home *** CD-ROM | disk | FTP | other *** search
/ Microsoft Programmer's Library 1.3 / Microsoft-Programers-Library-v1.3.iso / books / cadvprg.db < prev    next >
Encoding:
Text File  |  1991-03-01  |  1013.0 KB  |  20,727 lines
  1. %@1@%%@AB@%Microsoft  C - Advanced Programming Techniques%@AE@%%@EH@%%@NL@%
  2.                                       %@NL@%
  3.                                       %@NL@%
  4.                                       %@NL@%
  5.                                       %@NL@%
  6.                                       %@NL@%
  7.                                       %@NL@%
  8.                                       %@NL@%
  9.  
  10. ────────────────────────────────────────────────────────────────────────────%@NL@%
  11.              %@AB@%Microsoft (R) C - Advanced Programming Techniques%@AE@%%@NL@%
  12.                                       %@NL@%
  13.                        %@AB@%FOR MS (R) OS/2 AND MS-DOS (R)
  14.                              %@AB@%OPERATING SYSTEMS%@AE@%%@NL@%
  15. ────────────────────────────────────────────────────────────────────────────%@NL@%
  16.                                       %@NL@%
  17.                                       %@NL@%
  18.                            MICROSOFT CORPORATION%@NL@%
  19.                                       %@NL@%
  20. %@NL@%
  21. %@NL@%
  22. %@NL@%
  23. %@NL@%%@NL@%
  24. %@NL@%
  25.  
  26.  
  27. Information in this document is subject to change without notice and does
  28. not represent a commitment on the part of Microsoft Corporation. The
  29. software described in this document is furnished under a license agreement
  30. or nondisclosure agreement. The software may be used or copied only in
  31. accordance with the terms of the agreement. It is against the law to copy
  32. the software on any medium except as specifically allowed in the license or
  33. nondisclosure agreement. No part of this manual may be reproduced or trans-
  34. mitted in any form or by any means, electronic or mechanical, including
  35. photocopying and recording, for any purpose without the express written
  36. permission of Microsoft.
  37.  
  38. (C) Copyright Microsoft Corporation, 1990. All rights reserved.%@NL@%
  39. %@NL@%
  40. Printed and bound in the United States of America.%@NL@%
  41. %@NL@%
  42. Microsoft, MS, MS-DOS, CodeView, InPort, and XENIX are 
  43. registered trademarks and Windows is a trademark of Microsoft Corporation.%@NL@%
  44. %@NL@%
  45. Apple and Macintosh are registered trademarks and Finder 
  46. is a trademark of Apple Computer, Inc.%@NL@%
  47. %@NL@%
  48. AT&T is a registered trademark of American Telephone 
  49. and Telegraph Company.%@NL@%
  50. %@NL@%
  51. Hercules is a registered trademark and InColor is a trademark 
  52. of Hercules Computer Technology.%@NL@%
  53. %@NL@%
  54. IBM is a registered trademark of International Business 
  55. Machines Corporation.%@NL@%
  56. %@NL@%
  57. Intel is a registered trademark of Intel Corporation.%@NL@%
  58. %@NL@%
  59. Olivetti is a registered trademark of Ing. C. Olivetti.%@NL@%
  60. %@NL@%
  61. PDP-11 and VAX-11 are registered trademarks of Digital 
  62. Equipment Corporation.%@NL@%
  63. %@NL@%
  64. WANG is a registered trademark of Wang Laboratories.%@NL@%
  65. %@NL@%
  66. Z8000 is a registered trademark of Zilog, Inc.%@NL@%
  67. %@NL@%
  68. Document No. LN06514-1189 OEMO711-6Z
  69. 10 9 8 7 6 5 4 3 2 1 %@NL@%
  70. %@NL@%
  71. %@NL@%
  72. %@NL@%
  73. %@NL@%
  74. %@1@%%@AB@%Table of Contents%@AE@%%@EH@%%@NL@%
  75. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@NL@%
  76. %@NL@%
  77.  
  78. %@NL@%
  79. %@AB@%Introduction%@AE@%%@BO:        9686@%%@NL@%
  80.      Scope of This Book%@BO:        bdfd@%%@NL@%
  81.      Document Conventions%@BO:        a897@%%@NL@%
  82. %@NL@%
  83. %@NL@%
  84. %@AB@%PART I%@AE@%%@BO:        b991@%  %@AB@%Improving Program Performance%@AE@%%@NL@%
  85. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@NL@%
  86. %@NL@%
  87. %@NL@%
  88. %@AB@%Chapter 1%@AE@%%@BO:        bdfd@%  %@AB@%Optimizing C Programs%@AE@%%@NL@%
  89. %@NL@%
  90.      1.1%@BO:        a897@%   Controlling Optimization from the Programmer's WorkBench%@NL@%
  91.      1.2%@BO:        c938@%   Controlling Optimization from the Command Line%@NL@%
  92.      1.3%@BO:        ccf7@%   Controlling Optimization with Pragmas%@NL@%
  93.      1.4%@BO:        d6d0@%   Default Optimization%@NL@%
  94.             1.4.1%@BO:        d898@%    Common Subexpression Elimination%@NL@%
  95.             1.4.2%@BO:        db9a@%    Dead-Store Elimination%@NL@%
  96.             1.4.3%@BO:        de12@%    Constant Propagation%@NL@%
  97.      1.5%@BO:        e451@%   Customizing Your Optimizations%@NL@%
  98.             1.5.1%@BO:        e5c6@%    Choosing Speed or Size (/Ot and /Os)%@NL@%
  99.             1.5.2%@BO:        ea01@%    Generating Intrinsic Functions (/Oi)%@NL@%
  100.             1.5.3%@BO:       107f9@%    Assuming No Aliasing (/Oa and /Ow)%@NL@%
  101.             1.5.4%@BO:       1212b@%    Performing Loop Optimizations (/Ol)%@NL@%
  102.             1.5.5%@BO:       12e46@%    Disabling Unsafe Loop Optimizations (/On)%@NL@%
  103.             1.5.6%@BO:       12ff7@%    Enabling Aggressive Optimizations (/Oz)%@NL@%
  104.             1.5.7%@BO:       13a0d@%    Removing Stack Probes (/Gs)%@NL@%
  105.             1.5.8%@BO:       13daa@%    Enabling Global Register Allocation (/Oe)%@NL@%
  106.             1.5.9%@BO:       14925@%    Enabling Common Subexpression Optimization (/Oc and 
  107.                         /Og)%@NL@%
  108.             1.5.10%@BO:       14e06@%   Achieving Consistent Floating-Point Results (/Op)%@NL@%
  109.             1.5.11%@BO:       15770@%   Using the 80186, 80188, or 80286 Processor (/G0, /G1,
  110.                         /G2)%@NL@%
  111.             1.5.12%@BO:       15f38@%   Optimizing for Maximum Efficiency (/Ox)%@NL@%
  112.      1.6%@BO:       1651b@%   Linker (LINK) Options that Control Optimization%@NL@%
  113.             1.6.1%@BO:       1666f@%    Enabling Far Call Optimization (/FARCALLTRANSLATION)%@NL@%
  114.             1.6.2%@BO:       17905@%    Packing Code (/PACKCODE)%@NL@%
  115.             1.6.3%@BO:       17f5b@%    Packing Data (/PACKDATA)%@NL@%
  116.             1.6.4%@BO:       183a0@%    Packing the Executable File (/EXEPACK)%@NL@%
  117.      1.7%@BO:       18674@%   Optimizing in Different Environments%@NL@%
  118.             1.7.1%@BO:       18764@%    Optimizing in DOS%@NL@%
  119.             1.7.2%@BO:       188d6@%    Optimizing in OS/2%@NL@%
  120.             1.7.3%@BO:       189dc@%    Optimizing in Microsoft Windows(tm)%@NL@%
  121.      1.8%@BO:       18c3f@%   Choosing Function-Calling Conventions%@NL@%
  122.             1.8.1%@BO:       18f7f@%    The C Calling Convention (/Gd)%@NL@%
  123.             1.8.2%@BO:       1932b@%    The FORTRAN/Pascal Calling Convention (/Gc)%@NL@%
  124.             1.8.3%@BO:       19971@%    The Register Calling Convention (/Gr)%@NL@%
  125.             1.8.4%@BO:       19f58@%    The _fastcall Calling Convention%@NL@%
  126. %@NL@%
  127. %@AB@%Chapter 2%@AE@%%@BO:       1b75b@%  %@AB@%Managing Memory%@AE@%%@NL@%
  128. %@NL@%
  129.      2.1%@BO:       1bb95@%   Pointer Sizes%@NL@%
  130.             2.1.1%@BO:       1bdf8@%    Pointers and 64K Segments%@NL@%
  131.             2.1.2%@BO:       1c3da@%    Near Pointers%@NL@%
  132.             2.1.3%@BO:       1c68e@%    Far Pointers%@NL@%
  133.             2.1.4%@BO:       1ca77@%    Huge Pointers%@NL@%
  134.             2.1.5%@BO:       1d06e@%    Based Addressing%@NL@%
  135.      2.2%@BO:       1d327@%   Selecting a Standard Memory Model%@NL@%
  136.             2.2.1%@BO:       1d70e@%    The Six Standard Memory Models%@NL@%
  137.             2.2.2%@BO:       1dc36@%    Limitations on Code Size and Data Size%@NL@%
  138.             2.2.3%@BO:       1de9f@%    The Tiny Memory Model%@NL@%
  139.             2.2.4%@BO:       1e27d@%    The Huge Memory Model%@NL@%
  140.             2.2.5%@BO:       1ed27@%    Null Pointers%@NL@%
  141.             2.2.6%@BO:       1f5f0@%    Specifying a Memory Model%@NL@%
  142.      2.3%@BO:       1fcb2@%   Mixing Memory Models%@NL@%
  143.             2.3.1%@BO:       2101e@%    Pointer Problems%@NL@%
  144.             2.3.2%@BO:       21b7c@%    Declaring Near, Far, Huge, and Based Variables%@NL@%
  145.             2.3.3%@BO:       2249a@%    Declaring Near and Far Functions%@NL@%
  146.             2.3.4%@BO:       23064@%    Pointer Conversions%@NL@%
  147.      2.4%@BO:       24124@%   Customizing Memory Models%@NL@%
  148.             2.4.1%@BO:       249f8@%    Setting a Size for Code Pointers%@NL@%
  149.             2.4.2%@BO:       24d6d@%    Setting a Size for Data Pointers%@NL@%
  150.             2.4.3%@BO:       2530c@%    Setting Up Segments%@NL@%
  151.             2.4.4%@BO:       26cc4@%    Library Support for Customized Memory Models%@NL@%
  152.             2.4.5%@BO:       272c9@%    Setting the Data Threshold%@NL@%
  153.             2.4.6%@BO:       27753@%    Naming Modules and Segments%@NL@%
  154. %@NL@%
  155. %@AB@%Chapter 3%@AE@%%@BO:       283e2@%  %@AB@%Using the In-Line Assembler%@AE@%%@NL@%
  156. %@NL@%
  157.      3.1%@BO:       28684@%   Advantages of In-Line Assembly%@NL@%
  158.      3.2%@BO:       28b7b@%   The _asm Keyword%@NL@%
  159.      3.3%@BO:       29386@%   Using Assembly Language in _asm Blocks%@NL@%
  160.      3.4%@BO:       2aeac@%   Using C in _asm Blocks%@NL@%
  161.             3.4.1%@BO:       2b3b3@%    Using Operators%@NL@%
  162.             3.4.2%@BO:       2b8db@%    Using C Symbols%@NL@%
  163.             3.4.3%@BO:       2bd9d@%    Accessing C Data%@NL@%
  164.             3.4.4%@BO:       2c544@%    Writing Functions%@NL@%
  165.      3.5%@BO:       2d276@%   Using and Preserving Registers%@NL@%
  166.      3.6%@BO:       2dfda@%   Jumping to Labels%@NL@%
  167.      3.7%@BO:       2e897@%   Calling C Functions%@NL@%
  168.      3.8%@BO:       2ed4b@%   Defining _asm Blocks as C Macros%@NL@%
  169.      3.9%@BO:       2fc28@%   Optimizing%@NL@%
  170. %@NL@%
  171. %@AB@%Chapter 4%@AE@%%@BO:       306b8@%  %@AB@%Controlling Floating-Point Math Operations%@AE@%%@NL@%
  172. %@NL@%
  173.      4.1%@BO:       30a74@%   Declaring Floating-Point Types%@NL@%
  174.             4.1.1%@BO:       30d03@%    Declaring Variables as Floating-Point Types%@NL@%
  175.             4.1.2%@BO:       32643@%    Declaring Functions that Return Floating-Point Types%@NL@%
  176.      4.2%@BO:       32d2a@%   C Run-Time Library Support of Type long double%@NL@%
  177.      4.3%@BO:       3307c@%   Summary of Math Packages%@NL@%
  178.             4.3.1%@BO:       3376a@%    Emulator Package%@NL@%
  179.             4.3.2%@BO:       33f87@%    Math Coprocessor Package%@NL@%
  180.             4.3.3%@BO:       341c5@%    Alternate Math Package%@NL@%
  181.      4.4%@BO:       34641@%   Selecting Floating-Point Options (/FP)%@NL@%
  182.             4.4.1%@BO:       366b7@%    In-Line Emulator Option (/FPi)%@NL@%
  183.             4.4.2%@BO:       36f6a@%    In-Line Math Coprocessor Instructions Option (/FPi87)%@NL@%
  184.             4.4.3%@BO:       3737c@%    Calls to Emulator Option (/FPc)%@NL@%
  185.             4.4.4%@BO:       37927@%    Calls to Math Coprocessor Option (/FPc87)%@NL@%
  186.             4.4.5%@BO:       3826d@%    Use Alternate Math Option (/FPa)%@NL@%
  187.      4.5%@BO:       386a4@%   Library Considerations for Floating-Point Options%@NL@%
  188.             4.5.1%@BO:       3899b@%    Using One Standard Library for Linking%@NL@%
  189.             4.5.2%@BO:       38cfd@%    In-Line Instructions or Calls%@NL@%
  190.      4.6%@BO:       3913f@%   Compatibility between Floating-Point Options%@NL@%
  191.      4.7%@BO:       39a6a@%   Using the NO87 Environment Variable%@NL@%
  192.      4.8%@BO:       3a2a8@%   Incompatibility Issues%@NL@%
  193. %@NL@%
  194. %@NL@%
  195. %@AB@%PART II%@AE@%%@BO:       3a90c@%  %@AB@%Improving Programmer Productivity%@AE@%%@NL@%
  196. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@NL@%
  197. %@NL@%
  198. %@NL@%
  199. %@AB@%Chapter 5%@AE@%%@BO:       3ada9@%  %@AB@%Compiling and Linking Quickly%@AE@%%@NL@%
  200. %@NL@%
  201.      5.1%@BO:       3afdd@%   Compiling Quickly%@NL@%
  202.             5.1.1%@BO:       3b0c7@%    Quick Compiler%@NL@%
  203.             5.1.2%@BO:       3b47a@%    Incremental Compile Option%@NL@%
  204.      5.2%@BO:       3b7b3@%   Linking Quickly with ILINK%@NL@%
  205.             5.2.1%@BO:       3bf41@%    Preparing for Incremental Linking%@NL@%
  206.             5.2.2%@BO:       3cae1@%    Incremental Violations%@NL@%
  207. %@NL@%
  208. %@AB@%Chapter 6%@AE@%%@BO:       3d5e2@%  %@AB@%Managing Development Projects with NMAKE%@AE@%%@NL@%
  209. %@NL@%
  210.      6.1%@BO:       3da36@%   Overview of NMAKE%@NL@%
  211.      6.2%@BO:       3de62@%   The NMAKE Command%@NL@%
  212.      6.3%@BO:       3e70a@%   NMAKE Description Files%@NL@%
  213.             6.3.1%@BO:       3e89a@%    Description Blocks%@NL@%
  214.             6.3.2%@BO:       4157f@%    Comments%@NL@%
  215.             6.3.3%@BO:       4174e@%    Macros%@NL@%
  216.             6.3.4%@BO:       45bdb@%    Inference Rules%@NL@%
  217.             6.3.5%@BO:       473c7@%    Directives%@NL@%
  218.             6.3.6%@BO:       48e0c@%    Pseudotargets%@NL@%
  219.             6.3.7%@BO:       49ebe@%    PWB's extmake Syntax%@NL@%
  220.      6.4%@BO:       4a5bf@%   Command-Line Options%@NL@%
  221.      6.5%@BO:       4b91e@%   NMAKE Command Files%@NL@%
  222.      6.6%@BO:       4bef2@%   The TOOLS.INI File%@NL@%
  223.      6.7%@BO:       4c2bc@%   In-Line Files%@NL@%
  224.      6.8%@BO:       4cb4d@%   NMAKE Operations Sequence%@NL@%
  225.      6.9%@BO:       4de57@%   Differences between NMAKE and MAKE%@NL@%
  226. %@NL@%
  227. %@AB@%Chapter 7%@AE@%%@BO:       4ed59@%  %@AB@%Creating Help Files with HELPMAKE%@AE@%%@NL@%
  228. %@NL@%
  229.      7.1%@BO:       4f180@%   Structure and Contents of a Help Database%@NL@%
  230.             7.1.1%@BO:       4f2e4@%    Contents of a Help File%@NL@%
  231.             7.1.2%@BO:       5028d@%    Help File Formats%@NL@%
  232.      7.2%@BO:       50e99@%   Invoking HELPMAKE%@NL@%
  233.      7.3%@BO:       51889@%   HELPMAKE Options%@NL@%
  234.             7.3.1%@BO:       51a53@%    Options for Encoding%@NL@%
  235.             7.3.2%@BO:       543d4@%    Options for Decoding%@NL@%
  236.      7.4%@BO:       558a5@%   Creating a Help Database%@NL@%
  237.      7.5%@BO:       55ed3@%   Help Text Conventions%@NL@%
  238.             7.5.1%@BO:       55fed@%    Structure of the Help Text File%@NL@%
  239.             7.5.2%@BO:       56806@%    Local Contexts%@NL@%
  240.             7.5.3%@BO:       56dec@%    Context Prefixes%@NL@%
  241.             7.5.4%@BO:       582a4@%    Hyperlinks%@NL@%
  242.      7.6%@BO:       5932f@%   Using Help Database Formats%@NL@%
  243.             7.6.1%@BO:       59b21@%    QuickHelp Format%@NL@%
  244.             7.6.2%@BO:       5db23@%    Minimally Formatted ASCII Format%@NL@%
  245.             7.6.3%@BO:       5e410@%    Rich Text Format (RTF)%@NL@%
  246. %@NL@%
  247. %@AB@%Chapter 8%@AE@%%@BO:       5f750@%  %@AB@%Customizing the Microsoft Programmer's WorkBench%@AE@%%@NL@%
  248. %@NL@%
  249.      8.1%@BO:       5fc26@%   Setting Switches%@NL@%
  250.             8.1.1%@BO:       5fe49@%    Editing the <assign> Pseudofile%@NL@%
  251.             8.1.2%@BO:       604db@%    Editing the TOOLS.INI Initialization File%@NL@%
  252.      8.2%@BO:       610f5@%   Assigning Keystrokes%@NL@%
  253.      8.3%@BO:       619e7@%   Writing Macros%@NL@%
  254.             8.3.1%@BO:       61b24@%    Macro Syntax%@NL@%
  255.             8.3.2%@BO:       6270b@%    Macro Responses%@NL@%
  256.             8.3.3%@BO:       62dd1@%    Macro Arguments%@NL@%
  257.             8.3.4%@BO:       63473@%    Macro Conditionals%@NL@%
  258.             8.3.5%@BO:       63da5@%    Temporary Macros%@NL@%
  259.             8.3.6%@BO:       640d2@%    Macro Recordings%@NL@%
  260.      8.4%@BO:       64b33@%   Writing and Building C Extensions%@NL@%
  261.             8.4.1%@BO:       65cb5@%    Building Real-Mode Extensions%@NL@%
  262.             8.4.2%@BO:       667cc@%    Building Protected-Mode Extensions%@NL@%
  263.             8.4.3%@BO:       67183@%    Describing Functions and Switches%@NL@%
  264.             8.4.4%@BO:       689a6@%    Initializing Functions%@NL@%
  265.             8.4.5%@BO:       68d27@%    Prototyping Functions%@NL@%
  266.             8.4.6%@BO:       69122@%    Receiving Parameters%@NL@%
  267.             8.4.7%@BO:       6a36d@%    Calling PWB Functions%@NL@%
  268.             8.4.8%@BO:       6c45b@%    Calling C Library Functions%@NL@%
  269. %@NL@%
  270. %@AB@%Chapter 9%@AE@%%@BO:       6cc79@%  %@AB@%Debugging C Programs with CodeView%@AE@%%@NL@%
  271. %@NL@%
  272.      9.1%@BO:       6d0c1@%   Understanding CodeView Windows%@NL@%
  273.      9.2%@BO:       6e652@%   Overview of Debugging Techniques%@NL@%
  274.      9.3%@BO:       6ec41@%   Viewing and Modifying Program Data%@NL@%
  275.             9.3.1%@BO:       6edbe@%    Displaying Variables in the Watch Window%@NL@%
  276.             9.3.2%@BO:       6f66e@%    Displaying Expressions in the Watch Window%@NL@%
  277.             9.3.3%@BO:       6fd74@%    Displaying Arrays and Structures%@NL@%
  278.             9.3.4%@BO:       70e92@%    Displaying Array Elements Dynamically%@NL@%
  279.             9.3.5%@BO:       711f8@%    Using Quick Watch%@NL@%
  280.             9.3.6%@BO:       717dc@%    Displaying Memory%@NL@%
  281.             9.3.7%@BO:       72653@%    Displaying the Processor Registers%@NL@%
  282.             9.3.8%@BO:       72b9c@%    Modifying the Values of Variables, Registers,
  283.                         and Memory%@NL@%
  284.      9.4%@BO:       733af@%   Controlling Execution%@NL@%
  285.             9.4.1%@BO:       735dc@%    Continuous Execution%@NL@%
  286.             9.4.2%@BO:       75665@%    Single-Stepping%@NL@%
  287.      9.5%@BO:       75bf1@%   Replaying a Debug Session%@NL@%
  288.      9.6%@BO:       769d2@%   Advanced CodeView Techniques%@NL@%
  289.      9.7%@BO:       78caf@%   Controlling CodeView with Command-Line Options%@NL@%
  290.      9.8%@BO:       79ca7@%   Customizing CodeView with the TOOLS.INI FILE%@NL@%
  291. %@NL@%
  292. %@NL@%
  293. %@AB@%PART III%@AE@%%@BO:       7a0b5@%  %@AB@%Special Environments%@AE@%%@NL@%
  294. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@NL@%
  295. %@NL@%
  296. %@NL@%
  297. %@AB@%Chapter 10%@AE@%%@BO:       7a411@%  %@AB@%Communicating with Graphics%@AE@%%@NL@%
  298. %@NL@%
  299.      10.1%@BO:       7a96d@%  Video Modes%@NL@%
  300.             10.1.1%@BO:       7aed0@%    Sample Low-Level Graphics Program%@NL@%
  301.             10.1.2%@BO:       7b97c@%    Setting a Video Mode%@NL@%
  302.             10.1.3%@BO:       7c764@%    Reading the videoconfig Structure%@NL@%
  303.             10.1.4%@BO:       7d113@%    Maximizing Resolution or Color%@NL@%
  304.             10.1.5%@BO:       7d740@%    Selecting Your Own Video Modes%@NL@%
  305.      10.2%@BO:       7dc0f@%  Mixing Colors and Changing Palettes%@NL@%
  306.             10.2.1%@BO:       7e2a7@%    CGA Palettes%@NL@%
  307.             10.2.2%@BO:       7ec93@%    Olivetti(R) Palettes%@NL@%
  308.             10.2.3%@BO:       7ef5d@%    VGA Palettes%@NL@%
  309.             10.2.4%@BO:       7fb3a@%    MCGA Palettes%@NL@%
  310.             10.2.5%@BO:       7fcaa@%    EGA Palettes%@NL@%
  311.             10.2.6%@BO:       801b2@%    Symbolic Constants%@NL@%
  312.      10.3%@BO:       80592@%  Specifying Points within Coordinate Systems%@NL@%
  313.             10.3.1%@BO:       8099d@%    Physical Coordinates%@NL@%
  314.             10.3.2%@BO:       812e6@%    Viewport Coordinates%@NL@%
  315.             10.3.3%@BO:       81890@%    Window Coordinates%@NL@%
  316.             10.3.4%@BO:       81ee4@%    Screen Locations%@NL@%
  317.             10.3.5%@BO:       823fa@%    Bounding Rectangles%@NL@%
  318.             10.3.6%@BO:       82781@%    The Pixel Cursor%@NL@%
  319.      10.4%@BO:       82a7b@%  Graphics Functions%@NL@%
  320.             10.4.1%@BO:       82cc4@%    Controlling Video Modes%@NL@%
  321.             10.4.2%@BO:       83c39@%    Changing Colors%@NL@%
  322.             10.4.3%@BO:       844c2@%    Drawing Points, Lines, and Shapes%@NL@%
  323.             10.4.4%@BO:       859c2@%    Defining Patterns%@NL@%
  324.             10.4.5%@BO:       86184@%    Manipulating Images%@NL@%
  325.      10.5%@BO:       86bee@%  Using Graphic Fonts%@NL@%
  326.             10.5.1%@BO:       877ab@%    Using the C Font Library%@NL@%
  327.             10.5.2%@BO:       87c1d@%    Registering the Fonts%@NL@%
  328.             10.5.3%@BO:       88036@%    Setting the Current Font%@NL@%
  329.             10.5.4%@BO:       896c0@%    Displaying Text%@NL@%
  330.             10.5.5%@BO:       898aa@%    A Sample Program%@NL@%
  331.             10.5.6%@BO:       8a3d5@%    Using Fonts Effectively%@NL@%
  332. %@NL@%
  333. %@AB@%Chapter 11%@AE@%%@BO:       8aaf4@%  %@AB@%Creating Charts and Graphs%@AE@%%@NL@%
  334. %@NL@%
  335.      11.1%@BO:       8ae04@%  Overview of Presentation Graphics%@NL@%
  336.      11.2%@BO:       8b7df@%  Parts of a Graph%@NL@%
  337.      11.3%@BO:       8d6ab@%  Writing a Presentation Graphics Program%@NL@%
  338.             11.3.1%@BO:       8ddc9@%    Pie Chart%@NL@%
  339.             11.3.2%@BO:       8e7dc@%    Bar, Column, and Line Charts%@NL@%
  340.             11.3.3%@BO:       8f968@%    Scatter Diagram%@NL@%
  341.      11.4%@BO:       90562@%  Manipulating Colors and Patterns%@NL@%
  342.             11.4.1%@BO:       90ad9@%    Color Pool%@NL@%
  343.             11.4.2%@BO:       91535@%    Style Pool%@NL@%
  344.             11.4.3%@BO:       91a9b@%    Pattern Pool%@NL@%
  345.             11.4.4%@BO:       92c2b@%    Character Pool%@NL@%
  346.      11.5%@BO:       92dd5@%  Customizing the Chart Environment%@NL@%
  347.             11.5.1%@BO:       93be0@%    titletype Structures%@NL@%
  348.             11.5.2%@BO:       9459e@%    axistype Structures%@NL@%
  349.             11.5.3%@BO:       976d0@%    windowtype Structures%@NL@%
  350.             11.5.4%@BO:       98696@%    legendtype Structures%@NL@%
  351.             11.5.5%@BO:       9967d@%    chartenv Structures%@NL@%
  352. %@NL@%
  353. %@AB@%Chapter 12%@AE@%%@BO:       9aa24@%  %@AB@%Programming with Mixed Languages%@AE@%%@NL@%
  354. %@NL@%
  355.      12.1%@BO:       9ad4c@%  Making Mixed-Language Calls%@NL@%
  356.      12.2%@BO:       9ba76@%  Language Convention Requirements%@NL@%
  357.             12.2.1%@BO:       9bca6@%    Naming Convention Requirement%@NL@%
  358.             12.2.2%@BO:       9cfc0@%    Calling Convention Requirement%@NL@%
  359.             12.2.3%@BO:       9e1fd@%    Parameter-Passing Requirement%@NL@%
  360.      12.3%@BO:       9f253@%  Compiling and Linking%@NL@%
  361.             12.3.1%@BO:       9f3b2@%    Compiling with Correct Memory Models%@NL@%
  362.             12.3.2%@BO:       9f9ac@%    Linking with Language Libraries%@NL@%
  363.      12.4%@BO:       a0128@%  C Calls to High-Level Languages%@NL@%
  364.      12.5%@BO:       a1883@%  C Calls to BASIC%@NL@%
  365.      12.6%@BO:       a2cd2@%  C Calls to FORTRAN%@NL@%
  366.             12.6.1%@BO:       a2e7e@%    Calling a FORTRAN Subroutine from C%@NL@%
  367.             12.6.2%@BO:       a3920@%    Calling a FORTRAN Function from C%@NL@%
  368.      12.7%@BO:       a4226@%  C Calls to Pascal%@NL@%
  369.             12.7.1%@BO:       a43cc@%    Calling a Pascal Procedure from C%@NL@%
  370.             12.7.2%@BO:       a4d77@%    Calling a Pascal Function from C%@NL@%
  371.      12.8%@BO:       a5596@%  C Calls to Assembly Language%@NL@%
  372.             12.8.1%@BO:       a5da1@%    Writing the Assembly-Language Procedure%@NL@%
  373.             12.8.2%@BO:       a6312@%    Setting Up the Procedure%@NL@%
  374.             12.8.3%@BO:       a6aae@%    Entering the Procedure%@NL@%
  375.             12.8.4%@BO:       a6f57@%    Allocating Local Data%@NL@%
  376.             12.8.5%@BO:       a7510@%    Preserving Register Values%@NL@%
  377.             12.8.6%@BO:       a802c@%    Accessing Parameters%@NL@%
  378.             12.8.7%@BO:       a8e40@%    Returning a Value%@NL@%
  379.             12.8.8%@BO:       a9a4d@%    Exiting the Procedure%@NL@%
  380.      12.9%@BO:       aa24b@%  Handling Data in Mixed-Language Programming%@NL@%
  381.             12.9.1%@BO:       aa39c@%    Default Naming and Calling Conventions%@NL@%
  382.             12.9.2%@BO:       aacde@%    Numeric Data Representation%@NL@%
  383.             12.9.3%@BO:       ab885@%    Strings%@NL@%
  384.             12.9.4%@BO:       ad1db@%    Arrays%@NL@%
  385.             12.9.5%@BO:       ad98d@%    Array Declaration and Indexing%@NL@%
  386.             12.9.6%@BO:       ae795@%    Structures, Records, and User-Defined Types%@NL@%
  387.             12.9.7%@BO:       aeec0@%    External Data%@NL@%
  388.             12.9.8%@BO:       af676@%    Pointers and Address Variables%@NL@%
  389.             12.9.9%@BO:       afe32@%    Common Blocks%@NL@%
  390.             12.9.10%@BO:       b08e9@%   Using a Varying Number of Parameters%@NL@%
  391. %@NL@%
  392. %@AB@%Chapter 13%@AE@%%@BO:       b0c3c@%  %@AB@%Writing Portable Programs%@AE@%%@NL@%
  393. %@NL@%
  394.      13.1%@BO:       b1007@%  Assumptions about Hardware%@NL@%
  395.             13.1.1%@BO:       b1169@%    Size of Basic Types%@NL@%
  396.             13.1.2%@BO:       b3a6e@%    Storage Order and Alignment%@NL@%
  397.             13.1.3%@BO:       b4c9f@%    Byte Order in a Word%@NL@%
  398.             13.1.4%@BO:       b58da@%    Reading and Writing Structures%@NL@%
  399.             13.1.5%@BO:       b5c84@%    Bit Fields in Structures%@NL@%
  400.             13.1.6%@BO:       b6909@%    Processor Arithmetic Mode%@NL@%
  401.             13.1.7%@BO:       b6f0a@%    Pointers%@NL@%
  402.             13.1.8%@BO:       b83ac@%    Address Space%@NL@%
  403.             13.1.9%@BO:       b8a46@%    Character Set%@NL@%
  404.      13.2%@BO:       b962b@%  Assumptions about the Compiler%@NL@%
  405.             13.2.1%@BO:       b9892@%    Sign Extension%@NL@%
  406.             13.2.2%@BO:       bab57@%    Length and Case of Identifiers%@NL@%
  407.             13.2.3%@BO:       bb247@%    Register Variables%@NL@%
  408.             13.2.4%@BO:       bb8b1@%    Functions with a Variable Number of Arguments%@NL@%
  409.             13.2.5%@BO:       bbbc6@%    Evaluation Order%@NL@%
  410.             13.2.6%@BO:       bc416@%    Function and Macro Arguments with Side Effects%@NL@%
  411.             13.2.7%@BO:       bcd8f@%    Environment Differences%@NL@%
  412.      13.3%@BO:       bd133@%  Portability of Data Files%@NL@%
  413.      13.4%@BO:       bd422@%  Portability Concerns Specific to Microsoft C%@NL@%
  414.      13.5%@BO:       bd7f3@%  Microsoft C Byte Ordering%@NL@%
  415. %@NL@%
  416. %@NL@%
  417. %@AB@%PART IV%@AE@%%@BO:       bde61@%  %@AB@%OS/2 Support%@AE@%%@NL@%
  418. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@NL@%
  419. %@NL@%
  420. %@NL@%
  421. %@AB@%Chapter 14%@AE@%%@BO:       be208@%  %@AB@%Building OS/2 Applications%@AE@%%@NL@%
  422. %@NL@%
  423.      14.1%@BO:       be7b1@%  The OS/2 Applications Program Interface%@NL@%
  424.             14.1.1%@BO:       bec33@%    Calling the OS/2 API%@NL@%
  425.             14.1.2%@BO:       bf231@%    Including the OS/2 Header Files%@NL@%
  426.             14.1.3%@BO:       c006c@%    Creating Dual-Mode Programs as Family Applications%@NL@%
  427.      14.2%@BO:       c1470@%  Compile Options for the CL Command%@NL@%
  428.             14.2.1%@BO:       c1726@%    The Link Mode Options (/Lp, /Lr, and /Lc)%@NL@%
  429.             14.2.2%@BO:       c2381@%    Creating Bound Programs Option (/Fb)%@NL@%
  430.             14.2.3%@BO:       c2dcb@%    Library Selection Options (/MT, /ML, /MD, /Zl)%@NL@%
  431.             14.2.4%@BO:       c3cbe@%    Memory-Model Options (/Ax)%@NL@%
  432.      14.3%@BO:       c4599@%  Module-Definition Files and Import Libraries%@NL@%
  433.             14.3.1%@BO:       c53a4@%    Adding a Module-Definition File to the LINK Command%@NL@%
  434.             14.3.2%@BO:       c5818@%    Creating Dynamic-Link Libraries (DLLs)%@NL@%
  435.             14.3.3%@BO:       c5fe4@%    Creating Programs with I/O Privileges%@NL@%
  436.             14.3.4%@BO:       c670a@%    Creating Presentation Manager Applications%@NL@%
  437.             14.3.5%@BO:       c702b@%    Creating Import Libraries with the IMPLIB Utility%@NL@%
  438.      14.4%@BO:       c772b@%  Link Command-Line Options%@NL@%
  439.      14.5%@BO:       c87b2@%  The BIND Utility%@NL@%
  440. %@NL@%
  441. %@AB@%Chapter 15%@AE@%%@BO:       c9373@%  %@AB@%Creating Multithread OS/2 Applications%@AE@%%@NL@%
  442. %@NL@%
  443.      15.1%@BO:       c9735@%  Multithread Programs%@NL@%
  444.             15.1.1%@BO:       c9dc6@%    Library Support%@NL@%
  445.             15.1.2%@BO:       cb9f3@%    Include Files%@NL@%
  446.             15.1.3%@BO:       cbed0@%    C Run-Time Library Functions for Thread Control%@NL@%
  447.      15.2%@BO:       cd17f@%  Sample Multithread C Program%@NL@%
  448.      15.3%@BO:       cf4e2@%  Writing a Multithread Program%@NL@%
  449.      15.4%@BO:       d1b51@%  Compiling and Linking%@NL@%
  450.      15.5%@BO:       d282f@%  Avoiding Problem Areas%@NL@%
  451.      15.6%@BO:       d37c9@%  Using the Protected-Mode CodeView Debugger%@NL@%
  452.             15.6.1%@BO:       d3c94@%    Compiling with the /Zi Option%@NL@%
  453.             15.6.2%@BO:       d3f28@%    Prompt for Thread Number%@NL@%
  454.             15.6.3%@BO:       d4099@%    Thread Commands%@NL@%
  455.             15.6.4%@BO:       d5b8c@%    Screen Groups Used by CodeView%@NL@%
  456. %@NL@%
  457. %@AB@%Chapter 16%@AE@%%@BO:       d5e3d@%  %@AB@%Dynamic Linking with OS/2%@AE@%%@NL@%
  458. %@NL@%
  459.      16.1%@BO:       d61d4@%  Overview of Dynamic Linking%@NL@%
  460.             16.1.1%@BO:       d6650@%    Load-Time and Run-Time Linking%@NL@%
  461.             16.1.2%@BO:       d6b99@%    Application Programs and DLLs%@NL@%
  462.             16.1.3%@BO:       d6f69@%    DLLs and Microsoft C Run-Time Libraries%@NL@%
  463.      16.2%@BO:       d825b@%  Designing and Writing DLLs%@NL@%
  464.             16.2.1%@BO:       d853e@%    Floating-Point Math Requirements%@NL@%
  465.             16.2.2%@BO:       d8f0f@%    Initialization and Termination Requirements%@NL@%
  466.             16.2.3%@BO:       daf4b@%    Making the DLL Re-Entrant%@NL@%
  467.             16.2.4%@BO:       dc9ad@%    Signal Handling%@NL@%
  468.             16.2.5%@BO:       dcb62@%    Using Microsoft C Keywords%@NL@%
  469.             16.2.6%@BO:       dd57b@%    Compile Options for Dynamic-Link Libraries%@NL@%
  470.      16.3%@BO:       de27b@%  Building DLLs with Microsoft C%@NL@%
  471.             16.3.1%@BO:       de508@%    DLLs with Static C Run-Time Library Functions%@NL@%
  472.             16.3.2%@BO:       e0bb2@%    DLLs without C Run-Time Library Functions%@NL@%
  473.             16.3.3%@BO:       e1318@%    Programs and DLLs with a C Run-Time DLL%@NL@%
  474.             16.3.4%@BO:       e3bfc@%    Using CodeView to Debug Dynamic-Link Libraries%@NL@%
  475. %@NL@%
  476. %@AB@%Appendix A%@AE@%%@BO:       e416c@%  %@AB@%Using Exit Codes%@AE@%%@NL@%
  477. %@NL@%
  478.      A.1%@BO:       e4487@%   The exit Function%@NL@%
  479.      A.2%@BO:       e4c25@%   Testing Exit Codes from Command and Batch Files%@NL@%
  480.      A.3%@BO:       e516f@%   Accessing Exit Codes from Other Programs%@NL@%
  481. %@NL@%
  482. %@AB@%Appendix B%@AE@%%@BO:       e5c07@%  %@AB@%Differences between C Versions 5.1 and 6.0%@AE@%%@NL@%
  483. %@NL@%
  484.      B.1%@BO:       e5f2b@%   Modifications for ANSI Compatibility%@NL@%
  485.             B.1.1%@BO:       e604a@%    ANSI-Mandated New Features%@NL@%
  486.             B.1.2%@BO:       e6582@%    Integer Promotion Rules%@NL@%
  487.             B.1.3%@BO:       e69a6@%    Defining NULL as a Pointer%@NL@%
  488.             B.1.4%@BO:       e6aeb@%    Shift Operators%@NL@%
  489.             B.1.5%@BO:       e6e1a@%    Pointers to Typedefs%@NL@%
  490.             B.1.6%@BO:       e7281@%    Identifying Nonstandard Keywords%@NL@%
  491.             B.1.7%@BO:       e76c3@%    Trigraphs%@NL@%
  492.             B.1.8%@BO:       e7a5c@%    ANSI Nonconformance%@NL@%
  493.      B.2%@BO:       e7d0b@%   New Keywords and Functions%@NL@%
  494.             B.2.1%@BO:       e7e33@%    In-Line Assembler%@NL@%
  495.             B.2.2%@BO:       e7fa5@%    Based Pointers and Objects%@NL@%
  496.             B.2.3%@BO:       e8ba2@%    Based Heap Allocation Support%@NL@%
  497.             B.2.4%@BO:       e8ee2@%    Releasing Unused Heap Memory%@NL@%
  498.             B.2.5%@BO:       e9138@%    Making Static Data Available to the Heap%@NL@%
  499.             B.2.6%@BO:       e9224@%    Long Doubles%@NL@%
  500.             B.2.7%@BO:       e9612@%    Long Double Functions%@NL@%
  501.             B.2.8%@BO:       e99c4@%    Model-Independent String and Memory Functions%@NL@%
  502.             B.2.9%@BO:       ea290@%    Mixed-Model Memory Allocation Support%@NL@%
  503.             B.2.10%@BO:       ea4f7@%   The _fastcall Attribute (/Gr Option)%@NL@%
  504.             B.2.11%@BO:       eaef3@%   Drive and Directory Functions%@NL@%
  505.             B.2.12%@BO:       eb1d9@%   Text Output Functions for OS/2%@NL@%
  506.      B.3%@BO:       eb630@%   New Features%@NL@%
  507.             B.3.1%@BO:       eb6d7@%    Strings and Macros%@NL@%
  508.             B.3.2%@BO:       eb7a0@%    CL Options%@NL@%
  509.             B.3.3%@BO:       ec428@%    Tiny Memory Model (.COM Files)%@NL@%
  510.             B.3.4%@BO:       ec60e@%    The Optimize Pragma%@NL@%
  511.             B.3.5%@BO:       ec8b7@%    Nameless Structures and Unions%@NL@%
  512.             B.3.6%@BO:       ecc74@%    Unsized Arrays as the Last Member of a Structure%@NL@%
  513.             B.3.7%@BO:       ecfbb@%    Improved Warnings%@NL@%
  514.             B.3.8%@BO:       ed1ac@%    Macros%@NL@%
  515.             B.3.9%@BO:       ed252@%    Improved Multithread Support in OS/2%@NL@%
  516.             B.3.10%@BO:       ed5ec@%   Pipe Support in OS/2%@NL@%
  517.      B.4%@BO:       ed84a@%   Differences in Code Generation%@NL@%
  518.             B.4.1%@BO:       ed956@%    Speed and Space Improvements%@NL@%
  519.             B.4.2%@BO:       ed9f0@%    Code Quality%@NL@%
  520.             B.4.3%@BO:       edb8b@%    Floating-Point Code Generation%@NL@%
  521.             B.4.4%@BO:       ede82@%    Intrinsic Functions%@NL@%
  522.      B.5%@BO:       ee528@%   Changes and Deletions%@NL@%
  523.             B.5.1%@BO:       ee5f9@%    Deleted Features%@NL@%
  524.             B.5.2%@BO:       ee77b@%    Evaluation of Real Expressions%@NL@%
  525.             B.5.3%@BO:       ee929@%    Default Optimizations%@NL@%
  526.             B.5.4%@BO:       eeadf@%    Sign Extension of char Arguments%@NL@%
  527.             B.5.5%@BO:       eec98@%    Conditional Compilation and Signed Values%@NL@%
  528.             B.5.6%@BO:       eee9b@%    The const and volatile Qualifiers%@NL@%
  529.             B.5.7%@BO:       ef152@%    Memory Allocation%@NL@%
  530.             B.5.8%@BO:       ef2a5@%    Memory Used by Command-Line Arguments%@NL@%
  531.             B.5.9%@BO:       ef40f@%    Format Specifiers in printf%@NL@%
  532.             B.5.10%@BO:       ef859@%   Functions that Return Float Values%@NL@%
  533. %@NL@%
  534. %@AB@%Appendix C%@AE@%%@BO:       efa07@%  %@AB@%Implementation-Defined Behavior%@AE@%%@NL@%
  535. %@NL@%
  536.      C.1%@BO:       efe6d@%   Translation%@NL@%
  537.             C.1.1%@BO:       efebc@%    Diagnostics%@NL@%
  538.      C.2%@BO:       f017d@%   Environment%@NL@%
  539.             C.2.1%@BO:       f01cc@%    Arguments to main%@NL@%
  540.             C.2.2%@BO:       f0890@%    Interactive Devices%@NL@%
  541.      C.3%@BO:       f098e@%   Identifiers%@NL@%
  542.             C.3.1%@BO:       f09dd@%    Significant Characters without External Linkage%@NL@%
  543.             C.3.2%@BO:       f0b7a@%    Significant Characters with External Linkage%@NL@%
  544.             C.3.3%@BO:       f0d79@%    Upper- and Lowercase%@NL@%
  545.      C.4%@BO:       f11dd@%   Characters%@NL@%
  546.             C.4.1%@BO:       f122b@%    The ASCII Character Set%@NL@%
  547.             C.4.2%@BO:       f151c@%    Multibyte Characters%@NL@%
  548.             C.4.3%@BO:       f168f@%    Bits per Character%@NL@%
  549.             C.4.4%@BO:       f17cf@%    Character Sets%@NL@%
  550.             C.4.5%@BO:       f1bf4@%    Unrepresented Character Constants%@NL@%
  551.             C.4.6%@BO:       f1d93@%    Wide Characters%@NL@%
  552.             C.4.7%@BO:       f1f0d@%    Converting Multibyte Characters%@NL@%
  553.             C.4.8%@BO:       f2060@%    Range of char Values%@NL@%
  554.      C.5%@BO:       f227f@%   Integers%@NL@%
  555.             C.5.1%@BO:       f22cb@%    Range of Integer Values%@NL@%
  556.             C.5.2%@BO:       f2659@%    Demotion of Integers%@NL@%
  557.             C.5.3%@BO:       f2a1d@%    Signed Bitwise Operations%@NL@%
  558.             C.5.4%@BO:       f2c39@%    Remainders%@NL@%
  559.             C.5.5%@BO:       f2da8@%    Right Shifts%@NL@%
  560.      C.6%@BO:       f3130@%   Floating-Point Math%@NL@%
  561.             C.6.1%@BO:       f3187@%    Values%@NL@%
  562.             C.6.2%@BO:       f34ae@%    Casting Integers to Floating-Point Values%@NL@%
  563.             C.6.3%@BO:       f37ce@%    Truncation of Floating-Point Values%@NL@%
  564.      C.7%@BO:       f396c@%   Arrays and Pointers%@NL@%
  565.             C.7.1%@BO:       f39c3@%    Largest Array Size%@NL@%
  566.             C.7.2%@BO:       f3c0e@%    Casting Pointers%@NL@%
  567.             C.7.3%@BO:       f4018@%    Pointer Subtraction%@NL@%
  568.      C.8%@BO:       f42d8@%   Registers%@NL@%
  569.             C.8.1%@BO:       f4325@%    Availability of Registers%@NL@%
  570.      C.9%@BO:       f44b9@%   Structures, Unions, Enumerations, and Bit Fields%@NL@%
  571.             C.9.1%@BO:       f452d@%    Improper Access to a Union%@NL@%
  572.             C.9.2%@BO:       f47e3@%    Sign of Bit Fields%@NL@%
  573.             C.9.3%@BO:       f4925@%    Storage of Bit Fields%@NL@%
  574.             C.9.4%@BO:       f4cba@%    Alignment of Bit Fields%@NL@%
  575.             C.9.5%@BO:       f4f59@%    The enum Type%@NL@%
  576.      C.10%@BO:       f5071@%  Qualifiers%@NL@%
  577.             C.10.1%@BO:       f50c0@%   Access to Volatile Objects%@NL@%
  578.      C.11%@BO:       f51dc@%  Declarators%@NL@%
  579.             C.11.1%@BO:       f522c@%   Maximum Number%@NL@%
  580.      C.12%@BO:       f537a@%  Statements%@NL@%
  581.             C.12.1%@BO:       f53c9@%   Limits on Switch Statements%@NL@%
  582.      C.13%@BO:       f552c@%  Preprocessing Directives%@NL@%
  583.             C.13.1%@BO:       f5589@%   Character Constants and Conditional Inclusion%@NL@%
  584.             C.13.2%@BO:       f57dc@%   Including Bracketed File Names%@NL@%
  585.             C.13.3%@BO:       f5bc9@%   Including Quoted File Names%@NL@%
  586.             C.13.4%@BO:       f5eb7@%   Character Sequences%@NL@%
  587.             C.13.5%@BO:       f6113@%   Pragmas%@NL@%
  588.             C.13.6%@BO:       f648b@%   Default Date and Time%@NL@%
  589.      C.14%@BO:       f6604@%  Library Functions%@NL@%
  590.             C.14.1%@BO:       f665a@%   NULL Macro%@NL@%
  591.             C.14.2%@BO:       f6761@%   Diagnostic Printed by the assert Function%@NL@%
  592.             C.14.3%@BO:       f6a50@%   Character Testing%@NL@%
  593.             C.14.4%@BO:       f6ea9@%   Domain Errors%@NL@%
  594.             C.14.5%@BO:       f6fb1@%   Underflow of Floating-Point Values%@NL@%
  595.             C.14.6%@BO:       f7176@%   The fmod Function%@NL@%
  596.             C.14.7%@BO:       f72cd@%   The signal Function%@NL@%
  597.             C.14.8%@BO:       f7c08@%   Default Signals%@NL@%
  598.             C.14.9%@BO:       f7d6e@%   The SIGILL Signal%@NL@%
  599.             C.14.10%@BO:       f7efd@%  Terminating Newline Characters%@NL@%
  600.             C.14.11%@BO:       f804e@%  Blank Lines%@NL@%
  601.             C.14.12%@BO:       f8174@%  Null Characters%@NL@%
  602.             C.14.13%@BO:       f829c@%  File Position in Append Mode%@NL@%
  603.             C.14.14%@BO:       f841d@%  Truncation of Text Files%@NL@%
  604.             C.14.15%@BO:       f855b@%  File Buffering%@NL@%
  605.             C.14.16%@BO:       f86d2@%  Zero-Length Files%@NL@%
  606.             C.14.17%@BO:       f87b4@%  File Names%@NL@%
  607.             C.14.18%@BO:       f89f5@%  File Access Limits%@NL@%
  608.             C.14.19%@BO:       f8ae9@%  Deleting Open Files%@NL@%
  609.             C.14.20%@BO:       f8bf5@%  Renaming with a Name that Exists%@NL@%
  610.             C.14.21%@BO:       f8d68@%  Printing Pointer Values%@NL@%
  611.             C.14.22%@BO:       f9000@%  Reading Pointer Values%@NL@%
  612.             C.14.23%@BO:       f9167@%  Reading Ranges%@NL@%
  613.             C.14.24%@BO:       f9361@%  File Position Errors%@NL@%
  614.             C.14.25%@BO:       f9542@%  Messages Generated by the perror Function%@NL@%
  615.             C.14.26%@BO:       f991d@%  Allocating Zero Memory%@NL@%
  616.             C.14.27%@BO:       f9ad6@%  The abort Function%@NL@%
  617.             C.14.28%@BO:       f9c2a@%  The atexit Function%@NL@%
  618.             C.14.29%@BO:       f9d9c@%  Environment Names%@NL@%
  619.             C.14.30%@BO:       fa192@%  The system Function%@NL@%
  620.             C.14.31%@BO:       fa403@%  The strerror Function%@NL@%
  621.             C.14.32%@BO:       fa814@%  The Time Zone%@NL@%
  622.             C.14.33%@BO:       fa923@%  The clock Function%@NL@%
  623.  
  624. %@AB@%Index%@AE@%%@BO:       faa6e@%
  625.  
  626.  
  627. %@NL@%
  628. %@NL@%
  629. %@CR:C6A-Intro   @%%@1@%%@AB@%Introduction%@AE@%%@EH@%%@NL@%
  630. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  631. %@NL@%
  632. %@AI@%Advanced Programming Techniques%@AE@% describes how to get the most out of the
  633. Microsoft(R) C Professional Development System with its new integrated
  634. development environment─the Microsoft Programmer's WorkBench─and
  635. source-level debugging tool─the CodeView(R) debugger.  %@NL@%
  636. %@NL@%
  637. In this manual, you will see how all the components of the Microsoft C
  638. Professional Development System work together to provide you with the most
  639. powerful development environment available. A key element in the power of
  640. the Professional Development System is your ability to customize it to suit
  641. your individual needs as a programmer.  %@NL@%
  642. %@NL@%
  643. Because this book is arranged by topic, it answers questions about using
  644. Microsoft C version 6.0, rather than providing lists of options. If you have
  645. specific questions about menu items in the CodeView debugger, the
  646. Programmer's WorkBench, or any of the command-line utilities included in the
  647. Professional Development System, you can use the Microsoft C Advisor
  648. (on-line help) or the %@AI@%C Reference%@AE@% manual. %@AI@%  %@AE@%%@NL@%
  649. %@NL@%
  650. %@AI@%Advanced Programming Techniques%@AE@% shows you how tools and utilities all fit
  651. together.  %@NL@%
  652. %@NL@%
  653. %@NL@%
  654. %@2@%%@CR:C6A00010001 @%%@AB@%Scope of This Book%@AE@%%@EH@%%@NL@%
  655. %@NL@%
  656. %@AI@%Advanced Programming Techniques%@AE@% is divided into four parts. Part 1,
  657. "Improving Program Performance," helps you write more efficient programs. It
  658. provides specific information about optimizing─when and why to use various
  659. optimizing options. It also explains new memory management options and when
  660. to use them. For example, Chapter 3 describes the in-line assembler, a new
  661. feature that lets you mix assembly language with your C source code.  %@NL@%
  662. %@NL@%
  663. Part 2, "Improving Programmer Productivity," will help you perform
  664. programming tasks more quickly and efficiently. Chapter 8 explains the
  665. different ways you can customize the new Programmer's WorkBench (PWB)─an
  666. editor and integrated development environment that allows you to  %@NL@%
  667. %@NL@%
  668. %@NL@%
  669.   ■   Create new programs%@NL@%
  670. %@NL@%
  671.   ■   Modify existing programs%@NL@%
  672. %@NL@%
  673.   ■   Browse source files%@NL@%
  674. %@NL@%
  675.   ■   Obtain help about PWB, the C language, and the C run-time libraries%@NL@%
  676. %@NL@%
  677.   ■   Set program build lists%@NL@%
  678. %@NL@%
  679.   ■   Build programs%@NL@%
  680. %@NL@%
  681.   ■   Debug programs with the CodeView debugger%@NL@%
  682. %@NL@%
  683. %@NL@%
  684. Chapter 8 also describes how to change PWB behavior to suit your programming
  685. style by making keyboard assignments, recording or writing macros, and
  686. writing C extensions.  %@NL@%
  687. %@NL@%
  688. Also in Part 2 is a chapter about the Microsoft Program Maintenance Utility,
  689. NMAKE. NMAKE is a new program maintenance facility that allows you to use
  690. program lists as input, which provides extra flexibility in your program
  691. build process. It is a superset of the Microsoft XENIX(R) MAKE utility and
  692. is substantially more powerful than previous versions of MAKE.  %@NL@%
  693. %@NL@%
  694. Chapter 9 in Part 2 describes the CodeView debugger, which is even more
  695. powerful than in previous releases. With CodeView version 3.0, you get many
  696. new features, including the ability to record a debugging session, then play
  697. it back (history and dynamic replay).  %@NL@%
  698. %@NL@%
  699. Part 3, "Special Environments," describes new graphics capabilities. It also
  700. shows how to program in mixed languages and offers tips to make your
  701. programs more portable. Microsoft C helps you create graphics applications
  702. easily. The Microsoft C run-time libraries contain graphics functions for
  703. low-level graphics operations, such as drawing lines, rectangles, and
  704. circles. The libraries also contain functions for creating presentation
  705. graphics, such as pie charts and bar charts.  %@NL@%
  706. %@NL@%
  707. Part 4, "OS/2 Support," describes how the Professional Development System
  708. helps you build OS/2 applications. The three chapters in Part 4 provide
  709. information about dual-mode applications, creating multithread applications,
  710. and creating dynamic-link libraries.  %@NL@%
  711. %@NL@%
  712. A postage-paid documentation feedback card is at the end of this manual.
  713. After you have had a chance to become familiar with Microsoft C 6.0 and its
  714. documentation, please give us your opinion. Your ideas will help us as we
  715. develop future documentation. Also at the end of this book is a Product
  716. Assistance Request form. If you need to call Microsoft for assistance, use
  717. this form first to compile and organize pertinent information.  %@NL@%
  718. %@NL@%
  719. %@NL@%
  720. %@2@%%@CR:C6A00010002 @%%@AB@%Document Conventions%@AE@%%@EH@%%@NL@%
  721. %@NL@%
  722. ────────────────────────────────────────────────────────────────────────────%@NL@%
  723. NOTE
  724.  
  725. %@AI@%The pages that follow use the term "OS/2" to refer to the OS/2
  726. %@AI@%systems─Microsoft Operating System/2 (MS%@AI@%(R)%@AE@%%@AI@% OS/2) and IBM%@AE@%%@AI@%(R) %@AE@%%@AI@%OS/2.
  727. %@AI@%Similarly, the term "DOS" refers to both the MS-DOS%@AE@%%@AI@%(R)%@AE@%%@AI@% and IBM Personal
  728. %@AI@%Computer DOS operating systems. The name of a specific operating system is
  729. %@AI@%used when it is necessary to note features that are unique to the system.%@AE@%%@AE@%%@NL@%
  730.  
  731.  
  732. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  733. %@NL@%
  734. %@AB@%Example%@AE@%                           %@AB@%Description%@AE@%
  735. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  736. STDIO.H                           Uppercase letters indicate file names, 
  737.                                   segment names, registers, and terms used
  738.                                   at the DOS- or OS/2-command level.
  739.  
  740. %@AB@%_cdecl%@AE@%                            Boldface letters indicate C keywords, 
  741.                                   operators, language-specific characters,
  742.                                   and library functions, as well as OS/2 
  743.                                   functions. Within discussions of syntax,
  744.                                   bold type indicates that the text must 
  745.                                   be entered exactly as shown.
  746.  
  747. %@AI@%expression%@AE@%                        Words in italics indicate placeholders 
  748.                                   for information you must supply, such as
  749.                                   a file name. Italics are also 
  750.                                   occasionally used for emphasis in the 
  751.                                   text.
  752.  
  753. «%@AI@%option%@AE@%»                          Items inside double square brackets are 
  754.                                   optional. 
  755.  
  756. %@AB@%#pragma pack%@AE@% {%@AB@%1%@AE@%|%@AB@%2%@AE@%}                Braces and a vertical bar indicate a 
  757.                                   choice among two or more items. You must
  758.                                   choose one of these items unless double 
  759.                                   square brackets surround the braces.
  760.  
  761. %@AS@%CL A.C B.C C.OBJ%@AE@%                  This font is used for examples, user 
  762.                                   input, program output, and error 
  763.                                   messages in text.
  764.  
  765. %@AB@%CL%@AE@% %@AI@%options%@AE@% «%@AI@% files%@AE@%...»            A horizontal ellipsis following an item 
  766.                                   indicates that more items having the 
  767.                                   same form may follow.
  768.  
  769. %@AS@%while%@AE@%(   )                        A vertical ellipsis tells you that part 
  770. {                                 of the example program has been 
  771.    .                              intentionally omitted.
  772.    .                              
  773.    .                              
  774. }                                 
  775.  
  776. CTRL+ENTER                        Small capital letters are used for the 
  777.                                   names of keys on the keyboard. When you 
  778.                                   see a plus sign (+) between two key 
  779.                                   names, you should hold down the first 
  780.                                   key while pressing the second.
  781.  
  782.                                   The carriage-return key (sometimes 
  783.                                   appearing as a bent arrow on the 
  784.                                   keyboard) is called ENTER.
  785.  
  786.                                   The cursor-movement keys (sometimes 
  787.                                   called direction keys) are called the 
  788.                                   ARROW keys. Individual keys are referred
  789.                                   to by their direction (LEFT, UP) or by 
  790.                                   the name on the key (PGUP).
  791.  
  792. "argument"                        Quotation marks enclose a new term the 
  793.                                   first time it is defined in text.
  794.  
  795. Enhanced Graphics Adapter (EGA)   The first time an acronym is used, it is
  796.                                   often spelled out.
  797.  
  798. %@NL@%
  799. %@NL@%
  800. %@NL@%
  801. %@NL@%
  802. %@NL@%
  803. %@CR:C6A-Part 01 @%%@1@%%@AB@%PART I  Improving Program Performance%@AE@%%@EH@%%@NL@%
  804. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  805. %@NL@%
  806. The Microsoft C Professional Development System helps you create the
  807. fastest, smallest applications using its sophisticated optimizer and
  808. enhanced memory management capabilities.  %@NL@%
  809. %@NL@%
  810. Chapter 1 tells when to use certain optimizations and describes how
  811. Microsoft C generates code that is efficient in execution speed and size.
  812. Chapter 2 explains the sophisticated tools Microsoft C gives you to allocate
  813. and manage program memory, including the new %@AB@%_based%@AE@% type. For cases where
  814. your program requires localized optimization, you can use the in-line
  815. assembler, described in Chapter 3, to introduce the tightest possible code.
  816. If your application requires floating-point math computations, you will find
  817. Chapter 4 helpful in explaining the options in the Microsoft C math
  818. packages; it explains which floating-point options yield the fastest,
  819. smallest, and most flexible code.  %@NL@%
  820. %@NL@%
  821. %@NL@%
  822. %@NL@%
  823. %@NL@%
  824. %@NL@%
  825. %@NL@%
  826. %@CR:C6A00010001 @%%@1@%%@AB@%Chapter 1  Optimizing C Programs%@AE@%%@EH@%%@NL@%
  827. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  828. %@NL@%
  829. The Microsoft C compiler translates C source statements into
  830. machineexecutable instructions. In addition, the compiler rewrites or
  831. "optimizes"  parts of your program to make it more efficient in ways that
  832. are not apparent at the source level.  %@NL@%
  833. %@NL@%
  834. The compiler performs three general types of optimization:  %@NL@%
  835. %@NL@%
  836. %@NL@%
  837.   1.  It modifies or moves sections of code so that fewer instructions are
  838.       used, or so that the instructions used make more efficient use of the
  839.       processor.%@NL@%
  840. %@NL@%
  841.   2.  It moves code and combines operations to maximize use of registers
  842.       because operations on data stored in processor registers are far
  843.       faster than the same operations on data stored in memory.%@NL@%
  844. %@NL@%
  845.   3.  It eliminates sections of code that are redundant or unused.%@NL@%
  846. %@NL@%
  847. %@NL@%
  848. This chapter explains the various ways you can control how the Microsoft C
  849. compiler optimizes your code.  %@NL@%
  850. %@NL@%
  851. %@NL@%
  852. %@2@%%@CR:C6A00010002 @%%@AB@%1.1  Controlling Optimization from the Programmer's WorkBench%@AE@%%@EH@%%@NL@%
  853. %@NL@%
  854. The Programmer's WorkBench (PWB) is an integrated development environment
  855. for editing, building, and debugging applications written in Microsoft C.
  856. For more information on the PWB, see %@AI@%Installing and Using the Microsoft C
  857. %@AI@%Professional Development System%@AE@%.  %@NL@%
  858. %@NL@%
  859. There are two ways to compile from inside the Programmer's WorkBench:  %@NL@%
  860. %@NL@%
  861. %@NL@%
  862.   1.  Debug compile. In a default debug compile, the compiler performs no
  863.       optimizations at all.%@NL@%
  864. %@NL@%
  865.   2.  Release compile. In a default release compile, the compiler performs
  866.       most optimizations.%@NL@%
  867. %@NL@%
  868. %@NL@%
  869. By modifying the settings in C Global Build Options, C Debug Build Options,
  870. and C Release Build Options (on the Options menu), you can fine-tune
  871. optimization by individually enabling or disabling any of the optimizations
  872. the compiler performs.  %@NL@%
  873. %@NL@%
  874. The optimizations in each of the Build Options dialog boxes correspond to a
  875. command-line option to CL. (In fact, the PWB constructs a command line from
  876. your input and passes it to CL.)  %@NL@%
  877. %@NL@%
  878. ────────────────────────────────────────────────────────────────────────────%@NL@%
  879. NOTE
  880.  
  881. %@AI@%In this chapter, optimization options are discussed in terms of the effect
  882. %@AI@%of the optimization, the command-line option to invoke the optimization, and
  883. %@AI@%pragmas that control the optimization. All of these optimizations can be
  884. %@AI@%controlled at the compilation-unit (file) level using the Build Options
  885. %@AI@%dialog boxes.%@AE@%%@NL@%
  886. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  887. %@NL@%
  888. %@NL@%
  889. %@2@%%@CR:C6A00010003 @%%@AB@%1.2  Controlling Optimization from the Command Line%@AE@%%@EH@%%@NL@%
  890. %@NL@%
  891. Controlling optimization from the command line requires that you determine
  892. which optimizations you need for your application. You then specify those
  893. optimizations using command-line options that begin with /O (and in some
  894. cases /G).  %@NL@%
  895. %@NL@%
  896. If there is any conflict between options, the compiler uses the last option
  897. specified on the command line. The command line  %@NL@%
  898. %@NL@%
  899. %@AS@%  CL /Oa /Ol /Ot TEST.C%@AE@%%@NL@%
  900. %@NL@%
  901. compiles the program TEST.C. It specifies that the compiler can  %@NL@%
  902. %@NL@%
  903. %@NL@%
  904.   ■   Optimize on the assumption that you are doing no aliasing (/Oa)%@NL@%
  905. %@NL@%
  906.   ■   Perform loop optimization (/Ol)%@NL@%
  907. %@NL@%
  908.   ■   Perform other general speed-enhancing optimizations (/Ot)%@NL@%
  909. %@NL@%
  910. %@NL@%
  911. The preceding command line can also be written  %@NL@%
  912. %@NL@%
  913. %@AS@%  CL /Oalt TEST.C%@AE@%%@NL@%
  914. %@NL@%
  915. %@NL@%
  916. %@2@%%@CR:C6A00010004 @%%@AB@%1.3  Controlling Optimization with Pragmas%@AE@%%@EH@%%@NL@%
  917. %@NL@%
  918. Occasionally you will need to exercise a fine level of control over compiler
  919. optimizations. Command-line options allow you to control optimization over
  920. an entire compilation unit (file). In addition, Microsoft C supports several
  921. pragmas that allow you to exercise such control on a per-function basis.  %@NL@%
  922. %@NL@%
  923. The pragmas that control optimization are described in this chapter under
  924. the type of optimization they affect.  %@NL@%
  925. %@NL@%
  926. %@AU@% The optimize pragma is new to version 6.0.%@AE@%  %@NL@%
  927. %@NL@%
  928. In version 6.0, you can control each of the following optimization
  929. parameters on a function-by-function basis using the %@AB@%optimize%@AE@% pragma:  %@NL@%
  930. %@NL@%
  931. %@NL@%
  932.   ■   Behavior of code with respect to aliasing (%@AB@%a%@AE@% and %@AB@%w%@AE@%)%@NL@%
  933. %@NL@%
  934.   ■   Reduction of local common subexpressions (%@AB@%c%@AE@%)%@NL@%
  935. %@NL@%
  936.   ■   Reduction of global common subexpressions (%@AB@%g%@AE@%)%@NL@%
  937. %@NL@%
  938.   ■   Global register allocation (%@AB@%e%@AE@%)%@NL@%
  939. %@NL@%
  940.   ■   Loop optimization (%@AB@%l%@AE@%)%@NL@%
  941. %@NL@%
  942.   ■   Aggressiveness of optimizations (%@AB@%z%@AE@%)%@NL@%
  943. %@NL@%
  944.   ■   Disabling of unsafe optimizations (%@AB@%n%@AE@%)%@NL@%
  945. %@NL@%
  946.   ■   Achieving consistent floating-point results (%@AB@%p%@AE@%)%@NL@%
  947. %@NL@%
  948.   ■   Optimizing for smaller code size or for faster execution speed (%@AB@%t%@AE@%)%@NL@%
  949. %@NL@%
  950. %@NL@%
  951. Any optimization or combination of options can be enabled or disabled using
  952. the %@AB@%optimize%@AE@% pragma. For example, if you have one function that uses aliases
  953. heavily, you need to inhibit optimizations that could cause problems with
  954. aliases. You do not, however, want to inhibit these optimizations for code
  955. that does not do aliasing. To do this, use the %@AB@%optimize %@AE@%pragma as follows:  %@NL@%
  956. %@NL@%
  957. %@AS@%  /* Function(s) that do not do aliasing. */
  958. %@AS@%  .
  959. %@AS@%  .
  960. %@AS@%  .
  961. %@AS@%  #pragma optimize( "a", off )
  962. %@AS@%  /* Function(s) that do aliasing. */
  963. %@AS@%  .
  964. %@AS@%  .
  965. %@AS@%  .
  966. %@AS@%  #pragma optimize( "a", on )
  967. %@AS@%  /* More function(s) that do not do aliasing. */%@AE@%%@NL@%
  968. %@NL@%
  969. The parameters to the %@AB@%optimize %@AE@%pragma can be combined in a string to enable
  970. or disable multiple options at once. For example,  %@NL@%
  971. %@NL@%
  972. %@AS@%  #pragma optimize( "lge", off )%@AE@%%@NL@%
  973. %@NL@%
  974. disables loop optimization, global common subexpression optimization, and
  975. global register allocation.  %@NL@%
  976. %@NL@%
  977. %@NL@%
  978. %@2@%%@CR:C6A00010005 @%%@AB@%1.4  Default Optimization%@AE@%%@EH@%%@NL@%
  979. %@NL@%
  980. Many optimizations are not explicitly disabled by any command-line option
  981. except /Od (disable optimizations). These optimizations are small in scope
  982. and are almost always helpful. They include  %@NL@%
  983. %@NL@%
  984. %@NL@%
  985.   ■   Short range common subexpression elimination%@NL@%
  986. %@NL@%
  987.   ■   Dead-store elimination%@NL@%
  988. %@NL@%
  989.   ■   Constant propagation%@NL@%
  990. %@NL@%
  991. %@NL@%
  992. %@NL@%
  993. %@3@%%@CR:C6A00010006 @%%@AB@%1.4.1  Common Subexpression Elimination%@AE@%%@EH@%%@NL@%
  994. %@NL@%
  995. In common subexpression elimination, the compiler finds code containing
  996. repeated subexpressions and produces modified code in which the
  997. subexpressions are evaluated only once. Subexpression elimination is usually
  998. done with temporary variables as shown in the following example:  %@NL@%
  999. %@NL@%
  1000. %@AS@%  a = b + c * d;
  1001. %@AS@%  x = c * d / y;%@AE@%%@NL@%
  1002. %@NL@%
  1003. The preceding two lines contain the common subexpression %@AS@% c * d%@AE@%. This code
  1004. can be modified to evaluate %@AS@% c * d %@AE@% only once; the result is placed in a
  1005. temporary variable (usually a register):  %@NL@%
  1006. %@NL@%
  1007. %@AS@%  tmp = c * d;
  1008. %@AS@%  a = b + tmp;
  1009. %@AS@%  x = tmp / y;%@AE@%%@NL@%
  1010. %@NL@%
  1011. %@NL@%
  1012. %@3@%%@CR:C6A00010007 @%%@AB@%1.4.2  Dead-Store Elimination%@AE@%%@EH@%%@NL@%
  1013. %@NL@%
  1014. Dead-store elimination is an extension of common subexpression elimination.
  1015. Variables that contain the same value in a short piece of code can be
  1016. combined into a single temporary variable.  %@NL@%
  1017. %@NL@%
  1018. In the following code fragment, the compiler detects that the expression %@AS@%
  1019. %@AS@%func( x ) %@AE@% is equivalent to %@AS@% func( a + b )%@AE@%:  %@NL@%
  1020. %@NL@%
  1021. %@AS@%  x = a + b;
  1022. %@AS@%  x = func( x );%@AE@%%@NL@%
  1023. %@NL@%
  1024. Thus, the compiler can rewrite the code as follows:  %@NL@%
  1025. %@NL@%
  1026. %@AS@%  x = func( a + b);%@AE@%%@NL@%
  1027. %@NL@%
  1028. %@NL@%
  1029. %@3@%%@CR:C6A00010008 @%%@AB@%1.4.3  Constant Propagation%@AE@%%@EH@%%@NL@%
  1030. %@NL@%
  1031. When doing constant propagation, the compiler analyzes variable assignments
  1032. and determines if they can be changed to constant assignments. In the
  1033. following example, the variable %@AS@% i %@AE@% must have a value of %@AS@% 7 %@AE@% when it is
  1034. assigned to %@AS@% j%@AE@%:  %@NL@%
  1035. %@NL@%
  1036. %@AS@%  i = 7;
  1037. %@AS@%  j = i;%@AE@%%@NL@%
  1038. %@NL@%
  1039. Instead of assigning %@AS@% i %@AE@% to %@AS@% j%@AE@%, the constant %@AS@% 7 %@AE@% can be assigned to %@AS@% j%@AE@%:  %@NL@%
  1040. %@NL@%
  1041. %@AS@%  i = 7;
  1042. %@AS@%  j = 7;%@AE@%%@NL@%
  1043. %@NL@%
  1044. While you could make any of these changes in the source file, doing so might
  1045. reduce the readability of the program. In many cases, optimizations not only
  1046. increase the efficiency of the program but allow you to write more readable
  1047. code without any actual efficiency loss.  %@NL@%
  1048. %@NL@%
  1049. %@AU@% Remove optimization before using a symbolic debugger.%@AE@%  %@NL@%
  1050. %@NL@%
  1051. In some cases, you might want to disable even the default optimizations.
  1052. Because optimizations may rearrange code in the object file, it can become
  1053. difficult to recognize parts of your code during debugging. It is usually
  1054. best to remove all optimization before using a symbolic debugger. You can
  1055. remove all optimization with the /Od (disable optimizations) option.  %@NL@%
  1056. %@NL@%
  1057. You can disable all optimizations for a function by including the statement %@AS@%
  1058. %@AS@%#pragma optimize( "", off )%@AE@%. To restore optimization to its former state,
  1059. use the statement %@AS@% #pragma optimize( "", on )%@AE@%.  %@NL@%
  1060. %@NL@%
  1061. %@NL@%
  1062. %@2@%%@CR:C6A00010009 @%%@AB@%1.5  Customizing Your Optimizations%@AE@%%@EH@%%@NL@%
  1063. %@NL@%
  1064. The default optimizations are sufficient for many applications, but you may
  1065. want to tune your programs according to criteria not known to the compiler.
  1066. The optimization options offer you a way of providing the compiler specific
  1067. goals for optimizing your code.  %@NL@%
  1068. %@NL@%
  1069. %@NL@%
  1070. %@3@%%@CR:C6A00010010 @%%@AB@%1.5.1  Choosing Speed or Size (/Ot and /Os)%@AE@%%@EH@%%@NL@%
  1071. %@NL@%
  1072. In addition to the default optimizations, the Microsoft C compiler also
  1073. automatically uses the /Ot option, which optimizes for speed. The /Ot option
  1074. enables optimizations that increase speed but may also increase size. If you
  1075. would rather optimize for program size, use the /Os option. The /Os option
  1076. enables optimizations that decrease program size but may also decrease
  1077. program speed.  %@NL@%
  1078. %@NL@%
  1079. To optimize for speed or size on a per-function basis, use the %@AB@%optimize
  1080. %@AB@%%@AE@%pragma with the %@AB@%t %@AE@%option. The on setting instructs the compiler to optimize
  1081. for speed; the off setting instructs the compiler to optimize for
  1082. compactness of code. For example,  %@NL@%
  1083. %@NL@%
  1084. %@AS@%  #pragma optimize( "t", off )    /* Optimize for smallest 
  1085. %@AS@%                                    code. */
  1086. %@AS@%  .
  1087. %@AS@%  .
  1088. %@AS@%  .
  1089. %@AS@%  #pragma optimize( "t", on )     /* Optimize for fastest 
  1090. %@AS@%                                    code. */%@AE@%%@NL@%
  1091. %@NL@%
  1092. %@NL@%
  1093. %@3@%%@CR:C6A00010011 @%%@AB@%1.5.2  Generating Intrinsic Functions (/Oi)%@AE@%%@EH@%%@NL@%
  1094. %@NL@%
  1095. In place of some normal function calls, the C compiler can insert "intrinsic
  1096. functions," which operate more quickly. Every time a function is called, a
  1097. set of instructions must be executed to store parameters and to create space
  1098. for local variables. When the function returns, more code must be executed
  1099. to release space used by local variables and parameters and to return values
  1100. to the calling routine. These instructions take time to execute. In the
  1101. context of an average-sized function, the additional code is minimal, but if
  1102. the function is only a line or two, the additional code can comprise almost
  1103. half of the function's compiled code.  %@NL@%
  1104. %@NL@%
  1105. One way to avoid this type of code expansion is to avoid such short
  1106. functions, especially in often-used sections of code where speed is
  1107. critical. But many library functions contain only a line or two of code. The
  1108. compiler provides two forms of certain library functions. One form is a
  1109. standard C function, which requires the overhead of a function call. The
  1110. other form is a set of instructions that  %@NL@%
  1111. %@NL@%
  1112. performs the same action as the function without issuing a function call.
  1113. This second form is called an intrinsic function. Intrinsic functions are
  1114. always faster than their function-call equivalents and can provide
  1115. significant optimizations at the object-code level.  %@NL@%
  1116. %@NL@%
  1117. For example, the function %@AB@%strcpy%@AE@% might be written as follows:  %@NL@%
  1118. %@NL@%
  1119. %@AS@%  int strcpy(char * dest, char * source)
  1120. %@AS@%  {
  1121. %@AS@%      while( *dest++ = *source++ );
  1122. %@AS@%  }%@AE@%%@NL@%
  1123. %@NL@%
  1124. The compiler contains an intrinsic form of %@AB@%strcpy%@AE@%. If you instruct the
  1125. compiler to generate intrinsic functions, any call to %@AB@%strcpy%@AE@% will be
  1126. replaced with this intrin-sic form.  %@NL@%
  1127. %@NL@%
  1128. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1129. NOTE
  1130.  
  1131. %@AI@%While the example above is written in C for clarity, most of the library
  1132. %@AI@%functions use assembly language to take full advantage of the 80x86
  1133. %@AI@%instruction set. Intrinsic functions are not simply library functions
  1134. %@AI@%defined as macros. %@AE@%%@NL@%
  1135. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1136. %@NL@%
  1137. Compiling with the /Oi option causes the compiler to use the intrinsic forms
  1138. of the following functions:  %@NL@%
  1139. %@NL@%
  1140. %@AB@%abs             labs            memset          strcat%@AE@%
  1141. %@AB@%_disable        lrotl           outp            strcmp%@AE@%
  1142. %@AB@%_enable         lrotr           outpw           strcpy%@AE@%
  1143. %@AB@%fabs            memcmp          rotl            strlen%@AE@%
  1144. %@AB@%inp             memcpy          rotr            strset%@AE@%
  1145. %@AB@%inpw            
  1146.  
  1147. While the following floating-point functions do not have true intrinsic
  1148. forms, they do have versions that pass arguments directly to the
  1149. floating-point chip instead of pushing them on the normal argument stack:  %@NL@%
  1150. %@NL@%
  1151. %@AB@%acos            fmod            acosl           fmodl%@AE@%
  1152. %@AB@%asin            log             asinl           logl%@AE@%
  1153. %@AB@%atan            log10           atanl           log10l%@AE@%
  1154. %@AB@%atan2           pow             atan2l          powl%@AE@%
  1155. %@AB@%ceil            sin             ceill           sinl%@AE@%
  1156. %@AB@%cos             sinh            cosl            sinhl%@AE@%
  1157. %@AB@%cosh            sqrt            coshl           sqrtl%@AE@%
  1158. %@AB@%exp             tan             expl            tanl%@AE@%
  1159. %@AB@%floor           tanh            floorl          tanhl%@AE@%
  1160.  
  1161. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1162. %@AU@%WARNING%@AE@%%@NL@%
  1163. %@NL@%
  1164. The compiler performs optimizations assuming math intrinsics have no side
  1165. effects. This assumption is true except if you have written your own %@AB@%matherr
  1166. %@AB@%%@AE@%function and that function alters global variables. If you have written a
  1167. %@AB@%matherr %@AE@%function to handle floating-point errors, and your function has side
  1168. effects, use the%@AB@% function %@AE@%pragma to instruct the compiler not to generate
  1169. intrinsic code for math functions.%@NL@%
  1170. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1171. %@NL@%
  1172.  
  1173. If you want the compiler to generate intrinsic functions for only a subset
  1174. of the functions listed above, use the %@AB@%intrinsic %@AE@%pragma rather than the /Oi
  1175. option. The %@AB@%intrinsic%@AE@% pragma has the following format:  %@NL@%
  1176. %@NL@%
  1177. %@AS@%  #pragma intrinsic( function1, ... )%@AE@%%@NL@%
  1178. %@NL@%
  1179. If you want to have intrinsic functions generated for most of the functions
  1180. above and function calls for only a few, compile with the /Oi option and
  1181. force function use with the %@AB@%function %@AE@%pragma. The %@AB@%function%@AE@% pragma has the
  1182. following format:  %@NL@%
  1183. %@NL@%
  1184. %@AS@%  #pragma function( function1, ... )%@AE@%%@NL@%
  1185. %@NL@%
  1186. The following code illustrates the use of the %@AB@%intrinsic%@AE@% pragma:  %@NL@%
  1187. %@NL@%
  1188. %@AS@%  #pragma intrinsic(abs) 
  1189. %@AS@%  
  1190. %@AS@%  void main( void )
  1191. %@AS@%  {
  1192. %@AS@%      int i, j;
  1193. %@AS@%  
  1194. %@AS@%      i = big_routine_1();
  1195. %@AS@%      j = abs( i );
  1196. %@AS@%      big_routine_2( j );
  1197. %@AS@%  }%@AE@%%@NL@%
  1198. %@NL@%
  1199. Generating intrinsic functions for this program causes the call to %@AB@%abs %@AE@%to be
  1200. replaced with assembly-language code that takes the absolute value of a
  1201. number. The program will execute more quickly because the function-calling
  1202. overhead is no longer required when %@AB@%abs %@AE@%is called.  %@NL@%
  1203. %@NL@%
  1204. In the previous example, the overall speed increase is small because there
  1205. is only a single call to %@AB@%abs%@AE@%. In the following example, where the call to
  1206. %@AB@%abs %@AE@%is in a loop and there are many calls, you can save a significant amount
  1207. of execution time by generating intrinsic functions.  %@NL@%
  1208. %@NL@%
  1209. %@AS@%  #pragma intrinsic( abs )
  1210. %@AS@%  void main( void )
  1211. %@AS@%  {
  1212. %@AS@%  int i, j, x;%@AE@%%@NL@%
  1213. %@NL@%
  1214. %@AS@%  for( j = 0; j < 1000; j++ )
  1215. %@AS@%      {
  1216. %@AS@%          for( i = 0; i < 1000; i++)
  1217. %@AS@%          {
  1218. %@AS@%              x += abs( i - j );
  1219. %@AS@%          }
  1220. %@AS@%     }
  1221. %@AS@%     printf( "The value of x is %d\n", x ); 
  1222. %@AS@%  }%@AE@%%@NL@%
  1223. %@NL@%
  1224. The following is a list of restrictions on using the intrinsic forms of
  1225. function calls:  %@NL@%
  1226. %@NL@%
  1227. %@NL@%
  1228.   ■   Do not use the intrinsic forms of the floating-point math functions
  1229.       with the alternate math libraries (%@AI@%m%@AE@%LIBCA%@AI@%y%@AE@%.LIB).%@NL@%
  1230. %@NL@%
  1231.   ■   Do not use the intrinsic forms of the floating-point math functions in
  1232.       OS/2 dynamic-link libraries (DLLs) because you must use the alternate
  1233.       math library with LLIBCDLL.LIB.%@NL@%
  1234. %@NL@%
  1235.   ■   If you use the /Ox (maximum optimization) option, you are enabling the
  1236.       /Oi (generate intrinsic functions) option. Be careful that your use of
  1237.       /Ox does not conflict with the points listed previously.%@NL@%
  1238. %@NL@%
  1239. %@NL@%
  1240. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1241. NOTE
  1242.  
  1243. %@AI@%Intrinsic versions of %@AB@%_enable%@AE@%%@AI@%, %@AE@%%@AI@%%@AB@%_disable%@AE@%%@AE@%%@AI@%, %@AE@%%@AI@%%@AB@%inp%@AE@%%@AE@%%@AI@%, %@AE@%%@AI@%%@AB@%outp%@AE@%%@AE@%%@AI@%, %@AE@%%@AI@%%@AB@%inpw%@AE@%%@AE@%%@AI@%, and %@AE@%%@AI@%%@AB@%outpw 
  1244. %@AB@%%@AE@%%@AE@%%@AI@%do not work under OS/2. You must use the library versions. You can use the
  1245. %@AI@%%@AE@%%@AI@%%@AB@%function %@AE@%%@AE@%%@AI@%pragm%@AE@%%@AI@%a to force these functions to become library calls.%@AE@%%@AE@%%@NL@%
  1246. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1247. %@NL@%
  1248. %@NL@%
  1249. %@3@%%@CR:C6A00010012 @%%@AB@%1.5.3  Assuming No Aliasing (/Oa and /Ow)%@AE@%%@EH@%%@NL@%
  1250. %@NL@%
  1251. An "alias" is a name used to refer to a memory location already referred to
  1252. by a different name. Because a memory access takes more time than it takes
  1253. to access the CPU's registers, the compiler tries to store frequently used
  1254. variables in registers. However, the aliasing reduces the extent to which a
  1255. compiler can keep variables in registers.  %@NL@%
  1256. %@NL@%
  1257. A pointer is a reference to a memory location. Because the value of a
  1258. pointer is not determined until the program is run, the compiler has no way
  1259. of knowing which memory location will be modified when the program executes;
  1260. it could be a reference to a variable. Therefore, the compiler must assume
  1261. that any time the value pointed to by any pointer changes, the value of any
  1262. variable might also change. This limits the extent to which the compiler can
  1263. move values from memory to registers.  %@NL@%
  1264. %@NL@%
  1265. The /Oa option tells the compiler to ignore the possibility of multiple
  1266. aliases for a memory location. In the list that follows, the term
  1267. "reference" means read or write; that is, whether a variable is on the
  1268. left-hand side of an assignment statement or the right-hand side, you are
  1269. still referring to it. In addition, any function calls that use a variable
  1270. as a parameter are references to that variable. When you tell the compiler
  1271. to assume that you are not doing aliasing, it expects that the following
  1272. rules are being followed for any variable not declared as %@AB@%volatile%@AE@%:  %@NL@%
  1273. %@NL@%
  1274. %@NL@%
  1275.   ■   If a variable is used directly, no pointers are used to reference that
  1276.       variable.%@NL@%
  1277. %@NL@%
  1278.   ■   If a pointer is used to refer to a variable, that variable is not
  1279.       referred to directly.%@NL@%
  1280. %@NL@%
  1281.   ■   If a pointer is used to modify a memory location, no other pointers
  1282.       are used to access the same memory location.%@NL@%
  1283. %@NL@%
  1284. %@NL@%
  1285. To clarify how these rules affect your code, consider the following example:
  1286. %@NL@%
  1287. %@NL@%
  1288. %@AS@%  char    p;
  1289. %@AS@%  char    *ptr_p;
  1290. %@AS@%  
  1291. %@AS@%  ptr_p = &p;    /* Take the address of p. */%@AE@%%@NL@%
  1292. %@NL@%
  1293. You can now refer either to %@AS@% *ptr_p %@AE@% or to %@AS@% p%@AE@%, but not to both within the
  1294. same function. If you must refer to the variable by both names, you are
  1295. using aliases.  %@NL@%
  1296. %@NL@%
  1297. Code referring to the same location with two pointers uses aliases. For
  1298. example,  %@NL@%
  1299. %@NL@%
  1300. %@AS@%  char    *p_buf;
  1301. %@AS@%  char    *p_alias;
  1302. %@AS@%  
  1303. %@AS@%  if( (p_alias = p_buf = malloc( 5000 )) == NULL )
  1304. %@AS@%      return;
  1305. %@AS@%  else
  1306. %@AS@%  {
  1307. %@AS@%      .
  1308. %@AS@%      .
  1309. %@AS@%      .
  1310. %@AS@%  }%@AE@%%@NL@%
  1311. %@NL@%
  1312. The code in the example above is common. It demonstrates dynamically
  1313. allocating a block of memory from the heap, and preserving the original
  1314. address in %@AS@% p_buf%@AE@%. The program then performs all pointer arithmetic on the
  1315. alias %@AS@% p_alias%@AE@%. When the function finishes with the block of memory, %@AS@% p_buf %@AE@%
  1316. is a valid argument for the %@AB@%free %@AE@%function because it still contains the
  1317. original address.  %@NL@%
  1318. %@NL@%
  1319. %@AU@% The /Oa and /Ow options tell the compiler that you have not used aliases in
  1320. %@AU@%your code.%@AE@%  %@NL@%
  1321. %@NL@%
  1322. The difference between the /Oa and the /Ow option is that when you use /Oa
  1323. you specify that you will not be doing aliasing (which allows the compiler
  1324. to perform significant optimizations that might not otherwise have been
  1325. possible), and that function calls are safe. The /Ow option is similar to
  1326. the /Oa option, except that after a function call, pointer variables must be
  1327. reloaded from memory.  %@NL@%
  1328. %@NL@%
  1329. Here is an example of a program that would be a poor candidate for the /Oa
  1330. or /Ow optimization option:  %@NL@%
  1331. %@NL@%
  1332. %@AS@%  int g;
  1333. %@AS@%  
  1334. %@AS@%  void main( void )
  1335. %@AS@%  {
  1336. %@AS@%      add_em( &g );
  1337. %@AS@%  }
  1338. %@AS@%  
  1339. %@AS@%  int add_em( int *p )
  1340. %@AS@%  {
  1341. %@AS@%      *p = 2;          /* Assign a value to an alias for g. */
  1342. %@AS@%      g = 3;           /* Assign a value directly to g. */
  1343. %@AS@%      return( *p + g );
  1344. %@AS@%  }%@AE@%%@NL@%
  1345. %@NL@%
  1346. In the function %@AS@% add_em%@AE@%, both %@AS@% g %@AE@% and %@AS@% *p %@AE@% refer to the same memory
  1347. location. This location is first assigned %@AS@% 2%@AE@%, then %@AS@% 3%@AE@%. The value pointed to
  1348. by %@AS@% *p %@AE@% (the alias for %@AS@% g%@AE@%) is then added to %@AS@% g%@AE@%, and the result is returned
  1349. to the main program. If you do not use the /Oa command-line option, the
  1350. compiler assumes that the reference to %@AS@% *p %@AE@% could refer to the same memory
  1351. location as does %@AS@% g %@AE@% and makes no attempt to use a register to store the
  1352. value of either. If, however, you do specify the /Oa option, the compiler
  1353. assumes that %@AS@% g %@AE@% and %@AS@% *p %@AE@% refer to different memory locations and stores
  1354. each in a different register. At the return statement, %@AS@% g %@AE@% will have a
  1355. different value than %@AS@% *p%@AE@%, even though both aliases should actually contain
  1356. the same value.  %@NL@%
  1357. %@NL@%
  1358. Note that the compiler keeps values in registers for only a limited time. If
  1359. different aliases to a memory location occur in different functions, for
  1360. example, they will not cause unexpected results. When in doubt, avoid
  1361. aliasing.  %@NL@%
  1362. %@NL@%
  1363. %@AU@% Bugs involving aliasing are difficult to spot.%@AE@%  %@NL@%
  1364. %@NL@%
  1365. Aliasing bugs most frequently show up as corruption of data. If you find
  1366. that global or local variables are being assigned seemingly random values,
  1367. take the following steps to determine if you have a problem with
  1368. optimization and aliasing:  %@NL@%
  1369. %@NL@%
  1370. %@NL@%
  1371.   ■   Compile the program with /Od (disable optimizations).%@NL@%
  1372. %@NL@%
  1373.   ■   If the program works when compiled with the /Od option, check your
  1374.       normal compile options for the /Oa option (assume no aliasing).%@NL@%
  1375. %@NL@%
  1376.   ■   If you were using the /Oa option, fix your compile options so that /Oa
  1377.       is not specified.%@NL@%
  1378. %@NL@%
  1379. %@NL@%
  1380. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1381. NOTE
  1382. %@AI@%You can instruct the compiler to disable optimizations that are unsafe with
  1383. %@AI@%code that does aliasing by using the %@AB@%optimize%@AE@%%@AI@% pragma with the %@AE@%%@AI@%%@AB@%a%@AE@%%@AE@%%@AI@% or %@AE@%%@AI@%%@AB@%w%@AE@%%@AE@%%@AI@% option.%@CR:C6A00010013 @%%@AE@%%@AE@%%@NL@%
  1384. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1385. %@NL@%
  1386. %@NL@%
  1387. %@3@%%@CR:C6A00010014 @%%@AB@%1.5.4  Performing Loop Optimizations (/Ol)%@AE@%%@EH@%%@NL@%
  1388. %@NL@%
  1389. The /Ol option enables a set of optimizations involving loops. Because loops
  1390. involve sections of code that are executed repeatedly, they are targets for
  1391. optimization. These optimizations all involve moving code or rewriting code
  1392. so that it executes faster.  %@NL@%
  1393. %@NL@%
  1394. Loop optimization can be turned on with the /Ol option or with the %@AB@%loop_opt %@AE@%
  1395. pragma. The following line enables loop optimization for all subsequent
  1396. functions:  %@NL@%
  1397. %@NL@%
  1398. %@AS@%  #pragma loop_opt( on )%@AE@%%@NL@%
  1399. %@NL@%
  1400. The following line turns it off:  %@NL@%
  1401. %@NL@%
  1402. %@AS@%  #pragma loop_opt( off )%@AE@%%@NL@%
  1403. %@NL@%
  1404. %@AU@% The /Ol option removes invariant code.%@AE@%  %@NL@%
  1405. %@NL@%
  1406. An optimal loop contains only expressions whose values change through each
  1407. execution of the loop. Any subexpression whose value is constant should be
  1408. evaluated before the body of the loop is executed. Unfortunately, these
  1409. subexpressions are not always readily apparent. The optimizer can remove
  1410. many of these expressions from the body of a loop at compile time. This
  1411. example illustrates invariant code in a loop:  %@NL@%
  1412. %@NL@%
  1413. %@AS@%  i = -100;
  1414. %@AS@%  while( i < 0 )
  1415. %@AS@%  {
  1416. %@AS@%      i += x + y;
  1417. %@AS@%  }%@AE@%%@NL@%
  1418. %@NL@%
  1419. In the preceding example, the expression %@AS@% x + y %@AE@% does not change in the loop
  1420. body. Loop optimization removes this subexpression from the body of the loop
  1421. so that it is only executed once, not every time the loop body is executed.
  1422. The optimizer will change the code to the following fragment:  %@NL@%
  1423. %@NL@%
  1424. %@AS@%  i = -100;
  1425. %@AS@%  t = x + y;
  1426. %@AS@%  while( i < 0 )
  1427. %@AS@%  {
  1428. %@AS@%      i += t;
  1429. %@AS@%  }%@AE@%%@NL@%
  1430. %@NL@%
  1431. Loop optimization is much more effective when the compiler can assume no
  1432. aliasing. While you can use loop optimization without the /Oa or /Ow option,
  1433. use /Oa to ensure that the most options possible are used.  %@NL@%
  1434. %@NL@%
  1435. Here is a code fragment that could have an aliasing problem:  %@NL@%
  1436. %@NL@%
  1437. %@AS@%  i = -100;
  1438. %@AS@%  while( i < 0 )
  1439. %@AS@%  {
  1440. %@AS@%      i += x + y;
  1441. %@AS@%      *p = i;
  1442. %@AS@%  }%@AE@%%@NL@%
  1443. %@NL@%
  1444. If you do not specify the /Oa option, the compiler must assume that either %@AS@%
  1445. %@AS@%x %@AE@% or %@AS@% y %@AE@% could be modified by the assignment to %@AS@% *p%@AE@%. Therefore, the
  1446. compiler cannot assume the subexpression %@AS@% x + y %@AE@% is constant for each loop
  1447. iteration. If you specify that you are not doing any aliasing (with the /Oa
  1448. option), the compiler assumes that modifying %@AS@% *p %@AE@% cannot affect either %@AS@% x %@AE@%
  1449. or %@AS@% y%@AE@%, and that the subexpression is indeed constant and can be removed from
  1450. the loop, as in the previous example.  %@NL@%
  1451. %@NL@%
  1452. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1453. NOTE
  1454.  
  1455. %@AI@%All loop optimizations specified by the /Ol option or the %@AB@%loop_opt%@AE@%%@AI@% pragma
  1456. %@AI@%are safe optimizations. To enable aggressive loop optimizations, you must
  1457. %@AI@%use the enable aggressive optimizations (/Oz) option. While the
  1458. %@AI@%optimizations enabled by the combination of /Ol and /Oz are not safe for all
  1459. %@AI@%cases, they will work properly for most programs.%@AE@%%@AE@%%@NL@%
  1460. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1461. %@NL@%
  1462. %@NL@%
  1463. %@3@%%@CR:C6A00010015 @%%@AB@%1.5.5  Disabling Unsafe Loop Optimizations (/On)%@AE@%%@EH@%%@NL@%
  1464. %@NL@%
  1465. The disable unsafe loop optimizations (/On) option is an obsolescent option
  1466. and is only retained for compatibility with existing makefiles. Loop
  1467. optimizations are, by default, safe optimizations. The /On option is the
  1468. default and has the opposite effect of the /Oz (enable aggressive
  1469. optimizations) option.  %@NL@%
  1470. %@NL@%
  1471. %@NL@%
  1472. %@3@%%@CR:C6A00010016 @%%@AB@%1.5.6  Enabling Aggressive Optimizations (/Oz)%@AE@%%@EH@%%@NL@%
  1473. %@NL@%
  1474. The compiler can perform extremely aggressive optimizations. These
  1475. optimizations produce high code quality both in terms of speed and size.
  1476. Certain programs, however, cannot be optimized with the technologies enabled
  1477. by the /Oz option. For these programs, you should not specify this option;
  1478. you can still use all other optimization options.  %@NL@%
  1479. %@NL@%
  1480. Because the optimization strategies enabled by the /Oz option are so
  1481. aggressive, they are not part of the maximum optimization (/Ox) option.  %@NL@%
  1482. %@NL@%
  1483. Examples of the effects of the /Oz option are  %@NL@%
  1484. %@NL@%
  1485. %@NL@%
  1486.   ■   Loop optimization (/Ol). Loop optimization enables a technology that
  1487.       anticipates program flow and tries to remove invariant expressions
  1488.       from loops. When you specify the enable aggressive optimizations
  1489.       option (/Oz), the compiler removes invariant expressions even when it
  1490.       might cause an error. Errors with the enable aggressive optimizations
  1491.       option occur most often when an invariant expression that can cause an
  1492.       exception is protected by an %@AB@%if%@AE@% statement. The invariant expression is
  1493.       hoisted out of the loop body, causing it to be evaluated prior to the
  1494.       evaluation of the %@AB@%if%@AE@% statement that was designed to protect it. Here
  1495.       are two examples that illustrate this problem:
  1496. %@NL@%
  1497. %@AS@%        for( i = 0; i  100; ++i )
  1498. %@AS@%            if( float_val != 0.0F )
  1499. %@AS@%            /* Protect against divide-by-zero. */
  1500. %@AS@%                float_result = pi / float_val;%@AE@%%@NL@%
  1501.  
  1502. %@NL@%
  1503. %@AS@%        while( condition )
  1504. %@AS@%            if( ptr_val != NULL )
  1505. %@AS@%              /* Protect pointer dereference. */
  1506. %@AS@%                char_var = *ptr_val;%@AE@%%@NL@%
  1507. %@NL@%
  1508. %@NL@%
  1509.   ■   Global register allocation (/Oe). The enable aggressive optimizations
  1510.       option enables some register allocation strategies that can cause
  1511.       invalid segment selectors to be placed in registers. Although this
  1512.       problem is benign in DOS, it causes protection faults in OS/2.%@NL@%
  1513. %@NL@%
  1514. %@NL@%
  1515. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1516. NOTE
  1517.  
  1518. %@AI@%You can instruct the compiler to enable aggressive optimizations on a
  1519. %@AI@%function-by-function basis by using the %@AB@%optimize%@AE@%%@AI@% pragma with the %@AE@%%@AI@%%@AB@%z %@AE@%%@AE@%%@AI@%option.%@AE@%%@AE@%%@NL@%
  1520. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1521. %@NL@%
  1522. %@NL@%
  1523. %@3@%%@CR:C6A00010017 @%%@AB@%1.5.7  Removing Stack Probes (/Gs)%@AE@%%@EH@%%@NL@%
  1524. %@NL@%
  1525. Every time a function is called, the stack provides space for all parameters
  1526. and local variables declared in that function. A short assembly function
  1527. that checks for a stack overflow condition is then called. Stack overflows
  1528. are usually caused either by infinite loops or by runaway recursive
  1529. routines. Such errors can also be caused by extremely large parameters or
  1530. local variables.  %@NL@%
  1531. %@NL@%
  1532. Stack probes can be important during program development. Stack-overflow
  1533. errors alert you to problems in your code. When the program has been tested,
  1534. however, stack checking often becomes unnecessary. The compiler allows you
  1535. to remove stack-checking code with either the /Gs option or the %@AB@%check_stack
  1536. %@AB@%%@AE@%pragma. Eliminating stack probes produces programs that are smaller and that
  1537. run more quickly.  %@NL@%
  1538. %@NL@%
  1539. %@NL@%
  1540. %@3@%%@CR:C6A00010018 @%%@AB@%1.5.8  Enabling Global Register Allocation (/Oe)%@AE@%%@EH@%%@NL@%
  1541. %@NL@%
  1542. The global register allocation option (/Oe) instructs the compiler to
  1543. analyze your program and allocate CPU registers as efficiently as possible.
  1544. Without the global register allocation option, the compiler uses the CPU's
  1545. registers for several purposes:  %@NL@%
  1546. %@NL@%
  1547. %@NL@%
  1548.   ■   Holding temporary copies of variables%@NL@%
  1549. %@NL@%
  1550.   ■   Holding variables declared with the %@AB@%register%@AE@% keyword%@NL@%
  1551. %@NL@%
  1552.   ■   Passing parameters to functions declared with the %@AB@%_fastcall%@AE@% keyword
  1553.       (or functions in programs compiled with the /Gr command-line option)%@NL@%
  1554. %@NL@%
  1555. %@NL@%
  1556. When you enable global register allocation, the compiler ignores the
  1557. %@AB@%register%@AE@% keyword and allocates register storage to variables (and possibly
  1558. to common subexpressions). The compiler allocates register storage to
  1559. variables or subexpressions according to frequency of use. Because of the
  1560. limited number of physical registers, variables held in registers are
  1561. sometimes placed back in memory to free the register for another use. Here
  1562. is a C program example that demonstrates how the compiler might rewrite your
  1563. code to accomplish this:  %@NL@%
  1564. %@NL@%
  1565. %@AS@%  /* Original program */
  1566. %@AS@%  
  1567. %@AS@%  func()
  1568. %@AS@%  {
  1569. %@AS@%      int i, j;
  1570. %@AS@%      char *pc;
  1571. %@AS@%  
  1572. %@AS@%      for( i = 0; i < 1000; ++i )
  1573. %@AS@%      {
  1574. %@AS@%          j = i / 3;
  1575. %@AS@%          *pc++ = (char)i;
  1576. %@AS@%      }
  1577. %@AS@%  
  1578. %@AS@%      for( j = 0, --pc; j < 1000; 
  1579. %@AS@%          ++j, --pc )
  1580. %@AS@%          *pc--;
  1581. %@AS@%  }%@AE@%%@NL@%
  1582. %@NL@%
  1583. %@AS@%  /* Example of how the compiler might optimize the
  1584. %@AS@%   * code to move i and j in and out of registers */
  1585. %@AS@%  
  1586. %@AS@%  func()
  1587. %@AS@%  {
  1588. %@AS@%      int i, j;
  1589. %@AS@%      char *pc;
  1590. %@AS@%  
  1591. %@AS@%      { 
  1592. %@AS@%      register int i; /* i is in a register for this block. */
  1593. %@AS@%          for( i = 0; i < 1000; ++i )
  1594. %@AS@%          {
  1595. %@AS@%              j = i / 3;
  1596. %@AS@%              *pc++ = (char)i;
  1597. %@AS@%          }
  1598. %@AS@%      }
  1599. %@AS@%  
  1600. %@AS@%      {
  1601. %@AS@%      register int j; /* j is in a register for this block. */
  1602. %@AS@%          for( j = 0, --pc; j < 1000; 
  1603. %@AS@%              ++j, --pc )
  1604. %@AS@%              *pc--;
  1605. %@AS@%      }
  1606. %@AS@%  }%@AE@%%@NL@%
  1607. %@NL@%
  1608. In the preceding example, there are blocks (enclosed in curly braces) whose
  1609. only purpose is to delimit the span of code across which variables should
  1610. remain in registers.  %@NL@%
  1611. %@NL@%
  1612. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1613. NOTE
  1614.  
  1615. %@AI@%You can enable or disable global register allocation on a
  1616. %@AI@%function-by-function basis using the %@AB@%optimize%@AE@%%@AI@% pragma with the %@AE@%%@AI@%%@AB@%e%@AE@%%@AE@%%@AI@% option.%@CR:C6A00010019 @%%@AE@%%@AE@%%@NL@%
  1617. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1618. %@NL@%
  1619. %@NL@%
  1620. %@3@%%@CR:C6A00010020 @%%@AB@%1.5.9  Enabling Common Subexpression Optimization (/Oc and /Og)%@AE@%%@EH@%%@NL@%
  1621. %@NL@%
  1622. When you use option /Og (enable global common subexpression optimizations),
  1623. the compiler searches entire functions for common subexpressions. Option /Oc
  1624. (default common subexpression optimization) examines only short sections of
  1625. code for common subexpressions. You can disable default common subexpression
  1626. optimization with the /Od option. For more information about common
  1627. subexpression optimization, see Section 1.4, "Default Optimization."  %@NL@%
  1628. %@NL@%
  1629. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1630. NOTE
  1631.  
  1632. %@AI@%You can enable or disable block-scope common subexpression optimization on a
  1633. %@AI@%function-by-function basis using the %@AB@%optimize%@AE@%%@AI@% pragma with the %@AE@%%@AI@%%@AB@%c %@AE@%%@AE@%%@AI@%option. You
  1634. %@AI@%can enable or disable global common subexpression optimization on a
  1635. %@AI@%function-by-function basis using the %@AE@%%@AI@%%@AB@%optimize%@AE@%%@AE@%%@AI@% pragma with the %@AE@%%@AI@%%@AB@%g %@AE@%%@AE@%%@AI@%option.%@CR:C6A00010021 @%%@AE@%%@AE@%%@NL@%
  1636. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1637. %@NL@%
  1638. %@NL@%
  1639. %@3@%%@CR:C6A00010022 @%%@AB@%1.5.10  Achieving Consistent Floating-Point Results (/Op)%@AE@%%@EH@%%@NL@%
  1640. %@NL@%
  1641. Floating-point numbers stored in memory use either 32, 64, or 80 bits,
  1642. depending on whether they are of type %@AB@%float%@AE@%, type %@AB@%double%@AE@%, or type %@AB@%long
  1643. %@AB@%double%@AE@%. The 80%@AI@%x%@AE@%87 family of coprocessors uses 80-bit registers for all
  1644. operations. If a value of type %@AB@%float%@AE@% or type %@AB@%double%@AE@% is kept in these
  1645. registers through a number of operations, it will be more accurate than if
  1646. that value is moved to and from memory between operations.  %@NL@%
  1647. %@NL@%
  1648. Because of the difference in precision between memory and register
  1649. representation of a floating-point number, a value stored in memory is not
  1650. always equal to the same value in the 80%@AI@%x%@AE@%87 register.  %@NL@%
  1651. %@NL@%
  1652. The difference in precision primarily affects strict equality or strict
  1653. inequality tests (%@AB@%==%@AE@% and %@AB@%!=%@AE@%); however, relational tests of magnitude (%@AB@%>%@AE@%, %@AB@%>=%@AE@%,
  1654. %@AB@%%@AE@%, and %@AB@%%@AE@%) can behave erroneously if the coprocessor is able to maintain
  1655. significant digits that memory variables cannot.  %@NL@%
  1656. %@NL@%
  1657. You can avoid the difference in precision by using the /Op option. This
  1658. option forces floating-point values to be written to memory between
  1659. floating-point operations. While storing these values to memory reduces the
  1660. precision of floating-point expressions, it also ensures that these
  1661. expressions will produce consistent results regardless of the rest of the
  1662. code.  %@NL@%
  1663. %@NL@%
  1664. You can change the handling of floating-point results on a
  1665. function-by-function basis using the %@AB@%optimize %@AE@%pragma with the %@AB@%p %@AE@%option.%@CR:C6A00010023 @%  %@NL@%
  1666. %@NL@%
  1667. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1668. NOTE
  1669.  
  1670. %@AI@%Using the /Op option suppresses other optimizations because the
  1671. %@AI@%floating-point registers are not available for storage of intermediate
  1672. %@AI@%results. Because you suppress these optimizations, code compiled with the
  1673. %@AI@%/Op option executes more slowly than code compiled without this option.
  1674. %@AI@%Careful coding practices, especially in tests of strict equality and
  1675. %@AI@%inequality, can alleviate the need for this option.%@AE@%%@NL@%
  1676. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1677. %@NL@%
  1678. %@NL@%
  1679. %@3@%%@CR:C6A00010024 @%%@AB@%1.5.11  Using the 80186, 80188, or 80286 Processor (/G0, /G1, /G2)%@AE@%%@EH@%%@NL@%
  1680. %@NL@%
  1681. The compiler generates 8086 object code (/G0) unless you take special steps.
  1682. Because the newer processors (the 80186, 80188, and 80286) are
  1683. backwardcompatible with the 8086 instruction set, using this instruction set
  1684. ensures compatibility with all 80%@AI@%x%@AE@%86-based computers. While you gain
  1685. compatibility across the entire family of 80%@AI@%x%@AE@%86 processors, you lose the
  1686. advantage of some of the more powerful instructions in the newer processors.
  1687. %@NL@%
  1688. %@NL@%
  1689. If you know your program will only be running on an 80186, 80188, or 80286
  1690. processor, you can cause the compiler to generate instructions specific to
  1691. these processors. These instructions increase the speed of your program, but
  1692. you lose compatibility with machines that use older processors in the 80%@AI@%x%@AE@%86
  1693. family. Table 1.1 lists the options for processor-specific code generation:
  1694. %@NL@%
  1695. %@NL@%
  1696. %@AB@%Table 1.1  %@AB@%Processor Compatibility%@AE@%%@AE@%
  1697.  
  1698. %@TH:   6   432 02 23 53 @%Command-Line Option    Compatible Processors%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%/G0                    8088, 8086, 80188, 80186, 80286, 80388, 80486/G1                    80188, 80186, 80286, 80386, 80486/G2                    80286, 80386, 80486%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   6   432 02 23 53 @%
  1699.  
  1700. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1701. NOTE
  1702.  
  1703. %@AI@%When developing only for OS/2, always use the /G2 option, because OS/2 does
  1704. %@AI@%not run on the 8086, 8088, 80186, or 80188. Do not use /G2 for Family
  1705. %@AI@%Applications because they might be run on machines with 8088, 8086, 80188,
  1706. %@AI@%or 80186 processors.%@AE@%%@NL@%
  1707. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1708. %@NL@%
  1709. %@NL@%
  1710. %@3@%%@CR:C6A00010025 @%%@AB@%1.5.12  Optimizing for Maximum Efficiency (/Ox)%@AE@%%@EH@%%@NL@%
  1711. %@NL@%
  1712. The /Ox option combines a number of different optimizations:  %@NL@%
  1713. %@NL@%
  1714. %@NL@%
  1715.   ■   Enable global register allocation (/Oe)%@NL@%
  1716. %@NL@%
  1717.   ■   Enable global common subexpression optimization (/Og)%@NL@%
  1718. %@NL@%
  1719.   ■   Enable block-scoped common subexpression optimization (/Oc)%@NL@%
  1720. %@NL@%
  1721.   ■   Generate intrinsic functions (/Oi)%@NL@%
  1722. %@NL@%
  1723.   ■   Perform loop optimizations (/Ol)%@NL@%
  1724. %@NL@%
  1725.   ■   Optimize for speed (/Ot)%@NL@%
  1726. %@NL@%
  1727.   ■   Remove stack probes (/Gs)%@NL@%
  1728. %@NL@%
  1729. %@NL@%
  1730. %@AU@% Use /Ozax /Gr to get the fastest program.%@AE@%  %@NL@%
  1731. %@NL@%
  1732. The /Ox option does not include several optimizations that can improve code
  1733. efficiency: /Oa (assume no aliasing), /Oz (enable aggressive optimizations),
  1734. and /Gr (use fastcall calling convention). Before enabling these
  1735. optimizations, you should read the sections that describe the /Oa and /Oz
  1736. options and the fastcall calling convention to determine if they are
  1737. appropriate for your application.  %@NL@%
  1738. %@NL@%
  1739. %@AU@% Use the optimize pragma to reduce code size.%@AE@%  %@NL@%
  1740. %@NL@%
  1741. If you are more concerned with executable file size than execution time, use
  1742. the /Ox and /Gs options, then issue the %@AB@%optimize %@AE@%pragma as follows:  %@NL@%
  1743. %@NL@%
  1744. %@AS@%  #pragma optimize( "t", off )%@AE@%%@NL@%
  1745. %@NL@%
  1746. This set of options produces the smallest possible code, while also
  1747. performing some speed optimizations.  %@NL@%
  1748. %@NL@%
  1749. %@NL@%
  1750. %@2@%%@CR:C6A00010026 @%%@AB@%1.6  Linker (LINK) Options that Control Optimization%@AE@%%@EH@%%@NL@%
  1751. %@NL@%
  1752. Most code optimization is performed before the object file is produced.
  1753. There are four optimizations that the linker can perform to speed program
  1754. execution and reduce the disk space used by an executable file.  %@NL@%
  1755. %@NL@%
  1756. %@NL@%
  1757. %@3@%%@CR:C6A00010027 @%%@AB@%1.6.1  Enabling Far Call Optimization (/FARCALLTRANSLATION)%@AE@%%@EH@%%@NL@%
  1758. %@NL@%
  1759. You can call a function two ways. In a far call, the function is called
  1760. using both the segment and the offset of the function. This allows a program
  1761. to call a routine outside a 64K segment. In a near call, both the calling
  1762. statement and the function must be located in the same segment. Only the
  1763. offset is used to access the function; the segment address is implicit. You
  1764. can only use near calls to routines located in the same segment.%@CR:C6A00010028 @%%@CR:C6A00010029 @%  %@NL@%
  1765. %@NL@%
  1766. Because of the architecture of the processor, near function calls execute
  1767. faster than far calls. The decision to declare functions as near or far is
  1768. often made when selecting a memory model. As it is difficult to determine
  1769. where the linker will place a given function in memory, it is impractical
  1770. for the programmer to choose the way a function is called.  %@NL@%
  1771. %@NL@%
  1772. %@AU@% Use /FARCALLTRANSLATION with medium, large, and huge model programs.%@AE@%  %@NL@%
  1773. %@NL@%
  1774. The /FARCALLTRANSLATION option enables far call optimization. When you use
  1775. this option, any function calls within the same segment as the function
  1776. being called are converted to near calls. This optimization has no effect if
  1777. you have selected the tiny, small, or compact model, because all calls are
  1778. already near calls.  %@NL@%
  1779. %@NL@%
  1780. The abbreviation for the /FARCALLTRANSLATION option is /F.  %@NL@%
  1781. %@NL@%
  1782. %@NL@%
  1783. %@4@%%@AB@%How /FARCALLTRANSLATION Affects Your Code%@AE@%%@EH@%%@NL@%
  1784. %@NL@%
  1785. The linker can perform a form of post-optimization (an optimization that
  1786. occurs after most of the actual code generation is complete) that translates
  1787. far calls into near calls when possible. This optimization allows a given
  1788. function to be called with both near and far calls in the same program. To
  1789. perform this translation, the linker takes a section of object code such as
  1790. %@NL@%
  1791. %@NL@%
  1792. %@AS@%  CALL    FAR    _func%@AE@%%@NL@%
  1793. %@NL@%
  1794. where %@AS@% func %@AE@% is defined in the current segment, and replaces it with the
  1795. following code:  %@NL@%
  1796. %@NL@%
  1797. %@AS@%  PUSH    CS
  1798. %@AS@%  CALL    NEAR    _func
  1799. %@AS@%  NOP%@AE@%%@NL@%
  1800. %@NL@%
  1801. This substitution works because the linker has inserted %@AS@% PUSH CS %@AE@% to place a
  1802. far return address on the stack.  %@NL@%
  1803. %@NL@%
  1804. %@AU@% Use /FARCALLTRANSLATION with /PACKCODE.%@AE@%  %@NL@%
  1805. %@NL@%
  1806. The /FARCALLTRANSLATION option is most effective when used in conjunction
  1807. with the /PACKCODE option discussed in Section 1.6.2. Using the /PACKCODE
  1808. option causes far calls that were intersegment to become intrasegment calls.
  1809. The /FARCALLTRANSLATION feature can then take advantage of the new grouping
  1810. to translate all intrasegment far calls into near calls.%@CR:C6A00010030 @%  %@NL@%
  1811. %@NL@%
  1812. %@NL@%
  1813. %@4@%%@AB@%Benefits of /FARCALLTRANSLATION%@AE@%%@EH@%%@NL@%
  1814. %@NL@%
  1815. The /FARCALLTRANSLATION option is of significant benefit to protected-mode
  1816. programs. Table 1.2 illustrates why.  %@NL@%
  1817. %@NL@%
  1818. %@AB@%Table 1.2  %@AB@%Processor Clock Cycles for Calling Sequence%@AE@%%@AE@%
  1819.  
  1820. %@TH:  34  1635 03 20 15 11 15 15 @%                    %@AB@%Cycles  (Real%@AE@%             %@AB@%Cycles  %@AE@%                    %@AB@%Mode)%@AE@%                     %@AB@%(Protected %@AE@%                                              %@AB@%Mode)%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%%@AE@%                                   %@AB@%%@AE@%           %@AB@%%@AE@%               %@AB@%%@AE@%%@AB@%Instructions%@AE@%        286            %@AB@%386%@AE@%        %@AB@%286%@AE@%            %@AB@%386%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Far Function Call                             %@AS@%CALL FAR PTR _func%@AE@%  13             17         26             34Total               13             17         26             34%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Near Function Call                            %@AS@%PUSH CS%@AE@%             3              2          3              2%@AS@%CALL NEAR PTR %@AE@%      7              7          7              7%@AS@%_func%@AE@%                                                        %@AS@%NOP%@AE@%                 3              3          3              3Total               13             12         13             12%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Savings             0              5          13             22%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  34  1635 03 20 15 11 15 15 @%
  1821.  
  1822. %@NL@%
  1823. %@3@%%@CR:C6A00010031 @%%@AB@%1.6.2  Packing Code (/PACKCODE)%@AE@%%@EH@%%@NL@%
  1824. %@NL@%
  1825. The /PACKCODE linker option groups neighboring code segments together. When
  1826. used with the /F option, the /PACKCODE option greatly increases the number
  1827. of near calls that can be made to a function. This option can be followed
  1828. with a limit (expressed in bytes) at which to stop packing and to begin a
  1829. new group. Here is the syntax for the /PACKCODE option: ;/PACKCODE option  %@NL@%
  1830. %@NL@%
  1831. %@AS@%  /PACKCODE:number%@AE@%%@NL@%
  1832. %@NL@%
  1833. where %@AI@%number%@AE@% is an optional hexadecimal, octal, or decimal number that
  1834. specifies the limit for packing. The radix (octal, decimal, or hexadecimal)
  1835. is specified just as you would specify it to a C program.%@CR:C6A00010032 @%  %@NL@%
  1836. %@NL@%
  1837. %@AB@%Radix%@AE@%                             %@AB@%Rules for Specification%@AE@%
  1838. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1839. Octal                             Specify the octal number with a leading 
  1840.                                   0. You can only use the digits 0 through
  1841.                                   7 in an octal number. For example, 07777.
  1842.  
  1843. Decimal                           Specify the decimal number without a 
  1844.                                   leading 0. For example, 65530.
  1845.  
  1846. Hexadecimal                       Specify the hexadecimal number with a 
  1847.                                   leading 0x. For example, 0x3FFF.
  1848.  
  1849. If you omit the packing limit, the linker supplies a default value of 65,
  1850. 530.  %@NL@%
  1851. %@NL@%
  1852. The abbreviation for the /PACKCODE option is /PACKC.  %@NL@%
  1853. %@NL@%
  1854. %@NL@%
  1855. %@3@%%@CR:C6A00010033 @%%@AB@%1.6.3  Packing Data (/PACKDATA)%@AE@%%@EH@%%@NL@%
  1856. %@NL@%
  1857. The /PACKDATA option is analogous to the /PACKCODE option, except that it
  1858. groups together neighboring data segments instead of code segments. This
  1859. option is most useful when you have a large-model program that exceeds the
  1860. OS/2 limitation of 255 segments. By using /PACKDATA, you can group segments,
  1861. thereby reducing the total number OS/2 has to manage. Here is the syntax for
  1862. the /PACKDATA option:%@CR:C6A00010034 @%  %@NL@%
  1863. %@NL@%
  1864. %@AS@%  /PACKDATA:number%@AE@%%@NL@%
  1865. %@NL@%
  1866. where %@AI@%number%@AE@% is an optional hexadecimal, octal, or decimal number that
  1867. specifies the limit for packing. The radix (hexadecimal, octal, or decimal)
  1868. is specified just as you would specify it to a C program. For more
  1869. information on specifying hexadecimal, octal, or decimal numbers, see
  1870. Section 1.6.2 above.  %@NL@%
  1871. %@NL@%
  1872. If the packing limit is omitted, the linker supplies a default value of
  1873. 65,535 (0xFFFF).%@CR:C6A00010035 @%  %@NL@%
  1874. %@NL@%
  1875. The abbreviation for the /PACKDATA option is /PACKD.  %@NL@%
  1876. %@NL@%
  1877. %@NL@%
  1878. %@3@%%@CR:C6A00010036 @%%@AB@%1.6.4  Packing the Executable File (/EXEPACK)%@AE@%%@EH@%%@NL@%
  1879. %@NL@%
  1880. The executable file created by the compiler often contains sequences of
  1881. repeated bytes. You can remove these repeated sequences with the /EXEPACK
  1882. option. This decreases the size of the resulting executable file as well as
  1883. program load time.%@CR:C6A00010037 @%  %@NL@%
  1884. %@NL@%
  1885. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1886. %@AU@%WARNING%@AE@%%@NL@%
  1887. %@NL@%
  1888. Because the /EXEPACK option removes debug information from the executable
  1889. file, you should not use it with the /CODEVIEW option.%@NL@%
  1890. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1891. %@NL@%
  1892. %@NL@%
  1893. %@2@%%@CR:C6A00010038 @%%@AB@%1.7  Optimizing in Different Environments%@AE@%%@EH@%%@NL@%
  1894. %@NL@%
  1895. The environment in which you plan to use a program can have a bearing on the
  1896. types of optimizations that you should use.  %@NL@%
  1897. %@NL@%
  1898. %@NL@%
  1899. %@3@%%@CR:C6A00010039 @%%@AB@%1.7.1  Optimizing in DOS%@AE@%%@EH@%%@NL@%
  1900. %@NL@%
  1901. You need not take special precautions for programs written under DOS unless
  1902. you are writing a terminate-and-stay-resident (TSR) program. If an
  1903. interrupt-driven routine could modify a memory location in a program, you
  1904. should declare that variable %@AB@%volatile%@AE@%.  %@NL@%
  1905. %@NL@%
  1906. %@NL@%
  1907. %@3@%%@CR:C6A00010040 @%%@AB@%1.7.2  Optimizing in OS/2%@AE@%%@EH@%%@NL@%
  1908. %@NL@%
  1909. Many of the rules for interrupt routines apply to OS/2. If one thread can
  1910. modify variables in another thread, declare these variables as %@AB@%volatile%@AE@%.  %@NL@%
  1911. %@NL@%
  1912. %@NL@%
  1913. %@3@%%@CR:C6A00010041 @%%@AB@%1.7.3  Optimizing in Microsoft Windows(tm)%@AE@%%@EH@%%@NL@%
  1914. %@NL@%
  1915. Microsoft Windows(tm) can move segments dynamically. As a result of dynamic
  1916. heap compaction, pointers maintained in registers can be invalidated. The
  1917. /Ow option instructs the compiler that you will not be using aliases, but
  1918. that Windows might cause certain optimizations to be unsafe across function
  1919. calls.  %@NL@%
  1920. %@NL@%
  1921. If you are not using any aliases you must still use the /Ow option with
  1922. Windows programs. See Section 1.5.3, "Assuming No Aliasing (/Oa and /Ow),"
  1923. for more information.  %@NL@%
  1924. %@NL@%
  1925. %@NL@%
  1926. %@2@%%@CR:C6A00010042 @%%@AB@%1.8  Choosing Function-Calling Conventions%@AE@%%@EH@%%@NL@%
  1927. %@NL@%
  1928. In Microsoft C, version 6.0, functions can call other functions using three
  1929. different conventions. Note that, while no calling convention has been
  1930. defined as "standard," most C compilers use conventions similar to those
  1931. described here. The C calling convention requires the most object code to
  1932. set up, but it is the only calling convention that supports functions with
  1933. variable-length argument lists. The FORTRAN/Pascal calling convention is
  1934. more compact, but does not allow for variable-length argument lists. The
  1935. %@AB@%_fastcall%@AE@%, or register calling convention is the fastest of the three
  1936. calling conventions, but it does not support  variable-length argument lists
  1937. or mixed-language program interfaces.  %@NL@%
  1938. %@NL@%
  1939. %@NL@%
  1940. %@3@%%@CR:C6A00010043 @%%@AB@%1.8.1  The C Calling Convention (/Gd)%@AE@%%@EH@%%@NL@%
  1941. %@NL@%
  1942. Because C allows functions to have a variable number of parameters,
  1943. parameters must be pushed onto the stack from right to left. (If parameters
  1944. were pushed from left to right, it would be difficult for the compiler to
  1945. determine which parameter was first.) If you do not specify command-line
  1946. options that modify the function-calling convention, the C calling
  1947. convention is used; otherwise, the %@AB@%_cdecl%@AE@% keyword must be used before any
  1948. function using the C calling convention.%@CR:C6A00010044 @%%@CR:C6A00010045 @%%@CR:C6A00010046 @%  %@NL@%
  1949. %@NL@%
  1950. If, for example, you use the /Gr (register calling convention) option when
  1951. you compile, and the function %@AS@% add_two %@AE@% must have the C calling convention,
  1952. declare %@AS@% add_two %@AE@% as follows:  %@NL@%
  1953. %@NL@%
  1954. %@AS@%  int _cdecl add_two( int x, int y );%@AE@%%@NL@%
  1955. %@NL@%
  1956. %@NL@%
  1957. %@3@%%@CR:C6A00010047 @%%@AB@%1.8.2  The FORTRAN/Pascal Calling Convention (/Gc)%@AE@%%@EH@%%@NL@%
  1958. %@NL@%
  1959. Use the FORTRAN/Pascal calling convention for any functions declared with
  1960. either the %@AB@%_fortran%@AE@% or %@AB@%_pascal%@AE@% keywords. (The two keywords currently produce
  1961. identical results.) Parameters to these functions are always pushed on the
  1962. stack from left to right. While any function can be declared with the
  1963. FORTRAN/ Pascal convention, it is used primarily for prototypes to Pascal or
  1964. FORTRAN routines called from within C programs. This calling convention can
  1965. also produce smaller, faster programs.  %@NL@%
  1966. %@NL@%
  1967. The /Gc option (generate Pascal-style function calls) can be used to make
  1968. all functions in a file observe the FORTRAN/Pascal calling convention.  %@NL@%
  1969. %@NL@%
  1970. Note that C run-time library routines must still be called using C calling
  1971. conventions. Because these routines are declared using the %@AB@%_cdecl%@AE@% keyword
  1972. header files, you must include the appropriate header files in any program
  1973. using run-time library routines.  %@NL@%
  1974. %@NL@%
  1975. Functions with variable-length parameter lists (such as %@AB@%printf%@AE@%) cannot use
  1976. the FORTRAN/Pascal calling convention.  %@NL@%
  1977. %@NL@%
  1978. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1979. NOTE
  1980.  
  1981. %@AI@%The /ML, /MD, and /MT options cause all floating-point functions to be
  1982. %@AI@%declared as FORTRAN/Pascal. See Chapter 16, "Dynamic Linking with OS/2," for
  1983. %@AI@%more information.%@AE@%%@NL@%
  1984. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  1985. %@NL@%
  1986. %@NL@%
  1987. %@3@%%@CR:C6A00010048 @%%@AB@%1.8.3  The Register Calling Convention (/Gr)%@AE@%%@EH@%%@NL@%
  1988. %@NL@%
  1989. You can decrease execution time if parameters to functions are passed in
  1990. registers rather than on the stack. Compiling with the /Gr command-line
  1991. option enables the register calling convention for an entire file. The
  1992. %@AB@%_fastcall%@AE@% keyword enables the register calling convention on a
  1993. function-by-function basis.  %@NL@%
  1994. %@NL@%
  1995. Because the 80%@AI@%x%@AE@%86 processor has a limited number of registers, only the
  1996. first three parameters are allocated to registers; the rest are passed using
  1997. the FORTRAN/Pascal calling convention. The register calling convention can
  1998. increase the speed of a program.%@CR:C6A00010049 @%%@CR:C6A00010050 @%%@CR:C6A00010051 @%  %@NL@%
  1999. %@NL@%
  2000. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2001. NOTE
  2002.  
  2003. %@AI@%The compiler allocates different registers for variables declared as
  2004. %@AB@%register %@AE@%%@AI@%and for passing arguments using the register calling convention.
  2005. %@AI@%This calling convention will not conflict with any register variables that
  2006. %@AI@%you may have declared.%@AE@%%@AE@%%@NL@%
  2007. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  2008. %@NL@%
  2009. Exercise caution when using the register calling convention for any function
  2010. written in in-line assembly language. Your use of registers in
  2011. assembly-language could conflict with the compiler's use of registers for
  2012. storing parameters.  %@NL@%
  2013. %@NL@%
  2014. %@NL@%
  2015. %@3@%%@CR:C6A00010052 @%%@AB@%1.8.4  The _fastcall Calling Convention%@AE@%%@EH@%%@NL@%
  2016. %@NL@%
  2017. This section describes the details of the %@AB@%_fastcall%@AE@% calling convention. The
  2018. information is for the use of assembly-language programmers who are
  2019. interested in using either the in-line assembler or the Microsoft Macro
  2020. Assembler (MASM) to write functions declared as %@AB@%_fastcall%@AE@%. Functions
  2021. declared as %@AB@%_fastcall%@AE@% accept arguments in registers rather than on the
  2022. stack; functions declared as %@AB@%_cdecl%@AE@% or %@AB@%_pascal%@AE@% accept parameters only on the
  2023. stack.  %@NL@%
  2024. %@NL@%
  2025. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2026. %@AU@%WARNING%@AE@%%@NL@%
  2027. %@NL@%
  2028. The register usage documented here applies only to Microsoft C, version 6.0.
  2029. It may change in future releases of the compiler.%@NL@%
  2030. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2031. %@NL@%
  2032. %@NL@%
  2033. %@4@%%@AB@%Argument-Passing Convention%@AE@%%@EH@%%@NL@%
  2034. %@NL@%
  2035. The %@AB@%_fastcall%@AE@% calling convention is a "strongly typed" register calling
  2036. convention. This typing allows the compiler to generate better code by
  2037. passing arguments in registers that correspond to the data type you are
  2038. passing. Because the compiler chooses registers depending on the type of the
  2039. argument and not in a strict linear order, the calling program and called
  2040. function must agree on the types of the arguments in order to communicate
  2041. data correctly.  %@NL@%
  2042. %@NL@%
  2043. For each type of argument there is a list of register candidates. The
  2044. arguments are allocated to registers or, if no suitable register remains
  2045. unused, are pushed onto the stack left-to-right. Each argument is put in the
  2046. first register candidate that does not already contain an argument. Table
  2047. 1.3 shows the basic types and the register candidate list for each.  %@NL@%
  2048. %@NL@%
  2049. %@AB@%Table   %@AB@%1.3 Register Candidates%@AE@%%@AE@%
  2050.  
  2051. %@TH:  11   634 02 33 43 @%%@AB@%Type%@AE@%                             Register Candidates%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%character                        AL, DL, BLunsigned character               AL, DL, BLinteger                          AX, DX, BXunsigned integer                 AX, DX, BXlong integer                     DX:AXunsigned long integer            DX:AXnear pointer                     BX, AX, DXfar or huge pointer              passed on the stack%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  11   634 02 33 43 @%
  2052.  
  2053. All far and huge pointers are pushed on the stack, as are all structures,
  2054. unions, and floating-point types.%@CR:C6A00010053 @%  %@NL@%
  2055. %@NL@%
  2056. %@NL@%
  2057. %@4@%%@AB@%Return Value Convention%@AE@%%@EH@%%@NL@%
  2058. %@NL@%
  2059. The %@AB@%_fastcall%@AE@% return value convention is based on the size of the return
  2060. value, except with floating-point types. All floating point types are
  2061. returned on the top of the NDP stack. For more information about the NDP
  2062. stack and returning floating-point values, see Chapter 4, "Controlling
  2063. Floating-Point Math Operations." The following list shows how values 4 bytes
  2064. or smaller, including unions and structures, are returned from a %@AB@%_fastcall
  2065. %@AB@%%@AE@%function.  %@NL@%
  2066. %@NL@%
  2067. %@AB@%Size%@AE@%                              %@AB@%Return Convention%@AE@%
  2068. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2069. 1 Byte                            AL Register
  2070.  
  2071. 2 Bytes                           AX Register
  2072.  
  2073. 4 Bytes                           DX, AX Registers (for pointers, the 
  2074.                                   segment is returned in DX, the offset in
  2075.                                   AX; for long integers,
  2076.                                   the most-significant byte is returned in
  2077.                                   DX, leastsignificant byte in AX)
  2078.  
  2079. Note that the protocol for returning values 4 bytes or smaller is the same
  2080. as for functions declared as %@AB@%_cdecl%@AE@%. To return structures and unions larger
  2081. than 4 bytes, the calling program passes a hidden parameter as the last item
  2082. pushed. This parameter is a near pointer, implicitly SS-relative, to a
  2083. buffer in which the value is to be returned. A far pointer to
  2084. SS:%@AI@%hidden-param%@AE@% must be returned in DX:AX. This is the same convention for
  2085. returning structures as %@AB@%_pascal.%@AE@%%@CR:C6A00010054 @%  %@NL@%
  2086. %@NL@%
  2087. %@NL@%
  2088. %@4@%%@AB@%Stack Adjustment Convention%@AE@%%@EH@%%@NL@%
  2089. %@NL@%
  2090. Unlike functions declared as %@AB@%_cdecl%@AE@%, functions declared as %@AB@%_fastcall%@AE@% must
  2091. pop the arguments off the stack. The calling program does not adjust the
  2092. stack after function return.  %@NL@%
  2093. %@NL@%
  2094. %@NL@%
  2095. %@4@%%@AB@%Register Preservation Requirement%@AE@%%@EH@%%@NL@%
  2096. %@NL@%
  2097. All functions must preserve the DS, BP, SI, and DI registers. Your %@AB@%_fastcall%@AE@%
  2098. function can modify the values in AX, BX, CX, DX, and ES.  %@NL@%
  2099. %@NL@%
  2100. %@NL@%
  2101. %@4@%%@AB@%Function-Naming Convention%@AE@%%@EH@%%@NL@%
  2102. %@NL@%
  2103. The public name put into the object file for a function declared as
  2104. %@AB@%_fastcall%@AE@% is the name given by the user with a leading "at sign" (@). No
  2105. case translation is performed on the function name. The function declaration
  2106. %@NL@%
  2107. %@NL@%
  2108. %@AS@%  int _fastcall FCFunc( void );%@AE@%%@NL@%
  2109. %@NL@%
  2110. causes the compiler to place the public symbol %@AS@% @FCFunc %@AE@% in your object file
  2111. at every location %@AS@% FCFunc %@AE@% is referenced in your program.  %@NL@%
  2112. %@NL@%
  2113. If you do not declare the function as %@AB@%_fastcall%@AE@% in your C program, the
  2114. compiler assumes the default calling convention. The default is usually the
  2115. C calling convention but can be changed by the /Gc (Pascal Calling
  2116. Convention), /Gr (Register Calling Convention), or /Gd (C Calling
  2117. Convention) options. If the linker gives you an unresolved external
  2118. reference, you may have failed to declare an external %@AB@%_fastcall%@AE@% function
  2119. properly. For more information about calling conventions, see Chapter 12,
  2120. "Programming with Mixed Languages."%@CR:C6A00010055 @%  %@NL@%
  2121. %@NL@%
  2122. %@NL@%
  2123. %@NL@%
  2124. %@NL@%
  2125. %@NL@%
  2126. %@NL@%
  2127. %@CR:C6A00020001 @%%@1@%%@AB@%Chapter 2  Managing Memory%@AE@%%@EH@%%@NL@%
  2128. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2129. %@NL@%
  2130. When you develop advanced applications in Microsoft C, you must pay
  2131. attention to memory management─that is, how data and code are stored and
  2132. accessed in memory. A well-thought-out memory strategy will make your
  2133. programs run faster and occupy less memory.  %@NL@%
  2134. %@NL@%
  2135. You can follow one or more of these memory management strategies:  %@NL@%
  2136. %@NL@%
  2137. %@NL@%
  2138.   ■   Choose a standard memory model.%@NL@%
  2139. %@NL@%
  2140.   ■   Create a mixed-model program with the %@AB@%_near%@AE@%, %@AB@%_far%@AE@%, %@AB@%_huge%@AE@%, and %@AB@%_based%@AE@%
  2141.       keywords.%@NL@%
  2142. %@NL@%
  2143.   ■   Create your own customized memory model.%@NL@%
  2144. %@NL@%
  2145.   ■   Allocate memory as you need it with the %@AB@%malloc%@AE@% family of functions.%@NL@%
  2146. %@NL@%
  2147. %@NL@%
  2148. This chapter explains pointers, memory models (including the new tiny
  2149. model), variations such as custom memory models and mixed models, and based
  2150. pointers.  %@NL@%
  2151. %@NL@%
  2152. %@NL@%
  2153. %@2@%%@CR:C6A00020002 @%%@AB@%2.1  Pointer Sizes%@AE@%%@EH@%%@NL@%
  2154. %@NL@%
  2155. One of the strengths of the C language is that it allows you to use pointers
  2156. to directly access memory locations.  %@NL@%
  2157. %@NL@%
  2158. Every Microsoft C program has at least two parts: the code (function
  2159. definitions) and the data (variables and constants). As a program runs, it
  2160. refers to elements of the code or the data by their addresses. These
  2161. addresses can be stored in pointer variables.  %@NL@%
  2162. %@NL@%
  2163. Pointer variables can fit into 16 bits or 32 bits, depending on the distance
  2164. of the object to which they refer.  %@NL@%
  2165. %@NL@%
  2166. %@NL@%
  2167. %@3@%%@CR:C6A00020003 @%%@AB@%2.1.1  Pointers and 64K Segments%@AE@%%@EH@%%@NL@%
  2168. %@NL@%
  2169. IBM personal computers and compatibles use the Intel(R) 8086, 80186, 80286,
  2170. or 80386 processors (collectively called the 80%@AI@%x%@AE@%86 family). These processors
  2171. have a "segmented" architecture, which means they all have a mode that
  2172. treats memory as a series of segments, each of which occupies up to 64K of
  2173. memory. An offset from the base of the segment allows you to access
  2174. information within a given segment. Moving to a new segment requires
  2175. additional machine code.  %@NL@%
  2176. %@NL@%
  2177. %@AU@% A 16-bit pointer can address up to 65,536 locations.%@AE@%  %@NL@%
  2178. %@NL@%
  2179. The 64K limit is necessary because the 80%@AI@%x%@AE@%86 registers are 16 bits (2 bytes)
  2180. wide. A single register can address only 65,536 (64K) unique memory
  2181. locations.  %@NL@%
  2182. %@NL@%
  2183. A pointer variable that fully specifies a memory address needs 16 bits for
  2184. the segment location and another 16 bits for the offset within the segment,
  2185. a total of 32 bits. However, if you have several variables in the same
  2186. general area, your program can set the segment register once and treat the
  2187. pointers as smaller 16-bit quantities.  %@NL@%
  2188. %@NL@%
  2189. The 80%@AI@%x%@AE@%86 register CS holds the base for the code segment; the register DS
  2190. holds the base for the data segment. Two other segment registers are
  2191. available: the stack segment register (SS) and the extra segment register
  2192. (ES). (The 80386 has additional segment registers: FS and GS.)  %@NL@%
  2193. %@NL@%
  2194. %@NL@%
  2195. %@3@%%@CR:C6A00020004 @%%@AB@%2.1.2  Near Pointers%@AE@%%@EH@%%@NL@%
  2196. %@NL@%
  2197. If you don't explicitly specify a memory model, Microsoft C defaults to the
  2198. small model, which allots up to 64K for the code and another 64K for the
  2199. data (see Figure 2.1).  %@NL@%
  2200. %@NL@%
  2201. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  2202. %@NL@%
  2203. When a small-model program runs, the CS and DS segment registers never
  2204. change. All code pointers and all data pointers contain 16 bits because they
  2205. remain within the 64K range.  %@NL@%
  2206. %@NL@%
  2207. These 16-bit pointers to objects within a single 64K segment are called
  2208. "near pointers." Accessing a near object is called "near addressing."  %@NL@%
  2209. %@NL@%
  2210. %@NL@%
  2211. %@3@%%@CR:C6A00020005 @%%@AB@%2.1.3  Far Pointers%@AE@%%@EH@%%@NL@%
  2212. %@NL@%
  2213. If your program needs more than 64K for code or data, at least some of the
  2214. pointers must specify the memory segment, which means these pointers occupy
  2215. 32 bits instead of 16 bits.  %@NL@%
  2216. %@NL@%
  2217. These larger 32-bit pointers that can point anywhere in memory are called
  2218. "far pointers." Accessing a far object is called "far addressing."  %@NL@%
  2219. %@NL@%
  2220. %@AU@% Far pointers can address any location, but they are bigger and slower.%@AE@%  %@NL@%
  2221. %@NL@%
  2222. Far addressing has the advantage that your program can address any available
  2223. memory location─up to 640K in DOS or several megabytes in OS/2. The
  2224. disadvantages of the larger far pointers is that they take up more memory
  2225. (four bytes instead of two) and that any use of the pointers (assigning,
  2226. modifying, or otherwise accessing values) takes more time.  %@NL@%
  2227. %@NL@%
  2228. Allowing either code or data to expand beyond 64K makes your programs larger
  2229. and slower.  %@NL@%
  2230. %@NL@%
  2231. %@NL@%
  2232. %@3@%%@CR:C6A00020006 @%%@AB@%2.1.4  Huge Pointers%@AE@%%@EH@%%@NL@%
  2233. %@NL@%
  2234. A third type of pointer in Microsoft C is the "huge" pointer, which applies
  2235. only to data pointers. Code pointers cannot be declared as huge.  %@NL@%
  2236. %@NL@%
  2237. A huge address is similar to a far address in that both contain 32 bits,
  2238. made up of a segment value and an offset value. They differ only in the way
  2239. pointer arithmetic is performed.  %@NL@%
  2240. %@NL@%
  2241. For far pointers, Microsoft C assumes that code and data objects lie
  2242. completely within the segment in which they start, so pointer arithmetic
  2243. operates only on the offset portion of the address. Limiting the size of any
  2244. single item to 64K makes pointer arithmetic faster.  %@NL@%
  2245. %@NL@%
  2246. Huge pointers overcome this size limitation; pointer arithmetic is performed
  2247. on all 32 bits of the data item's address, thus allowing data items
  2248. referenced by huge pointers to span more than one segment. In this code
  2249. fragment,  %@NL@%
  2250. %@NL@%
  2251. %@AS@%  int _huge *hp;
  2252. %@AS@%  int _far *fp;
  2253. %@AS@%  .
  2254. %@AS@%  .
  2255. %@AS@%  .
  2256. %@AS@%  hp++;
  2257. %@AS@%  fp++;%@AE@%%@NL@%
  2258. %@NL@%
  2259. both %@AS@% hp %@AE@% and %@AS@% fp %@AE@% are incremented. The huge pointer is incremented as a
  2260. 32-bit value that represents the combined segment and offset. Only the
  2261. offset part of the far pointer (a 16-bit value) is incremented.  %@NL@%
  2262. %@NL@%
  2263. Extending the size of pointer arithmetic from 16 to 32 bits causes such
  2264. arithmetic to execute more slowly. You gain the use of larger arrays by
  2265. paying a price in execution speed.  %@NL@%
  2266. %@NL@%
  2267. %@NL@%
  2268. %@3@%%@CR:C6A00020007 @%%@AB@%2.1.5  Based Addressing%@AE@%%@EH@%%@NL@%
  2269. %@NL@%
  2270. When you declare near, far, and huge variables, the Microsoft C compiler and
  2271. linker automatically manage details such as allocating memory and keeping
  2272. track of segments.  %@NL@%
  2273. %@NL@%
  2274. A "based pointer" is a fourth kind of pointer that operates as a 16-bit
  2275. offset from a base that you specify. In this respect, based addressing
  2276. differs from near, far, or huge addressing; you're responsible for naming
  2277. the base, instead of letting the compiler decide.  %@NL@%
  2278. %@NL@%
  2279. Based pointers are new to version 6.0 of Microsoft C. They are explained in
  2280. more detail in Section 2.5, "Using Based Variables."  %@NL@%
  2281. %@NL@%
  2282. %@NL@%
  2283. %@2@%%@CR:C6A00020008 @%%@AB@%2.2  Selecting a Standard Memory Model%@AE@%%@EH@%%@NL@%
  2284. %@NL@%
  2285. If you want to choose one size for all pointers, there's no need to declare
  2286. each variable as near or far. Instead, you select a standard memory model
  2287. and your choice applies to all variables in the program.  %@NL@%
  2288. %@NL@%
  2289. One advantage of using standard memory models is simplicity. You specify the
  2290. way the compiler allocates storage for code and data only once.  %@NL@%
  2291. %@NL@%
  2292. %@AU@% A standard memory model assumes all pointers are the same size.%@AE@%  %@NL@%
  2293. %@NL@%
  2294. Another advantage is that the standard memory models do not require the use
  2295. of Microsoft-specific keywords such as %@AB@%_near%@AE@% and %@AB@%_far%@AE@%, so they are best for
  2296. writing code that is portable to other (non-DOS) systems.  %@NL@%
  2297. %@NL@%
  2298. The disadvantage of standard memory models is that, because they make global
  2299. assumptions about the environment, they do not always produce the most
  2300. efficient code.  %@NL@%
  2301. %@NL@%
  2302. %@NL@%
  2303. %@3@%%@CR:C6A00020009 @%%@AB@%2.2.1  The Six Standard Memory Models%@AE@%%@EH@%%@NL@%
  2304. %@NL@%
  2305. The six Microsoft C memory models are shown in Table 2.1.  %@NL@%
  2306. %@NL@%
  2307. %@AB@%Table 2.1  %@AB@%Memory Models %@AE@%%@AE@%
  2308.  
  2309. %@TH:  10   600 03 10 22 11 33 @%          Maximum Total Memory  Model     Code                  Data       Data Arrays%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Tiny      <64K                  <64K       <64KSmall     64K                   64K        64KMedium    No limit              64K        64KCompact   64K                   No limit   64KLarge     No limit              No limit   64KHuge      No limit              No limit   No limit%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  10   600 03 10 22 11 33 @%
  2310.  
  2311. The SETUP program creates the libraries that support the six standard memory
  2312. models.  %@NL@%
  2313. %@NL@%
  2314. When you choose one of the standard memory models, the compiler inserts the
  2315. name of the corresponding C run-time library in the object file so the
  2316. linker chooses it automatically. Each memory model has its own library,
  2317. except for the huge memory model (which uses the large-model library) and
  2318. the tiny model (which uses the small-model library).  %@NL@%
  2319. %@NL@%
  2320. %@NL@%
  2321. %@3@%%@CR:C6A00020010 @%%@AB@%2.2.2  Limitations on Code Size and Data Size%@AE@%%@EH@%%@NL@%
  2322. %@NL@%
  2323. When writing a program in Microsoft C, keep in mind two limitations that
  2324. apply to all six memory models:%@CR:C6A00020011 @%  %@NL@%
  2325. %@NL@%
  2326. %@NL@%
  2327.   ■   No single source module can generate 64K or more of code. You must
  2328.       break large programs into modules and link their individual .OBJ files
  2329.       to create the .EXE file.%@NL@%
  2330. %@NL@%
  2331.   ■   No single data item can exceed 64K unless it appears in a huge-model
  2332.       program or it has been declared with the %@AB@%_huge%@AE@% keyword.%@NL@%
  2333. %@NL@%
  2334. %@NL@%
  2335. %@NL@%
  2336. %@3@%%@CR:C6A00020012 @%%@AB@%2.2.3  The Tiny Memory Model%@AE@%%@EH@%%@NL@%
  2337. %@NL@%
  2338. The tiny memory model is new to Microsoft C. It resembles the small model
  2339. with three exceptions:%@CR:C6A00020013 @%%@CR:C6A00020014 @%  %@NL@%
  2340. %@NL@%
  2341. %@NL@%
  2342.   ■   The tiny model cannot exceed 64K per program (including both code and
  2343.       data). A small-model program, on the other hand, can occupy up to
  2344.       128K: 64K for code and 64K for data.%@NL@%
  2345. %@NL@%
  2346.   ■   The tiny model produces .COM, rather than .EXE, files. To produce .COM
  2347.       files, compile with the /AT option. Then link with the / TINY option
  2348.       and link in CRTCOM.OBJ.%@NL@%
  2349. %@NL@%
  2350.   ■   The tiny model applies to DOS only; it is not available in OS/2.%@NL@%
  2351. %@NL@%
  2352. %@NL@%
  2353. Although the tiny model imposes the most severe limits on code and data
  2354. size, it produces the smallest programs. The tiny memory model only offers a
  2355. load-time speed advantage over the small model; they both produce the
  2356. fastest programs.  %@NL@%
  2357. %@NL@%
  2358. %@NL@%
  2359. %@3@%%@CR:C6A00020015 @%%@AB@%2.2.4  The Huge Memory Model%@AE@%%@EH@%%@NL@%
  2360. %@NL@%
  2361. The huge memory model is nearly identical to the large model. The only
  2362. difference is that the huge model permits individual arrays to exceed 64K in
  2363. size. For example, an %@AB@%int%@AE@% uses two bytes, so an array of 40,000 integers,
  2364. occupying 80,000 bytes of memory, would be permitted in the huge model. All
  2365. other models limit each array, structure, or other data object to no more
  2366. than 64K.  %@NL@%
  2367. %@NL@%
  2368. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2369. NOTE
  2370. %@AI@%Automatic arrays cannot be declared huge. Only static arrays and arrays
  2371. %@AI@%occupying memory allocated by the %@AB@%halloc%@AE@%%@AI@% function can be huge.%@AE@%%@AE@%%@NL@%
  2372. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  2373. %@NL@%
  2374. %@AU@% The huge model lifts  the limits on arrays.%@AE@%  %@NL@%
  2375. %@NL@%
  2376. Although the huge model lifts the limits on arrays, some size restrictions
  2377. do apply. To maintain efficient addressing, no individual array element is
  2378. allowed to cross a segment boundary. This has the following implications:  %@NL@%
  2379. %@NL@%
  2380. %@NL@%
  2381.   ■   No single element of an array can be larger than 64K. An array can be
  2382.       larger than 64K, but its individual elements cannot.%@NL@%
  2383. %@NL@%
  2384.   ■   For any array larger than 128K, all elements must have a size in bytes
  2385.       equal to a power of 2: 2 bytes, 4 bytes, 8 bytes, 16 bytes, and so on.
  2386.       If the array is 128K or smaller, its elements can be any size, up to
  2387.       and including 64K.%@NL@%
  2388. %@NL@%
  2389. %@NL@%
  2390. Pointer arithmetic changes within the huge model, as well. In particular,
  2391. the %@AB@%sizeof%@AE@% operator may return an incorrect value. The ANSI draft standard
  2392. for C defines the value returned by %@AB@%sizeof%@AE@% to be of type %@AB@%size_t%@AE@% (which, in
  2393. Microsoft C, is  %@NL@%
  2394. %@NL@%
  2395. an %@AB@%unsigned int%@AE@%). The size in bytes of a huge array is an %@AB@%unsigned long%@AE@%
  2396. value, however. To find the correct value, you must use a type cast:  %@NL@%
  2397. %@NL@%
  2398. %@AS@%  (unsigned long)sizeof(monster_array)%@AE@%%@NL@%
  2399. %@NL@%
  2400. Similarly, the C language defines the result of subtracting two pointers as
  2401. %@AB@%ptrdiff_t%@AE@% (a %@AB@%signed int%@AE@% in Microsoft C). Subtracting two huge pointers will
  2402. yield a %@AB@%long%@AE@% value. Microsoft C gives the correct result with the following
  2403. type cast:  %@NL@%
  2404. %@NL@%
  2405. %@AS@%  (long)(ptr1_huge - ptr2_huge)%@AE@%%@NL@%
  2406. %@NL@%
  2407. When you select huge model, all %@AB@%extern%@AE@% arrays are treated as %@AB@%_huge%@AE@%.
  2408. Operations on data declared as %@AB@%_huge%@AE@% can be less efficient than the same
  2409. operations on data declared as %@AB@%_far%@AE@%.  %@NL@%
  2410. %@NL@%
  2411. %@NL@%
  2412. %@3@%%@CR:C6A00020016 @%%@AB@%2.2.5  Null Pointers%@AE@%%@EH@%%@NL@%
  2413. %@NL@%
  2414. Within the medium and compact models, code pointers and data pointers differ
  2415. in size: one is 16 bits wide and the other is 32 bits wide. When using these
  2416. memory models, you should be careful in your use of the manifest constant
  2417. %@AB@%NULL%@AE@%.  %@NL@%
  2418. %@NL@%
  2419. %@AB@%%@AE@%NULL represents a null data pointer. The C include files define it as  %@NL@%
  2420. %@NL@%
  2421. %@AS@%  #define NULL ((void *) 0)%@AE@%%@NL@%
  2422. %@NL@%
  2423. %@AU@% There can be problems in models with different sizes of code and data
  2424. %@AU@%pointers.%@AE@%  %@NL@%
  2425. %@NL@%
  2426. In memory models where data pointers have the same size as code pointers,
  2427. the actual size of a null pointer doesn't matter. In memory models where
  2428. code and data pointers are different sizes, problems can occur. Consider
  2429. this example:  %@NL@%
  2430. %@NL@%
  2431. %@AS@%  void main()
  2432. %@AS@%  {
  2433. %@AS@%     func1( NULL );
  2434. %@AS@%     func2( NULL );
  2435. %@AS@%  }
  2436. %@AS@%  
  2437. %@AS@%  func1( char *dp )
  2438. %@AS@%  {
  2439. %@AS@%     .
  2440. %@AS@%     .
  2441. %@AS@%     .
  2442. %@AS@%  }
  2443. %@AS@%  
  2444. %@AS@%  func2( char (*fp)( void ) )
  2445. %@AS@%  {
  2446. %@AS@%     .
  2447. %@AS@%     .
  2448. %@AS@%     .
  2449. %@AS@%  }%@AE@%%@NL@%
  2450. %@NL@%
  2451. In the absence of function prototypes for %@AS@% func1 %@AE@% and %@AS@% func2%@AE@%, the compiler
  2452. always assumes that %@AB@%NULL%@AE@% refers to data and not code.  %@NL@%
  2453. %@NL@%
  2454. The example above works correctly in tiny, small, large, and huge models
  2455. because, in those models, a data pointer is the same size as a code pointer.
  2456. Under medium or compact model, however, %@AS@% main %@AE@% passes %@AB@% NULL%@AE@% to %@AS@% func2 %@AE@% as a
  2457. null data pointer rather than as a null code pointer (a pointer to a
  2458. function), which means the pointer is the wrong size.  %@NL@%
  2459. %@NL@%
  2460. To ensure that your code works properly in all models, declare each function
  2461. with a prototype. For example, before %@AS@% main%@AE@%, include these two lines:  %@NL@%
  2462. %@NL@%
  2463. %@AS@%  int func1( char *dp );
  2464. %@AS@%  int func2( char (*fp)( void ));%@AE@%%@NL@%
  2465. %@NL@%
  2466. If you add these prototypes to the example, the code works properly in all
  2467. memory models. Prototypes force the compiler to coerce code pointers to the
  2468. correct size. Prototypes also enable strong type-checking of parameters.  %@NL@%
  2469. %@NL@%
  2470. %@NL@%
  2471. %@3@%%@CR:C6A00020017 @%%@AB@%2.2.6  Specifying a Memory Model%@AE@%%@EH@%%@NL@%
  2472. %@NL@%
  2473. If you do not specify a memory model, Microsoft C defaults to the small
  2474. model, which is adequate for many small to mid-sized programs.  %@NL@%
  2475. %@NL@%
  2476. You can select a memory model from the Programmer's WorkBench or from the
  2477. command line.  %@NL@%
  2478. %@NL@%
  2479. %@NL@%
  2480. %@4@%%@AB@%Selecting from within PWB%@AE@%%@EH@%%@NL@%
  2481. %@NL@%
  2482. If you're compiling from the Programmer's WorkBench, open the Options menu
  2483. and choose C Global Build Options. The available memory models appear in the
  2484. upper left corner. Choose one of the six standard models or choose
  2485. Customized and type in the options for a customized model.  %@NL@%
  2486. %@NL@%
  2487. %@NL@%
  2488. %@4@%%@AB@%Selecting from the Command Line%@AE@%%@EH@%%@NL@%
  2489. %@NL@%
  2490. You can choose a memory model by including an option on the command line.
  2491. For example, to compile CLICK.C as a compact-model program, type this:  %@NL@%
  2492. %@NL@%
  2493. %@AS@%  CL /AC CLICK.C%@AE@%%@NL@%
  2494. %@NL@%
  2495. The /AC option selects the compact memory model. The six options and four
  2496. libraries are listed below:  %@NL@%
  2497. %@NL@%
  2498. %@AB@%Option%@AE@%                            %@AB@%Memory Model: Library%@AE@%
  2499. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2500. /AT                               Tiny Model: SLIBC%@AI@%xx%@AE@%.LIB (plus CRTCOM.OBJ)
  2501.  
  2502. /AS                               Small Model: SLIBC%@AI@%xx%@AE@%.LIB
  2503.  
  2504. /AM                               Medium Model: MLIBC%@AI@%xx%@AE@%.LIB
  2505.  
  2506. /AC                               Compact Model: CLIBC%@AI@%xx%@AE@%.LIB
  2507.  
  2508. /AL                               Large Model: LLIBC%@AI@%xx%@AE@%.LIB
  2509.  
  2510. /AH                               Huge Model: LLIBC%@AI@%xx%@AE@%.LIB
  2511.  
  2512. %@NL@%
  2513. %@2@%%@CR:C6A00020018 @%%@AB@%2.3  Mixing Memory Models%@AE@%%@EH@%%@NL@%
  2514. %@NL@%
  2515. In standard memory models, explained above, all data pointers are the same
  2516. size and all code pointers are the same size.  %@NL@%
  2517. %@NL@%
  2518. A mixed memory model selectively combines different types of pointers within
  2519. the same program. A mixed model extends the limits of a given memory model
  2520. while retaining its benefits.%@CR:C6A00020019 @%%@CR:C6A00020020 @%%@CR:C6A00020021 @%%@CR:C6A00020022 @%  %@NL@%
  2521. %@NL@%
  2522. %@AU@% A mixed memory model lets you mix near and far pointers.%@AE@%  %@NL@%
  2523. %@NL@%
  2524. For example, imagine a programming situation where you add an array to a
  2525. small-model program, pushing the data segment past the 64K limit.  %@NL@%
  2526. %@NL@%
  2527. You could solve the problem by moving up from the small to the compact
  2528. memory model. Doing so would bump all data pointers from two to four bytes.
  2529. The .EXE file would grow accordingly. Execution time would slow.  %@NL@%
  2530. %@NL@%
  2531. A second and perhaps better solution is to stay within the standard small
  2532. memory model, which uses near pointers, but to declare the new array as far.
  2533. You mix near pointers and far pointers, creating a mixed model.  %@NL@%
  2534. %@NL@%
  2535. Microsoft C lets you override the standard addressing convention for a given
  2536. memory model by specifying that certain items are %@AB@%_near%@AE@%, %@AB@%_far%@AE@%, %@AB@%_huge%@AE@%, or
  2537. %@AB@%_based%@AE@%. These keywords are not a standard part of the C language; they are
  2538. Microsoft extensions, meaningful only on systems that use 80%@AI@%x%@AE@%86
  2539. microprocessors. Using these keywords may affect the portability of your
  2540. code.  %@NL@%
  2541. %@NL@%
  2542. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2543. NOTE
  2544.  
  2545. %@AI@%Previous versions of the Microsoft C Compiler accepted the keywords %@AB@%near%@AE@%%@AI@%,
  2546. %@AI@%%@AE@%%@AI@%%@AB@%far%@AE@%%@AE@%%@AI@%, and %@AE@%%@AI@%%@AB@%huge %@AE@%%@AE@%%@AI@%without an initial underscore. Since the ANSI draft standard
  2547. %@AI@%for C permits compiler implementors to reserve identifiers that begin with
  2548. %@AI@%underscores, an underscore was added to these keywords to mark them as
  2549. %@AI@%Microsoft-specific. To maintain compatibility with existing source code, the
  2550. %@AI@%compiler still recognizes the obsolescent versions of these keywords.%@AE@%%@AE@%%@NL@%
  2551. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  2552. %@NL@%
  2553. You can compile a program in the small model, for example, but declare a
  2554. certain array to be %@AB@%_far%@AE@%. At run time, the address of that array occupies
  2555. four bytes. The program may slow slightly when accessing items in that
  2556. particular far array, but throughout the rest of the program, all addressing
  2557. would be near. Note that all pointers to elements of an array declared as
  2558. %@AB@%_far%@AE@% must also be declared as %@AB@%_far%@AE@%.  %@NL@%
  2559. %@NL@%
  2560. Table 2.2 lists the effects of these keywords on data pointers, code
  2561. pointers, and pointer arithmetic.  %@NL@%
  2562. %@NL@%
  2563. %@AB@%Table 2.2  %@AB@%Addressing Declared with Microsoft Keywords%@AE@%%@AE@%
  2564.  
  2565. %@TH:  35  1876 02 09 22 22 23 @%Keyword  Data                  Code                  Arithmetic%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_near%@AE@%    Data reside in        Functions reside in   16 bits         default data          current code                   segment; 16-bit       segment; 16-bit                addresses             addresses             %@AB@%_far%@AE@%     Data can be anywhere  Functions can be      16 bits         in memory, not        called from anywhere           necessarily in the    in memory; 32-bit              default data          addresses                      segment; 32-bit                                      addresses                                   %@AB@%_huge%@AE@%    Data can be anywhere  Not applicable;       32 bits         in memory, not        code cannot be         (data only)         necessarily in the    declared %@AB@%_huge%@AE@%                 default data segment.                                 Individual data                                      items (arrays) can                                   exceed 64K in size;                                  32-bit addresses                            %@AB@%_based%@AE@%   Data can be anywhere  Not applicable;       16 bits         in memory, not        code cannot be         (data only)         necessarily in the    declared %@AB@%_based%@AE@%                default data                                         segment; 16-bit                                      addresses plus a                                     known base provide                                   the range of 32-bit                                  addresses                                   %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  35  1876 02 09 22 22 23 @%
  2566.  
  2567. %@NL@%
  2568. %@3@%%@CR:C6A00020023 @%%@AB@%2.3.1  Pointer Problems%@AE@%%@EH@%%@NL@%
  2569. %@NL@%
  2570. When you declare items to be %@AB@%_near%@AE@%, %@AB@%_far%@AE@%, %@AB@%_huge%@AE@%, or %@AB@%_based%@AE@%, you can link
  2571. with a standard run-time library. Be aware, however, that in some cases, the
  2572. modified pointers will be incompatible with standard library functions.
  2573. Watch for these problems that affect pointers:%@CR:C6A00020024 @%%@CR:C6A00020025 @%%@CR:C6A00020026 @%%@CR:C6A00020027 @%  %@NL@%
  2574. %@NL@%
  2575. %@NL@%
  2576.   ■   A library function that expects a 16-bit pointer as an argument will
  2577.       not function properly with modified variables that occupy 32 bits. In
  2578.       other words, you can cast a near pointer to a far pointer, because it
  2579.       adds the segment value and maintains the integrity of the address. If
  2580.       you cast a far pointer to near, however, the compiler generates a
  2581.       warning message because the offset may not lie within the default data
  2582.       segment, in which case the original far address is  irretrievably
  2583.       lost.%@NL@%
  2584. %@NL@%
  2585.   ■   A library function that returns a pointer will return a pointer of the
  2586.       default size for the memory model. This is only a problem if you are
  2587.       assigning the return value to a pointer of a smaller size. For
  2588.       example, there may be difficulties if you compile with a model that
  2589.       selects far data pointers, but you have explicitly declared the
  2590.       variable to receive the return value %@AB@%_near%@AE@%.%@NL@%
  2591. %@NL@%
  2592. %@STUB@%      This warning does not apply to all functions. See Section B.2.8 in
  2593.       Appendix B for a list of model-independent string and memory functions
  2594.       such as %@AB@%_fstrcat%@AE@%, the far version of %@AB@%strcat%@AE@%.%@NL@%
  2595. %@NL@%
  2596.   ■   Based pointers pose a special problem. Based pointers are passed to
  2597.       other functions as is (without normalization). Certain functions
  2598.       expect to receive based pointers, but most do not. Therefore, in most
  2599.       cases, you must either explicitly cast a based pointer to a far
  2600.       pointer or make sure that all functions that receive based pointers
  2601.       are prototyped.%@NL@%
  2602. %@NL@%
  2603. %@NL@%
  2604. Some run-time library functions support near, far, huge, and based
  2605. variables. For example, %@AB@%halloc%@AE@% allocates memory for a huge data array.  %@NL@%
  2606. %@NL@%
  2607. You can always pass the value (but not the address) of a far item to a
  2608. small-model library routine. For example,  %@NL@%
  2609. %@NL@%
  2610. %@AS@%  /* Compile in small model */
  2611. %@AS@%  #include <stdio.h>
  2612. %@AS@%  long _far time_val;
  2613. %@AS@%  
  2614. %@AS@%  void main()
  2615. %@AS@%  {
  2616. %@AS@%     time( &time_val );             /* Illegal far address */
  2617. %@AS@%     printf( "%ld\n", time_val );   /* Legal value */
  2618. %@AS@%  }%@AE@%%@NL@%
  2619. %@NL@%
  2620. When you use a mixed memory model, you should include function prototypes
  2621. with argument-type lists to ensure that all pointer arguments are passed to
  2622. functions correctly.  %@NL@%
  2623. %@NL@%
  2624. %@NL@%
  2625. %@3@%%@CR:C6A00020028 @%%@AB@%2.3.2  Declaring Near, Far, Huge, and Based Variables%@AE@%%@EH@%%@NL@%
  2626. %@NL@%
  2627. The %@AB@%_near%@AE@%, %@AB@%_far%@AE@%, %@AB@%_huge%@AE@%, and %@AB@%_based%@AE@% keywords modify either objects or
  2628. pointers to objects. When using them to declare variables, keep these rules
  2629. in mind:%@CR:C6A00020029 @%%@CR:C6A00020030 @%%@CR:C6A00020031 @%%@CR:C6A00020032 @%  %@NL@%
  2630. %@NL@%
  2631. %@NL@%
  2632.   ■   The keyword always modifies the object or pointer immediately to its
  2633.       right. In complex declarations, think of the %@AB@%_far%@AE@% keyword and the item
  2634.       to its right as being a single unit. For example, in the case of the
  2635.       declaration%@NL@%
  2636. %@NL@%
  2637. %@STUB@%      %@AS@%char _far * _near *p;%@AE@%%@NL@%
  2638. %@NL@%
  2639. %@STUB@%      %@AS@%p %@AE@% is a near pointer to a far pointer to %@AB@%char%@AE@%, which resides in the
  2640.       default data segment for the memory model being used.%@NL@%
  2641. %@NL@%
  2642. %@STUB@%      By contrast, the declaration%@NL@%
  2643. %@NL@%
  2644. %@STUB@%      %@AS@%char _far * _near p;%@AE@%%@NL@%
  2645. %@NL@%
  2646. %@STUB@%      is a far pointer to %@AB@%char%@AE@% that will always be stored in DGROUP,
  2647.       regardless of the memory model being used.%@NL@%
  2648. %@NL@%
  2649.   ■   If the item immediately to the right of the keyword is an identifier,
  2650.       the keyword determines whether the item will be allocated in the
  2651.       default data segment (%@AB@% _near%@AE@%) or a separate data segment (%@AB@% _far%@AE@%,
  2652.       %@AB@%_huge%@AE@%, or %@AB@%_based%@AE@%). For example,%@NL@%
  2653. %@NL@%
  2654. %@STUB@%      %@AS@%char _far a;%@AE@%%@NL@%
  2655. %@NL@%
  2656. %@STUB@%      allocates %@AS@% a %@AE@% as an item of type %@AB@%char%@AE@% with a %@AB@%_far%@AE@% address.%@NL@%
  2657. %@NL@%
  2658.   ■   If the item immediately to the right of the keyword is a pointer, the
  2659.       keyword determines whether the pointer will hold a near address (16
  2660.       bits), a based address (16 bits), a far address (32 bits), or a huge
  2661.       address (also 32 bits). For example,%@NL@%
  2662. %@NL@%
  2663. %@STUB@%      %@AS@%char _huge *p;%@AE@%%@NL@%
  2664. %@NL@%
  2665. %@STUB@%      allocates %@AS@% p %@AE@% as a huge pointer (32 bits) to an item of type %@AB@%char%@AE@%. Any
  2666.       arithmetic performed on the huge pointer %@AS@% p %@AE@% will affect all 32 bits.
  2667.       That is, the instruction %@AS@% p++ %@AE@% increments the pointer as a 32-bit
  2668.       entity.%@NL@%
  2669. %@NL@%
  2670. %@NL@%
  2671. %@NL@%
  2672. %@3@%%@CR:C6A00020033 @%%@AB@%2.3.3  Declaring Near and Far Functions%@AE@%%@EH@%%@NL@%
  2673. %@NL@%
  2674. You cannot declare functions as %@AB@%_huge%@AE@% or %@AB@%_based%@AE@%. The rules for using the
  2675. %@AB@%_near%@AE@% and %@AB@%_far%@AE@% keywords for functions are similar to those for using them
  2676. with data:  %@NL@%
  2677. %@NL@%
  2678. %@NL@%
  2679.   ■   The keyword always modifies the function or pointer immediately to its
  2680.       right.%@NL@%
  2681. %@NL@%
  2682.   ■   If the item immediately to the right of the keyword is a function, the
  2683.       keyword determines whether the function will be allocated as near or
  2684.       far. For example,%@NL@%
  2685. %@NL@%
  2686. %@STUB@%      %@AS@%char _far fun();%@AE@%%@NL@%
  2687. %@NL@%
  2688. %@STUB@%      defines %@AS@% fun %@AE@% as a function with a 32-bit address that returns a %@AB@%char%@AE@%.
  2689.       The function may be located in near memory or far memory, but it is
  2690.       called with the full 32-bit address. The %@AB@%_far%@AE@% keyword applies to the
  2691.       function, not to the return type.%@NL@%
  2692. %@NL@%
  2693.   ■   If the item immediately to the right of the keyword is a pointer to a
  2694.       function, the keyword determines whether the function will be called
  2695.       using a near (16-bit) or far (32-bit) address. For example,%@NL@%
  2696. %@NL@%
  2697. %@STUB@%      %@AS@%char (_far *pfun)( );%@AE@%%@NL@%
  2698. %@NL@%
  2699. %@STUB@%      defines %@AS@% pfun %@AE@% as a far pointer (32 bits) to a function returning type
  2700.       %@AB@%char%@AE@%.%@NL@%
  2701. %@NL@%
  2702.   ■   Function declarations must match function definitions.%@NL@%
  2703. %@NL@%
  2704.   ■   The %@AB@%_huge%@AE@% and %@AB@%_based%@AE@% keywords do not apply to functions. That is, a
  2705.       function cannot be huge (larger than 64K) or based. A function can
  2706.       return a huge data pointer to the calling function. A function can
  2707.       return a based pointer unless it is a pointer based on %@AB@%_self%@AE@% (see
  2708.       Section 2.5.2, "Declaring Based Variables").%@NL@%
  2709. %@NL@%
  2710. %@NL@%
  2711. The example below declares %@AS@% fun1 %@AE@% as a far function returning type %@AB@%char%@AE@%:  %@NL@%
  2712. %@NL@%
  2713. %@AS@%  char _far fun1(void);              /* small model */
  2714. %@AS@%  char _far fun(void)
  2715. %@AS@%  {
  2716. %@AS@%      .
  2717. %@AS@%      .
  2718. %@AS@%      .
  2719. %@AS@%  }%@AE@%%@NL@%
  2720. %@NL@%
  2721. Here, the %@AS@% fun2 %@AE@% function is a near function that returns a far pointer to
  2722. type %@AB@%char%@AE@%:  %@NL@%
  2723. %@NL@%
  2724. %@AS@%  char _far * _near fun2( );        /* large model */
  2725. %@AS@%  char _far * _near fun( )
  2726. %@AS@%  {
  2727. %@AS@%      .
  2728. %@AS@%      .
  2729. %@AS@%      .
  2730. %@AS@%  }%@AE@%%@NL@%
  2731. %@NL@%
  2732. The example below declares %@AS@% pfun %@AE@% as a far pointer to a function that has an
  2733. %@AB@%int%@AE@% return type, assigns the address of %@AB@%printf%@AE@% to %@AS@% pfun%@AE@%, and prints "Hello
  2734. world." twice.  %@NL@%
  2735. %@NL@%
  2736. %@AS@%  /* Compile in medium, large, or huge model */
  2737. %@AS@%  
  2738. %@AS@%  #include <stdio.h>
  2739. %@AS@%  int (_far *pfun)( char *, ... );
  2740. %@AS@%  
  2741. %@AS@%  void main()
  2742. %@AS@%  {
  2743. %@AS@%       pfun = printf;
  2744. %@AS@%       pfun( "Hello world.\n" );
  2745. %@AS@%       (*pfun)( "Hello world.\n" );
  2746. %@AS@%  }%@AE@%%@NL@%
  2747. %@NL@%
  2748. %@NL@%
  2749. %@3@%%@CR:C6A00020034 @%%@AB@%2.3.4  Pointer Conversions%@AE@%%@EH@%%@NL@%
  2750. %@NL@%
  2751. Passing near or far pointers as arguments to functions can cause automatic
  2752. conversions in the size of the pointer argument. Passing a pointer to an
  2753. unprototyped function forces the pointer size to the larger of the following
  2754. two sizes:  %@NL@%
  2755. %@NL@%
  2756. %@NL@%
  2757.   ■   The default pointer size for that type, as defined by the memory model
  2758.       selected during compilation.%@NL@%
  2759. %@NL@%
  2760. %@STUB@%      For example, in medium-model programs, data pointer arguments are near
  2761.       by default, and code pointer arguments are far by default.%@NL@%
  2762. %@NL@%
  2763.   ■   The size of the type of the argument.%@NL@%
  2764. %@NL@%
  2765. %@NL@%
  2766. Note that if you supply a based pointer as an argument to a function and do
  2767. not specifically cast it to a far pointer type, a 16-bit offset from the
  2768. base segment is passed.  %@NL@%
  2769. %@NL@%
  2770. %@AU@% Function prototypes prevent problems that may occur in mixed memory models.%@AE@%
  2771. %@NL@%
  2772. %@NL@%
  2773. If you provide a function prototype with complete argument types, the
  2774. compiler performs type-checking and enforces the conversion of actual
  2775. arguments to the declared type of the corresponding formal argument.
  2776. However, if no declaration is present or the argument-type list is empty,
  2777. the compiler will convert nonbased pointer arguments automatically to the
  2778. default type or the type of the argument, whichever is larger. To avoid
  2779. mismatched arguments, always use a prototype with the argument types.  %@NL@%
  2780. %@NL@%
  2781. For example, the following program produces unexpected results in
  2782. compact-model, large-model, or huge-model programs.  %@NL@%
  2783. %@NL@%
  2784. %@AS@%  void main( )
  2785. %@AS@%  {
  2786. %@AS@%      int _near *x;
  2787. %@AS@%     char _far *y;
  2788. %@AS@%     int z = 1;
  2789. %@AS@%  
  2790. %@AS@%     test_fun( x, y, z );   /* x is coerced to far
  2791. %@AS@%                                   pointer in compact,
  2792. %@AS@%                                   large, or huge model */
  2793. %@AS@%  }
  2794. %@AS@%  
  2795. %@AS@%  int test_fun( int _near *ptr1, char _far *ptr2, int a)
  2796. %@AS@%  {
  2797. %@AS@%      printf("Value of a = %d\n", a);
  2798. %@AS@%  }%@AE@%%@NL@%
  2799. %@NL@%
  2800. If the preceding example is compiled as a tiny, small, or medium program,
  2801. the size of %@AS@% x %@AE@% is 16 bits, the size of %@AS@% y %@AE@% is 32 bits, and the value
  2802. printed for %@AS@% a %@AE@% is 1.  %@NL@%
  2803. %@NL@%
  2804. However, if the example is compiled in compact, large, or huge model, both %@AS@%
  2805. %@AS@%x %@AE@% and %@AS@% y %@AE@% are automatically converted to far pointers when they are passed
  2806. to %@AS@% test_fun%@AE@%. Since %@AS@% ptr1%@AE@%, the first parameter of %@AS@% test_fun%@AE@%, is defined as a
  2807. near pointer argument, it takes only 16 bits of the 32 bits passed to it.
  2808. The next parameter, %@AS@% ptr2%@AE@%, takes the remaining 16 bits passed to %@AS@% ptr1%@AE@%, plus
  2809. 16 bits of the 32 bits passed to it. Finally, the third parameter, %@AS@% a%@AE@%, takes
  2810. the leftover 16 bits from %@AS@% ptr2%@AE@%, instead of the value of %@AS@% z %@AE@% in the %@AB@%main%@AE@%
  2811. function.  %@NL@%
  2812. %@NL@%
  2813. This shifting process does not generate an error message, because both the
  2814. function call and the function definition are legal. In this case the
  2815. program does not work as intended, however, since the value assigned to %@AS@% a %@AE@%
  2816. is not the value intended.  %@NL@%
  2817. %@NL@%
  2818. To pass %@AS@% ptr1 %@AE@% as a near pointer, you should include a function prototype
  2819. that specifically declares this argument for %@AS@% test_fun %@AE@% as a near pointer,
  2820. as shown below:  %@NL@%
  2821. %@NL@%
  2822. %@AS@%  /* First, prototype test_fun so the compiler
  2823. %@AS@%  * knows in advance about the near pointer argument:
  2824. %@AS@%  */
  2825. %@AS@%  int test_fun (int _near*, char _far *, int);
  2826. %@AS@%  
  2827. %@AS@%  main ( )
  2828. %@AS@%  {
  2829. %@AS@%     int _near *x;
  2830. %@AS@%     char _far *y;
  2831. %@AS@%     int z = 1;
  2832. %@AS@%  
  2833. %@AS@%     test_fun ( x, y, z );    /* now, x is not coerced
  2834. %@AS@%                              * to a far pointer; it is
  2835. %@AS@%                              * passed as a near pointer,
  2836. %@AS@%                              * no matter which memory
  2837. %@AS@%                              * model is used
  2838. %@AS@%                              */
  2839. %@AS@%  }
  2840. %@AS@%  
  2841. %@AS@%  int test_fun ( int _near *ptr1, char _far *ptr2, int a)
  2842. %@AS@%  {
  2843. %@AS@%     printf ( "Value of a = %d\n", a );
  2844. %@AS@%  }%@AE@%%@NL@%
  2845. %@NL@%
  2846. %@NL@%
  2847. %@2@%%@CR:C6A00020035 @%%@AB@%2.4  Customizing Memory Models%@AE@%%@EH@%%@NL@%
  2848. %@NL@%
  2849. A third way to manage memory is to combine different features from standard
  2850. memory models to create your own customized memory model. You should have a
  2851. thorough understanding of C memory models and the architecture of 80%@AI@%x%@AE@%86
  2852. processors before creating your own nonstandard memory models.  %@NL@%
  2853. %@NL@%
  2854. %@AU@% In a customized model, you select the size of code pointers and data
  2855. %@AU@%pointers.%@AE@%  %@NL@%
  2856. %@NL@%
  2857. The /A%@AI@%string%@AE@% option lets you change the attributes of the standard memory
  2858. models to create your own memory models. The three letters in %@AI@%string%@AE@%
  2859. correspond to the code pointer size, the data pointer size, and the stack
  2860. and data segment setup, respectively. Because the letter allowed in each
  2861. field is unique to that field, you can give the letters in any order after
  2862. /A. All three letters must be present.  %@NL@%
  2863. %@NL@%
  2864. The standard memory-model options (/AT, /AS, /AM, /AC, /AL, and /AH) can be
  2865. specified in the /A%@AI@%string%@AE@% form. As an example of how to construct memory
  2866. models, the standard memory-model options are listed below with their
  2867. /A%@AI@%string%@AE@% equivalents:  %@NL@%
  2868. %@NL@%
  2869. %@AB@%Standard%@AE@%                          %@AB@%Custom Equivalent%@AE@%
  2870. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2871. /AT                               /Asnd
  2872.  
  2873. /AS                               /Asnd
  2874.  
  2875. /AM                               /Alnd
  2876.  
  2877. /AC                               /Asfd
  2878.  
  2879. /AL                               /Alfd
  2880.  
  2881. /AH                               /Alhd
  2882.  
  2883. For example, you might want to create a huge-compact model. This model would
  2884. allow huge data items but only one code segment. The option for specifying
  2885. this model would be /Ashd.  %@NL@%
  2886. %@NL@%
  2887. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2888. NOTE
  2889.  
  2890. %@AI@%Tiny model is identical to small model except that it causes the linker to
  2891. %@AI@%search for CRTCOM.LIB. The executable file generated when you specify tiny
  2892. %@AI@%model is a .COM file rather than a .EXE.%@AE@%%@NL@%
  2893. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  2894. %@NL@%
  2895. %@NL@%
  2896. %@3@%%@CR:C6A00020036 @%%@AB@%2.4.1  Setting a Size for Code Pointers%@AE@%%@EH@%%@NL@%
  2897. %@NL@%
  2898. Within a custom memory model, you choose whether code pointers are short or
  2899. long:  %@NL@%
  2900. %@NL@%
  2901. %@AB@%Option%@AE@%                            %@AB@%Size%@AE@%
  2902. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2903. /As%@AI@%xx%@AE@%                             Short (near) code pointers
  2904.  
  2905. /Al%@AI@%xx%@AE@%                             Long (far) code pointers
  2906.  
  2907. The /As (short) option tells the compiler to generate near 16-bit pointers
  2908. and addresses for all functions. This is the default for tiny-, small-, and
  2909. compact-model programs.  %@NL@%
  2910. %@NL@%
  2911. The /Al (long) option means that far 32-bit pointers and addresses are used
  2912. to address all functions. Far pointers are the default for medium-, large-,
  2913. and huge-model programs.  %@NL@%
  2914. %@NL@%
  2915. %@NL@%
  2916. %@3@%%@CR:C6A00020037 @%%@AB@%2.4.2  Setting a Size for Data Pointers%@AE@%%@EH@%%@NL@%
  2917. %@NL@%
  2918. Data pointers can be near, far, or huge:  %@NL@%
  2919. %@NL@%
  2920. %@AB@%Option%@AE@%                            %@AB@%Size%@AE@%
  2921. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2922. /A%@AI@%x%@AE@%n%@AI@%x%@AE@%                             Near data pointers
  2923.  
  2924. /A%@AI@%x%@AE@%f%@AI@%x%@AE@%                             Far data pointers
  2925.  
  2926. /A%@AI@%x%@AE@%h%@AI@%x%@AE@%                             Huge data pointers
  2927.  
  2928. The /An (near) option tells the compiler to use 16-bit pointers and
  2929. addresses for all data. This is the default for tiny-, small-, and
  2930. medium-model programs.  %@NL@%
  2931. %@NL@%
  2932. The /Af (far) option specifies that all data pointers and addresses are 32
  2933. bits. This is the default for compact- and large-model programs.  %@NL@%
  2934. %@NL@%
  2935. The /Ah (huge) option specifies that all data pointers and addresses are far
  2936. (32-bit) and that arrays are permitted to extend beyond a 64K segment. This
  2937. is the default for huge-model programs.  %@NL@%
  2938. %@NL@%
  2939. With far data pointers, no single data item can be larger than a segment
  2940. (64K) because address arithmetic is performed only on 16 bits (the offset
  2941. portion) of the address. When huge data pointers are used, individual data
  2942. items can be larger than a segment (64K) because address arithmetic is
  2943. performed on both the segment and the offset.  %@NL@%
  2944. %@NL@%
  2945. %@NL@%
  2946. %@3@%%@CR:C6A00020038 @%%@AB@%2.4.3  Setting Up Segments%@AE@%%@EH@%%@NL@%
  2947. %@NL@%
  2948. Within a customized model, you can choose to make the stack segment (SS)
  2949. equal the data segment (DS), in which case they overlap:%@CR:C6A00020039 @%  %@NL@%
  2950. %@NL@%
  2951. %@AB@%Option%@AE@%                            %@AB@%Effect%@AE@%
  2952. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2953. /A%@AI@%xx%@AE@%d                             SS == DS
  2954.  
  2955. /A«%@AI@%xx%@AE@%»u                           SS != DS; DS reloaded on function entry
  2956.  
  2957. /A«%@AI@%xx%@AE@%»w                           SS != DS; DS not reloaded on function 
  2958.                                   entry
  2959.  
  2960. %@NL@%
  2961. %@4@%%@AB@%Segment Setup Option /Ad%@AE@%%@EH@%%@NL@%
  2962. %@NL@%
  2963. The option /Ad tells the compiler that the segment addresses stored in the
  2964. SS and DS registers are equal. The stack segment and the default data
  2965. segment are combined into a single segment. This is the default for all
  2966. standard-model programs. In small- and medium-model programs, the stack plus
  2967. all data must occupy less than 64K; thus, any data item is accessed with
  2968. only a 16-bit offset from the segment address in the SS and DS registers.  %@NL@%
  2969. %@NL@%
  2970. In compact-, large-, and huge-model programs, initialized global and static
  2971. data are placed in the default data segment up to a certain threshold. The
  2972. address of this segment is stored in the DS and SS registers. All pointers
  2973. to data, including pointers to local data (the stack), are full 32-bit
  2974. addresses. This is important to remember when passing pointers as arguments
  2975. in multiple-segment programs. Although you may have more than 64K of total
  2976. data in these models, no more than 64K of data can occupy the default
  2977. segment. The /Gt and /ND options control allocation of items in the default
  2978. data segment if a program exceeds this limit.  %@NL@%
  2979. %@NL@%
  2980. %@NL@%
  2981. %@4@%%@AB@%Segment Setup Option /Au%@AE@%%@EH@%%@NL@%
  2982. %@NL@%
  2983. The option /Au tells the compiler that the stack segment does not
  2984. necessarily coincide with the data segment. In addition, it adds the %@AB@%_loadds%@AE@%
  2985. attribute to all functions within a module, forcing the compiler to generate
  2986. code to load the DS register with the correct value prior to entering the
  2987. function body. Combine the /ND option with /Au to name data segments other
  2988. than the default. When /Au is combined with /ND, the address in the DS
  2989. register is saved upon entry to each function, and the new DS value for the
  2990. module in which the function was defined is loaded into the register. The
  2991. previous DS value is restored on exit from the function. Therefore, only one
  2992. data segment is accessible at any given time. The /ND option lets you
  2993. combine these segments into a single segment.  %@NL@%
  2994. %@NL@%
  2995. If a standard memory-model option precedes it on the command line, the /Au
  2996. option can be specified without any letters indicating data pointer or code
  2997. pointer sizes. The program uses a standard memory model, but different
  2998. segments are set up for the stack and data segments.  %@NL@%
  2999. %@NL@%
  3000. The /Au option is useful for OS/2 or Microsoft Windows dynamic-link
  3001. libraries (DLLs), since it forces DS to be loaded on entry to each function.
  3002. It is also useful for writing extensions to the Programmer's WorkBench. This
  3003. is a costly operation, however, so consider using the /Aw option.  %@NL@%
  3004. %@NL@%
  3005. %@NL@%
  3006. %@4@%%@AB@%Segment Setup Option /Aw%@AE@%%@EH@%%@NL@%
  3007. %@NL@%
  3008. The option /Aw, like /Au, causes the compiler to assume that the stack
  3009. segment is separate from the data segment. The compiler does not
  3010. automatically load the DS register at each function entry point. The /Aw
  3011. option is useful in creating applications that interface with an operating
  3012. system or with a program running at the operating-system level. The
  3013. operating system or the program running under the operating system actually
  3014. receives the data intended for the application program and places that data
  3015. in a segment; then the operating system or program must load the DS register
  3016. with the segment address for the application program.  %@NL@%
  3017. %@NL@%
  3018. As with the /Au option, the /Aw option can be specified without data pointer
  3019. and code pointer letters if a standard memory-model option precedes it on
  3020. the command line. In such a case, the program uses the specified memory
  3021. model just as with /Au, but the DS register is not reloaded at each function
  3022. entry point.  %@NL@%
  3023. %@NL@%
  3024. Even though /Au and /Aw indicate that the stack may be in a separate
  3025. segment, the stack's size is still fixed at the default size unless this is
  3026. overridden with the /F compiler option or the /STACK linker option.  %@NL@%
  3027. %@NL@%
  3028. The /Aw option is useful for writing OS/2 and Microsoft Windows dynamic-link
  3029. libraries (DLLs), but care must be taken when it is used. Declare all entry
  3030. points to the dynamic-link library as %@AB@%_loadds%@AE@% to force DS to be loaded on
  3031. entry to the function (exactly like the /Au option). The other functions
  3032. will then be more efficient, though, because they will not have to perform
  3033. redundant loads of the DS register. For example,  %@NL@%
  3034. %@NL@%
  3035. %@AS@%  _export _loadds _far pascal LibFunc( void )
  3036. %@AS@%  {
  3037. %@AS@%      .
  3038. %@AS@%      .
  3039. %@AS@%      .
  3040. %@AS@%      HelperFunc(); }
  3041. %@AS@%  
  3042. %@AS@%  HelperFunc( void )
  3043. %@AS@%  {
  3044. %@AS@%      .
  3045. %@AS@%      .
  3046. %@AS@%      .
  3047. %@AS@%  }%@AE@%%@NL@%
  3048. %@NL@%
  3049. The library entry point, %@AS@% LibFunc%@AE@%, is declared as %@AB@%_loadds%@AE@% to force the DS
  3050. register to be loaded on entry. The function %@AS@% HelperFunc%@AE@%, which is private
  3051. to the dynamic-link library, is declared as a normal C function. Since it
  3052. cannot be called from outside of the module, %@AS@% HelperFunc %@AE@% does not need to
  3053. reload DS.  %@NL@%
  3054. %@NL@%
  3055. If you choose one of the options that specifies that the stack segment is
  3056. not equal to the data segment (SS != DS), you cannot pass the address of
  3057. frame variables as arguments to functions that take near pointers. That is,
  3058. in tiny, small, and medium models, you cannot pass the address of a local
  3059. variable (which is allocated on the stack) as an argument, because the
  3060. receiving function will assume the pointer is relative to the data segment.
  3061. However, the receiving function could solve this problem by declaring the
  3062. pointer to be the following:  %@NL@%
  3063. %@NL@%
  3064. %@AS@%  based(_segname("_STACK"))%@AE@%%@NL@%
  3065. %@NL@%
  3066. Another solution would be to cast the pointer to a far pointer in both
  3067. locations as follows:  %@NL@%
  3068. %@NL@%
  3069. %@AS@%  /* Call func with an explicit cast to far */
  3070. %@AS@%  func( (char far *)frame_var );
  3071. %@AS@%  .
  3072. %@AS@%  .
  3073. %@AS@%  .
  3074. %@AS@%  void func( char far *formal_var )%@AE@%%@NL@%
  3075. %@NL@%
  3076. %@NL@%
  3077. %@3@%%@CR:C6A00020040 @%%@AB@%2.4.4  Library Support for Customized Memory Models%@AE@%%@EH@%%@NL@%
  3078. %@NL@%
  3079. Most C programs make function calls to the routines in the C run-time
  3080. library. When you write mixed-model programs, you are responsible for
  3081. determining which library (if any) is suitable for your program and for
  3082. ensuring that the appropriate library is linked. Table 2.3 shows the
  3083. libraries from which to extract the start-up routine for each customized
  3084. memory model.  %@NL@%
  3085. %@NL@%
  3086. %@AB@%Table 2.3  %@AB@%Start-Up Routines for Customized Memory Models%@AE@%%@AE@%
  3087.  
  3088. %@TH:   7   736 02 49 27 @%%@AB@%Memory-Model%@AE@% %@AB@%Option%@AE@%                              %@AB@%From Library%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%/Asn%@AI@%x%@AE@%; /AS plus /A%@AI@%x %@AE@%                             SLIBC%@AI@%f%@AE@%.LIB/Asf%@AI@%x%@AE@%; /Ash%@AI@%x%@AE@%; /AC plus /A%@AI@%x%@AE@%                       CLIBC%@AI@%f%@AE@%.LIB/Aln%@AI@%x%@AE@%; /AM plus /A%@AI@%x%@AE@%                              MLIBC%@AI@%f%@AE@%.LIB/Alf%@AI@%x%@AE@%; /Alh%@AI@%x%@AE@%; /AL plus /A%@AI@%x%@AE@%; /AH plus /A%@AI@%x %@AE@%        LLIBC%@AI@%f%@AE@%.LIB%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   7   736 02 49 27 @%
  3089.  
  3090. The /A%@AI@%x%@AE@% option represents either /Au or /Aw. In the library names, %@AI@% f%@AE@% is
  3091. either E (emulator library), 7 (8087/80287 library), or A (alternate math
  3092. library).  %@NL@%
  3093. %@NL@%
  3094. %@NL@%
  3095. %@3@%%@CR:C6A00020041 @%%@AB@%2.4.5  Setting the Data Threshold%@AE@%%@EH@%%@NL@%
  3096. %@NL@%
  3097. %@AB@%Option%@AE@%                            %@AB@%Effect%@AE@%
  3098. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3099. /Gt«%@AI@%number%@AE@%»                       Sets the threshold
  3100.  
  3101. The /Gt option causes all data items whose size is greater than to %@AI@%number%@AE@%
  3102. bytes to be allocated to a new data segment. When %@AI@%number%@AE@% is specified, it
  3103. must follow the /Gt option immediately, with no intervening spaces. When
  3104. %@AI@%number%@AE@% is omitted, the default threshold value is 256. When the /Gt option
  3105. is omitted, the default threshold value is 32,767.  %@NL@%
  3106. %@NL@%
  3107. The /Gt option applies only to compact-, large-, and huge-model programs,
  3108. since small- and medium-model programs have only one data segment. The
  3109. option is particularly useful with programs that have more than 64K of
  3110. initialized static and global data in small data items, because otherwise
  3111. you run out of memory in the default data segment and can't link the
  3112. program. The /Gt option has no effect on uninitialized global data.  %@NL@%
  3113. %@NL@%
  3114. %@NL@%
  3115. %@3@%%@CR:C6A00020042 @%%@AB@%2.4.6  Naming Modules and Segments%@AE@%%@EH@%%@NL@%
  3116. %@NL@%
  3117. %@AB@%Option%@AE@%                            %@AB@%Effect%@AE@%
  3118. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3119. /NM %@AI@%modulename%@AE@%                    Names the module
  3120.  
  3121. /NT %@AI@%textsegment%@AE@%                   Names the code segment
  3122.  
  3123. /ND %@AI@%datasegment%@AE@%                   Names the data segment
  3124.  
  3125. "Module" is another name for an object file created by the C compiler from a
  3126. single source file. Every module has a name. The compiler uses this name in
  3127. error messages if problems are encountered during processing. The module
  3128. name is usually the same as the source-file name. You can change this name
  3129. using the /NM (name module) option. The new %@AI@%modulename%@AE@% can include any
  3130. combination of letters and digits. The space between /NM and %@AI@%modulename%@AE@% is
  3131. optional.  %@NL@%
  3132. %@NL@%
  3133. Every module has at least two segments: a code segment (sometimes called the
  3134. text segment) containing the program instructions, and a data segment
  3135. containing the program data.  %@NL@%
  3136. %@NL@%
  3137. The compiler normally creates the code and data segment names. The default
  3138. names depend on the memory model chosen for the program. For example, in
  3139. small-model programs the code segment is named %@AB@%_TEXT%@AE@% and the data segment is
  3140. named %@AB@%_DATA%@AE@%.  %@NL@%
  3141. %@NL@%
  3142. Table 2.4 summarizes the naming conventions for code and data segments.  %@NL@%
  3143. %@NL@%
  3144. %@AB@%Table 2.4  %@AB@%Segment-Naming Conventions%@AE@%%@AE@%
  3145.  
  3146. %@TH:   9   727 02 10 14 08 44 @%Model     Code          Data    Module%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Tiny      %@AB@%_TEXT%@AE@%         %@AB@%_DATA%@AE@%   ---Small     %@AB@%_TEXT%@AE@%         %@AB@%_DATA%@AE@%   ---Medium    %@AI@%module%@AE@%%@AB@%_TEXT%@AE@%   %@AB@%_DATA%@AE@%   %@AI@%filename%@AE@%Compact   %@AB@%_TEXT%@AE@%         %@AB@%_DATA%@AE@%   %@AI@%filename%@AE@%Large     %@AI@%module%@AE@%%@AB@%_TEXT%@AE@%   %@AB@%_DATA%@AE@%   %@AI@%filename%@AE@%Huge      %@AI@%module%@AE@%%@AB@%_TEXT%@AE@%   %@AB@%_DATA%@AE@%   %@AI@%filename%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   9   727 02 10 14 08 44 @%
  3147.  
  3148. In memory models that contain multiple data segments (compact, large, and
  3149. huge), %@AB@%_DATA%@AE@% is the name of the default data segment. Other data segments
  3150. have unique private names. You can override the default names with the
  3151. options /NT (name text) and /ND (name data).  %@NL@%
  3152. %@NL@%
  3153. The /ND option is commonly used to create and compile modules that contain
  3154. data only. Such modules can be accessed from other parts of the program by
  3155. declaring their variables as external.  %@NL@%
  3156. %@NL@%
  3157. If you change the name of the default data segment with /ND, your program
  3158. must load the DS register with the segment selector of your named data
  3159. segment before it accesses it. You must therefore compile your program
  3160. either with the /A%@AI@%string%@AE@%form of the memory-model option and the /Au option
  3161. for the segment setup, or with the /A option for a s%@NL@%
  3162. %@NL@%
  3163. %@NL@%
  3164. %@NL@%
  3165. %@NL@%
  3166. %@CR:C6A00030001 @%%@1@%%@AB@%Chapter 3  Using the In-Line Assembler%@AE@%%@EH@%%@NL@%
  3167. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3168. %@NL@%
  3169. This chapter explains how to use the Microsoft C in-line assembler. Assembly
  3170. language serves many purposes, such as improving program speed, reducing
  3171. memory needs, and controlling hardware. The in-line assembler lets you embed
  3172. assembly-language instructions directly in your C source programs without
  3173. extra assembly and link steps. The in-line assembler is built into the
  3174. compiler─you don't need a separate assembler such as the Microsoft Macro
  3175. Assembler (MASM).  %@NL@%
  3176. %@NL@%
  3177. %@NL@%
  3178. %@2@%%@CR:C6A00030002 @%%@AB@%3.1  Advantages of In-Line Assembly%@AE@%%@EH@%%@NL@%
  3179. %@NL@%
  3180. Because the in-line assembler doesn't require separate assembly and link
  3181. steps, it is more convenient than a separate assembler. In-line assembly
  3182. code can use any C variable or function name that is in scope, so it is easy
  3183. to integrate it with your program's C code. And because the assembly code
  3184. can be mixed in-line with C statements, it can do tasks that are cumbersome
  3185. or impossible in C alone.%@CR:C6A00030003 @%  %@NL@%
  3186. %@NL@%
  3187. The uses of in-line assembly include  %@NL@%
  3188. %@NL@%
  3189. %@NL@%
  3190.   ■   Writing functions in assembly language%@NL@%
  3191. %@NL@%
  3192.   ■   Spot-optimizing speed-critical sections of code%@NL@%
  3193. %@NL@%
  3194.   ■   Calling DOS and BIOS routines with the %@AB@%INT%@AE@% instruction%@NL@%
  3195. %@NL@%
  3196.   ■   Creating TSR (terminate-and-stay-resident) code or handler routines
  3197.       that require knowledge of processor states%@NL@%
  3198. %@NL@%
  3199. %@NL@%
  3200. In-line assembly is a special-purpose tool. If you plan to transport an
  3201. application, you'll probably want to place machine-specific code in a
  3202. separate module. And because the in-line assembler doesn't support all of
  3203. MASM's macro and data directives, you may find it more convenient to use
  3204. MASM for such modules.  %@NL@%
  3205. %@NL@%
  3206. %@NL@%
  3207. %@2@%%@CR:C6A00030004 @%%@AB@%3.2  The _asm Keyword%@AE@%%@EH@%%@NL@%
  3208. %@NL@%
  3209. The %@AB@%_asm%@AE@% keyword invokes the in-line assembler and can appear wherever a C
  3210. statement is legal. It cannot appear by itself. It must be followed by an
  3211. assembly instruction, a group of instructions enclosed in braces, or, at the
  3212. very least, an empty pair of braces. The term "%@AB@%_asm%@AE@% block" here refers to
  3213. any instruction or group of instructions, whether or not in braces.  %@NL@%
  3214. %@NL@%
  3215. Below is a simple %@AB@%_asm%@AE@% block enclosed in braces. (The code prints the "beep"
  3216. character, ASCII 7.)  %@NL@%
  3217. %@NL@%
  3218. %@AS@%  _asm
  3219. %@AS@%  {
  3220. %@AS@%     mov ah, 2
  3221. %@AS@%     mov dl, 7
  3222. %@AS@%     int 21h
  3223. %@AS@%  }%@AE@%%@NL@%
  3224. %@NL@%
  3225. Alternatively, you can put %@AB@%_asm%@AE@% in front of each assembly instruction:  %@NL@%
  3226. %@NL@%
  3227. %@AS@%  _asm mov ah, 2
  3228. %@AS@%  _asm mov dl, 7
  3229. %@AS@%  _asm int 21h%@AE@%%@NL@%
  3230. %@NL@%
  3231. Since the %@AB@%_asm%@AE@% keyword is a statement separator, you can also put assembly
  3232. instructions on the same line:  %@NL@%
  3233. %@NL@%
  3234. %@AS@%  _asm mov ah, 2   _asm mov dl, 7   _asm int 21h%@AE@%%@NL@%
  3235. %@NL@%
  3236. %@AU@% Braces can prevent ambiguity and needless repetition.%@AE@%  %@NL@%
  3237. %@NL@%
  3238. All three examples generate the same code, but the first style─enclosing the
  3239. %@AB@%_asm%@AE@% block in braces─has some advantages. The braces clearly separate
  3240. assembly code from C code and avoid needless repetition of the %@AB@%_asm%@AE@% keyword.
  3241. Braces can also prevent ambiguities. If you want to put a C statement on the
  3242. same line as an %@AB@%_asm%@AE@% block, you must enclose the block in braces. Without
  3243. the braces, the compiler cannot tell where assembly code stops and C
  3244. statements begin. Finally, since the text in braces has the same format as
  3245. ordinary MASM text, you can easily cut and paste text from existing MASM
  3246. source files.  %@NL@%
  3247. %@NL@%
  3248. The braces enclosing an %@AB@%_asm%@AE@% block don't affect variable scope, as do braces
  3249. in C. You can also nest %@AB@%_asm%@AE@% blocks, but the nesting doesn't affect variable
  3250. scope.  %@NL@%
  3251. %@NL@%
  3252. %@NL@%
  3253. %@2@%%@CR:C6A00030005 @%%@AB@%3.3  Using Assembly Language in _asm Blocks%@AE@%%@EH@%%@NL@%
  3254. %@NL@%
  3255. The in-line assembler has much in common with other assemblers. For example,
  3256. it accepts any expression that is legal in MASM, and it supports all 80286
  3257. and 80287 instructions. This section describes the use of assembly-language
  3258. features in %@AB@%_asm%@AE@% blocks.  %@NL@%
  3259. %@NL@%
  3260. %@NL@%
  3261. %@4@%%@AB@%Instruction Set%@AE@%%@EH@%%@NL@%
  3262. %@NL@%
  3263. The in-line assembler supports the full instruction set of the Intel 80286
  3264. and 80287 processors. It does not recognize 80386- and 80387-specific
  3265. instructions. To use 80286 or 80287 instructions, compile with the /G2
  3266. option.  %@NL@%
  3267. %@NL@%
  3268. %@NL@%
  3269. %@4@%%@AB@%Expressions%@AE@%%@EH@%%@NL@%
  3270. %@NL@%
  3271. In-line assembly code can use any MASM expression, that is, any combination
  3272. of operands and operators that evaluates to a single value or address.  %@NL@%
  3273. %@NL@%
  3274. %@NL@%
  3275. %@4@%%@AB@%Data Directives and Operators%@AE@%%@EH@%%@NL@%
  3276. %@NL@%
  3277. Although an %@AB@%_asm%@AE@% block can reference C data types and objects, it cannot
  3278. define data objects with MASM directives or operators. Specifically, you
  3279. cannot use the definition directives %@AB@%DB%@AE@%, %@AB@%DW%@AE@%, %@AB@%DD%@AE@%, %@AB@%DQ%@AE@%, %@AB@%DT%@AE@%, and %@AB@%DF%@AE@%, or the
  3280. operators %@AB@%DUP%@AE@% or %@AB@%THIS%@AE@%. Nor are MASM structures and records available. The
  3281. in-line assembler doesn't accept the directives %@AB@%STRUC%@AE@%, %@AB@%RECORD%@AE@%, %@AB@%WIDTH%@AE@%, or
  3282. %@AB@%MASK%@AE@%.  %@NL@%
  3283. %@NL@%
  3284. %@NL@%
  3285. %@4@%%@AB@%EVEN and ALIGN Directives%@AE@%%@EH@%%@NL@%
  3286. %@NL@%
  3287. While the in-line assembler doesn't support most MASM directives, it does
  3288. support %@AB@%EVEN%@AE@% and %@AB@%ALIGN%@AE@%. These directives put %@AB@%NOP%@AE@% (no operation) instructions
  3289. in the assembly code as needed to align labels to specific boundaries. This
  3290. makes instruction-fetch operations more efficient for some processors (not
  3291. including eight-bit processors such as the Intel 8088).  %@NL@%
  3292. %@NL@%
  3293. %@NL@%
  3294. %@4@%%@AB@%Macros%@AE@%%@EH@%%@NL@%
  3295. %@NL@%
  3296. The in-line assembler is not a macro assembler. You cannot use MASM macro
  3297. directives (%@AB@%MACRO%@AE@%, %@AB@%REPT%@AE@%, %@AB@%IRC%@AE@%, %@AB@%IRP%@AE@%, and %@AB@%ENDM%@AE@%) or macro operators ( %@AB@%<>%@AE@%, %@AB@%!%@AE@%, %@AB@%&%@AE@%,
  3298. %@AB@%%%@AE@%, and %@AB@%.TYPE%@AE@%). An %@AB@%_asm%@AE@% block can use C preprocessor directives, however. See
  3299. Section 3.4, "Using C in %@AB@%_asm%@AE@% Blocks" for more information.  %@NL@%
  3300. %@NL@%
  3301. %@NL@%
  3302. %@4@%%@AB@%Segment References%@AE@%%@EH@%%@NL@%
  3303. %@NL@%
  3304. You must refer to segments by register rather than by name (the segment name
  3305. %@AB@%_TEXT%@AE@% is invalid, for instance). Segment overrides must use the register
  3306. explicitly, as in ES:[BX].  %@NL@%
  3307. %@NL@%
  3308. %@NL@%
  3309. %@4@%%@AB@%Type and Variable Sizes%@AE@%%@EH@%%@NL@%
  3310. %@NL@%
  3311. The %@AB@%LENGTH%@AE@%, %@AB@%SIZE%@AE@%, and %@AB@%TYPE%@AE@% operators have a limited meaning in in-line
  3312. assembly. They cannot be used at all with the %@AB@%DUP%@AE@% operator (because you
  3313. cannot define data with MASM directives or operators). But you can use them
  3314. to find the size of C variables or types:  %@NL@%
  3315. %@NL@%
  3316. %@NL@%
  3317.   ■   The %@AB@%LENGTH%@AE@% operator can return the number of elements in an array. It
  3318.       returns the value 1 for nonarray variables.%@NL@%
  3319. %@NL@%
  3320.   ■   The %@AB@%SIZE%@AE@% operator can return the size of a C variable. A variable's
  3321.       size is the product of its %@AB@%LENGTH%@AE@% and %@AB@%TYPE%@AE@%.%@NL@%
  3322. %@NL@%
  3323.   ■   The %@AB@%TYPE%@AE@% operator can return the size of a C type or variable. If the
  3324.       variable is an array, %@AB@%TYPE%@AE@% returns the size of a single element of the
  3325.       array.%@NL@%
  3326. %@NL@%
  3327. %@NL@%
  3328. For instance, if your program has an eight-element %@AB@%int%@AE@% array,  %@NL@%
  3329. %@NL@%
  3330. %@AS@%  int arr[8];%@AE@%%@NL@%
  3331. %@NL@%
  3332. the following C and assembly expressions yield the size of %@AS@% arr %@AE@% and its
  3333. elements:  %@NL@%
  3334. %@NL@%
  3335. %@TH:   6   425 02 12 27 37 @%_asm        C                          Size%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AS@%LENGTH arr%@AE@%  sizeof(ar)/sizeof(arr[0])  8%@AS@%SIZE arr%@AE@%    sizeof (arr)               16%@AS@%TYPE arr%@AE@%    size14(arr[0])             2%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   6   425 02 12 27 37 @%
  3336.  
  3337. %@NL@%
  3338. %@4@%%@AB@%Comments%@AE@%%@EH@%%@NL@%
  3339. %@NL@%
  3340. Instructions in an %@AB@%_asm%@AE@% block can use assembly-language comments:  %@NL@%
  3341. %@NL@%
  3342. %@AS@%  _asm mov ax, offset buff ; Load address of buff%@AE@%%@NL@%
  3343. %@NL@%
  3344. Because C macros expand into a single logical line, avoid using
  3345. assemblylanguage comments in macros (see Section 3.8, "Defining %@AB@%_asm%@AE@% Blocks
  3346. as C Macros"). An %@AB@%_asm%@AE@% block can also contain C-style comments, as noted
  3347. below.  %@NL@%
  3348. %@NL@%
  3349. %@NL@%
  3350. %@4@%%@AB@%The _emit Pseudoinstruction%@AE@%%@EH@%%@NL@%
  3351. %@NL@%
  3352. The %@AB@%_emit%@AE@% pseudoinstruction is similar to the %@AB@%DB%@AE@% directive of MASM. It
  3353. allows you to define a single immediate byte at the current location in the
  3354. current text segment. However, %@AB@%_emit%@AE@% can define only one byte at a time, and
  3355. it can only define bytes in the text segment. It uses the same syntax as the
  3356. %@AB@%INT%@AE@% instruction.  %@NL@%
  3357. %@NL@%
  3358. One use for %@AB@%_emit%@AE@% is to define 80386-specific instructions, which the
  3359. in-line assembler does not support. The following fragment, for instance,
  3360. defines the 80386 %@AB@%CWDE%@AE@% instruction:  %@NL@%
  3361. %@NL@%
  3362. %@AS@%  /* Assumes 16-bit mode */
  3363. %@AS@%  #define cwde _asm _emit 0x66 _asm _emit 0x98
  3364. %@AS@%   .
  3365. %@AS@%   .
  3366. %@AS@%   .
  3367. %@AS@%  _asm {
  3368. %@AS@%       cwde
  3369. %@AS@%       }%@AE@%%@NL@%
  3370. %@NL@%
  3371. %@NL@%
  3372. %@4@%%@AB@%Debugging and Listings%@AE@%%@EH@%%@NL@%
  3373. %@NL@%
  3374. %@AU@% In-line assembly code can be debugged with CodeView.%@AE@%  %@NL@%
  3375. %@NL@%
  3376. Programs containing in-line assembly code can be debugged with the CodeView
  3377. debugger, assuming you compile with the /Zi option.  %@NL@%
  3378. %@NL@%
  3379. Within CodeView, you can set breakpoints on both C and assembly-language
  3380. lines. If you enable mixed assembly and C mode, you can display both the
  3381. source and disassembled form of the assembly code.  %@NL@%
  3382. %@NL@%
  3383. Note that putting multiple assembly instructions or C statements on one line
  3384. can hamper debugging with CodeView. In source mode, the CodeView debugger
  3385. lets you set breakpoints on a single line but not on individual statements
  3386. on the same line. The same principle applies to an %@AB@%_asm%@AE@% block defined as a C
  3387. macro, which expands to a single logical line.  %@NL@%
  3388. %@NL@%
  3389. If you create a mixed source and assembly listing with the /Fc compiler
  3390. option, the listing contains both the source and assembly forms of each
  3391. assemblylanguage line. Macros are not expanded in listings, but they are
  3392. expanded during compilation.  %@NL@%
  3393. %@NL@%
  3394. See Chapter 9, "Debugging C Programs with CodeView," for more information.  %@NL@%
  3395. %@NL@%
  3396. %@NL@%
  3397. %@2@%%@CR:C6A00030006 @%%@AB@%3.4  Using C in _asm Blocks%@AE@%%@EH@%%@NL@%
  3398. %@NL@%
  3399. Because in-line assembly instructions can be mixed with C statements, they
  3400. can refer to C variables by name and use many other elements of C. An %@AB@%_asm%@AE@%
  3401. block can use the following C language elements:  %@NL@%
  3402. %@NL@%
  3403. %@NL@%
  3404.   ■   Symbols, including labels and variable and function names%@NL@%
  3405. %@NL@%
  3406.   ■   Constants, including symbolic constants and %@AB@%enum%@AE@% members%@NL@%
  3407. %@NL@%
  3408.   ■   Macros and preprocessor directives%@NL@%
  3409. %@NL@%
  3410.   ■   Comments (both %@AS@% /* */ %@AE@% and %@AS@% // %@AE@%)%@NL@%
  3411. %@NL@%
  3412.   ■   Type names (wherever a MASM type would be legal)%@NL@%
  3413. %@NL@%
  3414.   ■   %@AB@%typedef%@AE@% names, generally used with operators such as %@AB@%PTR%@AE@% and %@AB@%TYPE%@AE@% or
  3415.       to specify structure or union members%@NL@%
  3416. %@NL@%
  3417. %@NL@%
  3418. Within an %@AB@%_asm%@AE@% block, you can specify integer constants with either C
  3419. notation or assembler radix notation (0x100 and 100h are equivalent, for
  3420. instance). This allows you to define (using %@AB@%#define%@AE@%) a constant in C, and
  3421. use it in both C and assembly portions of the program. You can also specify
  3422. constants in octal by preceding them with a 0. For example, 0777 specifies
  3423. an octal constant.  %@NL@%
  3424. %@NL@%
  3425. %@NL@%
  3426. %@3@%%@CR:C6A00030007 @%%@AB@%3.4.1  Using Operators%@AE@%%@EH@%%@NL@%
  3427. %@NL@%
  3428. An %@AB@%_asm%@AE@% block cannot use C-specific operators, such as the %@AB@%%@AE@% operator.
  3429. However, operators shared by C and MASM, such as the %@AB@%*%@AE@% operator, are
  3430. interpreted as assembly-language operators. For instance, outside an %@AB@%_asm%@AE@%
  3431. block, square brackets (%@AB@% [] %@AE@%) are interpreted as enclosing array subscripts,
  3432. which C automatically scales to the size of an element in the array. Inside
  3433. an %@AB@%_asm%@AE@% block, they are seen as the MASM index operator, which yields an
  3434. unscaled byte offset from any data object or label (not just an array). The
  3435. following code illustrates the difference:  %@NL@%
  3436. %@NL@%
  3437. %@AS@%  int array[10];
  3438. %@AS@%  
  3439. %@AS@%  _asm mov array[6], bx ;  Store BX at array+6 (not scaled)
  3440. %@AS@%  
  3441. %@AS@%  array[6] = 0;         /* Store 0 at array+12 (scaled) */%@AE@%%@NL@%
  3442. %@NL@%
  3443. The first reference to %@AS@% array %@AE@% is not scaled, but the second is. Note that
  3444. you can use the %@AB@%TYPE%@AE@% operator to achieve scaling based on a constant. For
  3445. instance, the following statements are equivalent:  %@NL@%
  3446. %@NL@%
  3447. %@AS@%  _asm mov array[6 * TYPE int], 0 ; Store 0 at array + 12
  3448. %@AS@%  
  3449. %@AS@%  array[6] = 0;                   /* Store 0 at array + 12 */%@AE@%%@NL@%
  3450. %@NL@%
  3451. %@NL@%
  3452. %@3@%%@CR:C6A00030008 @%%@AB@%3.4.2  Using C Symbols%@AE@%%@EH@%%@NL@%
  3453. %@NL@%
  3454. An %@AB@%_asm%@AE@% block can refer to any C symbol in scope where the block appears. (C
  3455. symbols are variable names, function names, and labels─in other words, names
  3456. that aren't symbolic constants or %@AB@%enum%@AE@% members.)  %@NL@%
  3457. %@NL@%
  3458. A few restrictions apply to the use of C symbols:  %@NL@%
  3459. %@NL@%
  3460. %@NL@%
  3461.   ■   Each assembly-language statement can contain only one C symbol.
  3462.       Multiple symbols can appear in the same assembly instruction only with
  3463.       %@AB@%LENGTH, TYPE%@AE@%, and %@AB@%SIZE%@AE@% expressions.%@NL@%
  3464. %@NL@%
  3465.   ■   Functions referenced in an %@AB@%_asm%@AE@% block must be declared (prototyped)
  3466.       earlier in the program. Otherwise, the compiler cannot distinguish
  3467.       between function names and labels in the %@AB@%_asm%@AE@% block.%@NL@%
  3468. %@NL@%
  3469.   ■   An %@AB@%_asm%@AE@% block cannot use any C symbols with the same spelling as MASM
  3470.       reserved words (regardless of case). MASM reserved words include
  3471.       instruction names such as %@AB@%PUSH%@AE@% and register names such as SI.%@NL@%
  3472. %@NL@%
  3473.   ■   Structure and union tags are not recognized in %@AB@%_asm%@AE@% blocks.%@NL@%
  3474. %@NL@%
  3475. %@NL@%
  3476. %@NL@%
  3477. %@3@%%@CR:C6A00030009 @%%@AB@%3.4.3  Accessing C Data%@AE@%%@EH@%%@NL@%
  3478. %@NL@%
  3479. A great convenience of in-line assembly is the ability to refer to C
  3480. variables by name. An %@AB@%_asm%@AE@% block can refer to any symbols─including variable
  3481. names─that are in scope where the block appears. For instance, if the C
  3482. variable %@AS@% var %@AE@% is in scope, the instruction  %@NL@%
  3483. %@NL@%
  3484. %@AS@%  _asm mov ax, var%@AE@%%@NL@%
  3485. %@NL@%
  3486. stores the value of %@AS@% var %@AE@% in AX.  %@NL@%
  3487. %@NL@%
  3488. If a structure or union member has a unique name, an %@AB@%_asm%@AE@% block can refer to
  3489. it using only the member name, without specifying the C variable or %@AB@%typedef%@AE@%
  3490. name before the period (%@AB@%.%@AE@%) operator. If the member name is not unique,
  3491. however, you must place a variable or %@AB@%typedef%@AE@% name immediately before the
  3492. period (%@AB@%.%@AE@%) operator. For instance, the following structure types share %@AS@%
  3493. %@AS@%same_name %@AE@% as their member name: %@AS@%  %@AE@%%@NL@%
  3494. %@NL@%
  3495. %@AS@%  struct first_type
  3496. %@AS@%  {
  3497. %@AS@%     char *weasel;
  3498. %@AS@%     int same_name;
  3499. %@AS@%  };
  3500. %@AS@%  
  3501. %@AS@%  struct second_type
  3502. %@AS@%  {
  3503. %@AS@%     int wonton;
  3504. %@AS@%     long same_name;
  3505. %@AS@%  };%@AE@%%@NL@%
  3506. %@NL@%
  3507. If you declare variables with the types  %@NL@%
  3508. %@NL@%
  3509. %@AS@%  struct first_type hal;
  3510. %@AS@%  struct second_type oat;%@AE@%%@NL@%
  3511. %@NL@%
  3512. all references to the member %@AS@% same_name %@AE@% must use the variable name, because
  3513. %@AS@% same_name %@AE@% is not unique. But the member %@AS@% weasel %@AE@% has a unique name, so you
  3514. can refer to it using only its member name:  %@NL@%
  3515. %@NL@%
  3516. %@AS@%  _asm
  3517. %@AS@%  {
  3518. %@AS@%     mov bx, OFFSET hal
  3519. %@AS@%     mov cx, [bx]hal.same_name ; Must use 'hal'
  3520. %@AS@%     mov si, [bx].weasel       ; Can omit 'hal'
  3521. %@AS@%  }%@AE@%%@NL@%
  3522. %@NL@%
  3523. Note that omitting the variable name is merely a coding convenience. The
  3524. same assembly instructions are generated whether or not it is present.  %@NL@%
  3525. %@NL@%
  3526. %@NL@%
  3527. %@3@%%@CR:C6A00030010 @%%@AB@%3.4.4  Writing Functions%@AE@%%@EH@%%@NL@%
  3528. %@NL@%
  3529. If you write a function with in-line assembly code, it's a simple matter to
  3530. pass arguments to the function and return a value from it. The following
  3531. examples compare a function first written for a separate assembler and then
  3532. rewritten for the in-line assembler. The function, called %@AS@% power2%@AE@%, receives
  3533. two parameters, multiplying the first parameter by 2 to the power of the
  3534. second parameter. Written for a separate assembler, the function might look
  3535. like this:  %@NL@%
  3536. %@NL@%
  3537. %@AS@%  ; POWER.ASM
  3538. %@AS@%  ; Compute the power of an integer
  3539. %@AS@%  ;
  3540. %@AS@%         PUBLIC _power2
  3541. %@AS@%  _TEXT SEGMENT WORD PUBLIC 'CODE'
  3542. %@AS@%  _power2 PROC
  3543. %@AS@%  
  3544. %@AS@%          push bp         ; Save BP
  3545. %@AS@%          mov bp, sp      ; Move SP into BP so we can refer
  3546. %@AS@%                          ;   to arguments on the stack
  3547. %@AS@%          mov ax, [bp+4]  ; Get first argument
  3548. %@AS@%          mov cx, [bp+6]  ; Get second argument
  3549. %@AS@%          shl ax, cl      ; AX = AX * ( 2 ^ CL )
  3550. %@AS@%          pop bp          ; Restore BP
  3551. %@AS@%          ret             ; Return with sum in AX
  3552. %@AS@%  
  3553. %@AS@%  _power2 ENDP
  3554. %@AS@%  _TEXT   ENDS
  3555. %@AS@%          END%@AE@%%@NL@%
  3556. %@NL@%
  3557. %@AU@% Function arguments are usually passed on the stack.%@AE@%  %@NL@%
  3558. %@NL@%
  3559. Since it's written for a separate assembler, the function requires a
  3560. separate source file and assembly and link steps. C function arguments
  3561. usually are passed on the stack, so this version of the %@AS@% power2 %@AE@% function
  3562. accesses its arguments by their positions on the stack. (Note that the %@AB@%MODEL%@AE@%
  3563. directive, available in MASM and some other assemblers, also allows you to
  3564. access stack arguments and local stack variables by name.)  %@NL@%
  3565. %@NL@%
  3566. The POWER2.C program below writes the %@AS@% power2 %@AE@% function with in-line
  3567. assembly code:  %@NL@%
  3568. %@NL@%
  3569. %@AS@%  /* POWER2.C */
  3570. %@AS@%  #include <stdio.h>
  3571. %@AS@%  
  3572. %@AS@%  int power2( int num, int power );
  3573. %@AS@%  
  3574. %@AS@%  void main( void )
  3575. %@AS@%  {
  3576. %@AS@%     printf( "3 times 2 to the power of 5 is %d\n", \
  3577. %@AS@%             power2( 3, 5) );
  3578. %@AS@%  }
  3579. %@AS@%  
  3580. %@AS@%  int power2( int num, int power )
  3581. %@AS@%  {
  3582. %@AS@%     _asm
  3583. %@AS@%     {
  3584. %@AS@%        mov ax, num    ; Get first argument
  3585. %@AS@%        mov cx, power  ; Get second argument
  3586. %@AS@%        shl ax, cl     ; AX = AX * ( 2 to the power of CL )
  3587. %@AS@%     }
  3588. %@AS@%     /* Return with result in AX */
  3589. %@AS@%  }%@AE@%%@NL@%
  3590. %@NL@%
  3591. The in-line version of the %@AS@% power2 %@AE@% function refers to its arguments by name
  3592. and appears in the same source file as the rest of the program. This version
  3593. also requires fewer assembly instructions. Since C automatically preserves
  3594. BP, the %@AB@%_asm%@AE@% block doesn't need to do so. It can also dispense with the %@AB@%RET%@AE@%
  3595. instruction, since the C part of the function performs the return.  %@NL@%
  3596. %@NL@%
  3597. Because the in-line version of %@AS@% power2 %@AE@% doesn't execute a C %@AB@%return%@AE@%
  3598. statement, it causes a harmless warning if you compile at warning levels 2
  3599. or higher:  %@NL@%
  3600. %@NL@%
  3601. %@AS@%  warning C4035: 'power2' : no return value%@AE@%%@NL@%
  3602. %@NL@%
  3603. The function does return a value, but the compiler cannot tell that in the
  3604. absence of a %@AB@%return%@AE@% statement. Simply ignore the warning in this context.  %@NL@%
  3605. %@NL@%
  3606. %@NL@%
  3607. %@2@%%@CR:C6A00030011 @%%@AB@%3.5  Using and Preserving Registers%@AE@%%@EH@%%@NL@%
  3608. %@NL@%
  3609. In general, you should not assume that a register will have a given value
  3610. when an %@AB@%_asm%@AE@% block begins. An %@AB@%_asm%@AE@% block inherits whatever register values
  3611. happen to result from the normal flow of control.  %@NL@%
  3612. %@NL@%
  3613. If you use the %@AB@%_fastcall%@AE@% calling convention, the compiler passes function
  3614. arguments in registers instead of the stack. This can create problems in
  3615. functions with %@AB@%_asm%@AE@% blocks, since a function has no way to tell which
  3616. parameter is in which register. If the function happens to receive a
  3617. parameter in AX and immediately stores something else in AX, the parameter
  3618. is lost. In addition, you must preserve the CX and ES registers in any
  3619. function declared with %@AB@%_fastcall%@AE@%.  %@NL@%
  3620. %@NL@%
  3621. %@AU@% Don't use the _fastcall calling convention for functions with _asm blocks.%@AE@%
  3622. %@NL@%
  3623. %@NL@%
  3624. To avoid such register conflicts, don't use the %@AB@%_fastcall%@AE@% convention for
  3625. functions that contain an %@AB@%_asm%@AE@% block. If you specify the %@AB@%_fastcall%@AE@%
  3626. convention globally with the /Gr compiler option, declare every function
  3627. containing an %@AB@%_asm%@AE@% block with %@AB@%_cdecl%@AE@%. (The %@AB@%_cdecl%@AE@% attribute tells the
  3628. compiler to use the normal C calling convention for that function.) If you
  3629. are not compiling with /Gr, avoid declaring the function with the %@AB@%_fastcall%@AE@%
  3630. attribute.  %@NL@%
  3631. %@NL@%
  3632. As you may have noticed in the POWER2.C example in Section 3.4.4, the %@AS@%
  3633. %@AS@%power2 %@AE@% function doesn't preserve the value in the AX register. When you
  3634. write a function in assembly language, you don't need to preserve the AX,
  3635. BX, CX, DX, ES, and flags registers. However, you should preserve any other
  3636. registers you use (DI, SI, DS, SS, SP, and BP).  %@NL@%
  3637. %@NL@%
  3638. ────────────────────────────────────────────────────────────────────────────%@NL@%
  3639. %@AU@%WARNING%@AE@%%@NL@%
  3640. %@NL@%
  3641. If your in-line assembly code changes the direction flag using the STD or
  3642. CLD instructions, you must restore the flag to its original value.%@NL@%
  3643. ────────────────────────────────────────────────────────────────────────────%@NL@%
  3644. %@NL@%
  3645. %@AU@% Functions return values in the AX and DX registers.%@AE@%  %@NL@%
  3646. %@NL@%
  3647. The POWER2.C example in Section 3.4.4 also shows that functions return
  3648. values in registers. This is true whether the function is written in
  3649. assembly language or in C.  %@NL@%
  3650. %@NL@%
  3651. If the return value is short (a %@AB@%char%@AE@%, %@AB@%int%@AE@%, or %@AB@%near%@AE@% pointer), it is stored in
  3652. AX. The POWER2.C example returned a value by terminating with the desired
  3653. value in AX.  %@NL@%
  3654. %@NL@%
  3655. If the return value is long, store the high word in DX and the low word in
  3656. AX. To return a longer value (such as a floating-point value), store the
  3657. value in memory and return a pointer to the value (in AX if %@AB@%near%@AE@% or in DX:AX
  3658. if %@AB@%far%@AE@%).  %@NL@%
  3659. %@NL@%
  3660. Assembly instructions that appear in-line with C statements are free to
  3661. alter the AX, BX, CX, and DX registers. C doesn't expect these registers to
  3662. be maintained between statements, so you don't need to preserve them. The
  3663. same is true of the SI and DI registers, with some exceptions (see Section
  3664. 3.9, "Optimizing"). You should preserve the SP and BP registers unless you
  3665. have some reason to change them─to switch stacks, for instance.  %@NL@%
  3666. %@NL@%
  3667. %@NL@%
  3668. %@2@%%@CR:C6A00030012 @%%@AB@%3.6  Jumping to Labels%@AE@%%@EH@%%@NL@%
  3669. %@NL@%
  3670. Like an ordinary C label, a label in an %@AB@%_asm%@AE@% block has scope throughout the
  3671. function in which it is defined (not only in the block). Both assembly
  3672. instructions and C %@AB@%goto%@AE@% statements can jump to labels inside or outside the
  3673. %@AB@%_asm%@AE@% block.  %@NL@%
  3674. %@NL@%
  3675. %@AU@% Labels in _asm blocks have function scope and are not case sensitive.%@AE@%  %@NL@%
  3676. %@NL@%
  3677. Unlike C labels, labels defined in %@AB@%_asm%@AE@% blocks are not case sensitive, even
  3678. when used in C statements. C labels are not case sensitive in an %@AB@%_asm%@AE@% block,
  3679. either. (Outside an %@AB@%_asm%@AE@% block, a C label is case sensitive as usual.) The
  3680. following do-nothing code shows all the permutations:  %@NL@%
  3681. %@NL@%
  3682. %@AS@%  void func( void )
  3683. %@AS@%  {
  3684. %@AS@%     goto C_Dest;  /* legal */
  3685. %@AS@%     goto c_dest;  /* error */
  3686. %@AS@%  
  3687. %@AS@%     goto A_Dest;  /* legal */
  3688. %@AS@%     goto a_dest;  /* legal */
  3689. %@AS@%  
  3690. %@AS@%     _asm
  3691. %@AS@%     {
  3692. %@AS@%        jmp C_Dest ; legal
  3693. %@AS@%        jmp c_dest ; legal
  3694. %@AS@%  
  3695. %@AS@%        jmp A_Dest ; legal
  3696. %@AS@%        jmp a_dest ; legal
  3697. %@AS@%  
  3698. %@AS@%        a_dest:    ; _asm label
  3699. %@AS@%     }
  3700. %@AS@%  
  3701. %@AS@%     C_Dest:       /* C label */ 
  3702. %@AS@%     return;
  3703. %@AS@%  }%@AE@%%@NL@%
  3704. %@NL@%
  3705. Don't use C library function names as labels in %@AB@%_asm%@AE@% blocks. For instance,
  3706. you might be tempted to use %@AS@% exit %@AE@% as a label,  %@NL@%
  3707. %@NL@%
  3708. %@AS@%  jne exit
  3709. %@AS@%     .
  3710. %@AS@%     .
  3711. %@AS@%     .
  3712. %@AS@%  exit:
  3713. %@AS@%     ; More _asm code follows%@AE@%%@NL@%
  3714. %@NL@%
  3715. forgetting that %@AB@%exit%@AE@% is the name of a C library function. The code doesn't
  3716. cause a compiler error, but it might cause a jump to the %@AB@%exit%@AE@% function
  3717. instead of the desired location.  %@NL@%
  3718. %@NL@%
  3719. As in MASM programs, the dollar symbol (%@AB@%$%@AE@%) serves as the current location
  3720. counter─a label for the instruction currently being assembled. In %@AB@%_asm%@AE@%
  3721. blocks, its main use is to make long conditional jumps:  %@NL@%
  3722. %@NL@%
  3723. %@AS@%  jne $+5 ; next instruction is 5 bytes long
  3724. %@AS@%  jmp farlabel
  3725. %@AS@%  ; $+5
  3726. %@AS@%     .
  3727. %@AS@%     .
  3728. %@AS@%     .
  3729. %@AS@%  farlabel:%@AE@%%@NL@%
  3730. %@NL@%
  3731. %@NL@%
  3732. %@2@%%@CR:C6A00030013 @%%@AB@%3.7  Calling C Functions%@AE@%%@EH@%%@NL@%
  3733. %@NL@%
  3734. An %@AB@%_asm%@AE@% block can call C functions, including C library routines. The
  3735. following example calls the %@AB@%printf%@AE@% library routine:  %@NL@%
  3736. %@NL@%
  3737. %@AS@%  #include <stdio.h>
  3738. %@AS@%  
  3739. %@AS@%  char format[] = "%s %s\n";
  3740. %@AS@%  char hello[] = "Hello";
  3741. %@AS@%  char world[] = "world";
  3742. %@AS@%  
  3743. %@AS@%  void main( void )
  3744. %@AS@%  {
  3745. %@AS@%     _asm
  3746. %@AS@%     {
  3747. %@AS@%        mov  ax, offset world
  3748. %@AS@%        push ax
  3749. %@AS@%        mov  ax, offset hello
  3750. %@AS@%        push ax
  3751. %@AS@%        mov  ax, offset format
  3752. %@AS@%        push ax
  3753. %@AS@%        call printf
  3754. %@AS@%     }
  3755. %@AS@%  }%@AE@%%@NL@%
  3756. %@NL@%
  3757. Since function arguments are passed on the stack, you simply push the needed
  3758. arguments─string pointers, in the example above─before calling the function.
  3759. The arguments are pushed in reverse order, so they come off the stack in the
  3760. desired order. To emulate the C statement  %@NL@%
  3761. %@NL@%
  3762. %@AS@%  printf( format, hello, world );%@AE@%%@NL@%
  3763. %@NL@%
  3764. the example pushes pointers to %@AS@% world%@AE@%, %@AS@% hello%@AE@%, and %@AS@% format%@AE@%, in that order,
  3765. then calls %@AB@%printf%@AE@%.  %@NL@%
  3766. %@NL@%
  3767. %@NL@%
  3768. %@2@%%@CR:C6A00030014 @%%@AB@%3.8  Defining _asm Blocks as C Macros%@AE@%%@EH@%%@NL@%
  3769. %@NL@%
  3770. C macros offer a convenient way to insert assembly code into C code, but
  3771. they demand extra care because a macro expands into a single logical line.
  3772. To create trouble-free macros, follow these rules:  %@NL@%
  3773. %@NL@%
  3774. %@NL@%
  3775.   ■   Enclose the %@AB@%_asm%@AE@% block in braces.%@NL@%
  3776. %@NL@%
  3777.   ■   Put the %@AB@%_asm%@AE@% keyword in front of each assembly instruction.%@NL@%
  3778. %@NL@%
  3779.   ■   Use old-style C comments (%@AS@% /* comment */ %@AE@%) instead of assembly-style
  3780.       comments (%@AS@% ; comment %@AE@%) or single-line C comments (%@AS@% // comment %@AE@%).%@NL@%
  3781. %@NL@%
  3782. %@NL@%
  3783. To illustrate, the following example defines a simple macro:  %@NL@%
  3784. %@NL@%
  3785. %@AS@%  #define BEEP _asm \
  3786. %@AS@%  /* Beep sound */       \
  3787. %@AS@%  {                       \
  3788. %@AS@%     _asm mov ah, 2       \
  3789. %@AS@%     _asm mov dl, 7       \
  3790. %@AS@%     _asm int 21h         \
  3791. %@AS@%  }%@AE@%%@NL@%
  3792. %@NL@%
  3793. At first glance, the last three %@AB@%_asm%@AE@% keywords seem superfluous. They are
  3794. needed, however, because the macro expands into a single line:  %@NL@%
  3795. %@NL@%
  3796. %@AS@%  _asm /* Beep sound */ { _asm mov ah, 2  _asm mov dl, 7 _asm int 21h }%@AE@%%@NL@%
  3797. %@NL@%
  3798. The third and fourth %@AB@%_asm%@AE@% keywords are needed as statement separators. The
  3799. only statement separators recognized in %@AB@%_asm%@AE@% blocks are the newline
  3800. character and %@AB@%_asm%@AE@% keyword. And since a block defined as a macro is one
  3801. logical line, you must separate each instruction with %@AB@%_asm%@AE@%.  %@NL@%
  3802. %@NL@%
  3803. The braces are essential as well. If you omit them, the compiler can be
  3804. confused by C statements on the same line to the right of the macro
  3805. invocation. Without the closing brace, the compiler cannot tell where
  3806. assembly code stops, and it sees C statements after the %@AB@%_asm%@AE@% block as
  3807. assembly instructions.  %@NL@%
  3808. %@NL@%
  3809. %@AU@% Use C comments in _asm blocks written as macros.%@AE@%  %@NL@%
  3810. %@NL@%
  3811. Assembly-style comments that start with a semicolon (;) continue to the end
  3812. of the line. This causes problems in macros because the compiler ignores
  3813. everything after the comment, all the way to the end of the logical line.
  3814. The same is true of single-line C comments (%@AS@% // comment %@AE@%). To prevent
  3815. errors, use old-style C comments (%@AS@% /* comment */ %@AE@%) in %@AB@%_asm%@AE@% blocks defined as
  3816. macros.  %@NL@%
  3817. %@NL@%
  3818. %@AU@% An _asm block written as a C macro can take arguments but cannot return a
  3819. %@AU@%value.%@AE@%  %@NL@%
  3820. %@NL@%
  3821. An %@AB@%_asm%@AE@% block written as a C macro can take arguments. Unlike an ordinary C
  3822. macro, however, an %@AB@%_asm%@AE@% macro cannot return a value. So you cannot use such
  3823. macros in C expressions.  %@NL@%
  3824. %@NL@%
  3825. Be careful not to invoke macros of this type indiscriminately. For instance,
  3826. invoking an assembly-language macro in a function declared with the
  3827. %@AB@%_fastcall%@AE@% con-vention may cause unexpected results. (See Section 3.5, "Using
  3828. and Preserving Registers.")  %@NL@%
  3829. %@NL@%
  3830. %@AU@% You can convert MASM macros to C macros.%@AE@%  %@NL@%
  3831. %@NL@%
  3832. Note that some MASM-style macros can be written as C macros. Below is a MASM
  3833. macro that sets the video page to the value specified in the %@AS@% page %@AE@%
  3834. argument:  %@NL@%
  3835. %@NL@%
  3836. %@AS@%  setpage   MACRO page
  3837. %@AS@%            mov ah, 5
  3838. %@AS@%            mov al, page
  3839. %@AS@%            int 10h
  3840. %@AS@%            ENDM%@AE@%%@NL@%
  3841. %@NL@%
  3842. The following code defines %@AS@% setpage %@AE@% as a C macro:  %@NL@%
  3843. %@NL@%
  3844. %@AS@%  #define setpage( page ) _asm  \
  3845. %@AS@%     {                                \
  3846. %@AS@%        _asm mov ah, 5                \
  3847. %@AS@%        _asm mov al, page             \
  3848. %@AS@%        _asm int 10h                  \
  3849. %@AS@%  }%@AE@%%@NL@%
  3850. %@NL@%
  3851. Both macros do the same job.  %@NL@%
  3852. %@NL@%
  3853. %@NL@%
  3854. %@2@%%@CR:C6A00030015 @%%@AB@%3.9  Optimizing%@AE@%%@EH@%%@NL@%
  3855. %@NL@%
  3856. The presence of an %@AB@%_asm%@AE@% block in a function affects optimization in a few
  3857. different ways. First, as you might expect, the compiler doesn't try to
  3858. optimize the %@AB@%_asm%@AE@% block itself. What you write in assembly language is
  3859. exactly what you get.  %@NL@%
  3860. %@NL@%
  3861. Second, the presence of an %@AB@%_asm%@AE@% block affects register variable storage.
  3862. Under normal circumstances (unless you suppress optimization with the /Od
  3863. option) the compiler automatically stores variables in registers. This is
  3864. not done, however, in any function that contains an %@AB@%_asm%@AE@% block. To get
  3865. register variable storage in such a function, you must request it with the
  3866. %@AB@%register%@AE@% keyword.  %@NL@%
  3867. %@NL@%
  3868. Since the compiler stores register variables in the SI and DI registers,
  3869. these registers represent variables in functions that request register
  3870. storage. The first eligible variable is stored in SI and the second in DI.
  3871. Preserve SI and DI in such functions unless you want to change the register
  3872. variables.  %@NL@%
  3873. %@NL@%
  3874. Keep in mind that the name of a variable declared with %@AB@%register%@AE@% translates
  3875. directly into a register reference (assuming a register is available for
  3876. such use). For instance, if you declare  %@NL@%
  3877. %@NL@%
  3878. %@AS@%  register int sample;%@AE@%%@NL@%
  3879. %@NL@%
  3880. and the variable %@AS@% sample %@AE@% happens to be stored in SI, then the %@AB@%_asm%@AE@%
  3881. instruction  %@NL@%
  3882. %@NL@%
  3883. %@AS@%  _asm mov ax, sample%@AE@%%@NL@%
  3884. %@NL@%
  3885. is equivalent to  %@NL@%
  3886. %@NL@%
  3887. %@AS@%  _asm mov ax, si%@AE@%%@NL@%
  3888. %@NL@%
  3889. If you declare a variable with %@AB@%register%@AE@% and the compiler cannot store the
  3890. variable in a register, the compiler issues a warning to that effect at
  3891. compile time. The solution is to remove the %@AB@%register%@AE@% declaration from that
  3892. variable.  %@NL@%
  3893. %@NL@%
  3894. Register variables form a slight exception to the general rule that an
  3895. assembly-language statement can contain no more than one C symbol. If one of
  3896. the symbols is a register variable, for example,  %@NL@%
  3897. %@NL@%
  3898. %@AS@%  register int v1;
  3899. %@AS@%  int v2;%@AE@%%@NL@%
  3900. %@NL@%
  3901. then an instruction can use two C symbols, as in  %@NL@%
  3902. %@NL@%
  3903. %@AS@%  mov v1, v2%@AE@%%@NL@%
  3904. %@NL@%
  3905. Finally, the presence of in-line assembly code inhibits the following
  3906. optimizations for the entire function in which the code appears:  %@NL@%
  3907. %@NL@%
  3908. %@NL@%
  3909.   ■   Loop ( /Ol )%@NL@%
  3910. %@NL@%
  3911.   ■   Global register allocation ( /Oe )%@NL@%
  3912. %@NL@%
  3913.   ■   Global optimizations and common subexpressions ( /Og )%@NL@%
  3914. %@NL@%
  3915. %@NL@%
  3916. These optimizations are suppressed no matter which compiler options you use.
  3917. %@NL@%
  3918. %@NL@%
  3919. %@NL@%
  3920. %@NL@%
  3921. %@NL@%
  3922. %@NL@%
  3923. %@NL@%
  3924. %@CR:C6A00040001 @%%@1@%%@AB@%Chapter 4  Controlling Floating-Point Math Operations%@AE@%%@EH@%%@NL@%
  3925. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3926. %@NL@%
  3927. This chapter describes how to control the way your Microsoft C programs
  3928. perform floating-point math operations. It describes the math packages that
  3929. you can include in C libraries when you run the SETUP program, then
  3930. discusses  the options you can specify in the Programmer's WorkBench (PWB)
  3931. or on the CL command line to choose the appropriate library for linking and
  3932. controlling floating-point instructions.%@CR:C6A00040002 @%  %@NL@%
  3933. %@NL@%
  3934. This chapter also explains how to override floating-point options by
  3935. changing libraries at link time, and how to control use of the Intel math
  3936. coprocessor (80%@AI@%x%@AE@%87) using the NO87 environment variable.%@CR:C6A00040003 @%%@CR:C6A00040004 @%%@CR:C6A00040005 @%%@CR:C6A00040006 @%  %@NL@%
  3937. %@NL@%
  3938. %@NL@%
  3939. %@2@%%@CR:C6A00040007 @%%@AB@%4.1  Declaring Floating-Point Types%@AE@%%@EH@%%@NL@%
  3940. %@NL@%
  3941. Microsoft C supports three floating-point types that conform to the
  3942. Institute of Electrical and Electronics Engineers (IEEE) standard 754
  3943. format:%@CR:C6A00040008 @%  %@NL@%
  3944. %@NL@%
  3945. %@NL@%
  3946.   1.  Type %@AB@%float%@AE@%, a 32-bit floating-point quantity%@NL@%
  3947. %@NL@%
  3948.   2.  Type %@AB@%double%@AE@%, a 64-bit floating-point quantity%@NL@%
  3949. %@NL@%
  3950.   3.  Type %@AB@%long double%@AE@%, an 80-bit floating-point quantity%@NL@%
  3951. %@NL@%
  3952. %@NL@%
  3953. You can declare variables as any of these types. You can also declare
  3954. functions that return any of these types.  %@NL@%
  3955. %@NL@%
  3956. %@NL@%
  3957. %@3@%%@CR:C6A00040009 @%%@AB@%4.1.1  Declaring Variables as Floating-Point Types%@CR:C6A00040010 @%%@AE@%%@EH@%%@NL@%
  3958. %@NL@%
  3959. You can declare variables as %@AB@%float%@AE@%, %@AB@%double%@AE@%, or %@AB@%long double%@AE@%, depending on the
  3960. needs of your application. The principal differences between the three types
  3961. are the significance they can represent, the storage they require, and their
  3962. range. Table 4.1 shows the relationship between significance and storage
  3963. requirements.%@CR:C6A00040011 @%%@CR:C6A00040012 @%%@CR:C6A00040013 @%%@CR:C6A00040014 @%%@CR:C6A00040015 @%%@CR:C6A00040016 @%%@CR:C6A00040017 @%%@CR:C6A00040018 @%%@CR:C6A00040019 @%%@CR:C6A00040020 @%  %@NL@%
  3964. %@NL@%
  3965. %@AB@%Table 4.1  %@AB@%Floating-Point Types%@AE@%%@AE@%
  3966.  
  3967. %@TH:   6   416 02 14 20 42 @%Type          Significant Digits  Number of Bytes%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%float%@AE@%         6-7                 4%@AB@%double%@AE@%        15-16               8%@AB@%long double%@AE@%   19                  10%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   6   416 02 14 20 42 @%
  3968.  
  3969. Floating-point variables are represented by a mantissa, which contains the
  3970. value of the number, and an exponent, which contains the order of magnitude
  3971. of the number.%@CR:C6A00040021 @%%@CR:C6A00040022 @%  %@NL@%
  3972. %@NL@%
  3973. Table 4.2 shows the number of bits allocated to the mantissa and the
  3974. exponent for each floating-point type. The most-significant bit of any
  3975. %@AB@%float%@AE@%, %@AB@%double%@AE@%, or %@AB@%long double %@AE@%is always the sign bit. If it is 1, the number
  3976. is considered negative; otherwise, it is considered a positive number.%@CR:C6A00040023 @%  %@NL@%
  3977. %@NL@%
  3978. %@AB@%Table 4.2  %@AB@%Lengths of Exponents and Mantissas%@AE@%%@AE@%
  3979.  
  3980. %@TH:   6   421 02 14 17 45 @%Type          Exponent Length  Mantissa Length%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%float%@AE@%         8 bits           23 bits%@AB@%double%@AE@%        11 bits          52 bits%@AB@%long double%@AE@%   15 bits          64 bits%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   6   421 02 14 17 45 @%
  3981.  
  3982. Because exponents are stored in an unsigned form, the exponent is biased by
  3983. half its possible value. For type %@AB@%float%@AE@%, the bias is 127; for type %@AB@%double%@AE@%,
  3984. it is 1,023; for type %@AB@%long double%@AE@%, it is 16,383. You can compute the actual
  3985. exponent value by subtracting the bias value from the exponent value.%@CR:C6A00040024 @%  %@NL@%
  3986. %@NL@%
  3987. The mantissa is stored as a binary fraction greater than or equal to 1 and
  3988. less than 2. For types %@AB@%float %@AE@%and %@AB@%double%@AE@%, there is an implied leading 1 in
  3989. the mantissa in the most-significant bit position, so the mantissas are
  3990. actually 24 and 53 bits long, respectively, even though the most-significant
  3991. bit is never stored in memory.  %@NL@%
  3992. %@NL@%
  3993. Instead of the storage method just described, the floating-point package can
  3994. store binary floating-point numbers as denormalized numbers. Denormalized
  3995. numbers are nonzero floating-point numbers with reserved exponent values in
  3996. which the most-significant bit of the mantissa is zero. By using
  3997. denormalized format, the range of a floating-point number can be extended at
  3998. the cost of precision. You cannot control whether a floating-point number is
  3999. represented in normalized or denormalized form; the floating-point package
  4000. determines the representation. The floating-point packages never use
  4001. denormalized form unless the exponent becomes less than the minimum that can
  4002. be represented in a normalized form.%@CR:C6A00040025 @%%@CR:C6A00040026 @%  %@NL@%
  4003. %@NL@%
  4004. Table 4.3 shows the minimum and maximum value you can store in variables of
  4005. each floating-point type. The values listed in this table apply only to
  4006. normalized floating-point numbers; denormalized floating-point numbers have
  4007. a smaller minimum value. Note that numbers retained in 80%@AI@%x%@AE@%87 registers are
  4008. always represented in 80-bit normal form; numbers can only be represented in
  4009. denormal form when stored in 32- or 64-bit floating-point variables (type
  4010. %@AB@%float%@AE@% and type %@AB@%long%@AE@%).%@CR:C6A00040027 @%%@CR:C6A00040028 @%  %@NL@%
  4011. %@NL@%
  4012. %@AB@%Table 4.3  %@AB@%Range of Floating-Point Types%@AE@%%@AE@%
  4013.  
  4014. %@TH:   6   527 02 14 31 31 @%Type          Minimum Value                  Maximum Value%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%float%@AE@%         1.175494351 E - 38             3.402823466 E + 38%@AB@%double%@AE@%        2.2250738585072014 E - 308     1.7976931348623158 E + 308%@AB@%long double%@AE@%   3.362103143112093503 E - 4932  1.189731495357231765 E + 4932%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   6   527 02 14 31 31 @%
  4015.  
  4016. If precision is less of a concern than storage, consider using type %@AB@%float%@AE@%
  4017. for floating-point variables. Conversely, if precision is the most important
  4018. criterion, use type %@AB@%long double%@AE@%.%@CR:C6A00040029 @%%@CR:C6A00040030 @%  %@NL@%
  4019. %@NL@%
  4020. %@AU@% Microsoft C observes type-widening rules.%@CR:C6A00040031 @%%@AE@%  %@NL@%
  4021. %@NL@%
  4022. Floating-point variables can be promoted to a type of greater significance
  4023. (for example, from type %@AB@%float%@AE@% to type %@AB@%double%@AE@%). Promotion often occurs when
  4024. you perform arithmetic on floating-point variables. This arithmetic is
  4025. always done in as high a degree of precision as the variable with the
  4026. highest degree of precision. For example, consider the following type
  4027. declarations:%@CR:C6A00040032 @%%@CR:C6A00040033 @%  %@NL@%
  4028. %@NL@%
  4029. %@AS@%  float f_short;
  4030. %@AS@%  double f_long;
  4031. %@AS@%  long double f_longer;
  4032. %@AS@%  
  4033. %@AS@%  f_short = f_short * f_long;%@AE@%%@NL@%
  4034. %@NL@%
  4035. In the preceding example, the variable %@AS@% f_short %@AE@% is promoted to type %@AB@%double%@AE@%
  4036. and multiplied by %@AS@% f_long%@AE@%; then the result is rounded to type %@AB@%float %@AE@%before
  4037. being assigned to %@AS@% f_short%@AE@%.  %@NL@%
  4038. %@NL@%
  4039. In the example below (which uses the declarations from the preceding
  4040. example), the arithmetic is done in %@AB@%float%@AE@% (32-bit) precision on the
  4041. variables; the result is then promoted to type %@AB@%long double%@AE@%.  %@NL@%
  4042. %@NL@%
  4043. %@AS@%  f_longer = f_short * f_short;%@AE@%%@NL@%
  4044. %@NL@%
  4045. %@NL@%
  4046. %@3@%%@CR:C6A00040034 @%%@AB@%4.1.2  Declaring Functions that Return Floating-Point Types%@CR:C6A00040035 @%%@AE@%%@EH@%%@NL@%
  4047. %@NL@%
  4048. You can declare functions that return the floating-point types %@AB@%float%@AE@%,
  4049. %@AB@%double%@AE@%, and %@AB@%long double%@AE@%. Functions that return types %@AB@%float%@AE@% or %@AB@%double%@AE@% do not
  4050. place their return values in registers; they place their return values in a
  4051. global location called the floating-point accumulator ( fac).  %@NL@%
  4052. %@NL@%
  4053. When declaring a function as a floating-point type in a multithreaded
  4054. program for OS/2, you should use the %@AB@%_pascal%@AE@% keyword to specify the
  4055. FORTRAN/Pascal calling convention. Declaring the function as %@AB@%_pascal%@AE@% causes
  4056. the return value to be placed on the stack, rather than in the
  4057. floating-point accumulator, %@AB@% fac%@AE@%.  %@NL@%
  4058. %@NL@%
  4059. %@AU@% You can write re-entrant functions that return floating-point types.%@AE@%  %@NL@%
  4060. %@NL@%
  4061. Using the current thread's private stack to return values allows you to
  4062. write re-entrant functions by eliminating possible contention between
  4063. threads for the floating-point accumulator.%@CR:C6A00040036 @%%@CR:C6A00040037 @%%@CR:C6A00040038 @%%@CR:C6A00040039 @%%@CR:C6A00040040 @%%@CR:C6A00040041 @%%@CR:C6A00040042 @%  %@NL@%
  4064. %@NL@%
  4065. ────────────────────────────────────────────────────────────────────────────%@NL@%
  4066. NOTE
  4067.  
  4068. %@AI@%Functions that return type %@AB@%long double%@AE@%%@AI@% always place their return values on
  4069. %@AI@%the stack. You need not use the %@AE@%%@AI@%%@AB@%_pascal%@AE@%%@AE@%%@AI@% keyword with functions declared as
  4070. %@AI@%%@AE@%%@AI@%%@AB@%long double%@AE@%%@AE@%%@AI@%.%@AE@%%@AE@%%@NL@%
  4071. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  4072. %@NL@%
  4073. %@NL@%
  4074. %@2@%%@CR:C6A00040043 @%%@AB@%4.2  C Run-Time Library Support of Type long double%@CR:C6A00040044 @%%@CR:C6A00040045 @%%@CR:C6A00040046 @%%@AE@%%@EH@%%@NL@%
  4075. %@NL@%
  4076. All of the Microsoft C run-time libraries support type %@AB@%long double%@AE@%. Each of
  4077. the normal floating-point math functions has a special version that supports
  4078. type %@AB@%long double%@AE@%. These functions have the same name as the functions that
  4079. support type %@AB@%float %@AE@%and type %@AB@%double%@AE@%, except that they end with %@AB@%l%@AE@%. For
  4080. example, the function that returns the absolute value of a variable of type
  4081. %@AB@%float %@AE@%or type %@AB@%double %@AE@%is %@AB@%fabs%@AE@%. The %@AB@%long double %@AE@%equivalent function is %@AB@%fabsl%@AE@%.
  4082. The two exceptions to this rule are the %@AB@%_atold%@AE@% and %@AB@%_strtodl%@AE@% functions.  %@NL@%
  4083. %@NL@%
  4084. %@NL@%
  4085. %@2@%%@CR:C6A00040047 @%%@AB@%4.3  Summary of Math Packages%@AE@%%@EH@%%@NL@%
  4086. %@NL@%
  4087. The Microsoft C compiler offers a choice of the following three math
  4088. packages for handling floating-point operations:%@CR:C6A00040048 @%  %@NL@%
  4089. %@NL@%
  4090. %@NL@%
  4091.   1.  Emulator (default)%@CR:C6A00040049 @%%@CR:C6A00040050 @%%@NL@%
  4092. %@NL@%
  4093.   2.  Math coprocessor (a library that supports the Intel 80%@AI@%x%@AE@%87 family of
  4094.       math coprocessors)%@CR:C6A00040051 @%%@CR:C6A00040052 @%%@NL@%
  4095. %@NL@%
  4096.   3.  Alternate math %@NL@%
  4097. %@NL@%
  4098. %@NL@%
  4099. When you install Microsoft C, the SETUP program allows you to build combined
  4100. libraries. These libraries include the floating-point math library that you
  4101. choose. Any programs linked with that library use the math package included
  4102. in the library; you must use the appropriate PWB or CL option to make sure
  4103. that the library you want is used at link time.%@CR:C6A00040053 @%  %@NL@%
  4104. %@NL@%
  4105. The following descriptions of these math packages are designed to help you
  4106. choose the appropriate math option for your needs when you build a library
  4107. using SETUP. For more information about SETUP and about building combined
  4108. libraries, see %@AI@%Installing and Using the Microsoft C Professional Development
  4109. %@AI@%System%@AE@%.%@CR:C6A00040054 @%  %@NL@%
  4110. %@NL@%
  4111. Note that this chapter does not describe mode-specific libraries. For
  4112. simplicity, the base names of libraries are noted in their default form;
  4113. that is %@AI@%m%@AE@%LIBC%@AI@%f%@AE@%.LIB, where %@AI@%m%@AE@% is the model designator and  %@AI@%f%@AE@% is the
  4114. floating-point math package designator. For information about mode-specific
  4115. libraries, see Chapter 14, "Building OS/2 Applications," or %@AI@%Installing and
  4116. %@AI@%Using the Microsoft C Professional Development System%@AE@%.  %@NL@%
  4117. %@NL@%
  4118. %@NL@%
  4119. %@3@%%@CR:C6A00040055 @%%@AB@%4.3.1  Emulator Package%@CR:C6A00040056 @%%@CR:C6A00040057 @%%@AE@%%@EH@%%@NL@%
  4120. %@NL@%
  4121. Programs created using the emulator math package automatically detect and
  4122. use an 80%@AI@%x%@AE@%87 numeric coprocessor if one is installed. If no coprocessor is
  4123. installed, these 80%@AI@%x%@AE@%87 instructions are carried out in software. The
  4124. emulator package is the default math package; SETUP uses it if you do not
  4125. explicitly choose another package. Also, the emulator math option is the
  4126. option selected by default by the compiler if no other floating-point math
  4127. option is specified.%@CR:C6A00040058 @%%@CR:C6A00040059 @%%@CR:C6A00040060 @%  %@NL@%
  4128. %@NL@%
  4129. Use the emulator math package to maximize accuracy on systems without math
  4130. coprocessors or if your program will be run on some systems with
  4131. coprocessors and some systems without coprocessors.%@CR:C6A00040061 @%  %@NL@%
  4132. %@NL@%
  4133. The emulator package performs basic operations to the same degree of
  4134. accuracy as a math coprocessor. However, the emulator routines used for
  4135. transcendental math functions (such as %@AB@%sin%@AE@%, %@AB@%cos%@AE@%, %@AB@%tan%@AE@%) differ slightly from
  4136. the corresponding functions performed on a coprocessor. This difference can
  4137. cause a slight discrepancy (usually within two bits) between the results of
  4138. these operations when performed with the software emulation instead of with
  4139. a math coprocessor.%@CR:C6A00040062 @%  %@NL@%
  4140. %@NL@%
  4141. %@AU@% When you use the emulator package, some floating-point exceptions are
  4142. %@AU@%masked.%@CR:C6A00040063 @%%@AE@%  %@NL@%
  4143. %@NL@%
  4144. When you use a math coprocessor or the emulator floating-point math package,
  4145. interrupt-enable, precision, underflow, and denormalized-operand exceptions
  4146. are masked by default. The remaining floating-point exceptions are unmasked.
  4147. See the discussion of the %@AB@%_control87%@AE@% function in on-line help for more
  4148. information about 80%@AI@%x%@AE@%87 floating-point exceptions.%@CR:C6A00040064 @%%@CR:C6A00040065 @%%@CR:C6A00040066 @%%@CR:C6A00040067 @%%@CR:C6A00040068 @%%@CR:C6A00040069 @%  %@NL@%
  4149. %@NL@%
  4150. %@NL@%
  4151. %@3@%%@CR:C6A00040070 @%%@AB@%4.3.2  Math Coprocessor Package%@CR:C6A00040071 @%%@CR:C6A00040072 @%%@AE@%%@EH@%%@NL@%
  4152. %@NL@%
  4153. The math coprocessor package utilizes the 80%@AI@%x%@AE@%87 math coprocessor exclusively
  4154. for floating-point calculations. If you use the math coprocessor package,
  4155. the machine on which your application is to run must have an 80%@AI@%x%@AE@%87
  4156. coprocessor to perform floating-point operations. This package gives you the
  4157. fastest, smallest programs possible for handling floating-point math.%@CR:C6A00040073 @%%@CR:C6A00040074 @%  %@NL@%
  4158. %@NL@%
  4159. %@NL@%
  4160. %@3@%%@CR:C6A00040075 @%%@AB@%4.3.3  Alternate Math Package%@CR:C6A00040076 @%%@CR:C6A00040077 @%%@CR:C6A00040078 @%%@CR:C6A00040079 @%%@AE@%%@EH@%%@NL@%
  4161. %@NL@%
  4162. The alternate math package gives you the smallest and fastest programs
  4163. possible without a coprocessor. However, the program results are not as
  4164. accurate as results given by the emulator package.  %@NL@%
  4165. %@NL@%
  4166. The alternate math package uses the same format as the IEEE standard-format
  4167. numbers with less precision and weaker error checking. The alternate math
  4168. package does not support infinities, NANs ("not a number"), and denormal
  4169. numbers.%@CR:C6A00040080 @%%@CR:C6A00040081 @%%@CR:C6A00040082 @%%@CR:C6A00040083 @%%@CR:C6A00040084 @%  %@NL@%
  4170. %@NL@%
  4171. You must always use the alternate math package when developing routines that
  4172. are to be placed in an OS/2 dynamic-link library (DLL) using LLIBCDLL.LIB.
  4173. Do not, however, use the alternate math package for building the C run-time
  4174. DLL using CDLLOBJS.LIB; instead, use the emulator math package. For more
  4175. information about creating dynamic-link libraries for OS/2, see Chapter 16.%@CR:C6A00040085 @%%@CR:C6A00040086 @%
  4176. %@NL@%
  4177. %@NL@%
  4178. %@NL@%
  4179. %@2@%%@CR:C6A00040087 @%%@AB@%4.4  Selecting Floating-Point Options (/FP)%@AE@%%@EH@%%@NL@%
  4180. %@NL@%
  4181. You can select a floating-point library and the method of accessing
  4182. floatingpoint routines by setting options in PWB or by specifying
  4183. command-line options to CL. You can choose between the emulator, alternate,
  4184. or math coprocessor library. You can also access the floating-point routines
  4185. by issuing a function call (or calls) or by generating in-line 80%@AI@%x%@AE@%87
  4186. instructions to execute the floating-point operation. The smallest and the
  4187. fastest floating-point math option is the in-line math coprocessor package
  4188. because the compiler generates true 80%@AI@%x%@AE@%87 coprocessor instructions. If,
  4189. however, you cannot depend on the target computer having a coprocessor, you
  4190. must use either the emulator or alternate math options.%@CR:C6A00040088 @%%@CR:C6A00040089 @%%@CR:C6A00040090 @%  %@NL@%
  4191. %@NL@%
  4192. To specify floating-point options on the CL command line, you must specify
  4193. an option from the list in Table 4.4. You specify these options to CL
  4194. starting with the floating-point option string /FP.  %@NL@%
  4195. %@NL@%
  4196. Based on the floating-point option and the memory-model option you choose,
  4197. the compiler embeds a library name in the object file that it creates. This
  4198. library is then considered the default library; that is, the linker searches
  4199. in the standard places for a library with that name. If it finds a library
  4200. with that name, the linker uses the library to resolve external references
  4201. in the object file being linked. Otherwise, it displays a message indicating
  4202. that it could not find the library.  %@NL@%
  4203. %@NL@%
  4204. This mechanism allows the linker to automatically link object files with the
  4205. appropriate library. However, you can link with a different library in some
  4206. cases. See Table 4.4 and Section 4.5, "Library Considerations for
  4207. Floating-Point Options," for more information about linking with different
  4208. libraries.  %@NL@%
  4209. %@NL@%
  4210. Table 4.4 summarizes the floating-point options and their effects. These
  4211. options are described in detail in the following sections.  %@NL@%
  4212. %@NL@%
  4213. %@AB@%Table 4.4  %@AB@%Summary of Floating-Point Options%@AE@%%@AE@%
  4214.  
  4215. %@TH:  51  3718 03 23 15 15 21 17 @%Option for CL for PWB  Combined Use                                       Libraries                        of Method      Effect         Coprocessor          Selected%@AB@%───────────────────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%/FPi                   In-line        Default;       Uses coprocessor if  %@AI@%m%@AE@%LIBCE.LIB%@AU@%(2)%@AE@%In-Line                               larger than    present%@AU@%(1)%@AE@%           Emulation                             /FPi87, but                                                               can work                                                                  without a                                                                 coprocessor;                                                              most                                                                      efficient way                                                             to get                                                                    maximum                                                                   precision                                                                 without a                                                                 coprocessor                         /FPi87                 In-line        Smallest and   Requires             %@AI@%m%@AE@%LIBC7.LIBIn-Line Math                          fastest        coprocessor          Coprocessor                           option                                                                    available                                                                 with a                                                                    coprocessor                         /FPc                   Calls          Slower than    Uses coprocessor if  %@AI@%m%@AE@%LIBCE.LIB%@AU@%(2,3)%@AE@%Calls to                              /FPi, but      present%@AU@%(1)%@AE@%           Emulator                              allows use of                                                             alternate                                                                 math library                                                              at link time                        /FPc87                 Calls          Slower than    Requires             %@AI@%m%@AE@%LIBC7.LIB%@AU@%(3,4)%@AE@%Calls to Math                         /FPi87, but    coprocessor unless   Coprocessor                           allows use of  library changed at                                         alternate      link time%@AU@%(5)%@AE@%                                               math library                                                              at link time                        /FPa                   Calls          Fastest and    Ignores              %@AI@%m%@AE@%LIBCA.LIB%@AU@%(2,4)%@AE@%Alternate Math                        smallest       coprocessor                                                option                                                                    available                                                                 without a                                                                 coprocessor,                                                              but                                                                       sacrifices                                                                some accuracy                                                             for speed                           %@AB@%───────────────────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  51  3718 03 23 15 15 21 17 @%
  4216.  
  4217. %@AU@%(1) %@AE@% Use of the coprocessor can be suppressed by setting NO87. 
  4218. %@AU@%(2) %@AE@% Can be linked explicitly with %@AI@%m%@AE@%LIBC7.LIB at link time. 
  4219. %@AU@%(3) %@AE@% Can be linked explicitly with %@AI@%m%@AE@%LIBCA.LIB at link time. 
  4220. %@AU@%(4) %@AE@% Can be linked explicitly with %@AI@%m%@AE@%LIBCE.LIB at link time. 
  4221. %@AU@%(5) %@AE@% Use of the coprocessor can be suppressed by setting NO87 if you change
  4222. to the emulator library at link time. %@NL@%
  4223. %@NL@%
  4224. %@NL@%
  4225. Optimizations such as constant propagation and constant subexpression
  4226. elimination can cause some expressions to be evaluated at compile time. Such
  4227. evaluations always use IEEE format and are unaffected by the floating-point
  4228. option you choose. For more information about optimizing, see Chapter 1,
  4229. "Optimizing C Programs."%@CR:C6A00040091 @%%@CR:C6A00040092 @%%@CR:C6A00040093 @%  %@NL@%
  4230. %@NL@%
  4231. %@AU@% You can specify floatingpoint options in the Programmer's WorkBench.%@AE@%  %@NL@%
  4232. %@NL@%
  4233. To specify floating-point options when using the Programmer's WorkBench, you
  4234. must modify the C Global Build Options (available on the Options menu). In
  4235. the C Global Build Options dialog box, select one of the following
  4236. floating-point math options:%@CR:C6A00040094 @%%@CR:C6A00040095 @%%@CR:C6A00040096 @%  %@NL@%
  4237. %@NL@%
  4238. %@AB@%Option%@AE@%                            %@AB@%Effect%@AE@%
  4239. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4240. Emulation Calls %@CR:C6A00040097 @%                  Generates calls; makes emulator math 
  4241.                                   library the
  4242.                                   default (/FPc)
  4243.  
  4244. 80%@AI@%x%@AE@%87 Calls %@CR:C6A00040098 @%                      Generates calls; makes math coprocessor 
  4245.                                   library the default (/FPc87)
  4246.  
  4247. Fast Alternate Math %@CR:C6A00040099 @%              Generates calls; makes alternate math 
  4248.                                   library the
  4249.                                   default (/FPa)
  4250.  
  4251. Inline Emulation %@CR:C6A00040100 @%                 Generates in-line instructions; makes 
  4252.                                   emulator math library the default 
  4253.                                   (/FPi); this is the default option
  4254.  
  4255. Inline 80x87                      Generates in-line instructions; selects 
  4256. Instructions %@CR:C6A00040101 @%                     math coprocessor library (/FPi87)
  4257.  
  4258. %@NL@%
  4259. %@3@%%@CR:C6A00040102 @%%@AB@%4.4.1  In-Line Emulator Option (/FPi)%@CR:C6A00040103 @%%@CR:C6A00040104 @%%@CR:C6A00040105 @%%@AE@%%@EH@%%@NL@%
  4260. %@NL@%
  4261. The in-line emulator option (/FPi) generates in-line instructions for an
  4262. 80%@AI@%x%@AE@%87 coprocessor and places the name of the emulator library (%@AI@%m%@AE@%LIBCE.LIB)
  4263. in the object file. At link time, you can specify the math coprocessor
  4264. library (%@AI@%m%@AE@%LIBC7.LIB) instead. If you do not choose a floating-point option,
  4265. the compiler uses the in-line emulator option by default.%@CR:C6A00040106 @%  %@NL@%
  4266. %@NL@%
  4267. The in-line emulator option is useful if you cannot be sure that an 80%@AI@%x%@AE@%87
  4268. coprocessor will be available on the target computer. Programs compiled
  4269. using the in-line emulator option work as described below:  %@NL@%
  4270. %@NL@%
  4271. %@NL@%
  4272.   ■   If a coprocessor is present at run time, the program uses the
  4273.       coprocessor.%@NL@%
  4274. %@NL@%
  4275.   ■   If no coprocessor is present, the program uses the emulator. In this
  4276.       case, the in-line emulator option offers the most efficient way to get
  4277.       maximum precision in floating-point results.%@NL@%
  4278. %@NL@%
  4279. %@NL@%
  4280. When you use the in-line emulator option, the compiler does not generate
  4281. in-line 80%@AI@%x%@AE@%87 instructions. For real-mode code, the compiler generates
  4282. software interrupts to library code, which then fixes up the interrupts to
  4283. use either the emulator or the coprocessor, depending on whether a
  4284. coprocessor is present. For protected-mode code, the compiler generates no
  4285. such interrupts; it generates 80%@AI@%x%@AE@%87 instructions. If the target computer
  4286. does not have a coprocessor, an "unsupported extension" exception occurs,
  4287. which is vectored to library code. If you want true in-line 80%@AI@%x%@AE@%87
  4288. instructions, use the in-line math coprocessor option (/FPi87).  %@NL@%
  4289. %@NL@%
  4290. ────────────────────────────────────────────────────────────────────────────%@NL@%
  4291. NOTE
  4292.  
  4293. %@AI@%In an OS/2 dynamic-link library built with LLIBCDLL.LIB, you cannot use code
  4294. %@AI@%that requires the emulator library. You must use the alternate math library
  4295. %@AI@%instead.%@CR:C6A00040107 @%%@AE@%%@NL@%
  4296. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  4297. %@NL@%
  4298. %@NL@%
  4299. %@3@%%@CR:C6A00040108 @%%@AB@%4.4.2  In-Line Math Coprocessor Instructions Option (/FPi87)%@CR:C6A00040109 @%%@CR:C6A00040110 @%%@CR:C6A00040111 @%%@AE@%%@EH@%%@NL@%
  4300. %@NL@%
  4301. The in-line math coprocessor instructions option (/FPi87) instructs the
  4302. compiler to place 80%@AI@%x%@AE@%87 coprocessor instructions in your code for many math
  4303. operations. It also causes the name of a math coprocessor library
  4304. (%@AI@%m%@AE@%LIBC7.LIB) to be embedded in the object file.%@CR:C6A00040112 @%  %@NL@%
  4305. %@NL@%
  4306. If you use the in-line math coprocessor instructions option and link with
  4307. the library %@AI@%m%@AE@%LIBC7.LIB, an 80%@AI@%x%@AE@%87 coprocessor must be present at run time, or
  4308. the program fails and the following error message is displayed:  %@NL@%
  4309. %@NL@%
  4310. %@AS@%  run-time error R6002
  4311. %@AS@%  - floating point not loaded%@AE@%%@NL@%
  4312. %@NL@%
  4313. Compiling with the in-line math coprocessor instructions option results in
  4314. the smallest, fastest programs possible for handling floating-point results.%@CR:C6A00040113 @%%@CR:C6A00040114 @%
  4315. %@NL@%
  4316. %@NL@%
  4317. %@NL@%
  4318. %@3@%%@CR:C6A00040115 @%%@AB@%4.4.3  Calls to Emulator Option (/FPc)%@CR:C6A00040116 @%%@CR:C6A00040117 @%%@AE@%%@EH@%%@NL@%
  4319. %@NL@%
  4320. The calls to emulator option (/FPc) generates floating-point calls to the
  4321. emulator library and places the names of an emulator library (%@AI@%m%@AE@%LIBCE.LIB) in
  4322. the object file. At link time, you can specify a math coprocessor library
  4323. (%@AI@%m%@AE@%LIBC7.LIB) or an alternate math library (%@AI@%m%@AE@%LIBCA.LIB) instead. Thus, the
  4324. calls to emulator option gives you more flexibility in the libraries you can
  4325. use for linking than the in-line emulator option.  %@NL@%
  4326. %@NL@%
  4327. Using the calls to emulator option is also recommended in the following
  4328. cases:  %@NL@%
  4329. %@NL@%
  4330. %@NL@%
  4331.   ■   If you compile modules that perform floating-point operations and plan
  4332.       to include these modules in a library%@CR:C6A00040118 @%%@NL@%
  4333. %@NL@%
  4334.   ■   If you compile modules that you want to link with libraries other than
  4335.       the libraries provided with Microsoft C%@CR:C6A00040119 @%%@NL@%
  4336. %@NL@%
  4337. %@NL@%
  4338. You cannot link with an alternate math library if your program uses the
  4339. intrinsic forms of floating-point library routines (that is, if you have
  4340. compiled the program with the /Oi or /Ox option, selected the Generate
  4341. Intrinsic Functions option from the Debug Build Options or Release Build
  4342. Options dialog box in the Programmer's WorkBench, or specified math
  4343. functions in an %@AB@%intrinsic%@AE@% pragma).  %@NL@%
  4344. %@NL@%
  4345. %@NL@%
  4346. %@3@%%@CR:C6A00040120 @%%@AB@%4.4.4  Calls to Math Coprocessor Option (/FPc87)%@CR:C6A00040121 @%%@CR:C6A00040122 @%%@AE@%%@EH@%%@NL@%
  4347. %@NL@%
  4348. The calls to math coprocessor option (/FPc87) generates function calls to
  4349. routines in the math coprocessor library (%@AI@%m%@AE@%LIBC7.LIB) that issue the
  4350. corresponding 80%@AI@%x%@AE@%87 instructions. As with the in-line math coprocessor
  4351. instructions option (/FPi87), at link time you can choose to link with an
  4352. emulator library (%@AI@%m%@AE@%LIBCE.LIB). However, /FPc offers more flexibility in
  4353. choosing libraries, since you can change your mind and link with the
  4354. appropriate alternate math library as well (%@AI@%m%@AE@%LIBCA.LIB).  %@NL@%
  4355. %@NL@%
  4356. The disadvantages of using the calls to math coprocessor option as opposed
  4357. to the in-line coprocessor option are the following:  %@NL@%
  4358. %@NL@%
  4359. %@NL@%
  4360.   ■   Your executable size is larger because a call requires more
  4361.       instructions than a true coprocessor instruction.%@CR:C6A00040123 @%%@NL@%
  4362. %@NL@%
  4363.   ■   Your program does not execute as fast because you must issue a
  4364.       function call for each floating-point operation.%@CR:C6A00040124 @%%@NL@%
  4365. %@NL@%
  4366. %@NL@%
  4367. You cannot link with an alternate math library if your program uses the
  4368. intrinsic forms of floating-point library routines (that is, if you have
  4369. compiled the program with the /Oi or /Ox option, selected the Generate
  4370. Intrinsic Functions option from the Debug Build Options or Release Build
  4371. Options dialog box in the Programmer's WorkBench, or specified math
  4372. functions in an %@AB@%intrinsic%@AE@% pragma).  %@NL@%
  4373. %@NL@%
  4374. You must have a math coprocessor installed to run programs compiled with the
  4375. /FPc option and linked with a math coprocessor library. Otherwise, the
  4376. program fails and the following error message is displayed:  %@NL@%
  4377. %@NL@%
  4378. %@AS@%  run-time error R6002
  4379. %@AS@%  - floating point not loaded%@AE@%%@NL@%
  4380. %@NL@%
  4381. ────────────────────────────────────────────────────────────────────────────%@NL@%
  4382. NOTE
  4383.  
  4384. %@AI@%Certain optimizations are not performed when you use the calls to math
  4385. %@AI@%coprocessor option. This can reduce the efficiency of your code; also, since
  4386. %@AI@%arithmetic of different precision can result, there may be slight
  4387. %@AI@%differences in your results.%@CR:C6A00040125 @%%@AE@%%@NL@%
  4388. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  4389. %@NL@%
  4390. %@NL@%
  4391. %@3@%%@CR:C6A00040126 @%%@AB@%4.4.5  Use Alternate Math Option (/FPa)%@CR:C6A00040127 @%%@CR:C6A00040128 @%%@CR:C6A00040129 @%%@AE@%%@EH@%%@NL@%
  4392. %@NL@%
  4393. The use alternate math option (/FPa) generates floating-point calls and
  4394. selects the alternate math library for the appropriate memory model
  4395. (%@AI@%m%@AE@%LIBCA.LIB). Calls to this library provide the fastest and smallest option
  4396. for code intended to run on a machine without an 80%@AI@%x%@AE@%87 coprocessor. With
  4397. this option, you can choose an emulator library (%@AI@%m%@AE@%LIBCE.LIB) or a math
  4398. coprocessor library (%@AI@%m%@AE@%LIBC7.LIB) at link time.%@CR:C6A00040130 @%%@CR:C6A00040131 @%  %@NL@%
  4399. %@NL@%
  4400. You cannot link with an alternate math library if your program uses the
  4401. intrinsic forms of floating-point library routines (that is, if you have
  4402. compiled the program with the /Oi or /Ox option, selected the Generate
  4403. Intrinsic Functions from the Debug Build Options or Release Build Options
  4404. dialog box in the Programmer's WorkBench, or specified math functions in an
  4405. %@AB@%intrinsic%@AE@% pragma).  %@NL@%
  4406. %@NL@%
  4407. %@NL@%
  4408. %@2@%%@CR:C6A00040132 @%%@AB@%4.5  Library Considerations for Floating-Point Options%@CR:C6A00040133 @%%@AE@%%@EH@%%@NL@%
  4409. %@NL@%
  4410. You may want to use libraries in addition to the default library for the
  4411. floating-point option you have chosen in your compile options. For example,
  4412. you may want to create your own libraries (or other collections of
  4413. subprograms in object-file form), then link these libraries at a later time
  4414. with object files that you have compiled using different options.  %@NL@%
  4415. %@NL@%
  4416. The following sections describe these cases and ways to handle them.
  4417. Although the discussion assumes that you are putting your object files into
  4418. libraries, the same considerations apply if you are simply using individual
  4419. object files.  %@NL@%
  4420. %@NL@%
  4421. %@NL@%
  4422. %@3@%%@CR:C6A00040134 @%%@AB@%4.5.1  Using One Standard Library for Linking%@AE@%%@EH@%%@NL@%
  4423. %@NL@%
  4424. You must use only one standard C run-time library when you link. You can
  4425. control which library is used in one of two ways:  %@NL@%
  4426. %@NL@%
  4427. %@NL@%
  4428.   1.  In the Programmer's WorkBench, add the name of the C run-time library
  4429.       file you want to the program list using the Edit Program List option
  4430.       from the Make menu. You must also modify the Linker Options (from the
  4431.       Make menu) by specifying No Default Library Search.%@NL@%
  4432. %@NL@%
  4433.   2.  From the LINK command line, give the /NODEFAULTLIBRARYSEARCH (/NOD)
  4434.       option and then specify the name of the combined library file you want
  4435.       to use in the %@AI@%link-libinfo%@AE@% field of the CL command line. This
  4436.       overrides the library names embedded in the object files.%@NL@%
  4437. %@NL@%
  4438. %@NL@%
  4439. %@NL@%
  4440. %@3@%%@CR:C6A00040135 @%%@AB@%4.5.2  In-Line Instructions or Calls%@CR:C6A00040136 @%%@CR:C6A00040137 @%%@AE@%%@EH@%%@NL@%
  4441. %@NL@%
  4442. When deciding on a floating-point option, you should decide whether you want
  4443. to use in-line instructions. If you do, compile with the in-line math
  4444. coprocessor instructions (/FPi87) or in-line emulator (/FPi) option.
  4445. Otherwise, compile for floating-point function calls using the calls to math
  4446. coprocessor (/FPc87), calls to emulator (/FPc), or alternate math (/FPa)
  4447. option.  %@NL@%
  4448. %@NL@%
  4449. If you choose to use in-line instructions for your precompiled object files,
  4450. you cannot link with an alternate math library (%@AI@%m%@AE@%LIBCA.LIB). However,
  4451. in-line instructions achieve the best performance from your programs on
  4452. machines that have an 80%@AI@%x%@AE@%87 coprocessor installed.%@CR:C6A00040138 @%  %@NL@%
  4453. %@NL@%
  4454. If you choose to use calls, your programs are slower, but at link time you
  4455. can switch to any standard C run-time library (that is, any library created
  4456. by the SETUP program) that supports the memory model you have chosen.  %@NL@%
  4457. %@NL@%
  4458. %@NL@%
  4459. %@2@%%@CR:C6A00040139 @%%@AB@%4.6  Compatibility between Floating-Point Options%@CR:C6A00040140 @%%@AE@%%@EH@%%@NL@%
  4460. %@NL@%
  4461. Each time you compile a source file, you can specify a floating-point
  4462. option. When you link two or more source files to produce an executable
  4463. program file, you must ensure that floating-point operations are handled
  4464. consistently and that the environment is set up properly to allow the linker
  4465. to find the required library.  %@NL@%
  4466. %@NL@%
  4467. If you are building libraries of C routines that contain floating-point
  4468. operations, the calls to emulator option (/FPc) provides the most
  4469. flexibility.%@CR:C6A00040141 @%%@CR:C6A00040142 @%  %@NL@%
  4470. %@NL@%
  4471. The examples that follow illustrate how you can link your program with a
  4472. library other than the default. The floating-point option and the substitute
  4473. library are compatible.  %@NL@%
  4474. %@NL@%
  4475. The example below compiles the program %@AS@% CALC.C %@AE@% with the medium-model
  4476. option (/AM). Because no floating-point option is specified, the default
  4477. in-line emulator option (/FPi) is used. The in-line emulator option
  4478. generates 80%@AI@%x%@AE@%87 instructions and specifies the emulator library MLIBCE.LIB
  4479. in the object file. The /LINK field specifies the /NODEFAULTLIBRARYSEARCH
  4480. (/NOD) option and the names of the medium-model math coprocessor library.
  4481. Specifying the math coprocessor library forces the program to use an 80%@AI@%x%@AE@%87
  4482. coprocessor; the program fails if a coprocessor is not present.  %@NL@%
  4483. %@NL@%
  4484. %@AS@%  CL /AM CALC.C /link MLIBC7 /NOD%@AE@%%@NL@%
  4485. %@NL@%
  4486. The example below compiles %@AS@% CALC.C %@AE@% using the small (default) memory model
  4487. and the alternate math option (/FPa). The /LINK field specifies the /NOD
  4488. option and the library SLIBCE.LIB. Specifying the emulator library causes
  4489. all floating-point calls to refer to the emulator library instead of the
  4490. alternate math library.  %@NL@%
  4491. %@NL@%
  4492. %@AS@%  CL /FPa CALC.C /link SLIBCE /NOD%@AE@%%@NL@%
  4493. %@NL@%
  4494. The example below compiles %@AS@% CALC.C %@AE@% with the calls to math coprocessor
  4495. option (/FPc87), which places the library name SLIBC7.LIB in the object
  4496. file. The /LINK field overrides this default-library specification by giving
  4497. the /NOD option and the name of the small-model alternate math library
  4498. (SLIBCA.LIB).  %@NL@%
  4499. %@NL@%
  4500. %@AS@%  CL /FPc87 CALC.C /link SLIBCA.LIB/NOD%@AE@%%@NL@%
  4501. %@NL@%
  4502. %@NL@%
  4503. %@2@%%@CR:C6A00040143 @%%@AB@%4.7  Using the NO87 Environment Variable%@CR:C6A00040144 @%%@CR:C6A00040145 @%%@AE@%%@EH@%%@NL@%
  4504. %@NL@%
  4505. Programs compiled using either the calls to emulator (/FPc) or the in-line
  4506. emulator (/FPi) option automatically use an 80%@AI@%x%@AE@%87 coprocessor at run time if
  4507. one is installed. You can override this and force the use of the software
  4508. emulator by setting an environment variable named NO87.%@CR:C6A00040146 @%%@CR:C6A00040147 @%%@CR:C6A00040148 @%%@CR:C6A00040149 @%%@CR:C6A00040150 @%%@CR:C6A00040151 @%  %@NL@%
  4509. %@NL@%
  4510. %@AU@% Use the NO87 environment variable to suppress use of the 80x87 coprocessor
  4511. %@AU@%at run time.%@AE@%  %@NL@%
  4512. %@NL@%
  4513. If NO87 is set to any value when the program is executed, use of the
  4514. coprocessor is suppressed. The value of the NO87 setting is printed on the
  4515. standard output as a message. The message is printed only if a coprocessor
  4516. is present and suppressed; if no coprocessor is present, no message appears.
  4517. If you don't want a message to be printed, set NO87 equal to one or more
  4518. spaces. A blank string for NO87 causes a blank line to be printed.  %@NL@%
  4519. %@NL@%
  4520. Note that only the presence or absence of the NO87 definition is important
  4521. in suppressing use of the coprocessor. The actual value of the NO87 setting
  4522. is used only for printing the message.  %@NL@%
  4523. %@NL@%
  4524. The NO87 variable takes effect with any program linked with an emulator
  4525. library (%@AI@%m%@AE@%LIBCE.LIB). It has no effect on programs linked with math
  4526. coprocessor libraries (%@AI@%m%@AE@%LIBC7.LIB) or programs linked with alternate math
  4527. libraries (%@AI@%m%@AE@%LIBCA.LIB).  %@NL@%
  4528. %@NL@%
  4529. When a program that uses an emulator library is executed and an 80%@AI@%x%@AE@%87
  4530. coprocessor is present, the example below causes the message %@AS@% Use of
  4531. %@AS@%coprocessor suppressed %@AE@% to appear.  %@NL@%
  4532. %@NL@%
  4533. %@AS@%  SET NO87=Use of coprocessor suppressed%@AE@%%@NL@%
  4534. %@NL@%
  4535. The syntax below sets the NO87 variable to the space character. Use of the
  4536. coprocessor is still suppressed, but no message is displayed.  %@NL@%
  4537. %@NL@%
  4538. %@AS@%  SET NO87=space%@AE@%%@NL@%
  4539. %@NL@%
  4540. %@NL@%
  4541. %@2@%%@CR:C6A00040152 @%%@AB@%4.8  Incompatibility Issues%@CR:C6A00040153 @%%@AE@%%@EH@%%@NL@%
  4542. %@NL@%
  4543. The exception handler in the libraries for 80%@AI@%x%@AE@%87 floating-point calculations
  4544. (%@AI@%m%@AE@%LIBCE.LIB and %@AI@%m%@AE@%LIBC7.LIB) is designed to work without modification on the
  4545. IBM PC family of computers and on closely compatible computers, including
  4546. the WANG(R) PC, the AT&T(R) 6300, and the Olivetti(R) personal computers.
  4547. Also, the libraries need not be modified for the Texas Instruments(R)
  4548. Professional Computer, even though it is not compatible. Any machine that
  4549. uses nonmaskable interrupts (NMI) for 80%@AI@%x%@AE@%87 exceptions will run with the
  4550. unmodified libraries. If your computer is not one of these, and if you are
  4551. not sure whether it is completely compatible, you may need to modify the
  4552. math coprocessor libraries.%@CR:C6A00040154 @%  %@NL@%
  4553. %@NL@%
  4554. All Microsoft languages that support 80%@AI@%x%@AE@%87 coprocessors intercept 80%@AI@%x%@AE@%87
  4555. exceptions in order to produce accurate results and properly detect error
  4556. conditions. To make the libraries work correctly on incompatible machines,
  4557. you can modify the libraries. To make this easier, an assembly-language
  4558. source file, EMOEM.ASM, is included on the C 6.0 distribution disk. Any
  4559. machine that sends the 80%@AI@%x%@AE@%87 exception to an 8259 Priority Interrupt
  4560. Controller (master or master/slave) can be supported by a simple table
  4561. change to the EMOEM.ASM module. The source file contains further
  4562. instructions about how to modify EMOEM.ASM, patch libraries, and executable
  4563. files.%@CR:C6A00040155 @%  %@NL@%
  4564. %@NL@%
  4565. %@NL@%
  4566. %@NL@%
  4567. %@NL@%
  4568. %@NL@%
  4569. %@NL@%
  4570. %@CR:C6A-Part 02 @%%@1@%%@AB@%PART II  Improving Programmer Productivity%@AE@%%@EH@%%@NL@%
  4571. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4572. %@NL@%
  4573.  The Microsoft C Professional Development System helps you write and debug
  4574. software rapidly.  %@NL@%
  4575. %@NL@%
  4576. Chapter 5 describes the quick compile and incremental compile options, both
  4577. of which can save you time when compiling programs. Chapter 5 also describes
  4578. the incremental linker, ILINK, which can save you time when you link your
  4579. application. Chapter 6 describes NMAKE, a powerful new program maintenance
  4580. utility that automates your program build process. Chapter 7 describes how
  4581. to build help files with HELPMAKE, the help-file maintenance utility. When
  4582. you need to share documentation in a readily accessible form, you can add it
  4583. to the Microsoft Advisor on-line help system using the information in
  4584. Chapter 7. Chapter 8 explains how to customize the Programmer's WorkBench to
  4585. make it a personalized development platform. Chapter 9 offers procedures
  4586. (and some tips) for using the CodeView debugger to find errors in your
  4587. programs.  %@NL@%
  4588. %@NL@%
  4589. %@NL@%
  4590. %@NL@%
  4591. %@NL@%
  4592. %@NL@%
  4593. %@NL@%
  4594. %@CR:C6A00050001 @%%@1@%%@AB@%Chapter 5  Compiling and Linking Quickly%@AE@%%@EH@%%@NL@%
  4595. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4596. %@NL@%
  4597. The fundamental processes of compiling and linking take time to perform. The
  4598. larger your application grows, the longer it takes to compile and link.  %@NL@%
  4599. %@NL@%
  4600. This chapter describes how you can speed up compiling by using the quick
  4601. compiler and incremental compile option, and how you can speed up linking by
  4602. using ILINK, the Incremental Linker.  %@NL@%
  4603. %@NL@%
  4604. %@NL@%
  4605. %@2@%%@CR:C6A00050002 @%%@AB@%5.1  Compiling Quickly%@AE@%%@EH@%%@NL@%
  4606. %@NL@%
  4607. This section describes two ways to speed up the compiling process: using the
  4608. quick compiler and using the incremental compile option.  %@NL@%
  4609. %@NL@%
  4610. %@NL@%
  4611. %@3@%%@CR:C6A00050003 @%%@AB@%5.1.1  Quick Compiler%@AE@%%@EH@%%@NL@%
  4612. %@NL@%
  4613. The Microsoft C Professional Development System includes two separate C
  4614. compilers: the full compiler and the quick compiler. If you don't specify
  4615. otherwise, your program is compiled by the full compiler.  %@NL@%
  4616. %@NL@%
  4617. You access the quick compiler by specifying the /qc command-line option for
  4618. CL or by selecting the Quick Compile option from the C Release Build or C
  4619. Debug Build Options dialogs in the PWB Options menu.  %@NL@%
  4620. %@NL@%
  4621. The quick compiler cannot perform as many optimizations as the full
  4622. compiler, but it is much faster. You can use it to save time during
  4623. development, whenever optimizations are not critical. When your application
  4624. is finished, you can compile with the full compiler, using all the desired
  4625. optimizations.  %@NL@%
  4626. %@NL@%
  4627. On-line help for the /qc option describes which optimizations the quick
  4628. compiler can perform.  %@NL@%
  4629. %@NL@%
  4630. %@NL@%
  4631. %@3@%%@CR:C6A00050004 @%%@AB@%5.1.2  Incremental Compile Option%@AE@%%@EH@%%@NL@%
  4632. %@NL@%
  4633. You can speed up compiling even more by compiling incrementally. Incremental
  4634. compilation means that the compiler compiles only those functions that have
  4635. changed since you last compiled.  %@NL@%
  4636. %@NL@%
  4637. The incremental compile option is available only with the quick compiler
  4638. (see the previous section). You can access it from within PWB or from the
  4639. DOS command line. Within PWB, select the Incremental Compile option in the C
  4640. Release Build dialog box or in the C Debug Build Options dialog box. From
  4641. the DOS command line, specify the /Gi option for CL.  %@NL@%
  4642. %@NL@%
  4643. The incremental compile option automatically triggers another time-saving
  4644. feature: the Incremental Linker, which is described in the next section.  %@NL@%
  4645. %@NL@%
  4646. %@NL@%
  4647. %@2@%%@CR:C6A00050005 @%%@AB@%5.2  Linking Quickly with ILINK%@AE@%%@EH@%%@NL@%
  4648. %@NL@%
  4649. %@AU@% ILINK links only those modules that have changed since the last link.%@AE@%  %@NL@%
  4650. %@NL@%
  4651. The Incremental Linker (ILINK) offers the same advantage in linking that the
  4652. incremental compile option offers in compiling. Rather than link every
  4653. module in an application, as LINK does, ILINK links only those modules that
  4654. have changed since the last link. The more modules your application
  4655. contains, the more time ILINK can potentially save.  %@NL@%
  4656. %@NL@%
  4657. In a normal development scenario, you use LINK at the beginning and end of
  4658. the process, and use ILINK in the middle. In the early stages of
  4659. development, when your application contains only a few modules, ILINK offers
  4660. no speed advantage over LINK. Once your application contains several
  4661. modules, you can save time by using ILINK.  %@NL@%
  4662. %@NL@%
  4663. %@AU@% You must link once with LINK to prepare for incremental linking.%@AE@%  %@NL@%
  4664. %@NL@%
  4665. To prepare for incremental linking, you must run LINK using /INCREMENTAL, as
  4666. described in Section 5.2.1. At the same time, you have the option of adding
  4667. padding bytes to code or data segments by specifying the /PADCODE and
  4668. /PADDATA options. Padding allows ILINK to expand a segment without relinking
  4669. the entire module in which it is contained.  %@NL@%
  4670. %@NL@%
  4671. Now you can link with ILINK during the rest of development. If changes in
  4672. your code require a full link, ILINK invokes LINK automatically. When the
  4673. application is finished, you link a last time with LINK to produce the final
  4674. executable file.  %@NL@%
  4675. %@NL@%
  4676. You can use ILINK with programs compiled for any memory model except tiny
  4677. model. (Memory models are described in Chapter 2, "Managing Memory.")
  4678. Typically, ILINK is not efficient for small- or compact-model programs
  4679. unless they were compiled with the incremental compile option, which is
  4680. described in Section 5.1.2.  %@NL@%
  4681. %@NL@%
  4682. %@NL@%
  4683. %@3@%%@CR:C6A00050006 @%%@AB@%5.2.1  Preparing for Incremental Linking%@AE@%%@EH@%%@NL@%
  4684. %@NL@%
  4685. There are three LINK options that relate to the use of ILINK. One of them
  4686. (/INCREMENTAL) is mandatory; the other two (/PADCODE and /PADDATA) are
  4687. optional. This section explains the LINK options that prepare for ILINK. See
  4688. on-line help for a complete list of LINK options.  %@NL@%
  4689. %@NL@%
  4690. %@NL@%
  4691. %@4@%%@AB@%The /INCREMENTAL Option%@AE@%%@EH@%%@NL@%
  4692. %@NL@%
  4693. The /INCREMENTAL (/INC) option prepares an object file for incremental
  4694. linking. You must always run LINK using this option before using ILINK. When
  4695. you specify /INC, the linker produces two extra files: a symbol file (.SYM)
  4696. and an ILINK support file (.ILK). The .SYM and .ILK files tell ILINK which
  4697. parts of the executable file need to be updated.  %@NL@%
  4698. %@NL@%
  4699. You must use /INCREMENTAL whenever you use the /PADCODE and /PADDATA
  4700. options, which are described below.  %@NL@%
  4701. %@NL@%
  4702. %@NL@%
  4703. %@4@%%@AB@%The /PADCODE Option%@AE@%%@EH@%%@NL@%
  4704. %@NL@%
  4705. The /PADCODE option causes LINK to add padding bytes at the end of a
  4706. module's code segment. The padding bytes leave room for the code segment to
  4707. grow in subsequent links, allowing ILINK to update only that module. You can
  4708. use the /PADCODE option only when /INC is also specified.  %@NL@%
  4709. %@NL@%
  4710. Code padding is usually necessary for programs using the small memory model.
  4711. It is also recommended for compact- or mixed-model programs. You do not need
  4712. to specify /PADCODE for other memory models (medium, large, or huge).%@CR:C6A00050007 @%%@CR:C6A00050008 @%  %@NL@%
  4713. %@NL@%
  4714. If you don't specify /PADCODE, LINK doesn't pad the code segment at all. To
  4715. add padding, specify the desired number of bytes. The optimum amount of
  4716. padding depends on how much your code changes from one link to the next. If
  4717. you expect to add only a little code, choose a relatively%@CR:C6A00050009 @% small amount of
  4718. padding, say 32 to 64 bytes. If ILINK issues the message  %@NL@%
  4719. %@NL@%
  4720. %@AS@%  padding exceeded%@AE@%%@NL@%
  4721. %@NL@%
  4722. and performs a full link more often than desired, increase the padding by a
  4723. small amount, say 32 bytes. In any case, remember that the total size of a
  4724. code segment, including padding bytes, cannot exceed 64K (65,535) bytes.  %@NL@%
  4725. %@NL@%
  4726. %@NL@%
  4727. %@4@%%@AB@%The /PADDATA Option%@AE@%%@EH@%%@NL@%
  4728. %@NL@%
  4729. Like /PADCODE, the /PADDATA option causes LINK to add padding bytes that
  4730. leave room for the segment to grow in subsequent links. However, the
  4731. /PADDATA option pads the end of the data segment rather than the code
  4732. segment. You can use /PADDATA only when /INC is also specified.  %@NL@%
  4733. %@NL@%
  4734. If you don't specify /PADDATA, LINK adds 16 bytes of padding by default. The
  4735. default padding amount should suffice in many cases, since public variables
  4736. are added less frequently than code. If you need more padding, specify the
  4737. desired number of bytes. Remember that the total size of a data segment,
  4738. including padding bytes, cannot exceed 64K (65,535) bytes.  %@NL@%
  4739. %@NL@%
  4740. %@NL@%
  4741. %@3@%%@CR:C6A00050010 @%%@AB@%5.2.2  Incremental Violations%@AE@%%@EH@%%@NL@%
  4742. %@NL@%
  4743. ILINK can generate two kinds of errors: real errors and incremental
  4744. violations. Real errors are errors such as undefined symbols that cannot be
  4745. resolved by a full link. If ILINK detects a real error, it displays an error
  4746. message (real errors are documented in on-line help).  %@NL@%
  4747. %@NL@%
  4748. Incremental violations are caused by code changes you have made that go
  4749. beyond the scope of incremental linking. When an incremental violation
  4750. occurs, ILINK invokes LINK automatically. The following sections describe
  4751. the incremental violations.  %@NL@%
  4752. %@NL@%
  4753. %@NL@%
  4754. %@4@%%@AB@%Changing Libraries%@AE@%%@EH@%%@NL@%
  4755. %@NL@%
  4756. An incremental violation occurs when a library changes. Furthermore, if an
  4757. altered module shares a code segment with a library, ILINK needs access to
  4758. the library as well as to the altered module.  %@NL@%
  4759. %@NL@%
  4760. If you add a function, procedure, or subroutine call to a library that has
  4761. never been called before, ILINK invokes LINK automatically.  %@NL@%
  4762. %@NL@%
  4763. %@NL@%
  4764. %@4@%%@AB@%Exceeding Code/Data Padding%@AE@%%@EH@%%@NL@%
  4765. %@NL@%
  4766. An incremental violation occurs if two or more modules contribute to the
  4767. same physical segment and either module exceeds its padding. The padding
  4768. allows the module to increase the specified number of bytes before another
  4769. full link is required.  %@NL@%
  4770. %@NL@%
  4771. %@NL@%
  4772. %@4@%%@AB@%Moving or Deleting Data Symbols%@AE@%%@EH@%%@NL@%
  4773. %@NL@%
  4774. An incremental violation occurs if a data symbol is moved or deleted. To add
  4775. new data symbols without requiring a full link, add the new symbols at the
  4776. end of all other data symbols in the module.  %@NL@%
  4777. %@NL@%
  4778. %@NL@%
  4779. %@4@%%@AB@%Deleting Code Symbols%@AE@%%@EH@%%@NL@%
  4780. %@NL@%
  4781. You can move or add code symbols, but an incremental violation occurs if you
  4782. delete any code symbols from a module. Code symbols can be moved within a
  4783. module but cannot be moved between modules.  %@NL@%
  4784. %@NL@%
  4785. %@NL@%
  4786. %@4@%%@AB@%Changing Segment Definitions%@AE@%%@EH@%%@NL@%
  4787. %@NL@%
  4788. An incremental violation results if you add, delete, or change the order of
  4789. segment definitions.  %@NL@%
  4790. %@NL@%
  4791. %@NL@%
  4792. %@4@%%@AB@%Adding CodeView(R) Debugger Information%@AE@%%@EH@%%@NL@%
  4793. %@NL@%
  4794. If you include CodeView debugger information for a module when you fully
  4795. link (by compiling and linking with CodeView debugger support), ILINK
  4796. supports CodeView debugger information for the module. ILINK maintains
  4797. symbolic information for current symbols, and it adds information for any
  4798. new symbols. However, if you try to add CodeView debugger information for a
  4799. module that did not previously have CodeView debugger support, an
  4800. incremental violation occurs. See Chapter 9, "Debugging C Programs with
  4801. CodeView," for more information about CodeView.  %@NL@%
  4802. %@NL@%
  4803. %@NL@%
  4804. %@NL@%
  4805. %@NL@%
  4806. %@NL@%
  4807. %@NL@%
  4808. %@CR:C6A00060001 @%%@1@%%@AB@%Chapter 6  Managing Development Projects with NMAKE%@AE@%%@EH@%%@NL@%
  4809. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4810. %@NL@%
  4811. The Microsoft Program-Maintenance Utility (NMAKE) is a sophisticated command
  4812. processor that can save time and simplify project management. By determining
  4813. which project files depend on others, NMAKE can automatically execute the
  4814. commands needed to update your project when any project file has changed.  %@NL@%
  4815. %@NL@%
  4816. The advantage of using NMAKE over simple batch files is that NMAKE does only
  4817. what is needed. You don't waste time rebuilding files that are already
  4818. up-to-date. NMAKE also has advanced features, such as macros, that help you
  4819. manage complex projects.  %@NL@%
  4820. %@NL@%
  4821. This chapter provides complete documentation for NMAKE. Information about
  4822. NMAKE is also available in on-line help. If you are familiar with MAKE, the
  4823. predecessor of NMAKE, be sure to read Section 6.9, "Differences Between
  4824. NMAKE and MAKE." There are some important differences between the two
  4825. utilities.  %@NL@%
  4826. %@NL@%
  4827. %@NL@%
  4828. %@2@%%@CR:C6A00060002 @%%@AB@%6.1  Overview of NMAKE%@AE@%%@EH@%%@NL@%
  4829. %@NL@%
  4830. NMAKE works by comparing the times and dates of two sets of files, which are
  4831. called "targets" and "dependents." A target is normally a file that you want
  4832. to create, such as an executable file. A dependent is a file used to create
  4833. a target, such as a C source file.  %@NL@%
  4834. %@NL@%
  4835. When you run NMAKE, it reads a "description file" that you supply. The
  4836. description file consists of one or more blocks. Each block typically lists
  4837. a target, the target's dependents, and the command that builds the target.
  4838. NMAKE compares the date and time of the target to those of its dependents.
  4839. If any dependent has changed more recently than the target, NMAKE updates
  4840. the target by executing the command listed in the block.  %@NL@%
  4841. %@NL@%
  4842. NMAKE's main purpose is to help you update applications quickly and simply.
  4843. However, it can execute any command, so it is not limited to compiling and
  4844. linking. NMAKE can also make backups, move files, and do many other project
  4845. management tasks.  %@NL@%
  4846. %@NL@%
  4847. %@NL@%
  4848. %@2@%%@CR:C6A00060003 @%%@AB@%6.2  The NMAKE Command%@AE@%%@EH@%%@NL@%
  4849. %@NL@%
  4850. When you run NMAKE, you can supply the description-file name and other
  4851. arguments using the following syntax:  %@NL@%
  4852. %@NL@%
  4853. %@AB@%NMAKE%@AE@% «%@AI@%options%@AE@%» «%@AI@%macros%@AE@%» «%@AI@%targets%@AE@%» «%@AI@%descriptfile%@AE@%»  %@NL@%
  4854. %@NL@%
  4855. All of the command-line fields are optional. If you don't supply any
  4856. arguments, NMAKE looks for a default description file named MAKEFILE and
  4857. follows various other defaults that are described in this chapter.  %@NL@%
  4858. %@NL@%
  4859. The %@AI@%options%@AE@% field lists NMAKE options, which are described in Section 6.4,
  4860. "Command-Line Options."  %@NL@%
  4861. %@NL@%
  4862. The %@AI@%macros%@AE@% field lists macro definitions, which allow you to replace text in
  4863. the description file. Macros are described in Section 6.3.3.  %@NL@%
  4864. %@NL@%
  4865. The %@AI@%targets%@AE@% field lists targets to build. If you do not list any targets,
  4866. NMAKE builds only the first target in the description file. (This is a
  4867. significant departure from the behavior of MAKE, NMAKE's predecessor. See
  4868. Section 6.9, "Differences between NMAKE and MAKE.")  %@NL@%
  4869. %@NL@%
  4870. The %@AI@%descriptfile%@AE@% field specifies a description file. If this field is
  4871. absent, NMAKE automatically looks for a file named MAKEFILE in the current
  4872. directory. You can also specify the description file with the /F option (for
  4873. information, see Section 6.4, "Command-Line Options").  %@NL@%
  4874. %@NL@%
  4875. Below is a typical NMAKE command:  %@NL@%
  4876. %@NL@%
  4877. %@AS@%  NMAKE /S "program = sample" sort.exe search.exe%@AE@%%@NL@%
  4878. %@NL@%
  4879. The command supplies four arguments: an option (/S), a macro definition
  4880. (%@AS@%"program = sample"%@AE@%), and two target specifications (%@AS@%sort.exe search.exe%@AE@%).  %@NL@%
  4881. %@NL@%
  4882. Because the command does not specify a description file, NMAKE looks for the
  4883. default description file, MAKEFILE. The /S option tells NMAKE to suppress
  4884. the display of commands as they are executed. The macro definition performs
  4885. a text substitution throughout the description file, replacing every
  4886. instance of %@AS@% program %@AE@% with %@AS@% sample%@AE@%. The target specifications tell NMAKE to
  4887. update the targets SORT.EXE and SEARCH.EXE.  %@NL@%
  4888. %@NL@%
  4889. %@NL@%
  4890. %@2@%%@CR:C6A00060004 @%%@AB@%6.3  NMAKE Description Files%@AE@%%@EH@%%@NL@%
  4891. %@NL@%
  4892. You must always supply NMAKE with a description file. In addition to
  4893. description blocks, which tell NMAKE how to build your project's target
  4894. files, the description file can contain comments, macros, inference rules,
  4895. and directives. This section describes all the elements of description
  4896. files.  %@NL@%
  4897. %@NL@%
  4898. %@NL@%
  4899. %@3@%%@CR:C6A00060005 @%%@AB@%6.3.1  Description Blocks%@AE@%%@EH@%%@NL@%
  4900. %@NL@%
  4901. Description blocks form the heart of the description file. Figure 6.1
  4902. illustrates a typical NMAKE description block, including the three parts:
  4903. targets, dependents, and commands.  %@NL@%
  4904. %@NL@%
  4905. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  4906. %@NL@%
  4907. %@AU@% A target is a file that you want to build.%@AE@%  %@NL@%
  4908. %@NL@%
  4909. The targets part of the description block lists one or more files to build.
  4910. The line that lists targets and dependents is called the "dependency line."
  4911. %@NL@%
  4912. %@NL@%
  4913. The example in Figure 6.1 tells NMAKE to build a single target, MYAPP.EXE.
  4914. Although single targets are common, you can also list multiple targets;
  4915. separate each target name with a space. If the rightmost target name is one
  4916. character long, put a space between the name and the colon.  %@NL@%
  4917. %@NL@%
  4918. The target is normally a file, but it can also be a "pseudotarget," a name
  4919. that allows you to build groups of files or execute a group of commands. See
  4920. Section 6.3.6, "Pseudotargets."  %@NL@%
  4921. %@NL@%
  4922. %@AU@% A dependent is a file used to build a target.%@AE@%  %@NL@%
  4923. %@NL@%
  4924. The dependents part of the description block lists one or more files from
  4925. which the target is built. It is separated from the targets part by a colon.
  4926. The example in Figure 6.1 lists three dependents:  %@NL@%
  4927. %@NL@%
  4928. %@AS@%  myapp.exe : myapp.obj another.obj myapp.def%@AE@%%@NL@%
  4929. %@NL@%
  4930. The example tells NMAKE to build the target MYAPP.EXE whenever MYAPP.OBJ,
  4931. ANOTHER.OBJ, or MYAPP.DEF has changed more recently than MYAPP.EXE.  %@NL@%
  4932. %@NL@%
  4933. If any dependents of a target are listed as targets in other description
  4934. blocks, then NMAKE builds those files before it builds the original target.
  4935. Essentially NMAKE evaluates a "dependency tree" for the entire description
  4936. file. It builds files in the order needed to update the original target,
  4937. never building a target until all files that depend on it are up-to-date.  %@NL@%
  4938. %@NL@%
  4939. The dependent list can also include a list of directories in which NMAKE
  4940. should search for dependents. The directory list is enclosed in curly braces
  4941. ( {} ) and precedes the dependent list. NMAKE searches the current directory
  4942. first, then the directories you list:  %@NL@%
  4943. %@NL@%
  4944. %@AS@%  forward.exe : {\src\alpha;d:\proj}pass.obj%@AE@%%@NL@%
  4945. %@NL@%
  4946. In the line above, the target, FORWARD.EXE, has one dependent: PASS.OBJ. The
  4947. directory list specifies two directories:  %@NL@%
  4948. %@NL@%
  4949. %@AS@%  {\src\alpha;d:\proj}%@AE@%%@NL@%
  4950. %@NL@%
  4951. NMAKE begins searching for PASS.OBJ in the current directory. If it is not
  4952. found, NMAKE searches the \ SRC \ ALPHA directory, then the D:\ PROJ
  4953. directory. If NMAKE cannot find a dependent in the current directory or a
  4954. listed directory, it looks for an inference rule that describes how to
  4955. create the dependent (see Section 6.3.4, "Inference Rules").  %@NL@%
  4956. %@NL@%
  4957. %@AU@% The commands part of a  description block can contain  one or more
  4958. %@AU@%commands.%@AE@%  %@NL@%
  4959. %@NL@%
  4960. The commands part of the description block lists the command(s) NMAKE should
  4961. use to build the target. This can be any command that you can execute from
  4962. the command line. The example tells NMAKE to build MYAPP.EXE using the
  4963. following LINK command:  %@NL@%
  4964. %@NL@%
  4965. %@AS@%    LINK myapp another.obj, /align:16, NUL, os2, myapp%@AE@%%@NL@%
  4966. %@NL@%
  4967. Notice that the line above is indented. NMAKE uses indentation to
  4968. distinguish between the dependency line and command line. If the command
  4969. appears on a separate line, as here, it must be indented at least one space
  4970. or tab. The dependency line must not be indented (it cannot start with a
  4971. space or tab).  %@NL@%
  4972. %@NL@%
  4973. Many targets are built with a single command, but you can place more than
  4974. one command after the dependency line. A long command can span several lines
  4975. if each line ends with a backslash ( \ ).  %@NL@%
  4976. %@NL@%
  4977. You can also place the command at the end of the dependency line. Separate
  4978. the command from the rightmost dependent with a semicolon.  %@NL@%
  4979. %@NL@%
  4980. In OS/2 description files, NMAKE imposes a slight restriction on the use of
  4981. the CD, CHDIR, and SET commands. Do not place any of these commands on a
  4982. command line that uses the ampersand (&) to execute multiple commands. For
  4983. instance, the following command line is legal in an OS/2 description file,  %@NL@%
  4984. %@NL@%
  4985. %@AS@%  DIR & COPY sample.c backup.c%@AE@%%@NL@%
  4986. %@NL@%
  4987. but this line is not legal because it places a CD command after the
  4988. ampersand:  %@NL@%
  4989. %@NL@%
  4990. %@AS@%  DIR & CD \mydir%@AE@%%@NL@%
  4991. %@NL@%
  4992. To use CD, CHDIR, or SET in a description block, place the command on a
  4993. separate line:  %@NL@%
  4994. %@NL@%
  4995. %@AS@%  DIR
  4996. %@AS@%  CD \mydir%@AE@%%@NL@%
  4997. %@NL@%
  4998. Your OS/2 user's documentation contains more information about using the
  4999. ampersand in command lines.  %@NL@%
  5000. %@NL@%
  5001. %@NL@%
  5002. %@4@%%@AB@%Wild Cards%@AE@%%@EH@%%@NL@%
  5003. %@NL@%
  5004. You can use DOS wild-card characters (* and ?) to specify target and
  5005. dependent file names. NMAKE expands wild cards in target names when it reads
  5006. the description file. It expands wild cards in the dependent names when it
  5007. builds the target. For example, the following description block compiles all
  5008. source files with the .C extension:  %@NL@%
  5009. %@NL@%
  5010. %@AS@%  bondo.exe : *.c
  5011. %@AS@%      CL *.c%@AE@%%@NL@%
  5012. %@NL@%
  5013. %@NL@%
  5014. %@4@%%@AB@%Command Modifiers%@AE@%%@EH@%%@NL@%
  5015. %@NL@%
  5016. Command modifiers provide extra control over the command listed in a
  5017. description block. They are special characters that appear in front of a
  5018. command. You can use more than one modifier for a single command. Table 6.1
  5019. describes the three NMAKE command modifiers.  %@NL@%
  5020. %@NL@%
  5021. %@AB@%Table   %@AB@%6.1 Command Modifiers%@AE@%%@AE@%
  5022.  
  5023. %@TH:  45  2536 02 34 42 @%Character                         Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%At sign (@)                       Prevents NMAKE from displaying the                                   command as it executes. In the example                                   below, NMAKE does not display the ECHO                                   command line:                                  %@AS@%sort.exe : sort.obj%@AE@%                                  %@AS@%   @ECHO sorting%@AE@%                                  The output of the ECHO command appears                                   as usual.Dash (-)                          Turns off error checking for the command.                                  If the dash is followed by a number,                                   NMAKE stops only if the error level                                   returned by the command is greater than                                   the number. In the following example, if                                  the program %@AS@% sample %@AE@% returned an error                                   code NMAKE does not stop but continues                                   to execute commands:                                  %@AS@%light.lst : light.txt%@AE@%                                  %@AS@%   -sample light.txt%@AE@%Exclamation point (!)             Executes the command for each dependent                                   file if the command uses the predefined                                   macros %@AB@%$?%@AE@% or %@AB@%$**%@AE@%. The %@AB@%$?%@AE@% macro refers to                                  all dependent files that are out-of-date                                  with respect to the target. The %@AB@%$**%@AE@%                                   macro refers to all dependent files in                                   the description block (see Section 6.3.3,                                  "Macros"). For example,                                  %@AS@%print:hop.asm skip.bas jump.c%@AE@%                                  %@AS@%   !print $** lpt1:%@AE@%                                  generates the following commands:                                  %@AS@%print hop.asm lpt1:%@AE@%                                  %@AS@%print skip.bas lpt1:%@AE@%                                  %@AS@%print jump.c lpt1:%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  45  2536 02 34 42 @%
  5024.  
  5025. %@NL@%
  5026. %@4@%%@AB@%Using Control Characters as Literals%@AE@%%@EH@%%@NL@%
  5027. %@NL@%
  5028. Occasionally, you may need to list a file name that contains a character
  5029. that NMAKE uses as a control character. These characters are  %@NL@%
  5030. %@NL@%
  5031. # ( ) $ ^ \ { } ! @ -  %@NL@%
  5032. %@NL@%
  5033. To use an NMAKE control character as a literal character, place a caret (^)
  5034. in front of it. For example, say that you define a macro that ends with a
  5035. backslash:  %@NL@%
  5036. %@NL@%
  5037. %@AS@%  exepath=c:\bin\%@AE@%%@NL@%
  5038. %@NL@%
  5039. The line above is intended to define a macro named %@AS@% exepath %@AE@% with the value %@AS@%
  5040. %@AS@%c:\bin\%@AE@%. But the second backslash causes unexpected results. Since the
  5041. back-slash is the NMAKE line-continuation character, the line actually
  5042. defines the macro %@AS@% exepath %@AE@% as %@AS@% c:\bin %@AE@% followed by whatever appears on the
  5043. next line of the description file. You can solve the problem by placing a
  5044. caret in front of the second backslash:  %@NL@%
  5045. %@NL@%
  5046. %@AS@%  exepath=c:\bin^\%@AE@%%@NL@%
  5047. %@NL@%
  5048. You can also use a caret to place a literal newline character in a
  5049. description file. This feature can be useful in macro definitions:  %@NL@%
  5050. %@NL@%
  5051. %@AS@%  XYZ=abc^
  5052. %@AS@%  def%@AE@%%@NL@%
  5053. %@NL@%
  5054. NMAKE interprets the example as if you assigned the C-style string %@AS@% abc\ndef
  5055. %@AS@%%@AE@%to the %@AS@% XYZ %@AE@% macro. This effect differs from using the backslash ( \s ) to
  5056. continue a line. A newline character that follows a backslash is replaced
  5057. with a space.  %@NL@%
  5058. %@NL@%
  5059. Carets that precede noncontrol characters are ignored. The line  %@NL@%
  5060. %@NL@%
  5061. %@AS@%  ign^ore : these ca^rets%@AE@%%@NL@%
  5062. %@NL@%
  5063. is interpreted as  %@NL@%
  5064. %@NL@%
  5065. %@AS@%  ignore : these carets%@AE@%%@NL@%
  5066. %@NL@%
  5067. A caret that appears in quotation marks is treated as a literal caret
  5068. character.  %@NL@%
  5069. %@NL@%
  5070. %@NL@%
  5071. %@4@%%@AB@%Listing a Target in Multiple Description Blocks%@AE@%%@EH@%%@NL@%
  5072. %@NL@%
  5073. You can specify more than one description block for the same target by
  5074. placing two colons (::) after the target. This feature can be useful for
  5075. building a complex target, such as a library, that contains components
  5076. created with different commands. For example,  %@NL@%
  5077. %@NL@%
  5078. %@AS@%  target.lib :: a.asm b.asm c.asm
  5079. %@AS@%     CL a.asm b.asm c.asm
  5080. %@AS@%     LIB target -+a.obj -+b.obj -+c.obj; 
  5081. %@AS@%  target.lib :: d.c e.c
  5082. %@AS@%     CL /c d.c e.c
  5083. %@AS@%     LIB target -+d.obj -+e.obj;%@AE@%%@NL@%
  5084. %@NL@%
  5085. Both description blocks update the library named TARGET.LIB. If any of the
  5086. assembly-language files have changed more recently than the library, NMAKE
  5087. executes the commands in the first block to assemble the source files and
  5088. update  %@NL@%
  5089. %@NL@%
  5090. the library. Similarly, if any of the C-language files have changed, NMAKE
  5091. executes the second group of commands, which compile the C files and update
  5092. the library.  %@NL@%
  5093. %@NL@%
  5094. If you use a single colon in the example above, NMAKE issues an error
  5095. message. It is legal, however, to use single colons if commands are listed
  5096. in only one block. In this case, dependency lines are cumulative. For
  5097. example,  %@NL@%
  5098. %@NL@%
  5099. %@AS@%  target: jump.bas
  5100. %@AS@%  target: up.c
  5101. %@AS@%     echo Building target...%@AE@%%@NL@%
  5102. %@NL@%
  5103. is equivalent to  %@NL@%
  5104. %@NL@%
  5105. %@AS@%  target: jump.bas up.c
  5106. %@AS@%     echo Building target...%@AE@%%@NL@%
  5107. %@NL@%
  5108. %@NL@%
  5109. %@3@%%@CR:C6A00060006 @%%@AB@%6.3.2  Comments%@AE@%%@EH@%%@NL@%
  5110. %@NL@%
  5111. You can place comments in a description file by preceding them with a number
  5112. sign (#):  %@NL@%
  5113. %@NL@%
  5114. %@AS@%  # This comment appears on its own line
  5115. %@AS@%  huey.exe : huey.obj dewey.obj # Comment on the same line
  5116. %@AS@%     link huey.obj dewey.obj;%@AE@%%@NL@%
  5117. %@NL@%
  5118. A comment extends to the end of the line in which it appears. Command lines
  5119. cannot contain comments.  %@NL@%
  5120. %@NL@%
  5121. %@NL@%
  5122. %@3@%%@CR:C6A00060007 @%%@AB@%6.3.3  Macros%@AE@%%@EH@%%@NL@%
  5123. %@NL@%
  5124. %@AU@% Macros allow you to do text replacements throughout the description file.%@AE@%  %@NL@%
  5125. %@NL@%
  5126. Macros offer a convenient way to replace a string in the description file
  5127. with another string. The text is automatically replaced each time you run
  5128. NMAKE. Macros are useful in a variety of tasks, including the following:  %@NL@%
  5129. %@NL@%
  5130. %@NL@%
  5131.   ■   To create a standard description file for several projects. The macro
  5132.       represents the file names used in commands. These file names are then
  5133.       defined when you run NMAKE. When you switch to a different project,
  5134.       you can change file names throughout the description file by changing
  5135.       a single macro.%@NL@%
  5136. %@NL@%
  5137.   ■   To control the options that NMAKE passes to the compiler or linker.
  5138.       When you specify options in a macro, you can change options throughout
  5139.       the description file in one easy step.%@NL@%
  5140. %@NL@%
  5141. %@NL@%
  5142. You can define your own macros or use predefined macros. This section begins
  5143. by describing user-defined macros.  %@NL@%
  5144. %@NL@%
  5145. %@NL@%
  5146. %@4@%%@AB@%User-Defined Macros%@AE@%%@EH@%%@NL@%
  5147. %@NL@%
  5148. You can define a macro with  %@NL@%
  5149. %@NL@%
  5150. %@AS@%  macroname = string%@AE@%%@NL@%
  5151. %@NL@%
  5152. The %@AI@%macroname%@AE@% can be any combination of letters, digits, and the underscore
  5153. ( _ ) character. Macro names are case sensitive. NMAKE interprets %@AS@% MyMacro %@AE@%
  5154. and %@AS@% MYMACRO %@AE@% as different macro names.  %@NL@%
  5155. %@NL@%
  5156. The %@AI@%string%@AE@% can be any string, including a null string. For example,  %@NL@%
  5157. %@NL@%
  5158. %@AS@%  command = LINK%@AE@%%@NL@%
  5159. %@NL@%
  5160. defines a macro named %@AS@% command %@AE@% and assigns it the string %@AS@% LINK%@AE@%.  %@NL@%
  5161. %@NL@%
  5162. You can define macros in the description file or on the command line. In the
  5163. description file, you must define each macro on a separate line; the line
  5164. cannot start with a space or tab. The %@AI@%string%@AE@% can contain embedded spaces,
  5165. and NMAKE ignores spaces on either side of the equal sign. You do not need
  5166. to enclose %@AI@%string%@AE@% in quotation marks (if you do, they become part of the
  5167. string).  %@NL@%
  5168. %@NL@%
  5169. Slightly different rules apply when you define a macro on the command line,
  5170. because of the way that the command line handles spaces. You must enclose
  5171. %@AI@%string%@AE@% in quotation marks if it contains embedded spaces. No spaces can
  5172. surround the equal sign. You can also enclose the entire macro definition,
  5173. %@AI@%macroname%@AE@% and %@AI@%string%@AE@%, in quotation marks. For example,  %@NL@%
  5174. %@NL@%
  5175. %@AS@%  NMAKE "program=sample"%@AE@%%@NL@%
  5176. %@NL@%
  5177. defines the macro %@AS@% program%@AE@%, assigning it the value %@AS@% sample%@AE@%.  %@NL@%
  5178. %@NL@%
  5179. Once you have defined a macro, you can "undefine" it with the !UNDEF
  5180. directive (see Section 6.3.5, "Directives").  %@NL@%
  5181. %@NL@%
  5182. %@NL@%
  5183. %@4@%%@AB@%Invoking Macros%@AE@%%@EH@%%@NL@%
  5184. %@NL@%
  5185. You invoke a macro by enclosing its name in parentheses preceded by a dollar
  5186. sign ($). (The parentheses are optional if %@AI@%macroname%@AE@% is one character long.)
  5187. For example, you can invoke the %@AS@% command %@AE@% macro defined above as  %@NL@%
  5188. %@NL@%
  5189. %@AS@%  $(command)%@AE@%%@NL@%
  5190. %@NL@%
  5191. When NMAKE runs, it replaces every occurrence of %@AS@% $(command) %@AE@% with %@AS@% LINK%@AE@%.
  5192. The following description file defines and uses three macros:  %@NL@%
  5193. %@NL@%
  5194. %@AS@%  program = sample
  5195. %@AS@%  c = LINK
  5196. %@AS@%  options = 
  5197. %@AS@%  
  5198. %@AS@%  $(program).exe : $(program).obj
  5199. %@AS@%     $c  $(options)  $(program).obj;%@AE@%%@NL@%
  5200. %@NL@%
  5201. NMAKE interprets the description block as  %@NL@%
  5202. %@NL@%
  5203. %@AS@%  sample.exe : sample.obj
  5204. %@AS@%     LINK    sample.obj;%@AE@%%@NL@%
  5205. %@NL@%
  5206. NMAKE replaces every occurrence of %@AS@% $(program) %@AE@% with %@AS@% sample%@AE@%, every instance
  5207. of %@AS@% $c %@AE@% with %@AS@% LINK%@AE@%, and every instance of %@AS@% $(options) %@AE@%with a null string.
  5208. Because %@AS@% c %@AE@% is only one character long, you do not need to enclose it in
  5209. parentheses.  %@NL@%
  5210. %@NL@%
  5211. If you invoke a macro that is not defined, NMAKE treats the macro as a null
  5212. string.  %@NL@%
  5213. %@NL@%
  5214. Occasionally, you may need to use the dollar sign ($) as a literal
  5215. character. Use two signs ($$), or precede it with a caret (^$).  %@NL@%
  5216. %@NL@%
  5217. %@NL@%
  5218. %@4@%%@AB@%Predefined Macros%@AE@%%@EH@%%@NL@%
  5219. %@NL@%
  5220. NMAKE provides several predefined macros, which represent various file names
  5221. and commands. Predefined macros are useful in their own right, and they are
  5222. also employed in predefined inference rules, which are described later in
  5223. this chapter. Table 6.2 lists NMAKE predefined macros.  %@NL@%
  5224. %@NL@%
  5225. %@AB@%Table   %@AB@%6.2  Predefined Macros%@AE@%%@AE@%
  5226.  
  5227. %@TH:  29  1603 02 34 42 @%Macro                             Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%$@ %@AE@%                               The current target's full name.%@AB@%$* %@AE@%                               The current target's base name (full                                   name minus the file                                   extension).%@AB@%$** %@AE@%                              The dependents of the current target.%@AB@%$? %@AE@%                               The dependents that are out-of-date with                                  respect to the current target.%@AB@%$$@ %@AE@%                              The target that NMAKE is currently                                   evaluating. You can only use this macro                                   to specify a dependent.%@AB@%$< %@AE@%                               The dependent file that is out-of-date                                   with respect to the current target                                   (evaluated only for inference rules).%@AB@%$(CC) %@AE@%                            The command to invoke the C compiler. By                                  default,%@AB@% $(CC)%@AE@% is predefined as %@AS@% CC = cl%@AE@%,                                  which invokes the optimizing compiler.%@AB@%$(AS)  %@AE@%                           The command that invokes the Microsoft                                   Macro Assembler. NMAKE predefines this                                   macro as %@AS@% AS = masm%@AE@%. %@TE:  29  1603 02 34 42 @%
  5228.  
  5229. %@AB@%Table   %@AB@%6.2  (continued)%@AE@%%@AE@%
  5230.  
  5231. %@TH:  53  3240 02 34 42 @%Macro                             Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%$(MAKE)  %@AE@%                         The name with which the NMAKE utility is                                  invoked. This macro is used to invoke                                   NMAKE recursively. It causes the line on                                  which it appears to be executed even if                                   the /N option is on. You can redefine                                   this macro if you want to execute                                   another program.                                   The %@AB@%$(MAKE)%@AE@% macro is useful for building                                  different versions of a program. The                                   following description file invokes NMAKE                                  recursively to build targets in the                                   VERS1 and VERS2 directories.                                  %@AS@%all :vers1 vers2%@AE@%                                  %@AS@%versl  :%@AE@%                                  %@AS@%   cd versl%@AE@%                                  %@AS@%   $(MAKE)%@AE@%                                  %@AS@%   cd  . .%@AE@%                                  %@AS@%vers2 :%@AE@%                                  %@AS@%   cd vers2%@AE@%                                  %@AS@%   $(MAKE)%@AE@%                                  %@AS@%   cd . .%@AE@%                                  The example changes to the VERS1                                   directory, then invokes NMAKE                                   recursively, causing NMAKE to process                                   the file MAKEFILE in that directory.                                   Then it changes to the VERS2 directory                                   and invokes NMAKE again, processing the                                   file MAKEFILE in that directory.                                  Deeply recursive build procedures can                                   exhaust NMAKE's run-time stack, causing                                   a run-time error. To eliminate the error,                                  use the EXEHDR utility to increase                                   NMAKE's run-time stack. The following                                   command, for example, gives NMAKE.EXE a                                   stack size of 16,384 (0x4000) bytes:                                  %@AS@%exehdr /stack:0x4000 nmake.exe%@AE@%%@AB@%$(MAKEFLAGS) %@AE@%                     The NMAKE options currently in effect.                                   If you invoke NMAKE recursively, you                                   should use the command: %@AS@% $(MAKE)%@AE@% %@AS@% %@AE@%                                  %@AS@%$(MAKEFLAGS)%@AE@%. You cannot redefine this                                   macro.%@AB@%$(MAKEDIR) %@AE@%                       The directory from which NMAKE is                                   invoked.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  53  3240 02 34 42 @%
  5232.  
  5233. Like user-defined macro names, predefined macro names are case sensitive.
  5234. NMAKE interprets %@AS@% CC %@AE@% and %@AS@% cc %@AE@% as different macro names.  %@NL@%
  5235. %@NL@%
  5236. %@AU@% Macro modifiers allow you to specify parts of predefined macros
  5237. %@AU@%representing file names.%@AE@%  %@NL@%
  5238. %@NL@%
  5239. You can append characters to any of the first six macros in Table 6.2 to
  5240. modify its meaning. Appending a %@AB@%D%@AE@% specifies the directory part of the file
  5241. name only, an %@AB@%F%@AE@% specifies the file name, a %@AB@%B%@AE@% specifies just the base name,
  5242. and an %@AB@%R%@AE@% specifies the complete file name without the extension. If you add
  5243. one of these characters, you must enclose the macro name in parentheses.
  5244. (The predefined macros %@AB@%$$@%@AE@% and %@AB@%$**%@AE@% are the only exceptions to the rule that
  5245. macro names more than one character long must be enclosed in parentheses.)  %@NL@%
  5246. %@NL@%
  5247. For example, assume that %@AB@%$@%@AE@% has the value C:\ SOURCE \ PROG \ SORT.OBJ. The
  5248. list below shows the effect of combining the special characters with %@AB@%$@%@AE@%:  %@NL@%
  5249. %@NL@%
  5250. %@AB@%Macro%@AE@%                             %@AB@%Value%@AE@%
  5251. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5252. %@AB@%$(@D)%@AE@%                             C:\ SOURCE \ PROG
  5253.  
  5254. %@AB@%$(@F)%@AE@%                             SORT.OBJ
  5255.  
  5256. %@AB@%$(@B)%@AE@%                             SORT
  5257.  
  5258. %@AB@%$(@R)%@AE@%                             C:\ SOURCE \ PROG \ SORT
  5259.  
  5260. For example, in the code below, the macro %@AB@%$?%@AE@% represents the names of all
  5261. dependents that are more recent than the target. The exclamation point
  5262. causes NMAKE to execute the LIB command once for each dependent in the list.
  5263. As a result, the LIB command is executed up to three times, each time
  5264. replacing a module with a newer version.  %@NL@%
  5265. %@NL@%
  5266. %@AS@%  trig.lib : sin.obj cos.obj arctan.obj
  5267. %@AS@%          !LIB trig.lib -+$?;%@AE@%%@NL@%
  5268. %@NL@%
  5269. In the following example, NMAKE updates a group of include files:  %@NL@%
  5270. %@NL@%
  5271. %@AS@%  # Include files depend on versions in current directory
  5272. %@AS@%  DIR=c:\include
  5273. %@AS@%  $(DIR)\globals.h : globals.h
  5274. %@AS@%   COPY globals.h $@
  5275. %@AS@%  $(DIR)\types.h : types.h
  5276. %@AS@%   COPY types.h $@
  5277. %@AS@%  $(DIR)\macros.h : macros.h
  5278. %@AS@%   COPY macros.h $@%@AE@%%@NL@%
  5279. %@NL@%
  5280. Each of the files GLOBALS.H, TYPES.H, and MACROS.H in the directory  C:\
  5281. INCLUDE depends on its counterpart in the current directory. If one of the
  5282. include files is out-of-date, NMAKE replaces it with the file of the same
  5283. name from the current directory.  %@NL@%
  5284. %@NL@%
  5285. %@NL@%
  5286. %@4@%%@AB@%Substitution within Macros%@AE@%%@EH@%%@NL@%
  5287. %@NL@%
  5288. Just as macros allow you to substitute text in a description file, you can
  5289. also substitute text within a macro itself. Use the following form:  %@NL@%
  5290. %@NL@%
  5291. %@AS@%  $(macroname:string1 = string2)%@AE@%%@NL@%
  5292. %@NL@%
  5293. %@AU@% You can replace text in a macro, as well as in the description file.%@AE@%  %@NL@%
  5294. %@NL@%
  5295. Every occurrence of %@AI@%string1%@AE@% is replaced by %@AI@%string2%@AE@% in the macro %@AI@%macroname%@AE@%.
  5296. Do not put any spaces or tabs between %@AI@%macroname%@AE@% and the colon. Spaces
  5297. between the colon and %@AI@%string1%@AE@% are made part of %@AI@%string1%@AE@%. If %@AI@%string2%@AE@% is a null
  5298. string, all occurrences of %@AI@%string1%@AE@% are deleted from the %@AI@%macroname%@AE@% macro.  %@NL@%
  5299. %@NL@%
  5300. The following description file illustrates macro substitution:  %@NL@%
  5301. %@NL@%
  5302. %@AS@%  SRCS = prog.c sub1.c sub2.c 
  5303. %@AS@%  prog.exe : $(SRCS:.c=.obj)
  5304. %@AS@%          LINK  $**;
  5305. %@AS@%  
  5306. %@AS@%  DUP : $(SRCS)
  5307. %@AS@%          !COPY $** c:\backup%@AE@%%@NL@%
  5308. %@NL@%
  5309. The predefined macro %@AB@%$**%@AE@% stands for the names of all the dependent files
  5310. (see the previous section). If you invoke the example file with a command
  5311. line that specifies both targets, NMAKE executes the following commands:  %@NL@%
  5312. %@NL@%
  5313. %@AS@%  LINK prog.obj sub1.obj sub2.obj;%@AE@%%@NL@%
  5314. %@NL@%
  5315. %@AS@%  COPY prog.c c:\backup
  5316. %@AS@%  COPY sub1.c c:\backup
  5317. %@AS@%  COPY sub2.c c:\backup%@AE@%%@NL@%
  5318. %@NL@%
  5319. The macro substitution does not alter the definition of the %@AS@% SRCS %@AE@% macro,
  5320. rather, it simply replaces the listed characters. When NMAKE builds the
  5321. target PROG.EXE, it gets the definition for the predefined macro %@AB@%$**%@AE@% (the
  5322. dependent list) from the dependency line, which specifies the macro
  5323. substitution in %@AS@% SRCS%@AE@%. The same is true for the second target, %@AS@% DUP%@AE@%. In this
  5324. case, however, no macro substitution is requested, so %@AS@% SRCS %@AE@% retains its
  5325. original value, and %@AB@%$**%@AE@% represents the names of the C source files. (In the
  5326. example above, the target %@AS@% DUP %@AE@% is a pseudotarget; Section 6.3.6 describes
  5327. pseudotargets.)  %@NL@%
  5328. %@NL@%
  5329. You can also perform substitution in the following predefined macros: %@AB@%$@%@AE@%,
  5330. %@AB@%$*%@AE@%, %@AB@%$**%@AE@%, %@AB@%$?%@AE@%, and%@AB@% $%@AE@%. The principle is the same as for other macros. The
  5331. command in the following description block substitutes within a predefined
  5332. macro:  %@NL@%
  5333. %@NL@%
  5334. %@AS@%  target.abc : depend.xyz
  5335. %@AS@%     echo $(@:targ=blank)%@AE@%%@NL@%
  5336. %@NL@%
  5337. If dependent %@AS@% depend.xyz %@AE@% is out-of-date relative to target %@AS@% target.abc%@AE@%,
  5338. then NMAKE executes the command  %@NL@%
  5339. %@NL@%
  5340. %@AS@%  echo blanket.abc%@AE@%%@NL@%
  5341. %@NL@%
  5342. The example uses the predefined macro %@AB@%$@%@AE@%, which equals the full name of the
  5343. current target ( %@AS@%target.abc%@AE@%). It substitutes %@AS@% blank %@AE@% for %@AS@% targ %@AE@% in the
  5344. target, resulting in %@AS@% blanket.abc%@AE@%. Note that you do not put the usual dollar
  5345. sign in front of the predefined macro. The example uses  %@NL@%
  5346. %@NL@%
  5347. %@AS@%  $(@:targ=blank)%@AE@%%@NL@%
  5348. %@NL@%
  5349. instead of  %@NL@%
  5350. %@NL@%
  5351. %@AS@%  $($@:targ=blank)%@AE@%%@NL@%
  5352. %@NL@%
  5353. to substitute within the predefined macro %@AB@%$@%@AE@%.  %@NL@%
  5354. %@NL@%
  5355. %@NL@%
  5356. %@4@%%@AB@%Inherited Macros%@AE@%%@EH@%%@NL@%
  5357. %@NL@%
  5358. When NMAKE executes, it creates macros equivalent to every current
  5359. environment variable. These are called "inherited" macros because they have
  5360. the same names and values as the corresponding environment%@CR:C6A00060008 @% variables. (The
  5361. inherited macro is all uppercase, however, even if the corresponding
  5362. environment variable is not.)  %@NL@%
  5363. %@NL@%
  5364. Inherited macros can be used like other macros. You can also redefine them.
  5365. The following example redefines the inherited macro %@AS@% PATH%@AE@%:  %@NL@%
  5366. %@NL@%
  5367. %@AS@%  PATH = c:\tools\bin
  5368. %@AS@%  
  5369. %@AS@%  sample.obj : sample.c
  5370. %@AS@%     CL /c sample.c%@AE@%%@NL@%
  5371. %@NL@%
  5372. %@AU@% Inherited macros take their definitions from environment variables.%@AE@%  %@NL@%
  5373. %@NL@%
  5374. No matter what value PATH had in the DOS environment, it has the value %@AS@%
  5375. %@AS@%c:\tools\bin %@AE@% when NMAKE executes the CL command in this description block.
  5376. Redefining the inherited macro does not affect the original environment
  5377. variable; when NMAKE terminates, PATH has its original value.  %@NL@%
  5378. %@NL@%
  5379. The /E option defeats macro inheritance. If you supply this option, NMAKE
  5380. ignores any attempt to redefine a macro that derives from an environment
  5381. variable.  %@NL@%
  5382. %@NL@%
  5383. %@NL@%
  5384. %@4@%%@AB@%Precedence among Macro Definitions%@AE@%%@EH@%%@NL@%
  5385. %@NL@%
  5386. If you define the same macro in more than one place, NMAKE uses the macro
  5387. with the highest precedence. The precedence from highest to lowest is as
  5388. follows:  %@NL@%
  5389. %@NL@%
  5390. %@NL@%
  5391.   1.  Macros defined on the command line%@NL@%
  5392. %@NL@%
  5393.   2.  Macros defined in a description file or include file%@NL@%
  5394. %@NL@%
  5395.   3.  Inherited macros%@NL@%
  5396. %@NL@%
  5397.   4.  Macros defined in the TOOLS.INI file%@NL@%
  5398. %@NL@%
  5399.   5.  Predefined macros such as%@AB@% CC %@AE@%and%@AB@% AS%@AE@%%@NL@%
  5400. %@NL@%
  5401. %@NL@%
  5402. The /E option defeats any attempt to redefine inherited macros. If you run
  5403. NMAKE with this option, macros inherited from environment variables override
  5404. any same-named macros in the description file.  %@NL@%
  5405. %@NL@%
  5406. %@NL@%
  5407. %@3@%%@CR:C6A00060009 @%%@AB@%6.3.4  Inference Rules%@AE@%%@EH@%%@NL@%
  5408. %@NL@%
  5409. Inference rules are templates that NMAKE uses to create files with a given
  5410. extension. For instance, when NMAKE encounters a description block with no
  5411. commands, it tries to apply an inference rule that tells how to create the
  5412. target from the dependent files, given the two extensions. Similarly, if a
  5413. dependent file does not exist, NMAKE tries to apply an inference rule that
  5414. tells how to create the missing dependent from another file with the same
  5415. base name.  %@NL@%
  5416. %@NL@%
  5417. %@AU@% Inference rules tell NMAKE how to create files with a certain extension.%@AE@%  %@NL@%
  5418. %@NL@%
  5419. Inference rules provide a convenient shorthand for common operations. For
  5420. instance, you can use an inference rule to avoid repeating the same command
  5421. in several description blocks.  %@NL@%
  5422. %@NL@%
  5423. You can define your own inference rules or use predefined inference rules.
  5424. This section begins by describing user-defined inference rules.  %@NL@%
  5425. %@NL@%
  5426. %@NL@%
  5427. %@4@%%@AB@%User-Defined Inference Rules%@AE@%%@EH@%%@NL@%
  5428. %@NL@%
  5429. You can define inference rules in the description file or in the TOOLS.INI
  5430. file. An inference-rule definition lists two file extensions and one or more
  5431. commands. For instance, the following inference rule tells NMAKE how to
  5432. build a .OBJ file using a .C file:%@CR:C6A00060010 @%  %@NL@%
  5433. %@NL@%
  5434. %@AS@%  .C.OBJ:
  5435. %@AS@%     CL /c $<;%@AE@%%@NL@%
  5436. %@NL@%
  5437. The first line lists two extensions. The second extension (.OBJ) specifies
  5438. the type of the desired file and the first (.C) specifies the type of the
  5439. desired file's dependent. The second line lists the command used to build
  5440. the desired file. Here, the predefined macro %@AB@%$%@AE@% represents the name of a
  5441. dependent that is out-of-date relative to the target.  %@NL@%
  5442. %@NL@%
  5443. NMAKE could apply the above inference rule to the following description
  5444. block:  %@NL@%
  5445. %@NL@%
  5446. %@AS@%  sample.obj :%@AE@%%@NL@%
  5447. %@NL@%
  5448. The description block lists only a target, SAMPLE.OBJ. Both the dependent
  5449. and the command are missing. However, given the target's base name and
  5450. extension, plus the above inference rule, NMAKE has enough information to
  5451. build the target. NMAKE first looks for a .C file with the same base name as
  5452. the target. If SAMPLE.C exists, NMAKE compares its date to that of
  5453. SAMPLE.OBJ (the comparison is triggered by the predefined macro %@AB@%$%@AE@%). If
  5454. SAMPLE.C has changed more recently, NMAKE compiles it using the CL command
  5455. listed in the inference rule:  %@NL@%
  5456. %@NL@%
  5457. %@AS@%  CL/c sample.c%@AE@%%@NL@%
  5458. %@NL@%
  5459. ────────────────────────────────────────────────────────────────────────────%@NL@%
  5460. NOTE
  5461.  
  5462. %@AI@%NMAKE applies an inference rule only if the base name of the file it is
  5463. %@AI@%trying to create matches the base name of a file that already exists. Thus,
  5464. %@AI@%inference rules are useful only when there is a one-to-one correspondence
  5465. %@AI@%between the desired file and its dependent. You cannot define an inference
  5466. %@AI@%rule that replaces several modules in a library, for example.%@AE@%%@NL@%
  5467. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  5468. %@NL@%
  5469. %@NL@%
  5470. %@4@%%@AB@%Extension Search Paths%@AE@%%@EH@%%@NL@%
  5471. %@NL@%
  5472. If an inference rule does not specify a search path, as in the example
  5473. above, NMAKE looks for files in the current directory. You can specify a
  5474. single path for each of the extensions, using the following form:  %@NL@%
  5475. %@NL@%
  5476. %@AS@%  {frompath}. fromext{topath}. toext:
  5477. %@AS@%          commands%@AE@%%@NL@%
  5478. %@NL@%
  5479. NMAKE searches in the %@AI@%frompath%@AE@% directory for files with the %@AI@%fromext%@AE@%
  5480. extension. It uses %@AI@%commands%@AE@% to create files with the %@AI@%toext%@AE@% extension in the
  5481. %@AI@%topath%@AE@% directory.  %@NL@%
  5482. %@NL@%
  5483. %@NL@%
  5484. %@4@%%@AB@%Predefined Inference Rules%@AE@%%@EH@%%@NL@%
  5485. %@NL@%
  5486. NMAKE provides predefined inference rules to perform these common
  5487. development tasks:  %@NL@%
  5488. %@NL@%
  5489. %@NL@%
  5490.   ■   Creating an .OBJ file by compiling a .C file%@NL@%
  5491. %@NL@%
  5492.   ■   Creating an .OBJ file by assembling an .ASM file%@NL@%
  5493. %@NL@%
  5494.   ■   Creating an .EXE file by compiling a .C file and linking the resulting
  5495.       .OBJ file%@NL@%
  5496. %@NL@%
  5497. %@NL@%
  5498. Table 6.3 describes the predefined inference rules.  %@NL@%
  5499. %@NL@%
  5500. %@AB@%Table   %@AB@%6.3 Predefined Inference Rules%@AE@%%@AE@%
  5501.  
  5502. %@TH:   6   432 02 16 26 34 @%Inference Rule  Command                   Default Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%.c.obj          $(CC) $(CFLAGS) /c $*.c   cl /c $*.c.asm.obj        $(AS) $(AFLAGS) $*;       masm $*;.c.exe          $(CC) $(CFLAGS) $*.c      cl $*.c%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   6   432 02 16 26 34 @%
  5503.  
  5504. For example, say that you have the following description file:  %@NL@%
  5505. %@NL@%
  5506. %@AS@%  sample.exe :%@AE@%%@NL@%
  5507. %@NL@%
  5508. Like the previous example, this description block lists a target without any
  5509. dependents or commands. NMAKE looks at the target's extension (.EXE) and
  5510. checks for an inference rule that describes how to create a .EXE file. The
  5511. last rule in Table 6.3 provides this information:  %@NL@%
  5512. %@NL@%
  5513. %@AS@%  .c.exe:
  5514. %@AS@%     $(CC) $(CFLAGS) $*.c%@AE@%%@NL@%
  5515. %@NL@%
  5516. To apply this rule, NMAKE first looks for a file with the same base name as
  5517. the target (SAMPLE) and the .C extension. If SAMPLE.C exists in the current
  5518. directory, NMAKE executes the CL command given in the rule. The command
  5519. compiles SAMPLE.C and links the resulting file SAMPLE.OBJ to create
  5520. SAMPLE.EXE.  %@NL@%
  5521. %@NL@%
  5522. %@NL@%
  5523. %@4@%%@AB@%Precedence among Inference Rules%@AE@%%@EH@%%@NL@%
  5524. %@NL@%
  5525. If the same inference rule is defined in more than one place, NMAKE uses the
  5526. rule with the highest precedence. The precedence from highest to lowest is  %@NL@%
  5527. %@NL@%
  5528. %@NL@%
  5529.   1.  Inference rules defined in the description file%@NL@%
  5530. %@NL@%
  5531.   2.  Inference rules defined in the TOOLS.INI file%@NL@%
  5532. %@NL@%
  5533.   3.  Predefined inference rules%@NL@%
  5534. %@NL@%
  5535. %@NL@%
  5536. NMAKE uses a predefined inference rule only if no user-defined inference
  5537. rule exists for the desired operation.  %@NL@%
  5538. %@NL@%
  5539. %@NL@%
  5540. %@3@%%@CR:C6A00060011 @%%@AB@%6.3.5  Directives%@AE@%%@EH@%%@NL@%
  5541. %@NL@%
  5542. Directives allow you to write description files that are similar to batch
  5543. files. Directives can execute commands conditionally, display error
  5544. messages, include other files, and turn on or off certain options.  %@NL@%
  5545. %@NL@%
  5546. %@AU@% NMAKE directives are similar to C preprocessor directives.%@AE@%  %@NL@%
  5547. %@NL@%
  5548. A directive begins with an exclamation point (!), which must appear at the
  5549. beginning of the line. You can place spaces between the exclamation point
  5550. and the directive keyword. (See Table 6.4.)  %@NL@%
  5551. %@NL@%
  5552. %@AB@%Table 6.4  %@AB@%Directives%@AE@%%@AE@%
  5553.  
  5554. %@TH:  49  3078 02 25 51 @%Directive                Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%!CMDSWITCHES             Turns on or off one of four NMAKE options: /D, /I,{%@AB@%+%@AE@%| %@AB@%-%@AE@%}%@AI@%opt%@AE@%...                                       /N, and /S. If no options are specified, the                          options are reset to the way they were when NMAKE                         started. Turn an option on by preceding it with a                         plus sign (+), or turn it off by preceding it                          with a minus sign (-). Using this keyword updates                         the %@AB@%MAKEFLAGS%@AE@% macro.!ELSE                    Executes the statements between the%@AB@% !ELSE%@AE@% and%@AB@% %@AE@%                         %@AB@%!ENDIF%@AE@% keywords if the statements preceding the %@AB@%%@AE@%                         %@AB@%!ELSE%@AE@% keyword were not executed.!ENDIF                   Marks the end of the%@AB@% !IF%@AE@%,%@AB@% !IFDEF%@AE@%, or%@AB@% !IFNDEF%@AE@%                          block of statements.!ERROR %@AI@%text%@AE@%              Causes %@AI@%text%@AE@% to be printed and then stops                          execution.!IF %@AI@%constantexpression%@AE@%   Executes the statements between the%@AB@% !IF %@AE@%keyword                          and the next %@AB@%!ELSE%@AE@% or %@AB@%!ENDIF%@AE@% keyword if %@AI@%constant%@AE@%                         %@AI@%expression%@AE@% evaluates to a nonzero value.!IFDEF %@AI@%macroname%@AE@%         Executes the statements between the %@AB@%!IFDEF%@AE@%                          keyword and the next%@AB@% !ELSE%@AE@% or%@AB@% !ENDIF %@AE@%keyword if %@AI@%%@AE@%                         %@AI@%macroname%@AE@% is defined. NMAKE considers a macro                          with a null value to be defined.!IFNDEF %@AI@%macroname%@AE@%        Executes the statements between the%@AB@% !IFNDEF%@AE@%                          keyword and the next%@AB@% !ELSE%@AE@% or %@AB@%!ENDIF%@AE@% keyword if %@AI@%%@AE@%                         %@AI@%macroname%@AE@% is not defined.!INCLUDE %@AI@%filename%@AE@%        Reads and evaluates the file %@AI@%filename%@AE@% before                          continuing with the current description file. If %@AI@%%@AE@%                         %@AI@%filename%@AE@% is enclosed by angle brackets (< >),                          NMAKE searches for the file in the directories                          specified by the %@AB@%INCLUDE%@AE@% macro. Otherwise, it                          looks only in the current directory. The %@AB@%%@AE@%                         %@AB@%INCLUDE%@AE@% macro is initially set to the value of                          the                         INCLUDE environment variable.!UNDEF %@AI@%macroname%@AE@%         Marks %@AI@%macroname%@AE@% as being undefined in NMAKE's                          symbol table.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  49  3078 02 25 51 @%
  5555.  
  5556. The %@AI@%constantexpression%@AE@% used with the %@AB@%!IF%@AE@% directive can consist of integer
  5557. constants, string constants, or program invocations. Integer constants can
  5558. use the C unary operators for numerical negation (%@AB@%-%@AE@%), one's complement (%@AB@%~%@AE@%),
  5559. and logical negation (%@AB@%!%@AE@%). They can also use any of the C binary operators
  5560. listed in Table 6.5.  %@NL@%
  5561. %@NL@%
  5562. %@AB@%Table 6.5  %@AB@%Directive Operators%@AE@%%@AE@%
  5563.  
  5564. %@TH:  21  1088 02 22 54 @%Operator              Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%+%@AE@%                     Addition%@AB@%-%@AE@%                     Subtraction%@AB@%*%@AE@%                     Multiplication%@AB@%/%@AE@%                     Division%@AB@%%%@AE@%                     Modulus%@AB@%&%@AE@%                     Bitwise AND%@AB@%|%@AE@%                     Bitwise OR%@AB@%^^%@AE@%                    Bitwise XOR%@AB@%&&%@AE@%                    Logical AND%@AB@%||%@AE@%                    Logical OR%@AB@%<<%@AE@%                    Left shift%@AB@%>>%@AE@%                    Right shift%@AB@%==%@AE@%                    Equality%@AB@%!=%@AE@%                    Inequality%@AB@%<%@AE@%                     Less than%@AB@%>%@AE@%                     Greater than%@AB@%<=%@AE@%                    Less than or equal to%@AB@%>=%@AE@%                    Greater than or equal to%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  21  1088 02 22 54 @%
  5565.  
  5566. You can group expressions using parentheses. NMAKE treats numbers as decimal
  5567. unless they start with 0 (octal) or 0x (hexadecimal). Use the equality (%@AB@%==%@AE@%)
  5568. operator to compare two strings for equality or the inequality (%@AB@%!=%@AE@%) operator
  5569. to compare for inequality. Enclose strings with quotes. Program invocations
  5570. must be in square brackets ([ ]).  %@NL@%
  5571. %@NL@%
  5572. The following example illustrates directives:  %@NL@%
  5573. %@NL@%
  5574. %@AS@%  !INCLUDE <infrules.txt>
  5575. %@AS@%  !CMDSWITCHES +D
  5576. %@AS@%  winner.exe:winner.obj
  5577. %@AS@%  !IFDEF debug
  5578. %@AS@%  !  IF "$(debug)"=="y"
  5579. %@AS@%       LINK /CO winner.obj;
  5580. %@AS@%  !  ELSE
  5581. %@AS@%       LINK winner.obj;
  5582. %@AS@%  !  ENDIF
  5583. %@AS@%  !ELSE
  5584. %@AS@%  !  ERROR Macro named debug is not defined.
  5585. %@AS@%  !ENDIF%@AE@%%@NL@%
  5586. %@NL@%
  5587. The !INCLUDE directive causes NMAKE to insert the file INFRULES.TXT into the
  5588. description file. The !CMDSWITCHES directive turns on the /D option, which
  5589. displays the dates of the files as they are checked. If WINNER.EXE is
  5590. out-of-date with respect to WINNER.OBJ, the !IFDEF directive checks to see
  5591. if the macro %@AS@% debug %@AE@% is defined. If it is defined, the !IF directive checks
  5592. to see if it is set to %@AS@% y%@AE@%. If it is, the linker is invoked with the /CO
  5593. option; otherwise it is invoked without. If the %@AS@% debug %@AE@% macro is not
  5594. defined, the !ERROR directive prints the message and NMAKE stops.  %@NL@%
  5595. %@NL@%
  5596. %@NL@%
  5597. %@3@%%@CR:C6A00060012 @%%@AB@%6.3.6  Pseudotargets%@AE@%%@EH@%%@NL@%
  5598. %@NL@%
  5599. Pseudotargets are useful for building a group of files or executing a group
  5600. of commands.%@CR:C6A00060013 @%  %@NL@%
  5601. %@NL@%
  5602. A "pseudotarget" is similar to a target, but it is not a file. It is a name
  5603. that serves as a "handle" for building a group of files or executing a group
  5604. of commands. In the following example, %@AS@% UPDATE %@AE@% is a pseudotarget.  %@NL@%
  5605. %@NL@%
  5606. %@AS@%  UPDATE: *.*
  5607. %@AS@%   !COPY $** a:\product%@AE@%%@NL@%
  5608. %@NL@%
  5609. When NMAKE evaluates a pseudotarget, it always considers the dependents to
  5610. be out-of-date. In the example, NMAKE copies each of the dependent files to
  5611. the specified drive and directory.  %@NL@%
  5612. %@NL@%
  5613. Like macro names, pseudotarget names are case sensitive. Predefined
  5614. pseudotarget names are all uppercase.  %@NL@%
  5615. %@NL@%
  5616. The pseudotargets in Table 6.6 are predefined to provide special rules in a
  5617. description file. You can use their names on the command line, in a
  5618. description file, or in the TOOLS.INI file. You need not specify them as
  5619. targets; NMAKE uses the rules they define no matter where they appear.%@CR:C6A00060014 @%  %@NL@%
  5620. %@NL@%
  5621. %@AB@%Table   %@AB@%6.6  Pseudotargets%@AE@%%@AE@%
  5622.  
  5623. %@TH:  50  3027 02 34 42 @%Pseudotarget                      Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%.IGNORE:                          Ignores exit codes returned by programs                                   called from the description file. Same                                   effect as invoking NMAKE with the /I                                   option..PRECIOUS: %@AI@%target(s)%@AE@%              Tells NMAKE not to delete %@AI@%target(s)%@AE@% if                                   the commands that build it are quit or                                   interrupted. Using this pseudotarget                                   overrides the NMAKE default. By default,                                  NMAKE deletes the target if it cannot be                                  sure the target is built successfully.                                  The .PRECIOUS pseudotarget is rarely                                   needed. Like most professional tools,                                   Microsoft language tools clean up by                                   themselves when errors occur..SILENT:                          Does not display lines as they are                                   executed. Same effect as invoking NMAKE                                   with the /S option..SUFFIXES:%@AI@%list%@AE@%                    Lists file suffixes for NMAKE to try                                   when building a target file for which no                                  dependents are specified. This list is                                   used together with inference rules. See                                   Section 6.3.4, "Inference Rules."                                  When NMAKE finds a target without any                                   dependents, it searches the current                                   directory for a file with the same base                                   name as the target and a suffix from the                                  list. If NMAKE finds such a file, and if                                  an inference rule applies to the file,                                   then NMAKE treats the file as a depen-                                  dent of the target. The order of the                                   suffixes in the list defines the order                                   in which NMAKE searches for the file.                                   The list is predefined as follows:                                  %@AS@%.SUFFIXES: .obj .exe .c .asm%@AE@%                                  To add suffixes to the list, specify %@AS@% %@AE@%                                  %@AS@%.SUFFIXES : %@AE@%                                  followed by the new suffixes. To clear                                   the list, specify %@AS@% .SUFFIXES:%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  50  3027 02 34 42 @%
  5624.  
  5625. %@NL@%
  5626. %@3@%%@CR:C6A00060015 @%%@AB@%6.3.7  PWB's extmake Syntax%@AE@%%@EH@%%@NL@%
  5627. %@NL@%
  5628. NMAKE description files can use the same syntax as the %@AB@%extmake%@AE@% switch of PWB
  5629. (see Chapter 8, "Customizing the Microsoft Programmer's WorkBench"). This
  5630. syntax allows you to determine the drive, path, base name, and extension of
  5631. the first dependent, information that is not otherwise available. The file
  5632. name, and parts of its name, are represented using the syntax  %@NL@%
  5633. %@NL@%
  5634. %@AS@%  %|partsF%@AE@%%@NL@%
  5635. %@NL@%
  5636. where %@AI@%parts%@AE@% is one or more of the following:  %@NL@%
  5637. %@NL@%
  5638. %@AB@%Letter%@AE@%                            %@AB@%Description%@AE@%
  5639. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5640. %@AB@%d%@AE@%                                 Drive
  5641.  
  5642. %@AB@%e%@AE@%                                 File extension
  5643.  
  5644. %@AB@%f%@AE@%                                 File base name
  5645.  
  5646. %@AB@%p%@AE@%                                 Path
  5647.  
  5648. %@AB@%s%@AE@%                                 Complete name
  5649.  
  5650. The following example uses %@AB@%extmake%@AE@% syntax:  %@NL@%
  5651. %@NL@%
  5652. %@AS@%  sample.obj : sample.c
  5653. %@AS@%     CL /Fod:%|pfF %|dfeF%@AE@%%@NL@%
  5654. %@NL@%
  5655. In this example, the sequence %@AS@% %|pfF %@AE@% represents the path and base name of
  5656. the first dependent file, while the sequence %@AS@% %|dfeF %@AE@% represents the drive,
  5657. base name, and extension of the same file. The example, then, compiles the
  5658. file and writes the output to a file on the same path but with the default
  5659. .OBJ extension.  %@NL@%
  5660. %@NL@%
  5661. The percent symbol (%) is a replacement character in DOS and OS/2 command
  5662. lines in the description file. To use %@AB@%extmake%@AE@% syntax in command-line
  5663. arguments, specify each percent symbol as a double percent symbol (%%).  %@NL@%
  5664. %@NL@%
  5665. %@NL@%
  5666. %@2@%%@CR:C6A00060016 @%%@AB@%6.4  Command-Line Options%@AE@%%@EH@%%@NL@%
  5667. %@NL@%
  5668. NMAKE accepts a number of options, which are listed in Table 6.7. You can
  5669. specify options in uppercase or lowercase and use either a slash or dash.
  5670. For example, -A, /A, -a, and /a all represent the same option.  %@NL@%
  5671. %@NL@%
  5672. %@AB@%Table   %@AB@%6.7 NMAKE Options%@AE@%%@AE@%
  5673.  
  5674. %@TH:  73  3813 02 34 42 @%Option                            Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%/A                                Builds all of the requested targets even                                  if they are not out-of-date./C                                Suppresses nonfatal error or warning                                   messages and the NMAKE logo display./D                                Displays the modification date of each                                   file./E                                Causes environment variables to override                                  macro definitions in description files.                                   See Section 6.3.3, "Macros."/F %@AI@%filename%@AE@%                       Specifies %@AI@%filename%@AE@% as the name of the                                   description file. If you supply a dash                                   (-) instead of a file name, NMAKE gets                                   input from the standard input device                                   instead of the description file./HELP                             Calls the QuickHelp utility. If the                                   QuickHelp program is not available,                                   NMAKE displays the most commonly used                                   NMAKE options./I                                Ignores return codes from commands                                   listed in the description file. NMAKE                                   processes the whole description file                                   even if errors occur./N                                Displays but does not execute the                                   description file's commands. This option                                  is useful for debugging description                                   files and checking which targets are                                   out-of-date./NOLOGO                           Suppresses the NMAKE logo display./P                                Displays all macro definitions and                                   target descriptions on the standard                                   output device./Q                                Returns zero if the target is up-to-date                                  and nonzero if it is not. This option is                                  useful when running NMAKE from a batch                                   file./R                                Ignores inference rules and macros that                                   are predefined or defined in the                                   TOOLS.INI file./S                                Suppresses the display of commands                                   listed in the description file./T                                Changes the modification dates for                                   out-of-date target files to the current                                   date./X %@AI@%filename%@AE@%                       Sends all error output to %@AI@%filename%@AE@%,                                   which can be a file or a device. If you                                   supply a dash (-) instead of a file name,                                  the error output is sent to the standard                                  output device./Z                                Used for internal communication between                                   NMAKE and PWB./?                                Displays a brief summary of NMAKE syntax                                  and exits to the operating system.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  73  3813 02 34 42 @%
  5675.  
  5676. The following command specifies two NMAKE options:  %@NL@%
  5677. %@NL@%
  5678. %@AS@%  NMAKE /f sample.mak /c targ1 targ2%@AE@%%@NL@%
  5679. %@NL@%
  5680. The /f option tells NMAKE to read the description file SAMPLE.MAK. The /c
  5681. option tells NMAKE not to display nonfatal error messages and warnings. The
  5682. command lists two targets (%@AS@%targ1 %@AE@% and %@AS@% targ2%@AE@%) to update.  %@NL@%
  5683. %@NL@%
  5684. %@AS@%  NMAKE  /D /N targ1 targ1.mak%@AE@%%@NL@%
  5685. %@NL@%
  5686. In the example above, NMAKE updates the target %@AS@% targ1%@AE@%. If the current
  5687. directory does not contain a file named MAKEFILE, NMAKE reads the file
  5688. TARG1.MAK as the description file. The /D option displays the modification
  5689. date of each file; the /N option displays the commands without executing
  5690. them.  %@NL@%
  5691. %@NL@%
  5692. %@NL@%
  5693. %@2@%%@CR:C6A00060017 @%%@AB@%6.5  NMAKE Command Files%@AE@%%@EH@%%@NL@%
  5694. %@NL@%
  5695. Occasionally, you may need to give NMAKE a long list of command-line
  5696. arguments that exceeds the maximum length of a command line (128 characters
  5697. in DOS, 256 in OS/2). To do this, place the command arguments in a file,
  5698. then give the name of the file when you run NMAKE.  %@NL@%
  5699. %@NL@%
  5700. For instance, say that you create a file named UPDATE, which consists of
  5701. this line:  %@NL@%
  5702. %@NL@%
  5703. %@AS@%  /S "program = sample" sort.exe search.exe%@AE@%%@NL@%
  5704. %@NL@%
  5705. If you start NMAKE with the command  %@NL@%
  5706. %@NL@%
  5707. %@AS@%  NMAKE @update%@AE@%%@NL@%
  5708. %@NL@%
  5709. NMAKE reads its command-line arguments from UPDATE. The at sign (@) tells
  5710. NMAKE to read arguments from the file. The effect is the same as if you
  5711. typed the arguments directly on the command line:  %@NL@%
  5712. %@NL@%
  5713. %@AS@%  NMAKE /S "program = sample" sort.exe search.exe%@AE@%%@NL@%
  5714. %@NL@%
  5715. Within the file, line breaks between arguments are treated as spaces. Macro
  5716. definitions that contain spaces must be enclosed in quotation marks, just as
  5717. if you typed them on the command line. You can continue a macro definition
  5718. across multiple lines by ending each line except the last with a backslash (
  5719. \ ):  %@NL@%
  5720. %@NL@%
  5721. %@AS@%  /S "program \
  5722. %@AS@%  = sample" sort.exe search.exe%@AE@%%@NL@%
  5723. %@NL@%
  5724. This file is equivalent to the first example. The backslash in the example
  5725. allows the macro definition (%@AS@%"program = sample" %@AE@%) to span two lines.  %@NL@%
  5726. %@NL@%
  5727. %@NL@%
  5728. %@2@%%@CR:C6A00060018 @%%@AB@%6.6  The TOOLS.INI File%@AE@%%@EH@%%@NL@%
  5729. %@NL@%
  5730. You can customize NMAKE by placing commonly used macros and inference rules
  5731. in the TOOLS.INI initialization file. Settings for NMAKE must follow a line
  5732. that begins with %@AS@% [NMAKE]%@AE@%. This part of the initialization file can contain
  5733. macro definitions, .SUFFIXES lists, and inference rules. For example,  %@NL@%
  5734. %@NL@%
  5735. %@AS@%  [NMAKE]
  5736. %@AS@%  CC=cl
  5737. %@AS@%  CFLAGS=-Gc -Gs -W3 -Oat
  5738. %@AS@%  .c.obj:
  5739. %@AS@%      $(CC) -c $(CFLAGS) $*.c%@AE@%%@NL@%
  5740. %@NL@%
  5741. If TOOLS.INI contains the code above, NMAKE reads and applies the lines
  5742. following %@AS@% [NMAKE]%@AE@%. The example defines the macros %@AB@%CC%@AE@% and %@AB@%CFLAGS%@AE@% and
  5743. redefines the inference rule for making .OBJ files from .C sources.  %@NL@%
  5744. %@NL@%
  5745. NMAKE looks for TOOLS.INI in the current directory. If it is not found
  5746. there, NMAKE searches the directory specified by the INIT environment
  5747. variable.  %@NL@%
  5748. %@NL@%
  5749. %@NL@%
  5750. %@2@%%@CR:C6A00060019 @%%@AB@%6.7  In-Line Files%@AE@%%@EH@%%@NL@%
  5751. %@NL@%
  5752. NMAKE can write "in-line files," which can contain any text you specify. One
  5753. use for in-line files is to write a response file for another utility such
  5754. as LIB. (Response files are useful when you need to supply a program with a
  5755. long list of arguments that exceeds the maximum length of the command line.)
  5756. %@NL@%
  5757. %@NL@%
  5758. Use this syntax to create an in-line file:  %@NL@%
  5759. %@NL@%
  5760. %@AS@%  target : dependents
  5761. %@AS@%     command << «filename»
  5762. %@AS@%  inlinetext
  5763. %@AS@%  <<«KEEP | NOKEEP»%@AE@%%@NL@%
  5764. %@NL@%
  5765. All of the text between the two sets of double angle brackets (%@AB@%%@AE@%) is placed
  5766. in the in-line file. The %@AI@%filename%@AE@% is optional. If you don't supply %@AI@%filename%@AE@%,
  5767. NMAKE gives the in-line file a unique name. NMAKE places the in-line file in
  5768. the current directory or, if the TMP environment variable is defined, in the
  5769. directory specified by TMP.  %@NL@%
  5770. %@NL@%
  5771. The in-line file can be temporary or permanent. If you don't specify
  5772. otherwise, or if you specify %@AB@%NOKEEP%@AE@%, it is temporary. Specify %@AB@%KEEP%@AE@% to retain
  5773. the file.  %@NL@%
  5774. %@NL@%
  5775. The following example creates a LIB response file named LIB.LRF:  %@NL@%
  5776. %@NL@%
  5777. %@AS@%  math.lib : add.obj sub.obj mul.obj div.obj
  5778. %@AS@%    LIB @<<lib.lrf
  5779. %@AS@%  math.lib
  5780. %@AS@%  -+add.obj-+sub.obj-+mul.obj-+div.obj
  5781. %@AS@%  listing
  5782. %@AS@%  <<KEEP%@AE@%%@NL@%
  5783. %@NL@%
  5784. The resulting response file tells LIB which library to use, the commands to
  5785. execute, and the listing file to produce:  %@NL@%
  5786. %@NL@%
  5787. %@AS@%  math.lib
  5788. %@AS@%  -+add.obj-+sub.obj-+mul.obj-+div.obj
  5789. %@AS@%  listing%@AE@%%@NL@%
  5790. %@NL@%
  5791. The in-line file specification can create more than one in-line file. For
  5792. instance,  %@NL@%
  5793. %@NL@%
  5794. %@AS@%  target.abc : depend.xyz
  5795. %@AS@%     cat <<file1 <<file2
  5796. %@AS@%  I am the contents of file1.
  5797. %@AS@%  <<KEEP
  5798. %@AS@%  I am the contents of file2.
  5799. %@AS@%  <<KEEP%@AE@%%@NL@%
  5800. %@NL@%
  5801. The example creates two in-line files named FILE1 and FILE2; then NMAKE
  5802. executes the command:  %@NL@%
  5803. %@NL@%
  5804. %@AS@%  CAT file1 file2%@AE@%%@NL@%
  5805. %@NL@%
  5806. The %@AB@%KEEP%@AE@% keywords tell NMAKE not to delete FILE1 and FILE2 when done.  %@NL@%
  5807. %@NL@%
  5808. %@NL@%
  5809. %@2@%%@CR:C6A00060020 @%%@AB@%6.8  NMAKE Operations Sequence%@AE@%%@EH@%%@NL@%
  5810. %@NL@%
  5811. If you are writing a complex description file, you may need to know the
  5812. exact order of steps that NMAKE follows. This section describes those steps
  5813. in order.  %@NL@%
  5814. %@NL@%
  5815. When you run NMAKE from the command line, its first task is to find the
  5816. description file, following these steps:  %@NL@%
  5817. %@NL@%
  5818. %@NL@%
  5819.   1.  If NMAKE is invoked with the /F option, it uses the file name
  5820.       specified in the option.%@NL@%
  5821. %@NL@%
  5822.   2.  If /F is not specified, NMAKE looks for a file named MAKEFILE in the
  5823.       current directory. If such a file exists, it is used as a description
  5824.       file.%@NL@%
  5825. %@NL@%
  5826.   3.  If MAKEFILE is not in the current directory, NMAKE parses the command
  5827.       line for the first string that is not an option or a macro definition
  5828.       and treats this string as a file name. If the file-name extension does
  5829.       not appear in the .SUFFIXES list, NMAKE uses the file as the
  5830.       description file. If the extension appears in the .SUFFIXES list,
  5831.       NMAKE tries additional strings until it finds a suitable file. (See
  5832.       Section 6.3.6, "Pseudotargets," for a description of the .SUFFIXES
  5833.       list.)%@NL@%
  5834. %@NL@%
  5835.   4.  If NMAKE still has not found a description file, it returns an error.%@NL@%
  5836. %@NL@%
  5837. %@NL@%
  5838. NMAKE stops searching for a description file as soon as it finds one, even
  5839. if other potential description files exist. If you specify /F, NMAKE uses
  5840. the file specified by that option even if MAKEFILE exists in the current
  5841. directory. Similarly, if NMAKE uses MAKEFILE, any description file listed in
  5842. the command line is treated as a target.  %@NL@%
  5843. %@NL@%
  5844. %@AU@% If you do not specify targets, NMAKE updates only the first target in the
  5845. %@AU@%description file.%@AE@%  %@NL@%
  5846. %@NL@%
  5847. Next, NMAKE updates every target listed on the command line. If none is
  5848. listed, NMAKE updates only the first target in the description file. (This
  5849. behavior differs from the older MAKE program's default; see Section 6.9,
  5850. "Differences between NMAKE and MAKE.")  %@NL@%
  5851. %@NL@%
  5852. NMAKE then applies macro definitions and inference rules in the following
  5853. order, from highest to lowest priority:  %@NL@%
  5854. %@NL@%
  5855. %@NL@%
  5856.   1.  Macros defined on the command line%@NL@%
  5857. %@NL@%
  5858.   2.  Macros defined in a description file or include file%@NL@%
  5859. %@NL@%
  5860.   3.  Inherited macros%@NL@%
  5861. %@NL@%
  5862.   4.  Macros defined in the TOOLS.INI file%@NL@%
  5863. %@NL@%
  5864.   5.  Predefined macros such as %@AB@%CC%@AE@% and %@AB@%AS%@AE@%%@NL@%
  5865. %@NL@%
  5866. %@NL@%
  5867. Definitions in later steps take precedence over definitions in earlier
  5868. steps. The /E option, however, causes inherited macros to override macros
  5869. defined on the command line. The /R option causes NMAKE to ignore macros and
  5870. inference rules that are predefined or defined in TOOLS.INI.  %@NL@%
  5871. %@NL@%
  5872. Now NMAKE updates each target in the order in which it appears in the
  5873. description file. It compares the date and time of each dependent with that
  5874. of the target and performs the commands needed to update the target. If you
  5875. specify the /A option or if the target is a pseudotarget, NMAKE updates the
  5876. target even if its dependents are not out-of-date.  %@NL@%
  5877. %@NL@%
  5878. If the target has no explicit dependents, NMAKE looks in the current
  5879. directory for one or more files whose extensions are in the .SUFFIXES list.
  5880. If it finds such files, NMAKE treats them as dependents and updates the
  5881. target according to the commands.  %@NL@%
  5882. %@NL@%
  5883. If no commands are given to update the target or if the dependents cannot be
  5884. found, NMAKE applies inference rules to build the target. By default, it
  5885. tries to build .EXE files from .OBJ files; and it tries to build .OBJ files
  5886. from .C and .ASM sources. In practice, this means you should specify .OBJ
  5887. files as dependents, because NMAKE compiles your source files when it can't
  5888. find the .OBJ files.  %@NL@%
  5889. %@NL@%
  5890. NMAKE normally quits processing the description file when a command  returns
  5891. an error. In addition, if it cannot tell that the target was built
  5892. successfully, NMAKE deletes the partially created target. If you use the /I
  5893. commandline option, NMAKE ignores exit codes and attempts to continue
  5894. processing. The .IGNORE pseudotarget has the same effect. To prevent NMAKE
  5895. from  deleting the partially created target, specify the target name in the
  5896. .PRECIOUS pseudotarget.  %@NL@%
  5897. %@NL@%
  5898. Alternatively, you can use the dash (-) command modifier to ignore the error
  5899. code for an individual command. An optional number after the dash tells
  5900. NMAKE to continue if the command returns an error code that is less than or
  5901. equal to the number, and to stop if the error code is greater than the
  5902. number.  %@NL@%
  5903. %@NL@%
  5904. You can help document errors by using the !ERROR directive to print
  5905. descriptive text. The directive causes NMAKE to print some text, then stop,
  5906. even if you use /I, .IGNORE, or the dash (-) modifier.  %@NL@%
  5907. %@NL@%
  5908. %@NL@%
  5909. %@2@%%@CR:C6A00060021 @%%@AB@%6.9  Differences between NMAKE and MAKE%@AE@%%@EH@%%@NL@%
  5910. %@NL@%
  5911. As its name implies, NMAKE is a new utility that replaces the older
  5912. Microsoft MAKE program. NMAKE differs from MAKE in the following ways:  %@NL@%
  5913. %@NL@%
  5914. %@NL@%
  5915.   ■   NMAKE does not evaluate targets sequentially. Instead, NMAKE updates
  5916.       the targets you specify when you invoke it, regardless of their
  5917.       positions in the description file. If no targets are specified, NMAKE
  5918.       updates only the first target in the file.%@NL@%
  5919. %@NL@%
  5920.   ■   NMAKE accepts command-line arguments from a file.%@NL@%
  5921. %@NL@%
  5922.   ■   NMAKE provides more command-line options.%@NL@%
  5923. %@NL@%
  5924.   ■   NMAKE provides more predefined macros.%@NL@%
  5925. %@NL@%
  5926.   ■   NMAKE permits substitutions within macros.%@NL@%
  5927. %@NL@%
  5928.   ■   NMAKE supports directives placed in the description file.%@NL@%
  5929. %@NL@%
  5930.   ■   NMAKE allows you to specify include files in the description file.%@NL@%
  5931. %@NL@%
  5932. %@NL@%
  5933. The first item in the list deserves special emphasis. While MAKE normally
  5934. builds every target, working from beginning to end of the description file,
  5935. NMAKE expects you to specify targets on the command line. If you do not,
  5936. NMAKE builds only the first target in the description file.  %@NL@%
  5937. %@NL@%
  5938. The difference is clear if you run NMAKE using a typical MAKE description
  5939. file, which lists a series of subordinate targets followed by a higher-level
  5940. target that depends on the subordinates:  %@NL@%
  5941. %@NL@%
  5942. %@AS@%  pmapp.obj : pmapp.c
  5943. %@AS@%     CL /c /G2sw /W3 pmapp.c
  5944. %@AS@%  
  5945. %@AS@%  pmapp.exe : pmapp.obj pmapp.def
  5946. %@AS@%     LINK pmapp, /align:16, NUL, os2, pmapp%@AE@%%@NL@%
  5947. %@NL@%
  5948. MAKE builds both targets (PMAPP.OBJ and PMAPP.EXE), but NMAKE builds only
  5949. the first target (PMAPP.OBJ).  %@NL@%
  5950. %@NL@%
  5951. Because of these performance differences, you may want to convert MAKE files
  5952. to NMAKE files. MAKE description files are easy to convert. A simple method
  5953. is to create a new description block at the beginning of the file. Give this
  5954. block a pseudotarget named %@AS@% ALL %@AE@% and list the top-level target as a
  5955. dependent of %@AS@% ALL%@AE@%. To build %@AS@% ALL%@AE@%, NMAKE must update every target upon which
  5956. the target of %@AS@% ALL %@AE@% depends:  %@NL@%
  5957. %@NL@%
  5958. %@AS@%  ALL : pmapp.exe
  5959. %@AS@%  
  5960. %@AS@%  pmapp.obj : pmapp.c
  5961. %@AS@%     CL /c /G2sw /W3 pmapp.c
  5962. %@AS@%  
  5963. %@AS@%  pmapp.exe : pmapp.obj pmapp.def
  5964. %@AS@%     LINK pmapp, /align:16, NUL, os2, pmapp%@AE@%%@NL@%
  5965. %@NL@%
  5966. If the above file is named MAKEFILE, you can update the target PMAPP.EXE
  5967. with the command  %@NL@%
  5968. %@NL@%
  5969. %@AS@%  NMAKE%@AE@%%@NL@%
  5970. %@NL@%
  5971. or the command  %@NL@%
  5972. %@NL@%
  5973. %@AS@%  NMAKE ALL%@AE@%%@NL@%
  5974. %@NL@%
  5975. Note that it is not necessary to list PMAPP.OBJ as a dependent of %@AS@% ALL%@AE@%.
  5976. NMAKE builds a dependency tree for the entire description file, and builds
  5977. whatever files are needed to update PMAPP.EXE. So if PMAPP.C is out-ofdate
  5978. with respect to PMAPP.OBJ, NMAKE compiles PMAPP.C to create PMAPP.OBJ, then
  5979. links PMAPP.OBJ to create PMAPP.EXE.  %@NL@%
  5980. %@NL@%
  5981. The same technique is suitable for description files with more than one
  5982. top-level target. List all of the top-level targets as dependents of %@AS@% ALL%@AE@%:  %@NL@%
  5983. %@NL@%
  5984. %@AS@%  ALL : pmapp.exe second.exe another.exe%@AE@%%@NL@%
  5985. %@NL@%
  5986. The example updates the targets PMAPP.EXE, SECOND.EXE, and ANOTHER.EXE.  %@NL@%
  5987. %@NL@%
  5988. If the description file lists a single, top-level target, you can use an
  5989. even simpler technique. Move the top-level block to the beginning of the
  5990. file:  %@NL@%
  5991. %@NL@%
  5992. %@AS@%  pmapp.exe : pmapp.obj pmapp.def
  5993. %@AS@%     LINK pmapp, /align:16, NUL, os2, pmapp
  5994. %@AS@%  
  5995. %@AS@%  pmapp.obj : pmapp.c
  5996. %@AS@%     CL /c /G2sw /W3 pmapp.c%@AE@%%@NL@%
  5997. %@NL@%
  5998. NMAKE updates the second target (PMAPP.OBJ) whenever needed to keep the
  5999. first target (PMAPP.EXE) current.  %@NL@%
  6000. %@NL@%
  6001. %@NL@%
  6002. %@NL@%
  6003. %@NL@%
  6004. %@NL@%
  6005. %@NL@%
  6006. %@CR:C6A00070001 @%%@1@%%@AB@%Chapter 7  Creating Help Files with HELPMAKE%@AE@%%@EH@%%@NL@%
  6007. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6008. %@NL@%
  6009. If you have used PWB or other Microsoft language products such as QuickC,
  6010. you are familiar with the many advantages of on-line help. The Microsoft
  6011. Help-File-Creation Utility (HELPMAKE) allows you to create your own help
  6012. files for use with Microsoft products. It also allows you to customize the
  6013. help files supplied with Microsoft language products.  %@NL@%
  6014. %@NL@%
  6015. HELPMAKE translates help text files into a help database accessible from
  6016. within the following:  %@NL@%
  6017. %@NL@%
  6018. %@NL@%
  6019.   ■   Microsoft C 6.0 Programmer's WorkBench (PWB)%@NL@%
  6020. %@NL@%
  6021.   ■   QuickHelp Utility%@NL@%
  6022. %@NL@%
  6023.   ■   Microsoft Editor 1.02%@NL@%
  6024. %@NL@%
  6025.   ■   Microsoft QuickC 2.0%@NL@%
  6026. %@NL@%
  6027.   ■   Microsoft QuickPascal 1.0%@NL@%
  6028. %@NL@%
  6029.   ■   Microsoft QuickBASIC 4.5%@NL@%
  6030. %@NL@%
  6031. %@NL@%
  6032. This chapter describes how to create and modify help files using the
  6033. HELPMAKE utility.  %@NL@%
  6034. %@NL@%
  6035. %@NL@%
  6036. %@2@%%@CR:C6A00070002 @%%@AB@%7.1  Structure and Contents of a Help Database%@AE@%%@EH@%%@NL@%
  6037. %@NL@%
  6038. HELPMAKE creates a help database from one or more input files that contain
  6039. information formatted for the help system. This section defines some of the
  6040. terms involved in formatting and outlines the formats that HELPMAKE can
  6041. process.  %@NL@%
  6042. %@NL@%
  6043. %@NL@%
  6044. %@3@%%@CR:C6A00070003 @%%@AB@%7.1.1  Contents of a Help File%@AE@%%@EH@%%@NL@%
  6045. %@NL@%
  6046. As you might expect, each help text file starts with a topic and some
  6047. information about the topic, then lists another topic and some information
  6048. about it, and so on. In HELPMAKE terminology, topics are called "contexts";
  6049. the information is called "topic text."  %@NL@%
  6050. %@NL@%
  6051. The %@AB@%.context%@AE@% command introduces a context. In the source file for C 6.0
  6052. help, for example, this line introduces help for the %@AB@%open%@AE@% function:  %@NL@%
  6053. %@NL@%
  6054. %@AS@%  .context open%@AE@%%@NL@%
  6055. %@NL@%
  6056. The %@AB@%.context%@AE@% command and other formatting elements are described in Section
  6057. 7.5, "Help Text Conventions."  %@NL@%
  6058. %@NL@%
  6059. Whether a context is one or several words depends on the application.
  6060. QuickBASIC, for example, considers spaces to be delimiters, so in QuickBASIC
  6061. help files contexts are limited to a single word. Other applications, such
  6062. as the Microsoft Editor, can handle contexts that span several words. Either
  6063. way, the application simply hands the context to an internal "help engine,"
  6064. which searches the database for information.  %@NL@%
  6065. %@NL@%
  6066. Often, especially with library routines, the same information applies to
  6067. more than one subject. For example, the string-to-number functions %@AB@%strtod%@AE@%,
  6068. %@AB@%strtol%@AE@%, and %@AB@%stroul%@AE@% share the same help text. The help file lists all three
  6069. function names as contexts for one block of topic text. The converse,
  6070. however, is not true. You cannot specify different blocks of topic text, in
  6071. different places in the help file, to describe a single subject.  %@NL@%
  6072. %@NL@%
  6073. %@AU@% Cross-references help you navigate through  a help database.%@AE@%  %@NL@%
  6074. %@NL@%
  6075. Cross-references make it possible to view information about related topics,
  6076. including header files and code examples. The help for the %@AB@%open%@AE@% function,
  6077. for example, references the %@AB@%access%@AE@% function and the ASCII header file
  6078. FCNTL.H. Cross-references can point to other contexts in the same help
  6079. database, to contexts in other help databases, or to ASCII files outside the
  6080. database.  %@NL@%
  6081. %@NL@%
  6082. Help files can have two kinds of cross-references:  %@NL@%
  6083. %@NL@%
  6084. %@NL@%
  6085.   ■   Implicit%@NL@%
  6086. %@NL@%
  6087.   ■   Explicit, or hyperlinks%@NL@%
  6088. %@NL@%
  6089. %@NL@%
  6090. %@AU@% Implicit cross-references  are coded with an ordinary .context command.%@AE@%  %@NL@%
  6091. %@NL@%
  6092. The word "open" is an implicit cross-reference throughout C 6.0 help. If you
  6093. select the word "open" anywhere in C 6.0 help, the help system displays
  6094. information on the %@AB@%open%@AE@% function. As illustrated above, the context for %@AB@%open%@AE@%
  6095. begins with an ordinary %@AB@%.context%@AE@% command. As a result, anywhere that you
  6096. select "open," the help system references this context.  %@NL@%
  6097. %@NL@%
  6098. %@AU@% Hyperlinks are explicit cross-references marked  by invisible text.%@AE@%  %@NL@%
  6099. %@NL@%
  6100. A "hyperlink" is an explicit cross-reference tied to a word or phrase at a
  6101. specific location in the help file. You create hyperlinks when you write the
  6102. help text. The hyperlink consists of a word or phrase followed by invisible
  6103. text that gives the context to which the hyperlink refers.  %@NL@%
  6104. %@NL@%
  6105. For example, to cause an instance of the word "formatting" to display help
  6106. on the %@AB@%printf%@AE@% function, you would create an explicit cross-reference from
  6107. the word "formatting" to the context "printf." Elsewhere in the file,
  6108. "formatting" has no special significance but, at that one position, it
  6109. references the help for %@AB@%printf%@AE@%.  Section 7.5.4 describes how to create
  6110. hyperlinks.  %@NL@%
  6111. %@NL@%
  6112. %@AU@% Formatting flags let you change the appearance of text.%@AE@%  %@NL@%
  6113. %@NL@%
  6114. Help text can also include formatting flags to control the appearance of the
  6115. text on the screen. Using these flags, you can make certain words appear in
  6116. various colors, inverse video, and so forth, depending on the application
  6117. displaying help and the graphics capabilities of the host computer.  %@NL@%
  6118. %@NL@%
  6119. %@NL@%
  6120. %@3@%%@CR:C6A00070004 @%%@AB@%7.1.2  Help File Formats%@AE@%%@EH@%%@NL@%
  6121. %@NL@%
  6122. You can create help files using any of three formats:  %@NL@%
  6123. %@NL@%
  6124. %@NL@%
  6125.   ■   QuickHelp format%@NL@%
  6126. %@NL@%
  6127.   ■   Rich Text Format (RTF)%@NL@%
  6128. %@NL@%
  6129.   ■   Minimally formatted ASCII%@NL@%
  6130. %@NL@%
  6131. %@NL@%
  6132. In addition, you can reference unformatted ASCII files, such as include
  6133. files, from within a help database.  %@NL@%
  6134. %@NL@%
  6135. An entire help system (such as the one supplied with Microsoft C or
  6136. QuickBASIC) can use any combination of files formatted with different format
  6137. types. With C, for example, the README.DOC information file is encoded as
  6138. minimally formatted ASCII; the help files for the PWB, C language, and
  6139. run-time library are encoded in the QuickHelp format. The database also
  6140. cross-references the header (include) files, which are unformatted ASCII
  6141. files stored outside the database.  %@NL@%
  6142. %@NL@%
  6143. %@NL@%
  6144. %@4@%%@AB@%QuickHelp%@AE@%%@EH@%%@NL@%
  6145. %@NL@%
  6146. QuickHelp format is the default and is the format into which HELPMAKE
  6147. decodes help databases. Use any text editor to create a QuickHelp-format
  6148. help text file. QuickHelp format also lends itself to a relatively easy
  6149. automated translation from other document formats.  %@NL@%
  6150. %@NL@%
  6151. QuickHelp files can contain any kind of cross-reference or formatting
  6152. attribute. Typically, you use QuickHelp format for any changes to a database
  6153. supplied by Microsoft.  %@NL@%
  6154. %@NL@%
  6155. %@NL@%
  6156. %@4@%%@AB@%RTF%@AE@%%@EH@%%@NL@%
  6157. %@NL@%
  6158. Rich Text Format (RTF) is a Microsoft word-processing format that many other
  6159. word processors also support. You can create RTF help text with any word
  6160. processor that generates RTF output. You can also use any utility program
  6161. that takes word-processor output and produces an RTF file.  %@NL@%
  6162. %@NL@%
  6163. Use RTF when you want to transfer help files from one application to another
  6164. while retaining formatting information. You can format RTF files directly
  6165. with the word-processing program; you need not edit them to insert any
  6166. special commands or tags. Like QuickHelp files, RTF files can contain
  6167. formatting attributes and cross-references.  %@NL@%
  6168. %@NL@%
  6169. %@NL@%
  6170. %@4@%%@AB@%Minimally Formatted ASCII%@AE@%%@EH@%%@NL@%
  6171. %@NL@%
  6172. Minimally formatted ASCII files simply define contexts and their topic text.
  6173. These files cannot contain screen-formatting commands or explicit
  6174. crossreferences (implicit cross-references are allowed). They are often used
  6175. to display text such as README.DOC and small help files that do not require
  6176. compression.  %@NL@%
  6177. %@NL@%
  6178. %@NL@%
  6179. %@4@%%@AB@%Unformatted ASCII%@AE@%%@EH@%%@NL@%
  6180. %@NL@%
  6181. Unformatted ASCII files are exactly what their name implies: regular ASCII
  6182. files with no special formatting commands, context definitions, or special
  6183. information. An unformatted ASCII file does not become part of the help
  6184. database. Only its name is used as the object of a cross-reference. The
  6185. standard C header (include) files are unformatted ASCII files used for
  6186. cross-references by the help system for the C run-time library. Unformatted
  6187. ASCII files are also useful for storing program examples.  %@NL@%
  6188. %@NL@%
  6189. %@NL@%
  6190. %@2@%%@CR:C6A00070005 @%%@AB@%7.2  Invoking HELPMAKE%@AE@%%@EH@%%@NL@%
  6191. %@NL@%
  6192. The HELPMAKE program can encode or decode help files, allowing you to create
  6193. new help files or modify existing ones. Encoding converts a text file to a
  6194. compressed help database. HELPMAKE can encode text files written in
  6195. QuickHelp, RTF, and minimally formatted ASCII format. Decoding converts a
  6196. help database to a text file for editing. HELPMAKE always decodes a help
  6197. database into a QuickHelp format text file.  %@NL@%
  6198. %@NL@%
  6199. Invoke HELPMAKE with the following syntax:  %@NL@%
  6200. %@NL@%
  6201. %@AS@%  HELPMAKE «options» { /En | /D } { sourcefiles }%@AE@%%@NL@%
  6202. %@NL@%
  6203. The %@AI@%options%@AE@% modify the action of HELPMAKE; they are described in Section
  6204. 7.3.  %@NL@%
  6205. %@NL@%
  6206. %@AU@% Use the /E option to encode with HELPMAKE and use the /D option to decode.%@AE@%
  6207. %@NL@%
  6208. %@NL@%
  6209. You must supply either the /E (encode) or the /D (decode) option. When
  6210. encoding (/E) to create a help database, you must use the /O option to
  6211. specify the file name of the database.  %@NL@%
  6212. %@NL@%
  6213. The %@AI@%sourcefile%@AE@% field is required. It specifies the input file for HELPMAKE.
  6214. If you use the /D (decode) option, %@AI@%sourcefile%@AE@% can be one or more help
  6215. database files (such as QC.HLP). HELPMAKE decodes the database files into a
  6216. single text file. If you use the /E (encode) option, %@AI@%sourcefile%@AE@% can be one
  6217. or more help text files (such as QC.SRC). Separate file names with a space.
  6218. Standard wild-card characters can also be used.  %@NL@%
  6219. %@NL@%
  6220. The example below invokes HELPMAKE with the /V, /E, and /O options (see
  6221. Section 7.3.1, "Options for Encoding"). HELPMAKE reads input from the text
  6222. file %@AS@% my.txt %@AE@% and writes the compressed help database in the file %@AS@% my.hlp%@AE@%.
  6223. The /E option causes maximum compression. Note that the DOS redirection
  6224. symbol (>) sends a log of HELPMAKE activity to the file %@AS@% my.log%@AE@%. You may
  6225. find it helpful to redirect the log file because, in its more verbose modes
  6226. (given by /V), HELPMAKE may generate a lengthy log.  %@NL@%
  6227. %@NL@%
  6228. %@AS@%  HELPMAKE /V /E /Omy.hlp my.txt > my.log%@AE@%%@NL@%
  6229. %@NL@%
  6230. The example below invokes HELPMAKE to decode the help database %@AS@% my.hlp %@AE@% into
  6231. the text file %@AS@% my.src%@AE@%, given with the /O option. Once again, the /V option
  6232. results in verbose output, and the output is directed to the log file %@AS@%
  6233. %@AS@%my.log%@AE@%. Section 7.3.2 describes additional options for decoding.  %@NL@%
  6234. %@NL@%
  6235. %@AS@%  HELPMAKE /V /D /Omy.src my.hlp > my.log%@AE@%%@NL@%
  6236. %@NL@%
  6237. %@NL@%
  6238. %@2@%%@CR:C6A00070006 @%%@AB@%7.3  HELPMAKE Options%@AE@%%@EH@%%@NL@%
  6239. %@NL@%
  6240. HELPMAKE accepts a number of command-line options, which are described
  6241. below. You can specify options in uppercase or lowercase letters, and
  6242. precede them with either a forward slash ( / ) or a dash (-). For example,
  6243. -L, /L, -l, and /l all represent the same option. Most options apply only to
  6244. encoding; others apply only to decoding; and a few apply to both.  %@NL@%
  6245. %@NL@%
  6246. %@NL@%
  6247. %@3@%%@CR:C6A00070007 @%%@AB@%7.3.1  Options for Encoding%@AE@%%@EH@%%@NL@%
  6248. %@NL@%
  6249. When you encode a file─that is, when you build a help database─you must
  6250. specify the /E option. In addition, you can supply various other options
  6251. that control the way HELPMAKE works. All the options that apply when
  6252. encoding are listed below:  %@NL@%
  6253. %@NL@%
  6254. %@AB@%Option%@AE@%                            %@AB@%Action%@AE@%
  6255. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6256. /A%@AI@%c%@AE@%                               Specifies %@AI@%c%@AE@% as an application-specific 
  6257.                                   control character for the help database 
  6258.                                   file. The character marks a line that 
  6259.                                   contains special information for 
  6260.                                   internal use by the application. For 
  6261.                                   example, QuickC uses the colon (%@AB@%:%@AE@%).
  6262.  
  6263. /C                                Indicates that the context strings for 
  6264.                                   this help file are case sensitive. At 
  6265.                                   run time, all searches for help topics 
  6266.                                   are case sensitive if the help database 
  6267.                                   was built with the /C option in effect.
  6268.  
  6269. /E«%@AI@%n%@AE@%»                             Creates (encodes) a help database from a
  6270.                                   specified text file. The optional %@AI@%n%@AE@% 
  6271.                                   indicates the amount of compression to 
  6272.                                   take place. If %@AI@%n%@AE@% is omitted, HELPMAKE 
  6273.                                   compresses the file as much as possible,
  6274.                                   thereby reducing the size of the file by
  6275.                                   about 50%. The more compression 
  6276.                                   requested, the longer HELPMAKE takes to 
  6277.                                   create a database file. The value of %@AI@%n%@AE@% 
  6278.                                   is a number in the range 0 - 15. It is 
  6279.                                   the sum of successive powers of 2 
  6280.                                   representing various compression 
  6281.                                   techniques, as listed below:
  6282.  
  6283.                                   %@AB@%Value%@AE@%       %@AB@%Technique%@AE@%
  6284. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6285.                                   0           No compression
  6286.  
  6287.                                   1           Run-length compression
  6288.  
  6289.                                   2           Key word compression
  6290.  
  6291.                                   4           Extended key word
  6292.                                               compression
  6293.  
  6294.                                   8           Huffman compression
  6295.  
  6296.                                   Add values to combine compression 
  6297.                                   techniques. For example, use /E3 to get 
  6298.                                   run-length and key word compression. 
  6299.                                   This is useful in the testing stages of 
  6300.                                   creating a help database when you need 
  6301.                                   to create the database quickly and are 
  6302.                                   not too concerned with size.
  6303.  
  6304. /H                                Displays a summary of HELPMAKE syntax 
  6305.                                   and exits.
  6306.  
  6307. /HELP                             Invokes QH.EXE, the QuickHelp utility, 
  6308.                                   for help about HELPMAKE. If QuickHelp is
  6309.                                   not available, displays the same 
  6310.                                   information as the /H option.
  6311.  
  6312. /K %@AI@%filename%@AE@%                       Optimizes key word compression by 
  6313.                                   supplying a
  6314.                                   list of characters that act as word 
  6315.                                   separators. The %@AI@%filename%@AE@% is a file 
  6316.                                   containing your list of separator 
  6317.                                   characters.
  6318.  
  6319.                                   When you select key word compression, 
  6320.                                   HELPMAKE scans the help file to identify
  6321.                                   "key words." A key word is any word that
  6322.                                   occurs often enough to justify replacing
  6323.                                   it with a shorter character sequence. 
  6324.                                   HELPMAKE normally uses the following 
  6325.                                   characters as word separators:
  6326.  
  6327.                                   ■ All characters from 0-32 (including 
  6328.                                   the space)
  6329.  
  6330.                                   ■ !"#&'( )*+'-, /:;<=>?@[\]^_`{|}~
  6331.  
  6332.                                   ■ 127
  6333.  
  6334.                                   When performing key word compression, 
  6335.                                   HELPMAKE treats as a word any series of 
  6336.                                   characters not appearing in the 
  6337.                                   separator list.
  6338.  
  6339.                                   Depending on the content of your help 
  6340.                                   file, you may be able to improve key 
  6341.                                   word compression by using the /K option 
  6342.                                   to specify a different list of separator
  6343.                                   characters. For instance, the default 
  6344.                                   separator list contains the number sign 
  6345.                                   (#). If your help file contains %@AB@%#include%@AE@%
  6346.                                   directives, HELPMAKE normally treats %@AB@%%@AE@%
  6347.                                   %@AB@%#include%@AE@% as the word %@AB@%include%@AE@% without a 
  6348.                                   number sign. To cause HELPMAKE to treat %@AB@%%@AE@%
  6349.                                   %@AB@%#include%@AE@% as a word, you could specify 
  6350.                                   the following separator list:
  6351.  
  6352.                                   %@AS@%                     %@AE@%
  6353.                                   %@AS@%!"&'()*+'-,/:;<=>?@[\]^_`{|}~%@AE@%
  6354.  
  6355.                                   The list above does not include the 
  6356.                                   number sign. HELPMAKE always treats 
  6357.                                   characters in the range
  6358.                                   0-32 as separators, so you do not need 
  6359.                                   to include them. Your list must include 
  6360.                                   all the other characters you want 
  6361.                                   HELPMAKE to use as separators, including
  6362.                                   the space.
  6363.  
  6364. /L                                Locks the generated file so that it 
  6365.                                   cannot be decoded by HELPMAKE at a later
  6366.                                   time.
  6367.  
  6368. /O%@AI@%destfile%@AE@%                        Specifies %@AI@%destfile%@AE@% as the name of the 
  6369.                                   help database.
  6370.  
  6371. /S%@AI@%n%@AE@%                               Specifies the type of input file, 
  6372.                                   according to the following %@AI@%n%@AE@% values:
  6373.  
  6374.                                   %@AB@%Option%@AE@%      %@AB@%File%@AE@% %@AB@%Type%@AE@%
  6375. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6376.                                   /S1         Rich Text Format (RTF)
  6377.  
  6378.                                   /S2         QuickHelp (default)
  6379.  
  6380.                                   /S3         Minimally formatted ASCII
  6381.  
  6382. /T                                Translates dot commands into internal 
  6383.                                   format. If your help file contains dot 
  6384.                                   commands other than %@AB@%.context%@AE@%, you should
  6385.                                   supply this option when encoding it. Dot
  6386.                                   commands are described in Section 7.6.1,
  6387.                                   "QuickHelp Format," and in later 
  6388.                                   sections.
  6389.  
  6390. /V«%@AI@%n%@AE@%»                             Indicates the verbosity of diagnostic 
  6391.                                   and informational output, depending on 
  6392.                                   the value of %@AI@%n%@AE@%. Increasing the value 
  6393.                                   adds more information to the output. If 
  6394.                                   you omit this option or specify only /V,
  6395.                                   HELPMAKE gives you its most verbose 
  6396.                                   output. The possible values of %@AI@%n%@AE@% are 
  6397.                                   listed below:
  6398.  
  6399.                                   %@AB@%Option%@AE@%      %@AB@%Effect%@AE@%
  6400. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6401.                                   /V          Maximum diagnostic output
  6402.  
  6403.                                   /V0         No diagnostic output and no 
  6404.                                               banner
  6405.  
  6406.                                   /V1         Prints only HELPMAKE banner 
  6407.                                               (default)
  6408.  
  6409.                                   /V2         Prints pass names
  6410.  
  6411.                                   /V3         Prints contexts on first 
  6412.                                               pass
  6413.  
  6414.                                   /V4         Prints contexts on each pass
  6415.  
  6416.                                   /V5         Prints any intermediate 
  6417.                                               steps within each pass
  6418.  
  6419.                                   /V6         Prints statistics on help 
  6420.                                               file and compression
  6421.  
  6422. /W%@AI@%width%@AE@%                           Indicates the fixed width of the 
  6423.                                   resulting help text in number of 
  6424.                                   characters. The values of %@AI@%width%@AE@% can 
  6425.                                   range from 11 to 255. If the /W option 
  6426.                                   is omitted, the default is 76. When 
  6427.                                   encoding RTF source (/S1), HELPMAKE 
  6428.                                   automatically formats the text to %@AI@%width%@AE@%.
  6429.                                   When encoding QuickHelp (/S2) or 
  6430.                                   minimally formatted ASCII (/S3) files, 
  6431.                                   HELPMAKE truncates lines to this width.
  6432.  
  6433. %@NL@%
  6434. %@3@%%@CR:C6A00070008 @%%@AB@%7.3.2  Options for Decoding%@AE@%%@EH@%%@NL@%
  6435. %@NL@%
  6436. To decode a help database into QuickHelp files, you must use the /D option.
  6437. In addition, HELPMAKE accepts other options to control the decoding process.
  6438. The list below shows all the options that are valid when decoding:  %@NL@%
  6439. %@NL@%
  6440. %@AB@%Option%@AE@%                            %@AB@%Action%@AE@%
  6441. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6442. /D«%@AI@%letter%@AE@%»                        Decodes the input file into its original
  6443.                                   text or component parts. If a 
  6444.                                   destination file is not specified with 
  6445.                                   the /O option, the help file is decoded 
  6446.                                   to %@AB@%stdout%@AE@%. HELPMAKE decodes the file 
  6447.                                   differently depending on the letter 
  6448.                                   specified:
  6449.  
  6450.                                   %@AB@%Letter%@AE@%      %@AB@%Effect%@AE@%
  6451. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6452.                                   /D          "Decode." Fully decodes the 
  6453.                                               help database, leaving all 
  6454.                                               cross-references and 
  6455.                                               formatting information 
  6456.                                               intact.
  6457.  
  6458.                                   /DS         "Decode split." Splits the 
  6459.                                               concatenated, compressed 
  6460.                                               help database into its 
  6461.                                               components using their 
  6462.                                               original names. If the 
  6463.                                               database was created without
  6464.                                               concatenation (the default),
  6465.                                               HELPMAKE simply copies it to
  6466.                                               a file with its original 
  6467.                                               name. No decompression 
  6468.                                               occurs.
  6469.  
  6470.                                   /DU         "Decode unformatted." 
  6471.                                               Decompresses the database 
  6472.                                               and removes all screen 
  6473.                                               formatting and 
  6474.                                               cross-references. The output
  6475.                                               can still be used later for 
  6476.                                               input and recompression, but
  6477.                                               all screen formatting and 
  6478.                                               cross-references are lost.
  6479.  
  6480. /H                                Displays a summary of HELPMAKE syntax 
  6481.                                   and exits without encoding or decoding 
  6482.                                   any files.
  6483.  
  6484. /HELP                             Invokes QH.EXE, the QuickHelp utility, 
  6485.                                   for information about HELPMAKE. If 
  6486.                                   QuickHelp is not available, displays the
  6487.                                   same information as the /H option.
  6488.  
  6489. /O%@AI@%destfile%@AE@%                        Specifies %@AI@%destfile%@AE@% for the decoded 
  6490.                                   output from HELPMAKE. If %@AI@%destfile%@AE@% is 
  6491.                                   omitted, the help database is decoded to
  6492.                                   %@AB@%stdout%@AE@%. HELPMAKE always decodes help 
  6493.                                   database files into QuickHelp format.
  6494.  
  6495. /T                                Translates dot commands from internal 
  6496.                                   format into dot-command format. You 
  6497.                                   should always supply this option when 
  6498.                                   decoding a help database that contains 
  6499.                                   dot commands other than %@AB@%.context%@AE@%.
  6500.  
  6501. /V«%@AI@%n%@AE@%»                             Indicates the verbosity of diagnostic 
  6502.                                   and informational output depending on 
  6503.                                   the value of %@AI@%n%@AE@%. The possible values are 
  6504.                                   listed below. If you omit this option or
  6505.                                   specify only /V, HELPMAKE gives you its 
  6506.                                   most verbose output.
  6507.  
  6508.                                   %@AB@%Option%@AE@%      %@AB@%Effect%@AE@%
  6509. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6510.                                   /V          Maximum diagnostic output
  6511.  
  6512.                                   /V0         No diagnostic output and no 
  6513.                                               banner
  6514.  
  6515.                                   /V1         Prints only the HELPMAKE 
  6516.                                               banner
  6517.  
  6518.                                   /V2         Prints pass names
  6519.  
  6520.                                   /V3         Prints contexts on first 
  6521.                                               pass
  6522.  
  6523. %@NL@%
  6524. %@2@%%@CR:C6A00070009 @%%@AB@%7.4  Creating a Help Database%@AE@%%@EH@%%@NL@%
  6525. %@NL@%
  6526. You can create a Microsoft-compatible help database by either of two
  6527. methods.  %@NL@%
  6528. %@NL@%
  6529. The first method is to decompress an existing help database, modify the
  6530. resulting help text file, and recompress the help text file to form a new
  6531. database.  %@NL@%
  6532. %@NL@%
  6533. The second and simpler method is to append a new help database to an
  6534. existing help database. This method involves the following steps:  %@NL@%
  6535. %@NL@%
  6536. %@NL@%
  6537.   1.  Create a help text file in QuickHelp format, RTF, or minimally
  6538.       formatted ASCII.%@NL@%
  6539. %@NL@%
  6540.   2.  Use HELPMAKE to create a help database file. The example below invokes
  6541.       HELPMAKE, using SAMPLE.TXT as the input file and producing a help
  6542.       database file named %@AS@% sample.hlp%@AE@%:
  6543. %@NL@%
  6544. %@AS@%      HELPMAKE /V /E /Osample.hlp sample.txt > sample.log%@AE@%%@NL@%
  6545. %@NL@%
  6546. %@NL@%
  6547.   3.  Make a backup copy of the existing database file (for safety's sake).%@NL@%
  6548. %@NL@%
  6549.   4.  Append the new help database file to the existing help database. The
  6550.       example below concatenates the new database %@AS@% sample.hlp %@AE@% onto the end
  6551.       of the CLANG.HLP database:
  6552. %@NL@%
  6553. %@AS@%      COPY clang.hlp /b + sample.hlp /b%@AE@%%@NL@%
  6554. %@NL@%
  6555. %@NL@%
  6556.   5.  Test the database. The %@AS@% sample.hlp %@AE@% database contains the context %@AS@%
  6557. %@AS@%      sample%@AE@%. If you type the word "sample" in the PWB and request help on
  6558.       it, the help window displays the text associated with the context %@AS@%
  6559. %@AS@%      sample%@AE@%.%@NL@%
  6560. %@NL@%
  6561. %@NL@%
  6562. %@NL@%
  6563. %@2@%%@CR:C6A00070010 @%%@AB@%7.5  Help Text Conventions%@AE@%%@EH@%%@NL@%
  6564. %@NL@%
  6565. Microsoft help databases have a common structure and follow certain
  6566. organizational conventions. You should follow the same conventions to create
  6567. Microsoft-compatible help files.  %@NL@%
  6568. %@NL@%
  6569. %@NL@%
  6570. %@3@%%@CR:C6A00070011 @%%@AB@%7.5.1  Structure of the Help Text File%@AE@%%@EH@%%@NL@%
  6571. %@NL@%
  6572. The help-retrieval capability that is built into Microsoft products is
  6573. simply a data-retrieval tool. It imposes no restrictions on the content and
  6574. format of the help text. The HELPMAKE utility and the display routines built
  6575. into Microsoft language environments, however, make certain assumptions
  6576. about the format of help text. This section provides some guidelines for
  6577. creating help text files compatible with those assumptions.  %@NL@%
  6578. %@NL@%
  6579. In all three help text formats, the help text source file is a sequence of
  6580. topics, each preceded by one or more unique context definitions. The
  6581. following list specifies the various formats and the corresponding context
  6582. definition statements:  %@NL@%
  6583. %@NL@%
  6584. %@AB@%Format %@AE@%                           %@AB@%Context Definition%@AE@%
  6585. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6586. QuickHelp                         %@AB@%.context %@AE@%%@AI@%context%@AE@%
  6587.  
  6588. RTF                               \ par %@AI@%>>context%@AE@% \ par
  6589.  
  6590. Minimally formatted               %@AI@%>>context%@AE@%
  6591.  
  6592. ASCII                             (none)
  6593.  
  6594. In QuickHelp format, each topic begins with one or more %@AB@%.context%@AE@% statements
  6595. that define the context strings that map to the topic text. Subsequent lines
  6596. up to the next %@AB@%.context%@AE@% statement constitute the topic text.  %@NL@%
  6597. %@NL@%
  6598. In RTF format, each context definition must be in a paragraph of its own
  6599. (denoted by \ par), beginning with the help delimiter (>>). Subsequent
  6600. paragraphs up to the next context definition constitute the topic text.  %@NL@%
  6601. %@NL@%
  6602. In minimally formatted ASCII, each context definition must be on a separate
  6603. line, and each must begin with the help delimiter (>>). As in RTF and
  6604. QuickHelp files, subsequent lines up to the next context definition
  6605. constitute the topic text.  %@NL@%
  6606. %@NL@%
  6607. See Section 7.6, "Using Help Database Formats," for detailed information
  6608. about these three formats.  %@NL@%
  6609. %@NL@%
  6610. %@NL@%
  6611. %@3@%%@CR:C6A00070012 @%%@AB@%7.5.2  Local Contexts%@AE@%%@EH@%%@NL@%
  6612. %@NL@%
  6613. Context strings that begin with an "at" sign (@) are defined as "local" and
  6614. have no implicit cross-references. They are used in cross-references instead
  6615. of the context string that otherwise is generated.%@CR:C6A00070013 @%  %@NL@%
  6616. %@NL@%
  6617. When you use a local context, HELPMAKE does not generate a global context
  6618. string (a context string that is known throughout the help file). Instead,
  6619. it embeds an encoded cross-reference that has meaning only within the
  6620. current context. For example,  %@NL@%
  6621. %@NL@%
  6622. %@AS@%  .context normal
  6623. %@AS@%  This is a normal topic, accessible by the context string "normal."
  6624. %@AS@%  [button\v@local\v] is a cross-reference to the following topic.
  6625. %@AS@%  
  6626. %@AS@%  .context @local
  6627. %@AS@%  
  6628. %@AS@%  This topic can be reached only if the user browses
  6629. %@AS@%  sequentially through the file or uses the cross-reference
  6630. %@AS@%  in the previous topic.%@AE@%%@NL@%
  6631. %@NL@%
  6632. In the example above, the text %@AS@% [button\v@local\v] %@AE@% defines %@AS@% local %@AE@% as a
  6633. local context. If the user selects the text %@AS@% [button] %@AE@% or scrolls through
  6634. the file, the help system displays the topic text that follows the context
  6635. definition for %@AS@% local%@AE@%. Because %@AS@% local %@AE@% is defined with the "at" sign (@), it
  6636. can be accessed only by a hyperlink within the help file or by sequentially
  6637. browsing through the file. Making a context local saves file space and
  6638. speeds access.  %@NL@%
  6639. %@NL@%
  6640. %@NL@%
  6641. %@3@%%@CR:C6A00070014 @%%@AB@%7.5.3  Context Prefixes%@AE@%%@EH@%%@NL@%
  6642. %@NL@%
  6643. Microsoft help databases use several context prefixes. A "context prefix" is
  6644. a single letter followed by a period. It appears before a context string
  6645. that has a predefined meaning. If you decode a Microsoft help database, many
  6646. of these contexts may appear in the resulting text file.  %@NL@%
  6647. %@NL@%
  6648. %@AU@% Most context prefixes are internal. %@AE@%  %@NL@%
  6649. %@NL@%
  6650. Except for the h. prefix, which is described below, context prefixes are
  6651. internal. You do not need to add them in help files that you write.  %@NL@%
  6652. %@NL@%
  6653. You can use the h. prefix to identify standard help-file contexts. For
  6654. instance, h.default identifies the default help screen: the screen that
  6655. normally appears when you select "top-level" help. Table 7.1 lists the
  6656. standard h. contexts.  %@NL@%
  6657. %@NL@%
  6658. %@AB@%Table 7.1  %@AB@%Standard h. Contexts%@AE@%%@AE@%
  6659.  
  6660. %@TH:  43  2399 02 34 42 @%Context                           Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%h.contents                        The table of contents for the help file.                                  You should also define the string                                   "contents" for direct reference to this                                   context.h.default                         The default help screen, typically                                   displayed when the user presses SHIFT+F1                                  at the "top level" in most applications.                                  The contents are generally devoted to                                   information about using help.h.index                           The index for the help file.  You can                                   also define the string "index" for                                   direct reference to this context.h.notfound                        The help text that is displayed when the                                  help system cannot find information                                   about the requested context. The text                                   could be an index of contexts, a topical                                  list, or general information about using                                  help.h.pg#                             A specific page within the help file.                                   This is used in response to a "go to                                   page #" request.h.pg$                             The help text that is logically last in                                   the file. This is used by some                                   applications in response to a "go to the                                  end" request made within the help window.h.pg1                             The help text that is logically first in                                  the file. This is used by some                                   applications in response to a "go to the                                  beginning" request made within the help                                   window.h.title                           The title of the help database.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  43  2399 02 34 42 @%
  6661.  
  6662. The context prefixes in Table 7.2 are internal to Microsoft products. They
  6663. appear in decompressed databases, but you do not need to use them.  %@NL@%
  6664. %@NL@%
  6665. %@AB@%Table 7.2  %@AB@%Microsoft Product Context Prefixes%@AE@%%@AE@%
  6666.  
  6667. %@TH:  28  1705 02 34 42 @%Prefix                            Purpose%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%d.                                Dialog box. Each dialog box is assigned                                   a number. Its help context string is d.                                   followed by the number (for example, %@AS@% %@AE@%                                  %@AS@%d.12%@AE@%).e.                                Error number. If a product supports the                                   error-numbering scheme used by Microsoft                                  languages, it displays help for each                                   error using this prefix. For example,                                   the context %@AS@% e.c1234 %@AE@% refers to the C                                   compiler error message number C1234.m.                                Menu item. Contexts that relate to                                   product menu items are defined by their                                   accelerator keys. For example, the Exit                                   selection on the FILE menu item is                                   accessed by ALT+F X and is referenced in                                  help by %@AS@% m.f.x%@AE@%.n.                                Message number. Each message box is                                   assigned a number. Its help context                                   string is n. plus the number (for                                   example, %@AS@% n.5 %@AE@%).%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  28  1705 02 34 42 @%
  6668.  
  6669. %@NL@%
  6670. %@3@%%@CR:C6A00070015 @%%@AB@%7.5.4  Hyperlinks%@AE@%%@EH@%%@NL@%
  6671. %@NL@%
  6672. Explicit cross-references, or hyperlinks, in the help text file are marked
  6673. with invisible text. A hyperlink comprises a word or phrase followed by
  6674. invisible text that gives the context to which the hyperlink refers.  %@NL@%
  6675. %@NL@%
  6676. The keystroke that activates the hyperlink depends on the application.
  6677. Consult the documentation for each product to find the specific keystroke
  6678. needed.  %@NL@%
  6679. %@NL@%
  6680. When the user activates the hyperlink, the help system displays the topic
  6681. named by the invisible text. The invisible cross-reference text is formatted
  6682. as one of the following:  %@NL@%
  6683. %@NL@%
  6684. %@AB@%Hyperlink Text%@AE@%                    %@AB@%Action%@AE@%
  6685. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6686. %@AI@%contextstring%@AE@%                     Causes the help topic associated with %@AI@%%@AE@%
  6687.                                   %@AI@%contextstring%@AE@% to be displayed. For 
  6688.                                   example, %@AS@% exeformat %@AE@% results in the 
  6689.                                   display of the help topic associated 
  6690.                                   with the context %@AS@% exeformat%@AE@%.
  6691.  
  6692. %@AI@%filename%@AE@%!                         Treats %@AI@%filename%@AE@% as a single topic to be 
  6693.                                   displayed. For example, %@AS@% %@AE@%
  6694.                                   %@AS@%$INCLUDE:stdio.h! %@AE@% searches the
  6695.                                   INCLUDE environment variable for file 
  6696.                                   STDIO.H and displays it as a single help
  6697.                                   topic.
  6698.  
  6699. %@AI@%filename%@AE@%!%@AI@%contextstring%@AE@%            Works the same way as %@AI@%contextstring%@AE@% 
  6700.                                   above, except that only the help file %@AI@%%@AE@%
  6701.                                   %@AI@%filename%@AE@% is searched for the context. If
  6702.                                   the file is not already open, the help 
  6703.                                   system finds it (by searching either the
  6704.                                   current path or an explicit environment 
  6705.                                   variable) and opens it. For example, %@AS@% %@AE@%
  6706.                                   %@AS@%$BIN:readme.doc!patches %@AE@% searches for %@AS@% %@AE@%
  6707.                                   %@AS@%readme.doc %@AE@% in the BIN environment 
  6708.                                   variable and displays the topic 
  6709.                                   associated with %@AS@% patches%@AE@%.
  6710.  
  6711. In the following example, the word %@AS@% Example %@AE@% is a hyperlink:  %@NL@%
  6712. %@NL@%
  6713. %@AS@%  \bSee also:\p   \uExample\p\vopen.ex\v%@AE@%%@NL@%
  6714. %@NL@%
  6715. The hyperlink refers to %@AS@% open.ex%@AE@%. If you select any of the letters of %@AS@%
  6716. %@AS@%Example%@AE@%, the help system displays the topic whose context is %@AS@% open.ex%@AE@%. On
  6717. the screen, this line appears as follows:  %@NL@%
  6718. %@NL@%
  6719. %@AS@%  See also:   Example%@AE@%%@NL@%
  6720. %@NL@%
  6721. An application might display %@AS@% See also: %@AE@% and %@AS@% Example %@AE@% in different colors
  6722. or character types, depending on such factors as your default color
  6723. selection and type of monitor.  %@NL@%
  6724. %@NL@%
  6725. When a hyperlink needs to cross-reference more than one word, you must use
  6726. an anchor, as in the following example:  %@NL@%
  6727. %@NL@%
  6728. %@AS@%  \bSee also:\p   \uExample\p\vprintf.ex\v, fprintf, scanf, sprintf,
  6729. %@AS@%  vfprintf, vprintf, vsprintf
  6730. %@AS@%              \aformatting table\vprintf.table\v%@AE@%%@NL@%
  6731. %@NL@%
  6732. This part of the example is an anchored hyperlink:  %@NL@%
  6733. %@NL@%
  6734. %@AS@%  \aformatting table\vprintf.table\v%@AE@%%@NL@%
  6735. %@NL@%
  6736. %@AU@% Anchored hyperlinks must fit on a single line.%@AE@%  %@NL@%
  6737. %@NL@%
  6738. The \ a flag creates an anchor for the cross-reference. In the example, the
  6739. phrase following the \ a flag (%@AS@%formatting table%@AE@%) is the hyperlink. It refers
  6740. to the context %@AS@% printf.table%@AE@%. The first \v flag marks both the end of the
  6741. hyperlink and the beginning of the invisible text. The name %@AS@% printf.table %@AE@%
  6742. is invisible; it does not appear on the screen when the help is displayed.
  6743. The second \v flag ends the invisible text.  %@NL@%
  6744. %@NL@%
  6745. %@NL@%
  6746. %@2@%%@CR:C6A00070016 @%%@AB@%7.6  Using Help Database Formats%@AE@%%@EH@%%@NL@%
  6747. %@NL@%
  6748. The text format of the database can be any of three types. The list below
  6749. briefly describes these types. Sections 7.6.1-7.6.3 describe the formatting
  6750. types in detail.  %@NL@%
  6751. %@NL@%
  6752. An entire help system (such as the one supplied with the Professional
  6753. Development System or QuickC) can use any combination of files formatted
  6754. with different format types. With C, for example, the README.DOC information
  6755. file is encoded as minimally formatted ASCII; and the help files for the C
  6756. language and run-time library are encoded in the QuickHelp format. The
  6757. database also cross-references the header (include) files, which are
  6758. unformatted ASCII files stored outside the database.  %@NL@%
  6759. %@NL@%
  6760. %@AB@%Type%@AE@%                              %@AB@%Characteristics%@AE@%
  6761. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6762. QuickHelp                         Uses dot commands and embedded 
  6763.                                   formatting characters (the default 
  6764.                                   formatting type expected by HELPMAKE); 
  6765.                                   supports highlighting, color, and 
  6766.                                   cross-references. This format must be 
  6767.                                   compressed before using.
  6768.  
  6769. Minimally formatted ASCII         Uses a help delimiter (>>) to define 
  6770.                                   help contexts; does not support 
  6771.                                   highlighting, color, or crossreferences.
  6772.                                   This format can be compressed, but 
  6773.                                   compression is not required.
  6774.  
  6775. RTF                               Uses a subset of standard RTF; supports 
  6776.                                   highlighting, color, and 
  6777.                                   cross-references; supports dot commands.
  6778.                                   This format must be compressed before 
  6779.                                   using.
  6780.  
  6781. %@NL@%
  6782. %@3@%%@CR:C6A00070017 @%%@AB@%7.6.1  QuickHelp Format%@AE@%%@EH@%%@NL@%
  6783. %@NL@%
  6784. The QuickHelp format uses a dot command and embedded formatting flags to
  6785. convey information to HELPMAKE.%@CR:C6A00070018 @%  %@NL@%
  6786. %@NL@%
  6787. %@NL@%
  6788. %@4@%%@AB@%QuickHelp Dot Commands%@AE@%%@EH@%%@NL@%
  6789. %@NL@%
  6790. QuickHelp supports a number of dot commands, which identify topics and
  6791. convey other topic-related information to the help system. If your help file
  6792. contains dot commands other than %@AB@%.context%@AE@%, you must supply the /T option
  6793. when encoding and decoding with HELPMAKE.  %@NL@%
  6794. %@NL@%
  6795. %@AU@% You can define more than one context for a single topic.%@AE@%  %@NL@%
  6796. %@NL@%
  6797. The most important dot command is the %@AB@%.context%@AE@% command. Every topic in a
  6798. QuickHelp file begins with one or more %@AB@%.context%@AE@% commands. Each %@AB@%.context%@AE@%
  6799. command defines a context string for the topic text. You can define more
  6800. than one context for a single topic, as long as you do not place any topic
  6801. text between them.%@CR:C6A00070019 @%  %@NL@%
  6802. %@NL@%
  6803. Typical dot commands are shown below. The first defines a context for the %@AB@%
  6804. %@AB@%#include%@AE@% C preprocessor directive. The second set illustrates multiple
  6805. contexts for one block of topic text. In this case, the same topic text
  6806. explains all of the string-to-number conversion routines in C.  %@NL@%
  6807. %@NL@%
  6808. %@AS@%  .context #include
  6809. %@AS@%         .
  6810. %@AS@%         .description of #include goes here
  6811. %@AS@%         .
  6812. %@AS@%  .context strtod
  6813. %@AS@%  .context strtol
  6814. %@AS@%  .context strtoul
  6815. %@AS@%         .
  6816. %@AS@%         . description of string-to-number functions goes here
  6817. %@AS@%         .%@AE@%%@NL@%
  6818. %@NL@%
  6819. The QuickHelp format supports several other dot commands. Table 7.3 lists
  6820. all of the dot commands available in QuickHelp format.  %@NL@%
  6821. %@NL@%
  6822. %@AB@%Table 7.3  %@AB@%QuickHelp Dot Commands%@AE@%%@AE@%
  6823.  
  6824. %@TH: 100  6368 02 34 42 @%%@AB@%Command%@AE@%                           %@AB@%Action%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%.category%@AE@% %@AI@%string%@AE@%                  Lists the category in which the current                                   topic appears and its position in the                                   list of topics. The category name is                                   used by the QuickHelp Topic command,                                   which brings up the list of topics to                                   which the current topic belongs. Some                                   applications, such as the PWB, use this                                   name as a pointer to the applicable                                   table of contents.%@AB@%.command%@AE@%                          Indicates that the topic text is not a                                   displayable help topic. Use this command                                  to hide hyperlink topics and other                                   internal information. Hyperlink topics                                   are described in Section 7.5.5,                                   "Hyperlink Commands."%@AB@%.comment%@AE@% %@AI@%string%@AE@%                   The %@AI@%string%@AE@% is a comment that appears                                   only in the help source file. Comments                                   are especially useful for documenting                                   the purpose of cross-references.                                  Because comments are not inserted in the                                  help database, they are not restored                                   when you decompress a help file.%@AB@%.context%@AE@% %@AI@%string%@AE@%                   The %@AI@%string%@AE@% introduces a topic.%@AB@%.end%@AE@%                              Ends a paste section. See the %@AB@%.paste%@AE@%                                   command below.%@AB@%.freeze%@AE@% %@AI@%numlines%@AE@%                  Indicates that the first %@AI@%numlines%@AE@% lines                                   should be frozen as the top line of the                                   help screen. This is normally used to                                   freeze a row of cross-reference buttons                                   at the top of a help topic that might be                                  scrolled.%@CR:C6A00070020 @%%@AB@%.length%@AE@% %@AI@%topiclength%@AE@%               Indicates the default window size, in %@AI@%%@AE@%                                  %@AI@%topiclength%@AE@% lines, of the topic about to                                  be displayed. This command is always the                                  first line in the topic if present.%@AB@%.list%@AE@%                             Indicates that the current topic                                   contains a list of topics. QuickHelp                                   displays a highlighted line; you can                                   choose                                   a topic by moving the highlighted line                                   over the desired topic and pressing %@AB@%%@AE@%                                  %@AB@%ENTER%@AE@%. Help searches for the first word                                   of the line.%@AB@%.mark%@AE@% %@AI@%name%@AE@% «%@AI@%column%@AE@%»               Defines a mark immediately preceding the                                  following line of text. This command can                                  be used in help script commands to                                   indicate that the display of a                                   particular topic begins at the marked                                   line. The %@AI@%name%@AE@% identifies the mark. The                                   optional %@AI@%column%@AE@% value is an integer that                                  indicates a column location within the                                   specified line.%@AB@%.next%@AE@% %@AI@%context%@AE@%                     Tells the help system to look up the                                   next topic using %@AI@%%@AE@%                                  %@AI@%context%@AE@% instead of the next topic's name.                                  You can use this command to skip large                                   blocks of %@AB@%.command%@AE@% or %@AB@%.popup%@AE@% topics.%@AB@%.previous%@AE@% %@AI@%context%@AE@%                 Tells the help system to look up the                                   previous topic using %@AI@%context%@AE@% instead of                                   the previous topic's name. You can use                                   this command to skip large blocks of %@AB@%%@AE@%                                  %@AB@%.command%@AE@% or %@AB@%.popup%@AE@% topics.%@AB@%.paste%@AE@% %@AI@%pastename%@AE@%                  Begins a paste section. The %@AI@%pastename%@AE@%                                   appears in the QuickHelp Paste menu.%@AB@%.popup%@AE@%                            Tells the help system to display the                                   current topic as a popup instead of a                                   normal, scrollable topic.%@AB@%.ref%@AE@% %@AI@%string(s)%@AE@%                    Tells the help system to display the                                   list of %@AI@%string%@AE@% topics in the Reference                                   menu. You can list as many topics as                                   needed; separate each additional %@AI@%string%@AE@%                                   with a comma.%@AB@%.topic%@AE@% %@AI@%text%@AE@%                       Defines %@AI@%text%@AE@% as the name or title to be                                   displayed in place of the context string                                  if the application help displays a title.                                  This command is always the first line in                                  the context unless you also use the %@AB@% %@AE@%                                  %@AB@%.length%@AE@% command.%@CR:C6A00070021 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 100  6368 02 34 42 @%
  6825.  
  6826. %@NL@%
  6827. %@4@%%@AB@%QuickHelp Formatting Flags%@AE@%%@EH@%%@NL@%
  6828. %@NL@%
  6829. The QuickHelp format supports a number of formatting flags that are used to
  6830. highlight parts of the help database and to mark hyperlinks in the help
  6831. text.  %@NL@%
  6832. %@NL@%
  6833. Each formatting flag consists of a backslash ( \ ) followed by a character.
  6834. Table 7.4 lists the formatting flags.  %@NL@%
  6835. %@NL@%
  6836. %@AB@%Table 7.4  %@AB@%Formatting Flags%@AE@%%@AE@%
  6837.  
  6838. %@TH:  19   773 02 34 42 @%Formatting Flag                   Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%\a                                Anchors text for cross-references\b, \B                            Turns boldface on or off\i, \I                            Turns italics on or off\p, \P                            Turns off all attributes\u, \U                            Turns underlining on or off\v, \V                            Turns invisibility on or off (hides                                   cross-references in text)\\                                Inserts a single backslash in text%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  19   773 02 34 42 @%
  6839.  
  6840. On monochrome monitors, text labeled with the bold, italic, and underlining
  6841. attributes appears in various ways, depending on the application (for
  6842. example, high intensity and reverse video are commonly displayed). On color
  6843. monitors, these attributes are translated by the application into suitable
  6844. colors, depending on the user's default color selections.  %@NL@%
  6845. %@NL@%
  6846. The \b, \i, \u, and \v options are toggles, turning on and off their
  6847. respective attributes. You can use several of these on the same text. Use
  6848. the \p attribute to turn off all attributes. Use the \v attribute to hide
  6849. cross-references and hyperlinks in the text.  %@NL@%
  6850. %@NL@%
  6851. HELPMAKE truncates the lines in QuickHelp files to the width specified with
  6852. the /W option. (See Section 7.3.1, "Options for Encoding," for more
  6853. information.) Only visible characters count toward the character-width
  6854. limit. Lines that begin with an application-specific control character are
  6855. truncated to 255 characters regardless of the width specification. See
  6856. Section 7.3.1 for more information about application-specific control
  6857. characters.  %@NL@%
  6858. %@NL@%
  6859. In the example below, the \b flag initiates boldface text for %@AS@% Returns:%@AE@%, and
  6860. the \p flag that follows the word reverts to plain text for the remainder of
  6861. the line.  %@NL@%
  6862. %@NL@%
  6863. %@AS@%  \bReturns:\p    a handle if successful, or -1 if not.
  6864. %@AS@%              errno:  EACCES, EEXIST, EMFILE, ENOENT%@AE@%%@NL@%
  6865. %@NL@%
  6866. In the example below, \a anchors text for the hyperlink %@AS@% Example %@AE@%. The \v
  6867. flags define the cross-reference to be %@AS@% sample_prog %@AE@% and cause the text
  6868. between the flags to be invisible. Cross-references are described in the
  6869. following section.  %@NL@%
  6870. %@NL@%
  6871. %@AS@%  \aExample \vsample_prog\v%@AE@%%@NL@%
  6872. %@NL@%
  6873. %@NL@%
  6874. %@4@%%@AB@%QuickHelp Cross-References%@AE@%%@EH@%%@NL@%
  6875. %@NL@%
  6876. Help databases contain two types of cross-references: implicit
  6877. cross-references and explicit cross-references. They are described in
  6878. Section 7.1.1, "Contents of a Help File."  %@NL@%
  6879. %@NL@%
  6880. An implicit cross-reference is any word that appears both in the topic text
  6881. and as a context in the help file. For example, any time you request help on
  6882. the word "close," the help window displays help on the %@AB@%close%@AE@% function. You
  6883. don't need to code implicit cross-references in your help text files.  %@NL@%
  6884. %@NL@%
  6885. %@AU@% Insert formatting flags to mark explicit cross-references.%@AE@%  %@NL@%
  6886. %@NL@%
  6887. Explicit cross-references (hyperlinks) are words or phrases on the screen
  6888. that are associated with a context. For example, the word "Example" in the
  6889. initial help-screen area for any C function is an explicit cross-reference
  6890. to the C program example for that function. You must insert formatting flags
  6891. in your help text files to mark explicit cross-references.  %@NL@%
  6892. %@NL@%
  6893. If the hyperlink consists of a single word, you can use invisible text to
  6894. flag it in the source file. The \v formatting flag creates invisible text,
  6895. as follows:  %@NL@%
  6896. %@NL@%
  6897. %@AS@%  hyperlink\vcontext\v%@AE@%%@NL@%
  6898. %@NL@%
  6899. Specify the first \v flag immediately following the word you want to use as
  6900. the hyperlink. Following the flag, insert the context that the hyperlink
  6901. crossreferences. The second \v flag marks the end of the context; that is,
  6902. the end of the invisible text. HELPMAKE generates a cross-reference whose
  6903. context is the invisible text, and whose hyperlink is the entire word.  %@NL@%
  6904. %@NL@%
  6905. If the hyperlink consists of a phrase, rather than a single word, you must
  6906. use anchored text to create explicit cross-references. Use the \a and \v
  6907. flags to create anchored text as follows:  %@NL@%
  6908. %@NL@%
  6909. %@AS@%  \ahyperlink-words\vcontext\v%@AE@%%@NL@%
  6910. %@NL@%
  6911. The \a flag marks an anchor for the cross-reference. The text that follows
  6912. the \a flag is the hyperlink. The hyperlink must fit entirely on one line.
  6913. The first \v flag marks both the end of the hyperlink and the beginning of
  6914. the invisible text that  %@NL@%
  6915. %@NL@%
  6916. contains the cross-reference context. The second \v flag marks the end of
  6917. the invisible text.  %@NL@%
  6918. %@NL@%
  6919. The following example contains three implicit cross-references to the C
  6920. routines %@AB@%abs%@AE@%, %@AB@%cabs%@AE@%, and %@AB@%fabs%@AE@%.  %@NL@%
  6921. %@NL@%
  6922. %@AS@%  See also: abs, cabs, fabs%@AE@%%@NL@%
  6923. %@NL@%
  6924. The following example shows the encoding for an explicit cross-reference to
  6925. an example program and a function template from the help database for the C
  6926. run-time library:  %@NL@%
  6927. %@NL@%
  6928. %@AS@%  See also: Example\vopen.ex\v, Template\vopen.tm\v, close%@AE@%%@NL@%
  6929. %@NL@%
  6930. Here, the hyperlinks are %@AS@% Example %@AE@% and %@AS@% Template%@AE@%, which reference the
  6931. contexts %@AS@% open.ex %@AE@% and %@AS@% open.tm%@AE@%. The example also contains an implicit
  6932. cross-reference to the %@AB@%close%@AE@% function.  %@NL@%
  6933. %@NL@%
  6934. The following example shows the encoding for an explicit cross-reference to
  6935. an entire family of functions:  %@NL@%
  6936. %@NL@%
  6937. %@AS@%  See also: \ais... functions\vis_functions\v, atoi%@AE@%%@NL@%
  6938. %@NL@%
  6939. The cross-reference uses anchored text to associate a phrase, rather than
  6940. just a word, with a context. In this example, the hyperlink is the anchored
  6941. phrase %@AS@% is... functions%@AE@%, and it cross-references the context %@AS@% is_functions%@AE@%.
  6942. In addition, the example contains an implicit cross-reference to the %@AB@%atoi%@AE@%
  6943. routine.  %@NL@%
  6944. %@NL@%
  6945. The code below is an example in QuickHelp format that contains a single
  6946. entry:  %@NL@%
  6947. %@NL@%
  6948. %@AS@%  .context open
  6949. %@AS@%  .length 13
  6950. %@AS@%  \bInclude:\p   <fcntl.h>, <io.h>, <sys\\types.h>, <sys\\stat.h>
  6951. %@AS@%  
  6952. %@AS@%  \bPrototype:\p  int open(char *path, int flag[, int mode]);
  6953. %@AS@%            flag:  O_APPEND O_BINARY O_CREAT O_EXCL O_RDONLY
  6954. %@AS@%                   O_RDWR    O_TEXT    O_TRUNC  O_WRONLY
  6955. %@AS@%                   (can be joined by |)
  6956. %@AS@%            mode:  S_IWRITE  S_IREAD   S_IREAD | S_IWRITE%@AE@%%@NL@%
  6957. %@NL@%
  6958. %@AS@%  \bReturns:\p    a handle if successful, or -1 if not.
  6959. %@AS@%              errno:  EACCES, EEXIST, EMFILE, ENOENT
  6960. %@AS@%  
  6961. %@AS@%  \bSee also:\p  \uExample\p\vopen.ex\v, \uTemplate\p\vopen.tp\v,
  6962. %@AS@%               access, chmod, close, creat, dup, dup2, fopen, sopen, umask%@AE@%%@NL@%
  6963. %@NL@%
  6964. The%@AB@% .length %@AE@%command near the beginning of the example specifies the size of
  6965. the initial window for the help text. Here, the initial window displays 13
  6966. lines.  %@NL@%
  6967. %@NL@%
  6968. The manifest constants (such as %@AB@%O_WRONLY%@AE@% and %@AB@%EEXIST%@AE@%), the C keywords (such
  6969. as %@AB@%int%@AE@% and %@AB@%char%@AE@%), and the other functions (such as %@AB@%sopen%@AE@% and %@AB@%access%@AE@%) are
  6970. implicit cross-references. The words %@AS@% Example %@AE@% and %@AS@% Template %@AE@% are explicit
  6971. cross-references to the example %@AS@% open.ex %@AE@% and to the %@AB@%open%@AE@% template %@AS@% open.tp%@AE@%,
  6972. respectively. Note the use of double backslashes in the include file names.
  6973. %@NL@%
  6974. %@NL@%
  6975. %@NL@%
  6976. %@3@%%@CR:C6A00070022 @%%@AB@%7.6.2  Minimally Formatted ASCII Format%@AE@%%@EH@%%@NL@%
  6977. %@NL@%
  6978. A minimally formatted ASCII text file comprises a sequence of topics, each
  6979. preceded by one or more unique context definitions. Each context definition
  6980. must be on a separate line beginning with a help delimiter (>>). Subsequent
  6981. lines up to the next context definition constitute the topic text.  %@NL@%
  6982. %@NL@%
  6983. %@AU@% Minimally formatted ASCII files cannot contain highlighting.%@AE@%  %@NL@%
  6984. %@NL@%
  6985. Minimally formatted ASCII files can be used in two ways. You can compress
  6986. the file with HELPMAKE, creating a help database, or an application can
  6987. access the uncompressed file directly. Uncompressed files are somewhat
  6988. larger and slower to search, however. Minimally formatted ASCII files are of
  6989. fixed width, and they cannot contain highlighting (or other nondefault
  6990. attributes) or cross-references.  %@NL@%
  6991. %@NL@%
  6992. The following example, coded in minimally formatted ASCII, shows the same
  6993. text as the QuickHelp example in the previous section. The first line of the
  6994. example defines %@AS@% open %@AE@% as a context string. The minimally formatted ASCII
  6995. help file must begin with the help delimiter (>>), so that HELPMAKE or the
  6996. application can verify that the file is indeed an ASCII help file.  %@NL@%
  6997. %@NL@%
  6998. %@AS@%  >>>>open
  6999. %@AS@%  
  7000. %@AS@%  Include:    <fcntl.h>, <io.h>, <sys\types.h>, <sys\stat.h>
  7001. %@AS@%  
  7002. %@AS@%  Prototype:  int open(char *path, int flag[, int mode]);
  7003. %@AS@%          flag:  O_APPEND  O_BINARY  O_CREAT  O_EXCL  O_RDONLY
  7004. %@AS@%                 O_RDWR    O_TEXT    O_TRUNC  O_WRONLY
  7005. %@AS@%                 (can be joined by |)
  7006. %@AS@%          mode:  S_IWRITE  S_IREAD   S_IREAD | S_IWRITE
  7007. %@AS@%  
  7008. %@AS@%  Returns:    a handle if successful, or -1 if not.
  7009. %@AS@%              errno:  EACCES, EEXIST, EMFILE, ENOENT%@AE@%%@NL@%
  7010. %@NL@%
  7011. %@AS@%  See also:  access, chmod, close, creat, dup, dup2, fopen, sopen, umask%@AE@%%@NL@%
  7012. %@NL@%
  7013. When displayed, the help information appears exactly as it is typed into the
  7014. file. Any formatting codes are treated as ASCII text. Note that you do not
  7015. need to escape backslashes in minimally formatted ASCII files.  %@NL@%
  7016. %@NL@%
  7017. If you compress minimally formatted ASCII files, they are smaller and faster
  7018. to search.  %@NL@%
  7019. %@NL@%
  7020. %@NL@%
  7021. %@3@%%@CR:C6A00070023 @%%@AB@%7.6.3  Rich Text Format (RTF)%@AE@%%@EH@%%@NL@%
  7022. %@NL@%
  7023. RTF is a Microsoft word-processing format supported by many other word
  7024. processors. It allows documents to be transferred from one application to
  7025. another without losing any formatting information. The HELPMAKE utility
  7026. recognizes a subset of the full RTF syntax. If your file contains any RTF
  7027. code that is not part of the subset, HELPMAKE ignores the code and strips it
  7028. out of the file.  %@NL@%
  7029. %@NL@%
  7030. Certain word-processing and file-conversion programs generate the RTF code
  7031. automatically as output. You need not worry about inserting RTF codes
  7032. yourself; you can simply format your help files directly with a
  7033. word-processor that generates RTF, using the attributes supported by the
  7034. subset. The only items you need to insert are the help delimiter (>>) and
  7035. context string that start each entry.  %@NL@%
  7036. %@NL@%
  7037. HELPMAKE recognizes the subset of RTF listed below:  %@NL@%
  7038. %@NL@%
  7039. %@AB@%RTF Code%@AE@%                          %@AB@%Action%@AE@%
  7040. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7041. \b                                Boldface. The application decides how to
  7042.                                   display this; often it is intensified 
  7043.                                   text.
  7044.  
  7045. \fi <%@AI@%nnn%@AE@%>                         Paragraph first-line indent.
  7046.  
  7047. \i                                Italic. The application decides how to 
  7048.                                   display this; often it is reverse video.
  7049.  
  7050. \li <%@AI@%nnn%@AE@%>                         Paragraph indent from left margin.
  7051.  
  7052. \line                             New line (not new paragraph).
  7053.  
  7054. \par                              End of paragraph.
  7055.  
  7056. \pard                             Default paragraph formatting.
  7057.  
  7058. \plain                            Default attributes. On most screens this
  7059.                                   is nonblinking normal intensity.
  7060.  
  7061. \tab                              Tab character.
  7062.  
  7063. \ul                               Underline. The application decides how 
  7064.                                   to display this; some adapters that do 
  7065.                                   not support underlining display it as 
  7066.                                   blue text.
  7067.  
  7068. \v                                Hidden text. Hidden text is used for 
  7069.                                   cross-reference information and for some
  7070.                                   application-specific communications; it 
  7071.                                   is not displayed.
  7072.  
  7073. Using the word-processing program, you can break the topic text into
  7074. paragraphs. When HELPMAKE compresses the file, it formats the text to the
  7075. width given with the / W option, ignoring the paragraph formats.  %@NL@%
  7076. %@NL@%
  7077. As with the other text formats, each entry in the database source consists
  7078. of one or more context strings, followed by topic text. An RTF file can
  7079. contain QuickHelp dot commands.  %@NL@%
  7080. %@NL@%
  7081. The help delimiter (>>) at the beginning of any paragraph denotes the
  7082. beginning of a new help entry. The text that follows on the same line is
  7083. defined as a context for the topic. If the next paragraph also begins with
  7084. the help delimiter, it also defines a context string for the same topic
  7085. text. You can define any number of contexts for a block of topic text. The
  7086. topic text comprises all subsequent paragraphs up to the next paragraph that
  7087. begins with the help delimiter.  %@NL@%
  7088. %@NL@%
  7089. The code below is an example of a help database that contains a single entry
  7090. using subset RTF text. Note that RTF uses curly braces ({}) for nesting.
  7091. Thus, the entire file is enclosed in curly braces, as is each specially
  7092. formatted text item.  %@NL@%
  7093. %@NL@%
  7094. %@AS@%  {\rtf1
  7095. %@AS@%  \pard >>open\par 
  7096. %@AS@%    {\b Include:}    <fcntl.h>, <io.h>, <sys\\types.h>, <sys\\stat.h>\par
  7097. %@AS@%  \par 
  7098. %@AS@%    {\b Syntax:}     int open( char * filename, int oflag[, int pmode ]
  7099. %@AS@%);\par
  7100. %@AS@%               oflag:  O_APPEND  O_BINARY  O_CREAT  O_EXCL  O_RDONLY\par 
  7101. %@AS@%                       O_RDWR    O_TEXT    O_TRUNC  O_WRONLY\par 
  7102. %@AS@%                       (may be joined by |)\par 
  7103. %@AS@%               pmode:  S_IWRITE  S_IREAD   S_IREAD | S_IWRITE\par 
  7104. %@AS@%  \par 
  7105. %@AS@%    {\b Returns:}    a handle if successful, or -1 if not.\par
  7106. %@AS@%               errno:  EACCES, EEXIST, EMFILE, ENOENT\par 
  7107. %@AS@%  \par 
  7108. %@AS@%    {\b See also:}  Examples{\v open.ex}, access, chmod, close, creat,
  7109. %@AS@%dup,\par
  7110. %@AS@%               dup2, fopen, sopen, umask\par 
  7111. %@AS@%  >>open.ex\par 
  7112. %@AS@%  To build this help file, use the following command:\par
  7113. %@AS@%  \par
  7114. %@AS@%  HELPMAKE /S1 /E15 /OOPEN.HLP OPEN.RTF\par
  7115. %@AS@%  \par
  7116. %@AS@%  
  7117. %@AS@%          < Back >{\v !B}
  7118. %@AS@%  }%@AE@%%@NL@%
  7119. %@NL@%
  7120. Actual RTF output normally contains additional information that is not
  7121. visible to the user; HELPMAKE ignores this extra information.  %@NL@%
  7122. %@NL@%
  7123. %@NL@%
  7124. %@NL@%
  7125. %@NL@%
  7126. %@NL@%
  7127. %@NL@%
  7128. %@CR:C6A00080001 @%%@1@%%@AB@%Chapter 8  Customizing the Microsoft Programmer's WorkBench%@AE@%%@EH@%%@NL@%
  7129. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7130. %@NL@%
  7131. Designed with flexibility in mind, the Microsoft Programmer's WorkBench
  7132. (PWB) provides a highly extensible development platform for the Microsoft C
  7133. Professional Development System. Using PWB it is easy to change basic
  7134. environment features such as screen colors and key assignments, and you can
  7135. add powerful new functions of your own using macros and C-language
  7136. extensions.  %@NL@%
  7137. %@NL@%
  7138. This chapter explains four methods for customizing the Programmer's
  7139. WorkBench: setting switches, assigning keystrokes, writing macros, and
  7140. writing C extensions. While it explains customization methods, the chapter
  7141. does not document every customizable feature of the Programmer's WorkBench.
  7142. Use on-line help as your primary source of information about these and other
  7143. PWB features.  %@NL@%
  7144. %@NL@%
  7145. This chapter assumes you are familiar with basic PWB operations and
  7146. terminology. If you are not, read "Using the Programmer's WorkBench" in
  7147. %@AI@%Installing and Using the Microsoft C Professional Development System%@AE@%.  %@NL@%
  7148. %@NL@%
  7149. %@NL@%
  7150. %@2@%%@CR:C6A00080002 @%%@AB@%8.1  Setting Switches%@AE@%%@EH@%%@NL@%
  7151. %@NL@%
  7152. The Programmer's WorkBench has a number of "switches," or user-configurable
  7153. options, that control features such as screen colors. Each switch has a name
  7154. and can be assigned a value.  %@NL@%
  7155. %@NL@%
  7156. There are two ways to set PWB switches. The easiest way is by choosing
  7157. Editor Settings in the Options menu. You can also edit the TOOLS.INI
  7158. initialization file. These methods can also be used for more elaborate
  7159. customizations, such as writing macros.  %@NL@%
  7160. %@NL@%
  7161. %@NL@%
  7162. %@3@%%@CR:C6A00080003 @%%@AB@%8.1.1  Editing the <assign> Pseudofile%@AE@%%@EH@%%@NL@%
  7163. %@NL@%
  7164. If you choose Editor Settings in the Options menu, PWB changes to the
  7165. %@AB@%<assign>%@AE@% pseudofile and displays it in the current window. (A pseudofile is
  7166. constructed dynamically by PWB; it exists only in memory.) The %@AB@%<assign>%@AE@%
  7167. file lists all the current PWB settings.  %@NL@%
  7168. %@NL@%
  7169. To change a switch, edit the line where it appears. For instance, the
  7170. %@AB@%vscroll%@AE@% switch controls how many lines PWB scrolls vertically; its default
  7171. setting is 1. To change it, move to the corresponding line:  %@NL@%
  7172. %@NL@%
  7173. %@AS@%  vscroll:1%@AE@%%@NL@%
  7174. %@NL@%
  7175. Change the 1 to 3 and move the cursor to another line. PWB highlights the
  7176. line to indicate the change is legal. (If you make an illegal change, PWB
  7177. signals an error.) The change takes effect immediately: now PWB scrolls text
  7178. three vertical lines at a time.  %@NL@%
  7179. %@NL@%
  7180. If you don't explicitly save a change, it disappears at the end of the
  7181. current session. You can save a change by saving %@AB@%<assign>%@AE@% as you would any
  7182. other file (by pressing ALT+A ALT+A F2). When you exit PWB, you are asked if
  7183. you want to save TOOLS.INI, the PWB initialization file, which records
  7184. customizations. Answer yes (type %@AS@% Y) %@AE@% to save the change.  %@NL@%
  7185. %@NL@%
  7186. You can also use this method for more elaborate customizations, such as
  7187. writing macros (see Section 8.3, "Writing Macros"). Simply insert a few
  7188. blank lines in %@AB@%<assign>%@AE@% and enter the new information in them. Note that PWB
  7189. only pays attention to lines you change or add to %@AB@%<assign>%@AE@%. Deleting a line
  7190. has no effect.  %@NL@%
  7191. %@NL@%
  7192. %@NL@%
  7193. %@3@%%@CR:C6A00080004 @%%@AB@%8.1.2  Editing the TOOLS.INI Initialization File%@AE@%%@EH@%%@NL@%
  7194. %@NL@%
  7195. Another way to customize PWB is by editing TOOLS.INI, the initialization
  7196. file used by PWB and other Microsoft language tools. This method is useful
  7197. if you customize PWB extensively.  %@NL@%
  7198. %@NL@%
  7199. While the %@AB@%<assign>%@AE@% file lists every customizable PWB item, the TOOLS.INI
  7200. file contains lines only for items you have customized. Those items not
  7201. mentioned in TOOLS.INI are set to a default value.  %@NL@%
  7202. %@NL@%
  7203. %@NL@%
  7204. %@4@%%@AB@%Dividing TOOLS.INI into Sections%@AE@%%@EH@%%@NL@%
  7205. %@NL@%
  7206. Since several tools can use TOOLS.INI, the file may contain information that
  7207. doesn't relate to PWB. If you customize more than one tool, TOOLS.INI is
  7208. divided into sections, one for each tool. Each section begins with a tag
  7209. consisting of the tool's base name enclosed in square brackets: %@AS@% [PWB] %@AE@% for
  7210. PWB.EXE, %@AS@%[NMAKE] %@AE@% for NMAKE.EXE, and so on.  %@NL@%
  7211. %@NL@%
  7212. For example, say you set the %@AB@%vscroll%@AE@% switch to 3 and save the change, but
  7213. you have not customized PWB in any other way. Your TOOLS.INI file will
  7214. contain this section:  %@NL@%
  7215. %@NL@%
  7216. %@AS@%  [PWB]
  7217. %@AS@%  vscroll:3%@AE@%%@NL@%
  7218. %@NL@%
  7219. Settings following this tag are put in effect by PWB every time it starts.  %@NL@%
  7220. %@NL@%
  7221. You can also create sections of TOOLS.INI that PWB reads only in certain
  7222. circumstances. You can create sections for different video adapters,
  7223. file-name extensions, and operating system versions.  %@NL@%
  7224. %@NL@%
  7225. If you use more than one video display, TOOLS.INI can have a different
  7226. section for each display:  %@NL@%
  7227. %@NL@%
  7228. %@NL@%
  7229.   ■   %@AS@%[PWB-mono]%@AE@%%@NL@%
  7230. %@NL@%
  7231.   ■   %@AS@%[PWB-cga]%@AE@%%@NL@%
  7232. %@NL@%
  7233.   ■   %@AS@%[PWB-ega]%@AE@%%@NL@%
  7234. %@NL@%
  7235.   ■   %@AS@%[PWB-vga]%@AE@%%@NL@%
  7236. %@NL@%
  7237. %@NL@%
  7238. After each tag, you can set different screen colors, dimensions, and other
  7239. display-specific switches.  %@NL@%
  7240. %@NL@%
  7241. You can also create a section for files with specific extensions. For
  7242. instance, your TOOLS.INI file could contain a section beginning with the tag
  7243. %@NL@%
  7244. %@NL@%
  7245. %@AS@%  [PWB-.C]%@AE@%%@NL@%
  7246. %@NL@%
  7247. for C source files, and  %@NL@%
  7248. %@NL@%
  7249. %@AS@%  [PWB-.ASM]%@AE@%%@NL@%
  7250. %@NL@%
  7251. for assembly-language (.ASM) source files. Each time you load a file with
  7252. the designated extension, PWB reads the appropriate section of TOOLS.INI.
  7253. For each file type, you could use a different set of macros and other
  7254. customizations.  %@NL@%
  7255. %@NL@%
  7256. TOOLS.INI can also contain sections specific to operating system versions.
  7257. The following tag introduces a section specific to DOS version 3.20, for
  7258. instance:  %@NL@%
  7259. %@NL@%
  7260. %@AS@%  [PWB-3.20]%@AE@%%@NL@%
  7261. %@NL@%
  7262. You can combine tags as needed. For example, the tag  %@NL@%
  7263. %@NL@%
  7264. %@AS@%  [PWB-3.20 PWB-10.10R]%@AE@%%@NL@%
  7265. %@NL@%
  7266. applies to DOS version 3.20 and OS/2 version 1.1 real mode.  %@NL@%
  7267. %@NL@%
  7268. You can also create a section in TOOLS.INI containing switches for a
  7269. userwritten extension. See Section 8.4.3, "Describing Functions and
  7270. Switches." On-line help contains additional information about TOOLS.INI
  7271. tags.  %@NL@%
  7272. %@NL@%
  7273. %@NL@%
  7274. %@2@%%@CR:C6A00080005 @%%@AB@%8.2  Assigning Keystrokes%@AE@%%@EH@%%@NL@%
  7275. %@NL@%
  7276. PWB allows you to assign any editing function to almost any keystroke.
  7277. Reassigning keystrokes doesn't change PWB graphic interface, however.  %@NL@%
  7278. %@NL@%
  7279. Keystrokes, like switches, are listed in the %@AB@%<assign>%@AE@% pseudofile (choose Key
  7280. Assignments in the Options menu) and can be changed there. For example, say
  7281. you want to assign the %@AB@%home%@AE@% cursor function to the SHIFT+HOME keystroke. The
  7282. default keystroke assignment for %@AB@%home%@AE@% is:  %@NL@%
  7283. %@NL@%
  7284. %@AS@%  home:ctrl+home%@AE@%%@NL@%
  7285. %@NL@%
  7286. If you change the assignment to  %@NL@%
  7287. %@NL@%
  7288. %@AS@%  home:shift+home%@AE@%%@NL@%
  7289. %@NL@%
  7290. SHIFT+HOME moves the cursor to the home (upper left) window position.  %@NL@%
  7291. %@NL@%
  7292. It is legal to assign more than one keystroke to the same function. For
  7293. example, many keystrokes invoke the %@AB@%select%@AE@% function, which selects a text
  7294. region. Thus, the previous example adds a new keystroke (SHIFT+HOME) for the
  7295. %@AB@%home%@AE@% function; it does not remove the previous assignment (CTRL+HOME).  %@NL@%
  7296. %@NL@%
  7297. There are two limitations on keystroke assignments:  %@NL@%
  7298. %@NL@%
  7299. %@NL@%
  7300.   ■   You can't reassign a keystroke that PWB is using for a menu. For
  7301.       instance, if ALT+F pulls down the File menu, PWB ignores any attempt
  7302.       to reassign ALT+F.%@NL@%
  7303. %@NL@%
  7304.   ■   You can't reassign ALT plus the number keys 1 - 9 (ALT+1, ALT+2, and
  7305.       so on). These keystrokes are reserved for the file history menu items.%@NL@%
  7306. %@NL@%
  7307. %@NL@%
  7308. Each keystroke can only invoke one function. If you mistakenly assign a
  7309. key-stroke to more than one function, PWB uses the most recent assignment.
  7310. For example,  %@NL@%
  7311. %@NL@%
  7312. %@AS@%  home:ctrl+a
  7313. %@AS@%  setfile:ctrl+a%@AE@%%@NL@%
  7314. %@NL@%
  7315. assigns the CTRL+A keystroke to two different functions, %@AB@%home%@AE@% and %@AB@%setfile%@AE@%.
  7316. The second assignment overrides the first, assigning CTRL+A to %@AB@%setfile%@AE@%.  %@NL@%
  7317. %@NL@%
  7318. Occasionally, you may want to "unassign," or disable, a keystroke. This is
  7319. done by assigning the %@AB@%unassigned%@AE@% function to the keystroke. For example,  %@NL@%
  7320. %@NL@%
  7321. %@AS@%  unassigned:ctrl+a%@AE@%%@NL@%
  7322. %@NL@%
  7323. disables CTRL+A. PWB signals an error when you press any unassigned key.  %@NL@%
  7324. %@NL@%
  7325. %@NL@%
  7326. %@2@%%@CR:C6A00080006 @%%@AB@%8.3  Writing Macros%@AE@%%@EH@%%@NL@%
  7327. %@NL@%
  7328. The fastest way to create a new editing function for PWB is to write a
  7329. macro. The function can be as simple as inserting a long word or phrase, or
  7330. it can perform complex tasks by invoking PWB functions and other macros.  %@NL@%
  7331. %@NL@%
  7332. %@NL@%
  7333. %@3@%%@CR:C6A00080007 @%%@AB@%8.3.1  Macro Syntax%@AE@%%@EH@%%@NL@%
  7334. %@NL@%
  7335. A macro can contain any combination of PWB functions, literal text, and
  7336. macro operators. You can define as many as 1,024 macros at one time.  %@NL@%
  7337. %@NL@%
  7338. %@AU@% Literal text is case sensitive.%@AE@%  %@NL@%
  7339. %@NL@%
  7340. Literal text is anything inside double quotes. Inside literal text, you can
  7341. represent a double quote as %@AS@% \"%@AE@% and a backslash as %@AS@% \\%@AE@%. Text is case
  7342. sensitive inside quotes and case insensitive outside them.  %@NL@%
  7343. %@NL@%
  7344. The following macro comments out a line of C source code:  %@NL@%
  7345. %@NL@%
  7346. %@AS@%  comment:=begline "/* " endline " */"
  7347. %@AS@%  comment:alt+c%@AE@%%@NL@%
  7348. %@NL@%
  7349. The first line names the macro and tells what it does. The %@AB@%begline%@AE@% and
  7350. %@AB@%endline%@AE@% editor functions move the cursor, while the text inside quotes is
  7351. printed at the current cursor position. The second line assigns a keystroke
  7352. (ALT+C) to the macro.  %@NL@%
  7353. %@NL@%
  7354. A macro definition must fit on one logical line. If necessary, you can use
  7355. the backslash ( \ ) to continue the definition on the next line. For
  7356. instance, the definition  %@NL@%
  7357. %@NL@%
  7358. %@AS@%  comment:=begline "/* " endline " */"%@AE@%%@NL@%
  7359. %@NL@%
  7360. could be written as  %@NL@%
  7361. %@NL@%
  7362. %@AS@%  comment:=begline  \
  7363. %@AS@%  "/* " endline  \
  7364. %@AS@%  " */"%@AE@%%@NL@%
  7365. %@NL@%
  7366. Notice the extra space before each backslash. If you want a space between
  7367. the end of one line and the beginning of the other, you must precede the
  7368. backslash with two spaces.  %@NL@%
  7369. %@NL@%
  7370. You can use the %@AB@%arg%@AE@% function to pass arguments to functions. For example,
  7371. the following macro passes the argument %@AS@% 15 %@AE@% to the %@AB@%plines%@AE@% function (which
  7372. scrolls text down):  %@NL@%
  7373. %@NL@%
  7374. %@AS@%  movedown:=arg "15" plines%@AE@%%@NL@%
  7375. %@NL@%
  7376. Because %@AB@%arg%@AE@% precedes the literal text, the text doesn't appear on the
  7377. screen. Instead, it is passed as an argument to the next function, %@AB@%plines%@AE@%.
  7378. The macro scrolls the current text down 15 lines.  %@NL@%
  7379. %@NL@%
  7380. Arguments can use regular expression syntax, as well (regular expressions
  7381. are documented in on-line help):  %@NL@%
  7382. %@NL@%
  7383. %@AS@%  endword:=arg arg "( !.!$!\\:!;!\\)!\\(!,)" psearch%@AE@%%@NL@%
  7384. %@NL@%
  7385. The %@AB@%arg arg%@AE@% sequence directs the %@AB@%psearch%@AE@% function to treat the text argument
  7386. as a regular expression search pattern. This search pattern tells PWB to
  7387. search for the next period, end of line ($), colon, semicolon, close
  7388. parenthesis, open parenthesis, or comma.  %@NL@%
  7389. %@NL@%
  7390. A macro can invoke other macros:  %@NL@%
  7391. %@NL@%
  7392. %@AS@%  lcomment:= "/* "
  7393. %@AS@%  rcomment:= " */"
  7394. %@AS@%  commentout:=begline lcomment endline rcomment
  7395. %@AS@%  commentout:alt+z%@AE@%%@NL@%
  7396. %@NL@%
  7397. The %@AS@% commentout %@AE@% macro invokes the previously defined macros %@AS@% lcomment %@AE@% and %@AS@%
  7398. %@AS@%rcomment.%@AE@%  %@NL@%
  7399. %@NL@%
  7400. In addition to standard PWB functions, macros can invoke user-defined
  7401. (extension) functions. See Section 8.4, "Writing and Building C Extensions."
  7402. %@NL@%
  7403. %@NL@%
  7404. %@NL@%
  7405. %@3@%%@CR:C6A00080008 @%%@AB@%8.3.2  Macro Responses%@AE@%%@EH@%%@NL@%
  7406. %@NL@%
  7407. Some PWB functions ask you for confirmation. For example, the %@AB@%meta exit%@AE@%
  7408. (quit without saving) function normally asks if you really want to exit.
  7409. Such questions always take the answer "yes" (%@AS@%y%@AE@%) or "no" (%@AS@%n%@AE@%).  %@NL@%
  7410. %@NL@%
  7411. When you invoke such a function in a macro, the function assumes an answer
  7412. of yes and does not ask for confirmation. For example, the macro definition
  7413. %@NL@%
  7414. %@NL@%
  7415. %@AS@%  quit:=meta exit
  7416. %@AS@%  quit:alt+x%@AE@%%@NL@%
  7417. %@NL@%
  7418. invokes %@AB@%meta exit%@AE@% when you press ALT+X. Because the %@AB@%meta exit%@AE@% function is
  7419. invoked from a macro, PWB exits without asking for confirmation.  %@NL@%
  7420. %@NL@%
  7421. The following operators allow you to restore normal prompting or change the
  7422. default responses:  %@NL@%
  7423. %@NL@%
  7424. %@AB@%Operator%@AE@%                          %@AB@%Description%@AE@%
  7425. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7426. %@AB@%<%@AE@%                                 Asks for confirmation; if not followed 
  7427.                                   by another %@AB@%<%@AE@% operator, prompts for all 
  7428.                                   further questions
  7429.  
  7430. %@AB@%<y%@AE@%                                Assumes a response of yes
  7431.  
  7432. %@AB@%<n%@AE@%                                Assumes a response of no
  7433.  
  7434. A response operator applies to the function immediately preceding it. For
  7435. instance, you can add the %@AB@%%@AE@% operator to the %@AS@% quit %@AE@% macro definition to
  7436. restore the usual prompt:  %@NL@%
  7437. %@NL@%
  7438. %@AS@%  quit:=meta exit <
  7439. %@AS@%  quit:alt+x%@AE@%%@NL@%
  7440. %@NL@%
  7441. Now the macro prompts for a response before it exits.  %@NL@%
  7442. %@NL@%
  7443. %@NL@%
  7444. %@3@%%@CR:C6A00080009 @%%@AB@%8.3.3  Macro Arguments%@AE@%%@EH@%%@NL@%
  7445. %@NL@%
  7446. If you enter an argument in PWB and then invoke a macro, the argument is
  7447. passed to the first function in the macro that takes an argument:  %@NL@%
  7448. %@NL@%
  7449. %@AS@%  tripleit:=copy paste paste%@AE@%%@NL@%
  7450. %@NL@%
  7451. The %@AS@% tripleit %@AE@% macro invokes the %@AB@%copy%@AE@% and %@AB@%paste%@AE@% editing functions. If you
  7452. highlight a text area and then invoke the macro, your highlighted argument
  7453. is passed to the %@AB@%copy%@AE@% function, which copies the argument to the clipboard.
  7454. The macro then invokes %@AB@%paste%@AE@% twice. The effect is to insert two copies of
  7455. the highlighted text.  %@NL@%
  7456. %@NL@%
  7457. %@AU@% You cannot pass more than one argument from PWB to a macro.%@AE@%  %@NL@%
  7458. %@NL@%
  7459. You cannot pass more than one argument from PWB to a macro, even if the
  7460. macro invokes more than one function that can accept an argument. The
  7461. argument always goes to the first function in the macro that takes an
  7462. argument.  %@NL@%
  7463. %@NL@%
  7464. You can also prompt for input inside a macro and pass the input as an
  7465. argument using the %@AB@%prompt%@AE@% function as shown below:  %@NL@%
  7466. %@NL@%
  7467. %@AS@%  newfile:=arg "Next file: " prompt setfile <
  7468. %@AS@%  newfile:alt+n%@AE@%%@NL@%
  7469. %@NL@%
  7470. The %@AS@% newfile %@AE@% macro prompts for a file name and then switches to the
  7471. specified file. The sequence %@AS@% arg "Next file: "%@AE@% passes a text argument to
  7472. %@AB@%prompt%@AE@%, which prints the text on the dialog line and waits for input. The
  7473. input is passed as a text argument to the %@AB@%setfile%@AE@% function, which switches
  7474. to that file. For more information on the %@AB@%prompt%@AE@% function, see on-line help.
  7475. %@NL@%
  7476. %@NL@%
  7477. %@NL@%
  7478. %@3@%%@CR:C6A00080010 @%%@AB@%8.3.4  Macro Conditionals%@AE@%%@EH@%%@NL@%
  7479. %@NL@%
  7480. Macros can take different actions depending on certain conditions. Such
  7481. macros take advantage of the fact that PWB editing functions generally
  7482. return values─a TRUE (nonzero) value if successful or FALSE (zero) if
  7483. unsuccessful.  %@NL@%
  7484. %@NL@%
  7485. Macros can use four conditional operators:  %@NL@%
  7486. %@NL@%
  7487. %@AB@%Operator%@AE@%                          %@AB@%Description%@AE@%
  7488. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7489. %@AB@%:>%@AE@%%@AI@%label%@AE@%                           Defines a %@AI@%label%@AE@% that can be targeted by 
  7490.                                   other operators
  7491.  
  7492. %@AB@%=>%@AE@%%@AI@%label%@AE@%                           Jumps to %@AI@%label%@AE@%
  7493.  
  7494. %@AB@%+>%@AE@%%@AI@%label%@AE@%                           Jumps to %@AI@%label%@AE@% if the previous function 
  7495.                                   returns TRUE
  7496.  
  7497. %@AB@%->%@AE@%%@AI@%label%@AE@%                           Jumps to %@AI@%label%@AE@% if the previous function 
  7498.                                   returns FALSE
  7499.  
  7500. For example, the %@AS@% leftmarg %@AE@% macro moves the cursor to the left margin of the
  7501. editing window:  %@NL@%
  7502. %@NL@%
  7503. %@AS@%  leftmarg:=:>leftmore left +>leftmore%@AE@%%@NL@%
  7504. %@NL@%
  7505. The macro above invokes the %@AB@%left%@AE@% function repeatedly (jumping to the label %@AS@%
  7506. %@AS@%%@AE@%leftmore) until it returns FALSE, indicating the cursor has reached the left
  7507. margin.  %@NL@%
  7508. %@NL@%
  7509. The label must appear immediately after the conditional operator, with no
  7510. intervening spaces. A conditional operator without a label exits the macro
  7511. immediately if the condition is true. If the condition is false, the macro
  7512. continues execution. The following example demonstrates this:  %@NL@%
  7513. %@NL@%
  7514. %@AS@%  turnon:=insertmode +> insertmode%@AE@%%@NL@%
  7515. %@NL@%
  7516. This macro turns on insert mode regardless of whether insert mode is
  7517. currently on or off. If insert mode is off, the first invocation of
  7518. %@AB@%insertmode%@AE@% toggles the mode on and returns TRUE, causing the %@AB@%+>%@AE@% operator to
  7519. terminate the macro. If insert mode is currently on, the first invocation of
  7520. %@AB@%insertmode%@AE@% turns insert mode off and returns FALSE. The macro then invokes
  7521. %@AB@%insertmode%@AE@% a second time, turning insert mode back on.  %@NL@%
  7522. %@NL@%
  7523. %@NL@%
  7524. %@3@%%@CR:C6A00080011 @%%@AB@%8.3.5  Temporary Macros%@AE@%%@EH@%%@NL@%
  7525. %@NL@%
  7526. Occasionally, you may want to create a macro that lasts only through the
  7527. current session. This can be done with the %@AB@%assign%@AE@% function. For example, the
  7528. following steps create the %@AS@% comment %@AE@% macro described above.  %@NL@%
  7529. %@NL@%
  7530. To create the macro:  %@NL@%
  7531. %@NL@%
  7532. %@NL@%
  7533.   ■   Press ALT+A%@NL@%
  7534. %@NL@%
  7535.   ■   Type %@AS@% %@AE@%comment:=begline "/* " endline " */" %@NL@%
  7536. %@NL@%
  7537.   ■   Press ALT+=%@NL@%
  7538. %@NL@%
  7539. %@NL@%
  7540. To assign the ALT+C keystroke to the macro:  %@NL@%
  7541. %@NL@%
  7542. %@NL@%
  7543.   ■   Press ALT+A%@NL@%
  7544. %@NL@%
  7545.   ■   Type %@AS@% %@AE@%comment:alt+c%@NL@%
  7546. %@NL@%
  7547.   ■   Press ALT+=%@NL@%
  7548. %@NL@%
  7549. %@NL@%
  7550. The macro is available immediately and then disappears at the end of the
  7551. current session.  %@NL@%
  7552. %@NL@%
  7553. %@NL@%
  7554. %@3@%%@CR:C6A00080012 @%%@AB@%8.3.6  Macro Recordings%@AE@%%@EH@%%@NL@%
  7555. %@NL@%
  7556. Another way to create a macro is by recording your own actions. The entire
  7557. sequence of actions is saved and can be replayed later by pressing a key.  %@NL@%
  7558. %@NL@%
  7559. You start the recording by invoking the %@AB@%record%@AE@% function. PWB names the
  7560. resulting macro %@AB@%recordvalue%@AE@% by default, but you can use other names as well.
  7561. To record a macro:  %@NL@%
  7562. %@NL@%
  7563. %@NL@%
  7564.   ■   Choose Record On from the Edit menu to start the recording.%@NL@%
  7565. %@NL@%
  7566.   ■   Perform the actions you want to record.%@NL@%
  7567. %@NL@%
  7568.   ■   Choose Record On again to end the recording.%@NL@%
  7569. %@NL@%
  7570.   ■   If %@AB@%recordvalue%@AE@% is not already assigned, assign it to a keystroke as
  7571.       described above.%@NL@%
  7572. %@NL@%
  7573. %@NL@%
  7574. After you complete these steps, a macro named %@AB@%recordvalue%@AE@% is available
  7575. through the keystroke you assigned in the last step above. When you press
  7576. this key, PWB replays the actions you recorded.  %@NL@%
  7577. %@NL@%
  7578. If you don't do anything more, the recorded macro is temporary─it disappears
  7579. when you exit PWB. To save the macro permanently:  %@NL@%
  7580. %@NL@%
  7581. %@NL@%
  7582.   ■   Open the %@AB@%<record>%@AE@% pseudofile (press ALT+A, type %@AS@% <record>%@AE@%, press F2).%@NL@%
  7583. %@NL@%
  7584.   ■   Copy the macro definition in %@AB@%<record>%@AE@%.%@NL@%
  7585. %@NL@%
  7586.   ■   Paste the definition into the %@AS@% [PWB] %@AE@% section of your TOOLS.INI file.%@NL@%
  7587. %@NL@%
  7588. %@NL@%
  7589. Studying recorded macros can teach you a lot about macros and editor
  7590. functions. If you open the %@AB@%<record>%@AE@% pseudofile in a second window before you
  7591. record, you can watch PWB write the macro definition function by function.  %@NL@%
  7592. %@NL@%
  7593. If you save a recorded macro, you'll want to name it something other than
  7594. %@AB@%recordvalue,%@AE@% the default name. To do this, pass the new name as an argument
  7595. when you start the recording:  %@NL@%
  7596. %@NL@%
  7597. %@NL@%
  7598.   ■   Press ALT+A ALT+A.%@NL@%
  7599. %@NL@%
  7600.   ■   Type the new name.%@NL@%
  7601. %@NL@%
  7602.   ■   Choose Record On from the Edit menu to start recording.%@NL@%
  7603. %@NL@%
  7604.   ■   Complete the recording as usual.%@NL@%
  7605. %@NL@%
  7606. %@NL@%
  7607. You can expand an existing macro using the same process. If you supply the
  7608. name of an existing macro, PWB appends the recorded commands to the macro
  7609. instead of replacing it.  %@NL@%
  7610. %@NL@%
  7611. %@AU@% You can record a series  of actions without  executing them.%@AE@%  %@NL@%
  7612. %@NL@%
  7613. You can also make a "silent" recording, which records a series of actions
  7614. without executing them. Start the recording with a %@AB@%meta record%@AE@% command
  7615. (press F9 SHIFT+CTRL+R). Then complete the recording process as described
  7616. above.  %@NL@%
  7617. %@NL@%
  7618. %@NL@%
  7619. %@2@%%@CR:C6A00080013 @%%@AB@%8.4  Writing and Building C Extensions%@AE@%%@EH@%%@NL@%
  7620. %@NL@%
  7621. An "extension" is a file containing one or more user-written functions. PWB
  7622. loads extensions at run time. Once the extension has been loaded, its
  7623. functions can be assigned their own keystrokes, given arguments, and invoked
  7624. in macros, exactly like other PWB functions.  %@NL@%
  7625. %@NL@%
  7626. %@AU@% User-written functions execute more quickly than macros.%@AE@%  %@NL@%
  7627. %@NL@%
  7628. The ability to load and call user-written functions makes PWB highly
  7629. extensible. Because they consist of compiled C code, your functions can
  7630. perform more complex jobs than macros can, and they execute many times
  7631. faster.  %@NL@%
  7632. %@NL@%
  7633. An extension contains executable code, but it differs from a normal
  7634. executable file in some important ways:%@CR:C6A00080014 @%  %@NL@%
  7635. %@NL@%
  7636. %@NL@%
  7637.   ■   It does not contain the usual C start-up code.%@NL@%
  7638. %@NL@%
  7639.   ■   It contains special data structures that describe its functions to
  7640.       PWB.%@NL@%
  7641. %@NL@%
  7642.   ■   Its functions are declared in a form that allows PWB to call them and
  7643.       pass arguments to them.%@NL@%
  7644. %@NL@%
  7645.   ■   Its functions can call native PWB functions, and some, but not all, C
  7646.       library functions.%@NL@%
  7647. %@NL@%
  7648. %@NL@%
  7649. This section explains how to build, load, and invoke a PWB extension. The
  7650. example, CENTER.C, serves as a basis for discussion throughout the rest of
  7651. this chapter.%@CR:C6A00080015 @%%@CR:C6A00080016 @%  %@NL@%
  7652. %@NL@%
  7653. The CENTER.C extension contains one extension function, %@AS@% %@AE@%CenterLine, which
  7654. centers a line or range of lines in the current file.  %@NL@%
  7655. %@NL@%
  7656. %@AS@%  /* CENTER.C: Sample PWB extension */
  7657. %@AS@%  
  7658. %@AS@%  #define LINE_LENGTH 80 /* Assumes 80-column screen */
  7659. %@AS@%  
  7660. %@AS@%  #include <string.h>
  7661. %@AS@%  /* PWB extension header file */
  7662. %@AS@%  #include "ext.h"
  7663. %@AS@%  
  7664. %@AS@%  PWBFUNC CenterLine( unsigned argData,
  7665. %@AS@%                      ARG _far *pArg,
  7666. %@AS@%                      flagType fMeta );
  7667. %@AS@%  
  7668. %@AS@%  /* Switch Table */
  7669. %@AS@%  struct swiDesc   swiTable[] =
  7670. %@AS@%  {
  7671. %@AS@%     { NULL, NULL, 0 }
  7672. %@AS@%  };
  7673. %@AS@%  
  7674. %@AS@%  /* Command Table */
  7675. %@AS@%  struct cmdDesc   cmdTable[] =
  7676. %@AS@%  {
  7677. %@AS@%     { "CenterLine", CenterLine, 0, NOARG | LINEARG },
  7678. %@AS@%     { NULL, NULL, 0, 0 }
  7679. %@AS@%  };
  7680. %@AS@%  
  7681. %@AS@%  /* Initialization Function */
  7682. %@AS@%  void EXTERNAL WhenLoaded( void )
  7683. %@AS@%  {
  7684. %@AS@%     DoMessage( "Loading Center extension" );
  7685. %@AS@%  }
  7686. %@AS@%  
  7687. %@AS@%  /* Extension (user-written) function */
  7688. %@AS@%  PWBFUNC CenterLine( unsigned argData,
  7689. %@AS@%                      ARG _far *pArg,
  7690. %@AS@%                      flagType fMeta )
  7691. %@AS@%  {
  7692. %@AS@%     PFILE pFile;
  7693. %@AS@%     LINE  yStart, yEnd;
  7694. %@AS@%     int   len;
  7695. %@AS@%     char *pBuf, buf[BUFLEN];%@AE@%%@NL@%
  7696. %@NL@%
  7697. %@AS@%  /* Get a handle to the current file */
  7698. %@AS@%     pFile = FileNameToHandle( "", "" );
  7699. %@AS@%  
  7700. %@AS@%     /* Handle various argument types */
  7701. %@AS@%     switch( pArg->argType )
  7702. %@AS@%     {
  7703. %@AS@%        case NOARG:  /* No argument. Center current line */
  7704. %@AS@%           yStart = yEnd = pArg->arg.noarg.y;
  7705. %@AS@%           break;
  7706. %@AS@%  
  7707. %@AS@%        case LINEARG:  /*  Center range of lines */
  7708. %@AS@%           yStart = pArg->arg.linearg.yStart;
  7709. %@AS@%           yEnd = pArg->arg.linearg.yEnd;
  7710. %@AS@%           break;
  7711. %@AS@%     }
  7712. %@AS@%  
  7713. %@AS@%     /* Center current line or range of lines */
  7714. %@AS@%     for( ; yStart <= yEnd; yStart++ )
  7715. %@AS@%     {
  7716. %@AS@%        /* Get a line from the current file */
  7717. %@AS@%        len = GetLine( yStart, buf, pFile );
  7718. %@AS@%  
  7719. %@AS@%        if( len > 0 )
  7720. %@AS@%        {
  7721. %@AS@%           /* Center the text in this line */
  7722. %@AS@%           pBuf = buf + strspn( buf, " \t" );
  7723. %@AS@%           len = strlen( pBuf );
  7724. %@AS@%           memmove( buf+(LINE_LENGTH-len) / 2, pBuf, len+1 );
  7725. %@AS@%           memset( buf, ' ', (LINE_LENGTH - len) / 2 );
  7726. %@AS@%  
  7727. %@AS@%           /* Write modified line back to the current file */
  7728. %@AS@%           PutLine( yStart, buf, pFile );
  7729. %@AS@%        }
  7730. %@AS@%     }
  7731. %@AS@%     return TRUE;
  7732. %@AS@%  }%@AE@%%@NL@%
  7733. %@NL@%
  7734. Building and using a PWB extension involves four basic steps:%@CR:C6A00080017 @%  %@NL@%
  7735. %@NL@%
  7736. %@NL@%
  7737.   1.  Compiling%@NL@%
  7738. %@NL@%
  7739.   2.  Linking%@NL@%
  7740. %@NL@%
  7741.   3.  Loading the extension into PWB%@NL@%
  7742. %@NL@%
  7743.   4.  Assigning a keystroke to each function in the extension%@NL@%
  7744. %@NL@%
  7745. %@NL@%
  7746. You can build extensions for both real mode (DOS) and OS/2 protected mode.  %@NL@%
  7747. %@NL@%
  7748. %@NL@%
  7749. %@3@%%@CR:C6A00080018 @%%@AB@%8.4.1  Building Real-Mode Extensions%@AE@%%@EH@%%@NL@%
  7750. %@NL@%
  7751. This section describes how to build extensions for real mode.%@CR:C6A00080019 @%  %@NL@%
  7752. %@NL@%
  7753. %@NL@%
  7754. %@4@%%@AB@%Compiling%@AE@%%@EH@%%@NL@%
  7755. %@NL@%
  7756. The source (.C) file for an extension must include EXT.H, the extension
  7757. header file. Since an extension is not a stand-alone executable file, it
  7758. doesn't have a %@AB@%main%@AE@% function; so its source file is compiled with the /c
  7759. (compile, but don't link) option:  %@NL@%
  7760. %@NL@%
  7761. %@AS@%  CL /c /Gs /ACw CENTER.C%@AE@%%@NL@%
  7762. %@NL@%
  7763. The /Gs option turns off stack checking; the /ACw option selects the
  7764. required custom memory model.  %@NL@%
  7765. %@NL@%
  7766. PWB extension interface is designed for C programmers. However, you can
  7767. write extensions in assembly language or other languages if you simulate the
  7768. required C memory model (in which SS is not assumed to equal DS).  %@NL@%
  7769. %@NL@%
  7770. %@NL@%
  7771. %@4@%%@AB@%Linking%@AE@%%@EH@%%@NL@%
  7772. %@NL@%
  7773. The first object file in the link command must be the stub EXTHDR.OBJ:  %@NL@%
  7774. %@NL@%
  7775. %@AS@%  link exthdr center, center.mxt;%@AE@%%@NL@%
  7776. %@NL@%
  7777. PWB can load a file with any name, but most programmers use the .MXT
  7778. extension to distinguish a PWB extension from a normal .EXE file.  %@NL@%
  7779. %@NL@%
  7780. %@NL@%
  7781. %@4@%%@AB@%Loading the Extension%@AE@%%@EH@%%@NL@%
  7782. %@NL@%
  7783. Once the extension is built, you can cause PWB to load it by adding a %@AB@%load%@AE@%
  7784. command to your TOOLS.INI file:  %@NL@%
  7785. %@NL@%
  7786. %@AS@%  load:center%@AE@%%@NL@%
  7787. %@NL@%
  7788. You don't need to supply a file extension; PWB assumes the correct file
  7789. extension. To specify a path, supply the path name preceded by a dollar sign
  7790. ($):  %@NL@%
  7791. %@NL@%
  7792. %@AS@%  load:$INIT:center%@AE@%%@NL@%
  7793. %@NL@%
  7794. The example tells PWB to search the directories specified in the INIT
  7795. environment variable. If listed, the environment variable must be in
  7796. uppercase.  %@NL@%
  7797. %@NL@%
  7798. TOOLS.INI can contain multiple %@AB@%load%@AE@% commands for different extensions.
  7799. However, loading each extension involves a certain amount of memory
  7800. overhead, and there is no way to unload an extension from memory. To
  7801. conserve memory, place all frequently used functions in a single extension
  7802. and load only that extension.%@CR:C6A00080020 @%  %@NL@%
  7803. %@NL@%
  7804. %@NL@%
  7805. %@4@%%@AB@%Assigning Keystrokes to Functions%@AE@%%@EH@%%@NL@%
  7806. %@NL@%
  7807. After an extension has been loaded, you must provide some way to invoke its
  7808. functions from inside PWB. A keystroke is the most common means, although
  7809. extension functions, like native PWB functions, can be invoked in various
  7810. ways.  %@NL@%
  7811. %@NL@%
  7812. You can assign the ALT+C keystroke to the %@AS@% CenterLine %@AE@% function with:  %@NL@%
  7813. %@NL@%
  7814. %@AS@%  CenterLine:alt+c%@AE@%%@NL@%
  7815. %@NL@%
  7816. Once the %@AS@% CenterLine %@AE@% function has been assigned to this keystroke, you can
  7817. invoke it by pressing ALT+C.  %@NL@%
  7818. %@NL@%
  7819. %@NL@%
  7820. %@3@%%@CR:C6A00080021 @%%@AB@%8.4.2  Building Protected-Mode Extensions%@AE@%%@EH@%%@NL@%
  7821. %@NL@%
  7822. The build process for OS/2 protected mode differs only slightly from the
  7823. real-mode build process.%@CR:C6A00080022 @%  %@NL@%
  7824. %@NL@%
  7825. %@NL@%
  7826. %@4@%%@AB@%Compiling%@AE@%%@EH@%%@NL@%
  7827. %@NL@%
  7828. The source (.C) file for an extension must include EXT.H, the extension
  7829. header file. Since an extension is not a stand-alone executable file, it
  7830. doesn't have a %@AB@%main%@AE@% function; so its source file is compiled with the /c
  7831. (compile, but don't link) option:  %@NL@%
  7832. %@NL@%
  7833. %@AS@%  CL /c /Gs /ACw CENTER.C%@AE@%%@NL@%
  7834. %@NL@%
  7835. The /Gs option turns off stack checking; the /ACw option selects the
  7836. required custom memory model.  %@NL@%
  7837. %@NL@%
  7838. PWB extension interface is designed for C programmers. However, you can
  7839. write extensions in assembly language or other languages if you simulate the
  7840. required C memory model (in which SS is not assumed to equal DS).  %@NL@%
  7841. %@NL@%
  7842. %@NL@%
  7843. %@4@%%@AB@%Linking%@AE@%%@EH@%%@NL@%
  7844. %@NL@%
  7845. Link with EXTHRDP.OBJ instead of EXTHDR.OBJ. Specify the .PXT extension for
  7846. the output file. List the EXT.DEF definitions file:  %@NL@%
  7847. %@NL@%
  7848. %@AS@%  link exthdrp center, center.pxt,, os2, ext.def%@AE@%%@NL@%
  7849. %@NL@%
  7850. %@NL@%
  7851. %@4@%%@AB@%Loading the Extension%@AE@%%@EH@%%@NL@%
  7852. %@NL@%
  7853. In protected mode, PWB assumes the .PXT file extension. If your extension is
  7854. not found, PWB assumes the .DLL file extension.%@CR:C6A00080023 @%  %@NL@%
  7855. %@NL@%
  7856. %@AU@% You cannot create a bound extension.%@AE@%  %@NL@%
  7857. %@NL@%
  7858. There is no way to create a bound extension (one that runs in both real and
  7859. protected mode). However, you can build separate versions of an extension
  7860. and use a single TOOLS.INI %@AB@%load%@AE@% command to load the correct extension in
  7861. each mode. PWB loads the real-mode file (.MXT) in real mode and the
  7862. protected-mode file (.PXT or .DLL) in protected mode.  %@NL@%
  7863. %@NL@%
  7864. %@NL@%
  7865. %@4@%%@AB@%Assigning Keystrokes to Functions%@AE@%%@EH@%%@NL@%
  7866. %@NL@%
  7867. After an extension has been loaded, you must provide some way to invoke its
  7868. functions from inside PWB. A keystroke is the most common means, although
  7869. extension functions, like native PWB functions, can be invoked in various
  7870. ways.  %@NL@%
  7871. %@NL@%
  7872. You can assign the ALT+C keystroke to the %@AS@% CenterLine %@AE@% function with:  %@NL@%
  7873. %@NL@%
  7874. %@AS@%  CenterLine:alt+c%@AE@%%@NL@%
  7875. %@NL@%
  7876. Once the %@AS@% CenterLine %@AE@% function has been assigned to this keystroke, you can
  7877. invoke it by pressing ALT+C.  %@NL@%
  7878. %@NL@%
  7879. %@NL@%
  7880. %@3@%%@CR:C6A00080024 @%%@AB@%8.4.3  Describing Functions and Switches%@AE@%%@EH@%%@NL@%
  7881. %@NL@%
  7882. To call functions in your extension, PWB must know certain information about
  7883. each function, such as the name and address of the function, what types of
  7884. arguments it accepts, and what switches (if any) it employs. You provide
  7885. this information in a pair of arrays─%@AB@%cmdTable%@AE@% and %@AB@%swiTable%@AE@%─that must be
  7886. present in every PWB extension.%@CR:C6A00080025 @%  %@NL@%
  7887. %@NL@%
  7888. %@NL@%
  7889. %@4@%%@AB@%The cmdTable Array%@AE@%%@EH@%%@NL@%
  7890. %@NL@%
  7891. Every extension must contain an array of structures named %@AB@%cmdTable%@AE@%. This
  7892. array provides the information PWB needs to call the extension's functions.
  7893. %@NL@%
  7894. %@NL@%
  7895. The %@AB@%cmdTable%@AE@% array is an array of structures of type %@AB@%cmdDesc%@AE@% (which is
  7896. declared in EXT.H). Each structure in the array describes one function in
  7897. the extension. The array is terminated with a structure whose members are
  7898. all null.  %@NL@%
  7899. %@NL@%
  7900. For instance, the CENTER.C extension has one function, named %@AS@% CenterLine%@AE@%, so
  7901. its %@AB@%cmdTable%@AE@% array contains two structures (one for %@AS@% CenterLine %@AE@% and the
  7902. other to terminate the table):%@CR:C6A00080026 @%  %@NL@%
  7903. %@NL@%
  7904. %@AS@%  struct cmdDesc cmdTable[] =
  7905. %@AS@%  {
  7906. %@AS@%     { "CenterLine", CenterLine, 0, NOARG | LINEARG },
  7907. %@AS@%     { NULL, NULL, 0, 0 }
  7908. %@AS@%  };%@AE@%%@NL@%
  7909. %@NL@%
  7910. Each %@AB@%cmdDesc%@AE@% structure in %@AB@%cmdTable%@AE@% contains these members:  %@NL@%
  7911. %@NL@%
  7912. %@NL@%
  7913.   ■   The function's name%@NL@%
  7914. %@NL@%
  7915.   ■   The function's address%@NL@%
  7916. %@NL@%
  7917.   ■   Reserved item (must be 0)%@NL@%
  7918. %@NL@%
  7919.   ■   The argument types the function accepts%@NL@%
  7920. %@NL@%
  7921. %@NL@%
  7922. The last member in the list is an integer containing bitflags representing
  7923. types of arguments that your function accepts. You can combine more than one
  7924. bitflag using the %@AB@%OR%@AE@% (%@AB@% | %@AE@%) operator.  %@NL@%
  7925. %@NL@%
  7926. For instance, the %@AS@% CenterLine %@AE@% function can handle an argument of the type
  7927. %@AB@%LINEARG%@AE@%, or no arguments (%@AB@%NOARG%@AE@%). So it lists the types:  %@NL@%
  7928. %@NL@%
  7929. %@AS@%  NOARG | LINEARG%@AE@%%@NL@%
  7930. %@NL@%
  7931. There are many argument types in addition to these. For information about
  7932. specific argument types, see the Extensions topic in on-line help.  %@NL@%
  7933. %@NL@%
  7934. %@NL@%
  7935. %@4@%%@AB@%The swiTable Array%@AE@%%@EH@%%@NL@%
  7936. %@NL@%
  7937. Extension functions, such as native PWB functions, can respond to user-
  7938. configurable switches. From the viewpoint of an extension function, a switch
  7939. is usually a variable that the user can change at run time. Your function
  7940. must be ready to respond to these changes, and PWB must have some way to
  7941. convey them. The vehicle for this interchange is an array of structures
  7942. named %@AB@%swiTable%@AE@%.  %@NL@%
  7943. %@NL@%
  7944. The %@AB@%swiTable%@AE@% array is similar to the %@AB@%cmdTable%@AE@% array described above. It is
  7945. an array of structures, terminated by a structure whose members are all
  7946. null. Each structure in %@AB@%swiTable%@AE@% describes one switch used by a function in
  7947. your extension.  %@NL@%
  7948. %@NL@%
  7949. The CENTER.C extension doesn't take any switches, so its %@AB@%swiTable%@AE@% array only
  7950. contains a terminating null structure:%@CR:C6A00080027 @%  %@NL@%
  7951. %@NL@%
  7952. %@AS@%  struct swiDesc swiTable[] =
  7953. %@AS@%  {
  7954. %@AS@%      { NULL, NULL, 0 }
  7955. %@AS@%  };%@AE@%%@NL@%
  7956. %@NL@%
  7957. Each structure in %@AB@%swiTable%@AE@% is of type %@AB@%swiDesc%@AE@%, whose members are  %@NL@%
  7958. %@NL@%
  7959. %@NL@%
  7960.   ■   A pointer to the switch name%@NL@%
  7961. %@NL@%
  7962.   ■   A pointer to the switch or a function%@NL@%
  7963. %@NL@%
  7964.   ■   A flag that indicates the type of the switch%@NL@%
  7965. %@NL@%
  7966. %@NL@%
  7967. A switch can be one of three types: %@AB@%SWI_BOOLEAN%@AE@% for TRUE/FALSE conditions,
  7968. %@AB@%SWI_NUMERIC%@AE@% for numerics, or %@AB@%SWI_SPECIAL%@AE@% for strings.  %@NL@%
  7969. %@NL@%
  7970. The second member of %@AB@%swiDesc%@AE@% is a pointer. It points to the switch itself if
  7971. the switch is type %@AB@%SWI_BOOLEAN%@AE@% or %@AB@%SWI_NUMERIC%@AE@%, or to a string-handling
  7972. function if the switch is type %@AB@%SWI_SPECIAL%@AE@%.  %@NL@%
  7973. %@NL@%
  7974. For instance, the following code creates a numeric switch with the default
  7975. value 27:  %@NL@%
  7976. %@NL@%
  7977. %@AS@%  static int n = 27;
  7978. %@AS@%  
  7979. %@AS@%  struct swiDesc swiTable[] =
  7980. %@AS@%  {
  7981. %@AS@%     { "newswitch", &n, SWI_NUMERIC | RADIX10 },
  7982. %@AS@%     { NULL,  NULL, 0 }
  7983. %@AS@%  };%@AE@%%@NL@%
  7984. %@NL@%
  7985. The first structure in the example above contains the name of the switch
  7986. (%@AS@%"newswitch"%@AE@%), a pointer to the variable that contains the switch's value
  7987. (%@AS@%&n%@AE@%), and the switch's type (%@AB@%SWI_NUMERIC%@AE@%).  %@NL@%
  7988. %@NL@%
  7989. In this example, the third structure member contains another constant,
  7990. %@AB@%RADIX10%@AE@%. If a switch is type %@AB@%SWI_NUMERIC%@AE@%, you must supply a second constant
  7991. to tell PWB whether to interpret user-assigned values as decimal (%@AB@%RADIX10%@AE@%)
  7992. or hexadecimal (%@AB@%RADIX16%@AE@%) numbers.  %@NL@%
  7993. %@NL@%
  7994. If the switch is type %@AB@%SWI_SPECIAL%@AE@%, the second member of %@AB@%swiDesc%@AE@% is a pointer
  7995. to an additional string-handling function that you write. This function must
  7996. be of type %@AB@%int far _pascal%@AE@%. Each time the text switch changes, PWB calls
  7997. your function, passing it the address of the updated string as a %@AB@%char far%@AE@%
  7998. pointer. The following code stores the updated string in a buffer named %@AS@%
  7999. %@AS@%mystring%@AE@%:%@CR:C6A00080028 @%  %@NL@%
  8000. %@NL@%
  8001. %@AS@%  char mystring[BUFLEN];
  8002. %@AS@%  
  8003. %@AS@%  int far _pascal setstr( char far *ptr )
  8004. %@AS@%  {
  8005. %@AS@%     strcpy( mystring, ptr );
  8006. %@AS@%  }%@AE@%%@NL@%
  8007. %@NL@%
  8008. If desired, you can list switches for extension functions separately from
  8009. other switches. Whenever PWB loads an extension, it looks in TOOLS.INI for a
  8010. section with this form:  %@NL@%
  8011. %@NL@%
  8012. %@AS@%  [PWB-ext]%@AE@%%@NL@%
  8013. %@NL@%
  8014. where %@AI@%ext%@AE@% is the base name of the extension. If the extension exists, PWB
  8015. recognizes the settings immediately following the tag. For instance, if your
  8016. extension SAMPLE.MXT uses a numeric switch named %@AS@% numbills%@AE@%, you can set %@AS@%
  8017. %@AS@%numbills %@AE@% to the value 66 with:  %@NL@%
  8018. %@NL@%
  8019. %@AS@%  [PWB-SAMPLE]
  8020. %@AS@%  numbills:66%@AE@%%@NL@%
  8021. %@NL@%
  8022. %@NL@%
  8023. %@3@%%@CR:C6A00080029 @%%@AB@%8.4.4  Initializing Functions%@AE@%%@EH@%%@NL@%
  8024. %@NL@%
  8025. Every PWB extension must contain a function named %@AB@%WhenLoaded%@AE@%, which PWB
  8026. calls immediately after loading the extension. The %@AB@%WhenLoaded%@AE@% function
  8027. provides a chance to do any initialization that your functions require. (If
  8028. your functions don't need any initialization, they can simply return.)  %@NL@%
  8029. %@NL@%
  8030. The CENTER.C extension uses %@AB@%WhenLoaded%@AE@% to display a loading message:%@CR:C6A00080030 @%%@CR:C6A00080031 @%%@CR:C6A00080032 @%  %@NL@%
  8031. %@NL@%
  8032. %@AS@%  void EXTERNAL WhenLoaded( void )
  8033. %@AS@%  {
  8034. %@AS@%      DoMessage( "Loading Center extension" );
  8035. %@AS@%  }%@AE@%%@NL@%
  8036. %@NL@%
  8037. %@AB@%DoMessage%@AE@% is a PWB function that displays a message on the dialog line.
  8038. Section 8.4.7, "Calling PWB Functions," lists PWB functions and explains how
  8039. to call them.  %@NL@%
  8040. %@NL@%
  8041. %@NL@%
  8042. %@3@%%@CR:C6A00080033 @%%@AB@%8.4.5  Prototyping Functions%@AE@%%@EH@%%@NL@%
  8043. %@NL@%
  8044. To be called by PWB, each extension function must be declared as type
  8045. %@AB@%PWBFUNC%@AE@% and accept the parameters %@AB@%argData%@AE@%, %@AB@%pArg%@AE@%, and %@AB@%fMeta%@AE@%. The %@AS@% CenterLine
  8046. %@AS@%%@AE@%function in the section of CENTER.C code below follows  this model:  %@NL@%
  8047. %@NL@%
  8048. %@AS@%  PWBFUNC CenterLine( unsigned argData, 
  8049. %@AS@%                      ARG _far *pArg,
  8050. %@AS@%                      flagType fMeta )%@AE@%%@NL@%
  8051. %@NL@%
  8052. The %@AB@%PWBFUNC%@AE@% type is actually a macro that evaluates to %@AB@%flagType _pascal
  8053. %@AB@%_loadds _far%@AE@%. The %@AB@%flagType%@AE@% return type declares that the function returns
  8054. either TRUE (nonzero) or FALSE (zero). Your function should return a value
  8055. so that it can be used in a macro with conditionals. The modifiers %@AB@%_pascal%@AE@%,
  8056. %@AB@%_loadds%@AE@%, and %@AB@%_far%@AE@% specify the calling conventions PWB expects editor
  8057. functions to have.  %@NL@%
  8058. %@NL@%
  8059. %@NL@%
  8060. %@3@%%@CR:C6A00080034 @%%@AB@%8.4.6  Receiving Parameters%@AE@%%@EH@%%@NL@%
  8061. %@NL@%
  8062. Like native PWB functions, extension functions can receive parameters from
  8063. the user. The CENTER.C example allows you to select a range of lines to
  8064. center, for example. The selected range is passed as a parameter to the %@AS@%
  8065. %@AS@%CenterLine %@AE@% function.%@CR:C6A00080035 @%%@CR:C6A00080036 @%%@CR:C6A00080037 @%  %@NL@%
  8066. %@NL@%
  8067. Extension functions receive parameters in much the same way ordinary C
  8068. programs receive command-line parameters. In both cases, the parameters are
  8069. passed in a predefined data construct─%@AB@%argc%@AE@% and %@AB@%argv%@AE@% for a normal C program,
  8070. and the following parameters for an extension function:  %@NL@%
  8071. %@NL@%
  8072. %@AB@%Parameter%@AE@%                         %@AB@%Description%@AE@%
  8073. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8074. %@AB@%argData%@AE@%                           The keystroke used to invoke your 
  8075.                                   function
  8076.  
  8077. %@AB@%pArg%@AE@%                              A pointer to a structure containing 
  8078.                                   arguments passed to your function
  8079.  
  8080. %@AB@%fMeta%@AE@%                             TRUE (nonzero) if %@AB@%meta%@AE@% precedes the 
  8081.                                   argument, otherwise FALSE (zero)
  8082.  
  8083. The first parameter is rarely used. Most extension functions receive all
  8084. their parameter data in the second parameter, %@AB@%pArg%@AE@%. This parameter is a
  8085. pointer to a structure of type %@AB@%ARG%@AE@%, which contains:  %@NL@%
  8086. %@NL@%
  8087. %@AB@%Parameter%@AE@%                         %@AB@%Description%@AE@%
  8088. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8089. %@AB@%argType%@AE@%                           An integer that indicates the argument 
  8090.                                   type
  8091.  
  8092. %@AB@%arg%@AE@%                               A union of structures, one structure for
  8093.                                   each
  8094.                                   argument type
  8095.  
  8096. Typically, your function tests %@AB@%pArg->argType%@AE@% to find out what type of
  8097. parameter PWB has passed. Once the type is known, the function responds
  8098. accordingly. The following code from CENTER.C handles two argument types:%@CR:C6A00080038 @%  %@NL@%
  8099. %@NL@%
  8100. %@AS@%  switch( pArg->argType )
  8101. %@AS@%  {
  8102. %@AS@%     case NOARG:  /* No argument. Center current line */
  8103. %@AS@%        yStart = yEnd = pArg->arg.noarg.y;
  8104. %@AS@%        break;
  8105. %@AS@%  
  8106. %@AS@%     case LINEARG:  /*  Center range of lines */
  8107. %@AS@%        yStart = pArg->arg.linearg.yStart;
  8108. %@AS@%        yEnd = pArg->arg.linearg.yEnd;
  8109. %@AS@%        break;
  8110. %@AS@%  }%@AE@%%@NL@%
  8111. %@NL@%
  8112. %@AU@% PWB rejects invalid arguments.%@AE@%  %@NL@%
  8113. %@NL@%
  8114. If your function takes only one argument, it doesn't need to test
  8115. %@AB@%pArg->argType%@AE@% at all. PWB knows beforehand what argument types your function
  8116. accepts (via %@AB@%cmdDesc%@AE@%) and rejects any invalid arguments.  %@NL@%
  8117. %@NL@%
  8118. Once the argument type is known, your function can access the parameters
  8119. through %@AB@%pArg->arg%@AE@%, a structure whose members differ for each argument type.
  8120. In the %@AB@%NOARG%@AE@% (no arguments) case, it contains %@AI@%x%@AE@% and %@AI@%y%@AE@% values identifying the
  8121. cursor position in the current file:  %@NL@%
  8122. %@NL@%
  8123. %@AS@%  struct noargType
  8124. %@AS@%  {           /* no argument    */
  8125. %@AS@%     LINE y;  /* cursor line    */
  8126. %@AS@%     COL  x;  /* cursor column  */
  8127. %@AS@%  };%@AE@%%@NL@%
  8128. %@NL@%
  8129. The CENTER.C example uses the %@AI@%y%@AE@% value in this structure (%@AB@%noarg.y%@AE@%, the cursor
  8130. line) to center the current line:  %@NL@%
  8131. %@NL@%
  8132. %@AS@%  case NOARG:  /* No argument. Center current line */
  8133. %@AS@%     yStart = yEnd = pArg->arg.noarg.y;
  8134. %@AS@%     break;%@AE@%%@NL@%
  8135. %@NL@%
  8136. Similarly, in the %@AB@%LINEARG%@AE@% case, the %@AB@%pArg->arg%@AE@% structure contains three
  8137. values:  %@NL@%
  8138. %@NL@%
  8139. %@AS@%  struct lineargType
  8140. %@AS@%  {                /* line argument specified */
  8141. %@AS@%     int  cArg;    /* count of args pressed   */
  8142. %@AS@%     LINE yStart;  /* starting line of range  */
  8143. %@AS@%     LINE yEnd;    /* ending line of range    */
  8144. %@AS@%  };%@AE@%%@NL@%
  8145. %@NL@%
  8146. The CENTER.C example uses the starting and ending values in this structure
  8147. (%@AB@%yStart%@AE@% and %@AB@%yEnd%@AE@%) to center a range of selected lines:  %@NL@%
  8148. %@NL@%
  8149. %@AS@%  case LINEARG:  /*  Center range of lines */
  8150. %@AS@%     yStart = pArg->arg.linearg.yStart;
  8151. %@AS@%     yEnd = pArg->arg.linearg.yEnd;
  8152. %@AS@%     break;%@AE@%%@NL@%
  8153. %@NL@%
  8154. The method is the same for other argument types. The %@AB@%pArg->arg%@AE@% structures
  8155. for all argument types are described in on-line help.  %@NL@%
  8156. %@NL@%
  8157. %@NL@%
  8158. %@3@%%@CR:C6A00080039 @%%@AB@%8.4.7  Calling PWB Functions%@AE@%%@EH@%%@NL@%
  8159. %@NL@%
  8160. Many of PWB's internal functions are public. Your extension function can
  8161. call them for the same purposes that PWB itself does. This section
  8162. demonstrates the most commonly used PWB functions─those that manipulate the
  8163. current file.%@CR:C6A00080040 @%%@CR:C6A00080041 @%  %@NL@%
  8164. %@NL@%
  8165. A list of callable PWB functions appears near the end of this section. For
  8166. complete information on specific PWB functions, consult on-line help.  %@NL@%
  8167. %@NL@%
  8168. %@NL@%
  8169. %@4@%%@AB@%Getting a File Handle%@AE@%%@EH@%%@NL@%
  8170. %@NL@%
  8171. Extension functions can do many different tasks, but they typically
  8172. manipulate a file in some way. The extension function in the CENTER.C
  8173. example rewrites a line or lines in the current file, for example. The
  8174. current file is the one that appears in the editing window. Since it is
  8175. already open for editing, you can access the current file without opening
  8176. it. Simply assign its file handle to a variable in your function.  %@NL@%
  8177. %@NL@%
  8178. PWB file-handling functions use file handles of type %@AB@%PFILE%@AE@%. The CENTER.C
  8179. example declares the following handle variable:  %@NL@%
  8180. %@NL@%
  8181. %@AS@%  PFILE pFile;%@AE@%%@NL@%
  8182. %@NL@%
  8183. The %@AB@%FileNameToHandle%@AE@% function gets a handle to a file that is already open
  8184. for editing:  %@NL@%
  8185. %@NL@%
  8186. %@AS@%  pFile = FileNameToHandle( "", "" );%@AE@%%@NL@%
  8187. %@NL@%
  8188. The function takes two string arguments. If the first string is null, as
  8189. here, the %@AB@%FileNameToHandle%@AE@% function returns a handle to the current file.
  8190. You can use the %@AB@%AddFile%@AE@% function to get handles to other files (in which
  8191. case you may need to use other PWB functions such as %@AB@%FileRead%@AE@%).%@CR:C6A00080042 @%  %@NL@%
  8192. %@NL@%
  8193. %@NL@%
  8194. %@4@%%@AB@%Reading a Line From the File%@AE@%%@EH@%%@NL@%
  8195. %@NL@%
  8196. Once your function has a file handle, it can read from the file with the
  8197. %@AB@%GetLine%@AE@% function, which reads one line at a time:  %@NL@%
  8198. %@NL@%
  8199. %@AS@%  len = GetLine( yStart, buf, pFile );%@AE@%%@NL@%
  8200. %@NL@%
  8201. The first argument is a line number, the second a pointer to a buffer, and
  8202. the third a file handle. So the above call reads line number %@AS@% yStart %@AE@% from
  8203. the file whose handle is %@AS@% pFile %@AE@% into the buffer %@AS@% buf%@AE@%. Note that the first
  8204. line in a file is line 0, not line 1.  %@NL@%
  8205. %@NL@%
  8206. Once you have read a line into a local buffer, you can manipulate it as
  8207. desired. CENTER.C uses its buffer %@AS@% buf %@AE@% to center the line's text.  %@NL@%
  8208. %@NL@%
  8209. %@NL@%
  8210. %@4@%%@AB@%Writing a Line to the File%@AE@%%@EH@%%@NL@%
  8211. %@NL@%
  8212. After modifying a line, you can write it back to the file. The %@AB@%PutLine%@AE@%
  8213. function writes one line at a time:  %@NL@%
  8214. %@NL@%
  8215. %@AS@%  PutLine( yStart, buf, pFile );%@AE@%%@NL@%
  8216. %@NL@%
  8217. %@AB@%PutLine%@AE@% takes the same arguments as %@AB@%GetLine%@AE@%─a line number, buffer pointer,
  8218. and file handle. In CENTER.C, the above call writes the line from %@AS@% buf %@AE@% to
  8219. line %@AS@% %@AE@%yStart  in the file whose handle is %@AS@% pFile%@AE@%.  %@NL@%
  8220. %@NL@%
  8221. %@NL@%
  8222. %@4@%%@AB@%Summary of PWB Functions%@AE@%%@EH@%%@NL@%
  8223. %@NL@%
  8224. If you understand how CENTER.C works, you know the basics of using PWB
  8225. functions in your own functions. The rest is just a matter of learning the
  8226. details of individual functions. Table 8.1 lists the PWB functions, grouping
  8227. them by category. For additional information on specific functions, consult
  8228. on-line help.%@CR:C6A00080043 @%  %@NL@%
  8229. %@NL@%
  8230. %@AB@%Table 8.1  %@AB@%Callable PWB Functions%@AE@%%@AE@%
  8231.  
  8232. %@TH:  50  2028 02 19 19 38 @%Category           Function           Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Block Operations   %@AB@%CopyBox%@AE@%            Insert rectangular area                   %@AB@%CopyLine%@AE@%           Insert range of lines                   %@AB@%CopyStream%@AE@%         Insert stream of text                   %@AB@%DelBox%@AE@%             Delete rectangular area                   %@AB@%DelLine%@AE@%            Delete range of lines                   %@AB@%DelStream%@AE@%          Delete stream of textBuild              %@AB@%fGetMake%@AE@%           Get %@AB@%extmake%@AE@% setting                   %@AB@%fSetMake%@AE@%           Set %@AB@%extmake%@AE@% settingColor              %@AB@%GetColor%@AE@%           Get color of specified line                   %@AB@%PutColor%@AE@%           Set color of specified lineCursor             %@AB@%GetCursor%@AE@%          Get cursor position                   %@AB@%MoveCur%@AE@%            Move cursorDialog             %@AB@%DoMessageBox%@AE@%       Create message dialog                   %@AB@%PopUpBox%@AE@%           Display text in dialog                                       windowDisplay            %@AB@%BadArg%@AE@%             Report that argument was invalid                   %@AB@%Display%@AE@%            Update screen                   %@AB@%DoMessage%@AE@%          Display message on dialog lineFile               %@AB@%AddFile%@AE@%            Open new file and get file handle                   %@AB@%DelFile %@AE@%           Delete contents of file buffer                   %@AB@%fChangeFile%@AE@%        Change current file to named file                   %@AB@%FileNameToHandle%@AE@%   Get handle to open file                   %@AB@%FileRead%@AE@%           Copy disk file to file                                       buffer                   %@AB@%FileWrite%@AE@%          Copy file buffer to disk file%@TE:  50  2028 02 19 19 38 @%
  8233.  
  8234. %@AB@%Table 8.1  %@AB@% (continued)%@AE@%%@AE@%
  8235.  
  8236. %@TH:  71  2738 02 17 18 41 @%Category         Function          Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%                 %@AB@%pFileToTop%@AE@%        Make specified file the current file                 %@AB@%RemoveFile%@AE@%        Remove file from memoryKeyboard         %@AB@%KbHook %@AE@%           Restore keyboard control to PWB%@CR:C6A00080044 @%                 %@AB@%KbUnHook%@AE@%          Remove keyboard control from PWB                 %@AB@%ReadChar%@AE@%          Get information on next keystrokeFormat           %@AB@%ReadCmd%@AE@%           Get keystroke information in %@AB@%CmdDesc%@AE@%Line             %@AB@%FileLength%@AE@%        Get length of file                 %@AB@%GetLine%@AE@%           Get line from file                 %@AB@%PutLine%@AE@%           Write line to fileList             %@AB@%GetListEntry%@AE@%      Get item from list                 %@AB@%ScanList%@AE@%          Process listMemory           %@AB@%Falloc%@AE@%            Allocate far memory                 %@AB@%Fdalloc%@AE@%           Deallocate far memoryMiscellaneous    %@AB@%fExecute%@AE@%          Execute macro                 %@AB@%FindSwitch%@AE@%        Get information about switch                 %@AB@%GetEditorObject%@AE@%   Get internal PWB data item                 %@AB@%GetString%@AE@%         Get input from dialog line                 %@AB@%mgetenv%@AE@%           Get environment string                 %@AB@%NameToFunc%@AE@%        Get information about function or macro                 %@AB@%NameToKeys%@AE@%        Get key(s) assigned to specified                                    function                 %@AB@%Replace%@AE@%           Replace character                 %@AB@%SetEditorObject%@AE@%   Set internal PWB data item                 %@AB@%SetKey%@AE@%            Assign function to                                    keystrokeSearch           %@AB@%REsearch%@AE@%          Search for regular                                    expression                 %@AB@%search%@AE@%            Search for stringVirtual Memory   %@AB@%fpbtoVM%@AE@%           Copy data to virtual memory                 %@AB@%VMalloc%@AE@%           Allocate virtual memory                 %@AB@%VMFree%@AE@%            Free virtual memory                 %@AB@%VMtofpb%@AE@%           Copy data from virtual memoryWindow           %@AB@%CloseWnd%@AE@%          Close window                 %@AB@%Resize%@AE@%            Resize window                 %@AB@%SplitWnd%@AE@%          Split window%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  71  2738 02 17 18 41 @%
  8237.  
  8238. %@CR:C6A00080045 @%%@NL@%
  8239. %@3@%%@CR:C6A00080046 @%%@AB@%8.4.8  Calling C Library Functions%@AE@%%@EH@%%@NL@%
  8240. %@NL@%
  8241. You can write many useful extension functions using only PWB functions
  8242. listed in the previous section. It is also possible to call C library
  8243. routines, with some limitations. An extension written for OS/2 protected
  8244. mode can call any C library routine if it is linked with EXTHDRP.OBJ and the
  8245. .DLL C run-time library. The list of usable routines is shorter for
  8246. real-mode (DOS) extensions linked with the non-.DLL run-time library.%@CR:C6A00080047 @%  %@NL@%
  8247. %@NL@%
  8248. Before you call a C library routine, ask whether the task can be done with a
  8249. PWB function. If the answer is yes, you should always call a PWB function in
  8250. preference to the C library routine. This practice ensures compatibility
  8251. between your functions and PWB.  %@NL@%
  8252. %@NL@%
  8253. The following categories of C library routines are always safe to use in
  8254. real mode:  %@NL@%
  8255. %@NL@%
  8256. %@NL@%
  8257.   ■   Buffer manipulation%@NL@%
  8258. %@NL@%
  8259.   ■   Character classification and conversion%@NL@%
  8260. %@NL@%
  8261.   ■   Data conversion%@NL@%
  8262. %@NL@%
  8263.   ■   String manipulation%@NL@%
  8264. %@NL@%
  8265. %@NL@%
  8266. This list includes the library routines you are most likely to need in an
  8267. extension function. If your extension function calls C library functions,
  8268. you must link with the compact-model C library.  %@NL@%
  8269. %@NL@%
  8270. The following routines should not be used in real mode:  %@NL@%
  8271. %@NL@%
  8272. %@NL@%
  8273.   ■   Routines that need C start-up support (most input/output functions)%@NL@%
  8274. %@NL@%
  8275.   ■   Memory management routines, such as %@AB@%malloc%@AE@%, and routines that call
  8276.       them%@NL@%
  8277. %@NL@%
  8278.   ■   Process control routines such as %@AB@%spawn%@AE@% and %@AB@%exec%@AE@%%@NL@%
  8279. %@NL@%
  8280. %@NL@%
  8281. If you are in doubt about a particular C library routine, you can always use
  8282. it and see what happens. If the linker displays the following message,%@CR:C6A00080048 @%  %@NL@%
  8283. %@NL@%
  8284. %@AS@%  error L2044: __acrtused : symbol multiply defined, use /NOE%@AE@%%@NL@%
  8285. %@NL@%
  8286. the routine requires C start-up support and should not be used.  %@NL@%
  8287. %@NL@%
  8288. %@NL@%
  8289. %@NL@%
  8290. %@NL@%
  8291. %@NL@%
  8292. %@NL@%
  8293. %@CR:C6A00090001 @%%@1@%%@AB@%Chapter 9  Debugging C Programs with CodeView%@AE@%%@EH@%%@NL@%
  8294. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8295. %@NL@%
  8296. Even experienced programmers occasionally find bugs in their programs. This
  8297. chapter explores techniques that will help you locate these errors quickly,
  8298. using the Microsoft CodeView debugger.  %@NL@%
  8299. %@NL@%
  8300. This chapter describes:  %@NL@%
  8301. %@NL@%
  8302. %@NL@%
  8303.   ■   How to display and modify variables and memory%@NL@%
  8304. %@NL@%
  8305.   ■   How to control the flow of execution while debugging%@NL@%
  8306. %@NL@%
  8307.   ■   Advanced CodeView debugging techniques%@NL@%
  8308. %@NL@%
  8309.   ■   How to control CodeView's behavior with command-line switches and the
  8310.       TOOLS.INI file%@NL@%
  8311. %@NL@%
  8312. %@NL@%
  8313. CodeView supports the Microsoft mouse (or any fully compatible pointing
  8314. device). All operations are described first using the mouse; the keyboard
  8315. command follows.  %@NL@%
  8316. %@NL@%
  8317. For information about debugging OS/2 programs that use threads or processes,
  8318. see Chapter 15, "Creating OS/2 Multithread Applications."  %@NL@%
  8319. %@NL@%
  8320. %@NL@%
  8321. %@2@%%@CR:C6A00090002 @%%@AB@%9.1  Understanding CodeView Windows%@AE@%%@EH@%%@NL@%
  8322. %@NL@%
  8323. CodeView divides the screen into logically separate sections called windows,
  8324. so that a large amount of information can be displayed in an organized and
  8325. easy-to-read fashion. Each window is a discrete section of the display that
  8326. operates independently of the other windows.  %@NL@%
  8327. %@NL@%
  8328. %@AU@% Each window displays a different type of data.%@AE@%  %@NL@%
  8329. %@NL@%
  8330. Each CodeView window has a distinct function. The name of each window
  8331. described below appears in the top of the window's frame:  %@NL@%
  8332. %@NL@%
  8333. %@NL@%
  8334.   ■   The Source window displays the source code. You can open a second
  8335.       Source window to view an include file, another source file, or the
  8336.       same source file at a different location.%@NL@%
  8337. %@NL@%
  8338.   ■   The Command window accepts debugging commands.%@NL@%
  8339. %@NL@%
  8340.   ■   The Watch window displays the current values of selected variables.%@NL@%
  8341. %@NL@%
  8342.   ■   The Local window lists the values of all variables local to the
  8343.       current function or block.%@NL@%
  8344. %@NL@%
  8345.   ■   The Memory window shows the contents of memory. You can open a second
  8346.       Memory window to view a different section of memory.%@NL@%
  8347. %@NL@%
  8348.   ■   The Register window displays the contents of the microprocessor's
  8349.       registers, as well as the processor flags.%@NL@%
  8350. %@NL@%
  8351.   ■   The 8087 window displays the registers of the coprocessor or its
  8352.       software emulator.%@NL@%
  8353. %@NL@%
  8354. %@NL@%
  8355. CodeView starts running with three windows displayed. The Local window is at
  8356. the top, the Source window fills the middle of the screen, and the Command
  8357. window is at the bottom.  %@NL@%
  8358. %@NL@%
  8359. There are two ways to open windows. You can choose the desired window from
  8360. the View menu. (Note that you can open more than one of certain windows,
  8361. such as Source or Memory.) In addition, some operations (such as selecting a
  8362. Watch variable) open the appropriate window automatically, if it is not
  8363. already open.  %@NL@%
  8364. %@NL@%
  8365. %@AU@% All displays are  updated automatically.%@AE@%  %@NL@%
  8366. %@NL@%
  8367. CodeView continually and automatically updates the contents of all windows.
  8368. However, if you want to interact with a particular window (for instance, to
  8369. enter a command, set a breakpoint, or modify a variable), you must select
  8370. that window as the focus of user interaction.  %@NL@%
  8371. %@NL@%
  8372. The selected window is called the "current" window. The current window is
  8373. marked in three ways:  %@NL@%
  8374. %@NL@%
  8375. %@NL@%
  8376.   ■   The window's name is highlighted in white.%@NL@%
  8377. %@NL@%
  8378.   ■   The text cursor appears in the window.%@NL@%
  8379. %@NL@%
  8380.   ■   The vertical and horizontal scroll bars are moved into the window.%@NL@%
  8381. %@NL@%
  8382. %@NL@%
  8383. To select a new current window, click left in the window (position the mouse
  8384. cursor in the window and press the left mouse button) that you want to be
  8385. current. You can also press F6 or SHIFT+F6 to move the focus from one window
  8386. to the next.  %@NL@%
  8387. %@NL@%
  8388. Windows often contain more information than can be displayed in the area
  8389. allotted to the window. There are two ways to view these additional
  8390. contents. You can drag on the window's horizontal or vertical scroll bars.
  8391. (Position the mouse pointer on the bar and, while holding down the left
  8392. mouse button, drag the mouse in the appropriate direction.) You can also use
  8393. the direction keys (LEFT, RIGHT, UP, DOWN) to move the text cursor.  %@NL@%
  8394. %@NL@%
  8395. Typing commands into the Source window causes CodeView to temporarily shift
  8396. its focus to the Command window. Whatever you type is appended to the last
  8397. line in the Command window. If the Command window is closed, CodeView beeps
  8398. in response to your entry and ignores the input.  %@NL@%
  8399. %@NL@%
  8400. %@NL@%
  8401. %@4@%%@AB@%Adjusting the Windows%@AE@%%@EH@%%@NL@%
  8402. %@NL@%
  8403. Although you cannot change the relative positions of the windows, you can
  8404. change their size or remove them. The Maximize, Size, and Close commands
  8405. from the View menu perform these functions, or you can press CTRL+F10,
  8406. CTRL+F8, and CTRL+F4, respectively. Window manipulations are especially easy
  8407. with a mouse:  %@NL@%
  8408. %@NL@%
  8409. %@NL@%
  8410.   ■   To maximize a window (enlarge it so it fills the screen), click left
  8411.       on the up arrow at the right end of the window's top border. To
  8412.       restore the window to its previous size and position, click left on
  8413.       the double arrow at the right end of the top border.%@NL@%
  8414. %@NL@%
  8415.   ■   To change the size of a window, position the mouse pointer anywhere
  8416.       along the white line at the top of the window. Press and hold down the
  8417.       left mouse button. When two double arrows appear on the line, you can
  8418.       drag the mouse to enlarge or reduce the window. The same action on a
  8419.       vertical border widens or narrows the window.%@NL@%
  8420. %@NL@%
  8421.   ■   To close a window, click left on the dot at the left end of the top
  8422.       border. You can also close any window in the View menu whose name has
  8423.       a dot next to it by selecting that window from the menu or by pressing
  8424.       that window's acclerator key. The adjacent windows automatically
  8425.       expand to recover the empty space.%@NL@%
  8426. %@NL@%
  8427. %@NL@%
  8428. CodeView stores session information in a file called CURRENT.STS, which is
  8429. created in the directory pointed to by the INIT environment variable. The
  8430. session information includes such items as the name of the program being
  8431. debugged, which CodeView windows were open, and the breakpoint locations.
  8432. This information becomes the default status the next time you run CodeView.%@CR:C6A00090003 @%%@CR:C6A00090004 @%
  8433. %@NL@%
  8434. %@NL@%
  8435. %@NL@%
  8436. %@2@%%@CR:C6A00090005 @%%@AB@%9.2  Overview of Debugging Techniques%@AE@%%@EH@%%@NL@%
  8437. %@NL@%
  8438. There is no single best approach to debugging for all programs or users.
  8439. CodeView offers a variety of debugging tools that let you pick a method
  8440. appropriate to the program or your work habits. The following section  may
  8441. help you decide how to approach a particular program.  %@NL@%
  8442. %@NL@%
  8443. Broadly speaking, two things can go wrong in a program:  %@NL@%
  8444. %@NL@%
  8445. %@NL@%
  8446.   ■   The program doesn't manipulate the data the way you expected it to.%@NL@%
  8447. %@NL@%
  8448.   ■   The flow of execution is incorrect.%@NL@%
  8449. %@NL@%
  8450. %@NL@%
  8451. These problems occasionally overlap. Incorrect execution can corrupt the
  8452. data, and bad data can cause execution to take an unexpected turn. Because
  8453. CodeView allows you to trace program execution %@AI@%and%@AE@% display whatever
  8454. combination of variables you want simultaneously, you don't have to know
  8455. ahead of time whether the problem is bad data manipulation, a bad execution
  8456. path, or some combination of these.  %@NL@%
  8457. %@NL@%
  8458. CodeView has features that deal specifically with the problems of bad data
  8459. and incorrect execution:  %@NL@%
  8460. %@NL@%
  8461. %@NL@%
  8462.   ■   You can view and modify any program variable, any section of memory,
  8463.       or any processor register.%@NL@%
  8464. %@NL@%
  8465.   ■   You can monitor the path of execution and precisely control where
  8466.       execution pauses.%@NL@%
  8467. %@NL@%
  8468. %@NL@%
  8469. The following sections explain how to view and modify data and describe how
  8470. execution is controlled.  %@NL@%
  8471. %@NL@%
  8472. %@NL@%
  8473. %@2@%%@CR:C6A00090006 @%%@AB@%9.3  Viewing and Modifying Program Data%@AE@%%@EH@%%@NL@%
  8474. %@NL@%
  8475. The CodeView debugger offers a variety of ways to display program variables,
  8476. processor registers, and memory. You can also modify the values of all these
  8477. items as the program executes. This section shows how to display and modify
  8478. variables, registers, and memory.  %@NL@%
  8479. %@NL@%
  8480. %@NL@%
  8481. %@3@%%@CR:C6A00090007 @%%@AB@%9.3.1  Displaying Variables in the Watch Window%@AE@%%@EH@%%@NL@%
  8482. %@NL@%
  8483. To add a variable to the Watch window, position the cursor on the name of
  8484. the variable using either the mouse or the direction keys (LEFT, RIGHT, UP,
  8485. DOWN). Then select the Add Watch command from the Watch menu, or press
  8486. CTRL+W.  %@NL@%
  8487. %@NL@%
  8488. A dialog box appears with the selected variable's name displayed in the
  8489. Expression field. If you don't want to watch the variable shown, type in the
  8490. name of the variable you want to watch. Pressing ENTER or clicking left on
  8491. the OK button adds this variable to the Watch window.  %@NL@%
  8492. %@NL@%
  8493. The Watch window appears at the top of the screen. Adding a Watch variable
  8494. automatically opens the Watch window if the window doesn't already exist.  %@NL@%
  8495. %@NL@%
  8496. A newly added variable may be followed by the message:  %@NL@%
  8497. %@NL@%
  8498. %@AS@%  <Watch Expression Not in Context>%@AE@%%@NL@%
  8499. %@NL@%
  8500. This message appears when program execution has not yet reached the block
  8501. where the variable is defined. (A block is a section of code enclosed in
  8502. curly braces.) Global variables (those declared outside C functions) never
  8503. cause CodeView to display this message; they can be watched from anywhere in
  8504. the program.  %@NL@%
  8505. %@NL@%
  8506. To remove a variable from the Watch window, use the Delete Watch command
  8507. from the Watch menu, and select the variable to be removed using the list in
  8508. the dialog box. You can also position the cursor on any line in the Watch
  8509. window and press CTRL+Y to delete the line.  %@NL@%
  8510. %@NL@%
  8511. %@AU@% There is no limit to how many variables you can watch.%@AE@%  %@NL@%
  8512. %@NL@%
  8513. You can place as many variables as you like in the Watch window; the
  8514. quantity is limited only by available memory. You can scroll through the
  8515. Watch window to position it at those variables you want to view. CodeView
  8516. automatically updates all watched variables as the program runs, including
  8517. those not currently visible.  %@NL@%
  8518. %@NL@%
  8519. Loops (%@AB@%do%@AE@%, %@AB@%for%@AE@%, or %@AB@%while%@AE@%) cause problems when they don't terminate
  8520. correctly. Displaying loop variables in the Watch window is an easy way to
  8521. determine whether a loop variable achieves its proper value.  %@NL@%
  8522. %@NL@%
  8523. %@NL@%
  8524. %@3@%%@CR:C6A00090008 @%%@AB@%9.3.2  Displaying Expressions in the Watch Window%@AE@%%@EH@%%@NL@%
  8525. %@NL@%
  8526. You may have noticed that the Add Watch dialog box prompts for an
  8527. expression, not simply a variable name. As this suggests, you can enter an
  8528. expression (that is, any valid combination of variables, constants, and
  8529. operators) for CodeView to evaluate and display.  %@NL@%
  8530. %@NL@%
  8531. %@AU@% Expressions can use the  syntax of other languages.%@AE@%  %@NL@%
  8532. %@NL@%
  8533. You are not limited to evaluating C expressions. The Language command of the
  8534. Options menu offers a choice of BASIC or FORTRAN expression evaluation, if
  8535. one of these languages better suits your needs. The ability to select the
  8536. language evaluator is especially useful when debugging mixed-language
  8537. programs. Remember that C-specific features, such as type casting or pointer
  8538. conversions, are not available in other languages.  %@NL@%
  8539. %@NL@%
  8540. %@AU@% You can display more information with expressions than with individual
  8541. %@AU@%variables.%@AE@%  %@NL@%
  8542. %@NL@%
  8543. By reducing several variables to a single, easily read value, an expression
  8544. can be easier to interpret than the components that make it up. Imagine a
  8545. %@AB@%for%@AE@% loop with two variables whose ratio is supposed to remain constant. You
  8546. suspect that one of these variables (you aren't sure which) sometimes takes
  8547. the wrong value. With %@AS@%(var1 / var2) %@AE@% displayed as an expression in the Watch
  8548. window, you can easily see when this single value changes; you don't have to
  8549. mentally divide two numbers.  %@NL@%
  8550. %@NL@%
  8551. You can also display Boolean expressions. For example, if a variable is
  8552. never supposed to be larger than 100 or less than 25, %@AS@% (var < 25 || var >
  8553. %@AS@%100) %@AE@% evaluates to 1 (true) when %@AS@% var %@AE@% goes out-of-bounds.  %@NL@%
  8554. %@NL@%
  8555. %@NL@%
  8556. %@3@%%@CR:C6A00090009 @%%@AB@%9.3.3  Displaying Arrays and Structures%@AE@%%@EH@%%@NL@%
  8557. %@NL@%
  8558. Most program variables are scalar quantities─a single character or a single
  8559. integer or floating-point value. These appear in the Watch window with the
  8560. variable name to the left, followed by an equal sign (%@AB@%=%@AE@%) and the current
  8561. value.  %@NL@%
  8562. %@NL@%
  8563. %@AU@% You can view arrays and structures in expanded form.%@AE@%  %@NL@%
  8564. %@NL@%
  8565. Arrays and structures contain multiple values, arranged in one or more
  8566. layers. They are often referred to as "aggregate" data items. CodeView lets
  8567. you control how much of these variables is shown; that is, whether all,
  8568. part, or none of their internal structure is displayed.  %@NL@%
  8569. %@NL@%
  8570. An array initially appears in the Watch window in this form:  %@NL@%
  8571. %@NL@%
  8572. %@AS@%  +wordholder[]  = [...]%@AE@%%@NL@%
  8573. %@NL@%
  8574. The brackets indicate that this variable contains more than one element. The
  8575. plus sign (+) indicates that the variable has not yet been expanded to
  8576. display its components.  %@NL@%
  8577. %@NL@%
  8578. To expand the array, double-click anywhere on the line. You can also
  8579. position the cursor on the line and press ENTER. For example, if %@AS@% wordholder
  8580. %@AS@%%@AE@% is a six-character array containing the word "Basic," the Watch window
  8581. display changes to the following :  %@NL@%
  8582. %@NL@%
  8583. %@AS@%  -wordholder[]
  8584. %@AS@%     [0]  =  66 'B'
  8585. %@AS@%     [1]  =  97 'a'
  8586. %@AS@%     [2]  =  115 's'
  8587. %@AS@%     [3]  =  105 'i'
  8588. %@AS@%     [4]  =  99 'c'
  8589. %@AS@%     [5]  =  0 ''%@AE@%%@NL@%
  8590. %@NL@%
  8591. Note that both the individual character values and their ASCII decimal
  8592. equivalents are listed. The minus sign (-) indicates no further expansion is
  8593. possible. To contract the array, double-click on its line (or position the
  8594. cursor on the line and press ENTER) again.  %@NL@%
  8595. %@NL@%
  8596. If it is inconvenient to view a character array in this form, cast the
  8597. variable's name to a character pointer by placing %@AS@% (char *) %@AE@% in front of the
  8598. name. The character array is then displayed as a string delimited by
  8599. apostrophes.  %@NL@%
  8600. %@NL@%
  8601. You can display arrays with more than one dimension. Imagine a 5 x 5 integer
  8602. array named %@AS@% matrix%@AE@%, whose diagonal elements are the numbers 1 through 5 and
  8603. whose other elements are zero. Unexpanded, the array is displayed like this:
  8604. %@NL@%
  8605. %@NL@%
  8606. %@AS@%  +matrix[]  = [...]%@AE@%%@NL@%
  8607. %@NL@%
  8608. Double-clicking on %@AS@% matrix %@AE@% (or pressing ENTER) changes the display:  %@NL@%
  8609. %@NL@%
  8610. %@AS@%  -matrix[]
  8611. %@AS@%    +[0][]  =  [...]
  8612. %@AS@%    +[1][]  =  [...]
  8613. %@AS@%    +[2][]  =  [...]
  8614. %@AS@%    +[3][]  =  [...]
  8615. %@AS@%    +[4][]  =  [...]%@AE@%%@NL@%
  8616. %@NL@%
  8617. The actual values of the elements are not shown yet. You have to descend one
  8618. more level to see them. To view the elements of the third row of the array,
  8619. position the cursor anywhere on the fourth line and press ENTER:  %@NL@%
  8620. %@NL@%
  8621. %@AS@%  -matrix[]
  8622. %@AS@%    +[0][]  =  [...]
  8623. %@AS@%    +[1][]  =  [...]
  8624. %@AS@%    -[2][]
  8625. %@AS@%       [0]  = 0
  8626. %@AS@%       [1]  = 0
  8627. %@AS@%       [2]  = 3
  8628. %@AS@%       [3]  = 0
  8629. %@AS@%       [4]  = 0
  8630. %@AS@%    +[3][]  =  [...]
  8631. %@AS@%    +[4][]  =  [...]%@AE@%%@NL@%
  8632. %@NL@%
  8633. Expanding the fifth row of the array produces this display:  %@NL@%
  8634. %@NL@%
  8635. %@AS@%  -matrix[]
  8636. %@AS@%    +[0][]  =  [...]
  8637. %@AS@%    +[1][]  =  [...]
  8638. %@AS@%    -[2][]
  8639. %@AS@%       [0]  = 0
  8640. %@AS@%       [1]  = 0
  8641. %@AS@%       [2]  = 3
  8642. %@AS@%       [3]  = 0
  8643. %@AS@%       [4]  = 0
  8644. %@AS@%    +[3][]  =  [...]
  8645. %@AS@%    -[4][]
  8646. %@AS@%       [0]  = 0
  8647. %@AS@%       [1]  = 0
  8648. %@AS@%       [2]  = 0
  8649. %@AS@%       [3]  = 0
  8650. %@AS@%       [4]  = 5%@AE@%%@NL@%
  8651. %@NL@%
  8652. %@AU@% You can view individual elements instead of  the entire array.%@AE@%  %@NL@%
  8653. %@NL@%
  8654. Any element of an array (or structure) can be independently expanded or
  8655. contracted. If you only want to view one or two elements of a large array,
  8656. specify the particular array or structure elements in the Expression field
  8657. of the Add Watch dialog box; you need not display every element of the
  8658. variable.  %@NL@%
  8659. %@NL@%
  8660. %@AU@% You can dereference pointers.%@AE@%  %@NL@%
  8661. %@NL@%
  8662. You can dereference a pointer in the same way as you expand an array or
  8663. structure. The pointer address is displayed, followed by all the elements of
  8664. the variable to which the pointer currently refers. Multiple levels of
  8665. indirection (that is, pointers referencing other pointers) can be displayed
  8666. simultaneously.  %@NL@%
  8667. %@NL@%
  8668. %@NL@%
  8669. %@3@%%@CR:C6A00090010 @%%@AB@%9.3.4  Displaying Array Elements Dynamically%@AE@%%@EH@%%@NL@%
  8670. %@NL@%
  8671. You do not have to display every element of an array. If specific subscripts
  8672. are given, the corresponding element is displayed.  %@NL@%
  8673. %@NL@%
  8674. You can also specify a dynamic array element, which changes as some other
  8675. variable changes. For example, suppose that the loop variable %@AS@% p %@AE@% is a
  8676. subscript for the array variable %@AS@% catalogprice%@AE@%. The Watch window expression %@AS@%
  8677. %@AS@%catalogprice[p] %@AE@% displays only the array element currently specified by %@AS@%p%@AE@%,
  8678. not the entire array.  %@NL@%
  8679. %@NL@%
  8680. You can mix constant and variable subscripts. For example, the expression %@AS@%
  8681. %@AS@%bigarray[3][i] %@AE@% displays only the element in the third row of the array to
  8682. which the index variable %@AS@% i %@AE@% points.  %@NL@%
  8683. %@NL@%
  8684. %@NL@%
  8685. %@3@%%@CR:C6A00090011 @%%@AB@%9.3.5  Using Quick Watch%@AE@%%@EH@%%@NL@%
  8686. %@NL@%
  8687. Selecting the Quick Watch command from the Watch menu (or pressing SHIFT+F9)
  8688. displays the Quick Watch dialog box. If the text cursor is in the Source,
  8689. Local, or Watch window, the variable at the current cursor position appears
  8690. in the dialog box. If this is not the item you wish to display, type in the
  8691. desired expression or variable, then press ENTER. The selected item is
  8692. displayed immediately.  %@NL@%
  8693. %@NL@%
  8694. The Quick Watch display automatically expands arrays and structures to their
  8695. first level. For example, an array with three dimensions is expanded to the
  8696. first dimension. You can expand or contract an element just as you would in
  8697. the Watch window: position the cursor on the appropriate line and press
  8698. ENTER. If the array needs more lines than the Quick Watch window can
  8699. display, drag the mouse along the scroll bar, or press DOWN or PGDN to view
  8700. the rest of the array.  %@NL@%
  8701. %@NL@%
  8702. %@AU@% You can add Quick Watch variables to the Watch window.%@AE@%  %@NL@%
  8703. %@NL@%
  8704. If you decide to add a Quick Watch item to the Watch window, select the Add
  8705. Watch button. Arrays and structures appear in the Watch window expanded as
  8706. they were displayed in the Quick Watch box.  %@NL@%
  8707. %@NL@%
  8708. Quick Watch is a convenient way to take a quick look at a variable or
  8709. expression. Since only one Quick Watch variable can be viewed at a time, you
  8710. would not use Quick Watch for most of the variables you want to view.  %@NL@%
  8711. %@NL@%
  8712. %@NL@%
  8713. %@3@%%@CR:C6A00090012 @%%@AB@%9.3.6  Displaying Memory%@AE@%%@EH@%%@NL@%
  8714. %@NL@%
  8715. Selecting the Memory command from the View menu opens a Memory window. Up to
  8716. two Memory windows can be open at one time.  %@NL@%
  8717. %@NL@%
  8718. By default, memory is displayed as hexadecimal byte values, with 16 bytes
  8719. per line. At the end of each line is a second display of the same memory in
  8720. ASCII form. Values that correspond to printable ASCII characters (decimal 32
  8721. through 127) are displayed in that form. Values outside this range are shown
  8722. as periods.  %@NL@%
  8723. %@NL@%
  8724. %@AU@% You can display memory  values in any form.%@AE@%  %@NL@%
  8725. %@NL@%
  8726. Byte values are not always the most convenient way to view memory. If the
  8727. area of memory you're examining contains character strings or floating-point
  8728. values, you might prefer to view them in a directly readable form. The
  8729. Memory Window command of the Options menu displays a dialog box with a
  8730. variety of display options:  %@NL@%
  8731. %@NL@%
  8732. %@NL@%
  8733.   ■   ASCII characters%@NL@%
  8734. %@NL@%
  8735.   ■   Byte, word, or double-word binary values%@NL@%
  8736. %@NL@%
  8737.   ■   Signed or unsigned integer decimal values%@NL@%
  8738. %@NL@%
  8739.   ■   Short (32 bit), long (64 bit), or ten-byte (80 bit) floating-point
  8740.       values%@NL@%
  8741. %@NL@%
  8742. %@NL@%
  8743. You can also directly cycle through these display formats by pressing F3.  %@NL@%
  8744. %@NL@%
  8745. If a section of memory cannot be displayed as a valid floating-point number,
  8746. the number shown includes the characters %@AS@% NAN %@AE@% (not a number).  %@NL@%
  8747. %@NL@%
  8748. %@NL@%
  8749. %@4@%%@AB@%Displaying Variables with a Live Expression%@AE@%%@EH@%%@NL@%
  8750. %@NL@%
  8751. Section 9.3.4, "Displaying Array Elements Dynamically," explains how to
  8752. display a specific array element by adding the appropriate expression to the
  8753. Watch window. It is also possible to watch a particular memory area that
  8754. your program uses to store data in the Memory window. This CodeView display
  8755. feature is called a "live expression."  %@NL@%
  8756. %@NL@%
  8757. "Live" means that the area of memory displayed changes to reflect the value
  8758. of a pointer or subscript. For example, if %@AS@% buffer %@AE@% is an array and %@AS@% pbuf %@AE@%
  8759. is a pointer to that array, then %@AS@% *pbuf %@AE@% points to the array element
  8760. currently referenced. A live expression displays the section of memory
  8761. beginning with this element. If your program changes the value of %@AS@% pbuf%@AE@%,
  8762. CodeView dynamically adjusts the Memory window display.  %@NL@%
  8763. %@NL@%
  8764. Live expressions are displayed in a Memory window, not in the Watch window.
  8765. To create a live expression, select the Memory Window command of the Options
  8766. menu, then select the Live Expression check box. Enter the name of the
  8767. element you want to view. For example, if %@AS@% strgptr %@AE@% is a pointer to an array
  8768. of characters, and you want to see what it currently points at, enter %@AS@%
  8769. %@AS@%*strgptr%@AE@%. Then select the OK button or press ENTER to view that memory area.
  8770. %@NL@%
  8771. %@NL@%
  8772. A new Memory window opens. The first memory location in the window is the
  8773. first memory location of the live expression. The section of memory
  8774. displayed changes to the section the pointer currently references.  %@NL@%
  8775. %@NL@%
  8776. You can use the Memory Window command of the Options menu to display the
  8777. value of the live expression in a directly readable form. This is especially
  8778. convenient when the live expression represents strings or floating-point
  8779. values, which are difficult to interpret in hexadecimal form.  %@NL@%
  8780. %@NL@%
  8781. It is usually more convenient to view an item in the Watch window than as a
  8782. live expression. However, some items are more easily viewed as live
  8783. expressions. For example, you can examine what is currently on top of the
  8784. stack. Enter SS:SP as the live expression.  %@NL@%
  8785. %@NL@%
  8786. %@NL@%
  8787. %@3@%%@CR:C6A00090013 @%%@AB@%9.3.7  Displaying the Processor Registers%@AE@%%@EH@%%@NL@%
  8788. %@NL@%
  8789. Selecting the Register command from the View menu (or pressing F2) opens a
  8790. window on the right side of the screen. The current values of the
  8791. microprocessor's registers appear in this window.  %@NL@%
  8792. %@NL@%
  8793. At the bottom of the window is a group of mnemonics representing the
  8794. processor flags. When you first open the Register window, all values are
  8795. shown in normal-intensity video. Any subsequent changes are marked in
  8796. high-intensity video. For example, suppose the overflow flag is not set when
  8797. the Register window is first opened. The corresponding mnemonic is NV and it
  8798. appears in light gray. If the overflow flag is subsequently set, the
  8799. mnemonic changes to OV and appears in bright white.  %@NL@%
  8800. %@NL@%
  8801. Selecting the 386 Instructions command from the Options menu displays the
  8802. registers as 32-bit values, but only if your computer uses an 80386
  8803. processor, and only when running the real-mode version of CodeView.
  8804. Selecting this command a second time toggles back to a 16-bit display.  %@NL@%
  8805. %@NL@%
  8806. You can also display the registers of an 8087/287/387 coprocessor in a
  8807. separate window by selecting the 8087 command from the View menu. If your
  8808. program uses the coprocessor emulator, the emulated registers are displayed
  8809. instead.  %@NL@%
  8810. %@NL@%
  8811. %@NL@%
  8812. %@3@%%@CR:C6A00090014 @%%@AB@%9.3.8  Modifying the Values of Variables, Registers, and Memory%@AE@%%@EH@%%@NL@%
  8813. %@NL@%
  8814. You can easily change the values of variables, memory locations, or
  8815. registers displayed in the Watch, Local, Memory, Register, or 8087 windows.
  8816. Simply position the cursor at the value you want to change and edit it to
  8817. the appropriate value. If you change your mind, press ALT+BKSP to undo the
  8818. last change you made.  %@NL@%
  8819. %@NL@%
  8820. The starting address of each line of memory displayed is shown at the left
  8821. of the Memory window, in CS:IP form. Altering the address automatically
  8822. shifts the display to the corresponding section of memory. If that section
  8823. is not used by your program, memory locations are displayed as double
  8824. question marks (??).  %@NL@%
  8825. %@NL@%
  8826. %@AU@% Byte display form is different from other forms.%@AE@%  %@NL@%
  8827. %@NL@%
  8828. When you select Byte display from the Memory Window Options dialog box,
  8829. CodeView presents both a hexadecimal and an ASCII representation of the data
  8830. in memory. (Byte display is the default.) You can change data in memory
  8831. either by entering new hex values over the hexadecimal representation of
  8832. your data or by entering character values over the character representation.
  8833. %@NL@%
  8834. %@NL@%
  8835. To toggle a processor flag, click left on its mnemonic. You can also
  8836. position the cursor on a mnemonic, then press any key (except TAB or SPACE).
  8837. Repeat to restore the flag to its previous setting.  %@NL@%
  8838. %@NL@%
  8839. %@AU@% Be cautious when modifying memory or a register.%@AE@%  %@NL@%
  8840. %@NL@%
  8841. The effect of changing a register, flag, or memory location may vary from no
  8842. effect at all, to crashing the operating system. You should be cautious when
  8843. altering "machine-level" values; most of the items you would want to change
  8844. can be altered from the Watch window.  %@NL@%
  8845. %@NL@%
  8846. One instance where direct manipulation of register values can be valuable is
  8847. when you are debugging in-line assembly code. You can change register values
  8848. to test assumptions before making changes in your source code and
  8849. recompiling.  %@NL@%
  8850. %@NL@%
  8851. %@NL@%
  8852. %@2@%%@CR:C6A00090015 @%%@AB@%9.4  Controlling Execution%@AE@%%@EH@%%@NL@%
  8853. %@NL@%
  8854. There are two forms of program execution under CodeView:  %@NL@%
  8855. %@NL@%
  8856. %@NL@%
  8857.   ■   Continuous; the program executes until either a previously specified
  8858.       "breakpoint" has been reached or the program terminates normally.%@NL@%
  8859. %@NL@%
  8860.   ■   Single-step; the program pauses after each line of code has been
  8861.       executed. %@NL@%
  8862. %@NL@%
  8863. %@NL@%
  8864. Sections 9.4.1 and 9.4.2 explain how each form of execution works and the
  8865. most effective way to use each.  %@NL@%
  8866. %@NL@%
  8867. %@NL@%
  8868. %@3@%%@CR:C6A00090016 @%%@AB@%9.4.1  Continuous Execution%@AE@%%@EH@%%@NL@%
  8869. %@NL@%
  8870. Continuous execution lets you quickly execute the bug-free sections of code,
  8871. which would otherwise take a long time to execute a single step at a time.  %@NL@%
  8872. %@NL@%
  8873. The simplest form of continuous execution is to click right (position the
  8874. mouse pointer and press the right mouse button) anywhere on the line of code
  8875. you want to debug or examine in more detail. The program executes at full
  8876. speed up to the beginning of this line, then pauses. You can do the same
  8877. thing by positioning the text cursor on this line, then pressing F7.  %@NL@%
  8878. %@NL@%
  8879. You can also pause execution at a specific line of code with a "breakpoint."
  8880. There are several types of breakpoints. Breakpoints are explained in the
  8881. following section.  %@NL@%
  8882. %@NL@%
  8883. %@NL@%
  8884. %@4@%%@AB@%Selecting Breakpoint Lines%@AE@%%@EH@%%@NL@%
  8885. %@NL@%
  8886. %@AU@% Breakpoints can be  tied to lines of code.%@AE@%  %@NL@%
  8887. %@NL@%
  8888. You can skip over the parts of the program that you don't want to examine by
  8889. specifying one or more lines as "breakpoints." The program executes at full
  8890. speed up to the first breakpoint, then pauses. Pressing F5 continues program
  8891. execution up to the next breakpoint, and so on. (You can halt execution at
  8892. any time by pressing CTRL+BREAK or ALT+SYSRQ.)  %@NL@%
  8893. %@NL@%
  8894. %@AU@% There is no limit to the  number of breakpoints.%@AE@%  %@NL@%
  8895. %@NL@%
  8896. You can set as many breakpoints as you like (limited only by available
  8897. memory). There are several ways to set breakpoints:  %@NL@%
  8898. %@NL@%
  8899. %@NL@%
  8900.   ■   Double-click anywhere on the desired breakpoint line. The selected
  8901.       line is highlighted to show that it is a breakpoint. To remove the
  8902.       breakpoint, double-click on the line a second time.%@NL@%
  8903. %@NL@%
  8904.   ■   Position the cursor anywhere on the line at which you want execution
  8905.       to pause. Press F9 to select the line as a breakpoint. (CodeView
  8906.       highlights lines that have been selected as breakpoints.) Press F9 a
  8907.       second time to remove the breakpoint. %@NL@%
  8908. %@NL@%
  8909.   ■   Display the Set Breakpoint dialog box by selecting Set Breakpoint from
  8910.       the Watch menu. Choose one of the breakpoint options that permits a
  8911.       line ("location") to be specified. The line on which the text cursor
  8912.       currently rests is the default breakpoint line in the Location field.
  8913.       If this line is not the desired breakpoint, enter the line number
  8914.       desired. (The line number must begin with a period.) Use F9 or the
  8915.       Edit Breakpoints screen of the Watch menu to remove the breakpoint.%@NL@%
  8916. %@NL@%
  8917. %@NL@%
  8918. %@AU@% Not every line can  be a breakpoint.%@AE@%  %@NL@%
  8919. %@NL@%
  8920. A breakpoint line must be a program line that represents executable code.
  8921. You cannot select a blank line, a comment line, or a declaration line (such
  8922. as a variable declaration or a preprocessor statement) as a breakpoint.  %@NL@%
  8923. %@NL@%
  8924. A breakpoint can also be set at a function or an explicit address. To set a
  8925. breakpoint at a function, simply enter its name in the Set Breakpoint dialog
  8926. box. To set a breakpoint at an address, enter the address in CS:IP form.  %@NL@%
  8927. %@NL@%
  8928. ────────────────────────────────────────────────────────────────────────────%@NL@%
  8929. NOTE
  8930.  
  8931. %@AI@%By default, Microsoft compilers optimize your code. In the process of
  8932. %@AI@%optimization, some lines of code may be repositioned or reorganized for more
  8933. %@AI@%efficient execution. These changes can prevent CodeView from recognizing the
  8934. %@AI@%corresponding lines of source code as breakpoints. Therefore, it is a good
  8935. %@AI@%idea to disable optimization during development (use the /Od switch). You
  8936. %@AI@%can restore optimization once debugging is completed.%@AE@%%@NL@%
  8937. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  8938. %@NL@%
  8939. Once execution has paused, you can continue execution by pressing F5 or
  8940. clicking left on the <F5> button in the display.  %@NL@%
  8941. %@NL@%
  8942. %@NL@%
  8943. %@4@%%@AB@%Setting Breakpoint Values%@AE@%%@EH@%%@NL@%
  8944. %@NL@%
  8945. %@AU@% Breakpoints can be  tied to variables.%@AE@%  %@NL@%
  8946. %@NL@%
  8947. Breakpoints are not limited to specific lines of code. CodeView can also
  8948. break execution when a variable reaches a particular value, or just changes
  8949. value. You can also combine these value breakpoints with line breakpoints,
  8950. so that execution stops at a specific line only if a variable has
  8951. simultaneously reached a particular value, or changed value. You must use
  8952. the check boxes in the Set Breakpoint dialog box to select these other types
  8953. of breakpoints.  %@NL@%
  8954. %@NL@%
  8955. To pause execution when an expression reaches a particular value, enter that
  8956. expression in the Expression field of the Set Breakpoint dialog box. For
  8957. example, assume you have declared a tree structure as follows:  %@NL@%
  8958. %@NL@%
  8959. %@AS@%  struct Tagtree
  8960. %@AS@%  {
  8961. %@AS@%      char * s;                /* Pointer to a string */
  8962. %@AS@%      struct TAGtree * left;   /* Pointer to left branch */
  8963. %@AS@%      struct TAGtree * right;  /* Pointer to right branch */
  8964. %@AS@%  };
  8965. %@AS@%  
  8966. %@AS@%  struct TAGtree t;%@AE@%%@NL@%
  8967. %@NL@%
  8968. You can then pause execution when your tree traversal reaches a terminal
  8969. node by entering the expression %@AS@% (t.left == NULL) || (t.right == NULL)%@AE@%.  %@NL@%
  8970. %@NL@%
  8971. To pause execution when a variable changes value, you need to enter only the
  8972. name of the variable in the Expression field. For large variables (such as
  8973. arrays or character strings), you can specify the number of bytes you want
  8974. checked (up to 32K) in the Length field.  %@NL@%
  8975. %@NL@%
  8976. ────────────────────────────────────────────────────────────────────────────%@NL@%
  8977. NOTE
  8978.  
  8979. %@AI@%When a breakpoint is tied to a variable, CodeView must check the variable's
  8980. %@AI@%value after each machine instruction is executed. This slows execution
  8981. %@AI@%greatly. For maximum speed when debugging, either tie conditional
  8982. %@AI@%breakpoints to specific lines, or set conditional breakpoints only after you
  8983. %@AI@%have reached the section of code that needs to be debugged.%@AE@%%@NL@%
  8984. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  8985. %@NL@%
  8986. %@NL@%
  8987. %@4@%%@AB@%Using Breakpoints%@AE@%%@EH@%%@NL@%
  8988. %@NL@%
  8989. Here are several examples that show how breakpoints can help you find the
  8990. cause of a problem.  %@NL@%
  8991. %@NL@%
  8992. One of the most common bugs is a %@AB@%for%@AE@% loop that executes too many or too few
  8993. times. If you set a breakpoint that encloses the loop statements, the
  8994. program pauses after each iteration. With the loop variable or critical
  8995. program variables in the Watch or Local windows, it should be easy to see
  8996. what the loop is doing wrong.  %@NL@%
  8997. %@NL@%
  8998. %@AU@% You can specify how  many times a breakpoint  line is executed.%@AE@%  %@NL@%
  8999. %@NL@%
  9000. You do not have to pause at a breakpoint the first time execution reaches
  9001. it. CodeView lets you specify the number of times you want to ignore the
  9002. breakpoint condition before pausing. Enter the decimal number in the Pass
  9003. Count field of the Set Breakpoint dialog box of the Watch menu.  %@NL@%
  9004. %@NL@%
  9005. For example, suppose your program repeatedly calls a function to create a
  9006. binary tree. You suspect that something goes wrong with the process about
  9007. halfway through. You could mark the line that calls the function as the
  9008. breakpoint, then specify how many times this line is to execute before
  9009. execution pauses. Running the program creates a representative (but
  9010. unfinished) tree structure that can be examined from the Watch window. You
  9011. can then continue your analysis using single-stepping.  %@NL@%
  9012. %@NL@%
  9013. Another programming error is erroneously assigning a value to a variable.
  9014. Enter the variable in the Expression field of the Set Breakpoint dialog box.
  9015. Execution breaks whenever this variable changes value.  %@NL@%
  9016. %@NL@%
  9017. %@AU@% You can assign new  values to variables while  execution is paused.%@AE@%  %@NL@%
  9018. %@NL@%
  9019. Breakpoints are a convenient way to pause the program so you can assign new
  9020. values to variables. For example, if a limit value is set by a variable, you
  9021. can change the value to see whether program execution is affected.
  9022. Similarly, you can pass a variety of values to a %@AB@%switch%@AE@% statement to see if
  9023. they are correctly processed.  %@NL@%
  9024. %@NL@%
  9025. This ability to alter variables is an especially convenient way to test new
  9026. functions without having to write a stand-alone test program.  %@NL@%
  9027. %@NL@%
  9028. %@NL@%
  9029. %@3@%%@CR:C6A00090017 @%%@AB@%9.4.2  Single-Stepping%@AE@%%@EH@%%@NL@%
  9030. %@NL@%
  9031. In single-stepping, CodeView pauses after each line of code is executed. (If
  9032. a line contains more than one executable statement, CodeView executes all
  9033. the statements on the line before pausing.) The next line to be executed is
  9034. highlighted in reverse video.  %@NL@%
  9035. %@NL@%
  9036. %@AU@% There are two ways  to single-step.%@AE@%  %@NL@%
  9037. %@NL@%
  9038. You can single-step through a program with the Step and Trace functions.
  9039. Step (executed by pressing F10) steps over function calls. All the code in
  9040. the function is executed but, to you, the function appears to execute as a
  9041. single step. Trace (executed by pressing F8) traces through every step of
  9042. all functions for which CodeView has symbolic information. Each line of the
  9043. function is executed as a separate step. (CodeView has no symbolic
  9044. information about run-time functions; therefore, they are executed as a
  9045. single step.)  %@NL@%
  9046. %@NL@%
  9047. You can alternate between Trace and Step as you like. The method you use
  9048. depends only on whether you want to see what happens within a particular
  9049. function.  %@NL@%
  9050. %@NL@%
  9051. You can Trace through the program continuously (without having to press F8),
  9052. using the Animate command of the Run menu. The speed of execution is
  9053. controlled by the Trace Speed command from the Options menu. You can halt
  9054. animated execution at any time by pressing any key.  %@NL@%
  9055. %@NL@%
  9056. %@NL@%
  9057. %@2@%%@CR:C6A00090018 @%%@AB@%9.5  Replaying a Debug Session%@AE@%%@EH@%%@NL@%
  9058. %@NL@%
  9059. CodeView can automatically create a "tape" (a disk file) with all the
  9060. debugging instructions and input data you entered when testing a program.
  9061. The tape is then "replayed" to repeat the debugging process. This dynamic
  9062. replay feature is unique to the CodeView debugger and is activated by
  9063. selecting the History On command from the Run menu. Selecting History On a
  9064. second time terminates  recording.  %@NL@%
  9065. %@NL@%
  9066. You can use the recording as a bookmark. You can quit after a long debugging
  9067. session, then pick up the session later in the same place.  %@NL@%
  9068. %@NL@%
  9069. %@AU@% Dynamic replay makes it  easy to correct a mistake.%@AE@%  %@NL@%
  9070. %@NL@%
  9071. The principal use of dynamic replay is to allow you to back up when you make
  9072. an error or overshoot the section of code with the bug. This feature is
  9073. important because not all bugs are located when executing the program in a
  9074. linear fashion.  %@NL@%
  9075. %@NL@%
  9076. For example, you may have to manually execute a function many times before
  9077. its bug appears. If you then enter a command that alters the machine's or
  9078. program's status and thereby lose the information you need to find the cause
  9079. of the bug, you would have had to restart the program and manually repeat
  9080. every debugging step to return to that point. Even worse, if you don't
  9081. remember the exact sequence of events that exposed the bug, it could take
  9082. hours to find your way back.  %@NL@%
  9083. %@NL@%
  9084. Dynamic replay eliminates this problem. Selecting the Undo command from the
  9085. Run menu automatically restarts the program and rapidly executes every debug
  9086. command up to (but not including) the last one you entered. You can repeat
  9087. this process as many times as you like until you return to the desired point
  9088. in execution.  %@NL@%
  9089. %@NL@%
  9090. To add additional steps to an existing tape, select History On, then select
  9091. Replay. When replay has completed, perform whatever new debugging steps you
  9092. want, then select History On a second time to terminate recording. The new
  9093. tape contains both the original and the added commands.  %@NL@%
  9094. %@NL@%
  9095. ────────────────────────────────────────────────────────────────────────────%@NL@%
  9096. NOTE
  9097.  
  9098. %@AI@%CodeView records only those mouse commands that apply to CodeView. Mouse
  9099. %@AI@%commands recognized by the application being debugged are not recorded.%@AE@%%@NL@%
  9100. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  9101. %@NL@%
  9102. %@NL@%
  9103. %@4@%%@AB@%Replay Limitations under OS/2%@AE@%%@EH@%%@NL@%
  9104. %@NL@%
  9105. There are some limitations to dynamic replay when debugging under OS/2:  %@NL@%
  9106. %@NL@%
  9107. %@NL@%
  9108.   ■   The program must not respond to asynchronous events.%@NL@%
  9109. %@NL@%
  9110.   ■   Breakpoints must be specified at specific source lines or for specific
  9111.       symbols (rather than by absolute addresses), or replay may fail.%@NL@%
  9112. %@NL@%
  9113.   ■   Single-thread programs behave normally during replay. However, one of
  9114.       the threads in a multithread program may cause an asynchronous event,
  9115.       violating the first restriction. Multithread programs are, therefore,
  9116.       more likely to fail during replay.%@NL@%
  9117. %@NL@%
  9118.   ■   Multiprocess replay will fail. Each new process invokes a new CodeView
  9119.       session. The existence of multiple sessions makes it impractical to
  9120.       record the sequence of events if you execute commands in a session
  9121.       other than the original.%@NL@%
  9122. %@NL@%
  9123.   ■   Replay under Presentation Manager is not currently supported because
  9124.       it violates the first restriction.%@NL@%
  9125. %@NL@%
  9126. %@NL@%
  9127. %@NL@%
  9128. %@2@%%@CR:C6A00090019 @%%@AB@%9.6  Advanced CodeView Techniques%@AE@%%@EH@%%@NL@%
  9129. %@NL@%
  9130. Once you are comfortable displaying and changing variables, stepping through
  9131. the program, and using dynamic replay, you might want to experiment with the
  9132. advanced techniques explained below.  %@NL@%
  9133. %@NL@%
  9134. %@NL@%
  9135. %@4@%%@AB@%Setting Command-Line Arguments%@AE@%%@EH@%%@NL@%
  9136. %@NL@%
  9137. If your program retrieves command-line arguments, you can specify them with
  9138. the Set Runtime Arguments command from the Run menu. Enter the arguments in
  9139. the Command Line field before you begin execution. (Arguments entered after
  9140. execution begins cause an automatic restart.)  %@NL@%
  9141. %@NL@%
  9142. %@NL@%
  9143. %@4@%%@AB@%Multiple Source Windows%@AE@%%@EH@%%@NL@%
  9144. %@NL@%
  9145. You can open two Source windows at the same time. The windows can display
  9146. two different sections of the same program, or one can show the high-level
  9147. listing and the other the assembly-language listing. In the latter case, the
  9148. contents of the windows track, with the next assembly-language instruction
  9149. to be executed matching the next line of source code.  %@NL@%
  9150. %@NL@%
  9151. You can move freely between these windows, executing a single line of source
  9152. code or a single assembly instruction at a time. The assembly-language
  9153. window must be opened in CS:IP mode.  %@NL@%
  9154. %@NL@%
  9155. %@NL@%
  9156. %@4@%%@AB@%Calling Functions%@AE@%%@EH@%%@NL@%
  9157. %@NL@%
  9158. Any C function in your program (whether user-written or from the library)
  9159. can be called from the Command window or the Watch window, using the
  9160. following format:  %@NL@%
  9161. %@NL@%
  9162. %@AS@%  ?funcname (varlist)%@AE@%%@NL@%
  9163. %@NL@%
  9164. The function is evaluated and the returned value is displayed in the Command
  9165. window.  %@NL@%
  9166. %@NL@%
  9167. The function does not have to be called by your program to be available for
  9168. evaluation. For example, all the .OBJ code specified in the linker input
  9169. response file is linked. The functions in this code can then be evaluated
  9170. from the Command window.  %@NL@%
  9171. %@NL@%
  9172. This feature allows you to run functions from within CodeView that you would
  9173. not normally include in the final version of your program. For example, you
  9174. could include the OS/2 API functions that control semaphores, then execute
  9175. them from the Command window to manipulate the run-time environment at any
  9176. point in the debugging process.  %@NL@%
  9177. %@NL@%
  9178. %@NL@%
  9179. %@4@%%@AB@%Checking for Undefined Pointers%@AE@%%@EH@%%@NL@%
  9180. %@NL@%
  9181. Until a pointer has been explicitly assigned a value, its value is
  9182. undefined. That is, its value may be completely random, or it may be some
  9183. consistent value that does not point to a useful data address (such as -1).
  9184. %@NL@%
  9185. %@NL@%
  9186. Accessing data through an uninitialized pointer will cause unpredictable
  9187. program behavior and, under OS/2, will usually result in a protection
  9188. violation. Because many C programs use pointers heavily, tracking down
  9189. exactly which pointer variable was left uninitialized is tedious.  %@NL@%
  9190. %@NL@%
  9191. CodeView can help locate the problem quickly. If you use an uninitialized
  9192. pointer (or "null pointer" under OS/2) the operating system will generate a
  9193. protection violation. By examining the Calls menu, you can determine the
  9194. last line of your code that was executed before the protection violation
  9195. occurred.  %@NL@%
  9196. %@NL@%
  9197. Under DOS, you can take advantage of the fact that global or static
  9198. variables are initialized to 0 to track down uninitialized pointers. Set a
  9199. conditional breakpoint that stops when location 0 changes, then start
  9200. execution. Execution will pause when your program makes an assignment to
  9201. that location.  %@NL@%
  9202. %@NL@%
  9203. ────────────────────────────────────────────────────────────────────────────%@NL@%
  9204. NOTE
  9205.  
  9206. %@AI@%For near pointers, location 0 is DS:0000; for far pointers, location 0 is
  9207. %@AI@%0000:0000.%@AE@%%@NL@%
  9208. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  9209. %@NL@%
  9210. %@NL@%
  9211. %@4@%%@AB@%Using Breakpoints Efficiently%@AE@%%@EH@%%@NL@%
  9212. %@NL@%
  9213. Breakpoints slow execution when debugging. You can increase CodeView's speed
  9214. by using the /R command-line switch if you have an 80386-based computer.
  9215. This switch enables the 386's four debug registers, which support breakpoint
  9216. checking in hardware rather than in software.  %@NL@%
  9217. %@NL@%
  9218. %@NL@%
  9219. %@4@%%@AB@%Printing Selected Items%@AE@%%@EH@%%@NL@%
  9220. %@NL@%
  9221. You can print all or part of the contents of any window with the Print
  9222. command from the File menu. The check box lets you print the complete
  9223. contents of the window, only the material that is currently viewable in the
  9224. window, or selected text from the window. Text is selected by dragging the
  9225. mouse across it, or by holding down the SHIFT key and pressing the direction
  9226. keys (LEFT, RIGHT, UP, DOWN).  %@NL@%
  9227. %@NL@%
  9228. By default, print output is to the file CODEVIEW.LST in the current
  9229. directory. You can choose whether the new material will be appended to an
  9230. existing file or overwrite it, using the Append/Overwrite check box. If you
  9231. would like print output to go to a different file, type its name in the To
  9232. File Name field. If you want the output to go to a printer, enter the
  9233. appropriate device name, such as LPT1 or COM2.%@CR:C6A00090020 @%%@CR:C6A00090021 @%  %@NL@%
  9234. %@NL@%
  9235. %@NL@%
  9236. %@4@%%@AB@%Handling Register Variables%@AE@%%@EH@%%@NL@%
  9237. %@NL@%
  9238. A register variable is stored in one of the microprocessor's registers,
  9239. rather than in RAM. This speeds access to the variable.  %@NL@%
  9240. %@NL@%
  9241. There are two ways for a conventional variable to become a register
  9242. variable. One way is declaring the variable as a register variable; if a
  9243. register is free, the compiler will store the variable there. The other way
  9244. occurs during optimization, when the compiler stores an often-used variable
  9245. (such as a loop variable) in a register to speed up execution.  %@NL@%
  9246. %@NL@%
  9247. Register variables can cause problems during debugging. As with local
  9248. variables, they are only visible within the function where they are defined.
  9249. In addition, a register variable may not always be displayed with its
  9250. current value.  %@NL@%
  9251. %@NL@%
  9252. In general, it is a good idea to turn off all optimization and to avoid
  9253. declaring register variables until the program has been fully debugged. Any
  9254. side effects produced by optimization or register variables can then be
  9255. easily isolated.  %@NL@%
  9256. %@NL@%
  9257. %@NL@%
  9258. %@4@%%@AB@%Redirecting CodeView Input and Output%@AE@%%@EH@%%@NL@%
  9259. %@NL@%
  9260. The Command window accepts DOS-like commands that redirect input and output.
  9261. These commands can also be included on the command line that invokes
  9262. CodeView. Whatever follows the /C option in the command line is treated as
  9263. CodeView commands that are immediately executed at start-up.  %@NL@%
  9264. %@NL@%
  9265. %@AS@%  CV/c "infile; t >outfile" myprog%@AE@%%@NL@%
  9266. %@NL@%
  9267. Input is redirected to %@AS@% infile%@AE@%, which can contain start-up commands for
  9268. CodeView. When CodeView exhausts all commands in the input file, focus
  9269. automatically shifts to the command window. Output is sent to %@AS@% outfile %@AE@% and
  9270. echoed to the Command window. The %@AS@% t %@AE@% must precede the %@AS@% > %@AE@% command for
  9271. output to be sent to the Command window.  %@NL@%
  9272. %@NL@%
  9273. Redirection is a useful way to automate CodeView start-up. It also lets you
  9274. keep a viewable record of command-line input and output, a feature not
  9275. available with dynamic replay. (No record is kept of mouse operations.) Some
  9276. applications (particularly interactive ones) may need modification to allow
  9277. for redirection of input to the application itself.  %@NL@%
  9278. %@NL@%
  9279. %@NL@%
  9280. %@4@%%@AB@%Using CodeView with Additional Memory%@AE@%%@EH@%%@NL@%
  9281. %@NL@%
  9282. If your computer uses expanded or extended memory, you can increase
  9283. CodeView's functionality by selecting the /X or /E option. CodeView moves as
  9284. much as it can of itself, the debugging table, and the program to higher
  9285. memory (above the first megabyte).  %@NL@%
  9286. %@NL@%
  9287. The /X option uses extended memory and gives the greatest speed increase.
  9288. This option requires the HIMEM.SYS driver, which is included on your
  9289. distribution disks. Add %@AS@% DEVICE = HIMEM.SYS %@AE@% to your CONFIG.SYS file to load
  9290. HIMEM.SYS at boot time.%@CR:C6A00090022 @%%@CR:C6A00090023 @%%@CR:C6A00090024 @%  %@NL@%
  9291. %@NL@%
  9292. The /E option uses expanded memory. The speed increase is not as great as
  9293. that supplied by the /X option. The expanded memory manager (EMM) must be
  9294. LIM 4.0, and no single module's debug information can exceed 48K. If the
  9295. symbol table exceeds this limit, try reducing file-name information by not
  9296. specifying paths at compile time and using /Zi only with those sections of
  9297. the program that need debugging (use /Zd otherwise).  %@NL@%
  9298. %@NL@%
  9299. If you do not specify either /X or /E (or the /D disk-overlay option),
  9300. CodeView automatically searches for the HIMEM.SYS driver and extended memory
  9301. so it can implement the /X option. If it fails, CodeView searches for
  9302. expanded memory to implement the /E option. If that search fails, CodeView
  9303. uses a default disk overlay of 64K. (See the description of the /D option
  9304. below.)  %@NL@%
  9305. %@NL@%
  9306. %@NL@%
  9307. %@2@%%@CR:C6A00090025 @%%@AB@%9.7  Controlling CodeView with Command-Line Options%@AE@%%@EH@%%@NL@%
  9308. %@NL@%
  9309. The following options can be added to the command line that invokes
  9310. CodeView:  %@NL@%
  9311. %@NL@%
  9312. %@AB@%Option%@AE@%                            %@AB@%Effect%@AE@%
  9313. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9314. /2                                Two-monitor debugging. The display 
  9315.                                   adapters must be configured for 
  9316.                                   different addresses. One display shows 
  9317.                                   the output of the application; the other
  9318.                                   shows CodeView.
  9319.  
  9320. /25                               Display in 25-line mode.
  9321.  
  9322. /43                               Display in 43-line mode (EGA or VGA 
  9323.                                   only).
  9324.  
  9325. /50                               Display in 50-line mode (VGA only).
  9326.  
  9327. /B                                Display in black and white. This assures
  9328.                                   that the display is readable when a 
  9329.                                   color display is not used.
  9330.  
  9331. /C%@AI@%commands%@AE@%                        All items following this switch are 
  9332.                                   treated as CodeView commands to be 
  9333.                                   executed immediately on start-up. 
  9334.                                   Commands must be separated with a 
  9335.                                   semicolon (%@AB@%;%@AE@%).
  9336.  
  9337. /D«%@AI@%ddd%@AE@%»                           Use disk overlays, where %@AI@%ddd%@AE@% is the 
  9338.                                   decimal size of the overlay buffer, in 
  9339.                                   kilobytes. The acceptable range is 16K 
  9340.                                   to 128K. The default size is 64K. DOS 
  9341.                                   only.
  9342.  
  9343. /E                                Use expanded memory for symbolic 
  9344.                                   information. DOS only.
  9345.  
  9346. /F                                Flip screen video pages. When your 
  9347.                                   application does not use graphics, eight
  9348.                                   video screen pages are available. 
  9349.                                   Switching from CodeView to the output 
  9350.                                   screen is accomplished more quickly than
  9351.                                   swapping (/S) by directly selecting the 
  9352.                                   appropriate video page. Cannot be used 
  9353.                                   with /S. DOS only.
  9354.  
  9355. /I%@AI@%number%@AE@%                          Turns nonmaskable interrupts and 
  9356.                                   8259-interrupt trapping on (/I1) or off 
  9357.                                   (/I2).
  9358.  
  9359. /K                                Disables installation of keyboard 
  9360.                                   monitors for the program being debugged.
  9361.  
  9362. /L%@AI@%dlls%@AE@%                            Load DLLs specified. DLLs must be 
  9363.                                   separated by a semicolon (%@AB@%;%@AE@%). OS/2 only.
  9364.  
  9365. /M                                Disable the mouse.
  9366.  
  9367. /N%@AI@%number%@AE@%                          /N0 tells CodeView to trap; /N1 tells it
  9368.                                   not to.
  9369.  
  9370. /O                                Debug child processes ("offspring"). 
  9371.                                   OS/2 only.
  9372.  
  9373. /R                                Use 386 hardware debug registers. DOS 
  9374.                                   only.
  9375.  
  9376. /S                                Swap screen in buffers. When your 
  9377.                                   program uses graphics, all eight screen 
  9378.                                   buffers must be used. Switching from 
  9379.                                   CodeView to the output screen is
  9380.                                   accomplished by saving the previous 
  9381.                                   screen in a buffer. Cannot be used with 
  9382.                                   /F. DOS only.
  9383.  
  9384. /X                                Use extended memory for symbolic 
  9385.                                   information. DOS only.
  9386.  
  9387. %@NL@%
  9388. %@2@%%@CR:C6A00090026 @%%@AB@%9.8  Customizing CodeView with the TOOLS.INI FILE%@AE@%%@EH@%%@NL@%
  9389. %@NL@%
  9390. The TOOLS.INI file customizes the behavior and user interface of several
  9391. Microsoft products. The TOOLS.INI file is a plain ASCII text file. You
  9392. should place it in a directory pointed to the INIT environment variable. (If
  9393. you do not use the INIT environment variable, CodeView looks for TOOLS.INI
  9394. only in its source directory.)  %@NL@%
  9395. %@NL@%
  9396. The CodeView section of TOOLS.INI is preceded by the following line:  %@NL@%
  9397. %@NL@%
  9398. %@AS@%  [cv]%@AE@%%@NL@%
  9399. %@NL@%
  9400. If you are running the protected-mode version of CodeView, use %@AS@% [cvp] %@AE@%
  9401. instead. If you run both versions, include both: %@AS@% [cv cvp]%@AE@%.  %@NL@%
  9402. %@NL@%
  9403. Most of the TOOLS.INI customizations control screen colors, but you can also
  9404. specify such things as start-up commands or the name of the file that
  9405. receives CodeView output. On-line help contains full information about all
  9406. TOOLS.INI switches for CodeView.  %@NL@%
  9407. %@NL@%
  9408. %@NL@%
  9409. %@NL@%
  9410. %@NL@%
  9411. %@NL@%
  9412. %@NL@%
  9413. %@CR:C6A-Part 03 @%%@1@%%@AB@%PART III  Special Environments%@AE@%%@EH@%%@NL@%
  9414. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9415. %@NL@%
  9416. The Microsoft C Professional Development System provides a platform from
  9417. which you can build graphics applications and interface with programs
  9418. written in other languages.  %@NL@%
  9419. %@NL@%
  9420. Chapter 10 discusses using the real-world graphics functions to set video
  9421. modes, draw basic shapes, and use graphic fonts. Chapter 11 describes
  9422. "presentation graphics," sophisticated charts and graphics that show data
  9423. relationships. Chapter 12 explains how to write C programs so that they
  9424. interface with assembly language routines or routines written in other
  9425. languages. Chapter 13 describes portability of Microsoft C to other
  9426. environments.  %@NL@%
  9427. %@NL@%
  9428. %@NL@%
  9429. %@NL@%
  9430. %@NL@%
  9431. %@NL@%
  9432. %@NL@%
  9433. %@CR:C6A00100001 @%%@1@%%@AB@%Chapter 10  Communicating with Graphics%@AE@%%@EH@%%@NL@%
  9434. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9435. %@NL@%
  9436. A map, a chart, an illustration, a graph, or some other visual aid often can
  9437. communicate more information more quickly and more vividly than would
  9438. several screens of text.  %@NL@%
  9439. %@NL@%
  9440. The extensive Microsoft C graphics library allows you to communicate your
  9441. ideas graphically. The functions range from the simple to the complex; from
  9442. functions that turn on a pixel to functions that draw graphs and charts
  9443. complete with labels and legends.  %@NL@%
  9444. %@NL@%
  9445. This chapter describes low-level graphics functions that draw basic shapes
  9446. such as lines, circles, and rectangles. It introduces video modes, color
  9447. palettes, coordinate systems, and synopses of the graphics and font
  9448. functions. For complete function prototypes and example programs, use
  9449. on-line help.  %@NL@%
  9450. %@NL@%
  9451. ────────────────────────────────────────────────────────────────────────────%@NL@%
  9452. NOTE
  9453.  
  9454. %@AI@%The ANSI C standard does not define any standard graphics functions. The
  9455. %@AI@%functions described in this section are unique to Microsoft C and are not
  9456. %@AI@%portable to other implementations of C.%@AE@%%@NL@%
  9457. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  9458. %@NL@%
  9459. %@NL@%
  9460. %@2@%%@CR:C6A00100002 @%%@AB@%10.1  Video Modes%@AE@%%@EH@%%@NL@%
  9461. %@NL@%
  9462. Graphics adapters are boards or cards inside the computer that are
  9463. responsible for displaying text and graphics on the screen. Commonly used
  9464. adapters include:  %@NL@%
  9465. %@NL@%
  9466. %@NL@%
  9467.   ■   CGA (Color Graphics Adapter)%@NL@%
  9468. %@NL@%
  9469.   ■   EGA (Enhanced Graphics Adapter)%@NL@%
  9470. %@NL@%
  9471.   ■   HGC (Hercules Graphics Card)%@NL@%
  9472. %@NL@%
  9473.   ■   MCGA (Multicolor Graphics Array)%@NL@%
  9474. %@NL@%
  9475.   ■   MDPA (Monochrome Display Printer Adapter)%@NL@%
  9476. %@NL@%
  9477.   ■   VGA (Video Graphics Array)%@NL@%
  9478. %@NL@%
  9479. %@NL@%
  9480. In addition, there are Olivetti versions of the CGA, EGA, and VGA (called
  9481. OCGA, OEGA, and OVGA in this chapter).  %@NL@%
  9482. %@NL@%
  9483. %@AU@% The video modes available at run time depend on your graphics adapter and
  9484. %@AU@%monitor.%@AE@%  %@NL@%
  9485. %@NL@%
  9486. Adapters can enter one or more "video modes." The video mode controls the
  9487. resolution and number of colors on the video display. Microsoft C supports
  9488. 17 video modes, which fall into two broad categories:  %@NL@%
  9489. %@NL@%
  9490. %@NL@%
  9491.   ■   "Text modes," where characters are displayed%@NL@%
  9492. %@NL@%
  9493.   ■   "Graphics modes," where individual pixels can be turned on and off%@NL@%
  9494. %@NL@%
  9495. %@NL@%
  9496. The graphics adapter and the type of monitor in use determine which of the
  9497. 17 video modes are available at run time. See Section 10.1.2 for a list of
  9498. video modes.  %@NL@%
  9499. %@NL@%
  9500. %@NL@%
  9501. %@3@%%@CR:C6A00100003 @%%@AB@%10.1.1  Sample Low-Level Graphics Program%@AE@%%@EH@%%@NL@%
  9502. %@NL@%
  9503. The program ERESBOX.C below shows, in a few lines, the steps you follow to
  9504. enter and exit a graphics mode. It sets the video mode %@AB@%_ERESCOLOR%@AE@%, draws a
  9505. box, waits for a keypress, and returns to default mode, which is the video
  9506. mode in effect when the program began running.%@CR:C6A00100004 @%%@CR:C6A00100005 @%%@CR:C6A00100006 @%  %@NL@%
  9507. %@NL@%
  9508. %@AS@%  /* ERESBOX.C -- Enters _ERESCOLOR mode and draws a box */
  9509. %@AS@%  
  9510. %@AS@%  #include <graph.h> /* graphics functions */
  9511. %@AS@%  #include <stdio.h> /* puts */
  9512. %@AS@%  #include <conio.h> /* getch */
  9513. %@AS@%  
  9514. %@AS@%  main()
  9515. %@AS@%  {
  9516. %@AS@%     if( _setvideomode( _ERESCOLOR ) ) /* EGA 640x350 mode */
  9517. %@AS@%     {
  9518. %@AS@%        _rectangle( _GBORDER, 10, 10, 110, 110 ); /* draw */
  9519. %@AS@%        getch(); /* wait for a keypress */
  9520. %@AS@%        _setvideomode( _DEFAULTMODE ); /* return to default */
  9521. %@AS@%     } else puts( "Can't enter _ERESCOLOR graphics mode." )
  9522. %@AS@%  }%@AE@%%@NL@%
  9523. %@NL@%
  9524. The program above illustrates the steps you follow to display graphics:  %@NL@%
  9525. %@NL@%
  9526. %@NL@%
  9527.   ■   Include the header file GRAPH.H. It contains function prototypes,
  9528.       macros, useful structures, and symbolic constants such as %@AB@%_ERESCOLOR%@AE@%,
  9529.       %@AB@%_GBORDER%@AE@%, and %@AB@%_DEFAULTMODE%@AE@%.
  9530. %@NL@%
  9531. %@AS@%      #include <graph.h>%@AE@%%@NL@%
  9532. %@NL@%
  9533. %@NL@%
  9534.   ■   Call the %@AB@%_setvideomode%@AE@% function, which sets the desired video mode.
  9535.       The function returns 0 if the hardware does not support the requested
  9536.       mode. (See Section 10.1.2, "Setting a Video Mode.")
  9537. %@NL@%
  9538. %@AS@%      if( _setvideomode( _ERESCOLOR ) )%@AE@%%@NL@%
  9539. %@NL@%
  9540. %@NL@%
  9541.   ■   Draw the graphics on the screen. The example program calls the
  9542.       %@AB@%_rectangle%@AE@% function. (See Section 10.4.3, "Drawing Points, Lines, and
  9543.       Shapes.")
  9544. %@NL@%
  9545. %@AS@%      _rectangle( _GBORDER, 10, 10, 110, 110 )%@AE@%%@NL@%
  9546. %@NL@%
  9547. %@NL@%
  9548.   ■   Exit the graphics mode and return to whatever video mode was in effect
  9549.       before the program began. Call %@AB@%_setvideomode%@AE@%, passing the constant
  9550.       %@AB@%_DEFAULTMODE%@AE@%. In some cases, you might want to skip this step, exiting
  9551.       the program with the graphics screen still in place.
  9552. %@NL@%
  9553. %@AS@%      _setvideomode( _DEFAULTMODE );%@AE@%%@NL@%
  9554. %@NL@%
  9555. %@NL@%
  9556. %@NL@%
  9557. In addition, you must link with the GRAPHICS.LIB library, which contains the
  9558. function code. If you use window-coordinate functions (which require
  9559. floating-point calculations) and if you have not created a standard combined
  9560. library containing a floating-point component, you must explicitly link with
  9561. a floating-point math library.  %@NL@%
  9562. %@NL@%
  9563. %@NL@%
  9564. %@3@%%@CR:C6A00100007 @%%@AB@%10.1.2  Setting a Video Mode%@AE@%%@EH@%%@NL@%
  9565. %@NL@%
  9566. The %@AB@%_setvideomode%@AE@% function turns on one of the 17 available video modes.
  9567. Pass it a single integer that tells it which mode to display. The constants
  9568. in Table 10.1 are defined in the GRAPH.H file. The dimensions are listed in
  9569. pixels for video graphics mode and in columns for video text mode.  %@NL@%
  9570. %@NL@%
  9571. %@AB@%Table 10.1  %@AB@%Constants that Represent Video Modes%@AE@%%@AE@%
  9572.  
  9573. %@TH:  45  2006 02 17 40 19 @%Constant (Name)  Description                             Mode/Hardware%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_DEFAULTMODE%@AE@%     Restores the original mode              All/All%@AB@%_ERESCOLOR%@AE@%       640  x  350, 4 or 16 color              Graphics/EGA%@AB@%_ERESNOCOLOR%@AE@%     640  x  350, BW                         Graphics/EGA%@AB@%_HRES16COLOR%@AE@%     640  x  200, 16 color                   Graphics/EGA%@AB@%_HERCMONO%@AE@%*%@AB@% %@AE@%      720  x 348, BW                          Graphics/HGC%@AB@%_HRESBW%@AE@%          640  x  200, BW                         Graphics/CGA%@AB@%_MAXCOLORMODE%@AE@%    Graphics mode with the most colors      Graphics/All┼%@AB@%_MAXRESMODE%@AE@%      Graphics mode with the highest          Graphics/All┼                 resolution                              %@AB@%_MRES4COLOR%@AE@%      320  x  200, 4 color                    Graphics/All%@AB@%_MRES16COLOR%@AE@%     320  x  200, 16 color                   Graphics/EGA%@AB@%_MRES256COLOR%@AE@%    320  x  200, 256 color                  Graphics/VGA%@AB@%_MRESNOCOLOR%@AE@%     320  x  200, 4 gray                     Graphics/CGA%@AB@%_ORESCOLOR%@AE@%       640  x  400, 1 of 16 colors             Graphics/Olivetti%@AB@%_TEXTBW40%@AE@%        40 column text, 16 gray                 Text/CGA%@AB@%_TEXTBW80%@AE@%        80 column text, 16 gray                 Text/CGA%@AB@%_TEXTC40%@AE@%         40 column text, 16/8 color              Text/CGA%@AB@%_TEXTC80%@AE@%         80 column text, 16/8 color              Text/CGA%@AB@%_TEXTMONO%@AE@%        80 column text, BW                      Text/MDPA%@AB@%_VRES2COLOR%@AE@%      640  x  480, BW                         Graphics/VGA%@AB@%_VRES16COLOR%@AE@%     640  x  480, 16 color                   Graphics/VGA%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  45  2006 02 17 40 19 @%
  9574.  
  9575. *%@AB@% %@AE@%Before attempting to enter%@AB@% _HERCMONO%@AE@% mode, you must install the
  9576. terminate-and-stay-resident program MSHERC.COM, which comes in the Microsoft
  9577. C package. If you have both a Hercules adapter and an additional graphics
  9578. adapter in the same computer, use the /H option  to put the Hercules into
  9579. %@AB@%HALF %@AE@%mode to avoid unpredictable and undesirable results.
  9580. ┼ %@AB@%_MAXRESMODE%@AE@% and%@AB@% _MAXCOLORMODE %@AE@%support all adapters except the MDPA. See
  9581. Section  %@NL@%
  9582. %@NL@%
  9583. %@NL@%
  9584. If the hardware does not support the selected mode, %@AB@%_setvideomode%@AE@% returns 0.
  9585. %@NL@%
  9586. %@NL@%
  9587. Some graphics adapters are able to enter additional video modes:  %@NL@%
  9588. %@NL@%
  9589. %@NL@%
  9590.   ■   EGA adapters can display all CGA modes.  %@NL@%
  9591. %@NL@%
  9592.   ■   HGC adapters can enter %@AB@%_TEXTMONO%@AE@% mode.  %@NL@%
  9593. %@NL@%
  9594.   ■   MCGA adapters can display all CGA modes, plus %@AB@%_VRES2COLOR%@AE@% and
  9595.       %@AB@%_MRES256COLOR%@AE@%.%@NL@%
  9596. %@NL@%
  9597.   ■   VGA adapters can display all EGA and CGA modes.  %@NL@%
  9598. %@NL@%
  9599. %@NL@%
  9600. %@NL@%
  9601. %@3@%%@CR:C6A00100008 @%%@AB@%10.1.3  Reading the videoconfig Structure%@AE@%%@EH@%%@NL@%
  9602. %@NL@%
  9603. At any time, you can inquire about the current video configuration by
  9604. passing the %@AB@%_getvideoconfig%@AE@% function a structure of type %@AB@%videoconfig%@AE@%. The
  9605. structure contains 11 members, all of which are short integers. They are
  9606. listed in Table 10.2.  %@NL@%
  9607. %@NL@%
  9608. %@AB@%Table 10.2  %@AB@%Members of a videoconfig Structure%@AE@%%@AE@%
  9609.  
  9610. %@TH:  14   967 02 23 53 @%Member                 Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%adapter%@AE@%*               Active display adapter%@AB@%bitsperpixel%@AE@%           Number of bits per pixel%@AB@%memory%@AE@%                 Adapter video memory in kilobytes%@AB@%mode%@AE@%*                  Current video mode%@AB@%monitor%@AE@%*               Active display monitor%@AB@%numcolors%@AE@%              Number of color indexes%@AB@%numtextcols%@AE@%            Number of text columns available%@AB@%numtextrows%@AE@%            Number of text rows available%@AB@%numvideopages%@AE@%          Number of video pages available%@AB@%numxpixels%@AE@%             Number of pixels on the %@AI@%x%@AE@% axis%@AB@%numypixels%@AE@%             Number of pixels on the %@AI@%y%@AE@% axis%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  14   967 02 23 53 @%
  9611.  
  9612. * Possible values for the mode, adapter, and monitor items are listed in the
  9613. GRAPH.H file.%@NL@%
  9614. %@NL@%
  9615. %@NL@%
  9616. The %@AB@%_getvideoconfig%@AE@% function initializes these values. Most of the values
  9617. are self-explanatory. For example, if %@AB@%numxpixels%@AE@% holds 640, the current
  9618. video mode contains 640 horizontal pixels, numbered 0 - 639.  %@NL@%
  9619. %@NL@%
  9620. The READVC.C example program below illustrates how to initialize and examine
  9621. a %@AB@%videoconfig%@AE@% structure:  %@NL@%
  9622. %@NL@%
  9623. %@AS@%  /* READVC.C -- Reads the videoconfig structure */
  9624. %@AS@%  
  9625. %@AS@%  #include <graph.h>
  9626. %@AS@%  #include <stdio.h>
  9627. %@AS@%  
  9628. %@AS@%  main()
  9629. %@AS@%  {
  9630. %@AS@%     struct videoconfig vc;
  9631. %@AS@%  
  9632. %@AS@%     _getvideoconfig( &vc );
  9633. %@AS@%     printf( "Text Rows = %i.\n", vc.numtextrows );
  9634. %@AS@%  }%@AE@%%@NL@%
  9635. %@NL@%
  9636. First, the program declares a structure %@AS@% vc %@AE@% of type %@AB@%videoconfig%@AE@%. Next, it
  9637. calls %@AB@%_getvideoconfig%@AE@% to initialize the structure. Finally, it prints a
  9638. member of the structure.  %@NL@%
  9639. %@NL@%
  9640. %@NL@%
  9641. %@3@%%@CR:C6A00100009 @%%@AB@%10.1.4  Maximizing Resolution or Color%@AE@%%@EH@%%@NL@%
  9642. %@NL@%
  9643. Two symbolic constants are new to Microsoft C 6.0:%@AB@% _MAXRESMODE%@AE@% and
  9644. %@AB@%_MAXCOLORMODE%@AE@%. The first selects the highest possible resolution for the
  9645. graphics adapter and monitor currently in use. The second selects the
  9646. graphics mode with the greatest number of colors. The constants work with
  9647. all graphics adapters except the MDPA. (See Table 10.3.)  %@NL@%
  9648. %@NL@%
  9649. %@AB@%Table 10.3  %@AB@%Constants for Maximum Resolution and Color%@AE@%%@AE@%
  9650.  
  9651. %@TH:  14   988 02 17 15 44 @%Adapter/Monitor  _MAXRESMODE    _MAXCOLORMODE%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%CGA              %@AB@%_HRESBW%@AE@%        %@AB@%_MRES4COLOR%@AE@%EGA color        %@AB@%_HRES16COLOR%@AE@%   %@AB@%_HRES16COLOR%@AE@%EGA ecd 64K      %@AB@%_ERESCOLOR%@AE@%     %@AB@%_HRES16COLOR%@AE@%EGA ecd 256K     %@AB@%_ERESCOLOR%@AE@%     %@AB@%_ERESCOLOR%@AE@%EGA mono         %@AB@%_ERESNOCOLOR%@AE@%   %@AB@%_ERESNOCOLOR%@AE@%HGC              %@AB@%_HERCMONO%@AE@%      %@AB@%_HERCMONO%@AE@%MCGA             %@AB@%_VRES2COLOR%@AE@%    %@AB@%_MRES256COLOR%@AE@%MDPA             Fails          FailsOCGA             %@AB@%_ORESCOLOR%@AE@%     %@AB@%_MRES4COLOR%@AE@%OEGA color       %@AB@%_ORESCOLOR%@AE@%     %@AB@%_ERESCOLOR%@AE@%VGA/OVGA         %@AB@%_VRES16COLOR%@AE@%   %@AB@%_MRES256COLOR%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  14   988 02 17 15 44 @%
  9652.  
  9653. %@NL@%
  9654. %@3@%%@CR:C6A00100010 @%%@AB@%10.1.5  Selecting Your Own Video Modes%@AE@%%@EH@%%@NL@%
  9655. %@NL@%
  9656. A program that will run only on a single machine with a known graphics
  9657. adapter can enter the appropriate video mode immediately. However, if you
  9658. attempt to run the program on another machine with a different adapter, it
  9659. may not run correctly, if at all.  %@NL@%
  9660. %@NL@%
  9661. If your program might run on a variety of computers and you prefer to select
  9662. your own video modes, initialize a %@AB@%videoconfig %@AE@%structure by calling the
  9663. %@AB@%_getvideoconfig%@AE@% function. Then check the %@AB@%adapter %@AE@%member and use a %@AB@%switch
  9664. %@AB@%%@AE@%statement to enter the selected video mode.  %@NL@%
  9665. %@NL@%
  9666. For example, suppose you know that a program will run on monochrome systems
  9667. equipped with either an EGA adapter or a Hercules adapter. To enter the
  9668. appropriate mode, use code such as this:  %@NL@%
  9669. %@NL@%
  9670. %@AS@%  struct videoconfig vc;
  9671. %@AS@%  
  9672. %@AS@%  _getvideoconfig( &vc );
  9673. %@AS@%  
  9674. %@AS@%  switch( vc.adapter )
  9675. %@AS@%  {
  9676. %@AS@%     case _EGA:
  9677. %@AS@%        _setvideomode( _ERESNOCOLOR );
  9678. %@AS@%        break;
  9679. %@AS@%     case _HGC:
  9680. %@AS@%        _setvideomode( _HERCMONO );
  9681. %@AS@%        break;
  9682. %@AS@%  }%@AE@%%@NL@%
  9683. %@NL@%
  9684. %@NL@%
  9685. %@2@%%@CR:C6A00100011 @%%@AB@%10.2  Mixing Colors and Changing Palettes%@AE@%%@EH@%%@NL@%
  9686. %@NL@%
  9687. Depending on the graphics card installed and the video mode in effect, you
  9688. can display 2, 4, 8, 16, or 256 colors on the screen at the same time. You
  9689. specify a color by selecting a color index (sometimes called a "pixel value"
  9690. or "color attribute"). The color indexes are numbered from 0 to %@AI@%n%@AE@%-1, where %@AI@%n%@AE@%
  9691. is the number of colors in the palette.  %@NL@%
  9692. %@NL@%
  9693. CGA adapters offer four different palettes containing predefined fixed color
  9694. sets.  %@NL@%
  9695. %@NL@%
  9696. %@AU@% All video modes that support color offer a color palette.%@AE@%  %@NL@%
  9697. %@NL@%
  9698. EGA, MCGA, and VGA adapters have palettes that can be redefined to suit your
  9699. needs. You can change the visible color associated with any color index by
  9700. remapping to a color index a color value that describes the true color (the
  9701. amount of red, green, and blue) you want to display.  %@NL@%
  9702. %@NL@%
  9703. Olivetti adapters (OCGA, OEGA, and OVGA) support the standard CGA, EGA, and
  9704. VGA modes (and palettes), plus an additional Olivetti mode described in
  9705. Section 10.2.2, "Olivetti Palettes."  %@NL@%
  9706. %@NL@%
  9707. ────────────────────────────────────────────────────────────────────────────%@NL@%
  9708. NOTE
  9709.  
  9710. %@AI@%The distinction between a color index and a color value is important. A
  9711. %@AI@%color index is always a short integer. A color value is always a long
  9712. %@AI@%integer. The only exception to this rule involves %@AB@%_setbkcolor%@AE@%%@AI@%, which uses a
  9713. %@AI@%color index cast to a long integer in CGA and text modes.%@AE@%%@AE@%%@NL@%
  9714. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  9715. %@NL@%
  9716. %@NL@%
  9717. %@3@%%@CR:C6A00100012 @%%@AB@%10.2.1  CGA Palettes%@AE@%%@EH@%%@NL@%
  9718. %@NL@%
  9719. The CGA (Color Graphics Adapter) supports two color video modes: %@AB@%_MRES4COLOR%@AE@%
  9720. and %@AB@%_MRESNOCOLOR%@AE@%, which display four colors selected from one of several
  9721. predefined palettes of colors. They display these foreground colors against
  9722. a background color that can be any one of the 16 available colors. With the
  9723. CGA hardware, the palette of foreground colors is predefined and cannot be
  9724. changed. Each palette number is an integer. (See Table 10.4.)  %@NL@%
  9725. %@NL@%
  9726. %@AB@%Table 10.4  %@AB@%CGA Palettes in _MRES4COLOR Mode%@AE@%%@AE@%
  9727.  
  9728. %@TH:  14   585 04 16 14 16 30 @%                              Color Index     Palette         1             2               3Number                                        %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%0               Green         Red             Brown1               Cyan          Magenta         Light Gray2               Light Green   Light Red       Yellow3               Light Cyan    Light Magenta   White%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  14   585 04 16 14 16 30 @%
  9729.  
  9730. %@AU@% _MRESNOCOLOR produces palettes with shades of gray on monochrome monitors.%@AE@%
  9731. %@NL@%
  9732. %@NL@%
  9733. The %@AB@%_MRESNOCOLOR%@AE@% video mode produces palettes containing various shades of
  9734. gray on monochrome monitors. However, the %@AB@%_MRESNOCOLOR%@AE@% mode displays colors
  9735. when used with a color display. Only two palettes are available in this
  9736. mode. Table 10.5 shows the colors available in the two palettes.  %@NL@%
  9737. %@NL@%
  9738. %@AB@%Table 10.5  %@AB@%CGA Palettes in _MRESNOCOLOR Mode%@AE@%%@AE@%
  9739.  
  9740. %@TH:  10   463 04 16 13 14 33 @%                             Color Index   Palette         1            2             3Number                                     %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%0               Blue         Red           Light Gray1               Light Blue   Light Red     White%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  10   463 04 16 13 14 33 @%
  9741.  
  9742. You can use the %@AB@%_selectpalette%@AE@% function only in the %@AB@%_MRES4COLOR%@AE@%,
  9743. %@AB@%_MRESNOCOLOR%@AE@%, and %@AB@%_ORESCOLOR%@AE@% graphics modes. To change palettes in other
  9744. video modes, use the %@AB@%_remappalette%@AE@% or %@AB@%_remapallpalette%@AE@% functions.  %@NL@%
  9745. %@NL@%
  9746. %@NL@%
  9747. %@3@%%@CR:C6A00100013 @%%@AB@%10.2.2  Olivetti(R) Palettes%@AE@%%@EH@%%@NL@%
  9748. %@NL@%
  9749. Olivetti graphics adapters are found in most Olivetti computers (including
  9750. the M24, M28, M240, M280, and M380) and in the AT&T 6300 series computers.
  9751. These adapters function the same as their non-Olivetti equivalents; that is,
  9752. the OCGA, OEGA, and OVGA adapters support CGA, EGA, and VGA modes,
  9753. respectively. In addition, Olivetti adapters can enter the high resolution
  9754. %@AB@%_ORESCOLOR%@AE@% mode.  %@NL@%
  9755. %@NL@%
  9756. In %@AB@%_ORESCOLOR%@AE@% mode, you can choose one of 16 foreground colors by passing a
  9757. value in the range 0 -15 to the %@AB@%_selectpalette%@AE@% function. The background
  9758. color is always black.  %@NL@%
  9759. %@NL@%
  9760. %@NL@%
  9761. %@3@%%@CR:C6A00100014 @%%@AB@%10.2.3  VGA Palettes%@AE@%%@EH@%%@NL@%
  9762. %@NL@%
  9763. Depending on the video mode currently in effect, a VGA (Video Graphics
  9764. Array) screen has 2, 16, or 256 color indexes chosen from a pool of 262,144
  9765. (256K) color values.  %@NL@%
  9766. %@NL@%
  9767. To name a color value, specify a level of intensity ranging from 0 - 63 for
  9768. each of the red, green, and blue components. The long integer that defines a
  9769. color value contains four bytes (32 bits):  %@NL@%
  9770. %@NL@%
  9771. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  9772. %@NL@%
  9773. The most-significant byte should contain zeros. The two high bits in the
  9774. remaining three bytes should also be zero (these bits are ignored).  %@NL@%
  9775. %@NL@%
  9776. To mix a light red (pink), turn red all the way up, and mix in some green
  9777. and blue:  %@NL@%
  9778. %@NL@%
  9779. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  9780. %@NL@%
  9781. The number 0x0020203FL represents this value in hexadecimal notation. You
  9782. can also use the following macro:  %@NL@%
  9783. %@NL@%
  9784. %@AS@%  #define RGB ( r, g, b ) (0x3F3F3FL & ((long)(b) << 16 | (g) << 8 | (r)))%@AE@%%@NL@%
  9785. %@NL@%
  9786. To create pure yellow (100% red plus 100% green) and assign it to a variable
  9787. %@AS@% yel%@AE@%, use this line:  %@NL@%
  9788. %@NL@%
  9789. %@AS@%  yel = RGB( 63, 63, 0 );%@AE@%%@NL@%
  9790. %@NL@%
  9791. For white, turn all the colors on: %@AS@% RGB( 63, 63, 63)%@AE@%. For black, set all
  9792. colors to 0: %@AS@% RGB( 0, 0, 0 )%@AE@%. %@AS@%  %@AE@%%@NL@%
  9793. %@NL@%
  9794. Once you have the color value,  %@NL@%
  9795. %@NL@%
  9796. %@NL@%
  9797.   ■   Call %@AB@%_remappalette%@AE@%, passing a color index and a color value.%@NL@%
  9798. %@NL@%
  9799.   ■   Call %@AB@%_setcolor%@AE@% to make that color index the current color.%@NL@%
  9800. %@NL@%
  9801.   ■   Draw something.%@NL@%
  9802. %@NL@%
  9803. %@NL@%
  9804. The program YELLOW.C below shows how to remap a color. It draws a rectangle
  9805. in color index 3 and then changes index 3 to the color value 0x00003F3FL
  9806. (yellow).  %@NL@%
  9807. %@NL@%
  9808. %@AS@%  /* YELLOW.C -- Draws a yellow box on the screen */
  9809. %@AS@%  /* Requires VGA or EGA */
  9810. %@AS@%  
  9811. %@AS@%  #include <graph.h> /* graphics functions */
  9812. %@AS@%  #include <conio.h> /* getch */
  9813. %@AS@%  
  9814. %@AS@%  main()
  9815. %@AS@%  {
  9816. %@AS@%     short int index3 = 3;
  9817. %@AS@%     long int yellow = 0x00003F3FL;
  9818. %@AS@%     long int old3;%@AE@%%@NL@%
  9819. %@NL@%
  9820. %@AS@%  if( _setvideomode( _HRES16COLOR ) )
  9821. %@AS@%     {
  9822. %@AS@%              /* set current color to index 3*/
  9823. %@AS@%        _setcolor( index3 );
  9824. %@AS@%              /* draw a rectangle in that color */
  9825. %@AS@%        _rectangle( _GBORDER, 10, 10, 110, 110 );
  9826. %@AS@%              /* wait for a keypress */
  9827. %@AS@%        getch();
  9828. %@AS@%              /* change index 3 to yellow */
  9829. %@AS@%        old3 = _remappalette( index3, yellow );
  9830. %@AS@%              /* wait for a keypress */
  9831. %@AS@%        getch();
  9832. %@AS@%              /* restore the old color */
  9833. %@AS@%        _remappalette( index3, old3 );
  9834. %@AS@%        getch();
  9835. %@AS@%               /* back to default mode */
  9836. %@AS@%        _setvideomode( _DEFAULTMODE );
  9837. %@AS@%     } else _outtext( "This program requires EGA or VGA." );
  9838. %@AS@%  }%@AE@%%@NL@%
  9839. %@NL@%
  9840. %@NL@%
  9841. %@3@%%@CR:C6A00100015 @%%@AB@%10.2.4  MCGA Palettes%@AE@%%@EH@%%@NL@%
  9842. %@NL@%
  9843. In terms of color mixing, the MCGA (Multicolor Graphics Array) adapter is
  9844. the same as the VGA. It can display any of 256K colors. It cannot enter all
  9845. of the VGA video modes, however. It is limited to CGA modes and %@AB@%_VRES2COLOR%@AE@%
  9846. and %@AB@%_MRES256COLOR%@AE@%.  %@NL@%
  9847. %@NL@%
  9848. %@NL@%
  9849. %@3@%%@CR:C6A00100016 @%%@AB@%10.2.5  EGA Palettes%@AE@%%@EH@%%@NL@%
  9850. %@NL@%
  9851. Mixing colors in EGA (Enhanced Graphics Adapter) is similar to the VGA
  9852. mixing described in Section 10.2.3, but there are fewer levels of intensity
  9853. for the red, green, and blue (RGB) components. In the modes that offer 64
  9854. colors, the RGB values include two bits and can range in value from 0 - 3.
  9855. The long integer that defines a color value looks like this:  %@NL@%
  9856. %@NL@%
  9857. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  9858. %@NL@%
  9859. The bits marked %@AS@% 0 %@AE@% should be zeros; the bits marked %@AS@% ? %@AE@% are ignored. EGA
  9860. color values are defined this way to maintain compatibility with VGA color
  9861. values.  %@NL@%
  9862. %@NL@%
  9863. To form a pure red color value, use the constant 0x00000030L. For cyan (blue
  9864. plus green), use 0x00303000L. The RGB macro defined above for VGA color
  9865. mixing can be used as is, or you can modify it for EGA monitors:  %@NL@%
  9866. %@NL@%
  9867. %@AS@%  #define EGARGB( r, g, b ) (0x303030L & ((long)(b) << 20 | (g) << 12 | (r
  9868. %@AS@%  << 4)))%@AE@%%@NL@%
  9869. %@NL@%
  9870. In this macro, you would pass values in the range 0 -3 instead of 0 - 63.  %@NL@%
  9871. %@NL@%
  9872. For an example program that remaps a color index to a color value, see
  9873. YELLOW.C in Section 10.2.3, "VGA Palettes."  %@NL@%
  9874. %@NL@%
  9875. %@NL@%
  9876. %@3@%%@CR:C6A00100017 @%%@AB@%10.2.6  Symbolic Constants%@AE@%%@EH@%%@NL@%
  9877. %@NL@%
  9878. The GRAPH.H file defines the following constants, which can be used as
  9879. ready-made color values for EGA and VGA adapters:  %@NL@%
  9880. %@NL@%
  9881. %@TH:   7   448 01 14 15 47 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_BLACK%@AE@%        _GREEN         %@AB@%_LIGHTYELLOW%@AE@%%@AB@%_BLUE%@AE@%         _LIGHTBLUE     %@AB@%_MAGENTA%@AE@%%@AB@%_BRIGHTWHITE%@AE@%  _LIGHTCYAN     %@AB@%_RED%@AE@%%@AB@%_BROWN%@AE@%        _LIGHTGREEN    %@AB@%_WHITE%@AE@%%@AB@%_CYAN%@AE@%         _LIGHTMAGENTA%@AB@%_GRAY%@AE@%         _LIGHTRED%@TE:   7   448 01 14 15 47 @%
  9882.  
  9883. For example, to change color index 1 to red, use the line%@AB@%  %@AE@%%@NL@%
  9884. %@NL@%
  9885. %@AS@%  _remappalette( 1, _RED );%@AE@%%@NL@%
  9886. %@NL@%
  9887. which causes any object currently drawn with color index 1 to change to red.
  9888. The default color value associated with index 1 is blue.  %@NL@%
  9889. %@NL@%
  9890. %@NL@%
  9891. %@2@%%@CR:C6A00100018 @%%@AB@%10.3  Specifying Points within Coordinate Systems%@AE@%%@EH@%%@NL@%
  9892. %@NL@%
  9893. A coordinate system describes points on the screen in terms of their
  9894. horizontal (%@AI@%x%@AE@%) and vertical (%@AI@%y%@AE@%) positions. You specify a certain location by
  9895. providing two values that map to a unique position.%@CR:C6A00100019 @%%@AI@%  %@AE@%%@NL@%
  9896. %@NL@%
  9897. %@AU@% Graphics functions usually use viewport and window coordinates.%@AE@%  %@NL@%
  9898. %@NL@%
  9899. Coordinates on the physical screen never change. Only five functions, listed
  9900. in Section 10.3.1, use physical coordinates. All other graphics functions
  9901. use one of these two coordinate systems:  %@NL@%
  9902. %@NL@%
  9903. %@NL@%
  9904.   ■   Viewport coordinates (short integers)%@NL@%
  9905. %@NL@%
  9906.   ■   Window coordinates (double-precision floating-point numbers)%@NL@%
  9907. %@NL@%
  9908. %@NL@%
  9909. Viewports and windows can occupy all of the physical screen or just part of
  9910. it. The three coordinate systems and conventions for naming points and
  9911. regions of the screen are described below.  %@NL@%
  9912. %@NL@%
  9913. %@NL@%
  9914. %@3@%%@CR:C6A00100020 @%%@AB@%10.3.1  Physical Coordinates%@AE@%%@EH@%%@NL@%
  9915. %@NL@%
  9916. Within the physical screen, the upper left corner is called the "origin."
  9917. The %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinates for the origin are always (0, 0). The %@AI@%x%@AE@% axis extends
  9918. in the positive direction left to right, while the %@AI@%y%@AE@% axis extends in the
  9919. positive direction top to bottom.%@CR:C6A00100021 @%  %@NL@%
  9920. %@NL@%
  9921. For example, the video mode %@AB@%_VRES16COLOR%@AE@% has a resolution of 640 x 480,
  9922. which means the %@AI@%x%@AE@% axis contains the values 0 - 639 (left to right), and the
  9923. %@AI@%y%@AE@% axis contains 0 - 479 (top to bottom). (See Figure 10.1.)  %@NL@%
  9924. %@NL@%
  9925. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  9926. %@NL@%
  9927. Only five functions use physical coordinates: %@AB@%_setcliprgn%@AE@%, %@AB@%_setvieworg%@AE@%,
  9928. %@AB@%_setviewport%@AE@%,%@AB@% _getviewcoord%@AE@%, and%@AB@% _getphyscoord%@AE@%.  %@NL@%
  9929. %@NL@%
  9930. The %@AB@%_setcliprgn%@AE@% function establishes a "clipping region." Attempts to draw
  9931. inside the region succeed, while attempts to draw outside the region are
  9932. clipped (ignored). When you first enter a graphics mode, the clipping region
  9933. defaults to the entire screen.  %@NL@%
  9934. %@NL@%
  9935. The %@AB@%_setvieworg%@AE@% function changes the current location of the origin. When a
  9936. program first enters a graphics mode, the physical origin and the viewport
  9937. origin are in the upper left corner. The following code moves the viewport
  9938. origin to the physical screen location (50, 100):%@CR:C6A00100022 @%  %@NL@%
  9939. %@NL@%
  9940. %@AS@%  _setvieworg( 50, 100 );%@AE@%%@NL@%
  9941. %@NL@%
  9942. The effect on the screen is illustrated in Figure 10.2. Note that the number
  9943. of pixels remains constant, but the range of legal %@AI@%x%@AE@% values changes from a
  9944. range of 0 to 639 (physical screen) to -50 to 589. The legal %@AI@%y%@AE@% values change
  9945. as well.  %@NL@%
  9946. %@NL@%
  9947. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  9948. %@NL@%
  9949. All graphics functions are affected by the new origin, including %@AB@%_arc%@AE@%,
  9950. %@AB@%_ellipse%@AE@%, %@AB@%_lineto%@AE@%, %@AB@%_moveto%@AE@%, %@AB@%_outgtext%@AE@%,%@AB@% %@AE@% %@AB@%_pie%@AE@%, and %@AB@%_rectangle%@AE@%.  %@NL@%
  9951. %@NL@%
  9952. The third function that uses physical coordinates is %@AB@%_setviewport%@AE@%, described
  9953. below, which establishes the boundaries of the current viewport.  %@NL@%
  9954. %@NL@%
  9955. %@NL@%
  9956. %@3@%%@CR:C6A00100023 @%%@AB@%10.3.2  Viewport Coordinates%@AE@%%@EH@%%@NL@%
  9957. %@NL@%
  9958. The default viewport coordinate system is identical to the physical screen
  9959. coordinate system. The %@AB@%_setviewport%@AE@% function creates a new viewport within
  9960. the boundaries of the physical screen. A standard viewport has two
  9961. distinguishing features:%@CR:C6A00100024 @%%@CR:C6A00100025 @%  %@NL@%
  9962. %@NL@%
  9963. %@NL@%
  9964.   ■   The origin of a viewport initially lies in the upper left corner of
  9965.       the viewport, not the upper left corner of the physical screen.%@NL@%
  9966. %@NL@%
  9967.   ■   The clipping region matches the outer boundaries of the viewport.%@NL@%
  9968. %@NL@%
  9969. %@NL@%
  9970. %@AU@% Graphics output functions require viewport or window coordinate values.%@AE@%  %@NL@%
  9971. %@NL@%
  9972. In other words, the %@AB@%_setviewport%@AE@% function does the same thing as would two
  9973. separate calls to %@AB@%_setvieworg%@AE@% and %@AB@%_setcliprgn%@AE@%. All graphics output functions
  9974. require values that are either viewport coordinates or window coordinates.  %@NL@%
  9975. %@NL@%
  9976. For example,  %@NL@%
  9977. %@NL@%
  9978. %@AS@%  _setviewport( 50, 50, 200, 100 );%@AE@%%@NL@%
  9979. %@NL@%
  9980. creates the viewport illustrated in Figure 10.3. The values passed to the
  9981. %@AB@%_setviewport%@AE@% function are physical screen locations of opposite corners.
  9982. After the viewport is created, the viewport origin lies in the upper left
  9983. corner.  %@NL@%
  9984. %@NL@%
  9985. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  9986. %@NL@%
  9987. %@NL@%
  9988. %@3@%%@CR:C6A00100026 @%%@AB@%10.3.3  Window Coordinates%@AE@%%@EH@%%@NL@%
  9989. %@NL@%
  9990. The %@AB@%_setwindow%@AE@% function allows you to use floating-point coordinates instead
  9991. of integers. More importantly, it scales the screen coordinates to almost
  9992. any size within the current viewport. Window functions take double-precision
  9993. arguments and have names that end with the suffixes %@AB@%_w%@AE@% or %@AB@%_wxy%@AE@%. The function
  9994. %@AB@%_lineto_w%@AE@% is the window-coordinate equivalent of the viewport function
  9995. %@AB@%_lineto%@AE@%.%@CR:C6A00100027 @%  %@NL@%
  9996. %@NL@%
  9997. To create a window for charting 12 months of average temperatures ranging
  9998. from - 40 to 100, use this line:  %@NL@%
  9999. %@NL@%
  10000. %@AS@%  _setwindow( TRUE, 1.0, -40.0, 12.0, 100.0 );%@AE@%%@NL@%
  10001. %@NL@%
  10002. The first argument is the invert flag, which puts the lowest %@AI@%y%@AE@% value at the
  10003. bottom of the screen instead of the top. The minimum and maximum coordinates
  10004. follow. The new organization of the screen is shown in Figure 10.4.  %@NL@%
  10005. %@NL@%
  10006. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  10007. %@NL@%
  10008. If you plot a point with %@AB@%_setpixel_w%@AE@% or draw a line with %@AB@%_lineto_w%@AE@%, the
  10009. values are automatically scaled to the established window.  %@NL@%
  10010. %@NL@%
  10011. Window-coordinate graphics provide a lot of flexibility. You can fit an axis
  10012. into a small range (such as 151.25 to 151.45) or into a large range (-50,000
  10013. to 80,000), depending on the type of data to be graphed. In addition, by
  10014. changing the window coordinates and redrawing a figure, you can create the
  10015. effects of zooming in or panning across a figure.  %@NL@%
  10016. %@NL@%
  10017. %@NL@%
  10018. %@3@%%@CR:C6A00100028 @%%@AB@%10.3.4  Screen Locations%@AE@%%@EH@%%@NL@%
  10019. %@NL@%
  10020. A coordinate system needs two values (a horizontal and a vertical position)
  10021. to describe the location of a point on the screen. There are times, however,
  10022. when it is more convenient to use one variable instead of two.%@CR:C6A00100029 @%%@CR:C6A00100030 @%  %@NL@%
  10023. %@NL@%
  10024. Some graphics functions require you to pass the location of a point on the
  10025. screen. Others return a value that represents a location. The GRAPH.H file
  10026. defines two structures that allow you to refer to a point with a single
  10027. variable.  %@NL@%
  10028. %@NL@%
  10029. %@NL@%
  10030.   ■   An %@AB@%xycoord %@AE@%structure contains two short integers called %@AB@%xcoord %@AE@%and
  10031.       %@AB@%ycoord%@AE@% for use in viewport graphics.%@NL@%
  10032. %@NL@%
  10033.   ■   A %@AB@%_wxycoord %@AE@%structure contains two %@AB@%doubles%@AE@% called %@AB@%wx %@AE@%and %@AB@%wy %@AE@%for use in
  10034.       window-coordinate graphics.%@NL@%
  10035. %@NL@%
  10036. %@NL@%
  10037. For example, you pass four %@AB@%doubles%@AE@% to the %@AB@%_rectangle_w%@AE@% function: an %@AI@%x%@AE@% and %@AI@%y%@AE@%
  10038. position for the upper left corner of the window and an %@AI@%x%@AE@% and %@AI@%y%@AE@% position for
  10039. the lower right corner. The %@AB@%_rectangle_wxy%@AE@% function takes two %@AB@%_wxycoord%@AE@%
  10040. structures.  %@NL@%
  10041. %@NL@%
  10042. %@NL@%
  10043. %@3@%%@CR:C6A00100031 @%%@AB@%10.3.5  Bounding Rectangles%@AE@%%@EH@%%@NL@%
  10044. %@NL@%
  10045. Certain figures such as arcs and ellipses are centered within a "bounding
  10046. rectangle," specified by two points that define the opposite corners of the
  10047. rectangle. The center of the rectangle becomes the center of the figure, and
  10048. the rectangle's borders determine the size of the figure. Figure 10.5 shows
  10049. start and end vectors and a bounding rectangle in which a pie shape has been
  10050. drawn with the %@AB@%_pie%@AE@% function. The first two sets of coordinates are %@AI@%x1%@AE@%, %@AI@%y1%@AE@%,
  10051. %@AI@%x2%@AE@%, and %@AI@%y2%@AE@%. They define the boundaries of the rectangle. The pie shape needs
  10052. two other points, %@AI@%x3%@AE@%, %@AI@%y3%@AE@%, %@AI@%x4%@AE@%, and %@AI@%y4%@AE@%, which indicate the starting and ending
  10053. lines.  %@NL@%
  10054. %@NL@%
  10055. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  10056. %@NL@%
  10057. %@NL@%
  10058. %@3@%%@CR:C6A00100032 @%%@AB@%10.3.6  The Pixel Cursor%@AE@%%@EH@%%@NL@%
  10059. %@NL@%
  10060. A "pixel cursor" is a location on the screen. The %@AB@%_moveto%@AE@% function positions
  10061. this cursor at a given spot. Nothing visible appears. If you call %@AB@%_lineto%@AE@%, a
  10062. line is drawn from the current pixel cursor to another point. The %@AB@%_lineto%@AE@%
  10063. function also changes the location of the pixel cursor. When you call
  10064. %@AB@%_outgtext%@AE@% to display fonted text, the characters are drawn at the current
  10065. pixel cursor location.  %@NL@%
  10066. %@NL@%
  10067. To draw a series of connected lines, call %@AB@%_lineto%@AE@% several times.  %@NL@%
  10068. %@NL@%
  10069. The %@AB@%_getcurrentposition%@AE@% function returns the cursor location in an %@AB@%xycoord%@AE@%
  10070. structure.  %@NL@%
  10071. %@NL@%
  10072. %@NL@%
  10073. %@2@%%@CR:C6A00100033 @%%@AB@%10.4  Graphics Functions%@AE@%%@EH@%%@NL@%
  10074. %@NL@%
  10075. This section lists the functions that work in one or more bit-mapped
  10076. graphics modes. Most of these functions are present in several forms. The
  10077. function names that end with %@AB@%_w%@AE@% use %@AB@%double%@AE@% values as arguments and the
  10078. window coordinate system. Functions that end with %@AB@%_wxy%@AE@% use the window
  10079. coordinate system and a %@AB@%_wxycoord%@AE@% structure to define the coordinates.
  10080. Functions with no suffix use the viewport coordinate system.%@CR:C6A00100034 @%  %@NL@%
  10081. %@NL@%
  10082. %@NL@%
  10083. %@3@%%@CR:C6A00100035 @%%@AB@%10.4.1  Controlling Video Modes%@AE@%%@EH@%%@NL@%
  10084. %@NL@%
  10085. The functions described below affect the current video mode, coordinate
  10086. systems, clipping regions, viewports, and windows. For more information, use
  10087. on-line help.  %@NL@%
  10088. %@NL@%
  10089. %@AB@%_clearscreen%@AE@% - Erases the text or graphics screen and fills it with the
  10090. current background color (note that setting the video mode automatically
  10091. clears the screen). Pass one of the constants %@AB@%_GCLEARSCREEN%@AE@%, %@AB@%_GVIEWPORT%@AE@%, or
  10092. %@AB@%_GWINDOW%@AE@%. No return value.%@NL@%
  10093. %@NL@%
  10094. %@AB@%_getphyscoord%@AE@% - Converts viewport coordinates to physical coordinates. Pass
  10095. an %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinate from the viewport. The function returns an %@AB@%xycoord%@AE@%
  10096. structure, which includes an %@AI@%x%@AE@% and a %@AI@%y%@AE@% position from the physical screen.%@CR:C6A00100036 @%%@NL@%
  10097. %@NL@%
  10098. %@AB@%_getvideoconfig%@AE@% - Obtains the status of the current graphics environment.
  10099. Pass it the address of a structure of type %@AB@%_videoconfig%@AE@%. See Section 10.1.3.
  10100. "Reading the videoconfig Structure."%@NL@%
  10101. %@NL@%
  10102. %@AB@%_getviewcoord%@AE@% - Converts physical coordinates to viewport coordinates. Pass
  10103. two integers: an %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinate. The function returns an %@AB@%xycoord%@AE@%
  10104. structure containing the equivalent position within the viewport.%@NL@%
  10105. %@NL@%
  10106. %@AB@%_getviewcoord_w%@AE@% - Converts window coordinates to viewport coordinates. Pass
  10107. two %@AB@%doubles%@AE@% that name points within the window. Returns the equivalent
  10108. viewport coordinates as an %@AB@%xycoord%@AE@% structure.%@NL@%
  10109. %@NL@%
  10110. %@AB@%_getviewcoord_wxy%@AE@% - Converts window coordinates to viewport coordinates in
  10111. an %@AB@%xycoord%@AE@% structure. Pass a %@AB@%_wxycoord%@AE@% structure.%@NL@%
  10112. %@NL@%
  10113. %@AB@%_getwindowcoord%@AE@% - Converts viewport coordinates to window coordinates. Pass
  10114. two integers representing viewport coordinates. Returns a %@AB@%_wxycoord%@AE@%
  10115. structure.%@NL@%
  10116. %@NL@%
  10117. %@AB@%_setcliprgn%@AE@% - Limits graphic output to part of the screen, called the
  10118. "clipping  region." Pass four values: the %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinate of the upper
  10119. left corner (on the physical screen) and the coordinates of the lower right
  10120. corner. The default clipping region is the entire screen. See Section
  10121. 10.3.1, "Physical Coordinates."%@NL@%
  10122. %@NL@%
  10123. %@AB@%_setvideomode%@AE@% - Selects an operating mode for the display screen. Pass a
  10124. constant, such as %@AB@%_HRES16COLOR%@AE@%. Returns 0 if the video mode selected is not
  10125. supported by the hardware. See Section 10.1.2, "Setting a Video Mode."%@NL@%
  10126. %@NL@%
  10127. %@AB@%_setvideomoderows%@AE@% - Sets the video mode and the number of rows for text
  10128. operations. Pass two values: a video mode and the desired number of text
  10129. rows (25, 30, 43, 50, or 60). Pass the symbolic constant %@AB@%_MAXTEXTROWS%@AE@% to get
  10130. the largest available number of rows. Returns the number of rows or 0 if
  10131. unsuccessful.%@NL@%
  10132. %@NL@%
  10133. %@AB@%_setvieworg%@AE@% - Repositions the viewport origin. Pass an %@AI@%x%@AE@% and %@AI@%y%@AE@% position: the
  10134. physical screen location that will become the new origin. Returns the
  10135. previous origin in an %@AB@%xycoord%@AE@% structure.%@NL@%
  10136. %@NL@%
  10137. %@AB@%_setviewport%@AE@% - Creates a viewport, including a clipping region and a new
  10138. origin in the upper left corner of the viewport. Subsequent calls to
  10139. graphics routines will be limited to the viewport area. Pass four short
  10140. integers that indicate the physical screen locations of the %@AI@%x%@AE@% and %@AI@%y%@AE@%
  10141. coordinates in the upper left and  lower right corners of the viewport. No
  10142. return value.%@NL@%
  10143. %@NL@%
  10144. %@AB@%_setwindow%@AE@% - Defines a window coordinate system. Pass five values: a short
  10145. invert flag (TRUE or FALSE) and four %@AB@%doubles%@AE@% that represent the extreme
  10146. values in the upper left and lower right portions of the current viewport.
  10147. See Section 10.3.3, "Window Coordinates."%@NL@%
  10148. %@NL@%
  10149. %@NL@%
  10150. %@3@%%@CR:C6A00100037 @%%@AB@%10.4.2  Changing Colors%@AE@%%@EH@%%@NL@%
  10151. %@NL@%
  10152. The functions below control colors and color palettes. For an introduction
  10153. to this topic, see Section 10.2, "Mixing Colors and Changing Palettes." For
  10154. function prototypes and more information, consult on-line help.%@CR:C6A00100038 @%%@CR:C6A00100039 @%  %@NL@%
  10155. %@NL@%
  10156. %@AB@%_getbkcolor%@AE@% - Reports the current background color as a long integer. In
  10157. EGA, MCGA, and VGA video modes, this is a color value. In CGA and text
  10158. modes, it is a color index.%@NL@%
  10159. %@NL@%
  10160. %@AB@%_getcolor%@AE@% - Returns the current color index.%@NL@%
  10161. %@NL@%
  10162. %@AB@%_remapallpalette%@AE@% - Assigns new color values to all color indexes. Pass a
  10163. pointer to an array of color values. Returns 0 if unsuccessful.%@NL@%
  10164. %@NL@%
  10165. %@AB@%_remappalette%@AE@% - Assigns a color value to a specific color index. Pass a
  10166. short color index and a long color value (which specifies the amount of red,
  10167. green, and blue). Returns the previous color value for that index or -1 if
  10168. unsuccessful. See Section 10.2.1, "CGA Palettes."%@NL@%
  10169. %@NL@%
  10170. %@AB@%_selectpalette%@AE@% - Selects a predefined palette. This function applies only to
  10171. the CGA video modes %@AB@%_MRES4COLOR%@AE@% and %@AB@%_MRESNOCOLOR%@AE@% and the Olivetti graphics
  10172. mode%@AB@% _ORESCOLOR%@AE@%. To change palettes in other color video modes, use
  10173. %@AB@%_remappalette%@AE@% instead. Pass a short integer in the range 0 - 4 for CGA, or 0
  10174. -15 for Olivetti mode. Returns the value of the previous palette.%@NL@%
  10175. %@NL@%
  10176. %@AB@%_setbkcolor%@AE@% - Sets the current background color. Always pass a long integer.
  10177. In EGA, MCGA, and VGA modes, this value is a color value. In CGA and text
  10178. modes, this is a color index cast to a long integer. Returns the old
  10179. background color or -1 if unsuccessful.%@NL@%
  10180. %@NL@%
  10181. %@AB@%_setcolor%@AE@% - Sets the color index to be used for graphic output. It affects
  10182. later calls to functions such as %@AB@%_arc%@AE@%, %@AB@%_ellipse%@AE@%, %@AB@%_floodfill%@AE@%, %@AB@%_lineto%@AE@%,
  10183. %@AB@%_outgtext%@AE@%, %@AB@%_outtext%@AE@%, %@AB@%_pie%@AE@%, %@AB@%_rectangle%@AE@%, and %@AB@%_setpixel%@AE@%. Returns the previous
  10184. color or -1 if unsuccessful.%@NL@%
  10185. %@NL@%
  10186. %@NL@%
  10187. %@3@%%@CR:C6A00100040 @%%@AB@%10.4.3  Drawing Points, Lines, and Shapes%@AE@%%@EH@%%@NL@%
  10188. %@NL@%
  10189. The functions described below draw points, lines, and shapes. For a
  10190. definition of bounding rectangle and pixel cursor, see Sections 10.3.5 and
  10191. 10.3.6.%@CR:C6A00100041 @%  %@NL@%
  10192. %@NL@%
  10193. %@AB@%_arc%@AE@% - Draws an elliptical arc. Pass eight short integers: four pairs of %@AI@%x%@AE@%
  10194. and %@AI@%y%@AE@% coordinates. The first two pairs are the corners of the bounding
  10195. rectangle. The third and fourth are the starting and ending points of the
  10196. arc. Returns 0 if unsuccessful.%@NL@%
  10197. %@NL@%
  10198. %@AB@%_arc_wxy%@AE@% - Draws an arc within the window. Pass four %@AB@%wxycoord%@AE@% structures.
  10199. The first two are the corners of the bounding rectangle. The third and
  10200. fourth are the starting and ending points of the arc. Returns 0 if
  10201. unsuccessful.%@NL@%
  10202. %@NL@%
  10203. %@AB@%_ellipse%@AE@% - Draws an ellipse or a circle. Pass a short fill flag (%@AB@% _GBORDER%@AE@%
  10204. or %@AB@%_GFILLINTERIOR%@AE@%) and four short integers representing the corners of the
  10205. bounding rectangle. Returns 0 if unsuccessful.%@NL@%
  10206. %@NL@%
  10207. %@AB@%_ellipse_w%@AE@% - Draws an ellipse or a circle within a window. Pass a short fill
  10208. flag (%@AB@% _GBORDER%@AE@% or %@AB@%_GFILLINTERIOR%@AE@%) and four %@AB@%doubles%@AE@% representing the corners
  10209. of the bounding rectangle. Returns 0 if unsuccessful.%@NL@%
  10210. %@NL@%
  10211. %@AB@%_ellipse_wxy%@AE@% - Draws an ellipse or a circle. Pass a short fill flag (%@AB@%
  10212. %@AB@%_GBORDER%@AE@% or  %@AB@%_GFILLINTERIOR%@AE@%) and two %@AB@%_wxycoord%@AE@% structures representing the
  10213. two corners of the bounding rectangle. Returns 0 if unsuccessful.%@NL@%
  10214. %@NL@%
  10215. %@AB@%_getcurrentposition%@CR:C6A00100042 @%%@AE@% - Returns the current pixel cursor position in viewport
  10216. coordinates as an %@AB@%xycoord%@AE@% structure. The current position can be changed by
  10217. %@AB@%_arc%@AE@%, %@AB@%_lineto%@AE@%, and %@AB@%_moveto%@AE@%. The default position is the center of the
  10218. viewport.%@NL@%
  10219. %@NL@%
  10220. %@AB@%_getcurrentposition_w%@AE@% - Returns the current position of the pixel cursor as
  10221. a %@AB@%_wxycoord%@AE@% structure containing the %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinates. Pass nothing.%@NL@%
  10222. %@NL@%
  10223. %@AB@%_getpixel%@AE@% - Returns a pixel's color index. Pass a short %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinate
  10224. (in viewport coordinates). If the point is outside the clipping region, the
  10225. function returns -1.%@NL@%
  10226. %@NL@%
  10227. %@AB@%_getpixel_w%@AE@% - Returns a pixel's color index. Pass two doubles: an %@AI@%x%@AE@% and %@AI@%y%@AE@%
  10228. coordinate.%@NL@%
  10229. %@NL@%
  10230. %@AB@%_lineto%@AE@% - Draws a line from the current pixel cursor position to a specified
  10231. point. Pass a short %@AI@%x%@AE@% and a short %@AI@%y%@AE@% position. Returns 0 if unsuccessful.%@NL@%
  10232. %@NL@%
  10233. %@AB@%_lineto_w%@AE@% - Draws a line from the current pixel position to a specified
  10234. window coordinate point. Pass a %@AB@%double%@AE@% %@AI@%x%@AE@% and %@AI@%y%@AE@% position. Returns 0 if
  10235. unsuccessful.%@NL@%
  10236. %@NL@%
  10237. %@AB@%_moveto%@AE@% - Moves the pixel cursor to a specified point (with no graphic
  10238. output). Pass an %@AI@%x%@AE@% and %@AI@%y%@AE@% position. Returns the coordinates of the previous
  10239. position in an %@AB@%xycoord%@AE@% structure.%@NL@%
  10240. %@NL@%
  10241. %@AB@%_moveto_w%@AE@% - Moves the pixel cursor to a specified point in a window. Pass
  10242. two doubles: an %@AI@%x%@AE@% and a %@AI@%y%@AE@% coordinate. Returns the previous position as a
  10243. %@AB@%_wxycoord%@AE@% structure.%@NL@%
  10244. %@NL@%
  10245. %@AB@%_ pie%@AE@% - Draws a figure shaped like a pie slice. Pass a short fill flag and
  10246. eight short integers. The first four describe the bounding rectangle. The
  10247. final four represent the starting vector and ending vector. Returns 0 if
  10248. unsuccessful.%@NL@%
  10249. %@NL@%
  10250. %@AB@%_ pie_wxy%@AE@% - Draws a pie-slice figure within a window. Pass a short fill flag
  10251. and four %@AB@%_wxycoord%@AE@% structures. The first two describe the bounding
  10252. rectangle. The second two represent the starting vector and ending vector.
  10253. Returns 0 if unsuccessful.%@NL@%
  10254. %@NL@%
  10255. %@AB@%_rectangle%@AE@% - Draws a rectangle in the current line style. Pass a short fill
  10256. flag (%@AB@% _GFILLINTERIOR%@AE@% or %@AB@%_GBORDER%@AE@%) and four short integers: the %@AI@%x%@AE@% and %@AI@%y%@AE@%
  10257. coordinates of opposite corners. Returns 0 if unsuccessful.%@NL@%
  10258. %@NL@%
  10259. %@AB@%_rectangle_w%@AE@% - Draws a rectangle in the current line style. Pass a short
  10260. fill flag (%@AB@% _GFILLINTERIOR%@AE@% or %@AB@%_GBORDER%@AE@%) and four doubles: the %@AI@%x%@AE@% and %@AI@%y%@AE@% window
  10261. coordinates of opposite corners. Returns 0 if unsuccessful.%@NL@%
  10262. %@NL@%
  10263. %@AB@%_rectangle_wxy%@AE@% - Draws a rectangle in the current line style. Pass a short
  10264. fill flag (%@AB@% _GFILLINTERIOR%@AE@% or %@AB@%_GBORDER%@AE@%) and two %@AB@%_wxycoord%@AE@% structures
  10265. describing the %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinates of opposite corners. Returns 0 if
  10266. unsuccessful.%@NL@%
  10267. %@NL@%
  10268. %@AB@%_setpixel%@AE@% - Sets a pixel to the current color (which is selected by
  10269. %@AB@%_setcolor%@AE@%). Pass it integer %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinates. Returns the previous value
  10270. of the pixel or -1 if unsuccessful.%@NL@%
  10271. %@NL@%
  10272. %@AB@%_setpixel_w%@AE@% - Sets a pixel to the current color (which is selected by
  10273. %@AB@%_setcolor%@AE@%). Pass it %@AB@%double%@AE@% %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinates describing a position within
  10274. the window. Returns the previous value of the pixel or -1 if unsuccessful.%@NL@%
  10275. %@NL@%
  10276. %@NL@%
  10277. %@3@%%@CR:C6A00100043 @%%@AB@%10.4.4  Defining Patterns%@AE@%%@EH@%%@NL@%
  10278. %@NL@%
  10279. The following functions control the style in which straight lines are drawn
  10280. and the fill pattern used for solid shapes. For more information, use
  10281. on-line help.%@CR:C6A00100044 @%  %@NL@%
  10282. %@NL@%
  10283. %@AB@%_floodfill%@AE@% - Fills a bounded shape with the fill pattern set by %@AB@%_setfillmask%@AE@%
  10284. in the current color established by %@AB@%_setcolor%@AE@%. Pass an %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinate
  10285. and a boundary color (the color index that marks the edge of the shape to be
  10286. filled). Returns 0 if unsuccessful.%@NL@%
  10287. %@NL@%
  10288. %@AB@%_floodfill_w%@AE@% - Fills a bounded shape with the fill pattern set by
  10289. %@AB@%_setfillmask%@AE@%. Pass %@AB@%doubles%@AE@% that describe an %@AI@%x%@AE@% and %@AI@%y%@AE@% position within the
  10290. window and a boundary color (the color index that marks the edge of the
  10291. shape to be filled). Returns 0 if unsuccessful.%@NL@%
  10292. %@NL@%
  10293. %@AB@%_getfillmask%@AE@% - Returns the address of the current fill mask, an
  10294. eight-character array, or 0 if the fill mask is not currently defined.%@NL@%
  10295. %@NL@%
  10296. %@AB@%_getlinestyle%@AE@% - Returns the line style, a short integer whose bits
  10297. correspond to the screen pixels turned on or off within a line.%@NL@%
  10298. %@NL@%
  10299. %@AB@%_setfillmask%@AE@% - Sets the current fill mask used by %@AB@%_floodfill %@AE@%and functions
  10300. that draw solid shapes (%@AB@%_ellipse%@AE@%, %@AB@%_pie%@AE@%, and %@AB@%_rectangle%@AE@%). Pass the address of
  10301. an array of eight unsigned characters, where each bit represents a pixel.
  10302. The pixels are drawn in the current color. No return value.%@NL@%
  10303. %@NL@%
  10304. %@AB@%_setlinestyle%@AE@% - Sets the current style, which is used to draw the straight
  10305. lines within %@AB@%_lineto%@AE@%, %@AB@%_rectangle%@AE@%, and %@AB@%_pie%@AE@%. Pass an unsigned short integer
  10306. within which the bits correspond to the pixels on screen. For example,
  10307. 0xFFFF represents a solid line, 0xAAAA is a dotted line, and 0xF0F0 is
  10308. dashed.%@NL@%
  10309. %@NL@%
  10310. %@NL@%
  10311. %@3@%%@CR:C6A00100045 @%%@AB@%10.4.5  Manipulating Images%@AE@%%@EH@%%@NL@%
  10312. %@NL@%
  10313. The functions described below can be used to create animated graphics. The
  10314. %@AB@%_getimage %@AE@%and %@AB@%_putimage %@AE@%functions act like a rubber stamp; after capturing a
  10315. shape, you can make copies anywhere on the screen.%@CR:C6A00100046 @%  %@NL@%
  10316. %@NL@%
  10317. %@AB@%_getimage%@AE@% - Stores a screen image in memory. Pass four integers (the
  10318. coordinates of the bounding rectangle) and a pointer to a storage buffer.
  10319. Call %@AB@%_imagesize%@AE@% to find out how much memory is required. No return value.%@NL@%
  10320. %@NL@%
  10321. %@AB@%_getimage_w%@AE@% - Stores a screen image in memory. Pass four %@AB@%doubles%@AE@% (the
  10322. coordinates of the bounding rectangle) and a pointer to a storage buffer.
  10323. Call %@AB@%_imagesize_w%@AE@% to find out how much memory is required. No return value.%@NL@%
  10324. %@NL@%
  10325. %@AB@%_getimage_wxy%@AE@% - Same as %@AB@%_getimage_w%@AE@%, but you pass two %@AB@%_wxycoord%@AE@% structures
  10326. and a pointer to memory.%@NL@%
  10327. %@NL@%
  10328. %@AB@%_imagesize%@AE@% - Returns a long integer representing the size of an image in
  10329. bytes. Call this function in preparation for a call to %@AB@%_getimage%@AE@%. Pass four
  10330. integers: the %@AI@%x%@AE@% and %@AI@%y%@AE@% coordinates of opposite corners of the portion of the
  10331. screen to be saved.%@NL@%
  10332. %@NL@%
  10333. %@AB@%_imagesize_w%@AE@% - Returns the size of an image in bytes in preparation for a
  10334. call to %@AB@%_getimage_w%@AE@% and %@AB@%_putimage_w%@AE@%. Pass four doubles: the %@AI@%x%@AE@% and %@AI@%y%@AE@% window
  10335. coordinates of opposite corners of the portion of the screen to be saved.%@NL@%
  10336. %@NL@%
  10337. %@AB@%_imagesize_wxy%@AE@% - Same as %@AB@%_imagesize_w%@AE@%, but you pass two %@AB@%_wxycoord%@AE@%
  10338. structures.%@NL@%
  10339. %@NL@%
  10340. %@AB@%_putimage%@AE@% - Retrieves an image from memory and displays it on the active
  10341. screen page. The image should previously have been saved to memory with
  10342. %@AB@%_getimage%@AE@%. Pass two short integers (coordinates where the image is to be
  10343. placed), a pointer to the image, and a short integer indicating what kind of
  10344. action to take: %@AB@%_GAND%@AE@%, %@AB@%_GOR%@AE@%, %@AB@%_GPRESET%@AE@%, %@AB@%_GPSET%@AE@%, or %@AB@%_GXOR%@AE@%. No return value.%@NL@%
  10345. %@NL@%
  10346. %@AB@%_putimage_w%@AE@% - Displays an image from memory within a window. The image
  10347. should previously have been saved to memory with %@AB@%_getimage_w%@AE@%. Pass two
  10348. %@AB@%doubles%@AE@% (coordinates where the image is to be placed), a pointer to the
  10349. image, and a short integer indicating what kind of action to take: %@AB@%_GAND%@AE@%,
  10350. %@AB@%_GOR%@AE@%, %@AB@%_GPRESET%@AE@%, %@AB@%_GPSET%@AE@%, or %@AB@%_GXOR%@AE@%. No return value.%@NL@%
  10351. %@NL@%
  10352. %@NL@%
  10353. %@2@%%@CR:C6A00100047 @%%@AB@%10.5  Using Graphic Fonts%@AE@%%@EH@%%@NL@%
  10354. %@NL@%
  10355. A "font" is a collection of stylized text characters. Each font consists of
  10356. a typeface with several type sizes.%@CR:C6A00100048 @%  %@NL@%
  10357. %@NL@%
  10358. A "typeface" is the name of the displayed text─Courier, for example, or
  10359. Roman. The list on the next page shows six of the typefaces available with
  10360. the Microsoft C font library.  %@NL@%
  10361. %@NL@%
  10362. "Type size" measures the screen area occupied by individual characters in
  10363. units of screen pixels. For example, "Courier 12 x 9" denotes text of
  10364. Courier typeface, with each character occupying a screen area of 12 vertical
  10365. pixels by 9 horizontal pixels.  %@NL@%
  10366. %@NL@%
  10367. A font's spacing can be fixed or proportional. "Fixed" means that all
  10368. characters have the same width in pixels. "Proportional" means the width
  10369. varies. An %@AI@%i%@AE@%, for example, is thinner than an %@AI@%M%@AE@%.  %@NL@%
  10370. %@NL@%
  10371. The Microsoft C font functions use two methods to create fonts. The first
  10372. technique generates Courier, Helv, and Tms Rmn fonts through a "bit-mapping"
  10373. (or "raster-mapping") technique. Bit-mapping defines character images with
  10374. binary data. Each bit in the map corresponds to a screen pixel. If a bit is
  10375. 1, its associated pixel is set to the current screen color.  %@NL@%
  10376. %@NL@%
  10377. The second method creates the remaining three type styles─Modern, Script,
  10378. and Roman─as "vector-mapped" fonts. Vector-mapping represents each character
  10379. in terms of lines and arcs.  %@NL@%
  10380. %@NL@%
  10381. Each method has advantages and disadvantages. Bit-mapped characters are more
  10382. completely formed since the pixel mapping is predetermined. However, they
  10383. cannot be scaled. Vector-mapped text can be scaled to any size, but the
  10384. characters tend to lack the solid appearance of the bit-mapped characters.  %@NL@%
  10385. %@NL@%
  10386. The following list shows six sample typefaces:  %@NL@%
  10387. %@NL@%
  10388. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  10389. %@NL@%
  10390. Table 10.6 lists available sizes for each font. Note that the bit-mapped
  10391. fonts come in preset sizes as measured in pixels. The vector-mapped fonts
  10392. can be scaled to any size.  %@NL@%
  10393. %@NL@%
  10394. %@AB@%Table 10.6  %@AB@%Typefaces and Type Sizes in the C Library%@AE@%%@AE@%
  10395.  
  10396. %@TH:  21   759 02 10 09 18 39 @%Typeface  Mapping  Size (in pixels)  Spacing%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Courier   Bit      10 x 8, 12 x 9,   Fixed                   15 x 12           Helv      Bit      10 x 5, 12 x 7,   Proportional                   15 x 8, 18 x 9,                      22 x 12, 28 x 16  Tms Rmn   Bit      10 x 5, 12 x 6,   Proportional                   15 x 8, 16 x 9,                      20 x 12, 26 x 16  Modern    Vector   Scaled            ProportionalScript    Vector   Scaled            ProportionalRoman     Vector   Scaled            Proportional%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  21   759 02 10 09 18 39 @%
  10397.  
  10398. %@NL@%
  10399. %@3@%%@CR:C6A00100049 @%%@AB@%10.5.1  Using the C Font Library%@AE@%%@EH@%%@NL@%
  10400. %@NL@%
  10401. Data for both bit-mapped and vector-mapped fonts reside in .FON files. For
  10402. example, the files MODERN.FON, ROMAN.FON, and SCRIPT.FON hold data for the
  10403. three vector-mapped fonts.%@CR:C6A00100050 @%%@CR:C6A00100051 @%  %@NL@%
  10404. %@NL@%
  10405. %@AU@% You can use Microsoft Windows .FON files.%@AE@%  %@NL@%
  10406. %@NL@%
  10407. The Microsoft C .FON files are identical to the .FON files used in the
  10408. Microsoft Windows operating environment. If you have access to Windows, you
  10409. can use any of its .FON files with Microsoft C font functions. In addition,
  10410. several vendors offer software that creates or modifies .FON files, allowing
  10411. you to design your own fonts.  %@NL@%
  10412. %@NL@%
  10413. Your programs should follow these three steps to display fonted text:  %@NL@%
  10414. %@NL@%
  10415. %@NL@%
  10416.   1.  Register the fonts.%@NL@%
  10417. %@NL@%
  10418.   2.  Set the current font from the register.%@NL@%
  10419. %@NL@%
  10420.   3.  Display text using the current font.%@NL@%
  10421. %@NL@%
  10422. %@NL@%
  10423. The following sections describe each of the three steps in detail. An
  10424. example program in Section 10.5.5 demonstrates these steps.  %@NL@%
  10425. %@NL@%
  10426. %@NL@%
  10427. %@3@%%@CR:C6A00100052 @%%@AB@%10.5.2  Registering the Fonts%@AE@%%@EH@%%@NL@%
  10428. %@NL@%
  10429. The fonts must first be organized into a list in memory, a process called
  10430. "registering." Register fonts by calling the function %@AB@%_registerfonts%@AE@%. This
  10431. function reads header information from specified .FON files, building a list
  10432. of file information but not reading any mapping data from the files.%@CR:C6A00100053 @%%@CR:C6A00100054 @%  %@NL@%
  10433. %@NL@%
  10434. The GRAPH.H file prototypes the %@AB@%_registerfonts%@AE@% function as  %@NL@%
  10435. %@NL@%
  10436. %@AS@%  short far _registerfonts( unsigned char far * );%@AE@%%@NL@%
  10437. %@NL@%
  10438. The argument points to a string containing a file name. The file name is the
  10439. name of the .FON file for the desired font. The file name can include wild
  10440. cards, allowing you to register several fonts with one call to
  10441. %@AB@%_registerfonts%@AE@%.  %@NL@%
  10442. %@NL@%
  10443. If it successfully reads one or more .FON files, %@AB@%_registerfonts%@AE@% returns the
  10444. number of fonts. If the function fails, it returns a negative error code.  %@NL@%
  10445. %@NL@%
  10446. %@NL@%
  10447. %@3@%%@CR:C6A00100055 @%%@AB@%10.5.3  Setting the Current Font%@AE@%%@EH@%%@NL@%
  10448. %@NL@%
  10449. Call the function %@AB@%_setfont%@AE@% to select a current font. This function checks to
  10450. see if the requested font is registered, then reads the mapping data from
  10451. the appropriate .FON file. A font must be registered and marked current
  10452. before your program can display text in that font.  %@NL@%
  10453. %@NL@%
  10454. The GRAPH.H file prototypes the%@AB@%_setfonts%@AE@% function as  %@NL@%
  10455. %@NL@%
  10456. %@AS@%  short far _setfont( unsigned char far * );%@AE@%%@NL@%
  10457. %@NL@%
  10458. The function's argument is a pointer to a character string. The string
  10459. consists of letter codes that describe the desired font, as outlined here:  %@NL@%
  10460. %@NL@%
  10461. %@AB@%Option Code%@AE@%                       %@AB@%Meaning%@AE@%
  10462. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10463. %@AB@%b%@AE@%                                 The best fit from the registered fonts. 
  10464.                                   This option instructs %@AB@%_setfont%@AE@% to accept
  10465.                                   the closest-fitting font if a font of 
  10466.                                   the specified size is not registered.
  10467.  
  10468.                                   If at least one font is registered, the %@AB@%%@AE@%
  10469.                                   %@AB@%b%@AE@% option always sets a current font. If 
  10470.                                   you do not specify the %@AB@%b%@AE@% option and an 
  10471.                                   exact matching font is not registered, 
  10472.                                   the%@AB@%%@AE@%
  10473.                                   %@AB@%_setfont%@AE@% function will fail. In this 
  10474.                                   case, any existing current font remains 
  10475.                                   current. Refer to on-line help for a 
  10476.                                   description of error codes returned by%@AB@%%@AE@%
  10477.                                   %@AB@%_setfont%@AE@%.
  10478.  
  10479.                                   The %@AB@%_setfont%@AE@% function uses four criteria
  10480.                                   for selecting the best fit. In 
  10481.                                   descending order of precedence, the four
  10482.                                   criteria are pixel height, typeface, 
  10483.                                   pixel width, and spacing (fixed or 
  10484.                                   proportional). If you request a 
  10485.                                   vector-mapped font,%@AB@% _setfont%@AE@% sizes the 
  10486.                                   font to correspond with the specified 
  10487.                                   pixel height and width. If you request a
  10488.                                   raster-mapped (bit-mapped) font,%@AB@%%@AE@%
  10489.                                   %@AB@%_setfont%@AE@% chooses the closest available 
  10490.                                   size. If the requested type size for a 
  10491.                                   raster-mapped font fits exactly between 
  10492.                                   two registered fonts, the smaller size 
  10493.                                   takes precedence.
  10494.  
  10495. %@AB@%f%@AE@%                                 Fixed-spaced font.
  10496.  
  10497. %@AB@%h%@AE@%%@AI@%y%@AE@%                                Character height, where %@AI@%y%@AE@% is the height 
  10498.                                   in pixels.
  10499.  
  10500. %@AB@%n%@AE@%%@AI@%x%@AE@%                                Font number %@AI@%x%@AE@%, where %@AI@%x%@AE@% is less than or 
  10501.                                   equal to the value returned by %@AB@%%@AE@%
  10502.                                   %@AB@%_registerfonts%@AE@%. For example, the option %@AB@%%@AE@%
  10503.                                   %@AB@%n%@AE@%3 makes the third registered font 
  10504.                                   current, if three or more fonts are 
  10505.                                   registered.
  10506.  
  10507. %@AB@%p%@AE@%                                 Proportional-spaced font.
  10508.  
  10509. %@AB@%r%@AE@%                                 Raster-mapped (bit-mapped) font.
  10510.  
  10511. %@AB@%t`%@AE@%%@AI@%fontname%@AE@%%@AB@%'%@AE@%                       Typeface of the font in single quotes. 
  10512.                                   The %@AI@%fontname%@AE@% string is one of the 
  10513.                                   following:
  10514.  
  10515.   courier  modern  helv  script  tms rmn  roman
  10516.  
  10517.                                   Note the space in tms rmn. Additional 
  10518.                                   font files use other names for %@AI@%fontname%@AE@%.
  10519.                                   Refer to the vendor's documentation for 
  10520.                                   these names.
  10521.  
  10522. %@AB@%v%@AE@%                                 Vector-mapped font.
  10523.  
  10524. %@AB@%w%@AE@%%@AI@%x%@AE@%                                Character width, where %@AI@%x%@AE@% is the width in
  10525.                                   pixels.
  10526.  
  10527. Option codes are not case sensitive and can be listed in any order. You can
  10528. separate codes with spaces or any other character that is not a valid option
  10529. code. The %@AB@%_setfont%@AE@% function ignores all invalid codes.  %@NL@%
  10530. %@NL@%
  10531. The %@AB@%_setfont%@AE@% function updates a data area with parameters of the current
  10532. font. The data area is in the form of a structure, defined in GRAPH.H as
  10533. follows:  %@NL@%
  10534. %@NL@%
  10535. %@AS@%  struct _fontinfo
  10536. %@AS@%  {
  10537. %@AS@%     int     type;          /* set = vector,clear = bit map */
  10538. %@AS@%     int     ascent;        /* pix dist from top to base */
  10539. %@AS@%     int     pixwidth;      /* character width in pixels */
  10540. %@AS@%     int     pixheight;     /* character height in pixels */
  10541. %@AS@%     int     avgwidth;      /* average character width */
  10542. %@AS@%     char    filename[81];  /* file name including path */
  10543. %@AS@%     char    faceName[32];  /* font name */
  10544. %@AS@%  };%@AE@%%@NL@%
  10545. %@NL@%
  10546. If you want to retrieve the parameters of the current font, call the
  10547. function %@AB@%_getfontinfo%@AE@%.  %@NL@%
  10548. %@NL@%
  10549. %@NL@%
  10550. %@3@%%@CR:C6A00100056 @%%@AB@%10.5.4  Displaying Text%@AE@%%@EH@%%@NL@%
  10551. %@NL@%
  10552. The last step, displaying text, consists of two parts. First you must select
  10553. a screen position for the text with the graphics function %@AB@%_moveto%@AE@%. Then
  10554. display fonted text at that position with the function %@AB@%_outgtext%@AE@%. The
  10555. %@AB@%_moveto%@AE@% function takes pixel coordinates as arguments. The coordinates
  10556. locate the top left of the first character in the text string.  %@NL@%
  10557. %@NL@%
  10558. %@NL@%
  10559. %@3@%%@CR:C6A00100057 @%%@AB@%10.5.5  A Sample Program%@AE@%%@EH@%%@NL@%
  10560. %@NL@%
  10561. The program SAMPLER.C displays sample text in all the available fonts, then
  10562. exits when a key is pressed. Make sure the .FON files are in the current
  10563. directory before running the program.  %@NL@%
  10564. %@NL@%
  10565. %@AS@%  /* SAMPLER.C: Displays sample text in various fonts. */
  10566. %@AS@%  
  10567. %@AS@%  #include <stdio.h>
  10568. %@AS@%  #include <conio.h>
  10569. %@AS@%  #include <stdlib.h>
  10570. %@AS@%  #include <graph.h>
  10571. %@AS@%  #include <string.h>
  10572. %@AS@%  #define NFONTS 6
  10573. %@AS@%  
  10574. %@AS@%  main()
  10575. %@AS@%  
  10576. %@AS@%  {
  10577. %@AS@%     static unsigned char *text[2*NFONTS] =
  10578. %@AS@%     {
  10579. %@AS@%         "COURIER",        "courier",
  10580. %@AS@%         "HELV",           "helv",
  10581. %@AS@%         "TMS RMN",        "tms rmn",
  10582. %@AS@%         "MODERN",         "modern",
  10583. %@AS@%         "SCRIPT",         "script",
  10584. %@AS@%         "ROMAN",          "roman"
  10585. %@AS@%     };
  10586. %@AS@%     static unsigned char *face[NFONTS] =
  10587. %@AS@%     {
  10588. %@AS@%         "t'courier'",
  10589. %@AS@%         "t'helv'",
  10590. %@AS@%         "t'tms rmn'",
  10591. %@AS@%         "t'modern'",
  10592. %@AS@%         "t'script'",
  10593. %@AS@%         "t'roman'"
  10594. %@AS@%     };%@AE@%%@NL@%
  10595. %@NL@%
  10596. %@AS@%  static unsigned char list[20];
  10597. %@AS@%     struct videoconfig vc;
  10598. %@AS@%     int mode = _VRES16COLOR;
  10599. %@AS@%     register i;%@AE@%%@NL@%
  10600. %@NL@%
  10601. %@AS@%  /*   Read header info from all .FON files in
  10602. %@AS@%      *   current directory
  10603. %@AS@%      */
  10604. %@AS@%  
  10605. %@AS@%     if( _registerfonts( "*.FON" ) < 0 )
  10606. %@AS@%     {
  10607. %@AS@%        _outtext( "Error: can't register fonts" );
  10608. %@AS@%        exit( 0 );
  10609. %@AS@%     }
  10610. %@AS@%  
  10611. %@AS@%     /*   Set highest available video mode */
  10612. %@AS@%  
  10613. %@AS@%     if( _setvideomode( _MAXRESMODE ) == 0 )
  10614. %@AS@%        exit ( 0 );
  10615. %@AS@%  
  10616. %@AS@%     /*   Copy video configuration into structure vc */
  10617. %@AS@%  
  10618. %@AS@%     _getvideoconfig( &vc );
  10619. %@AS@%  
  10620. %@AS@%     /*   Display six lines of sample text */
  10621. %@AS@%  
  10622. %@AS@%     for( i = 0; i < NFONTS; i++ )
  10623. %@AS@%     {
  10624. %@AS@%        strcpy( list, face[i] );
  10625. %@AS@%        strcat( list, "h30w24b" );
  10626. %@AS@%  
  10627. %@AS@%        if( _setfont( list ) >= 0 )
  10628. %@AS@%        {
  10629. %@AS@%            _setcolor( i + 1 );
  10630. %@AS@%            _moveto( 0, (i * vc.numypixels) / NFONTS );
  10631. %@AS@%            _outgtext( text[i * 2] );
  10632. %@AS@%            _moveto( vc.numxpixels / 2,
  10633. %@AS@%                        (i * vc.numypixels) / NFONTS );
  10634. %@AS@%            _outgtext( text[(i * 2) + 1] );
  10635. %@AS@%        }
  10636. %@AS@%        else
  10637. %@AS@%        {
  10638. %@AS@%            _setvideomode( _DEFAULTMODE );
  10639. %@AS@%            _outtext( "Error: can't set font" );
  10640. %@AS@%            exit( 0 );
  10641. %@AS@%        }
  10642. %@AS@%     }%@AE@%%@NL@%
  10643. %@NL@%
  10644. %@AS@%  getch();
  10645. %@AS@%     _setvideomode( _DEFAULTMODE );
  10646. %@AS@%  
  10647. %@AS@%     /* Return memory when finished with fonts */
  10648. %@AS@%  
  10649. %@AS@%     _unregisterfonts();
  10650. %@AS@%     exit( 0 );
  10651. %@AS@%  }%@AE@%%@NL@%
  10652. %@NL@%
  10653. %@NL@%
  10654. %@3@%%@CR:C6A00100058 @%%@AB@%10.5.6  Using Fonts Effectively%@AE@%%@EH@%%@NL@%
  10655. %@NL@%
  10656. Displaying fonts is simply another form of graphics; using fonts effectively
  10657. requires little programming effort. Still, there are a few things to watch:%@CR:C6A00100059 @%%@CR:C6A00100060 @%
  10658. %@NL@%
  10659. %@NL@%
  10660. %@NL@%
  10661.   ■   Remember that the video mode should be set only once. If you generate
  10662.       an image with presentation graphics and want to add text to it, do not
  10663.       reset the video mode prior to calling the font routines. Doing so will
  10664.       blank the screen, destroying the original image.%@NL@%
  10665. %@NL@%
  10666.   ■   The %@AB@%_setfont%@AE@% function reads specified .FON files to obtain mapping
  10667.       data for the current font. Each call to %@AB@%_setfont%@AE@% causes a disk access
  10668.       and overwrites the old font data in memory. If you want to show text
  10669.       of different styles on the same screen, display all text of one font
  10670.       before moving on to the others. Minimizing the number of calls to
  10671.       %@AB@%_setfont%@AE@% saves time spent in disk I/O and memory reloads.  %@NL@%
  10672. %@NL@%
  10673.   ■   When your program finishes using the fonts library, you may want to
  10674.       free the memory occupied by the register list by calling
  10675.       %@AB@%_unregisterfonts%@AE@%. This function frees the memory allocated by
  10676.       %@AB@%_registerfonts%@AE@%. The register information for each type size of each
  10677.       font takes up approximately 140 bytes of memory. %@NL@%
  10678. %@NL@%
  10679.   ■   Aesthetic suggestions for the printed page also apply to screen text.
  10680.       Typefaces are more effective when they do not compete with each other
  10681.       for attention. Restricting the number of styles per screen to one or
  10682.       two generally results in a more pleasing, less cluttered image.%@NL@%
  10683. %@NL@%
  10684. %@NL@%
  10685.   %@NL@%
  10686. %@NL@%
  10687. %@NL@%
  10688. %@NL@%
  10689. %@NL@%
  10690. %@NL@%
  10691. %@NL@%
  10692. %@CR:C6A00110001 @%%@1@%%@AB@%Chapter 11  Creating Charts and Graphs%@AE@%%@EH@%%@NL@%
  10693. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10694. %@NL@%
  10695. The low-level graphics functions described in Chapter 10, "Communicating
  10696. with Graphics," draw points, lines, and shapes. Although it is possible to
  10697. use them to generate charts and graphs, an additional set of high-level
  10698. graphics functions is better suited to this task.  %@NL@%
  10699. %@NL@%
  10700. "Presentation graphics" is a set of high-level functions that displays
  10701. presentation-quality graphics. These functions transform numeric data into
  10702. pie charts, bar and column charts, line graphs, and scatter diagrams.  %@NL@%
  10703. %@NL@%
  10704. This chapter describes how to use presentation graphics.  %@NL@%
  10705. %@NL@%
  10706. %@NL@%
  10707. %@2@%%@CR:C6A00110002 @%%@AB@%11.1  Overview of Presentation Graphics%@AE@%%@EH@%%@NL@%
  10708. %@NL@%
  10709. The presentation graphics library PGCHART.LIB contains 22 functions. They
  10710. are listed in Table 11.1 for convenient reference.  %@NL@%
  10711. %@NL@%
  10712. %@AB@%Table 11.1  %@AB@%Presentation Graphics Function%@AE@%%@AE@%
  10713.  
  10714. %@TH:  11   968 02 20 22 34 @%Primary Functions   Secondary Functions%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_pg_chart%@AE@%           %@AB@%_pg_analyzechart%@AE@%      %@AB@%_pg_hlabelchart%@AE@%%@AB@%_pg_chartms%@AE@%         %@AB@%_pg_analyzechartms%@AE@%    %@AB@%_pg_resetpalette%@AE@%%@AB@%_pg_chartpie%@AE@%        %@AB@%_pg_analyzepie%@AE@%        %@AB@%_pg_resetstyleset%@AE@%%@AB@%_pg_chartscatter%@AE@%    %@AB@%_pg_analyzescatter%@AE@%    %@AB@%_pg_setchardef%@AE@%%@AB@%_pg_chartscatterms%@AE@%  %@AB@%_pg_analyzescatterms%@AE@%  %@AB@%_pg_setpalette%@AE@%%@AB@%_pg_defaultchart%@AE@%    %@AB@%_pg_getchardef%@AE@%        %@AB@%_pg_setstyleset%@AE@%%@AB@%_pg_initchart%@AE@%       %@AB@%_pg_getpalette%@AE@%        %@AB@%_pg_vlabelchart%@AE@%                    %@AB@%_pg_getstyleset%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  11   968 02 20 22 34 @%
  10715.  
  10716. %@AU@% The seven primary functions initialize variables and display selected chart
  10717. %@AU@%types.%@AE@%  %@NL@%
  10718. %@NL@%
  10719. In most cases, you will be using only seven "primary functions." These
  10720. functions initialize variables and display selected chart types. The 15
  10721. "secondary functions" of presentation graphics do not directly display
  10722. charts. Most of them retrieve or set data in the presentation graphics chart
  10723. environment.  %@NL@%
  10724. %@NL@%
  10725. Among the secondary functions are the "analysis functions," identified by
  10726. the prefix %@AB@%_pg_analyze%@AE@%. These five functions calculate default values that
  10727. pertain to a given chart type and data set. Calling an analysis function has
  10728. the same effect as calling a corresponding primary function, except that the
  10729. chart is not displayed. This allows you to pass on to the library the burden
  10730. of calculating values. You can then make modifications to the resulting
  10731. values and call a primary routine to display the chart.  %@NL@%
  10732. %@NL@%
  10733. Use the %@AB@%_pg_hlabelchart%@AE@% and %@AB@%_pg_vlabelchart%@AE@% functions to display text that
  10734. is not part of a title or axis label on your chart. These functions enable
  10735. you to attach notes or other messages to your chart.  %@NL@%
  10736. %@NL@%
  10737. %@NL@%
  10738. %@2@%%@CR:C6A00110003 @%%@AB@%11.2  Parts of a Graph%@AE@%%@EH@%%@NL@%
  10739. %@NL@%
  10740. This section describes the terms used to refer to the different kinds of
  10741. information that can be plotted. The various types of charts and graphs are
  10742. also defined.  %@NL@%
  10743. %@NL@%
  10744. %@NL@%
  10745. %@4@%%@AB@%Data Series%@AE@%%@EH@%%@NL@%
  10746. %@NL@%
  10747. Data that are related by a common idea or purpose constitute a "series." For
  10748. example, the prices of a futures commodity over the course of a year form a
  10749. single series of data. The volume forms a second data series.  %@NL@%
  10750. %@NL@%
  10751. When you include several series in one chart, characteristics such as color
  10752. and pattern can help distinguish one from another. You can more readily
  10753. differentiate series on a color monitor than you can on a monochrome
  10754. monitor. The number of series that can appear on the same chart depends on
  10755. the chart type and the number of available colors.  %@NL@%
  10756. %@NL@%
  10757. %@NL@%
  10758. %@4@%%@AB@%Categories%@AE@%%@EH@%%@NL@%
  10759. %@NL@%
  10760. "Categories" are nonnumeric data. A set of categories forms a frame of
  10761. reference for the comparison of numeric data. For example, the months of the
  10762. year are categories against which numeric data such as inches of rainfall
  10763. can be plotted.  %@NL@%
  10764. %@NL@%
  10765. Regional sales provide another example. A chart can compare a company's
  10766. sales in different parts of the country. Each region forms a category.  %@NL@%
  10767. %@NL@%
  10768. %@NL@%
  10769. %@4@%%@AB@%Values%@AE@%%@EH@%%@NL@%
  10770. %@NL@%
  10771. "Values" are numeric data. Sales, stock prices, air temperatures, and
  10772. populations are all series of values that can be plotted against categories
  10773. or against other values.  %@NL@%
  10774. %@NL@%
  10775. Presentation graphics allows you to overlay different series of value data
  10776. on a single graph. For example, average monthly temperatures or monthly
  10777. sales of heating oil during different years─or a combination of temperatures
  10778. and sales─can be plotted together on the same graph.  %@NL@%
  10779. %@NL@%
  10780. %@NL@%
  10781. %@4@%%@AB@%Pie Charts%@AE@%%@EH@%%@NL@%
  10782. %@NL@%
  10783. "Pie charts" are used to represent data by showing the relationship of each
  10784. part to the whole. A good example is a company's annual budget. A pie chart
  10785. allows you to view each area of revenue or spending by its relative size
  10786. within the context of the entire company budget.  %@NL@%
  10787. %@NL@%
  10788. Presentation graphics can display either a standard or an "exploded" pie
  10789. chart. The exploded view shows the pie with one or more pieces separated for
  10790. emphasis. You can label each slice of a pie chart with a percentage figure
  10791. if you wish.  %@NL@%
  10792. %@NL@%
  10793. %@NL@%
  10794. %@4@%%@AB@%Bar and Column Charts%@AE@%%@EH@%%@NL@%
  10795. %@NL@%
  10796. As the name implies, a "bar chart" shows data as horizontal bars. Bar charts
  10797. show comparisons among items rather than absolute value.  %@NL@%
  10798. %@NL@%
  10799. "Column charts" are vertical bar charts. Column charts are frequently used
  10800. to show variations over a period of time, since they suggest time flow
  10801. better than a bar chart.  %@NL@%
  10802. %@NL@%
  10803. %@NL@%
  10804. %@4@%%@AB@%Line Graphs%@AE@%%@EH@%%@NL@%
  10805. %@NL@%
  10806. "Line graphs" illustrate trends or changes in data. They show how a series
  10807. of values varies against a particular category─for example, average
  10808. temperatures throughout one year.  %@NL@%
  10809. %@NL@%
  10810. Traditionally, line graphs show a collection of data points connected by
  10811. lines. Presentation graphics can also plot points that are not connected by
  10812. lines.  %@NL@%
  10813. %@NL@%
  10814. %@NL@%
  10815. %@4@%%@AB@%Scatter Diagrams%@AE@%%@EH@%%@NL@%
  10816. %@NL@%
  10817. A "scatter diagram" is the only type of graph available in presentation
  10818. graphics that directly compares values with values. A scatter diagram simply
  10819. plots points.  %@NL@%
  10820. %@NL@%
  10821. Scatter diagrams illustrate the relationship between numeric values in
  10822. different groups of data. They graphically show trends and correlations not
  10823. easily detected from rows and columns of raw numbers.  %@NL@%
  10824. %@NL@%
  10825. Scatter diagrams are most useful with large amounts of data. Consider, for
  10826. example, the relationship between personal income and family size. If you
  10827. poll one thousand wage earners for their income and family size, you have a
  10828. scatter diagram with one thousand points. If you combine your results so
  10829. that you are left with one average income for each family size, you have a
  10830. line graph.  %@NL@%
  10831. %@NL@%
  10832. %@NL@%
  10833. %@4@%%@AB@%Axes%@AE@%%@EH@%%@NL@%
  10834. %@NL@%
  10835. All presentation graphics charts except pie charts are displayed with two
  10836. perpendicular reference axes. The vertical, or %@AI@%y%@AE@%, axis runs from top to
  10837. bottom of the chart and is placed against the left side of the screen. The
  10838. horizontal, or %@AI@%x%@AE@%, axis runs from left to right across the bottom of the
  10839. screen.  %@NL@%
  10840. %@NL@%
  10841. %@AU@% The chart type determines the axis used for category data and the axis for
  10842. %@AU@%value data.%@AE@%  %@NL@%
  10843. %@NL@%
  10844. The %@AI@%x%@AE@% axis is the category axis for column and line charts and the value
  10845. axis for bar charts. The %@AI@%y%@AE@% axis is the value axis for column and line charts
  10846. and the category axis for bar charts.  %@NL@%
  10847. %@NL@%
  10848. %@NL@%
  10849. %@4@%%@AB@%Chart Windows%@AE@%%@EH@%%@NL@%
  10850. %@NL@%
  10851. The "chart window" defines that part of the screen on which the chart is
  10852. drawn. By default, the window fills the entire screen, but presentation
  10853. graphics allows you to resize the window for smaller graphs. By redefining
  10854. the chart window to different screen locations, you can view separate graphs
  10855. together on the same screen.  %@NL@%
  10856. %@NL@%
  10857. %@NL@%
  10858. %@4@%%@AB@%Data Windows%@AE@%%@EH@%%@NL@%
  10859. %@NL@%
  10860. While the chart window defines the entire graph including axes and labels,
  10861. the "data window" defines only the actual plotting area. This is the portion
  10862. of the graph to the right of the %@AI@%y%@AE@% axis and above the %@AI@%x%@AE@% axis. You cannot
  10863. specify or adjust the size of the data window. Presentation graphics
  10864. automatically determines its size based on the dimensions of the chart
  10865. window.  %@NL@%
  10866. %@NL@%
  10867. %@NL@%
  10868. %@4@%%@AB@%Chart Styles%@AE@%%@EH@%%@NL@%
  10869. %@NL@%
  10870. Each of the five types of presentation graphics charts can appear in two
  10871. different "chart styles," as described in Table 11.2.  %@NL@%
  10872. %@NL@%
  10873. %@AB@%Table 11.2  %@AB@%Presentation Graphics Chart Styles%@AE@%%@AE@%
  10874.  
  10875. %@TH:   8   488 02 12 20 44 @%Chart Type  Chart Style #1      Chart Style #2%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Pie         With percentages    Without percentagesBar         Side-by-side        StackedColumn      Side-by-side        StackedLine        Points with lines   Points onlyScatter     Points with lines   Points only%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   8   488 02 12 20 44 @%
  10876.  
  10877. Bar and column charts have only one style when displaying a single series of
  10878. data. The styles "side-by-side" and "stacked" are applicable when more than
  10879. one series appears on the same chart. The first style arranges the bars or
  10880. columns for the different series side by side, showing relative heights or
  10881. lengths. The stacked style, illustrated for a column chart in Figure 11.3,
  10882. emphasizes relative sizes between bars or columns.  %@NL@%
  10883. %@NL@%
  10884. %@NL@%
  10885. %@4@%%@AB@%Legends%@AE@%%@EH@%%@NL@%
  10886. %@NL@%
  10887. %@AU@% Legends help identify  individual data series.%@AE@%  %@NL@%
  10888. %@NL@%
  10889. When displaying more than one data series on a chart, presentation graphics
  10890. uses different colors, line styles, or patterns to differentiate them.
  10891. Presentation graphics also can display a "legend" that labels the different
  10892. series of a chart. For a pie chart, the legend labels individual slices of
  10893. the pie.  %@NL@%
  10894. %@NL@%
  10895. A sample of the color and pattern used to graph the series appears next to
  10896. the series label. This identifies the set of data to which the labels
  10897. belong.  %@NL@%
  10898. %@NL@%
  10899. You may change the font displayed by calling the %@AB@%_registerfonts%@AE@% and %@AB@%_setfont%@AE@%
  10900. functions (see Section 10.5 for more information about using fonts). If you
  10901. don't select a font, presentation graphics defaults to an internal font.  %@NL@%
  10902. %@NL@%
  10903. %@NL@%
  10904. %@2@%%@CR:C6A00110004 @%%@AB@%11.3  Writing a Presentation Graphics Program%@AE@%%@EH@%%@NL@%
  10905. %@NL@%
  10906. To write a C program that uses presentation graphics, follow these steps:  %@NL@%
  10907. %@NL@%
  10908. %@NL@%
  10909.   1.  Include the required header files, GRAPH.H and PGCHART.H, as well as
  10910.       any other header files your program may need.%@NL@%
  10911. %@NL@%
  10912.   2.  Set the video mode to a graphics mode. See Chapter 10, "Communicating
  10913.       with Graphics," for a description of video modes.%@NL@%
  10914. %@NL@%
  10915.   3.  Initialize the presentation graphics chart environment. Presentation
  10916.       graphics places charting parameters in data structures. The amount of
  10917.       initialization that must be done by your program depends on how
  10918.       extensively it relies on the defaults.%@NL@%
  10919. %@NL@%
  10920.   4.  Assemble the plot data. Data can be collected in a variety of ways: by
  10921.       calculating it elsewhere in the program, reading it from files, or
  10922.       entering it from the keyboard. All plot data must be assembled in
  10923.       arrays because the presentation graphics functions locate them through
  10924.       pointers.%@NL@%
  10925. %@NL@%
  10926.   5.  Call presentation graphics functions to display the chart. Pause while
  10927.       the chart is on the screen.%@NL@%
  10928. %@NL@%
  10929.   6.  Reset the video mode. When your program detects the signal to
  10930.       continue, it should reset the video to its original (default) mode.%@NL@%
  10931. %@NL@%
  10932. %@NL@%
  10933. After compiling the program, link it to the library modules PGCHART.LIB and
  10934. GRAPHICS.LIB.  %@NL@%
  10935. %@NL@%
  10936. The sample programs in Sections 11.3.1-11.3.3 use 5 of the 22 presentation
  10937. graphics functions: %@AB@%_pg_initchart%@AE@%, %@AB@%_pg_defaultchart%@AE@%, %@AB@%_pg_chartpie%@AE@%,
  10938. %@AB@%_pg_chart%@AE@%, and %@AB@%_pg_chartscatter%@AE@%. Each program is commented so that you can
  10939. recognize the steps given in this section.  %@NL@%
  10940. %@NL@%
  10941. %@NL@%
  10942. %@3@%%@CR:C6A00110005 @%%@AB@%11.3.1  Pie Chart%@AE@%%@EH@%%@NL@%
  10943. %@NL@%
  10944. The following program uses presentation graphics to display a pie chart for
  10945. monthly sales of orange juice over a year. The chart, which is shown in
  10946. Figure 11.1, remains on the screen until a key is pressed.  %@NL@%
  10947. %@NL@%
  10948. %@AS@%  /* PIE.C:  Create sample pie chart.  */
  10949. %@AS@%  
  10950. %@AS@%  #include <conio.h>
  10951. %@AS@%  #include <string.h>
  10952. %@AS@%  #include <graph.h>
  10953. %@AS@%  #include <pgchart.h>
  10954. %@AS@%  
  10955. %@AS@%  #define MONTHS 12
  10956. %@AS@%  
  10957. %@AS@%  typedef enum {FALSE, TRUE} boolean;
  10958. %@AS@%  
  10959. %@AS@%  float far value[MONTHS] = 
  10960. %@AS@%  {
  10961. %@AS@%      33.0, 27.0, 42.0, 64.0,106.0,157.0,
  10962. %@AS@%     182.0,217.0,128.0, 62.0, 43.0, 36.0
  10963. %@AS@%  };
  10964. %@AS@%  char far *category[MONTHS] = 
  10965. %@AS@%  {
  10966. %@AS@%     "Jan", "Feb", "Mar", "Apr",
  10967. %@AS@%     "May", "Jun", "Jly", "Aug",
  10968. %@AS@%     "Sep", "Oct", "Nov", "Dec"
  10969. %@AS@%  };
  10970. %@AS@%  short far explode[MONTHS] = {0};%@AE@%%@NL@%
  10971. %@NL@%
  10972. %@AS@%  main()
  10973. %@AS@%  {
  10974. %@AS@%     chartenv env;
  10975. %@AS@%     int mode = _VRES16COLOR;%@AE@%%@NL@%
  10976. %@NL@%
  10977. %@AS@%  /* Set highest video mode available */
  10978. %@AS@%  
  10979. %@AS@%     if( _setvideomode( _MAXRESMODE ) == 0 )
  10980. %@AS@%        exit( 0 );
  10981. %@AS@%  
  10982. %@AS@%     /* Initialize chart library and a default pie chart */
  10983. %@AS@%  
  10984. %@AS@%     _pg_initchart();
  10985. %@AS@%     _pg_defaultchart( &env, _PG_PIECHART, _PG_PERCENT );
  10986. %@AS@%  
  10987. %@AS@%     /* Add titles and some chart options */
  10988. %@AS@%  
  10989. %@AS@%     strcpy( env.maintitle.title, "Good Neighbor Grocery" );
  10990. %@AS@%     env.maintitle.titlecolor = 6;
  10991. %@AS@%     env.maintitle.justify = _PG_RIGHT;
  10992. %@AS@%     strcpy( env.subtitle.title, "Orange Juice Sales" ); 
  10993. %@AS@%     env.subtitle.titlecolor = 6;
  10994. %@AS@%     env.subtitle.justify = _PG_RIGHT;
  10995. %@AS@%     env.chartwindow.border = FALSE;
  10996. %@AS@%  
  10997. %@AS@%     /* Parameters for call to _pg_chartpie are:
  10998. %@AS@%      *  
  10999. %@AS@%      *    env        - Environment variable
  11000. %@AS@%      *    category   - Category labels
  11001. %@AS@%      *    value      - Data to chart
  11002. %@AS@%      *    explode    - Separated pieces
  11003. %@AS@%      *    MONTHS     - Number of data values
  11004. %@AS@%      */
  11005. %@AS@%     if( _pg_chartpie( &env, category, value,
  11006. %@AS@%                       explode, MONTHS ) )
  11007. %@AS@%     {
  11008. %@AS@%        _setvideomode( _DEFAULTMODE );
  11009. %@AS@%        _outtext( "Error:  can't draw chart" );
  11010. %@AS@%     }
  11011. %@AS@%     else
  11012. %@AS@%     {
  11013. %@AS@%        getch(); 
  11014. %@AS@%        _setvideomode( _DEFAULTMODE );
  11015. %@AS@%     }
  11016. %@AS@%     return( 0 );
  11017. %@AS@%  }%@AE@%%@NL@%
  11018. %@NL@%
  11019. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  11020. %@NL@%
  11021. %@NL@%
  11022. %@3@%%@CR:C6A00110006 @%%@AB@%11.3.2  Bar, Column, and Line Charts%@AE@%%@EH@%%@NL@%
  11023. %@NL@%
  11024. The code for the PIE.C program needs only minor alterations to produce bar,
  11025. column, and line charts for the same data:  %@NL@%
  11026. %@NL@%
  11027. %@NL@%
  11028.   ■   Replace the call to %@AB@%_pg_chartpie%@AE@% with %@AB@%_pg_chart%@AE@%. This function
  11029.       produces bar, column, and line charts depending on the value of the
  11030.       second argument for %@AB@%_pg_defaultchart%@AE@%.%@NL@%
  11031. %@NL@%
  11032.   ■   Give new arguments to %@AB@%_pg_defaultchart%@AE@% that specify chart type and
  11033.       style.%@NL@%
  11034. %@NL@%
  11035.   ■   Assign titles for the %@AI@%x%@AE@% axis and %@AI@%y%@AE@% axis in the structure %@AS@% env%@AE@%.%@NL@%
  11036. %@NL@%
  11037.   ■   Remove references to array %@AS@% explode%@AE@%, which is applicable only to pie
  11038.       charts. %@AS@% %@AE@%%@NL@%
  11039. %@NL@%
  11040. %@NL@%
  11041. The following example produces a bar chart for the store owner's data. The
  11042. result is shown in Figure 11.2.  %@NL@%
  11043. %@NL@%
  11044. %@AS@%  /* BAR.C:  Create sample bar chart. */
  11045. %@AS@%  
  11046. %@AS@%  #include <conio.h>
  11047. %@AS@%  #include <string.h>
  11048. %@AS@%  #include <graph.h>
  11049. %@AS@%  #include <pgchart.h>
  11050. %@AS@%  
  11051. %@AS@%  #define MONTHS 12
  11052. %@AS@%  
  11053. %@AS@%  typedef enum {FALSE, TRUE} boolean;
  11054. %@AS@%  
  11055. %@AS@%  float far value[MONTHS] = 
  11056. %@AS@%  { 
  11057. %@AS@%      33.0, 27.0, 42.0, 64.0,106.0,157.0,
  11058. %@AS@%     182.0,217.0,128.0, 62.0, 43.0, 36.0
  11059. %@AS@%  };
  11060. %@AS@%  char far *category[MONTHS] =
  11061. %@AS@%  {
  11062. %@AS@%     "Jan", "Feb", "Mar", "Apr",
  11063. %@AS@%     "May", "Jun", "Jly", "Aug",
  11064. %@AS@%     "Sep", "Oct", "Nov", "Dec"
  11065. %@AS@%  };
  11066. %@AS@%  
  11067. %@AS@%  main()
  11068. %@AS@%  {
  11069. %@AS@%     chartenv env;
  11070. %@AS@%     int mode = _VRES16COLOR;
  11071. %@AS@%  
  11072. %@AS@%     /* Set highest video mode available */
  11073. %@AS@%  
  11074. %@AS@%     if( _setvideomode( _MAXRESMODE ) == 0 )
  11075. %@AS@%        exit( 0 );
  11076. %@AS@%  
  11077. %@AS@%     /* Initialize chart library and a default bar chart */ 
  11078. %@AS@%     _pg_initchart();
  11079. %@AS@%     _pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS );
  11080. %@AS@%  
  11081. %@AS@%     /* Add titles and some chart options */
  11082. %@AS@%  
  11083. %@AS@%     strcpy( env.maintitle.title, "Good Neighbor Grocery" );
  11084. %@AS@%     env.maintitle.titlecolor = 6;
  11085. %@AS@%     env.maintitle.justify = _PG_RIGHT;
  11086. %@AS@%     strcpy( env.subtitle.title, "Orange Juice Sales" );
  11087. %@AS@%     env.subtitle.titlecolor = 6;
  11088. %@AS@%     env.subtitle.justify = _PG_RIGHT;
  11089. %@AS@%     strcpy( env.yaxis.axistitle.title, "Months" );
  11090. %@AS@%     strcpy( env.xaxis.axistitle.title, "Quantity (cases)" );
  11091. %@AS@%     env.chartwindow.border = FALSE;%@AE@%%@NL@%
  11092. %@NL@%
  11093. %@AS@%  /* Parameters for call to _pg_chart are:
  11094. %@AS@%      *    env        - Environment variable
  11095. %@AS@%      *    category   - Category labels
  11096. %@AS@%      *    value      - Data to chart
  11097. %@AS@%      *    MONTHS     - Number of data values
  11098. %@AS@%      */
  11099. %@AS@%     if( _pg_chart( &env, category, value, MONTHS ) )
  11100. %@AS@%     {
  11101. %@AS@%        _setvideomode( _DEFAULTMODE );
  11102. %@AS@%        _outtext( "Error:  can't draw chart" );
  11103. %@AS@%     }
  11104. %@AS@%     else
  11105. %@AS@%     {
  11106. %@AS@%        getch(); 
  11107. %@AS@%        _setvideomode( _DEFAULTMODE );
  11108. %@AS@%     }
  11109. %@AS@%     return( 0 );
  11110. %@AS@%  }%@AE@%%@NL@%
  11111. %@NL@%
  11112. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  11113. %@NL@%
  11114. The grocer's bar chart becomes a column chart in two easy steps. Simply
  11115. specify the new chart type when calling %@AB@%_pg_defaultchart%@AE@% and change the axis
  11116. titles. To produce a column chart for the grocer's data, replace the call to
  11117. %@AB@%_pg_defaultchart%@AE@% with  %@NL@%
  11118. %@NL@%
  11119. %@AS@%  _pg_defaultchart( &env, _PG_COLUMNCHART, _PG_PLAINBARS );%@AE@%%@NL@%
  11120. %@NL@%
  11121. Replace the last two calls to %@AB@%strcpy%@AE@% with  %@NL@%
  11122. %@NL@%
  11123. %@AS@%  strcpy( env.xaxis.axistitle.title, "Months" );
  11124. %@AS@%  strcpy( env.yaxis.axistitle.title, "Quantity (cases)" );%@AE@%%@NL@%
  11125. %@NL@%
  11126. Note that now the %@AI@%x%@AE@% axis is labeled "Months" and the %@AI@%y %@AE@%axis is labeled
  11127. "Quantity (cases)." Figure 11.3 shows the resulting column chart.  %@NL@%
  11128. %@NL@%
  11129. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  11130. %@NL@%
  11131. Creating an equivalent line chart requires only one change. Use the same
  11132. code as for the column chart and replace the call to %@AB@%_pg_defaultchart%@AE@% with  %@NL@%
  11133. %@NL@%
  11134. %@AS@%  _pg_defaultchart( &env, _PG_LINECHART, _PG_POINTANDLINE );%@AE@%%@NL@%
  11135. %@NL@%
  11136. Figure 11.4 shows the line chart for the grocer's data.%@NL@%
  11137. %@NL@%
  11138. %@AU@%(Please refer to the printed book.)%@AE@%%@NL@%
  11139. %@NL@%
  11140. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  11141. %@NL@%
  11142. %@NL@%
  11143. %@3@%%@CR:C6A00110007 @%%@AB@%11.3.3  Scatter Diagram%@AE@%%@EH@%%@NL@%
  11144. %@NL@%
  11145. The program SCATTER.C displays a scatter diagram that illustrates the
  11146. relationship between the sales of orange juice and hot chocolate throughout
  11147. a 12-month period. Figure 11.5 shows the results of SCATTER.C. Notice that
  11148. the scatter points form a slightly curved line, indicating that a
  11149. correlation exists between the sales of the two products. The demand for
  11150. orange juice is roughly inverse to the demand for hot chocolate.  %@NL@%
  11151. %@NL@%
  11152. %@AS@%  /* SCATTER.C:  Create sample scatter diagram. */
  11153. %@AS@%  
  11154. %@AS@%  #include <conio.h>
  11155. %@AS@%  #include <string.h>
  11156. %@AS@%  #include <graph.h>
  11157. %@AS@%  #include <pgchart.h>
  11158. %@AS@%  
  11159. %@AS@%  #define MONTHS 12
  11160. %@AS@%  
  11161. %@AS@%  typedef enum {FALSE, TRUE} boolean;%@AE@%%@NL@%
  11162. %@NL@%
  11163. %@AS@%  /* Orange juice sales */
  11164. %@AS@%  
  11165. %@AS@%  float far xvalue[MONTHS] = 
  11166. %@AS@%  { 
  11167. %@AS@%      33.0, 27.0, 42.0, 64.0,106.0,157.0,
  11168. %@AS@%     182.0,217.0,128.0, 62.0, 43.0, 36.0
  11169. %@AS@%  };
  11170. %@AS@%  
  11171. %@AS@%  /* Hot chocolate sales */
  11172. %@AS@%  
  11173. %@AS@%  float far yvalue[MONTHS] = 
  11174. %@AS@%  { 
  11175. %@AS@%     37.0, 37.0, 30.0, 19.0, 10.0,  5.0,
  11176. %@AS@%      2.0,  1.0,  7.0, 15.0, 28.0, 39.0
  11177. %@AS@%  };
  11178. %@AS@%  
  11179. %@AS@%  main()
  11180. %@AS@%  {
  11181. %@AS@%     chartenv env;
  11182. %@AS@%     int mode = _VRES16COLOR;
  11183. %@AS@%  
  11184. %@AS@%     /* Set highest video mode available */
  11185. %@AS@%  
  11186. %@AS@%     if( _setvideomode( _MAXRESMODE ) == 0 )
  11187. %@AS@%        exit( 0 );
  11188. %@AS@%     /* Initialize chart library and default
  11189. %@AS@%      * scatter diagram
  11190. %@AS@%      */
  11191. %@AS@%     _pg_initchart();
  11192. %@AS@%     _pg_defaultchart( &env, _PG_SCATTERCHART,
  11193. %@AS@%                       _PG_POINTONLY );
  11194. %@AS@%  
  11195. %@AS@%     /* Add titles and some chart options */
  11196. %@AS@%  
  11197. %@AS@%     strcpy( env.maintitle.title, "Good Neighbor Grocery" );
  11198. %@AS@%     env.maintitle.titlecolor = 6;
  11199. %@AS@%     env.maintitle.justify = _PG_RIGHT;
  11200. %@AS@%     strcpy( env.subtitle.title,
  11201. %@AS@%             "Orange Juice vs Hot Chocolate" );
  11202. %@AS@%     env.subtitle.titlecolor = 6;
  11203. %@AS@%     env.subtitle.justify = _PG_RIGHT;
  11204. %@AS@%     env.yaxis.grid = TRUE;
  11205. %@AS@%     strcpy( env.xaxis.axistitle.title,
  11206. %@AS@%             "Orange Juice Sales" );
  11207. %@AS@%     strcpy( env.yaxis.axistitle.title,
  11208. %@AS@%             "Hot Chocolate Sales" );
  11209. %@AS@%     env.chartwindow.border = FALSE;%@AE@%%@NL@%
  11210. %@NL@%
  11211. %@AS@%  /* Parameters for call to _pg_chartscatter are:
  11212. %@AS@%      *    env        - Environment variable
  11213. %@AS@%      *    xvalue     - X-axis data
  11214. %@AS@%      *    yvalue     - Y-axis data
  11215. %@AS@%      *    MONTHS     - Number of data values
  11216. %@AS@%      */
  11217. %@AS@%     if( _pg_chartscatter( &env, xvalue,
  11218. %@AS@%                           yvalue, MONTHS ) )
  11219. %@AS@%     {
  11220. %@AS@%        _setvideomode( _DEFAULTMODE );
  11221. %@AS@%        _outtext( "Error:  can't draw chart" );
  11222. %@AS@%     }
  11223. %@AS@%     else
  11224. %@AS@%     {
  11225. %@AS@%        getch(); 
  11226. %@AS@%        _setvideomode( _DEFAULTMODE );
  11227. %@AS@%     }
  11228. %@AS@%     return( 0 );
  11229. %@AS@%  } %@AE@%%@NL@%
  11230. %@NL@%
  11231. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  11232. %@NL@%
  11233. %@NL@%
  11234. %@2@%%@CR:C6A00110008 @%%@AB@%11.4  Manipulating Colors and Patterns%@AE@%%@EH@%%@NL@%
  11235. %@NL@%
  11236. Presentation graphics displays each data series in a way that makes it
  11237. discernible from other series. It does this by defining a separate "palette"
  11238. for every data series in a chart. Palettes consist of entries that determine
  11239. color, line style, fill pattern, and point character used to graph the
  11240. series.  %@NL@%
  11241. %@NL@%
  11242. Presentation graphics maintains its palettes as an array of structures. The
  11243. header file PGCHART.H defines the palette structures as shown below:  %@NL@%
  11244. %@NL@%
  11245. %@AS@%  /* Typedef for pattern bitmap */
  11246. %@AS@%  typedef unsigned char fillmap[8];
  11247. %@AS@%  
  11248. %@AS@%  /* Typedef for palette entry definition */
  11249. %@AS@%  typedef struct 
  11250. %@AS@%  {
  11251. %@AS@%     unsigned short color;
  11252. %@AS@%     unsigned short style;
  11253. %@AS@%     fillmap        fill;
  11254. %@AS@%     char           plotchar;
  11255. %@AS@%  } paletteentry;
  11256. %@AS@%  
  11257. %@AS@%  /* Typedef for palette definition */
  11258. %@AS@%  typedef paletteentry palettetype[_PG_PALETTELEN];%@AE@%%@NL@%
  11259. %@NL@%
  11260. Do not confuse the presentation graphics palettes with the adapter display
  11261. palettes, which are register values kept by the video controller. The
  11262. function %@AB@%_selectpalette%@AE@% described in Chapter 10, "Communicating with
  11263. Graphics," sets the display palette. It does not define the data series
  11264. palettes used by presentation graphics.  %@NL@%
  11265. %@NL@%
  11266. %@NL@%
  11267. %@3@%%@CR:C6A00110009 @%%@AB@%11.4.1  Color Pool%@AE@%%@EH@%%@NL@%
  11268. %@NL@%
  11269. %@AU@% The color pool determines the  colors of graphic elements (axes, labels,
  11270. %@AU@%legends, titles).%@AE@%  %@NL@%
  11271. %@NL@%
  11272. Presentation graphics organizes all chart colors into a "color pool." The
  11273. color pool holds the color index values valid for the current graphics mode.
  11274. (Refer to Chapter 10, "Communicating with Graphics," for more information
  11275. about the color index.) Palette structures contain color codes that refer to
  11276. the color pool. A palette's color index determines the colors used to graph
  11277. the data series associated with the palette. The colors of labels, titles,
  11278. legends, and axes are determined by the contents of the color pool.  %@NL@%
  11279. %@NL@%
  11280. The first element of the color pool is always 0, which is the color index
  11281. for the screen background color. The second element is always the highest
  11282. color index available for the graphics mode. The remaining elements repeat
  11283. the sequences of available pixel values, beginning with 1.  %@NL@%
  11284. %@NL@%
  11285. As shown in the example in Section 11.4, the first member of a palette data
  11286. structure is  %@NL@%
  11287. %@NL@%
  11288. %@AS@%  unsigned short color;%@AE@%%@NL@%
  11289. %@NL@%
  11290. This member defines the color index for the data series associated with the
  11291. palette.  %@NL@%
  11292. %@NL@%
  11293. An example should make this clearer. A graphics mode of %@AB@%_MRES4COLOR%@AE@% (320 by
  11294. 200 pixels) provides four colors for display. Color index values from 0 to 3
  11295. determine the possible colors─say, black, green, red, and brown,
  11296. respectively. The first eight elements of this color pool are shown below.  %@NL@%
  11297. %@NL@%
  11298. %@TH:  11   550 02 18 13 45 @%Color Pool Index  Color Index  Color%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%0                 0            Black1                 3            Brown2                 1            Green3                 2            Red4                 3            Brown5                 1            Green6                 2            Red7                 3            Brown%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  11   550 02 18 13 45 @%
  11299.  
  11300. Notice that the sequence of available foreground colors repeats from the
  11301. third element. The first data series in this case would be plotted in brown,
  11302. the second series in green, the third series in red, the fourth series again
  11303. in brown, and so forth.  %@NL@%
  11304. %@NL@%
  11305. Video adapters such as the EGA or the Hercules(R) InColor(tm) Card allow 16
  11306. on-screen colors. This allows presentation graphics to graph more series
  11307. without duplicating colors.  %@NL@%
  11308. %@NL@%
  11309. %@NL@%
  11310. %@3@%%@CR:C6A00110010 @%%@AB@%11.4.2  Style Pool%@AE@%%@EH@%%@NL@%
  11311. %@NL@%
  11312. Presentation graphics matches the color pool with a collection of different
  11313. line styles called the "style pool." Entries in the style pool define the
  11314. appearance of lines such as axes and grids. Lines can be solid, dotted,
  11315. dashed, or some combination of styles.  %@NL@%
  11316. %@NL@%
  11317. The second member of a palette structure defines a style code as  %@NL@%
  11318. %@NL@%
  11319. %@AS@%  unsigned short style;%@AE@%%@NL@%
  11320. %@NL@%
  11321. Each palette contains a style code that refers to an entry in the style pool
  11322. in the same way that it contains a color code that refers to an entry in the
  11323. color pool. The style code value in a palette is applicable only to line
  11324. graphs and lined scatter diagrams. The style code determines the appearance
  11325. of the lines drawn between points.  %@NL@%
  11326. %@NL@%
  11327. %@AU@% Use the different line styles in the style pool to differentiate series.%@AE@%  %@NL@%
  11328. %@NL@%
  11329. The palette's style code adds further variety to the lines of a multiseries
  11330. graph. It is most useful when the number of lines in a chart exceeds the
  11331. number of available colors. For example, a graph of nine different data
  11332. series must repeat colors if only three foreground colors are available for
  11333. the display. However, the style code for each color repetition will be
  11334. different, ensuring that none of the lines looks the same.  %@NL@%
  11335. %@NL@%
  11336. %@NL@%
  11337. %@3@%%@CR:C6A00110011 @%%@AB@%11.4.3  Pattern Pool%@AE@%%@EH@%%@NL@%
  11338. %@NL@%
  11339. Presentation graphics also maintains a pool of "fill patterns" that
  11340. determine the fill design for column, bar, and pie charts. The third member
  11341. of the palette structure holds the fill pattern. The pattern member is an
  11342. array:%@CR:C6A00110012 @%  %@NL@%
  11343. %@NL@%
  11344. %@AS@%  fillmap fill;%@AE@%%@NL@%
  11345. %@NL@%
  11346. where %@AS@% fillmap %@AE@% is type-defined as  %@NL@%
  11347. %@NL@%
  11348. %@AS@%  typedef unsigned char fillmap[8];%@AE@%%@NL@%
  11349. %@NL@%
  11350. Each fill pattern array holds an 8-by-8 bit map that defines the fill
  11351. pattern for the data series associated with the palette. Table 11.3 shows
  11352. how a fill pattern of diagonal stripes is created with the %@AS@% fill %@AE@% pattern
  11353. array.  %@NL@%
  11354. %@NL@%
  11355. The bit map in Table 11.3 corresponds to screen pixels. Each of the eight
  11356. layers of the map is a binary number, where a solid circle signifies 1 and
  11357. an open circle signifies 0. Thus the first layer of the map─that is, the
  11358. first byte─represents the binary number 10011001, which is the decimal
  11359. number 153.  %@NL@%
  11360. %@NL@%
  11361. %@AB@%Table   %@AB@%11.3 Fill Patterns%@AE@%%@AE@%
  11362.  
  11363. %@TH:  11   766 02 36 40 @%Bit Map                             Value in Fill%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%  ∙  ∙      ∙  ∙                %@AS@%fill[0]%@AE@% = 153    ∙  ∙      ∙  ∙              %@AS@%fill[1]%@AE@% = 204∙      ∙  ∙      ∙              %@AS@%fill[2]%@AE@% = 102∙  ∙      ∙  ∙                  %@AS@%fill[3]%@AE@% =   51  ∙  ∙      ∙  ∙                %@AS@%fill[4]%@AE@% = 153    ∙  ∙      ∙  ∙              %@AS@%fill[5]%@AE@% = 204∙      ∙  ∙      ∙              %@AS@%fill[6]%@AE@% = 102∙  ∙      ∙  ∙                  %@AS@%fill[7]%@AE@% =   51%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  11   766 02 36 40 @%
  11364.  
  11365. For example, if you want to create the pattern in Table 11.3 for your
  11366. chart's first data series, you must reset the %@AS@% fill%@AE@%%@AB@% %@AE@%array for the first
  11367. palette structure. You can do this in five steps:%@CR:C6A00110013 @%  %@NL@%
  11368. %@NL@%
  11369. %@NL@%
  11370.   1.  Declare a structure of type %@AB@%palettetype%@AE@% to hold the palette
  11371.       parameters.%@NL@%
  11372. %@NL@%
  11373.   2.  Call %@AB@%_pg_initchart%@AE@% to initialize the palettes with default values.%@NL@%
  11374. %@NL@%
  11375.   3.  Call the presentation graphics function %@AB@%_pg_getpalette%@AE@% to retrieve a
  11376.       copy of the current palette data.%@NL@%
  11377. %@NL@%
  11378.   4.  Assign the values given in Table 11.3 to the array %@AS@% fill %@AE@% for the
  11379.       first palette.%@NL@%
  11380. %@NL@%
  11381.   5.  Call the presentation graphics function %@AB@%_pg_setpalette%@AE@% to load the
  11382.       modified palette values.%@NL@%
  11383. %@NL@%
  11384. %@NL@%
  11385. The following lines of code demonstrate these five steps:  %@NL@%
  11386. %@NL@%
  11387. %@AS@%  /* Declare a structure array for palette data. */
  11388. %@AS@%  
  11389. %@AS@%  palettetype palette_struct;
  11390. %@AS@%  .
  11391. %@AS@%  .
  11392. %@AS@%  .
  11393. %@AS@%  /* Initialize chart library */
  11394. %@AS@%  
  11395. %@AS@%  _pg_initchart();
  11396. %@AS@%  .
  11397. %@AS@%  .
  11398. %@AS@%  .
  11399. %@AS@%  /* Copy current palette data into palette_struct */
  11400. %@AS@%  
  11401. %@AS@%  _pg_getpalette( palette_struct );
  11402. %@AS@%  
  11403. %@AS@%  /* Reinitialize fill pattern for first palette using
  11404. %@AS@%     values in Table .3 */
  11405. %@AS@%  
  11406. %@AS@%  palette_struct[1].fill[0] = 153;
  11407. %@AS@%  palette_struct[1].fill[1] = 204;
  11408. %@AS@%  palette_struct[1].fill[2] = 102;
  11409. %@AS@%  palette_struct[1].fill[3] =  51;
  11410. %@AS@%  palette_struct[1].fill[4] = 153;
  11411. %@AS@%  palette_struct[1].fill[5] = 204;
  11412. %@AS@%  palette_struct[1].fill[6] = 102;
  11413. %@AS@%  palette_struct[1].fill[7] =  51;
  11414. %@AS@%  
  11415. %@AS@%  /* Load new palette data */
  11416. %@AS@%  
  11417. %@AS@%  _pg_setpalette( palette_struct );%@AE@%%@NL@%
  11418. %@NL@%
  11419. Now when you display your bar or column chart, the first series appears
  11420. filled with the striped pattern shown in Table 11.3.  %@NL@%
  11421. %@NL@%
  11422. Palette structures are used differently with pie charts. Instead of
  11423. clarifying multiple series, fill patterns, line styles, and colors, palette
  11424. structures are used to distinguish individual slices in a pie chart.
  11425. Palettes are recycled if the number of slices exceeds %@AB@%_PG_PALETTELEN%@AE@%. Thus,
  11426. the first palette dictates not only the appearance of the first slice, but
  11427. of slice number %@AB@%_PG_PALETTELEN%@AE@% as well. The second palette determines the
  11428. appearance of both the second slice and of slice number %@AB@%_PG_PALETTELEN%@AE@% + 1,
  11429. and so forth.%@CR:C6A00110014 @%  %@NL@%
  11430. %@NL@%
  11431. %@NL@%
  11432. %@3@%%@CR:C6A00110015 @%%@AB@%11.4.4  Character Pool%@AE@%%@EH@%%@NL@%
  11433. %@NL@%
  11434. The last member of a palette structure is an index number in a pool of ASCII
  11435. characters:  %@NL@%
  11436. %@NL@%
  11437. %@AS@%  char plotchar;%@AE@%%@NL@%
  11438. %@NL@%
  11439. The member %@AB@%plotchar%@AE@% represents plot points on line graphs and scatter
  11440. diagrams. Each palette uses a different character to distinguish plot points
  11441. between data series.  %@NL@%
  11442. %@NL@%
  11443. %@NL@%
  11444. %@2@%%@CR:C6A00110016 @%%@AB@%11.5  Customizing the Chart Environment%@AE@%%@EH@%%@NL@%
  11445. %@NL@%
  11446. The presentation graphics functions are designed to be flexible. You can use
  11447. the system of default values to produce professional-looking charts with a
  11448. minimum of programming effort. Or you can fine-tune the appearance of your
  11449. charts by overriding default values and initializing variables explicitly in
  11450. your program.  %@NL@%
  11451. %@NL@%
  11452. The header file PGCHART.H defines a structure type %@AB@%chartenv%@AE@%, which organizes
  11453. the chart environment variables. The chart environment describes everything
  11454. about a chart except the plots themselves. It is the blank page, in other
  11455. words, ready for plotting data. The environment determines the appearance of
  11456. text, axes, grid lines, and legends.  %@NL@%
  11457. %@NL@%
  11458. Colors and line styles in the chart environment are taken from palettes. In
  11459. this way, the appearance of titles and axis lines matches the colors and
  11460. line styles of plotted data series.  %@NL@%
  11461. %@NL@%
  11462. %@AU@% You can reset any variable in the environment.%@AE@%  %@NL@%
  11463. %@NL@%
  11464. Calling the %@AB@%_pg_defaultchart%@AE@% function fills the chart environment with
  11465. default values. Presentation graphics allows you to reset any variable in
  11466. the environment before displaying a chart. Except for adjusting the palette
  11467. values, all initialization of data is done through a %@AB@%chartenv%@AE@% type
  11468. structure.  %@NL@%
  11469. %@NL@%
  11470. The sample chart programs provided in Section 11.3, "Writing a Presentation
  11471. Graphics Program," illustrate how to adjust variables in the chart
  11472. environment. These programs create a structure %@AS@% env %@AE@% of type %@AB@%chartenv%@AE@%. The
  11473. structure %@AS@% env %@AE@% contains the chart environment variables, initialized by the
  11474. call to the %@AB@%_pg_defaultchart%@AE@% function. Environment variables such as the
  11475. chart title are then given specific values, as in  %@NL@%
  11476. %@NL@%
  11477. %@AS@%  strcpy( env.maintitle.title, "Good Neighbor Grocery" );%@AE@%%@NL@%
  11478. %@NL@%
  11479. Environment variables that determine colors and line styles deserve special
  11480. mention. The chart environment holds several such variables, which can be
  11481. recognized by their names. For example, the variable %@AB@%titlecolor%@AE@% specifies
  11482. the color of title text. Similarly, the variable %@AB@%gridstyle%@AE@% specifies the
  11483. line style used to draw the chart grid.  %@NL@%
  11484. %@NL@%
  11485. These variables are index numbers, but do not refer directly to the color
  11486. pool or line pool. They correspond instead to palette numbers. If you set
  11487. %@AB@%titlecolor%@AE@% to 2, presentation graphics uses the color code in the second
  11488. palette to determine the title's color. Thus, the title in this case would
  11489. be the same color as the chart's second data series. If you change the color
  11490. code in the palette, you'll also change the title's color.  %@NL@%
  11491. %@NL@%
  11492. A structure of type %@AB@%chartenv%@AE@% consists of four types of secondary structures.
  11493. The file PGCHART.H type-defines these secondary structures: %@AB@%titletype%@AE@%,
  11494. %@AB@%axistype%@AE@%, %@AB@%windowtype%@AE@%, and %@AB@%legendtype%@AE@%.  %@NL@%
  11495. %@NL@%
  11496. The remainder of this section describes the chart environment of
  11497. presentation graphics. It first examines structures of the four secondary
  11498. structures that make up the chart environment structure. The section
  11499. concludes with a description of the %@AB@%chartenv%@AE@% structure type. Each section
  11500. begins with a brief explanation of the structure's purpose, followed by a
  11501. listing of the structure type definition as it appears in the PGCHART.H
  11502. file. All symbolic constants are defined in the file PGCHART.H.  %@NL@%
  11503. %@NL@%
  11504. %@NL@%
  11505. %@3@%%@CR:C6A00110017 @%%@AB@%11.5.1  titletype Structures%@AE@%%@EH@%%@NL@%
  11506. %@NL@%
  11507. Structures of type %@AB@%titletype%@AE@% determine text, color, and placement of titles
  11508. appearing in the graph. The PGCHART.H file defines the structure type as  %@NL@%
  11509. %@NL@%
  11510. %@AS@%  typedef struct 
  11511. %@AS@%  {
  11512. %@AS@%     char     title[_PG_TITLELEN];  /* Title text */
  11513. %@AS@%     short    titlecolor;           /* Palette color
  11514. %@AS@%                                       for title text */
  11515. %@AS@%     short    justify;              /* _PG_LEFT, _PG_CENTER,
  11516. %@AS@%                                       _PG_RIGHT */
  11517. %@AS@%  } titletype;%@AE@%%@NL@%
  11518. %@NL@%
  11519. The following list describes %@AB@%titletype%@AE@% members:  %@NL@%
  11520. %@NL@%
  11521. %@AB@%Member Variable%@AE@%                   %@AB@%Description%@AE@%
  11522. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11523. %@AI@%justify%@AE@%                           An integer specifying how the title is 
  11524.                                   justified within the chart window. The 
  11525.                                   symbolic constants defined
  11526.                                   in PGCHART.H for this variable are %@AB@%%@AE@%
  11527.                                   %@AB@%_PG_LEFT%@AE@%,%@AB@%%@AE@%
  11528.                                   %@AB@%_PG_CENTER%@AE@%, and %@AB@%_PG_RIGHT%@AE@%.
  11529.  
  11530. %@AI@%titlecolor%@AE@%                        An integer between 1 and %@AB@%_PG_PALETTELEN%@AE@%
  11531.                                   that specifies a title's color. The 
  11532.                                   default value for%@AI@%%@AE@%
  11533.                                   %@AI@%titlecolor%@AE@% is 1.
  11534.  
  11535. %@AI@%title%@AE@%%@AB@%[_PG_TITLELEN]%@AE@%               A character array containing title text.
  11536.                                   For example, if %@AS@% env %@AE@% is a structure of 
  11537.                                   type%@AB@% chartenv%@AE@%, then %@AS@% env.maintitle.title%@AE@%
  11538.                                   %@AS@%%@AE@% holds the character string used for the
  11539.                                   main title of the chart. Similarly, %@AS@%%@AE@%
  11540.                                   %@AS@%env.xaxis.axistitle.title %@AE@% contains the %@AI@%%@AE@%
  11541.                                   %@AI@%x%@AE@% axis title. The number of characters 
  11542.                                   in a title must be one less than %@AB@%%@AE@%
  11543.                                   %@AB@%_PG_TITLELEN%@AE@% to allow room for a null 
  11544.                                   terminator. 
  11545.  
  11546. %@NL@%
  11547. %@3@%%@CR:C6A00110018 @%%@AB@%11.5.2  axistype Structures%@AE@%%@EH@%%@NL@%
  11548. %@NL@%
  11549. Structures of type %@AB@%axistype%@AE@% contain variables for the axes such as color,
  11550. scale, grid style, and tick marks. The PGCHART.H file defines the structure
  11551. type as the following:  %@NL@%
  11552. %@NL@%
  11553. %@AS@%  typedef struct 
  11554. %@AS@%  {
  11555. %@AS@%     short       grid;          /* TRUE=grid lines drawn;
  11556. %@AS@%                                   FALSE=no lines */
  11557. %@AS@%     short       gridstyle;     /* Style bytes for grid */
  11558. %@AS@%     titletype   axistitle;     /* Title definition
  11559. %@AS@%                                   for axis */
  11560. %@AS@%     short       axiscolor;     /* Color for axis */
  11561. %@AS@%     short       labeled;       /* TRUE=ticks marks and titles
  11562. %@AS@%                                   drawn */
  11563. %@AS@%     short       rangetype;     /* _PG_LINEARAXIS,
  11564. %@AS@%                                   _PG_LOGAXIS */
  11565. %@AS@%     float       logbase;       /* Base used if log axis */
  11566. %@AS@%     short       autoscale;     /* TRUE=next 7 values
  11567. %@AS@%                                   calculated by system */
  11568. %@AS@%     float       scalemin;      /* Minimum value of scale */
  11569. %@AS@%     float       scalemax;      /* Maximum value of scale */
  11570. %@AS@%     float       scalefactor;   /* Scale factor for data on
  11571. %@AS@%                                   this axis */
  11572. %@AS@%     titletype   scaletitle;    /* Title definition for
  11573. %@AS@%                                   scaling factor */
  11574. %@AS@%     float       ticinterval;   /* Distance between tick marks
  11575. %@AS@%                                   (world coord.) */
  11576. %@AS@%     short       ticformat;     /* _PG_EXPFORMAT or
  11577. %@AS@%                                   _PG_DECFORMAT */
  11578. %@AS@%     short       ticdecimals;   /* Number of decimals for tick
  11579. %@AS@%                                   labels (max=9) */
  11580. %@AS@%  } axistype;%@AE@%%@NL@%
  11581. %@NL@%
  11582. The following list describes %@AB@%axistype%@AE@% member variables:  %@NL@%
  11583. %@NL@%
  11584. %@AB@%Member Variable%@AE@%                   %@AB@%Description%@AE@%
  11585. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11586. %@AI@%autoscale%@AE@%                         A Boolean variable. If %@AI@%autoscale%@AE@% is set 
  11587.                                   to %@AB@%TRUE%@AE@%, 
  11588.                                   presentation graphics automatically 
  11589.                                   determines
  11590.                                   values for %@AI@%scalefactor%@AE@%, %@AI@%scalemax%@AE@%, %@AI@%%@AE@%
  11591.                                   %@AI@%scalemin%@AE@%, %@AI@%%@AE@%
  11592.                                   %@AI@%scaletitle%@AE@%, %@AI@%ticdecimals%@AE@%, %@AI@%ticformat%@AE@%, and %@AI@%%@AE@%
  11593.                                   %@AI@%ticinterval%@AE@% 
  11594.                                   (see below). If %@AI@%autoscale%@AE@% equals %@AB@%FALSE%@AE@%, 
  11595.                                   these seven variables must be specified 
  11596.                                   in your program.
  11597.  
  11598. %@AI@%axiscolor%@AE@%                         An integer between 1 and %@AB@%_PG_PALETTELEN%@AE@% 
  11599.                                   that specifies the color used for the 
  11600.                                   axis and parallel grid lines. (See 
  11601.                                   description for %@AI@%gridstyle%@AE@% below.) Note 
  11602.                                   that this member does not determine the 
  11603.                                   color of
  11604.                                   the axis title. That selection is made 
  11605.                                   through the%@AB@%%@AE@%
  11606.                                   %@AB@%axistitle%@AE@% structure.
  11607.  
  11608. %@AI@%axistitle%@AE@%                         A %@AB@%titletype%@AE@% structure that defines the 
  11609.                                   title of the associated axis. The title 
  11610.                                   of the %@AI@%y%@AE@% axis displays vertically to the
  11611.                                   left of the %@AI@%y%@AE@% axis, and the title of the
  11612.                                   %@AI@%x%@AE@% axis displays horizontally below the %@AI@%x%@AE@%
  11613.                                   axis.
  11614.  
  11615. %@AI@%grid%@AE@%                              A Boolean true/false value that 
  11616.                                   determines whether grid lines are drawn 
  11617.                                   for the associated axis. Grid lines span
  11618.                                   the data window perpendicular to the 
  11619.                                   axis.
  11620.  
  11621. %@AI@%gridstyle%@AE@%                         An integer between 1 and %@AB@%_PG_PALETTELEN%@AE@% 
  11622.                                   that specifies the grid's line style. 
  11623.                                   Lines can be solid, dashed, dotted, or 
  11624.                                   some combination. The default value for %@AI@%%@AE@%
  11625.                                   %@AI@%gridstyle%@AE@% is 1. 
  11626.  
  11627.                                   Note that the color of the parallel axis
  11628.                                   determines the color of the grid lines. 
  11629.                                   Thus, the %@AI@%x%@AE@% axis grid is the same color 
  11630.                                   as the %@AI@%y%@AE@% axis, and the %@AI@%y%@AE@% axis grid is 
  11631.                                   the same color as the %@AI@%x%@AE@% axis.
  11632.  
  11633. %@AI@%labeled%@AE@%                           A Boolean value that determines whether 
  11634.                                   tick marks and labels are drawn on the 
  11635.                                   axis. Axis labels should not be confused
  11636.                                   with axis titles. Axis labels are 
  11637.                                   numbers or descriptions such as "23.2" 
  11638.                                   or "January" attached to each tick mark.
  11639.  
  11640. %@AI@%logbase%@AE@%                           If%@AI@% rangetype%@AE@% is logarithmic, the %@AI@%logbase%@AE@%
  11641.                                   variable determines the log base used to
  11642.                                   scale the axis. The default value is 10.
  11643.  
  11644. %@AI@%rangetype%@AE@%                         An integer that determines whether the 
  11645.                                   scale of the axis is linear or 
  11646.                                   logarithmic. The variable %@AI@%rangetype%@AE@% 
  11647.                                   applies only to value data.
  11648.  
  11649.                                   Specify a linear scale with %@AB@%%@AE@%
  11650.                                   %@AB@%_PG_LINEARAXIS%@AE@%. A linear scale is best 
  11651.                                   when the difference between axis minimum
  11652.                                   and maximum is relatively small. For
  11653.                                   example, a linear axis range 0 - 10 
  11654.                                   results in 10 tick marks evenly spaced 
  11655.                                   along the axis.
  11656.  
  11657.                                   Use %@AB@%_PG_LOGAXIS%@AE@% to specify a logarithmic
  11658.                                   %@AI@%rangetype%@AE@%. Logarithmic scales are useful
  11659.                                   when
  11660.                                   the range is very large or when the data
  11661.                                   varies exponentially. Line graphs of 
  11662.                                   exponentially varying data can be made 
  11663.                                   straight with a logarithmic%@AI@%%@AE@%
  11664.                                   %@AI@%rangetype%@AE@%.
  11665.  
  11666. %@AI@%scalefactor%@AE@%                       All numeric data are scaled by dividing 
  11667.                                   each
  11668.                                   value by %@AI@%scalefactor%@AE@%. For relatively 
  11669.                                   small values,%@AI@%%@AE@%
  11670.                                   %@AI@%scalefactor%@AE@% should be 1, which is the 
  11671.                                   default. But data with large values 
  11672.                                   should be scaled by an appropriate 
  11673.                                   factor. For example, data in the range
  11674.                                   2 million - 20 million should be plotted
  11675.                                   with%@AI@%%@AE@%
  11676.                                   %@AI@%scalemin%@AE@% set to 2, %@AI@%scalemax%@AE@% set to 20, 
  11677.                                   and%@AI@%%@AE@%
  11678.                                   %@AI@%scalefactor%@AE@% set to 1 million.
  11679.  
  11680.                                   If %@AI@%autoscale%@AE@% is set to %@AB@%TRUE%@AE@%, 
  11681.                                   presentation graphics automatically 
  11682.                                   determines a suitable value for%@AI@%%@AE@%
  11683.                                   %@AI@%scalefactor%@AE@% based on the range of data 
  11684.                                   to be plotted. Presentation graphics 
  11685.                                   selects only values that are a factor of
  11686.                                   1 thousand─that is, values such as 1 
  11687.                                   thousand, 1 million, or 1 billion. It 
  11688.                                   then labels the%@AI@%%@AE@%
  11689.                                   %@AI@%scaletitle%@AE@% appropriately (see below). If
  11690.                                   you desire some other value for scaling,
  11691.                                   you must set %@AI@%autoscale%@AE@% to %@AB@%FALSE%@AE@% and set %@AI@%%@AE@%
  11692.                                   %@AI@%scalefactor%@AE@% to the desired scaling value.
  11693.  
  11694. %@AI@%scalemax%@AE@%                          Highest value represented by the axis.
  11695.  
  11696. %@AI@%scalemin%@AE@%                          Lowest value represented by the axis.
  11697.  
  11698. %@AI@%scaletitle%@AE@%                        A %@AB@%titletype%@AE@% structure defining a string 
  11699.                                   of text that 
  11700.                                   describes the value of %@AI@%scalefactor%@AE@%. If %@AI@%%@AE@%
  11701.                                   %@AI@%autoscale%@AE@% is %@AB@%TRUE%@AE@%, presentation graphics
  11702.                                   automatically writes a scale description
  11703.                                   to %@AI@%scaletitle%@AE@%. If%@AI@% autoscale%@AE@% equals %@AB@%FALSE%@AE@%
  11704.                                   and %@AI@%scalefactor%@AE@% is 1, %@AI@%scaletitle.title%@AE@% 
  11705.                                   should be blank. Otherwise your program 
  11706.                                   should copy an appropriate scale 
  11707.                                   description to %@AI@%scaletitle.title%@AE@%, such as
  11708.                                   "( x 1000)," "(in millions of units)," 
  11709.                                   or "times 10 thousand dollars."
  11710.  
  11711.                                   For the %@AI@%y%@AE@% axis, the %@AI@%scaletitle%@AE@% text 
  11712.                                   displays vertically between the axis 
  11713.                                   title and the %@AI@%y%@AE@% axis. For the %@AI@%x%@AE@% axis, 
  11714.                                   the scale title appears below the %@AI@%x%@AE@% axis
  11715.                                   title.
  11716.  
  11717. %@AI@%ticdecimals %@AE@%                      Number of digits to display after the 
  11718.                                   decimal point in tick labels. Maximum 
  11719.                                   value is 9. (This variable applies only 
  11720.                                   to axes with value data and is ignored 
  11721.                                   for the category axis.)
  11722.  
  11723. %@AI@%ticformat%@AE@%                         An integer that determines format of the
  11724.                                   labels
  11725.                                   assigned to each tick mark. Set %@AI@%%@AE@%
  11726.                                   %@AI@%ticformat%@AE@%  to%@AB@%%@AE@%
  11727.                                   %@AB@%_PG_EXPFORMAT%@AE@% for exponential format or
  11728.                                   to %@AB@%_PG_DECFORMAT%@AE@% for decimal. The 
  11729.                                   default is %@AB@%_PG_DECFORMAT%@AE@%. (This variable
  11730.                                   applies only to axes with value data and
  11731.                                   is ignored for the category axis.)
  11732.  
  11733. %@AI@%ticinterval%@AE@%                       Sets interval between tick marks on the 
  11734.                                   axis. The tick interval is measured in 
  11735.                                   the same units as the numeric data 
  11736.                                   associated with the axis. For example, 
  11737.                                   if 2 sequential tick marks correspond to
  11738.                                   the values 20 and 25, the tick interval 
  11739.                                   between them is 5. (This variable 
  11740.                                   applies only to axes with value data and
  11741.                                   is ignored for the category axis.)
  11742.  
  11743. %@NL@%
  11744. %@3@%%@CR:C6A00110019 @%%@AB@%11.5.3  windowtype Structures%@AE@%%@EH@%%@NL@%
  11745. %@NL@%
  11746. Structures of type %@AB@%windowtype%@AE@% contain sizes, locations, and color codes for
  11747. the three windows produced by presentation graphics: the chart window, the
  11748. data window, and the legend. Windows are located on the screen relative to
  11749. the screen's logical origin. By changing the logical origin, you can display
  11750. charts that are partly or completely off the screen.  %@NL@%
  11751. %@NL@%
  11752. The PGCHART.H file defines %@AB@%windowtype%@AE@% as the following:  %@NL@%
  11753. %@NL@%
  11754. %@AS@%  typedef struct 
  11755. %@AS@%  {
  11756. %@AS@%     short  x1;            /* Left edge of window in
  11757. %@AS@%                              pixels */
  11758. %@AS@%     short  y1;            /* Top edge of window in
  11759. %@AS@%                              pixels */
  11760. %@AS@%     short  x2;            /* Right edge of window in
  11761. %@AS@%                              pixels */
  11762. %@AS@%     short  y2;            /* Bottom edge of window in
  11763. %@AS@%                              pixels */
  11764. %@AS@%     short  border;        /* TRUE for border, FALSE
  11765. %@AS@%                              otherwise */
  11766. %@AS@%     short  background;    /* Internal palette color for
  11767. %@AS@%                              window background */
  11768. %@AS@%     short  borderstyle;   /* Style bytes for window
  11769. %@AS@%                              border */
  11770. %@AS@%     short  bordercolor;   /* Internal palette color for
  11771. %@AS@%                              window border */
  11772. %@AS@%  } windowtype;%@AE@%%@NL@%
  11773. %@NL@%
  11774. The following list describes %@AB@%windowtype%@AE@% member variables:  %@NL@%
  11775. %@NL@%
  11776. %@AB@%Member Variable%@AE@%                   %@AB@%Description%@AE@%
  11777. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11778. %@AI@%background%@AE@%                        An integer between 1 and %@AB@%_PG_PALETTELEN%@AE@% 
  11779.                                   that specifies the window's background 
  11780.                                   color. The default value for %@AI@%background%@AE@% 
  11781.                                   is 1.
  11782.  
  11783. %@AI@%border%@AE@%                            A Boolean variable that determines 
  11784.                                   whether a border frame is drawn around a
  11785.                                   window.
  11786.  
  11787. %@AI@%bordercolor%@AE@%                       An integer between 1 and %@AB@%_PG_PALETTELEN%@AE@% 
  11788.                                   that specifies the color of the window's
  11789.                                   border frame. The default value is 1.
  11790.  
  11791. %@AI@%borderstyle%@AE@%                       An integer between 1 and %@AB@%_PG_PALETTELEN%@AE@% 
  11792.                                   that specifies the line style of the 
  11793.                                   window's border frame. The default value
  11794.                                   is 1.
  11795.  
  11796. %@AI@%x1, y1, x2, y2%@AE@%                    Window coordinates in pixels. The 
  11797.                                   ordered pair
  11798.                                   (%@AI@%x1%@AE@%, %@AI@%y1%@AE@%) specifies the coordinate of the
  11799.                                   upper left corner of the window. The 
  11800.                                   ordered pair ( %@AI@%x2%@AE@%, %@AI@%y2%@AE@% ) specifies the 
  11801.                                   coordinate of the lower right corner.
  11802.  
  11803.                                   The reference point for the coordinates 
  11804.                                   depends on the type of window. The chart
  11805.                                   window is located relative to the 
  11806.                                   logical origin, usually the upper left 
  11807.                                   corner of the screen. The data and 
  11808.                                   legend windows are located relative to 
  11809.                                   the upper left corner of the chart 
  11810.                                   window. This allows you to change the 
  11811.                                   position of the chart window without 
  11812.                                   having to redefine coordinates for the 
  11813.                                   other two windows.
  11814.  
  11815. %@NL@%
  11816. %@3@%%@CR:C6A00110020 @%%@AB@%11.5.4  legendtype Structures%@AE@%%@EH@%%@NL@%
  11817. %@NL@%
  11818. Structures of type %@AB@%legendtype%@AE@% contain size, location, and colors of the
  11819. chart legend. The PGCHART.H file defines the structure type as the
  11820. following:  %@NL@%
  11821. %@NL@%
  11822. %@AS@%  typedef struct 
  11823. %@AS@%  {
  11824. %@AS@%     short      legend;        /* TRUE=draw legend;
  11825. %@AS@%                                  FALSE=no legend */
  11826. %@AS@%     short      place;         /* _PG_RIGHT, _PG_BOTTOM,
  11827. %@AS@%                                  _PG_OVERLAY */
  11828. %@AS@%     short      textcolor;     /* Palette color for text*/
  11829. %@AS@%     short      autosize;      /* TRUE=system calculates
  11830. %@AS@%                                  legend size */
  11831. %@AS@%     windowtype legendwindow;  /* Window definition for
  11832. %@AS@%                                  legend */
  11833. %@AS@%  } legendtype;%@AE@%%@NL@%
  11834. %@NL@%
  11835. The following list describes %@AB@%legendtype%@AE@% member variables:  %@NL@%
  11836. %@NL@%
  11837. %@AB@%Member Variable%@AE@%                   %@AB@%Description%@AE@%
  11838. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11839. %@AI@%autosize%@AE@%                          A Boolean true/false variable that 
  11840.                                   determines whether presentation graphics
  11841.                                   is to automatically
  11842.                                   calculate the size of the legend. If %@AI@%%@AE@%
  11843.                                   %@AI@%autosize%@AE@% equals %@AB@%FALSE%@AE@%, the legend window
  11844.                                   must be specified in the %@AI@%legendwindow%@AE@% 
  11845.                                   structure (see below).
  11846.  
  11847. %@AI@%legend%@AE@%                            A Boolean true/false variable that 
  11848.                                   determines whether a legend is to appear
  11849.                                   on the chart. The %@AI@%legend%@AE@% variable is 
  11850.                                   ignored by functions that graph 
  11851.                                   single-series charts.
  11852.  
  11853. %@AI@%legendwindow%@AE@%                      A %@AB@%windowtype%@AE@% structure that defines 
  11854.                                   coordinates, background color, and 
  11855.                                   border frame for the legend. Coordinates
  11856.                                   given in %@AI@%legendwindow%@AE@% are ignored if %@AI@%%@AE@%
  11857.                                   %@AI@%autosize%@AE@% is set to %@AB@%TRUE%@AE@%.
  11858.  
  11859. %@AI@%place%@AE@%                             An integer that specifies the location 
  11860.                                   of the legend relative to the data 
  11861.                                   window. Setting %@AI@%place%@AE@% equal
  11862.                                   to the constant %@AB@%_PG_RIGHT%@AE@% positions the 
  11863.                                   legend
  11864.                                   to the right of the data window. Setting
  11865.                                   %@AI@%place%@AE@% to%@AB@%%@AE@%
  11866.                                   %@AB@%_PG_BOTTOM%@AE@% positions the legend below 
  11867.                                   the data window. Setting %@AI@%place%@AE@% to %@AB@%%@AE@%
  11868.                                   %@AB@%_PG_OVERLAY%@AE@% positions the legend within 
  11869.                                   the data window.
  11870.  
  11871.                                   These settings influence the size of the
  11872.                                   data window. If %@AI@%place%@AE@% equals %@AB@%_PG_RIGHT%@AE@% 
  11873.                                   or %@AB@%_PG_BOTTOM%@AE@%, presentation graphics 
  11874.                                   automatically sizes the data window to 
  11875.                                   accommodate the legend. If %@AI@%place%@AE@% equals %@AB@%%@AE@%
  11876.                                   %@AB@%_PG_OVERLAY%@AE@%, the data window is sized 
  11877.                                   without regard to the legend.
  11878.  
  11879. %@AI@%textcolor%@AE@%                         An integer between 1 and %@AB@%_PG_PALETTELEN%@AE@% 
  11880.                                   that specifies the color of text within 
  11881.                                   the legend window.
  11882.  
  11883. %@NL@%
  11884. %@3@%%@CR:C6A00110021 @%%@AB@%11.5.5  chartenv Structures%@AE@%%@EH@%%@NL@%
  11885. %@NL@%
  11886. A structure of type%@AB@% chartenv%@AE@% defines the chart environment. The following
  11887. listing shows that a %@AB@%chartenv%@AE@% type structure consists almost entirely of
  11888. structures of the four types described above.  %@NL@%
  11889. %@NL@%
  11890. The PGCHART.H file defines the %@AB@%chartenv%@AE@% structure type as the following:  %@NL@%
  11891. %@NL@%
  11892. %@AS@%  typedef struct 
  11893. %@AS@%  {
  11894. %@AS@%     short       charttype;     /* Chart type */
  11895. %@AS@%     short       chartstyle;    /* Chart style */
  11896. %@AS@%     windowtype  chartwindow;   /* Window definition for
  11897. %@AS@%                                   overall chart */
  11898. %@AS@%     windowtype  datawindow;    /* Window definition for data
  11899. %@AS@%                                   part of chart */
  11900. %@AS@%     titletype   maintitle;     /* Main chart title */
  11901. %@AS@%     titletype   subtitle;      /* Chart subtitle */
  11902. %@AS@%     axistype    xaxis;         /* Definition for x axis */
  11903. %@AS@%     axistype    yaxis;         /* Definition for y axis */
  11904. %@AS@%     legendtype  legend;        /* Definition for legend */
  11905. %@AS@%  } chartenv;%@AE@%%@NL@%
  11906. %@NL@%
  11907. %@AU@% Initialize the chart environment with the _pg_defaultchart function.%@AE@%  %@NL@%
  11908. %@NL@%
  11909. The data in a %@AB@%chartenv%@AE@% type structure is initialized by calling the function%@AB@%
  11910. %@AB@%_pg_defaultchart%@AE@%. If your program does not call %@AB@%_pg_defaultchart%@AE@%, it must
  11911. explicitly define every variable in the chart environment─a tedious
  11912. procedure. The recommended method for adjusting the appearance of your chart
  11913. is to initialize variables for the proper chart type by calling the
  11914. %@AB@%_pg_defaultchart%@AE@% function, and then to reassign selected environment
  11915. variables such as titles.  %@NL@%
  11916. %@NL@%
  11917. The following list describes %@AB@%chartenv%@AE@% member variables:  %@NL@%
  11918. %@NL@%
  11919. %@AB@%Member Variable%@AE@%                   %@AB@%Description%@AE@%
  11920. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11921. %@AI@%chartstyle%@AE@%                        An integer that determines the style of 
  11922.                                   the chart
  11923.                                   (see Table 11.2). Legal values for %@AI@%%@AE@%
  11924.                                   %@AI@%chartstyle%@AE@% are %@AB@%_PG_PERCENT%@AE@% and %@AB@%%@AE@%
  11925.                                   %@AB@%_PG_NOPERCENT%@AE@% for pie charts; %@AB@%%@AE@%
  11926.                                   %@AB@%_PG_PLAINBARS%@AE@% and %@AB@%_PG_STACKEDBARS%@AE@% for 
  11927.                                   bar and column charts; and %@AB@%_PG_POINTONLY%@AE@%
  11928.                                   and  %@AB@%_PG_POINTANDLINE%@AE@% for line graphs 
  11929.                                   and scatter diagrams. This variable 
  11930.                                   corresponds to the third argument for 
  11931.                                   the %@AB@%_pg_defaultchart%@AE@% function.
  11932.  
  11933. %@AI@%charttype%@AE@%                         An integer that determines the type of 
  11934.                                   chart displayed. The value of %@AI@%charttype%@AE@% 
  11935.                                   is %@AB@%_PG_BARCHART%@AE@%, %@AB@%_PG_COLUMNCHART%@AE@%, %@AB@%%@AE@%
  11936.                                   %@AB@%_PG_LINECHART%@AE@%, %@AB@%_PG_SCATTERCHART%@AE@%, or %@AB@%%@AE@%
  11937.                                   %@AB@%_PG_PIECHART%@AE@%. This variable corresponds 
  11938.                                   to the second argument for the %@AB@%%@AE@%
  11939.                                   %@AB@%_pg_defaultchart%@AE@% function.
  11940.  
  11941. %@AI@%chartwindow%@AE@%                       A %@AB@%windowtype%@AE@% structure that defines the 
  11942.                                   appearance of the chart window.
  11943.  
  11944. %@AI@%datawindow%@AE@%                        A %@AB@%windowtype%@AE@% structure that defines the 
  11945.                                   appearance of the data window.
  11946.  
  11947. %@AI@%legend%@AE@%                            A %@AB@%legendtype%@AE@% structure that defines the 
  11948.                                   appearance of the legend window.
  11949.  
  11950. %@AI@%maintitle%@AE@%                         A %@AB@%titletype%@AE@% structure that defines the 
  11951.                                   appearance of the main title of the 
  11952.                                   chart.
  11953.  
  11954. %@AI@%subtitle%@AE@%                          A %@AB@%titletype%@AE@% structure that defines the 
  11955.                                   appearance of the chart's subtitle.
  11956.  
  11957. %@AI@%xaxis%@AE@%                             An %@AB@%axistype%@AE@% structure that defines the 
  11958.                                   appearance of the %@AI@%x%@AE@% axis. (This variable
  11959.                                   is not applicable for pie charts.)
  11960.  
  11961. %@AI@%yaxis%@AE@%                             An %@AB@%axistype%@AE@% structure that defines the 
  11962.                                   appearance of the %@AI@%y%@AE@% axis. (This variable
  11963.                                   is not applicable for pie charts.)
  11964.  
  11965.                                   
  11966.  
  11967.   %@NL@%
  11968. %@NL@%
  11969. %@NL@%
  11970. %@NL@%
  11971. %@NL@%
  11972. %@NL@%
  11973. %@NL@%
  11974. %@CR:C6A00120001 @%%@1@%%@AB@%Chapter 12  Programming with Mixed Languages%@AE@%%@EH@%%@NL@%
  11975. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11976. %@NL@%
  11977. There are times when your Microsoft C programs need to call programs written
  11978. in other languages or when programs written in other languages need to call
  11979. your C functions. This is called mixed-language programming. For example,
  11980. when a particular subprogram is available commercially in a language other
  11981. than C or when algorithms are described more naturally in a different
  11982. language, you need to use more than one language.  %@NL@%
  11983. %@NL@%
  11984. This chapter describes the elements of mixed-language programming─how to
  11985. make calls from programs written in one language to routines written in
  11986. another.  %@NL@%
  11987. %@NL@%
  11988. %@NL@%
  11989. %@2@%%@CR:C6A00120002 @%%@AB@%12.1  Making Mixed-Language Calls%@AE@%%@EH@%%@NL@%
  11990. %@NL@%
  11991. Mixed-language programming always involves a call to a function, procedure,
  11992. or subroutine. For example, a BASIC main module may need to execute a
  11993. specific task that you would like to program separately. Instead of calling
  11994. a BASIC subprogram, however, you decide to call a C function.  %@NL@%
  11995. %@NL@%
  11996. Mixed-language calls involve calling functions in separate modules. Instead
  11997. of compiling all of your source modules with the same compiler, you use
  11998. different compilers. In the instance mentioned above, you would compile the
  11999. mainmodule source file with the BASIC compiler, another source file (written
  12000. in C) with the C compiler, and then link the two object files.  %@NL@%
  12001. %@NL@%
  12002. Figure 12.1 illustrates how the syntax of a mixed-language call works, using
  12003. the instance mentioned above.  %@NL@%
  12004. %@NL@%
  12005. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  12006. %@NL@%
  12007. In Figure 12.1, the BASIC call to C is %@AS@% CALL Prn%@AE@%, similar to a call to a
  12008. BASIC subprogram. There are two differences between this mixed-language call
  12009. and a call between two BASIC modules:  %@NL@%
  12010. %@NL@%
  12011. %@NL@%
  12012.   1.  The subprogram %@AS@% Prn %@AE@% is implemented in C, using standard C syntax.%@NL@%
  12013. %@NL@%
  12014.   2.  The implementation of the call in BASIC is affected by the %@AB@%DECLARE%@AE@%
  12015.       statement, which uses the %@AB@%CDECL%@AE@% keyword to create compatibility with
  12016.       C. The %@AB@%DECLARE%@AE@% statement (which is described in detail in the
  12017.       %@AI@%Microsoft BASIC Language Reference%@AE@% and the %@AI@%Microsoft BASIC
  12018. %@AI@%      Programmer's Guide%@AE@%) is an example of a mixed-language "interface"
  12019.       statement. These interface statements override default naming and
  12020.       calling conventions. Each language provides its own form of interface.%@NL@%
  12021. %@NL@%
  12022. %@NL@%
  12023. You can make mixed-language calls to routines regardless of whether they
  12024. have return values. (In this chapter, "routine" refers to any function,
  12025. procedure, or subroutine that can be called from another module.)  %@NL@%
  12026. %@NL@%
  12027. Table 12.1 shows the correspondence between calls to routines in different
  12028. languages.  %@NL@%
  12029. %@NL@%
  12030. %@AB@%Table 12.1  %@AB@%Language Equivalents for Routine Calls%@AE@%%@AE@%
  12031.  
  12032. %@TH:   8   553 02 20 21 35 @%Language            Return Value         No Return Value%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Assembly Language   Procedure            ProcedureBASIC               FUNCTION procedure   SubprogramC                   function             (%@AB@%void%@AE@%) functionFORTRAN             FUNCTION             SUBROUTINEPascal              Function             Procedure%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   8   553 02 20 21 35 @%
  12033.  
  12034. For example, a C module can make a subprogram call to a FORTRAN subroutine.
  12035. You can prototype a FORTRAN subroutine as a function with a %@AB@% void%@AE@% type.  %@NL@%
  12036. %@NL@%
  12037. ────────────────────────────────────────────────────────────────────────────%@NL@%
  12038. NOTE
  12039.  
  12040. %@AI@%BASIC %@AI@%DEF FN%@AE@%%@AI@% functions and GOSUB%@AE@%%@AI@% subroutines cannot be called from another
  12041. %@AI@%language.%@AE@%%@AE@%%@NL@%
  12042. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  12043. %@NL@%
  12044. %@NL@%
  12045. %@2@%%@CR:C6A00120003 @%%@AB@%12.2  Language Convention Requirements%@AE@%%@EH@%%@NL@%
  12046. %@NL@%
  12047. To mix languages, the calling program must observe the same conventions as
  12048. the called program. The conventions described in this section govern the
  12049. following:  %@NL@%
  12050. %@NL@%
  12051. %@NL@%
  12052.   ■   How compilers treat identifiers, including function and variable names
  12053.       (naming convention)%@NL@%
  12054. %@NL@%
  12055.   ■   How the subprogram call is implemented (calling convention)%@NL@%
  12056. %@NL@%
  12057.   ■   How parameters are passed (parameter-passing convention)%@NL@%
  12058. %@NL@%
  12059. %@NL@%
  12060. %@NL@%
  12061. %@3@%%@CR:C6A00120004 @%%@AB@%12.2.1  Naming Convention Requirement%@AE@%%@EH@%%@NL@%
  12062. %@NL@%
  12063. Both the calling program and the called subprogram must agree on the names
  12064. of identifiers. Identifiers can refer to subprograms (functions, procedures,
  12065. and subroutines) or to variables that have a public or global scope. Each
  12066. language alters the names of identifiers.%@CR:C6A00120005 @%  %@NL@%
  12067. %@NL@%
  12068. The term "naming convention" refers to the way a compiler alters the name of
  12069. the routine before placing it in an object file. Languages may alter the
  12070. identifier names differently. You can choose between several naming
  12071. conventions to ensure that the names in the calling program agree with those
  12072. in the called program. If the names of called routines are stored
  12073. differently in each object file, the linker will not be able to find a
  12074. match. It will instead report unresolved external references.  %@NL@%
  12075. %@NL@%
  12076. Microsoft compilers place machine code into object files; they also place
  12077. the names of all publicly accessed routines and variables in object files.
  12078. The linker can then compare the name of a routine called in one module with
  12079. the name of a routine defined in another module, and recognize a match.
  12080. Names are stored in the ASCII (American Standard Code for Information
  12081. Interchange) character set.  %@NL@%
  12082. %@NL@%
  12083. %@AU@% Some languages translate names to uppercase.%@AE@%  %@NL@%
  12084. %@NL@%
  12085. BASIC, FORTRAN, and Pascal use similar naming conventions. They translate
  12086. each letter to uppercase. BASIC type declaration characters (%, &, !, #, $)
  12087. are dropped.  %@NL@%
  12088. %@NL@%
  12089. Each language recognizes a different number of characters. FORTRAN
  12090. recognizes the first 31 characters of any name (unless identifier names are
  12091. truncated), Pascal the first 8, and BASIC the first 40. If a name is longer
  12092. than the language will recognize, additional characters are simply not
  12093. placed in the object file.  %@NL@%
  12094. %@NL@%
  12095. ────────────────────────────────────────────────────────────────────────────%@NL@%
  12096. NOTE
  12097.  
  12098. %@AI@%Versions of Microsoft FORTRAN previous to version 5.0 truncated identifiers
  12099. %@AI@%to six characters. As of version 5.0, FORTRAN retains up to 31 characters of
  12100. %@AI@%significance unless you use the /4Yt option.%@AE@%%@NL@%
  12101. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  12102. %@NL@%
  12103. %@AU@% C is a case-sensitive language.%@AE@%  %@NL@%
  12104. %@NL@%
  12105. The C compiler does not translate any letters to uppercase. It inserts a
  12106. leading underscore ( _ ) in front of the name of each routine. C recognizes
  12107. the first 31 characters of a name.  %@NL@%
  12108. %@NL@%
  12109. Differences in naming conventions are dealt with automatically by
  12110. mixedlanguage keywords, as long as you follow two rules:%@CR:C6A00120006 @%  %@NL@%
  12111. %@NL@%
  12112. %@NL@%
  12113.   1.  If you use any FORTRAN routines that were compiled with the /4Yt
  12114.       command-line option or with the %@AB@%$TRUNCATE%@AE@% metacommand enabled, make
  12115.       all names 6 characters or less. Make all names 6 characters or less
  12116.       when using FORTRAN routines compiled with versions of the FORTRAN
  12117.       compiler prior to 5.0.%@NL@%
  12118. %@NL@%
  12119.   2.  Do not use the /NOIGNORECASE linker option (which causes the linker to
  12120.       treat identifiers in a case-sensitive manner). With C modules, this
  12121.       means that you must be careful not to rely upon differences between
  12122.       uppercase and lowercase letters when programming.%@NL@%
  12123. %@NL@%
  12124. %@STUB@%      CL automatically uses the /NOIGNORECASE option when linking. To solve
  12125.       the problems created by this behavior, either link separately with the
  12126.       LINK utility, or use all lowercase letters in your C function names
  12127.       and public variables (global variables that are not declared as
  12128.       static).%@NL@%
  12129. %@NL@%
  12130. %@NL@%
  12131. ────────────────────────────────────────────────────────────────────────────%@NL@%
  12132. NOTE
  12133.  
  12134. %@AI@%If you use the command-line option /Gc (generate Pascal-style function
  12135. %@AI@%calls) when you compile, or if you declare a function or variable with the
  12136. %@AB@%_pascal%@AE@%%@AI@% keyword, the compiler will translate your identifiers to uppercase.%@AE@%%@AE@%%@NL@%
  12137. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  12138. %@NL@%
  12139. Figure 12.2 illustrates a complete mixed-language development example,
  12140. showing how naming conventions enter into the process.  %@NL@%
  12141. %@NL@%
  12142. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  12143. %@NL@%
  12144. In Figure 12.2, note that the BASIC compiler inserts a leading underscore in
  12145. front of %@AS@% Prn %@AE@% as it places the name into the object file, because the %@AB@%CDECL%@AE@%
  12146. keyword directs the BASIC compiler to use the C naming convention. BASIC
  12147. will also convert all letters to lowercase when this keyword is used.
  12148. (Converting letters to lowercase is not part of the C naming convention;
  12149. however, it is consistent with the programming style of many C programs.)%@CR:C6A00120007 @%  %@NL@%
  12150. %@NL@%
  12151. %@NL@%
  12152. %@3@%%@CR:C6A00120008 @%%@AB@%12.2.2  Calling Convention Requirement%@AE@%%@EH@%%@NL@%
  12153. %@NL@%
  12154. The term "calling convention" refers to the way a language implements a
  12155. call. The choice of calling convention affects the machine instructions that
  12156. a compiler generates to execute (and return from) a function, procedure, or
  12157. subroutine call.%@CR:C6A00120009 @%  %@NL@%
  12158. %@NL@%
  12159. It is crucial that the two routines concerned (the routine issuing a call
  12160. and the routine being called) use the same protocol. Otherwise, the
  12161. processor may receive inconsistent instructions, causing the program to
  12162. behave incorrectly.  %@NL@%
  12163. %@NL@%
  12164. The use of a calling convention affects programming in three ways:  %@NL@%
  12165. %@NL@%
  12166. %@NL@%
  12167.   1.  The calling routine uses a calling convention to determine the order
  12168.       in which to pass arguments (parameters) to another routine. This
  12169.       convention can be specified in a mixed-language interface statement or
  12170.       declaration.%@NL@%
  12171. %@NL@%
  12172.   2.  The called routine uses a calling convention to determine the order in
  12173.       which to receive the parameters passed to it. In most languages, this
  12174.       convention can be specified in the routine's heading. BASIC, however,
  12175.       always uses its own convention to receive parameters.%@NL@%
  12176. %@NL@%
  12177.   3.  Both the calling routine and the called routine must agree on which of
  12178.       them is responsible for adjusting the stack after all parameters are
  12179.       removed.%@NL@%
  12180. %@NL@%
  12181. %@NL@%
  12182. In other words, each call to a routine uses a certain calling convention;
  12183. each routine heading specifies or assumes some calling convention. The two
  12184. conventions must be compatible. With all languages except BASIC, it is
  12185. possible to change the calling convention at the point of the call or at the
  12186. declaration of the called routine. Usually, however, it is easier to adopt
  12187. the convention of the called routine. For example, a C function would use
  12188. its own convention to call another C function, and would use the Pascal
  12189. convention to call Pascal.  %@NL@%
  12190. %@NL@%
  12191. BASIC, FORTRAN, and Pascal use the same standard calling convention. C uses
  12192. a different convention.  %@NL@%
  12193. %@NL@%
  12194. %@NL@%
  12195. %@4@%%@AB@%Effects of Calling Conventions%@AE@%%@EH@%%@NL@%
  12196. %@NL@%
  12197. Calling conventions dictate three things:%@CR:C6A00120010 @%%@CR:C6A00120011 @%  %@NL@%
  12198. %@NL@%
  12199. %@NL@%
  12200.   1.  The way parameters are communicated from one routine to another (in
  12201.       Microsoft mixed-language programming, parameters or pointers to the
  12202.       parameters are passed on the stack)%@NL@%
  12203. %@NL@%
  12204.   2.  The order in which parameters are passed from one routine to another%@NL@%
  12205. %@NL@%
  12206.   3.  The part of the program responsible for adjusting the stack%@NL@%
  12207. %@NL@%
  12208. %@NL@%
  12209. %@AU@% Some languages pass parameters in a different order than C.%@AE@%  %@NL@%
  12210. %@NL@%
  12211. The BASIC, FORTRAN and Pascal calling conventions push parameters onto the
  12212. stack in the order in which they appear in the source code. For example, the
  12213. BASIC statement  %@NL@%
  12214. %@NL@%
  12215. %@AS@%  CALL Calc( A, B )%@AE@%%@NL@%
  12216. %@NL@%
  12217. pushes argument %@AS@% A %@AE@% onto the stack before it pushes %@AS@% B%@AE@%. These conventions
  12218. also specify that the stack is adjusted by the called routine just before
  12219. returning control to the caller.  %@NL@%
  12220. %@NL@%
  12221. The C calling convention pushes parameters onto the stack in the reverse
  12222. order from their appearance in the source code. For example, the C function
  12223. call  %@NL@%
  12224. %@NL@%
  12225. %@AS@%  calc( a, b );%@AE@%%@NL@%
  12226. %@NL@%
  12227. pushes %@AS@% b %@AE@% onto the stack before it pushes %@AS@% a%@AE@%. In contrast with the other
  12228. high-level languages, the C calling convention specifies that a calling
  12229. routine always adjusts the stack immediately after the called routine
  12230. returns control.  %@NL@%
  12231. %@NL@%
  12232. The BASIC, FORTRAN, and Pascal conventions produce slightly less object
  12233. code. However, the C convention makes calling with a variable number of
  12234. parameters possible. (Because the first parameter is always the last one
  12235. pushed, it is always on the top of the stack; therefore it has the same
  12236. address relative to the frame pointer, regardless of how many parameters
  12237. were actually passed.)  %@NL@%
  12238. %@NL@%
  12239. ────────────────────────────────────────────────────────────────────────────%@NL@%
  12240. NOTE
  12241.  
  12242. %@AI@%The %@AB@%_fastcall%@AE@%%@AI@% keyword, which specifies that parameters are to be passed in
  12243. %@AI@%registers, is incompatible with programs written in other languages. Avoid
  12244. %@AI@%using %@AE@%%@AI@%%@AB@%_fastcall%@AE@%%@AE@%%@AI@% or the /Gr command-line option for C functions that you
  12245. %@AI@%intend to make public to BASIC, FORTRAN, or Pascal programs.%@AE@%%@AE@%%@NL@%
  12246. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  12247. %@NL@%
  12248. %@NL@%
  12249. %@3@%%@CR:C6A00120012 @%%@AB@%12.2.3  Parameter-Passing Requirement%@AE@%%@EH@%%@NL@%
  12250. %@NL@%
  12251. Your programs must agree on the calling convention and the naming
  12252. convention; they must also agree on the order in which they pass parameters.
  12253. It is important that your routines send parameters in the same way to ensure
  12254. proper data transmission and correct program results.%@CR:C6A00120013 @%  %@NL@%
  12255. %@NL@%
  12256. Microsoft compilers support three methods for passing a parameter:  %@NL@%
  12257. %@NL@%
  12258. %@AB@%Method%@AE@%                            %@AB@%Description%@AE@%
  12259. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12260. Near reference                    Passes a variable's near (offset) 
  12261.                                   address. This address is expressed as an
  12262.                                   offset from the default data segment.
  12263.  
  12264.                                   This method gives the called routine 
  12265.                                   direct access to the variable itself. 
  12266.                                   Any change the routine makes to the 
  12267.                                   parameter changes the variable in the 
  12268.                                   calling routine.
  12269.  
  12270. Far reference                     Passes a variable's far (segmented) 
  12271.                                   address.
  12272.  
  12273.                                   This method is similar to passing by 
  12274.                                   near reference, except that a longer 
  12275.                                   address is passed. This method is slower
  12276.                                   than passing by near reference, but is 
  12277.                                   necessary when you pass data that is 
  12278.                                   outside the default data segment. (This 
  12279.                                   is an issue in BASIC or Pascal only if 
  12280.                                   you have specifically requested far 
  12281.                                   memory.)
  12282.  
  12283. Value                             Passes only the variable's value, not 
  12284.                                   its address. 
  12285.  
  12286.                                   With this method, the called routine 
  12287.                                   knows the value of the parameter but has
  12288.                                   no access to the original variable. 
  12289.                                   Changes to a value passed by a parameter
  12290.                                   have no affect on the value of the 
  12291.                                   parameter in the calling routine.
  12292.  
  12293. These different parameter-passing methods mean that you must consider the
  12294. following when programming with mixed languages:  %@NL@%
  12295. %@NL@%
  12296. %@NL@%
  12297.   ■   You need to make sure that the called routine and the calling routine
  12298.       use the same method for passing each parameter (argument). In most
  12299.       cases, you will need to check the parameter-passing defaults used by
  12300.       each language and possibly make adjustments. Each language has
  12301.       keywords or language features that allow you to change
  12302.       parameter-passing methods.%@NL@%
  12303. %@NL@%
  12304.   ■   You may want to choose a specific parameter-passing method rather than
  12305.       using the defaults of any language.%@NL@%
  12306. %@NL@%
  12307. %@NL@%
  12308. Table 12.2 summarizes the parameter-passing defaults for each language.  %@NL@%
  12309. %@NL@%
  12310. %@AB@%Table 12.2  %@AB@%Parameter-Passing Defaults%@AE@%%@AE@%
  12311.  
  12312. %@TH:  13   662 02 10 22 22 22 @%Language  Near Reference        Far Reference         By Value%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%BASIC     All                   ---                   ---C         Near arrays           Far arrays            All data except                                                      arraysFORTRAN   All (medium model)    All (large model)     With attributes%@AU@%(1)%@AE@%Pascal    %@AB@%VAR, CONST%@AE@%            %@AB@%VARS, CONSTS%@AE@%          Other parameters %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  13   662 02 10 22 22 22 @%
  12313.  
  12314. %@AU@%(1) %@AE@% When a PASCAL or C attribute is applied to a FORTRAN routine, passing
  12315. by value becomes the  default. %@NL@%
  12316. %@NL@%
  12317. %@NL@%
  12318. %@NL@%
  12319. %@2@%%@CR:C6A00120014 @%%@AB@%12.3  Compiling and Linking%@AE@%%@EH@%%@NL@%
  12320. %@NL@%
  12321. After you have written your source files and decided on a naming convention,
  12322. a calling convention, and a parameter-passing convention, you are ready to
  12323. compile and link individual modules.%@CR:C6A00120015 @%%@CR:C6A00120016 @%%@CR:C6A00120017 @%  %@NL@%
  12324. %@NL@%
  12325. %@NL@%
  12326. %@3@%%@CR:C6A00120018 @%%@AB@%12.3.1  Compiling with Correct Memory Models%@AE@%%@EH@%%@NL@%
  12327. %@NL@%
  12328. With BASIC, FORTRAN, and Pascal, no special options are required to compile
  12329. source files that are part of a mixed-language program.  %@NL@%
  12330. %@NL@%
  12331. %@AU@% With C, not all memory models are compatible with other languages. %@AE@%  %@NL@%
  12332. %@NL@%
  12333. BASIC, FORTRAN, and Pascal use only far (segmented) code addresses.
  12334. Therefore, you must use one of two techniques with C programs that call one
  12335. of these languages: compile C modules in medium, large, or huge model (using
  12336. the /A%@AI@%X%@AE@% command-line options), because these models also use far code
  12337. addresses; or apply the %@AB@%_far%@AE@% keyword to the definitions of C functions you
  12338. make public. If you use the /A%@AI@%X%@AE@% command-line option to specify medium,
  12339. large, or huge model, all your function calls become far by default. This
  12340. means you don't have to declare your functions explicitly with the %@AB@%_far%@AE@%
  12341. keyword.  %@NL@%
  12342. %@NL@%
  12343. Choice of memory model affects the default data pointer size in C and
  12344. FORTRAN, although this default can be overridden with the %@AB@%_near%@AE@% and %@AB@%_far%@AE@%
  12345. keywords. With C and FORTRAN, choice of memory model also affects whether
  12346. data objects are located in the default data segment; if a data object is
  12347. not located in the default data segment, it cannot be passed by near
  12348. reference.  %@NL@%
  12349. %@NL@%
  12350. For more information about code and data address sizes in C, refer to
  12351. Chapter 2, "Managing Memory."  %@NL@%
  12352. %@NL@%
  12353. %@NL@%
  12354. %@3@%%@CR:C6A00120019 @%%@AB@%12.3.2  Linking with Language Libraries%@AE@%%@EH@%%@NL@%
  12355. %@NL@%
  12356. In most cases, you can easily link modules compiled with different
  12357. languages. Do any of the following to ensure that all required libraries
  12358. link in the correct order:  %@NL@%
  12359. %@NL@%
  12360. %@NL@%
  12361.   ■   Put all language libraries in the same directory as the source files.%@NL@%
  12362. %@NL@%
  12363.   ■   List directories containing all needed libraries in the LIB
  12364.       environment variable.%@NL@%
  12365. %@NL@%
  12366.   ■   Let the linker prompt you for libraries.%@NL@%
  12367. %@NL@%
  12368. %@NL@%
  12369. In each of the cases above, the linker finds libraries in the order that it
  12370. requires them. If you enter the library names on the command line, make sure
  12371. you enter them in an order that allows the linker to resolve your program's
  12372. external references. Here are some points to observe when specifying
  12373. libraries on the command line:  %@NL@%
  12374. %@NL@%
  12375. %@NL@%
  12376.   ■   If you are using FORTRAN to write one of your modules, you need to
  12377.       link with the /NOD (no default libraries) option and explicitly
  12378.       specify all the libraries you need on the link command line. You can
  12379.       also specify these libraries with an automatic-response file (or batch
  12380.       file), but you cannot use a default-library search.%@NL@%
  12381. %@NL@%
  12382.   ■   If your program uses both FORTRAN and C, specify the library for the
  12383.       most recent of the two language products first. In addition, make sure
  12384.       that you choose a C-compatible library when you install FORTRAN.%@NL@%
  12385. %@NL@%
  12386.   ■   If you are listing BASIC libraries on the LINK command line, specify
  12387.       those libraries first.%@NL@%
  12388. %@NL@%
  12389. %@NL@%
  12390. The following example shows how to link two modules, %@AS@% mod1 %@AE@% and %@AS@% mod2%@AE@%, with
  12391. a user library, GRAFX, the C run-time library, LLIBCE, and the FORTRAN
  12392. run-time library, LLIBFORE:  %@NL@%
  12393. %@NL@%
  12394. %@AS@%  LINK /NOD mod1 mod2,,,GRAFX+LLIBCE+LLIBFORE%@AE@%%@NL@%
  12395. %@NL@%
  12396. %@NL@%
  12397. %@2@%%@CR:C6A00120020 @%%@AB@%12.4  C Calls to High-Level Languages%@AE@%%@EH@%%@NL@%
  12398. %@NL@%
  12399. Just as you can call Microsoft C routines from other Microsoft languages,
  12400. you can call routines written in Microsoft FORTRAN and Pascal from C. With
  12401. FORTRAN, Pascal, and C, freestanding routines can be written with no
  12402. restriction. When calling BASIC routines, however, you must write the main
  12403. program in BASIC; any subprograms are free to call one another, whether they
  12404. are written in C or BASIC.  %@NL@%
  12405. %@NL@%
  12406. For information about how to pass particular kinds of data, see Section
  12407. 12.9, "Handling Data in Mixed-Language Programming."  %@NL@%
  12408. %@NL@%
  12409. %@NL@%
  12410. %@4@%%@AB@%Executing a Mixed-Language Call%@AE@%%@EH@%%@NL@%
  12411. %@NL@%
  12412. The C interface to other languages uses standard C prototypes, with the
  12413. %@AB@%_fortran%@AE@% or %@AB@%_pascal%@AE@% keyword. Using either of these keywords causes the
  12414. routine to be called with the FORTRAN/Pascal naming and calling convention.
  12415. (The FORTRAN/Pascal convention also works for BASIC.) Here are the
  12416. recommended steps for executing a mixed-language call from C:  %@NL@%
  12417. %@NL@%
  12418. %@NL@%
  12419.   1.  Write a prototype for each mixed-language routine called. The
  12420.       prototype should declare the routine %@AB@%extern%@AE@% for the purpose of program
  12421.       documentation.%@NL@%
  12422. %@NL@%
  12423. %@STUB@%      Instead of using the %@AB@%_fortran%@AE@% or %@AB@%_pascal%@AE@% keyword, you can simply
  12424.       compile with the Pascal calling convention option (/Gc). The /Gc
  12425.       option causes all functions in the module to use the FORTRAN/Pascal
  12426.       naming and calling conventions, except where you apply the %@AB@%_cdecl%@AE@%
  12427.       keyword.%@NL@%
  12428. %@NL@%
  12429.   2.  Pass the values of variables or pointers to variables. You can obtain
  12430.       a pointer to a variable with the address-of (%@AB@%&%@AE@%) operator.%@NL@%
  12431. %@NL@%
  12432. %@STUB@%      In C, array names are always passed as pointers to the first element
  12433.       of the array; they are always passed by reference.%@NL@%
  12434. %@NL@%
  12435. %@STUB@%      The prototype you declare for your function ensures that you are
  12436.       passing the correct length address (that is, near or far). %@NL@%
  12437. %@NL@%
  12438.   3.  Issue a function call in your program as though you were calling a C
  12439.       function.%@NL@%
  12440. %@NL@%
  12441.   4.  Always compile the C module in either medium, large, or huge model, or
  12442.       use the %@AB@%_far %@AE@%keyword in your function prototype. This ensures that a
  12443.       far (intersegment) call is made to the routine. %@NL@%
  12444. %@NL@%
  12445. %@NL@%
  12446. %@NL@%
  12447. %@4@%%@AB@%Using the _fortran or _pascal Keyword%@AE@%%@EH@%%@NL@%
  12448. %@NL@%
  12449. There are two rules of syntax that apply when you use the %@AB@%_fortran%@AE@% or
  12450. %@AB@%_pascal%@AE@% keyword:%@CR:C6A00120021 @%%@CR:C6A00120022 @%  %@NL@%
  12451. %@NL@%
  12452. %@NL@%
  12453.   1.  The %@AB@%_fortran%@AE@% and %@AB@%_pascal%@AE@% keywords modify only the item immediately to
  12454.       their right.%@NL@%
  12455. %@NL@%
  12456.   2.  The %@AB@%_near%@AE@% and %@AB@%_far%@AE@% keywords can be used with the %@AB@%_fortran%@AE@% and %@AB@%_pascal%@AE@%
  12457.       keywords in prototypes. The sequences %@AB@%_fortran _far%@AE@% and %@AB@%_far _fortran%@AE@%
  12458.       are equivalent.%@NL@%
  12459. %@NL@%
  12460. %@NL@%
  12461. The keywords %@AB@%_pascal%@AE@% and %@AB@%_fortran%@AE@% have the same effect on the program; using
  12462. one or the other makes no difference except for internal program
  12463. documentation. Use %@AB@%_fortran%@AE@% to declare a FORTRAN routine, %@AB@%_pascal%@AE@% to declare
  12464. a Pascal rou-tine, and either keyword to declare a BASIC routine.  %@NL@%
  12465. %@NL@%
  12466. The following examples demonstrate the syntax rules presented above.  %@NL@%
  12467. %@NL@%
  12468. The example below declares %@AB@%func%@AE@% to be a BASIC, Pascal, or FORTRAN function
  12469. taking two %@AB@%short%@AE@% parameters and returning a %@AB@%short%@AE@% value.  %@NL@%
  12470. %@NL@%
  12471. %@AS@%  short _pascal func( short sarg1, short sarg2 );%@AE@%%@NL@%
  12472. %@NL@%
  12473. The example below declares %@AB@%func%@AE@% to be pointer to a BASIC, Pascal, or FORTRAN
  12474. routine that takes a %@AB@%long%@AE@% parameter and returns no value. The keyword %@AB@%void%@AE@%
  12475. is appropriate when the called routine is a BASIC subprogram, Pascal
  12476. procedure, or FORTRAN subroutine, since it indicates that the function
  12477. returns no value.  %@NL@%
  12478. %@NL@%
  12479. %@AS@%  void ( _fortran * func )( long larg );%@AE@%%@NL@%
  12480. %@NL@%
  12481. The example below declares %@AB@%func%@AE@% to be a %@AB@%_near%@AE@% BASIC, Pascal, or FORTRAN
  12482. routine. The routine receives a %@AB@%double%@AE@% parameter by reference (because it
  12483. expects a pointer to a %@AB@%double%@AE@%) and returns a %@AB@%short%@AE@% value.  %@NL@%
  12484. %@NL@%
  12485. %@AS@%  short _near _pascal func( _near double * darg );%@AE@%%@NL@%
  12486. %@NL@%
  12487. The example below is equivalent to the preceding example (%@AB@% _pascal _near%@AE@% is
  12488. equivalent to %@AB@%_near _pascal%@AE@%).  %@NL@%
  12489. %@NL@%
  12490. %@AS@%  short _pascal _near func( _near double * darg );%@AE@%%@NL@%
  12491. %@NL@%
  12492. %@AU@% You can make C adopt the conventions of other languages.%@AE@%  %@NL@%
  12493. %@NL@%
  12494. When you call a BASIC subprogram, you must use the FORTRAN/Pascal
  12495. conventions to make the call. When you call FORTRAN or Pascal, however, you
  12496. have a choice. You can make C adopt the conventions described in the
  12497. previous section, or you can make the FORTRAN or Pascal routine adopt the C
  12498. conventions.  %@NL@%
  12499. %@NL@%
  12500. To make a FORTRAN or Pascal routine adopt the C conventions, put the %@AB@%C%@AE@%
  12501. attribute in the heading of the routine's definition. The following example
  12502. shows the syntax for the %@AB@%C%@AE@% attribute in a FORTRAN subroutine-definition
  12503. heading:  %@NL@%
  12504. %@NL@%
  12505. %@AS@%  SUBROUTINE FFROMC [C] (N)
  12506. %@AS@%  INTEGER*2 N%@AE@%%@NL@%
  12507. %@NL@%
  12508. The following example shows the syntax for the %@AB@%C%@AE@% attribute in a Pascal
  12509. procedure-definition heading:  %@NL@%
  12510. %@NL@%
  12511. %@AS@%  PROCEDURE Pfromc( n : INTEGER ) [C];%@AE@%%@NL@%
  12512. %@NL@%
  12513. To make a C function adopt the FORTRAN/Pascal conventions, declare the
  12514. function as %@AB@%_fortran%@AE@% or %@AB@%_pascal%@AE@%. For example,  %@NL@%
  12515. %@NL@%
  12516. %@AS@%  void _pascal CfromP( int n );%@AE@%%@NL@%
  12517. %@NL@%
  12518. %@NL@%
  12519. %@2@%%@CR:C6A00120023 @%%@AB@%12.5  C Calls to BASIC%@AE@%%@EH@%%@NL@%
  12520. %@NL@%
  12521. No BASIC routine can be executed unless the main program is in BASIC,
  12522. because a BASIC routine requires the environment to be initialized in a way
  12523. that is unique to BASIC. No other language will perform this special
  12524. initialization.  %@NL@%
  12525. %@NL@%
  12526. However, your program can start up in BASIC, call a C function that does
  12527. most of the work of the program, and then call BASIC subprograms and
  12528. function procedures as needed. Figure 12.3 illustrates how to do this.  %@NL@%
  12529. %@NL@%
  12530. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  12531. %@NL@%
  12532. Follow these rules when you call BASIC from C:  %@NL@%
  12533. %@NL@%
  12534. %@NL@%
  12535.   1.  Start up in a BASIC main module. You will need to use the %@AB@%DECLARE%@AE@%
  12536.       statement to provide an interface to the C module. %@NL@%
  12537. %@NL@%
  12538.   2.  In the C module, write a prototype for the BASIC routine and include
  12539.       type information for parameters. Use either the %@AB@%_fortran%@AE@% or %@AB@%_pascal%@AE@%
  12540.       keyword to modify the routine itself.%@NL@%
  12541. %@NL@%
  12542.   3.  Make sure that all data are passed as near pointers. BASIC can pass
  12543.       data in a variety of ways but is unable to receive data in any form
  12544.       other than near reference. With near pointers, the program assumes
  12545.       that the data are in the default data segment. If you want to pass
  12546.       data that are not in the default data segment, copy the data to a
  12547.       variable in the default data segment.%@NL@%
  12548. %@NL@%
  12549.   4.  Compile the C module in medium or large model to ensure far
  12550.       (intersegment) calls.%@NL@%
  12551. %@NL@%
  12552. %@NL@%
  12553. The example below demonstrates a BASIC program that calls a C function. The
  12554. C function then calls a BASIC function that returns twice the number passed
  12555. to it and a BASIC subprogram that prints two numbers.  %@NL@%
  12556. %@NL@%
  12557. %@AS@%  ' BASIC source
  12558. %@AS@%  '
  12559. %@AS@%  ' The main program is in BASIC because of BASIC's start-up
  12560. %@AS@%  ' requirements.  The BASIC main program calls the C function
  12561. %@AS@%  ' Cprog.
  12562. %@AS@%  '
  12563. %@AS@%  ' Cprog calls the BASIC subroutine Dbl.
  12564. %@AS@%  '
  12565. %@AS@%  DEFINT A-Z
  12566. %@AS@%  DECLARE SUB Cprog CDECL()
  12567. %@AS@%  CALL Cprog
  12568. %@AS@%  END
  12569. %@AS@%  '
  12570. %@AS@%  FUNCTION Dbl(N) STATIC
  12571. %@AS@%      Dbl = N*2
  12572. %@AS@%  END FUNCTION
  12573. %@AS@%  '
  12574. %@AS@%  SUB Printnum(A,B) STATIC
  12575. %@AS@%      PRINT "The first number is ";A
  12576. %@AS@%      PRINT "The second number is ";B
  12577. %@AS@%  END SUB
  12578. %@AS@%  
  12579. %@AS@%  
  12580. %@AS@%  /* C source; compile in medium or large model */
  12581. %@AS@%  
  12582. %@AS@%  int _fortran dbl( int _near * N );
  12583. %@AS@%  void _fortran printnum( int _near * A, int _near * B );
  12584. %@AS@%  
  12585. %@AS@%  void cprog()
  12586. %@AS@%  {
  12587. %@AS@%  int a = 5;
  12588. %@AS@%  int b = 6;
  12589. %@AS@%  
  12590. %@AS@%      printf( "%d times 2 is %d\n", a, dbl( &a ) );
  12591. %@AS@%      printnum( &a, &b );
  12592. %@AS@%  }%@AE@%%@NL@%
  12593. %@NL@%
  12594. In the previous example, note that the addresses of %@AS@% a %@AE@% and %@AS@% b %@AE@% are passed,
  12595. since BASIC expects to receive addresses for parameters. This is important
  12596. because C passes parameters by value unless you use the address-of (%@AB@%&%@AE@%)
  12597. operator to obtain the address, or are passing an array. Also note that the
  12598. function prototype for %@AS@% printnum %@AE@% declares the parameters as near pointers.
  12599. The prototype causes the  %@NL@%
  12600. %@NL@%
  12601. variables to be passed by near reference. If %@AS@% a %@AE@% or %@AS@% b %@AE@% is declared as %@AB@%_far%@AE@%,
  12602. the C compiler issues a warning that you are converting a far pointer to a
  12603. near pointer and that a segment was lost in the conversion.  %@NL@%
  12604. %@NL@%
  12605. Calling and naming conventions are resolved by the %@AB@%CDECL%@AE@% keyword in the
  12606. BASIC declaration of %@AB@%Cprog%@AE@%, and by the %@AB@%_fortran%@AE@% keyword in the C declaration
  12607. of %@AS@% dbl %@AE@% and %@AS@% printnum%@AE@%.  %@NL@%
  12608. %@NL@%
  12609. %@AU@% BASIC can invoke one of your functions as part of the termination
  12610. %@AU@%procedure.%@AE@%  %@NL@%
  12611. %@NL@%
  12612. Versions of QuickBASIC later than 4.0 provide a "user entry point,"
  12613. %@AB@%B_OnExit%@AE@%, which can be called directly from C. The %@AB@%B_OnExit%@AE@% function enables
  12614. you to make sure you have performed an orderly termination. The following
  12615. code shows how to use %@AB@%B_OnExit%@AE@%.  %@NL@%
  12616. %@NL@%
  12617. %@AS@%  #include <malloc.h>    /* For declaration of _fmalloc */
  12618. %@AS@%  #include <stdlib.h>    /* For declaration of onexit_t */
  12619. %@AS@%  
  12620. %@AS@%  /* The prototype for B_OnExit declares it as a function
  12621. %@AS@%   * returning type onexit_t that takes one parameter. The
  12622. %@AS@%   * parameter is a far pointer to a function that returns
  12623. %@AS@%   * no value.
  12624. %@AS@%   */
  12625. %@AS@%  extern onexit_t _pascal _far B_OnExit( onexit_t );
  12626. %@AS@%  void TermProc( void );
  12627. %@AS@%  
  12628. %@AS@%  int * p_IntArray;
  12629. %@AS@%  
  12630. %@AS@%  void InitProc( void )
  12631. %@AS@%  {
  12632. %@AS@%      /* Allocate far space for 20-integer array */
  12633. %@AS@%  
  12634. %@AS@%      p_IntArray = (int *)_fmalloc( 20 * sizeof( int ) );
  12635. %@AS@%  
  12636. %@AS@%      /* Log termination routine (TermProc) with BASIC. */
  12637. %@AS@%  
  12638. %@AS@%      B_OnExit( TermProc );
  12639. %@AS@%  }
  12640. %@AS@%  
  12641. %@AS@%  void TermProc( void )
  12642. %@AS@%  {
  12643. %@AS@%      free( p_IntArray );    /* Release far space allocated */
  12644. %@AS@%  }                          /* previously by InitProc.     */%@AE@%%@NL@%
  12645. %@NL@%
  12646. %@NL@%
  12647. %@2@%%@CR:C6A00120024 @%%@AB@%12.6  C Calls to FORTRAN%@AE@%%@EH@%%@NL@%
  12648. %@NL@%
  12649. This section shows two examples of C-FORTRAN programs. There are two types
  12650. of subprogram calls to FORTRAN routines: calls to subroutines and calls to
  12651. functions. Functions return a value, while subroutines do not. The examples
  12652. in the next sections illustrate how to handle the difference between
  12653. function and subroutine calls.  %@NL@%
  12654. %@NL@%
  12655. %@NL@%
  12656. %@3@%%@CR:C6A00120025 @%%@AB@%12.6.1  Calling a FORTRAN Subroutine from C%@AE@%%@EH@%%@NL@%
  12657. %@NL@%
  12658. The example below demonstrates a C main module calling a FORTRAN subroutine,
  12659. %@AB@%MAXPARAM%@AE@%. This subroutine adjusts the lower of two arguments to be equal to
  12660. the higher argument.  %@NL@%
  12661. %@NL@%
  12662. %@AS@%  /* C source file - calls FORTRAN subroutine
  12663. %@AS@%   * Compile in medium or large model
  12664. %@AS@%   */
  12665. %@AS@%  
  12666. %@AS@%  extern void _fortran maxparam( int _near * I, int _near * J );
  12667. %@AS@%  
  12668. %@AS@%  /* Declare as void, because there is no return value.
  12669. %@AS@%   * FORTRAN keyword causes C to use FORTRAN/Pascal
  12670. %@AS@%   * calling and naming conventions.
  12671. %@AS@%   * Two integer parameters, passed by near reference.
  12672. %@AS@%   */
  12673. %@AS@%  
  12674. %@AS@%  main()
  12675. %@AS@%  {
  12676. %@AS@%      int a = 5;
  12677. %@AS@%      int b = 7;
  12678. %@AS@%  
  12679. %@AS@%      printf( "a = %d, b = %d", a, b );
  12680. %@AS@%      maxparam( &a, &b );
  12681. %@AS@%      printf( "a = %d, b = %d", a, b );
  12682. %@AS@%  }
  12683. %@AS@%  
  12684. %@AS@%  C   FORTRAN source file, subroutine MAXPARAM
  12685. %@AS@%  C
  12686. %@AS@%  $NOTRUNCATE
  12687. %@AS@%  
  12688. %@AS@%      SUBROUTINE MAXPARAM (I, J)
  12689. %@AS@%      INTEGER*2 I [NEAR]
  12690. %@AS@%      INTEGER*2 J [NEAR]
  12691. %@AS@%  C
  12692. %@AS@%  C   I and J received by near reference,
  12693. %@AS@%  C   because of NEAR attribute
  12694. %@AS@%  C
  12695. %@AS@%      IF (I .GT. J) THEN
  12696. %@AS@%          J = I
  12697. %@AS@%      ELSE
  12698. %@AS@%          I = J
  12699. %@AS@%      ENDIF
  12700. %@AS@%      END%@AE@%%@NL@%
  12701. %@NL@%
  12702. In the previous example, the C program adopts the naming convention and
  12703. call-ing convention of the FORTRAN subroutine. The two programs must agree
  12704. on whether parameters are to be passed by reference or by value. The
  12705. following keywords affect how the two programs interface:  %@NL@%
  12706. %@NL@%
  12707. %@NL@%
  12708.   ■   The %@AB@%_fortran%@AE@% keyword directs C to call %@AS@% maxparam %@AE@% with the FORTRAN/
  12709.       Pascal naming convention (as %@AS@% MAXPARAM%@AE@%);%@AB@% _fortran%@AE@% also directs C to
  12710.       call %@AS@% maxparam %@AE@% with the FORTRAN/Pascal calling convention.%@NL@%
  12711. %@NL@%
  12712.   ■   Since the FORTRAN subroutine %@AS@% MAXPARAM %@AE@% may alter the value of either
  12713.       parameter, both parameters must be passed by reference. In this case,
  12714.       near reference was chosen; this method is specified in C by the use of
  12715.       near pointers, and in FORTRAN by applying the %@AB@%NEAR%@AE@% keyword to the
  12716.       parameter declarations.%@NL@%
  12717. %@NL@%
  12718. %@STUB@%      Far reference could have been specified by using far pointers in C. In
  12719.       that case, you would not declare the FORTRAN subroutine %@AS@% MAXPARAM %@AE@%
  12720.       with the %@AB@%NEAR%@AE@% keyword. If you compile the FORTRAN program in medium
  12721.       model, declare %@AS@% MAXPARAM %@AE@% using the %@AB@%FAR%@AE@% keyword.%@NL@%
  12722. %@NL@%
  12723. %@NL@%
  12724. %@NL@%
  12725. %@3@%%@CR:C6A00120026 @%%@AB@%12.6.2  Calling a FORTRAN Function from C%@AE@%%@EH@%%@NL@%
  12726. %@NL@%
  12727. The example below demonstrates a C main module calling the FORTRAN  function
  12728. %@AS@% fact%@AE@%. This function returns the factorial of an integer value.  %@NL@%
  12729. %@NL@%
  12730. %@AS@%  /* C source file - calls FORTRAN function.
  12731. %@AS@%   * Compile in medium or large model.
  12732. %@AS@%   */
  12733. %@AS@%  
  12734. %@AS@%  int _fortran fact( int N );
  12735. %@AS@%  
  12736. %@AS@%  /* FORTRAN keyword causes C to use FORTRAN/Pascal
  12737. %@AS@%   * calling and naming conventions.
  12738. %@AS@%   * Integer parameter passed by value.
  12739. %@AS@%   */
  12740. %@AS@%  
  12741. %@AS@%  main()
  12742. %@AS@%  {
  12743. %@AS@%   int x = 3;
  12744. %@AS@%   int y = 4;
  12745. %@AS@%  
  12746. %@AS@%      printf( "The factorial of x   is %4d", fact( x ) );
  12747. %@AS@%      printf( "The factorial of y   is %4d", fact( y ) );
  12748. %@AS@%      printf( "The factorial of x+y is %4d", fact( x + y ) );
  12749. %@AS@%  }%@AE@%%@NL@%
  12750. %@NL@%
  12751. %@AS@%  C   FORTRAN source file - factorial function
  12752. %@AS@%  C
  12753. %@AS@%  $NOTRUNCATE
  12754. %@AS@%      INTEGER*2 FUNCTION FACT (N)
  12755. %@AS@%      INTEGER*2 N [VALUE]
  12756. %@AS@%  C
  12757. %@AS@%  C   N is received by value, because of VALUE attribute
  12758. %@AS@%  C
  12759. %@AS@%         INTEGER*2 I
  12760. %@AS@%         FACT = 1
  12761. %@AS@%         DO 100 I = 1, N
  12762. %@AS@%             FACT = FACT * I
  12763. %@AS@%  100    CONTINUE
  12764. %@AS@%         RETURN
  12765. %@AS@%         END%@AE@%%@NL@%
  12766. %@NL@%
  12767. In the example above, the C program adopts the naming convention and calling
  12768. convention of the FORTRAN subroutine. Both programs must agree on whether
  12769. parameters are passed by reference or by value. Note that the C program
  12770. passes the parameters by value rather than by reference. Passing parameters
  12771. by value is the default for C. To accept parameters passed by value, the
  12772. keyword %@AB@%VALUE%@AE@% is used in the declaration of %@AS@% N %@AE@% in the FORTRAN function. The
  12773. %@AB@%_fortran%@AE@% keyword directs C to call %@AS@% fact %@AE@% with the FORTRAN/Pascal naming
  12774. convention (as %@AS@% FACT%@AE@%); %@AB@%_fortran%@AE@% also directs C to call %@AS@% fact %@AE@% with the
  12775. FORTRAN/Pascal calling convention.  %@NL@%
  12776. %@NL@%
  12777. When passing a parameter that should not be changed, pass the parameter by
  12778. value. Passing by value is the default method in C and is specified in
  12779. FORTRAN by applying the %@AB@%VALUE%@AE@% attribute to the parameter declaration.  %@NL@%
  12780. %@NL@%
  12781. %@NL@%
  12782. %@2@%%@CR:C6A00120027 @%%@AB@%12.7  C Calls to Pascal%@AE@%%@EH@%%@NL@%
  12783. %@NL@%
  12784. This section shows two examples of C-Pascal programs. There are two types of
  12785. subprogram calls to Pascal routines: calls to procedures and calls to
  12786. functions. Functions return a value, while procedures do not. The examples
  12787. in the next sections illustrate how to handle the difference between
  12788. function and procedure calls.  %@NL@%
  12789. %@NL@%
  12790. %@NL@%
  12791. %@3@%%@CR:C6A00120028 @%%@AB@%12.7.1  Calling a Pascal Procedure from C%@AE@%%@EH@%%@NL@%
  12792. %@NL@%
  12793. The following example demonstrates a C main module calling a Pascal
  12794. procedure, %@AS@% maxparam%@AE@%. This procedure adjusts the lower of two arguments to
  12795. be equal to the higher argument.  %@NL@%
  12796. %@NL@%
  12797. %@AS@%  /* C source file - calls Pascal procedure.
  12798. %@AS@%   * Compile in medium or large model.
  12799. %@AS@%   */
  12800. %@AS@%  
  12801. %@AS@%  void _pascal maxparam( int _near * a, int _near * b );
  12802. %@AS@%  
  12803. %@AS@%  /* Declare as void, because there is no return value.
  12804. %@AS@%   * The _pascal keyword causes C to use FORTRAN/Pascal
  12805. %@AS@%   * calling and naming conventions.
  12806. %@AS@%   * Two integer params, passed by near reference.
  12807. %@AS@%   */
  12808. %@AS@%  
  12809. %@AS@%  main()
  12810. %@AS@%  {
  12811. %@AS@%      int a = 5;
  12812. %@AS@%      int b = 7;
  12813. %@AS@%  
  12814. %@AS@%      printf( "a = %d, b = %d", a, b );
  12815. %@AS@%      maxparam( &a, &b );
  12816. %@AS@%      printf( "a = %d, b = %d", a, b );
  12817. %@AS@%  }
  12818. %@AS@%  
  12819. %@AS@%  { Pascal source code - Maxparam procedure. }
  12820. %@AS@%  
  12821. %@AS@%  MODULE Psub;
  12822. %@AS@%  PROCEDURE Maxparam( VAR a:INTEGER; VAR b:INTEGER );
  12823. %@AS@%  
  12824. %@AS@%  { Two integer parameters are received by near reference. }
  12825. %@AS@%  { Near reference is specified with the VAR keyword. }
  12826. %@AS@%  
  12827. %@AS@%      BEGIN
  12828. %@AS@%          if a > b THEN
  12829. %@AS@%              b := a
  12830. %@AS@%          ELSE
  12831. %@AS@%              a := b
  12832. %@AS@%      END;
  12833. %@AS@%  END.%@AE@%%@NL@%
  12834. %@NL@%
  12835. In the example above, the C program adopts the Pascal naming convention and
  12836. calling convention. Both programs must agree on whether parameters are
  12837. passed by reference or by value; the following keywords affect the
  12838. conventions:  %@NL@%
  12839. %@NL@%
  12840. %@NL@%
  12841.   ■   The %@AB@%_pascal%@AE@% keyword directs C to call %@AS@% Maxparam %@AE@% with the FORTRAN/
  12842.       Pascal naming convention (as %@AS@% MAXPARAM%@AE@%); %@AB@%_pascal%@AE@% also directs C to
  12843.       call %@AS@%Maxparam %@AE@% with the FORTRAN/Pascal calling convention.%@NL@%
  12844. %@NL@%
  12845.   ■   Since the procedure %@AS@% Maxparam %@AE@% can alter the value of either
  12846.       parameter, both parameters must be passed by reference. In this case,
  12847.       near reference is used; this method is specified in C by the use of
  12848.       near pointers, and in Pascal with the %@AB@%VAR%@AE@% keyword.%@NL@%
  12849. %@NL@%
  12850. %@STUB@%      Far reference could have been specified by using far pointers in C. To
  12851.       specify far reference in Pascal, use the %@AB@%VARS%@AE@% keyword instead of %@AB@%VAR%@AE@%.%@NL@%
  12852. %@NL@%
  12853. %@NL@%
  12854. %@NL@%
  12855. %@3@%%@CR:C6A00120029 @%%@AB@%12.7.2  Calling a Pascal Function from C%@AE@%%@EH@%%@NL@%
  12856. %@NL@%
  12857. The example below demonstrates a C main module calling Pascal function %@AS@%
  12858. %@AS@%fact%@AE@%. This function returns the factorial of an integer value.  %@NL@%
  12859. %@NL@%
  12860. %@AS@%  /* C source file - calls Pascal function.
  12861. %@AS@%   * Compile in medium or large model.
  12862. %@AS@%   */
  12863. %@AS@%  
  12864. %@AS@%  int _pascal fact(int n);
  12865. %@AS@%  
  12866. %@AS@%  /* PASCAL keyword causes C to use FORTRAN/Pascal
  12867. %@AS@%   * calling and naming conventions.
  12868. %@AS@%   * Integer parameter passed by value.
  12869. %@AS@%   */
  12870. %@AS@%  
  12871. %@AS@%  main()
  12872. %@AS@%  {
  12873. %@AS@%      int x = 3;
  12874. %@AS@%      int y = 4;
  12875. %@AS@%  
  12876. %@AS@%      printf( "The factorial of x   is %4d", fact( x ) );
  12877. %@AS@%      printf( "The factorial of y   is %4d", fact( y ) );
  12878. %@AS@%      printf( "The factorial of x+y is %4d", fact( x + y ) );
  12879. %@AS@%  }
  12880. %@AS@%  
  12881. %@AS@%  { Pascal source code - factorial function. }
  12882. %@AS@%  
  12883. %@AS@%  MODULE Pfun;
  12884. %@AS@%  FUNCTION Fact (n : INTEGER) : INTEGER;
  12885. %@AS@%  
  12886. %@AS@%  {Integer parameters received by value, the Pascal default. }
  12887. %@AS@%  
  12888. %@AS@%      BEGIN
  12889. %@AS@%          Fact := 1;
  12890. %@AS@%          WHILE n > 0 DO
  12891. %@AS@%              BEGIN
  12892. %@AS@%                  Fact := Fact * n;
  12893. %@AS@%                  n := n - 1;          {Parameter n modified.}
  12894. %@AS@%              END;
  12895. %@AS@%      END;
  12896. %@AS@%  END.%@AE@%%@NL@%
  12897. %@NL@%
  12898. In the example above, the C program adopts the Pascal naming convention and
  12899. calling convention. Both programs must agree on whether parameters are
  12900. passed by reference or by value. The %@AB@%_pascal%@AE@% keyword directs C to call %@AS@% fact
  12901. %@AS@%%@AE@% with the FORTRAN/Pascal naming convention (as %@AS@% FACT%@AE@%); %@AB@% _pascal%@AE@% also directs
  12902. C to call %@AS@%fact %@AE@% with the FORTRAN/Pascal calling convention.  %@NL@%
  12903. %@NL@%
  12904. The Pascal function %@AS@% fact %@AE@% should receive a parameter by value. Otherwise,
  12905. the Pascal function will corrupt the parameter's value in the calling
  12906. module. Passing by value is the default method for both C and Pascal.  %@NL@%
  12907. %@NL@%
  12908. %@NL@%
  12909. %@2@%%@CR:C6A00120030 @%%@AB@%12.8  C Calls to Assembly Language%@AE@%%@EH@%%@NL@%
  12910. %@NL@%
  12911. In Microsoft C, Version 6.0, you can write assembly-language programs either
  12912. by using the in-line assembler or by creating a stand-alone module using the
  12913. Microsoft Macro Assembler (MASM). If you use the in-line assembler, you do
  12914. not need to take any special precautions other than those outlined in
  12915. Chapter 3, "Using the In-Line Assembler." This section explains the
  12916. techniques for interfacing your assembly-language routines with your C
  12917. program.  %@NL@%
  12918. %@NL@%
  12919. When deciding whether to use the in-line assembler or MASM, there are
  12920. several considerations. Here is a list of advantages MASM provides over the
  12921. in-line assembler:  %@NL@%
  12922. %@NL@%
  12923. %@NL@%
  12924.   ■   MASM supports declaration of data in MASM format; in-line assembly
  12925.       does not.%@NL@%
  12926. %@NL@%
  12927.   ■   MASM has a more powerful macro capability than in-line assembly.%@NL@%
  12928. %@NL@%
  12929.   ■   Modules written for MASM can be interfaced more easily with modules
  12930.       written in more than one Microsoft high-level language.%@NL@%
  12931. %@NL@%
  12932.   ■   MASM assembles large assembly-language programs more quickly than the
  12933.       in-line assembler.%@NL@%
  12934. %@NL@%
  12935.   ■   MASM supports assembly-language code written prior to the existence of
  12936.       the in-line assembler.%@NL@%
  12937. %@NL@%
  12938.   ■   MASM error messages and warnings are more complete than those of the
  12939.       in-line assembler.%@NL@%
  12940. %@NL@%
  12941. %@NL@%
  12942. The in-line assembler is far more efficient for some assembly-language
  12943. programming tasks. Here are some of the benefits of the in-line assembler:  %@NL@%
  12944. %@NL@%
  12945. %@NL@%
  12946.   ■   You can do spot optimizations by including short sections of
  12947.       assemblylanguage code in your C programs with the in-line assembler.%@NL@%
  12948. %@NL@%
  12949.   ■   Code written in in-line assembler does not necessarily incur the
  12950.       overhead of a function call; code assembled using MASM always does.%@NL@%
  12951. %@NL@%
  12952.   ■   You can include in-line assembly code in your C source files; code
  12953.       written for MASM must be in a separate file.%@NL@%
  12954. %@NL@%
  12955. %@NL@%
  12956. %@NL@%
  12957. %@3@%%@CR:C6A00120031 @%%@AB@%12.8.1  Writing the Assembly-Language Procedure%@AE@%%@EH@%%@NL@%
  12958. %@NL@%
  12959. You must write your assembly-language procedure so that it uses the same
  12960. call-ing conventions and naming conventions as your C program. If you follow
  12961. these conventions, you will be able to write recursive procedures
  12962. (procedures that call themselves), and you will be able to use the CodeView
  12963. debugger to locate errors in the code.  %@NL@%
  12964. %@NL@%
  12965. ────────────────────────────────────────────────────────────────────────────%@NL@%
  12966. NOTE
  12967.  
  12968. %@AI@%This section discusses only the simplified segment directives provided with
  12969. %@AI@%the Microsoft Macro Assembler, version 5.0. If you are using a version prior
  12970. %@AI@%to 5.0, you have to specify complete %@AI@%SEGMENT %@AE@%%@AI@%directives.%@AE@%%@AE@%%@NL@%
  12971. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  12972. %@NL@%
  12973. The standard assembly-language interface method consists of these steps:  %@NL@%
  12974. %@NL@%
  12975. %@NL@%
  12976.   1.  Setting up the procedure%@NL@%
  12977. %@NL@%
  12978.   2.  Entering the procedure%@NL@%
  12979. %@NL@%
  12980.   3.  Allocating local data (optional)%@NL@%
  12981. %@NL@%
  12982.   4.  Preserving register values%@NL@%
  12983. %@NL@%
  12984.   5.  Accessing parameters%@NL@%
  12985. %@NL@%
  12986.   6.  Returning a value (optional)%@NL@%
  12987. %@NL@%
  12988.   7.  Exiting the procedure%@NL@%
  12989. %@NL@%
  12990. %@NL@%
  12991. The next sections describe each of these steps in detail.  %@NL@%
  12992. %@NL@%
  12993. %@NL@%
  12994. %@3@%%@CR:C6A00120032 @%%@AB@%12.8.2  Setting Up the Procedure%@AE@%%@EH@%%@NL@%
  12995. %@NL@%
  12996. The linker cannot combine the assembly-language procedure with the C program
  12997. unless you define compatible segments and declare the procedure properly.
  12998. Perform the following steps to set up the procedure:  %@NL@%
  12999. %@NL@%
  13000. %@NL@%
  13001.   1.  Use the %@AB@%.MODEL%@AE@% directive at the beginning of the source file; this
  13002.       directive automatically causes the appropriate kind of returns to be
  13003.       generated (%@AB@%NEAR%@AE@% for tiny, small or compact models, %@AB@%FAR%@AE@% for medium,
  13004.       large, or huge models).%@NL@%
  13005. %@NL@%
  13006. %@STUB@%      If you are using a version of MASM prior to 5.0, declare the procedure
  13007.       %@AB@%NEAR%@AE@% for small or compact model, %@AB@%FAR%@AE@% for medium, large, or huge
  13008.       models.%@NL@%
  13009. %@NL@%
  13010.   2.  Use the simplified segment directives %@AB@%.CODE%@AE@% and %@AB@%.DATA%@AE@% to declare the
  13011.       code and data segments.%@NL@%
  13012. %@NL@%
  13013. %@STUB@%      If you are using a version of MASM prior to 5.0, declare the segments
  13014.       using the %@AB@%SEGMENT%@AE@%, %@AB@%GROUP%@AE@%, and %@AB@%ASSUME%@AE@% directives. These directives are
  13015.       described in the %@AI@%Microsoft%@AE@% %@AI@%Macro Assembler%@AE@% %@AI@%Reference %@AE@%.%@NL@%
  13016. %@NL@%
  13017.   3.  Use the %@AB@%PUBLIC %@AE@%directive to declare the procedure label public. This
  13018.       declaration makes the procedure visible to other modules. Also declare
  13019.       any data you want to make public as %@AB@%PUBLIC%@AE@%.%@NL@%
  13020. %@NL@%
  13021.   4.  Use the %@AB@%EXTRN %@AE@%directive to declare any global data or procedures
  13022.       accessed by the routine as external. The safest way to use%@AB@% EXTRN%@AE@% is to
  13023.       place the directive outside any segment definition; however, place
  13024.       near data inside the data segment.%@NL@%
  13025. %@NL@%
  13026.   5.  Observe the C naming convention; precede all procedure names and
  13027.       global data names with an underscore.%@NL@%
  13028. %@NL@%
  13029. %@NL@%
  13030. %@NL@%
  13031. %@3@%%@CR:C6A00120033 @%%@AB@%12.8.3  Entering the Procedure%@AE@%%@EH@%%@NL@%
  13032. %@NL@%
  13033. When you enter the procedure, in most cases you will want to set up a "stack
  13034. frame." This allows you to access parameters passed on the stack and to
  13035. allocate local data on the stack. You do not need to set up the stack frame
  13036. if your procedure accepts no arguments and does not use the stack.  %@NL@%
  13037. %@NL@%
  13038. To set up the stack frame, issue the instructions:  %@NL@%
  13039. %@NL@%
  13040. %@AS@%  push    bp
  13041. %@AS@%  mov     bp,sp%@AE@%%@NL@%
  13042. %@NL@%
  13043. This sequence establishes BP as the frame pointer. You cannot use SP for
  13044. this purpose because it is not an index or base register. Also, the value of
  13045. SP may change as more data are pushed onto the stack. However, the value of
  13046. the base register BP remains constant for the life of the procedure unless
  13047. your program changes it, so each parameter can be addressed as an offset
  13048. from BP.  %@NL@%
  13049. %@NL@%
  13050. The instruction sequence above preserves the value of BP, since it will be
  13051. needed in the calling procedure as soon as your assembly-language procedure
  13052. returns. It then transfers the value in SP to BP to establish a stack frame
  13053. on entry to the procedure.  %@NL@%
  13054. %@NL@%
  13055. %@NL@%
  13056. %@3@%%@CR:C6A00120034 @%%@AB@%12.8.4  Allocating Local Data%@AE@%%@EH@%%@NL@%
  13057. %@NL@%
  13058. Your assembly-language procedure can use the same technique for allocating
  13059. temporary storage for local data that is used by high-level languages. To
  13060. set up local data space, decrease the contents of SP just after setting up
  13061. the stack frame. (To ensure correct execution, always increase or decrease
  13062. SP by an even number.) Decreasing SP reserves space on the stack for local
  13063. data. You must restore the space at the end of the procedure as follows:  %@NL@%
  13064. %@NL@%
  13065. %@AS@%  push    bp
  13066. %@AS@%  mov     bp,sp
  13067. %@AS@%  sub     sp,space%@AE@%%@NL@%
  13068. %@NL@%
  13069. In the example above, %@AS@% space %@AE@% is the total size in bytes of the local data
  13070. you want to allocate. Local variables are then accessed as fixed negative
  13071. displacements from BP.  %@NL@%
  13072. %@NL@%
  13073. In the following example, the entry sequence establishes a stack frame and
  13074. allocates temporary local storage for two words (4 bytes) of data. Later in
  13075. the example, the program accesses the local storage, initializing both to 0.
  13076. %@NL@%
  13077. %@NL@%
  13078. %@AS@%  push    bp          ; Save old stack frame.
  13079. %@AS@%  mov     bp,sp       ; Set up new stack frame.
  13080. %@AS@%  sub     sp,4        ; Allocate 4 bytes of local storage.
  13081. %@AS@%  .
  13082. %@AS@%  .
  13083. %@AS@%  .
  13084. %@AS@%  mov     WORD PTR [bp-2],0
  13085. %@AS@%  mov     WORD PTR [bp-4],0%@AE@%%@NL@%
  13086. %@NL@%
  13087. Note that local variables are also called dynamic, stack, or automatic
  13088. variables.  %@NL@%
  13089. %@NL@%
  13090. %@NL@%
  13091. %@3@%%@CR:C6A00120035 @%%@AB@%12.8.5  Preserving Register Values%@AE@%%@EH@%%@NL@%
  13092. %@NL@%
  13093. A procedure called from C should preserve the values of SI, DI, SS, and DS
  13094. (in addition to BP, which is already saved). You should push any register
  13095. value that your procedure modifies onto the stack after setting up the stack
  13096. frame and allocating local storage, but prior to entering the main body of
  13097. the procedure. Registers that your procedure does not alter need not be
  13098. preserved.  %@NL@%
  13099. %@NL@%
  13100. ────────────────────────────────────────────────────────────────────────────%@NL@%
  13101. %@AU@%WARNING%@AE@%%@NL@%
  13102. %@NL@%
  13103. Routines that your assembly-language procedure calls must not alter the SI,
  13104. DI, SS, DS, or BP registers. If they do, and you have not preserved the
  13105. registers, they can corrupt the calling program's register variables,
  13106. segment registers, and stack frame, causing program failure. If your
  13107. procedure modifies the direction flag using the %@AI@%STD%@AE@%%@AB@% %@AE@%or %@AI@%CLD %@AE@%instructions, you
  13108. must preserve the flags register.%@NL@%
  13109. ────────────────────────────────────────────────────────────────────────────%@NL@%
  13110. %@NL@%
  13111. The example below shows an entry sequence that sets up a stack frame,
  13112. allocates 4 bytes of local data space on the stack, then preserves the SI,
  13113. DI, and flags registers.  %@NL@%
  13114. %@NL@%
  13115. %@AS@%  push    bp        ; Save caller's stack frame.
  13116. %@AS@%  mov     bp,sp     ; Establish new stack frame.
  13117. %@AS@%  sub     sp,4      ; Allocate local data space.
  13118. %@AS@%  push    si        ; Save SI and DI registers.
  13119. %@AS@%  push    di
  13120. %@AS@%  pushf             ; Save the flags register.
  13121. %@AS@%  .
  13122. %@AS@%  .
  13123. %@AS@%  .%@AE@%%@NL@%
  13124. %@NL@%
  13125. In the example above, you must exit the procedure with the following code:  %@NL@%
  13126. %@NL@%
  13127. %@AS@%  popf              ; Restore the flags register.
  13128. %@AS@%  pop    di         ; Restore the old value in the DI 
  13129. %@AS@%                      register.
  13130. %@AS@%  pop    si         ; Restore the old value in the SI 
  13131. %@AS@%                      register.
  13132. %@AS@%  mov    sp,bp      ; Restore the stack pointer.
  13133. %@AS@%  pop    bp         ; Restore the frame pointer.
  13134. %@AS@%  ret               ; Return to the calling routine.%@AE@%%@NL@%
  13135. %@NL@%
  13136. If you do not issue the instructions above in the order shown, you will
  13137. place incorrect data in registers. Follow the rules below when restoring the
  13138. calling program's registers, stack pointer, and frame pointer:  %@NL@%
  13139. %@NL@%
  13140. %@NL@%
  13141.   ■   Pop all registers that you preserve in the reverse order from which
  13142.       they were pushed onto the stack. So, in the example above, SI and DI
  13143.       are pushed, and DI and SI are popped.%@NL@%
  13144. %@NL@%
  13145.   ■   Restore the stack pointer by transferring the value of BP into SP
  13146.       before restoring the value of the frame pointer.%@NL@%
  13147. %@NL@%
  13148.   ■   Always restore the frame pointer last.%@NL@%
  13149. %@NL@%
  13150. %@NL@%
  13151. %@NL@%
  13152. %@3@%%@CR:C6A00120036 @%%@AB@%12.8.6  Accessing Parameters%@AE@%%@EH@%%@NL@%
  13153. %@NL@%
  13154. Once you have established the frame pointer, allocated local storage (if
  13155. required), and pushed any registers that need to be preserved, you can write
  13156. the main body of the procedure. Figure 12.4 shows how functions that observe
  13157. the C calling convention use the stack frame.  %@NL@%
  13158. %@NL@%
  13159. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  13160. %@NL@%
  13161. The stack frame for the assembly-language procedure shown in Figure 12.4 is
  13162. established by the following:  %@NL@%
  13163. %@NL@%
  13164. %@NL@%
  13165.   1.  The calling program pushes each of the parameters onto the stack,
  13166.       after which SP points to the last parameter pushed.%@NL@%
  13167. %@NL@%
  13168.   2.  The calling program issues a %@AB@%CALL%@AE@% instruction, which causes the return
  13169.       address (the place in the calling program to which control will
  13170.       ultimately return) to be placed on the stack. This address can be
  13171.       either two bytes long (for near calls) or four bytes long (for far
  13172.       calls). SP now points to this address.%@NL@%
  13173. %@NL@%
  13174.   3.  The first instruction of the called procedure saves the old value of
  13175.       BP, with the instruction %@AS@% push bp%@AE@%. SP now points to the saved copy of
  13176.       BP.%@NL@%
  13177. %@NL@%
  13178.   4.  BP is used to hold the current value of SP, with the instruction %@AS@% mov
  13179. %@AS@%      bp%@AE@%,%@AS@%sp%@AE@%. BP therefore now points to the old value of BP (saved on the
  13180.       stack).%@NL@%
  13181. %@NL@%
  13182.   5.  While BP remains constant throughout the procedure, SP is often
  13183.       decreased to provide room on the stack for local data or saved
  13184.       registers.%@NL@%
  13185. %@NL@%
  13186. %@NL@%
  13187. In general, the displacement (from BP) for a parameter %@AI@%x%@AE@% is equal to the
  13188. size of return address plus 2 plus the total size of parameters between %@AI@%x%@AE@%
  13189. and BP.  %@NL@%
  13190. %@NL@%
  13191. To calculate the size of parameters between %@AI@%x%@AE@% and BP, you must start with
  13192. the rightmost parameter because C pushes parameters from right to left. For
  13193. example, consider a %@AB@%FAR%@AE@% procedure that has one argument of type %@AB@%int%@AE@% (two
  13194. bytes). The displacement of the parameter is  %@NL@%
  13195. %@NL@%
  13196. %@AS@%  Argument's displacement = size of far return address + 2
  13197. %@AS@%                          = 4 + 2
  13198. %@AS@%                          = 6%@AE@%%@NL@%
  13199. %@NL@%
  13200. The argument can thus be loaded into BP with the following instruction:  %@NL@%
  13201. %@NL@%
  13202. %@AS@%  mov    bx,[bp+6]%@AE@%%@NL@%
  13203. %@NL@%
  13204. Once you determine the displacement of each parameter, you can use %@AB@%EQU
  13205. %@AB@%%@AE@%directives or structures to refer to the parameter with a single identifier
  13206. name in your assembly source code. For example, you can use a more readable
  13207. name to reference the parameter at %@AS@% BP+6 %@AE@% if you put the following statement
  13208. at the beginning of the assembly source file:  %@NL@%
  13209. %@NL@%
  13210. %@AS@%  Arg1    EQU    [bp+6]%@AE@%%@NL@%
  13211. %@NL@%
  13212. You can then refer to the first parameter in your source as %@AS@% Arg1 %@AE@% in any
  13213. instruction. Use of this feature is optional.  %@NL@%
  13214. %@NL@%
  13215. For far (segmented) addresses, Microsoft C pushes the segment address before
  13216. pushing the offset address. When pushing arguments larger than two bytes,
  13217. high-order words are always pushed before low-order words, and parameters
  13218. larger than two bytes are stored on the stack in most-significant,
  13219. least-significant order.  %@NL@%
  13220. %@NL@%
  13221. This standard for pushing segment addresses before pushing offset addresses
  13222. facilitates the use of the assembly-language instructions %@AB@%LDS%@AE@% (load data
  13223. segment) and %@AB@%LES%@AE@% (load extra segment).  %@NL@%
  13224. %@NL@%
  13225. %@NL@%
  13226. %@3@%%@CR:C6A00120037 @%%@AB@%12.8.7  Returning a Value%@AE@%%@EH@%%@NL@%
  13227. %@NL@%
  13228. Your assembly-language procedure can return a value to a C calling program.
  13229. All return values of four bytes or less are passed in registers. Far
  13230. pointers to return values larger than four bytes are returned in the DX and
  13231. AX registers. The DX register contains the segment address; the AX register
  13232. contains the offset relative to the segment contained in DX.  %@NL@%
  13233. %@NL@%
  13234. Table 12.3 shows the register conventions for returning simple data types to
  13235. a C program.  %@NL@%
  13236. %@NL@%
  13237. %@AB@%Table   %@AB@%12.3 Register Conventions for Simple Return Values%@AE@%%@AE@%
  13238.  
  13239. %@TH:  13   641 02 34 42 @%Data Type                         Registers%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%char%@AE@%                              AL%@AB@%int%@AE@%, %@AB@%short%@AE@%, %@AB@%_near *%@AE@%               AX%@AB@%long%@AE@%, %@AB@%_far *%@AE@%                      High-order portion (or segment address)                                   in DX;                                   low-order portion (or offset address) in                                  AX%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  13   641 02 34 42 @%
  13240.  
  13241. %@AU@% Your procedures can return structures.%@AE@%  %@NL@%
  13242. %@NL@%
  13243. To return a structure from a procedure that uses the C calling convention,
  13244. you must copy the structure to a global variable, then return a pointer to
  13245. that variable in the AX register (DX:AX, if you compiled in compact, large,
  13246. or huge model).  %@NL@%
  13247. %@NL@%
  13248. Procedures that use the FORTRAN/Pascal calling convention return structures
  13249. similarly, with the following exceptions:  %@NL@%
  13250. %@NL@%
  13251. %@NL@%
  13252.   ■   The calling program allocates space for the return value on the stack.%@NL@%
  13253. %@NL@%
  13254.   ■   The calling program passes a pointer to the location where the return
  13255.       value is to be placed in a hidden parameter.%@NL@%
  13256. %@NL@%
  13257.   ■   Instead of copying your structure into a global data item, you copy it
  13258.       into the location pointed to by the hidden parameter.%@NL@%
  13259. %@NL@%
  13260.   ■   You must still return the pointer to that location in the AX register
  13261.       (or DX:AX for far data models).%@NL@%
  13262. %@NL@%
  13263. %@NL@%
  13264. %@AU@% You can return floating-point values from your procedures.%@AE@%  %@NL@%
  13265. %@NL@%
  13266. Procedures that use the C calling convention and return type %@AB@%float%@AE@% or type
  13267. %@AB@%double%@AE@% must always copy their return values into the global variable %@AB@%fac%@AE@%. To
  13268. return floating-point values from procedures declared with the
  13269. FORTRAN/Pascal calling convention, you must return the result on the stack,
  13270. just as you would a structure.  %@NL@%
  13271. %@NL@%
  13272. To return a value of type %@AB@%long double%@AE@%, you must place the value on the
  13273. %@AB@%NDP%@AE@%(80%@AI@%x%@AE@%87) stack using the %@AB@%FLD %@AE@%instruction. The C run-time math routines
  13274. guarantee that the only value on the %@AB@%NDP %@AE@%stack is a return value; your
  13275. routines must observe the same rule.  %@NL@%
  13276. %@NL@%
  13277. %@NL@%
  13278. %@3@%%@CR:C6A00120038 @%%@AB@%12.8.8  Exiting the Procedure%@AE@%%@EH@%%@NL@%
  13279. %@NL@%
  13280. Before you exit your assembly-language procedure, you must perform several
  13281. steps to restore the calling program's environment. Some of these steps are
  13282. dependent on actions you took in allocating space for local variables and
  13283. preserving registers.  %@NL@%
  13284. %@NL@%
  13285. You must follow these steps (if appropriate to your procedure) in the order
  13286. shown:  %@NL@%
  13287. %@NL@%
  13288. %@NL@%
  13289.   1.  If you saved any of the registers SS, DS, SI, or DI, they must be
  13290.       popped off the stack in the reverse order from which they were saved.
  13291.       If you pop these registers in any other order, your program will
  13292.       behave incorrectly.%@NL@%
  13293. %@NL@%
  13294.   2.  If you allocated local data space at the beginning of the procedure,
  13295.       you must restore SP with the instruction %@AS@% mov s %@AE@% p %@AS@% ,bp%@AE@%.%@NL@%
  13296. %@NL@%
  13297.   3.  Restore BP with the instruction %@AS@% pop bp%@AE@%. This step is always
  13298.       necessary.%@NL@%
  13299. %@NL@%
  13300.   4.  Return to the calling program by issuing the %@AB@%ret%@AE@% instruction.%@NL@%
  13301. %@NL@%
  13302. %@NL@%
  13303. The following example shows the simplest possible entry and exit sequence.
  13304. In the entry sequence, no registers are saved and no local data space is
  13305. allocated.  %@NL@%
  13306. %@NL@%
  13307. %@AS@%  push   bp
  13308. %@AS@%  mov    bp,sp   ; Set up the new stack frame.
  13309. %@AS@%  .
  13310. %@AS@%  .
  13311. %@AS@%  .
  13312. %@AS@%  pop    bp      ; Restore the caller's stack frame.
  13313. %@AS@%  ret%@AE@%%@NL@%
  13314. %@NL@%
  13315. The following example shows an entry and exit sequence for a procedure that
  13316. saves SI and DI and allocates local data space on the stack.  %@NL@%
  13317. %@NL@%
  13318. %@AS@%  push   bp
  13319. %@AS@%  mov    bp,sp   ; Establish local stack frame.
  13320. %@AS@%  sub    sp,4    ; Allocate space for local data.
  13321. %@AS@%  push   si      ; Preserve the SI and DI registers.
  13322. %@AS@%  push   di
  13323. %@AS@%  .
  13324. %@AS@%  .
  13325. %@AS@%  .
  13326. %@AS@%  pop    di      ; Pop saved registers.
  13327. %@AS@%  pop    si
  13328. %@AS@%  mov    sp,bp   ; Free local data space.
  13329. %@AS@%  pop    bp      ; Restore old stack frame.
  13330. %@AS@%  ret%@AE@%%@NL@%
  13331. %@NL@%
  13332. %@NL@%
  13333. %@2@%%@CR:C6A00120039 @%%@AB@%12.9  Handling Data in Mixed-Language Programming%@AE@%%@EH@%%@NL@%
  13334. %@NL@%
  13335. This section contains detailed information about naming and calling
  13336. conventions in a mixed-language program. It also describes how various
  13337. languages represent strings, numerical data, arrays, and logical data.  %@NL@%
  13338. %@NL@%
  13339. %@NL@%
  13340. %@3@%%@CR:C6A00120040 @%%@AB@%12.9.1  Default Naming and Calling Conventions%@AE@%%@EH@%%@NL@%
  13341. %@NL@%
  13342. Each language has its own default naming and calling conventions (Table
  13343. 12.4).  %@NL@%
  13344. %@NL@%
  13345. %@AB@%Table 12.4  %@AB@%Default Naming and Calling Conventions%@AE@%%@AE@%
  13346.  
  13347. %@TH:  15   723 03 10 19 19 28 @%          Calling            Naming             Parameter Language  Convention         Convention         Passing%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%BASIC     FORTRAN/Pascal     Case insensitive   Near referenceC         C                  Case sensitive     Value (scalar variables),                                                 reference (arrays and                                                 pointers)FORTRAN   FORTRAN/Pascal     Case insensitive   ReferencePascal    FORTRAN/Pascal     Case insensitive   Value%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  15   723 03 10 19 19 28 @%
  13348.  
  13349. %@NL@%
  13350. %@4@%%@AB@%BASIC Conventions%@AE@%%@EH@%%@NL@%
  13351. %@NL@%
  13352. When you call BASIC routines from C, you must pass all arguments by near
  13353. reference (near pointer). You can modify the conventions observed by BASIC
  13354. routines that interface with C functions by using the %@AB@%DECLARE%@AE@%, %@AB@%BYVAL%@AE@%, %@AB@%SEG%@AE@%,
  13355. and %@AB@%CALLS%@AE@% keywords. For more information on these keywords, see the
  13356. %@AI@%Microsoft BASIC Language Reference%@AE@% or the %@AI@%Microsoft BASIC Programmer's
  13357. %@AI@%Guide%@AE@%.  %@NL@%
  13358. %@NL@%
  13359. %@NL@%
  13360. %@4@%%@AB@%FORTRAN Conventions%@AE@%%@EH@%%@NL@%
  13361. %@NL@%
  13362. You can modify the conventions observed by FORTRAN routines that call C
  13363. functions by using the %@AB@%INTERFACE%@AE@%, %@AB@%VALUE%@AE@%, %@AB@%PASCAL%@AE@%, and %@AB@%C%@AE@% keywords. For more
  13364. information about the use of these keywords, see the%@AI@% Microsoft FORTRAN%@AE@%
  13365. %@AI@%Reference.%@AE@%  %@NL@%
  13366. %@NL@%
  13367. %@NL@%
  13368. %@4@%%@AB@%Pascal Conventions%@AE@%%@EH@%%@NL@%
  13369. %@NL@%
  13370. You can modify the conventions observed by Pascal routines that interface
  13371. with C functions by using the %@AB@%VAR%@AE@%, %@AB@%CONST%@AE@%, %@AB@%ADR%@AE@%, %@AB@%VARS%@AE@%, %@AB@%CONSTS%@AE@%, %@AB@%ADRS%@AE@%, and %@AB@%C%@AE@%
  13372. keywords. For more information about the use of these keywords, see the
  13373. %@AI@%Microsoft Pascal Compiler User's Guide.%@AE@%  %@NL@%
  13374. %@NL@%
  13375. %@NL@%
  13376. %@3@%%@CR:C6A00120041 @%%@AB@%12.9.2  Numeric Data Representation%@AE@%%@EH@%%@NL@%
  13377. %@NL@%
  13378. Table 12.5 shows how to declare numeric variables of similar type in
  13379. different languages.  %@NL@%
  13380. %@NL@%
  13381. %@AB@%Table 12.5  %@AB@%Equivalent Numeric Data Types%@AE@%%@AE@%
  13382.  
  13383. %@TH:  34  1857 02 14 20 23 19 @%BASIC         C                   FORTRAN                Pascal%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%x%@AE@%%@AB@%%%@AE@%            %@AB@%short%@AE@%               %@AB@%INTEGER*2 %@AE@%             %@AB@%INTEGER2%@AE@%%@AB@%INTEGER%@AE@%       %@AB@%int%@AE@%                 ---                    %@AB@%INTEGER %@AE@%                                                         (default)---           %@AB@%unsigned short%@AE@%%@AU@%(1)%@AE@%   ---                    %@AB@%WORD%@AE@%---           %@AB@%unsigned%@AE@%            ---                    ---%@AI@%x%@AE@%%@AB@%&%@AE@%            %@AB@%long%@AE@%                %@AB@%INTEGER*4%@AE@%              %@AB@%INTEGER4%@AE@%%@AB@%LONG%@AE@%          ---                 %@AB@%INTEGER%@AE@% (default)      ------           %@AB@%unsigned long%@AE@%%@AU@%(1)%@AE@%    ---                    ---%@AI@%x%@AE@%%@AB@%!%@AE@%            %@AB@%float%@AE@%               %@AB@%REAL*4%@AE@%                 %@AB@%REAL4%@AE@%%@AI@%x%@AE@% (default)   ---                 %@AB@%REAL%@AE@%                   %@AB@%REAL%@AE@% (default)%@AB@%SINGLE%@AE@%        ---                 ---                    ---%@AI@%x%@AE@%%@AB@%#%@AE@%            %@AB@%double%@AE@%              %@AB@%REAL*8%@AE@%                 %@AB@%REAL8%@AE@%%@AB@%DOUBLE%@AE@%        ---                 %@AB@%DOUBLE %@AE@%                ---                                  %@AB@%PRECISION%@AE@%              ---           %@AB@%long double%@AE@%         %@AB@%REAL*16%@AE@%                %@AB@%REAL16%@AE@%---           %@AB@%unsigned char%@AE@%       %@AB@%CHARACTER*1%@AE@%%@AU@%(2)%@AE@%         %@AB@%CHAR%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  34  1857 02 14 20 23 19 @%
  13384.  
  13385. %@AU@%(1) %@AE@% Types %@AB@%unsigned short%@AE@% and %@AB@%unsigned long%@AE@% are not supported by BASIC or
  13386. FORTRAN. Type  %@AB@%unsigned long %@AE@%is not supported by Pascal. A signed integral
  13387. type can be substituted, but the maximum range will be less.  
  13388. %@AU@%(2) %@AE@% The FORTRAN type %@AB@%CHARACTER*1 %@AE@%is not the same as %@AB@%LOGICAL%@AE@%. %@NL@%
  13389. %@NL@%
  13390. %@NL@%
  13391. The FORTRAN types %@AB@%COMPLEX*8%@AE@% and %@AB@%COMPLEX*16%@AE@% are not implemented in C but can
  13392. be represented with structures.  %@NL@%
  13393. %@NL@%
  13394. The FORTRAN types %@AB@%LOGICAL*2%@AE@% and %@AB@%LOGICAL*4%@AE@% are not implemented in C.
  13395. %@AB@%LOGICAL*2%@AE@% is stored as a one-byte Boolean indicator followed by an unused
  13396. byte; %@AB@%LOGICAL*4%@AE@% is stored as a one-byte Boolean indicator followed by three
  13397. unused bytes.  %@NL@%
  13398. %@NL@%
  13399. %@NL@%
  13400. %@3@%%@CR:C6A00120042 @%%@AB@%12.9.3  Strings%@AE@%%@EH@%%@NL@%
  13401. %@NL@%
  13402. Each language implements strings differently. This section describes the
  13403. ways that strings are implemented in Microsoft languages.  %@NL@%
  13404. %@NL@%
  13405. %@NL@%
  13406. %@4@%%@AB@%C String Format%@AE@%%@EH@%%@NL@%
  13407. %@NL@%
  13408. C stores strings as arrays of bytes and uses a null character ( %@AS@% '\0' %@AE@% ) as
  13409. an end-of-string delimiter. For example, consider the following string:  %@NL@%
  13410. %@NL@%
  13411. %@AS@%  char c_string[] = "C text string";%@AE@%%@NL@%
  13412. %@NL@%
  13413. This string is represented in memory as follows:  %@NL@%
  13414. %@NL@%
  13415. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  13416. %@NL@%
  13417. Because %@AS@% c_string %@AE@% is an array like any other, C passes it by reference in
  13418. function calls.  %@NL@%
  13419. %@NL@%
  13420. %@NL@%
  13421. %@4@%%@AB@%BASIC String Format%@AE@%%@EH@%%@NL@%
  13422. %@NL@%
  13423. BASIC stores strings as four-byte descriptors pointing to the actual string
  13424. data. The format of the descriptor is as follows:  %@NL@%
  13425. %@NL@%
  13426. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  13427. %@NL@%
  13428. The first field of the string descriptor contains an integer indicating the
  13429. length (in bytes) of the string. The second field contains the address of
  13430. the string in the default data segment.  %@NL@%
  13431. %@NL@%
  13432. Do not attempt to alter the length of BASIC strings, because they are
  13433. managed by BASIC string-space management routines. You cannot count on a
  13434. particular string remaining at a given offset during the execution of a
  13435. BASIC program because the BASIC string-space management routines allocate
  13436. strings to different areas of memory depending on program requirements.  %@NL@%
  13437. %@NL@%
  13438. The format of the string at DS:%@AI@%Address%@AE@% is a simple array of characters. The
  13439. string is exactly the length indicated in the descriptor.  %@NL@%
  13440. %@NL@%
  13441. %@AU@% To pass a BASIC string to C, append a null character.%@AE@%  %@NL@%
  13442. %@NL@%
  13443. Because C needs the null character to delimit the end of the string, you
  13444. should append %@AS@% chr$( 0 ) %@AE@% to your BASIC string before passing it to your C
  13445. function. For example,  %@NL@%
  13446. %@NL@%
  13447. %@AS@%  A$ = "I am a BASIC string"
  13448. %@AS@%  A$ = A$ + chr$( 0 )
  13449. %@AS@%  
  13450. %@AS@%  CALL CFunc( SADD(A$) )%@AE@%%@NL@%
  13451. %@NL@%
  13452. Note that the BASIC call is made by near reference using the %@AB@%SADD %@AE@%keyword.  %@NL@%
  13453. %@NL@%
  13454. %@AU@% Use a string descriptor to pass a C string to BASIC.%@AE@%  %@NL@%
  13455. %@NL@%
  13456. To pass a C string to BASIC, create a structure for the string descriptor.
  13457. For example,  %@NL@%
  13458. %@NL@%
  13459. %@AS@%  char c_string[] = "C String Data";
  13460. %@AS@%  
  13461. %@AS@%  struct tagBASICStringDes
  13462. %@AS@%  {
  13463. %@AS@%      char *   sd_addr;
  13464. %@AS@%      int      sd_len;
  13465. %@AS@%  } str_des;
  13466. %@AS@%  
  13467. %@AS@%  str_des.sd_addr = c_string;
  13468. %@AS@%  str_des.sd_len = strlen( c_string );
  13469. %@AS@%  
  13470. %@AS@%  BASICFunction( &str_des );%@AE@%%@NL@%
  13471. %@NL@%
  13472. %@NL@%
  13473. %@4@%%@AB@%FORTRAN String Format%@AE@%%@EH@%%@NL@%
  13474. %@NL@%
  13475. FORTRAN stores strings as a series of bytes at a fixed location in memory.
  13476. There is no delimiter at the end of the string. Consider the string declared
  13477. as follows:  %@NL@%
  13478. %@NL@%
  13479. %@AS@%  STR = 'FORTRAN STRING'%@AE@%%@NL@%
  13480. %@NL@%
  13481. The string is stored in memory as follows:  %@NL@%
  13482. %@NL@%
  13483. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  13484. %@NL@%
  13485. FORTRAN passes strings by reference, as it does all other data.  %@NL@%
  13486. %@NL@%
  13487. ────────────────────────────────────────────────────────────────────────────%@NL@%
  13488. NOTE
  13489.  
  13490. %@AI@%FORTRAN's variable length strings cannot be used in mixed-language
  13491. %@AI@%programming because the temporary variable used to communicate string length
  13492. %@AI@%is not accessible to other languages.%@AE@%%@NL@%
  13493. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  13494. %@NL@%
  13495. To pass a C string to FORTRAN (or Pascal), pass the variable by reference as
  13496. you normally would. In your FORTRAN or Pascal routine, you must specify the
  13497. length of the string; strings that are passed as arguments from one language
  13498. to another must be of fixed length.  %@NL@%
  13499. %@NL@%
  13500. %@NL@%
  13501. %@4@%%@AB@%Pascal String Format%@AE@%%@EH@%%@NL@%
  13502. %@NL@%
  13503. Pascal represents strings as fixed-length arrays of %@AB@%CHAR%@AE@% or as strings with
  13504. a length byte followed by the string data.  %@NL@%
  13505. %@NL@%
  13506. %@AU@% To pass a fixed-length string to C, append a null character.%@AE@%  %@NL@%
  13507. %@NL@%
  13508. To pass a fixed-length string to a C function, use the concatenation
  13509. operator (%@AB@%*%@AE@%) to append a null character. Then pass the string to the C
  13510. function by reference (by declaring the string as %@AB@%CONST%@AE@%, %@AB@%CONSTS%@AE@%, %@AB@%VAR%@AE@%, or
  13511. %@AB@%VARS%@AE@%). For example,  %@NL@%
  13512. %@NL@%
  13513. %@AS@%  PROGRAM PasStr( input, output );
  13514. %@AS@%  type
  13515. %@AS@%      stype15 = string(15);  { fixed-length }
  13516. %@AS@%  var
  13517. %@AS@%      str : stype15;
  13518. %@AS@%  
  13519. %@AS@%  PROCEDURE PasStrToC( VAR s1 : stype15 ) [C]; EXTERN;
  13520. %@AS@%  
  13521. %@AS@%  BEGIN
  13522. %@AS@%      str := 'Pass this to C' * chr( 0 );
  13523. %@AS@%      PasStrToC( str );
  13524. %@AS@%  END.%@AE@%%@NL@%
  13525. %@NL@%
  13526. A more flexible way to pass Pascal strings to C functions is to declare them
  13527. as type %@AB@%ADRMEM%@AE@% or %@AB@%ADSMEM%@AE@%, then pass the address of the string. For example,
  13528. %@NL@%
  13529. %@NL@%
  13530. %@AS@%  PROCEDURE PasStrToC( s1adr : ADRMEM ) [C]; EXTERN;%@AE@%%@NL@%
  13531. %@NL@%
  13532. Then you can call the C function with this code:  %@NL@%
  13533. %@NL@%
  13534. %@AS@%  PasStrToC( ADR str );%@AE@%%@NL@%
  13535. %@NL@%
  13536. Using this method, you can pass strings of different lengths to C functions.
  13537. %@NL@%
  13538. %@NL@%
  13539. ────────────────────────────────────────────────────────────────────────────%@NL@%
  13540. NOTE
  13541.  
  13542. %@AI@%The Pascal type %@AI@%LSTRING %@AE@%%@AI@%is not compatible with C; you can pass a string
  13543. %@AI@%declared as LSTRING %@AE@%%@AI@%by first assigning it to another variable of type
  13544. %@AI@%STRING%@AE@%%@AI@%, then passing that variable.%@AE@%%@AE@%%@NL@%
  13545. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  13546. %@NL@%
  13547. Whenever you pass a variable of type %@AB@%STRING%@AE@% or type %@AB@%LSTRING%@AE@% by value, Pascal
  13548. pushes the whole string onto the stack and passes the length of the string
  13549. as another parameter. C cannot access strings passed in this manner.  %@NL@%
  13550. %@NL@%
  13551. %@AU@% Before passing a string from C to Pascal, make sure enough space is
  13552. %@AU@%allocated.%@AE@%  %@NL@%
  13553. %@NL@%
  13554. Passing a string from a C function to a Pascal function or procedure is
  13555. identical to passing a string from a C function to a FORTRAN routine. The
  13556. only provision you must make is to specify the length of the string to your
  13557. Pascal function.  %@NL@%
  13558. %@NL@%
  13559. %@NL@%
  13560. %@3@%%@CR:C6A00120043 @%%@AB@%12.9.4  Arrays%@AE@%%@EH@%%@NL@%
  13561. %@NL@%
  13562. When you use an array in a program written in a single language, the method
  13563. for array handling is consistent. When you mix languages, you need to be
  13564. aware of the differences between array-handling techniques in various
  13565. languages.  %@NL@%
  13566. %@NL@%
  13567. Unlike most Microsoft languages, BASIC keeps an array descriptor, which is
  13568. similar to the BASIC string descriptor discussed in Section 12.9.3,
  13569. "Strings." This array descriptor is necessary because BASIC handles memory
  13570. allocation for arrays dynamically (at run time). Dynamic allocation requires
  13571. BASIC to shift arrays in memory.  %@NL@%
  13572. %@NL@%
  13573. %@AU@% To pass a BASIC array to a  C function, use the %@AE@%%@AB@%VARPTR%@AE@% and %@AB@%VARSEG %@AE@%keywords.
  13574. %@NL@%
  13575. %@NL@%
  13576. The %@AB@%VARPTR %@AE@%and %@AB@%VARSEG %@AE@%keywords obtain the address of the first element of
  13577. the array and its segment, respectively. The example below shows how to call
  13578. a C function with a near reference and a far reference to an array:  %@NL@%
  13579. %@NL@%
  13580. %@AS@%  DIM ARRAY%( 20 )
  13581. %@AS@%  DECLARE CNearArray CDECL( BYVAL Addr AS INTEGER )
  13582. %@AS@%  DECLARE CFarArray CDECL( BYVAL Addr AS INTEGER, BYVAL Seg AS INTEGER )
  13583. %@AS@%  .
  13584. %@AS@%  .
  13585. %@AS@%  .
  13586. %@AS@%  CALL CNearArray( VARPTR( ARRAY%(0) ) )
  13587. %@AS@%  CALL CFarArray( VARPTR( ARRAY%(0) ), VARSEG( ARRAY%(0) ) )%@AE@%%@NL@%
  13588. %@NL@%
  13589. The C functions receiving %@AS@% ARRAY %@AE@% can be declared as follows:  %@NL@%
  13590. %@NL@%
  13591. %@AS@%  _cdecl CNearArray( int * array );
  13592. %@AS@%  _cdecl CFarArray( int far * array );%@AE@%%@NL@%
  13593. %@NL@%
  13594. The routine that receives the array must not make a call back to BASIC. If
  13595. it does, the location of the array data could change, and the address that
  13596. was passed to the routine would become meaningless.  %@NL@%
  13597. %@NL@%
  13598. If you only need to pass one member of the array from BASIC to your C
  13599. function, you can pass it by value as follows:  %@NL@%
  13600. %@NL@%
  13601. %@AS@%  CALL CFunc( ARRAY%(8) )%@AE@%%@NL@%
  13602. %@NL@%
  13603. %@NL@%
  13604. %@3@%%@CR:C6A00120044 @%%@AB@%12.9.5  Array Declaration and Indexing%@AE@%%@EH@%%@NL@%
  13605. %@NL@%
  13606. Each language varies in the way that arrays are declared and indexed. Array
  13607. indexing is a source-level consideration and involves no transformation of
  13608. data. There are two differences in the way elements are indexed by each
  13609. language:  %@NL@%
  13610. %@NL@%
  13611. %@NL@%
  13612.   1.  The value of the lower array bound is different among Microsoft
  13613.       languages.%@NL@%
  13614. %@NL@%
  13615. %@STUB@%      By default, FORTRAN indexes the first element of an array as 1. BASIC
  13616.       and C index it as 0. Pascal lets you begin indexing at any integer
  13617.       value. Recent versions of BASIC and FORTRAN also give you the option
  13618.       of specifying lower bounds at any integer value.%@NL@%
  13619. %@NL@%
  13620.   2.  Some languages vary subscripts in row-major order; others vary
  13621.       subscripts in column-major order.%@NL@%
  13622. %@NL@%
  13623. %@STUB@%      This issue only affects arrays with more than one dimension. With
  13624.       row-major order (used by C and Pascal), the rightmost dimension
  13625.       changes first. With column-major order (used by FORTRAN, and BASIC by
  13626.       default), the leftmost dimension changes first. Thus, in C, the first
  13627.       four elements of an array declared as %@AS@% X[3][3] %@AE@% are%@NL@%
  13628. %@NL@%
  13629. %@AS@%      X[0][0]    X[0][1]    X[0][2]    X[1][0]%@AE@%%@NL@%
  13630. %@NL@%
  13631. %@STUB@%      In FORTRAN, the four elements are%@NL@%
  13632. %@NL@%
  13633. %@AS@%      X(1,1)     X(2,1)     X(3,1)     X(1,2)%@AE@%%@NL@%
  13634. %@NL@%
  13635. %@STUB@%      The C and FORTRAN arrays shown above illustrate the difference between
  13636.       row-major and column-major order as well as the difference in the
  13637.       assumed lower bound between C and FORTRAN. Table 12.6 shows
  13638.       equivalences for array declarations in each language. In this table, %@AI@%r%@AE@%
  13639.       is the number of elements of the row dimension (which changes most
  13640.       slowly), and %@AI@%c%@AE@% is the number of elements of the column dimension
  13641.       (which changes most quickly).%@NL@%
  13642. %@AB@%Table 12.6  %@AB@%Equivalent Array Declarations%@AE@%%@AE@%
  13643.  
  13644. %@TH:  14   951 02 10 33 33 @%Language  Array Declaration                Notes%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%BASIC     %@AB@%DIM%@AE@% %@AI@%x%@AE@%(%@AI@%r%@AE@%-1, %@AI@%c%@AE@%-1)                  With default lower bounds of 0C         type %@AI@%x%@AE@%[%@AI@%r%@AE@%][%@AI@%c%@AE@%]%@AB@%%@AE@%                     When passed by reference          %@AB@%struct %@AE@%{ %@AI@%type%@AE@% %@AI@%x%@AE@%[%@AI@%r%@AE@%][%@AI@%c%@AE@%]; } %@AI@%x%@AE@%       When passed by valueFORTRAN   %@AI@%type x%@AE@%(%@AI@%c%@AE@%, %@AI@%r%@AE@%)                     With default lower bounds of 1Pascal    %@AI@%x%@AE@% : %@AB@%ARRAY%@AE@% [%@AI@%a%@AE@%..%@AI@%a%@AE@%+%@AI@%r%@AE@%-1, %@AI@%b%@AE@%..%@AI@%b%@AE@%+%@AI@%c%@AE@%-1]%@AB@% %@AE@%          %@AB@%OF%@AE@% %@AI@%type%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  14   951 02 10 33 33 @%
  13645.  
  13646. %@NL@%
  13647. %@NL@%
  13648. The order of indexing extends to any number of dimensions you declare. For
  13649. example, the C declaration  %@NL@%
  13650. %@NL@%
  13651. %@AS@%  int arr1[2][10][15][20];%@AE@%%@NL@%
  13652. %@NL@%
  13653. is equivalent to the FORTRAN declaration  %@NL@%
  13654. %@NL@%
  13655. %@AS@%  INTEGER*2 ARR1( 20, 15, 10, 2 )%@AE@%%@NL@%
  13656. %@NL@%
  13657. The constants used in a C array declaration represent dimensions, not upper
  13658. bounds as they do in other languages. Therefore, the last element in the C
  13659. array declared as %@AS@% int arr[5][5] %@AE@% is %@AS@% arr[4][4]%@AE@%, not %@AS@% arr[5][5]%@AE@%.  %@NL@%
  13660. %@NL@%
  13661. %@NL@%
  13662. %@3@%%@CR:C6A00120045 @%%@AB@%12.9.6  Structures, Records, and User-Defined Types%@AE@%%@EH@%%@NL@%
  13663. %@NL@%
  13664. The C %@AB@%struct %@AE@%type, the BASIC user-defined type, the FORTRAN record (defined
  13665. with the %@AB@%STRUCTURE %@AE@%keyword), and the Pascal %@AB@%record %@AE@%type are equivalent.
  13666. Therefore, these data types can be passed between C, FORTRAN, Pascal, and
  13667. BASIC.  %@NL@%
  13668. %@NL@%
  13669. These types can be affected by the storage method. By default, C, FORTRAN,
  13670. and Pascal use word alignment for types shorter than one word (type %@AB@%char %@AE@%and
  13671. %@AB@%unsigned char%@AE@%). This storage method specifies that occasional bytes can be
  13672. inserted as padding so that word and double-word objects start on an even
  13673. boundary. (In addition, all nested structures and records start on a word
  13674. boundary.)  %@NL@%
  13675. %@NL@%
  13676. If you are passing a structure or record across a mixed-language interface,
  13677. your calling routine and called routine must agree on the storage method and
  13678. parameter-passing convention. Otherwise, data will not be interpreted
  13679. correctly.  %@NL@%
  13680. %@NL@%
  13681. Because Pascal, FORTRAN, and C use the same storage method for structures
  13682. and records, you can interchange data between routines without taking any
  13683. special precautions unless you modify the storage method. Make sure the
  13684. storage methods agree before interchanging data between C, FORTRAN, and
  13685. Pascal.  %@NL@%
  13686. %@NL@%
  13687. BASIC packs user-defined types, so your C function must also pack structures
  13688. (using the /Zp command-line option or the %@AB@%pack%@AE@% pragma) to agree.  %@NL@%
  13689. %@NL@%
  13690. You can pass structures as parameters by value or by reference. Both the
  13691. calling program and the called program must agree on the parameter-passing
  13692. convention. See Section 12.2.3, "Parameter-Passing Requirement," for more
  13693. information about the language you are using.  %@NL@%
  13694. %@NL@%
  13695. %@NL@%
  13696. %@3@%%@CR:C6A00120046 @%%@AB@%12.9.7  External Data%@AE@%%@EH@%%@NL@%
  13697. %@NL@%
  13698. External data refers to data that is both static and public; that is, the
  13699. data is stored in a set place in memory as opposed to being allocated on the
  13700. stack, and the data is visible to other modules.  %@NL@%
  13701. %@NL@%
  13702. External data can be defined in C, Pascal, and assembly language. Note that
  13703. a data definition is distinct from an external declaration. A data
  13704. definition causes a compiler to create a data object; an external
  13705. declaration informs a compiler that the object is to be found in another
  13706. module. FORTRAN can only define external data in COMMON blocks. (See Section
  13707. 12.9.9, "Common Blocks," for more information about sharing external data
  13708. with FORTRAN programs.)  %@NL@%
  13709. %@NL@%
  13710. There are three requirements for programs that share external data between
  13711. languages:  %@NL@%
  13712. %@NL@%
  13713. %@NL@%
  13714.   1.  One of the modules must define the data.%@NL@%
  13715. %@NL@%
  13716. %@STUB@%      You can define a static data object in a C module by defining a data
  13717.       object outside all functions. (If you use the %@AB@%static%@AE@% keyword in C,
  13718.       however, the data object will not be made public.)%@NL@%
  13719. %@NL@%
  13720.   2.  The other modules that will access the data must declare the data as
  13721.       external.%@NL@%
  13722. %@NL@%
  13723. %@STUB@%      In C, you can declare data as external by using an %@AB@%extern%@AE@% declaration,
  13724.       similar to the %@AB@%extern%@AE@% declaration for functions. In FORTRAN and
  13725.       Pascal, you can declare data as external by adding the %@AB@%EXTERN
  13726. %@AB@%      %@AE@%attribute to the data declaration.%@NL@%
  13727. %@NL@%
  13728.   3.  Resolve naming-convention differences.%@NL@%
  13729. %@NL@%
  13730. %@STUB@%      In C, you can adopt the FORTRAN/Pascal naming convention by applying
  13731.       %@AB@%_fortran %@AE@%or %@AB@%_pascal %@AE@%to the data declaration. In FORTRAN and Pascal,
  13732.       you can adopt the C naming convention by applying the %@AB@%C %@AE@%attribute to
  13733.       the data declaration.%@NL@%
  13734. %@NL@%
  13735. %@NL@%
  13736. %@NL@%
  13737. %@3@%%@CR:C6A00120047 @%%@AB@%12.9.8  Pointers and Address Variables%@AE@%%@EH@%%@NL@%
  13738. %@NL@%
  13739. Rather than passing data directly, you may want to pass the address of a
  13740. piece of data. Passing the address amounts to passing the data by reference.
  13741. In some cases, such as in BASIC arrays, there is no other way to pass a data
  13742. item as a parameter.  %@NL@%
  13743. %@NL@%
  13744. C programs always pass array variables by address. All other types are
  13745. passed by value unless you use the address-of (%@AB@%&%@AE@%) operator to obtain the
  13746. address.  %@NL@%
  13747. %@NL@%
  13748. The Pascal %@AB@%ADR %@AE@%and %@AB@%ADS %@AE@%types are equivalent to near and far pointers,
  13749. respectively, in C. You can pass %@AB@%ADR %@AE@%and %@AB@%ADS %@AE@%variables as %@AB@%ADRMEM %@AE@%or %@AB@%ADSMEM%@AE@%.
  13750. BASIC and FORTRAN do not have formal address types. However, they do provide
  13751. ways for storing and passing addresses.  %@NL@%
  13752. %@NL@%
  13753. BASIC programs can access a variable's segment address with the %@AB@%VARSEG
  13754. %@AB@%%@AE@%function and its offset address with the %@AB@%VARPTR%@AE@% function. The values
  13755. returned by these intrinsic functions should then be passed or stored as
  13756. ordinary integer variables. If you pass them to another language, pass by
  13757. value. Otherwise you will be attempting to pass the address of the address,
  13758. rather than the address itself.  %@NL@%
  13759. %@NL@%
  13760. To pass a near address, pass only the offset; if you need to pass a far
  13761. address, you may have to pass the segment and the offset separately. Pass
  13762. the segment address first, unless %@AB@%CDECL %@AE@%is in effect.  %@NL@%
  13763. %@NL@%
  13764. FORTRAN programs can determine near and far addresses with the %@AB@%LOC %@AE@%and
  13765. %@AB@%LOCFAR %@AE@%functions. Store the result of the %@AB@%LOC %@AE@%function as %@AB@%INTEGER*2 %@AE@%and the
  13766. result of the %@AB@%LOCFAR %@AE@%function as %@AB@%INTEGER*4%@AE@%.  %@NL@%
  13767. %@NL@%
  13768. As with BASIC, if you pass the result of %@AB@%LOC %@AE@%or %@AB@%LOCFAR %@AE@%to another language,
  13769. be sure to pass by value.  %@NL@%
  13770. %@NL@%
  13771. %@NL@%
  13772. %@3@%%@CR:C6A00120048 @%%@AB@%12.9.9  Common Blocks%@AE@%%@EH@%%@NL@%
  13773. %@NL@%
  13774. You can pass individual members of a FORTRAN or BASIC common block in an
  13775. argument list, just as you can any data item. However, you can also give a
  13776. different language module access to the entire common block at once.  %@NL@%
  13777. %@NL@%
  13778. C modules can reference the items of a common block by first declaring a
  13779. structure with fields that correspond to the common-block variables. Having
  13780. defined a structure with the appropriate fields, the C module must then
  13781. connect with the common block itself. The next two sections present methods
  13782. for gaining access to common blocks.  %@NL@%
  13783. %@NL@%
  13784. %@NL@%
  13785. %@4@%%@AB@%Passing the Address of a Common Block%@AE@%%@EH@%%@NL@%
  13786. %@NL@%
  13787. To pass the address of a common block, simply pass the address of the first
  13788. variable in the block. (In other words, pass the first variable by
  13789. reference.) The receiving C module should expect to receive a structure by
  13790. reference.  %@NL@%
  13791. %@NL@%
  13792. In the example below, the C function %@AS@% initcb %@AE@% receives the address of the
  13793. variable %@AS@% N%@AE@%, which it considers to be a pointer to a structure with three
  13794. fields:  %@NL@%
  13795. %@NL@%
  13796. %@AS@%  C      FORTRAN SOURCE CODE
  13797. %@AS@%  C
  13798. %@AS@%         COMMON /CBLOCK/N, X, Y
  13799. %@AS@%         INTEGER*2 N
  13800. %@AS@%         REAL*8    X, Y
  13801. %@AS@%  .
  13802. %@AS@%  .
  13803. %@AS@%  .
  13804. %@AS@%         CALL INITCB( N )
  13805. %@AS@%  
  13806. %@AS@%  
  13807. %@AS@%  /* C source code */
  13808. %@AS@%  
  13809. %@AS@%  
  13810. %@AS@%  /* Explicitly set structure packing to word-alignment */
  13811. %@AS@%  #pragma pack( 2 );
  13812. %@AS@%  
  13813. %@AS@%  struct block_type
  13814. %@AS@%  {
  13815. %@AS@%      int     n;
  13816. %@AS@%      double  x;
  13817. %@AS@%      double  y;
  13818. %@AS@%  };
  13819. %@AS@%  
  13820. %@AS@%  initcb( struct block_type * block_hed )
  13821. %@AS@%  {
  13822. %@AS@%      block_hed-n = 1;
  13823. %@AS@%      block_hed-x = 10.0;
  13824. %@AS@%      block_hed-y = 20.0;
  13825. %@AS@%  }%@AE@%%@NL@%
  13826. %@NL@%
  13827. %@NL@%
  13828. %@4@%%@AB@%Accessing Common Blocks Directly%@AE@%%@EH@%%@NL@%
  13829. %@NL@%
  13830. You can access FORTRAN common blocks directly by defining a structure with
  13831. the appropriate fields and then using the methods described in Section
  13832. 12.9.7, "External Data." Here is an example of accessing common blocks
  13833. directly:  %@NL@%
  13834. %@NL@%
  13835. %@AS@%  struct block_type
  13836. %@AS@%  {
  13837. %@AS@%      int    n;
  13838. %@AS@%      double x;
  13839. %@AS@%      double y;
  13840. %@AS@%  };
  13841. %@AS@%  
  13842. %@AS@%  extern struct block_type fortran cblock;%@AE@%%@NL@%
  13843. %@NL@%
  13844. %@AU@% You cannot access common blocks directly using BASIC common blocks.%@AE@%  %@NL@%
  13845. %@NL@%
  13846. Note that the technique of accessing common blocks directly works with
  13847. FORTRAN common blocks, but not with BASIC common blocks. If your C module
  13848. must work with both FORTRAN and BASIC common blocks, pass the address of the
  13849. common block as a parameter to the function.  %@NL@%
  13850. %@NL@%
  13851. %@NL@%
  13852. %@3@%%@CR:C6A00120049 @%%@AB@%12.9.10  Using a Varying Number of Parameters%@AE@%%@EH@%%@NL@%
  13853. %@NL@%
  13854. Some C functions (for example %@AB@%printf%@AE@%) accept a variable number of
  13855. parameters. To call such a function from another language, you need to
  13856. suppress the type-checking that normally forces a call to be made with a
  13857. fixed number of parameters. In BASIC, you can remove this type-checking by
  13858. omitting a parameter list from the %@AB@%DECLARE %@AE@%statement. In FORTRAN or Pascal,
  13859. you can call routines with a variable number of parameters by including the
  13860. %@AB@%VARYING %@AE@%attribute in your interface to the routine, along with the %@AB@%C
  13861. %@AB@%%@AE@%attribute. You must use the %@AB@%C%@AE@% attribute because a variable number of
  13862. parameters is feasible only with the C calling convention.  %@NL@%
  13863. %@NL@%
  13864. %@NL@%
  13865. %@NL@%
  13866. %@NL@%
  13867. %@NL@%
  13868. %@NL@%
  13869. %@CR:C6A00130001 @%%@1@%%@AB@%Chapter 13  Writing Portable Programs%@AE@%%@EH@%%@NL@%
  13870. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13871. %@NL@%
  13872. Because C compilers exist on a variety of computers, some C applications
  13873. developed for one computer system can be ported to other systems. However,
  13874. some aspects of language behavior depend on how a particular C compiler is
  13875. implemented and how a specific computer operates. Therefore, when designing
  13876. a program to be ported to another system, it is important that you examine
  13877. programming assumptions.  %@NL@%
  13878. %@NL@%
  13879. This chapter describes programming assumptions that can affect writing
  13880. portable programs.  %@NL@%
  13881. %@NL@%
  13882. The American National Standards Institute Standard for the C Language (the
  13883. ANSI Standard) details every instance where language behavior is defined by
  13884. the implementation. Appendix C summarizes implementation-defined behavior
  13885. for Microsoft C.  %@NL@%
  13886. %@NL@%
  13887. %@NL@%
  13888. %@2@%%@CR:C6A00130002 @%%@AB@%13.1  Assumptions about Hardware%@AE@%%@EH@%%@NL@%
  13889. %@NL@%
  13890. To make C programs portable, you must examine two aspects of your code:
  13891. hardware assumptions and compiler dependency. This section deals with
  13892. hardware assumptions. Section 13.2, "Assumptions about the Compiler," deals
  13893. with compiler dependency.  %@NL@%
  13894. %@NL@%
  13895. %@NL@%
  13896. %@3@%%@CR:C6A00130003 @%%@AB@%13.1.1  Size of Basic Types%@AE@%%@EH@%%@NL@%
  13897. %@NL@%
  13898. In C, the size of basic types (%@AB@%char%@AE@%, %@AB@%signed%@AE@% %@AB@%int%@AE@%, %@AB@%unsigned int%@AE@%, %@AB@%float%@AE@%,
  13899. %@AB@%double%@AE@%, and %@AB@%long double%@AE@%) is implementation-defined, so relying on a
  13900. particular data type to be a given size reduces the portability of a
  13901. program.  %@NL@%
  13902. %@NL@%
  13903. %@AU@% Don't make assumptions about the size of data types.%@AE@%  %@NL@%
  13904. %@NL@%
  13905. Because the size of basic types is left to the implementation, do not make
  13906. assumptions about the size or alignment of data types within aggregate
  13907. types. Use only the %@AB@%sizeof %@AE@%operator to determine the size or amount of
  13908. storage required for a variable or a type.  %@NL@%
  13909. %@NL@%
  13910. Following are some rules governing the size of data types.  %@NL@%
  13911. %@NL@%
  13912. %@NL@%
  13913. %@4@%%@AB@%Type char%@AE@%%@EH@%%@NL@%
  13914. %@NL@%
  13915. Type %@AB@%char%@AE@% is the smallest of the basic types, but it must be large enough to
  13916. hold any of the characters in the implementation's basic character set.
  13917. Normally, variables of type %@AB@%char%@AE@% are one byte.  %@NL@%
  13918. %@NL@%
  13919. %@NL@%
  13920. %@4@%%@AB@%Type int and Type short int%@AE@%%@EH@%%@NL@%
  13921. %@NL@%
  13922. Type %@AB@%int%@AE@% and type %@AB@%short int%@AE@% often correspond to the register size of the
  13923. target machine. Both %@AB@%int%@AE@% and %@AB@%short%@AE@% are greater than or equal to the size of
  13924. type %@AB@%char%@AE@% but less than or equal to the size of type %@AB@%long%@AE@%.  %@NL@%
  13925. %@NL@%
  13926. If you assume that type %@AB@%int%@AE@% is a certain size, your code may not be portable
  13927. because  %@NL@%
  13928. %@NL@%
  13929. %@NL@%
  13930.   ■   An %@AB@%int%@AE@% can be defined as a 16-bit (two-byte) or a 32-bit quantity.%@NL@%
  13931. %@NL@%
  13932.   ■   An %@AB@%int%@AE@% is not always large enough to hold array indexes. For large
  13933.       arrays, you must use %@AB@%unsigned int%@AE@%; for extremely large arrays, use
  13934.       %@AB@%long%@AE@%. To be certain your code is portable, define your array indexes
  13935.       as type %@AB@%size_t%@AE@%. You may not know, before porting your code, the
  13936.       maximum value to expect an array index of type %@AB@%int%@AE@% to hold. The file
  13937.       LIMITS.H contains manifest constants, listed below, for the maximum
  13938.       and minimum values of each basic integral type.%@NL@%
  13939. %@NL@%
  13940. %@NL@%
  13941. %@AB@%Constant%@AE@%                          %@AB@%Value%@AE@%
  13942. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13943. %@AB@%CHAR_BIT%@AE@%                          Number of bits in a variable of type %@AB@%%@AE@%
  13944.                                   %@AB@%char%@AE@%
  13945.  
  13946. %@AB@%CHAR_MIN%@AE@%                          Minimum value a variable of type %@AB@%char%@AE@% 
  13947.                                   can hold
  13948.  
  13949. %@AB@%CHAR_MAX%@AE@%                          Maximum value a variable of type %@AB@%char%@AE@% 
  13950.                                   can hold
  13951.  
  13952. %@AB@%SCHAR_MIN%@AE@%                         Minimum value a variable of type %@AB@%signed%@AE@% %@AB@%%@AE@%
  13953.                                   %@AB@%char%@AE@%
  13954.                                   can hold
  13955.  
  13956. %@AB@%SCHAR_MAX%@AE@%                         Maximum value a variable of type %@AB@%signed%@AE@% %@AB@%%@AE@%
  13957.                                   %@AB@%char%@AE@%
  13958.                                   can hold
  13959.  
  13960. %@AB@%UCHAR_MAX%@AE@%                         Maximum value a variable of type %@AB@%%@AE@%
  13961.                                   %@AB@%unsigned%@AE@% %@AB@%char%@AE@% can hold
  13962.  
  13963. %@AB@%SHRT_MIN%@AE@%                          Minimum value a variable of type %@AB@%short%@AE@% 
  13964.                                   can hold
  13965.  
  13966. %@AB@%SHRT_MAX%@AE@%                          Maximum value a variable of type %@AB@%short%@AE@% 
  13967.                                   can hold
  13968.  
  13969. %@AB@%USHRT_MAX%@AE@%                         Maximum value a variable of type %@AB@%%@AE@%
  13970.                                   %@AB@%unsigned short%@AE@% can hold
  13971.  
  13972. %@AB@%INT_MIN%@AE@%                           Minimum value a variable of type %@AB@%int%@AE@% can
  13973.                                   hold
  13974.  
  13975. %@AB@%INT_MAX%@AE@%                           Maximum value a variable of type %@AB@%int%@AE@% can
  13976.                                   hold
  13977.  
  13978. %@AB@%UINT_MAX%@AE@%                          Maximum value a variable of type %@AB@%%@AE@%
  13979.                                   %@AB@%unsigned int%@AE@%
  13980.                                   can hold
  13981.  
  13982. %@AB@%LONG_MIN%@AE@%                          Minimum value a variable of type %@AB@%long%@AE@% 
  13983.                                   can hold
  13984.  
  13985. %@AB@%LONG_MAX%@AE@%                          Maximum value a variable of type %@AB@%long%@AE@% 
  13986.                                   can hold
  13987.  
  13988. %@AB@%ULONG_MAX%@AE@%                         Maximum value a variable of type %@AB@%%@AE@%
  13989.                                   %@AB@%unsigned long%@AE@% can hold
  13990.  
  13991. %@NL@%
  13992. %@4@%%@AB@%Type float, Type double, and Type long double%@AE@%%@EH@%%@NL@%
  13993. %@NL@%
  13994. Type %@AB@%float%@AE@% is the smallest of the basic floating-point types. Type %@AB@%double%@AE@% is
  13995. usually larger than type %@AB@%float%@AE@%, and type %@AB@%long double%@AE@% is usually the largest
  13996. of the floating-point types. You can make only these portability assumptions
  13997. about floating-point types:  %@NL@%
  13998. %@NL@%
  13999. %@NL@%
  14000.   ■   Any value that can be represented as type %@AB@%float%@AE@% can be represented as
  14001.       type %@AB@%double%@AE@% (type %@AB@%float%@AE@% is a subset of type %@AB@%double%@AE@%).%@NL@%
  14002. %@NL@%
  14003.   ■   Any value that can be represented as type %@AB@%double%@AE@% can be represented as
  14004.       type %@AB@%long double%@AE@% (type %@AB@%double%@AE@% is a subset of type %@AB@%long double%@AE@%).%@NL@%
  14005. %@NL@%
  14006. %@NL@%
  14007. The file FLOAT.H contains manifest constants, listed below, for the maximum
  14008. and minimum values of each basic floating-point type.  %@NL@%
  14009. %@NL@%
  14010. %@AB@%Constant%@AE@%                          %@AB@%Value%@AE@%
  14011. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14012. %@AB@%DBL_DIG%@AE@%                           Number of decimal digits of precision a 
  14013.                                   variable of type %@AB@%double%@AE@% can hold
  14014.  
  14015. %@AB@%DBL_MAX%@AE@%                           Maximum value a variable of type %@AB@%double%@AE@% 
  14016.                                   can hold
  14017.  
  14018. %@AB@%DBL_MAX_10_EXP%@AE@%                    Maximum value (base 10) the exponent of 
  14019.                                   a variable of type %@AB@%double%@AE@% can hold
  14020.  
  14021. %@AB@%DBL_MAX_EXP%@AE@%                       Maximum value (base 2) the exponent of a
  14022.                                   variable of type %@AB@%double%@AE@% can hold
  14023.  
  14024. %@AB@%DBL_MIN%@AE@%                           Minimum positive value a variable of 
  14025.                                   type %@AB@%double%@AE@% can hold
  14026.  
  14027. %@AB@%DBL_MIN_10_EXP%@AE@%                    Minimum value (base 10) the exponent of 
  14028.                                   a variable of type %@AB@%double%@AE@% can hold
  14029.  
  14030. %@AB@%DBL_MIN_EXP%@AE@%                       Minimum value (base 2) the exponent of a
  14031.                                   variable of type %@AB@%double%@AE@% can hold
  14032.  
  14033. %@AB@%FLT_DIG%@AE@%                           Number of decimal digits of precision a 
  14034.                                   variable of type %@AB@%float%@AE@% can hold
  14035.  
  14036. %@AB@%FLT_MAX%@AE@%                           Maximum value a variable of type %@AB@%float%@AE@% 
  14037.                                   can hold
  14038.  
  14039. %@AB@%FLT_MAX_10_EXP%@AE@%                    Maximum value (base 10) the exponent of 
  14040.                                   a variable of type %@AB@%float%@AE@% can hold
  14041.  
  14042. %@AB@%FLT_MAX_EXP%@AE@%                       Maximum value (base 2) the exponent of a
  14043.                                   variable of type %@AB@%float%@AE@% can hold
  14044.  
  14045. %@AB@%FLT_MIN%@AE@%                           Minimum positive value a variable of 
  14046.                                   type %@AB@%float%@AE@% can hold
  14047.  
  14048. %@AB@%FLT_MIN_10_EXP%@AE@%                    Minimum value (base 10) the exponent of 
  14049.                                   a variable of type %@AB@%float%@AE@% can hold
  14050.  
  14051. %@AB@%FLT_MIN_EXP%@AE@%                       Minimum value (base 2) the exponent of a
  14052.                                   variable of type %@AB@%float%@AE@% can hold
  14053.  
  14054. %@AB@%LDBL_DIG%@AE@%                          Number of decimal digits of precision a 
  14055.                                   variable of type %@AB@%long double%@AE@% can hold
  14056.  
  14057. %@AB@%LDBL_MAX%@AE@%                          Maximum value a variable of type %@AB@%long %@AE@%
  14058.                                   %@AB@%double%@AE@% can hold
  14059.  
  14060. %@AB@%LDBL_MAX_10_EXP%@AE@%                   Maximum value (base 10) the exponent of 
  14061.                                   a variable of type %@AB@%long double%@AE@% can hold
  14062.  
  14063. %@AB@%LDBL_MAX_EXP%@AE@%                      Maximum value (base 2) the exponent of a
  14064.                                   variable of type %@AB@%long double%@AE@% can hold
  14065.  
  14066. %@AB@%LDBL_MIN%@AE@%                          Minimum positive value a variable of 
  14067.                                   type %@AB@%long double%@AE@% can hold
  14068.  
  14069. %@AB@%LDBL_MIN_10_EXP%@AE@%                   Minimum value (base 10) the exponent of 
  14070.                                   a variable of type %@AB@%long double%@AE@% can hold
  14071.  
  14072. %@AB@%LDBL_MIN_EXP%@AE@%                      Minimum value (base 2) the exponent of a
  14073.                                   variable of type %@AB@%long double%@AE@% can hold
  14074.  
  14075. %@NL@%
  14076. %@4@%%@AB@%Microsoft C Type Sizes%@AE@%%@EH@%%@NL@%
  14077. %@NL@%
  14078. Table 13.1 summarizes the size of the basic types in Microsoft C.  %@NL@%
  14079. %@NL@%
  14080. %@AB@%Table 13.1  %@AB@%Size of Basic Types in Microsoft C%@AE@%%@AE@%
  14081.  
  14082. %@TH:  22   848 03 38 38 @%                                      Number Type                                  of Bytes%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%char%@AE@%, %@AB@%unsigned char%@AE@%                   1%@AB@%int%@AE@%, %@AB@%short%@AE@%,%@AB@% unsigned int%@AE@%,%@AB@%%@AE@%             2%@AB@%unsigned short%@AE@%                        %@AB@%near pointer%@AE@%                          2%@AB@%long%@AE@%, %@AB@%unsigned long%@AE@%                   4%@AB@%far pointer%@AE@%                           4%@AB@%float%@AE@%                                 4%@AB@%double%@AE@%                                8%@AB@%long double%@AE@%                           10%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  22   848 03 38 38 @%
  14083.  
  14084. %@NL@%
  14085. %@3@%%@CR:C6A00130004 @%%@AB@%13.1.2  Storage Order and Alignment%@AE@%%@EH@%%@NL@%
  14086. %@NL@%
  14087. The C language does not define any specific layout for the storage of data
  14088. items relative to one another. The layout for storage of structure elements,
  14089. or unions within a structure or union, is defined by the implementation.  %@NL@%
  14090. %@NL@%
  14091. Some processors require that data longer than one byte be word-aligned
  14092. (aligned to an even-byte address). Other processors, such as the 80%@AI@%x%@AE@%86
  14093. family, do not have such a restriction.  %@NL@%
  14094. %@NL@%
  14095. %@NL@%
  14096. %@4@%%@AB@%Structure Order and Alignment%@AE@%%@EH@%%@NL@%
  14097. %@NL@%
  14098. The example below illustrates how alignment can affect your program. In the
  14099. example, a structure is cast to type %@AB@%long%@AE@% because the programmer knew the
  14100. order in which a particular implementation stored data.  %@NL@%
  14101. %@NL@%
  14102. %@AS@%  /* Nonportable code */
  14103. %@AS@%  struct time
  14104. %@AS@%  {
  14105. %@AS@%      char hour;     /* 0 < hour < 24   -- fits in a char */
  14106. %@AS@%      char minute;   /* 0 < minute < 60 -- fits in a char */
  14107. %@AS@%      char second;   /* 0 < second < 60 -- fits in a char */
  14108. %@AS@%  };
  14109. %@AS@%  
  14110. %@AS@%      .
  14111. %@AS@%      .
  14112. %@AS@%      .
  14113. %@AS@%      struct time now, alarm_time;
  14114. %@AS@%      .
  14115. %@AS@%      .
  14116. %@AS@%      .
  14117. %@AS@%      if ( (long)now >= (long)alarm_time )
  14118. %@AS@%      {
  14119. %@AS@%          /* sound an alarm */
  14120. %@AS@%      }%@AE@%%@NL@%
  14121. %@NL@%
  14122. The preceding code makes these nonportable assumptions:  %@NL@%
  14123. %@NL@%
  14124. %@NL@%
  14125.   ■   The data for %@AS@% hour %@AE@% will be stored in a higher order position than %@AS@%
  14126. %@AS@%      minute %@AE@% or %@AS@% second%@AE@%. Because C does not guarantee storage order or
  14127.       alignment of structures or unions, the code may not be portable to
  14128.       other machines.%@NL@%
  14129. %@NL@%
  14130.   ■   Three variables of type %@AB@%char %@AE@%will be shorter than or the same length
  14131.       as a variable of type %@AB@%long%@AE@%. Thus, the code is not portable according
  14132.       to the rules governing the size of basic types, as described in
  14133.       Section 13.1.1.%@NL@%
  14134. %@NL@%
  14135. %@NL@%
  14136. If either of these assumptions proves false, the comparison (%@AB@%if %@AE@%statement)
  14137. is invalid.  %@NL@%
  14138. %@NL@%
  14139. %@AU@% You can write code that makes no assumptions about storage order.%@AE@%  %@NL@%
  14140. %@NL@%
  14141. To make the program in the preceding example portable, you can break the
  14142. comparison between the two long integers into a component-by-component
  14143. comparison. This technique is illustrated in the following example:  %@NL@%
  14144. %@NL@%
  14145. %@AS@%  /* Portable code */
  14146. %@AS@%  struct time
  14147. %@AS@%  {
  14148. %@AS@%      char hour;     /* 0 < hour < 24   -- fits in a char */
  14149. %@AS@%      char minute;   /* 0 < minute < 60 -- fits in a char */
  14150. %@AS@%      char second;   /* 0 < second < 60 -- fits in a char */
  14151. %@AS@%  };
  14152. %@AS@%  
  14153. %@AS@%      .
  14154. %@AS@%      .
  14155. %@AS@%      .
  14156. %@AS@%      struct time now, alarm_time;
  14157. %@AS@%      .
  14158. %@AS@%      .
  14159. %@AS@%      .
  14160. %@AS@%      if ( time_cmp( now, alarm_time ) >= 0 )
  14161. %@AS@%      {
  14162. %@AS@%          /* sound an alarm */
  14163. %@AS@%      }
  14164. %@AS@%      .
  14165. %@AS@%      .
  14166. %@AS@%      .
  14167. %@AS@%  
  14168. %@AS@%  int time_cmp( struct time t1, struct time t2 )
  14169. %@AS@%  {
  14170. %@AS@%      if( t1.hour != t2.hour )
  14171. %@AS@%          return( t2.hour - t1.hour );
  14172. %@AS@%      if( t1.minute != t2.minute )
  14173. %@AS@%          return( t2.minute - t1.minute );
  14174. %@AS@%      return( t2.second - t1.second );
  14175. %@AS@%  }%@AE@%%@NL@%
  14176. %@NL@%
  14177. %@NL@%
  14178. %@4@%%@AB@%Union Order and Alignment%@AE@%%@EH@%%@NL@%
  14179. %@NL@%
  14180. Programmers use unions most often for two purposes: to store data whose
  14181. exact type is not known until run time or to access the same data in
  14182. different ways.  %@NL@%
  14183. %@NL@%
  14184. Unions falling into the second category are usually not portable. For
  14185. example, the union below is not portable:  %@NL@%
  14186. %@NL@%
  14187. %@AS@%  union tag_u
  14188. %@AS@%  {
  14189. %@AS@%   char bytes_in_long[4];
  14190. %@AS@%   long a_long;
  14191. %@AS@%  };%@AE@%%@NL@%
  14192. %@NL@%
  14193. The intent of the union above is to access the individual bytes of a
  14194. variable of type %@AB@%long%@AE@%. However, the union may not work as intended when
  14195. ported to other computers because  %@NL@%
  14196. %@NL@%
  14197. %@NL@%
  14198.   ■   It relies on a constant size for type %@AB@%long%@AE@%.%@NL@%
  14199. %@NL@%
  14200.   ■   It may assume byte ordering within a variable of type %@AB@%long%@AE@%. (Byte
  14201.       ordering is described in detail in Section 13.1.3, "Byte Order in a
  14202.       Word.")%@NL@%
  14203. %@NL@%
  14204. %@NL@%
  14205. The first problem can be addressed by coding the union as follows:  %@NL@%
  14206. %@NL@%
  14207. %@AS@%  union tag_u 
  14208. %@AS@%  {
  14209. %@AS@%   char bytes_in_long[sizeof( long ) / sizeof( char )];
  14210. %@AS@%   long a_long;
  14211. %@AS@%  };%@AE@%%@NL@%
  14212. %@NL@%
  14213. Note the use of the %@AB@%sizeof%@AE@% operator to determine the size of a data type.  %@NL@%
  14214. %@NL@%
  14215. %@NL@%
  14216. %@3@%%@CR:C6A00130005 @%%@AB@%13.1.3  Byte Order in a Word%@AE@%%@EH@%%@NL@%
  14217. %@NL@%
  14218. The order of bytes within a word (%@AB@%int %@AE@%or %@AB@%short%@AE@%) or a double word (%@AB@%long%@AE@%) can
  14219. vary among machines. Code that assumes an internal order is not portable, as
  14220. shown by this example:  %@NL@%
  14221. %@NL@%
  14222. %@AS@%  /*
  14223. %@AS@%   * Nonportable structure to access an
  14224. %@AS@%   * int in bytes.
  14225. %@AS@%   */
  14226. %@AS@%  struct tag_int_bytes
  14227. %@AS@%  {
  14228. %@AS@%      char lobyte;
  14229. %@AS@%      char hibyte;
  14230. %@AS@%  };%@AE@%%@NL@%
  14231. %@NL@%
  14232. A more portable way to access the individual bytes in a word is to define
  14233. two macros that rely on the constant %@AB@%CHAR_BIT%@AE@%, defined in LIMITS.H:  %@NL@%
  14234. %@NL@%
  14235. %@AS@%  #define LOBYTE(a) (char)((a) & 0xff)
  14236. %@AS@%  #define HIBYTE(a) (char)((unsigned)(a) >> CHAR_BIT)%@AE@%%@NL@%
  14237. %@NL@%
  14238. The %@AB@%LOBYTE%@AE@% macro is still not completely portable. It assumes that a %@AB@%char %@AE@%is
  14239. eight bits long, and it uses the constant %@AS@% 0xff %@AE@% to mask the high-order
  14240. eight bits. Because portable programs cannot rely on a given number of bits
  14241. in a byte, consider the revision below:  %@NL@%
  14242. %@NL@%
  14243. %@AS@%  #define LOBYTE(a) (char)((a) & ((unsigned)~0>>CHAR_BIT))
  14244. %@AS@%  #define HIBYTE(a) (char)((unsigned)(a) >> CHAR_BIT)%@AE@%%@NL@%
  14245. %@NL@%
  14246. The new %@AB@%LOBYTE %@AE@%macro performs a bitwise complement on 0; that is, all zero
  14247. bits are turned into ones. It then takes that unsigned quantity and shifts
  14248. it right far enough to create a mask of the correct length for the
  14249. implementation.  %@NL@%
  14250. %@NL@%
  14251. The following code assumes that the order of bytes in a word will be
  14252. leastsignificant first:  %@NL@%
  14253. %@NL@%
  14254. %@AS@%  int c;
  14255. %@AS@%      .
  14256. %@AS@%      .
  14257. %@AS@%      .
  14258. %@AS@%      fread( &c, sizeof( char ), 1, fp );%@AE@%%@NL@%
  14259. %@NL@%
  14260. The code attempts to read one byte as an %@AB@%int%@AE@%, without converting it from a
  14261. %@AB@%char%@AE@%. However, the code will fail in any implementation where the low-order
  14262. byte is not the first byte of an %@AB@%int%@AE@%. The following solution is more
  14263. portable. In the example below, the data is read into an intermediate
  14264. variable of type %@AB@%char%@AE@% before being assigned to the integer variable.  %@NL@%
  14265. %@NL@%
  14266. %@AS@%  int c;
  14267. %@AS@%      char ch;
  14268. %@AS@%      .
  14269. %@AS@%      .
  14270. %@AS@%      .
  14271. %@AS@%      fread( &ch, sizeof( char ), 1, fp );
  14272. %@AS@%      c = ch;%@AE@%%@NL@%
  14273. %@NL@%
  14274. The example below shows how to use the C run-time function %@AB@%fgetc%@AE@% to return
  14275. the value. The %@AB@%fgetc%@AE@% function returns type %@AB@%char%@AE@%, but the value is promoted
  14276. to type %@AB@%int%@AE@% when it is assigned to a variable of type %@AB@%int%@AE@%.  %@NL@%
  14277. %@NL@%
  14278. %@AS@%  int c;
  14279. %@AS@%      .
  14280. %@AS@%      .
  14281. %@AS@%      .
  14282. %@AS@%      c = fgetc( fp );%@AE@%%@NL@%
  14283. %@NL@%
  14284. %@NL@%
  14285. %@4@%%@AB@%Microsoft C Specific%@AE@%%@EH@%%@NL@%
  14286. %@NL@%
  14287. Microsoft C normally aligns data types longer than one byte to an even-byte
  14288. address for improved performance. See the /Zp compiler option and the %@AB@%pack%@AE@%
  14289. pragma in the %@AI@%Microsoft C Reference%@AE@% and in on-line help for information
  14290. about controlling structure packing in Microsoft C.  %@NL@%
  14291. %@NL@%
  14292. %@NL@%
  14293. %@3@%%@CR:C6A00130006 @%%@AB@%13.1.4  Reading and Writing Structures%@AE@%%@EH@%%@NL@%
  14294. %@NL@%
  14295. Many C programs read data from disk into structures and write data to disk
  14296. from structures. The functions that perform disk I/O in C require you to
  14297. specify the number of bytes to be transferred. You should always use the
  14298. %@AB@%sizeof%@AE@% operator to obtain the size of the data to be read or written because
  14299. differing data type sizes or alignment schemes may alter the size of a given
  14300. structure. For example,  %@NL@%
  14301. %@NL@%
  14302. %@AS@%  fread( &my_struct, sizeof(my_struct), 1, fp );%@AE@%%@NL@%
  14303. %@NL@%
  14304. %@NL@%
  14305. %@4@%%@AB@%Microsoft C Specific%@AE@%%@EH@%%@NL@%
  14306. %@NL@%
  14307. When performing disk input and output in Microsoft C, structures may be
  14308. different sizes depending on the structure-packing option you have selected
  14309. (see the /Zp compiler option and the %@AB@%pack%@AE@% pragma in the %@AI@%Microsoft C
  14310. %@AI@%Reference%@AE@%).  %@NL@%
  14311. %@NL@%
  14312. %@NL@%
  14313. %@3@%%@CR:C6A00130007 @%%@AB@%13.1.5  Bit Fields in Structures%@AE@%%@EH@%%@NL@%
  14314. %@NL@%
  14315. The Microsoft C compiler implements bit fields. However, many C compilers
  14316. do not.  %@NL@%
  14317. %@NL@%
  14318. Bit fields allow you to access the individual bits within a data item. While
  14319. the practice of accessing the bits in a data item is inherently nonportable,
  14320. you can  %@NL@%
  14321. %@NL@%
  14322. improve your chances of porting a program that uses bit fields if you make
  14323. no assumptions about order of assignment, or size and alignment of bit
  14324. fields.  %@NL@%
  14325. %@NL@%
  14326. %@NL@%
  14327. %@4@%%@AB@%Order of Assignment%@AE@%%@EH@%%@NL@%
  14328. %@NL@%
  14329. The order of assignment of bit fields in memory is left to the
  14330. implementation, so you cannot rely on a particular entry in a bit field
  14331. structure to be in a higher order position than another. (This problem is
  14332. similar to the portability constraint imposed by alignment of basic data
  14333. types in structures. The C language does not define any specific layout for
  14334. the storage of data items relative to one another.) See Section 13.1.2,
  14335. "Storage Order and Alignment" for more information.  %@NL@%
  14336. %@NL@%
  14337. %@NL@%
  14338. %@4@%%@AB@%Size and Alignment of Bit Fields%@AE@%%@EH@%%@NL@%
  14339. %@NL@%
  14340. The Microsoft C compiler supports bit fields up to the size of the type
  14341. %@AB@%long%@AE@%. Each individual member of the bit field structure can be up to the
  14342. size of the declared type. Some compilers do not support bit field-structure
  14343. elements that are longer than type %@AB@%int%@AE@%.  %@NL@%
  14344. %@NL@%
  14345. The example below defines a bit field, %@AS@% short_bitfield%@AE@%, that is shorter than
  14346. type %@AB@%int%@AE@%:  %@NL@%
  14347. %@NL@%
  14348. %@AS@%  struct short_bitfield
  14349. %@AS@%  {
  14350. %@AS@%      unsigned usr_bkup : 1; /* 0  <= usr_bkup <  1 */
  14351. %@AS@%      unsigned usr_sec  : 4; /* 9 <= usr_sec < 16 */
  14352. %@AS@%  };%@AE@%%@NL@%
  14353. %@NL@%
  14354. The example below defines a bit field, %@AS@% long_bitfield%@AE@%, that has elements
  14355. longer than type %@AB@%int%@AE@%:  %@NL@%
  14356. %@NL@%
  14357. %@AS@%  struct long_bitfield
  14358. %@AS@%  {
  14359. %@AS@%      unsigned long disk_pos : 22;  /* 0 <= disk_pos   < 4,194,304 */
  14360. %@AS@%      unsigned long rec_no   : 10;  /* 0 <= rec_no < 1,024 */
  14361. %@AS@%  };%@AE@%%@NL@%
  14362. %@NL@%
  14363. The bit field %@AS@% short_bitfield %@AE@% is likely to be supported by more
  14364. implementations than %@AS@% long_bitfield%@AE@%.  %@NL@%
  14365. %@NL@%
  14366. %@NL@%
  14367. %@4@%%@AB@%Microsoft C Specific%@AE@%%@EH@%%@NL@%
  14368. %@NL@%
  14369. The example below introduces another portability issue: alignment of data
  14370. defined in bit fields. The Microsoft C compiler does not allow an element in
  14371. a structure to extend across two words. The first two elements, %@AS@% day %@AE@% and %@AS@%
  14372. %@AS@%month%@AE@%, take up nine bits. The third, %@AS@% year%@AE@%, would extend across a word
  14373. boundary, so it must begin on the next word boundary.  %@NL@%
  14374. %@NL@%
  14375. %@AS@%  struct long_bitfield
  14376. %@AS@%  {
  14377. %@AS@%      unsigned int day    : 5;  /* 0 <= day   < 32 */
  14378. %@AS@%      unsigned int month  : 4;  /* 0 <= month < 16 */
  14379. %@AS@%      unsigned int year   : 11; /* 0 <= year  < 2048 */
  14380. %@AS@%  };%@AE@%%@NL@%
  14381. %@NL@%
  14382. Figure 13.1 illustrates the example above.  %@NL@%
  14383. %@NL@%
  14384. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  14385. %@NL@%
  14386. Other compilers may not use the same storage techniques.  %@NL@%
  14387. %@NL@%
  14388. %@NL@%
  14389. %@3@%%@CR:C6A00130008 @%%@AB@%13.1.6  Processor Arithmetic Mode%@AE@%%@EH@%%@NL@%
  14390. %@NL@%
  14391. Two types of arithmetic are common on digital computers: one's-complement
  14392. arithmetic and two's-complement arithmetic. Some programs assume that all
  14393. target computers perform two's-complement arithmetic. If you take advantage
  14394. of the fact that a given operation causes a particular bit pattern to be set
  14395. on either a one's-complement or two's-complement computer, your program will
  14396. not be portable. For example, two's-complement machines represent the
  14397. eight-bit integer value -1 as a binary 11111111. A one's-complement machine
  14398. represents the same decimal value (-1) as 11111110. Some programmers assume
  14399. that -1 will fill a byte or a word with ones, and use it to construct a mask
  14400. template that they later shift. This will not work correctly on
  14401. one's-complement machines, but the error will not surface until the
  14402. least-significant bit is used.  %@NL@%
  14403. %@NL@%
  14404. In two's-complement arithmetic, there is only one value that represents
  14405. zero. In one's-complement arithmetic, there is a value for zero and a value
  14406. for negative zero. Use the C relational operators to handle this anomaly
  14407. correctly; if you write code that deliberately circumvents the C relational
  14408. operators, tests for zero or %@AB@%NULL %@AE@%may not operate correctly.  %@NL@%
  14409. %@NL@%
  14410. %@NL@%
  14411. %@4@%%@AB@%Microsoft C Specific%@AE@%%@EH@%%@NL@%
  14412. %@NL@%
  14413. Microsoft C produces code only for the Intel 80%@AI@%x%@AE@%86 processors, which all
  14414. perform two's-complement arithmetic.  %@NL@%
  14415. %@NL@%
  14416. %@NL@%
  14417. %@3@%%@CR:C6A00130009 @%%@AB@%13.1.7  Pointers%@AE@%%@EH@%%@NL@%
  14418. %@NL@%
  14419. One of the most powerful but potentially dangerous features of the C
  14420. language is its use of indirect addressing through pointers. Bugs introduced
  14421. by misusing pointers can be difficult to detect and isolate because the
  14422. error often corrupts memory unpredictably.  %@NL@%
  14423. %@NL@%
  14424. %@NL@%
  14425. %@4@%%@AB@%Casting Pointers%@AE@%%@EH@%%@NL@%
  14426. %@NL@%
  14427. Be sure you do not make nonportable assumptions when casting pointers to
  14428. different types.  %@NL@%
  14429. %@NL@%
  14430. %@AS@%  /* Nonportable coercion */
  14431. %@AS@%  char c[4];
  14432. %@AS@%  long *lp;
  14433. %@AS@%  
  14434. %@AS@%  lp = (long *)c;
  14435. %@AS@%  *lp = 0x12345678L;%@AE@%%@NL@%
  14436. %@NL@%
  14437. This code is nonportable because using a cast to change an array of %@AB@%char%@AE@% to
  14438. a pointer of type %@AB@%long%@AE@% assumes a particular byte-ordering scheme. This is
  14439. discussed in greater detail in Section 13.1.3, "Byte Order in a Word."  %@NL@%
  14440. %@NL@%
  14441. %@NL@%
  14442. %@4@%%@AB@%Pointer Size%@AE@%%@EH@%%@NL@%
  14443. %@NL@%
  14444. A pointer can be assigned (or cast) to any integer type large enough to hold
  14445. it, but the size of the integer type depends on the machine and the
  14446. implementation. (In fact, it can even depend on the memory model.)
  14447. Therefore, you cannot assume:  %@NL@%
  14448. %@NL@%
  14449. %@AS@%  sizeof( char * ) == sizeof( int )%@AE@%%@NL@%
  14450. %@NL@%
  14451. To determine the size of any unmodified data pointer, use  %@NL@%
  14452. %@NL@%
  14453. %@AS@%  sizeof( void * )%@AE@%%@NL@%
  14454. %@NL@%
  14455. the size of a generic data pointer.  %@NL@%
  14456. %@NL@%
  14457. %@NL@%
  14458. %@4@%%@AB@%Pointer Subtraction%@AE@%%@EH@%%@NL@%
  14459. %@NL@%
  14460. Code that assumes that pointer subtraction yields an %@AB@%int%@AE@% value is
  14461. nonportable. Pointer subtraction yields a result of type %@AB@%ptrdiff_t%@AE@% (defined
  14462. in STDDEF.H). Portable code must always use variables of type %@AB@%ptrdiff_t%@AE@% for
  14463. storing the result of pointer subtraction.  %@NL@%
  14464. %@NL@%
  14465. %@NL@%
  14466. %@4@%%@AB@%The Null Pointer%@AE@%%@EH@%%@NL@%
  14467. %@NL@%
  14468. In most implementations, %@AB@%NULL%@AE@% is defined as 0. In Microsoft C, it is defined
  14469. as %@AS@% ((void *)0)%@AE@%. Because code pointers and data pointers are often different
  14470. sizes, using 0 for the null pointer for both can lead to nonportability. The
  14471. difference in size between code pointers and data pointers will cause
  14472. problems for functions that expect pointer arguments longer than an %@AB@%int%@AE@%. To
  14473. avoid these problems, use the null pointer, as defined in the include file
  14474. STDDEF.H; use prototypes; or explicitly cast %@AB@%NULL %@AE@%to the correct data type.
  14475. Here is a portable way to use the null pointer:  %@NL@%
  14476. %@NL@%
  14477. %@AS@%  /* Portable use of the NULL pointer */
  14478. %@AS@%  main()
  14479. %@AS@%  {
  14480. %@AS@%      func1( (char *)NULL );
  14481. %@AS@%      func2( (void *(*)())NULL );
  14482. %@AS@%  }
  14483. %@AS@%  
  14484. %@AS@%  void func1( char * c )
  14485. %@AS@%  {
  14486. %@AS@%  }
  14487. %@AS@%  
  14488. %@AS@%  void func2( void *(* func)() )
  14489. %@AS@%  {
  14490. %@AS@%  }%@AE@%%@NL@%
  14491. %@NL@%
  14492. The invocations of %@AS@% func1 %@AE@% and %@AS@% func2 %@AE@% explicitly cast %@AB@%NULL %@AE@%to the correct
  14493. size. In the case of %@AS@% func1%@AE@%, %@AB@%NULL %@AE@%is cast to type %@AB@%char *%@AE@%; in the case of %@AS@%
  14494. %@AS@%func2%@AE@%, it is cast to a pointer to a function that returns type %@AB@%void%@AE@%.  %@NL@%
  14495. %@NL@%
  14496. %@NL@%
  14497. %@4@%%@AB@%Microsoft C Specific%@AE@%%@EH@%%@NL@%
  14498. %@NL@%
  14499. Subtraction of pointers to huge arrays that have more than 32,767 elements
  14500. may yield a %@AB@%long%@AE@% result. The %@AB@%_huge%@AE@% keyword is implementation-defined by
  14501. Microsoft C and is not portable. Here is how to subtract pointers to huge
  14502. arrays:%@CR:C6A00130010 @%  %@NL@%
  14503. %@NL@%
  14504. %@AS@%  char _huge *a;
  14505. %@AS@%  char _huge *b;
  14506. %@AS@%  long        d;
  14507. %@AS@%  .
  14508. %@AS@%  .
  14509. %@AS@%  .
  14510. %@AS@%  d = (long)( a - b );%@AE@%%@NL@%
  14511. %@NL@%
  14512. In Microsoft C, the memory model selected and the special keywords %@AB@%_near%@AE@%,
  14513. %@AB@%_far%@AE@%, and %@AB@%_huge %@AE@%can change the size of a pointer. The Microsoft memory
  14514. models and extended keywords are nonportable, but you should be aware of
  14515. their effects.%@CR:C6A00130011 @%%@CR:C6A00130012 @%%@CR:C6A00130013 @%  %@NL@%
  14516. %@NL@%
  14517. Sizes of generic pointers and default pointer sizes are shown in Tables 13.2
  14518. and 13.3, respectively.  %@NL@%
  14519. %@NL@%
  14520. %@AB@%Table 13.2  %@AB@%Size of Generic Pointers%@AE@%%@AE@%
  14521.  
  14522. %@TH:   6   438 02 15 23 38 @%Declaration    Name                   Size%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%void _near *%@AE@%   Generic near pointer   16 bits%@AB@%void _far *%@AE@%    Generic far pointer    32 bits%@AB@%void _huge *%@AE@%   Generic huge pointer   32 bits%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   6   438 02 15 23 38 @%
  14523.  
  14524. %@AB@%Table 13.3  %@AB@%Default Pointer Sizes%@AE@%%@AE@%
  14525.  
  14526. %@TH:   9   518 02 14 19 43 @%Memory Model  Code Pointer Size  Data Pointer Size%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Tiny          16 bits            16 bitsSmall         16 bits            16 bitsMedium        32 bits            16 bitsCompact       16 bits            32 bitsLarge         32 bits            32 bitsHuge          32 bits            32 bits%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   9   518 02 14 19 43 @%
  14527.  
  14528. %@NL@%
  14529. %@3@%%@CR:C6A00130014 @%%@AB@%13.1.8  Address Space%@AE@%%@EH@%%@NL@%
  14530. %@NL@%
  14531. The amount of available memory and the address space on systems varies,
  14532. depending on many factors outside your control. A program designed with
  14533. portability in mind should handle insufficient-memory situations. To ensure
  14534. that your program handles these situations, you should always check the
  14535. error return from any of the dynamic memory allocation routines, such as
  14536. %@AB@%malloc%@AE@%, %@AB@%calloc%@AE@%, %@AB@%strdup%@AE@%, and %@AB@%realloc%@AE@%.  %@NL@%
  14537. %@NL@%
  14538. These situations occur not only because of a lack of installed memory but
  14539. also because too many other applications are using memory. For example,  %@NL@%
  14540. %@NL@%
  14541. %@NL@%
  14542.   ■   Installed resident software can cause your program to fail. In DOS,
  14543.       these programs are usually device drivers or
  14544.       terminate-and-stay-resident (TSR) utilities.%@NL@%
  14545. %@NL@%
  14546.   ■   An event or combination of events in a multitasking operating system
  14547.       such as OS/2 or XENIX can cause your program to fail. These failures
  14548.       are complex and difficult to predict. Here is an example: the user has
  14549.       installed a daemon to "pop up" every so often and check the system
  14550.       status. The user is running your application along with enough other
  14551.       large applications to cause a critical shortage of memory. When the
  14552.       daemon pops up, your program may fail on a memory allocation request.%@NL@%
  14553. %@NL@%
  14554.   ■   An application running under Windows can use an extraordinary amount
  14555.       of the global heap and not return it to the free pool. This type of
  14556.       behavior will cause Windows to deny a %@AB@%GlobalAlloc%@AE@% request.%@NL@%
  14557. %@NL@%
  14558. %@NL@%
  14559. %@NL@%
  14560. %@3@%%@CR:C6A00130015 @%%@AB@%13.1.9  Character Set%@AE@%%@EH@%%@NL@%
  14561. %@NL@%
  14562. The C language does not define the character set used in an implementation.
  14563. This means that any programs that assume the character set to be ASCII are
  14564. nonportable.  %@NL@%
  14565. %@NL@%
  14566. The only restrictions on the character set are these:  %@NL@%
  14567. %@NL@%
  14568. %@NL@%
  14569.   ■   No character in the implementation's character set may be larger than
  14570.       the size of type %@AB@%char%@AE@%.%@NL@%
  14571. %@NL@%
  14572.   ■   Each character in the set must be represented as a positive value by
  14573.       type %@AB@%char%@AE@%, whether it is treated as signed or unsigned. So, in the
  14574.       case of the ASCII character set and an eight-bit %@AB@%char%@AE@%, the maximum
  14575.       value is 127 (128 is a negative number when stored in a %@AB@%char%@AE@%
  14576.       variable).%@NL@%
  14577. %@NL@%
  14578. %@NL@%
  14579. %@NL@%
  14580. %@4@%%@AB@%Character Classification%@AE@%%@EH@%%@NL@%
  14581. %@NL@%
  14582. The standard C run-time support contains a complete set of
  14583. characterclassification macros and functions. These functions are defined in
  14584. the CTYPE.H file and are guaranteed to be portable:  %@NL@%
  14585. %@NL@%
  14586. %@AB@%isalnum         isdigit         isprint         isupper%@AE@%
  14587. %@AB@%isalpha         isgraph         ispunct         isxdigit%@AE@%
  14588. %@AB@%iscntrl         islower         isspace         
  14589.  
  14590. The following code fragment is not portable to implementations that do not
  14591. use the ASCII character set:  %@NL@%
  14592. %@NL@%
  14593. %@AS@%  /* Nonportable */
  14594. %@AS@%  if( c >= 'A' && c <= 'Z' )
  14595. %@AS@%      /* uppercase alphabetic */%@AE@%%@NL@%
  14596. %@NL@%
  14597. Instead, consider using this:  %@NL@%
  14598. %@NL@%
  14599. %@AS@%  /* Portable */
  14600. %@AS@%  if( isalpha(c) && isupper(c) )
  14601. %@AS@%      /* uppercase alphabetic */%@AE@%%@NL@%
  14602. %@NL@%
  14603. The first example above is nonportable, because it assumes that uppercase %@AS@% A
  14604. %@AS@%%@AE@% is represented by a smaller value than uppercase %@AS@% Z%@AE@%, and that no lowercase
  14605. characters fall between the values of %@AS@% A %@AE@% and %@AS@% Z%@AE@%. The second example is
  14606. portable, because it uses the character classification functions to perform
  14607. the tests.  %@NL@%
  14608. %@NL@%
  14609. In a portable program, you should not perform any comparison on variables of
  14610. type %@AB@%char%@AE@% except strict equality (==). You cannot assume the character set
  14611. follows an increasing sequence─that may not be true on a different machine.
  14612. %@NL@%
  14613. %@NL@%
  14614. %@NL@%
  14615. %@4@%%@AB@%Case Translation%@AE@%%@EH@%%@NL@%
  14616. %@NL@%
  14617. Translation of characters from upper- to lowercase or from lowerto uppercase
  14618. is called "case translation." The following example shows a coding technique
  14619. for case translation not portable to implementations using a non-ASCII
  14620. character set.  %@NL@%
  14621. %@NL@%
  14622. %@AS@%  #define make_upper(c) ((c)&0xcf)
  14623. %@AS@%  #define make_lower(c) ((c)|0x20)%@AE@%%@NL@%
  14624. %@NL@%
  14625. This code takes advantage of the fact that you can map uppercase to
  14626. lowercase simply by changing the state of bit 6. It is extremely efficient
  14627. but nonportable. To write portable code, use the case-translation macros
  14628. %@AB@%toupper%@AE@% and %@AB@%tolower%@AE@% (defined in CTYPE.H).  %@NL@%
  14629. %@NL@%
  14630. %@NL@%
  14631. %@2@%%@CR:C6A00130016 @%%@AB@%13.2  Assumptions about the Compiler%@AE@%%@EH@%%@NL@%
  14632. %@NL@%
  14633. Different compilers translate C source code into object code in different
  14634. ways. The ANSI draft standard for the C programming language defines how
  14635. many of these translations must be done; others are implementation-defined.
  14636. %@NL@%
  14637. %@NL@%
  14638. This section describes assumptions about how the compiler translates your C
  14639. code, which can make your programs nonportable. For a complete description
  14640. of how Microsoft C handles implementation-defined operations, see Appendix
  14641. C, "Implementation-Defined Behavior."  %@NL@%
  14642. %@NL@%
  14643. %@NL@%
  14644. %@3@%%@CR:C6A00130017 @%%@AB@%13.2.1  Sign Extension%@AE@%%@EH@%%@NL@%
  14645. %@NL@%
  14646. "Sign extension" is the propagation of the sign bit to fill unoccupied space
  14647. when promoting to a more-significant type or when performing bitwise
  14648. right-shift operations.  %@NL@%
  14649. %@NL@%
  14650. %@NL@%
  14651. %@4@%%@AB@%Promotion from Shorter Types%@AE@%%@EH@%%@NL@%
  14652. %@NL@%
  14653. Integral promotions from shorter types occur when you make an assignment,
  14654. perform arithmetic, perform a comparison, or perform an explicit cast.  %@NL@%
  14655. %@NL@%
  14656. The behavior of integral promotion is well defined, except for type %@AB@%char%@AE@%.
  14657. The implementation defines whether type %@AB@%char%@AE@% is treated as signed or
  14658. unsigned. The code fragment below is an example of promotion as a result of
  14659. assignment:  %@NL@%
  14660. %@NL@%
  14661. %@AS@%  char c1 = -3;
  14662. %@AS@%  int  i1;
  14663. %@AS@%  
  14664. %@AS@%  i1 = c1;%@AE@%%@NL@%
  14665. %@NL@%
  14666. In this example, the expected result of the assignment statement is that %@AS@% i1
  14667. %@AS@%%@AE@% will be set to -3. If the implementation defines type %@AB@%char%@AE@% as unsigned,
  14668. however, sign extension will not occur, and %@AS@% i1 %@AE@% will be 253 (on a
  14669. two's-complement machine).  %@NL@%
  14670. %@NL@%
  14671. Promotion can also occur as a result of a comparison of different types:  %@NL@%
  14672. %@NL@%
  14673. %@AS@%  char c;
  14674. %@AS@%  
  14675. %@AS@%  if( c == 0x80 )
  14676. %@AS@%      .
  14677. %@AS@%      .
  14678. %@AS@%      .%@AE@%%@NL@%
  14679. %@NL@%
  14680. This comparison will never evaluate as true on an implementation that
  14681. signextends %@AB@%char%@AE@% types but treats hexadecimal constants as unsigned. Use a
  14682. character constant of the form %@AB@%'\x80'%@AE@%, or explicitly cast the constant to
  14683. type %@AB@%char%@AE@% to perform the comparison correctly.  %@NL@%
  14684. %@NL@%
  14685. The following comparison, which is an example of promotion as a result of a
  14686. cast, is also nonportable:  %@NL@%
  14687. %@NL@%
  14688. %@AS@%  char c;
  14689. %@AS@%  unsigned int u;
  14690. %@AS@%  
  14691. %@AS@%  if( u == (unsigned)c )%@AE@%%@NL@%
  14692. %@NL@%
  14693. There are two problems with this code:  %@NL@%
  14694. %@NL@%
  14695. %@NL@%
  14696.   ■   The %@AB@%char%@AE@% type may be treated as signed or unsigned, depending on the
  14697.       implementation.%@NL@%
  14698. %@NL@%
  14699.   ■   If the %@AB@%char%@AE@% type is treated as signed, it can be converted to %@AB@%unsigned%@AE@%
  14700.       in two different ways: the %@AB@%char%@AE@% value may first be sign-extended to
  14701.       %@AB@%int%@AE@%, then converted to %@AB@%unsigned%@AE@%; or the %@AB@%char%@AE@% may be converted to
  14702.       %@AB@%unsigned char%@AE@%, then sign-extended to %@AB@%int%@AE@% length.%@NL@%
  14703. %@NL@%
  14704. %@NL@%
  14705. It is always safe to compare a %@AB@%signed int%@AE@% with a %@AB@%char%@AE@% constant because C
  14706. requires all character constants to be positive.  %@NL@%
  14707. %@NL@%
  14708. Variables of type %@AB@%char%@AE@% are promoted to type %@AB@%int%@AE@% when passed as arguments to
  14709. a function. This will cause sign extension on some machines. Consider the
  14710. following code:  %@NL@%
  14711. %@NL@%
  14712. %@AS@%  char c = 128;
  14713. %@AS@%  
  14714. %@AS@%  printf( "%d\n", c );%@AE@%%@NL@%
  14715. %@NL@%
  14716. %@NL@%
  14717. %@4@%%@AB@%Microsoft C Specific%@AE@%%@EH@%%@NL@%
  14718. %@NL@%
  14719. Microsoft C allows you to treat type %@AB@%char%@AE@% as signed or unsigned. By default,
  14720. a %@AB@%char%@AE@% is considered signed, but if you change the default %@AB@%char%@AE@% type using
  14721. the /J compiler option, you can treat it as unsigned.  %@NL@%
  14722. %@NL@%
  14723. %@NL@%
  14724. %@4@%%@AB@%Bitwise Right-Shift Operations%@AE@%%@EH@%%@NL@%
  14725. %@NL@%
  14726. Positive or unsigned integral types (%@AB@%char%@AE@%, %@AB@%short%@AE@%, %@AB@%int%@AE@%, and %@AB@%long%@AE@%) yield
  14727. positive or zero values after a right bitwise shift (>>) operation. For
  14728. example,  %@NL@%
  14729. %@NL@%
  14730. %@AS@%  (char)120 >> 4%@AE@%%@NL@%
  14731. %@NL@%
  14732. yields 7,  %@NL@%
  14733. %@NL@%
  14734. %@AS@%  (unsigned char)240 >> 8%@AE@%%@NL@%
  14735. %@NL@%
  14736. yields 0,  %@NL@%
  14737. %@NL@%
  14738. %@AS@%  (int)500 >> 8%@AE@%%@NL@%
  14739. %@NL@%
  14740. yields 1, and  %@NL@%
  14741. %@NL@%
  14742. %@AS@%  (unsigned int)65535 >> 4%@AE@%%@NL@%
  14743. %@NL@%
  14744. yields 4,095.  %@NL@%
  14745. %@NL@%
  14746. Negative-signed integral types yield implementation-defined values after a
  14747. bitwise right-shift operation. This means that you must know whether you
  14748. want to do a signed or unsigned shift, then code accordingly.  %@NL@%
  14749. %@NL@%
  14750. If you don't know how the implementation performs, you may get unexpected
  14751. results. For example, %@AS@% (signed char)0x80 >> 3 %@AE@% yields 0xf0 if the
  14752. imple-mentation performs sign extension on right bitwise shifts. If the
  14753. implementation does not perform the sign extension, the result is 0x10.  %@NL@%
  14754. %@NL@%
  14755. You can use right shifts to speed up division when the divisor can be
  14756. represented by powers of 2 and the dividend is positive. To maintain
  14757. portability, you should use the division operator.  %@NL@%
  14758. %@NL@%
  14759. To perform an unsigned shift, explicitly cast the data to an unsigned type.
  14760. To perform a shift that extends the sign bit, use the division operator as
  14761. follows: divide by 2n, where %@AI@%n%@AE@% is the number of bits you want to shift.  %@NL@%
  14762. %@NL@%
  14763. %@NL@%
  14764. %@3@%%@CR:C6A00130018 @%%@AB@%13.2.2  Length and Case of Identifiers%@AE@%%@EH@%%@NL@%
  14765. %@NL@%
  14766. Some implementations do not support long identifiers. Some allow only 6
  14767. characters, while others allow as many as 32. They may report each
  14768. identifier that exceeds the maximum length or truncate identifiers to a
  14769. given length. Truncation causes serious problems, especially if you have a
  14770. number of similarly named variables within the scope of a block of code,
  14771. such as the following:  %@NL@%
  14772. %@NL@%
  14773. %@AS@%  double acct_receivable_30_days;
  14774. %@AS@%  double acct_receivable_60_days;
  14775. %@AS@%  double acct_receivable_90_days;
  14776. %@AS@%  double current_interest_rate;
  14777. %@AS@%  
  14778. %@AS@%  acct_receivable_30_days *= current_interest_rate;%@AE@%%@NL@%
  14779. %@NL@%
  14780. If your target system retains only six significant characters, you will have
  14781. to rename all your %@AS@% acct_receivable %@AE@% variables.  %@NL@%
  14782. %@NL@%
  14783. Case sensitivity also affects portability. C is usually a case-sensitive
  14784. language. That is, %@AS@% CalculateInterest %@AE@% is not considered the same identifier
  14785. as %@AS@%calculateinterest%@AE@%. Some systems are not case sensitive, however, so to
  14786. write portable code, differentiate your identifiers by something other than
  14787. case.  %@NL@%
  14788. %@NL@%
  14789. These problems with identifiers can occur in two locations: the compiler and
  14790. the linker or loader. Even if the compiler can handle long and
  14791. case-differentiated identifiers, if the linker or loader cannot, you can get
  14792. duplicate definitions or other unexpected errors.  %@NL@%
  14793. %@NL@%
  14794. %@NL@%
  14795. %@4@%%@AB@%Microsoft C Specific%@AE@%%@EH@%%@NL@%
  14796. %@NL@%
  14797. The Microsoft C compiler issues the /NOIGNORECASE command to the Microsoft
  14798. Segmented-Executable Linker (LINK), specifically instructing it to consider
  14799. the case of identifiers.  %@NL@%
  14800. %@NL@%
  14801. %@NL@%
  14802. %@3@%%@CR:C6A00130019 @%%@AB@%13.2.3  Register Variables%@AE@%%@EH@%%@NL@%
  14803. %@NL@%
  14804. The number and type of register variables in a function depend on the
  14805. implementation. You can declare more variables as %@AB@%register %@AE@%than the number
  14806. of physical registers the implementation uses. In such a case, the compiler
  14807. treats the excess register variables as %@AB@%automatic%@AE@%.  %@NL@%
  14808. %@NL@%
  14809. Since the types that qualify for %@AB@%register%@AE@% class differ among
  14810. implementations, invalid %@AB@%register %@AE@%declarations are treated as %@AB@%automatic%@AE@%.  %@NL@%
  14811. %@NL@%
  14812. If you declare variables as %@AB@%register %@AE@%to optimize performance, declare them
  14813. in decreasing order of importance to ensure that the compiler allocates a
  14814. register to the most important variables.  %@NL@%
  14815. %@NL@%
  14816. %@NL@%
  14817. %@4@%%@AB@%Microsoft C Specific%@AE@%%@EH@%%@NL@%
  14818. %@NL@%
  14819. The compiler ignores %@AB@%register%@AE@% declarations if you select the global register
  14820. allocation optimization. You can select global register allocation as
  14821. follows:  %@NL@%
  14822. %@NL@%
  14823. %@AB@%Environment%@AE@%                       %@AB@%Selection%@AE@%
  14824. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14825. CL command line                   Specify either the /Oe or /Ox option.
  14826.  
  14827. PWB                               Select the Global Register Allocation 
  14828.                                   option in the Debug Build Options or 
  14829.                                   Release Build Options dialog boxes.
  14830.  
  14831. pragma                            Use the %@AB@%optimize%@AE@% pragma with the %@AB@%e%@AE@% 
  14832.                                   parameter.
  14833.  
  14834. %@NL@%
  14835. %@3@%%@CR:C6A00130020 @%%@AB@%13.2.4  Functions with a Variable Number of Arguments%@AE@%%@EH@%%@NL@%
  14836. %@NL@%
  14837. Functions that accept a variable number of arguments are not portable.
  14838. Although both the ANSI Standard and %@AI@%The C Programming Language%@AE@% specify how
  14839. to write these functions and how they behave, differences still exist among
  14840. compiler implementors about how to use variable argument lists.  %@NL@%
  14841. %@NL@%
  14842. Many UNIX(R) systems support a standard that differs from the ANSI Standard
  14843. for variable arguments. Although this may change, it currently presents a
  14844. portability concern.  %@NL@%
  14845. %@NL@%
  14846. Microsoft C run-time libraries and macros allow you to use whichever version
  14847. of variable argument support you expect to be most portable for your
  14848. application.  %@NL@%
  14849. %@NL@%
  14850. %@NL@%
  14851. %@3@%%@CR:C6A00130021 @%%@AB@%13.2.5  Evaluation Order%@AE@%%@EH@%%@NL@%
  14852. %@NL@%
  14853. The C language does not guarantee the evaluation order of most expressions.
  14854. Avoid writing constructs that depend on evaluation within an expression to
  14855. proceed in a particular manner. For example,  %@NL@%
  14856. %@NL@%
  14857. %@AS@%  i = 0;
  14858. %@AS@%  func( i++, i++ );
  14859. %@AS@%  .
  14860. %@AS@%  .
  14861. %@AS@%  .
  14862. %@AS@%  func( int a, int b )
  14863. %@AS@%  {%@AE@%%@NL@%
  14864. %@NL@%
  14865. A compiler could evaluate this code fragment and pass 0 as %@AS@% a %@AE@% and 1 as %@AS@% b%@AE@%.
  14866. It could also pass 1 as %@AS@% a %@AE@% and 0 as %@AS@% b %@AE@% and conform equally with the
  14867. standards.  %@NL@%
  14868. %@NL@%
  14869. The C language does guarantee that an expression will be completely
  14870. evaluated at any given "sequence point." A sequence point is a point in the
  14871. syntax of the language at which all side effects of an expression or series
  14872. of expressions have been completed.  %@NL@%
  14873. %@NL@%
  14874. These are the sequence points in the C language:  %@NL@%
  14875. %@NL@%
  14876. %@NL@%
  14877.   1.  The semicolon (;) statement separator%@NL@%
  14878. %@NL@%
  14879.   2.  The call to a function after the arguments have been evaluated%@NL@%
  14880. %@NL@%
  14881.   3.  The end of the first operand of one of the following:
  14882. %@NL@%
  14883.       ■   Logical AND (%@AB@%&&%@AE@%)%@NL@%
  14884. %@NL@%
  14885.       ■   Logical OR (%@AB@%||%@AE@%)%@NL@%
  14886. %@NL@%
  14887.       ■   Conditional (%@AB@%?%@AE@%)%@NL@%
  14888. %@NL@%
  14889.       ■   Comma separator (%@AB@%,%@AE@%) when used to separate statements or in
  14890.           expressions; the comma separator is not a sequence point when it
  14891.           is used between variables in declaration statements or between
  14892.           parameters in a function  invocation%@NL@%
  14893. %@NL@%
  14894. %@NL@%
  14895.   4.  The end of a full expression, such as
  14896. %@NL@%
  14897.       ■   An initializer%@NL@%
  14898. %@NL@%
  14899.       ■   The expression in an expression statement (for example, any
  14900.           expression inside parentheses)%@NL@%
  14901. %@NL@%
  14902.       ■   The controlling expression of a %@AB@%while %@AE@%or %@AB@%do %@AE@%statement%@NL@%
  14903. %@NL@%
  14904.       ■   Any of the three expressions of a %@AB@%for %@AE@%statement%@NL@%
  14905. %@NL@%
  14906.       ■   The expression in a %@AB@%return %@AE@%statement%@NL@%
  14907. %@NL@%
  14908. %@NL@%
  14909. %@NL@%
  14910. %@NL@%
  14911. %@3@%%@CR:C6A00130022 @%%@AB@%13.2.6  Function and Macro Arguments with Side Effects%@AE@%%@EH@%%@NL@%
  14912. %@NL@%
  14913. Run-time support functions can be implemented either as functions or as
  14914. macros. Avoid including expressions with side effects inside function
  14915. invocations unless you are sure the function will not be implemented as a
  14916. macro. Here is an illustration of how an argument with side effects can
  14917. cause problems:  %@NL@%
  14918. %@NL@%
  14919. %@AS@%  #define limit_number(a) ((a>1000)?1000:(a))
  14920. %@AS@%  
  14921. %@AS@%  a = limit_number( a++ );%@AE@%%@NL@%
  14922. %@NL@%
  14923. If %@AS@% a ≤%@AE@% 1000, it is incremented once. If %@AS@% a %@AE@%> 1000, it is incremented twice,
  14924. which is probably not the intended behavior.  %@NL@%
  14925. %@NL@%
  14926. A macro can be used safely with an argument that has side effects if it
  14927. evaluates its parameter only once. You can determine whether a macro is safe
  14928. only by inspecting the code.  %@NL@%
  14929. %@NL@%
  14930. A common example of a run-time support function that is often implemented as
  14931. a macro is %@AB@%toupper%@AE@%. You will find your program's behavior confusing if you
  14932. use the following code:  %@NL@%
  14933. %@NL@%
  14934. %@AS@%  char c;
  14935. %@AS@%  
  14936. %@AS@%  c = toupper( getc() );%@AE@%%@NL@%
  14937. %@NL@%
  14938. If %@AS@% toupper %@AE@% is implemented as a function, %@AS@% getc %@AE@% will be called only once,
  14939. and its return value will be translated to uppercase. However, if %@AS@% toupper %@AE@%
  14940. is implemented as a macro, %@AS@% getc %@AE@% will be called once or twice, depending on
  14941. whether %@AS@% c %@AE@%is upper- or lowercase. Consider the following macro example:  %@NL@%
  14942. %@NL@%
  14943. %@AS@%  #define toupper(c) ( (islower(c)) ? _toupper(c) : (c) )%@AE@%%@NL@%
  14944. %@NL@%
  14945. If you include the %@AB@%toupper%@AE@% macro in your code, the preprocessor expands it
  14946. as follows:  %@NL@%
  14947. %@NL@%
  14948. %@AS@%  /* What you wrote */
  14949. %@AS@%  c = toupper( getc() );
  14950. %@AS@%  
  14951. %@AS@%  /* Macro expansion */
  14952. %@AS@%  ch = (islower( (getc()) ) ? _toupper( getc() ) : (getc()) );%@AE@%%@NL@%
  14953. %@NL@%
  14954. The expansion of the macro shows that the argument to %@AS@% toupper %@AE@% will always
  14955. be called twice: once to determine if the character is lowercase and the
  14956. next time to perform case translation (if necessary). In the example, this
  14957. double evaluation calls the %@AB@%getc%@AE@% function twice. Because %@AS@% getc %@AE@% is a
  14958. function whose side effect is to read a character from the standard input
  14959. device, the example requests two characters from standard input.  %@NL@%
  14960. %@NL@%
  14961. %@NL@%
  14962. %@3@%%@CR:C6A00130023 @%%@AB@%13.2.7  Environment Differences%@AE@%%@EH@%%@NL@%
  14963. %@NL@%
  14964. Many programs perform some file I/O. When writing these programs for
  14965. portability, consider the following:  %@NL@%
  14966. %@NL@%
  14967. %@NL@%
  14968.   ■   Do not hard-code file or path names. Use constants you define either
  14969.       in a header file or at the beginning of the program.%@NL@%
  14970. %@NL@%
  14971.   ■   Do not assume the use of any particular file system. For example, the
  14972.       UNIX-model, hierarchical file system is prevalent on small computers.
  14973.       On larger systems, the file system often follows a different model.%@NL@%
  14974. %@NL@%
  14975.   ■   Do not assume a particular display size (number of rows and columns).%@NL@%
  14976. %@NL@%
  14977.   ■   Do not assume that display attributes exist. Some environments do not
  14978.       support such attributes as color, underlined text, blinking text,
  14979.       highlighted text, inverse text, protected text, or dim text.%@NL@%
  14980. %@NL@%
  14981. %@NL@%
  14982. %@NL@%
  14983. %@2@%%@CR:C6A00130024 @%%@AB@%13.3  Portability of Data Files%@AE@%%@EH@%%@NL@%
  14984. %@NL@%
  14985. Data files are rarely portable across different CPUs. Structures, unions,
  14986. and arrays have varying internal layout and alignment requirements on
  14987. different machines. In addition, byte ordering within words and actual word
  14988. length may vary.  %@NL@%
  14989. %@NL@%
  14990. The best way to achieve data-file portability is to write and read data
  14991. files as one-dimensional character arrays. This procedure prevents alignment
  14992. and padding problems if the data are written and read as characters. The
  14993. only portability problem you are likely to encounter if you follow this
  14994. course is a conflict in character sets; many computers have character-set
  14995. conversion utilities.  %@NL@%
  14996. %@NL@%
  14997. %@NL@%
  14998. %@2@%%@CR:C6A00130025 @%%@AB@%13.4  Portability Concerns Specific to Microsoft C%@AE@%%@EH@%%@NL@%
  14999. %@NL@%
  15000. Microsoft C offers extensions that let you take advantage of the full
  15001. capabilities of the computer. These extensions are not portable to other
  15002. compilers or environments. The following list shows keywords specific to
  15003. Microsoft C:  %@NL@%
  15004. %@NL@%
  15005. %@AB@%_asm               _far            _huge           pascal%@AE@%
  15006. %@AB@%_based          _fastcall       _interrupt      _pascal%@AE@%
  15007. %@AB@%cdecl           fortran         near            _saveregs%@AE@%
  15008. %@AB@%_cdecl          _fortran        _near           _segment%@AE@%
  15009. %@AB@%_export         huge            _loadds         _segname%@AE@%
  15010. %@AB@%far             
  15011.  
  15012. The %@AI@%Microsoft C Reference%@AE@% contains compatibility information for every
  15013. function in the run-time library. Any function or macro that does not have
  15014. the ANSI box marked may not be portable to other compilers or computer
  15015. systems.  %@NL@%
  15016. %@NL@%
  15017. %@NL@%
  15018. %@2@%%@CR:C6A00130026 @%%@AB@%13.5  Microsoft C Byte Ordering%@AE@%%@EH@%%@NL@%
  15019. %@NL@%
  15020. Tables 13.4 and 13.5 summarize Microsoft C byte ordering for %@AB@%short%@AE@% and %@AB@%long%@AE@%
  15021. types, respectively. In these tables, the least-significant byte of the data
  15022. item is b0; the next byte is denoted by b1, and so on.  %@NL@%
  15023. %@NL@%
  15024. Since byte ordering is machine specific, any program that uses this byte
  15025. ordering will not be portable.  %@NL@%
  15026. %@NL@%
  15027. %@AB@%Table 13.4  %@AB@%Byte Ordering for Short Types%@AE@%%@AE@%
  15028.  
  15029. %@TH:   9   473 02 28 48 @%CPU                         Byte Order%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%8086                        b0   b180286                       b0   b1PDP-11(R)                   b0   b1VAX-11(R)                   b0   b1M68000                      b1   b0Z8000(R)                    b1   b0%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   9   473 02 28 48 @%
  15030.  
  15031. %@AB@%Table 13.5  %@AB@%Byte Ordering for Long Types%@AE@%%@AE@%
  15032.  
  15033. %@TH:   9   494 02 25 51 @%CPU                      Byte Order%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%8086                     b0  b1  b2  b380286                    b0  b1  b2  b3PDP-11                   b2  b3  b0  b1VAX-11                   b0  b1  b2  b3M68000                   b3  b2  b1  b0Z8000                    b3  b2  b1  b0%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:   9   494 02 25 51 @%
  15034.  
  15035. %@NL@%
  15036. %@NL@%
  15037. %@NL@%
  15038. %@NL@%
  15039. %@NL@%
  15040. %@CR:C6A-Part 04 @%%@1@%%@AB@%PART IV  OS/2 Support%@AE@%%@EH@%%@NL@%
  15041. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15042. %@NL@%
  15043. The Microsoft C Professional Development System provides support for OS/2
  15044. development.  %@NL@%
  15045. %@NL@%
  15046. Chapter 14 explains many of the general issues of OS/2 development,
  15047. including accessing the OS/2 system functions, creating module-definition
  15048. files, and using the OS/2-specific features of utilities such as the linker
  15049. and BIND. Chapter 15 focuses on how to create a multithread application,
  15050. including information about C run-time library support, potential problem
  15051. areas, and how to use CodeView to debug multithread applications. Chapter 16
  15052. concentrates on the creation of dynamic-link libraries, including C run-time
  15053. library support, application program interface with DLLs, and debugging DLLs
  15054. with CodeView.  %@NL@%
  15055. %@NL@%
  15056. %@NL@%
  15057. %@NL@%
  15058. %@NL@%
  15059. %@NL@%
  15060. %@NL@%
  15061. %@CR:C6A00140001 @%%@1@%%@AB@%Chapter 14  Building OS/2 Applications%@AE@%%@EH@%%@NL@%
  15062. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15063. %@NL@%
  15064. Using Microsoft C 6.0, you can create applications for OS/2. This chapter
  15065. explains features in the compiler and the utilities that  %@NL@%
  15066. %@NL@%
  15067. %@NL@%
  15068.   ■   Call the OS/2 operating system directly from C functions%@NL@%
  15069. %@NL@%
  15070.   ■   Perform multitasking within your program by starting multiple
  15071.       execution paths known as "threads"%@NL@%
  15072. %@NL@%
  15073.   ■   Create dynamic-link libraries that can be used by multiple
  15074.       applications%@NL@%
  15075. %@NL@%
  15076.   ■   Work in either OS/2 or DOS to create programs for both environments%@NL@%
  15077. %@NL@%
  15078.   ■   Develop "dual-mode" applications that will run under both OS/2 and DOS
  15079.       from a single executable program file%@NL@%
  15080. %@NL@%
  15081. %@NL@%
  15082. This chapter contains information about accessing the OS/2 Applications
  15083. Program Interface (API) from your C programs. It also discusses compile
  15084. options that affect applications you develop for OS/2, module-definition
  15085. files and import libraries, linker options specific to developing OS/2
  15086. applications, and using the BIND utility to create dual-mode applications.  %@NL@%
  15087. %@NL@%
  15088. Chapters 15 and 16, "Creating Multithread OS/2 Applications" and
  15089. "Dynamic-Linking with OS/2," contain detailed information about how
  15090. Microsoft C supports these advanced OS/2 features.  %@NL@%
  15091. %@NL@%
  15092. %@NL@%
  15093. %@2@%%@CR:C6A00140002 @%%@AB@%14.1  The OS/2 Applications Program Interface%@AE@%%@EH@%%@NL@%
  15094. %@NL@%
  15095. The entire set of OS/2 system calls is known as the OS/2 API. You need to
  15096. access the OS/2 API for the low-level functions provided by the operating
  15097. system, such as  %@NL@%
  15098. %@NL@%
  15099. %@NL@%
  15100.   ■   Requests for information about the display%@NL@%
  15101. %@NL@%
  15102.   ■   Requests to display information%@NL@%
  15103. %@NL@%
  15104.   ■   Requests for information from the pointing device (mouse)%@NL@%
  15105. %@NL@%
  15106.   ■   Requests for information from the keyboard%@NL@%
  15107. %@NL@%
  15108.   ■   Requests for blocks of memory%@NL@%
  15109. %@NL@%
  15110.   ■   Requests for disk actions, including reading and writing%@NL@%
  15111. %@NL@%
  15112. %@NL@%
  15113. You can call all of the OS/2 system services directly from programs written
  15114. in C. Under DOS, the API operates at a lower level, requiring programs to
  15115. set up hardware registers and generate a software interrupt to access the
  15116. system services. Under OS/2, programs use function calls to access the
  15117. operating system services.  %@NL@%
  15118. %@NL@%
  15119. Sections 14.1.1-14.1.3 describe the calling conventions and precautions you
  15120. must observe when accessing OS/2 API functions.  %@NL@%
  15121. %@NL@%
  15122. %@NL@%
  15123. %@3@%%@CR:C6A00140003 @%%@AB@%14.1.1  Calling the OS/2 API%@AE@%%@EH@%%@NL@%
  15124. %@NL@%
  15125. Your program must declare calls to the OS/2 API with both the %@AB@%_far%@AE@% and
  15126. %@AB@%_pascal%@AE@% keywords. Adding the %@AB@%_pascal%@AE@% keyword to the function declaration
  15127. ensures that the FORTRAN/Pascal calling convention is used. The %@AB@%_far%@AE@% keyword
  15128. directs the compiler to generate an intersegment call instruction. A sample
  15129. declaration for the OS/2 API function %@AB@%DosExit%@AE@% follows:%@CR:C6A00140004 @%  %@NL@%
  15130. %@NL@%
  15131. %@AS@%  void _far _pascal DosExit( unsigned int, unsigned int );%@AE@%%@NL@%
  15132. %@NL@%
  15133. You must be sure that all pointers passed to OS/2 API functions are far
  15134. pointers, even if you are writing a program using the small or medium memory
  15135. models. This process can be simplified if you include the OS2.H header file.
  15136. %@NL@%
  15137. %@NL@%
  15138. %@AU@% OS/2 API function calls are far and must use the FORTRAN/ Pascal calling
  15139. %@AU@%convention.%@AE@%  %@NL@%
  15140. %@NL@%
  15141. OS/2 API functions use the FORTRAN/Pascal language calling convention. They
  15142. expect arguments to be pushed onto the stack in left-to-right order, with
  15143. the last argument in the list pushed onto the stack last. OS/2 API functions
  15144. remove their arguments from the stack before returning to the caller.
  15145. Standard C functions push their arguments from right to left, with the first
  15146. argument being the last one pushed.  %@NL@%
  15147. %@NL@%
  15148. All OS/2 API functions return 0 if the operation is successful. They return
  15149. an error code if the operation fails.  %@NL@%
  15150. %@NL@%
  15151. %@NL@%
  15152. %@3@%%@CR:C6A00140005 @%%@AB@%14.1.2  Including the OS/2 Header Files%@AE@%%@EH@%%@NL@%
  15153. %@NL@%
  15154. You do not have to construct your own API declarations if you use the OS2.H
  15155. header file. It is the first file of a set of header files that supply
  15156. function prototypes for every OS/2 API call and definitions of special OS/2
  15157. structures, data types, and constants.  %@NL@%
  15158. %@NL@%
  15159. The API function prototypes define all functions as far procedures with the
  15160. FORTRAN/Pascal calling convention. They also take care of casting all near
  15161. pointers to far pointers and other similar type coercions.  %@NL@%
  15162. %@NL@%
  15163. %@AU@% Define a constant before including OS2.H.%@AE@%  %@NL@%
  15164. %@NL@%
  15165. When you include OS2.H, the most commonly used data types and macros are
  15166. automatically defined. To minimize compile time for the C preprocessor,
  15167. other definitions are grouped by function. They are included only if your
  15168. source file defines the appropriate constant before including OS2.H. The
  15169. following list shows how these manifest constants affect functions from the
  15170. OS/2 API:  %@NL@%
  15171. %@NL@%
  15172. %@AB@%Constant%@AE@%                          %@AB@%Effect%@AE@%
  15173. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15174. %@AB@%INCL_BASE%@AE@%                         All error constants, kernel, keyboard, 
  15175.                                   video, and mouse definitions (same as %@AB@%%@AE@%
  15176.                                   %@AB@%INCL_DOS%@AE@% +%@AB@% INCL_SUB%@AE@% + %@AB@%INCL_DOSERRORS%@AE@%)
  15177.  
  15178. %@AB@%INCL_DOS%@AE@%                          All kernel system definitions
  15179.  
  15180. %@AB@%INCL_DOSERRORS%@AE@%                    All error constants
  15181.  
  15182. %@AB@%INCL_KBD%@AE@%                          All keyboard definitions
  15183.  
  15184. %@AB@%INCL_MOU%@AE@%                          All mouse definitions
  15185.  
  15186. %@AB@%INCL_SUB%@AE@%                          All keyboard, video, and mouse 
  15187.                                   definitions (same as %@AB@%INCL_KBD%@AE@% + %@AB@%INCL_VIO%@AE@%
  15188.                                   + %@AB@%INCL_MOU)%@AE@%
  15189.  
  15190. %@AB@%INCL_VIO%@AE@%                          All video-display definitions
  15191.  
  15192. %@AB@%INCL_WIN%@AE@%                          Basic set of Presentation Manager 
  15193.                                   definitions
  15194.  
  15195. The header files have additional constants that let you include smaller
  15196. subsets or functions not defined in the standard sets.  %@NL@%
  15197. %@NL@%
  15198. %@AU@% The statement #define INCL_DOS affects the functions defined.%@AE@%  %@NL@%
  15199. %@NL@%
  15200. The program in the example below calls the OS/2 kernel to request a
  15201. nonshareable, nondiscardable memory segment for an 8K buffer. The %@AB@%INCL_DOS%@AE@%
  15202. constant in the %@AB@%#define%@AE@% statement instructs the C preprocessor to include
  15203. all of the kernel function definitions. The function prototype for
  15204. %@AB@%DosAllocSeg%@AE@% declares the first and third arguments as %@AB@%USHORT%@AE@% (unsigned short
  15205. integers). The second argument is a far pointer to the OS/2 data type %@AB@%SEL%@AE@%,
  15206. which is used for segment selectors.  %@NL@%
  15207. %@NL@%
  15208. %@AS@%  #define  INCL_DOS
  15209. %@AS@%  #include <os2.h>
  15210. %@AS@%  
  15211. %@AS@%  VOID GetMemorySegment()
  15212. %@AS@%  {
  15213. %@AS@%       SEL    selector;
  15214. %@AS@%  
  15215. %@AS@%       if ( DosAllocSeg( 8192, &selector, 0 ) )
  15216. %@AS@%           puts( "Allocation failed\n" );
  15217. %@AS@%       else
  15218. %@AS@%           puts( "Successful allocation\n" );
  15219. %@AS@%  }%@AE@%%@NL@%
  15220. %@NL@%
  15221. The function call in the example works correctly even in a small or medium
  15222. memory model program where the selector variable is a %@AB@%near data%@AE@% type. All
  15223. three arguments are coerced by the function prototype to the proper types,
  15224. regardless of the memory model used.  %@NL@%
  15225. %@NL@%
  15226. %@NL@%
  15227. %@3@%%@CR:C6A00140006 @%%@AB@%14.1.3  Creating Dual-Mode Programs as Family Applications%@AE@%%@EH@%%@NL@%
  15228. %@NL@%
  15229. The OS/2 API has a subset of system functions that have direct DOS
  15230. equivalents. This subset is known as the "Family Applications Program
  15231. Interface" (Family API). Programs that use only the Family API can be run
  15232. under DOS and the OS/2 compatibility box, as well as under OS/2.  %@NL@%
  15233. %@NL@%
  15234. %@AU@% You can build a single executable file for use under both OS/2 and DOS.%@AE@%  %@NL@%
  15235. %@NL@%
  15236. By creating a Family API application, you can distribute the same executable
  15237. file to both OS/2 and DOS users. The Microsoft C compiler, linker, and
  15238. object module librarian are examples of family applications. The benefit of
  15239. having a single executable file is offset by a few disadvantages:  %@NL@%
  15240. %@NL@%
  15241. %@NL@%
  15242.   ■   The executable file is larger, because it includes a special loader
  15243.       and OS/2 API-simulator routines for running in DOS mode.%@NL@%
  15244. %@NL@%
  15245.   ■   In real mode, the application loads more slowly than a program created
  15246.       specifically for either OS/2 or DOS. There is no performance penalty
  15247.       in loading or running in OS/2 protected mode.%@NL@%
  15248. %@NL@%
  15249.   ■   When running in real mode, the program cannot use advanced OS/2
  15250.       features such as multiple threads or system calls that are not part of
  15251.       the Family API. If you take special precautions (described in Section
  15252.       14.5, "The BIND Utility"), the program can take advantage of these
  15253.       features when running in OS/2 protected mode. %@NL@%
  15254. %@NL@%
  15255. %@NL@%
  15256. Follow the same steps to build both family and protected-mode applications
  15257. but add an extra step at the end to create the Family API program. This step
  15258. links functions from the dynamic-link libraries directly into a stand-alone
  15259. executable file that can run in both real and protected mode.  %@NL@%
  15260. %@NL@%
  15261. %@NL@%
  15262. %@4@%%@AB@%Restrictions on Family Applications%@AE@%%@EH@%%@NL@%
  15263. %@NL@%
  15264. Programs that use the Family API are subject to certain restrictions:  %@NL@%
  15265. %@NL@%
  15266. %@NL@%
  15267.   ■   They cannot overcommit memory; they must fit into the DOS 640K
  15268.       environment.%@NL@%
  15269. %@NL@%
  15270.   ■   They cannot use advanced OS/2 features, such as threads and
  15271.       semaphores, that do not have DOS counterparts.%@NL@%
  15272. %@NL@%
  15273.   ■   They must restrict their use of some calls to the defined common
  15274.       subset. For example, some of the file-mode options for the %@AB@%DosOpen%@AE@%
  15275.       function are not available in real mode.%@NL@%
  15276. %@NL@%
  15277. %@NL@%
  15278. %@NL@%
  15279. %@4@%%@AB@%Family API Functions%@AE@%%@EH@%%@NL@%
  15280. %@NL@%
  15281. The system calls that make up Family API are listed below. The calls marked
  15282. with an asterisk (*) have different options or behavior, depending on
  15283. whether they are running in real mode or protected mode. The %@AI@%Microsoft OS/2
  15284. %@AI@%Programmer's Reference%@AE@% explains the functions and the differences between
  15285. their real- and protected-mode implementations.  %@NL@%
  15286. %@NL@%
  15287. %@AB@%DosAllocHuge*        DosHoldSignal*       DosSubSet%@AE@%
  15288. %@AB@%DosAllocSeg*         DosInsMessage*       DosWrite%@AE@%
  15289. %@AB@%DosBeep              DosMkDir             KbdCharIn*%@AE@%
  15290. %@AB@%DosBufReset          DosMove              KbdFlushBuffer*%@AE@%
  15291. %@AB@%DosCaseMap*          DosNewSize           KbdGetStatus*%@AE@%
  15292. %@AB@%DosChdir             DosOpen*             KbdPeek*%@AE@%
  15293. %@AB@%DosChgFilePtr        DosPutMessage*       KbdSetStatus*%@AE@%
  15294. %@AB@%DosCLIAccess         DosQCurDir           KbdStringIn*%@AE@%
  15295. %@AB@%DosClose             DosQCurDisk          VioGetBuf%@AE@%
  15296. %@AB@%DosCreateCSAlias*    DosQFHandState       VioGetConfig%@AE@%
  15297. %@AB@%DosDelete            DosQFileInfo         VioGetCurPos%@AE@%
  15298. %@AB@%DosDevConfig         DosQFileMode         VioGetCurType%@AE@%
  15299. %@AB@%DosDevIOCtl*         DosQFSInfo           VioGetMode%@AE@%
  15300. %@AB@%DosDupHandle         DosQHandType         VioGetPhysBuf%@AE@%
  15301. %@AB@%DosErrClass          DosQVerify           VioReadCellStr%@AE@%
  15302. %@AB@%DosError*            DosRead*             VioReadCharStr%@AE@%
  15303. %@AB@%DosExecPgm*          DosReallocHuge*      VioScrLock*%@AE@%
  15304. %@AB@%DosExit*             DosReallocSeg*       VioScrollDn%@AE@%
  15305. %@AB@%DosFileLocks         DosRmDir             VioScrollLf%@AE@%
  15306. %@AB@%DosFindClose         DosSelectDisk        VioScrollRt%@AE@%
  15307. %@AB@%DosFindFirst         DosSetCp             VioScrollUp%@AE@%
  15308. %@AB@%DosFindNext*         DosSetDateTime       VioScrUnLock%@AE@%
  15309. %@AB@%DosFreeSeg*          DosSetFHandState*    VioSetCurPos%@AE@%
  15310. %@AB@%DosGetCollate*       DosSetFileInfo       VioSetCurType%@AE@%
  15311. %@AB@%DosGetCp             DosSetFileMode       VioSetMode%@AE@%
  15312. %@AB@%DosGetCtryInfo*      DosSetFSInfo         VioShowBuf%@AE@%
  15313. %@AB@%DosGetDateTime       DosSetSigHandler*    VioWrtCellStr%@AE@%
  15314. %@AB@%DosGetDBSCEv*        DosSetVec*           VioWrtCharStr%@AE@%
  15315. %@AB@%DosGetEnv            DosSetVerify         VioWrtCharStrAtt%@AE@%
  15316. %@AB@%DosGetHugeShift      DosSizeSeg           VioWrtNAttr%@AE@%
  15317. %@AB@%DosGetMachineMode    DosSleep             VioWrtNCell%@AE@%
  15318. %@AB@%DosGetMessage*       DosSubAlloc          VioWrtNChar%@AE@%
  15319. %@AB@%DosGetVersion        DosSubFree           VioWrtTTy %@AE@%
  15320.  
  15321. %@2@%%@CR:C6A00140007 @%%@AB@%14.2  Compile Options for the CL Command%@AE@%%@EH@%%@NL@%
  15322. %@NL@%
  15323. This section describes the compile options you must specify in the
  15324. Programmer's WorkBench or on the CL command line to designate a program's
  15325. target environment (OS/2, DOS, or both). It also introduces options you
  15326. should use with certain types of OS/2 applications, such as multithread
  15327. programs, dynamic-link libraries, and programs calling C function
  15328. dynamic-link libraries. For an in-depth discussion of topics that affect
  15329. multithread processes and dynamic-link libraries, see Chapter 15, "Creating
  15330. Multithread OS/2 Applications," and Chapter 16, "Dynamic-Linking with OS/2."
  15331. %@NL@%
  15332. %@NL@%
  15333. %@NL@%
  15334. %@3@%%@CR:C6A00140008 @%%@AB@%14.2.1  The Link Mode Options (/Lp, /Lr, and /Lc)%@AE@%%@EH@%%@NL@%
  15335. %@NL@%
  15336. The /L%@AI@%x%@AE@% options (/Lp, /Lr, and /Lc) provide the flexibility of programming
  15337. for both OS/2 and DOS in either environment. Regardless of the host
  15338. operating system, you can build applications for either target operating
  15339. system. You do not have to switch to the target system to build the program.
  15340. %@NL@%
  15341. %@NL@%
  15342. The /Lp option produces an OS/2 protected-mode program; the /Lr option
  15343. creates a DOS real-mode program. /Lc is a synonym for /Lr.%@CR:C6A00140009 @%%@CR:C6A00140010 @%%@CR:C6A00140011 @%%@CR:C6A00140012 @%  %@NL@%
  15344. %@NL@%
  15345. To use these options, the mode-specific combined libraries must be
  15346. installed. Unless you choose a default operating environment, each
  15347. mode-specific library has the letter P or R at the end of its base name. For
  15348. example, the protected-mode small memory model library with the emulator
  15349. floating-point option is named SLIBCEP.LIB. The corresponding real-mode
  15350. library is named SLIBCER.LIB. The default name, however, is SLIBCE.LIB.  %@NL@%
  15351. %@NL@%
  15352. %@AI@%Installing and Using the Microsoft C Professional Development System%@AE@%
  15353. describes how to create mode-specific libraries with the SETUP program. It
  15354. also explains how to establish a default target environment by renaming
  15355. libraries. A default environment is useful if you work mainly in one mode
  15356. (OS/2 or DOS) but sometimes write programs for the other mode. When you set
  15357. up OS/2 as the default mode, SLIBCEP.LIB, for example, becomes SLIBCE.LIB.  %@NL@%
  15358. %@NL@%
  15359. %@AU@% Don't use /Lx options unless you have mode-specific libraries.%@AE@%  %@NL@%
  15360. %@NL@%
  15361. When you use the /L%@AI@%x%@AE@% options, you instruct the compiler to override the
  15362. default library name in the object module's library search record and to
  15363. substitute the mode-specific combined library name. The compiler also
  15364. generates a link response file with the /NODEFAULTLIBRARYSEARCH (/NOD)
  15365. linker option to override the default library. See Section 14.4, "Link
  15366. Command-Line Options," for more information about the /NOD option.  %@NL@%
  15367. %@NL@%
  15368. Do not use the /Lp option to specify protected mode when OS/2 is the default
  15369. environment. If you do this, the compiler uses the name of the mode-specific
  15370. library (e.g., SLIBCEP.LIB). Because SETUP renamed the library to SLIBCE.LIB
  15371. to create a default environment, the library search fails. This caution also
  15372. applies to specifying /Lr when you have installed DOS as the default
  15373. environment.  %@NL@%
  15374. %@NL@%
  15375. If you invoke the linker in a separate step from the compilation, you must
  15376. specify the /NOD link option.  %@NL@%
  15377. %@NL@%
  15378. ────────────────────────────────────────────────────────────────────────────%@NL@%
  15379. NOTE
  15380.  
  15381. %@AI@%There is a special library, LLIBCMT, for building multithread OS/2
  15382. %@AI@%applications. Another special library, LLIBCDLL, supports multithread
  15383. %@AI@%dynamic-link libraries. If you use LLIBCMT or LLIBCDLL, you must use one of
  15384. %@AI@%the library selection options described in Section 14.2.3 instead of %@AI@%/%@AE@%%@AI@% Lp.%@AE@%%@AE@%%@NL@%
  15385. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  15386. %@NL@%
  15387. %@NL@%
  15388. %@3@%%@CR:C6A00140013 @%%@AB@%14.2.2  Creating Bound Programs Option (/Fb)%@AE@%%@EH@%%@NL@%
  15389. %@NL@%
  15390. The /Fb option allows you to compile, link, and bind an application in one
  15391. step. Binding an executable file creates a Family API program that can run
  15392. under both OS/2 and DOS.%@CR:C6A00140014 @%%@CR:C6A00140015 @%%@CR:C6A00140016 @%  %@NL@%
  15393. %@NL@%
  15394. When you use /Fb, the compiler invokes the BIND utility program immediately
  15395. after the link step. You can also execute BIND directly (as described in
  15396. Section 14.5, "The BIND Utility"). You must have the API.LIB and OS2.LIB
  15397. files in the path specified by the LIB environment variable or in your
  15398. current working directory.  %@NL@%
  15399. %@NL@%
  15400. The syntax for the /Fb option is  %@NL@%
  15401. %@NL@%
  15402. %@AS@%  /Fb«bound-exe»%@AE@%%@NL@%
  15403. %@NL@%
  15404. %@AU@% You can specify a separate name for a bound-executable file.%@AE@%  %@NL@%
  15405. %@NL@%
  15406. The optional %@AI@%bound-exe%@AE@% parameter specifies the name of the bound program. It
  15407. must directly follow the /Fb option, without intervening spaces. The
  15408. %@AI@%bound-exe%@AE@% name can be a file specification, a drive name, or a directory
  15409. specification. If you specify a file name without an extension, the compiler
  15410. appends the .EXE extension to the name. If you give a directory
  15411. specification for %@AI@%bound-exe%@AE@%, the name must end with a backslash ( \ ) so the
  15412. compiler can distinguish it from an ordinary file name. If you do not supply
  15413. a name, BIND uses the name of the unbound program and overwrites it.  %@NL@%
  15414. %@NL@%
  15415. When creating both bound and protected-mode versions with different names,
  15416. consider this example:  %@NL@%
  15417. %@NL@%
  15418. %@AS@%  CL /Lp /Fbsampleb sample.c%@AE@%%@NL@%
  15419. %@NL@%
  15420. The protected-mode executable file that this command creates is called
  15421. SAMPLE.EXE; the bound-executable file is called SAMPLEB.EXE.  %@NL@%
  15422. %@NL@%
  15423. %@AU@% You may need to run BIND as a separate step instead of using the /Fb
  15424. %@AU@%option.%@AE@%  %@NL@%
  15425. %@NL@%
  15426. The /Fb option works only if you are doing a single-step compile and link.
  15427. If the CL command line includes the /c (compile without link) option, the
  15428. compiler ignores the /Fb option. If you use /c, you must run the BIND
  15429. utility as a separate step of the program build.  %@NL@%
  15430. %@NL@%
  15431. If your program includes calls to API functions that are not in the FAPI
  15432. subset, you must use the /n option of the BIND utility, described in Section
  15433. 14.5, to build the dual-mode executable file. If you need to use the /n BIND
  15434. option, you cannot compile with /Fb. You must compile without linking by
  15435. using the /c option at the compile stage; then link the program and run the
  15436. BIND utility with the /n option.  %@NL@%
  15437. %@NL@%
  15438. %@NL@%
  15439. %@3@%%@CR:C6A00140017 @%%@AB@%14.2.3  Library Selection Options (/MT, /ML, /MD, /Zl)%@AE@%%@EH@%%@NL@%
  15440. %@NL@%
  15441. Special libraries are provided for building OS/2 multithread applications
  15442. and dynamic-link libraries. You must not use these libraries with any other
  15443. C run-time library.%@CR:C6A00140018 @%  %@NL@%
  15444. %@NL@%
  15445. %@AU@% Special libraries must be the only C run-time libraries linked with your
  15446. %@AU@%program.%@AE@%  %@NL@%
  15447. %@NL@%
  15448. If you use one of these special libraries, apply one of the library
  15449. selection options (/ML, /MD, or /MT) to tell the compiler to replace the
  15450. default library name in the object file with the name of the special
  15451. library. This ensures that the linker does not bring in code from the
  15452. default libraries. If you do not specify one of the options when compiling,
  15453. you must link with the /NOD option to prevent search of a default library,
  15454. such as SLIBCE.LIB.  %@NL@%
  15455. %@NL@%
  15456. If you fail to include any of these options, the linker searches the default
  15457. library and may select the wrong version of a library function. It might,
  15458. for example, select the single thread version of the %@AB@%printf%@AE@% function for a
  15459. multithread program that has more than one thread calling %@AB@%printf%@AE@%.  %@NL@%
  15460. %@NL@%
  15461. Because the /Lp option (see Section 14.2.1, "The Link Mode Options")
  15462. instructs the compiler to specify the default protected-mode libraries
  15463. rather than the special multithread or DLL-specific libraries, do not use it
  15464. with /Zl or /Mx.  %@NL@%
  15465. %@NL@%
  15466. %@NL@%
  15467. %@4@%%@AB@%Multithread Library Option (/MT)%@AE@%%@EH@%%@NL@%
  15468. %@NL@%
  15469. When you specify the /MT option, the compiler embeds the LLIBCMT.LIB
  15470. library name in the object file. Chapter 15, "Creating Multithread OS/2
  15471. Applications," explains how to build multithread applications using
  15472. LLIBCMT.LIB. The /MT option also has the effect of combining these
  15473. command-line options:  %@NL@%
  15474. %@NL@%
  15475. %@AS@%  /ALw /FPi /G2 /D MT%@AE@%%@NL@%
  15476. %@NL@%
  15477. %@NL@%
  15478. %@4@%%@AB@%C Run-Time Library for Building DLLs (/ML)%@AE@%%@EH@%%@NL@%
  15479. %@NL@%
  15480. Use the /ML option to specify that you are building a dynamic-link library
  15481. that calls functions in LLIBCDLL.LIB, the C run-time library for
  15482. dynamic-link  libraries. The library name is embedded in the object file.
  15483. The /ML option also has the effect of combining these command-line options:
  15484. %@NL@%
  15485. %@NL@%
  15486. %@AS@%  /ALw /FPa /G2 /D MT%@AE@%%@NL@%
  15487. %@NL@%
  15488. %@NL@%
  15489. %@4@%%@AB@%C Run-Time Library for DLLs (/MD)%@AE@%%@EH@%%@NL@%
  15490. %@NL@%
  15491. Use the /MD option to create a dynamic-link library of C run-time routines.
  15492. With this option, the object file does not have any library search records.
  15493. The /MD option has the effect of combining these command-line options:  %@NL@%
  15494. %@NL@%
  15495. %@AS@%  /ALw /FPi /G2 /DDLL /D MT%@AE@%%@NL@%
  15496. %@NL@%
  15497. Chapter 16, "Dynamic Linking with OS/2," describes the process of building
  15498. and using dynamic-link libraries with LLIBCDLL.LIB.  %@NL@%
  15499. %@NL@%
  15500. %@NL@%
  15501. %@4@%%@AB@%Suppress Default Library Option (/Zl)%@AE@%%@EH@%%@NL@%
  15502. %@NL@%
  15503. Use the /Zl option when you want to suppress selection of a default library.
  15504. It tells the compiler not to place the default library name in the object
  15505. file.%@CR:C6A00140019 @%  %@NL@%
  15506. %@NL@%
  15507. %@AU@% You can specify libraries and additional LINK options on the CL command
  15508. %@AU@%line.%@AE@%  %@NL@%
  15509. %@NL@%
  15510. You can specify link options or the names of libraries on the CL command
  15511. line with the /LINK option. You can also give the library name, with its
  15512. .LIB extension, before the /LINK option. Each command below selects the
  15513. multithread C run-time library:  %@NL@%
  15514. %@NL@%
  15515. %@AS@%  CL /Zl myprog.c llibcmt.lib
  15516. %@AS@%  
  15517. %@AS@%  CL /Zl myprog.c /link llibcmt%@AE@%%@NL@%
  15518. %@NL@%
  15519. If you compile with the /c (compile without link) option, your link command
  15520. must include the library name:  %@NL@%
  15521. %@NL@%
  15522. %@AS@%  LINK myprog, myprog.exe, myprog.map, llibcmt.lib, myprog.def%@AE@%%@NL@%
  15523. %@NL@%
  15524. %@NL@%
  15525. %@3@%%@CR:C6A00140020 @%%@AB@%14.2.4  Memory-Model Options (/Ax)%@AE@%%@EH@%%@NL@%
  15526. %@NL@%
  15527. You must select the memory model appropriate to your application. For
  15528. protected-mode applications, the large model provides the most convenient
  15529. interface with the special libraries. It provides the additional benefit of
  15530. placing code and data into multiple segments, allowing OS/2 to swap parts of
  15531. the program to disk efficiently.  %@NL@%
  15532. %@NL@%
  15533. %@AU@% Use the large memory model with LLIBCMT (/AL and /MT).%@AE@%  %@NL@%
  15534. %@NL@%
  15535. The multithread run-time C library, LLIBCMT.LIB, is a large-model library.
  15536. All library function calls must be far calls. In addition, all pointers
  15537. passed to functions in the library must be far pointers. If you do not
  15538. compile with the /AL option, you use must use the keyword %@AB@%_far%@AE@% when
  15539. declaring pointers. Variables can be declared either near or far as long as
  15540. they are either passed by value or cast to a far address.  %@NL@%
  15541. %@NL@%
  15542. If you want to call %@AB@%fopen %@AE@%for example, you must use code such as the
  15543. following:  %@NL@%
  15544. %@NL@%
  15545. %@AS@%  FILE _far * fp;
  15546. %@AS@%  fp = fopen( ... );%@AE@%%@NL@%
  15547. %@NL@%
  15548. ────────────────────────────────────────────────────────────────────────────%@NL@%
  15549. NOTE
  15550.  
  15551. %@AI@%If you are using the compact, large, or huge memory model, data pointers are
  15552. %@AI@%far by default, so you do not need to explicitly specify %@AB@%_far%@AE@%%@AI@%.%@AE@%%@AE@%%@NL@%
  15553. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  15554. %@NL@%
  15555. %@AU@% Because each thread has its own stack, you have to compile in an SS != DS
  15556. %@AU@%model.%@AE@%  %@NL@%
  15557. %@NL@%
  15558. Multithread applications require that each thread have its own stack. As a
  15559. result, you cannot safely assume that the stack segment is in the default
  15560. data group (DGROUP). That means that the stack segment can be different from
  15561. the data segment (SS != DS).  %@NL@%
  15562. %@NL@%
  15563. To specify that you have selected an SS != DS model, you must use the /Au or
  15564. /Aw option. The /MT option is a shorthand way of specifying this combination
  15565. of options to the compiler:  %@NL@%
  15566. %@NL@%
  15567. %@AS@%  /ALw/FPi/G2/DMT%@AE@%%@NL@%
  15568. %@NL@%
  15569. The /MT option also causes the compiler to place a library search record for
  15570. LLIBCMT in the object file.  %@NL@%
  15571. %@NL@%
  15572. %@NL@%
  15573. %@2@%%@CR:C6A00140021 @%%@AB@%14.3  Module-Definition Files and Import Libraries%@AE@%%@EH@%%@NL@%
  15574. %@NL@%
  15575. A module-definition file tells the linker about the characteristics of an
  15576. application or dynamic-link library. It describes names, segments, memory
  15577. requirements, and import and export definitions. Export definitions make
  15578. functions in the OS/2 dynamic-link libraries (DLLs) available to other
  15579. programs. Each export definition specifies a function name. A program using
  15580. these functions must have import definitions in order to find each
  15581. dynamic-link function. Each import definition specifies a function name and
  15582. the name of the dynamic-link library where the function resides.  %@NL@%
  15583. %@NL@%
  15584. The IMPLIB utility generates a library of import definitions that can be
  15585. examined during the link. For imported functions, the import library can be
  15586. used in place of a module-definition file.  %@NL@%
  15587. %@NL@%
  15588. Module-definition files are optional for most OS/2 programs. Two types of
  15589. programs must use them:  %@NL@%
  15590. %@NL@%
  15591. %@NL@%
  15592.   ■   Dynamic-link libraries%@NL@%
  15593. %@NL@%
  15594.   ■   Programs with I/O privileges%@NL@%
  15595. %@NL@%
  15596. %@NL@%
  15597. Each module-definition file contains one or more module statements defining
  15598. attributes of the executable program. The statements and their associated
  15599. attributes are listed below:  %@NL@%
  15600. %@NL@%
  15601. %@AB@%Statement%@AE@%                         %@AB@%Attribute%@AE@%
  15602. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15603. %@AB@%CODE%@AE@%                              Gives default attributes for code 
  15604.                                   segments
  15605.  
  15606. %@AB@%DATA%@AE@%                              Gives default attributes for data 
  15607.                                   segments
  15608.  
  15609. %@AB@%DESCRIPTION%@AE@%                       Describes the module in one line
  15610.  
  15611. %@AB@%EXETYPE%@AE@%                           Identifies the operating system
  15612.  
  15613. %@AB@%EXPORTS%@AE@%                           Defines exported functions
  15614.  
  15615. %@AB@%HEAPSIZE%@AE@%                          Specifies local heap size, in bytes
  15616.  
  15617. %@AB@%IMPORTS%@AE@%                           Defines imported functions
  15618.  
  15619. %@AB@%LIBRARY%@AE@%                           Names a dynamic-link library
  15620.  
  15621. %@AB@%NAME%@AE@%                              Names an application
  15622.  
  15623. %@AB@%OLD%@AE@%                               Preserves import information from a 
  15624.                                   previous version of the library
  15625.  
  15626. %@AB@%PROTMODE%@AE@%                          Specifies that the module runs only in 
  15627.                                   OS/2 protected mode
  15628.  
  15629. %@AB@%REALMODE%@AE@%                          Relaxes some restrictions that the 
  15630.                                   linker imposes for protected-mode 
  15631.                                   programs
  15632.  
  15633. %@AB@%SEGMENTS%@AE@%                          Gives attributes for specific segments
  15634.  
  15635. %@AB@%STACKSIZE%@AE@%                         Specifies local stack size, in bytes
  15636.  
  15637. %@AB@%STUB%@AE@%                              Adds a DOS 3.x executable file to the 
  15638.                                   beginning of the module, usually to 
  15639.                                   terminate the program when run in real 
  15640.                                   mode
  15641.  
  15642. In addition to the keywords listed above, each statement includes one or
  15643. more fields to complete the attribute description. All keywords must be
  15644. entered in uppercase. You can include comments in the module-definition file
  15645. by beginning the line with a semicolon (;). For a complete list of the
  15646. keywords and their meaning, see on-line help for information about
  15647. module-definition files.  %@NL@%
  15648. %@NL@%
  15649. %@NL@%
  15650. %@3@%%@CR:C6A00140022 @%%@AB@%14.3.1  Adding a Module-Definition File to the LINK Command%@AE@%%@EH@%%@NL@%
  15651. %@NL@%
  15652. The module-definition file name is the last field of the link command:  %@NL@%
  15653. %@NL@%
  15654. %@AS@%  LINK objects «,«exe» » «, «map» » «, «lib» » «, «def» » «;»%@AE@%%@NL@%
  15655. %@NL@%
  15656. This example uses the default libraries:  %@NL@%
  15657. %@NL@%
  15658. %@AS@%  LINK sample, sample.exe, sample.map,,sample.def%@AE@%%@NL@%
  15659. %@NL@%
  15660. When you use a module-definition file, you must use the /c option on the CL
  15661. command line and link in a separate step. If you are linking without a
  15662. module-definition file, you can use a semicolon after your last entry to
  15663. suppress LINK's prompt for the module-definition file name and other missing
  15664. parameters.  %@NL@%
  15665. %@NL@%
  15666. The segmented-executable linker is the only LINK program that recognizes
  15667. module-definition files. Since it is backwards compatible, it should be the
  15668. only linker in your path. The QuickC linker does not process these files.  %@NL@%
  15669. %@NL@%
  15670. The following sections illustrate ways to use module-definition files.
  15671. On-line help describes all of the commands and options available.  %@NL@%
  15672. %@NL@%
  15673. %@NL@%
  15674. %@3@%%@CR:C6A00140023 @%%@AB@%14.3.2  Creating Dynamic-Link Libraries (DLLs)%@AE@%%@EH@%%@NL@%
  15675. %@NL@%
  15676. You can build your own dynamic-link libraries. A simple module-definition
  15677. file for such a library with one public function is shown below:%@CR:C6A00140024 @%  %@NL@%
  15678. %@NL@%
  15679. %@AS@%  LIBRARY Mylib INITINSTANCE
  15680. %@AS@%  
  15681. %@AS@%  DATA MULTIPLE
  15682. %@AS@%  
  15683. %@AS@%  EXPORTS
  15684. %@AS@%   MyProc%@AE@%%@NL@%
  15685. %@NL@%
  15686. You can use the same module-definition file you used to create the
  15687. dynamic-link library as input to the IMPLIB utility. IMPLIB generates a
  15688. library file with a .LIB extension for use by applications calling your
  15689. dynamic-link routines. Section 14.3.5 describes the IMPLIB program. Chapter
  15690. 16, "Dynamic Linking with OS/2," explains how to build a dynamic-link
  15691. library.  %@NL@%
  15692. %@NL@%
  15693. The %@AB@%LIBRARY%@AE@% statement tells the linker that this is a dynamic-link library
  15694. rather than an application. (Applications use the %@AB@%NAME%@AE@% statement instead of
  15695. the %@AB@%LIBRARY%@AE@% statement.)  %@NL@%
  15696. %@NL@%
  15697. The %@AB@%EXPORTS%@AE@% statement gives the name of the public function.  %@NL@%
  15698. %@NL@%
  15699. %@AU@% You can designate exported functions in a C source file.%@AE@%  %@NL@%
  15700. %@NL@%
  15701. The C language keyword %@AB@%_export%@AE@% is an alternative to the %@AB@%EXPORTS%@AE@% statement.
  15702. When %@AB@%_export%@AE@% appears in a function declaration or definition, the compiler
  15703. puts the function and its parameter size in the object module's export
  15704. record. Functions with the %@AB@%_export%@AE@% keyword that are not listed in the
  15705. module-definition file cannot have input/output privileges or alias names.  %@NL@%
  15706. %@NL@%
  15707. %@AU@% Using generic library names is dangerous.%@AE@%  %@NL@%
  15708. %@NL@%
  15709. Since OS/2 systems have many dynamic-link libraries installed, try to pick a
  15710. name that uniquely identifies your library. If you choose a generic name,
  15711. such as CRT.DLL or WINDOWS.DLL, you run the risk of having your library
  15712. overwritten by someone else's dynamic-link library with the same name.  %@NL@%
  15713. %@NL@%
  15714. %@NL@%
  15715. %@3@%%@CR:C6A00140025 @%%@AB@%14.3.3  Creating Programs with I/O Privileges%@AE@%%@EH@%%@NL@%
  15716. %@NL@%
  15717. OS/2 programs that must access hardware directly can designate a code
  15718. segment with input/output privileges. This segment can then perform a
  15719. limited set of I/O instructions but cannot make any calls to dynamic-link
  15720. libraries.  %@NL@%
  15721. %@NL@%
  15722. You cannot use the C run-time library functions %@AB@%inp%@AE@% and %@AB@%outp%@AE@% for input and
  15723. output. Their use is limited to real-mode programs. You can, however, use
  15724. in-line assembler code in your C source program to access a port.  %@NL@%
  15725. %@NL@%
  15726. The sample module-definition file below shows two segments for a program:  %@NL@%
  15727. %@NL@%
  15728. %@AS@%  NAME         IOPROG
  15729. %@AS@%  
  15730. %@AS@%  EXETYPE         OS/2
  15731. %@AS@%  
  15732. %@AS@%  SEGMENTS     
  15733. %@AS@%       _IOSEG      IOPL
  15734. %@AS@%       _TEXT       NOIOPL
  15735. %@AS@%  
  15736. %@AS@%  EXPORTS
  15737. %@AS@%       CharIn      4
  15738. %@AS@%       CharOut     4%@AE@%%@NL@%
  15739. %@NL@%
  15740. The first code segment contains the I/O portion of the program and has the
  15741. %@AB@%IOPL %@AE@%keyword. The second segment is designated %@AB@%NOIOPL %@AE@%(the default).  %@NL@%
  15742. %@NL@%
  15743. %@AU@% The EXPORT statement for IOPL functions must include parameter size.%@AE@%  %@NL@%
  15744. %@NL@%
  15745. The %@AB@%EXPORTS %@AE@%section names two functions in the %@AB@%IOPL%@AE@% segment that can be
  15746. called by procedures outside the segment. It also specifies the size of the
  15747. function's parameters. Procedures with I/O privileges must specify the
  15748. number of words needed for their parameters.  %@NL@%
  15749. %@NL@%
  15750. ────────────────────────────────────────────────────────────────────────────%@NL@%
  15751. NOTE
  15752.  
  15753. %@AI@%Unless the user has specified IOPL=YES in the CONFIG.SYS file, the program
  15754. %@AI@%will not load.%@AE@%%@NL@%
  15755. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  15756. %@NL@%
  15757. %@NL@%
  15758. %@3@%%@CR:C6A00140026 @%%@AB@%14.3.4  Creating Presentation Manager Applications%@AE@%%@EH@%%@NL@%
  15759. %@NL@%
  15760. The Presentation Manager calls window and dialog procedures inside a
  15761. Presentation Manager application. The sample module-definition file below
  15762. exports these procedures and gives the linker additional instructions for
  15763. building the program. Module-definition files are optional for Presentation
  15764. Manager applications. They can be used to control the way different segments
  15765. of the program are loaded.  %@NL@%
  15766. %@NL@%
  15767. %@AS@%  NAME         PMSAMPLE    WINDOWAPI
  15768. %@AS@%  
  15769. %@AS@%  EXETYPE          OS/2
  15770. %@AS@%  STACKSIZE        4096
  15771. %@AS@%  
  15772. %@AS@%  SEGMENTS
  15773. %@AS@%       _INIT       PRELOAD
  15774. %@AS@%       _HELP       LOADONCALL
  15775. %@AS@%       _TEXT       LOADONCALL%@AE@%%@NL@%
  15776. %@NL@%
  15777. In the preceding example, the %@AB@%NAME %@AE@%statement identifies the program as an
  15778. application named PMSAMPLE. The %@AB@%WINDOWAPI %@AE@%keyword tells the linker to mark
  15779. the executable file as a Presentation Manager application. Only programs
  15780. marked as windows applications or windows-compatible applications can share
  15781. the Presentation Manager screen group.  %@NL@%
  15782. %@NL@%
  15783. The %@AB@%EXETYPE %@AE@%statement tells the linker to build a program that runs only in
  15784. protected mode and to produce the optimal executable file for OS/2.  %@NL@%
  15785. %@NL@%
  15786. The %@AB@%STACKSIZE %@AE@%statement allocates 4096 bytes of local stack space. This is
  15787. the minimum stack size recommended for Presentation Manager programs.  %@NL@%
  15788. %@NL@%
  15789. %@AU@% You can reduce run-time memory requirements.%@AE@%  %@NL@%
  15790. %@NL@%
  15791. The %@AB@%SEGMENTS %@AE@%statement controls the way code and data segments are handled.
  15792. By default, segments are not brought into physical memory until needed. The
  15793. %@AB@%PRELOAD %@AE@%keyword in the example tells the system loader to load the %@AS@% _INIT %@AE@%
  15794. segment when the program starts. The %@AS@% _TEXT %@AE@% and %@AS@% _HELP %@AE@% segments are loaded
  15795. on demand. You can use the compiler's /NT option to generate your own
  15796. segment names, such as %@AS@% _INIT %@AE@% and %@AS@% _HELP%@AE@%. Separate segments are useful for
  15797. code that is executed infrequently, such as a help subsystem. This reduces
  15798. the amount of run-time memory required for your application, since each
  15799. segment will be loaded when and if there is a request for it.  %@NL@%
  15800. %@NL@%
  15801. %@NL@%
  15802. %@3@%%@CR:C6A00140027 @%%@AB@%14.3.5  Creating Import Libraries with the IMPLIB Utility%@AE@%%@EH@%%@NL@%
  15803. %@NL@%
  15804. Applications that call dynamic-link library functions must use import
  15805. definitions that specify the location of each dynamic-link function. The
  15806. definitions consist of a function name and the name of the dynamic-link
  15807. library file where it resides.%@CR:C6A00140028 @%  %@NL@%
  15808. %@NL@%
  15809. Although the application can use a module-definition file to create the
  15810. import definitions, it is easier to use import libraries built by the IMPLIB
  15811. utility.  %@NL@%
  15812. %@NL@%
  15813. IMPLIB creates an import library in the form of a file with a .LIB
  15814. extension, which is read by the linker. At link time, the .LIB file is
  15815. specified in the LINK command line, along with other libraries.  %@NL@%
  15816. %@NL@%
  15817. IMPLIB accepts two types of sources:  %@NL@%
  15818. %@NL@%
  15819. %@NL@%
  15820.   ■   The module-definition file used to create the dynamic-link library%@NL@%
  15821. %@NL@%
  15822.   ■   The dynamic-link library itself%@NL@%
  15823. %@NL@%
  15824. %@NL@%
  15825. The IMPLIB command has the syntax:  %@NL@%
  15826. %@NL@%
  15827. %@AS@%  IMPLIB «/c»libfile deffile  «deffile ...»%@AE@%%@NL@%
  15828. %@NL@%
  15829. or  %@NL@%
  15830. %@NL@%
  15831. %@AS@%  IMPLIB  «/c»libfile dynlib «dynlib ...»%@AE@%%@NL@%
  15832. %@NL@%
  15833. The /c option directs IMPLIB to be case sensitive. By default, it is case
  15834. insensitive.  %@NL@%
  15835. %@NL@%
  15836. The %@AI@%libfile %@AE@%field names the new import library file. The %@AI@%deffile %@AE@%or %@AI@%dynlib
  15837. %@AI@%%@AE@%fields name the input files, which are dynamic-link library or
  15838. module-definition files.  %@NL@%
  15839. %@NL@%
  15840. The following example creates the import library file named MYLIB.LIB from
  15841. the MYLIB.DLL dynamic-link library:  %@NL@%
  15842. %@NL@%
  15843. %@AS@%  IMPLIB mylib.lib mylib.dll%@AE@%%@NL@%
  15844. %@NL@%
  15845. For more information about import libraries and IMPLIB, consult on-line
  15846. help.  %@NL@%
  15847. %@NL@%
  15848. %@NL@%
  15849. %@2@%%@CR:C6A00140029 @%%@AB@%14.4  Link Command-Line Options%@AE@%%@EH@%%@NL@%
  15850. %@NL@%
  15851. This section describes command-line options that control various aspects of
  15852. the linker and the circumstances in which you will need to use them.%@CR:C6A00140030 @%%@CR:C6A00140031 @%  %@NL@%
  15853. %@NL@%
  15854. %@NL@%
  15855. %@4@%%@AB@%/NODEFAULTLIBRARYSEARCH (/NOD)%@AE@%%@EH@%%@NL@%
  15856. %@NL@%
  15857. %@AU@% If you did not compile with /MT, /MD, or /ML, suppress default library
  15858. %@AU@%searching.%@AE@%  %@NL@%
  15859. %@NL@%
  15860. The /NODEFAULTLIBRARYSEARCH option prevents the linker from searching any
  15861. library specified in an object file. When you specify this option, you
  15862. should also specify the name of the library to be linked. The minimum
  15863. abbreviation for this option is /NOD.  %@NL@%
  15864. %@NL@%
  15865. If you are using the multithread library, LLIBCMT, or the dynamic-link
  15866. library, LLIBCDLL, you should use this option. Use it with dynamic-link
  15867. libraries built with LLIBCDLL. This is mandatory if you did not compile with
  15868. the /Zl, /MT, or /ML options.  %@NL@%
  15869. %@NL@%
  15870. You can select a specific library by appending the library name to the /NOD
  15871. option, as in  %@NL@%
  15872. %@NL@%
  15873. %@AS@%  /NOD:LLIBCMT.LIB%@AE@%%@NL@%
  15874. %@NL@%
  15875. %@NL@%
  15876. %@4@%%@AB@%/NOEXTENDEDDICTSEARCH (/NOE)%@AE@%%@EH@%%@NL@%
  15877. %@NL@%
  15878. The /NOEXTENDEDDICTSEARCH option prevents the linker from searching the
  15879. extended dictionary, which is an internal list of symbol locations
  15880. maintained by the linker. You need to use this option if a library symbol
  15881. (such as %@AB@%_setargv%@AE@%, %@AB@%_binmode%@AE@%, or %@AB@%_varstck%@AE@%) is redefined and you receive error
  15882. L2044 from the linker. The minimum abbreviation for this option is /NOE.%@CR:C6A00140032 @%%@CR:C6A00140033 @%  %@NL@%
  15883. %@NL@%
  15884. %@NL@%
  15885. %@4@%%@AB@%/NOIGNORECASE (/NOI)%@AE@%%@EH@%%@NL@%
  15886. %@NL@%
  15887. The /NOIGNORECASE option preserves case sensitivity. By default, LINK maps
  15888. all names to uppercase characters. Because many C function names are a mix
  15889. of upper- and lowercase letters, it is important to use this option. The
  15890. compile option /Zc causes any name declared with the %@AB@%_pascal%@AE@% keyword to be
  15891. treated without regard to case at the source level. The minimum abbreviation
  15892. is /NOI.  %@NL@%
  15893. %@NL@%
  15894. %@NL@%
  15895. %@4@%%@AB@%/PMTYPE%@AE@%%@EH@%%@NL@%
  15896. %@NL@%
  15897. The /PMTYPE option is an alternative to specifying Presentation Manager
  15898. compatibility with the %@AB@%NAME%@AE@% statement of a module-definition file. Use the
  15899. following syntax:  %@NL@%
  15900. %@NL@%
  15901. %@AS@%  /PMTYPE:type%@AE@%%@NL@%
  15902. %@NL@%
  15903. Type must be one of the following:  %@NL@%
  15904. %@NL@%
  15905. %@AB@%Type%@AE@%                              %@AB@%Effect%@AE@%
  15906. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15907. %@AB@%PM%@AE@%                                The application is an OS/2 Presentation 
  15908.                                   Manager application using the 
  15909.                                   Presentation Manager API and running in 
  15910.                                   the Presentation Manager screen group. 
  15911.                                   This type corresponds to specifying %@AB@%%@AE@%
  15912.                                   %@AB@%WINDOWAPI%@AE@% in the %@AB@%NAME%@AE@% statement of a 
  15913.                                   module-definition file.
  15914.  
  15915. %@AB@%VIO%@AE@%                               The application is compatible with the 
  15916.                                   OS/2 Presentation Manager and can run in
  15917.                                   a window or in a
  15918.                                   separate screen group. This type 
  15919.                                   corresponds to specifying %@AB@%WINDOWCOMPAT%@AE@% 
  15920.                                   in the %@AB@%NAME %@AE@%statement of a 
  15921.                                   module-definition file.
  15922.  
  15923. %@AB@%NOVIO%@AE@%                             The application is not compatible with 
  15924.                                   the OS/2
  15925.                                   Presentation Manager. It must run in a 
  15926.                                   separate
  15927.                                   screen group. This type corresponds to 
  15928.                                   specifying%@AB@%%@AE@%
  15929.                                   %@AB@%NOTWINDOWCOMPAT%@AE@% in the %@AB@%NAME%@AE@% statement of
  15930.                                   a module-definition file.
  15931.  
  15932. %@NL@%
  15933. %@2@%%@CR:C6A00140034 @%%@AB@%14.5  The BIND Utility%@AE@%%@EH@%%@NL@%
  15934. %@NL@%
  15935. The BIND utility converts a protected-mode program into a program that runs
  15936. in both OS/2 and DOS environments. It replaces Family API calls to
  15937. dynamic-link library functions with DOS emulator routines from the API.LIB
  15938. library. (See Section 14.1.3, "Creating Dual-Mode Programs as Family
  15939. Applications," for a list of Family API calls.) BIND produces a stand-alone
  15940. program file that can run under  %@NL@%
  15941. %@NL@%
  15942. %@NL@%
  15943.   ■   OS/2 protected mode%@NL@%
  15944. %@NL@%
  15945.   ■   OS/2 real mode%@NL@%
  15946. %@NL@%
  15947.   ■   DOS 2.x and DOS 3.x%@NL@%
  15948. %@NL@%
  15949. %@NL@%
  15950. BIND is an alternative to the C compiler's /Fb option described in Section
  15951. 14.2.2, "Creating Bound Programs Option." You must use BIND instead of the
  15952. /Fb option when you compile with the /c (compile without link) option or
  15953. when your program includes functions that operate only in protected mode.  %@NL@%
  15954. %@NL@%
  15955. %@AU@% You can include functions in a bound application that are not members of
  15956. %@AU@%the Family API.%@AE@%  %@NL@%
  15957. %@NL@%
  15958. To include functions available only in protected mode, you must run the BIND
  15959. utility with the /n option. Your run-time code must call the Family API
  15960. function %@AB@%DosGetMachineMode%@AE@% to determine whether it is running in real or
  15961. protected mode. When your program executes in real mode, it will be aborted
  15962. if it tries to call a function available only in protected mode.  %@NL@%
  15963. %@NL@%
  15964. You might choose to design your application so it executes different
  15965. sections of code, depending on the machine mode. For example, the
  15966. application may need to keep track of the passage of elapsed time or to
  15967. detect time-outs. In real mode, you might use polling or timing loops or
  15968. perhaps intercept the timer interrupts. In protected mode, you should use
  15969. the OS/2 semaphore and timer services, such as %@AB@%DosSetSem%@AE@% and %@AB@%DosTimerAsync%@AE@%,
  15970. instead.  %@NL@%
  15971. %@NL@%
  15972. Invoke BIND with the following syntax:  %@NL@%
  15973. %@NL@%
  15974. %@AS@%  BIND infile «implibs» «linklibs» «/o outfile» «/n @file» «/n names» 
  15975. %@AS@%  «/m mapfile»%@AE@%%@NL@%
  15976. %@NL@%
  15977. The /n option provides a way to include protected-mode functions. It has two
  15978. formats:  %@NL@%
  15979. %@NL@%
  15980. %@NL@%
  15981.   ■   A list of one or more names, separated by spaces.%@NL@%
  15982. %@NL@%
  15983.   ■   The name of a file, preceded by the at (@) sign. The file should
  15984.       consist of a list of functions, one name per line.%@NL@%
  15985. %@NL@%
  15986. %@NL@%
  15987. The /o option specifies a name for the bound-executable file. If it is not
  15988. present, the name of the input file is used.  %@NL@%
  15989. %@NL@%
  15990. The /m option causes a link map to be generated for the real-mode version of
  15991. the executable file.  %@NL@%
  15992. %@NL@%
  15993. To bind a program named TIMER that uses %@AB@%DosTimerAsync%@AE@% to manage time-outs
  15994. when running in protected mode, invoke BIND as follows:  %@NL@%
  15995. %@NL@%
  15996. %@AS@%  BIND TIMER /n DosTimerAsync%@AE@%%@NL@%
  15997. %@NL@%
  15998. For more information about BIND and other command-line options, consult
  15999. on-line help.  %@NL@%
  16000. %@NL@%
  16001. %@NL@%
  16002. %@NL@%
  16003. %@NL@%
  16004. %@NL@%
  16005. %@NL@%
  16006. %@CR:C6A00150001 @%%@1@%%@AB@%Chapter 15  Creating Multithread OS/2 Applications%@AE@%%@EH@%%@NL@%
  16007. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16008. %@NL@%
  16009. Microsoft C, version 6.0, provides support for creating multithread
  16010. applications under OS/2. You should consider using more than one thread if
  16011. your application needs to manage multiple activities, such as simultaneous
  16012. keyboard and mouse input. One thread can process keyboard input while a
  16013. second thread filters mouse activities. A third thread could update the
  16014. display screen based on data from the mouse and keyboard threads. At the
  16015. same time, other threads can access disk files or get data from a
  16016. communications port.  %@NL@%
  16017. %@NL@%
  16018. This chapter explains the features in C 6.0 that support the creation of
  16019. multithread programs. It also describes some important ways in which
  16020. programming for OS/2 is different than programming for DOS.  %@NL@%
  16021. %@NL@%
  16022. %@NL@%
  16023. %@2@%%@CR:C6A00150002 @%%@AB@%15.1  Multithread Programs%@AE@%%@EH@%%@NL@%
  16024. %@NL@%
  16025. OS/2 performs the scheduling and allocation of real hardware resources to
  16026. multiple programs, or "processes." It does not actually schedule the
  16027. processes themselves; it schedules threads belonging to the processes.  %@NL@%
  16028. %@NL@%
  16029. A thread is basically a path of execution through a program. It is also the
  16030. smallest unit of execution that OS/2 schedules. A thread consists of a
  16031. stack, the state of the CPU registers, and an entry in the execution list of
  16032. the system scheduler. Each thread shares all of the process's resources.  %@NL@%
  16033. %@NL@%
  16034. A process consists of one or more threads and the code, data, and other
  16035. resources of a program in memory. Typical program resources are open files,
  16036. semaphores, and dynamically allocated memory. A program executes when the
  16037. system scheduler gives one of its threads execution control. The scheduler
  16038. determines which threads should run and when they should run. Threads of
  16039. lower priority may have to wait while higher priority threads complete their
  16040. tasks.  %@NL@%
  16041. %@NL@%
  16042. %@AU@% Threads operate  independently and are  unaware of other threads.%@AE@%  %@NL@%
  16043. %@NL@%
  16044. All threads in a process operate independently of one another. Unless you
  16045. take special steps to make them visible to each other, each thread executes
  16046. while completely unaware of the existence of other threads in a process.
  16047. Threads sharing common resources, however, must coordinate their work by
  16048. using flags, semaphores or some other method of interprocess communication.
  16049. See Section 15.3, "Writing a Multithread Program," for more information
  16050. about synchronizing threads.  %@NL@%
  16051. %@NL@%
  16052. %@NL@%
  16053. %@3@%%@CR:C6A00150003 @%%@AB@%15.1.1  Library Support%@AE@%%@EH@%%@NL@%
  16054. %@NL@%
  16055. %@AU@% All shared functions  in a multithread  program must be re-entrant.%@AE@%  %@NL@%
  16056. %@NL@%
  16057. If one thread is suspended by the OS/2 scheduler while executing the %@AB@%printf%@AE@%
  16058. function, one of the program's other threads might start executing. If the
  16059. second thread also calls %@AB@%printf%@AE@%, data might be corrupted. To avoid this,
  16060. access to static data used by the function must be restricted to one thread
  16061. at a time. This process of restricting access to certain data is called
  16062. serialization.  %@NL@%
  16063. %@NL@%
  16064. You do not need to serialize access to stack-based (automatic) variables
  16065. because each thread has a different stack. Therefore, a function that uses
  16066. only automatic (stack) variables is re-entrant. The standard C run-time
  16067. libraries, such as SLIBCE, have a limited number of re-entrant functions. A
  16068. multithread program needing to use C run-time library functions that are
  16069. normally not re-entrant should be built with the multithread library
  16070. LLIBCMT.LIB.  %@NL@%
  16071. %@NL@%
  16072. %@NL@%
  16073. %@4@%%@AB@%The Multithread C Library LLIBCMT.LIB%@AE@%%@EH@%%@NL@%
  16074. %@NL@%
  16075. The support library LLIBCMT.LIB is a re-entrant large-model library for
  16076. cre-ating multithread programs.  %@NL@%
  16077. %@NL@%
  16078. %@AU@% A multithread program  linked with LLIBCMT.LIB can  use any memory model.%@AE@%  %@NL@%
  16079. %@NL@%
  16080. All calls to library functions must use the large-model calling interface
  16081. (far code pointers, far calls, and far data pointers). When your application
  16082. calls functions in this library,  %@NL@%
  16083. %@NL@%
  16084. %@NL@%
  16085.   ■   All library calls must be far calls.%@NL@%
  16086. %@NL@%
  16087.   ■   All library calls must use the C calling convention; programs compiled
  16088.       using the /Gr (fastcall calling convention) or /Gc (Pascal calling
  16089.       convention) options must use the standard include files for the
  16090.       run-time library functions they call.%@NL@%
  16091. %@NL@%
  16092.   ■   All data and code pointers must be far pointers.%@NL@%
  16093. %@NL@%
  16094.   ■   Variables passed to library functions must either be passed by value
  16095.       or cast to a far address.%@NL@%
  16096. %@NL@%
  16097.   ■   Your main function must be declared far if you are compiling with the
  16098.       small or compact memory models.%@NL@%
  16099. %@NL@%
  16100. %@NL@%
  16101. You do not need to explicitly declare far pointers if you are using the
  16102. compact, large, or huge memory models, since these models use far pointers
  16103. as default. For the large and huge memory models, the function calls are
  16104. also far by default.  %@NL@%
  16105. %@NL@%
  16106. A small-model program calling a library function such as %@AB@%isupper%@AE@%, for
  16107. example, must use declarations like the following:  %@NL@%
  16108. %@NL@%
  16109. %@AS@%  int _far _cdecl isupper( int _c );%@AE@%%@NL@%
  16110. %@NL@%
  16111. %@AU@% Programs built with LLIBCMT.LIB are entirely self-contained.%@AE@%  %@NL@%
  16112. %@NL@%
  16113. Programs built with LLIBCMT.LIB do not share C run-time library code or data
  16114. with any dynamic-link libraries they call. Chapter 16 explains how to build
  16115. DLLs and how to share code and data between processes.  %@NL@%
  16116. %@NL@%
  16117. %@NL@%
  16118. %@4@%%@AB@%Alternatives to LLIBCMT.LIB%@AE@%%@EH@%%@NL@%
  16119. %@NL@%
  16120. If you choose to build a multithread program without using LLIBCMT.LIB, you
  16121. must do the following:  %@NL@%
  16122. %@NL@%
  16123. %@NL@%
  16124.   ■   Use the standard C libraries and limit library calls to the set of
  16125.       re-entrant functions.%@NL@%
  16126. %@NL@%
  16127.   ■   Use the OS/2 API thread management functions, such as %@AB@%DosCreateThread%@AE@%.%@NL@%
  16128. %@NL@%
  16129.   ■   Provide your own synchronization for functions that are not re-entrant
  16130.       by using OS/2 services such as semaphores and the %@AB@%DosEnterCritSec%@AE@% and
  16131.       %@AB@%DosExitCritSec%@AE@% functions.%@NL@%
  16132. %@NL@%
  16133. %@NL@%
  16134. The C run-time library functions listed below are re-entrant and can be used
  16135. in multithread programs linked with the standard libraries.  %@NL@%
  16136. %@NL@%
  16137. %@AB@%abs%@AE@%
  16138. %@AB@%atoi%@AE@%
  16139. %@AB@%atol%@AE@%
  16140. %@AB@%bsearch%@AE@%
  16141. %@AB@%chdir%@AE@%
  16142. %@AB@%getpid%@AE@%
  16143. %@AB@%halloc%@AE@%
  16144. %@AB@%hfree%@AE@%
  16145. %@AB@%itoa%@AE@%
  16146. %@AB@%labs%@AE@%
  16147. %@AB@%lfind%@AE@%
  16148. %@AB@%lsearch%@AE@%
  16149. %@AB@%memccpy%@AE@%
  16150. %@AB@%memchr%@AE@%
  16151. %@AB@%memcmp%@AE@%
  16152. %@AB@%memcpy%@AE@%
  16153. %@AB@%memicmp%@AE@%
  16154. %@AB@%memmove%@AE@%
  16155. %@AB@%memset%@AE@%
  16156. %@AB@%mkdir%@AE@%
  16157. %@AB@%movedata%@AE@%
  16158. %@AB@%putch%@AE@%
  16159. %@AB@%rmdir%@AE@%
  16160. %@AB@%segread%@AE@%
  16161. %@AB@%strcat%@AE@%
  16162. %@AB@%strchr%@AE@%
  16163. %@AB@%strcmp%@AE@%
  16164. %@AB@%strcmpi%@AE@%
  16165. %@AB@%strcpy%@AE@%
  16166. %@AB@%stricmp%@AE@%
  16167. %@AB@%strlen%@AE@%
  16168. %@AB@%strlwr%@AE@%
  16169. %@AB@%strncat%@AE@%
  16170. %@AB@%strncmp%@AE@%
  16171. %@AB@%strncpy%@AE@%
  16172. %@AB@%strnicmp%@AE@%
  16173. %@AB@%strnset%@AE@%
  16174. %@AB@%strrchr%@AE@%
  16175. %@AB@%strrev%@AE@%
  16176. %@AB@%strset%@AE@%
  16177. %@AB@%strstr%@AE@%
  16178. %@AB@%strupr%@AE@%
  16179. %@AB@%swab%@AE@%
  16180. %@AB@%tolower%@AE@%
  16181. %@AB@%toupper%@AE@%
  16182. %@AB@%──────────────────────────────────────────%@AE@%
  16183.  
  16184. %@AU@%WARNING%@AE@%%@NL@%
  16185. %@NL@%
  16186. The multithread library LLIBCMT.LIB includes the %@AB@%%@AE@%%@AI@%_beginthread%@AE@% and %@AB@%%@AE@%%@AI@%_endthread%@AE@%
  16187. functions. The %@AB@%%@AE@%%@AI@%_beginthread%@AE@% function performs initialization without which
  16188. many C run-time functions will fail. You must use %@AB@%%@AE@%%@AI@%_beginthread%@AE@% instead of
  16189. %@AB@%%@AE@%%@AI@%DosCreateThread%@AE@% in C programs built with LLIBCMT.LIB if you intend to call C
  16190. run-time functions.%@NL@%
  16191. ────────────────────────────────────────────────────────────────────────────%@NL@%
  16192. %@NL@%
  16193. %@NL@%
  16194. %@4@%%@AB@%The Multithread Library Compile Option (/MT)%@AE@%%@EH@%%@NL@%
  16195. %@NL@%
  16196. The /MT option for the CL command is the best way to build a multithread
  16197. program with LLIBCMT.LIB. The /MT option embeds the LLIBCMT library name in
  16198. the object file. Using the /MT option automatically specifies the /ALw /FPi
  16199. /G2 /D MT options. The following list describes what these options do.  %@NL@%
  16200. %@NL@%
  16201. %@AB@%Switch%@AE@%                            %@AB@%Effect%@AE@%
  16202. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16203. /ALw                              Use the large memory model with separate
  16204.                                   stack segment; do not reload the DS 
  16205.                                   register as part of the entry sequence 
  16206.                                   for every function
  16207.  
  16208. /FPi                              Generate in-line floating-point 
  16209.                                   instructions and select the emulator 
  16210.                                   math package
  16211.  
  16212. /G2                               Use the 80286 processor instruction set
  16213.  
  16214. /D MT                             Use the multithread version of the 
  16215.                                   include files
  16216.  
  16217. These options can be combined with other options to specify different memory
  16218. models and different relationships between the data segment and the stack.
  16219. You can override the /G2 and /FPi options by specifying a different option
  16220. later on the command line. The following example shows how to override the
  16221. floating-point package option:  %@NL@%
  16222. %@NL@%
  16223. %@AS@%  CL /MT /FPa /Lp PROG.C%@AE@%%@NL@%
  16224. %@NL@%
  16225. ────────────────────────────────────────────────────────────────────────────%@NL@%
  16226. NOTE
  16227.  
  16228. %@AI@%You cannot replace the /MT option with /ALw /FPi /G2. You must use /MT to
  16229. %@AI@%generate multithread programs.%@AE@%%@NL@%
  16230. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  16231. %@NL@%
  16232. %@NL@%
  16233. %@3@%%@CR:C6A00150004 @%%@AB@%15.1.2  Include Files%@AE@%%@EH@%%@NL@%
  16234. %@NL@%
  16235. The Microsoft C 6.0 include files contain conditional sections for
  16236. multithread applications using LLIBCMT.LIB. To compile your application with
  16237. the appropriate definitions, you can  %@NL@%
  16238. %@NL@%
  16239. %@NL@%
  16240.   ■   Compile with the /MT option described in Section 15.1.1, "Library
  16241.       Support."%@NL@%
  16242. %@NL@%
  16243.   ■   Define the symbolic constant %@AB@%MT%@AE@% in your source file or on the command
  16244.       line with the /D option.%@NL@%
  16245. %@NL@%
  16246. %@NL@%
  16247. %@AU@% Always use the  standard include files.%@AE@%  %@NL@%
  16248. %@NL@%
  16249. Standard include files declare C run-time library functions as they are
  16250. implemented in the libraries. If you used the Maximum Optimization (/Ox) or
  16251. Register Calling Convention (/Gr) option, the compiler assumes that all
  16252. functions should be called using the register calling convention. The
  16253. run-time library functions were compiled using either the C or the
  16254. FORTRAN/Pascal calling convention, and the declarations in the standard
  16255. include files tell the compiler to generate correct external references to
  16256. these functions.  %@NL@%
  16257. %@NL@%
  16258. See Section 15.4, "Compiling and Linking," for examples of how to use the%@AB@% MT%@AE@%
  16259. constant.  %@NL@%
  16260. %@NL@%
  16261. %@NL@%
  16262. %@3@%%@CR:C6A00150005 @%%@AB@%15.1.3  C Run-Time Library Functions for Thread Control%@AE@%%@EH@%%@NL@%
  16263. %@NL@%
  16264. All OS/2 programs have at least one thread. Any thread can create additional
  16265. threads. A thread can complete its work very quickly and then terminate, or
  16266. it can stay active for the life of the program.  %@NL@%
  16267. %@NL@%
  16268. The LLIBCMT and LLIBCDLL C run-time libraries provide two functions for
  16269. thread creation and termination: the %@AB@%_beginthread%@AE@% and %@AB@%_endthread%@AE@% functions.
  16270. They also declare the global variable %@AB@%_threadid%@AE@%, which contains the address
  16271. of an application's current thread identifier.  %@NL@%
  16272. %@NL@%
  16273. The %@AB@%_beginthread%@AE@% function creates a new thread and returns a thread
  16274. identifier if the operation is successful. The thread will terminate
  16275. automatically if it completes execution, or it can terminate itself with a
  16276. call to %@AB@%_endthread%@AE@%.  %@NL@%
  16277. %@NL@%
  16278. The global variable %@AB@%_threadid%@AE@% holds the address of the identifier of the
  16279. current thread. It is defined in the STDDEF.H file as shown below:  %@NL@%
  16280. %@NL@%
  16281. %@AS@%  /* define pointer to thread id value */
  16282. %@AS@%  extern int far * _threadid;%@AE@%%@NL@%
  16283. %@NL@%
  16284. ────────────────────────────────────────────────────────────────────────────%@NL@%
  16285. %@AU@%WARNING%@AE@%%@NL@%
  16286. %@NL@%
  16287. If you are going to call C run-time routines from a program built with
  16288. LLIBCMT.LIB, you must start your threads with the %@AB@%%@AE@%%@AI@%_beginthread%@AE@% function. Do
  16289. not use the OS/2 functions %@AB@%%@AE@%%@AI@%DosExit%@AE@% %@AB@% %@AE@%and %@AB@%DosCreateThread%@AE@%.%@AB@%%@AE@%%@AI@% %@AE@%Using
  16290. %@AB@%%@AE@%%@AI@%DosSuspendThread%@AE@% can lead to a deadlock condition when more than one thread
  16291. is blocked waiting for the suspended thread to complete its access to a C
  16292. run-time data structure.%@NL@%
  16293. ────────────────────────────────────────────────────────────────────────────%@NL@%
  16294. %@NL@%
  16295. The %@AB@%_beginthread%@AE@% and %@AB@%_endthread%@AE@% functions are described in detail below.
  16296. Section 15.2 illustrates their use in a sample multithread program.  %@NL@%
  16297. %@NL@%
  16298. %@NL@%
  16299. %@4@%%@AB@%The _beginthread Function%@AE@%%@EH@%%@NL@%
  16300. %@NL@%
  16301. %@AU@% All threads in a process  can execute concurrently.%@AE@%  %@NL@%
  16302. %@NL@%
  16303. The %@AB@%_beginthread%@AE@% function creates a new thread. A thread shares the code and
  16304. data segments of a process with other threads in the process but has its own
  16305. unique register values, stack space, and current instruction address. The
  16306. system gives CPU time to each thread, so that all threads in a process can
  16307. execute concurrently. You can find a complete description of %@AB@%_beginthread%@AE@%
  16308. and its arguments in on-line help.%@CR:C6A00150006 @%%@CR:C6A00150007 @%  %@NL@%
  16309. %@NL@%
  16310. The %@AB@%_beginthread%@AE@% function is similar to the %@AB@%DosCreateThread%@AE@% function in the
  16311. OS/2 API with these differences:  %@NL@%
  16312. %@NL@%
  16313. %@NL@%
  16314.   ■   The %@AB@%_beginthread%@AE@% function lets you pass arguments to the thread.%@NL@%
  16315. %@NL@%
  16316.   ■   The stack address points to the bottom of the stack. It is the address
  16317.       of the start of an array or of the start of a block of dynamically
  16318.       allocated memory. When you use the %@AB@%DosCreateThread%@AE@% call, the stack
  16319.       address points to the top of the stack.%@NL@%
  16320. %@NL@%
  16321.   ■   If you specify %@AB@%NULL%@AE@% for the stack address, %@AB@%_beginthread%@AE@% manages
  16322.       allocation and deallocation of the thread stack for you. This option
  16323.       is advantageous because it is difficult for your program to determine
  16324.       when a thread has terminated, so you cannot know when to deallocate
  16325.       the thread stack. However, %@AB@%_beginthread%@AE@% maintains enough information
  16326.       to know when a thread has terminated and deallocates the thread's
  16327.       stack the next time its thread ID is used.%@NL@%
  16328. %@NL@%
  16329. %@NL@%
  16330. The %@AB@%_beginthread%@AE@% function returns the thread ID number of the new thread if
  16331. successful or -1 if there was an error. Errors include specifying an
  16332. odd-address stack or an odd- or zero-length stack (which is different than
  16333. passing %@AB@%NULL%@AE@% for the stack address) or trying to create too many threads.
  16334. The multithread library, LLIBCMT.LIB, supports the maximum number of threads
  16335. allowed by OS/2.  %@NL@%
  16336. %@NL@%
  16337. %@NL@%
  16338. %@4@%%@AB@%The _endthread Function%@AE@%%@EH@%%@NL@%
  16339. %@NL@%
  16340. The %@AB@%_endthread%@AE@% function terminates a thread created by %@AB@%_beginthread%@AE@%. Threads
  16341. terminate automatically when they complete. The %@AB@%_endthread%@AE@% function is
  16342. useful for conditional termination from within a thread. A thread dedicated
  16343. to communications processing, for example, can quit if it is unable to get
  16344. control of the communications port. You can find a complete description of
  16345. %@AB@%_endthread%@AE@% in on-line help.  %@NL@%
  16346. %@NL@%
  16347. %@NL@%
  16348. %@2@%%@CR:C6A00150008 @%%@AB@%15.2  Sample Multithread C Program%@AE@%%@EH@%%@NL@%
  16349. %@NL@%
  16350. BOUNCE.C is a sample multithread program that creates a new thread each time
  16351. the letter `a' or `A' is entered at the keyboard. Each thread bounces a
  16352. "happy face" of a different color around the screen. Up to 32 threads can be
  16353. created. The program's normal termination occurs when `q' or `Q' is entered.
  16354. It will also terminate if it receives the CTRL+C or CTRL+BREAK signals. See
  16355. Section 15.4, "Compiling and Linking," for details on compiling and linking
  16356. BOUNCE.C.  %@NL@%
  16357. %@NL@%
  16358. %@AS@%  /*  Bounce - Creates a new thread each time the letter 'a'is typed.
  16359. %@AS@%   *  Each thread bounces a happy face of a different color around the
  16360. %@AS@%screen.
  16361. %@AS@%   *  All threads are terminated when the letter 'q' is entered or when
  16362. %@AS@%   *  the CTRL+C/CTRL+BREAK signals are received.
  16363. %@AS@%   *
  16364. %@AS@%   *  This program requires the multithread library. For example, compile
  16365. %@AS@%   *  with the following command line:
  16366. %@AS@%   *      CL /MT BOUNCE.C
  16367. %@AS@%   */
  16368. %@AS@%  
  16369. %@AS@%  #define INCL_NOCOMMON                     /* Use only what we need */
  16370. %@AS@%  #define INCL_NOPM                         /* Don't need PM */
  16371. %@AS@%  #define INCL_DOSPROCESS                   /* DosBeep and DosSleep */
  16372. %@AS@%  #define INCL_DOSSEMAPHORES                /* OS/2 semaphore functions */
  16373. %@AS@%  #define INCL_DOSSIGNALS                   /* OS/2 signal functions */
  16374. %@AS@%  #define INCL_VIO
  16375. %@AS@%  #define INCL_KBD
  16376. %@AS@%  #include <os2.h>
  16377. %@AS@%  #include <stdlib.h>
  16378. %@AS@%  #include <string.h>
  16379. %@AS@%  #include <stdio.h>
  16380. %@AS@%  #include <process.h>
  16381. %@AS@%  
  16382. %@AS@%  #define STACK_SIZE   4096
  16383. %@AS@%  #define MAX_THREADS  32
  16384. %@AS@%  
  16385. %@AS@%  void main( void );                          /* Thread 1: main */
  16386. %@AS@%  void KbdThread( void );                     /* Thread 2: keyboard input */
  16387. %@AS@%  void BounceProc( char * MyID );             /* Threads 3 to n: display */
  16388. %@AS@%  void VioClrScr( void );                     /* Screen clear */
  16389. %@AS@%  void ShutDown( void );                      /* Program shutdown */
  16390. %@AS@%  void VioWrtCStr( char *pchString,           /* Write string to display */
  16391. %@AS@%                   unsigned usRow, unsigned usColumn );
  16392. %@AS@%  void pascal far SigHandler( unsigned SigArg,/* Signal handler */
  16393. %@AS@%                              unsigned SigNum );
  16394. %@AS@%                                              /* Screen clear macro */
  16395. %@AS@%  #define VioClrScr() VioScrollDn( 0, 0, 50, 80, 50, BlankCell, 0 )%@AE@%%@NL@%
  16396. %@NL@%
  16397. %@AS@%  struct tagCoords                            /* Display coordinates */
  16398. %@AS@%  {
  16399. %@AS@%      int xLoc;
  16400. %@AS@%      int yLoc;
  16401. %@AS@%      int xInc;
  16402. %@AS@%      int yInc;
  16403. %@AS@%  };
  16404. %@AS@%  
  16405. %@AS@%  unsigned long  RunFlag = 0;                 /* "Keep Running" semaphore */
  16406. %@AS@%  unsigned long  ScreenLock = 0;              /* Screen update semaphore  */
  16407. %@AS@%  
  16408. %@AS@%  char BlankCell[2] = { 0x20, 0x07 };
  16409. %@AS@%  VIOMODEINFO vmi = { sizeof( VIOMODEINFO ) };/* Mode information */
  16410. %@AS@%  
  16411. %@AS@%  PFNSIGHANDLER PrevHandler;                  /* for SetSigHandler call */
  16412. %@AS@%  unsigned int  PrevAction;                   /* for SetSigHandler call */
  16413. %@AS@%  
  16414. %@AS@%  void main()                                 /* Thread One */
  16415. %@AS@%  {
  16416. %@AS@%      /* Get display screen's text row and column sizes & clear the
  16417. %@AS@%screen.*/
  16418. %@AS@%      VioGetMode( &vmi, 0 );
  16419. %@AS@%      VioClrScr();
  16420. %@AS@%      VioWrtCStr( "Threads running: 00.  Press 'a' to start another thread",
  16421. %@AS@%                  vmi.row - 1, 0 );
  16422. %@AS@%  
  16423. %@AS@%      /* Set the "we are running" semaphore. */
  16424. %@AS@%      DosSemSet( &RunFlag );
  16425. %@AS@%  
  16426. %@AS@%      /* Start keyboard thread. Let _beginthread allocate memory
  16427. %@AS@%       *  for the thread's stack.
  16428. %@AS@%       */
  16429. %@AS@%      _beginthread( KbdThread, NULL, STACK_SIZE, NULL );
  16430. %@AS@%  
  16431. %@AS@%      /* Install signal handler for CTRL+BREAK & CRTL+C. */
  16432. %@AS@%      DosSetSigHandler( (PFNSIGHANDLER)SigHandler, &PrevHandler,
  16433. %@AS@%&PrevAction,
  16434. %@AS@%                         SIGA_ACCEPT, SIG_CTRLC );
  16435. %@AS@%  
  16436. %@AS@%      /* Wait for "running" semaphore to clear (from signal or 'q' key). */
  16437. %@AS@%      DosSemWait( &RunFlag, SEM_INDEFINITE_WAIT );
  16438. %@AS@%  
  16439. %@AS@%      _endthread();             /* Kill all threads */
  16440. %@AS@%  }%@AE@%%@NL@%
  16441. %@NL@%
  16442. %@AS@%  void pascal far SigHandler( unsigned int SigArg, unsigned int SigNum )
  16443. %@AS@%  {
  16444. %@AS@%      static char BreakMsg[] = "Signal Termination";
  16445. %@AS@%  
  16446. %@AS@%      ShutDown();
  16447. %@AS@%      VioWrtCStr( BreakMsg, vmi.row - 1, 0 );
  16448. %@AS@%      /* Restore original signal handler for CTRL+BREAK & CRTL+C. */
  16449. %@AS@%      DosSetSigHandler( (PFNSIGHANDLER)PrevHandler, &PrevHandler,
  16450. %@AS@%&PrevAction,
  16451. %@AS@%                         PrevAction, SIG_CTRLC );
  16452. %@AS@%  }
  16453. %@AS@%  void ShutDown( void )                       /* Clean up display when done
  16454. %@AS@%*/
  16455. %@AS@%  {
  16456. %@AS@%      /* Lock out screen updates from BounceProc & clear "running" semaphore
  16457. %@AS@%*/
  16458. %@AS@%      DosSemWait( &ScreenLock, SEM_INDEFINITE_WAIT );
  16459. %@AS@%      DosSemSet( &ScreenLock );
  16460. %@AS@%      VioClrScr();
  16461. %@AS@%      DosSemClear( &RunFlag );
  16462. %@AS@%  }
  16463. %@AS@%  
  16464. %@AS@%  void KbdThread( void )                          /* Thread Two: keyboard */
  16465. %@AS@%  {
  16466. %@AS@%      KBDKEYINFO  KeyInfo;                        /* for KbdCharIn call */
  16467. %@AS@%      char        ThreadNr = 0;
  16468. %@AS@%      char        NThreadMsg[4];
  16469. %@AS@%  
  16470. %@AS@%      do
  16471. %@AS@%      {
  16472. %@AS@%          /* Block this thread by waiting for keyboard input. */
  16473. %@AS@%  
  16474. %@AS@%          KbdCharIn( &KeyInfo, IO_WAIT, 0 );
  16475. %@AS@%          if( tolower( KeyInfo.chChar ) == 'a' && ThreadNr < MAX_THREADS)
  16476. %@AS@%          {
  16477. %@AS@%              ThreadNr++;
  16478. %@AS@%              _beginthread( BounceProc, NULL, STACK_SIZE, &ThreadNr );
  16479. %@AS@%              VioWrtCharStr( NThreadMsg, sprintf( NThreadMsg, "%02d",
  16480. %@AS@%ThreadNr ),
  16481. %@AS@%                             vmi.row - 1, 17, 0 );
  16482. %@AS@%          }
  16483. %@AS@%      } while( tolower( KeyInfo.chChar ) != 'q' );
  16484. %@AS@%  
  16485. %@AS@%      ShutDown();
  16486. %@AS@%  }
  16487. %@AS@%  
  16488. %@AS@%  /* getrandom returns a random number between min and max, which must be in
  16489. %@AS@%   * integer range.
  16490. %@AS@%   */
  16491. %@AS@%  #define getrandom( min, max ) ((rand() % (int)(((max) + 1) - (min))) +
  16492. %@AS@%(min))%@AE@%%@NL@%
  16493. %@NL@%
  16494. %@AS@%  void BounceProc( char * MyID )                  /* Threads Three to n */
  16495. %@AS@%  {
  16496. %@AS@%      int       xOld, yOld;
  16497. %@AS@%      char      MyCell[2];
  16498. %@AS@%      char      CurrentCell[2];
  16499. %@AS@%      int       CellLen = 2;
  16500. %@AS@%      struct tagCoords Coords;%@AE@%%@NL@%
  16501. %@NL@%
  16502. %@AS@%   /* Generate update increments and initial display coordinates. */
  16503. %@AS@%      srand( (unsigned) *MyID * 3 );
  16504. %@AS@%      Coords.xLoc = getrandom( 0, vmi.col - 1 );
  16505. %@AS@%      Coords.yLoc = getrandom( 0, vmi.row - 1 );
  16506. %@AS@%      Coords.xInc = getrandom( -3, 3 );
  16507. %@AS@%      Coords.yInc = getrandom( -3, 3 );
  16508. %@AS@%  
  16509. %@AS@%      /* Set up "happy face" & generate color attribute from thread
  16510. %@AS@%number.*/
  16511. %@AS@%      if( *MyID > 16)
  16512. %@AS@%          MyCell[0] = 0x01;          /* outline face */
  16513. %@AS@%      else
  16514. %@AS@%          MyCell[0] = 0x02;          /* solid face */
  16515. %@AS@%      MyCell[1] =  *MyID & 0x0F;     /* force black background */
  16516. %@AS@%  
  16517. %@AS@%      for( ;; )
  16518. %@AS@%      {
  16519. %@AS@%          /* Wait for display to be available, then lock it. */
  16520. %@AS@%          DosSemWait( &ScreenLock, SEM_INDEFINITE_WAIT );
  16521. %@AS@%          DosSemSet( &ScreenLock );
  16522. %@AS@%  
  16523. %@AS@%          /* If we still occupy the old screen position, blank it out. */
  16524. %@AS@%          VioReadCellStr( CurrentCell, &CellLen, yOld, xOld, 0 );
  16525. %@AS@%          if ( CurrentCell[0] == MyCell[0] && CurrentCell[1] == MyCell[1] )
  16526. %@AS@%              VioWrtCellStr( BlankCell, CellLen, yOld, xOld, 0 );
  16527. %@AS@%  
  16528. %@AS@%          /* Draw new face, then clear screen lock */
  16529. %@AS@%          VioWrtCellStr( MyCell, CellLen, Coords.yLoc, Coords.xLoc, 0 );
  16530. %@AS@%          DosSemClear( &ScreenLock );
  16531. %@AS@%  
  16532. %@AS@%          /* Increment the coordinates for next placement of the block. */
  16533. %@AS@%          xOld = Coords.xLoc;
  16534. %@AS@%          yOld = Coords.yLoc;
  16535. %@AS@%          Coords.xLoc += Coords.xInc;
  16536. %@AS@%          Coords.yLoc += Coords.yInc;
  16537. %@AS@%  
  16538. %@AS@%   %@AE@%%@NL@%
  16539. %@NL@%
  16540. %@AS@%         /* If we are about to go off the screen, reverse direction */
  16541. %@AS@%          if( Coords.xLoc < 0 || Coords.xLoc >= vmi.col )
  16542. %@AS@%          {
  16543. %@AS@%              Coords.xInc = -Coords.xInc;
  16544. %@AS@%              DosBeep( 400, 50 );
  16545. %@AS@%          }
  16546. %@AS@%          if( Coords.yLoc < 0 || Coords.yLoc >= vmi.row )
  16547. %@AS@%          {
  16548. %@AS@%              Coords.yInc = -Coords.yInc;
  16549. %@AS@%              DosBeep( 600, 50 );
  16550. %@AS@%          }
  16551. %@AS@%  
  16552. %@AS@%          /* Sleep to slow down screen update rate */
  16553. %@AS@%          DosSleep( 75L );
  16554. %@AS@%      }
  16555. %@AS@%  }
  16556. %@AS@%  
  16557. %@AS@%  void VioWrtCStr( char *pchString, unsigned usRow, unsigned usColumn )
  16558. %@AS@%  {
  16559. %@AS@%      VioWrtCharStr( pchString, strlen( pchString ), usRow, usColumn, 0 );
  16560. %@AS@%  }%@AE@%%@NL@%
  16561. %@NL@%
  16562. %@NL@%
  16563. %@2@%%@CR:C6A00150009 @%%@AB@%15.3  Writing a Multithread Program%@AE@%%@EH@%%@NL@%
  16564. %@NL@%
  16565. When you write a program with multiple threads, you must coordinate their
  16566. behavior and use of the program's resources. You must also make sure that
  16567. each thread receives its own stack.  %@NL@%
  16568. %@NL@%
  16569. %@NL@%
  16570. %@4@%%@AB@%Sharing Common Resources%@AE@%%@EH@%%@NL@%
  16571. %@NL@%
  16572. Each thread has its own stack and its own copy of the CPU registers. Other
  16573. resources, such as files, static data, and heap memory, are shared by all
  16574. threads in the process. Threads using these common resources must coordinate
  16575. their work. OS/2 provides semaphores and the %@AB@%DosEnterCritSec%@AE@% and
  16576. %@AB@%DosExitCritSec%@AE@% system services for synchronizing resources.  %@NL@%
  16577. %@NL@%
  16578. %@AU@% Your program must provide  for resource conflicts.%@AE@%  %@NL@%
  16579. %@NL@%
  16580. When multiple threads are accessing static data, your program must provide
  16581. for possible resource conflicts. Consider a program where one thread updates
  16582. a static data structure containing %@AI@%x%@AE@%,%@AI@%y%@AE@% coordinates for items to be displayed
  16583. by another thread. If the update thread alters the %@AI@%x%@AE@% coordinate and is
  16584. preempted before it can change the %@AI@%y%@AE@% coordinate, the display thread may be
  16585. scheduled before the %@AI@%y%@AE@% coordinate is updated. The item would be displayed at
  16586. the wrong location. You can avoid this type of problem by using semaphores
  16587. to control access to the structure.  %@NL@%
  16588. %@NL@%
  16589. Using semaphores is a way of communicating among threads or processes that
  16590. are executing asynchronously of one another. This communication is usually
  16591. used to coordinate the activities of multiple threads or processes,
  16592. typically by controlling access to a shared resource by "locking" and
  16593. "unlocking" the resource. To solve the %@AI@%x,y%@AE@% coordinate update problem
  16594. described above, the update thread would set a semaphore indicating that the
  16595. data structure is in use before performing the update. It would then clear
  16596. the semaphore when both coordinates had been processed. The display thread
  16597. must wait for the semaphore to be clear before updating the display. This
  16598. process of waiting for a semaphore is often called "blocking" on a semaphore
  16599. because the process is blocked and cannot continue until the semaphore
  16600. clears.  %@NL@%
  16601. %@NL@%
  16602. %@AU@% RAM semaphores are faster  than system semaphores.%@AE@%  %@NL@%
  16603. %@NL@%
  16604. OS/2 supports two types of semaphores: system and RAM semaphores. You must
  16605. use a system semaphore if more than one process needs to access the
  16606. semaphore. You can use the much faster RAM semaphores if their use is
  16607. confined to the threads within a process.  %@NL@%
  16608. %@NL@%
  16609. The BOUNCE.C program in Section 15.2 uses a RAM semaphore named %@AS@% ScreenLock %@AE@%
  16610. to coordinate screen updates. Each time one of the display threads is ready
  16611. to write to the screen, it calls %@AB@%DosSemWait%@AE@% with a pointer to %@AS@% ScreenLock
  16612. %@AS@%%@AE@%and constant %@AB@%SEM_INDEFINITE_WAIT%@AE@% to indicate that the %@AB@%DosSemWait %@AE@%call should
  16613. block on the semaphore and not time out. If the %@AS@%ScreenLock %@AE@%semaphore is
  16614. clear, the wait function returns immediately. Otherwise, the thread blocks
  16615. until the semaphore clears. When the thread receives control again, it calls
  16616. %@AB@%DosSemSet%@AE@% to set the %@AS@%ScreenLock %@AE@%semaphore so other threads cannot interfere
  16617. with the display. When the thread completes the display update, it releases
  16618. the semaphore by calling %@AB@%DosSemClear%@AE@%.%@AS@%  %@AE@%%@NL@%
  16619. %@NL@%
  16620. The %@AS@% ShutDown %@AE@% routine in BOUNCE.C is called from both the keyboard thread
  16621. and the signal handler. The routine uses the %@AS@% ScreenLock %@AE@% semaphore to make
  16622. sure other threads do not write to the screen after the screen has been
  16623. cleared.  %@NL@%
  16624. %@NL@%
  16625. Screen displays and static data are only two of the resources requiring
  16626. careful management. For example, your program may have multiple threads
  16627. accessing the same file. Since another thread may have moved the file
  16628. pointer, each thread must reset the file pointer before reading or writing.
  16629. In addition, each thread must make sure that it is not preempted between the
  16630. time it positions the pointer and the time it accesses the file. These
  16631. threads should use a semaphore to coordinate access to the file by
  16632. bracketing each file access with %@AB@%DosSemRequest%@AE@% and %@AB@%DosSemClear%@AE@% calls. The
  16633. following code fragment illustrates this technique:  %@NL@%
  16634. %@NL@%
  16635. %@AS@%  HSEM    hsemIOSem;
  16636. %@AS@%  
  16637. %@AS@%  DosSemRequest( hsemIOSem, SEM_INDEFINITE_WAIT );
  16638. %@AS@%  fseek( fp, desired_position, 0L );
  16639. %@AS@%  fwrite( data, sizeof( data ), 1, fp );
  16640. %@AS@%  DosSemClear( hsemIOSem );%@AE@%%@NL@%
  16641. %@NL@%
  16642. %@NL@%
  16643. %@4@%%@AB@%Thread Stacks%@AE@%%@EH@%%@NL@%
  16644. %@NL@%
  16645. %@AU@% Stack checking is performed for each thread.%@AE@%  %@NL@%
  16646. %@NL@%
  16647. All of an application's default stack space is allocated to the first thread
  16648. of execution, which is known as thread 1. As a result, you must allocate
  16649. memory to provide a separate stack for each additional thread your program
  16650. needs. You must do this before creating the thread. Stack checking, if
  16651. enabled, is performed for each thread. The keyboard thread in BOUNCE.C calls
  16652. the %@AB@%malloc%@AE@% function each time the user wants to start a new display thread.
  16653. If the allocation is successful, the %@AB@%_beginthread%@AE@% function is called. The
  16654. first argument in the %@AB@%_beginthread%@AE@% call is a pointer to the %@AB@%BounceProc%@AE@%
  16655. function, which will execute the threads. The last argument is an ID number
  16656. that is passed to %@AB@%BounceProc%@AE@%. %@AB@%BounceProc%@AE@% uses the ID number to seed the
  16657. random number generator and to select the thread's color attribute and
  16658. display character.  %@NL@%
  16659. %@NL@%
  16660. Threads that make calls to the C run-time library or to the OS/2 API must
  16661. allow sufficient stack space for the library and API functions they call.
  16662. The C %@AB@%printf%@AE@% function requires more than 500 bytes of stack space, and you
  16663. should have 2K of stack space available when calling OS/2 API routines. To
  16664. be safe, allocate at least 4K for each thread's stack.  %@NL@%
  16665. %@NL@%
  16666. %@AU@% Use as little static  data as possible.%@AE@%  %@NL@%
  16667. %@NL@%
  16668. Since each thread has its own stack, you can avoid potential collisions over
  16669. data items by using as little static data as possible. Design your program
  16670. to use automatic stack variables for all data that can be private to a
  16671. thread. The only global variables in the BOUNCE.C program are either RAM
  16672. semaphores or variables that never change once they are initialized.  %@NL@%
  16673. %@NL@%
  16674. %@NL@%
  16675. %@4@%%@AB@%Signal Handling%@AE@%%@EH@%%@NL@%
  16676. %@NL@%
  16677. Signals are events that interrupt the normal flow of your program's
  16678. execution. They are similar to hardware interrupts, but they come from the
  16679. operating system or other programs and occur asynchronously. If you do not
  16680. provide your own routines, OS/2 will take the default action for each
  16681. signal, such as cancelling your program when the user enters CTRL+BREAK. You
  16682. can install your own signal handler with the OS/2 API function
  16683. %@AB@%DosSetSigHandler%@AE@%.  %@NL@%
  16684. %@NL@%
  16685. ────────────────────────────────────────────────────────────────────────────%@NL@%
  16686. %@AU@%WARNING%@AE@%%@NL@%
  16687. %@NL@%
  16688. The C run-time function signal is not supported in the multithread library
  16689. LLIBCMT.LIB.%@NL@%
  16690. ────────────────────────────────────────────────────────────────────────────%@NL@%
  16691. %@NL@%
  16692. When a signal occurs, OS/2 always suspends thread 1 and gives control to the
  16693. signal handler, if installed. As a result, thread 1 must not be executing C
  16694. run-time library code when the signal handler gets control or a potential
  16695. deadlock condition can occur. In addition, the signal handler must not call
  16696. C run-time library functions. Consider the following sequence of events:  %@NL@%
  16697. %@NL@%
  16698. %@NL@%
  16699.   1.  Thread 2 is executing %@AB@%printf%@AE@% when the user interrupts it by pressing
  16700.       CTRL+C. The program has designated a CTRL+C signal handler, so OS/2
  16701.       immediately transfers control to the signal handler in thread 1.%@NL@%
  16702. %@NL@%
  16703.   2.  The signal handler in thread 1 tries to execute the statement: 
  16704. %@NL@%
  16705. %@AS@%      printf( "^C: Do you want to quit?" );%@AE@%%@NL@%
  16706. %@NL@%
  16707. %@NL@%
  16708.   3.  The %@AB@%printf%@AE@% call in thread 2 has already locked output to the console,
  16709.       so thread 1's %@AB@%printf%@AE@% must wait for release of that lock.%@NL@%
  16710. %@NL@%
  16711.   4.  The thread 2 %@AB@%printf%@AE@% function never regains control because the signal
  16712.       handler must complete before other processing can continue. As a
  16713.       result, it is never able to release the lock on console output.%@NL@%
  16714. %@NL@%
  16715. %@NL@%
  16716. If a situation like this happens, the program will wait indefinitely for
  16717. resolution of the two mutually exclusive conditions.  %@NL@%
  16718. %@NL@%
  16719. A multithread C program can process signals if it adheres to the following
  16720. restrictions:  %@NL@%
  16721. %@NL@%
  16722. %@NL@%
  16723.   ■   Thread 1 must be dedicated to signal handling and must not call the C
  16724.       run-time library once it identifies the signal handler to OS/2 using
  16725.       the API function %@AB@%DosSetSigHandler%@AE@%. When the signal handler gets
  16726.       control, it should set a semaphore or flag so other threads in the
  16727.       program can determine that the signal has occurred and is being
  16728.       processed.%@NL@%
  16729. %@NL@%
  16730.   ■   The other threads in the process must check the status of semaphores
  16731.       set by thread 1 and respond accordingly. %@NL@%
  16732. %@NL@%
  16733. %@NL@%
  16734. The BOUNCE.C sample program waits until thread 2, the keyboard handler,
  16735. starts before installing the signal handler. It then dedicates thread 1 to
  16736. signal handling by having the thread wait for a semaphore. Thread 1 blocks
  16737. until either the keyboard thread or the signal handler clears the semaphore.
  16738. It then calls %@AB@%_endthread%@AE@% to terminate the process, including all the other
  16739. threads.  %@NL@%
  16740. %@NL@%
  16741. %@NL@%
  16742. %@2@%%@CR:C6A00150010 @%%@AB@%15.4  Compiling and Linking%@AE@%%@EH@%%@NL@%
  16743. %@NL@%
  16744. The steps for compiling and linking the multithread program BOUNCE.C are
  16745. given below:  %@NL@%
  16746. %@NL@%
  16747. %@NL@%
  16748.   1.  Ensure that the files LLIBCMT.LIB and OS2.LIB are in the directory
  16749.       specified in your LIB environment variable.%@NL@%
  16750. %@NL@%
  16751. %@STUB@%      The file LLIBCMT.LIB takes the place of the regular C run-time library
  16752.       files. The file OS2.LIB provides support for OS/2 system calls made in
  16753.       the program, such as %@AB@%KbdCharIn%@AE@%.%@NL@%
  16754. %@NL@%
  16755.   2.  Compile and link the program with the CL command-line option /MT.%@NL@%
  16756. %@NL@%
  16757. %@STUB@%      The /Lp option instructs the compiler to create a protected-mode
  16758.       application. The /MT option implies the large memory model with a
  16759.       separate stack segment (/ALw). The multithread library functions have
  16760.       their own data segment but use the caller's stack. This option also
  16761.       sets the library search record to LLIBCMT.LIB and sets the %@AB@%MT%@AE@% symbolic
  16762.       constant for the multithread versions of the include files. The /link
  16763.       GRTEXTP option instructs the linker to search GRTEXTP.LIB, the
  16764.       character-graphics library for protected mode.%@NL@%
  16765. %@NL@%
  16766. %@STUB@%      To compile and link in a single step, use this CL command line:%@NL@%
  16767. %@NL@%
  16768. %@AS@%      CL /Lp /MT BOUNCE.C /link grtextp%@AE@%%@NL@%
  16769. %@NL@%
  16770. %@STUB@%      For separate compile and link steps, you invoke the compiler and the
  16771.       linker with this code:%@NL@%
  16772. %@NL@%
  16773. %@AS@%      CL /c /Lp /MT BOUNCE.C
  16774. %@AS@%      LINK BOUNCE;%@AE@%%@NL@%
  16775. %@NL@%
  16776.   3.  If you choose not to use the /MT option, you must take these steps:%@NL@%
  16777. %@NL@%
  16778. %@NL@%
  16779. %@NL@%
  16780.   ■   Ensure that the special multithread include file support is enabled.
  16781. %@NL@%
  16782.       ■   Use the /Aw option. This is required because the functions in
  16783.           LLIBCMT.LIB have their own data segment but use the caller's
  16784.           stack. The /Aw option specifies a segment setup of SS not equal to
  16785.           DS with DS not reloaded on function entry.%@NL@%
  16786. %@NL@%
  16787.       ■   Make sure that only far pointers are passed to library functions.%@NL@%
  16788. %@NL@%
  16789.       ■   Make sure that all variables are either passed by value or cast to
  16790.           a far address (the large memory model).%@NL@%
  16791. %@NL@%
  16792.       ■   Specify the multithread library and suppress default library
  16793.           selection.%@NL@%
  16794. %@NL@%
  16795. %@STUB@%      The multithread include files are used when you define the symbolic
  16796.       constant %@AB@%MT%@AE@%. You can do this with the CL command line option /D MT or
  16797.       within the C source file before any include statements, as shown
  16798.       below:%@NL@%
  16799. %@NL@%
  16800. %@AS@%      #define MT
  16801. %@AS@%      #include <stdlib.h>%@AE@%%@NL@%
  16802. %@NL@%
  16803. %@STUB@%      To compile and link in a single step with the default libraries
  16804.       suppressed, this is the complete CL command line:%@NL@%
  16805. %@NL@%
  16806. %@AS@%      CL /Lp /ALw /Zl /D MT BOUNCE.C /link LLIBCMT+OS2%@AE@%%@NL@%
  16807. %@NL@%
  16808. %@STUB@%      To perform a two-step compile and link with the default libraries
  16809.       suppressed in the link step, use these commands:%@NL@%
  16810. %@NL@%
  16811. %@AS@%      CL /c /Lp /ALw /D MT BOUNCE.C
  16812. %@AS@%      LINK /NOD BOUNCE,,,LLIBCMT+OS2;%@AE@%%@NL@%
  16813. %@NL@%
  16814.       1.  Run the program under OS/2.%@NL@%
  16815. %@NL@%
  16816. %@NL@%
  16817. %@NL@%
  16818. %@NL@%
  16819. %@2@%%@CR:C6A00150011 @%%@AB@%15.5  Avoiding Problem Areas%@AE@%%@EH@%%@NL@%
  16820. %@NL@%
  16821. There are several problems you can encounter in creating, linking, or
  16822. executing a multithread C program. Some of the more common ones are
  16823. described here.  %@NL@%
  16824. %@NL@%
  16825. %@AB@%Problem%@AE@%                           %@AB@%Probable Cause%@AE@%
  16826. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16827. LINK searches for mLIBC%@AI@% f%@AE@%.LIB.    If you omit the /NOD option from the 
  16828.                                   LINK command, LINK searches for the 
  16829.                                   default library. The
  16830.                                   default library should not be used with 
  16831.                                   multithread programs. The /NOD option 
  16832.                                   tells the computer not to search the 
  16833.                                   default libraries. This problem can also
  16834.                                   be avoided by compiling with the /Zl 
  16835.                                   option, which suppresses default library
  16836.                                   search records in the object files.
  16837.  
  16838. You get error SYS1943. A program  Many OS/2 programming errors cause 
  16839. caused a protection               protection violations. A common cause of
  16840. violation.                        protection violations is the indirect 
  16841.                                   assignment of data to null pointers. 
  16842.                                   This results in your program trying to 
  16843.                                   access memory that does not "belong" to 
  16844.                                   it, so a protection violation is issued.
  16845.                                   Protection violations also occur if your
  16846.                                   program gets a memory buffer from the 
  16847.                                   operating system and then tries to read 
  16848.                                   or write past the end of the 
  16849.  
  16850.                                   buffer. Another cause of this error is 
  16851.                                   failing to specify the condition "SS is 
  16852.                                   not equal to DS" in the CL command 
  16853.                                   invocation. Specify the correct 
  16854.                                   conditions with the /ALw memory model 
  16855.                                   option.
  16856.  
  16857.                                   An easy way to detect the cause of a 
  16858.                                   protection violation is to compile your 
  16859.                                   program with CodeView information, then 
  16860.                                   run it in CodeView. When the protection 
  16861.                                   fault occurs, OS/2 will transfer control
  16862.                                   to CodeView, and the cursor will be 
  16863.                                   positioned on the line that caused the 
  16864.                                   problem. See Chapter 9, "Debugging C 
  16865.                                   Programs with CodeView," for more 
  16866.                                   information about the CodeView debugger.
  16867.  
  16868. Your program generates numerous   If you attempt to compile and link a 
  16869. compile and link errors.          multithread
  16870.                                   program without defining the symbolic 
  16871.                                   constant%@AB@% MT%@AE@%, many of the definitions 
  16872.                                   required for the multithread library 
  16873.                                   will be missing. Define %@AB@%MT%@AE@% on the CL 
  16874.                                   command line with /MT or /D MT, or use %@AS@% %@AE@%
  16875.                                   %@AS@%#define MT %@AE@%in your program.
  16876.  
  16877. You can eliminate many potential problems by setting the compiler's warning
  16878. level to one of its highest values and heeding the warning messages. By
  16879. using the /W3 or /W4 warning level options, you can detect unintentional
  16880. data conversions, missing function prototypes, and use of non-ANSI features.
  16881. %@NL@%
  16882. %@NL@%
  16883. %@NL@%
  16884. %@2@%%@CR:C6A00150012 @%%@AB@%15.6  Using the Protected-Mode CodeView Debugger%@AE@%%@EH@%%@NL@%
  16885. %@NL@%
  16886. The protected-mode version of CodeView (CVP) has special commands for
  16887. debugging multiple processes and threads. It adds Thread and Process items
  16888. to the standard Run Menu. Your CONFIG.SYS file must specify IOPL=YES for
  16889. protected-mode CodeView to run.%@CR:C6A00150013 @%%@CR:C6A00150014 @%%@CR:C6A00150015 @%  %@NL@%
  16890. %@NL@%
  16891. To enable multiple process debugging, invoke CodeView with the /O
  16892. (offspring) option. Selecting the Process item from the Run Menu brings up a
  16893. list box of child processes associated with the parent process. You choose
  16894. the process to be debugged by selecting it with the list box. The Process
  16895. item will be grey (unselectable) if you did not specify the /O option. The
  16896. /O option applies only to debugging multiple processes. You do not need to
  16897. use it to debug multiple threads.  %@NL@%
  16898. %@NL@%
  16899. Selecting the Thread item from the Run Menu produces a list box showing the
  16900. status of each thread associated with the current process. You can use the
  16901. list box to designate a different current thread or to change a thread's
  16902. status. There are equivalent keyboard commands for each option.  %@NL@%
  16903. %@NL@%
  16904. %@NL@%
  16905. %@3@%%@CR:C6A00150016 @%%@AB@%15.6.1  Compiling with the /Zi Option%@AE@%%@EH@%%@NL@%
  16906. %@NL@%
  16907. The compiler option /Zi causes the compiler to include symbolic information
  16908. and line numbers in the object file for debugging with CodeView. If you run
  16909. LINK in a separate step, you must invoke it with the /CODEVIEW option, which
  16910. can be abbreviated as /CO. To compile and link the sample program BOUNCE.C
  16911. in a single step, enter this code:  %@NL@%
  16912. %@NL@%
  16913. %@AS@%  CL /MT /Zi BOUNCE.C%@AE@%%@NL@%
  16914. %@NL@%
  16915. The following commands are for a two-step compile and link:  %@NL@%
  16916. %@NL@%
  16917. %@AS@%  CL /c /MT /Zi BOUNCE.C
  16918. %@AS@%  
  16919. %@AS@%  link /CO BOUNCE;%@AE@%%@NL@%
  16920. %@NL@%
  16921. %@NL@%
  16922. %@3@%%@CR:C6A00150017 @%%@AB@%15.6.2  Prompt for Thread Number%@AE@%%@EH@%%@NL@%
  16923. %@NL@%
  16924. When you debug a protected-mode program with CodeView, the command prompt is
  16925. preceded by a three-digit number indicating the current thread. Thread 1 is
  16926. always the current thread when you start a program. The prompt appears as  %@NL@%
  16927. %@NL@%
  16928. %@AS@%  001>%@AE@%%@NL@%
  16929. %@NL@%
  16930. %@NL@%
  16931. %@3@%%@CR:C6A00150018 @%%@AB@%15.6.3  Thread Commands%@AE@%%@EH@%%@NL@%
  16932. %@NL@%
  16933. Protected-mode CodeView (CVP) has special commands to control the execution
  16934. of threads. The CodeView Thread commands are accessed using the Thread
  16935. command from the Run menu. Dialog commands for thread control start with the
  16936. tilde character (%@AB@%~%@AE@%). Thread commands specify which thread(s) the command
  16937. applies to, followed by the command. The syntax of the dialog version of the
  16938. Thread command is  %@NL@%
  16939. %@NL@%
  16940. %@AB@%~%@AE@%«%@AI@%specifier%@AE@%«%@AI@%command%@AE@%»»  %@NL@%
  16941. %@NL@%
  16942. Entering the tilde character by itself displays the status of all threads.
  16943. Enter the tilde and a specifier to see the status of particular threads.
  16944. Legal values for the specifier field are listed below:  %@NL@%
  16945. %@NL@%
  16946. %@AB@%Specifier%@AE@%                         %@AB@%Function%@AE@%
  16947. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16948. (blank)                           Displays the status of all threads
  16949.  
  16950. #                                 Specifies the last thread that executed
  16951.  
  16952. .                                 Specifies the current thread
  16953.  
  16954. *                                 Specifies all threads
  16955.  
  16956. n                                 Specifies the number of an existing 
  16957.                                   thread
  16958.  
  16959. The optional command field controls the way specified threads are executed.
  16960. If it is omitted, status is displayed, but thread activity is not affected.
  16961. Thread commands are summarized below, followed by examples. For more
  16962. information about command execution and about how other threads in the
  16963. process may be affected, consult on-line help.  %@NL@%
  16964. %@NL@%
  16965. %@AB@%Command%@AE@%                           %@AB@%Function%@AE@%
  16966. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16967. (blank)                           Display status
  16968.  
  16969. %@AB@%BP%@AE@%                                Set a breakpoint (used with the normal 
  16970.                                   Breakpoint Set command syntax)
  16971.  
  16972. %@AB@%E%@AE@%                                 Execute in slow motion
  16973.  
  16974. %@AB@%F%@AE@%                                 Freeze the thread(s)
  16975.  
  16976. %@AB@%G%@AE@%                                 Pass control to a thread
  16977.  
  16978. %@AB@%P%@AE@%                                 Execute a program step
  16979.  
  16980. %@AB@%S%@AE@%                                 Select specified thread as the current 
  16981.                                   thread
  16982.  
  16983. %@AB@%T%@AE@%                                 Trace a thread
  16984.  
  16985. %@AB@%U%@AE@%                                 Unfreeze thread(s)
  16986.  
  16987. %@NL@%
  16988. %@4@%%@AB@%Controlling a Thread Being Debugged%@AE@%%@EH@%%@NL@%
  16989. %@NL@%
  16990. If your program has multiple threads using the same functions, you may want
  16991. to monitor the behavior of one particular thread. The standard Breakpoint
  16992. Set command will affect every thread. The thread Breakpoint Set command lets
  16993. you limit the breakpoint to one or more threads. The sample program BOUNCE.C
  16994. has multiple threads executing the function %@AB@%BounceProc%@AE@%. This function erases
  16995. the symbol at the thread's current screen position, writes it to a new
  16996. location, computes the display coordinates to be used the next time the
  16997. thread receives control, and then sleeps to slow down the rate at which the
  16998. display is updated.  %@NL@%
  16999. %@NL@%
  17000. Since thread-specific breakpoints can only be set for threads that are
  17001. already running, you can set a breakpoint that will be executed after the
  17002. target thread starts. In BOUNCE.C, the source line in thread 2 that tests
  17003. each character received from the keyboard is a good location for such a
  17004. breakpoint (line 113). Since thread 2 is not active when the program begins,
  17005. you must first set a breakpoint in thread 1 after it has started thread 2
  17006. (line 73). The first breakpoint can be set by conventional methods or by
  17007. using the thread breakpoint command:  %@NL@%
  17008. %@NL@%
  17009. %@AS@%  001>~1BP .73%@AE@%%@NL@%
  17010. %@NL@%
  17011. Once you have reached the first breakpoint, you can set the keyboard test
  17012. breakpoint for thread 2:  %@NL@%
  17013. %@NL@%
  17014. %@AS@%  001>~2BP .113%@AE@%%@NL@%
  17015. %@NL@%
  17016. The BOUNCE.C program starts a new thread each time the letter `a' is typed.
  17017. (`A' is also accepted.) Once you have started the desired number of threads,
  17018. you can trigger the thread 2 breakpoint without starting a new thread by
  17019. pressing another key, such as the space bar. When you reach the breakpoint
  17020. in thread 2, you can set breakpoints for the other threads. To set a
  17021. breakpoint in thread 3's %@AB@%BounceProc%@AE@% function immediately after it has
  17022. updated the screen (source line 168), enter this code:  %@NL@%
  17023. %@NL@%
  17024. %@AS@%  001>~3BP .168%@AE@%%@NL@%
  17025. %@NL@%
  17026. When this breakpoint is reached, the CodeView prompt will reflect the
  17027. current thread number:  %@NL@%
  17028. %@NL@%
  17029. %@AS@%  003>%@AE@%%@NL@%
  17030. %@NL@%
  17031. You can then set other breakpoints for the thread, execute it in slow motion
  17032. without any other threads running in the background, or enter other CodeView
  17033. commands, such as Breakpoint Clear.  %@NL@%
  17034. %@NL@%
  17035. %@NL@%
  17036. %@4@%%@AB@%Freezing and Unfreezing Threads%@AE@%%@EH@%%@NL@%
  17037. %@NL@%
  17038. %@AU@% Frozen threads do not execute.%@AE@%  %@NL@%
  17039. %@NL@%
  17040. It can be useful to freeze one or more threads so they don't interfere with
  17041. execution of a thread you are debugging. In the BOUNCE.C program, for
  17042. example, you can monitor the path of a single bouncing ball by freezing all
  17043. but one of the bounce threads. Frozen threads will not be scheduled for
  17044. execution.  %@NL@%
  17045. %@NL@%
  17046. If you have a large number of threads running, you can freeze all of them in
  17047. a single command and then unfreeze the threads you want to monitor. Unfrozen
  17048. threads continue to operate normally and will execute any breakpoints they
  17049. encounter. The following example freezes all threads, enables threads 1 and
  17050. 4, and then checks the status of all threads:  %@NL@%
  17051. %@NL@%
  17052. %@AS@%  001>~*F
  17053. %@AS@%  001>~1U
  17054. %@AS@%  001>~4U
  17055. %@AS@%  001>~%@AE@%%@NL@%
  17056. %@NL@%
  17057. If thread 1 is waiting for a semaphore when the status command is invoked,
  17058. the report shows the following:  %@NL@%
  17059. %@NL@%
  17060. %@AS@%  001 Blocked
  17061. %@AS@%  002 Frozen
  17062. %@AS@%  003 Frozen
  17063. %@AS@%  004 Runnable%@AE@%%@NL@%
  17064. %@NL@%
  17065. %@NL@%
  17066. %@4@%%@AB@%Switching to a Particular Thread%@AE@%%@EH@%%@NL@%
  17067. %@NL@%
  17068. The %@AB@%S%@AE@% (select) and %@AB@%E%@AE@% (execute) variations of the Thread command can be used
  17069. to switch the current thread. However, when another thread causes the
  17070. program to stop by hitting a breakpoint, the debugger will select the thread
  17071. that encountered the breakpoint as the current thread.  %@NL@%
  17072. %@NL@%
  17073. If you include %@AB@%~.S%@AE@% in the breakpoint command, CodeView stops the thread that
  17074. encounters the breakpoint, then immediately switches back to the current
  17075. thread. The following example selects thread 4, sets a breakpoint at line
  17076. 168 in thread 3, and switches to thread 4 when the breakpoint is hit:  %@NL@%
  17077. %@NL@%
  17078. %@AS@%  001>~4S
  17079. %@AS@%  001>~3BP .168 "~.S"
  17080. %@AS@%  001>G%@AE@%%@NL@%
  17081. %@NL@%
  17082. %@NL@%
  17083. %@3@%%@CR:C6A00150019 @%%@AB@%15.6.4  Screen Groups Used by CodeView%@AE@%%@EH@%%@NL@%
  17084. %@NL@%
  17085. Only one CodeView session at a time is supported in protected mode. You
  17086. cannot run multiple copies in concurrent screen groups.  %@NL@%
  17087. %@NL@%
  17088. The View Output Screen command ( %@AB@%\%@AE@% ) works differently in protected mode and
  17089. in real mode. In protected mode, your application's output will be displayed
  17090. for three seconds. The display will then revert to the CodeView display. To
  17091. view the output window for a longer period, specify a different delay
  17092. interval, measured in seconds, as follows:  %@NL@%
  17093. %@NL@%
  17094. %@AS@%  \10%@AE@%%@NL@%
  17095. %@NL@%
  17096.   %@NL@%
  17097. %@NL@%
  17098. %@NL@%
  17099. %@NL@%
  17100. %@NL@%
  17101. %@NL@%
  17102. %@NL@%
  17103. %@CR:C6A00160001 @%%@1@%%@AB@%Chapter 16  Dynamic Linking with OS/2%@AE@%%@EH@%%@NL@%
  17104. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17105. %@NL@%
  17106. An OS/2 dynamic-link library (DLL) is an executable file containing
  17107. functions that are available to other programs. In a statically linked
  17108. program, you link the program with all its component functions when you
  17109. build the executable file. In a dynamically linked program, the
  17110. program-build step does not link all of the code. Instead, OS/2 links calls
  17111. to functions in dynamic-link libraries at program load time or while the
  17112. program is running. The DLL code and data become part of the address space
  17113. of each program, even when the DLL is being accessed by several application
  17114. programs.  %@NL@%
  17115. %@NL@%
  17116. This chapter describes how to build your own dynamic-link libraries and how
  17117. to build programs that use them.  %@NL@%
  17118. %@NL@%
  17119. %@NL@%
  17120. %@2@%%@CR:C6A00160002 @%%@AB@%16.1  Overview of Dynamic Linking%@AE@%%@EH@%%@NL@%
  17121. %@NL@%
  17122. Dynamic linking is the process of resolving external calls when a program
  17123. runs, instead of at link time. It offers several benefits:  %@NL@%
  17124. %@NL@%
  17125. %@NL@%
  17126.   ■   Multiple programs can use the same dynamic-link library
  17127.       simultaneously. Since only one copy of the DLL is in memory, there are
  17128.       fewer demands for physical memory and swap space.%@NL@%
  17129. %@NL@%
  17130.   ■   Updates to dynamic-link libraries do not affect the programs that use
  17131.       them, since the only connection between DLLs and application programs
  17132.       is the function-calling sequence.%@NL@%
  17133. %@NL@%
  17134.   ■   Application programs require less disk space and memory, since their
  17135.       executable program files contain the names of DLL functions but not
  17136.       the code for the functions.%@NL@%
  17137. %@NL@%
  17138.   ■   Dynamic-link libraries can call other dynamic-link libraries.%@NL@%
  17139. %@NL@%
  17140.   ■   DLLs can extend the OS/2 operating system to provide new or improved
  17141.       system services. This is possible because most of OS/2 consists of a
  17142.       set of dynamic-link libraries.%@NL@%
  17143. %@NL@%
  17144. %@NL@%
  17145. %@NL@%
  17146. %@3@%%@CR:C6A00160003 @%%@AB@%16.1.1  Load-Time and Run-Time Linking%@AE@%%@EH@%%@NL@%
  17147. %@NL@%
  17148. Dynamic linking can take place both at program load time and while the
  17149. program is running. A program can call functions in more than one DLL and
  17150. combine both load-time and run-time linking.  %@NL@%
  17151. %@NL@%
  17152. %@AU@% For load-time dynamic linking, build a program that calls DLL functions by
  17153. %@AU@%name.%@AE@%  %@NL@%
  17154. %@NL@%
  17155. The linker creates special records containing the name of each DLL
  17156. subroutine and the name of its DLL file. It does not put any DLL code into
  17157. the program's executable file. At load time, OS/2 dynamically links the
  17158. program and its DLLs. It brings the program and the DLLs into memory and
  17159. updates the program's DLL calls with the address of each DLL routine. If a
  17160. DLL is already in memory, it is not reloaded.  %@NL@%
  17161. %@NL@%
  17162. With run-time dynamic linking, the program creates the DLL file name and
  17163. subroutine names during execution. The program then passes these names to
  17164. OS/2 so the operating system can load the dynamic-link library.  %@NL@%
  17165. %@NL@%
  17166. An example of a run-time dynamic link is an extension to the Programmer's
  17167. WorkBench (PWB). PWB has no information about which extensions it needs
  17168. until it reads the initialization file, TOOLS.INI. PWB then sends requests
  17169. to OS/2 to demand-load the DLLs that it needs.  %@NL@%
  17170. %@NL@%
  17171. %@NL@%
  17172. %@3@%%@CR:C6A00160004 @%%@AB@%16.1.2  Application Programs and DLLs%@AE@%%@EH@%%@NL@%
  17173. %@NL@%
  17174. With static linking, all library code is bound into the executable program
  17175. when you link the program. If the library changes, all programs using the
  17176. library must be relinked. With the exception of some Microsoft Windows
  17177. programs, all DOS programs use static linking.  %@NL@%
  17178. %@NL@%
  17179. %@AU@% Updates to parts of a program are easier to deliver using DLLs.%@AE@%  %@NL@%
  17180. %@NL@%
  17181. You can create loosely coupled applications and DLLs and modify the DLLs
  17182. without relinking the program. For example, if your product has an
  17183. underlying database access mechanism, you can package the database access
  17184. routines into a DLL. You can then ship improvements or changes to the
  17185. database code in a new dynamic-link library. The executable files for the
  17186. program do not have to be relinked or redistributed.  %@NL@%
  17187. %@NL@%
  17188. The programs calling a DLL are known as the DLL's "clients."  %@NL@%
  17189. %@NL@%
  17190. %@NL@%
  17191. %@3@%%@CR:C6A00160005 @%%@AB@%16.1.3  DLLs and Microsoft C Run-Time Libraries%@AE@%%@EH@%%@NL@%
  17192. %@NL@%
  17193. You can construct three types of dynamic-link libraries with the Microsoft C
  17194. Professional Development System. All of them can be multithreaded; they can
  17195. support more than one client at a time. There are three types:  %@NL@%
  17196. %@NL@%
  17197. %@NL@%
  17198.   ■   A stand-alone dynamic-link library that includes both your routines
  17199.       and code for the Microsoft C run-time library functions used by your
  17200.       DLL. This type of DLL is self-contained and completely independent of
  17201.       the programs that call it.%@NL@%
  17202. %@NL@%
  17203.   ■   A dynamic-link library that does not use any functions from the
  17204.       Microsoft C run-time library. This type of DLL is also self-contained.%@NL@%
  17205. %@NL@%
  17206.   ■   A private dynamic-link library that consists only of selected
  17207.       functions from the Microsoft C run-time library. This DLL is usually
  17208.       specific to one program or a closely tied group of programs.
  17209.       Application programs and dynamic-link libraries using this DLL do not
  17210.       contain any code for the C run-time library functions.%@NL@%
  17211. %@NL@%
  17212. %@NL@%
  17213. The following sections provide more information about the differences
  17214. between the various types of DLLs.  %@NL@%
  17215. %@NL@%
  17216. %@NL@%
  17217. %@4@%%@AB@%Stand-Alone Dynamic-Link Libraries%@AE@%%@EH@%%@NL@%
  17218. %@NL@%
  17219. %@AU@% Stand-alone DLLs include C run-time functions.%@AE@%  %@NL@%
  17220. %@NL@%
  17221. If you want to call C run-time library functions in your DLL, you can
  17222. include the functions you need. These run-time functions are statically
  17223. linked in the DLL and the DLL does not rely on the client or any other DLL
  17224. for run-time support.  %@NL@%
  17225. %@NL@%
  17226. Figure 16.1 illustrates the relationships between this type of DLL, an
  17227. application program, and C run-time library functions. Both the application
  17228. program and the dynamic-link library have their own copies of functions from
  17229. the C run-time library. This ensures that  %@NL@%
  17230. %@NL@%
  17231. %@NL@%
  17232.   ■   The DLL always has access to the C run-time library routines it needs.%@NL@%
  17233. %@NL@%
  17234.   ■   The DLL is not dependent on the calling application for any support
  17235.       code.%@NL@%
  17236. %@NL@%
  17237.   ■   The programs using the DLL do not depend on the DLL for C run-time
  17238.       library functions.%@NL@%
  17239. %@NL@%
  17240. %@NL@%
  17241. Section 16.3.1, "DLLs with Static C Run-Time Library Functions," describes
  17242. the steps involved in creating this type of dynamic-link library using the
  17243. special library LLIBCDLL.LIB.  %@NL@%
  17244. %@NL@%
  17245. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  17246. %@NL@%
  17247. %@NL@%
  17248. %@4@%%@AB@%DLLs without C Run-Time Library Functions%@AE@%%@EH@%%@NL@%
  17249. %@NL@%
  17250. You can write a dynamic-link library in C without calling any functions from
  17251. the C run-time library. Section 16.3.2, "DLLs without C Run-Time Library
  17252. Functions," shows how to set up this type of DLL. These DLLs contain only
  17253. your code and require no run-time library support; they make no calls to
  17254. run-time library functions.  %@NL@%
  17255. %@NL@%
  17256. %@NL@%
  17257. %@4@%%@AB@%Private C Run-Time DLLs%@AE@%%@EH@%%@NL@%
  17258. %@NL@%
  17259. %@AU@% You can create a custom C run-time DLL.%@AE@%  %@NL@%
  17260. %@NL@%
  17261. A C run-time DLL can be shared by multiple programs and their DLLs. You
  17262. generate the C run-time DLL in two steps. The first builds a
  17263. module-definition file with a list of the C run-time library functions
  17264. needed by your application and its DLLs; the second step links the
  17265. module-definition file with the special library CDLLOBJS.LIB to create a C
  17266. run-time DLL.  %@NL@%
  17267. %@NL@%
  17268. The executable files for programs and DLLs linked with a customized C
  17269. run-time DLL do not contain any code for the C run-time library functions.
  17270. Figure 16.2 shows the relationships of the components.  %@NL@%
  17271. %@NL@%
  17272. %@AU@% A private C run-time DLL must be closely tied to its programs and
  17273. %@AU@%associated DLLs.%@AE@%  %@NL@%
  17274. %@NL@%
  17275. Processes and DLLs that share a private run-time DLL share environment
  17276. strings and global C run-time data (for example, file pointers for buffered
  17277. I/O and memory allocated with the %@AB@%malloc%@AE@% function). Therefore, the program
  17278. and the DLLs must cooperate on the use of this data.  %@NL@%
  17279. %@NL@%
  17280. %@AU@%(This figure may be found in the printed book.)%@AE@%%@NL@%
  17281. %@NL@%
  17282. A closely tied structure is suitable for a complex application consisting of
  17283. a set of application programs that act as front-end processors to several
  17284. DLLs. A word processor, for example, might support one user interface for
  17285. beginners, another for intermediate users, and a third for expert users. The
  17286. different user interfaces could be implemented in three separate executable
  17287. program files. All three programs would share the DLLs that do most of the
  17288. real work.  %@NL@%
  17289. %@NL@%
  17290. Section 16.3.3, "Programs and DLLs with a C Run-Time DLL," describes the
  17291. procedures for building a C run-time library DLL and its associated programs
  17292. and dynamic-link libraries.  %@NL@%
  17293. %@NL@%
  17294. %@NL@%
  17295. %@2@%%@CR:C6A00160006 @%%@AB@%16.2  Designing and Writing DLLs%@AE@%%@EH@%%@NL@%
  17296. %@NL@%
  17297. Before you write a DLL, you must determine some of the DLL's requirements.
  17298. You need to know  %@NL@%
  17299. %@NL@%
  17300. %@NL@%
  17301.   ■   Floating-point math requirements%@NL@%
  17302. %@NL@%
  17303.   ■   Special initialization requirements such as allocation of buffers or
  17304.       registration of special termination routines%@NL@%
  17305. %@NL@%
  17306.   ■   Termination requirements such as clearing semaphores or releasing
  17307.       allocated memory%@NL@%
  17308. %@NL@%
  17309.   ■   Re-entrancy requirements; if the DLL is to be called by more than one
  17310.       process, it must be re-entrant%@NL@%
  17311. %@NL@%
  17312. %@NL@%
  17313. This section explains how to design a DLL to take these requirements into
  17314. account.  %@NL@%
  17315. %@NL@%
  17316. %@NL@%
  17317. %@3@%%@CR:C6A00160007 @%%@AB@%16.2.1  Floating-Point Math Requirements%@AE@%%@EH@%%@NL@%
  17318. %@NL@%
  17319. Stand-alone DLLs built with the LLIBCDLL library are independent of the
  17320. programs calling them. They are "black boxes" that must operate without
  17321. knowing anything about their client programs and without interfering with
  17322. their clients.%@CR:C6A00160008 @%  %@NL@%
  17323. %@NL@%
  17324. One area of potential conflict for stand-alone DLLs is control of the 80%@AI@%x%@AE@%87
  17325. math coprocessor. For a DLL to use the 80%@AI@%x%@AE@%87 coprocessor or the emulator
  17326. floating-point library, the DLL and all of its client programs must agree on
  17327. which process is going to handle floating-point exceptions and on which
  17328. process is going to handle emulation if the machine does not have a
  17329. coprocessor.  %@NL@%
  17330. %@NL@%
  17331. Floating-point emulation is not possible with a genuinely independent DLL. A
  17332. stand-alone DLL must use the alternate math library, which ignores the math
  17333. coprocessor chip. The alternate math library provides the fastest processing
  17334. available without a coprocessor, but results are not as accurate as those
  17335. produced by the emulator floating-point library. Because the constraint
  17336. applies only to the DLL and not to applications, clients of a stand-alone
  17337. DLL can use any floating-point model. Since the DLL uses the alternate math
  17338. library, it does not conflict with clients over control of the math
  17339. coprocessor.  %@NL@%
  17340. %@NL@%
  17341. In contrast, DLLs and programs using a private C run-time DLL are tightly
  17342. coupled. This means that the floating-point math option is known when the
  17343. program is built. Because these programs and DLLs all use the same C runtime
  17344. functions (unlike the stand-alone DLL and its clients, which may incorporate
  17345. different C run-time libraries), no contention can arise over control of the
  17346. math coprocessor. The same floating-point math library is used for the
  17347. entire application.  %@NL@%
  17348. %@NL@%
  17349. %@AU@% The only way to use a math coprocessor within a DLL is with a private C
  17350. %@AU@%run-time DLL.%@AE@%  %@NL@%
  17351. %@NL@%
  17352. A private C run-time DLL uses the CDLLOBJS library and the emulator
  17353. floating-point package. The emulator uses the 80%@AI@%x%@AE@%87 math coprocessor if one
  17354. is installed; otherwise, it emulates the coprocessor. Floating-point
  17355. emulation produces the most accurate results. There is no conflict over use
  17356. of the coprocessor, since the C run-time DLL performs all floating-point
  17357. math. The programs and DLLs calling the C run-time DLL do not have any C
  17358. run-time library code of their own.  %@NL@%
  17359. %@NL@%
  17360. %@NL@%
  17361. %@3@%%@CR:C6A00160009 @%%@AB@%16.2.2  Initialization and Termination Requirements%@AE@%%@EH@%%@NL@%
  17362. %@NL@%
  17363. When you design a DLL, you must decide if it has special initialization or
  17364. termination requirements. If the DLL needs to initialize variables or
  17365. allocate memory buffers when it starts, it needs custom start-up procedures.
  17366. If the DLL acquires system resources for a client program, the resources
  17367. must be released when the program completes its processing.  %@NL@%
  17368. %@NL@%
  17369. %@NL@%
  17370. %@4@%%@AB@%Initialization%@AE@%%@EH@%%@NL@%
  17371. %@NL@%
  17372. All DLLs built with the Microsoft C run-time libraries must use per-process
  17373. initialization to set up the C run-time data. Per-process initialization
  17374. (also known as instance initialization) means that OS/2 calls the DLL's
  17375. initialization code each time it loads a program linked with the DLL. For
  17376. most DLLs, the default initialization routine is sufficient, and you do not
  17377. need to take any other measures.  %@NL@%
  17378. %@NL@%
  17379. %@AU@% If your DLL has special requirements, you must provide additional start-up
  17380. %@AU@%processing.%@AE@%  %@NL@%
  17381. %@NL@%
  17382. The C run-time library initialization function is called each time a new
  17383. client is attached to the DLL. To override the default initialization, you
  17384. must link your DLL with one of the following object modules, which are
  17385. provided with the Microsoft C Professional Development System:  %@NL@%
  17386. %@NL@%
  17387. %@AB@%File Name%@AE@%                         %@AB@%Description%@AE@%
  17388. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17389. DLLINIT.OBJ                       Initialization module for DLLs built 
  17390.                                   with LLIBCDLL.LIB and using C run-time 
  17391.                                   library code
  17392.  
  17393. CRTDLL_I.OBJ                      Initialization module for DLLs using a C
  17394.                                   run-time DLL built with CDLLOBJS.LIB 
  17395.                                   (replaces CRTDLL.OBJ)
  17396.  
  17397. In addition, you must declare an entry point for your own DLL initialization
  17398. function. Your function, or the application program calling your DLL, must
  17399. initialize the C run-time data by calling the library function %@AB@%C_INIT%@AE@% before
  17400. any other C run-time library functions are called.  %@NL@%
  17401. %@NL@%
  17402. The prototype for %@AB@%C_INIT%@AE@% is  %@NL@%
  17403. %@NL@%
  17404. %@AS@%  void _far _pascal C_INIT( void );%@AE@%%@NL@%
  17405. %@NL@%
  17406. %@AU@% Designate your initialization function as the DLL's starting point.%@AE@%  %@NL@%
  17407. %@NL@%
  17408. To have your custom function recognized as the DLL's default initialization
  17409. routine, it must be the starting point for the DLL. This requires an
  17410. assembly language file with an %@AB@%END%@AE@% statement naming your function. The
  17411. sample file, SETENTRY.ASM, in the following example shows the minimum
  17412. assembler code required for specifying a C language function named
  17413. %@AB@%SampleInit%@AE@% as the DLL's entry point.  %@NL@%
  17414. %@NL@%
  17415. %@AS@%  ; SETENTRY.ASM
  17416. %@AS@%  extrn _SampleInit:FAR         ;name of C start-up routine
  17417. %@AS@%  end   _SampleInit%@AE@%%@NL@%
  17418. %@NL@%
  17419. The following example, SAMPLE.C, shows a simple custom initialization
  17420. routine that maintains a count of how many clients it is currently serving.
  17421. Since this example overrides the default dynamic-link library
  17422. initialization, it must return a nonzero status code to OS/2 to show a
  17423. successful start-up. If a DLL initialization function returns a status of 0,
  17424. OS/2 will not load the program using the DLL.  %@NL@%
  17425. %@NL@%
  17426. %@AS@%  /*                    SAMPLE.C                    */ 
  17427. %@AS@%  void _far _pascal C_INIT( void ); 
  17428. %@AS@%  int  UserCount = 0;
  17429. %@AS@%  
  17430. %@AS@%  int _export _loadds SampleInit() 
  17431. %@AS@%  {
  17432. %@AS@%      UserCount++;        /* increment number of users  */
  17433. %@AS@%      C_INIT();           /* initialize C run-time data */
  17434. %@AS@%      return( 1 );        /* indicate successful start  */
  17435. %@AS@%  }
  17436. %@AS@%  
  17437. %@AS@%  /* code for other DLL functions belongs here */%@AE@%%@NL@%
  17438. %@NL@%
  17439. All DLLs must be linked with a module-definition file that contains a
  17440. %@AB@%LIBRARY%@AE@% statement, such as the following:  %@NL@%
  17441. %@NL@%
  17442. %@AS@%  LIBRARY SAMPLE INITINSTANCE%@AE@%%@NL@%
  17443. %@NL@%
  17444. The following commands will create object files from the sample files and
  17445. link them with DLLINIT.OBJ to make a stand-alone dynamic-link library  named
  17446. SAMPLE.DLL. The /ML compile option, explained in Section 16.2.6, "Compile
  17447. Options for Dynamic-Link Libraries," sets the library search record to
  17448. LLIBCDLL.LIB.  %@NL@%
  17449. %@NL@%
  17450. %@AS@%  MASM /Mx SETENTRY;
  17451. %@AS@%  CL /c /Gs /ML SAMPLE.C
  17452. %@AS@%  LINK /NOE DLLINIT+SETENTRY+SAMPLE,SAMPLE.DLL,,,SAMPLE.DEF;%@AE@%%@NL@%
  17453. %@NL@%
  17454. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17455. %@AU@%WARNING%@AE@%%@NL@%
  17456. %@NL@%
  17457. For DLLs linked with Microsoft C run-time libraries, the %@AI@%LIBRARY%@AE@% statement
  17458. in the DLL's module-definition file must specify %@AI@%INITINSTANCE %@AE@%in the
  17459. initialization field. If you omit this, the initialization routine is called
  17460. only when the DLL is loaded into memory for the first client program, and
  17461. the DLL will not function properly if it is called by additional programs.%@NL@%
  17462. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17463. %@NL@%
  17464. %@NL@%
  17465. %@4@%%@AB@%Termination%@AE@%%@EH@%%@NL@%
  17466. %@NL@%
  17467. %@AU@% You may have to clean up before terminating.%@AE@%  %@NL@%
  17468. %@NL@%
  17469. You may need to know when an application using your DLL is finished. If your
  17470. DLL has created buffers, semaphores, or other resources for a particular
  17471. application, they must be released when the application terminates.  %@NL@%
  17472. %@NL@%
  17473. You can have an initialization routine in your DLL that calls the OS/2 API
  17474. function %@AB@%DosExitList%@AE@% to register one or more exit subroutines for your DLL.
  17475. OS/2 will call the exit routines when the client program finishes. The exit
  17476. functions should free any resources your DLL acquired for the client
  17477. program.  %@NL@%
  17478. %@NL@%
  17479. %@AU@% DLLs built with LLIBCDLL.LIB have a default termination routine.%@AE@%  %@NL@%
  17480. %@NL@%
  17481. The start-up routine for dynamic-link libraries built with the LLIBCDLL
  17482. library calls %@AB@%DosExitList%@AE@% with a pointer to a default termination function.
  17483. To replace the default processing with your own function, link the module
  17484. DLLTERM.OBJ into the DLL. This suppresses the call to %@AB@%DosExitList%@AE@%. During
  17485. initialization, your DLL must register its own routine by calling
  17486. %@AB@%DosExitList%@AE@% unless you are sure the termination routine will be called
  17487. explicitly. The termination processing must include a call to the library
  17488. function %@AB@%C_TERM%@AE@%.  %@NL@%
  17489. %@NL@%
  17490. The prototype for %@AB@%C_TERM%@AE@% is  %@NL@%
  17491. %@NL@%
  17492. %@AS@%  void _far _pascal C_TERM( void );%@AE@%%@NL@%
  17493. %@NL@%
  17494. There is no equivalent to DLLTERM.OBJ and %@AB@%C_TERM%@AE@% for DLLs using a private C
  17495. run-time DLL built with the CDLLOBJS library. If special cleanup processing
  17496. is required, these DLLs must provide their own termination function. The
  17497. function is registered during initialization by calling either the C
  17498. run-time library function %@AB@%atexit%@AE@% or the OS/2 API function %@AB@%DosExitList%@AE@%.  %@NL@%
  17499. %@NL@%
  17500. %@AU@% Any DLL that calls %@AE@%%@AB@%DosExitList %@AE@%should also have a termination function.  %@NL@%
  17501. %@NL@%
  17502. DLLs that set exit lists must provide termination functions that can be
  17503. called by clients when they no longer need the DLL. If a program attaches
  17504. itself to the DLL at run-time (using %@AB@%DosLoadModule%@AE@%), it cannot disconnect
  17505. from the DLL as long as the exit list points to a function in the
  17506. dynamic-link library. The DLL's termination function can perform any
  17507. necessary cleanup and call %@AB@%DosExitList%@AE@% to remove itself from the exit list.
  17508. %@NL@%
  17509. %@NL@%
  17510. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17511. NOTE
  17512. %@AI@%There is no special termination procedure for DLLs build with CDLLOBJS.LIB
  17513. %@AI@%because the C run-time termination code is called by the %@AB@%exit%@AE@%%@AI@% or %@AE@%%@AI@%%@AB@%_exit%@AE@%%@AE@%%@AI@%
  17514. %@AI@%functions. If the process is terminated by a critical error or %@AE@%%@AI@%%@AB@%DosExit%@AE@%%@AE@%%@AI@%, C
  17515. %@AI@%run-time termination does not occur.%@AE@%%@AE@%%@NL@%
  17516. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  17517. %@NL@%
  17518. %@NL@%
  17519. %@3@%%@CR:C6A00160010 @%%@AB@%16.2.3  Making the DLL Re-Entrant%@AE@%%@EH@%%@NL@%
  17520. %@NL@%
  17521. Re-entrant code is code that can be shared by multiple programs in a
  17522. multitasking environment. DLLs that may be used by more than one program
  17523. must be re-entrant. To do this, they must isolate each client program's data
  17524. and resources. File handles belonging to one client, for example, must not
  17525. be used for other clients. Re-entrancy also means that the DLL cannot allow
  17526. itself to be switched to a different thread while it is performing certain
  17527. operations.  %@NL@%
  17528. %@NL@%
  17529. %@NL@%
  17530. %@4@%%@AB@%Global Versus Instance Data%@AE@%%@EH@%%@NL@%
  17531. %@NL@%
  17532. %@AU@% A dynamic-link library can have separate data segments for each program
  17533. %@AU@%that calls it.%@AE@%  %@NL@%
  17534. %@NL@%
  17535. Separate data segments are known as "instance" data. With instance data
  17536. segments, the DLL does not have to keep track of which resources belong to
  17537. each client. OS/2 assigns a different data segment to each process calling
  17538. the DLL, even though the selectors are the same.  %@NL@%
  17539. %@NL@%
  17540. A dynamic-link library can also have a global data segment used for internal
  17541. purposes or to support all of the programs using its services.  %@NL@%
  17542. %@NL@%
  17543. A DLL providing time and date conversions might, for example, keep the
  17544. current date in a global storage area. The same DLL might provide functions
  17545. to compute elapsed time, such as the number of minutes between two clock
  17546. readings. If static variables are used by the elapsed time functions, they
  17547. should be in instance data segments, since the OS/2 scheduler might preempt
  17548. the function and schedule another thread that calls the same function with
  17549. different arguments before it has completed the first caller's task.  %@NL@%
  17550. %@NL@%
  17551. Data sharing is controlled by %@AB@%DATA%@AE@% and %@AB@%SEGMENTS%@AE@% statements in a dynamic-link
  17552. library's module-definition file. By default, a DLL's automatic data segment
  17553. (the local stack and heap) is shared by all processes calling the DLL. You
  17554. can specify a unique automatic data segment for each client process by
  17555. specifying %@AB@%DATA MULTIPLE%@AE@%.  %@NL@%
  17556. %@NL@%
  17557. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17558. %@AU@%WARNING%@AE@%%@NL@%
  17559. %@NL@%
  17560. DLLs built with the LLIBCDLL or CDLLOBJS C run-time libraries must use %@AI@%DATA
  17561. %@AI@%MULTIPLE%@AE@% in the module-definition file.%@NL@%
  17562. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17563. %@NL@%
  17564. %@AU@% You can use %@AE@%%@AI@%SEGMENTS%@AE@% to specify attributes on a segment-by-segment basis.  %@NL@%
  17565. %@NL@%
  17566. Using the %@AB@%SEGMENTS%@AE@% statement allows you to have both global and per-process
  17567. (instance) data in the same DLL. The C run-time data segment must be
  17568. per-process. The following is an example of a C program fragment and
  17569. moduledefinition file that implement both instance and global data:  %@NL@%
  17570. %@NL@%
  17571. %@AS@%  /* Define static data in the shared segment SHR_SEG */
  17572. %@AS@%  int _based(_segname("SHR_SEG")) intvar;
  17573. %@AS@%  char _based(_segname("SHR_SEG")) charvar;%@AE@%%@NL@%
  17574. %@NL@%
  17575. In the module-definition file, define all data segments as nonshareable,
  17576. then override that default for %@AS@% SHR_SEG %@AE@% as follows:  %@NL@%
  17577. %@NL@%
  17578. %@AS@%  DATA MULTIPLE NONSHARED
  17579. %@AS@%  SEGMENTS
  17580. %@AS@%      SHR_SEG     CLASS   'FAR_DATA'  SHARED%@AE@%%@NL@%
  17581. %@NL@%
  17582. Global data segments are created when OS/2 brings the dynamic-link library
  17583. into memory for its first client process. All of the processes calling the
  17584. DLL share the same global variables.  %@NL@%
  17585. %@NL@%
  17586. %@NL@%
  17587. %@4@%%@AB@%Serializing Nonatomic References%@AE@%%@EH@%%@NL@%
  17588. %@NL@%
  17589. An atomic operation is an operation that can be completed in one machine
  17590. language instruction. When writing a re-entrant procedure (in a multithread
  17591. program or in a DLL), you must ensure that changes to static or global data
  17592. are not preempted by the OS/2 scheduler before the update is complete. To
  17593. prevent this, you must explicitly serialize nonatomic references to static
  17594. or global data. The following code example is safe from preemption, because
  17595. incrementing an integer requires only one machine instruction:  %@NL@%
  17596. %@NL@%
  17597. %@AS@%  int int_var;
  17598. %@AS@%  _export _loadds void _far _pascal dynlink_proc( void ) 
  17599. %@AS@%  {
  17600. %@AS@%     int_var++; 
  17601. %@AS@%  }%@AE@%%@NL@%
  17602. %@NL@%
  17603. The following variation on the same function is not safe because
  17604. incrementing  a %@AB@%long%@AE@% variable is not atomic; it requires two machine
  17605. instructions. Between incrementing the least-significant word and the
  17606. most-significant word, another thread could gain control of the processor.
  17607. If that thread executes code in your DLL that uses %@AS@% long_var%@AE@%, that data
  17608. would be in an indeterminate state.  %@NL@%
  17609. %@NL@%
  17610. %@AS@%  long long_var;
  17611. %@AS@%  _export _loadds void _far _pascal dynlink_proc( void )
  17612. %@AS@%  {
  17613. %@AS@%     long_var++; 
  17614. %@AS@%  }%@AE@%%@NL@%
  17615. %@NL@%
  17616. %@NL@%
  17617. %@4@%%@AB@%Critical Code Sections%@AE@%%@EH@%%@NL@%
  17618. %@NL@%
  17619. A critical code section is a section of code that manipulates a resource
  17620. (such as the long variable in the previous example) while blocking all other
  17621. threads. When your program enters a critical section, it cannot be preempted
  17622. until it performs a %@AB@%DosExitCritSec%@AE@% or until a signal is received. You don't
  17623. usually just alter the value of a variable; you alter it and then use it
  17624. later. In this case, you must isolate the smallest group of operations that
  17625. must occur without interruption. You define these sections with the
  17626. %@AB@%DosEnterCritSec%@AE@% and %@AB@%DosExitCritSec%@AE@% OS/2 API functions, as in the following
  17627. example:  %@NL@%
  17628. %@NL@%
  17629. %@AS@%  _export _loadds void _far _pascal dynlink_proc( void )
  17630. %@AS@%  {   static int_var;%@AE@%%@NL@%
  17631. %@NL@%
  17632. %@AS@%     DosEnterCritSec();
  17633. %@AS@%     int_var += 7;
  17634. %@AS@%     SetLeftCorner( int_var, int_var );
  17635. %@AS@%     DosExitCritSec();%@AE@%%@NL@%
  17636. %@NL@%
  17637. %@AS@%  /* Code that does not reference int_var */
  17638. %@AS@%  }%@AE@%%@NL@%
  17639. %@NL@%
  17640. %@AU@% Keep your critical sections as short as possible.%@AE@%  %@NL@%
  17641. %@NL@%
  17642. While in a critical section, all other threads in the process are blocked
  17643. from execution. Writing extremely long critical sections can make your
  17644. program inefficient and can degrade system performance.  %@NL@%
  17645. %@NL@%
  17646. Although other threads are blocked from execution by %@AB@%DosEnterCritSec%@AE@% and
  17647. %@AB@%DosExitCritSec%@AE@%, these functions do not block signal handling.  %@NL@%
  17648. %@NL@%
  17649. Note that static variables in DLLs are protected from interference from
  17650. other processes if they are in an instance data segment designated as
  17651. %@AB@%MULTIPLE%@AE@% in the %@AB@%DATA%@AE@% statement of the DLL's module-definition file. Memory
  17652. is "owned" by a process and, unless specifically allocated as shareable,
  17653. cannot be altered by any other process.  %@NL@%
  17654. %@NL@%
  17655. %@NL@%
  17656. %@3@%%@CR:C6A00160011 @%%@AB@%16.2.4  Signal Handling%@AE@%%@EH@%%@NL@%
  17657. %@NL@%
  17658. The C library function %@AB@%signal%@AE@% is not supported for multithread programs or
  17659. for DLLs. If you need to process signals, use the OS/2 API signal functions,
  17660. such as %@AB@%DosSetSigHandler%@AE@%.  %@NL@%
  17661. %@NL@%
  17662. See Chapter 15, "Creating Multithread OS/2 Applications," for more
  17663. information about signal handling in OS/2 programs.  %@NL@%
  17664. %@NL@%
  17665. %@NL@%
  17666. %@3@%%@CR:C6A00160012 @%%@AB@%16.2.5  Using Microsoft C Keywords%@AE@%%@EH@%%@NL@%
  17667. %@NL@%
  17668. The %@AB@%_export%@AE@% and %@AB@%_loadds%@AE@% keywords simplify writing DLLs. They are used to
  17669. define or declare functions or pointers to functions. In the DLL, an
  17670. exported function with a single argument might be defined as  %@NL@%
  17671. %@NL@%
  17672. %@AS@%  int _export _loadds sample( int )%@AE@%%@NL@%
  17673. %@NL@%
  17674. %@NL@%
  17675. %@4@%%@AB@%The _export Keyword%@AE@%%@EH@%%@NL@%
  17676. %@NL@%
  17677. %@AU@% All DLL functions that will be called from outside the library must be
  17678. %@AU@%exported.%@AE@%  %@NL@%
  17679. %@NL@%
  17680. The %@AB@%_export%@AE@% keyword gives a function the export attribute. Stack checking
  17681. must be disabled for exported entry points. You can use the /Gs compile
  17682. option or the %@AB@%check_stack%@AE@% pragma to accomplish this.  %@NL@%
  17683. %@NL@%
  17684. Using the %@AB@%_export%@AE@% keyword is an alternative to declaring the name of the
  17685. function in the %@AB@%EXPORTS%@AE@% section of a module-definition file. It assigns
  17686. certain default attributes: no I/O privilege, shared data, load on demand,
  17687. and no alias name. If the defaults are not acceptable, you must specify the
  17688. proper attributes in the module-definition file.  %@NL@%
  17689. %@NL@%
  17690. Not all functions in a DLL are for external use. A DLL can have any number
  17691. of utility subroutines supporting the work of the exported functions.
  17692. Functions that are private to the DLL should not have the %@AB@%_export%@AE@% keyword.  %@NL@%
  17693. %@NL@%
  17694. %@NL@%
  17695. %@4@%%@AB@%The _loadds Keyword%@AE@%%@EH@%%@NL@%
  17696. %@NL@%
  17697. At entry to a DLL, the DS (data segment) register points to the calling
  17698. program's data segment. To access the DLL's data, the DS register has to be
  17699. loaded with the DLL's segment selector. The %@AB@%_loadds%@AE@% keyword causes the
  17700. compiler to add prolog and epilog code to the function. The prolog code
  17701. initializes the DS register to point to the function's data group. The
  17702. epilog code restores the caller's DS register when the function terminates.
  17703. %@NL@%
  17704. %@NL@%
  17705. Since loading the DS register is a high overhead operation, you should limit
  17706. the use of %@AB@%_loadds%@AE@% to the exported functions in your DLL.  %@NL@%
  17707. %@NL@%
  17708. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17709. %@AU@%WARNING%@AE@%%@NL@%
  17710. %@NL@%
  17711. Do not use the %@AB@%_loadds%@AE@% keyword in a function definition if the function uses
  17712. only stack variables. If you specify %@AB@%_loadds%@AE@% in a DLL that does not have any
  17713. static data, the linker will issue a segment fix-up error.%@NL@%
  17714. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17715. %@NL@%
  17716. %@NL@%
  17717. %@3@%%@CR:C6A00160013 @%%@AB@%16.2.6  Compile Options for Dynamic-Link Libraries%@AE@%%@EH@%%@NL@%
  17718. %@NL@%
  17719. Dynamic-link libraries must be compiled with specific options that control
  17720. linking, memory models, and library selection.  %@NL@%
  17721. %@NL@%
  17722. %@NL@%
  17723. %@4@%%@AB@%Compile without Linking (/c)%@AE@%%@EH@%%@NL@%
  17724. %@NL@%
  17725. You must use the /c option to build your DLL in separate compile and link
  17726. steps. This is necessary because the DLL must be linked with a
  17727. module-definition file specifying that the output file is a dynamic-link
  17728. library. (The compiler does not pass module-definition file names to the
  17729. linker.) The /c option is automatically specified in the makefile generated
  17730. by the Programmer's WorkBench.  %@NL@%
  17731. %@NL@%
  17732. %@NL@%
  17733. %@4@%%@AB@%Large Memory Model with Separate Stack (/ALw)%@AE@%%@EH@%%@NL@%
  17734. %@NL@%
  17735. The /ALw option instructs the compiler to use the large memory model with a
  17736. separate stack segment. Because all DLLs use the caller's stack, you must
  17737. use /Aw or /Au. The /Aw option sets up separate stack and data segments but
  17738. does not cause the DS register to be reloaded at the entry to each function.
  17739. This allows you to call private functions (functions that you do not export)
  17740. without incurring the overhead of loading the DS register. Functions that
  17741. you do export must also be declared using the %@AB@%_loadds%@AE@% keyword, described
  17742. above, which sets up the proper DS register handling. If you use the /Au
  17743. option, the DS register will be reloaded on entry to every function, which
  17744. can cause the function calls in your DLLs to execute more slowly.  %@NL@%
  17745. %@NL@%
  17746. All DLL functions are reached using far calls. Pointers passed to and from
  17747. the DLL must be far pointers.  %@NL@%
  17748. %@NL@%
  17749. %@NL@%
  17750. %@4@%%@AB@%Remove Stack Probes (/Gs)%@AE@%%@EH@%%@NL@%
  17751. %@NL@%
  17752. Since the DLL uses the caller's stack, you should usually use the /Gs option
  17753. to disable stack checking within the DLL.  %@NL@%
  17754. %@NL@%
  17755. %@NL@%
  17756. %@4@%%@AB@%Specify 80286 Code (/G2)%@AE@%%@EH@%%@NL@%
  17757. %@NL@%
  17758. Use the /G2 option to designate code generation for the 80286 processor
  17759. instruction set, since OS/2 runs only on 80286 and higher model processors.
  17760. %@NL@%
  17761. %@NL@%
  17762. %@NL@%
  17763. %@4@%%@AB@%Link C Run-Time into Stand-Alone DLL (/ML)%@AE@%%@EH@%%@NL@%
  17764. %@NL@%
  17765. Use the /ML option to build a stand-alone dynamic-link library that includes
  17766. static code for C run-time library functions. This option has the same
  17767. effect as using the /ALw, /FPa, /G2, and /D MT options. It changes the
  17768. library search record to LLIBCDLL.LIB. See Section 16.3.1, "DLLs with Static
  17769. C Run-Time Library Functions" for more information about these options.  %@NL@%
  17770. %@NL@%
  17771. %@NL@%
  17772. %@4@%%@AB@%Link Executable or DLL with C Run-Time DLL (/MD)%@AE@%%@EH@%%@NL@%
  17773. %@NL@%
  17774. Use the /MD option to build an executable file or a dynamic-link library
  17775. that calls a C run-time DLL. This option has the same effect as using the
  17776. /ALw, /FPi, /G2, /D DLL, and /D MT options. It inhibits library search
  17777. records. See Section 16.3.3, "Programs and DLLs with a C Run-Time DLL," for
  17778. more information about these options.  %@NL@%
  17779. %@NL@%
  17780. %@NL@%
  17781. %@4@%%@AB@%Suppress Default Library Selection (/Zl)%@AE@%%@EH@%%@NL@%
  17782. %@NL@%
  17783. If you do not compile with the /MD or /ML options described above, compile
  17784. with the /Zl option or use the /NOD option when you link in order to inhibit
  17785. searches for default libraries.  %@NL@%
  17786. %@NL@%
  17787. %@NL@%
  17788. %@2@%%@CR:C6A00160014 @%%@AB@%16.3  Building DLLs with Microsoft C%@AE@%%@EH@%%@NL@%
  17789. %@NL@%
  17790. %@AU@% Building a DLL for OS/2 is like building an executable program file.%@AE@%  %@NL@%
  17791. %@NL@%
  17792. To build a DLL, compile and link the dynamic-link library like any other
  17793. executable file, but add a module-definition file. This module-definition
  17794. file tells the linker that the output is a dynamic-link library.  %@NL@%
  17795. %@NL@%
  17796. When you build applications that use a dynamic-link library, you must tell
  17797. the linker where to find the library's dynamically linked functions. You use
  17798. import libraries and module-definition files for this purpose.  %@NL@%
  17799. %@NL@%
  17800. %@NL@%
  17801. %@3@%%@CR:C6A00160015 @%%@AB@%16.3.1  DLLs with Static C Run-Time Library Functions%@AE@%%@EH@%%@NL@%
  17802. %@NL@%
  17803. The LLIBCDLL library is used to create stand-alone DLLs. The library
  17804. functions are re-entrant and can be called by multiple threads within a
  17805. program as well as by multiple programs. The code for the stand-alone DLL's
  17806. C run-time library functions is contained within the DLL. Programs that call
  17807. stand-alone DLLs have their own run-time library code.  %@NL@%
  17808. %@NL@%
  17809. %@NL@%
  17810. %@4@%%@AB@%Building the DLL%@AE@%%@EH@%%@NL@%
  17811. %@NL@%
  17812. The files required to build a stand-alone DLL with the LLIBCDLL library are
  17813. listed below:  %@NL@%
  17814. %@NL@%
  17815. %@AB@%File Name%@AE@%                         %@AB@%Description%@AE@%
  17816. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17817. OS2.LIB                           OS/2 kernel import library
  17818.  
  17819. LLIBCDLL.LIB                      Large-model multithread C run-time 
  17820.                                   library for DLLs
  17821.  
  17822. DLLINIT.OBJ                       Optional initialization module for DLLs 
  17823.                                   requiring custom initialization
  17824.  
  17825. DLLTERM.OBJ                       Optional termination module for DLLs 
  17826.                                   requiring custom exit processing
  17827.  
  17828. %@AI@%userdll%@AE@%.C                         Source code for the DLL you create
  17829.  
  17830. %@AI@%userdll%@AE@%.DEF                       Module-definition file for the DLL you 
  17831.                                   create
  17832.  
  17833. The module JUSTIFY.C, below, is an example of source code for a simple
  17834. dynamic-link library. The %@AB@%RightJustify%@AE@% routine calls the %@AB@%strlen%@AE@% function
  17835. from the C run-time library and right-justifies a caller's buffer. The
  17836. function definition includes the %@AB@%_export%@AE@% keyword. The %@AB@%_loadds%@AE@% keyword is
  17837. omitted, since this function does not need any static data. If it did, you
  17838. would need to specify %@AB@%_loadds%@AE@%.  %@NL@%
  17839. %@NL@%
  17840. For simplicity, JUSTIFY.C below shows a DLL with a single function. In
  17841. actual practice, you would usually package a group of similar utilities into
  17842. one DLL.  %@NL@%
  17843. %@NL@%
  17844. %@AS@%  /* JUSTIFY.C -- Sample Dynamic-Link Library */
  17845. %@AS@%  
  17846. %@AS@%  #include <string.h>
  17847. %@AS@%  
  17848. %@AS@%  /* Right justifies the string in TargetBuff to TargetSize
  17849. %@AS@%   * and inserts necessary number of FillChars on the left.
  17850. %@AS@%   */%@AE@%%@NL@%
  17851. %@NL@%
  17852. %@AS@%  #pragma stack_check(off)
  17853. %@AS@%  
  17854. %@AS@%  int _export RightJustify( char *TargetBuff, int TargetSize,
  17855. %@AS@%                            char FillChar)
  17856. %@AS@%  {
  17857. %@AS@%     char *s, *d;
  17858. %@AS@%      s = TargetBuff + strlen( TargetBuff ); 
  17859. %@AS@%     d = TargetBuff + TargetSize;
  17860. %@AS@%     while ( s = TargetBuff )
  17861. %@AS@%         *d-- = *s--;
  17862. %@AS@%     while ( d = TargetBuff )
  17863. %@AS@%         *d-- = FillChar;
  17864. %@AS@%  
  17865. %@AS@%     return( 0 );
  17866. %@AS@%  }%@AE@%%@NL@%
  17867. %@NL@%
  17868. The steps for creating a stand-alone dynamic-link library with JUSTIFY.C are
  17869. given below. The DLL in the example is named JUSTLIB1.DLL.  %@NL@%
  17870. %@NL@%
  17871. %@NL@%
  17872.   ■   Compile with the /ML Option.%@NL@%
  17873. %@NL@%
  17874. %@STUB@%      Compile the source file without linking. Dynamic-link libraries linked
  17875.       with LLIBCDLL must be compiled with specific options.%@NL@%
  17876. %@NL@%
  17877. %@STUB@%      Use the /ML option to set the library search record to LLIBCDLL.LIB
  17878.       and to indicate that C run-time code is to be included in the DLL.
  17879.       When you use /ML, the following options take effect:%@NL@%
  17880. %@NL@%
  17881. %@AB@%Option%@AE@%                            %@AB@%Effect%@AE@%
  17882. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17883. %@NL@%
  17884. /ALw                              Use large memory model with separate 
  17885.                                   stack
  17886.                                   segment
  17887.  
  17888. /G2                               Use 80286 processor instruction set
  17889.  
  17890. /D MT                             Use the multithread version of the 
  17891.                                   include files
  17892.  
  17893. /FPa                              Generate floating-point calls and select
  17894.                                   the alternate math library
  17895.  
  17896. The /G2 and the /ALw options can be overridden.%@NL@%
  17897. %@NL@%
  17898. %@STUB@%      You should also use the /Gs option to suppress stack checking and the
  17899.       /c option to compile without linking. The complete command to compile
  17900.       the sample file JUSTIFY.C is%@NL@%
  17901. %@NL@%
  17902. %@AS@%      CL /ML /Gs /c JUSTIFY.C%@AE@%%@NL@%
  17903. %@NL@%
  17904.   ■   Create a module-definition file.%@NL@%
  17905. %@NL@%
  17906. %@STUB@%      Create a module-definition file, JUSTLIB1.DEF, which includes the
  17907.       following lines:%@NL@%
  17908. %@NL@%
  17909. %@AS@%      LIBRARY JUSTLIB1 INITINSTANCE
  17910. %@AS@%      DATA MULTIPLE%@AE@%%@NL@%
  17911. %@NL@%
  17912. %@STUB@%      The %@AB@%LIBRARY%@AE@% statement identifies the executable file, JUSTLIB1.DLL, as
  17913.       a dynamic-link library. DLLs linked with the LLIBCDLL library must
  17914.       specify %@AB@%INITINSTANCE%@AE@% in the initialization field. You could add an
  17915.       %@AB@%EXPORTS%@AE@% statement for the %@AB@%RightJustify%@AE@% function in JUSTIFY.C, but it
  17916.       is optional since the %@AB@%_export%@AE@% keyword was used in the source code.%@NL@%
  17917. %@NL@%
  17918. %@STUB@%      See Chapter 14, "Building OS/2 Applications," for more information
  17919.       about module-definition files.%@NL@%
  17920. %@NL@%
  17921.   ■   Link with LLIBCDLL.LIB.%@NL@%
  17922. %@NL@%
  17923. %@STUB@%      Ensure that the file LLIBCDLL.LIB, which takes the place of the
  17924.       regular C run-time library, is available.%@NL@%
  17925. %@NL@%
  17926. %@STUB@%      Create JUSTLIB1.DLL with a command such as%@NL@%
  17927. %@NL@%
  17928. %@AS@%      LINK justify,justlib1.dll,,,justlib1.def/NOI%@AE@%%@NL@%
  17929. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17930. %@AU@%WARNING%@AE@%%@NL@%
  17931. %@NL@%
  17932. When you link with LLIBCDLL, you cannot have any other C run-time libraries
  17933. in the link.%@NL@%
  17934. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17935. %@NL@%
  17936. %@NL@%
  17937.   ■   Create an import library.%@NL@%
  17938. %@NL@%
  17939. %@STUB@%      Applications that call DLLs use import libraries to identify DLL
  17940.       functions to the linker. The following example uses JUSTLIB1.DLL and
  17941.       the IMPLIB utility to create an import library named JUSTLIB1.LIB.%@NL@%
  17942. %@NL@%
  17943. %@AS@%      IMPLIB justlib1.lib justlib1.dll%@AE@%%@NL@%
  17944. %@NL@%
  17945. %@STUB@%      For more information about import libraries, see Chapter 14, "Building
  17946.       OS/2 Applications."%@NL@%
  17947. %@NL@%
  17948. %@NL@%
  17949. %@NL@%
  17950. %@4@%%@AB@%Building Programs that Call the DLL%@AE@%%@EH@%%@NL@%
  17951. %@NL@%
  17952. To link a dynamic-link library with an application, you must have one of the
  17953. following:  %@NL@%
  17954. %@NL@%
  17955. %@NL@%
  17956.   ■   A module-definition file with an %@AB@%IMPORTS%@AE@% statement for each DLL
  17957.       function called by your program%@NL@%
  17958. %@NL@%
  17959.   ■   An import library created from the DLL itself or from a
  17960.       module-definition file%@NL@%
  17961. %@NL@%
  17962. %@NL@%
  17963. All calls to DLLs must be far calls; all pointers passed must be far data
  17964. pointers. If you do not compile with the large memory model option (/AL),
  17965. you must cast the DLL function calls and pointers yourself.  %@NL@%
  17966. %@NL@%
  17967. The sample file below, TESTJUST.C, is compiled and linked into a small-model
  17968. program named SAMPLE1.EXE. TESTJUST.C includes a function prototype that
  17969. declares %@AB@%RightJustify%@AE@% as a far function expecting a far pointer as its first
  17970. argument. Because of the prototype, the compiler will generate a far call to
  17971. %@AB@%RightJustify%@AE@% and coerce the pointer argument to the proper value.  %@NL@%
  17972. %@NL@%
  17973. %@AS@%  /* TESTJUST.C. Call sample DLL library */%@AE@%%@NL@%
  17974. %@NL@%
  17975. %@AS@%  #include <stdio.h>
  17976. %@AS@%  #include <string.h>%@AE@%%@NL@%
  17977. %@NL@%
  17978. %@AS@%  /* DLL function prototype */
  17979. %@AS@%  
  17980. %@AS@%  int _far RightJustify( char _far *, int, char );
  17981. %@AS@%  
  17982. %@AS@%  void main( void )
  17983. %@AS@%  {
  17984. %@AS@%      char buff[12];
  17985. %@AS@%  
  17986. %@AS@%      strcpy( buff, "ABCD" );
  17987. %@AS@%  
  17988. %@AS@%      /* Right justify to 8 characters and zero fill. */
  17989. %@AS@%      RightJustify( buff, 8, '0' );
  17990. %@AS@%      printf( "Result: %s\n", buff );
  17991. %@AS@%  }%@AE@%%@NL@%
  17992. %@NL@%
  17993. You need several files to link an application with a stand-alone DLL:  %@NL@%
  17994. %@NL@%
  17995. %@AB@%File Name%@AE@%                         %@AB@%Description%@AE@%
  17996. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17997. %@AI@%userdll%@AE@%.LIB                       Import library file for the DLL
  17998.  
  17999. %@AI@%userapp%@AE@%.DEF                       Optional module-definition file for your
  18000.                                   application that contains an %@AB@%IMPORTS%@AE@% 
  18001.                                   statement for each DLL function called 
  18002.                                   (required if not using an import
  18003.                                   library)
  18004.  
  18005. OS2.LIB                           Optional import library file for the 
  18006.                                   OS/2 kernel (required if your 
  18007.                                   application calls the kernel directly or
  18008.                                   via a C run-time library function)
  18009.  
  18010. %@AI@%userapp%@AE@%.OBJ                       Object module(s) for your application
  18011.  
  18012. %@AI@%m%@AE@%LIBC %@AI@%f%@AE@% P.LIB                     Regular C run-time library for protected
  18013.                                   mode, where %@AI@%m%@AE@% indicates memory model (S,
  18014.                                   C, M, L) and%@AI@%%@AE@%
  18015.                                   %@AI@%f%@AE@% indicates math package (A, E, 7)
  18016.  
  18017. The following command lines illustrate how TESTJUST.C can be compiled  and
  18018. linked with the standard libraries, plus the sample dynamic-link library,
  18019. JUSTLIB1.DLL. The example uses the small memory model library and the
  18020. JUSTLIB1.LIB import library created from JUSTLIB1.DLL to create SAMPLE1.EXE.
  18021. %@NL@%
  18022. %@NL@%
  18023. %@AS@%  CL /AS /G2 /c TESTJUST.C
  18024. %@AS@%  LINK TESTJUST,SAMPLE1.EXE,,JUSTLIB1;%@AE@%%@NL@%
  18025. %@NL@%
  18026. Make sure that the JUSTLIB1.DLL file is in a directory on your LIBPATH
  18027. before executing SAMPLE1.EXE.  %@NL@%
  18028. %@NL@%
  18029. %@NL@%
  18030. %@3@%%@CR:C6A00160016 @%%@AB@%16.3.2  DLLs without C Run-Time Library Functions%@AE@%%@EH@%%@NL@%
  18031. %@NL@%
  18032. Building a DLL that does not call any of the C run-time library functions is
  18033. similar to creating a stand-alone DLL.  %@NL@%
  18034. %@NL@%
  18035. To use the JUSTIFY.C sample program shown in Section 16.3.1, "DLLs with
  18036. Static C Run-Time Library Functions," without calling C run-time functions,
  18037. one change must be made. You must remove the call to the C run-time library
  18038. function %@AB@%strlen%@AE@%. The %@AB@%strlen%@AE@% function was used in the sample program to
  18039. calculate a pointer to the end of the caller's buffer. Remove the following
  18040. line in the program JUSTIFY.C:  %@NL@%
  18041. %@NL@%
  18042. %@AS@%  s = TargetBuff + strlen( TargetBuff ); %@AE@%%@NL@%
  18043. %@NL@%
  18044. Replace the line above with the following code fragment, which does the same
  18045. thing without calling %@AB@%strlen%@AE@%:  %@NL@%
  18046. %@NL@%
  18047. %@AS@%  s = TargetBuff;
  18048. %@AS@%  while ( *s )
  18049. %@AS@%     s++;%@AE@%%@NL@%
  18050. %@NL@%
  18051. After making this change, you can use the following commands to create a DLL
  18052. named JUSTLIB2.DLL and its import library:  %@NL@%
  18053. %@NL@%
  18054. %@AS@%  CL /c /ALw /G2s /Zl JUSTIFY.C
  18055. %@AS@%  LINK JUSTIFY,JUSTLIB2.DLL,,,JUSTLIB2.DEF/NOI
  18056. %@AS@%  IMPLIB JUSTLIB2.LIB JUSTLIB2.DLL%@AE@%%@NL@%
  18057. %@NL@%
  18058. Note that object modules compiled with releases of Microsoft C prior to
  18059. Version 6.0 refer to the C run-time library variable %@AB@%_acrtused%@AE@%. C 6.0
  18060. defines this variable if the %@AB@%main%@AE@% function is present. This causes the
  18061. linker to automatically add the C run-time start-up module to the DLL. To
  18062. suppress the start-up module, your source file must include a line defining
  18063. %@AB@%_acrtused%@AE@% as follows:  %@NL@%
  18064. %@NL@%
  18065. %@AS@%  int _acrtused = 0;%@AE@%%@NL@%
  18066. %@NL@%
  18067. This is required only if you do not use a C run-time library and if the link
  18068. includes object modules built with earlier versions of the compiler.  %@NL@%
  18069. %@NL@%
  18070. %@NL@%
  18071. %@3@%%@CR:C6A00160017 @%%@AB@%16.3.3  Programs and DLLs with a C Run-Time DLL%@AE@%%@EH@%%@NL@%
  18072. %@NL@%
  18073. The CDLLOBJS.LIB and CDLLOBJS.DEF files are the foundation for building a
  18074. DLL that consists only of C run-time library functions. The application
  18075. programs and optional dynamic-link libraries linked with this DLL do not
  18076. contain any C run-time library code.  %@NL@%
  18077. %@NL@%
  18078. You create an application to use the C run-time DLL in either two or three
  18079. phases, depending on whether or not the application has additional DLLs:  %@NL@%
  18080. %@NL@%
  18081. %@NL@%
  18082.   ■   Build a C run-time DLL.%@NL@%
  18083. %@NL@%
  18084.   ■   Build any optional DLLs that use the C run-time DLL.%@NL@%
  18085. %@NL@%
  18086.   ■   Compile and link the application.%@NL@%
  18087. %@NL@%
  18088. %@NL@%
  18089. The examples in this section use the JUSTIFY.C and TESTJUST.C source files
  18090. shown in Section 16.3.1, "DLLs with Static C Run-Time Library Functions."  %@NL@%
  18091. %@NL@%
  18092. %@NL@%
  18093. %@4@%%@AB@%Building a C Run-Time DLL%@AE@%%@EH@%%@NL@%
  18094. %@NL@%
  18095. The C run-time DLL is derived from the CDLLOBJS.LIB and CDLLOBJS.DEF files
  18096. provided with the Microsoft C Professional Development System. The
  18097. CDLLOBJS.DEF file includes export definitions for all of the C run-time
  18098. library functions.  %@NL@%
  18099. %@NL@%
  18100. The steps for creating a C run-time DLL are given below. The C run-time DLL
  18101. in the example is named CEXAMPLE.DLL.  %@NL@%
  18102. %@NL@%
  18103. %@NL@%
  18104.   1.  Create a module-definition file.%@NL@%
  18105. %@NL@%
  18106. %@STUB@%      You can use CDLLOBJS.DEF as the basis for your own module-definition
  18107.       file by copying and editing it. This allows you to create a customized
  18108.       DLL that contains only the functions your application requires. If you
  18109.       use the CDLLOBJS.DEF file without modification, every program that
  18110.       links to your C run-time DLL will get the entire C run-time library.%@NL@%
  18111. %@NL@%
  18112. %@STUB@%      The following examples create the sample file CEXAMPLE.DEF to define
  18113.       the custom dynamic link library CEXAMPLE.DLL. The CEXAMPLE.DEF file,
  18114.       shown below, exports the three C run-time library functions called
  18115.       from JUSTIFY.C and TESTJUST.C. It also exports functions required by
  18116.       the C run-time library start-up modules.%@NL@%
  18117. %@NL@%
  18118. %@AS@%      LIBRARY CEXAMPLE INITINSTANCE
  18119. %@AS@%      DESCRIPTION 'Sample Dynamic-link C Run-Time Library'
  18120. %@AS@%      DATA MULTIPLE
  18121. %@AS@%      PROTMODE
  18122. %@AS@%      EXPORTS
  18123. %@AS@%             _printf
  18124. %@AS@%             _strlen
  18125. %@AS@%             _strcpy
  18126. %@AS@%             __CRT_INIT
  18127. %@AS@%             __aFchkstk
  18128. %@AS@%             _exit%@AE@%%@NL@%
  18129. %@NL@%
  18130.   2.  Create the C run-time DLL.%@NL@%
  18131. %@NL@%
  18132. %@STUB@%      The files for creating a C run-time DLL are listed below:%@NL@%
  18133. %@NL@%
  18134. %@AB@%File Name%@AE@%                         %@AB@%Description%@AE@%
  18135. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18136. %@NL@%
  18137. OS2.LIB                           Import library for the OS/2 kernel
  18138.  
  18139. CDLLOBJS.LIB                      Dynamic link C run-time library
  18140.  
  18141. CRTLIB.OBJ                        Start-up code for C run-time DLL
  18142.  
  18143. %@AI@%yourclib%@AE@%.DEF                      Module-definition file specifying C 
  18144.                                   run-time library functions for the DLL
  18145.  
  18146. The command to create the sample CEXAMPLE.DLL file is%@NL@%
  18147. %@NL@%
  18148. %@AS@%      
  18149. %@AS@%      LINK /NOD /NOE /NOI crtlib.obj,cexample.dll,,cdllobjs+os2,cexample.def%@AE@%%@NL@%
  18150. %@NL@%
  18151.   3.  Create an import library.%@NL@%
  18152. %@NL@%
  18153. %@STUB@%      You need to create a library file of import definitions that can be
  18154.       used by programs that will be linked with your custom DLL. This is a
  18155.       two-step process. The first phase uses the module-definition file and
  18156.       the IMPLIB utility to create an interim version of the library, as in
  18157.       this example:%@NL@%
  18158. %@NL@%
  18159. %@AS@%      IMPLIB cexample.lib cexample.def%@AE@%%@NL@%
  18160. %@NL@%
  18161. %@STUB@%      Note that the IMPLIB utility accepts either a module-definition file
  18162.       or a DLL as input.%@NL@%
  18163. %@NL@%
  18164. %@STUB@%      The second step uses the LIB utility to append the file CDLLSUPP.LIB
  18165.       to the import library. You must append CDLLSUPP.LIB because it
  18166.       contains some routines that cannot be dynamically linked. The LIB
  18167.       utility requires the full path name for CDLLSUPP.LIB. If it is in a
  18168.       directory named C:\ LIB, the command to complete the library build for
  18169.       CEXAMPLE.LIB is%@NL@%
  18170. %@NL@%
  18171. %@AS@%      LIB CEXAMPLE.LIB+C:\LIB\CDLLSUPP.LIB;%@AE@%%@NL@%
  18172. %@NL@%
  18173. %@STUB@%      When you have finished building the custom DLL, be sure to copy it to
  18174.       a directory specified in the %@AB@%LIBPATH%@AE@% statement of the CONFIG.SYS file.%@NL@%
  18175. %@NL@%
  18176. %@NL@%
  18177. %@NL@%
  18178. %@4@%%@AB@%Building an Application-Specific DLL%@AE@%%@EH@%%@NL@%
  18179. %@NL@%
  18180. You must compile a DLL that calls a C run-time DLL with specific options
  18181. and link it with the C run-time DLL's import library. The steps for building
  18182. an application-specific DLL named JUSTLIB3.DLL are given below.  %@NL@%
  18183. %@NL@%
  18184. %@NL@%
  18185.   1.  Compile with the /MD option.%@NL@%
  18186. %@NL@%
  18187. %@STUB@%      The easiest way to be sure you choose the proper options is to use the
  18188.       /MD switch, which indicates that the DLL will be used with a C
  18189.       run-time DLL. When you use /MD, library search records are suppressed
  18190.       and the following options are in effect:%@NL@%
  18191. %@NL@%
  18192. %@AB@%Option%@AE@%                            %@AB@%Effect%@AE@%
  18193. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18194. %@NL@%
  18195. /ALw                              Use large memory model with separate 
  18196.                                   stack
  18197.                                   segment
  18198.  
  18199. /G2                               Use 80286 processor instruction set
  18200.  
  18201. /D MT                             Use the multithread version of the 
  18202.                                   include files
  18203.  
  18204. /D DLL                            Use a C run-time dynamic-link library
  18205.  
  18206. /FPi                              Generate in-line floating-point 
  18207.                                   instructions and select the emulator 
  18208.                                   math package
  18209.  
  18210. The /G2 and /ALw options can be overridden. The FPi option can be replaced
  18211. with /FPi87 or /FPc, but not with /FPa. See Chapter 4, "Controlling
  18212. Floating-Point Math Operations," for more information about compatible
  18213. floating-point options.%@NL@%
  18214. %@NL@%
  18215. %@STUB@%      You should also use the /c option to compile without linking. The
  18216.       command line to compile the sample file JUSTIFY.C is%@NL@%
  18217. %@NL@%
  18218. %@AS@%      CL /MD /c JUSTIFY.C%@AE@%%@NL@%
  18219. %@NL@%
  18220.   2.  Create a module-definition file.%@NL@%
  18221. %@NL@%
  18222. %@STUB@%      Create a module-definition file named JUSTLIB3.DEF that includes the
  18223.       following line:%@NL@%
  18224. %@NL@%
  18225. %@AS@%      LIBRARY JUSTLIB3 INITINSTANCE%@AE@%%@NL@%
  18226. %@NL@%
  18227.   3.  Link the DLL with the C run-time and OS/2 import libraries.%@NL@%
  18228. %@NL@%
  18229. %@STUB@%      To create a DLL that will call a C run-time DLL, the following files
  18230.       must be linked together:%@NL@%
  18231. %@NL@%
  18232. %@AB@%File Name%@AE@%                         %@AB@%Description%@AE@%
  18233. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18234. %@NL@%
  18235. OS2.LIB                           Import library for the OS/2 kernel
  18236.  
  18237. %@AI@%yourclib%@AE@%.LIB                      Import library for your C run-time DLL
  18238.  
  18239. CRTDLL.OBJ                        Start-up code for DLLs using a C 
  18240.                                   run-time DLL
  18241.  
  18242. CRTDLL_I.OBJ                      Optional initialization module for DLLs 
  18243.                                   requiring custom initialization 
  18244.                                   (replaces CRTDLL.OBJ)
  18245.  
  18246. %@AI@%yourdll%@AE@%.OBJ                       Object file for your DLL
  18247.  
  18248. %@AI@%yourdll%@AE@%.DEF                       Module-definition file for your DLL
  18249.  
  18250. The command for linking these files to create JUSTLIB3.DLL is%@NL@%
  18251. %@NL@%
  18252. %@AS@%      
  18253. %@AS@%      LINK justify+crtdll,justlib3.dll,,cexample+os2,justlib3.def%@AE@%%@NL@%
  18254. %@NL@%
  18255.   4.  Create an import library.%@NL@%
  18256. %@NL@%
  18257. %@STUB@%      Use JUSTLIB3.DLL and the IMPLIB utility to create an import library
  18258.       file, JUSTLIB3.LIB, for use by applications calling JUSTLIB3.DLL:%@NL@%
  18259. %@NL@%
  18260. %@AS@%      IMPLIB JUSTLIB3.LIB JUSTLIB3.DLL%@AE@%%@NL@%
  18261. %@NL@%
  18262. %@STUB@%      Remember to copy JUSTLIB3.DLL to a directory named in the %@AB@%LIBPATH%@AE@%
  18263.       statement in the CONFIG.SYS file.%@NL@%
  18264. %@NL@%
  18265. %@NL@%
  18266. %@NL@%
  18267. %@4@%%@AB@%Using C Run-Time and Application-Specific DLLs%@AE@%%@EH@%%@NL@%
  18268. %@NL@%
  18269. Application programs using a C run-time DLL, such as the sample program
  18270. CEXAMPLE.DLL (described earilier in this section), must define the symbolic
  18271. constants %@AB@%MT%@AE@% and %@AB@%DLL%@AE@%. These constants cause the compiler to use the
  18272. multithread and DLL sections of the include files. You can define the
  18273. constants in your source code or with the compiler's /D command-line option.
  18274. Since the C run-time DLL uses the large memory model, your program must
  18275. either use the same model or declare all C run-time functions and pointers
  18276. passed to them as %@AB@%_far%@AE@%. If you use the standard include files for the C
  18277. run-time functions in your program, all these declarations are made for you.
  18278. %@NL@%
  18279. %@NL@%
  18280. The following files are required to link an application that calls a C
  18281. runtime DLL:  %@NL@%
  18282. %@NL@%
  18283. %@AB@%File Name%@AE@%                         %@AB@%Description%@AE@%
  18284. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18285. OS2.LIB                           Import library for the OS/2 kernel
  18286.  
  18287. %@AI@%yourclib%@AE@%.LIB                      Import library for your C run-time DLL
  18288.  
  18289. %@AI@%yourdll%@AE@%.LIB                       Import library for each optional 
  18290.                                   application DLL
  18291.  
  18292. CRTEXE.OBJ                        Start-up code for executable files 
  18293.                                   calling a C run-time DLL
  18294.  
  18295. %@AI@%yourapp%@AE@%.OBJ                       Object file(s) for your application
  18296.  
  18297. %@AI@%yourapp%@AE@%.DEF                       Optional module-definition file for your
  18298.                                   application
  18299.  
  18300. The following commands compile and link the TESTJUST.C file from Section
  18301. 16.3.1 for use with the dynamic-link libraries CEXAMPLE.DLL and
  18302. JUSTLIB3.DLL. The link command uses the /NOD option to suppress selection of
  18303. the standard large-model library. The result is a program named SAMPLE2.EXE.
  18304. %@NL@%
  18305. %@NL@%
  18306. %@AS@%  CL /AL /D MT /D DLL /G2 /c TESTJUST.C
  18307. %@AS@%  LINK /NOD TESTJUST+CRTEXE,SAMPLE2.EXE,,CEXAMPLE+OS2+JUSTLIB3;%@AE@%%@NL@%
  18308. %@NL@%
  18309. %@NL@%
  18310. %@3@%%@CR:C6A00160018 @%%@AB@%16.3.4  Using CodeView to Debug Dynamic-Link Libraries%@AE@%%@EH@%%@NL@%
  18311. %@NL@%
  18312. The protected-mode version of CodeView (CVP) supports debugging of
  18313. dynamic-link libraries. The /L option lets you name one or more DLLs to be
  18314. debugged with your application.  %@NL@%
  18315. %@NL@%
  18316. To enable full symbolic debugging, use the CodeView options /Zi when
  18317. compiling and /CO when linking. Do this for both the DLL to be debugged and
  18318. for the program that calls the DLL.  %@NL@%
  18319. %@NL@%
  18320. The syntax for the /L CodeView option is  %@NL@%
  18321. %@NL@%
  18322. %@AS@%  /L file%@AE@%%@NL@%
  18323. %@NL@%
  18324. At least one space must separate /L from the file name(s). You can enter
  18325. multiple DLL names. To debug the JUSTLIB3.DLL dynamic-link library and the
  18326. SAMPLE2.EXE program discussed in the previous section, use this command
  18327. line:%@CR:C6A00160019 @%  %@NL@%
  18328. %@NL@%
  18329. %@AS@%  CVP /L JUSTLIB3.DLL SAMPLE2.EXE%@AE@%%@NL@%
  18330. %@NL@%
  18331. %@AU@% Use the CodeView Trace com%@AE@%%@AB@%mand (F8) to enter an%@AE@%d view DLL code.  %@NL@%
  18332. %@NL@%
  18333. A simple way to use CodeView is to place a breakpoint at the instruction
  18334. that calls the DLL function you want to debug. When you reach the
  18335. breakpoint, press F8 to execute the current source line. CodeView will then
  18336. display the DLL function's source code, allowing you to set additional
  18337. breakpoints and enter other CodeView commands.  %@NL@%
  18338. %@NL@%
  18339. %@NL@%
  18340. %@NL@%
  18341. %@NL@%
  18342. %@NL@%
  18343. %@NL@%
  18344. %@CR:C6A-A0001   @%%@1@%%@AB@%Appendix A  Using Exit Codes%@AE@%%@EH@%%@NL@%
  18345. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18346. %@NL@%
  18347. When C programs terminate, they return values to the process that started
  18348. them. These values are called "exit codes." The process that starts a C
  18349. program can be either an operating system, such as DOS or OS/2, or another
  18350. program. The process that starts the C program is referred to as the "parent
  18351. process"; the program started is referred to as the "child process." The
  18352. parent process can interpret return values as an error code sent to the
  18353. operating system or use those return values as a form of interprocess
  18354. communication (communication between two separate processes).%@CR:C6A-A0002   @%  %@NL@%
  18355. %@NL@%
  18356. %@NL@%
  18357. %@2@%%@CR:C6A-A0003   @%%@AB@%A.1  The exit Function%@AE@%%@EH@%%@NL@%
  18358. %@NL@%
  18359. The %@AB@%exit%@AE@% function terminates execution of your C program and returns an exit
  18360. code (an integer value) to the parent process. The parent process can be the
  18361. operating system or another program, depending on how the child process was
  18362. executed. Note that a C program always returns an integer, regardless of how
  18363. you declare the %@AB@%main%@AE@% function.  %@NL@%
  18364. %@NL@%
  18365. Most programs use exit codes to communicate errors to the parent process;
  18366. these are called "error codes." By convention, programs return zero if they
  18367. complete normally and a nonzero value if they are exiting because of an
  18368. error. This error code (the nonzero value) can then be used by the operating
  18369. system to control the execution of other programs (for example, from inside
  18370. a batch file).  %@NL@%
  18371. %@NL@%
  18372. The Microsoft C compiler is a good example of a program that returns an exit
  18373. code. It returns 0 if no errors occur in your compile and a positive value
  18374. if an error occurs during compilation.  %@NL@%
  18375. %@NL@%
  18376. The following program attempts to open a file for reading. If the file
  18377. cannot be opened, %@AB@%exit%@AE@% returns 1 to the calling program. Therefore, 1 and 0
  18378. are both exit codes.  %@NL@%
  18379. %@NL@%
  18380. %@AS@%  #include <stdio.h>
  18381. %@AS@%  
  18382. %@AS@%  int main(void)
  18383. %@AS@%  {
  18384. %@AS@%     FILE * fp;
  18385. %@AS@%  
  18386. %@AS@%     if( !(fp = fopen( filename, "rb" )) )
  18387. %@AS@%     {
  18388. %@AS@%         printf("Error %d: Could not open file\n", errno);
  18389. %@AS@%         exit(1);
  18390. %@AS@%     }
  18391. %@AS@%  
  18392. %@AS@%     do_file_access(fp);
  18393. %@AS@%  }%@AE@%%@NL@%
  18394. %@NL@%
  18395. In the preceding example, the exit code is unpredictable because the %@AB@%exit
  18396. %@AB@%%@AE@%function is not used. The value actually returned to the parent process (or
  18397. to the operating system shell) is whatever happens to be in the AX register
  18398. when the program terminates─in this case, whatever %@AS@% do_file_access %@AE@%
  18399. returned.  %@NL@%
  18400. %@NL@%
  18401. %@NL@%
  18402. %@2@%%@CR:C6A-A0004   @%%@AB@%A.2  Testing Exit Codes from Command and Batch Files%@AE@%%@EH@%%@NL@%
  18403. %@NL@%
  18404. Using the IF ERRORLEVEL command, you can test to see if a program has
  18405. executed successfully by checking its exit code. The IF ERRORLEVEL command
  18406. is an OS/2 command file or DOS batch file command that tests the exit code
  18407. of the most recently executed program.  %@NL@%
  18408. %@NL@%
  18409. IF ERRORLEVEL can help you organize program execution. For example, you can
  18410. define program execution to be dependent on the successful exit code testing
  18411. of earlier programs by IF ERRORLEVEL. You can also use the value of the exit
  18412. code to branch to different commands in a batch or command file.  %@NL@%
  18413. %@NL@%
  18414. When placed in a batch or command file, the following commands will execute
  18415. REPORTS.EXE only if FILEMNG.EXE does not return an error:  %@NL@%
  18416. %@NL@%
  18417. %@AS@%  echo Running file manager....
  18418. %@AS@%  FILEMNG.EXE
  18419. %@AS@%  IF NOT ERRORLEVEL 1 REPORTS.EXE%@AE@%%@NL@%
  18420. %@NL@%
  18421. Despite the name %@AS@% ERRORLEVEL%@AE@%, the exit code does not always denote an error.
  18422. You can define error codes to communicate any information useful to you.  %@NL@%
  18423. %@NL@%
  18424. Refer to the %@AI@%Microsoft Operating System/2 User's Guide%@AE@% or the %@AI@%Microsoft
  18425. %@AI@%MS-DOS User's Guide and User's Reference %@AE@%for more information about the IF
  18426. ERRORLEVEL command.  %@NL@%
  18427. %@NL@%
  18428. %@NL@%
  18429. %@2@%%@CR:C6A-A0005   @%%@AB@%A.3  Accessing Exit Codes from Other Programs%@AE@%%@EH@%%@NL@%
  18430. %@NL@%
  18431. When you use any of the %@AB@%spawn%@AE@% family of functions to run a program as the
  18432. child of another program, the return value of %@AB@%spawn %@AE@%is the exit code of the
  18433. function. The following code performs the same function as the batch file in
  18434. Section A.2:  %@NL@%
  18435. %@NL@%
  18436. %@AS@%  void main( void )
  18437. %@AS@%  {
  18438. %@AS@%     if( !spawnl( P_WAIT, "filemng.exe", "filemng.exe", 
  18439. %@AS@%                   NULL ) )
  18440. %@AS@%         spawnl( P_WAIT, "reports.exe", "reports.exe", 
  18441. %@AS@%                  NULL );
  18442. %@AS@%  }%@AE@%%@NL@%
  18443. %@NL@%
  18444. The program %@AS@% reports.exe %@AE@% is executed only if the program %@AS@% filemng.exe
  18445. %@AS@%%@AE@%terminates with an exit code of 0.  %@NL@%
  18446. %@NL@%
  18447. The following code uses the exit code as part of a simple menu system:  %@NL@%
  18448. %@NL@%
  18449. %@AS@%  void main(void)
  18450. %@AS@%  {
  18451. %@AS@%     int option;
  18452. %@AS@%     int menu_num = 0;  /* Initialize for first execution */
  18453. %@AS@%  
  18454. %@AS@%     while( (option = spawnl( P_WAIT, "menu.exe",
  18455. %@AS@%                          "menu.exe", menu_num, NULL )) )
  18456. %@AS@%      {
  18457. %@AS@%          switch( option )
  18458. %@AS@%          {
  18459. %@AS@%              case 1 :
  18460. %@AS@%                  menu_num = spawnl( P_WAIT, "program1.exe",
  18461. %@AS@%                                "program1.exe", NULL );
  18462. %@AS@%                  break;
  18463. %@AS@%              case 2 :
  18464. %@AS@%                  menu_num = spawnl( P_WAIT, "program2.exe",
  18465. %@AS@%                                 "program2.exe", NULL );
  18466. %@AS@%                  break;
  18467. %@AS@%              case 3 :
  18468. %@AS@%                  menu_num = spawnl( P_WAIT, "program3.exe",
  18469. %@AS@%                                 "program3.exe", NULL );
  18470. %@AS@%                 break;
  18471. %@AS@%             default:       /* Guard against a bad option */
  18472. %@AS@%                 break;
  18473. %@AS@%         }
  18474. %@AS@%      }
  18475. %@AS@%  }%@AE@%%@NL@%
  18476. %@NL@%
  18477. The preceding example demonstrates how you could have a program, %@AS@% menu.exe%@AE@%,
  18478. that solicits input from a menu of choices. This input is interpreted and
  18479. passed back to the main program in the form of an exit code. (The %@AB@%spawnl%@AE@%
  18480. function returns the value of the child process's exit code.) This exit code
  18481. value is stored in %@AS@% option%@AE@%, which is used as a selector variable in a switch
  18482. statement.  %@NL@%
  18483. %@NL@%
  18484. Based on the value returned from %@AS@% menu.exe%@AE@%, the main program executes
  18485. %@AS@%program1.exe%@AE@%, %@AS@% program2.exe%@AE@%, or %@AS@% program3.exe%@AE@%. Finally, %@AS@% menu_num%@AE@%, the exit
  18486. code of the program selected, is used as a parameter to the next execution
  18487. of %@AS@% menu.exe%@AE@%.  %@NL@%
  18488. %@NL@%
  18489. %@NL@%
  18490. %@NL@%
  18491. %@NL@%
  18492. %@NL@%
  18493. %@NL@%
  18494. %@CR:C6A-B0001   @%%@1@%%@AB@%Appendix B  Differences between C Versions 5.1 and 6.0%@AE@%%@EH@%%@NL@%
  18495. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18496. %@NL@%
  18497. This appendix describes the differences between versions 5.1 and 6.0 of
  18498. Microsoft C, including additions, deletions, and changes. Some of the
  18499. changes are required by the American National Standards Institute (ANSI)
  18500. draft standard for the C programming language. Other changes improve or
  18501. augment the existing capabilities of the compiler.  %@NL@%
  18502. %@NL@%
  18503. Many of the changes will have no effect on code that was written and
  18504. compiled with previous versions of Microsoft C. In some cases, however, you
  18505. may have to modify or correct existing code before compiling with version
  18506. 6.0.  %@NL@%
  18507. %@NL@%
  18508. %@NL@%
  18509. %@2@%%@CR:C6A-B0002   @%%@AB@%B.1  Modifications for ANSI Compatibility%@AE@%%@EH@%%@NL@%
  18510. %@NL@%
  18511. A number of changes have been made to the compiler to support the ANSI draft
  18512. standard. These include new features (Section B.1.1) and changes (Sections
  18513. B.1.2 - B.1.8).  %@NL@%
  18514. %@NL@%
  18515. %@NL@%
  18516. %@3@%%@CR:C6A-B0003   @%%@AB@%B.1.1  ANSI-Mandated New Features%@AE@%%@EH@%%@NL@%
  18517. %@NL@%
  18518. The following ANSI-mandated features are new to version 6.0:  %@NL@%
  18519. %@NL@%
  18520. %@NL@%
  18521.   ■   The semantics for %@AB@%volatile%@AE@% have been implemented.%@NL@%
  18522. %@NL@%
  18523.   ■   Both %@AB@%long %@AE@%and %@AB@%unsigned long%@AE@% values are allowed in switch expressions
  18524.       and case constants.%@NL@%
  18525. %@NL@%
  18526.   ■   The compiler supports %@AB@%unsigned long%@AE@% decimal constants. It is now
  18527.       possible to initialize %@AB@%unsigned long%@AE@% variables with values larger than
  18528.       %@AB@%MAX_LONG%@AE@% using decimal (rather than hexadecimal or octal) constants.%@NL@%
  18529. %@NL@%
  18530.   ■   Bit fields are permitted in unions.%@NL@%
  18531. %@NL@%
  18532.   ■   The address-of operator (%@AB@%&%@AE@%) works correctly on arrays and functions.%@NL@%
  18533. %@NL@%
  18534.   ■   Storage classes or types (or both) are now required on variable
  18535.       declarations. The compiler previously assumed that untyped variables
  18536.       (such as %@AS@% a;%@AE@%) were integers. This declaration now generates a warning.%@NL@%
  18537. %@NL@%
  18538.   ■   The LOCALE.H header file is new to version 6.0. It declares functions
  18539.       and structures for describing conventions that vary from one country
  18540.       to the next, such as the currency symbol and the way calendar dates
  18541.       are printed.%@NL@%
  18542. %@NL@%
  18543. %@NL@%
  18544. %@NL@%
  18545. %@3@%%@CR:C6A-B0004   @%%@AB@%B.1.2  Integer Promotion Rules%@AE@%%@EH@%%@NL@%
  18546. %@NL@%
  18547. The ANSI draft standard requires a change in the evaluation of some
  18548. expressions that mix signed and unsigned integers. Earlier versions of the
  18549. compiler attempted to preserve an expression's unsigned nature as much as
  18550. possible. Version 6.0 attempts to preserve the expression's value.  %@NL@%
  18551. %@NL@%
  18552. In version 5.1, an %@AB@%unsigned char%@AE@% promotes to an %@AB@%unsigned int%@AE@%; an %@AB@%unsigned
  18553. %@AB@%int%@AE@% promotes to an %@AB@%unsigned long%@AE@%.  %@NL@%
  18554. %@NL@%
  18555. In version 6.0, an %@AB@%unsigned char%@AE@% promotes to a %@AB@%signed int%@AE@%; an %@AB@%unsigned int%@AE@%
  18556. promotes to a %@AB@%signed long%@AE@%.  %@NL@%
  18557. %@NL@%
  18558. For example,  %@NL@%
  18559. %@NL@%
  18560. %@AS@%  main()
  18561. %@AS@%  {
  18562. %@AS@%    long int li = -256L;
  18563. %@AS@%    test( li );
  18564. %@AS@%  }
  18565. %@AS@%  
  18566. %@AS@%  test( long li) 
  18567. %@AS@%  {
  18568. %@AS@%    if( li < 0xffff )
  18569. %@AS@%       puts( "C 6.0 does a signed compare" );
  18570. %@AS@%     else puts( "C 5.1 does an unsigned compare" );
  18571. %@AS@%  }%@AE@%%@NL@%
  18572. %@NL@%
  18573. %@NL@%
  18574. %@3@%%@CR:C6A-B0005   @%%@AB@%B.1.3  Defining NULL as a Pointer%@AE@%%@EH@%%@NL@%
  18575. %@NL@%
  18576. The constant %@AB@%NULL %@AE@%is now defined as %@AS@% ((void *)0)%@AE@%. Previous versions of
  18577. Microsoft C defined %@AB@%NULL%@AE@% as 0x0000 in small and medium models and
  18578. 0x00000000L in compact and large models.  %@NL@%
  18579. %@NL@%
  18580. %@NL@%
  18581. %@3@%%@CR:C6A-B0006   @%%@AB@%B.1.4  Shift Operators%@AE@%%@EH@%%@NL@%
  18582. %@NL@%
  18583. Shift operators now give a result that is of the same type as the left side.
  18584. For example,  %@NL@%
  18585. %@NL@%
  18586. %@AS@%  short si;
  18587. %@AS@%  long li;
  18588. %@AS@%  si = 0x0001;
  18589. %@AS@%  li = si << 16L;%@AE@%%@NL@%
  18590. %@NL@%
  18591. The compiler previously yielded a result that was the size of the largest of
  18592. the two values. In the example above, the short value would be automatically
  18593. cast to a long because 16L is long. The value assigned to %@AS@% li %@AE@% would be
  18594. 0x00010000L in Microsoft C 5.1.  %@NL@%
  18595. %@NL@%
  18596. To adhere to the ANSI draft standard, Microsoft C 6.0 maintains the size of
  18597. the left operand. The variable %@AS@% si %@AE@% has 16 bits. Shifting left 16 times
  18598. produces a value of 0, which is then assigned to %@AS@% li%@AE@%.  %@NL@%
  18599. %@NL@%
  18600. %@NL@%
  18601. %@3@%%@CR:C6A-B0007   @%%@AB@%B.1.5  Pointers to Typedefs%@AE@%%@EH@%%@NL@%
  18602. %@NL@%
  18603. The rules for handling pointers to typedefs have changed subtly. For
  18604. example, C 5.1 interprets  %@NL@%
  18605. %@NL@%
  18606. %@AS@%  typedef int far f_int;
  18607. %@AS@%  f_int *fp_i;%@AE@%%@NL@%
  18608. %@NL@%
  18609. as being equivalent to  %@NL@%
  18610. %@NL@%
  18611. %@AS@%  int *far fp_i;%@AE@%%@NL@%
  18612. %@NL@%
  18613. which means %@AS@% fp_i %@AE@% is a distant pointer to an integer. The address of %@AS@% fp_i %@AE@%
  18614. contains 32 bits. The size of the integer's address is indeterminate.  %@NL@%
  18615. %@NL@%
  18616. C 6.0 interprets it as  %@NL@%
  18617. %@NL@%
  18618. %@AS@%  int far *fp_i;%@AE@%%@NL@%
  18619. %@NL@%
  18620. This means %@AS@% fp_i %@AE@% is a far pointer to an integer. The address of the integer
  18621. contains 32 bits. The size of the address of %@AS@% fp_i %@AE@% is indeterminate. %@AS@%  %@AE@%%@NL@%
  18622. %@NL@%
  18623. This affects typedefs containing %@AB@%_near%@AE@%, %@AB@%_far%@AE@%, %@AB@%_based%@AE@%, and other modifiers.
  18624. Although these are Microsoft-specific keywords, their new behavior is
  18625. consistent with what the ANSI draft standard requires for the %@AB@%const %@AE@%and
  18626. %@AB@%volatile %@AE@%keywords.  %@NL@%
  18627. %@NL@%
  18628. %@NL@%
  18629. %@3@%%@CR:C6A-B0008   @%%@AB@%B.1.6  Identifying Nonstandard Keywords%@AE@%%@EH@%%@NL@%
  18630. %@NL@%
  18631. The following modifiers are specific to Microsoft C; they are not described
  18632. in the ANSI draft standard. To identify these implementation-defined
  18633. keywords as non-ANSI, an initial underscore has been added.%@CR:C6A-B0009   @%  %@NL@%
  18634. %@NL@%
  18635. %@AB@%C 5.1 Keyword%@AE@%                     %@AB@%C 6.0 Keyword%@AE@%
  18636. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18637. %@AB@%far%@AE@%                               %@AB@%_far%@AE@%
  18638.  
  18639. %@AB@%huge%@AE@%                              %@AB@%_huge%@AE@%
  18640.  
  18641. %@AB@%near%@AE@%                              %@AB@%_near%@AE@%
  18642.  
  18643. %@AB@%cdecl%@AE@%                             %@AB@%_cdecl%@AE@%
  18644.  
  18645. %@AB@%fortran%@AE@%                           %@AB@%_fortran%@AE@%
  18646.  
  18647. %@AB@%interrupt%@AE@%                         %@AB@%_interrupt%@AE@%
  18648.  
  18649. %@AB@%pascal%@AE@%                            %@AB@%_pascal%@AE@%
  18650.  
  18651. The compiler still accepts the obsolescent versions of these keywords,
  18652. unless the /Za option is used.  %@NL@%
  18653. %@NL@%
  18654. %@NL@%
  18655. %@3@%%@CR:C6A-B0010   @%%@AB@%B.1.7  Trigraphs%@AE@%%@EH@%%@NL@%
  18656. %@NL@%
  18657. To maintain compatibility with and portability to other systems, Microsoft C
  18658. 6.0 supports the following trigraphs:  %@NL@%
  18659. %@NL@%
  18660. %@AB@%Trigraph%@AE@%                          %@AB@%Character%@AE@%
  18661. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18662. %@AB@%??=%@AE@%                               %@AB@%#%@AE@%
  18663.  
  18664. %@AB@%??(%@AE@%                               %@AB@%[%@AE@%
  18665.  
  18666. %@AB@%??/%@AE@%                               %@AB@%\%@AE@%
  18667.  
  18668. %@AB@%??)%@AE@%                               %@AB@%]%@AE@%
  18669.  
  18670. %@AB@%??'%@AE@%                               %@AB@%^%@AE@%
  18671.  
  18672. %@AB@%??<%@AE@%                               %@AB@%{%@AE@%
  18673.  
  18674. %@AB@%??!%@AE@%                               %@AB@%|%@AE@%
  18675.  
  18676. %@AB@%??>%@AE@%                               %@AB@%}%@AE@%
  18677.  
  18678. %@AB@%??-%@AE@%                               %@AB@%~%@AE@%
  18679.  
  18680. %@NL@%
  18681. %@3@%%@CR:C6A-B0011   @%%@AB@%B.1.8  ANSI Nonconformance%@AE@%%@EH@%%@NL@%
  18682. %@NL@%
  18683. This section lists the areas where Microsoft C 6.0 does not conform to the
  18684. ANSI draft standard.  %@NL@%
  18685. %@NL@%
  18686. %@NL@%
  18687.   ■   Microsoft C does not support multibyte characters, wide-character and
  18688.       string constants, and the related library functions and types.%@NL@%
  18689. %@NL@%
  18690.   ■   Microsoft C contains some name-space violations in the language
  18691.       (extended keywords, such as %@AB@%near%@AE@% and %@AB@%far%@AE@%) and in the library (non-ANSI
  18692.       macros and types in header files and extended library function names,
  18693.       such as %@AB@%read %@AE@%and %@AB@%write%@AE@%).%@NL@%
  18694. %@NL@%
  18695. %@NL@%
  18696. %@NL@%
  18697. %@2@%%@CR:C6A-B0012   @%%@AB@%B.2  New Keywords and Functions%@AE@%%@EH@%%@NL@%
  18698. %@NL@%
  18699. This section describes keywords and functions that did not exist in previous
  18700. versions of Microsoft C. Details about how to use these features can be
  18701. found elsewhere in the documentation.  %@NL@%
  18702. %@NL@%
  18703. %@NL@%
  18704. %@3@%%@CR:C6A-B0013   @%%@AB@%B.2.1  In-Line Assembler%@AE@%%@EH@%%@NL@%
  18705. %@NL@%
  18706. The new %@AB@%_asm%@AE@% keyword allows you to mix assembly instructions with C source
  18707. code. This feature includes the %@AB@%_emit%@AE@% function, which lets you enter
  18708. arbitrary values into the code stream.  %@NL@%
  18709. %@NL@%
  18710. See Chapter 3, "Using the In-Line Assembler."  %@NL@%
  18711. %@NL@%
  18712. %@NL@%
  18713. %@3@%%@CR:C6A-B0014   @%%@AB@%B.2.2  Based Pointers and Objects%@AE@%%@EH@%%@NL@%
  18714. %@NL@%
  18715. A based pointer is a special, compact form of pointer. It is always
  18716. represented as a short offset. The address represented by such a pointer is
  18717. calculated by adding the based pointer to its base. The base must be
  18718. supplied each time the pointer is dereferenced, either explicitly using a
  18719. special operator or implicitly by associating the base value with the
  18720. pointer when it is declared. The base can be a far pointer, a near pointer,
  18721. or a new type that represents a segment.  %@NL@%
  18722. %@NL@%
  18723. Based pointers and objects are declared using the new keyword, %@AB@%_based%@AE@%.  %@NL@%
  18724. %@NL@%
  18725. %@NL@%
  18726. %@4@%%@AB@%Segment Types%@AE@%%@EH@%%@NL@%
  18727. %@NL@%
  18728. The new type specifier, %@AB@%_segment%@AE@%, specifies a segment.  %@NL@%
  18729. %@NL@%
  18730. Any pointer or address can be cast to %@AB@%_segment%@AE@%. If the operand is a near
  18731. pointer, the result is the current value of the data segment register (DS).
  18732. If the operand is a far pointer, the result is the segment part of the far
  18733. pointer.  %@NL@%
  18734. %@NL@%
  18735. %@NL@%
  18736. %@4@%%@AB@%Segment Names%@AE@%%@EH@%%@NL@%
  18737. %@NL@%
  18738. Segment names are declared using the built-in function %@AB@%_segname%@AE@%. The
  18739. compiler recognizes four predefined segment names: %@AB@%_CODE%@AE@%, %@AB@%_CONST%@AE@%, %@AB@%_DATA%@AE@%, and
  18740. %@AB@%_STACK%@AE@%.  %@NL@%
  18741. %@NL@%
  18742. Each segment name represents a constant of type %@AB@%_segment%@AE@%.  %@NL@%
  18743. %@NL@%
  18744. %@NL@%
  18745. %@4@%%@AB@%Base Operator%@AE@%%@EH@%%@NL@%
  18746. %@NL@%
  18747. The base operator%@AB@% %@AE@%(%@AB@%:>%@AE@%) associates a base expression (usually a segment) with
  18748. a based pointer, to form a far pointer value. For example,  %@NL@%
  18749. %@NL@%
  18750. %@AS@%  0x0F01:>0x0015%@AE@%%@NL@%
  18751. %@NL@%
  18752. combines the segment 0x0F01 with the offset 0x0015 to form the effective
  18753. address 0x0F025. The base operator's precedence falls between ( ) and [ ].  %@NL@%
  18754. %@NL@%
  18755. %@NL@%
  18756. %@4@%%@AB@%Casting Based Pointers%@AE@%%@EH@%%@NL@%
  18757. %@NL@%
  18758. A based pointer can be cast to a pointer, a long integer, a short integer,
  18759. or another based pointer. When a based pointer is converted to a far
  18760. pointer, a long integer, a near pointer, or another based pointer having a
  18761. different base expression, it is first normalized to a far pointer
  18762. (including adding the offset in the base, if present, to the based pointer);
  18763. then any additional conversions are applied.  %@NL@%
  18764. %@NL@%
  18765. %@NL@%
  18766. %@4@%%@AB@%Operations on Based Pointers%@AE@%%@EH@%%@NL@%
  18767. %@NL@%
  18768. Based pointers, for the purpose of arithmetic and dereferencing, are treated
  18769. as semantically equivalent to far pointers. When a based pointer mixes with
  18770. another integral type (%@AB@%int%@AE@%, %@AB@%long%@AE@%, near pointer, far pointer, or based
  18771. pointer), implicit casting is done. In some cases, the compiler can optimize
  18772. these references and treat the pointer as an offset.  %@NL@%
  18773. %@NL@%
  18774. The value of 0 is treated specially, as it is for near and far pointers. No
  18775. conversions are applied to the constant 0 because it is assumed to be a null
  18776. pointer.  %@NL@%
  18777. %@NL@%
  18778. See Chapter 2, "Managing Memory."  %@NL@%
  18779. %@NL@%
  18780. %@NL@%
  18781. %@3@%%@CR:C6A-B0015   @%%@AB@%B.2.3  Based Heap Allocation Support%@AE@%%@EH@%%@NL@%
  18782. %@NL@%
  18783. The functions listed below provide support for allocating, expanding, and
  18784. freeing memory for based heaps, which dynamically allocate memory for based
  18785. items. The functions are prototyped in the MALLOC.H include file.  %@NL@%
  18786. %@NL@%
  18787. %@TH:   6   421 01 11 12 53 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_bcalloc%@AE@%   %@AB@%_bheapchk%@AE@%   %@AB@%_bmalloc%@AE@%%@AB@%_bexpand%@AE@%   %@AB@%_bheapmin%@AE@%   %@AB@%_bmsize%@AE@%%@AB@%_bfree%@AE@%     %@AB@%_bheapseg%@AE@%   %@AB@%_brealloc%@AE@%%@AB@%_bfreeseg%@AE@%  %@AB@%_bheapset%@AE@%%@AB@%_bheapadd%@AE@%  %@AB@%_bheapwalk%@AE@%%@TE:   6   421 01 11 12 53 @%
  18788.  
  18789. See Chapter 2, "Managing Memory."  %@NL@%
  18790. %@NL@%
  18791. %@NL@%
  18792. %@3@%%@CR:C6A-B0016   @%%@AB@%B.2.4  Releasing Unused Heap Memory%@AE@%%@EH@%%@NL@%
  18793. %@NL@%
  18794. The following routines release unused heap memory by shortening data
  18795. segments. MALLOC.H contains the function prototypes.  %@NL@%
  18796. %@NL@%
  18797. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18798. %@AB@%_fheapmin%@AE@%                                                                   
  18799. %@AB@%_heapmin%@AE@%                                                                    
  18800. %@AB@%_nheapmin%@AE@%                                                                   
  18801.  
  18802. %@NL@%
  18803. %@3@%%@CR:C6A-B0017   @%%@AB@%B.2.5  Making Static Data Available to the Heap%@AE@%%@EH@%%@NL@%
  18804. %@NL@%
  18805. The %@AB@%_heapadd%@AE@% function is new. It allows the user to make unused static data
  18806. available to the heap.  %@NL@%
  18807. %@NL@%
  18808. %@NL@%
  18809. %@3@%%@CR:C6A-B0018   @%%@AB@%B.2.6  Long Doubles%@AE@%%@EH@%%@NL@%
  18810. %@NL@%
  18811. Microsoft C version 5.1 treated %@AB@%double%@AE@% and %@AB@%long double%@AE@% as syntactically
  18812. different types that were semantically equal. Both types were stored in
  18813. memory as 64-bit quantities. For purposes of type-checking, %@AB@%long double%@AE@% and
  18814. %@AB@%double%@AE@% have always been different types.  %@NL@%
  18815. %@NL@%
  18816. Because the 80%@AI@%x%@AE@%87 family of math coprocessors supports an 80-bit
  18817. floating-point type, Microsoft C version 6.0 stores %@AB@%long double%@AE@% variables in
  18818. the 80%@AI@%x%@AE@%87 10-byte (80-bit) form.  %@NL@%
  18819. %@NL@%
  18820. Certain functions have been modified to handle the %@AB@%long double%@AE@% type. The
  18821. %@AB@%printf%@AE@% and %@AB@%scanf%@AE@% family of functions supports %@AB@%long double%@AE@% values with the
  18822. trailing %@AB@%l%@AE@%. The library contains new versions of the transcendental
  18823. functions as well as intrinsic forms that accept %@AB@%long double%@AE@% arguments.  %@NL@%
  18824. %@NL@%
  18825. %@NL@%
  18826. %@3@%%@CR:C6A-B0019   @%%@AB@%B.2.7  Long Double Functions%@AE@%%@EH@%%@NL@%
  18827. %@NL@%
  18828. All the functions below are defined in the standard include file MATH.H.
  18829. They return %@AB@%long double%@AE@% values and results and error codes analogous to the
  18830. double versions.  %@NL@%
  18831. %@NL@%
  18832. %@TH:  10   630 01 08 08 60 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%acosl%@AE@%   %@AB@%expl%@AE@%    %@AB@%_matherrl%@AE@%%@AB@%asinl%@AE@%   %@AB@%fabsl%@AE@%   %@AB@%modfl%@AE@%%@AB@%atanl%@AE@%   %@AB@%floorl%@AE@%  %@AB@%powl%@AE@%%@AB@%atan2l%@AE@%  %@AB@%fmodl%@AE@%   %@AB@%sinl%@AE@%%@AB@%_atold%@AE@%  %@AB@%frexpl%@AE@%  %@AB@%sinhl%@AE@%%@AB@%cabsl%@AE@%   %@AB@%hypotl%@AE@%  %@AB@%sqrtl%@AE@%%@AB@%ceill%@AE@%   %@AB@%ldexpl%@AE@%  %@AB@%tanl%@AE@%%@AB@%cosl%@AE@%    %@AB@%logl%@AE@%    %@AB@%tanhl%@AE@%%@AB@%coshl%@AE@%   %@AB@%log10l%@AE@%%@TE:  10   630 01 08 08 60 @%
  18833.  
  18834. %@NL@%
  18835. %@3@%%@CR:C6A-B0020   @%%@AB@%B.2.8  Model-Independent String and Memory Functions%@AE@%%@EH@%%@NL@%
  18836. %@NL@%
  18837. The following functions make it easier to write mixed-model programs by
  18838. providing model-independent (large model) forms for most of the standard
  18839. string and memory functions. These functions can be called from any point in
  18840. any program, no matter which memory model has been selected. These functions
  18841. take only far pointers as arguments. Thus, any data item, near or far, in
  18842. any combination, can be handled.  %@NL@%
  18843. %@NL@%
  18844. The names of these functions are the same as the model-dependent forms,
  18845. except they include an %@AB@%_f %@AE@%prefix. For example, %@AB@%_fstrlen %@AE@%is the
  18846. model-independent version of the %@AB@%strlen %@AE@%function.  %@NL@%
  18847. %@NL@%
  18848. The functions listed below are defined in the standard include file
  18849. STRING.H.  %@NL@%
  18850. %@NL@%
  18851. %@NL@%
  18852. %@4@%%@AB@%Memory Functions%@AE@%%@EH@%%@NL@%
  18853. %@NL@%
  18854. %@TH:   5   340 01 29 47 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_fmemccpy %@AE@%                   %@AB@%_fmemcpy%@AE@%%@AB@%_fmemchr%@AE@%                     %@AB@%_fmemmove%@AE@%%@AB@%_fmemcmp%@AE@%                     _fmemset%@AB@%_fmemicmp%@AE@%                    %@TE:   5   340 01 29 47 @%
  18855.  
  18856. %@NL@%
  18857. %@4@%%@AB@%String Functions%@AE@%%@EH@%%@NL@%
  18858. %@NL@%
  18859. %@TH:   8   520 01 11 12 53 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_fstrcat%@AE@%   _fstrlwr    %@AB@%_fstrrchr%@AE@%%@AB@%_fstrchr%@AE@%   %@AB@%_fstrncat%@AE@%   _fstrrev%@AB@%_fstrcmp%@AE@%   _fstrncmp   %@AB@%_fstrset%@AE@%%@AB@%_fstricmp%@AE@%  _fstrnicmp  %@AB@%_fstrspn%@AE@%%@AB@%_fstrcpy%@AE@%   _fstrncpy   %@AB@%_fstrstr%@AE@%%@AB@%_fstrcspn%@AE@%  %@AB@%_fstrnset%@AE@%   _fstrtok%@AB@%_fstrlen%@AE@%   _fstrpbrk   %@AB@%_fstrupr %@AE@%%@TE:   8   520 01 11 12 53 @%
  18860.  
  18861. %@NL@%
  18862. %@4@%%@AB@%String Duplication Functions%@AE@%%@EH@%%@NL@%
  18863. %@NL@%
  18864. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18865. %@AB@%_fstrdup%@AE@%                                                                    
  18866. %@AB@%_nstrdup%@AE@%                                                                    
  18867.  
  18868. %@NL@%
  18869. %@3@%%@CR:C6A-B0021   @%%@AB@%B.2.9  Mixed-Model Memory Allocation Support%@AE@%%@EH@%%@NL@%
  18870. %@NL@%
  18871. The following functions are based on %@AB@%realloc%@AE@%, %@AB@%calloc%@AE@%, and %@AB@%expand%@AE@%, but they
  18872. affect only near memory or far memory. MALLOC.H contains the function
  18873. prototypes.  %@NL@%
  18874. %@NL@%
  18875. %@TH:   4   271 01 28 48 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_fcalloc%@AE@%                    _ncalloc%@AB@%_fexpand%@AE@%                    _nexpand%@AB@%_frealloc%@AE@%                   _nrealloc%@TE:   4   271 01 28 48 @%
  18876.  
  18877. %@NL@%
  18878. %@3@%%@CR:C6A-B0022   @%%@AB@%B.2.10  The _fastcall Attribute (/Gr Option)%@AE@%%@EH@%%@NL@%
  18879. %@NL@%
  18880. Individual function prototypes can be declared with the new attribute
  18881. %@AB@%_fastcall%@AE@%.  %@NL@%
  18882. %@NL@%
  18883. The /Gr option enables the fastcall function-calling convention for all
  18884. functions that are not explicitly prototyped with the %@AB@%_cdecl%@AE@%, %@AB@%_pascal%@AE@%, or
  18885. %@AB@%_fortran %@AE@%attributes. Using /Gr on the command line causes each function in
  18886. the module to compile as %@AB@%_fastcall%@AE@% unless the function is declared with a
  18887. conflicting attribute, or the name of the function is %@AB@%main%@AE@%.  %@NL@%
  18888. %@NL@%
  18889. When you use the /Gr option, all functions are assumed to use the %@AB@%_fastcall
  18890. %@AB@%%@AE@%convention. As a result, to use any run-time library functions, you must
  18891. either include the standard include files or explicitly prototype the
  18892. function you want to call.  %@NL@%
  18893. %@NL@%
  18894. A fastcall function receives up to three 16-bit arguments, passed in
  18895. registers rather than on the stack. Arguments are passed in the AX, BX, and
  18896. DX registers. This may change in future versions of the compiler.  %@NL@%
  18897. %@NL@%
  18898. The argument types and their potential register assignments are  %@NL@%
  18899. %@NL@%
  18900. %@AB@%Argument%@AE@%                          %@AB@%Registers%@AE@%
  18901. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18902. character (3)                     AL, DL, BL
  18903.  
  18904. short integer (3)                 AX, DX, BX
  18905.  
  18906. near pointer (3)                  BX, AX, DX
  18907.  
  18908. long integer (1)                  DX:AX
  18909.  
  18910. far pointer (1)                   ES:BX
  18911.  
  18912. If the registers for a particular class have already been used, or if an
  18913. argument is not one of the five types listed above, it is pushed on the
  18914. stack as usual. An argument list of types %@AB@%long%@AE@%, %@AB@%float%@AE@%, %@AB@%short %@AE@%would pass the
  18915. %@AB@%long %@AE@%in DX:AX, push the %@AB@%float%@AE@%, and pass the %@AB@%short %@AE@%in BX.  %@NL@%
  18916. %@NL@%
  18917. The treatment of character arguments depends further on prototypes. If there
  18918. is no prototype, the argument is promoted to %@AB@%short %@AE@%and the rules for short
  18919. integers apply. Only if the argument is prototyped as a %@AB@%char %@AE@%do the
  18920. character rules apply.  %@NL@%
  18921. %@NL@%
  18922. The %@AB@%_fastcall %@AE@%convention is not compatible with any of the following
  18923. attributes: %@AB@%_interrupt%@AE@%, %@AB@%_saveregs%@AE@%, %@AB@%_export%@AE@%, %@AB@%_cdecl%@AE@%, %@AB@%_fortran%@AE@%, or %@AB@%_pascal%@AE@%.  %@NL@%
  18924. %@NL@%
  18925. See Chapter 1, "Optimizing C Programs."  %@NL@%
  18926. %@NL@%
  18927. %@NL@%
  18928. %@3@%%@CR:C6A-B0023   @%%@AB@%B.2.11  Drive and Directory Functions%@AE@%%@EH@%%@NL@%
  18929. %@NL@%
  18930. Several new functions make it easier to get and set the current drive and
  18931. the current directory. The prototypes for the following routines are in
  18932. DIRECT.H:%@CR:C6A-B0024   @%  %@NL@%
  18933. %@NL@%
  18934. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18935. %@AB@%_chdrive%@AE@%                                                                    
  18936. %@AB@%_fullpath%@AE@%                                                                   
  18937. %@AB@%_getdrive%@AE@%                                                                   
  18938. %@AB@%_getdcwd%@AE@%                                                                    
  18939.  
  18940. %@NL@%
  18941. %@3@%%@CR:C6A-B0025   @%%@AB@%B.2.12  Text Output Functions for OS/2%@AE@%%@EH@%%@NL@%
  18942. %@NL@%
  18943. Several text-mode screen functions have been added to Microsoft C 6.0 for
  18944. OS/2. With the exception of the new %@AB@%_scrolltextwindow %@AE@%function, they are
  18945. identical to what is defined in real mode, except for any references to
  18946. behavior in graphics modes. The following routines are located in
  18947. GRTEXT.LIB, and the prototypes are in GRAPH.H:  %@NL@%
  18948. %@NL@%
  18949. %@TH:   7   561 01 18 18 40 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_clearscreen%@AE@%      _getvideoconfig   %@AB@%_settextrows%@AE@%%@AB@%_displaycursor%@AE@%    _outtext          %@AB@%_settextwindow%@AE@%%@AB@%_getbkcolor%@AE@%       _setbkcolor       %@AB@%_setvideomode%@AE@%%@AB@%_gettextcolor%@AE@%     _settextcolor     %@AB@%_setvideomoderows%@AE@%%@AB@%_gettextcursor%@AE@%    _settextcursor    _scrolltextwindow%@AB@%_gettextposition%@AE@%  _settextposition  %@AB@%_wrapon %@AE@%%@TE:   7   561 01 18 18 40 @%
  18950.  
  18951. See Part 4 of this manual, "OS/2 Support."  %@NL@%
  18952. %@NL@%
  18953. %@NL@%
  18954. %@2@%%@CR:C6A-B0026   @%%@AB@%B.3  New Features%@AE@%%@EH@%%@NL@%
  18955. %@NL@%
  18956. The features described in Sections B.3.1-B.3.10 are new to version 6.0.  %@NL@%
  18957. %@NL@%
  18958. %@NL@%
  18959. %@3@%%@CR:C6A-B0027   @%%@AB@%B.3.1  Strings and Macros%@AE@%%@EH@%%@NL@%
  18960. %@NL@%
  18961. The compiler now allows longer string literals (up to 4K) and longer macro
  18962. expansions (up to 6K).  %@NL@%
  18963. %@NL@%
  18964. %@NL@%
  18965. %@3@%%@CR:C6A-B0028   @%%@AB@%B.3.2  CL Options%@AE@%%@EH@%%@NL@%
  18966. %@NL@%
  18967. The following options are new to Microsoft C 6.0:%@CR:C6A-B0029   @%  %@NL@%
  18968. %@NL@%
  18969. %@AB@%Option%@AE@%                            %@AB@%Action%@AE@%
  18970. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18971. /AT                               Compiles in tiny model (.COM files).
  18972.  
  18973. /Fr« %@AI@%filename%@AE@%»                    Outputs source browser information file.
  18974.  
  18975. /FR«%@AI@% filename%@AE@%»                    Outputs extended source browser 
  18976.                                   information file.
  18977.  
  18978. /Gd                               Forces %@AB@%_cdecl %@AE@%calling conventions.
  18979.  
  18980. /Gr                               Enables register (%@AB@%_fastcall%@AE@%) 
  18981.                                   function-calling
  18982.                                   conventions.
  18983.  
  18984. /MA%@AI@%masmoption%@AE@%                     Supports invocation of the assembler 
  18985.                                   using the CL driver. All MASM-supported 
  18986.                                   options are accepted. In addition, the 
  18987.                                   compiler recognizes file names with .ASM
  18988.                                   suffixes and passes them directly to 
  18989.                                   MASM.
  18990.  
  18991. /MD-                              Uses C run-time as DLL option. Defaults 
  18992.                                   to
  18993.                                   /ALw /FPi /G2 /DDLL /DMT and inhibits 
  18994.                                   library search records.
  18995.  
  18996. /ML                               Links C run-time as part of a 
  18997.                                   dynamic-link library (DLL). Defaults to 
  18998.                                   /ALw /FPa /G2 /DMT and changes library 
  18999.                                   search record to LLIBCDLL.LIB.
  19000.  
  19001. /MT                               Enables multithread option. Defaults to
  19002.                                   /ALw /FPi /G2 /DMT and changes library
  19003.                                   search record to LLIBCMT.LIB.
  19004.  
  19005. /Oe                               Enables global register allocation.
  19006.  
  19007. /Og                               Enables global optimizations and global 
  19008.                                   common subexpressions (CSEs).
  19009.  
  19010. /Ox                               Is now equivalent to /Ocegilt /Gs. Note 
  19011.                                   that this implies that maximum 
  19012.                                   optimization includes the %@AB@%_fastcall%@AE@% 
  19013.                                   function-calling convention.
  19014.  
  19015. /Oz                               Enables aggressive optimizations.
  19016.  
  19017. /Ta %@AI@%name%@AE@%                          Specifies that%@AI@% name %@AE@%is to be treated as 
  19018.                                   an assembler input file.
  19019.  
  19020. /W4                               Turns on extra warning level which 
  19021.                                   supports more detailed (LINT-like) 
  19022.                                   warnings and recognition of ANSI 
  19023.                                   violations.
  19024.  
  19025. /WX                               Causes warnings to be treated as errors.
  19026.                                   If a warning occurs, the .OBJ file is 
  19027.                                   not created.
  19028.  
  19029. %@NL@%
  19030. %@3@%%@CR:C6A-B0030   @%%@AB@%B.3.3  Tiny Memory Model (.COM Files)%@AE@%%@EH@%%@NL@%
  19031. %@NL@%
  19032. Microsoft C 6.0 now supports the tiny memory model, which produces .COM
  19033. rather than .EXE files (for DOS only).  %@NL@%
  19034. %@NL@%
  19035. The /AT option selects the tiny model. This forces the linker to use options
  19036. /NOE and /TINY. Within the linker, /TINY turns on /FARCALLTRANSLATION to
  19037. help eliminate far segment relocations. If you link your own .OBJ files,
  19038. link with CRTCOM.OBJ.  %@NL@%
  19039. %@NL@%
  19040. %@NL@%
  19041. %@3@%%@CR:C6A-B0031   @%%@AB@%B.3.4  The Optimize Pragma%@AE@%%@EH@%%@NL@%
  19042. %@NL@%
  19043. The %@AB@%optimize %@AE@%pragma turns optimizing options on or off:  %@NL@%
  19044. %@NL@%
  19045. %@AS@%  #pragma optimize("<optimization switch list>",{off|on})%@AE@%%@NL@%
  19046. %@NL@%
  19047. where %@AI@%<optimization switch list>%@AE@% can be an empty list or one or more of the
  19048. following: a, c, e, g, l, w, n, p, t, and z. For example,  %@NL@%
  19049. %@NL@%
  19050. %@AS@%  #pragma optimize("lp",on) /* equivalent to /Olp */
  19051. %@AS@%  #pragma optimize("",off)  /* turns off all optimization */
  19052. %@AS@%  #pragma optimize("",on)  /* restores default settings */%@AE@%%@NL@%
  19053. %@NL@%
  19054. See Chapter 1, "Optimizing C Programs."  %@NL@%
  19055. %@NL@%
  19056. %@NL@%
  19057. %@3@%%@CR:C6A-B0032   @%%@AB@%B.3.5  Nameless Structures and Unions%@AE@%%@EH@%%@NL@%
  19058. %@NL@%
  19059. Both %@AB@%struct %@AE@%and %@AB@%union %@AE@%declarations can now be specified without a declarator
  19060. when they are members of another structure or union.  %@NL@%
  19061. %@NL@%
  19062. A nameless union would look like this:  %@NL@%
  19063. %@NL@%
  19064. %@AS@%  struct str
  19065. %@AS@%  {
  19066. %@AS@%     int a,b;
  19067. %@AS@%     union           /* unnamed union */
  19068. %@AS@%     {
  19069. %@AS@%        char c[4];
  19070. %@AS@%        long l;
  19071. %@AS@%        float f;
  19072. %@AS@%     };
  19073. %@AS@%     char c_array[10];
  19074. %@AS@%  } my_str;
  19075. %@AS@%  .
  19076. %@AS@%  .
  19077. %@AS@%  .
  19078. %@AS@%  my_str.l == 0L;%@AE@%%@NL@%
  19079. %@NL@%
  19080. A nameless structure would look like this:  %@NL@%
  19081. %@NL@%
  19082. %@AS@%  struct s1
  19083. %@AS@%  {
  19084. %@AS@%     int a,b,c;
  19085. %@AS@%  };
  19086. %@AS@%  
  19087. %@AS@%  struct s2
  19088. %@AS@%  {
  19089. %@AS@%     float y;
  19090. %@AS@%     struct s1;
  19091. %@AS@%     char str[10];
  19092. %@AS@%  } *p_s2;
  19093. %@AS@%  .
  19094. %@AS@%  .
  19095. %@AS@%  .
  19096. %@AS@%  
  19097. %@AS@%  p_s2->b = 100;%@AE@%%@NL@%
  19098. %@NL@%
  19099. %@NL@%
  19100. %@3@%%@CR:C6A-B0033   @%%@AB@%B.3.6  Unsized Arrays as the Last Member of a Structure%@AE@%%@EH@%%@NL@%
  19101. %@NL@%
  19102. The compiler now allows an unsized or zero-sized array as the last member of
  19103. a structure. The declaration of such a structure would look like this:  %@NL@%
  19104. %@NL@%
  19105. %@AS@%  struct var_length
  19106. %@AS@%  {
  19107. %@AS@%     <set of declarations>;
  19108. %@AS@%     <type> array[];
  19109. %@AS@%  };%@AE@%%@NL@%
  19110. %@NL@%
  19111. Unsized arrays can appear only as the last member of a structure. Structures
  19112. containing unsized array declarations can be nested within other structures
  19113. as long as no further members are declared in any enclosing structures.
  19114. Arrays of such structures are not allowed.  %@NL@%
  19115. %@NL@%
  19116. The %@AB@%sizeof %@AE@%operator, when applied to a variable of this type or to the type
  19117. itself, assumes 0 for the size of the array.  %@NL@%
  19118. %@NL@%
  19119. %@NL@%
  19120. %@3@%%@CR:C6A-B0034   @%%@AB@%B.3.7  Improved Warnings%@AE@%%@EH@%%@NL@%
  19121. %@NL@%
  19122. A new warning level four (CL option /W4) has been added for the following
  19123. warnings:  %@NL@%
  19124. %@NL@%
  19125. %@NL@%
  19126.   ■   Detection of unused global variables%@NL@%
  19127. %@NL@%
  19128.   ■   Expressions without side effects%@NL@%
  19129. %@NL@%
  19130.   ■   Nonportable (non-ANSI) constructs%@NL@%
  19131. %@NL@%
  19132.   ■   Local variable referenced before being initialized%@NL@%
  19133. %@NL@%
  19134.   ■   Undefined or implementation-defined constructs%@NL@%
  19135. %@NL@%
  19136. %@NL@%
  19137. %@NL@%
  19138. %@3@%%@CR:C6A-B0035   @%%@AB@%B.3.8  Macros%@AE@%%@EH@%%@NL@%
  19139. %@NL@%
  19140. The number of macros definable with /D options has increased from 20 to 30.
  19141. %@NL@%
  19142. %@NL@%
  19143. %@NL@%
  19144. %@3@%%@CR:C6A-B0036   @%%@AB@%B.3.9  Improved Multithread Support in OS/2%@AE@%%@EH@%%@NL@%
  19145. %@NL@%
  19146. The number of OS/2 threads supported at run time has increased from 32 to
  19147. the operating system limit. Three new options aid development of multithread
  19148. applications and dynamic-link libraries:  %@NL@%
  19149. %@NL@%
  19150. %@NL@%
  19151.   1.  /MT for building multithread programs. It implies /ALw /FPi /G2 /D MT,
  19152.       and changes the library search record emitted in the object file to
  19153.       reference LLIBCMT.%@NL@%
  19154. %@NL@%
  19155.   2.  /ML for building a DLL that uses the C run-time library. It implies
  19156.       /ALw /FPa /G2 /D MT, and changes the library search record emitted  in
  19157.       the object file to reference LLIBCDLL.%@NL@%
  19158. %@NL@%
  19159.   3.  /MD for building .EXE files and DLLs that share a C run-time DLL. It
  19160.       implies /ALw /FPi /G2 /DDLL /D MT, and no library search records are
  19161.       emitted in the object file.%@NL@%
  19162. %@NL@%
  19163. %@NL@%
  19164. %@NL@%
  19165. %@3@%%@CR:C6A-B0037   @%%@AB@%B.3.10  Pipe Support in OS/2%@AE@%%@EH@%%@NL@%
  19166. %@NL@%
  19167. Microsoft C 6.0 supports pipes as part of the file I/O system. The functions
  19168. listed below are defined in the standard include file IO.H:  %@NL@%
  19169. %@NL@%
  19170. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19171. %@AB@%_pipe%@AE@%                                                                       
  19172. %@AB@%_popen%@AE@%                                                                      
  19173. %@AB@%_pclose%@AE@%                                                                     
  19174.  
  19175. %@NL@%
  19176. %@2@%%@CR:C6A-B0038   @%%@AB@%B.4  Differences in Code Generation%@AE@%%@EH@%%@NL@%
  19177. %@NL@%
  19178. This section lists ways in which the executable files produced by Microsoft
  19179. C 6.0 may differ from the files produced by previous versions of the
  19180. compiler.  %@NL@%
  19181. %@NL@%
  19182. %@NL@%
  19183. %@3@%%@CR:C6A-B0039   @%%@AB@%B.4.1  Speed and Space Improvements%@AE@%%@EH@%%@NL@%
  19184. %@NL@%
  19185. Executable files are smaller and faster.  %@NL@%
  19186. %@NL@%
  19187. %@NL@%
  19188. %@3@%%@CR:C6A-B0040   @%%@AB@%B.4.2  Code Quality%@AE@%%@EH@%%@NL@%
  19189. %@NL@%
  19190. Microsoft C 6.0 generates improved local code in default optimization cases
  19191. and, under full optimization, supports global (function level) register
  19192. allocation and common subexpressions (CSEs), loop optimizations, parameter
  19193. passing through registers, and generation of in-line code for certain
  19194. intrinsic functions.  %@NL@%
  19195. %@NL@%
  19196. %@NL@%
  19197. %@3@%%@CR:C6A-B0041   @%%@AB@%B.4.3  Floating-Point Code Generation%@AE@%%@EH@%%@NL@%
  19198. %@NL@%
  19199. In Microsoft C 6.0, the /FPi87 option suppresses the fixups previously used
  19200. for emulation. Pure coprocessor instructions are now emitted. This makes
  19201. object files smaller and speeds up linking, in addition to making in-line
  19202. assembly easier to use.  %@NL@%
  19203. %@NL@%
  19204. In version 5.1, /FPi and /FPi87 generated the same code; the only difference
  19205. was the library. In C 6.0, the two options generate different code. It is no
  19206. longer possible to force /FPi87 to act like /FPi. If you use /FPi87, the
  19207. math coprocessor must be in the computer on which the program is running.  %@NL@%
  19208. %@NL@%
  19209. Note that if you use /FPi87 you must link with mLIB7, not mLIBCE.  %@NL@%
  19210. %@NL@%
  19211. %@NL@%
  19212. %@3@%%@CR:C6A-B0042   @%%@AB@%B.4.4  Intrinsic Functions%@AE@%%@EH@%%@NL@%
  19213. %@NL@%
  19214. The intrinsic function optimization option (/Oi) causes the compiler to
  19215. generate in-line code for the following functions:  %@NL@%
  19216. %@NL@%
  19217. %@TH:   8   467 01 10 08 58 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%abs%@AE@%       _lrotl  %@AB@%_rotl%@AE@%%@AB@%_disable%@AE@%  _lrotr  %@AB@%_rotr%@AE@%%@AB@%_enable%@AE@%   memcmp  %@AB@%strcat%@AE@%%@AB@%ffabs%@AE@%     memcpy  %@AB@%strcmp%@AE@%%@AB@%inp%@AE@%       memset  %@AB@%strcpy%@AE@%%@AB@%inpw%@AE@%      outp    %@AB@%strlen%@AE@%%@AB@%labs%@AE@%      outpw   %@AB@%strset%@AE@%%@TE:   8   467 01 10 08 58 @%
  19218.  
  19219. The compiler does not generate in-line code for the following functions,
  19220. although it will modify the calling convention to pass the arguments on the
  19221. floating-point chip:  %@NL@%
  19222. %@NL@%
  19223. %@TH:  13   759 01 07 08 61 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%acos%@AE@%   %@AB@%pow%@AE@%     %@AB@%coshl%@AE@%%@AB@%asin%@AE@%   %@AB@%sin%@AE@%     %@AB@%expl%@AE@%%@AB@%atan%@AE@%   %@AB@%sinh%@AE@%    %@AB@%floorl%@AE@%%@AB@%atan2%@AE@%  %@AB@%sqrt%@AE@%    %@AB@%fmodl%@AE@%%@AB@%ceil%@AE@%   %@AB@%tan%@AE@%     logl%@AB@%cos%@AE@%    %@AB@%tanh%@AE@%    %@AB@%log10l%@AE@%%@AB@%cosh%@AE@%   %@AB@%acosl%@AE@%   %@AB@%powl%@AE@%%@AB@%exp%@AE@%    %@AB@%asinl%@AE@%   sinl%@AB@%floor%@AE@%  %@AB@%atanl%@AE@%   %@AB@%sinhl%@AE@%%@AB@%fmod%@AE@%   atan2l  %@AB@%sqrtl%@AE@%%@AB@%log%@AE@%    %@AB@%ceill%@AE@%   %@AB@%tanl%@AE@%%@AB@%log10%@AE@%  cosl    %@AB@%tanhl%@AE@%%@TE:  13   759 01 07 08 61 @%
  19224.  
  19225. %@NL@%
  19226. %@2@%%@CR:C6A-B0043   @%%@AB@%B.5  Changes and Deletions%@AE@%%@EH@%%@NL@%
  19227. %@NL@%
  19228. The changes and deletions listed in this section have a high probability of
  19229. affecting existing programs.  %@NL@%
  19230. %@NL@%
  19231. %@NL@%
  19232. %@3@%%@CR:C6A-B0044   @%%@AB@%B.5.1  Deleted Features%@AE@%%@EH@%%@NL@%
  19233. %@NL@%
  19234. The %@AB@%data_seg%@AE@% pragma has been deleted.  %@NL@%
  19235. %@NL@%
  19236. The memory management routine %@AB@%sbrk%@AE@% has been deleted.  %@NL@%
  19237. %@NL@%
  19238. The compiler and tools do not run under DOS 2.1. The run-time files produced
  19239. by the compiler and linker will continue to run under DOS 2.1.  %@NL@%
  19240. %@NL@%
  19241. %@NL@%
  19242. %@3@%%@CR:C6A-B0045   @%%@AB@%B.5.2  Evaluation of Real Expressions%@AE@%%@EH@%%@NL@%
  19243. %@NL@%
  19244. Real expressions inside parentheses are now evaluated according to the
  19245. semantics of the parentheses. For example, in the expression  %@NL@%
  19246. %@NL@%
  19247. %@AS@%  ((r1 / r2) * r3)%@AE@%%@NL@%
  19248. %@NL@%
  19249. the division is performed before the multiplication. Previous versions of
  19250. the compiler might have reordered the operations.  %@NL@%
  19251. %@NL@%
  19252. %@NL@%
  19253. %@3@%%@CR:C6A-B0046   @%%@AB@%B.5.3  Default Optimizations%@AE@%%@EH@%%@NL@%
  19254. %@NL@%
  19255. Version 6.0 performs more extensive optimizations than version 5.1. This
  19256. implies that code that had aliasing but worked with the /Oa option in 5.1
  19257. might not work with version 6.0 and /Oa. Also, because of the improved
  19258. optimizations, the /Od option should be used to turn off all optimizing
  19259. before you begin debugging with CodeView.  %@NL@%
  19260. %@NL@%
  19261. %@NL@%
  19262. %@3@%%@CR:C6A-B0047   @%%@AB@%B.5.4  Sign Extension of char Arguments%@AE@%%@EH@%%@NL@%
  19263. %@NL@%
  19264. Previous versions of Microsoft C would sign-extend %@AB@%char %@AE@%arguments to %@AB@%int
  19265. %@AB@%%@AE@%size before passing them to a second function. Version 6.0 does not extend
  19266. the sign if the function is prototyped and the prototype includes a %@AB@%char%@AE@%
  19267. argument. The most-significant byte is considered undefined.  %@NL@%
  19268. %@NL@%
  19269. %@NL@%
  19270. %@3@%%@CR:C6A-B0048   @%%@AB@%B.5.5  Conditional Compilation and Signed Values%@AE@%%@EH@%%@NL@%
  19271. %@NL@%
  19272. Version 5.1 of Microsoft C treated conditional compilation expressions as
  19273. %@AB@%signed long%@AE@% values. Version 6.0 evaluates these expressions using the same
  19274. rules as expressions in C. For example,  %@NL@%
  19275. %@NL@%
  19276. %@AS@%  #if 0xFFFFFFFFL > 1UL
  19277. %@AS@%  .
  19278. %@AS@%  .
  19279. %@AS@%  .
  19280. %@AS@%  #endif%@AE@%%@NL@%
  19281. %@NL@%
  19282. The expression evaluates to be true. It was evaluated as false in version
  19283. 5.1.  %@NL@%
  19284. %@NL@%
  19285. %@NL@%
  19286. %@3@%%@CR:C6A-B0049   @%%@AB@%B.5.6  The const and volatile Qualifiers%@AE@%%@EH@%%@NL@%
  19287. %@NL@%
  19288. The %@AB@%const %@AE@% and %@AB@%volatile %@AE@%qualifiers must be placed after the type they
  19289. qualify. The declaration  %@NL@%
  19290. %@NL@%
  19291. %@AS@%  int (const *p);%@AE@%%@NL@%
  19292. %@NL@%
  19293. is now treated as a syntax error. Previous versions of the compiler would
  19294. accept such a construction.  %@NL@%
  19295. %@NL@%
  19296. The following declarations are legal:  %@NL@%
  19297. %@NL@%
  19298. %@AS@%  int const *p_ci;  /* pointer to constant int */
  19299. %@AS@%  int const (*p_ci); /* pointer to constant int */
  19300. %@AS@%  int *const cp_i;  /* constant pointer to int */
  19301. %@AS@%  int (*const cp_i); /* constant pointer to int */%@AE@%%@NL@%
  19302. %@NL@%
  19303. %@NL@%
  19304. %@3@%%@CR:C6A-B0050   @%%@AB@%B.5.7  Memory Allocation%@AE@%%@EH@%%@NL@%
  19305. %@NL@%
  19306. The %@AB@%_fmalloc %@AE@%function attempts to allocate far memory. It previously called
  19307. %@AB@%_nmalloc %@AE@%if far memory was not available. Now it returns a null pointer if
  19308. far memory isn't available, even if near memory is available.  %@NL@%
  19309. %@NL@%
  19310. %@NL@%
  19311. %@3@%%@CR:C6A-B0051   @%%@AB@%B.5.8  Memory Used by Command-Line Arguments%@AE@%%@EH@%%@NL@%
  19312. %@NL@%
  19313. Previous versions of the compiler placed the command-line argument strings
  19314. and environment strings in the near heap. Now they are allocated though
  19315. %@AB@%malloc%@AE@%, which means that they will be in far memory in compact and large
  19316. models.  %@NL@%
  19317. %@NL@%
  19318. %@NL@%
  19319. %@3@%%@CR:C6A-B0052   @%%@AB@%B.5.9  Format Specifiers in printf%@AE@%%@EH@%%@NL@%
  19320. %@NL@%
  19321. The %@AB@%printf%@AE@% format specifier modifiers %@AB@%N%@AE@%, %@AB@%F%@AE@%, %@AB@%h%@AE@%, and%@AB@% l%@AE@% have changed.  %@NL@%
  19322. %@NL@%
  19323. The specifier %@AB@%%Np%@AE@% is a synonym for %@AB@%%hp%@AE@%, but the latter is preferred.
  19324. Likewise, %@AB@%%Fp%@AE@% is a synonym for %@AB@%%lp%@AE@%.  %@NL@%
  19325. %@NL@%
  19326. For %@AB@%scanf%@AE@%, %@AB@%N%@AE@% and %@AB@%F%@AE@% refer to the distance to the object being read in; that
  19327. is, whether the pointer itself is allocated near or far. The modifiers %@AB@%h%@AE@% and%@AB@%
  19328. %@AB@%l%@AE@% refer to the size of the object (16-bit near pointer or 32-bit far
  19329. pointer). In these examples,  %@NL@%
  19330. %@NL@%
  19331. %@AS@%  scanf("%Nlp", n_fp);
  19332. %@AS@%  scanf("%Fhp", f_np);%@AE@%%@NL@%
  19333. %@NL@%
  19334. the first line reads in an address that resides in near memory (%@AS@%N%@AE@%) but holds
  19335. a 32-bit far pointer variable (%@AS@%lp%@AE@%). The second line reads in a near pointer
  19336. value (%@AS@%hp%@AE@%) into a pointer variable that resides in far memory (%@AS@%F%@AE@%).  %@NL@%
  19337. %@NL@%
  19338. %@NL@%
  19339. %@3@%%@CR:C6A-B0053   @%%@AB@%B.5.10  Functions that Return Float Values%@AE@%%@EH@%%@NL@%
  19340. %@NL@%
  19341. In Microsoft C 5.1, a prototype or definition such as  %@NL@%
  19342. %@NL@%
  19343. %@AS@%  float funcname();%@AE@%%@NL@%
  19344. %@NL@%
  19345. was interpreted as %@AS@%  %@AE@%%@NL@%
  19346. %@NL@%
  19347. %@AS@%  double funcname()%@AE@%%@NL@%
  19348. %@NL@%
  19349. Version 6.0 interprets it as %@AS@%  %@AE@%%@NL@%
  19350. %@NL@%
  19351. %@AS@%  float %@AE@%%@NL@%
  19352. %@NL@%
  19353. %@NL@%
  19354. %@NL@%
  19355. %@NL@%
  19356. %@NL@%
  19357. %@NL@%
  19358. %@CR:C6A-C0001   @%%@1@%%@AB@%Appendix C  Implementation-Defined Behavior%@AE@%%@EH@%%@NL@%
  19359. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19360. %@NL@%
  19361. The American National Standards Institute (ANSI) Standard for the C
  19362. programming language contains an appendix called "Portability Issues." The
  19363. ANSI appendix lists areas of the C language that ANSI leaves open to each
  19364. particular implementation. This appendix describes how Microsoft C handles
  19365. these implementation-defined areas of the C language.  %@NL@%
  19366. %@NL@%
  19367. This appendix follows the same order as the ANSI Standard appendix. Each
  19368. item covered includes references to the ANSI chapter and section that
  19369. explains the implementation-defined behavior.  %@NL@%
  19370. %@NL@%
  19371. ────────────────────────────────────────────────────────────────────────────%@NL@%
  19372. NOTE
  19373.  
  19374. %@AI@%This appendix describes the U.S. English-language version of the C compiler
  19375. %@AI@%only. Foreign-language implementations of Microsoft C may differ slightly.%@AE@%%@NL@%
  19376. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  19377. %@NL@%
  19378. %@NL@%
  19379. %@2@%%@CR:C6A-C0002   @%%@AB@%C.1  Translation%@AE@%%@EH@%%@NL@%
  19380. %@NL@%
  19381. %@NL@%
  19382. %@3@%%@CR:C6A-C0003   @%%@AB@%C.1.1  Diagnostics%@AE@%%@EH@%%@NL@%
  19383. %@NL@%
  19384. %@AB@%How a diagnostic is identified (2.1.1.3)%@AE@%  %@NL@%
  19385. %@NL@%
  19386. Microsoft C produces error messages in the form:  %@NL@%
  19387. %@NL@%
  19388. %@AS@%  filename(line-number) : diagnostic Cnumber message%@AE@%%@NL@%
  19389. %@NL@%
  19390. where %@AI@%filename%@AE@% is the name of the source file in which the error was
  19391. encountered; %@AI@%line-number%@AE@% is the line number at which the compiler detected
  19392. the error; %@AI@%diagnostic%@AE@% is either "error" or "warning"; %@AI@%number%@AE@% is a unique
  19393. four-digit number (preceded by a %@AB@%C%@AE@%) that identifies the error or warning;
  19394. %@AI@%message%@AE@% is an explanatory message.  %@NL@%
  19395. %@NL@%
  19396. %@NL@%
  19397. %@2@%%@CR:C6A-C0004   @%%@AB@%C.2  Environment%@AE@%%@EH@%%@NL@%
  19398. %@NL@%
  19399. %@NL@%
  19400. %@3@%%@CR:C6A-C0005   @%%@AB@%C.2.1  Arguments to main%@AE@%%@EH@%%@NL@%
  19401. %@NL@%
  19402. %@AB@%The semantics of the arguments to main (2.1.2.2)%@AE@%  %@NL@%
  19403. %@NL@%
  19404. In Microsoft C, the function called at program start-up is called %@AB@%main%@AE@%.
  19405. There is no prototype declared for %@AB@%main%@AE@%, and it can be defined with zero,
  19406. two, or three parameters:  %@NL@%
  19407. %@NL@%
  19408. %@AS@%  int main( void )
  19409. %@AS@%  int main( int argc, char *argv[] )
  19410. %@AS@%  int main( int argc, char *argv[], char *envp[] )%@AE@%%@NL@%
  19411. %@NL@%
  19412. The third line above, where %@AB@%main %@AE@%accepts three parameters, is a Microsoft
  19413. extension to the ANSI Standard. The third parameter, %@AB@%envp%@AE@%, is an array of
  19414. pointers to environment variables. The %@AB@%envp %@AE@%array is terminated by a null
  19415. pointer. See on-line help for more information about %@AB@%main %@AE@%and %@AB@%envp%@AE@%.  %@NL@%
  19416. %@NL@%
  19417. The variable %@AB@%argc%@AE@% never holds a negative value.  %@NL@%
  19418. %@NL@%
  19419. The array of strings ends with %@AB@%argv[argc]%@AE@%, which contains a null pointer.  %@NL@%
  19420. %@NL@%
  19421. All elements of the %@AB@%argv %@AE@%array are pointers to strings.  %@NL@%
  19422. %@NL@%
  19423. A program invoked with no command-line arguments will receive a value of one
  19424. for %@AB@%argc%@AE@%, as the name of the executable file is placed in %@AB@%argv[0]%@AE@%. (In DOS
  19425. versions prior to 3.0, the executable file name is not available. The letter
  19426. "C" is placed in %@AB@%argv[0]%@AE@%.) Strings pointed to by %@AB@%argv[1] %@AE@%through %@AB@%argv[argc -
  19427. %@AB@%1] %@AE@%represent program parameters.  %@NL@%
  19428. %@NL@%
  19429. The parameters %@AB@%argc %@AE@%and %@AB@%argv %@AE@%are modifiable and retain their last-stored
  19430. values between program start-up and program termination.  %@NL@%
  19431. %@NL@%
  19432. %@NL@%
  19433. %@3@%%@CR:C6A-C0006   @%%@AB@%C.2.2  Interactive Devices%@AE@%%@EH@%%@NL@%
  19434. %@NL@%
  19435. %@AB@%What constitutes an interactive device (2.1.2.3)%@AE@%  %@NL@%
  19436. %@NL@%
  19437. Microsoft C defines the keyboard and the display as interactive devices.  %@NL@%
  19438. %@NL@%
  19439. %@NL@%
  19440. %@2@%%@CR:C6A-C0007   @%%@AB@%C.3  Identifiers%@AE@%%@EH@%%@NL@%
  19441. %@NL@%
  19442. %@NL@%
  19443. %@3@%%@CR:C6A-C0008   @%%@AB@%C.3.1  Significant Characters without External Linkage%@AE@%%@EH@%%@NL@%
  19444. %@NL@%
  19445. %@AB@%The number of significant characters without external linkage (3.1.2)%@AE@%  %@NL@%
  19446. %@NL@%
  19447. Identifiers are significant to 31 characters. The compiler does not restrict
  19448. the number of characters you can use in an identifier; it simply ignores any
  19449. characters beyond the limit.  %@NL@%
  19450. %@NL@%
  19451. %@NL@%
  19452. %@3@%%@CR:C6A-C0009   @%%@AB@%C.3.2  Significant Characters with External Linkage%@AE@%%@EH@%%@NL@%
  19453. %@NL@%
  19454. %@AB@%The number of significant characters with external linkage (3.1.2)%@AE@%  %@NL@%
  19455. %@NL@%
  19456. Identifiers declared %@AB@%extern %@AE@%in programs compiled with Microsoft C are
  19457. significant to 31 characters. You can modify this default to a smaller
  19458. number using the /H (restrict length of external names) option. See on-line
  19459. help for more information on the syntax of the /H option.  %@NL@%
  19460. %@NL@%
  19461. %@NL@%
  19462. %@3@%%@CR:C6A-C0010   @%%@AB@%C.3.3  Upper- and Lowercase%@AE@%%@EH@%%@NL@%
  19463. %@NL@%
  19464. %@AB@%Whether case distinctions are significant (3.1.2)%@AE@%  %@NL@%
  19465. %@NL@%
  19466. Microsoft C treats identifiers within a compilation unit as case sensitive.
  19467. Externally linked identifiers may or may not be case sensitive, depending on
  19468. whether you use /NOIGNORECASE option when you invoke the linker. The default
  19469. for the linker is to ignore case, making externally linked identifiers case
  19470. insensitive.  %@NL@%
  19471. %@NL@%
  19472. Thus, symbols in source files are sensitive to case. By default, symbols in
  19473. object files are not.  %@NL@%
  19474. %@NL@%
  19475. Two CL command-line options affect case sensitivity:  %@NL@%
  19476. %@NL@%
  19477. %@NL@%
  19478.   1.  The /Gc (generate Pascal-style function calls) command-line option
  19479.       converts all external identifiers (including function names) to
  19480.       uppercase.%@NL@%
  19481. %@NL@%
  19482. %@STUB@%      The %@AB@%_pascal%@AE@% declarator performs the same operation on a
  19483.       function-byfunction basis.%@NL@%
  19484. %@NL@%
  19485.   2.  The /Zc (compile case insensitive) converts all identifiers (excluding
  19486.       function names) to uppercase.%@NL@%
  19487. %@NL@%
  19488. %@NL@%
  19489. %@NL@%
  19490. %@2@%%@CR:C6A-C0011   @%%@AB@%C.4  Characters%@AE@%%@EH@%%@NL@%
  19491. %@NL@%
  19492. %@NL@%
  19493. %@3@%%@CR:C6A-C0012   @%%@AB@%C.4.1  The ASCII Character Set%@AE@%%@EH@%%@NL@%
  19494. %@NL@%
  19495. %@AB@%Members of source and execution character sets (2.2.1)%@AE@%  %@NL@%
  19496. %@NL@%
  19497. The source character set is the set of legal characters that can appear in
  19498. source files. For Microsoft C, the source character set is the standard
  19499. ASCII character set. Figure C.1 contains an ASCII table.  %@NL@%
  19500. %@NL@%
  19501. ────────────────────────────────────────────────────────────────────────────%@NL@%
  19502. %@AU@%WARNING%@AE@%%@NL@%
  19503. %@NL@%
  19504. Because keyboard and console drivers can remap the character set, programs
  19505. intended for international distribution should check the country code.%@NL@%
  19506. ────────────────────────────────────────────────────────────────────────────%@NL@%
  19507. %@NL@%
  19508. %@NL@%
  19509. %@3@%%@CR:C6A-C0013   @%%@AB@%C.4.2  Multibyte Characters%@AE@%%@EH@%%@NL@%
  19510. %@NL@%
  19511. %@AB@%Shift states for multibyte characters (2.2.1)%@AE@%  %@NL@%
  19512. %@NL@%
  19513. Multibyte characters are used by some implementations to represent
  19514. foreignlanguage characters not represented in the base character set.
  19515. Microsoft C 6.0 does not support multibyte characters.  %@NL@%
  19516. %@NL@%
  19517. %@NL@%
  19518. %@3@%%@CR:C6A-C0014   @%%@AB@%C.4.3  Bits per Character%@AE@%%@EH@%%@NL@%
  19519. %@NL@%
  19520. %@AB@%Number of bits in a character (2.2.4.2)%@AE@%  %@NL@%
  19521. %@NL@%
  19522. The number of bits in a character is represented by the manifest constant
  19523. %@AB@%CHAR_BIT%@AE@%. The LIMITS.H file defines %@AB@%CHAR_BIT%@AE@% as 8.  %@NL@%
  19524. %@NL@%
  19525. %@NL@%
  19526. %@3@%%@CR:C6A-C0015   @%%@AB@%C.4.4  Character Sets%@AE@%%@EH@%%@NL@%
  19527. %@NL@%
  19528. %@AB@%Mapping members of the source character set (3.1.3.4)%@AE@%  %@NL@%
  19529. %@NL@%
  19530. The source character set and execution character set include the ANSI ASCII
  19531. characters listed in Table C.1. Escape sequences are also shown in Table
  19532. C.1.  %@NL@%
  19533. %@NL@%
  19534. %@AB@%Table   %@AB@%C.1%@AE@%%@AE@%
  19535.  
  19536. %@TH:  13   657 02 17 18 41 @%Escape Sequence  Character         ASCII Value%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%\a               Alert/bell        7\b               Backspace         8\f               Form feed         12\n               Newline           10\r               Carriage return   13\t               Horizontal tab    9\v               Vertical tab      11\"               Double quotation  34\%@AS@%'%@AE@%               Single quotation  39\\               Backslash         92%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  13   657 02 17 18 41 @%
  19537.  
  19538. %@NL@%
  19539. %@3@%%@CR:C6A-C0016   @%%@AB@%C.4.5  Unrepresented Character Constants%@AE@%%@EH@%%@NL@%
  19540. %@NL@%
  19541. %@AB@%The value of an integer character constant that contains a character or
  19542. %@AB@%escape sequence not represented in the basic execution character set or the
  19543. %@AB@%extended character set for a wide character constant (3.1.3.4)%@AE@%  %@NL@%
  19544. %@NL@%
  19545. Microsoft C does not support wide characters.  %@NL@%
  19546. %@NL@%
  19547. %@NL@%
  19548. %@3@%%@CR:C6A-C0017   @%%@AB@%C.4.6  Wide Characters%@AE@%%@EH@%%@NL@%
  19549. %@NL@%
  19550. %@AB@%The value of an integer character constant that contains more than one
  19551. %@AB@%character or a wide character constant that contains more than one multibyte
  19552. %@AB@%character (3.1.3.4)%@AE@%  %@NL@%
  19553. %@NL@%
  19554. Microsoft C does not support wide characters or multibyte characters.  %@NL@%
  19555. %@NL@%
  19556. %@NL@%
  19557. %@3@%%@CR:C6A-C0018   @%%@AB@%C.4.7  Converting Multibyte Characters%@AE@%%@EH@%%@NL@%
  19558. %@NL@%
  19559. %@AB@%The current locale used to convert multibyte characters into corresponding
  19560. %@AB@%wide characters (codes) for a wide character constant (3.1.3.4)  %@AE@%%@NL@%
  19561. %@NL@%
  19562. Microsoft C does not support multibyte characters.  %@NL@%
  19563. %@NL@%
  19564. %@NL@%
  19565. %@3@%%@CR:C6A-C0019   @%%@AB@%C.4.8  Range of char Values%@AE@%%@EH@%%@NL@%
  19566. %@NL@%
  19567. %@AB@%Whether a "plain" char has the same range of values as a signed char or an
  19568. %@AB@%unsigned char (3.2.1.1)%@AE@%  %@NL@%
  19569. %@NL@%
  19570. All character values range from 0x00 to 0xFF, signed or unsigned. If a %@AB@%char%@AE@%
  19571. is not explicitly marked as %@AB@%signed%@AE@% or %@AB@%unsigned%@AE@%, it defaults to the %@AB@%signed%@AE@%
  19572. type.  %@NL@%
  19573. %@NL@%
  19574. The CL option /J changes the default from %@AB@%signed%@AE@% to %@AB@%unsigned%@AE@%.  %@NL@%
  19575. %@NL@%
  19576. %@NL@%
  19577. %@2@%%@CR:C6A-C0020   @%%@AB@%C.5  Integers%@AE@%%@EH@%%@NL@%
  19578. %@NL@%
  19579. %@NL@%
  19580. %@3@%%@CR:C6A-C0021   @%%@AB@%C.5.1  Range of Integer Values%@AE@%%@EH@%%@NL@%
  19581. %@NL@%
  19582. %@AB@%The representations and sets of values of the various types of integers
  19583. %@AB@%(3.1.2.5)%@AE@%  %@NL@%
  19584. %@NL@%
  19585. Short integers contain 16 bits (two bytes). Long integers contain 32 bits
  19586. (four bytes). Signed integers are represented in two's-complement form. The
  19587. mostsignificant bit holds the sign: 1 for negative, 0 for positive and zero.
  19588. The values are listed below:  %@NL@%
  19589. %@NL@%
  19590. %@AB@%Type%@AE@%                              %@AB@%Minimum and Maximum%@AE@%
  19591. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19592. %@AB@%unsigned short%@AE@%                    0 to 65535
  19593.  
  19594. %@AB@%signed short%@AE@%                      -32768 to 32767
  19595.  
  19596. %@AB@%unsigned long%@AE@%                     0 to 4294967295
  19597.  
  19598. %@AB@%signed long%@AE@%                       -2147483648 to 2147483647
  19599.  
  19600. %@NL@%
  19601. %@3@%%@CR:C6A-C0022   @%%@AB@%C.5.2  Demotion of Integers%@AE@%%@EH@%%@NL@%
  19602. %@NL@%
  19603. %@AB@%The result of converting an integer to a shorter signed integer, or the
  19604. %@AB@%result of converting an unsigned integer to a signed integer of equal
  19605. %@AB@%length, if the value cannot be represented (3.2.1.2)%@AE@%  %@NL@%
  19606. %@NL@%
  19607. When a %@AB@%long%@AE@% integer is cast to a %@AB@%short%@AE@%, or a %@AB@%short%@AE@% is cast to a %@AB@%char%@AE@%, the
  19608. least significant bytes are retained.  %@NL@%
  19609. %@NL@%
  19610. For example, this line  %@NL@%
  19611. %@NL@%
  19612. %@AS@%  short x = (short)0x12345678L;%@AE@%%@NL@%
  19613. %@NL@%
  19614. assigns the value 0x5678 to %@AS@% x%@AE@%, and this line  %@NL@%
  19615. %@NL@%
  19616. %@AS@%  char y = (char)0x1234;%@AE@%%@NL@%
  19617. %@NL@%
  19618. assigns the value 0x34 to %@AS@% y%@AE@%.  %@NL@%
  19619. %@NL@%
  19620. When signed variables are converted to unsigned and vice versa, the bit
  19621. patterns remain the same. For example, casting -2 (0xFE) to an unsigned
  19622. value yields 254 (also 0xFE).  %@NL@%
  19623. %@NL@%
  19624. %@NL@%
  19625. %@3@%%@CR:C6A-C0023   @%%@AB@%C.5.3  Signed Bitwise Operations%@AE@%%@EH@%%@NL@%
  19626. %@NL@%
  19627. %@AB@%The results of bitwise operations on signed integers (3.3)%@AE@%  %@NL@%
  19628. %@NL@%
  19629. Bitwise operations on signed integers work the same as bitwise operations on
  19630. unsigned integers. For example, %@AS@% -16 & 99 %@AE@% can be expressed in binary as  %@NL@%
  19631. %@NL@%
  19632. %@AS@%  11111111 11110000
  19633. %@AS@%  & 00000000 01100011
  19634. %@AS@%    -----------------
  19635. %@AS@%    00000000 01100000%@AE@%%@NL@%
  19636. %@NL@%
  19637. The result of the bitwise AND is 96.  %@NL@%
  19638. %@NL@%
  19639. %@NL@%
  19640. %@3@%%@CR:C6A-C0024   @%%@AB@%C.5.4  Remainders%@AE@%%@EH@%%@NL@%
  19641. %@NL@%
  19642. %@AB@%The sign of the remainder on integer division (3.3.5)%@AE@%  %@NL@%
  19643. %@NL@%
  19644. The sign of the remainder is the same as the sign of the dividend. For
  19645. example,  %@NL@%
  19646. %@NL@%
  19647. %@AS@%  50 / -6 == -8
  19648. %@AS@%   50 % -6 ==  2
  19649. %@AS@%  -50 /  6 == -8
  19650. %@AS@%  -50 %  6 == -2%@AE@%%@NL@%
  19651. %@NL@%
  19652. %@NL@%
  19653. %@3@%%@CR:C6A-C0025   @%%@AB@%C.5.5  Right Shifts%@AE@%%@EH@%%@NL@%
  19654. %@NL@%
  19655. %@AB@%The result of a right shift of a negative-value signed integral type
  19656. %@AB@%(3.3.7)%@AE@%  %@NL@%
  19657. %@NL@%
  19658. Shifting a negative value to the right yields half the absolute value,
  19659. rounded down. For example, -253 (binary 11111111 00000011) shifted right one
  19660. bit produces -127 (binary 11111111 10000001). A %@AI@%positive%@AE@% 253 shifts right to
  19661. produce +126.  %@NL@%
  19662. %@NL@%
  19663. Right shifts preserve the sign bit. When a signed integer shifts right, the
  19664. mostsignificant bit remains set. When an unsigned integer shifts right, the
  19665. mostsignificant bit is cleared. Thus, if 0xF000 is signed, a right shift
  19666. produces 0xF800. If 0xF000 is unsigned, the result is 0x7800.  %@NL@%
  19667. %@NL@%
  19668. Shifting a positive number right sixteen times produces 0x0000. Shifting a
  19669. negative number right sixteen times produces 0xFFFF.  %@NL@%
  19670. %@NL@%
  19671. %@NL@%
  19672. %@2@%%@CR:C6A-C0026   @%%@AB@%C.6  Floating-Point Math%@AE@%%@EH@%%@NL@%
  19673. %@NL@%
  19674. %@NL@%
  19675. %@3@%%@CR:C6A-C0027   @%%@AB@%C.6.1  Values%@AE@%%@EH@%%@NL@%
  19676. %@NL@%
  19677. %@AB@%The representations and sets of values of the various types of
  19678. %@AB@%floating-point numbers (3.1.2.5)%@AE@%  %@NL@%
  19679. %@NL@%
  19680. The %@AB@%float%@AE@% type contains 32 bits: 1 for the sign, 8 for the exponent, and 23
  19681. for the mantissa. Its range is +/- 3.4E38 with at least 7 digits of
  19682. precision.  %@NL@%
  19683. %@NL@%
  19684. The %@AB@%double%@AE@% type contains 64 bits: 1 for the sign, 11 for the exponent, and
  19685. 52 for the mantissa. Its range is +/- 1.7E308 with at least 15 digits of
  19686. precision.  %@NL@%
  19687. %@NL@%
  19688. The %@AB@%long double%@AE@% type is new to Version 6.0 of Microsoft C. It contains 80
  19689. bits: 1 for the sign, 15 for the exponent, and 64 for the mantissa. Its
  19690. range is +/- 1.2E4932 with at least 17 digits of precision.  %@NL@%
  19691. %@NL@%
  19692. %@NL@%
  19693. %@3@%%@CR:C6A-C0028   @%%@AB@%C.6.2  Casting Integers to Floating-Point Values%@AE@%%@EH@%%@NL@%
  19694. %@NL@%
  19695. %@AB@%The direction of truncation when an integral number is converted to a
  19696. %@AB@%floating-point number that cannot exactly represent the original value
  19697. %@AB@%(3.2.1.3)%@AE@%  %@NL@%
  19698. %@NL@%
  19699. When an integral number is cast to a floating-point value that cannot
  19700. exactly represent the value, the value is rounded (up or down) to the
  19701. nearest suitable value.  %@NL@%
  19702. %@NL@%
  19703. For example, casting an %@AB@%unsigned long%@AE@% (with 32 bits of precision) to a %@AB@%float%@AE@%
  19704. (whose mantissa has 23 bits of precision) rounds the number to the nearest
  19705. multiple of 256. The %@AB@%long%@AE@% values 4294966913 - 4294967167 are all rounded to
  19706. the %@AB@%float%@AE@% value 4294967040.  %@NL@%
  19707. %@NL@%
  19708. %@NL@%
  19709. %@3@%%@CR:C6A-C0029   @%%@AB@%C.6.3  Truncation of Floating-Point Values%@AE@%%@EH@%%@NL@%
  19710. %@NL@%
  19711. %@AB@%The direction of truncation or rounding when a floating-point number is
  19712. %@AB@%converted to a narrower floating-point number (3.2.1.4)%@AE@%  %@NL@%
  19713. %@NL@%
  19714. When an underflow occurs, the value of a floating-point variable is rounded
  19715. down to zero. An overflow causes a run-time math error.  %@NL@%
  19716. %@NL@%
  19717. %@NL@%
  19718. %@2@%%@CR:C6A-C0030   @%%@AB@%C.7  Arrays and Pointers%@AE@%%@EH@%%@NL@%
  19719. %@NL@%
  19720. %@NL@%
  19721. %@3@%%@CR:C6A-C0031   @%%@AB@%C.7.1  Largest Array Size%@AE@%%@EH@%%@NL@%
  19722. %@NL@%
  19723. %@AB@%The type of integer required to hold the maximum size of an array─that is,
  19724. %@AB@%the size of size_t (3.3.3.4, 4.1.1)%@AE@%  %@NL@%
  19725. %@NL@%
  19726. The %@AB@%size_t%@AE@% typedef is an %@AB@%unsigned short%@AE@%, with the range 0x0000 to 0xFFFF.
  19727. Huge arrays can exceed this limit if they contain more than 65,535 elements.
  19728. Arithmetic operations on huge arrays should therefore cast %@AB@%size_t%@AE@% and the
  19729. results of an arithmetic operations on pointers to %@AB@%unsigned long%@AE@%.  %@NL@%
  19730. %@NL@%
  19731. %@NL@%
  19732. %@3@%%@CR:C6A-C0032   @%%@AB@%C.7.2  Casting Pointers%@AE@%%@EH@%%@NL@%
  19733. %@NL@%
  19734. %@AB@%The result of casting a pointer to an integer or vice versa (3.3.4)%@AE@%  %@NL@%
  19735. %@NL@%
  19736. Near pointers are the same size as short integers; casting near to short (or
  19737. short to near) has no immediate effect on the value.  %@NL@%
  19738. %@NL@%
  19739. Far pointers and huge pointers are the same size as long integers. Casting
  19740. far/huge to long (or long to far/huge) has no immediate effect on the value.
  19741. %@NL@%
  19742. %@NL@%
  19743. When a near pointer is cast to a long, the 16-bit value is "normalized,"
  19744. which means the segment (usually DS) and offset are combined to produce a
  19745. 32-bit memory location.  %@NL@%
  19746. %@NL@%
  19747. When a far or huge pointer is cast to a short, the long value is truncated
  19748. to a short.  %@NL@%
  19749. %@NL@%
  19750. The compiler normalizes based pointers when necessary, unless the based
  19751. pointer is a constant zero, in which case it is assumed to be a null
  19752. pointer. See Chapter 13, "Writing Portable Programs," for more information
  19753. about based pointers.  %@NL@%
  19754. %@NL@%
  19755. %@NL@%
  19756. %@3@%%@CR:C6A-C0033   @%%@AB@%C.7.3  Pointer Subtraction%@AE@%%@EH@%%@NL@%
  19757. %@NL@%
  19758. %@AB@%The type of integer required to hold the difference between two pointers to
  19759. %@AB@%elements of the same array, ptrdiff_t (3.3.6, 4.1.1)%@AE@%  %@NL@%
  19760. %@NL@%
  19761. A %@AB@%ptrdiff_t%@AE@% is a signed integer in the range -32768 to 32767, with one
  19762. exception. Because huge pointers can address more than 64K of memory,
  19763. subtracting one huge pointer from another can yield a result that is a long
  19764. integer. The result of subtracting two huge pointers should be cast to a
  19765. long.  %@NL@%
  19766. %@NL@%
  19767. The compiler normalizes based pointers when necessary. In most cases, based
  19768. pointers are treated as far pointers.  %@NL@%
  19769. %@NL@%
  19770. %@NL@%
  19771. %@2@%%@CR:C6A-C0034   @%%@AB@%C.8  Registers%@AE@%%@EH@%%@NL@%
  19772. %@NL@%
  19773. %@NL@%
  19774. %@3@%%@CR:C6A-C0035   @%%@AB@%C.8.1  Availability of Registers%@AE@%%@EH@%%@NL@%
  19775. %@NL@%
  19776. %@AB@%The extent to which objects can actually be placed in registers by use of
  19777. %@AB@%the register storage-class specifier (3.5.1)%@AE@%  %@NL@%
  19778. %@NL@%
  19779. Two registers, SI and DI, are available in Microsoft C. Register variables
  19780. with a type that has 16 bits may be allocated in these registers.  %@NL@%
  19781. %@NL@%
  19782. %@NL@%
  19783. %@2@%%@CR:C6A-C0036   @%%@AB@%C.9  Structures, Unions, Enumerations, and Bit Fields%@AE@%%@EH@%%@NL@%
  19784. %@NL@%
  19785. %@NL@%
  19786. %@3@%%@CR:C6A-C0037   @%%@AB@%C.9.1  Improper Access to a Union%@AE@%%@EH@%%@NL@%
  19787. %@NL@%
  19788. %@AB@%A member of a union object is accessed using a member of a different type
  19789. %@AB@%(3.3.2.3)%@AE@%  %@NL@%
  19790. %@NL@%
  19791. If a union of two types is declared and one value is stored, but the union
  19792. is accessed with the other type, the results are unreliable.  %@NL@%
  19793. %@NL@%
  19794. For example, a union of %@AB@%float%@AE@% and %@AB@%int%@AE@% is declared. A %@AB@%float%@AE@% value is stored,
  19795. but the program later accesses the value as an %@AB@%int%@AE@%. In such a situation, the
  19796. value would depend on the internal storage of %@AB@%float%@AE@% values. The integer
  19797. value would not be reliable.  %@NL@%
  19798. %@NL@%
  19799. %@NL@%
  19800. %@3@%%@CR:C6A-C0038   @%%@AB@%C.9.2  Sign of Bit Fields%@AE@%%@EH@%%@NL@%
  19801. %@NL@%
  19802. %@AB@%Whether a "plain" int field is treated as a signed int bit field or as an
  19803. %@AB@%unsigned int bit field (3.5.2.1)%@AE@%  %@NL@%
  19804. %@NL@%
  19805. Bit fields can be signed or unsigned. Plain bit fields are treated as
  19806. signed.  %@NL@%
  19807. %@NL@%
  19808. %@NL@%
  19809. %@3@%%@CR:C6A-C0039   @%%@AB@%C.9.3  Storage of Bit Fields%@AE@%%@EH@%%@NL@%
  19810. %@NL@%
  19811. %@AB@%The order of allocation of bit fields within an int (3.5.2.1)%@AE@%  %@NL@%
  19812. %@NL@%
  19813. Bit fields are allocated within a 16-bit integer from least-significant to
  19814. mostsignificant bit. In the following code,  %@NL@%
  19815. %@NL@%
  19816. %@AS@%  struct mybitfields
  19817. %@AS@%  {
  19818. %@AS@%     unsigned a : 4;
  19819. %@AS@%     unsigned b : 5;
  19820. %@AS@%     unsigned c : 7;
  19821. %@AS@%  } test;
  19822. %@AS@%  
  19823. %@AS@%  void main( void )
  19824. %@AS@%  {
  19825. %@AS@%     test.a = 2;
  19826. %@AS@%     test.b = 31;
  19827. %@AS@%     test.c = 0;
  19828. %@AS@%  }%@AE@%%@NL@%
  19829. %@NL@%
  19830. the bits would be arranged as follows:  %@NL@%
  19831. %@NL@%
  19832. %@AS@%  00000001 11110010
  19833. %@AS@%  cccccccb bbbbaaaa%@AE@%%@NL@%
  19834. %@NL@%
  19835. Since the 80%@AI@%x%@AE@%86 processors store the low byte of integer values before the
  19836. high byte, the integer 0x01F2 above would be stored in physical memory as
  19837. 0xF2 followed by 0x01.  %@NL@%
  19838. %@NL@%
  19839. %@NL@%
  19840. %@3@%%@CR:C6A-C0040   @%%@AB@%C.9.4  Alignment of Bit Fields%@AE@%%@EH@%%@NL@%
  19841. %@NL@%
  19842. %@AB@%Whether a bit field can straddle a storage-unit boundary (3.5.2.1)%@AE@%  %@NL@%
  19843. %@NL@%
  19844. Bit fields default to size %@AB@%short%@AE@%, which can cross a byte boundary (see
  19845. Section C.9.3 above) but not a 16-bit boundary. If the size and location of
  19846. a bit field would cause it to overflow the current integer, the field is
  19847. moved to the beginning of the next available integer.  %@NL@%
  19848. %@NL@%
  19849. If a bit field is declared as a %@AB@%long%@AE@%, it can hold up to 32 bits.  %@NL@%
  19850. %@NL@%
  19851. In either case, an individual field cannot cross a 16- or 32-bit boundary.  %@NL@%
  19852. %@NL@%
  19853. %@NL@%
  19854. %@3@%%@CR:C6A-C0041   @%%@AB@%C.9.5  The enum Type%@AE@%%@EH@%%@NL@%
  19855. %@NL@%
  19856. %@AB@%The integer type chosen to represent the values of an enumeration type
  19857. %@AB@%(3.5.2.2)%@AE@%  %@NL@%
  19858. %@NL@%
  19859. A variable declared as %@AB@%enum%@AE@% is a signed short integer.  %@NL@%
  19860. %@NL@%
  19861. %@NL@%
  19862. %@2@%%@CR:C6A-C0042   @%%@AB@%C.10  Qualifiers%@AE@%%@EH@%%@NL@%
  19863. %@NL@%
  19864. %@NL@%
  19865. %@3@%%@CR:C6A-C0043   @%%@AB@%C.10.1  Access to Volatile Objects%@AE@%%@EH@%%@NL@%
  19866. %@NL@%
  19867. %@AB@%What constitutes an access to an object that has volatile-qualified type
  19868. %@AB@%(3.5.3)%@AE@%  %@NL@%
  19869. %@NL@%
  19870. Any reference to a volatile-qualified type is an access.  %@NL@%
  19871. %@NL@%
  19872. %@NL@%
  19873. %@2@%%@CR:C6A-C0044   @%%@AB@%C.11  Declarators%@AE@%%@EH@%%@NL@%
  19874. %@NL@%
  19875. %@NL@%
  19876. %@3@%%@CR:C6A-C0045   @%%@AB@%C.11.1  Maximum Number%@AE@%%@EH@%%@NL@%
  19877. %@NL@%
  19878. %@AB@%The maximum number of declarators that can modify an arithmetic, structure,
  19879. %@AB@%or union type (3.5.4)%@AE@%  %@NL@%
  19880. %@NL@%
  19881. Microsoft C does not limit the number of declarators. The number is limited
  19882. only by available memory.  %@NL@%
  19883. %@NL@%
  19884. %@NL@%
  19885. %@2@%%@CR:C6A-C0046   @%%@AB@%C.12  Statements%@AE@%%@EH@%%@NL@%
  19886. %@NL@%
  19887. %@NL@%
  19888. %@3@%%@CR:C6A-C0047   @%%@AB@%C.12.1  Limits on Switch Statements%@AE@%%@EH@%%@NL@%
  19889. %@NL@%
  19890. %@AB@%The maximum number of case values in a switch statement (3.6.4.2)%@AE@%  %@NL@%
  19891. %@NL@%
  19892. Microsoft C does not limit the number of %@AB@%case%@AE@% values in a %@AB@%switch%@AE@% statement.
  19893. The number is limited only by available memory.  %@NL@%
  19894. %@NL@%
  19895. %@NL@%
  19896. %@2@%%@CR:C6A-C0048   @%%@AB@%C.13  Preprocessing Directives%@AE@%%@EH@%%@NL@%
  19897. %@NL@%
  19898. %@NL@%
  19899. %@3@%%@CR:C6A-C0049   @%%@AB@%C.13.1  Character Constants and Conditional Inclusion%@AE@%%@EH@%%@NL@%
  19900. %@NL@%
  19901. %@AB@%Whether the value of a single-character character constant in a constant
  19902. %@AB@%expression that controls conditional inclusion matches the value of the same
  19903. %@AB@%character constant in the execution character set. Whether such a character
  19904. %@AB@%constant can have a negative value (3.8.1)%@AE@%  %@NL@%
  19905. %@NL@%
  19906. The character set used in preprocessor statements is the same as the
  19907. execution character set. The preprocessor recognizes negative character
  19908. values.  %@NL@%
  19909. %@NL@%
  19910. %@NL@%
  19911. %@3@%%@CR:C6A-C0050   @%%@AB@%C.13.2  Including Bracketed File Names%@AE@%%@EH@%%@NL@%
  19912. %@NL@%
  19913. %@AB@%The method for locating includable source files (3.8.2)%@AE@%  %@NL@%
  19914. %@NL@%
  19915. The preprocessor first searches the directories specified by the CL option
  19916. /I. If the /I option is not present or if it fails, the preprocessor uses
  19917. the INCLUDE environment variable to find any include files within angle
  19918. brackets. If more than one directory appears as part of the /I option or
  19919. within the INCLUDE variable, the preprocessor searches them in the order
  19920. they appear.  %@NL@%
  19921. %@NL@%
  19922. For example, the command  %@NL@%
  19923. %@NL@%
  19924. %@AS@%  CL /ID:\MSC\INCLUDE MYPROG.C%@AE@%%@NL@%
  19925. %@NL@%
  19926. causes the preprocessor to search the directory D:\MSC\INCLUDE for include
  19927. files such as STDIO.H.  %@NL@%
  19928. %@NL@%
  19929. The commands  %@NL@%
  19930. %@NL@%
  19931. %@AS@%  SET INCLUDE = D:\MSC\INCLUDE
  19932. %@AS@%  CL MYPROG.C%@AE@%%@NL@%
  19933. %@NL@%
  19934. have a similar effect.  %@NL@%
  19935. %@NL@%
  19936. If both sets of searches fail, a fatal error is generated.  %@NL@%
  19937. %@NL@%
  19938. %@NL@%
  19939. %@3@%%@CR:C6A-C0051   @%%@AB@%C.13.3  Including Quoted File Names%@AE@%%@EH@%%@NL@%
  19940. %@NL@%
  19941. %@AB@%The support for quoted names for includable source files (3.8.2)%@AE@%  %@NL@%
  19942. %@NL@%
  19943. If the file name is fully specified, with a path that includes a colon (for
  19944. example, F:\C6\SPECIAL\INCL\ORANGE.H), the preprocessor follows the path.  %@NL@%
  19945. %@NL@%
  19946. If the file name is not fully specified, the preprocessor searches the
  19947. directory of the file that included it. If the file is not found there, the
  19948. preprocessor searches the parent directory, the parent's parent, and so on,
  19949. terminating with the root directory.  %@NL@%
  19950. %@NL@%
  19951. If the include file is not found in any of those directories, the rules for
  19952. bracketed file names apply.  %@NL@%
  19953. %@NL@%
  19954. %@NL@%
  19955. %@3@%%@CR:C6A-C0052   @%%@AB@%C.13.4  Character Sequences%@AE@%%@EH@%%@NL@%
  19956. %@NL@%
  19957. %@AB@%The mapping of source file character sequences (3.8.2)%@AE@%  %@NL@%
  19958. %@NL@%
  19959. Preprocessor statements use the same character set as source file statements
  19960. with the exception that escape sequences are not supported.  %@NL@%
  19961. %@NL@%
  19962. Thus, to specify a path for an include file, use only one backslash:  %@NL@%
  19963. %@NL@%
  19964. %@AS@%  #include "path1\path2\myfile"%@AE@%%@NL@%
  19965. %@NL@%
  19966. Within source code, two backslashes are necessary:  %@NL@%
  19967. %@NL@%
  19968. %@AS@%  fil = fopen( "path1\\path2\\myfile", "rt" );%@AE@%%@NL@%
  19969. %@NL@%
  19970. %@NL@%
  19971. %@3@%%@CR:C6A-C0053   @%%@AB@%C.13.5  Pragmas%@AE@%%@EH@%%@NL@%
  19972. %@NL@%
  19973. %@AB@%The behavior on each recognized #pragma directive (3.8.6)%@AE@%  %@NL@%
  19974. %@NL@%
  19975. The following pragmas are defined in the %@AI@%Microsoft C Reference%@AE@%:  %@NL@%
  19976. %@NL@%
  19977. %@AB@%#pragma alloc_text%@AE@%                %@AB@%#pragma optimize%@AE@%
  19978. %@AB@%#pragma check_pointer%@AE@%             %@AB@%#pragma pack%@AE@%
  19979. %@AB@%#pragma check_stack%@AE@%               %@AB@%#pragma page%@AE@%
  19980. %@AB@%#pragma comment%@AE@%                   %@AB@%#pragma pagesize%@AE@%
  19981. %@AB@%#pragma function%@AE@%                  %@AB@%#pragma same_seg%@AE@%
  19982. %@AB@%#pragma intrinsic%@AE@%                 %@AB@%#pragma skip%@AE@%
  19983. %@AB@%#pragma linesize%@AE@%                  %@AB@%#pragma subtitle%@AE@%
  19984. %@AB@%#pragma loop_opt%@AE@%                  %@AB@%#pragma title%@AE@%
  19985. %@AB@%#pragma message%@AE@%                   
  19986.  
  19987. %@NL@%
  19988. %@3@%%@CR:C6A-C0054   @%%@AB@%C.13.6  Default Date and Time%@AE@%%@EH@%%@NL@%
  19989. %@NL@%
  19990. %@AB@%The definitions for _DATE_ and _TIME_ when, respectively, the date and time
  19991. %@AB@%of translation are not available (3.8.8)%@AE@%  %@NL@%
  19992. %@NL@%
  19993. When a hardware clock is not accessible, the default values for _DATE_ and
  19994. _TIME_ are Friday, May 3, 1957 and 5:00 PM.  %@NL@%
  19995. %@NL@%
  19996. %@NL@%
  19997. %@2@%%@CR:C6A-C0055   @%%@AB@%C.14  Library Functions%@AE@%%@EH@%%@NL@%
  19998. %@NL@%
  19999. %@NL@%
  20000. %@3@%%@CR:C6A-C0056   @%%@AB@%C.14.1  NULL Macro%@AE@%%@EH@%%@NL@%
  20001. %@NL@%
  20002. %@AB@%The null pointer constant to which the macro NULL expands (4.1.5)%@AE@%  %@NL@%
  20003. %@NL@%
  20004. Several include files define the NULL macro as %@AS@% ((void *)0)%@AE@%.  %@NL@%
  20005. %@NL@%
  20006. %@NL@%
  20007. %@3@%%@CR:C6A-C0057   @%%@AB@%C.14.2  Diagnostic Printed by the assert Function%@AE@%%@EH@%%@NL@%
  20008. %@NL@%
  20009. %@AB@%The diagnostic printed by and the termination behavior of the assert
  20010. %@AB@%function (4.2)%@AE@%  %@NL@%
  20011. %@NL@%
  20012. The%@AB@% assert %@AE@%function prints a diagnostic message and calls the abort routine
  20013. if the expression is false (0). The diagnostic message has the form  %@NL@%
  20014. %@NL@%
  20015. Assertion failed: [%@AI@%expression%@AE@%], file [%@AI@%filename%@AE@%], line [%@AI@%linenumber%@AE@%]  %@NL@%
  20016. %@NL@%
  20017. where %@AI@%filename %@AE@%is the name of the source file and %@AI@%linenumber %@AE@%is the line
  20018. number of the assertion that failed in the source file. No action is taken
  20019. if%@AI@% expression%@AE@% is true (nonzero).  %@NL@%
  20020. %@NL@%
  20021. %@NL@%
  20022. %@3@%%@CR:C6A-C0058   @%%@AB@%C.14.3  Character Testing%@AE@%%@EH@%%@NL@%
  20023. %@NL@%
  20024. %@AB@%The sets of characters tested for by the isalnum, isalpha, iscntrl, islower,
  20025. %@AB@%isprint, and isupper functions (4.3.1)%@AE@%  %@NL@%
  20026. %@NL@%
  20027. %@AB@%Function%@AE@%                          %@AB@%Tests For%@AE@%
  20028. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20029. %@AB@%isalnum%@AE@%                           Characters 0 - 9, A-Z, a-z
  20030.                                   ASCII 48-57, 65-90, 97-122
  20031.  
  20032. %@AB@%isalpha%@AE@%                           Characters A-Z, a-z
  20033.                                   ASCII 65-90, 97-122
  20034.  
  20035. %@AB@%iscntrl%@AE@%                           ASCII 0 -31, 127
  20036.  
  20037. %@AB@%islower%@AE@%                           Characters a-z
  20038.                                   ASCII 97-122
  20039.  
  20040. %@AB@%isprint%@AE@%                           Characters A-Z, a-z, 0 - 9, punctuation,
  20041.                                   space
  20042.                                   ASCII 32-126
  20043.  
  20044. %@AB@%isupper%@AE@%                           Characters A-Z
  20045.                                   ASCII 65-90
  20046.  
  20047. %@NL@%
  20048. %@3@%%@CR:C6A-C0059   @%%@AB@%C.14.4  Domain Errors%@AE@%%@EH@%%@NL@%
  20049. %@NL@%
  20050. %@AB@%The values returned by the mathematics functions on domain errors (4.5.1)%@AE@%  %@NL@%
  20051. %@NL@%
  20052. The ERRNO.H file defines the domain error constant EDOM as 33.  %@NL@%
  20053. %@NL@%
  20054. %@NL@%
  20055. %@3@%%@CR:C6A-C0060   @%%@AB@%C.14.5  Underflow of Floating-Point Values%@AE@%%@EH@%%@NL@%
  20056. %@NL@%
  20057. %@AB@%Whether the mathematics functions set the integer expression errno to the
  20058. %@AB@%value of the macro ERANGE on underflow range errors (4.5.1)%@AE@%  %@NL@%
  20059. %@NL@%
  20060. A floating-point underflow does not set the expression %@AB@%errno%@AE@% to ERANGE. When
  20061. a value approaches zero and eventually underflows, the value is set to zero.
  20062. %@NL@%
  20063. %@NL@%
  20064. %@NL@%
  20065. %@3@%%@CR:C6A-C0061   @%%@AB@%C.14.6  The fmod Function%@AE@%%@EH@%%@NL@%
  20066. %@NL@%
  20067. %@AB@%Whether a domain error occurs or zero is returned when the fmod function has
  20068. %@AB@%a second argument of zero (4.5.6.4)%@AE@%  %@NL@%
  20069. %@NL@%
  20070. When the %@AB@%fmod%@AE@% function has a second argument of zero, the function returns
  20071. zero.  %@NL@%
  20072. %@NL@%
  20073. %@NL@%
  20074. %@3@%%@CR:C6A-C0062   @%%@AB@%C.14.7  The signal Function%@AE@%%@EH@%%@NL@%
  20075. %@NL@%
  20076. %@AB@%The set of signals for the signal function (4.7.1.1)%@AE@%  %@NL@%
  20077. %@NL@%
  20078. The first argument passed to %@AB@%signal%@AE@% must be one of the symbolic constants
  20079. listed below. The constants are defined in SIGNAL.H. Also listed is the
  20080. operating mode support for each signal.  %@NL@%
  20081. %@NL@%
  20082. %@AB@%Signal Argument%@AE@%                   %@AB@%Description%@AE@%
  20083. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20084. SIGABRT                           Abnormal termination (real and protected
  20085.                                   mode).
  20086.  
  20087. SIGBREAK                          CTRL+BREAK signal. Terminates the 
  20088.                                   calling program (protected mode only).
  20089.  
  20090. SIGFPE                            Floating-point error, such as overflow, 
  20091.                                   division by zero, or invalid operation. 
  20092.                                   Terminates the calling program (real and
  20093.                                   protected mode).
  20094.  
  20095. SIGILL                            Illegal instruction. Terminates the 
  20096.                                   calling program (protected mode only).
  20097.  
  20098. SIGINT                            CTRL+C interrupt. Issues INT 23H (real 
  20099.                                   and
  20100.                                   protected mode).
  20101.  
  20102. SIGSEGV                           Illegal storage access. Not generated by
  20103.                                   DOS or OS/2, but supported for ANSI 
  20104.                                   compatibility. Terminates the calling 
  20105.                                   program (real and protected mode).
  20106.  
  20107. SIGTERM                           Termination request sent to the program.
  20108.                                   Not generated by DOS or OS/2, but 
  20109.                                   supported for ANSI compatibility. 
  20110.                                   Terminates the calling program (real and
  20111.                                   protected mode).
  20112.  
  20113. SIGUSR1                           OS/2 process flag A (protected mode 
  20114.                                   only).
  20115.  
  20116. SIGUSR2                           OS/2 process flag B (protected mode 
  20117.                                   only).
  20118.  
  20119. SIGUSR3                           OS/2 process flag C (protected mode 
  20120.                                   only).
  20121.  
  20122. %@NL@%
  20123. %@3@%%@CR:C6A-C0063   @%%@AB@%C.14.8  Default Signals%@AE@%%@EH@%%@NL@%
  20124. %@NL@%
  20125. %@AB@%If the equivalent of signal (sig, SIG_DFL) is not executed prior to the call
  20126. %@AB@%of a signal handler, the blocking of the signal that is performed (4.7.1.1)%@AE@%
  20127. %@NL@%
  20128. %@NL@%
  20129. Signals are set to their default status when a program begins running.  %@NL@%
  20130. %@NL@%
  20131. %@NL@%
  20132. %@3@%%@CR:C6A-C0064   @%%@AB@%C.14.9  The SIGILL Signal%@AE@%%@EH@%%@NL@%
  20133. %@NL@%
  20134. %@AB@%Whether the default handling is reset if the SIGILL signal is received by a
  20135. %@AB@%handler specified to the signal function (4.7.1.1)%@AE@%  %@NL@%
  20136. %@NL@%
  20137. The SIGILL signal applies to OS/2 applications only. When SIGILL is
  20138. received, the signal handling is not reset to the default SIG_DFL.  %@NL@%
  20139. %@NL@%
  20140. %@NL@%
  20141. %@3@%%@CR:C6A-C0065   @%%@AB@%C.14.10  Terminating Newline Characters%@AE@%%@EH@%%@NL@%
  20142. %@NL@%
  20143. %@AB@%Whether the last line of a text stream requires a terminating newline
  20144. %@AB@%character (4.9.2)%@AE@%  %@NL@%
  20145. %@NL@%
  20146. Stream functions recognize either newline or end-of-file as the terminating
  20147. character for a line.  %@NL@%
  20148. %@NL@%
  20149. %@NL@%
  20150. %@3@%%@CR:C6A-C0066   @%%@AB@%C.14.11  Blank Lines%@AE@%%@EH@%%@NL@%
  20151. %@NL@%
  20152. %@AB@%Whether space characters that are written out to a text stream immediately
  20153. %@AB@%before a newline character appear when read in (4.9.2)%@AE@%  %@NL@%
  20154. %@NL@%
  20155. Space characters are preserved.  %@NL@%
  20156. %@NL@%
  20157. %@NL@%
  20158. %@3@%%@CR:C6A-C0067   @%%@AB@%C.14.12  Null Characters%@AE@%%@EH@%%@NL@%
  20159. %@NL@%
  20160. %@AB@%The number of null characters that can be appended to data written to a
  20161. %@AB@%binary stream (4.9.2)%@AE@%  %@NL@%
  20162. %@NL@%
  20163. Any number of null characters can be appended to a binary stream.  %@NL@%
  20164. %@NL@%
  20165. %@NL@%
  20166. %@3@%%@CR:C6A-C0068   @%%@AB@%C.14.13  File Position in Append Mode%@AE@%%@EH@%%@NL@%
  20167. %@NL@%
  20168. %@AB@%Whether the file position indicator of an append mode stream is initially
  20169. %@AB@%positioned at the beginning or end of the file (4.9.3)%@AE@%  %@NL@%
  20170. %@NL@%
  20171. When a file is opened in append mode, the file position indicator initially
  20172. points to the end of the file.  %@NL@%
  20173. %@NL@%
  20174. %@NL@%
  20175. %@3@%%@CR:C6A-C0069   @%%@AB@%C.14.14  Truncation of Text Files%@AE@%%@EH@%%@NL@%
  20176. %@NL@%
  20177. %@AB@%Whether a write on a text stream causes the associated file to be truncated
  20178. %@AB@%beyond that point (4.9.3)%@AE@%  %@NL@%
  20179. %@NL@%
  20180. Writing to a text stream does not truncate the file beyond that point.  %@NL@%
  20181. %@NL@%
  20182. %@NL@%
  20183. %@3@%%@CR:C6A-C0070   @%%@AB@%C.14.15  File Buffering%@AE@%%@EH@%%@NL@%
  20184. %@NL@%
  20185. %@AB@%The characteristics of file buffering (4.9.3)%@AE@%  %@NL@%
  20186. %@NL@%
  20187. Disk files accessed through standard I/O functions are fully buffered. By
  20188. default, the buffer holds 512 bytes. Some of the low-level DOS and BIOS
  20189. functions (all of which are non-ANSI) are unbuffered.  %@NL@%
  20190. %@NL@%
  20191. %@NL@%
  20192. %@3@%%@CR:C6A-C0071   @%%@AB@%C.14.16  Zero-Length Files%@AE@%%@EH@%%@NL@%
  20193. %@NL@%
  20194. %@AB@%Whether a zero-length file actually exists (4.9.3)%@AE@%  %@NL@%
  20195. %@NL@%
  20196. Files with a length of zero are permitted.  %@NL@%
  20197. %@NL@%
  20198. %@NL@%
  20199. %@3@%%@CR:C6A-C0072   @%%@AB@%C.14.17  File Names%@AE@%%@EH@%%@NL@%
  20200. %@NL@%
  20201. %@AB@%The rules for composing valid file names (4.9.3)%@AE@%  %@NL@%
  20202. %@NL@%
  20203. A file specification can include an optional drive letter (always followed
  20204. by a colon), a series of optional directory names (separated by
  20205. backslashes), and a file name.  %@NL@%
  20206. %@NL@%
  20207. File names and directory names can contain up to eight characters followed
  20208. by a period and a three-character extension. Case is ignored. The wild-card
  20209. characters * and ? are not permitted within the name or extension.  %@NL@%
  20210. %@NL@%
  20211. %@NL@%
  20212. %@3@%%@CR:C6A-C0073   @%%@AB@%C.14.18  File Access Limits%@AE@%%@EH@%%@NL@%
  20213. %@NL@%
  20214. %@AB@%Whether the same file can be open multiple times (4.9.3)%@AE@%  %@NL@%
  20215. %@NL@%
  20216. Opening a file that is already open is not permitted.  %@NL@%
  20217. %@NL@%
  20218. %@NL@%
  20219. %@3@%%@CR:C6A-C0074   @%%@AB@%C.14.19  Deleting Open Files%@AE@%%@EH@%%@NL@%
  20220. %@NL@%
  20221. %@AB@%The effect of the remove function on an open file (4.9.4.1)%@AE@%  %@NL@%
  20222. %@NL@%
  20223. The %@AB@%remove%@AE@% function deletes a file, even if the file is open.  %@NL@%
  20224. %@NL@%
  20225. %@NL@%
  20226. %@3@%%@CR:C6A-C0075   @%%@AB@%C.14.20  Renaming with a Name that Exists%@AE@%%@EH@%%@NL@%
  20227. %@NL@%
  20228. %@AB@%The effect if a file with the new name exists prior to a call to the rename
  20229. %@AB@%function (4.9.4.2)%@AE@%  %@NL@%
  20230. %@NL@%
  20231. If you attempt to rename a file using a name that exists, the %@AB@%rename%@AE@%
  20232. function fails and returns an error code.  %@NL@%
  20233. %@NL@%
  20234. %@NL@%
  20235. %@3@%%@CR:C6A-C0076   @%%@AB@%C.14.21  Printing Pointer Values%@AE@%%@EH@%%@NL@%
  20236. %@NL@%
  20237. %@AB@%The output for %p conversion in the fprintf function (4.9.6.1)%@AE@%  %@NL@%
  20238. %@NL@%
  20239. Microsoft C supports three types of pointer conversions: %@AB@%%p %@AE@%(a pointer),%@AB@% %lp%@AE@%
  20240. (a 32-bit far pointer), and %@AB@%%hp %@AE@%(a 16-bit near pointer).  %@NL@%
  20241. %@NL@%
  20242. The %@AB@%fprintf%@AE@% function produces hexadecimal values of the form %@AI@%XXXX%@AE@% (an
  20243. offset) for near pointers or %@AI@%XXXX:XXXX%@AE@% (a segment plus an offset, separated
  20244. by a colon) for far pointers. The output for%@AB@% %p%@AE@% depends on the memory model
  20245. in use.  %@NL@%
  20246. %@NL@%
  20247. %@NL@%
  20248. %@3@%%@CR:C6A-C0077   @%%@AB@%C.14.22  Reading Pointer Values%@AE@%%@EH@%%@NL@%
  20249. %@NL@%
  20250. %@AB@%The input for %p conversion in the fscanf function (4.9.6.2)%@AE@%  %@NL@%
  20251. %@NL@%
  20252. When the %@AB@%%p%@AE@% format character is specified, the %@AB@%fscanf%@AE@% function converts
  20253. pointers from hexadecimal ASCII values into the correct address.  %@NL@%
  20254. %@NL@%
  20255. %@NL@%
  20256. %@3@%%@CR:C6A-C0078   @%%@AB@%C.14.23  Reading Ranges%@AE@%%@EH@%%@NL@%
  20257. %@NL@%
  20258. %@AB@%The interpretation of a dash (-) character that is neither the first nor the
  20259. %@AB@%last character in the scanlist for % [ conversion in the fscanf function
  20260. %@AB@%(4.9.6.2)%@AE@%  %@NL@%
  20261. %@NL@%
  20262. The following line  %@NL@%
  20263. %@NL@%
  20264. %@AS@%  fscanf( fileptr, "%[A-Z]", strptr);%@AE@%%@NL@%
  20265. %@NL@%
  20266. reads any number of characters in the range A-Z into the string to which %@AS@%
  20267. %@AS@%strptr %@AE@% points.  %@NL@%
  20268. %@NL@%
  20269. %@NL@%
  20270. %@3@%%@CR:C6A-C0079   @%%@AB@%C.14.24  File Position Errors%@AE@%%@EH@%%@NL@%
  20271. %@NL@%
  20272. %@AB@%The value to which the macro errno is set by the fgetpos or ftell function
  20273. %@AB@%on failure (4.9.9.1, 4.9.9.4)%@AE@%  %@NL@%
  20274. %@NL@%
  20275. When %@AB@%fgetpos%@AE@% or %@AB@%ftell%@AE@% fails, %@AB@%errno%@AE@% is set to the manifest constant %@AB@%EINVAL%@AE@% if
  20276. the position is invalid or %@AB@%EBADF%@AE@% if the file number is bad. The constants
  20277. are defined in ERRNO.H.  %@NL@%
  20278. %@NL@%
  20279. %@NL@%
  20280. %@3@%%@CR:C6A-C0080   @%%@AB@%C.14.25  Messages Generated by the perror Function%@AE@%%@EH@%%@NL@%
  20281. %@NL@%
  20282. %@AB@%The messages generated by the perror function (4.9.10.4)%@AE@%  %@NL@%
  20283. %@NL@%
  20284. The %@AB@%perror%@AE@% function generates these messages:  %@NL@%
  20285. %@NL@%
  20286. %@AS@%  0  Error 0
  20287. %@AS@%  1 
  20288. %@AS@%  2  No such file or directory
  20289. %@AS@%  3  
  20290. %@AS@%  4 
  20291. %@AS@%  5 
  20292. %@AS@%  6 
  20293. %@AS@%  7  Arg list too long
  20294. %@AS@%  8  Exec format error
  20295. %@AS@%  9  Bad file number
  20296. %@AS@%  10 
  20297. %@AS@%  11 
  20298. %@AS@%  12 Not enough core
  20299. %@AS@%  13 Permission denied
  20300. %@AS@%  14 
  20301. %@AS@%  15 
  20302. %@AS@%  16 
  20303. %@AS@%  17 File exists
  20304. %@AS@%  18 Cross-device link
  20305. %@AS@%  19 
  20306. %@AS@%  20 
  20307. %@AS@%  21 
  20308. %@AS@%  22 Invalid argument
  20309. %@AS@%  23 
  20310. %@AS@%  24 Too many open files
  20311. %@AS@%  25 
  20312. %@AS@%  26 
  20313. %@AS@%  27 
  20314. %@AS@%  28 No space left on device
  20315. %@AS@%  29 
  20316. %@AS@%  30 
  20317. %@AS@%  31 
  20318. %@AS@%  32 
  20319. %@AS@%  33 Math argument
  20320. %@AS@%  34 Result too large
  20321. %@AS@%  35 
  20322. %@AS@%  36 Resource deadlock would occur%@AE@%%@NL@%
  20323. %@NL@%
  20324. %@NL@%
  20325. %@3@%%@CR:C6A-C0081   @%%@AB@%C.14.26  Allocating Zero Memory%@AE@%%@EH@%%@NL@%
  20326. %@NL@%
  20327. %@AB@%The behavior of the calloc, malloc, or realloc function if the size
  20328. %@AB@%requested is zero (4.10.3)%@AE@%  %@NL@%
  20329. %@NL@%
  20330. The %@AB@%calloc%@AE@%, %@AB@%malloc%@AE@%, and %@AB@%realloc %@AE@%functions accept zero as an argument. No
  20331. actual memory is allocated, but the memory size can be modified later by
  20332. %@AB@%realloc%@AE@%.  %@NL@%
  20333. %@NL@%
  20334. %@NL@%
  20335. %@3@%%@CR:C6A-C0082   @%%@AB@%C.14.27  The abort Function%@AE@%%@EH@%%@NL@%
  20336. %@NL@%
  20337. %@AB@%The behavior of the abort function with regard to open and temporary  files
  20338. %@AB@%(4.10.4.1)%@AE@%  %@NL@%
  20339. %@NL@%
  20340. The %@AB@%abort%@AE@% function does not close files that are open or temporary. It does
  20341. not flush stream buffers.  %@NL@%
  20342. %@NL@%
  20343. %@NL@%
  20344. %@3@%%@CR:C6A-C0083   @%%@AB@%C.14.28  The atexit Function%@AE@%%@EH@%%@NL@%
  20345. %@NL@%
  20346. %@AB@%The status returned by the atexit function if the value of the argument is
  20347. %@AB@%other than zero, EXIT_SUCCESS, or EXIT_FAILURE (4.10.4.3r)%@AE@%  %@NL@%
  20348. %@NL@%
  20349. The %@AB@%atexit %@AE@%function returns zero if successful, or a nonzero value if
  20350. unsuccessful.  %@NL@%
  20351. %@NL@%
  20352. %@NL@%
  20353. %@3@%%@CR:C6A-C0084   @%%@AB@%C.14.29  Environment Names%@AE@%%@EH@%%@NL@%
  20354. %@NL@%
  20355. %@AB@%The set of environment names and the method for altering the environment
  20356. %@AB@%list used by the getenv function (4.10.4.4)%@AE@%  %@NL@%
  20357. %@NL@%
  20358. The set of environment names is unlimited.  %@NL@%
  20359. %@NL@%
  20360. To change environment variables from within a C program, call the %@AB@%putenv%@AE@%
  20361. function. To change environment variables from the DOS command line, use the
  20362. SET command (for example, SET LIB = D:\ LIBS).  %@NL@%
  20363. %@NL@%
  20364. Environment variables exist only as long as their host copy of DOS is
  20365. running. For example, the line  %@NL@%
  20366. %@NL@%
  20367. %@AS@%  system( "SET LIB = D:\LIBS" );%@AE@%%@NL@%
  20368. %@NL@%
  20369. would run a copy of DOS, set the environment variable LIB, and return to the
  20370. C program, exiting the secondary copy of DOS. Exiting that copy of DOS
  20371. removes the temporary environment variable LIB.  %@NL@%
  20372. %@NL@%
  20373. Likewise, changes made by the %@AB@%putenv%@AE@% function last only until the program
  20374. ends.  %@NL@%
  20375. %@NL@%
  20376. %@NL@%
  20377. %@3@%%@CR:C6A-C0085   @%%@AB@%C.14.30  The system Function%@AE@%%@EH@%%@NL@%
  20378. %@NL@%
  20379. %@AB@%The contents and mode of execution of the string by the system function
  20380. %@AB@%(4.10.4.5)%@AE@%  %@NL@%
  20381. %@NL@%
  20382. The %@AB@%system%@AE@% function executes an internal DOS or OS/2 command, or an EXE,
  20383. COM, or BAT file from within a C program rather than from the command line.
  20384. %@NL@%
  20385. %@NL@%
  20386. It examines the COMSPEC environment variable to find the command
  20387. interpreter, which is typically COMMAND.COM in DOS or CMD.EXE in OS/2. The
  20388. %@AB@%system%@AE@% function then passes the argument string to the command interpreter.
  20389. %@NL@%
  20390. %@NL@%
  20391. %@NL@%
  20392. %@3@%%@CR:C6A-C0086   @%%@AB@%C.14.31  The strerror Function%@AE@%%@EH@%%@NL@%
  20393. %@NL@%
  20394. %@AB@%The contents of the error message strings returned by the strerror function
  20395. %@AB@%(4.11.6.2)%@AE@%  %@NL@%
  20396. %@NL@%
  20397. The %@AB@%strerror%@AE@% function generates these messages:  %@NL@%
  20398. %@NL@%
  20399. %@AS@%  0   Error 0
  20400. %@AS@%  1  
  20401. %@AS@%  2   No such file or directory
  20402. %@AS@%  3  
  20403. %@AS@%  4  
  20404. %@AS@%  5  
  20405. %@AS@%  6  
  20406. %@AS@%  7   Arg list too long
  20407. %@AS@%  8   Exec format error
  20408. %@AS@%  9   Bad file number
  20409. %@AS@%  10  
  20410. %@AS@%  11  
  20411. %@AS@%  12  Not enough core
  20412. %@AS@%  13  Permission denied
  20413. %@AS@%  14  
  20414. %@AS@%  15  
  20415. %@AS@%  16  
  20416. %@AS@%  17  File exists
  20417. %@AS@%  18  Cross-device link
  20418. %@AS@%  19  
  20419. %@AS@%  20  
  20420. %@AS@%  21  
  20421. %@AS@%  22  Invalid argument
  20422. %@AS@%  23  
  20423. %@AS@%  24  Too many open files
  20424. %@AS@%  25  
  20425. %@AS@%  26  
  20426. %@AS@%  27  
  20427. %@AS@%  28  No space left on device
  20428. %@AS@%  29  
  20429. %@AS@%  30  
  20430. %@AS@%  31  
  20431. %@AS@%  32  
  20432. %@AS@%  33  Math argument
  20433. %@AS@%  34  Result too large
  20434. %@AS@%  35  
  20435. %@AS@%  36  Resource deadlock would occur%@AE@%%@NL@%
  20436. %@NL@%
  20437. %@NL@%
  20438. %@3@%%@CR:C6A-C0087   @%%@AB@%C.14.32  The Time Zone%@AE@%%@EH@%%@NL@%
  20439. %@NL@%
  20440. %@AB@%The local time zone and Daylight Saving Time (4.12.1)%@AE@%  %@NL@%
  20441. %@NL@%
  20442. The local time zone is Pacific Standard Time. Microsoft C supports Daylight
  20443. Saving Time.  %@NL@%
  20444. %@NL@%
  20445. %@NL@%
  20446. %@3@%%@CR:C6A-C0088   @%%@AB@%C.14.33  The clock Function%@AE@%%@EH@%%@NL@%
  20447. %@NL@%
  20448. %@AB@%The era for the clock function (4.12.2.1)%@AE@%  %@NL@%
  20449. %@NL@%
  20450. The %@AB@%clock %@AE@%function's era begins (with a value of 0) when the C program
  20451. starts to execute. It returns times measured in 1/1000th seconds.  %@NL@%
  20452. %@NL@%
  20453. %@NL@%
  20454. %@NL@%
  20455. %@CR:GeneralIndex@%
  20456. %@1@%%@AB@%INDEX%@AE@%%@EH@%%@NL@%
  20457. %@AB@%──────────────────────────────────────────────────────────────────────────
  20458.  
  20459.  
  20460.  
  20461. 80x87 coprocessor%@BO:       309cd@%%@BO:       370f9@%%@BO:       39bde@%
  20462. 80x87
  20463.   Detection of%@BO:       339af@%
  20464.  
  20465. %@2@%%@AB@%    A%@AE@%%@EH@%%@NL@%
  20466. Alternate math package%@BO:       341c5@%%@BO:       3826d@%
  20467.  
  20468. %@2@%%@AB@%    B%@AE@%%@EH@%%@NL@%
  20469. _based keyword%@BO:       1fe23@%%@BO:       2117b@%%@BO:       21caa@%
  20470.  
  20471. %@2@%%@AB@%    C%@AE@%%@EH@%%@NL@%
  20472. C extensions, PWB
  20473.   building protected-mode%@BO:       66d22@%
  20474.   building real-mode%@BO:       65d11@%%@BO:       66532@%
  20475.   calling C library functions%@BO:       6c61c@%
  20476.   calling C library routines%@BO:       6cb47@%
  20477.   calling PWB functions%@BO:       6a499@%%@BO:       6a9d3@%%@BO:       6b0c7@%%@BO:       6bab9@%%@BO:       6c441@%
  20478.   describing functions and switches%@BO:       67324@%%@BO:       67619@%%@BO:       67de2@%%@BO:       6866c@%
  20479.   initializing functions%@BO:       68b44@%
  20480.   prototyping functions%@BO:       69257@%
  20481.   receiving parameters%@BO:       69257@%%@BO:       699b4@%%@BO:       6a499@%
  20482.   sample%@BO:       650a9@%%@BO:       65b31@%
  20483.   versus executable files%@BO:       64e30@%
  20484. C extentions, PWB
  20485.   building protected-mode%@BO:       66876@%
  20486. Calls
  20487.   Emulator math package%@BO:       3737c@%
  20488.   Emulator package%@BO:       39396@%%@BO:       39bde@%
  20489.   Floating-point%@BO:       3494a@%%@BO:       38cfd@%
  20490.   Math coprocessor package%@BO:       37927@%
  20491. CODEVIEW.LST file%@BO:       77d77@%
  20492. CodeView
  20493.   debugging
  20494.     DLLs with%@BO:       e3f22@%
  20495. CONFIG.SYS file%@BO:       7890b@%
  20496. CONFIG.SYS files%@BO:       d390b@%
  20497. _control87%@BO:       33ec0@%
  20498. Coordinates
  20499.   overview%@BO:       806a5@%
  20500.   physical%@BO:       80b01@%%@BO:       80f5d@%%@BO:       8141f@%
  20501.   screen location%@BO:       81fcd@%
  20502.   viewport%@BO:       8141f@%%@BO:       83d1f@%
  20503.   window%@BO:       81a8a@%%@BO:       81fcd@%%@BO:       82fc7@%%@BO:       83d1f@%%@BO:       845b2@%%@BO:       84b29@%%@BO:       85aa5@%%@BO:       86287@%%@BO:       86c8b@%
  20504. Coprocessor%@BO:       309cd@%
  20505. CURRENT.STS%@BO:       6e5cb@%
  20506.  
  20507. %@2@%%@AB@%    D%@AE@%%@EH@%%@NL@%
  20508. Default math package%@BO:       339af@%
  20509. Denormalized numbers%@BO:       31b6f@%%@BO:       33ec0@%%@BO:       34416@%
  20510. Dot commands%@BO:       59bb9@%%@BO:       59efd@%%@BO:       5ac14@%%@BO:       5ba95@%
  20511. double%@BO:       30ed4@%%@BO:       32a89@%
  20512.  
  20513. %@2@%%@AB@%    E%@AE@%%@EH@%%@NL@%
  20514. 80x87 coprocessor%@BO:       309cd@%%@BO:       370f9@%%@BO:       39bde@%
  20515. 80x87
  20516.   Detection of%@BO:       339af@%
  20517. EMOEM.ASM%@BO:       3a8c0@%
  20518. Emulator math package%@BO:       33170@%%@BO:       3376a@%
  20519. Emulator package
  20520.   In-line%@BO:       366b7@%%@BO:       39bde@%
  20521.   With dynamic-link libraries%@BO:       36ed5@%
  20522. Environment
  20523.   NO87 variable%@BO:       309cd@%%@BO:       39a6a@%
  20524.  
  20525. %@2@%%@AB@%    F%@AE@%%@EH@%%@NL@%
  20526. _far keyword%@BO:       1fe23@%%@BO:       2117b@%%@BO:       21caa@%%@BO:       9f33e@%%@BO:       a0b7f@%%@BO:       b7e65@%
  20527. _fastcall keyword%@BO:       9d859@%
  20528. Files
  20529.   .FON%@BO:       87899@%%@BO:       87d60@%%@BO:       8a479@%
  20530.   CODEVIEW.LST%@BO:       77d77@%
  20531.   CONFIG.SYS%@BO:       7890b@%%@BO:       d390b@%
  20532.   CURRENT.STS%@BO:       6e5cb@%
  20533.   TOOLS.INI See TOOLS.INI%@BO:       460ef@%
  20534. Fill patterns%@BO:       91bc1@%%@BO:       922bf@%%@BO:       92bf4@%
  20535. float%@BO:       30ed4@%%@BO:       32a89@%
  20536. Floating-point accumulator%@BO:       32a89@%
  20537. Floating-point math
  20538.   requirements, DLLs%@BO:       d8678@%
  20539. Floating-point
  20540.   Alternate math package%@BO:       341c5@%%@BO:       3826d@%
  20541.   Biased exponent%@BO:       316fc@%
  20542.   Compatibility between options%@BO:       3913f@%
  20543. Floating-Point
  20544.   Controlling%@BO:       308f3@%
  20545. Floating-point
  20546.   Default math package%@BO:       36898@%
  20547.   Default package%@BO:       339af@%
  20548.   Denormalized numbers%@BO:       31b6f@%%@BO:       33ec0@%%@BO:       34416@%
  20549.   Effect of calls on code size%@BO:       37cb2@%%@BO:       38491@%
  20550.   Effect of calls on speed%@BO:       37d4f@%%@BO:       38491@%%@BO:       38feb@%
  20551.   Effect on optimization%@BO:       36063@%
  20552.   Emulator package%@BO:       33170@%%@BO:       3376a@%
  20553.   Exception masking%@BO:       33ec0@%
  20554.   Exceptions%@BO:       33d51@%%@BO:       3a5d8@%
  20555.   exponent%@BO:       3123f@%
  20556.   Fastest programs%@BO:       372f4@%
  20557.   In libraries%@BO:       3768f@%
  20558.   Infinities%@BO:       34416@%
  20559.   Interrupt-enable%@BO:       33ec0@%
  20560.   Library considerations for%@BO:       386a4@%
  20561.   Mantissa%@BO:       3123f@%
  20562.   Math coprocessor package%@BO:       33212@%%@BO:       33f87@%
  20563.   Maximizing accuracy%@BO:       33a98@%
  20564.   NaNs%@BO:       34416@%
  20565.   On non-IBM compatible computers%@BO:       3a2a8@%
  20566.   Packages%@BO:       33116@%%@BO:       3353d@%
  20567.   Precision%@BO:       3210e@%
  20568.   Program size%@BO:       34143@%%@BO:       341c5@%
  20569.   Program speed%@BO:       34143@%%@BO:       341c5@%
  20570.   Sign bit%@BO:       31380@%
  20571.   Smallest programs%@BO:       372f4@%
  20572.   Transcendental function results%@BO:       33cce@%
  20573.   Underflow%@BO:       33ec0@%
  20574.   Using in dynamic-link libraries%@BO:       345ba@%
  20575.   With libraries not provided by Microsoft%@BO:       37728@%
  20576. .FON files%@BO:       87899@%%@BO:       87d60@%%@BO:       8a479@%
  20577. /FPa%@BO:       3826d@%
  20578. /FPc%@BO:       3737c@%%@BO:       39396@%%@BO:       39bde@%
  20579. /FPc87%@BO:       37927@%
  20580. /FPi%@BO:       366b7@%%@BO:       39bde@%
  20581. /FPi87%@BO:       36f6a@%
  20582. Function calls
  20583.    near call%@BO:       16856@%
  20584.   C calling convention%@BO:       19198@%
  20585.   FORTRAN/Pascal calling convention%@BO:       19198@%%@BO:       19c0f@%
  20586.   register calling convention%@BO:       19c0f@%
  20587.   _fastcall calling convention%@BO:       19c0f@%%@BO:       1a9ca@%%@BO:       1b06e@%%@BO:       1b6f2@%
  20588. Functions
  20589.   drive and directory (list)%@BO:       eafe2@%
  20590.   graphics (list)%@BO:       82c5e@%
  20591.   initializing%@BO:       68b44@%
  20592.   prototyping%@BO:       69257@%
  20593.   Returning floating-point types%@BO:       32643@%
  20594.   WhenLoaded%@BO:       68b44@%
  20595.  
  20596. %@2@%%@AB@%    G%@AE@%%@EH@%%@NL@%
  20597. /Gd option%@BO:       eb7e9@%
  20598. Gd option%@BO:       19198@%
  20599. Graphics
  20600.   video modes 
  20601.      default mode%@BO:       7b01e@%
  20602.      graphics mode, defined%@BO:       7b01e@%
  20603.      text mode, defined%@BO:       7b01e@%
  20604.  
  20605. %@2@%%@AB@%    H%@AE@%%@EH@%%@NL@%
  20606. Help files
  20607.   local help context%@BO:       568ec@%
  20608. HIMEM.SYS driver%@BO:       7890b@%
  20609. _huge keyword%@BO:       e7371@%
  20610. _huge Keyword%@BO:       1dce4@%
  20611. _huge keyword%@BO:       1fe23@%%@BO:       2117b@%%@BO:       21caa@%%@BO:       b7caa@%%@BO:       b7e65@%
  20612.  
  20613. %@2@%%@AB@%    I%@AE@%%@EH@%%@NL@%
  20614. IEEE%@BO:       30b59@%%@BO:       34416@%%@BO:       36063@%
  20615. In-line assembly
  20616.   advantages%@BO:       28854@%
  20617. In-line
  20618.   Floating-point emulator package%@BO:       366b7@%
  20619.   Floating-point emulator%@BO:       39bde@%
  20620.   Floating-point instructions%@BO:       38cfd@%
  20621.   Floating-point math coprocessor package%@BO:       36f6a@%
  20622.   Floating-point%@BO:       3494a@%
  20623. Institute of Electrical and Electronics Engineers
  20624.    %@AI@%see%@AE@% IEEE%@NL@%; %@AI@%see%@AE@% %@NL@%
  20625.  
  20626. %@2@%%@AB@%    L%@AE@%%@EH@%%@NL@%
  20627. Language conventions
  20628.   calling conventions%@BO:       9d0ff@%%@BO:       9d859@%
  20629.   naming conventions%@BO:       9bde5@%%@BO:       9c6f1@%%@BO:       9cf4d@%
  20630.   parameter-passing conventions%@BO:       9e336@%%@BO:       9f33e@%
  20631. Libraries
  20632.   dynamic-link See DLLs%@BO:       c58c8@%
  20633.   import%@BO:       c7173@%%@BO:       c77ce@%
  20634.   special%@BO:       c2ecf@%%@BO:       c39de@%
  20635. LINK
  20636.   /EXEPACK option%@BO:       184e3@%
  20637.   /FARCALLTRANSLATION option%@BO:       16856@%
  20638.   /NODEFAULTLIBRARYSEARCH (/NOD) option%@BO:       c1915@%%@BO:       c247b@%%@BO:       c77ce@%
  20639.   /NOEXTENDEDDICTSEARCH (/NOE) option%@BO:       c7d3e@%
  20640.   /NOIGNORECASE (/NOI) option%@BO:       c7d3e@%
  20641.   /PACKCODE option%@BO:       17100@%
  20642.   /PACKDATA option%@BO:       1812a@%%@BO:       18322@%
  20643.   /PADCODE option%@BO:       3c4e6@%
  20644.   /PADDATA option%@BO:       3c4e6@%%@BO:       3c641@%
  20645.   /TINY option%@BO:       1df3d@%
  20646.   compatibility (/Lc)%@BO:       c1915@%
  20647.   PACKCODE option%@BO:       17bab@%
  20648.   protected-mode (/Lp)%@BO:       c1915@%%@BO:       c247b@%
  20649.   real-mode (/Lr)%@BO:       c1915@%%@BO:       c247b@%
  20650. LLIBCDLL.LIB%@BO:       345ba@%
  20651. long double%@BO:       30ed4@%%@BO:       32a89@%%@BO:       32d2a@%
  20652.  
  20653. %@2@%%@AB@%    M%@AE@%%@EH@%%@NL@%
  20654. Macros
  20655.   inherited%@BO:       454a5@%
  20656. Math coprocessor package%@BO:       33212@%%@BO:       33f87@%
  20657.   In-line%@BO:       36f6a@%
  20658.  
  20659. %@2@%%@AB@%    N%@AE@%%@EH@%%@NL@%
  20660. _near keyword%@BO:       1fe23@%%@BO:       2117b@%%@BO:       21caa@%%@BO:       9f33e@%%@BO:       a0b7f@%%@BO:       b7e65@%
  20661. NO87%@BO:       309cd@%%@BO:       39a6a@%
  20662.  
  20663. %@2@%%@AB@%    O%@AE@%%@EH@%%@NL@%
  20664. optimise pragma%@BO:       14ce4@%%@BO:       1546c@%
  20665. Optimization
  20666.   Effect of floating-point math on%@BO:       36063@%%@BO:       381c4@%
  20667. optimize pragma%@BO:       11ff2@%%@BO:       14815@%
  20668. OS/2 
  20669.   calling%@BO:       bede0@%
  20670.  
  20671. %@2@%%@AB@%    P%@AE@%%@EH@%%@NL@%
  20672. Process
  20673.   child%@BO:       e4420@%
  20674.   debugging multiple processes%@BO:       d390b@%
  20675. Programmer's WorkBench
  20676.    %@AI@%see%@AE@% PWB%@NL@%; %@AI@%see%@AE@% %@NL@%
  20677. Pseudotargets%@BO:       48ea4@%%@BO:       4922a@%
  20678. PWB
  20679.   80x87 option%@BO:       363c0@%
  20680.   Debug Build Options%@BO:       36200@%
  20681.   Emulation calls option%@BO:       36305@%
  20682.   extensions.See C extensions, PWB%@BO:       650a9@%
  20683.   Fast alternate math option%@BO:       3646a@%
  20684.   Global Compile Options%@BO:       36200@%
  20685.   Inline 80x87 Instructions option%@BO:       36658@%
  20686.   Inline Emulation option%@BO:       36526@%
  20687.   Release Build Options%@BO:       36200@%
  20688.   Selecting floating-point options from%@BO:       3494a@%
  20689.  
  20690. %@2@%%@AB@%    R%@AE@%%@EH@%%@NL@%
  20691. Run-time
  20692.   support of type long double%@BO:       32d2a@%
  20693.  
  20694. %@2@%%@AB@%    S%@AE@%%@EH@%%@NL@%
  20695. SETUP%@BO:       333b8@%
  20696. SLLs
  20697.   data segments%@BO:       253a7@%
  20698.  
  20699. %@2@%%@AB@%    T%@AE@%%@EH@%%@NL@%
  20700. Threads
  20701.   _beginthread function%@BO:       cc91d@%
  20702.   _endthread function%@BO:       cc91d@%
  20703. /TINY option%@BO:       1df3d@%
  20704. Type
  20705.   double%@BO:       30ed4@%
  20706.   float%@BO:       30ed4@%
  20707.   long double%@BO:       30ed4@%
  20708.   Promotion of floating point%@BO:       3234a@%
  20709.   Range of floating-point%@BO:       31d97@%
  20710.   Significance of floating-point%@BO:       30ed4@%
  20711.   Storage requirements for floating-point%@BO:       30ed4@%
  20712.   Widening for floating-point types%@BO:       32170@%
  20713. Types
  20714.   double%@BO:       32a89@%
  20715.   float%@BO:       32a89@%
  20716.   long double%@BO:       32a89@%%@BO:       32d2a@%
  20717.  
  20718. %@2@%%@AB@%    V%@AE@%%@EH@%%@NL@%
  20719. Variables
  20720.   Declaring as floating-point types%@BO:       30d03@%
  20721.   Precision with floating-point%@BO:       3210e@%
  20722.   Promotion of floating-point%@BO:       3234a@%
  20723.   Range of floating-point%@BO:       31d97@%
  20724.   Significance of%@BO:       30ed4@%
  20725.   Storage requirements for%@BO:       30ed4@%
  20726.  
  20727.