home *** CD-ROM | disk | FTP | other *** search
/ Microsoft Programmer's Library 1.3 / Microsoft-Programers-Library-v1.3.iso / books / qaprog.db < prev    next >
Encoding:
Text File  |  1991-03-01  |  1.1 MB  |  20,649 lines
Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents.
  1. %@1@%Microsoft(R) QuickAssembler Programmer's Guide Version 2.01%@EH@%%@NL@%
  2. %@NL@%
  3. %@NL@%
  4. %@AB@%════════════════════════════════════════════════════════════════════════════%@AE@%%@NL@%
  5. %@NL@%
  6. %@NL@%
  7. %@AB@%Microsoft(R) QuickAssembler Programmer's Guide Version 2.01%@AE@%%@NL@%
  8. %@NL@%
  9. %@NL@%
  10. %@AB@%════════════════════════════════════════════════════════════════════════════%@AE@%%@NL@%
  11. %@NL@%
  12. %@4@%%@EH@%%@NL@%
  13.   Information in this document is subject to change without notice and does
  14.   not represent a commitment on the part of Microsoft Corporation. The
  15.   software described in this document is furnished under a license agreement
  16.   or nondisclosure agreement. The software may be used or copied only in
  17.   accordance with the terms of the agreement. It is against the law to copy
  18.   the software on any medium except as specifically allowed in the license
  19.   or nondisclosure agreement. No part of this manual may be reproduced or
  20.   transmitted in any form or by any means, electronic or mechanical,
  21.   including photocopying and recording, for any purpose without the express
  22.   written permission of Microsoft.%@NL@%
  23. %@NL@%
  24.   (C)Copyright Microsoft Corporation, 1989. All rights reserved.%@NL@%
  25.   Simultaneously published in the U.S. and Canada.%@NL@%
  26. %@NL@%
  27.   Printed and bound in the United States of America.%@NL@%
  28. %@NL@%
  29.   Microsoft, MS, MS-DOS, GW-BASIC, QuickC, and XENIX are registered
  30.   trademarks of Microsoft Corporation.%@NL@%
  31. %@NL@%
  32.   IBM is a registered trademark of International Business Machines
  33.   Corporation.%@NL@%
  34. %@NL@%
  35.   Intel is a registered trademark of Intel Corporation.%@NL@%
  36. %@NL@%
  37.   Document No. LN0114-201-R00-0689%@NL@%
  38.   Part No. 06792%@NL@%
  39.   10  9  8  7  6  5  4  3  2  1%@NL@%
  40. %@NL@%
  41. %@NL@%
  42. %@NL@%
  43. %@NL@%
  44. %@NL@%
  45. ────────────────────────────────────────────────────────────────────────────%@NL@%
  46. %@1@%%@CR:Contents    @%%@AB@%Table of Contents%@AE@%%@EH@%%@NL@%
  47. %@NL@%
  48. %@AB@%Introduction%@AE@%%@BO:        71b3@%%@NL@%
  49. %@NL@%
  50. %@AB@%Chapter 1  The QuickAssembler Interface%@AE@%%@BO:        bdb6@%%@NL@%
  51.         1.1  Creating the Program%@BO:        c2ee@%%@NL@%
  52.         1.2  Building and Running a Program%@BO:        d078@%%@NL@%
  53.         1.3  Assembling from the Command Line%@BO:        e4be@%%@NL@%
  54.         1.4  Choosing C or Assembler Defaults%@BO:        ece3@%%@NL@%
  55.         1.5  Using the Quick Advisor (Help)%@BO:        f864@%%@NL@%
  56.         1.6  Debugging Assembly Code%@BO:       10827@%%@NL@%
  57.              1.6.1  Debugging .COM Files%@BO:       10d74@%%@NL@%
  58.              1.6.2  Specifying Expressions%@BO:       11102@%%@NL@%
  59.              1.6.3  Tracing Execution%@BO:       13131@%%@NL@%
  60.              1.6.4  Modifying Registers and Flags%@BO:       13ded@%%@NL@%
  61.         1.7  Viewing a Listing File%@BO:       146ad@%%@NL@%
  62. %@NL@%
  63. %@AB@%Chapter 2  Introducing 8086 Assembly Language%@AE@%%@BO:       151ff@%%@NL@%
  64.         2.1  Programming the 8086 Family%@BO:       156a6@%%@NL@%
  65.         2.2  Instructions, Directives, and Operands%@BO:       1602a@%%@NL@%
  66.              2.2.1  The Name Field%@BO:       16928@%%@NL@%
  67.              2.2.2  The Operation Field%@BO:       16feb@%%@NL@%
  68.              2.2.3  The Operand Field%@BO:       1736e@%%@NL@%
  69.              2.2.4  The Comment Field%@BO:       17a6d@%%@NL@%
  70.              2.2.5  Entering Numbers in Different Bases%@BO:       183c3@%%@NL@%
  71.              2.2.6  Line-Continuation Character%@BO:       188aa@%%@NL@%
  72.         2.3  8086-Family Instructions%@BO:       18e01@%%@NL@%
  73.              2.3.1  Data-Manipulation Instructions%@BO:       1923f@%%@NL@%
  74.                     2.3.1.1  The MOV Instruction%@BO:       19666@%%@NL@%
  75.                     2.3.1.2  The ADD Instruction%@BO:       19c57@%%@NL@%
  76.                     2.3.1.3  The SUB Instruction%@BO:       19f8c@%%@NL@%
  77.                     2.3.1.4  The INC and DEC Instructions%@BO:       1a1b6@%%@NL@%
  78.                     2.3.1.5  The AND Instruction%@BO:       1a40c@%%@NL@%
  79.                     2.3.1.6  The MUL Instruction%@BO:       1a61b@%%@NL@%
  80.              2.3.2  Control-Flow Instructions%@BO:       1a91f@%%@NL@%
  81.                     2.3.2.1  The JMP Instruction%@BO:       1ad5f@%%@NL@%
  82.                     2.3.2.2  The CMP Instruction%@BO:       1af9f@%%@NL@%
  83.                     2.3.2.3  The Conditional Jump Instructions%@BO:       1b4ae@%%@NL@%
  84.         2.4  Declaring Simple Data Objects%@BO:       1c0ef@%%@NL@%
  85.         2.5  8086-Family Registers%@BO:       1e475@%%@NL@%
  86.              2.5.1  The General-Purpose Registers%@BO:       1ef06@%%@NL@%
  87.                     2.5.1.1  The AX Register%@BO:       1f77d@%%@NL@%
  88.                     2.5.1.2  The BX Register%@BO:       2003e@%%@NL@%
  89.                     2.5.1.3  The CX Register%@BO:       204b0@%%@NL@%
  90.                     2.5.1.4  The DX Register%@BO:       20a0f@%%@NL@%
  91.              2.5.2  The Index Registers%@BO:       2112f@%%@NL@%
  92.              2.5.3  The Pointer Registers%@BO:       21724@%%@NL@%
  93.                     2.5.3.1  The BP Register%@BO:       219b0@%%@NL@%
  94.                     2.5.3.2  The SP Register%@BO:       21e9c@%%@NL@%
  95.                     2.5.3.3  The IP Register%@BO:       227c9@%%@NL@%
  96.              2.5.4  The Flags Register%@BO:       22b46@%%@NL@%
  97.         2.6  Addressing Modes%@BO:       2404d@%%@NL@%
  98.              2.6.1  Immediate Operands%@BO:       24a4c@%%@NL@%
  99.              2.6.2  Register Operands%@BO:       25a37@%%@NL@%
  100.              2.6.3  Direct Memory Operands%@BO:       263fe@%%@NL@%
  101.              2.6.4  Indirect Memory Operands%@BO:       27375@%%@NL@%
  102.         2.7  Segmented Addressing and Segment Registers%@BO:       28c1c@%%@NL@%
  103. %@NL@%
  104. %@AB@%Chapter 3  Writing Assembly Modules for C Programs%@AE@%%@BO:       2aca0@%%@NL@%
  105.         3.1  A Skeleton for Procedure Modules%@BO:       2b09b@%%@NL@%
  106.              3.1.1  The .MODEL Directive%@BO:       2b5d8@%%@NL@%
  107.              3.1.2  The .CODE Directive%@BO:       2bcd7@%%@NL@%
  108.              3.1.3  The PROC Directive%@BO:       2c048@%%@NL@%
  109.              3.1.4  The ENDP and END Statements%@BO:       2ce1f@%%@NL@%
  110.         3.2  Instructions Used in This Chapter%@BO:       2d0aa@%%@NL@%
  111.         3.3  Decimal Conversion Example%@BO:       2da0c@%%@NL@%
  112.         3.4  Decimal Conversion with Far Data Pointers%@BO:       30c03@%%@NL@%
  113.              3.4.1  Writing a Model-Independent Procedure%@BO:       31d77@%%@NL@%
  114.              3.4.2  Accessing Far Data through ES%@BO:       32809@%%@NL@%
  115.         3.5  Hexadecimal Conversion Example%@BO:       32dd7@%%@NL@%
  116. %@NL@%
  117. %@AB@%Chapter 4  Writing Stand-Alone Assembly Programs%@AE@%%@BO:       34dba@%%@NL@%
  118.         4.1  A Skeleton for Stand-Alone Programs%@BO:       352d5@%%@NL@%
  119.              4.1.1  The .MODEL Directive%@BO:       35c29@%%@NL@%
  120.              4.1.2  The .STACK, .CODE, and .DATA Directives%@BO:       36319@%%@NL@%
  121.              4.1.3  The .STARTUP Directive%@BO:       368bc@%%@NL@%
  122.         4.2  Instructions Used in This Chapter%@BO:       36f98@%%@NL@%
  123.         4.3  A Program That Says Hello%@BO:       3793a@%%@NL@%
  124.         4.4  Inside the Stack Segment%@BO:       3817c@%%@NL@%
  125.         4.5  Inside the Data Segment%@BO:       386bf@%%@NL@%
  126.         4.6  Inside the Code Segment%@BO:       391bd@%%@NL@%
  127.         4.7  Making the Program Repeat Itself%@BO:       3b04f@%%@NL@%
  128.         4.8  Creating .COM Files%@BO:       3c62a@%%@NL@%
  129.         4.9  Creating .COM Files with Full Segment Definitions%@BO:       3e206@%%@NL@%
  130. %@NL@%
  131. %@AB@%Chapter 5  Defining Segment Structure%@AE@%%@BO:       3ffad@%%@NL@%
  132.         5.1  Simplified Segment Directives%@BO:       406ed@%%@NL@%
  133.              5.1.1  Understanding Memory Models%@BO:       40c7f@%%@NL@%
  134.              5.1.2  Specifying DOS Segment Order%@BO:       41df5@%%@NL@%
  135.              5.1.3  Defining Basic Attributes of the Module%@BO:       42b44@%%@NL@%
  136.              5.1.4  Defining Simplified Segments%@BO:       44e63@%%@NL@%
  137.                     5.1.4.1  How to Use Simplified Segments%@BO:       45417@%%@NL@%
  138.                     5.1.4.2  How Simplified Segments Are Implemented%@BO:       46b2b@%%@NL@%
  139.              5.1.5  Using Predefined Segment Equates%@BO:       47722@%%@NL@%
  140.              5.1.6  Simplified Segment Defaults%@BO:       48b18@%%@NL@%
  141.              5.1.7  Default Segment Names%@BO:       493ed@%%@NL@%
  142.         5.2  Full Segment Definitions%@BO:       4b9a0@%%@NL@%
  143.              5.2.1  Setting the Segment-Order Method%@BO:       4bb75@%%@NL@%
  144.              5.2.2  Defining Full Segments%@BO:       4c98d@%%@NL@%
  145.                     5.2.2.1  Controlling Alignment with Align Type%@BO:       4d1c0@%%@NL@%
  146.                     5.2.2.2  Defining Segment Combinations with Combine Type%@BO:       4d84e@%%@NL@%
  147.                     5.2.2.3  Controlling Segment Structure with Class Type%@BO:       4f990@%%@NL@%
  148.         5.3  Defining Segment Groups%@BO:       512db@%%@NL@%
  149.         5.4  Associating Segments with Registers%@BO:       52503@%%@NL@%
  150.         5.5  Initializing Segment Registers%@BO:       53a35@%%@NL@%
  151.              5.5.1  Initializing the CS and IP Registers%@BO:       54127@%%@NL@%
  152.              5.5.2  Initializing the DS Register%@BO:       54d57@%%@NL@%
  153.              5.5.3  Initializing the SS and SP Registers%@BO:       55651@%%@NL@%
  154.              5.5.4  Initializing the ES Register%@BO:       5655f@%%@NL@%
  155.         5.6  Nesting Segments%@BO:       5678c@%%@NL@%
  156. %@NL@%
  157. %@AB@%Chapter 6  Defining Constants, Labels, and Variables%@AE@%%@BO:       5749b@%%@NL@%
  158.         6.1  Constants%@BO:       57adf@%%@NL@%
  159.              6.1.1  Integer Constants%@BO:       57c8a@%%@NL@%
  160.                     6.1.1.1  Specifying Integers with Radix Specifiers%@BO:       58381@%%@NL@%
  161.                     6.1.1.2  Setting the Default Radix%@BO:       58a87@%%@NL@%
  162.              6.1.2  Packed Binary Coded Decimal Constants%@BO:       59313@%%@NL@%
  163.              6.1.3  Real-Number Constants%@BO:       5971d@%%@NL@%
  164.              6.1.4  String Constants%@BO:       5a65b@%%@NL@%
  165.              6.1.5  Determining Floating-Point Format%@BO:       5ac90@%%@NL@%
  166.         6.2  Assigning Names to Symbols%@BO:       5b018@%%@NL@%
  167.         6.3  Using Type Specifiers%@BO:       5cd7a@%%@NL@%
  168.         6.4  Defining Code Labels%@BO:       5d761@%%@NL@%
  169.              6.4.1  Near-Code Labels%@BO:       5d8ad@%%@NL@%
  170.              6.4.2  Anonymous Labels%@BO:       5e370@%%@NL@%
  171.              6.4.3  Procedure Labels%@BO:       5ea93@%%@NL@%
  172.              6.4.4  Code Labels Defined with the LABEL Directive%@BO:       5f8c9@%%@NL@%
  173.         6.5  Defining and Initializing Data%@BO:       5ff03@%%@NL@%
  174.              6.5.1  Variables%@BO:       60128@%%@NL@%
  175.                     6.5.1.1  Integer Variables%@BO:       6093b@%%@NL@%
  176.                     6.5.1.2  Binary Coded Decimal Variables%@BO:       61d5d@%%@NL@%
  177.                     6.5.1.3  String Variables%@BO:       624c4@%%@NL@%
  178.                     6.5.1.4  Real-Number Variables%@BO:       62baf@%%@NL@%
  179.              6.5.2  Arrays and Buffers%@BO:       65365@%%@NL@%
  180.              6.5.3  Labeling Variables%@BO:       66496@%%@NL@%
  181.              6.5.4  Pointer Variables%@BO:       668f9@%%@NL@%
  182.         6.6  Setting the Location Counter%@BO:       67109@%%@NL@%
  183.         6.7  Aligning Data%@BO:       67efe@%%@NL@%
  184. %@NL@%
  185. %@AB@%Chapter 7  Using Structures and Records%@AE@%%@BO:       69661@%%@NL@%
  186.         7.1  Structures%@BO:       69ad4@%%@NL@%
  187.              7.1.1  Declaring Structure Types%@BO:       69fa7@%%@NL@%
  188.              7.1.2  Defining Structure Variables%@BO:       6abcb@%%@NL@%
  189.              7.1.3  Using Structure Operands%@BO:       6bb03@%%@NL@%
  190.         7.2  Records%@BO:       6c3c6@%%@NL@%
  191.              7.2.1  Declaring Record Types%@BO:       6c897@%%@NL@%
  192.              7.2.2  Defining Record Variables%@BO:       6d883@%%@NL@%
  193.              7.2.3  Using Record Operands and Record Variables%@BO:       6e991@%%@NL@%
  194.              7.2.4  Record Operators%@BO:       6f341@%%@NL@%
  195.                     7.2.4.1  The MASK Operator%@BO:       6f465@%%@NL@%
  196.                     7.2.4.2  The WIDTH Operator%@BO:       6fc80@%%@NL@%
  197.              7.2.5  Using Record-Field Operands%@BO:       7047a@%%@NL@%
  198. %@NL@%
  199. %@AB@%Chapter 8  Creating Programs from Multiple Modules%@AE@%%@BO:       70f6e@%%@NL@%
  200.         8.1  Declaring Symbols Public%@BO:       71a9a@%%@NL@%
  201.         8.2  Declaring Symbols External%@BO:       7299e@%%@NL@%
  202.         8.3  Using Multiple Modules%@BO:       74c1a@%%@NL@%
  203.         8.4  Declaring Symbols Communal%@BO:       75dae@%%@NL@%
  204.         8.5  Specifying Library Files%@BO:       78240@%%@NL@%
  205. %@NL@%
  206. %@AB@%Chapter 9  Using Operands and Expressions%@AE@%%@BO:       78a1d@%%@NL@%
  207.         9.1  Using Operands with Directives%@BO:       78f56@%%@NL@%
  208.         9.2  Using Operators%@BO:       799d6@%%@NL@%
  209.              9.2.1  Calculation Operators%@BO:       79f46@%%@NL@%
  210.                     9.2.1.1  Arithmetic Operators%@BO:       7a0b8@%%@NL@%
  211.                     9.2.1.2  Structure-Field-Name Operator%@BO:       7afe8@%%@NL@%
  212.                     9.2.1.3  Index Operator%@BO:       7b606@%%@NL@%
  213.                     9.2.1.4  Shift Operators%@BO:       7c2cb@%%@NL@%
  214.                     9.2.1.5  Bitwise Logical Operators%@BO:       7c89d@%%@NL@%
  215.              9.2.2  Relational Operators%@BO:       7d2f0@%%@NL@%
  216.              9.2.3  Segment-Override Operator%@BO:       7e029@%%@NL@%
  217.              9.2.4  Type Operators%@BO:       7e884@%%@NL@%
  218.                     9.2.4.1  PTR Operator%@BO:       7e982@%%@NL@%
  219.                     9.2.4.2  SHORT Operator%@BO:       7f627@%%@NL@%
  220.                     9.2.4.3  THIS Operator%@BO:       7faf7@%%@NL@%
  221.                     9.2.4.4  HIGH and LOW Operators%@BO:       8003d@%%@NL@%
  222.                     9.2.4.5  SEG Operator%@BO:       80576@%%@NL@%
  223.                     9.2.4.6  OFFSET Operator%@BO:       809dd@%%@NL@%
  224.                     9.2.4.7  .TYPE Operator%@BO:       813fa@%%@NL@%
  225.                     9.2.4.8  TYPE Operator%@BO:       81de8@%%@NL@%
  226.                     9.2.4.9  LENGTH Operator%@BO:       821b8@%%@NL@%
  227.                     9.2.4.10  SIZE Operator%@BO:       828bd@%%@NL@%
  228.              9.2.5  Operator Precedence%@BO:       83028@%%@NL@%
  229.         9.3  Using the Location Counter%@BO:       83a2d@%%@NL@%
  230.         9.4  Using Forward References%@BO:       84253@%%@NL@%
  231.              9.4.1  Forward References to Labels%@BO:       845be@%%@NL@%
  232.              9.4.2  Forward References to Variables%@BO:       855f0@%%@NL@%
  233.         9.5  Strong Typing for Memory Operands%@BO:       85b10@%%@NL@%
  234. %@NL@%
  235. %@AB@%Chapter 10  Assembling Conditionally%@AE@%%@BO:       867d7@%%@NL@%
  236.         10.1  Using Conditional-Assembly Directives%@BO:       86c68@%%@NL@%
  237.               10.1.1  Testing Expressions with IF and IFE Directives%@BO:       875ae@%%@NL@%
  238.               10.1.2  Testing the Pass with IF1 and IF2 Directives%@BO:       87b1f@%%@NL@%
  239.               10.1.3  Testing Symbol Definition with IFDEF and IFNDEF Directives%@BO:       880e2@%%@NL@%
  240.               10.1.4  Verifying Macro Parameters with IFB and IFNB Directives%@BO:       889a1@%%@NL@%
  241.               10.1.5  Comparing Macro Arguments with IFIDN and IFDIF Directives%@BO:       89144@%%@NL@%
  242.               10.1.6  ELSEIF Directives%@BO:       89a62@%%@NL@%
  243.         10.2  Using Conditional-Error Directives%@BO:       8a75c@%%@NL@%
  244.               10.2.1  Generating Unconditional Errors with .ERR, .ERR1, and .ERR2
  245.                       Directives%@BO:       8b0d5@%%@NL@%
  246.               10.2.2  Testing Expressions with .ERRE or .ERRNZ Directives%@BO:       8b9ee@%%@NL@%
  247.               10.2.3  Verifying Symbol Definition with .ERRDEF and .ERRNDEF
  248.                       Directives%@BO:       8c16c@%%@NL@%
  249.               10.2.4  Testing for Macro Parameters with .ERRB and .ERRNB
  250.                       Directives%@BO:       8c715@%%@NL@%
  251.               10.2.5  Comparing Macro Arguments with .ERRIDN and .ERRDIF
  252.                       Directives%@BO:       8ce3c@%%@NL@%
  253. %@NL@%
  254. %@AB@%Chapter 11  Using Equates, Macros, and Repeat Blocks%@AE@%%@BO:       8d6e4@%%@NL@%
  255.         11.1  Using Equates%@BO:       8dc18@%%@NL@%
  256.               11.1.1  Redefinable Numeric Equates%@BO:       8ddc1@%%@NL@%
  257.               11.1.2  Nonredefinable Numeric Equates%@BO:       8e80f@%%@NL@%
  258.               11.1.3  String Equates%@BO:       8f1c6@%%@NL@%
  259.               11.1.4  Predefined Equates%@BO:       8ff00@%%@NL@%
  260.         11.2  Using Macros%@BO:       91763@%%@NL@%
  261.               11.2.1  Defining Macros%@BO:       91f51@%%@NL@%
  262.               11.2.2  Calling Macros%@BO:       92d97@%%@NL@%
  263.               11.2.3  Using Local Symbols%@BO:       93a20@%%@NL@%
  264.               11.2.4  Exiting from a Macro%@BO:       94af2@%%@NL@%
  265.         11.3  Text-Macro String Directives%@BO:       95341@%%@NL@%
  266.               11.3.1  The SUBSTR Directive%@BO:       95c51@%%@NL@%
  267.               11.3.2  The CATSTR Directive%@BO:       962fa@%%@NL@%
  268.               11.3.3  The SIZESTR Directive%@BO:       96760@%%@NL@%
  269.               11.3.4  The INSTR Directive%@BO:       96c6e@%%@NL@%
  270.               11.3.5  Using String Directives Inside Macros%@BO:       97329@%%@NL@%
  271.         11.4  Defining Repeat Blocks%@BO:       982dc@%%@NL@%
  272.               11.4.1  The REPT Directive%@BO:       9891a@%%@NL@%
  273.               11.4.2  The IRP Directive%@BO:       98e70@%%@NL@%
  274.               11.4.3  The IRPC Directive%@BO:       99749@%%@NL@%
  275.         11.5  Using Macro Operators%@BO:       9a1b8@%%@NL@%
  276.               11.5.1  Substitute Operator%@BO:       9a58b@%%@NL@%
  277.               11.5.2  Literal-Text Operator%@BO:       9b48f@%%@NL@%
  278.               11.5.3  Literal-Character Operator%@BO:       9bf61@%%@NL@%
  279.               11.5.4  Expression Operator%@BO:       9c525@%%@NL@%
  280.               11.5.5  Macro Comments%@BO:       9e12a@%%@NL@%
  281.         11.6  Using Recursive, Nested, and Redefined Macros%@BO:       9e5c9@%%@NL@%
  282.               11.6.1  Using Recursion%@BO:       9e78b@%%@NL@%
  283.               11.6.2  Nesting Macro Definitions%@BO:       9ec85@%%@NL@%
  284.               11.6.3  Nesting Macro Calls%@BO:       9f74e@%%@NL@%
  285.               11.6.4  Redefining Macros%@BO:       9ffc4@%%@NL@%
  286.               11.6.5  Avoiding Inadvertent Substitutions%@BO:       a0677@%%@NL@%
  287.         11.7  Managing Macros and Equates%@BO:       a0af7@%%@NL@%
  288.               11.7.1  Using Include Files%@BO:       a0d21@%%@NL@%
  289.               11.7.2  Purging Macros from Memory%@BO:       a1a12@%%@NL@%
  290. %@NL@%
  291. %@AB@%Chapter 12  Controlling Assembly Output%@AE@%%@BO:       a2236@%%@NL@%
  292.         12.1  Sending Messages to the Standard Output Device%@BO:       a2455@%%@NL@%
  293.         12.2  Controlling Page Format in Listings%@BO:       a2ad0@%%@NL@%
  294.               12.2.1  Setting the Listing Title%@BO:       a2dc2@%%@NL@%
  295.               12.2.2  Setting the Listing Subtitle%@BO:       a32b6@%%@NL@%
  296.               12.2.3  Controlling Page Breaks%@BO:       a39b9@%%@NL@%
  297.               12.2.4  Naming the Module%@BO:       a4677@%%@NL@%
  298.         12.3  Controlling the Contents of Listings%@BO:       a47ae@%%@NL@%
  299.               12.3.1  Suppressing and Restoring Listing Output%@BO:       a4c32@%%@NL@%
  300.               12.3.2  Controlling Listing of Conditional Blocks%@BO:       a518f@%%@NL@%
  301.               12.3.3  Controlling Listing of Macros%@BO:       a5d0c@%%@NL@%
  302. %@NL@%
  303. %@AB@%Chapter 13  Loading, Storing, and Moving Data%@AE@%%@BO:       a71ac@%%@NL@%
  304.         13.1  Transferring Data%@BO:       a7396@%%@NL@%
  305.               13.1.1  Copying Data%@BO:       a759d@%%@NL@%
  306.               13.1.2  Exchanging Data%@BO:       a8091@%%@NL@%
  307.               13.1.3  Looking Up Data%@BO:       a8377@%%@NL@%
  308.               13.1.4  Transferring Flags%@BO:       a90c8@%%@NL@%
  309.         13.2  Converting between Data Sizes%@BO:       a94e2@%%@NL@%
  310.               13.2.1  Extending Signed Values%@BO:       a9772@%%@NL@%
  311.               13.2.2  Extending Unsigned Values%@BO:       a9de1@%%@NL@%
  312.         13.3  Loading Pointers%@BO:       aa128@%%@NL@%
  313.               13.3.1  Loading Near Pointers%@BO:       aa259@%%@NL@%
  314.               13.3.2  Loading Far Pointers%@BO:       aa7dc@%%@NL@%
  315.         13.4  Transferring Data to and from the Stack%@BO:       aaec9@%%@NL@%
  316.               13.4.1  Pushing and Popping%@BO:       ab441@%%@NL@%
  317.               13.4.2  Using the Stack%@BO:       ac5c8@%%@NL@%
  318.               13.4.3  Saving Flags on the Stack%@BO:       acdc0@%%@NL@%
  319.               13.4.4  Saving All Registers on the Stack%@BO:       ad126@%%@NL@%
  320.         13.5  Transferring Data to and from Ports%@BO:       ad681@%%@NL@%
  321. %@NL@%
  322. %@AB@%Chapter 14  Doing Arithmetic and Bit Manipulations%@AE@%%@BO:       ae658@%%@NL@%
  323.         14.1  Adding%@BO:       ae8c6@%%@NL@%
  324.               14.1.1  Adding Values Directly%@BO:       aed84@%%@NL@%
  325.               14.1.2  Adding Values in Multiple Registers%@BO:       afe06@%%@NL@%
  326.         14.2  Subtracting%@BO:       b06f6@%%@NL@%
  327.               14.2.1  Subtracting Values Directly%@BO:       b0c2b@%%@NL@%
  328.               14.2.2  Subtracting with Values in Multiple Registers%@BO:       b1c0d@%%@NL@%
  329.         14.3  Multiplying%@BO:       b2553@%%@NL@%
  330.         14.4  Dividing%@BO:       b3ae1@%%@NL@%
  331.         14.5  Calculating with Binary Coded Decimals%@BO:       b4ede@%%@NL@%
  332.               14.5.1  Unpacked BCD Numbers%@BO:       b53c9@%%@NL@%
  333.               14.5.2  Packed BCD Numbers%@BO:       b69dc@%%@NL@%
  334.         14.6  Doing Logical Bit Manipulations%@BO:       b74b7@%%@NL@%
  335.               14.6.1  AND Operations%@BO:       b8064@%%@NL@%
  336.               14.6.2  OR Operations%@BO:       b8a3f@%%@NL@%
  337.               14.6.3  XOR Operations%@BO:       b9322@%%@NL@%
  338.               14.6.4  NOT Operations%@BO:       b9cba@%%@NL@%
  339.         14.7  Shifting and Rotating Bits%@BO:       ba3f6@%%@NL@%
  340.               14.7.1  Multiplying and Dividing by Constants%@BO:       bb18b@%%@NL@%
  341.               14.7.2  Moving Bits to the Least-Significant Position%@BO:       bbea4@%%@NL@%
  342.               14.7.3  Adjusting Masks%@BO:       bc14a@%%@NL@%
  343.               14.7.4  Shifting Multiword Values%@BO:       bc6f5@%%@NL@%
  344. %@NL@%
  345. %@AB@%Chapter 15  Controlling Program Flow%@AE@%%@BO:       bcdd3@%%@NL@%
  346.         15.1  Jumping%@BO:       bcff4@%%@NL@%
  347.               15.1.1  Jumping Unconditionally%@BO:       bd2e4@%%@NL@%
  348.               15.1.2  Jumping Conditionally%@BO:       be4fa@%%@NL@%
  349.                       15.1.2.1  Comparing and Jumping%@BO:       bf2c9@%%@NL@%
  350.                       15.1.2.2  Jumping Based on Flag Status%@BO:       c0ebd@%%@NL@%
  351.                       15.1.2.3  Testing Bits and Jumping%@BO:       c19f4@%%@NL@%
  352.         15.2  Looping%@BO:       c265d@%%@NL@%
  353.         15.3  Using Procedures%@BO:       c3a3e@%%@NL@%
  354.               15.3.1  Calling Procedures%@BO:       c470d@%%@NL@%
  355.               15.3.2  Defining Procedures%@BO:       c4c26@%%@NL@%
  356.               15.3.3  Passing Arguments on the Stack%@BO:       c60b0@%%@NL@%
  357.               15.3.4  Declaring Parameters with the PROC Directive%@BO:       c7284@%%@NL@%
  358.               15.3.5  Using Local Variables%@BO:       c9deb@%%@NL@%
  359.               15.3.6  Creating Locals Automatically%@BO:       cb138@%%@NL@%
  360.               15.3.7  Variable Scope%@BO:       cc4c8@%%@NL@%
  361.               15.3.8  Setting Up Stack Frames%@BO:       cce8a@%%@NL@%
  362.         15.4  Using Interrupts%@BO:       cdbc9@%%@NL@%
  363.               15.4.1  Calling Interrupts%@BO:       ce52a@%%@NL@%
  364.               15.4.2  Defining and Redefining Interrupt Routines%@BO:       cf793@%%@NL@%
  365.         15.5  Checking Memory Ranges%@BO:       d0ebd@%%@NL@%
  366. %@NL@%
  367. %@AB@%Chapter 16  Processing Strings%@AE@%%@BO:       d1833@%%@NL@%
  368.         16.1  Setting Up String Operations%@BO:       d1f06@%%@NL@%
  369.         16.2  Moving Strings%@BO:       d40ac@%%@NL@%
  370.         16.3  Searching Strings%@BO:       d52a2@%%@NL@%
  371.         16.4  Comparing Strings%@BO:       d60d5@%%@NL@%
  372.         16.5  Filling Strings%@BO:       d7174@%%@NL@%
  373.         16.6  Loading Values from Strings%@BO:       d79db@%%@NL@%
  374.         16.7  Transferring Strings to and from Ports%@BO:       d8b5c@%%@NL@%
  375. %@NL@%
  376. %@AB@%Chapter 17  Calculating with a Math Coprocessor%@AE@%%@BO:       d965a@%%@NL@%
  377.         17.1  Coprocessor Architecture%@BO:       d9b76@%%@NL@%
  378.               17.1.1  Coprocessor Data Registers%@BO:       da015@%%@NL@%
  379.               17.1.2  Coprocessor Control Registers%@BO:       da706@%%@NL@%
  380.         17.2  Emulation%@BO:       dae73@%%@NL@%
  381.         17.3  Using Coprocessor Instructions%@BO:       db35c@%%@NL@%
  382.               17.3.1  Using Implied Operands in the Classical-Stack Form%@BO:       dc0bc@%%@NL@%
  383.               17.3.2  Using Memory Operands%@BO:       dc9e0@%%@NL@%
  384.               17.3.3  Specifying Operands in the Register Form%@BO:       dd3d0@%%@NL@%
  385.               17.3.4  Specifying Operands in the Register-Pop Form%@BO:       ddb1e@%%@NL@%
  386.         17.4  Coordinating Memory Access%@BO:       de11e@%%@NL@%
  387.         17.5  Transferring Data%@BO:       dedf8@%%@NL@%
  388.               17.5.1  Transferring Data to and from Registers%@BO:       defb7@%%@NL@%
  389.                       17.5.1.1  Real Transfers%@BO:       df628@%%@NL@%
  390.                       17.5.1.2  Integer Transfers%@BO:       dff78@%%@NL@%
  391.                       17.5.1.3  Packed BCD Transfers%@BO:       e054c@%%@NL@%
  392.               17.5.2  Loading Constants%@BO:       e11e1@%%@NL@%
  393.               17.5.3  Transferring Control Data%@BO:       e1971@%%@NL@%
  394.         17.6  Doing Arithmetic Calculations%@BO:       e24a3@%%@NL@%
  395.         17.7  Controlling Program Flow%@BO:       e64cc@%%@NL@%
  396.               17.7.1  Comparing Operands to Control Program Flow%@BO:       e6d88@%%@NL@%
  397.                       17.7.1.1  Compare%@BO:       e74e1@%%@NL@%
  398.                       17.7.1.2  Compare and Pop%@BO:       e79bf@%%@NL@%
  399.               17.7.2  Testing Control Flags after Other Instructions%@BO:       e8aba@%%@NL@%
  400.         17.8  Using Transcendental Instructions%@BO:       e90ee@%%@NL@%
  401.         17.9  Controlling the Coprocessor%@BO:       e9fb7@%%@NL@%
  402. %@NL@%
  403. %@AB@%Chapter 18  Controlling the Processor%@AE@%%@BO:       eab36@%%@NL@%
  404.         18.1  Controlling Timing and Alignment%@BO:       eae62@%%@NL@%
  405.         18.2  Controlling the Processor%@BO:       eb42c@%%@NL@%
  406.         18.3  Processor Directives%@BO:       ebd6e@%%@NL@%
  407. %@NL@%
  408. %@AB@%Appendix A  Mixed-Language Mechanics%@AE@%%@BO:       ed697@%%@NL@%
  409.         A.1  Writing the Assembly Procedure%@BO:       edd84@%%@NL@%
  410.              A.1.1  Setting Up the Procedure%@BO:       ee356@%%@NL@%
  411.              A.1.2  Entering the Procedure%@BO:       eea11@%%@NL@%
  412.              A.1.3  Allocating Local Data (Optional)%@BO:       ef0a0@%%@NL@%
  413.              A.1.4  Preserving Register Values%@BO:       ef916@%%@NL@%
  414.              A.1.5  Accessing Parameters%@BO:       efea0@%%@NL@%
  415.              A.1.6  Returning a Value (Optional)%@BO:       f10ef@%%@NL@%
  416.              A.1.7  Exiting the Procedure%@BO:       f1e90@%%@NL@%
  417.         A.2  Calls from Modules Using C Conventions%@BO:       f27fe@%%@NL@%
  418.         A.3  Calls from Non-C Modules%@BO:       f3f49@%%@NL@%
  419.         A.4  Calling High-Level Languages from Assembly Language%@BO:       f5679@%%@NL@%
  420.         A.5  Using Full Segment Definitions%@BO:       f5e57@%%@NL@%
  421. %@NL@%
  422. %@AB@%Appendix B  Using Assembler Options with QCL%@AE@%%@BO:       f653b@%%@NL@%
  423.         B.1  Specifying the Segment-Order Method%@BO:       f7a41@%%@NL@%
  424.         B.2  Checking Code for Tiny Model%@BO:       f829e@%%@NL@%
  425.         B.3  Selecting Case Sensitivity%@BO:       f8648@%%@NL@%
  426.         B.4  Defining Assembler Symbols%@BO:       f8ea4@%%@NL@%
  427.         B.5  Displaying Error Lines on the Screen%@BO:       f96cf@%%@NL@%
  428.         B.6  Creating Code for a Floating-Point Emulator%@BO:       f9a75@%%@NL@%
  429.         B.7  Creating Listing Files%@BO:       fa7e3@%%@NL@%
  430.         B.8  Enabling One-Pass Assembly%@BO:       fab38@%%@NL@%
  431.         B.9  Listing All Lines of Macro Expansions%@BO:       fafe0@%%@NL@%
  432.         B.10  Creating a Pass 1 Listing%@BO:       fb2f8@%%@NL@%
  433.         B.11  Specifying an Editor-Oriented Listing%@BO:       fb5b2@%%@NL@%
  434.         B.12  Suppressing Tables in the Listing File%@BO:       fb87f@%%@NL@%
  435.         B.13  Adding a Line-Number Index to the Listing%@BO:       fbb4c@%%@NL@%
  436.         B.14  Listing False Conditionals%@BO:       fbf3d@%%@NL@%
  437.         B.15  Controlling Display of Assembly Statistics%@BO:       fc55d@%%@NL@%
  438.         B.16  Setting the Warning Level%@BO:       fc9ca@%%@NL@%
  439. %@NL@%
  440. %@AB@%Appendix C  Reading Assembly Listings%@AE@%%@BO:       fd1fd@%%@NL@%
  441.         C.1  Reading Code in a Listing%@BO:       fd684@%%@NL@%
  442.         C.2  Reading a Macro Table%@BO:       ff16e@%%@NL@%
  443.         C.3  Reading a Structure and Record Table%@BO:       ff39a@%%@NL@%
  444.         C.4  Reading a Segment and Group Table%@BO:       ffde3@%%@NL@%
  445.         C.5  Reading a Symbol Table%@BO:      10061e@%%@NL@%
  446.         C.6  Reading Assembly Statistics%@BO:      1017b0@%%@NL@%
  447.         C.7  Reading a Pass 1 Listing%@BO:      101a0c@%%@NL@%
  448. %@NL@%
  449. %@AB@%Index%@AE@%%@BO:      102280@%%@NL@%
  450. %@NL@%
  451. %@NL@%
  452. %@NL@%
  453. ────────────────────────────────────────────────────────────────────────────%@NL@%
  454. %@1@%%@CR:CH0         @%%@AB@%Introduction%@AE@%%@EH@%%@NL@%
  455. %@NL@%
  456. %@NL@%
  457. %@4@%  If you're a C programmer who has been wanting to try out the full power of%@EH@%
  458.   assembly language, this is the product for you.%@NL@%
  459. %@NL@%
  460. %@4@%  Microsoft(R) QuickC(R) with QuickAssembler is a package you install along%@EH@%
  461.   with Microsoft QuickC Version 2.0 in order to create a single powerful
  462.   environment in which you can develop C, assembly, and mixed-language
  463.   programs. What's more, QuickAssembler is an integrated environment,
  464.   containing tools for editing, assembling, compiling, and linking.
  465.   Integrated tools help you achieve faster development of assembly-language
  466.   programs.%@NL@%
  467. %@NL@%
  468. %@4@%  Each MS-DOS(R) and IBM(R) PC-DOS computer is driven by one of the%@EH@%
  469.   processors in the 8086 family. A processor is the central motor of a
  470.   computer. It responds to its own numeric language, called "machine code."
  471.   Assembly language is very close to machine code, but it lets you use
  472.   meaningful keywords and variable names instead of difficult-to-remember
  473.   numeric codes. As a result, assembly language is convenient to use, but
  474.   gives you the ultimate in ability to control hardware and optimize code.%@NL@%
  475. %@NL@%
  476. %@4@%  To support the low-level operations of assembly language, QuickAssembler%@EH@%
  477.   expands the general power of the QuickC environment. Increased debugging
  478.   capabilities let you change flag settings and modify registers──including
  479.   registers of the 8087 math coprocessor. Furthermore, the Quick Advisor
  480.   (the on-line Help system) is expanded to provide help on QuickAssembler
  481.   keywords as well as DOS and ROM-BIOS services.%@NL@%
  482. %@NL@%
  483. %@3@%  %@AB@%A Note about Operating-System Terms%@AE@%%@EH@%%@NL@%
  484. %@NL@%
  485. %@4@%  Microsoft documentation uses the term "OS/2" to refer to the OS/2 system──%@EH@%
  486.   Microsoft Operating System/2 (MS(R) OS/2) and IBM OS/2. Similarly, the
  487.   term "DOS" refers to both the MS-DOS and IBM Personal Computer DOS
  488.   operating systems. The name of a specific operating system is used when it
  489.   is necessary to note features unique to that system.%@NL@%
  490. %@NL@%
  491. %@NL@%
  492. %@2@%%@AB@%General Features%@AE@%%@EH@%%@NL@%
  493. %@NL@%
  494. %@4@%  QuickAssembler does not replace the QuickC in-line assembler, which you%@EH@%
  495.   can continue to use inside .C files. The joint QuickC/QuickAssembler
  496.   environment puts both QuickAssember and the in-line assembler at your
  497.   disposal. But Microsoft QuickAssembler supports a number of features
  498.   beyond those supported by the in-line assembler:%@NL@%
  499. %@NL@%
  500.   ■  You can write stand-alone assembly programs. These programs begin and
  501.      end with assembly code and do not include the C start-up code. Unlike
  502.      programs written from within C modules, useful stand-alone assembly
  503.      programs can be 1K (kilobyte) or even smaller.%@NL@%
  504. %@NL@%
  505.   ■  You can use the assembler's rich set of macro-definition capabilities,
  506.      which go far beyond the macro capabilities supported by C. An
  507.      assembly-language macro can handle variable parameter lists, recursion,
  508.      and repeated operations. These macros are roughly as powerful and
  509.      flexible as procedure calls, but execute faster.%@NL@%
  510. %@NL@%
  511.   ■  Your assembly modules can be shared by many different programs. Since
  512.      an assembly-language module is in its own file, you can write the
  513.      module once and link it to any program you want.%@NL@%
  514. %@NL@%
  515.   ■  QuickAssembler is a full implementation of 8086 assembly language. You
  516.      can use the full set of the Microsoft Macro Assembler 5.1 directives
  517.      and operators.%@NL@%
  518. %@NL@%
  519. %@4@%  In addition, QuickAssembler provides the best set of keywords yet%@EH@%
  520.   available for simplifying tedious programming tasks, such as initializing
  521.   registers at the beginning of a program or determining how to access
  522.   parameters on the stack. (Part 1%@BO:        b8f5@% of this manual focuses on the use of
  523.   these keywords.)%@NL@%
  524. %@NL@%
  525. %@4@%  QuickAssembler for QuickC is a DOS-based product, and it does not include%@EH@%
  526.   the following extensions to 8086 assembly language:%@NL@%
  527. %@NL@%
  528.   ■  80386 extended registers and special instructions%@NL@%
  529. %@NL@%
  530.   ■  80387 extended instructions%@NL@%
  531. %@NL@%
  532.   ■  OS/2 protected-mode operation%@NL@%
  533. %@NL@%
  534. %@4@%  QuickAssembler does support the 80286 extended instruction set, as well as%@EH@%
  535.   the 8087 and 80287 coprocessors. The 80386 processor can run all
  536.   QuickAssembler programs; the only limitation is that QuickAssembler does
  537.   not support extended capabilities of the 80386.%@NL@%
  538. %@NL@%
  539. %@4@%  The Microsoft Macro Assembler supports 80386 extended features and%@EH@%
  540.   development of protected-mode applications.%@NL@%
  541. %@NL@%
  542. %@NL@%
  543. %@2@%%@AB@%System Requirements%@AE@%%@EH@%%@NL@%
  544. %@NL@%
  545. %@4@%%@CR:IX0.1       @%%@CR:IX0.2       @%%@CR:IX0.3       @%  In addition to a computer with one of the 8086-family processors, you must%@EH@%
  546.   have Version 2.1 or later of the MS-DOS or IBM PC-DOS operating system.
  547.   You can also run QuickAssembler in the 3.x compatibility box of OS/2
  548.   systems. Your computer system must have approximately 512K of memory. A
  549.   hard-disk setup is strongly recommended.%@NL@%
  550. %@NL@%
  551. %@4@%  To enable the use of QuickAssembler, you should first choose Full Menus%@EH@%
  552.   from the Options menu.%@NL@%
  553. %@NL@%
  554.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  555.   %@AB@%NOTE%@AE@%  The 8086 family is a set of processors that all support the same
  556.   basic instruction set. This family includes the 8088, 8086, 80188, 80186,
  557.   80286, and 80386 chips. All of these processors support the entire
  558.   instruction set of the 8086 itself; some support additional instructions.
  559.   Rather than list the entire set of chips, this manual often discusses the
  560.   core instruction set by referring only to the 8086.%@NL@%
  561.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  562. %@NL@%
  563. %@NL@%
  564. %@2@%%@AB@%Installing QuickAssembler%@AE@%%@EH@%%@NL@%
  565. %@NL@%
  566. %@4@%  If you purchased QuickC and QuickAssembler together, the installation%@EH@%
  567.   procedure described in %@AI@%Up%@AE@% %@AI@%and%@AE@% %@AI@%Running%@AE@% automatically installs both
  568.   products. A few of the questions shown in that booklet are reworded in the
  569.   install program to make more sense for the joint QuickC/QuickAssembler
  570.   installation.%@NL@%
  571. %@NL@%
  572. %@4@%  If you purchased QuickAssembler separately, run the installation program%@EH@%
  573.   on the QuickAssembler distribution disks. The first screen asks you the
  574.   following questions:%@NL@%
  575. %@NL@%
  576.   %@AS@%Source of assembler files [A:]:%@AE@%%@NL@%
  577.   %@AS@%Installing on a hard disk drive [Y]:%@AE@%%@NL@%
  578.   %@AS@%Copy QuickAssembler documentation files [Y]:%@AE@%%@NL@%
  579.   %@AS@%Copy sample Assembler programs [N]:%@AE@%%@NL@%
  580. %@NL@%
  581.   %@AS@%Do you want to change any of the above options? [N]%@AE@%%@NL@%
  582. %@NL@%
  583. %@4@%  As with the QuickC installation program, the default responses are%@EH@%
  584.   indicated in brackets ([]). Each of these questions is accompanied by an
  585.   explanation at the bottom of the screen. To accept a default response,
  586.   press ENTER. If you enter an incorrect response, just answer no (N) to the
  587.   last question.%@NL@%
  588. %@NL@%
  589. %@4@%  The second screen asks you the following questions:%@EH@%%@NL@%
  590. %@NL@%
  591.   %@AS@%Directory for QuickC executable files [C:\QC2\BIN]:%@AE@%%@NL@%
  592.   %@AS@%Directory for Sample files [C:\QC2\SAMPLES]:%@AE@%%@NL@%
  593. %@NL@%
  594.   %@AS@%Do you want to change any of the above options? [N]%@AE@%%@NL@%
  595. %@NL@%
  596. %@4@%  The QuickAssembler installation program replaces some of the existing%@EH@%
  597.   QuickC files. QuickAssembler must be installed in the directory that
  598.   currently contains QC.EXE. Make sure you enter the location of your
  599.   current QuickC executable files. If you're not sure, press CTRL+C to stop
  600.   the installation and examine your setup.%@NL@%
  601. %@NL@%
  602. %@NL@%
  603. %@2@%%@AB@%Getting Information about Assembly Language%@AE@%%@EH@%%@NL@%
  604. %@NL@%
  605. %@4@%  The combined paper and on-line documentation with QuickAssembler gives you%@EH@%
  606.   a complete reference to the language. This manual provides three basic
  607.   kinds of information:%@NL@%
  608. %@NL@%
  609.   ■  Part 1%@BO:        b8f5@%, "Introducing QuickAssembler," provides a basic introduction to
  610.      programming in assembly language. Chapter 1%@BO:        bdb6@% describes how the
  611.      interface changes when you install QuickAssembler. Chapter 2%@BO:       151ff@% gives a
  612.      general background to 8086 architecture and assembly-language concepts.
  613.      Chapters 3%@BO:       2aca0@% and 4%@BO:       34dba@% demonstrate how to use special QuickAssembler
  614.      keywords to simplify programming. Even if you have used assembly
  615.      language before, you should take a look at these chapters.%@NL@%
  616. %@NL@%
  617.   ■  Parts 2%@BO:       3faf8@% ("Using Directives") and 3%@BO:       a6c61@% ("Using Instructions") give a
  618.      reference to the use of directives and instructions. This material is
  619.      much less tutorial than Part 1%@BO:        b8f5@%, but it does illustrate the use of each
  620.      directive and instruction in context.%@NL@%
  621. %@NL@%
  622.   ■  The appendixes explain low-level mixed-language techniques, the use of
  623.      assembly options with the QCL driver, and how to read listing files.%@NL@%
  624. %@NL@%
  625. %@4@%  This manual does not teach systems programming or advanced programming%@EH@%
  626.   techniques. Even with the tutorial material provided in this manual, you
  627.   may want to purchase other books on assembly language, such as the ones
  628.   listed in the next section.%@NL@%
  629. %@NL@%
  630. %@4@%  In addition, this manual assumes you understand certain basic concepts of%@EH@%
  631.   programming, such as modules, variables, and pointers. If you need more
  632.   background in one of these topics, you should first read the appropriate
  633.   sections in %@AI@%C%@AE@% %@AI@%For%@AE@% %@AI@%Yourself%@AE@%. Part 1%@BO:        b8f5@% of this manual often explains concepts
  634.   by comparing a language feature to C.%@NL@%
  635. %@NL@%
  636. %@4@%  The Quick Advisor (the on-line Help system) is an integral part of the%@EH@%
  637.   overall documentation. As explained in Section 1.5%@BO:        f864@%, "Using the Quick
  638.   Advisor (Help)," QuickAssembler provides help on all keywords──in
  639.   particular, you get instant reference information on each instruction,
  640.   including timing, encoding, and flag settings. The Help Contents and Index
  641.   screens also provide information on each DOS service.%@NL@%
  642. %@NL@%
  643. %@NL@%
  644. %@2@%%@AB@%Books on Assembly Language%@AE@%%@EH@%%@NL@%
  645. %@NL@%
  646. %@4@%%@CR:IX0.4       @%%@CR:IX0.5       @%%@CR:IX0.6       @%  The following books may be useful in learning to program in assembly%@EH@%
  647.   language:%@NL@%
  648. %@NL@%
  649. %@4@%  Duncan, Ray. %@AI@%Advanced%@AE@% %@AI@%MS-DOS%@AE@%. Redmond, WA: Microsoft Corporation, 1986.%@EH@%%@NL@%
  650. %@NL@%
  651. %@4@%    An intermediate book on writing C and assembly-language programs that%@EH@%
  652.     interact with MS-DOS (includes DOS and BIOS function descriptions)%@NL@%
  653. %@NL@%
  654. %@4@%  Jourdain, Robert. %@AI@%Programmer's%@AE@% %@AI@%Problem%@AE@% %@AI@%Solver%@AE@% %@AI@%for%@AE@% %@AI@%the%@AE@% %@AI@%IBM%@AE@% %@AI@%PC,%@AE@% %@AI@%XT%@AE@% %@AI@%and%@AE@% %@AI@%AT%@AE@%.%@EH@%
  655.     New York: Brady Communications Company, Inc., 1986.%@NL@%
  656. %@NL@%
  657. %@4@%    Reference of routines and techniques for interacting with hardware%@EH@%
  658.     devices through DOS, BIOS, and ports (high-level routines in BASIC and
  659.     low- or medium-level routines in assembler)%@NL@%
  660. %@NL@%
  661. %@4@%  Lafore, Robert. %@AI@%Assembly%@AE@% %@AI@%Language%@AE@% %@AI@%Primer%@AE@% %@AI@%for%@AE@% %@AI@%the%@AE@% %@AI@%IBM%@AE@% %@AI@%PC%@AE@% %@AI@%&%@AE@% %@AI@%XT%@AE@%. New York:%@EH@%
  662.     Plume/Waite, 1984.%@NL@%
  663. %@NL@%
  664. %@4@%    An introduction to assembly language, including some information on DOS%@EH@%
  665.     function calls and IBM-type BIOS%@NL@%
  666. %@NL@%
  667. %@4@%  Metcalf, Christopher D., and Sugiyama, Marc B. %@AI@%COMPUTE!'s%@AE@% %@AI@%Beginner's%@AE@% %@AI@%Guide%@AE@%%@EH@%
  668.     %@AI@%to%@AE@% %@AI@%Machine%@AE@% %@AI@%Language%@AE@% %@AI@%on%@AE@% %@AI@%the%@AE@% %@AI@%IBM%@AE@% %@AI@%PC%@AE@% %@AI@%&%@AE@% %@AI@%PCjr%@AE@%. Greensboro, NC: COMPUTE!
  669.     Publications, Inc., 1985.%@NL@%
  670. %@NL@%
  671. %@4@%    Beginning discussion of assembly language, including information on the%@EH@%
  672.     instruction set and MS-DOS function calls%@NL@%
  673. %@NL@%
  674. %@4@%  %@AI@%Microsoft%@AE@% %@AI@%MS-DOS%@AE@% %@AI@%Programmer's%@AE@% %@AI@%Reference%@AE@%. Redmond, WA: Microsoft Press,%@EH@%
  675.     1986, 1987.%@NL@%
  676. %@NL@%
  677. %@4@%    Reference manual for MS-DOS%@EH@%%@NL@%
  678. %@NL@%
  679. %@4@%  Morgan, Christopher, and the Waite Group. %@AI@%Bluebook%@AE@% %@AI@%of%@AE@% %@AI@%Assembly%@AE@% %@AI@%Routines%@AE@%%@EH@%
  680.     %@AI@%for%@AE@% %@AI@%the%@AE@% %@AI@%IBM%@AE@% %@AI@%PC%@AE@%. New York: New American Library, 1984.%@NL@%
  681. %@NL@%
  682. %@4@%    Sample assembly routines that can be integrated into assembly or%@EH@%
  683.     high-level-language programs%@NL@%
  684. %@NL@%
  685. %@4@%  Norton, Peter. %@AI@%The%@AE@% %@AI@%Peter%@AE@% %@AI@%Norton%@AE@% %@AI@%Programmer's%@AE@% %@AI@%Guide%@AE@% %@AI@%to%@AE@% %@AI@%the%@AE@% %@AI@%IBM%@AE@% %@AI@%PC%@AE@%. Redmond,%@EH@%
  686.     WA: Microsoft Press, 1985.%@NL@%
  687. %@NL@%
  688. %@4@%    Information on using IBM-type BIOS and MS-DOS function calls%@EH@%%@NL@%
  689. %@NL@%
  690. %@4@%  Scanlon, Leo J. %@AI@%IBM%@AE@% %@AI@%PC%@AE@% %@AI@%Assembly%@AE@% %@AI@%Language:%@AE@% %@AI@%A%@AE@% %@AI@%Guide%@AE@% %@AI@%for%@AE@% %@AI@%Programmers%@AE@%. Bowie,%@EH@%
  691.     MD: Robert J. Brady Co., 1983.%@NL@%
  692. %@NL@%
  693. %@4@%    An introduction to assembly language, including information on DOS%@EH@%
  694.     function calls%@NL@%
  695. %@NL@%
  696. %@4@%  Schneider, Al. %@AI@%Fundamentals%@AE@% %@AI@%of%@AE@% %@AI@%IBM%@AE@% %@AI@%PC%@AE@% %@AI@%Assembly%@AE@% %@AI@%Language%@AE@%. Blue Ridge%@EH@%
  697.     Summit, PA: Tab Books Inc., 1984.%@NL@%
  698. %@NL@%
  699. %@4@%    An introduction to assembly language, including information on DOS%@EH@%
  700.     function calls%@NL@%
  701. %@NL@%
  702. %@4@%  These books are listed for your convenience only. Microsoft Corporation%@EH@%
  703.   does not endorse these books (with the exception of those published by
  704.   Microsoft) or recommend them over others on the same subjects.%@NL@%
  705. %@NL@%
  706. %@NL@%
  707. %@2@%%@AB@%Document Conventions%@AE@%%@EH@%%@NL@%
  708. %@NL@%
  709. %@4@%%@CR:IX0.7       @%  The following document conventions are used throughout this manual:%@EH@%%@NL@%
  710. %@NL@%
  711.   %@AB@%Example of%@AE@%          %@AB@%Description%@AE@%
  712.   %@AB@%Convention%@AE@%%@NL@%
  713.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  714.   SAMPLE2.ASM         Uppercase letters indicate file names, segment names,
  715.                       registers, and terms used at the DOS-command level.%@NL@%
  716. %@NL@%
  717.   %@AB@%.MODEL%@AE@%              Boldface type indicates assembly-language directives,
  718.                       instructions, type specifiers, and predefined equates,
  719.                       as well as keywords in other programming languages.%@NL@%
  720. %@NL@%
  721.   %@AI@%placeholders%@AE@%        Italic letters indicate placeholders for information
  722.                       you must supply, such as a file name. Italics are also
  723.                       occasionally used for emphasis in the text.%@NL@%
  724. %@NL@%
  725.   %@AS@%target%@AE@%              This font is used to indicate example programs, user
  726.                       input, and screen output.%@NL@%
  727. %@NL@%
  728.   SHIFT               Names of keys on the keyboard appear in small capital
  729.                       letters. Notice that a plus (+) indicates a
  730.                       combination of keys. For example, CTRL+E means to hold
  731.                       down the CTRL key while pressing the E key.%@NL@%
  732. %@NL@%
  733.   [[%@AI@%argument%@AE@% ]]       Items inside double square brackets are optional.%@NL@%
  734. %@NL@%
  735.   {%@AI@%register%@AE@% | %@AI@%memory%@AE@%} Braces and a vertical bar indicate a choice between
  736.                       two or more items. You must choose one of the items
  737.                       unless double square brackets surround the braces.%@NL@%
  738. %@NL@%
  739.   Repeating           Three dots following an item indicate that more items
  740.   elements...         having the same form may appear.%@NL@%
  741. %@NL@%
  742.   %@AS@%Program%@AE@%             A column of three dots tells you that part of a
  743.   %@AS@%.%@AE@%                   program has been intentionally omitted.%@NL@%
  744.   %@AS@%.%@AE@%%@NL@%
  745.   %@AS@%.%@AE@%%@NL@%
  746.   %@AS@%Fragment%@AE@%%@NL@%
  747. %@NL@%
  748.   "processor flag"    The first time a new term is defined, it is enclosed
  749.                       in quotation marks.%@NL@%
  750. %@NL@%
  751.   Color Graphics      The first time an acronym is used, it is spelled out.
  752.   Adapter (CGA)%@NL@%
  753. %@NL@%
  754. %@NL@%
  755. %@2@%%@AB@%Getting Assistance or Reporting Problems%@AE@%%@EH@%%@NL@%
  756. %@NL@%
  757. %@4@%%@CR:IX0.8       @%%@CR:IX0.9       @%%@CR:IX0.10      @%%@CR:IX0.11      @%  If you need help or feel you have discovered a problem in the software,%@EH@%
  758.   please provide the following information to help us locate the problem:%@NL@%
  759. %@NL@%
  760.   ■  The version of DOS you are running (use the DOS VER command)%@NL@%
  761. %@NL@%
  762.   ■  Your system configuration (the type of machine you are using, its total
  763.      memory, and its total free memory at assembler execution time, as well
  764.      as any other information you think might be useful)%@NL@%
  765. %@NL@%
  766.   ■  The assembly command line used (or the link command line if the problem
  767.      occurred during linking)%@NL@%
  768. %@NL@%
  769.   ■  Any object files or libraries you linked with if the problem occurred
  770.      at link time%@NL@%
  771. %@NL@%
  772. %@4@%  If your program is very large, please try to reduce its size to the%@EH@%
  773.   smallest possible program that still produces the problem.%@NL@%
  774. %@NL@%
  775. %@4@%  Use the Product Assistance Request form at the back of this manual to send%@EH@%
  776.   this information to Microsoft.%@NL@%
  777. %@NL@%
  778. %@4@%%@CR:IX0.12      @%  If you have comments or suggestions regarding any of the manuals%@EH@%
  779.   accompanying this product, please indicate them on the Document Feedback
  780.   card at the back of this manual.%@NL@%
  781. %@NL@%
  782. %@4@%%@CR:IX0.13      @%  If you are not already a registered QuickAssembler owner, you should fill%@EH@%
  783.   out and return the Registration Card. This enables Microsoft to keep you
  784.   informed of updates and other information about the assembler.%@NL@%
  785. %@NL@%
  786. %@NL@%
  787. %@NL@%
  788. ────────────────────────────────────────────────────────────────────────────%@NL@%
  789. %@1@%%@CR:PT1         @%%@AB@%PART 1:  Using Assembler Programs%@AE@%%@EH@%%@NL@%
  790. %@NL@%
  791. %@NL@%
  792. %@4@%  Part 1%@BO:        b8f5@% of the Programmer's Guide (comprising Chapters 1%@BO:        bdb6@%-4%@BO:       34dba@%) will help%@EH@%
  793.   you start using assembly language quickly.%@NL@%
  794. %@NL@%
  795. %@4@%  Chapter 1%@BO:        bdb6@% summarizes all the differences between the standard QuickC%@EH@%
  796.   interface and the expanded QuickC/QuickAssembler interface. Read this
  797.   chapter to learn how to enter, assemble, and run an assembly-language
  798.   program.%@NL@%
  799. %@NL@%
  800. %@4@%  Read Chapter 2%@BO:       151ff@% if you are new to 8086 assembly language or need to review%@EH@%
  801.   basic concepts. Chapter 2%@BO:       151ff@% explains the architecture of 8086-family
  802.   processors, as well as how to write simple code and data statements.%@NL@%
  803. %@NL@%
  804. %@4@%  Whether or not you're new to assembly language, you'll want to read%@EH@%
  805.   Chapters 3%@BO:       2aca0@% and 4%@BO:       34dba@%, which show the use of QuickAssembler's simplified
  806.   keywords in useful examples. These keywords make programming easier.%@NL@%
  807. %@NL@%
  808. %@NL@%
  809. %@NL@%
  810. %@NL@%
  811. ────────────────────────────────────────────────────────────────────────────%@NL@%
  812. %@1@%%@CR:CH1         @%%@AB@%Chapter 1:  The QuickAssembler Interface%@AE@%%@EH@%%@NL@%
  813. %@NL@%
  814. %@NL@%
  815. %@4@%%@CR:IX1.1       @%  After you install Microsoft QuickC with QuickAssembler, you'll have a%@EH@%
  816.   single environment for both compiling and assembling. You can create C
  817.   programs, assembly-language programs, and programs that combine both
  818.   languages.%@NL@%
  819. %@NL@%
  820. %@4@%  The environment completely supports the standard QuickC features,%@EH@%
  821.   including all editing commands as well as mouse, keyboard, and menu
  822.   techniques. This manual assumes you have read QuickC %@AI@%Up%@AE@% %@AI@%and%@AE@% %@AI@%Running%@AE@% and
  823.   have used the on-line Help system to learn how to use each menu. Refer to
  824.   these sources of information for basic help on using the interface.%@NL@%
  825. %@NL@%
  826. %@4@%  The combined QuickC/QuickAssembler interface provides some new menu%@EH@%
  827.   selections and dialog boxes to support development of assembly-language
  828.   programs. This chapter describes the new features, focusing on areas where
  829.   the interface adds new functionality: creating a program, building a
  830.   program, getting help, debugging, and viewing a listing file. To enable
  831.   all the features described in this chapter, you should first choose Full
  832.   Menus from the Options menu if you are not already using full menus.%@NL@%
  833. %@NL@%
  834. %@NL@%
  835. %@2@%%@CR:SC1.1       @%%@AB@%1.1  Creating the Program%@AE@%%@EH@%%@NL@%
  836. %@NL@%
  837. %@4@%%@CR:IX1.2       @%%@CR:IX1.3       @%  Start the environment with the QC command, regardless of whether you're%@EH@%
  838.   creating a C or assembly-language source file. You can type %@AS@%QC %@AE@%by itself
  839.   or %@AS@%QC %@AE@%followed by the name of a file.%@NL@%
  840. %@NL@%
  841. %@4@%  By default, QC assumes that a file name on the command line has a .C%@EH@%
  842.   extension. You'll learn how to change this behavior later (by choosing
  843.   Display from the Options menu), but for now, make sure you include the
  844.   .ASM file extension when you want to create an assembly-language module:%@NL@%
  845. %@NL@%
  846.   %@AS@%QC SAMPLE.ASM%@AE@%%@NL@%
  847. %@NL@%
  848. %@4@%  If the file is new, the QuickC/QuickAssembler environment asks you if you%@EH@%
  849.   would like to create the file.%@NL@%
  850. %@NL@%
  851. %@4@%%@CR:IX1.4       @%  Once inside the QuickC/QuickAssembler environment, you can enter a program%@EH@%
  852.   by using all the QuickC editing commands. You can get started by entering
  853.   the following stand-alone assembly program. By default, QuickAssembler is
  854.   not case sensitive (except for external symbols), so you can enter
  855.   statements as uppercase or lowercase.%@NL@%
  856. %@NL@%
  857.   %@AS@%            .MODEL  small%@AE@%%@NL@%
  858.   %@AS@%            .STACK%@AE@%%@NL@%
  859.   %@AS@%            .CODE%@AE@%%@NL@%
  860.   %@AS@%            .STARTUP%@AE@%%@NL@%
  861.   %@AS@%            mov   ah,2%@AE@%%@NL@%
  862.   %@AS@%            mov   dl,7%@AE@%%@NL@%
  863.   %@AS@%            int   21h%@AE@%%@NL@%
  864.   %@AS@%            mov   ax,4c00h%@AE@%%@NL@%
  865.   %@AS@%            int   21h%@AE@%%@NL@%
  866.   %@AS@%            END%@AE@%%@NL@%
  867. %@NL@%
  868. %@4@%  Enter the program above in a file with a .ASM extension. No other modules%@EH@%
  869.   and no special assembly or link flags are required. When run, the program
  870.   beeps and exits.%@NL@%
  871. %@NL@%
  872. %@4@%  For now, you may just want to run the program to see how the%@EH@%
  873.   QuickC/Quick-Assembler environment works. However, you can read the rest
  874.   of this section to get a brief explanation of why the program works.%@NL@%
  875. %@NL@%
  876. %@4@%  The four statements are directives──nonexecutable statements that give%@EH@%
  877.   basic structure to the program by declaring a memory model, stack segment,
  878.   and code segment.%@NL@%
  879. %@NL@%
  880. %@4@%  The next five statements perform the actions of the program. The first%@EH@%
  881.   three set up a call to a DOS function that prints the beep character. (The
  882.   QuickAssembler Advisor, which you access through the Help menu, provides
  883.   information on each DOS function.) The first three statements are shown
  884.   below, with comments:%@NL@%
  885. %@NL@%
  886.   %@AS@%            mov   ah,2     ; Move 2 to AH (select Print function)%@AE@%%@NL@%
  887.   %@AS@%            mov   dl,7     ; Move 7 to DL (select Beep character)%@AE@%%@NL@%
  888.   %@AS@%            int   21h      ; Call DOS function%@AE@%%@NL@%
  889. %@NL@%
  890. %@4@%  The next two statements, shown below with comments, call DOS to exit%@EH@%
  891.   gracefully. Unlike C programs, assembly-language programs must make an
  892.   explicit function call to exit, or else cause the processor to execute
  893.   meaningless instructions beyond the end of the program.%@NL@%
  894. %@NL@%
  895.   %@AS@%            mov   ax,4c00h ; Move 4c00h to AX (select Exit%@AE@%%@NL@%
  896.   %@AS@%                           ;   function and 0 return code)%@AE@%%@NL@%
  897.   %@AS@%            int   21h      ; Call DOS function%@AE@%%@NL@%
  898. %@NL@%
  899. %@4@%  The last statement ends the module.%@EH@%%@NL@%
  900. %@NL@%
  901. %@NL@%
  902. %@2@%%@CR:SC1.2       @%%@AB@%1.2  Building and Running a Program%@AE@%%@EH@%%@NL@%
  903. %@NL@%
  904. %@4@%%@CR:IX1.5       @%%@CR:IX1.6       @%%@CR:IX1.7       @%  Once inside the QuickC/QuickAssembler environment, you build an%@EH@%
  905.   assembly-language program the same way you build a C program. Choose the
  906.   Go command from the Run menu, or press the F5 key.%@NL@%
  907. %@NL@%
  908. %@4@%  The environment assembles and links the program if it needs to be built.%@EH@%
  909.   Then, if there are no errors, it executes the program. You can also
  910.   assemble a program by using the Make menu. The Compile File command
  911.   assembles your file rather than compiling it, assuming the current file
  912.   has a .ASM extension.%@NL@%
  913. %@NL@%
  914. %@4@%  To help you create assembly-language programs, the QuickC/QuickAssembler%@EH@%
  915.   interface adds the following extensions to QuickC:%@NL@%
  916. %@NL@%
  917.   ■  A program list can now have .ASM files as well as .C, .OBJ, and .LIB
  918.      files if you work with multiple modules.%@NL@%
  919. %@NL@%
  920.   ■  The Make dialog box from the Options menu has a new option button:
  921.      Assembler Flags.%@NL@%
  922. %@NL@%
  923.   ■  The Assembler Flags dialog box lets you control how .ASM files are
  924.      assembled.%@NL@%
  925. %@NL@%
  926. %@4@%  If your program has multiple modules, you can add .ASM files to the%@EH@%
  927.   program list as well as other kinds of files. When you build the program,
  928.   the environment compiles each .C file module that needs to be built and
  929.   assembles each .ASM module that needs to be built.%@NL@%
  930. %@NL@%
  931. %@4@%%@CR:IX1.8       @%%@CR:IX1.9       @%%@CR:IX1.10      @%  For example, the program list in Figure 1.1 creates a mixed-language%@EH@%
  932.   program with both C and assembly-language source files.%@NL@%
  933. %@NL@%
  934.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  935.   │ This figure can be found in Section 1.2 of the manual                  │%@NL@%
  936.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  937. %@NL@%
  938. %@4@%%@CR:IX1.11      @%%@CR:IX1.12      @%  The environment sets the default file extension by looking at the%@EH@%
  939.   extension of the last file loaded. If the last file loaded had a .ASM
  940.   extension, the File List field now displays all the .ASM files for the
  941.   current directory. If the last file loaded had a .C extension, the File
  942.   List field displays all .C files.%@NL@%
  943. %@NL@%
  944. %@4@%  You can alter this behavior by choosing Display from the Options menu, as%@EH@%
  945.   explained in Section 1.4%@BO:        ece3@%, "Choosing C or Assembler Defaults." In any
  946.   case, you can always control which files are displayed by entering a
  947.   wildcard expression, such as %@AS@%*.asm%@AE@%, in the File Name field.%@NL@%
  948. %@NL@%
  949. %@4@%%@CR:IX1.13      @%%@CR:IX1.14      @%%@CR:IX1.15      @%  The environment lets you set assembler options as well as compiler%@EH@%
  950.   options. When you open the Options menu and choose Make, the dialog box
  951.   shown in Figure 1.2 appears.%@NL@%
  952. %@NL@%
  953.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  954.   │ This figure can be found in Section 1.2 of the manual                  │%@NL@%
  955.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  956. %@NL@%
  957. %@4@%%@CR:IX1.16      @%  This dialog box contains one new field: Assembler Flags. When you choose%@EH@%
  958.   this field, a new dialog box, shown in Figure 1.3, appears.%@NL@%
  959. %@NL@%
  960.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  961.   │ This figure can be found in Section 1.2 of the manual                  │%@NL@%
  962.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  963. %@NL@%
  964. %@4@%%@CR:IX1.17      @%  By setting flags in the Assembler Flags dialog box, you control the action%@EH@%
  965.   of the assembler whenever it builds a program. These settings have no
  966.   effect on .C modules, but do affect how each .ASM module is assembled.%@NL@%
  967. %@NL@%
  968. %@4@%%@CR:IX1.18      @%%@CR:IX1.19      @%  This dialog box contains a Debug Flags section, which has options that%@EH@%
  969.   apply only to Debug builds, and a Global Flags section, which has options
  970.   that apply to every build. Choose the Help button for an explanation of
  971.   each option.%@NL@%
  972. %@NL@%
  973.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  974.   %@AB@%NOTE%@AE@%  You control the type of build operation (Debug or Release) by
  975.   choosing the appropriate option button in the dialog box shown in Figure
  976.   1.2. You can return to that dialog box by choosing the OK or Cancel
  977.   command button. By choosing Debug (the default), you can use all of the
  978.   QuickC debugging commands while running the program. By choosing Release,
  979.   you produce a program that cannot be debugged but is somewhat smaller.%@NL@%
  980.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  981. %@NL@%
  982. %@4@%%@CR:IX1.20      @%  The Custom Flags section lets you enter additional options. In the three%@EH@%
  983.   Custom Flags text boxes, you can type any of the assembly options accepted
  984.   by the QCL driver. See Appendix B%@BO:       f653b@% for a description of these options. The
  985.   next section describes how to use the QCL driver to assemble programs.%@NL@%
  986. %@NL@%
  987. %@NL@%
  988. %@2@%%@CR:SC1.3       @%%@AB@%1.3  Assembling from the Command Line%@AE@%%@EH@%%@NL@%
  989. %@NL@%
  990. %@4@%%@CR:IX1.21      @%%@CR:IX1.22      @%  You can run QuickAssembler from the command line, just as you can run%@EH@%
  991.   QuickC. One utility, QCL, invokes both the assembler and compiler. You can
  992.   even use it to compile, assemble, and link mixed-language programs in one
  993.   step. However, make sure you use the version of QCL copied during
  994.   QuickAssembler installation.%@NL@%
  995. %@NL@%
  996. %@4@%  If you type a file name that has a .C extension, QCL invokes the C%@EH@%
  997.   compiler. For example, the following command compiles and links the file
  998.   SAMPLE1.C:%@NL@%
  999. %@NL@%
  1000.   %@AS@%QCL SAMPLE1.C%@AE@%%@NL@%
  1001. %@NL@%
  1002. %@4@%  If you type a file name that has a .ASM extension, QCL invokes the%@EH@%
  1003.   QuickAssembler. For example, the following command assembles and links the
  1004.   file SAMPLE2.ASM:%@NL@%
  1005. %@NL@%
  1006.   %@AS@%QCL SAMPLE2.ASM%@AE@%%@NL@%
  1007. %@NL@%
  1008. %@4@%  In any case, QCL links all resulting object files to create a .EXE file,%@EH@%
  1009.   unless you specify /c on the command line. (You can also create a .COM
  1010.   file if the program is written entirely in assembly language.) For
  1011.   example, the following command compiles SAMPLE1.C and assembles
  1012.   SAMPLE2.ASM, but does not link the resulting object files:%@NL@%
  1013. %@NL@%
  1014.   %@AS@%QCL /c SAMPLE1.C /Cl SAMPLE2.ASM%@AE@%%@NL@%
  1015. %@NL@%
  1016. %@4@%%@CR:IX1.23      @%  As always, you can specify .LIB files and .OBJ files on the QCL command%@EH@%
  1017.   line. A file with no extension is assumed to have a .OBJ extension by
  1018.   default. For example, the following QCL command compiles M1.C, assembles
  1019.   M2.ASM (with lowercase symbols preserved), and links M1.OBJ, M2.OBJ, and
  1020.   M3.OBJ. Finally, QCL searches M4.LIB for any unresolved references.%@NL@%
  1021. %@NL@%
  1022.   %@AS@%QCL /Cx  M1.C  M2.ASM  M3  M4.LIB%@AE@%%@NL@%
  1023. %@NL@%
  1024. %@4@%  You can specify a number of QuickAssembler options, in addition to the%@EH@%
  1025.   ones provided specifically for C. See Appendix B%@BO:       f653b@%, "Using Assembler
  1026.   Options with QCL," for a description of all these options.%@NL@%
  1027. %@NL@%
  1028. %@NL@%
  1029. %@2@%%@CR:SC1.4       @%%@AB@%1.4  Choosing C or Assembler Defaults%@AE@%%@EH@%%@NL@%
  1030. %@NL@%
  1031. %@4@%%@CR:IX1.24      @%  At all times, you can use the QuickC/QuickAssembler environment to create%@EH@%
  1032.   either C modules or assembly-language modules. However, there are some
  1033.   details of operation that make it a little easier to work with one
  1034.   language or another.%@NL@%
  1035. %@NL@%
  1036. %@4@%%@CR:IX1.25      @%  For example, one consideration is whether the dialog box starts by%@EH@%
  1037.   displaying all the C files in the directory (%@AS@%*.c%@AE@%) or all the
  1038.   assembly-language files (%@AS@%*.asm%@AE@%) when you choose the Open command from the
  1039.   File menu. You can control this behavior by choosing Display from the
  1040.   Options menu. Figure 1.4 shows the dialog box that appears.%@NL@%
  1041. %@NL@%
  1042.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  1043.   │ This figure can be found in Section 1.4 of the manual                  │%@NL@%
  1044.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  1045. %@NL@%
  1046. %@4@%%@CR:IX1.26      @%%@CR:IX1.27      @%%@CR:IX1.28      @%  In the Language section of this dialog box, select either C, Assembler, or%@EH@%
  1047.   Auto. The Auto selection uses C or Assembler defaults, depending on what
  1048.   file was last loaded into the active window. For example, if you load the
  1049.   PROG.ASM file into the source window, all the defaults (described below)
  1050.   change to assembly-language settings.%@NL@%
  1051. %@NL@%
  1052.   %@AB@%──────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1053.   %@AB@%NOTE%@AE@%  When you first use QuickAssembler, the environment starts up in Auto
  1054.   mode. Thereafter, it looks at the settings in QC.INI to determine what
  1055.   mode to start in; this feature has the effect of saving display-mode
  1056.   settings between sessions.%@NL@%
  1057.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  1058. %@NL@%
  1059. %@4@%%@CR:IX1.29      @%  The following items change when the display mode changes──either because%@EH@%
  1060.   you change the mode manually or because you are in Auto mode and load a
  1061.   different kind of file:%@NL@%
  1062. %@NL@%
  1063. %@CR:IX1.30      @%  ■  For commands on the File menu, the default file name changes to %@AS@%*.c %@AE@%or
  1064.      %@AS@%*.asm%@AE@%.%@NL@%
  1065. %@NL@%
  1066. %@CR:IX1.31      @%%@CR:IX1.32      @%  ■  The Include command on the View menu responds to .H files if the
  1067.      display mode is C, or .INC files if the display mode is Assembler.%@NL@%
  1068. %@NL@%
  1069. %@CR:IX1.33      @%%@CR:IX1.34      @%  ■  The Index and Contents items from the Help menu bring up lists of
  1070.      topics for either C or Assembly, as determined by the display mode.%@NL@%
  1071. %@NL@%
  1072. %@4@%  Auto display mode assumes C defaults until you load a .ASM file. When you%@EH@%
  1073.   start the environment with the QC command, QC assumes that file names on
  1074.   the command line have .C extensions, unless the environment is in
  1075.   Assembler display mode.%@NL@%
  1076. %@NL@%
  1077. %@NL@%
  1078. %@2@%%@CR:SC1.5       @%%@AB@%1.5  Using the Quick Advisor (Help)%@AE@%%@EH@%%@NL@%
  1079. %@NL@%
  1080. %@4@%%@CR:IX1.35      @%%@CR:IX1.36      @%%@CR:IX1.37      @%%@CR:IX1.38      @%  QuickAssembler extends the number of topics you can get information on,%@EH@%
  1081.   and updates QCENV.HLP so you can get context-sensitive help on the new
  1082.   menu items and dialog boxes. In addition, you still continue to get help
  1083.   on all of the C-language topics. The new topics, added for use with
  1084.   assembly language, are shown below:%@NL@%
  1085. %@NL@%
  1086. %@CR:IX1.39      @%  ■  QuickAssembler instructions%@NL@%
  1087. %@NL@%
  1088. %@CR:IX1.40      @%  ■  QuickAssembler directives and operators%@NL@%
  1089. %@NL@%
  1090. %@CR:IX1.41      @%%@CR:IX1.42      @%  ■  DOS and ROM-BIOS services%@NL@%
  1091. %@NL@%
  1092. %@4@%  You can get help on assembly-language topics by using one of two different%@EH@%
  1093.   methods:%@NL@%
  1094. %@NL@%
  1095.   1. Topical Help (press F1)%@NL@%
  1096. %@NL@%
  1097.   2. The Help menu%@NL@%
  1098. %@NL@%
  1099. %@4@%%@CR:IX1.43      @%  At all times, the expanded environment provides topical Help for both%@EH@%
  1100.   assembler and C keywords. Place the cursor on the keyword, then press F1.
  1101.   You can also get topical Help by moving the mouse cursor to the desired
  1102.   word and clicking the Right mouse button. The display mode (described in
  1103.   the previous section) determines whether C help files or assembly help
  1104.   files are searched first.%@NL@%
  1105. %@NL@%
  1106.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  1107.   %@AB@%NOTE%@AE@%  If the keyword starts with a dot (.), do not place the cursor on the
  1108.   dot or click on the dot to get topical Help. Place the cursor on the
  1109.   keyword or click on the keyword.%@NL@%
  1110.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  1111. %@NL@%
  1112. %@4@%  QuickAssembler keywords include instructions, directives, and operators.%@EH@%
  1113.   Chapter 2%@BO:       151ff@%, "Introducing 8086 Assembly Language" provides information on
  1114.   each of these concepts. An "instruction" is a specific action that the
  1115.   processor executes. Instructions are the primary building blocks of an
  1116.   assembly-language program.%@NL@%
  1117. %@NL@%
  1118. %@4@%%@CR:IX1.44      @%  The Help screens on instructions are particularly useful, because they%@EH@%
  1119.   provide detailed information on timing, syntax, and processor flags. This
  1120.   manual features a topical discussion of instructions, but provides only
  1121.   limited information on timing and flags. To write the most efficient
  1122.   assembly-language programs, you should refer often to the on-line Help for
  1123.   instructions.%@NL@%
  1124. %@NL@%
  1125. %@4@%%@CR:IX1.45      @%%@CR:IX1.46      @%%@CR:IX1.47      @%  To get help on DOS or ROM-BIOS services, select Contents or Index from the%@EH@%
  1126.   Help menu. These menu items give you help on assembly-language topics
  1127.   rather than C topics whenever the display mode (described in the previous
  1128.   section) is set to Assembler.%@NL@%
  1129. %@NL@%
  1130. %@4@%  The Help system offers other paths to get to information on DOS and BIOS%@EH@%
  1131.   functions. Move the mouse cursor to an interrupt number (such as 21H or
  1132.   33) and click the Right mouse button, or move the cursor to the number and
  1133.   press F1. The Help system responds by showing a screen listing of all the
  1134.   functions accessed through that interrupt number. You can then go to the
  1135.   specific Help screen you want. You can also get help on interrupt
  1136.   functions by selecting context-sensitive help for the %@AB@%INT%@AE@% keyword.%@NL@%
  1137. %@NL@%
  1138. %@4@%  You call these DOS and BIOS functions by using the %@AB@%INT%@AE@% instruction, as%@EH@%
  1139.   described in Chapter 4%@BO:       34dba@%. These services perform basic input and output
  1140.   functions for you, giving you access to DOS and to hardware.%@NL@%
  1141. %@NL@%
  1142. %@4@%%@CR:IX1.48      @%  By default, the Smart Help display option is on. This option makes the%@EH@%
  1143.   system more flexible by ignoring the presence or absence of a leading
  1144.   underscore (_) in front of a name. Consequently, pressing F1 while on
  1145.   %@AS@%_printf %@AE@%gives you help for the %@AB@%printf%@AE@% function.%@NL@%
  1146. %@NL@%
  1147. %@NL@%
  1148. %@2@%%@CR:SC1.6       @%%@AB@%1.6  Debugging Assembly Code%@AE@%%@EH@%%@NL@%
  1149. %@NL@%
  1150. %@4@%%@CR:IX1.49      @%%@CR:IX1.50      @%  You can run a Debug build by choosing Debug in the dialog box opened by%@EH@%
  1151.   the Options menu's Make command. Debug is the default setting, so you
  1152.   probably won't need to choose it.%@NL@%
  1153. %@NL@%
  1154. %@4@%  You can use all of QuickC's debugging commands with programs written in%@EH@%
  1155.   assembly language. But keep in mind these considerations:%@NL@%
  1156. %@NL@%
  1157.   ■  You must use an extra file with a .DBG file extension to debug programs
  1158.      in .COM format.%@NL@%
  1159. %@NL@%
  1160.   ■  You must use C syntax to specify expressions to watch or modify, even
  1161.      when you debug assembly code. In addition, you can use the %@AB@%BY%@AE@%, %@AB@%WO%@AE@%, and
  1162.      %@AB@%DW%@AE@% memory operators, register names, and the colon (%@AB@%:%@AE@%) operator. The
  1163.      colon operator helps to specify segmented addresses.%@NL@%
  1164. %@NL@%
  1165.   ■  When you trace execution of an assembly-language module, the behavior
  1166.      of the environment changes. Screen swapping is turned on by default,
  1167.      and the first line of code is never highlighted.%@NL@%
  1168. %@NL@%
  1169.   ■  You can alter flag values and registers from within the environment.%@NL@%
  1170. %@NL@%
  1171. %@4@%  Sections 1.6.1%@BO:       10d74@%-1.6.4 discuss each debugging feature in turn.%@EH@%%@NL@%
  1172. %@NL@%
  1173. %@NL@%
  1174. %@3@%%@CR:SC1.6.1     @%%@AB@%1.6.1  Debugging .COM Files%@AE@%%@EH@%%@NL@%
  1175. %@NL@%
  1176. %@4@%%@CR:IX1.51      @%%@CR:IX1.52      @%  Section 4.8%@BO:       3c62a@%, "Creating .COM Files," explains how to use tiny memory%@EH@%
  1177.   model, along with a linker flag, to generate a program in the .COM-file
  1178.   format. A .COM file has a total size limitation of 64K, but is slightly
  1179.   smaller and loads faster than a similar .EXE file.%@NL@%
  1180. %@NL@%
  1181. %@4@%%@CR:IX1.53      @%%@CR:IX1.54      @%  When you run a Debug build that creates a .COM file, the linker places%@EH@%
  1182.   debugging information in a separate file with the same base name as the
  1183.   program and with a .DBG extension. If you delete the .DBG file, you cannot
  1184.   debug your program until you run another Debug build.%@NL@%
  1185. %@NL@%
  1186. %@4@%  Otherwise, all the considerations that apply to debugging .EXE files apply%@EH@%
  1187.   to .COM files as well.%@NL@%
  1188. %@NL@%
  1189. %@NL@%
  1190. %@3@%%@CR:SC1.6.2     @%%@AB@%1.6.2  Specifying Expressions%@AE@%%@EH@%%@NL@%
  1191. %@NL@%
  1192. %@4@%%@CR:IX1.55      @%%@CR:IX1.56      @%%@CR:IX1.57      @%%@CR:IX1.58      @%  The Debug menu provides two commands──Watch Value and Watchpoint──that let%@EH@%
  1193.   you specify an expression for the QuickC/QuickAssembler environment to
  1194.   dynamically update and display. The environment displays the updated
  1195.   values in the Watch window. When you choose one of these commands, a
  1196.   dialog box appears, prompting you to enter an expression. Figure 1.5 shows
  1197.   the dialog box for the Watch Value command.%@NL@%
  1198. %@NL@%
  1199.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  1200.   │ This figure can be found in Section 1.6.2 of the manual                │%@NL@%
  1201.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  1202. %@NL@%
  1203. %@4@%  You can enter any combination of variable names, constants, and C-language%@EH@%
  1204.   syntax. You cannot enter assembly-language keywords. However, the
  1205.   environment does recognize all valid register names (including names of
  1206.   both 8-bit and 16-bit registers). See Chapter 2%@BO:       151ff@%, "Introducing 8086
  1207.   Assembly Language," for information on registers.%@NL@%
  1208. %@NL@%
  1209. %@4@%%@CR:IX1.59      @%  In addition to register names, the expanded environment supports the%@EH@%
  1210.   optional use of the colon operator (%@AB@%:%@AE@%) for specifying segmented addresses:
  1211. %@NL@%
  1212. %@4@%  %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@%%@EH@%%@NL@%
  1213. %@NL@%
  1214. %@4@%  In the syntax display above, %@AI@%segment%@AE@% can be a constant or a register;%@EH@%
  1215.   %@AI@%offset%@AE@% can be any expression. The QuickC/QuickAssembler environment
  1216.   combines the segment and offset addresses to determine a physical address,
  1217.   as described in Section 2.7%@BO:       28c1c@%, "Segmented Addressing and Segment
  1218.   Registers."%@NL@%
  1219. %@NL@%
  1220. %@4@%%@CR:IX1.60      @%  The following examples demonstrate the use of the colon in valid%@EH@%
  1221.   expressions. Note that you use C-language syntax to specify hexadecimal
  1222.   numbers:%@NL@%
  1223. %@NL@%
  1224.   %@AS@%0xb000:0x0000%@AE@%%@NL@%
  1225.   %@AS@%es:0x0100%@AE@%%@NL@%
  1226.   %@AS@%es:(array[2])%@AE@%%@NL@%
  1227.   %@AS@%ss:bp%@AE@%%@NL@%
  1228. %@NL@%
  1229. %@4@%  The QuickC/QuickAssembler environment considers a segmented-address%@EH@%
  1230.   expression to be a pointer to a character, which the Watch window
  1231.   evaluates by displaying the character pointed to. However, you can use
  1232.   QuickC type specifiers to alter how an expression is displayed. For
  1233.   example, the Watch window evaluates the following expression by displaying
  1234.   the numeric value of the address %@AS@%es:(warray+3)%@AE@%:%@NL@%
  1235. %@NL@%
  1236.   %@AS@%es:(warray+3),p%@AE@%%@NL@%
  1237. %@NL@%
  1238. %@4@%%@CR:IX1.61      @%%@CR:IX1.62      @%%@CR:IX1.63      @%%@CR:IX1.64      @%  You can use the three memory operators──%@AB@%BY%@AE@%, %@AB@%WO%@AE@%, and %@AB@%DW%@AE@%──to view the byte,%@EH@%
  1239.   word, or doubleword of memory at a given address.%@NL@%
  1240. %@NL@%
  1241. %@4@%  With pointer expressions and registers, %@AB@%BY%@AE@% returns the byte pointed to by%@EH@%
  1242.   the expression. (Segmented addresses are pointer expressions, as are
  1243.   procedure parameters declared with %@AB@%PTR%@AE@%.) With nonpointer variables, %@AB@%BY%@AE@%
  1244.   returns the byte at the same address as the variable. %@AB@%WO%@AE@% and %@AB@%DW%@AE@% work the
  1245.   same way, but return a word or doubleword, respectively.%@NL@%
  1246. %@NL@%
  1247. %@4@%  The rest of this section demonstrates how to use the three memory%@EH@%
  1248.   operators to specify useful expressions.%@NL@%
  1249. %@NL@%
  1250. %@4@%%@CR:IX1.65      @%  To watch the contents of a register, enter just the register's name. To%@EH@%
  1251.   examine the value that the register points to, enter the %@AB@%BY%@AE@%, %@AB@%WO%@AE@%, and %@AB@%DW%@AE@%
  1252.   operators followed by the register name.%@NL@%
  1253. %@NL@%
  1254.   %@AB@%Example%@AE@%             %@AB@%Value Specified%@AE@%%@NL@%
  1255.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  1256.   %@AS@%bx%@AE@%                  The contents of the BX register%@NL@%
  1257. %@NL@%
  1258.   %@AS@%BY bx%@AE@%               The byte pointed to by the BX register%@NL@%
  1259. %@NL@%
  1260.   %@AS@%WO bx%@AE@%               The word pointed to by the BX register%@NL@%
  1261. %@NL@%
  1262.   %@AS@%DW es:si%@AE@%            The doubleword pointed to by the SI register, relative
  1263.                       to the segment address in ES%@NL@%
  1264. %@NL@%
  1265. %@NL@%
  1266. %@4@%%@CR:IX1.66      @%  To watch the value of a variable, enter the variable's name. To watch the%@EH@%
  1267.   byte, word, or doubleword at the same address as the variable, use the %@AB@%BY%@AE@%,
  1268.   %@AB@%WO%@AE@%, and %@AB@%DW%@AE@% operators. In this context, these operators function as the
  1269.   QuickAssembler %@AB@%PTR%@AE@% operator does: they change the size of data to be
  1270.   examined. They are similar, but not identical, to C type casts. In the
  1271.   following examples, assume that %@AS@%Var %@AE@%is a word variable defined with%@AB@% DW%@AE@%:%@NL@%
  1272. %@NL@%
  1273.   %@AB@%Example%@AE@%             %@AB@%Value Specified%@AE@%%@NL@%
  1274.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  1275.   %@AS@%Var%@AE@%                 The variable %@AS@%Var%@AE@% (the word at the address of %@AS@%Var%@AE@%)%@NL@%
  1276. %@NL@%
  1277.   %@AS@%BY Var%@AE@%              The byte at the address of %@AS@%Var%@AE@%%@NL@%
  1278. %@NL@%
  1279.   %@AS@%DW Var%@AE@%              The doubleword at the address of %@AS@%Var%@AE@%%@NL@%
  1280. %@NL@%
  1281. %@NL@%
  1282. %@4@%%@CR:IX1.67      @%  You can use %@AB@%BY%@AE@%, %@AB@%WO%@AE@%, and %@AB@%DW%@AE@% to specify an array element, but you must%@EH@%
  1283.   understand that expressions in the Debug window are treated like C
  1284.   expressions rather than assembler expressions. As a result, the syntax you
  1285.   use to watch a memory location in the Debug window is often different from
  1286.   the syntax in your assembly source. For example, assume you have the
  1287.   following data and code:%@NL@%
  1288. %@NL@%
  1289.   %@AS@%warr        DW     1, 2, 3, 4, 5, 6%@AE@%%@NL@%
  1290.   %@AS@%            .%@AE@%%@NL@%
  1291.   %@AS@%            .%@AE@%%@NL@%
  1292.   %@AS@%            .%@AE@%%@NL@%
  1293.   %@AS@%            mov    bx,0%@AE@%%@NL@%
  1294.   %@AS@%            mov    cx,5%@AE@%%@NL@%
  1295. %@NL@%
  1296.   %@AS@%loop1:      add    ax,warr[bx]%@AE@%%@NL@%
  1297.   %@AS@%            add    bx,2%@AE@%%@NL@%
  1298.   %@AS@%            loop   loop1%@AE@%%@NL@%
  1299. %@NL@%
  1300. %@4@%  You cannot watch the assembler expression %@AS@%warr[bx] %@AE@%directly. However, you%@EH@%
  1301.   can put an equivalent C expression in the Debug window:%@NL@%
  1302. %@NL@%
  1303.   %@AS@%WO (char*)&warr + bx%@AE@%%@NL@%
  1304. %@NL@%
  1305. %@4@%  The address-of operator is necessary to make the C debugger look at the%@EH@%
  1306.   MASM array as a C array──that is, as an address. The value must cast to a
  1307.   character pointer because the debugger looks at it as a scaled C index
  1308.   rather than an unscaled assembler index. In this case, the assembler code
  1309.   adds 2 to the pointer BX to adjust for the variable size. You must tell
  1310.   the debugger to ignore its normal word scaling.%@NL@%
  1311. %@NL@%
  1312. %@4@%  Expressions are only scaled when there is a variable in the expression. In%@EH@%
  1313.   the expression %@AS@%WO BP+6 %@AE@%the %@AS@%6 %@AE@%is not scaled──the expression means, "look at
  1314.   the word six bytes beyond the address that is in BP." However, in the
  1315.   expression %@AS@%WO &warr+6%@AE@%, the %@AS@%6 %@AE@%is scaled because of the word size of the
  1316.   variable. Note that the variable size, not the expression type (%@AB@% BY%@AE@%, %@AB@%WO%@AE@%,
  1317.   or %@AB@%DW%@AE@%), determines the size of scaling.%@NL@%
  1318. %@NL@%
  1319. %@4@%  If you are comfortable with C, you can also use C expressions to look at%@EH@%
  1320.   assembler expressions. Here are some examples you might find useful:%@NL@%
  1321. %@NL@%
  1322.   %@AB@%Example%@AE@%             %@AB@%Value Specified%@AE@%%@NL@%
  1323.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  1324.   %@AS@%&Var%@AE@%                The address of%@AS@% Var%@AE@%%@NL@%
  1325. %@NL@%
  1326.   %@AS@%es:0x81,s%@AE@%           The string at%@AS@% es:[81h] %@AE@%(the DOS command line when a
  1327.                       program is started)%@NL@%
  1328. %@NL@%
  1329.   %@AS@%&Arr[3]%@AE@%             The third element of an array (note that the%@AS@% 3%@AE@% will be
  1330.                       scaled)%@NL@%
  1331. %@NL@%
  1332.   %@AS@%*(&Arr+3)%@AE@%           Equivalent to the previous expression%@NL@%
  1333. %@NL@%
  1334. %@NL@%
  1335. %@NL@%
  1336. %@3@%%@CR:SC1.6.3     @%%@AB@%1.6.3  Tracing Execution%@AE@%%@EH@%%@NL@%
  1337. %@NL@%
  1338. %@4@%%@CR:IX1.68      @%%@CR:IX1.69      @%%@CR:IX1.70      @%%@CR:IX1.71      @%%@CR:IX1.72      @%  The Run menu's Trace Into, Animate, and Step Over commands execute one%@EH@%
  1339.   statement of your program at a time. These commands are fully functional
  1340.   with assembly-language programs. However, debugging commands behave
  1341.   differently when you trace execution of an assembly-language module, as
  1342.   summarized below:%@NL@%
  1343. %@NL@%
  1344.   ■  By default, screen swapping is on.%@NL@%
  1345. %@NL@%
  1346.   ■  If the main module of the program is an assembly-language module, the
  1347.      first line of the program is never highlighted.%@NL@%
  1348. %@NL@%
  1349.   ■  The Calls menu does not function unless you write your program
  1350.      according to certain guidelines.%@NL@%
  1351. %@NL@%
  1352. %@4@%  The rest of this section elaborates on these differences.%@EH@%%@NL@%
  1353. %@NL@%
  1354. %@4@%  When you trace execution of an assembly-language module, screen swapping%@EH@%
  1355.   is turned on. The environment does not support an Auto screen-swapping
  1356.   mode for assembly-language programs because it cannot detect when a
  1357.   program writes to the screen. Therefore, when executing a .ASM file, the
  1358.   environment equates the Auto screen-swapping selection with screen
  1359.   swapping turned on.%@NL@%
  1360. %@NL@%
  1361. %@4@%  You can always turn screen swapping off manually by choosing the Run/Debug%@EH@%
  1362.   command from the Options menu. When a dialog box appears, choose the Off
  1363.   option button in the Screen Swapping field.%@NL@%
  1364. %@NL@%
  1365. %@4@%%@CR:IX1.73      @%  Screen swapping causes the environment to switch to a full output screen%@EH@%
  1366.   each time the program executes code. The effect is particularly noticeable
  1367.   when you choose the Animate command. Leaving screen swapping on preserves
  1368.   program output. However, if large portions of your program do not write to
  1369.   the video display, you may want to turn screen swapping off temporarily.%@NL@%
  1370. %@NL@%
  1371. %@4@%%@CR:IX1.74      @%  The second debugging feature that operates differently for assembly-%@EH@%%@NL@%
  1372. %@4@%  language programs is current-line highlighting. When you restart a%@EH@%
  1373.   program, the environment does not highlight the first line of code. The
  1374.   debugging facility does not know which line of code is the first to be
  1375.   executed, since this information is stored in the executable-file header.
  1376.   After you execute a trace, the second program line is highlighted, and
  1377.   thereafter current-line highlighting works as you would expect.%@NL@%
  1378. %@NL@%
  1379. %@4@%%@CR:IX1.75      @%%@CR:IX1.76      @%  The third feature that operates differently is the Calls command from the%@EH@%
  1380.   Debug menu. To ensure that the command works with assembly-language
  1381.   modules, either use the %@AB@%PROC%@AE@% directive with an argument list or local
  1382.   variables, as described in Chapter 3%@BO:       2aca0@%, "Writing Assembly Modules for C
  1383.   Programs," or else set up the framepointer (the BP register) as described
  1384.   in Appendix A%@BO:       ed697@%, "Mixed-Language Mechanics." Both these methods set up a
  1385.   stack frame for each procedure, using the standard Microsoft methods. The
  1386.   environment checks stack frames to see what procedures have been called,
  1387.   and with what parameters.%@NL@%
  1388. %@NL@%
  1389. %@NL@%
  1390. %@3@%%@CR:SC1.6.4     @%%@AB@%1.6.4  Modifying Registers and Flags%@AE@%%@EH@%%@NL@%
  1391. %@NL@%
  1392. %@4@%%@CR:IX1.77      @%%@CR:IX1.78      @%%@CR:IX1.79      @%  With the expanded QuickC/QuickAssembler environment, you can get much%@EH@%
  1393.   greater use from the Registers window. The Registers window displays more
  1394.   information than it does in the simple QuickC environment, and you can
  1395.   also use the window to alter register and flag values.%@NL@%
  1396. %@NL@%
  1397.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  1398.   %@AB@%NOTE%@AE@%  By default, the environment does not display the Registers window.
  1399.   To open this window, choose the Window command from the View menu. A
  1400.   dialog box appears that lists all windows. Move the cursor to Registers
  1401.   and press the ENTER key, or move the mouse cursor to Registers and double
  1402.   click the Left mouse button. To close the window, repeat the procedure.%@NL@%
  1403.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  1404. %@NL@%
  1405. %@4@%%@CR:IX1.80      @%  The Registers window displays the contents of both 8086 and 8087%@EH@%
  1406.   registers. You can remove 8087 registers from the Registers window by
  1407.   choosing Display from the Options menu. When the dialog box appears, turn
  1408.   the Show 8087 option button off. The environment only displays 8087
  1409.   registers if you have a math coprocessor or have a program that calls
  1410.   floating-point emulator routines from a high-level language.%@NL@%
  1411. %@NL@%
  1412. %@4@%  You can alter values in the window by either using the mouse or the%@EH@%
  1413.   keyboard. To alter a value, you first select the item you want to change:%@NL@%
  1414. %@NL@%
  1415.   ■  To alter a value with the mouse, select an item by clicking the Left
  1416.      mouse button.%@NL@%
  1417. %@NL@%
  1418.   ■  To alter a value with the keyboard, first place the cursor on an item
  1419.      in the window. (Press TAB or SHIFT+TAB to cycle quickly through the
  1420.      items.) Then select the item by pressing the ENTER key. The List field
  1421.      has no function in this context and should be ignored.%@NL@%
  1422. %@NL@%
  1423. %@4@%  Choosing a flag toggles the flag to the opposite setting. Choosing a%@EH@%
  1424.   register brings up a dialog box. Type the new value for the register and
  1425.   press ENTER.%@NL@%
  1426. %@NL@%
  1427. %@NL@%
  1428. %@2@%%@CR:SC1.7       @%%@AB@%1.7  Viewing a Listing File%@AE@%%@EH@%%@NL@%
  1429. %@NL@%
  1430. %@4@%%@CR:IX1.81      @%%@CR:IX1.82      @%  When you assemble a module with the Debug build setting (the default),%@EH@%
  1431.   QuickAssembler can create a listing file. Choose the type of listing by
  1432.   using the Assembler Flags dialog box. (To access this dialog box, choose
  1433.   Make from the Options menu, then choose Assembler Flags.) You should also
  1434.   make sure that the One Pass Assembly option is not selected.%@NL@%
  1435. %@NL@%
  1436. %@4@%  A QuickAssembler listing file shows precisely how the assembler translated%@EH@%
  1437.   each line of code during the last program build. Each instruction in the
  1438.   source code is listed next to its corresponding numeric code (machine
  1439.   instruction).%@NL@%
  1440. %@NL@%
  1441. %@4@%%@CR:IX1.83      @%  Listing files are particularly useful if your program uses macro calls or%@EH@%
  1442.   include files. The listing file displays each statement generated by a
  1443.   macro call and each line of code copied from an include file. Tables at
  1444.   the end of the listing file give information on macros, symbols,
  1445.   structures, groups, and records. Part 2%@BO:       3faf8@% of this manual describes each of
  1446.   these features of assembly language.%@NL@%
  1447. %@NL@%
  1448. %@4@%%@CR:IX1.84      @%  To view the listing file, assemble the source code at least once. You can%@EH@%
  1449.   view the listing file for the current module by choosing the Listing
  1450.   command from the View menu. You can also view the file with the CTRL+F2
  1451.   shortcut key.%@NL@%
  1452. %@NL@%
  1453. %@4@%%@CR:IX1.85      @%  The listing file is then displayed in the Source window, as shown in%@EH@%
  1454.   Figure 1.6. You can page through this file by using all the normal
  1455.   cursor-movement commands. When you want to return to the previous file,
  1456.   press F2 or use the File menu. You can also leave the listing file by
  1457.   choosing the Listing command again; this action causes the environment to
  1458.   switch to the original line of source code that generated the current line
  1459.   of code. In particular, if you are in a listing file and move the cursor
  1460.   to a line generated from an include file (.INC), the Listing command
  1461.   switches directly to that include file.%@NL@%
  1462. %@NL@%
  1463.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  1464.   │ This figure can be found in Section 1.7 of the manual                  │%@NL@%
  1465.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  1466. %@NL@%
  1467. %@4@%  Normally, you would choose the Listing command when in a .LST file or in a%@EH@%
  1468.   .ASM file with a corresponding .LST file (previously generated by a
  1469.   program build). If you are not in either of these types of files, the
  1470.   environment responds by displaying a dialog box for opening a file; %@AS@%*.lst%@AE@%
  1471.   is the default file name.%@NL@%
  1472. %@NL@%
  1473. %@NL@%
  1474. %@NL@%
  1475. ────────────────────────────────────────────────────────────────────────────%@NL@%
  1476. %@1@%%@CR:CH2         @%%@AB@%Chapter 2:  Introducing 8086 Assembly Language%@AE@%%@EH@%%@NL@%
  1477. %@NL@%
  1478. %@NL@%
  1479. %@4@%%@CR:IX2.1       @%  Assembly-language programs control hardware directly, giving you the%@EH@%
  1480.   ability to write the fastest, smallest programs possible and to execute
  1481.   any operation. But assembly-language programming also requires an
  1482.   understanding of the architecture of 8086-family processors.%@NL@%
  1483. %@NL@%
  1484. %@4@%%@CR:IX2.2       @%  Assembly language is close to machine code──the processor's numeric%@EH@%
  1485.   language of 1's and 0's. Each QuickAssembler instruction corresponds to an
  1486.   8086 instruction but consists of a meaningful name (mnemonic) instead of a
  1487.   number. For example, the %@AB@%ADD%@AE@% instruction computes the sum of two items.
  1488.   QuickAssembler translates this instruction to produce a numeric code, such
  1489.   as 10000010 binary. The processor responds to this code when you run the
  1490.   program.%@NL@%
  1491. %@NL@%
  1492. %@4@%  This process of translation is called "assembling." Before you can%@EH@%
  1493.   assemble a program, you need to understand the basic concepts of the
  1494.   processor and of assembly language. This chapter presents these concepts.%@NL@%
  1495. %@NL@%
  1496. %@NL@%
  1497. %@2@%%@CR:SC2.1       @%%@AB@%2.1  Programming the 8086 Family%@AE@%%@EH@%%@NL@%
  1498. %@NL@%
  1499. %@4@%  If you have programmed in C, you can get a good grasp of 8086 assembly%@EH@%
  1500.   language by focusing on the differences between the two languages:%@NL@%
  1501. %@NL@%
  1502. %@CR:IX2.3       @%%@CR:IX2.4       @%  1. A C statement may combine many complex operations, but each line of
  1503.      assembly language specifies just one limited action called an
  1504.      "instruction." QuickAssembler also supports a number of nonexecutable
  1505.      statements called "directives," which provide structure to the program,
  1506.      declare data objects, and provide other information.%@NL@%
  1507. %@NL@%
  1508.      Sections 2.2%@BO:       1602a@%-2.4 explain the basics of writing instructions and
  1509.      directives.%@NL@%
  1510. %@NL@%
  1511. %@CR:IX2.5       @%  2. C programs deal with memory locations (known as variables), but
  1512.      assembly-language programs must deal with registers as well. A
  1513.      "register" is a special memory location inside the processor itself,
  1514.      having a permanent name rather than a numeric address.%@NL@%
  1515. %@NL@%
  1516.      Section 2.5%@BO:       1e475@%, "8086-Family Registers," describes the use of each
  1517.      register.%@NL@%
  1518. %@NL@%
  1519. %@CR:IX2.6       @%  3. A data object in a C program can be arbitrarily complicated.
  1520.      Assembly-language statements work on objects accessed through four
  1521.      specific modes: immediate, register, direct memory, and indirect
  1522.      memory. Each mode has specific properties and limitations imposed by
  1523.      the processor.%@NL@%
  1524. %@NL@%
  1525.      Section 2.6%@BO:       2404d@%, "Addressing Modes," explains each of these four modes and
  1526.      gives examples.%@NL@%
  1527. %@NL@%
  1528.   4. The processor combines two 16-bit addresses to access each memory
  1529.      location. This mechanism is called "segmented addressing." Assembly
  1530.      language often requires a more complete understanding of segmented
  1531.      addressing than C does.%@NL@%
  1532. %@NL@%
  1533.      Section 2.7%@BO:       28c1c@%, "Segmented Addressing and Segment Registers," explains
  1534.      the full implications of segmented addressing.%@NL@%
  1535. %@NL@%
  1536.   Of the features listed above, segmented addressing is unique to the 8086
  1537.   family. The 8086 is further distinguished from other processors by its set
  1538.   of string operations, which permit fast initialization and copying of
  1539.   blocks of data. You can read more about the string operations in Chapter
  1540.   16%@BO:       d1833@%, "Processing Strings."%@NL@%
  1541. %@NL@%
  1542. %@NL@%
  1543. %@2@%%@CR:SC2.2       @%%@AB@%2.2  Instructions, Directives, and Operands%@AE@%%@EH@%%@NL@%
  1544. %@NL@%
  1545. %@4@%  The 8086-family processors understand only one kind of statement: an%@EH@%
  1546.   instruction. QuickAssembler understands two kinds of statements:
  1547.   instructions and directives.%@NL@%
  1548. %@NL@%
  1549. %@4@%%@CR:IX2.7       @%  As explained above, an instruction corresponds to a specific action that%@EH@%
  1550.   the processor executes at run time. The fundamental task of the assembler
  1551.   is to correctly translate each of these statements to specific
  1552.   machine-code instructions.%@NL@%
  1553. %@NL@%
  1554. %@4@%%@CR:IX2.8       @%  As nonexecutable statements, directives are not translated to machine%@EH@%
  1555.   actions. However, they give information to the assembler that affects how
  1556.   other statements are translated. For example, some of the most important
  1557.   directives declare data. These directives, in turn, help the assembler
  1558.   correctly interpret instructions that refer to the data.%@NL@%
  1559. %@NL@%
  1560. %@4@%  The rest of this section explains each part of an assembly-language%@EH@%
  1561.   statement; the general syntax applies to both instructions and directives.
  1562.   The section ends by stating the basics of entering numbers in different
  1563.   radixes.%@NL@%
  1564. %@NL@%
  1565. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  1566. %@NL@%
  1567. %@4@%  Each line of source code consists of a blank line or a statement. Each%@EH@%
  1568.   statement is an instruction or directive, and can contain as many as 512
  1569.   characters. Statements can have up to four fields, as shown below:%@NL@%
  1570. %@NL@%
  1571. %@4@%  [[%@AI@%name%@AE@%]] [[%@AI@%operation%@AE@%]] [[%@AI@%operands%@AE@%]] [[%@AB@%;%@AE@%%@AI@%comment%@AE@%]]%@EH@%%@NL@%
  1572. %@NL@%
  1573. %@4@%%@CR:IX2.9       @%%@CR:IX2.10      @%  Each field (except the comment field) must be separated from the other%@EH@%
  1574.   fields by a space or tab character. You can enter statements in uppercase
  1575.   or lowercase letters. By default, QuickAssembler is not case sensitive,
  1576.   but it does preserve case for external variables──thus providing
  1577.   compatibility with C, which is case sensitive. You can control case
  1578.   sensitivity by using the Assembler Flags dialog box.%@NL@%
  1579. %@NL@%
  1580. %@4@%  As a convention, sample code in this manual uses uppercase letters for%@EH@%
  1581.   directives, hexadecimal letter digits, and segment definitions.%@NL@%
  1582. %@NL@%
  1583. %@NL@%
  1584. %@3@%%@CR:SC2.2.1     @%%@AB@%2.2.1  The Name Field%@AE@%%@EH@%%@NL@%
  1585. %@NL@%
  1586. %@4@%  The %@AI@%name%@AE@% field labels the statement with a symbolic name that other parts%@EH@%
  1587.   of the program can reference. The meaning of the name depends on the type
  1588.   of statement.%@NL@%
  1589. %@NL@%
  1590. %@4@%  One of the most important uses of this field occurs in data declarations.%@EH@%
  1591.   These declarations are much like variable declarations in C. The statement
  1592.   defines the type and initial value. You use the name elsewhere in the
  1593.   program, when you want to access the data.%@NL@%
  1594. %@NL@%
  1595. %@4@%  QuickAssembler is different from C, however, in that the symbolic name%@EH@%
  1596.   occurs in the first field. For example, the following %@AB@%DB%@AE@% directive
  1597.   (Declare Bytes) associates the name %@AS@%string %@AE@%with a series of characters:%@NL@%
  1598. %@NL@%
  1599.   %@AS@%string      DB    "Hello, world"%@AE@%%@NL@%
  1600. %@NL@%
  1601. %@4@%  In instructions, the %@AI@%name%@AE@% field functions like a program label in C: it%@EH@%
  1602.   provides a target for a jump or call instruction elsewhere in the program.%@NL@%
  1603. %@NL@%
  1604. %@4@%  To label an instruction, follow the %@AI@%name%@AE@% field with a colon (%@AB@%:%@AE@%). You can%@EH@%
  1605.   place the name on the same line as the rest of the instruction or, to
  1606.   improve readability, on a separate line. The following example shows the
  1607.   latter case:%@NL@%
  1608. %@NL@%
  1609.   %@AS@%top:                    ; This label marks the top of the loop%@AE@%%@NL@%
  1610.   %@AS@%            mov   ax,1  ; This is first instruction in the loop%@AE@%%@NL@%
  1611. %@NL@%
  1612. %@4@%  There are other ways to label instructions. See Section 6.4%@BO:       5d761@%, "Defining%@EH@%
  1613.   Code Labels," for more information on how to declare labels.%@NL@%
  1614. %@NL@%
  1615. %@NL@%
  1616. %@3@%%@CR:SC2.2.2     @%%@AB@%2.2.2  The Operation Field%@AE@%%@EH@%%@NL@%
  1617. %@NL@%
  1618. %@4@%  The %@AI@%operation%@AE@% field states the action of the statement. This field%@EH@%
  1619.   determines the fundamental type of the statement──instruction or
  1620.   directive. It also determines what additional syntax, if any, is required.
  1621.   Some operations require an entry in the %@AI@%name%@AE@% field; most do not. If the
  1622.   operation is an instruction, it strictly determines how many and what kind
  1623.   of operands are legal.%@NL@%
  1624. %@NL@%
  1625. %@4@%  This field contains exactly one item──an instruction or directive%@EH@%
  1626.   mnemonic. "Mnemonics" are abbreviated, easy-to-remember names that each
  1627.   symbolize a different operation (for instance, %@AB@%ADD%@AE@%, %@AB@%SUB%@AE@%, and %@AB@%OR%@AE@%). Examples
  1628.   of directive mnemonics include %@AB@%EQU%@AE@% (Equate) and %@AB@%DB%@AE@% (Declare Bytes).%@NL@%
  1629. %@NL@%
  1630. %@NL@%
  1631. %@3@%%@CR:SC2.2.3     @%%@AB@%2.2.3  The Operand Field%@AE@%%@EH@%%@NL@%
  1632. %@NL@%
  1633. %@4@%  The %@AI@%operand%@AE@% field lists the objects on which the statement operates.%@EH@%
  1634.   Multiple operands are separated by commas. These objects can be registers,
  1635.   constants, or memory locations. A memory location is typically represented
  1636.   as a variable, although it can also be expressed as a numeric address or
  1637.   complex expression.%@NL@%
  1638. %@NL@%
  1639. %@4@%  Registers and constants require no previous declaration. To refer to a%@EH@%
  1640.   variable, however, you should first declare the name with a data
  1641.   directive, such as %@AB@%DB%@AE@% (Declare Bytes). The following example declares the
  1642.   variable %@AS@%count %@AE@%and then uses it in an instruction:%@NL@%
  1643. %@NL@%
  1644.   %@AS@% count      DB      7       ; Declare count as a byte variable%@AE@%%@NL@%
  1645.   %@AS@%            .%@AE@%%@NL@%
  1646.   %@AS@%            .%@AE@%%@NL@%
  1647.   %@AS@%            .%@AE@%%@NL@%
  1648.   %@AS@%            inc     count   ; count = count + 1%@AE@%%@NL@%
  1649. %@NL@%
  1650. %@4@%  In the first statement, %@AS@%count %@AE@%appears in the %@AI@%name%@AE@% field and the number %@AS@%7%@AE@%%@EH@%
  1651.   appears in the %@AI@%operand%@AE@% field. The %@AB@%DB%@AE@% directive associates %@AS@%count %@AE@%with the
  1652.   address of a byte initialized to %@AS@%7%@AE@%. In the second statement,%@AS@% count %@AE@%appears
  1653.   in the %@AI@%operand%@AE@% field. The %@AB@%INC%@AE@% instruction (increment) adds 1 to %@AS@%count%@AE@%,
  1654.   thus increasing the value of the data to %@AS@%8%@AE@%.%@NL@%
  1655. %@NL@%
  1656. %@4@%  The next section gives more information on how to declare memory locations%@EH@%
  1657.   as data types. Section 2.6%@BO:       2404d@%, "Addressing Modes," gives a complete
  1658.   description of all the different methods for specifying operands.%@NL@%
  1659. %@NL@%
  1660. %@NL@%
  1661. %@3@%%@CR:SC2.2.4     @%%@AB@%2.2.4  The Comment Field%@AE@%%@EH@%%@NL@%
  1662. %@NL@%
  1663. %@4@%  The %@AI@%comment%@AE@% field lets you add text that appears in source code but is%@EH@%
  1664.   ignored by the assembler. You can enter any text you want in this field.
  1665.   Typically, you would use it to document the purpose of the statement. The
  1666.   purpose of an assembly-language statement is not always self-explanatory,
  1667.   and for this reason, programs often contain at least one comment for each
  1668.   instruction.%@NL@%
  1669. %@NL@%
  1670. %@4@%  Single-line comments always begin with a semicolon (%@AB@%;%@AE@%). You can also%@EH@%
  1671.   create a multiline comment by one of two methods. You can enter successive
  1672.   comment lines as shown below:%@NL@%
  1673. %@NL@%
  1674.   %@AS@%            add     count,5    ; Add 5 to count.%@AE@%%@NL@%
  1675.   %@AS@%                               ;   ADD is the operation.%@AE@%%@NL@%
  1676.   %@AS@%                               ;   count and 5 are operands.%@AE@%%@NL@%
  1677.   %@AS@%            sub     Sum,12     ; Subtract 12 from Sum.%@AE@%%@NL@%
  1678.   %@AS@%                               ;   SUB is the operation.%@AE@%%@NL@%
  1679.   %@AS@%                               ;   Sum and 12 are operands.%@AE@%%@NL@%
  1680. %@NL@%
  1681. %@4@%%@CR:IX2.11      @%%@CR:IX2.12      @%  You can also use the %@AB@%COMMENT%@AE@% directive, which lets you enter multiline%@EH@%
  1682.   comments without using the semicolon. This directive has the following
  1683.   syntax:%@NL@%
  1684. %@NL@%
  1685. %@4@%  %@AB@%COMMENT %@AE@%%@AI@%delimiter%@AE@% [[%@AI@%text%@AE@%]]%@EH@%%@NL@%
  1686.   %@AI@%text%@AE@%%@NL@%
  1687.   [[%@AI@%text%@AE@%]] %@AI@%delimiter%@AE@% [[%@AI@%text%@AE@%]]%@NL@%
  1688. %@NL@%
  1689. %@4@%  All %@AI@%text%@AE@% between the first %@AI@%delimiter%@AE@% and the line containing a second%@EH@%
  1690.   %@AI@%delimiter%@AE@% is ignored by the assembler. The %@AI@%delimiter%@AE@% character is the
  1691.   first nonblank character after the %@AB@%COMMENT%@AE@% directive. The %@AI@%text%@AE@% includes
  1692.   the comments up to and including the line containing the next occurrence
  1693.   of the delimiter.%@NL@%
  1694. %@NL@%
  1695. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  1696. %@NL@%
  1697.   %@AS@%            COMMENT + The plus%@AE@%%@NL@%
  1698.   %@AS@%                    sign is the delimiter. The%@AE@%%@NL@%
  1699.   %@AS@%                    assembler ignores the statement%@AE@%%@NL@%
  1700.   %@AS@%                    following the last delimiter%@AE@%%@NL@%
  1701.   %@AS@%+           mov     ax,1   (ignored)%@AE@%%@NL@%
  1702. %@NL@%
  1703. %@NL@%
  1704. %@3@%%@CR:SC2.2.5     @%%@AB@%2.2.5  Entering Numbers in Different Bases%@AE@%%@EH@%%@NL@%
  1705. %@NL@%
  1706. %@4@%  As with C, you can enter assembly-language constants as decimal,%@EH@%
  1707.   hexadecimal, or octal. You can also enter binary constants. By default,
  1708.   all constants are decimal, but you specify a different default with the
  1709.   %@AB@%RADIX%@AE@% directive.%@NL@%
  1710. %@NL@%
  1711. %@4@%  Hexadecimal constants appear frequently in assembly-language programs. To%@EH@%
  1712.   indicate a hexadecimal constant, add an uppercase or lowercase H suffix.
  1713.   If the first digit is one of the letters A-F, prefix the constant with a
  1714.   leading 0 to indicate that the number is not a symbolic name.%@NL@%
  1715. %@NL@%
  1716. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  1717. %@NL@%
  1718.   %@AS@%100H%@AE@%%@NL@%
  1719.   %@AS@%10FAh%@AE@%%@NL@%
  1720.   %@AS@%0be03H%@AE@%%@NL@%
  1721.   %@AS@%0FFh%@AE@%%@NL@%
  1722. %@NL@%
  1723. %@4@%  You may often want to enter binary constants as well, particularly when%@EH@%
  1724.   constructing bit masks. To indicate a binary constant, simply add an
  1725.   uppercase or lowercase B suffix.%@NL@%
  1726. %@NL@%
  1727. %@4@%  For more information on using different bases and using the %@AB@%RADIX%@AE@%%@EH@%
  1728.   directive, see Section 6.1.1.2%@BO:       58a87@%, "Setting the Default Radix."%@NL@%
  1729. %@NL@%
  1730. %@CR:IX2.13      @%%@NL@%
  1731. %@3@%%@CR:SC2.2.6     @%%@AB@%2.2.6  Line-Continuation Character%@AE@%%@EH@%%@NL@%
  1732. %@NL@%
  1733. %@4@%  You can create program lines that extend over more than one physical line%@EH@%
  1734.   by using the backslash (\) as a line-continuation character. The backslash
  1735.   must be the last character on the line. Comments cannot follow it. A
  1736.   backslash is not considered a continuation character if it occurs in a
  1737.   comment.%@NL@%
  1738. %@NL@%
  1739. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  1740. %@NL@%
  1741.   %@AS@%BigProc     PROC FAR \%@AE@%%@NL@%
  1742.   %@AS@%            USES DS SI DI, \%@AE@%%@NL@%
  1743.   %@AS@%            IntArg:WORD, \%@AE@%%@NL@%
  1744.   %@AS@%            String:FAR PTR BYTE, \%@AE@%%@NL@%
  1745.   %@AS@%            Ptr:FAR PTR BIGSTRUC, \%@AE@%%@NL@%
  1746.   %@AS@%            Long:DWORD%@AE@%%@NL@%
  1747.   %@AS@%            .%@AE@%%@NL@%
  1748.   %@AS@%            .%@AE@%%@NL@%
  1749.   %@AS@%            .%@AE@%%@NL@%
  1750. %@NL@%
  1751.   %@AS@%            ret%@AE@%%@NL@%
  1752.   %@AS@%BigProc     ENDP%@AE@%%@NL@%
  1753. %@NL@%
  1754. %@4@%  In this example, the line continuation-character is used to specify%@EH@%
  1755.   multiple procedure arguments with the extended %@AB@%PROC%@AE@% syntax. All the
  1756.   arguments must be placed on a single logical line, but they would go past
  1757.   the edge of the editor screen if not placed on separate lines. The
  1758.   continuation character is also useful for long macro calls and data
  1759.   initializations.%@NL@%
  1760. %@NL@%
  1761. %@NL@%
  1762. %@2@%%@CR:SC2.3       @%%@AB@%2.3  8086-Family Instructions%@AE@%%@EH@%%@NL@%
  1763. %@NL@%
  1764. %@4@%%@CR:IX2.14      @%  The 8086-family processors support more than 80 instructions, but you%@EH@%
  1765.   don't need to memorize the entire instruction set. Once inside the
  1766.   expanded QuickC environment, you can get instant information on any
  1767.   instruction. Move the cursor to an instruction keyword on the screen, then
  1768.   press F1. To find the appropriate instruction for the action you want to
  1769.   perform, refer to Part 3%@BO:       a6c61@% of this book, which provides a topical survey of
  1770.   instructions.%@NL@%
  1771. %@NL@%
  1772. %@4@%  Many programs can be written with just a few of the most common%@EH@%
  1773.   instructions. Sections 2.3.1%@BO:       1923f@% and 2.3.2%@BO:       1a91f@% introduce some of these
  1774.   instructions, grouping them into two sets: instructions that manipulate
  1775.   data and instructions that control program flow. The programs in Chapters
  1776.   3%@BO:       2aca0@% and 4%@BO:       34dba@% use these same instructions to illustrate basic concepts of 8086
  1777.   assembly language.%@NL@%
  1778. %@NL@%
  1779. %@NL@%
  1780. %@3@%%@CR:SC2.3.1     @%%@AB@%2.3.1  Data-Manipulation Instructions%@AE@%%@EH@%%@NL@%
  1781. %@NL@%
  1782. %@4@%%@CR:IX2.15      @%%@CR:IX2.16      @%  The first group of instructions manipulate data. Each causes the processor%@EH@%
  1783.   to copy data or perform a calculation at run time. Some of the simpler C
  1784.   statements translate directly into a single instruction, so this section
  1785.   uses C statements for illustration. Here are the six basic data-
  1786.   manipulation instructions introduced in this section:%@NL@%
  1787. %@NL@%
  1788.   ■  %@AB@%MOV%@AE@% (move data)%@NL@%
  1789. %@NL@%
  1790.   ■  %@AB@%ADD%@AE@% (add second operand to first)%@NL@%
  1791. %@NL@%
  1792.   ■  %@AB@%SUB%@AE@% (subtract second operand from first)%@NL@%
  1793. %@NL@%
  1794.   ■  %@AB@%INC%@AE@% (increment operand)%@NL@%
  1795. %@NL@%
  1796.   ■  %@AB@%DEC%@AE@% (decrement operand)%@NL@%
  1797. %@NL@%
  1798.   ■  %@AB@%MUL%@AE@% (integer multiplication)%@NL@%
  1799. %@NL@%
  1800. %@4@%  The processor supports a great many other data-manipulation instructions,%@EH@%
  1801.   which are covered in Part 3%@BO:       a6c61@% of this manual.%@NL@%
  1802. %@NL@%
  1803. %@CR:IX2.17      @%%@CR:IX2.18      @%%@NL@%
  1804. %@3@%%@CR:SC2.3.1.1   @%%@AB@%2.3.1.1  The MOV Instruction%@AE@%%@EH@%%@NL@%
  1805. %@NL@%
  1806. %@4@%  The %@AB@%MOV%@AE@% instruction, probably the most frequently used 8086 instruction,%@EH@%
  1807.   copies data from one location to another. The instruction leaves the
  1808.   source data unaffected, so it is more a copy than a move. The %@AB@%MOV%@AE@%
  1809.   instruction takes two operands:%@NL@%
  1810. %@NL@%
  1811. %@4@%  %@AB@%MOV%@AE@% %@AI@%destination%@AE@%%@AB@%,%@AE@%%@AI@%source%@AE@%%@EH@%%@NL@%
  1812. %@NL@%
  1813. %@4@%%@CR:IX2.19      @%%@CR:IX2.20      @%  The instruction copies the value of the %@AI@%source%@AE@% to the %@AI@%destination%@AE@%. It%@EH@%
  1814.   might seem more logical to place the %@AI@%source%@AE@% operand first, until you
  1815.   consider that C and BASIC assignments use the same order. For example, the
  1816.   instruction%@NL@%
  1817. %@NL@%
  1818.   %@AS@%mov   count,5%@AE@%%@NL@%
  1819. %@NL@%
  1820. %@4@%  places the value %@AS@%5 %@AE@%at the memory location %@AS@%count %@AE@%and thus performs the same%@EH@%
  1821.   action as the C statement%@NL@%
  1822. %@NL@%
  1823.   %@AS@%count = 5;%@AE@%%@NL@%
  1824. %@NL@%
  1825. %@4@%%@CR:IX2.21      @%%@CR:IX2.22      @%  The destination operand is similar to an "lvalue" in C. Instructions that%@EH@%
  1826.   have two operands always interpret the leftmost operand as the
  1827.   destination, or lvalue. The destination is the operand that the
  1828.   instruction can alter; thus, it can't be a constant. Another limitation on
  1829.   instructions with two operands is that the operands cannot both be memory
  1830.   locations.%@NL@%
  1831. %@NL@%
  1832. %@CR:IX2.23      @%%@CR:IX2.24      @%%@NL@%
  1833. %@3@%%@CR:SC2.3.1.2   @%%@AB@%2.3.1.2  The ADD Instruction%@AE@%%@EH@%%@NL@%
  1834. %@NL@%
  1835. %@4@%  The %@AB@%ADD%@AE@% instruction, like %@AB@%MOV%@AE@%, takes two operands: a destination and a%@EH@%
  1836.   source. The processor adds the two operands together, storing the result
  1837.   in the destination (on the left). This action will be familiar to C
  1838.   programmers, since the instruction%@NL@%
  1839. %@NL@%
  1840.   %@AS@%add  sum,10%@AE@%%@NL@%
  1841. %@NL@%
  1842. %@4@%  adds %@AS@%10 %@AE@%to the memory location %@AS@%sum %@AE@%and thus performs the same action as%@EH@%
  1843.   the C statement%@NL@%
  1844. %@NL@%
  1845.   %@AS@%sum += 10;%@AE@%%@NL@%
  1846. %@NL@%
  1847. %@4@%  The 8086 does not perform automatic scaling for pointer addition as C%@EH@%
  1848.   does. The program itself must perform scaling for all pointer arithmetic.%@NL@%
  1849. %@NL@%
  1850. %@CR:IX2.25      @%%@CR:IX2.26      @%%@NL@%
  1851. %@3@%%@CR:SC2.3.1.3   @%%@AB@%2.3.1.3  The SUB Instruction%@AE@%%@EH@%%@NL@%
  1852. %@NL@%
  1853. %@4@%  The %@AB@%SUB%@AE@% instruction is the counterpart of %@AB@%ADD%@AE@%: it subtracts the source%@EH@%
  1854.   operand from the destination operand, storing the result in the
  1855.   destination (on the left). Thus, the instruction%@NL@%
  1856. %@NL@%
  1857.   %@AS@%sub  total,7%@AE@%%@NL@%
  1858. %@NL@%
  1859. %@4@%  performs the same action as the C statement%@EH@%%@NL@%
  1860. %@NL@%
  1861.   %@AS@%total -= 7;%@AE@%%@NL@%
  1862. %@NL@%
  1863. %@CR:IX2.27      @%%@CR:IX2.28      @%%@CR:IX2.29      @%%@CR:IX2.30      @%%@NL@%
  1864. %@3@%%@CR:SC2.3.1.4   @%%@AB@%2.3.1.4  The INC and DEC Instructions%@AE@%%@EH@%%@NL@%
  1865. %@NL@%
  1866. %@4@%  The %@AB@%INC%@AE@% (Increment) and %@AB@%DEC%@AE@% (Decrement) instructions add and subtract 1,%@EH@%
  1867.   respectively. They are similar to, but faster than, %@AB@%ADD%@AE@% and %@AB@%SUB%@AE@%, and are
  1868.   provided because adding and subtracting by 1 are such common operations.
  1869.   The instruction%@NL@%
  1870. %@NL@%
  1871.   %@AS@%inc   count%@AE@%%@NL@%
  1872. %@NL@%
  1873. %@4@%  performs the same action as the C statement%@EH@%%@NL@%
  1874. %@NL@%
  1875.   %@AS@%count++;%@AE@%%@NL@%
  1876. %@NL@%
  1877. %@CR:IX2.31      @%%@CR:IX2.32      @%%@NL@%
  1878. %@3@%%@CR:SC2.3.1.5   @%%@AB@%2.3.1.5  The AND Instruction%@AE@%%@EH@%%@NL@%
  1879. %@NL@%
  1880. %@4@%  The %@AB@%AND%@AE@% instruction is one of several bitwise logic operations supported%@EH@%
  1881.   by the 8086. %@AB@%AND%@AE@% provides an efficient way to mask out bits. The
  1882.   instruction%@NL@%
  1883. %@NL@%
  1884.   %@AS@%and   stuff,0FFF0h%@AE@%%@NL@%
  1885. %@NL@%
  1886. %@4@%  masks out the four lowest bits of %@AS@%stuff%@AE@%, as does the C statement%@EH@%%@NL@%
  1887. %@NL@%
  1888.   %@AS@%stuff &= 0x0FFF0;%@AE@%%@NL@%
  1889. %@NL@%
  1890. %@CR:IX2.33      @%%@CR:IX2.34      @%%@NL@%
  1891. %@3@%%@CR:SC2.3.1.6   @%%@AB@%2.3.1.6  The MUL Instruction%@AE@%%@EH@%%@NL@%
  1892. %@NL@%
  1893. %@4@%  The %@AB@%MUL%@AE@% instruction multiplies two items, but one of these items is an%@EH@%
  1894.   "implied operand"──that is, an operand you do not specify. For example,
  1895.   the 16-bit version of the %@AB@%MUL%@AE@% instruction takes one explicit 16-bit
  1896.   operand:%@NL@%
  1897. %@NL@%
  1898.   %@AS@%mul   factor%@AE@%%@NL@%
  1899. %@NL@%
  1900. %@4@%  The other operand is the AX register. The processor multiplies %@AS@%factor %@AE@%by%@EH@%
  1901.   the value of AX, storing the low 16 bits of the result in AX. The
  1902.   description of the AX register in Section 2.5.1%@BO:       1ef06@%, "The General-Purpose
  1903.   Registers," gives more information on %@AB@%MUL%@AE@%.%@NL@%
  1904. %@NL@%
  1905. %@CR:IX2.35      @%%@CR:IX2.36      @%%@NL@%
  1906. %@3@%%@CR:SC2.3.2     @%%@AB@%2.3.2  Control-Flow Instructions%@AE@%%@EH@%%@NL@%
  1907. %@NL@%
  1908. %@4@%  The control-flow instructions enable the program to execute loops and to%@EH@%
  1909.   make decisions. Some of these instructions transfer control of the program
  1910.   to a new address. The conditional jump instructions let you provide
  1911.   program logic: they look at the result of a previous operation, and then
  1912.   decide whether to jump or not. Here are the five basic control-flow
  1913.   instructions introduced in this section:%@NL@%
  1914. %@NL@%
  1915.   ■  %@AB@%JMP%@AE@% (Jump unconditionally)%@NL@%
  1916. %@NL@%
  1917.   ■  %@AB@%CMP%@AE@% (Compare──subtract without storing result)%@NL@%
  1918. %@NL@%
  1919.   ■  %@AB@%JE%@AE@% (Jump If Equal)%@NL@%
  1920. %@NL@%
  1921.   ■  %@AB@%JA%@AE@% (Jump If Above)%@NL@%
  1922. %@NL@%
  1923.   ■  %@AB@%JB%@AE@% (Jump If Below)%@NL@%
  1924. %@NL@%
  1925. %@4@%  The processor supports a number of other control-flow instructions,%@EH@%
  1926.   including several conditional jumps. See Section 15.1.2%@BO:       be4fa@%, "Jumping
  1927.   Conditionally," for a description of these instructions.%@NL@%
  1928. %@NL@%
  1929. %@CR:IX2.37      @%%@CR:IX2.38      @%%@NL@%
  1930. %@3@%%@CR:SC2.3.2.1   @%%@AB@%2.3.2.1  The JMP Instruction%@AE@%%@EH@%%@NL@%
  1931. %@NL@%
  1932. %@4@%  The %@AB@%JMP%@AE@% instruction causes the processor to jump to a new program address.%@EH@%
  1933.   Like the C %@AB@%goto%@AE@% statement, %@AB@%JMP%@AE@% takes one operand: a label associated with
  1934.   another statement. The instruction%@NL@%
  1935. %@NL@%
  1936.   %@AS@%jmp   begin%@AE@%%@NL@%
  1937. %@NL@%
  1938. %@4@%  jumps to the label %@AS@%begin%@AE@%, and thus performs the same action as the C%@EH@%
  1939.   statement%@NL@%
  1940. %@NL@%
  1941.   %@AS@%goto begin;%@AE@%%@NL@%
  1942. %@NL@%
  1943. %@CR:IX2.39      @%%@CR:IX2.40      @%%@NL@%
  1944. %@3@%%@CR:SC2.3.2.2   @%%@AB@%2.3.2.2  The CMP Instruction%@AE@%%@EH@%%@NL@%
  1945. %@NL@%
  1946. %@4@%  The %@AB@%CMP%@AE@% instruction, like %@AB@%SUB%@AE@%, performs a subtraction. But %@AB@%CMP%@AE@% doesn't%@EH@%
  1947.   store the result; instead, it just sets processor flags in preparation for
  1948.   a conditional jump (such as %@AB@%JE%@AE@%, %@AB@%JA%@AE@%, or %@AB@%JB%@AE@%).%@NL@%
  1949. %@NL@%
  1950. %@4@%  A "processor flag" is a bit that resides in the processor and indicates%@EH@%
  1951.   whether a specific condition is on or off. For example, the Zero flag
  1952.   indicates that the result of the last operation produced zero. The %@AB@%JE%@AE@%
  1953.   instruction (Jump If Equal) checks this one flag only, jumping if it is
  1954.   set. Other conditional jumps determine a result by checking a %@AI@%combination%@AE@%
  1955.   of flag settings. See Section 2.5.4%@BO:       22b46@%, "The Flags Register," for a
  1956.   description of all the flags.%@NL@%
  1957. %@NL@%
  1958. %@4@%  Many instructions, including %@AB@%SUB%@AE@%, set processor flags. However, some of%@EH@%
  1959.   these instructions have strong side effects. Use %@AB@%ADD%@AE@% or %@AB@%SUB%@AE@% to prepare for
  1960.   a conditional jump when convenient. But use %@AB@%CMP%@AE@% when you need to make a
  1961.   simple comparison without altering data.%@NL@%
  1962. %@NL@%
  1963. %@CR:IX2.41      @%%@CR:IX2.42      @%%@NL@%
  1964. %@3@%%@CR:SC2.3.2.3   @%%@AB@%2.3.2.3  The Conditional Jump Instructions%@AE@%%@EH@%%@NL@%
  1965. %@NL@%
  1966. %@4@%  The %@AB@%JE%@AE@%, %@AB@%JA%@AE@%, and %@AB@%JB%@AE@% instructions are conditional jumps (meaning Jump On%@EH@%
  1967.   Equal, Jump If Above, and Jump If Below, respectively). Like %@AB@%JMP%@AE@%, they
  1968.   each take one argument: a program label to which to jump. Unlike %@AB@%JMP%@AE@%, they
  1969.   cause the processor to jump only when certain flag settings are detected.
  1970.   The result is that when you use %@AB@%CMP%@AE@% in combination with a conditional jump
  1971.   instruction, you create an if-then relationship similar to an %@AB@%if%@AE@% statement
  1972.   in a high-level language. Consider the following instructions:%@NL@%
  1973. %@NL@%
  1974.   %@AS@%            cmp     sum,10       ; Compare sum to 10%@AE@%%@NL@%
  1975.   %@AS@%            ja      top          ; If sum > 10, jump to top%@AE@%%@NL@%
  1976. %@NL@%
  1977. %@4@%  This logic is a little different from a C program. The first instruction%@EH@%
  1978.   makes the comparison. The second states, "If the result of the %@AI@%previous%@AE@%
  1979.   instruction was above zero, then jump." Taken together, these two
  1980.   instructions perform the same action as the C statement%@NL@%
  1981. %@NL@%
  1982.   %@AS@%if( sum > 10 )%@AE@%%@NL@%
  1983.   %@AS@%    goto top;%@AE@%%@NL@%
  1984. %@NL@%
  1985. %@4@%%@CR:IX2.43      @%  Of course, most C programmers do not use many%@AB@% goto %@AE@%statements. Typically,%@EH@%
  1986.   you would test for a condition and execute a series of statements if the
  1987.   condition is true, as in the following code:%@NL@%
  1988. %@NL@%
  1989.   %@AS@%if( sum >= 10 )%@AE@%%@NL@%
  1990.   %@AS@%{%@AE@%%@NL@%
  1991.   %@AS@%    sum = 1;%@AE@%%@NL@%
  1992.   %@AS@%    count += 2;%@AE@%%@NL@%
  1993.   %@AS@%    delta = 5;%@AE@%%@NL@%
  1994.   %@AS@%}%@AE@%%@NL@%
  1995. %@NL@%
  1996. %@4@%%@CR:IX2.44      @%  To implement this code in assembly language, test for the opposite%@EH@%
  1997.   condition, then jump past statements if they should not be executed. For
  1998.   example, the following code executes the three statements inside the if
  1999.   block only if %@AS@%sum %@AE@%is greater than or equal to %@AS@%10%@AE@%:%@NL@%
  2000. %@NL@%
  2001.   %@AS@%TopOfBlock:%@AE@%%@NL@%
  2002.   %@AS@%            cmp     sum,10           ; Compare sum to 10%@AE@%%@NL@%
  2003.   %@AS@%            jb      SumNotGreater    ; If sum < 10, do NOT do%@AE@%%@NL@%
  2004.   %@AS@%                                     ;   next three statements%@AE@%%@NL@%
  2005.   %@AS@%            mov     sum,1            ; sum = 1%@AE@%%@NL@%
  2006.   %@AS@%            add     count,2          ; count = count + 2%@AE@%%@NL@%
  2007.   %@AS@%            mov     delta,5          ; delta = 5%@AE@%%@NL@%
  2008.   %@AS@%SumNotGreater:%@AE@%%@NL@%
  2009. %@NL@%
  2010.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2011.   %@AB@%NOTE%@AE@%  %@AB@%JA%@AE@% (Jump If Above) and %@AB@%JB%@AE@% (Jump If Below) each work properly when
  2012.   you compare unsigned integers. To compare signed integers, use %@AB@%JG%@AE@% (Jump If
  2013.   Greater) and %@AB@%JL%@AE@% (Jump If Less Than). See Section 15.1.2%@BO:       be4fa@%, "Jumping
  2014.   Conditionally," for a complete list of conditional jump instructions.%@NL@%
  2015.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2016. %@NL@%
  2017. %@NL@%
  2018. %@2@%%@CR:SC2.4       @%%@AB@%2.4  Declaring Simple Data Objects%@AE@%%@EH@%%@NL@%
  2019. %@NL@%
  2020. %@4@%  This section describes how to declare global variables──often called%@EH@%
  2021.   "static" because each corresponds to a fixed memory location.%@NL@%
  2022. %@NL@%
  2023. %@4@%  Programs generally require data. If you wrote a program in machine code,%@EH@%
  2024.   you'd have to reserve locations in memory for data, determine the address
  2025.   of each data object, and remember these addresses whenever you operated on
  2026.   memory. Fortunately, the assembler reserves memory locations for you and
  2027.   associates each location with a symbolic name.%@NL@%
  2028. %@NL@%
  2029. %@4@%%@CR:IX2.45      @%%@CR:IX2.46      @%  You use data directives to tell the assembler how to allocate and refer to%@EH@%
  2030.   memory. The most common data directives for characters and integers are:%@NL@%
  2031. %@NL@%
  2032.   %@AB@%Directive%@AE@%           %@AB@%Description%@AE@%%@NL@%
  2033.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2034. %@CR:IX2.47      @%%@CR:IX2.48      @%  %@AB@%DB%@AE@%                  Declare byte (either a small integer or a character)%@NL@%
  2035. %@NL@%
  2036. %@CR:IX2.49      @%%@CR:IX2.50      @%  %@AB@%DW%@AE@%                  Declare word (2-byte integer)%@NL@%
  2037. %@NL@%
  2038. %@CR:IX2.51      @%%@CR:IX2.52      @%  %@AB@%DD%@AE@%                  Declare doubleword (4-byte integer)%@NL@%
  2039. %@NL@%
  2040. %@NL@%
  2041. %@4@%  To use these directives, place the name of the variable first, then enter%@EH@%
  2042.   the data directive. The third column (operand field) contains one or more
  2043.   initial values. Use a question mark to indicate an item with no initial
  2044.   value.%@NL@%
  2045. %@NL@%
  2046.   %@AS@%aByte       DB    1    ; aByte is a 1-byte integer, initialized to 1%@AE@%%@NL@%
  2047.   %@AS@%area        DW    500  ; area is a 2-byte integer, initialized to 500%@AE@%%@NL@%
  2048.   %@AS@%population  DD    ?    ; population is a 4-byte integer, no initial value%@AE@%%@NL@%
  2049. %@NL@%
  2050. %@4@%  These directives correspond roughly to the following C statements:%@EH@%%@NL@%
  2051. %@NL@%
  2052.   %@AS@%char    aByte = 1;%@AE@%%@NL@%
  2053.   %@AS@%int     area = 500;%@AE@%%@NL@%
  2054.   %@AS@%long    population;%@AE@%%@NL@%
  2055. %@NL@%
  2056. %@4@%  Assembly data declarations are different from C declarations, however, in%@EH@%
  2057.   that assembly data declarations are not declared signed or unsigned.
  2058.   Instead, you must remember whether you intend to treat a variable as
  2059.   signed or unsigned, and choose the appropriate operations.%@NL@%
  2060. %@NL@%
  2061. %@4@%%@CR:IX2.53      @%  Data directives reserve memory in the object file. They also associate%@EH@%
  2062.   each variable with a name and a size attribute.%@NL@%
  2063. %@NL@%
  2064. %@4@%  The assembler uses this information to correctly assemble instructions%@EH@%
  2065.   that operate on variables. For example, at the machine-code level, the %@AB@%INC%@AE@%
  2066.   instruction can be encoded to increment either a byte or a word of data.
  2067.   The way the assembler encodes the instruction%@NL@%
  2068. %@NL@%
  2069.   %@AS@%            inc     myvar%@AE@%%@NL@%
  2070. %@NL@%
  2071. %@4@%  depends on whether %@AS@%myvar %@AE@%was declared as a byte or word. (If it was%@EH@%
  2072.   declared a doubleword, the instruction is illegal.) Another important use
  2073.   of size attributes is in checking the validity of two operands. For
  2074.   example, the following instruction causes the assembler to print a warning
  2075.   message, because %@AS@%aByte %@AE@%and %@AS@%bx %@AE@%do not share the size attribute:%@NL@%
  2076. %@NL@%
  2077.   %@AS@%            mov     bx,aByte    ; Move aByte into a word register%@AE@%%@NL@%
  2078. %@NL@%
  2079. %@4@%  Moving a byte into a word location is not possible. After issuing the%@EH@%
  2080.   warning, the assembler adjusts the instruction as if it were written as
  2081.   follows:%@NL@%
  2082. %@NL@%
  2083.   %@AS@%            mov     bx,WORD PTR aByte  ; Move the word at aByte to BX%@AE@%%@NL@%
  2084. %@NL@%
  2085. %@4@%%@CR:IX2.54      @%%@CR:IX2.55      @%  The %@AB@%PTR%@AE@% operator temporarily modifies the size attribute of the object%@EH@%
  2086.   that follows it. %@AB@%PTR%@AE@% can be used with a number of different data types, as
  2087.   shown below:%@NL@%
  2088. %@NL@%
  2089.   %@AB@%Keywords%@AE@%            %@AB@%Refers to%@AE@%%@NL@%
  2090.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2091.   %@AB@%BYTE PTR%@AE@% %@AI@%object%@AE@%     The byte at address of %@AI@%object%@AE@%%@NL@%
  2092. %@NL@%
  2093.   %@AB@%WORD PTR%@AE@% %@AI@%object%@AE@%     The word at address of %@AI@%object%@AE@%%@NL@%
  2094. %@NL@%
  2095.   %@AB@%DWORD PTR%@AE@% %@AI@%object%@AE@%    The doubleword at address of %@AI@%object%@AE@%%@NL@%
  2096. %@NL@%
  2097. %@NL@%
  2098. %@4@%  However, this adjustment may not produce the action you really want. The%@EH@%
  2099.   %@AB@%PTR%@AE@% operator is not quite the same as a type cast in C. The C %@AS@%(int)%@AE@% type
  2100.   cast manipulates data so that it represents the same value, but in a
  2101.   different format. %@AB@%WORD PTR%@AE@% does no data manipulation──it simply causes the
  2102.   instruction to operate on the word at the given address. In the example
  2103.   above, the use of %@AB@%WORD PTR%@AE@% causes two adjacent bytes of data to be loaded
  2104.   from memory into BX. If what you really want is to move a single byte of
  2105.   data to BX, but convert it to a word, use the following code:%@NL@%
  2106. %@NL@%
  2107.   %@AS@%            mov     bl,aByte            ; Lower byte of BX = aByte%@AE@%%@NL@%
  2108.   %@AS@%            sub     bh,bh               ; Higher byte of BX = 0%@AE@%%@NL@%
  2109. %@NL@%
  2110. %@4@%%@CR:IX2.56      @%  The example above only works properly when handling unsigned numbers. When%@EH@%
  2111.   working with signed quantities, use the %@AB@%CBW%@AE@% instruction, as described in
  2112.   Section 13.2.1%@BO:       a9772@%, "Extending Signed Values."%@NL@%
  2113. %@NL@%
  2114. %@4@%%@CR:IX2.57      @%  By far the most common use of %@AB@%WORD PTR%@AE@% is in operations on objects 32 bits%@EH@%
  2115.   or longer. An 8086 instruction can operate only on a byte or a word. You
  2116.   use %@AB@%WORD PTR%@AE@% to tell the assembler to operate on one word at a time. For
  2117.   example, the following code uses two moves to copy the 32-bit integer %@AS@%X %@AE@%to
  2118.   a similar integer, %@AS@%Y%@AE@%:%@NL@%
  2119. %@NL@%
  2120.   %@AS@%X     DD      80000               ; X is a long integer = 80,000%@AE@%%@NL@%
  2121.   %@AS@%Y     DD      ?                   ; Y is a long integer%@AE@%%@NL@%
  2122.   %@AS@%      .%@AE@%%@NL@%
  2123.   %@AS@%      .%@AE@%%@NL@%
  2124.   %@AS@%      .%@AE@%%@NL@%
  2125.   %@AS@%      mov     ax, WORD PTR X      ; Move word at X to word at Y%@AE@%%@NL@%
  2126.   %@AS@%      mov     WORD PTR Y, ax      ;   (using AX as intermediate register)%@AE@%%@NL@%
  2127.   %@AS@%      mov     ax, WORD PTR X[2]   ; Move word 2 bytes past X to%@AE@%%@NL@%
  2128.   %@AS@%      mov     WORD PTR Y[2], ax   ;   word 2 bytes past Y%@AE@%%@NL@%
  2129. %@NL@%
  2130. %@4@%%@CR:IX2.58      @%%@CR:IX2.59      @%  Brackets ([ ]) are used with arrays as well as portions of large data%@EH@%
  2131.   objects as shown here; they also let you add a displacement to an address.
  2132.   The use of brackets is further explained in the next few paragraphs.%@NL@%
  2133. %@NL@%
  2134. %@4@%%@CR:IX2.60      @%  Assembly language makes almost no distinction between simple variables and%@EH@%
  2135.   arrays. You refer to the first element of an array just as you would a
  2136.   simple variable──index brackets are optional. To declare an array or
  2137.   string, just give a series of initial values:%@NL@%
  2138. %@NL@%
  2139.   %@AS@%warray      DW      ?,?,?,?%@AE@%%@NL@%
  2140.   %@AS@%xarray      DW      1,2,3,4%@AE@%%@NL@%
  2141.   %@AS@%mystring    DB      "Hello, there."%@AE@%%@NL@%
  2142. %@NL@%
  2143. %@4@%  To refer to the first element of %@AS@%warray%@AE@%, type %@AS@%warray %@AE@%into your program (no%@EH@%
  2144.   brackets required). To refer to the next element, use either of these two
  2145.   forms, each of which refers to the object two bytes past the beginning of
  2146.   %@AS@%warray%@AE@%:%@NL@%
  2147. %@NL@%
  2148.   %@AS@%warray+2%@AE@%%@NL@%
  2149.   %@AS@%warray[2]%@AE@%%@NL@%
  2150. %@NL@%
  2151. %@4@%%@CR:IX2.61      @%%@CR:IX2.62      @%  When used with a variable name, the brackets do nothing but add a number%@EH@%
  2152.   to the address. If %@AS@%warray %@AE@%refers to the address %@AS@%2400h%@AE@%, then %@AS@%warray[2]%@AE@%
  2153.   refers to the address %@AS@%2402h%@AE@%. However, the brackets have an additional
  2154.   function when used with registers. See Section 2.6.4%@BO:       27375@%, "Indirect Memory
  2155.   Operands," for more information.%@NL@%
  2156. %@NL@%
  2157. %@4@%  In assembly language, array indexes are zero-based, as in C; but unlike C,%@EH@%
  2158.   they are unscaled. The number inside brackets always represents an
  2159.   absolute distance in bytes.%@NL@%
  2160. %@NL@%
  2161. %@4@%%@CR:IX2.63      @%  In practical terms, the fact that indexes are unscaled means that if the%@EH@%
  2162.   size of an element is larger than one byte, you must multiply the index of
  2163.   the element by its size (in this case, 2), then add the result to the
  2164.   address of the array. Thus, the expression %@AS@%warray[4] %@AE@%represents the third
  2165.   element, which is 4 bytes past the beginning of the array. Similarly, the
  2166.   expression %@AS@%warray[6] %@AE@%represents the fourth element.%@NL@%
  2167. %@NL@%
  2168. %@4@%  In general, the numeric offset required to access an array element can be%@EH@%
  2169.   calculated as shown in the following formula:%@NL@%
  2170. %@NL@%
  2171. %@4@%  %@AS@%Nth element of Array = Array[(N-1) * size of element]%@AE@%%@EH@%%@NL@%
  2172. %@NL@%
  2173. %@NL@%
  2174. %@2@%%@CR:SC2.5       @%%@AB@%2.5  8086-Family Registers%@AE@%%@EH@%%@NL@%
  2175. %@NL@%
  2176. %@4@%%@CR:IX2.64      @%%@CR:IX2.65      @%  A "register" is a special memory location inside the processor itself.%@EH@%
  2177.   Operations on registers execute faster than operations on main memory. The
  2178.   processor has a limited number of registers. Moreover, many operations on
  2179.   the 8086 are impossible without the use of registers at some point. For
  2180.   example, you cannot copy data between two memory locations without first
  2181.   moving it into a register.%@NL@%
  2182. %@NL@%
  2183. %@4@%%@CR:IX2.66      @%  Figure 2.1 shows the registers common to all the 8086-family processors.%@EH@%
  2184.   The 8086 registers can be grouped by function into the following sets:
  2185.   general-purpose registers, index registers, pointer registers, and segment
  2186.   registers. Each set corresponds to a different ending letter (X, I, P, or
  2187.   S). The registers in each set are as follows:%@NL@%
  2188. %@NL@%
  2189.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  2190.   │ This figure can be found in Section 2.5 of the manual                  │%@NL@%
  2191.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  2192. %@NL@%
  2193. %@CR:IX2.67      @%  ■  The four general-purpose registers are AX, BX, CX, and DX. These
  2194.      registers exist for the general use of the program. You can use these
  2195.      registers to store temporary values and perform calculations.%@NL@%
  2196. %@NL@%
  2197. %@CR:IX2.68      @%  ■  The two index registers are SI (Source Index) and DI (Destination
  2198.      Index). These registers can also be used for general storage, but are
  2199.      less flexible than the general-purpose registers. SI and DI have a
  2200.      special purpose in string instructions.%@NL@%
  2201. %@NL@%
  2202. %@CR:IX2.69      @%  ■  The pointer registers are IP (Instruction Pointer), SP (Stack Pointer),
  2203.      and BP (Base Pointer). These registers should not be confused with BX,
  2204.      which is the register normally used for pointer indirection. IP, SP,
  2205.      and BP each have a special purpose in conjunction with procedure calls.
  2206.      SP and BP should be altered with care; IP cannot be altered or
  2207.      referenced directly at all.%@NL@%
  2208. %@NL@%
  2209.   ■  The segment registers are CS, DS, SS, and ES. This section does not
  2210.      describe these registers. You generally don't alter or reference them
  2211.      except when starting the program or accessing data from multiple
  2212.      segments. Section 2.7%@BO:       28c1c@%, "Segmented Addressing and Segment Registers,"
  2213.      describes each segment register and how it is important to programs.%@NL@%
  2214. %@NL@%
  2215. %@4@%%@CR:IX2.70      @%  In addition, there is a flags register that indicates the status of the%@EH@%
  2216.   process.%@NL@%
  2217. %@NL@%
  2218. %@NL@%
  2219. %@3@%%@CR:SC2.5.1     @%%@AB@%2.5.1  The General-Purpose Registers%@AE@%%@EH@%%@NL@%
  2220. %@NL@%
  2221. %@4@%%@CR:IX2.71      @%%@CR:IX2.72      @%%@CR:IX2.73      @%  The general-purpose registers have many important uses in an 8086%@EH@%
  2222.   assembly-language program, including:%@NL@%
  2223. %@NL@%
  2224.   ■  Storing the values most frequently used. Operations on registers are
  2225.      much faster than operations on memory. Therefore, place the program's
  2226.      principal values in registers. In larger programs, you will probably
  2227.      have too many variables to place them all into registers. You can,
  2228.      however, place a value in a register while it is in heavy use.%@NL@%
  2229. %@NL@%
  2230.   ■  Supporting operations with two or more variables. Direct
  2231.      memory-to-memory operations are illegal with 8086 processors. To
  2232.      operate on two memory locations, you need to first load one of the
  2233.      values into a register.%@NL@%
  2234. %@NL@%
  2235.   ■  Enabling use of all the instructions. Many instructions require the use
  2236.      of a particular register. For example, the %@AB@%MUL%@AE@% instruction always works
  2237.      with the AX register (or AL, if you specify a byte operand).%@NL@%
  2238. %@NL@%
  2239.   ■  Passing or returning values in a procedure or interrupt call.%@NL@%
  2240. %@CR:IX2.74      @%%@CR:IX2.75      @%%@CR:IX2.76      @%%@CR:IX2.77      @%%@CR:IX2.78      @%%@CR:IX2.79      @%%@CR:IX2.80      @%%@CR:IX2.81      @%%@CR:IX2.82      @%%@CR:IX2.83      @%%@NL@%
  2241. %@4@%%@CR:IX2.84      @%%@CR:IX2.85      @%%@CR:IX2.86      @%%@CR:IX2.87      @%%@CR:IX2.88      @%%@CR:IX2.89      @%  Each of the general-purpose registers──AX, BX, CX, and DX──can be accessed%@EH@%
  2242.   as single 16-bit registers, or as two 8-bit registers. As shown in Figure
  2243.   2.1, the AH, BH, CH, and DH registers represent the high-order 8 bits of
  2244.   the corresponding registers. Similarly, AL, BL, CL, and DL represent the
  2245.   low-order 8 bits.%@NL@%
  2246. %@NL@%
  2247. %@4@%  This design lets you operate directly on two-byte and one-byte objects. It%@EH@%
  2248.   also lets you load a two-byte object and then manipulate one byte at a
  2249.   time.%@NL@%
  2250. %@NL@%
  2251. %@4@%  Each of the general-purpose registers has special uses, discussed below.%@EH@%%@NL@%
  2252. %@NL@%
  2253. %@NL@%
  2254. %@3@%%@CR:SC2.5.1.1   @%%@AB@%2.5.1.1  The AX Register%@AE@%%@EH@%%@NL@%
  2255. %@NL@%
  2256. %@4@%%@CR:IX2.90      @%%@CR:IX2.91      @%%@CR:IX2.92      @%%@CR:IX2.93      @%  The AX (Accumulator) register is ideal for repeated calculations. It%@EH@%
  2257.   accumulates totals as well as the results of multiplication and division.
  2258.   Using AX can add speed to your program, because some instructions have
  2259.   special encodings optimized for use with AX.%@NL@%
  2260. %@NL@%
  2261. %@4@%  Multiplication instructions always use AX. In the 16-bit version of the%@EH@%
  2262.   %@AB@%MUL%@AE@% instruction, you specify one 16-bit value. The processor multiplies
  2263.   this value by the contents of AX and stores the 16 least significant
  2264.   binary digits of the result in AX. (The 16 most significant digits are
  2265.   stored in DX.)%@NL@%
  2266. %@NL@%
  2267. %@4@%%@CR:IX2.94      @%%@CR:IX2.95      @%  The following example multiplies %@AS@%base %@AE@%times %@AS@%height%@AE@%, and stores the result%@EH@%
  2268.   in %@AS@%area%@AE@%. These instructions are sufficient if the result does not exceed
  2269.   the limit for two-byte numbers (otherwise, the DX register will contain
  2270.   the overflow):%@NL@%
  2271. %@NL@%
  2272.   %@AS@%base     DW     5       ; base is a word, initialized to 5%@AE@%%@NL@%
  2273.   %@AS@%height   DW     3       ; height is a word, initialized to 3%@AE@%%@NL@%
  2274.   %@AS@%area     DW     ?       ; area stores 16-bit (word) product%@AE@%%@NL@%
  2275.   %@AS@%         .%@AE@%%@NL@%
  2276.   %@AS@%         .%@AE@%%@NL@%
  2277.   %@AS@%         .%@AE@%%@NL@%
  2278.   %@AS@%         mov    ax,base ; AX = base%@AE@%%@NL@%
  2279.   %@AS@%         mul    height  ; AX = AX * height%@AE@%%@NL@%
  2280.   %@AS@%         mov    area,ax ; area = result%@AE@%%@NL@%
  2281. %@NL@%
  2282. %@4@%  AX has a similar use in division instructions (%@AB@%DIV%@AE@% and %@AB@%IDIV%@AE@%). See Section%@EH@%
  2283.   14.4%@BO:       b3ae1@%, "Dividing," for examples of division. Also, in port I/O
  2284.   instructions, AX holds the data to write to a port and receives data read
  2285.   from a port.%@NL@%
  2286. %@NL@%
  2287. %@4@%  By convention, AX has another special use. Microsoft high-level languages%@EH@%
  2288.   expect AX to contain a function's return value. If the return value is
  2289.   longer than four bytes, the high-level languages expect DX:AX to point to
  2290.   the location of the return value.%@NL@%
  2291. %@NL@%
  2292. %@NL@%
  2293. %@3@%%@CR:SC2.5.1.2   @%%@AB@%2.5.1.2  The BX Register%@AE@%%@EH@%%@NL@%
  2294. %@NL@%
  2295. %@4@%%@CR:IX2.96      @%%@CR:IX2.97      @%%@CR:IX2.98      @%%@CR:IX2.99      @%%@CR:IX2.100     @%  The BX (Base) register has great importance as a pointer or address%@EH@%
  2296.   register. All 16-bit registers can hold addresses, but not all registers
  2297.   can be used to retrieve the contents of an address. In C this operation is
  2298.   called "pointer dereferencing," or "indirection." The C source code to
  2299.   implement this action might look like this:%@NL@%
  2300. %@NL@%
  2301.   %@AS@%value = *pVar;%@AE@%%@NL@%
  2302. %@NL@%
  2303. %@4@%  The following assembly code achieves the same effect:%@EH@%%@NL@%
  2304. %@NL@%
  2305.   %@AS@%            mov     bx,pVar      ; BX = pVar%@AE@%%@NL@%
  2306.   %@AS@%            mov     value,[bx]   ; value = object pointed to by BX%@AE@%%@NL@%
  2307. %@NL@%
  2308. %@4@%  The brackets around BX in the second instruction direct QuickAssembler to%@EH@%
  2309.   consider BX a pointer to the actual operand. The item %@AS@%[bx] %@AE@%is an example
  2310.   of an indirect memory operand. See Section 2.6.4%@BO:       27375@%, "Indirect Memory
  2311.   Operands," for more information.%@NL@%
  2312. %@NL@%
  2313. %@NL@%
  2314. %@3@%%@CR:SC2.5.1.3   @%%@AB@%2.5.1.3  The CX Register%@AE@%%@EH@%%@NL@%
  2315. %@NL@%
  2316. %@4@%%@CR:IX2.101     @%%@CR:IX2.102     @%%@CR:IX2.103     @%  The CX (Count) register has special meaning to instructions with a%@EH@%
  2317.   repeat-operation feature. The contents of CX indicate how many times to
  2318.   repeat execution. Loops, string operations, certain jump instructions, and
  2319.   shifts and rotates all use CX this way.%@NL@%
  2320. %@NL@%
  2321. %@4@%%@CR:IX2.104     @%%@CR:IX2.105     @%%@CR:IX2.106     @%  A common instruction that uses CX to repeat execution is %@AB@%LOOP%@AE@%, which is%@EH@%
  2322.   analogous to the C %@AB@%for%@AE@% statement. This instruction subtracts one from CX,
  2323.   then jumps to the given label if CX is not equal to 0. Thus, the following
  2324.   loop executes 20 times:%@NL@%
  2325. %@NL@%
  2326.   %@AS@%            mov     cx,20%@AE@%%@NL@%
  2327.   %@AS@%top:%@AE@%%@NL@%
  2328.   %@AS@%            .%@AE@%%@NL@%
  2329.   %@AS@%            .%@AE@%%@NL@%
  2330.   %@AS@%            .%@AE@%%@NL@%
  2331.   %@AS@%            loop    top%@AE@%%@NL@%
  2332. %@NL@%
  2333. %@4@%  In the case of shifts and rotates, CL (the lower byte of CX) indicates how%@EH@%
  2334.   many bit positions to shift. See Section 14.7%@BO:       ba3f6@%, "Shifting and Rotating
  2335.   Bits," for more information. Also, when an instruction has a %@AB@%REP%@AE@% (repeat)
  2336.   prefix, the value in CX determines how many times the instruction is
  2337.   executed.%@NL@%
  2338. %@NL@%
  2339. %@NL@%
  2340. %@3@%%@CR:SC2.5.1.4   @%%@AB@%2.5.1.4  The DX Register%@AE@%%@EH@%%@NL@%
  2341. %@NL@%
  2342. %@4@%%@CR:IX2.107     @%%@CR:IX2.108     @%  The DX (Data) register often is used only for storage of temporary values.%@EH@%
  2343.   However, DX has a special function in some versions of the multiplication,
  2344.   division, and port instructions. Each of these uses is closely related to
  2345.   AX. In fact, DX is located next to AX in the actual physical layout of the
  2346.   8086 chip. (Figure 2.1 places the registers in the order AX, BX, CX, and
  2347.   DX merely for ease of reference.)%@NL@%
  2348. %@NL@%
  2349. %@4@%%@CR:IX2.109     @%%@CR:IX2.110     @%  When you multiply 16-bit values with %@AB@%MUL%@AE@%, DX holds the high 16 bits of the%@EH@%
  2350.   32-bit result. The following example is a variation of the one given for
  2351.   AX. In this example, %@AS@%Area %@AE@%is a 32-bit value (a long integer), and it
  2352.   stores the entire 32-bit result of the %@AB@%MUL%@AE@% instruction:%@NL@%
  2353. %@NL@%
  2354.   %@AS@%base        DW     500                 ; base is a word, initialized to 500%@AE@%%@NL@%
  2355.   %@AS@%height      DW     300                 ; height is a word, initialized to 300%@AE@%%@NL@%
  2356.   %@AS@%area        DD     ?                   ; area stores doubleword product%@AE@%%@NL@%
  2357.   %@AS@%            .%@AE@%%@NL@%
  2358.   %@AS@%            .%@AE@%%@NL@%
  2359.   %@AS@%            .%@AE@%%@NL@%
  2360.   %@AS@%            mov    ax,base             ; AX = base%@AE@%%@NL@%
  2361.   %@AS@%            mul    height              ; DX:AX = AX * height%@AE@%%@NL@%
  2362.   %@AS@%            mov    WORD PTR area[0],ax ; Store low 16 bits%@AE@%%@NL@%
  2363.   %@AS@%            mov    WORD PTR area[2],dx ; Store high 16 bits%@AE@%%@NL@%
  2364. %@NL@%
  2365. %@4@%  By convention, Microsoft high-level languages use both DX and AX to return%@EH@%
  2366.   four-byte values from procedures. The high 16 bits are placed in DX.%@NL@%
  2367. %@NL@%
  2368. %@NL@%
  2369. %@3@%%@CR:SC2.5.2     @%%@AB@%2.5.2  The Index Registers%@AE@%%@EH@%%@NL@%
  2370. %@NL@%
  2371. %@4@%%@CR:IX2.111     @%%@CR:IX2.112     @%%@CR:IX2.113     @%%@CR:IX2.114     @%%@CR:IX2.115     @%%@CR:IX2.116     @%  The two index registers are SI (Source Index) and DI (Destination Index).%@EH@%
  2372.   These registers are similar to the general-purpose registers, but cannot
  2373.   be accessed one byte at a time. Index registers are efficient places to
  2374.   store general data, pointers, array indexes, and pointers to blocks of
  2375.   memory. They have the following special uses:%@NL@%
  2376. %@NL@%
  2377.   ■  You can use both SI and DI for pointer indirection, as you can BX and
  2378.      BP. "Pointer indirection" is the process of retrieving the value that a
  2379.      pointer points to.%@NL@%
  2380. %@NL@%
  2381.   ■  You can use SI or DI to hold an array index. Indirect memory operands
  2382.      can combine this index with a base address stored in BX or BP.%@NL@%
  2383. %@NL@%
  2384.   ■  You prepare for string instructions, which execute highly efficient
  2385.      block operations, by loading SI with a source address and DI with a
  2386.      destination address.%@NL@%
  2387. %@NL@%
  2388. %@4@%  See Chapter 16%@BO:       d1833@%, "Processing Strings," for information on how to use%@EH@%
  2389.   string instructions.%@NL@%
  2390. %@NL@%
  2391. %@4@%%@CR:IX2.117     @%%@CR:IX2.118     @%%@CR:IX2.119     @%  When you write a procedure to be called by C, be careful to leave SI and%@EH@%
  2392.   DI in the same state they were in before C called your procedure.
  2393.   Microsoft QuickC allocates register variables in SI and DI.%@NL@%
  2394. %@NL@%
  2395. %@NL@%
  2396. %@3@%%@CR:SC2.5.3     @%%@AB@%2.5.3  The Pointer Registers%@AE@%%@EH@%%@NL@%
  2397. %@NL@%
  2398. %@4@%%@CR:IX2.120     @%%@CR:IX2.121     @%  The pointer registers──BP, SP, and IP──are all special-purpose registers%@EH@%
  2399.   that help implement procedure calls. The processor alters SP (Stack
  2400.   Pointer) and IP (Instruction Pointer) whenever you call a procedure, and
  2401.   you can use BP (Base Pointer) to access parameters placed on the stack.%@NL@%
  2402. %@NL@%
  2403. %@4@%  Despite their names, pointer registers are not good places to store%@EH@%
  2404.   pointer variables or other general program data; you should generally use
  2405.   BX, SI, and DI for that purpose.%@NL@%
  2406. %@NL@%
  2407. %@NL@%
  2408. %@3@%%@CR:SC2.5.3.1   @%%@AB@%2.5.3.1  The BP Register%@AE@%%@EH@%%@NL@%
  2409. %@NL@%
  2410. %@4@%%@CR:IX2.122     @%%@CR:IX2.123     @%  You can use BP (Base Pointer) to retrieve the contents pointed to by an%@EH@%
  2411.   address. However, by default, the BP register points into the stack
  2412.   segment rather than the data segment. Therefore, BP is typically used to
  2413.   access items on the stack.%@NL@%
  2414. %@NL@%
  2415. %@4@%  The "stack" is the area of memory that holds parameters, local variables,%@EH@%
  2416.   and return addresses for each procedure being executed. Although you can
  2417.   store general data in BP, it is commonly used to access parameters of the
  2418.   current procedure.%@NL@%
  2419. %@NL@%
  2420. %@4@%  When you use the %@AB@%PROC%@AE@% statement with a parameter list as explained in the%@EH@%
  2421.   next chapter, avoid altering the value of BP. The %@AB@%PROC%@AE@% directive generates
  2422.   instructions that set BP to point to the procedure's local stack area, and
  2423.   then use BP to access parameters and local data. If BP changes, all your
  2424.   references to parameters will be wrong.%@NL@%
  2425. %@NL@%
  2426. %@4@%  To learn how to set BP yourself, see Section 15.3.3%@BO:       c60b0@%, "Passing Arguments%@EH@%
  2427.   on the Stack," or Appendix A%@BO:       ed697@%, "Mixed-Language Mechanics."%@NL@%
  2428. %@NL@%
  2429. %@NL@%
  2430. %@3@%%@CR:SC2.5.3.2   @%%@AB@%2.5.3.2  The SP Register%@AE@%%@EH@%%@NL@%
  2431. %@NL@%
  2432. %@4@%%@CR:IX2.124     @%%@CR:IX2.125     @%  The SP (Stack Pointer) register points to the current location within the%@EH@%
  2433.   stack segment. As you add or remove items from the stack, the processor
  2434.   changes the value of SP, so that SP always points to the top of the stack.
  2435. %@NL@%
  2436. %@4@%  The processor stack works like a stack of dishes: you push items onto the%@EH@%
  2437.   top of the stack as you need to save them, then pop them off the stack
  2438.   when you're ready to use them again. The stack is a last-in-first-out
  2439.   mechanism. You can only remove the item currently at the top of the stack.
  2440.   Items must be removed in the reverse order they were placed there.%@NL@%
  2441. %@NL@%
  2442. %@4@%  The processor automatically pushes and pops return addresses for you when%@EH@%
  2443.   you call or return from a procedure. A "return address" is the place a
  2444.   procedure or routine returns to when done. You can also place other values
  2445.   on the stack by using the %@AB@%PUSH%@AE@% and %@AB@%POP%@AE@% instructions.%@NL@%
  2446. %@NL@%
  2447. %@4@%  The %@AB@%PUSH%@AE@% instruction saves the value of a register or memory location by%@EH@%
  2448.   placing it on the stack. %@AB@%POP%@AE@% removes the value from the stack and places
  2449.   it back in the original location. (You can also pop the contents into some
  2450.   other location if you wish.) Use these instructions when you need to
  2451.   preserve a value. In the following example, BX holds an important value,
  2452.   but the program needs temporary use of BX:%@NL@%
  2453. %@NL@%
  2454.   %@AS@%            push    bx             ; Save BX on the stack%@AE@%%@NL@%
  2455.   %@AS@%            mov     bx,pointer     ; Load pointer into BX%@AE@%%@NL@%
  2456.   %@AS@%            mov     value,[bx]     ; value = *pointer%@AE@%%@NL@%
  2457.   %@AS@%            pop     bx             ; Pop old value back into BX%@AE@%%@NL@%
  2458. %@NL@%
  2459. %@4@%  The stack also holds parameters and local variables during procedure%@EH@%
  2460.   calls. Sections 13.4.2%@BO:       ac5c7@%, "Using the Stack," and 15.3.3%@BO:       ac5c8@%, "Passing
  2461.   Arguments on the Stack," provide more information on using the stack.
  2462.   Appendix A%@BO:       ed697@%, "Mixed-Language Mechanics," explains how to manipulate the
  2463.   stack to make room for local variables──one of the few times you should
  2464.   change the value of SP directly.%@NL@%
  2465. %@NL@%
  2466. %@NL@%
  2467. %@3@%%@CR:SC2.5.3.3   @%%@AB@%2.5.3.3  The IP Register%@AE@%%@EH@%%@NL@%
  2468. %@NL@%
  2469. %@4@%  You cannot adjust the IP (Instruction Pointer) register directly; it can%@EH@%
  2470.   only be adjusted indirectly, through control-flow instructions. For this
  2471.   reason, Quick-Assembler does not even recognize IP as a keyword.%@NL@%
  2472. %@NL@%
  2473. %@4@%%@CR:IX2.126     @%%@CR:IX2.127     @%%@CR:IX2.128     @%  The IP register contains the address of the next instruction to execute.%@EH@%
  2474.   The instructions that control program flow (calls, jumps, loops, and
  2475.   interrupts) automatically set the instruction pointer to the proper value.
  2476.   The processor pushes the address of the next instruction onto the stack
  2477.   when you call a procedure. The processor pops this instruction into IP
  2478.   when the procedure returns. Normally, the processor increments IP to point
  2479.   to the next instruction in memory.%@NL@%
  2480. %@NL@%
  2481. %@NL@%
  2482. %@3@%%@CR:SC2.5.4     @%%@AB@%2.5.4  The Flags Register%@AE@%%@EH@%%@NL@%
  2483. %@NL@%
  2484. %@4@%%@CR:IX2.129     @%%@CR:IX2.130     @%%@CR:IX2.131     @%%@CR:IX2.132     @%  The flags register, shown in Figure 2.2, is a 16-bit register made up of%@EH@%
  2485.   bits that each indicate some specific condition. Most of the flags help
  2486.   determine the behavior of conditional jump instructions. Many
  2487.   instructions──most notably %@AB@%CMP%@AE@%──set these flags in a meaningful way. Other
  2488.   flags (Trap, Interrupt Enable, and Direction) do not affect conditional
  2489.   jump instructions but control the processor's general operation.%@NL@%
  2490. %@NL@%
  2491.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  2492.   │ This figure can be found in Section 2.5.4 of the manual                │%@NL@%
  2493.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  2494. %@NL@%
  2495. %@4@%  The nine flags common to all 8086-family processors are summarized below,%@EH@%
  2496.   progressing from the low-order to high-order flags. In these descriptions,
  2497.   the term "set" means the bit value is 1, and "cleared" means the bit value
  2498.   is 0.%@NL@%
  2499. %@NL@%
  2500. %@4@%  Instructions actively set and clear various flags. For example, if the%@EH@%
  2501.   result of a %@AB@%SUB%@AE@% or %@AB@%CMP%@AE@% instruction is zero, it sets the Zero flag. This
  2502.   flag setting can, in turn, affect subsequent instructions──in particular,
  2503.   conditional jumps. Some instructions do not set the flags at all, or have
  2504.   random effects on some flags. Consult on-line Help for each instruction to
  2505.   see precisely how it affects flag settings.%@NL@%
  2506. %@NL@%
  2507.   %@AB@%Flag%@AE@%                %@AB@%Description%@AE@%%@NL@%
  2508.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2509. %@CR:IX2.133     @%  Carry               Is set if an operation generates a carry to or a
  2510.                       borrow from a destination operand. (Operation viewed
  2511.                       as unsigned.)%@NL@%
  2512. %@NL@%
  2513. %@CR:IX2.134     @%  Parity              Is set if the low-order bits of the result of an
  2514.                       operation contain an even number of set bits.%@NL@%
  2515. %@NL@%
  2516. %@CR:IX2.135     @%  Auxiliary Carry     Is set if an operation generates a carry to or a
  2517.                       borrow from the low-order four bits of an operand.
  2518.                       This flag is used for binary coded decimal arithmetic.
  2519. %@NL@%
  2520. %@CR:IX2.136     @%  Zero                Is set if the result of an operation is 0.%@NL@%
  2521. %@NL@%
  2522. %@CR:IX2.137     @%  Sign                Equal to the high-order bit of the result of an
  2523.                       operation (0 is positive, 1 is negative).%@NL@%
  2524. %@NL@%
  2525. %@CR:IX2.138     @%  Trap                If set, the processor generates a single-step
  2526.                       interrupt after each instruction. Debugging programs,
  2527.                       including the QuickC/QuickAssembler debugging
  2528.                       facility, use this feature to execute a program one
  2529.                       instruction at a time.%@NL@%
  2530. %@NL@%
  2531. %@CR:IX2.139     @%  Interrupt Enable    If set, interrupts will be recognized and acted on as
  2532.                       they are received. The bit can be cleared to
  2533.                       temporarily turn off interrupt processing.%@NL@%
  2534. %@NL@%
  2535. %@CR:IX2.140     @%  Direction           Can be set to make string operations process down from
  2536.                       high addresses to low addresses, or can be cleared to
  2537.                       make string operations process up from low addresses
  2538.                       to high addresses.%@NL@%
  2539. %@NL@%
  2540. %@CR:IX2.141     @%  Overflow            Is set if the result of an operation is too large or
  2541.                       small to fit in the destination operand. (Operation
  2542.                       viewed as signed.)%@NL@%
  2543. %@NL@%
  2544. %@NL@%
  2545. %@4@%%@CR:IX2.142     @%%@CR:IX2.143     @%  The Carry and Overflow flags are similar, but have one major difference:%@EH@%
  2546.   the Carry flag is set according to the rules of unsigned operations, and
  2547.   the Overflow flag is set according to the rules of signed operations. A
  2548.   signed operation uses two's complement arithmetic to represent negative
  2549.   numbers. One of the features of this system is that a number is negative
  2550.   if the most significant bit is set. Unsigned operations do not view any
  2551.   number as negative.%@NL@%
  2552. %@NL@%
  2553. %@4@%  Thus, the same %@AB@%ADD%@AE@% operation can be viewed as adding FFFFH to FFFEH%@EH@%
  2554.   (unsigned) or -1 to -2 (signed). This operation would set the Carry flag
  2555.   (because the maximum unsigned value is FFFFH), but not the Overflow flag.%@NL@%
  2556. %@NL@%
  2557.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2558.   %@AB@%NOTE%@AE@%  This manual does not describe the details of two's-complement
  2559.   arithmetic. For more information, see one of the references listed in the
  2560.   Introduction.%@NL@%
  2561.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2562. %@NL@%
  2563. %@4@%  Each of the conditional jump instructions responds to a particular flag or%@EH@%
  2564.   combination of flags. For example, the %@AB@%JZ %@AE@%(Jump If Zero) instruction jumps
  2565.   if the Zero flag is set. The %@AB@%JBE%@AE@% (Jump If Below or Equal) jumps if either
  2566.   the Zero flag or the Carry flag is set. For a description of all the
  2567.   conditional jump instructions, see Section 15.1.2%@BO:       be4fa@%, "Jumping
  2568.   Conditionally."%@NL@%
  2569. %@NL@%
  2570. %@NL@%
  2571. %@2@%%@CR:SC2.6       @%%@AB@%2.6  Addressing Modes%@AE@%%@EH@%%@NL@%
  2572. %@NL@%
  2573. %@4@%%@CR:IX2.144     @%  You can specify several kinds of operands: immediate, register, direct%@EH@%
  2574.   memory, and indirect memory. Each type of operand corresponds to a
  2575.   different addressing mode. The "addressing mode" is the method that the
  2576.   processor uses to calculate the actual value of the operand at run time.%@NL@%
  2577. %@NL@%
  2578. %@4@%  You don't specify addressing modes explicitly. You simply give an operand,%@EH@%
  2579.   and the assembler determines the corresponding addressing mode.%@NL@%
  2580. %@NL@%
  2581. %@4@%%@CR:IX2.145     @%%@CR:IX2.146     @%  The four types of operands are summarized below, and described at length%@EH@%
  2582.   in the rest of this section.%@NL@%
  2583. %@NL@%
  2584.   %@AB@%Operand Type%@AE@%        %@AB@%Description%@AE@%%@NL@%
  2585.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2586.   Immediate           A constant value contained in the instruction itself%@NL@%
  2587. %@NL@%
  2588.   Register            A 16-bit or 8-bit register%@NL@%
  2589. %@NL@%
  2590.   Direct memory       A fixed location in memory%@NL@%
  2591. %@NL@%
  2592.   Indirect memory     A memory location determined at run time by using the
  2593.                       address stored in one or two registers%@NL@%
  2594. %@NL@%
  2595. %@NL@%
  2596. %@4@%%@CR:IX2.147     @%%@CR:IX2.148     @%  Direct memory and indirect memory operands are closely related. Syntax%@EH@%
  2597.   displays in this manual, as well as in on-line Help, often refer to %@AI@%memory%@AE@%
  2598.   operands. You can use either type of memory operand wherever %@AI@%memory%@AE@% is
  2599.   specified. From the processor's viewpoint, the only difference between
  2600.   these types of operands is how the address is determined. The address
  2601.   specified in the memory operand is called the "effective address" of the
  2602.   instruction.%@NL@%
  2603. %@NL@%
  2604. %@4@%  Most two-operand instructions require operands of the same size. When one%@EH@%
  2605.   of the operands is a register, QuickAssembler adjusts the size of the
  2606.   other, if possible, to be the size of the register──either 8 or 16 bits.
  2607.   An instruction that operates on AX and BL is illegal, since these
  2608.   registers are different sizes.%@NL@%
  2609. %@NL@%
  2610. %@4@%  If the sizes conflict, you can sometimes use the %@AB@%PTR%@AE@% operator to override%@EH@%
  2611.   the size attribute of an operand.%@NL@%
  2612. %@NL@%
  2613. %@4@%%@CR:IX2.149     @%%@CR:IX2.150     @%%@CR:IX2.151     @%%@CR:IX2.152     @%%@CR:IX2.153     @%%@CR:IX2.154     @%  Sections 2.6.1-2.6.4 discuss each of the four operand types (and%@EH@%
  2614.   corresponding addressing modes) in detail.%@NL@%
  2615. %@NL@%
  2616. %@NL@%
  2617. %@3@%%@CR:SC2.6.1     @%%@AB@%2.6.1  Immediate Operands%@AE@%%@EH@%%@NL@%
  2618. %@NL@%
  2619. %@4@%%@CR:IX2.155     @%%@CR:IX2.156     @%%@CR:IX2.157     @%  An "immediate operand" is a constant value on which the instruction%@EH@%
  2620.   operates directly. This is the only addressing mode that involves no
  2621.   further access of registers or memory. The data follows the instruction
  2622.   right inside the executable code, thus giving rise to the name
  2623.   "immediate."%@NL@%
  2624. %@NL@%
  2625. %@4@%  Use immediate operands for the same reasons you would use a literal or%@EH@%
  2626.   symbolic constant in C. The value of an immediate operand never changes.%@NL@%
  2627. %@NL@%
  2628. %@4@%  An immediate operand can be a symbolic constant declared with the %@AB@%EQU%@AE@%%@EH@%
  2629.   operand. This operand is often used for the same purpose as the C%@AB@% #define%@AE@%
  2630.   directive. For example, consider the constant declaration:%@NL@%
  2631. %@NL@%
  2632.   %@AS@%magic       EQU     7243%@AE@%%@NL@%
  2633. %@NL@%
  2634. %@4@%  You could use this the same way as the C statement:%@EH@%%@NL@%
  2635. %@NL@%
  2636.   %@AS@%#define magic  7243%@AE@%%@NL@%
  2637. %@NL@%
  2638. %@4@%  Chapter 11%@BO:       8d6e4@%, "Using Equates, Macros, and Repeat Blocks," tells more about%@EH@%
  2639.   defining constants with the%@AB@% EQU%@AE@% or %@AB@%=%@AE@% operator.%@NL@%
  2640. %@NL@%
  2641. %@4@%  An immediate operand can also be an expression made up of constants. For%@EH@%
  2642.   example, the following code directs QuickAssembler to calculate the
  2643.   difference between two ASCII values, then use this difference as the
  2644.   source (rightmost) operand:%@NL@%
  2645. %@NL@%
  2646.   %@AS@%            mov     bigdiff,'a'-'A'%@AE@%%@NL@%
  2647. %@NL@%
  2648. %@4@%  The assembler interprets the one-byte strings %@AS@%'a' %@AE@%and %@AS@%'A' %@AE@%as the ASCII%@EH@%
  2649.   values 97 and 65. The assembler calculates the difference──in this case,
  2650.   32──and places the resulting value into the object code. At run time, this
  2651.   value is fixed. Each time the instruction is executed, the processor moves
  2652.   the value 32 into the memory location %@AS@%bigdiff%@AE@%. This instruction is
  2653.   precisely equivalent to, but more readable than, the following:%@NL@%
  2654. %@NL@%
  2655.   %@AS@%            mov     bigdiff,32%@AE@%%@NL@%
  2656. %@NL@%
  2657. %@4@%  One-byte and two-byte strings can be immediate operands. Larger strings%@EH@%
  2658.   cannot be processed by a single 8086 instruction. Chapter 3%@BO:       2aca0@%, "Writing
  2659.   Assembly Modules for C Programs," explains how to process longer strings,
  2660.   one character at a time.%@NL@%
  2661. %@NL@%
  2662. %@4@%  The %@AB@%OFFSET%@AE@% and %@AB@%SEG%@AE@% operators turn variable names (which normally are%@EH@%
  2663.   memory operands) into immediate operands. These operators are similar to
  2664.   the address operator (%@AB@%&%@AE@%) in C. In Chapter 4%@BO:       34dba@%, "Writing Stand-Alone
  2665.   Assembly Programs," you'll see how to use the %@AB@%OFFSET%@AE@% operator to treat an
  2666.   address as immediate data.%@NL@%
  2667. %@NL@%
  2668. %@4@%  When an instruction has two operands, you cannot place immediate data in%@EH@%
  2669.   the destination (leftmost) operand. (The %@AB@%OUT%@AE@% instruction is the one
  2670.   exception.)%@NL@%
  2671. %@NL@%
  2672. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  2673. %@NL@%
  2674.   %@AS@%var         DW        ?%@AE@%%@NL@%
  2675.   %@AS@%college     DW        1636%@AE@%%@NL@%
  2676.   %@AS@%nine        EQU       5+4           ; Declare nine as symbolic constant%@AE@%%@NL@%
  2677.   %@AS@%            .%@AE@%%@NL@%
  2678.   %@AS@%            .%@AE@%%@NL@%
  2679.   %@AS@%            .%@AE@%%@NL@%
  2680.   %@AS@%            mov       var,nine      ; Move immediate data to memory%@AE@%%@NL@%
  2681.   %@AS@%            mov       bx,'ab'       ; Move ASCII values for 'a' and 'b'%@AE@%%@NL@%
  2682.   %@AS@%                                    ;   into BH and BL%@AE@%%@NL@%
  2683.   %@AS@%            mov       college,1701  ; Move immediate data to memory%@AE@%%@NL@%
  2684.   %@AS@%            mov       ax,1+2+3+4    ; Move immediate data to AX%@AE@%%@NL@%
  2685.   %@AS@%            mov       ax,OFFSET var ; Move address of var to AX%@AE@%%@NL@%
  2686.   %@AS@%            int       21h           ; Immediate data is single operand%@AE@%%@NL@%
  2687.   %@AS@%                                    ;   21 hexadecimal (33 decimal)%@AE@%%@NL@%
  2688. %@NL@%
  2689. %@NL@%
  2690. %@3@%%@CR:SC2.6.2     @%%@AB@%2.6.2  Register Operands%@AE@%%@EH@%%@NL@%
  2691. %@NL@%
  2692. %@4@%%@CR:IX2.158     @%%@CR:IX2.159     @%%@CR:IX2.160     @%  A register operand consists of one of the 20 register names. The processor%@EH@%
  2693.   operates directly on the data stored in the register. "Register-direct"
  2694.   mode refers to the direct use of the value of the register rather than a
  2695.   memory location. Registers can also be used indirectly, to point to memory
  2696.   locations as described in Section 2.6.4%@BO:       27375@%, "Indirect Memory Operands."%@NL@%
  2697. %@NL@%
  2698. %@4@%  Most instructions can take one or more register operands. You generally%@EH@%
  2699.   can use any of the general-purpose registers with these instructions,
  2700.   although some instructions require specific registers. The use of segment
  2701.   registers (CS, DS, SS, and ES) is restricted. You can refer to segment
  2702.   registers only under special circumstances.%@NL@%
  2703. %@NL@%
  2704.   %@4@%Table 2.1 shows all the valid register names for 8086 processors. You can%@EH@%
  2705.   use any of these names as a register-direct operand.%@NL@%
  2706. %@NL@%
  2707.   %@AB@%Table 2.1 Register Operands%@AE@%%@NL@%
  2708. %@NL@%
  2709.   %@AB@%Register Type%@AE@%         %@AB@%Register%@AE@%
  2710.                         %@AB@%Name%@AE@%%@NL@%
  2711.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2712.   8-bit high registers  AH          BH          CH          DH%@NL@%
  2713. %@NL@%
  2714.   8-bit low registers   AL          BL          CL          DL%@NL@%
  2715. %@NL@%
  2716.   16-bit general        AX          BX          CX          DX
  2717.   purpose%@NL@%
  2718.   16-bit pointer and    SP          BP          SI          DI
  2719.   index%@NL@%
  2720.   16-bit segment        CS          DS          SS          ES%@NL@%
  2721. %@NL@%
  2722.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2723. %@NL@%
  2724. %@NL@%
  2725. %@4@%  Section 2.5%@BO:       1e475@%, "8086-Family Registers," discusses registers in more detail.%@EH@%
  2726.   Limitations on register use for specific instructions are discussed in
  2727.   sections on the specific instructions throughout Part 3%@BO:       a6c61@%, "Using
  2728.   Instructions."%@NL@%
  2729. %@NL@%
  2730. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  2731. %@NL@%
  2732.   %@AS@%       mov         ds,ax         ; Both operands are register direct%@AE@%%@NL@%
  2733.   %@AS@%       mov         stuff,dx      ; Source operand is register direct%@AE@%%@NL@%
  2734.   %@AS@%       mov         ax,1          ; Destination is register direct%@AE@%%@NL@%
  2735.   %@AS@%       mul         bx            ; Single operand, register direct%@AE@%%@NL@%
  2736. %@NL@%
  2737. %@NL@%
  2738. %@3@%%@CR:SC2.6.3     @%%@AB@%2.6.3  Direct Memory Operands%@AE@%%@EH@%%@NL@%
  2739. %@NL@%
  2740. %@4@%%@CR:IX2.161     @%%@CR:IX2.162     @%%@CR:IX2.163     @%%@CR:IX2.164     @%  A direct memory operand specifies a fixed address in main memory%@EH@%
  2741.   containing the data to operate on. At the machine level, a direct memory
  2742.   operand is a numeric address. In your QuickAssembler source code, you
  2743.   usually represent a direct memory operand by entering a symbolic name
  2744.   previously declared with a data directive such as %@AB@%DB%@AE@% (Declare Bytes).%@NL@%
  2745. %@NL@%
  2746. %@4@%%@CR:IX2.165     @%  A direct memory operand is similar to a simple variable in C or an array%@EH@%
  2747.   element with a constant index. Any object in memory can be a direct memory
  2748.   operand as long as the exact location is fixed in the executable code. The
  2749.   data at the location can change, but the location itself is the same each
  2750.   time the processor executes the instruction. This fact gives direct memory
  2751.   operands a static character. For more dynamic operations, use indirect
  2752.   memory operands.%@NL@%
  2753. %@NL@%
  2754. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  2755. %@NL@%
  2756.   %@AS@%            mov     ax,count    ; Source operand is direct memory%@AE@%%@NL@%
  2757.   %@AS@%            mov     count,ax    ; Destination operand is direct memory%@AE@%%@NL@%
  2758.   %@AS@%            inc     total       ; Single operand is direct memory%@AE@%%@NL@%
  2759. %@NL@%
  2760. %@4@%  Typically, a direct memory operand is a simple label. As with immediate%@EH@%
  2761.   operands, you can specify a direct memory operand by entering an
  2762.   expression. As long as the address can be determined at assembly time, the
  2763.   operand is direct memory.%@NL@%
  2764. %@NL@%
  2765.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2766.   %@AB@%NOTE%@AE@%  Technically, a program address is not determined until link time (in
  2767.   the case of near addresses) or load time (in the case of segment
  2768.   addresses). These adjustments are necessary to support multiple modules
  2769.   and to enable the program to run anywhere in memory. However, you can
  2770.   ignore these details. If the assembler can determine the operand's address
  2771.   relative to the rest of the module, the operand is direct memory.%@NL@%
  2772.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2773. %@NL@%
  2774. %@4@%  The following example uses an expression that translates to a direct%@EH@%
  2775.   memory operand. This example could be used to load the value of DX into
  2776.   the third element of an array of bytes. QuickAssembler considers %@AS@%area[2]%@AE@%
  2777.   as equivalent to %@AS@%area+2%@AE@%.%@NL@%
  2778. %@NL@%
  2779.   %@AS@%            mov   area[2],dx   ; Move DX to memory location 2 bytes%@AE@%%@NL@%
  2780.   %@AS@%                               ;   past the address of "area"%@AE@%%@NL@%
  2781. %@NL@%
  2782. %@4@%%@CR:IX2.166     @%%@CR:IX2.167     @%  In the statement above, the assembler calculates an address by adding %@AS@%2 %@AE@%to%@EH@%
  2783.   the address of %@AS@%area%@AE@%. The resulting address will be the same no matter what
  2784.   values are stored in registers. At run time, the address is fixed. Thus,
  2785.   the operand is direct memory.%@NL@%
  2786. %@NL@%
  2787. %@4@%%@CR:IX2.168     @%  You can use a numeric constant as a direct memory operand. Normally,%@EH@%
  2788.   Quick-Assembler interprets a numeric constant as an immediate operand. To
  2789.   ensure interpretation as a memory operand, prefix the number with a
  2790.   segment register and colon (%@AB@%:%@AE@%). Brackets are optional. The following
  2791.   instructions each load AX with the contents of memory address 100
  2792.   hexadecimal in the data segment:%@NL@%
  2793. %@NL@%
  2794.   %@AS@%            mov     ax,ds:[100h]%@AE@%%@NL@%
  2795.   %@AS@%            mov     ax,ds:100h%@AE@%%@NL@%
  2796. %@NL@%
  2797. %@4@%  Section 2.7%@BO:       28c1c@%, "Segmented Addressing and Segment Registers," provides more%@EH@%
  2798.   information on segment registers and the use of the colon (%@AB@%:%@AE@%). By default,
  2799.   the processor assumes that data references lie in the segment pointed to
  2800.   by DS.%@NL@%
  2801. %@NL@%
  2802. %@NL@%
  2803. %@3@%%@CR:SC2.6.4     @%%@AB@%2.6.4  Indirect Memory Operands%@AE@%%@EH@%%@NL@%
  2804. %@CR:IX2.169     @%%@CR:IX2.170     @%%@CR:IX2.171     @%%@CR:IX2.172     @%%@CR:IX2.173     @%%@CR:IX2.174     @%%@CR:IX2.175     @%%@NL@%
  2805. %@4@%%@CR:IX2.176     @%%@CR:IX2.177     @%%@CR:IX2.178     @%%@CR:IX2.179     @%%@CR:IX2.180     @%  With indirect memory operands, the processor calculates the address of the%@EH@%
  2806.   data at execution time, by referring to the contents of one or two
  2807.   registers. Since values in the registers can change at run time, indirect
  2808.   memory operands provide the most dynamic method for accessing data.%@NL@%
  2809. %@NL@%
  2810. %@4@%  Indirect memory operands make possible run-time operations such as pointer%@EH@%
  2811.   indirection, dynamic indexing of array elements──including indexing of
  2812.   multi-dimensional arrays──and dynamic accessing of members of a structure.
  2813.   All these operations are similar to operations in high-level languages.
  2814.   The major difference is that assembly language requires you to use one of
  2815.   several specific registers: BX, BP, SI, and DI.%@NL@%
  2816. %@NL@%
  2817. %@4@%  You indicate an indirect memory operand by using at least one pair of%@EH@%
  2818.   brackets. Use of the index operator (%@AB@%[ ]%@AE@%) is explained in more detail in
  2819.   Section 9.2.1.3%@BO:       7b606@%.%@NL@%
  2820. %@NL@%
  2821. %@4@%%@CR:IX2.181     @%%@CR:IX2.182     @%%@CR:IX2.183     @%%@CR:IX2.184     @%  When you place a register name in brackets, the processor uses the data%@EH@%
  2822.   pointed to by the register. For example, the following instruction
  2823.   accesses the data at the address contained in BX, and then moves this data
  2824.   into AX:%@NL@%
  2825. %@NL@%
  2826.   %@AS@%            mov     ax,[bx]%@AE@%%@NL@%
  2827. %@NL@%
  2828. %@4@%  When you specify more than one register, the processor adds the contents%@EH@%
  2829.   together to determine the effective address (the address of the data to
  2830.   operate on). One register must be a base register (BX or BP), and the
  2831.   other must be an index register (SI or DI):%@NL@%
  2832. %@NL@%
  2833.   %@AS@%            mov     ax,[bx+si]%@AE@%%@NL@%
  2834. %@NL@%
  2835. %@4@%%@CR:IX2.185     @%%@CR:IX2.186     @%  You can specify one or more displacements. A "displacement" is a constant%@EH@%
  2836.   value to add to the effective address. A simple use of a displacement is
  2837.   to add a base address to a register:%@NL@%
  2838. %@NL@%
  2839.   %@AS@%            mov     ax,table[si]%@AE@%%@NL@%
  2840. %@NL@%
  2841. %@4@%%@CR:IX2.187     @%%@CR:IX2.188     @%  In the example above, the displacement %@AS@%table %@AE@%is the address of an array;%@EH@%
  2842.   SI holds an index to an array element. (Unlike C, an assembly-language
  2843.   index always indicates the distance in bytes between the beginning of the
  2844.   array and the element.) Each time the instruction executes, it may load a
  2845.   different element into AX. The value of SI determines which array element
  2846.   to load.%@NL@%
  2847. %@NL@%
  2848. %@4@%  Each displacement can be an address or numeric constant. If there is more%@EH@%
  2849.   than one displacement, the assembler adds them all together at assembly
  2850.   time, and places the total displacement into the executable code. For
  2851.   example, in the statement%@NL@%
  2852. %@NL@%
  2853.   %@AS@%            mov     ax,table[bx][di]+6%@AE@%%@NL@%
  2854. %@NL@%
  2855. %@4@%  both %@AS@%table %@AE@%and %@AS@%6 %@AE@%are displacements. The assembler adds the value of %@AS@%table%@AE@%%@EH@%
  2856.   to %@AS@%6 %@AE@%to get the total displacement.%@NL@%
  2857. %@NL@%
  2858. %@4@%%@CR:IX2.189     @%  Table 2.2 shows the modes in which registers can be used to specify%@EH@%
  2859.   indirect memory operands.%@NL@%
  2860. %@NL@%
  2861.   %@AB@%Table 2.2 Indirect Addressing Modes%@AE@%%@NL@%
  2862. %@NL@%
  2863.   %@AB@%Mode%@AE@%                %@AB@%Syntax%@AE@%                  %@AB@%Description%@AE@%%@NL@%
  2864.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2865.   Register indirect   %@AB@%[%@AE@%BX%@AB@%]%@AE@% %@AB@%[%@AE@%BP%@AB@%]%@AE@% %@AB@%[%@AE@%DI%@AB@%]%@AE@% %@AB@%[%@AE@%DI%@AB@%]%@AE@%     Effective address is contents
  2866.                                               of register%@NL@%
  2867. %@NL@%
  2868.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2869.   Based or indexed    %@AI@%displacement%@AE@%%@AB@%[%@AE@%BX%@AB@%]%@AE@%        Effective address is contents
  2870.                       %@AI@%displacement%@AE@%%@AB@%[%@AE@%BP%@AB@%]%@AE@%        of register plus %@AI@%displacement%@AE@%
  2871.                       %@AI@%displacement%@AE@%%@AB@%[%@AE@%DI%@AB@%]%@AE@%
  2872.                       %@AI@%displacement%@AE@%%@AB@%[%@AE@%SI%@AB@%]%@AE@%%@NL@%
  2873.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2874.   Based indexed       %@AB@%[%@AE@%BX%@AB@%][%@AE@%DI%@AB@%]%@AE@% %@AB@%[%@AE@%BP%@AB@%][%@AE@%DI%@AB@%]%@AE@%       Effective address is contents
  2875.                       %@AB@%[%@AE@%BX%@AB@%][%@AE@%SI%@AB@%]%@AE@% %@AB@%[%@AE@%BP%@AB@%][%@AE@%SI%@AB@%]%@AE@%       of base register plus contents
  2876.                                               of index register%@NL@%
  2877. %@NL@%
  2878.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2879.   Based indexed with  %@AI@%displacement%@AE@%%@AB@%[%@AE@%BX%@AB@%][%@AE@%DI%@AB@%]%@AE@%    Effective address is the sum
  2880.   displacement        %@AI@%displacement%@AE@%%@AB@%[%@AE@%BP%@AB@%][%@AE@%DI%@AB@%]%@AE@%    of base register, index
  2881.                       %@AI@%displacement%@AE@%%@AB@%[%@AE@%BX%@AB@%][%@AE@%SI%@AB@%]%@AE@%    register, plus %@AI@%displacement%@AE@%
  2882.                       %@AI@%displacement%@AE@%%@AB@%[%@AE@%BP%@AB@%][%@AE@%SI%@AB@%]%@AE@%%@NL@%
  2883.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  2884. %@NL@%
  2885. %@NL@%
  2886. %@4@%%@CR:IX2.190     @%%@CR:IX2.191     @%%@CR:IX2.192     @%%@CR:IX2.193     @%  You can enclose each register in its own pair of brackets, or you can%@EH@%
  2887.   place the registers in the same pair of brackets separated by a plus sign
  2888.   (%@AB@%+%@AE@%). The period (%@AB@%.%@AE@%) is normally used with structures, but it also
  2889.   indicates addition. The following statements are equivalent:%@NL@%
  2890. %@NL@%
  2891.   %@AS@%            mov     ax,table[bx][di]%@AE@%%@NL@%
  2892.   %@AS@%            mov     ax,table[bx+di]%@AE@%%@NL@%
  2893.   %@AS@%            mov     ax,[table+bx+di]%@AE@%%@NL@%
  2894.   %@AS@%            mov     ax,[bx][di].table%@AE@%%@NL@%
  2895.   %@AS@%            mov     ax,[bx][di]+table%@AE@%%@NL@%
  2896.   %@AS@%            mov     ax,table[di][bx]%@AE@%%@NL@%
  2897. %@NL@%
  2898. %@NL@%
  2899. %@2@%%@CR:SC2.7       @%%@AB@%2.7  Segmented Addressing and Segment Registers%@AE@%%@EH@%%@NL@%
  2900. %@NL@%
  2901. %@4@%%@CR:IX2.194     @%%@CR:IX2.195     @%  "Segmented addressing" is the internal mechanism that enables the%@EH@%
  2902.   processor to address up to one megabyte of main memory. This mechanism
  2903.   accesses each physical memory location by combining two 16-bit addresses.
  2904.   The two addresses can be represented in source code as follows:%@NL@%
  2905. %@NL@%
  2906. %@4@%  %@AI@%segment%@AE@%:%@AI@%offset%@AE@%%@EH@%%@NL@%
  2907. %@NL@%
  2908. %@4@%  The first 16-bit address is the "segment address." The second 16-bit%@EH@%
  2909.   address is the "offset address." In effect, the segment address selects a
  2910.   64K region of memory, and the offset address selects a byte within this
  2911.   region. Here's how it works:%@NL@%
  2912. %@NL@%
  2913.   1. The processor shifts the segment address left by four places, producing
  2914.      a 20-bit address ending in four zeros. This operation has the effect of
  2915.      multiplying the segment address by 16.%@NL@%
  2916. %@NL@%
  2917.   2. The processor adds this 20-bit address to the 16-bit offset address.
  2918.      The offset address is not shifted.%@NL@%
  2919. %@NL@%
  2920.   3. The processor uses the resulting 20-bit address, often called the
  2921.      "physical address," to access an actual location in the one-megabyte
  2922.      address space.%@NL@%
  2923. %@NL@%
  2924. %@4@%%@CR:IX2.196     @%  Figure 2.3 illustrates this process. The 8086-family processors were%@EH@%
  2925.   developed to use this mechanism because 16 bits (the size of an 8086
  2926.   register) can only address 64K at a time. However, the combined 20-bit
  2927.   address is sufficient to address a full megabyte. Note that DOS and ROM
  2928.   BIOS reserve part of this area, so that no more than 640K is available for
  2929.   program addresses.%@NL@%
  2930. %@NL@%
  2931.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  2932.   │ This figure can be found in Section 2.7 of the manual                  │%@NL@%
  2933.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  2934. %@NL@%
  2935. %@4@%%@CR:IX2.197     @%  A "segment" consists of a series of addresses that share the same segment%@EH@%
  2936.   address, but different offsets. Segments can be no more than 64K in size.
  2937.   To create large programs, you need to divide your program into multiple
  2938.   segments. Even with smaller programs, it is convenient to have separate
  2939.   code, data, and stack segments. (With tiny-model programs, the linker
  2940.   combines these segments into a single physical segment.)%@NL@%
  2941. %@NL@%
  2942. %@4@%  The following example helps illustrate segmented-address calculations%@EH@%
  2943.   further. The processor calculates the address %@AS@%53C2:107A %@AE@%by multiplying the
  2944.   segment portion of the address by 16 (10H), and then adding the offset
  2945.   portion, as shown below:%@NL@%
  2946. %@NL@%
  2947.   %@AS@%    53C20h           Segment times 10h%@AE@%%@NL@%
  2948. %@NL@%
  2949.   %@AS@% +   107Ah           Offset%@AE@%%@NL@%
  2950. %@NL@%
  2951.   %@AS@%    54C9Ah           Physical address%@AE@%%@NL@%
  2952. %@NL@%
  2953. %@4@%  The use of segmented architecture doesn't mean that you have to specify%@EH@%
  2954.   two addresses every time you access memory. The 8086-family processors use
  2955.   four segment registers, which simplify programming in the following ways:%@NL@%
  2956. %@NL@%
  2957.   ■  Normally, you don't specify a segment address when you access data.
  2958.      Every data reference is relative to one of the four segment
  2959.      registers──CS, DS, SS, or ES──so the segment address is implied.%@NL@%
  2960. %@NL@%
  2961.   ■  Most of the time, you don't need to tell the processor which segment
  2962.      register to use. By default, the processor uses CS for code addresses,
  2963.      DS for data addresses, and SS for stack addresses, except where
  2964.      otherwise noted in this section.%@NL@%
  2965. %@NL@%
  2966.   ■  You initialize segment registers at the beginning of your program. Once
  2967.      initialized, you can continue to use the segment addresses stored in
  2968.      those registers.%@NL@%
  2969. %@NL@%
  2970. %@4@%  If the program uses medium, large, huge, or compact model, you may need to%@EH@%
  2971.   periodically reload one or more of the segment registers. These memory
  2972.   models let you use more than 64K of code or 64K of data.%@NL@%
  2973. %@NL@%
  2974. %@4@%  However, if the program uses small or tiny model, you never reload a%@EH@%
  2975.   segment register except in the following situations: to access a special
  2976.   hardware-defined location in memory, such as the video-display area, or to
  2977.   access far memory allocated to the program by DOS function 48H.%@NL@%
  2978. %@NL@%
  2979. %@4@%%@CR:IX2.198     @%  Although each memory operand has a default segment register (usually DS,%@EH@%
  2980.   unless the operand uses BP), you can specify another segment register by
  2981.   using the segment override operator (%@AB@%:%@AE@%). The following example loads the
  2982.   variable %@AS@%far_away %@AE@%residing in the segment pointed to by ES:%@NL@%
  2983. %@NL@%
  2984.   %@AS@%            mov     ax,es:far_away%@AE@%%@NL@%
  2985. %@NL@%
  2986. %@4@%  For more information on this operator, see Section 9.2.3%@BO:       7e029@%,%@EH@%
  2987.   "Segment-Override Operator."%@NL@%
  2988. %@NL@%
  2989. %@3@%  %@AB@%The CS Register%@AE@%%@EH@%%@NL@%
  2990. %@NL@%
  2991. %@4@%%@CR:IX2.199     @%%@CR:IX2.200     @%%@CR:IX2.201     @%%@CR:IX2.202     @%%@CR:IX2.203     @%  The processor always uses the CS (Code Segment) register as the segment%@EH@%
  2992.   address of the next instruction to execute; IP (Instruction Pointer) holds
  2993.   the offset address. CS:IP represents the full address of the next
  2994.   instruction.%@NL@%
  2995. %@NL@%
  2996. %@4@%  Near jumps and procedure calls alter the value of IP. Far jumps and%@EH@%
  2997.   procedure calls alter both CS and IP. You never alter CS directly because
  2998.   the far jump and call instructions do so automatically. Furthermore, DOS
  2999.   initializes CS for you at the beginning of the program.%@NL@%
  3000. %@NL@%
  3001. %@3@%  %@AB@%The DS Register%@AE@%%@EH@%%@NL@%
  3002. %@NL@%
  3003. %@4@%%@CR:IX2.204     @%%@CR:IX2.205     @%%@CR:IX2.206     @%  By default, the processor uses the DS (Data Segment) register as the%@EH@%
  3004.   segment address for program data. String instructions and indirect memory
  3005.   operands present some exceptions to this rule. With indirect memory
  3006.   operands, the use of BP anywhere in the operand causes SS to be the
  3007.   default segment register. Otherwise, DS is the default.%@NL@%
  3008. %@NL@%
  3009. %@4@%  All the Microsoft standard memory models place the most frequently used%@EH@%
  3010.   data in an area pointed to by DS. This area is commonly called the
  3011.   "default data area," and it can be no larger than 64K. These memory models
  3012.   use the ES register to access data outside the default data area. Your own
  3013.   programs can either use this technique, or else reload DS whenever you
  3014.   enter a new module. The standard method has the advantage of providing
  3015.   fast access to the most frequently used data.%@NL@%
  3016. %@NL@%
  3017. %@3@%  %@AB@%The SS Register%@AE@%%@EH@%%@NL@%
  3018. %@NL@%
  3019. %@4@%%@CR:IX2.207     @%%@CR:IX2.208     @%%@CR:IX2.209     @%  When the processor accesses data on the stack, it uses the SS (Stack%@EH@%
  3020.   Segment) register as the segment register. (See the description of SP in
  3021.   Section 2.5.3%@BO:       21724@% for more information about the stack.) Thus, SS:SP always
  3022.   points to the current stack position. Indirect memory operands involving
  3023.   BP also use SS as the default segment register.%@NL@%
  3024. %@NL@%
  3025. %@4@%  The Microsoft standard memory models set SS equal to DS. This setting%@EH@%
  3026.   makes some programming tasks easier. In particular, it lets you address
  3027.   stack or data addresses with either register. If you have to reload DS,
  3028.   you can always access items in the default data area by using an SS
  3029.   override.%@NL@%
  3030. %@NL@%
  3031. %@3@%  %@AB@%The ES Register%@AE@%%@EH@%%@NL@%
  3032. %@NL@%
  3033. %@4@%%@CR:IX2.210     @%%@CR:IX2.211     @%%@CR:IX2.212     @%%@CR:IX2.213     @%  The ES (Extra Segment) register is convenient for accessing data outside%@EH@%
  3034.   of the default data area. As demonstrated in Section 3.4%@BO:       30c03@%, "Decimal
  3035.   Conversion with Far Data Pointers," you access far data by loading ES with
  3036.   the desired segment address, and then giving a segment override. Section
  3037.   13.3.2%@BO:       aa7dc@%, "Loading Far Pointers," provides further information.%@NL@%
  3038. %@NL@%
  3039. %@4@%  ES also plays a role in string instructions. With these instructions, the%@EH@%
  3040.   DI (Destination Index) register is always relative to the segment address
  3041.   in ES.%@NL@%
  3042. %@NL@%
  3043. %@NL@%
  3044. %@NL@%
  3045. ────────────────────────────────────────────────────────────────────────────%@NL@%
  3046. %@1@%%@CR:CH3         @%%@AB@%Chapter 3:  Writing Assembly Modules for C Programs%@AE@%%@EH@%%@NL@%
  3047. %@NL@%
  3048. %@NL@%
  3049. %@4@%  As a C programmer, you can take advantage of the superior speed and%@EH@%
  3050.   compactness of assembly-language routines. You can write most of your
  3051.   program in C, then write time-critical routines in assembly language.%@NL@%
  3052. %@NL@%
  3053. %@4@%%@CR:IX3.1       @%  This chapter presents QuickAssembler programming techniques for%@EH@%
  3054.   interfacing to C. You can use similar techniques to interface with other
  3055.   languages. By using C with assembly language, however, you gain the
  3056.   advantage of being able to develop the entire program from within the
  3057.   integrated environment.%@NL@%
  3058. %@NL@%
  3059. %@4@%  If you've read Chapter 2%@BO:       151ff@%, read this chapter to see how to use assembly%@EH@%
  3060.   language in a complete example module. If you skipped over Chapter 2%@BO:       151ff@%, you
  3061.   may want to refer to it occasionally for basic concepts, such as
  3062.   instructions and registers.%@NL@%
  3063. %@NL@%
  3064. %@NL@%
  3065. %@2@%%@CR:SC3.1       @%%@AB@%3.1  A Skeleton for Procedure Modules%@AE@%%@EH@%%@NL@%
  3066. %@NL@%
  3067. %@4@%  Let's start by looking at the skeleton of a module with one procedure. The%@EH@%
  3068.   "skeleton" consists of statements that give basic structure to the module.
  3069.   Within this structure, you can supply most any instructions you want.
  3070.   Later sections of this chapter flesh out the skeleton by supplying useful
  3071.   code.%@NL@%
  3072. %@NL@%
  3073. %@4@%  The following skeleton assumes that the module is called by a small-model%@EH@%
  3074.   C program, and consists of one procedure which takes a single parameter, a
  3075.   pointer to a byte:%@NL@%
  3076. %@NL@%
  3077.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  3078.   %@AS@%            .CODE%@AE@%%@NL@%
  3079. %@NL@%
  3080.   %@AS@%dectoint    PROC    Array:PTR BYTE%@AE@%%@NL@%
  3081.   %@AS@%;%@AE@%%@NL@%
  3082.   %@AS@%;   (supply executable code here)%@AE@%%@NL@%
  3083.   %@AS@%;%@AE@%%@NL@%
  3084.   %@AS@%dectoint    ENDP%@AE@%%@NL@%
  3085.   %@AS@%            END%@AE@%%@NL@%
  3086. %@NL@%
  3087. %@4@%  Some features of the skeleton change when you write different procedures.%@EH@%
  3088.   Other parts may remain the same. In particular, you'll need to add a %@AB@%PROC%@AE@%
  3089.   and %@AB@%ENDP%@AE@% statement each time you add another procedure to the module.%@NL@%
  3090. %@NL@%
  3091. %@4@%  Before looking at a full program example, let's examine each part of the%@EH@%
  3092.   skeleton.%@NL@%
  3093. %@NL@%
  3094. %@NL@%
  3095. %@3@%%@CR:SC3.1.1     @%%@AB@%3.1.1  The .MODEL Directive%@AE@%%@EH@%%@NL@%
  3096. %@NL@%
  3097. %@4@%%@CR:IX3.2       @%%@CR:IX3.3       @%  The %@AB@%.MODEL%@AE@% directive gives general information about the module. It uses%@EH@%
  3098.   the following syntax:%@NL@%
  3099. %@NL@%
  3100. %@4@%  %@AB@%.MODEL %@AE@%%@AI@%memorymodel%@AE@% [[%@AB@%,%@AE@%%@AI@%langtype%@AE@% [[%@AB@%,%@AE@%%@AI@%stacktype%@AE@%]]]]%@EH@%%@NL@%
  3101. %@NL@%
  3102. %@4@%  The last two fields are optional. Commas are field separators and are only%@EH@%
  3103.   required if you use more than one field. Usually, you'll want to enter
  3104.   values in the first two fields.%@NL@%
  3105. %@NL@%
  3106. %@4@%%@CR:IX3.4       @%%@CR:IX3.5       @%%@CR:IX3.6       @%  The %@AI@%memorymodel%@AE@% and %@AI@%langtype%@AE@% fields correspond to the memory model and%@EH@%
  3107.   language, respectively, of the calling module. If your C program declares
  3108.   your procedure to be of type %@AB@%pascal%@AE@% or %@AB@%fortran%@AE@%, use %@AB@%Pascal%@AE@%, %@AB@%BASIC%@AE@%, or
  3109.   %@AB@%FORTRAN%@AE@% in the %@AI@%langtype%@AE@% field. These keywords specify the use of the non-C
  3110.   calling and naming conventions. Otherwise, specify%@AB@% C%@AE@% as the %@AI@%langtype%@AE@%.
  3111.   Although the %@AI@%langtype%@AE@% field is optional, you should supply it since the
  3112.   %@AB@%PROC%@AE@% features described later in this chapter require it.%@NL@%
  3113. %@NL@%
  3114. %@4@%%@CR:IX3.7       @%%@CR:IX3.8       @%%@CR:IX3.9       @%  Don't use the %@AI@%stacktype%@AE@% field unless the calling C program is compiled%@EH@%
  3115.   with SS not equal to DS, in which case you should type in %@AB@%farStack%@AE@%.
  3116.   (QuickC does not generate code that sets SS not equal to DS, but other
  3117.   versions of Microsoft C do support this option.) The default is %@AB@%nearStack%@AE@%,
  3118.   which assumes SS is equal to DS.%@NL@%
  3119. %@NL@%
  3120. %@NL@%
  3121. %@3@%%@CR:SC3.1.2     @%%@AB@%3.1.2  The .CODE Directive%@AE@%%@EH@%%@NL@%
  3122. %@NL@%
  3123. %@4@%%@CR:IX3.10      @%%@CR:IX3.11      @%  The %@AB@%.CODE%@AE@% directive marks the beginning of the code segment, which is the%@EH@%
  3124.   section of your program that contains the actual steps to execute:%@NL@%
  3125. %@NL@%
  3126.   %@AS@%            .CODE%@AE@%%@NL@%
  3127. %@NL@%
  3128. %@4@%  Statements that follow this directive are considered part of the code%@EH@%
  3129.   segment. The segment continues to the end of the module or the next
  3130.   segment directive. Typically, the code segment consists of instructions
  3131.   and procedure definitions. It can also contain macro calls.%@NL@%
  3132. %@NL@%
  3133. %@4@%  Some procedures work with static data. In Chapter 4%@BO:       34dba@%, "Writing Stand-Alone%@EH@%
  3134.   Assembly Programs," you'll see how to declare a data segment in which you
  3135.   can place data declarations.%@NL@%
  3136. %@NL@%
  3137. %@NL@%
  3138. %@3@%%@CR:SC3.1.3     @%%@AB@%3.1.3  The PROC Directive%@AE@%%@EH@%%@NL@%
  3139. %@NL@%
  3140. %@4@%%@CR:IX3.12      @%%@CR:IX3.13      @%  Use the %@AB@%PROC%@AE@% directive to define a procedure. The name of the procedure%@EH@%
  3141.   appears in the first column:%@NL@%
  3142. %@NL@%
  3143.   %@AS@%dectoint    PROC    Array:PTR BYTE%@AE@%%@NL@%
  3144. %@NL@%
  3145. %@4@%  Because the %@AB@%.MODEL%@AE@% statement specified C-language conventions, the%@EH@%
  3146.   assembler prefixes the name %@AS@%dectoint %@AE@%with an underscore (_), and places
  3147.   the name into object code as a public code label.%@NL@%
  3148. %@NL@%
  3149. %@4@%%@CR:IX3.14      @%%@CR:IX3.15      @%  If your procedure alters registers that should be preserved, the optional%@EH@%
  3150.   %@AB@%USES%@AE@% keyword automatically generates code to push the value of these
  3151.   registers on the stack and pop them when the procedure returns. Procedures
  3152.   called by C should not corrupt the value of SI, DI, or the segment
  3153.   registers CS, DS, or SS. (The value of BP is automatically preserved.) The
  3154.   following example shows how to preserve SI and DI for a procedure that
  3155.   changes these registers:%@NL@%
  3156. %@NL@%
  3157.   %@AS@%dectoint    PROC    USES si di, Array:PTR BYTE%@AE@%%@NL@%
  3158. %@NL@%
  3159. %@4@%%@CR:IX3.16      @%%@CR:IX3.17      @%  The last part of the statement declares one or more parameters. In this%@EH@%
  3160.   case, the procedure declares a single parameter, %@AS@%Array%@AE@%, as a pointer to a
  3161.   byte. The most common parameter types you can declare are listed below:%@NL@%
  3162. %@NL@%
  3163.   %@AB@%Declaration%@AE@%         %@AB@%Meaning%@AE@%%@NL@%
  3164.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3165.   %@AB@%WORD%@AE@%                Word (two bytes)%@NL@%
  3166. %@NL@%
  3167.   %@AB@%DWORD%@AE@%               Doubleword (four bytes)%@NL@%
  3168. %@NL@%
  3169.   %@AB@%PTR BYTE%@AE@%            Pointer to a byte; most commonly, a pointer to a
  3170.                       character string%@NL@%
  3171. %@NL@%
  3172.   %@AB@%PTR WORD%@AE@%            Pointer to a word; typically, the address of an array
  3173.                       of integers%@NL@%
  3174. %@NL@%
  3175.   %@AB@%PTR DWORD%@AE@%           Pointer to a doubleword%@NL@%
  3176. %@NL@%
  3177. %@NL@%
  3178. %@4@%  For example, the following procedure definition declares a procedure named%@EH@%
  3179.   %@AS@%MidStr%@AE@%, which takes as parameters two pointers to character strings and
  3180.   one integer:%@NL@%
  3181. %@NL@%
  3182.   %@AS@%MidStr      PROC    Str1:PTR BYTE, Str2:PTR BYTE, Index:WORD%@AE@%%@NL@%
  3183. %@NL@%
  3184. %@4@%  References to parameters are really references to locations on the stack.%@EH@%
  3185.   C modules pass parameters by pushing them on the stack just before calling
  3186.   the procedure. The BP register serves as a framepointer (a pointer to the
  3187.   procedure's stack area), and each parameter is an offset from BP. The
  3188.   exact offset of each parameter depends on the memory model and calling
  3189.   convention, both established by the %@AB@%.MODEL%@AE@% directive.%@NL@%
  3190. %@NL@%
  3191. %@4@%  When you use QuickAssembler procedure definitions, the assembler automates%@EH@%
  3192.   the work of referring to parameters. Instead of setting up the
  3193.   framepointer or calculating parameter offsets, you simply refer to
  3194.   parameters by name. You can also use these names with debugging commands.%@NL@%
  3195. %@NL@%
  3196. %@4@%  Appendix A%@BO:       ed697@%, "Mixed-Language Mechanics," shows the actual code that%@EH@%
  3197.   establishes BP as the framepointer. It also shows how to calculate
  3198.   parameter offsets.%@NL@%
  3199. %@NL@%
  3200. %@4@%  Section 6.4.3%@BO:       5ea93@%, "Procedure Labels," gives the complete syntax and rules%@EH@%
  3201.   for using the %@AB@%PROC%@AE@% statement.%@NL@%
  3202. %@NL@%
  3203. %@NL@%
  3204. %@3@%%@CR:SC3.1.4     @%%@AB@%3.1.4  The ENDP and END Statements%@AE@%%@EH@%%@NL@%
  3205. %@NL@%
  3206. %@4@%%@CR:IX3.18      @%%@CR:IX3.19      @%%@CR:IX3.20      @%%@CR:IX3.21      @%  The module ends with two statements: %@AB@%ENDP%@AE@%, which declares the end of a%@EH@%
  3207.   procedure, and %@AB@%END%@AE@%, which declares the end of the module:%@NL@%
  3208. %@NL@%
  3209.   %@AS@%dectoint    ENDP%@AE@%%@NL@%
  3210.   %@AS@%            END%@AE@%%@NL@%
  3211. %@NL@%
  3212. %@4@%  You can place any number of procedures in the same module. Each time you%@EH@%
  3213.   end a procedure, use %@AB@%ENDP%@AE@%. However, %@AB@%END%@AE@% should only occur once, at the end
  3214.   of the module.%@NL@%
  3215. %@NL@%
  3216. %@NL@%
  3217. %@2@%%@CR:SC3.2       @%%@AB@%3.2  Instructions Used in This Chapter%@AE@%%@EH@%%@NL@%
  3218. %@NL@%
  3219. %@4@%  The instructions below were introduced in Chapter 2%@BO:       151ff@%, "Introducing 8086%@EH@%
  3220.   Assembly Language." They are summarized here briefly for review. The first
  3221.   group of instructions manipulates data:%@NL@%
  3222. %@NL@%
  3223.   %@AB@%Instruction%@AE@%               %@AB@%Description%@AE@%%@NL@%
  3224.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3225.   %@AB@%MOV%@AE@% %@AI@%destination%@AE@%, %@AI@%source%@AE@%   Copies value of %@AI@%source%@AE@% to %@AI@%destination%@AE@%%@NL@%
  3226. %@NL@%
  3227.   %@AB@%ADD%@AE@% %@AI@%destination%@AE@%, %@AI@%source%@AE@%   Adds %@AI@%source%@AE@% to %@AI@%destination%@AE@%, storing result in
  3228.                             %@AI@%destination%@AE@%%@NL@%
  3229. %@NL@%
  3230.   %@AB@%SUB%@AE@% %@AI@%destination%@AE@%, %@AI@%source%@AE@%   Subtracts %@AI@%source%@AE@% from %@AI@%destination%@AE@%, storing
  3231.                             result in %@AI@%destination%@AE@%%@NL@%
  3232. %@NL@%
  3233.   %@AB@%INC%@AE@% %@AI@%destination%@AE@%           Increment──adds 1 to %@AI@%destination%@AE@%%@NL@%
  3234. %@NL@%
  3235.   %@AB@%DEC%@AE@% %@AI@%destination%@AE@%           Decrement──subtracts 1 from %@AI@%destination%@AE@%%@NL@%
  3236. %@NL@%
  3237.   %@AB@%MUL%@AE@% %@AI@%source%@AE@%                Multiplies %@AI@%source%@AE@% by AX (if operand is 16 bits),
  3238.                             storing high 16 bits in DX and low 16 bits in AX%@NL@%
  3239. %@NL@%
  3240. %@NL@%
  3241. %@4@%  The second group of instructions controls the flow of program execution:%@EH@%%@NL@%
  3242. %@NL@%
  3243.   %@AB@%Instruction%@AE@%         %@AB@%Description%@AE@%%@NL@%
  3244.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3245.   %@AB@%CMP%@AE@% %@AI@%destination%@AE@%,    Compare──subtracts %@AI@%source%@AE@% from %@AI@%destination%@AE@%, ignoring
  3246.   %@AI@%source%@AE@%              result but setting processor flags appropriately%@NL@%
  3247. %@NL@%
  3248.   %@AB@%JE%@AE@% %@AI@%label%@AE@%            Jumps to %@AI@%label%@AE@% if result of last operation was equal
  3249.                       to zero%@NL@%
  3250. %@NL@%
  3251.   %@AB@%JAE%@AE@% %@AI@%label%@AE@%           Jumps to %@AI@%label%@AE@% if result of last operation was equal
  3252.                       to or above zero (unsigned operations)%@NL@%
  3253. %@NL@%
  3254.   %@AB@%JMP%@AE@% %@AI@%label%@AE@%           Jumps unconditionally to %@AI@%label%@AE@%%@NL@%
  3255. %@NL@%
  3256. %@NL@%
  3257. %@CR:IX3.22      @%%@NL@%
  3258. %@2@%%@CR:SC3.3       @%%@AB@%3.3  Decimal Conversion Example%@AE@%%@EH@%%@NL@%
  3259. %@NL@%
  3260. %@4@%  This section uses a decimal-conversion example to illustrate the use of%@EH@%
  3261.   some basic instructions and directives. It features an assembly module
  3262.   that takes a pointer to a null-terminated string of characters as input
  3263.   and returns an unsigned integer value. This chapter assumes that the value
  3264.   is unsigned.%@NL@%
  3265. %@NL@%
  3266. %@4@%  You can compute the value of a decimal string by multiplying each digit by%@EH@%
  3267.   a power of 10:%@NL@%
  3268. %@NL@%
  3269.   %@AS@%2035 = 2 x 10 cubed + 0 x 10 squared + 3 x 10 + 5%@AE@%%@NL@%
  3270. %@NL@%
  3271. %@4@%  One way to calculate the value of the number is to calculate each power of%@EH@%
  3272.   10 separately, then multiply each digit by the corresponding power. For
  3273.   example, you can calculate 10 cubed, and then multiply by 2.%@NL@%
  3274. %@NL@%
  3275. %@4@%  A much more efficient algorithm %@AI@%combines%@AE@% the calculations for powers of%@EH@%
  3276.   10. The algorithm adds each digit to a running total, then multiplies the
  3277.   total by 10 after every digit but the last. The following pseudo-code
  3278.   represents this algorithm, and assumes that the first character in the
  3279.   string is the most significant digit:%@NL@%
  3280. %@NL@%
  3281.   %@AS@%initialize total to 0%@AE@%%@NL@%
  3282.   %@AS@%while there's another digit%@AE@%%@NL@%
  3283.   %@AS@%    add value of digit to total%@AE@%%@NL@%
  3284.   %@AS@%    advance to next digit%@AE@%%@NL@%
  3285.   %@AS@%    if no more digits%@AE@%%@NL@%
  3286.   %@AS@%        we're done%@AE@%%@NL@%
  3287.   %@AS@%    else%@AE@%%@NL@%
  3288.   %@AS@%        multiply total by 10%@AE@%%@NL@%
  3289. %@NL@%
  3290. %@4@%  A simple C program that calls the procedure might look like this:%@EH@%%@NL@%
  3291. %@NL@%
  3292.   %@AS@%extern  unsigned int  dectoint( char * );%@AE@%%@NL@%
  3293.   %@AS@%main()%@AE@%%@NL@%
  3294.   %@AS@%{%@AE@%%@NL@%
  3295.   %@AS@%    char    digits[81];%@AE@%%@NL@%
  3296. %@NL@%
  3297.   %@AS@%    gets( digits );%@AE@%%@NL@%
  3298.   %@AS@%    printf( "Numeric value is: %d", dectoint( digits ) );%@AE@%%@NL@%
  3299.   %@AS@%}%@AE@%%@NL@%
  3300. %@NL@%
  3301. %@4@%  The procedure itself could be written in C as:%@EH@%%@NL@%
  3302. %@NL@%
  3303.   %@AS@%unsigned int dectoint( char *Array)%@AE@%%@NL@%
  3304.   %@AS@%{%@AE@%%@NL@%
  3305.   %@AS@%    unsigned int total = 0;       /* Initialize total */%@AE@%%@NL@%
  3306. %@NL@%
  3307.   %@AS@%    while( *Array != '\0' )       /* While there's another digit%@AE@%%@NL@%
  3308.   %@AS@%    {%@AE@%%@NL@%
  3309.   %@AS@%        total += *Array - '0';    /* Add value to total */%@AE@%%@NL@%
  3310.   %@AS@%        Array++;                  /* Advance to next digit */%@AE@%%@NL@%
  3311.   %@AS@%        if( *Array == '\0' )      /* If no more digits,  */%@AE@%%@NL@%
  3312.   %@AS@%            break;                /*   we're done    */%@AE@%%@NL@%
  3313.   %@AS@%        total *= 10;              /* Else, multiply by 10 */%@AE@%%@NL@%
  3314.   %@AS@%    }%@AE@%%@NL@%
  3315.   %@AS@%    return( total );%@AE@%%@NL@%
  3316.   %@AS@%}%@AE@%%@NL@%
  3317. %@NL@%
  3318. %@4@%  This chapter shows how to write the same procedure in assembly language.%@EH@%
  3319.   The assembly-language version will be faster because it can make strategic
  3320.   use of registers and choose optimal instructions. You can write a main
  3321.   module with C code, place the assembly routine in a separate module with a
  3322.   .ASM extension, then link them together by creating a program list.%@NL@%
  3323. %@NL@%
  3324.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3325.   %@AB@%NOTE%@AE@%  You can build mixed-language programs by placing both .C and .ASM
  3326.   files in a program list. Place the main module first. In the Assembler
  3327.   Flags dialog box, make sure that you select either Preserve Case or
  3328.   Preserve Extrn (the default). From the QCL command line, use the /Cl
  3329.   (preserve case) or /Cx (preserve case of external symbols) option. QC
  3330.   calls the linker with case sensitivity on, so C and assembler symbols must
  3331.   match exactly.%@NL@%
  3332.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3333. %@NL@%
  3334. %@4@%%@CR:IX3.23      @%  Before writing the assembly procedure, we first need to develop a strategy%@EH@%
  3335.   for using registers.%@NL@%
  3336. %@NL@%
  3337. %@4@%  The AX (Accumulator) register is ideal for keeping the running total. The%@EH@%
  3338.   algorithm changes this total through both addition and multiplication. The
  3339.   %@AB@%MUL%@AE@% instruction requires the use of AX. By keeping the total in AX at all
  3340.   times, the procedure avoids having to constantly reload this register.%@NL@%
  3341. %@NL@%
  3342. %@4@%  The BX register should be used to access the individual digits. The%@EH@%
  3343.   procedure receives the address of the digit string, and then retrieves
  3344.   each ASCII byte through pointer indirection. BX is one of the few
  3345.   registers that supports this operation. SI and DI could also be used this
  3346.   way, but C-generated code requires that SI and DI be preserved. BX can be
  3347.   freely altered.%@NL@%
  3348. %@NL@%
  3349. %@4@%  The procedure needs to allocate two more registers: one for holding the%@EH@%
  3350.   multiplication factor (10), and another for adjusting the binary value of
  3351.   the digit. The procedure uses CX and DX for these purposes. In this case,
  3352.   CX and DX are interchangeable. However, we use CX for multiplication now,
  3353.   because in the hex conversion example, CX will be needed for a special
  3354.   kind of multiplication──shifting bits. We use DX as an intermediate
  3355.   location to receive a byte and then add a word to AX.%@NL@%
  3356. %@NL@%
  3357. %@4@%  The complete assembly-language module is shown below:%@EH@%%@NL@%
  3358. %@NL@%
  3359.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  3360.   %@AS@%            .CODE%@AE@%%@NL@%
  3361. %@NL@%
  3362.   %@AS@%dectoint    PROC    Array:PTR BYTE%@AE@%%@NL@%
  3363. %@NL@%
  3364.   %@AS@%            sub     ax,ax               ; ax = 0%@AE@%%@NL@%
  3365.   %@AS@%            mov     bx,Array            ; bx = Array%@AE@%%@NL@%
  3366.   %@AS@%            mov     cx,10               ; factor = CX = 10%@AE@%%@NL@%
  3367.   %@AS@%            sub     dx,dx               ; dx = 0%@AE@%%@NL@%
  3368.   %@AS@%            cmp     BYTE PTR [bx],0     ; Compare byte to NULL%@AE@%%@NL@%
  3369.   %@AS@%            je      done                ; If byte=0 we're done%@AE@%%@NL@%
  3370.   %@AS@%top:%@AE@%%@NL@%
  3371.   %@AS@%            mov     dl,BYTE PTR [bx]    ; Get next digit%@AE@%%@NL@%
  3372.   %@AS@%            sub     dl,'0'              ; Convert numeral%@AE@%%@NL@%
  3373.   %@AS@%            add     ax,dx               ; Add to total%@AE@%%@NL@%
  3374.   %@AS@%            inc     bx                  ; Point to next byte%@AE@%%@NL@%
  3375.   %@AS@%            cmp     BYTE PTR [bx],0     ; Compare byte to NULL%@AE@%%@NL@%
  3376.   %@AS@%            je      done                ; If byte=0 we're done%@AE@%%@NL@%
  3377.   %@AS@%            mul     cx                  ; AX = AX * 10%@AE@%%@NL@%
  3378.   %@AS@%            jmp     SHORT top           ; Goto top of loop%@AE@%%@NL@%
  3379.   %@AS@%done:%@AE@%%@NL@%
  3380.   %@AS@%            ret                         ; Exit procedure%@AE@%%@NL@%
  3381.   %@AS@%dectoint    ENDP%@AE@%%@NL@%
  3382.   %@AS@%            END%@AE@%%@NL@%
  3383. %@NL@%
  3384. %@4@%  We'll examine each section of the module in turn. The first three%@EH@%
  3385.   statements are directives that form part of the module's skeleton. The
  3386.   %@AB@%PROC%@AE@% directive, when used with one or more parameters as it is here,
  3387.   generates code to set the framepointer (BP) properly so that you can
  3388.   access parameters.%@NL@%
  3389. %@NL@%
  3390.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  3391.   %@AS@%            .CODE%@AE@%%@NL@%
  3392. %@NL@%
  3393.   %@AS@%dectoint    PROC    Array:PTR BYTE%@AE@%%@NL@%
  3394. %@NL@%
  3395. %@4@%  The rest of the module consists of instructions──the actual core of the%@EH@%
  3396.   program. The first four instructions initialize the registers AX, BX, CX,
  3397.   and DX. Note that when initializing a register to 0, the procedure uses
  3398.   %@AB@%SUB%@AE@% in preference to %@AB@%MOV%@AE@%. Any value subtracted from itself leaves zero in
  3399.   the destination operand. Although the result is the same, the %@AB@%SUB%@AE@%
  3400.   instruction is smaller and faster because it involves no immediate data.%@NL@%
  3401. %@NL@%
  3402.   %@AS@%            sub     ax,ax               ; ax = 0%@AE@%%@NL@%
  3403.   %@AS@%            mov     bx,Array            ; bx = Array%@AE@%%@NL@%
  3404.   %@AS@%            mov     cx,10               ; factor = CX = 10%@AE@%%@NL@%
  3405.   %@AS@%            sub     dx,dx               ; dx = 0%@AE@%%@NL@%
  3406. %@NL@%
  3407. %@4@%  The next two instructions handle a special case──that of a string%@EH@%
  3408.   containing no digits at all. Recall that the procedure is passed a
  3409.   null-terminated string. The operand %@AS@%BYTE PTR [bx] %@AE@%is a memory operand
  3410.   referring to the byte pointed to by BX. If the string is empty, %@AS@%Array%@AE@%
  3411.   points to a null byte. The two instructions test for a 0 (null) value and
  3412.   jump to the end of the procedure if 0 is detected:%@NL@%
  3413. %@NL@%
  3414.   %@AS@%            cmp     BYTE PTR [bx],0     ; Compare byte to NULL%@AE@%%@NL@%
  3415.   %@AS@%            je      done                ; If byte=0 we're done%@AE@%%@NL@%
  3416. %@NL@%
  3417. %@4@%  In the %@AB@%CMP%@AE@% instruction above, the %@AS@%BYTE PTR %@AE@%operator is strictly required,%@EH@%
  3418.   because otherwise the assembler would have no way of knowing whether to
  3419.   compare 0 to the byte or a word pointed to by BX. However, when one of the
  3420.   operands is a register (as is the case with the %@AB@%MOV%@AE@% instruction below),
  3421.   the %@AS@%BYTE PTR%@AE@% operator is optional.%@NL@%
  3422. %@NL@%
  3423. %@4@%  The next eight instructions consist of a loop executed once for every%@EH@%
  3424.   digit character in the string. The label %@AS@%top %@AE@%indicates the top of the
  3425.   loop, and the first three instructions add the value of the digit to AX:%@NL@%
  3426. %@NL@%
  3427.   %@AS@%top:%@AE@%%@NL@%
  3428.   %@AS@%            mov     dl,BYTE PTR [bx]    ; Get next digit%@AE@%%@NL@%
  3429.   %@AS@%            sub     dl,'0'              ; Convert numeral%@AE@%%@NL@%
  3430.   %@AS@%            add     ax,dx               ; Add to total%@AE@%%@NL@%
  3431. %@NL@%
  3432. %@4@%%@CR:IX3.24      @%  The first instruction above retrieves the digit. The next instruction%@EH@%
  3433.   converts the digit's ASCII value to the numeric value by subtracting the
  3434.   value of the character %@AS@%'0' %@AE@%(48 decimal). This statement works because the
  3435.   ASCII character set places all digit characters in sequence from 0 to 9.
  3436.   Finally, the procedure adds the resulting value to the running total
  3437.   stored in AX. Note that the operands in each case are the same size. The
  3438.   first two instructions above access DL, the low byte of DX.%@NL@%
  3439. %@NL@%
  3440. %@4@%  The next three instructions advance to the next byte in the string, and%@EH@%
  3441.   test it for equality to zero. Getting the next byte is just a matter of
  3442.   adding the value 1 to BX (with the %@AB@%INC%@AE@% instruction), so that BX points to
  3443.   the next byte. The other two instructions are identical to previous
  3444.   instructions that tested for zero value.%@NL@%
  3445. %@NL@%
  3446.   %@AS@%            inc     bx                  ; Point to next byte%@AE@%%@NL@%
  3447.   %@AS@%            cmp     BYTE PTR [bx],0     ; Compare byte to NULL%@AE@%%@NL@%
  3448.   %@AS@%            je      done                ; If byte=0 we're done%@AE@%%@NL@%
  3449. %@NL@%
  3450. %@4@%  If the next byte is a null byte, the processor jumps to the end of the%@EH@%
  3451.   program. Otherwise, the processor continues executing the bottom of the
  3452.   loop, which multiplies the current total by 10 (stored in CX), and then
  3453.   jumps to the top:%@NL@%
  3454. %@NL@%
  3455.   %@AS@%            mul     CX                  ; AX = AX * 10%@AE@%%@NL@%
  3456.   %@AS@%            jmp     SHORT top           ; Goto top of loop%@AE@%%@NL@%
  3457. %@NL@%
  3458. %@4@%  Notice the operator%@AB@% SHORT%@AE@% used with the%@AS@% jmp %@AE@%instruction. This optional%@EH@%
  3459.   operator makes the encoded instruction smaller and faster, but it can be
  3460.   used only if the destination of the jump is less than 128 bytes away.
  3461.   %@AB@%SHORT%@AE@% is explained in more detail in Section 9.2.4.2%@BO:       7f627@%.%@NL@%
  3462. %@NL@%
  3463. %@4@%  The loop is now complete. The rest of the module exits and marks the end%@EH@%
  3464.   of the segment and the module. The %@AB@%RET%@AE@% statement causes the assembler to
  3465.   generate instructions to do the following: restore the stack, restore the
  3466.   framepointer (BP), and return properly for the memory model (small) and
  3467.   calling convention (C).%@NL@%
  3468. %@NL@%
  3469.   %@AS@%done:%@AE@%%@NL@%
  3470.   %@AS@%            ret                         ; Exit procedure%@AE@%%@NL@%
  3471.   %@AS@%dectoint    ENDP%@AE@%%@NL@%
  3472.   %@AS@%            END%@AE@%%@NL@%
  3473. %@NL@%
  3474. %@4@%%@CR:IX3.25      @%  Microsoft high-level languages always look for function return values in%@EH@%
  3475.   AX, if two bytes long, or in DX and AX, if four bytes long. If the return
  3476.   value is longer than four bytes, DX:AX points to the value returned. If
  3477.   the return value is one byte, AL contains the value.%@NL@%
  3478. %@NL@%
  3479. %@4@%  The C module that calls this procedure looks in AX for the return%@EH@%
  3480.   value──as does all high-level-language code that calls a function
  3481.   returning a two-byte value. In this case, AX already contains the results
  3482.   of the calculation. No further action is required.%@NL@%
  3483. %@NL@%
  3484. %@NL@%
  3485. %@2@%%@CR:SC3.4       @%%@AB@%3.4  Decimal Conversion with Far Data Pointers%@AE@%%@EH@%%@NL@%
  3486. %@NL@%
  3487. %@4@%%@CR:IX3.26      @%%@CR:IX3.27      @%  This section uses the same basic algorithm introduced in the last section,%@EH@%
  3488.   but presents coding techniques for different memory models.%@NL@%
  3489. %@NL@%
  3490. %@4@%%@CR:IX3.28      @%%@CR:IX3.29      @%  The %@AB@%.MODEL%@AE@% directive resolves all differences in the size of code%@EH@%
  3491.   addresses. However, when you use memory models that use far data pointers
  3492.   (compact, large, and huge), you must make some additional adjustments.%@NL@%
  3493. %@NL@%
  3494. %@4@%  The program below shows the module rewritten for large memory model. This%@EH@%
  3495.   example works for compact model if %@AS@%large %@AE@%in the first line is replaced
  3496.   with %@AS@%compact%@AE@%.%@NL@%
  3497. %@NL@%
  3498.   %@AS@%            .MODEL  large,c%@AE@%%@NL@%
  3499.   %@AS@%            .CODE%@AE@%%@NL@%
  3500. %@NL@%
  3501.   %@AS@%dectoint    PROC    USES ds, Array:PTR BYTE%@AE@%%@NL@%
  3502. %@NL@%
  3503.   %@AS@%            sub     ax,ax               ; ax = 0%@AE@%%@NL@%
  3504.   %@AS@%            lds     bx,Array            ; ds:bx = Array%@AE@%%@NL@%
  3505.   %@AS@%            mov     cx,10               ; factor = CX = 10%@AE@%%@NL@%
  3506.   %@AS@%            sub     dx,dx               ; dx = 0%@AE@%%@NL@%
  3507.   %@AS@%            cmp     BYTE PTR [bx],0     ; Compare byte to NULL%@AE@%%@NL@%
  3508.   %@AS@%            je      done                ; If byte=0 we're done%@AE@%%@NL@%
  3509.   %@AS@%top:%@AE@%%@NL@%
  3510.   %@AS@%            mov     dl,BYTE PTR [bx]    ; Get next digit%@AE@%%@NL@%
  3511.   %@AS@%            sub     dl,'0'              ; Convert numeral%@AE@%%@NL@%
  3512.   %@AS@%            add     ax,dx               ; Add to total%@AE@%%@NL@%
  3513.   %@AS@%            inc     bx                  ; Point to next byte%@AE@%%@NL@%
  3514.   %@AS@%            cmp     BYTE PTR [bx],0     ; Compare byte to NULL%@AE@%%@NL@%
  3515.   %@AS@%            je      done                ; If byte=0 we're done%@AE@%%@NL@%
  3516.   %@AS@%            mul     cx                  ; AX = AX * 10%@AE@%%@NL@%
  3517.   %@AS@%            jmp     SHORT top           ; Goto top of loop%@AE@%%@NL@%
  3518.   %@AS@%done:%@AE@%%@NL@%
  3519.   %@AS@%            ret                         ; Exit procedure%@AE@%%@NL@%
  3520.   %@AS@%dectoint    ENDP%@AE@%%@NL@%
  3521.   %@AS@%            END%@AE@%%@NL@%
  3522. %@NL@%
  3523. %@4@%  This procedure is the same as the one in the last section, except for two%@EH@%
  3524.   lines. The %@AB@%PROC%@AE@% directive now includes a %@AB@%USES%@AE@% clause, and the %@AB@%LDS%@AE@%
  3525.   instruction replaces the first %@AB@%MOV%@AE@% instruction.%@NL@%
  3526. %@NL@%
  3527. %@4@%  The procedure loads the DS register with the segment address of %@AS@%Array%@AE@%,%@EH@%
  3528.   thus causing subsequent data references to be relative to the new segment
  3529.   address. However, procedures called from C must preserve DS. The %@AB@%PROC%@AE@%
  3530.   statement, therefore, includes %@AS@%USES ds%@AE@%, which generates code to place DS
  3531.   on the stack.%@NL@%
  3532. %@NL@%
  3533. %@4@%%@CR:IX3.30      @%%@CR:IX3.31      @%  The %@AB@%LDS%@AE@% instruction (Load Data Segment) does the actual loading of the DS%@EH@%
  3534.   register. This instruction is similar to the %@AB@%MOV%@AE@% instruction:%@NL@%
  3535. %@NL@%
  3536.   %@AS@%            mov     bx,Array            ; bx = Array%@AE@%%@NL@%
  3537.   %@AS@%                                        ;   2-byte data pointer%@AE@%%@NL@%
  3538.   %@AS@%            lds     bx,Array            ; ds:bx = Array%@AE@%%@NL@%
  3539.   %@AS@%                                        ;   4-byte data pointer%@AE@%%@NL@%
  3540. %@NL@%
  3541. %@4@%  The %@AB@%LDS%@AE@% instruction accomplishes two moves. First, it loads the offset%@EH@%
  3542.   portion of the pointer into the specified register (BX). Second, it loads
  3543.   the segment portion of the pointer into DS.%@NL@%
  3544. %@NL@%
  3545. %@CR:IX3.32      @%%@CR:IX3.33      @%%@CR:IX3.34      @%  ──────────────────────────────────────────────────────────────────────────%@NL@%
  3546.   %@AB@%NOTE %@AE@%  For the %@AB@%LDS%@AE@% and %@AB@%LES%@AE@% instructions to work properly, the segment
  3547.   portion must be stored in the upper word of the four-byte (far) pointer. C
  3548.   meets this requirement by always pushing the segment portion of the
  3549.   pointer on the stack first. (The stack grows downward.) In your own
  3550.   programs, you declare far pointers with the %@AB@%DD%@AE@% directive. You initialize
  3551.   them by loading a segment address into the upper word of the pointer
  3552.   variable and an offset address into the lower word.%@NL@%
  3553.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3554. %@NL@%
  3555. %@NL@%
  3556. %@3@%%@CR:SC3.4.1     @%%@AB@%3.4.1  Writing a Model-Independent Procedure%@AE@%%@EH@%%@NL@%
  3557. %@NL@%
  3558. %@4@%%@CR:IX3.35      @%  In the case of this procedure, the use of the %@AB@%LDS%@AE@% instruction is most%@EH@%
  3559.   convenient. Once DS is loaded with the new segment address, all subsequent
  3560.   memory references are automatically correct. No further adjustments are
  3561.   needed.%@NL@%
  3562. %@NL@%
  3563. %@4@%  The simplicity of this technique makes it easy to write a module that is%@EH@%
  3564.   completely independent of memory models. This module can then be linked
  3565.   with any C program. To adjust memory model, you simply change the %@AB@%.MODEL%@AE@%
  3566.   directive, and recompile. In fact, the memory model itself can even be
  3567.   specified with a compile flag so that source code never need change.%@NL@%
  3568. %@NL@%
  3569. %@4@%  The model-independent version contains only a few lines different from the%@EH@%
  3570.   previous example:%@NL@%
  3571. %@NL@%
  3572.   %@AS@%%           .MODEL  mem,c%@AE@%%@NL@%
  3573.   %@AS@%            .CODE%@AE@%%@NL@%
  3574. %@NL@%
  3575.   %@AS@%dectoint    PROC    USES ds, Array:PTR BYTE%@AE@%%@NL@%
  3576. %@NL@%
  3577.   %@AS@%            sub     ax,ax               ; ax = 0%@AE@%%@NL@%
  3578.   %@AS@%            IF      @DataSize%@AE@%%@NL@%
  3579.   %@AS@%            lds     bx,Array            ; ds:bx = Array%@AE@%%@NL@%
  3580.   %@AS@%            ELSE%@AE@%%@NL@%
  3581.   %@AS@%            mov     bx,Array            ; bx = Array%@AE@%%@NL@%
  3582.   %@AS@%            ENDIF%@AE@%%@NL@%
  3583. %@NL@%
  3584. %@4@%%@CR:IX3.36      @%  The %@AB@%.MODEL%@AE@% directive operates on an undefined variable, %@AS@%mem%@AE@%. You define%@EH@%
  3585.   this variable on the QCL command line or in the Assembler Flags dialog
  3586.   box. For example, to assemble with QCL in compact model, enter the
  3587.   following text in the defines text box:%@NL@%
  3588. %@NL@%
  3589.   %@AS@%/Dmem=compact%@AE@%%@NL@%
  3590. %@NL@%
  3591. %@4@%%@CR:IX3.37      @%  The %@AB@%IF%@AE@%, %@AB@%ELSE%@AE@%, and %@AB@%ENDIF%@AE@% directives cause conditional assembly. The%@EH@%
  3592.   %@AB@%@DataSize%@AE@% predefined macro is equal to 1 (true) if the memory model uses
  3593.   far data pointers, and 0 (false) otherwise. The statement %@AS@%IF @DataSize%@AE@%
  3594.   begins a conditional-assembly block that assembles the %@AB@%LDS%@AE@% instruction if
  3595.   the memory model uses far data pointers; it assembles the %@AB@%MOV%@AE@% instruction
  3596.   otherwise.%@NL@%
  3597. %@NL@%
  3598. %@4@%  For more information on conditional assembly, see Chapter 10%@BO:       867d7@%, "Assembling%@EH@%
  3599.   Conditionally."%@NL@%
  3600. %@NL@%
  3601. %@4@%  The %@AB@%USES%@AE@% clause is retained for all memory models, since even with small%@EH@%
  3602.   model it does no harm. However, to increase efficiency, you may wish to
  3603.   include the %@AB@%PROC%@AE@% statement inside conditional-assembly blocks.%@NL@%
  3604. %@NL@%
  3605. %@NL@%
  3606. %@3@%%@CR:SC3.4.2     @%%@AB@%3.4.2  Accessing Far Data through ES%@AE@%%@EH@%%@NL@%
  3607. %@NL@%
  3608. %@4@%  The %@AB@%LDS%@AE@% instruction is inconvenient if you need to access items in the%@EH@%
  3609.   default data segment, because you have no guarantee that DS still points
  3610.   to that area of memory. Therefore, it's sometimes more efficient to leave
  3611.   DS alone and use the ES register to access far data.%@NL@%
  3612. %@NL@%
  3613. %@4@%%@CR:IX3.38      @%%@CR:IX3.39      @%  The standard C memory models all use the %@AB@%LES%@AE@% instruction to access far%@EH@%
  3614.   data. You can also use this method, but it is not required, since it has
  3615.   no effect on the interface between modules. Give the %@AB@%LES%@AE@% instruction to
  3616.   load a far data pointer, which will load the ES register with the new
  3617.   segment address. Then give the ES override whenever you refer to data in
  3618.   the far segment. This method requires alteration of all instructions that
  3619.   access the string data:%@NL@%
  3620. %@NL@%
  3621.   %@AS@%            les     bx,Array            ; es:bx = Array%@AE@%%@NL@%
  3622.   %@AS@%            .%@AE@%%@NL@%
  3623.   %@AS@%            .%@AE@%%@NL@%
  3624.   %@AS@%            .%@AE@%%@NL@%
  3625.   %@AS@%            cmp     es:BYTE PTR [bx],0  ; Compare byte to NULL%@AE@%%@NL@%
  3626. %@NL@%
  3627. %@4@%  Once ES is loaded with the segment address of far data, access objects in%@EH@%
  3628.   the default data area (the segment containing near data) as you normally
  3629.   would. Use the ES override to access the far data.%@NL@%
  3630. %@NL@%
  3631. %@CR:IX3.40      @%%@NL@%
  3632. %@2@%%@CR:SC3.5       @%%@AB@%3.5  Hexadecimal Conversion Example%@AE@%%@EH@%%@NL@%
  3633. %@NL@%
  3634. %@4@%  The following example builds on the decimal example in Section 3.3%@BO:       2da0c@%,%@EH@%
  3635.   adding the additional logic needed to convert hexadecimal rather than
  3636.   decimal strings.%@NL@%
  3637. %@NL@%
  3638. %@4@%  Hexadecimal conversion can use an algorithm similar to the one used%@EH@%
  3639.   earlier for decimal conversion, with these adjustments made:%@NL@%
  3640. %@NL@%
  3641.   ■  The procedure multiplies the running total by 16, not 10.%@NL@%
  3642. %@NL@%
  3643.   ■  The procedure converts the letters A-F to numeric values, in addition
  3644.      to converting the numerals 0-9.%@NL@%
  3645. %@NL@%
  3646. %@4@%%@CR:IX3.41      @%%@CR:IX3.42      @%%@CR:IX3.43      @%%@CR:IX3.44      @%  You could make the first adjustment by loading CX with 16 instead of 10. A%@EH@%
  3647.   much more efficient method is to use the %@AB@%SHL%@AE@% (Shift Left) instruction to
  3648.   shift an object's bits left by four places. This effectively multiplies
  3649.   the object by 16.%@NL@%
  3650. %@NL@%
  3651. %@4@%  The second adjustment requires more complex logic. Hexadecimal digits can%@EH@%
  3652.   consist of either letters or numerals. The procedure must consider three
  3653.   different cases──one for each sequence of hexadecimal characters:%@NL@%
  3654. %@NL@%
  3655.   %@AB@%Range of Characters%@AE@% %@AB@%Conversion Required%@AE@%%@NL@%
  3656.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3657.   0-9                 Convert to face value. Subtract ASCII value of %@AS@%'0'%@AE@%.%@NL@%
  3658. %@NL@%
  3659.   A-F, and a-f        Convert to values 10-15. Convert all letters to
  3660.                       uppercase, then subtract ASCII value of %@AS@%'A'%@AE@% and add
  3661.                       10.%@NL@%
  3662. %@NL@%
  3663. %@NL@%
  3664. %@4@%%@CR:IX3.45      @%%@CR:IX3.46      @%%@CR:IX3.47      @%%@CR:IX3.48      @%  We convert all letters to uppercase in an optimized fashion by taking%@EH@%
  3665.   advantage of the ASCII coding sequence. Uppercase letters are coded as 41H
  3666.   onward. Lowercase letters are coded as 61H onward. Consequently, each
  3667.   lowercase letter differs from the corresponding uppercase letter by
  3668.   exactly one bit. We use the %@AB@%AND%@AE@% instruction, with the immediate operand
  3669.   0DFH, to mask out this bit. This operation has the effect of setting the
  3670.   third highest bit to 0.%@NL@%
  3671. %@NL@%
  3672.   %@AS@%         0110 0001  61h = 'a'     0100 0001  41h = 'A'%@AE@%%@NL@%
  3673.   %@AS@%AND      1101 1111  DFh           1101 1111  DFh%@AE@%%@NL@%
  3674.   %@AS@%         ======================   ======================%@AE@%%@NL@%
  3675.   %@AS@%result   0100 0001  41h = 'A'     0100 0001  41h = 'A'%@AE@%%@NL@%
  3676. %@NL@%
  3677.   %@AS@%         0110 0010  62h = 'b'     0100 0010  42h = 'B'%@AE@%%@NL@%
  3678.   %@AS@%AND      1101 1111  DFh           1101 1111  DFh%@AE@%%@NL@%
  3679.   %@AS@%         ======================   ======================%@AE@%%@NL@%
  3680.   %@AS@%result   0100 0010  42h = 'B'     0100 0010  42h = 'B'%@AE@%%@NL@%
  3681. %@NL@%
  3682. %@4@%  The beauty of the operation is that it converts lowercase letters to%@EH@%
  3683.   uppercase, but leaves uppercase letters alone. If the third highest bit is
  3684.   already 0 (as is the case with uppercase letters), doing an %@AB@%AND%@AE@% operation
  3685.   with 0DFH has no effect. This operation removes the need to handle
  3686.   lowercase letters as a separate case.%@NL@%
  3687. %@NL@%
  3688. %@4@%  The revised algorithm does the following:%@EH@%%@NL@%
  3689. %@NL@%
  3690.   %@AS@%initialize total to zero%@AE@%%@NL@%
  3691.   %@AS@%while there's another digit%@AE@%%@NL@%
  3692.   %@AS@%    move byte to temporary location%@AE@%%@NL@%
  3693.   %@AS@%    if ascii value < 'A'%@AE@%%@NL@%
  3694.   %@AS@%        Subtract '0'%@AE@%%@NL@%
  3695.   %@AS@%    else%@AE@%%@NL@%
  3696.   %@AS@%        Convert lowercase to uppercase%@AE@%%@NL@%
  3697.   %@AS@%        Subtract 'A'-10%@AE@%%@NL@%
  3698.   %@AS@%    add byte value to total%@AE@%%@NL@%
  3699.   %@AS@%    advance to next digit%@AE@%%@NL@%
  3700.   %@AS@%    if no more digits%@AE@%%@NL@%
  3701.   %@AS@%        we're done%@AE@%%@NL@%
  3702.   %@AS@%    else%@AE@%%@NL@%
  3703.   %@AS@%        shift total left by four bits%@AE@%%@NL@%
  3704. %@NL@%
  3705. %@4@%  The assembly-language code below implements this algorithm. The code tests%@EH@%
  3706.   for each range, performing a different conversion for each case. Note the
  3707.   use of %@AB@%JB%@AE@% (Jump If Below), which jumps to the specified label if the
  3708.   previous comparison or subtraction produced a negative value──that is, if
  3709.   the first operand is less than the second.%@NL@%
  3710. %@NL@%
  3711.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  3712.   %@AS@%            .CODE%@AE@%%@NL@%
  3713. %@NL@%
  3714.   %@AS@%hextoint    PROC    Array:PTR BYTE%@AE@%%@NL@%
  3715. %@NL@%
  3716.   %@AS@%            sub     ax,ax             ; ax = 0%@AE@%%@NL@%
  3717.   %@AS@%            mov     bx,Array          ; bx = Array%@AE@%%@NL@%
  3718.   %@AS@%            mov     cl,4              ; Prepare to shift left by 4%@AE@%%@NL@%
  3719.   %@AS@%            sub     dx,dx             ; dx = 0%@AE@%%@NL@%
  3720.   %@AS@%            cmp     BYTE PTR [bx],0   ; Compare byte to NULL%@AE@%%@NL@%
  3721.   %@AS@%            je      done              ; if byte=0 we're done%@AE@%%@NL@%
  3722.   %@AS@%top:%@AE@%%@NL@%
  3723.   %@AS@%            mov     dl,BYTE PTR [bx]  ; Move byte to DL%@AE@%%@NL@%
  3724.   %@AS@%            cmp     dl,'A'            ; ASCII value >= 'A'?%@AE@%%@NL@%
  3725.   %@AS@%            jae     isletter          ; If so, goto isletter%@AE@%%@NL@%
  3726.   %@AS@%            sub     dl,'0'            ; Convert ascii to numeric%@AE@%%@NL@%
  3727.   %@AS@%            jmp     addbyte           ; Go add value of byte%@AE@%%@NL@%
  3728.   %@AS@%isletter:%@AE@%%@NL@%
  3729.   %@AS@%            and     dl,0DFh           ; Convert to uppercase%@AE@%%@NL@%
  3730.   %@AS@%            sub     dl,'A'-10         ; Convert ascii to numeric%@AE@%%@NL@%
  3731.   %@AS@%addbyte:%@AE@%%@NL@%
  3732.   %@AS@%            add     ax,dx             ; Add value to total%@AE@%%@NL@%
  3733.   %@AS@%            inc     bx                ; Point to next byte%@AE@%%@NL@%
  3734.   %@AS@%            cmp     BYTE PTR [bx],0   ; Compare byte to NULL%@AE@%%@NL@%
  3735.   %@AS@%            je      done              ; If byte=0 we're done%@AE@%%@NL@%
  3736.   %@AS@%            shl     ax,cl             ; AX = AX * 16%@AE@%%@NL@%
  3737.   %@AS@%            jmp     SHORT top         ; Goto top of loop%@AE@%%@NL@%
  3738.   %@AS@%done:%@AE@%%@NL@%
  3739.   %@AS@%            ret%@AE@%%@NL@%
  3740.   %@AS@%hextoint    ENDP%@AE@%%@NL@%
  3741.   %@AS@%            END%@AE@%%@NL@%
  3742. %@NL@%
  3743. %@4@%%@CR:IX3.49      @%%@CR:IX3.50      @%%@CR:IX3.51      @%%@CR:IX3.52      @%  The beginning of the procedure initializes the CL register to %@AS@%4%@AE@%. This step%@EH@%
  3744.   is necessary, because you can use the %@AB@%SHL%@AE@% instruction (Shift Left) in only
  3745.   two ways: you can shift by exactly one bit, or you can shift by the number
  3746.   of places indicated in CL. Clearly, using CL is more efficient than a
  3747.   sequence of four shift instructions.%@NL@%
  3748. %@NL@%
  3749. %@4@%  The main loop reads a character, tests it, and makes one basic decision:%@EH@%
  3750.   is the character a letter or not? This test takes advantage of the ASCII
  3751.   coding sequence. If the value of the character is equal to or greater than
  3752.   %@AS@%'A'%@AE@%, it cannot be one of the digits 0-9. The procedure uses the %@AB@%JAE%@AE@%
  3753.   instruction (Jump If Above or Equal) to test for this condition.%@NL@%
  3754. %@NL@%
  3755.   %@AS@%top:%@AE@%%@NL@%
  3756.   %@AS@%            mov     dl,BYTE PTR [bx]  ; Move byte to DL%@AE@%%@NL@%
  3757.   %@AS@%            cmp     dl,'a'            ; ASCII value >= 'A'?%@AE@%%@NL@%
  3758.   %@AS@%            jae     isletter          ; If so, goto isletter%@AE@%%@NL@%
  3759. %@NL@%
  3760. %@4@%  If the character is a letter, the procedure first converts the letter to%@EH@%
  3761.   uppercase──using an %@AB@%AND%@AE@% instruction that converts lowercase letters but
  3762.   leaves uppercase letters unchanged. The following instruction can then
  3763.   properly handle all letters the same way, regardless of their original
  3764.   case:%@NL@%
  3765. %@NL@%
  3766.   %@AS@%isletter:%@AE@%%@NL@%
  3767.   %@AS@%            and     dl,0DFh           ; Convert to uppercase%@AE@%%@NL@%
  3768.   %@AS@%            sub     dl,'A'-10         ; Convert ascii to numeric%@AE@%%@NL@%
  3769. %@NL@%
  3770. %@4@%  For simplicity, the procedure accepts invalid letters. You could easily%@EH@%
  3771.   enhance it to verify that the letters are hexadecimal.%@NL@%
  3772. %@NL@%
  3773. %@NL@%
  3774. %@NL@%
  3775. ────────────────────────────────────────────────────────────────────────────%@NL@%
  3776. %@1@%%@CR:CH4         @%%@AB@%Chapter 4:  Writing Stand-Alone Assembly Programs%@AE@%%@EH@%%@NL@%
  3777. %@NL@%
  3778. %@NL@%
  3779. %@4@%%@CR:IX4.1       @%  With QuickAssembler, you can write stand-alone assembly programs to%@EH@%
  3780.   produce small, efficient utilities. For example, you might write a utility
  3781.   in assembly language to count the number of lines or paragraphs in a file.
  3782.   These programs start and end with assembly code and generally do not
  3783.   involve any links to high-level languages.%@NL@%
  3784. %@NL@%
  3785. %@4@%  Stand-alone assembly programs can yield remarkably small .EXE files. They%@EH@%
  3786.   require relatively little space, because they do not include the start-up
  3787.   code for a high-level language. And often you can make your assembly
  3788.   program even smaller by converting it to a .COM file as shown in this
  3789.   chapter. Some useful .COM files take up less than 100 bytes of memory.%@NL@%
  3790. %@NL@%
  3791. %@4@%  This chapter first describes the directives you need to write stand-alone%@EH@%
  3792.   assembly programs, reviews instructions used in the chapter's examples,
  3793.   and then presents a simple stand-alone program. Next, Sections 4.4%@BO:       3817c@%-4.6
  3794.   look closely at each segment of the program: stack, data, and code.
  3795.   Finally, the chapter describes how to create a program in the .COM format.%@NL@%
  3796. %@NL@%
  3797. %@NL@%
  3798. %@2@%%@CR:SC4.1       @%%@AB@%4.1  A Skeleton for Stand-Alone Programs%@AE@%%@EH@%%@NL@%
  3799. %@NL@%
  3800. %@4@%  This chapter uses the simplified segment directives described in the%@EH@%
  3801.   previous chapter, and introduces three more directives──%@AB@%.STACK%@AE@%, %@AB@%.DATA%@AE@%, and
  3802.   %@AB@%.STARTUP%@AE@%. The simplified segment directives produce programs using the
  3803.   Microsoft standard segment format.%@NL@%
  3804. %@NL@%
  3805. %@4@%  This format is not required, since your stand-alone program need not be%@EH@%
  3806.   compatible with a high-level-language module. However, the standard format
  3807.   is convenient because you can specify a number of different memory models,
  3808.   and you are freed from having to specify segment names, attributes, and
  3809.   register assumptions.%@NL@%
  3810. %@NL@%
  3811.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3812.   %@AB@%NOTE%@AE@%  Occasionally, you may need a customized segment structure. Linking
  3813.   assembly code to a non-Microsoft language is the most common situation
  3814.   that requires customized segments. QuickAssembler lets you use full
  3815.   segment definitions any time you need to customize segments. However, you
  3816.   should find that simplified segment directives support the vast majority
  3817.   of assembly-language programming you do──even when you write .COM files.%@NL@%
  3818.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3819. %@NL@%
  3820. %@4@%  The skeleton for the programs in this chapter includes a stack, data, and%@EH@%
  3821.   code segment. Note that one of the directives, %@AB@%.MODEL%@AE@%, will change when
  3822.   you alter the memory model. The other statements remain the same.%@NL@%
  3823. %@NL@%
  3824.   %@AS@%            .MODEL   small               ; Use small memory model%@AE@%%@NL@%
  3825. %@NL@%
  3826.   %@AS@%            .STACK   100h                ; Declare 256-byte stack%@AE@%%@NL@%
  3827. %@NL@%
  3828.   %@AS@%            .DATA%@AE@%%@NL@%
  3829.   %@AS@%;%@AE@%%@NL@%
  3830.   %@AS@%;    (place data declarations here)%@AE@%%@NL@%
  3831.   %@AS@%;%@AE@%%@NL@%
  3832.   %@AS@%            .CODE%@AE@%%@NL@%
  3833.   %@AS@%            .STARTUP                     ; Set up DS, SS, and SP registers%@AE@%%@NL@%
  3834.   %@AS@%;%@AE@%%@NL@%
  3835.   %@AS@%;    (place executable code here)%@AE@%%@NL@%
  3836.   %@AS@%;%@AE@%%@NL@%
  3837.   %@AS@%            END%@AE@%%@NL@%
  3838. %@NL@%
  3839. %@4@%  Sections 4.1.1%@BO:       35c29@%-4.1.3 examine each of the statements in this skeleton more%@EH@%
  3840.   closely.%@NL@%
  3841. %@NL@%
  3842. %@NL@%
  3843. %@3@%%@CR:SC4.1.1     @%%@AB@%4.1.1  The .MODEL Directive%@AE@%%@EH@%%@NL@%
  3844. %@NL@%
  3845. %@4@%  The %@AB@%.MODEL%@AE@% directive performs the same role that it did in the previous%@EH@%
  3846.   chapter; it defines the overall attributes of the module. Note, however,
  3847.   that with a stand-alone program, a language type is not always required. A
  3848.   language type is useful when a module contains one or more procedures.
  3849.   Otherwise, you need only type %@AB@%.MODEL%@AE@% followed by a memory model:%@NL@%
  3850. %@NL@%
  3851.   %@AS@%            .MODEL   small               ; Use small memory model%@AE@%%@NL@%
  3852. %@NL@%
  3853. %@4@%  The memory model can be %@AB@%TINY%@AE@%, %@AB@%SMALL%@AE@%, %@AB@%MEDIUM%@AE@%, %@AB@%COMPACT%@AE@%, %@AB@%LARGE%@AE@%, or %@AB@%HUGE%@AE@%. Most%@EH@%
  3854.   of these memory models may be familiar to you if you have used QuickC. For
  3855.   a complete description of each memory model, see Section 5.1.1%@BO:       40c7f@%.%@NL@%
  3856. %@NL@%
  3857. %@4@%  The %@AB@%TINY%@AE@% memory model is new; it alone results in the creation of a .COM%@EH@%
  3858.   file rather than a .EXE file. Section 4.8%@BO:       3c62a@%, "Creating .COM Files," gives a
  3859.   complete example featuring the use of tiny memory model.%@NL@%
  3860. %@NL@%
  3861. %@4@%  Generally, to change memory model you change the %@AB@%.MODEL%@AE@% directive. You%@EH@%
  3862.   also change the way you load and use data pointers, as described in
  3863.   Chapter 3%@BO:       2aca0@%, "Writing Assembly Modules for C Programs." With these changes
  3864.   made, many programs can readily be reassembled for a new memory model.
  3865.   (However, as you'll see in Chapter 5%@BO:       3ffad@%, "Defining Segment Structure," you
  3866.   cannot use %@AB@%.FARDATA%@AE@% segments in tiny, small, or medium model, and this may
  3867.   require further revision of code in some cases.)%@NL@%
  3868. %@NL@%
  3869. %@NL@%
  3870. %@3@%%@CR:SC4.1.2     @%%@AB@%4.1.2  The .STACK, .CODE, and .DATA Directives%@AE@%%@EH@%%@NL@%
  3871. %@NL@%
  3872. %@4@%%@CR:IX4.2       @%%@CR:IX4.3       @%  Each of the segment directives──%@AB@%.STACK%@AE@%, %@AB@%.CODE%@AE@%, and %@AB@%.DATA%@AE@%──declares the%@EH@%
  3873.   beginning of a segment.%@NL@%
  3874. %@NL@%
  3875. %@4@%  The code and data segments begin with %@AB@%.CODE%@AE@% and %@AB@%.DATA%@AE@%, respectively. Each%@EH@%
  3876.   of these segments continues to the next segment directive or the end of
  3877.   the program. The data segment contains data and symbolic constant
  3878.   declarations. The code segment contains instructions.%@NL@%
  3879. %@NL@%
  3880. %@4@%  However, the stack segment consists of only one line:%@EH@%%@NL@%
  3881. %@NL@%
  3882. %@4@%  %@AB@%.STACK%@AE@% [[%@AI@%size%@AE@%]]%@EH@%%@NL@%
  3883. %@NL@%
  3884. %@4@%%@CR:IX4.4       @%%@CR:IX4.5       @%%@CR:IX4.6       @%%@CR:IX4.7       @%  By default, QuickAssembler interprets %@AI@%size%@AE@% according to the current radix,%@EH@%
  3885.   which by default is decimal. You can specify a hexadecimal constant by
  3886.   using the H suffix. (Example: %@AS@%200h%@AE@%.) The %@AI@%size%@AE@% argument is optional. If you
  3887.   leave it out, the assembler creates a stack 1024 bytes long.%@NL@%
  3888. %@NL@%
  3889. %@4@%  Unless the program is written in tiny memory model, you should always%@EH@%
  3890.   declare a stack segment in your main module. Section 4.4%@BO:       3817c@%, "Inside the
  3891.   Stack Segment," explains the purpose of this segment.%@NL@%
  3892. %@NL@%
  3893. %@NL@%
  3894. %@3@%%@CR:SC4.1.3     @%%@AB@%4.1.3  The .STARTUP Directive%@AE@%%@EH@%%@NL@%
  3895. %@NL@%
  3896. %@4@%%@CR:IX4.8       @%%@CR:IX4.9       @%  Unlike C programs, assembly-language programs have to initialize register%@EH@%
  3897.   values. Specifically, the program has to initialize DS, the Data Segment
  3898.   register; CS and IP, which point to the first instruction to execute; and
  3899.   SS and SP, the stack registers.%@NL@%
  3900. %@NL@%
  3901. %@4@%  By far the easiest way to initialize all these registers is to just%@EH@%
  3902.   include %@AB@%.STARTUP%@AE@%, a simple directive that takes no arguments:%@NL@%
  3903. %@NL@%
  3904.   %@AS@%            .STARTUP         ; Set up DS, SS, and SP registers%@AE@%%@NL@%
  3905. %@NL@%
  3906. %@4@%  When you use this directive, the assembler generates code to initialize%@EH@%
  3907.   your registers the way Microsoft high-level languages do. The generated
  3908.   code is similar to some of the instructions in the C start-up code. The
  3909.   directive takes care of minimal start-up, but many programs will need to
  3910.   do additional start-up tasks, such as releasing unused memory.%@NL@%
  3911. %@NL@%
  3912.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3913.   %@AB@%NOTE%@AE@%  The start-up sequence adjusts SS and SP so that SS is equal to DS.
  3914.   This starting condition gives you some advantages. If you later have to
  3915.   alter the value of DS, you can always access a data object as an indirect
  3916.   operand using BP, or through an SS segment override. To avoid this
  3917.   starting sequence, so that the stack and data are separate physical
  3918.   segments, use the %@AB@%farStack%@AE@% keyword with the %@AB@%.MODEL %@AE@%directive, as described
  3919.   in Section 5.1.3%@BO:       42b44@%.%@NL@%
  3920.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3921. %@NL@%
  3922. %@NL@%
  3923. %@2@%%@CR:SC4.2       @%%@AB@%4.2  Instructions Used in This Chapter%@AE@%%@EH@%%@NL@%
  3924. %@NL@%
  3925. %@4@%  This section summarizes the instructions used in this chapter. Because the%@EH@%
  3926.   program examples are simple, only a very few of the 80-odd instructions of
  3927.   the 8086 are featured here.%@NL@%
  3928. %@NL@%
  3929. %@4@%  This chapter features four instructions:%@EH@%%@NL@%
  3930. %@NL@%
  3931.   %@AB@%Instruction%@AE@%         %@AB@%Description%@AE@%%@NL@%
  3932.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  3933.   %@AB@%MOV%@AE@% %@AI@%destination%@AE@%,    Moves %@AI@%source%@AE@% to %@AI@%destination%@AE@%
  3934.   %@AI@%source%@AE@%%@NL@%
  3935.   %@AB@%INT%@AE@% %@AI@%number%@AE@%          Generates the indicated interrupt signal, causing
  3936.                       processor to call a memory-resident interrupt routine%@NL@%
  3937. %@NL@%
  3938.   %@AB@%DEC%@AE@% %@AI@%destination%@AE@%     Decrement──subtracts 1 from %@AI@%destination%@AE@%%@NL@%
  3939. %@NL@%
  3940.   %@AB@%JNZ%@AE@% %@AI@%label%@AE@%           Jump If Not Zero──jumps to %@AI@%label%@AE@% if result of last
  3941.                       operation was not zero%@NL@%
  3942. %@NL@%
  3943. %@NL@%
  3944. %@4@%  Most of the instructions above were introduced in Chapter 2%@BO:       151ff@%, "Introducing%@EH@%
  3945.   8086 Assembly Language." The new instruction is %@AB@%INT%@AE@%.%@NL@%
  3946. %@NL@%
  3947. %@4@%%@CR:IX4.10      @%%@CR:IX4.11      @%%@CR:IX4.12      @%  The %@AB@%INT%@AE@% instruction generates a software interrupt signal, causing the%@EH@%
  3948.   processor to call an interrupt service routine usually residing in a DOS
  3949.   or ROM-BIOS memory area. This call is much like a procedure call; the
  3950.   processor executes a specific function and returns to the program when the
  3951.   routine is complete.%@NL@%
  3952. %@NL@%
  3953. %@4@%  There are two major differences between an interrupt call and a procedure%@EH@%
  3954.   call. First, instead of calling a procedure you have written, an %@AB@%INT%@AE@%
  3955.   instruction calls a DOS system routine or ROM-BIOS service. These
  3956.   low-level routines carry out a variety of basic operations, such as
  3957.   reading the keyboard, writing to the screen, or using the file system.
  3958.   Most DOS services are accessed through interrupt 21H (33 decimal).%@NL@%
  3959. %@NL@%
  3960. %@4@%  The second major difference is syntactic. You follow the %@AB@%INT%@AE@% keyword by an%@EH@%
  3961.   interrupt number (in the range 0 to 255), rather than a procedure name. In
  3962.   many cases, you further specify the interrupt routine by loading AH with a
  3963.   function number.%@NL@%
  3964. %@NL@%
  3965. %@NL@%
  3966. %@2@%%@CR:SC4.3       @%%@AB@%4.3  A Program That Says Hello%@AE@%%@EH@%%@NL@%
  3967. %@NL@%
  3968. %@4@%  The following sample program prints %@AS@%Hello world %@AE@%and then successfully%@EH@%
  3969.   exits back to DOS. You can use this program as a template and insert your
  3970.   own code and data.%@NL@%
  3971. %@NL@%
  3972.   %@AS@%            .MODEL  small                ; Use small model%@AE@%%@NL@%
  3973. %@NL@%
  3974.   %@AS@%            .STACK  100h                 ; Allocate 256-byte stack%@AE@%%@NL@%
  3975. %@NL@%
  3976.   %@AS@%            .DATA%@AE@%%@NL@%
  3977.   %@AS@%message     DB    "Hello, world.",13,10  ; Message to print%@AE@%%@NL@%
  3978.   %@AS@%lmessage    EQU   $ - message            ; Determine length of message%@AE@%%@NL@%
  3979.   %@AS@%            .CODE%@AE@%%@NL@%
  3980.   %@AS@%            .STARTUP                     ; Use standard startup code%@AE@%%@NL@%
  3981. %@NL@%
  3982.   %@AS@%            mov   bx,1                   ; Load 1 - file handle%@AE@%
  3983.   %@AS@%                                         ;   for standard output%@AE@%%@NL@%
  3984.   %@AS@%            mov   cx,lmessage            ; Load length of message%@AE@%%@NL@%
  3985.   %@AS@%            mov   dx,OFFSET message      ; Load address of message%@AE@%%@NL@%
  3986.   %@AS@%            mov   ah,40h                 ; Load no. of DOS Write function%@AE@%%@NL@%
  3987.   %@AS@%            int   21h                    ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  3988. %@NL@%
  3989.   %@AS@%            mov   ax,4c00h               ; Load no. of DOS Exit function%@AE@%%@NL@%
  3990.   %@AS@%                                         ;   in AH, and 0 exit code in AL%@AE@%%@NL@%
  3991.   %@AS@%            int   21h                    ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  3992. %@NL@%
  3993.   %@AS@%            END%@AE@%%@NL@%
  3994. %@NL@%
  3995. %@4@%  The first statement determines the memory model of the program:%@EH@%%@NL@%
  3996. %@NL@%
  3997.   %@AS@%            .MODEL  small                ; Use small model%@AE@%%@NL@%
  3998. %@NL@%
  3999. %@4@%  This statement specifies small memory model, which places code and data in%@EH@%
  4000.   two separate segments, each of which cannot exceed 64K.%@NL@%
  4001. %@NL@%
  4002. %@4@%  The next few sections consider the rest of this program──stack, data, and%@EH@%
  4003.   code.%@NL@%
  4004. %@NL@%
  4005. %@NL@%
  4006. %@2@%%@CR:SC4.4       @%%@AB@%4.4  Inside the Stack Segment%@AE@%%@EH@%%@NL@%
  4007. %@NL@%
  4008. %@4@%%@CR:IX4.13      @%%@CR:IX4.14      @%  The stack segment is the easiest to create, because with simplified%@EH@%
  4009.   segment directives you enter only one statement:%@NL@%
  4010. %@NL@%
  4011.   %@AS@%            .STACK  100h                  ; Allocate 256-byte stack%@AE@%%@NL@%
  4012. %@NL@%
  4013. %@4@%  Each processor or interrupt call uses up stack space. The stack stores%@EH@%
  4014.   return addresses, parameters, and local variables for each procedure
  4015.   called. When a procedure or interrupt routine returns, the stack space it
  4016.   used is restored. The more procedure calls your program makes without
  4017.   returning, the more stack area it requires. Programs that nest many
  4018.   procedures or use recursion (in which a procedure calls itself repeatedly)
  4019.   may require large stacks. Unfortunately, there is no formula for
  4020.   determining how large a stack is needed.%@NL@%
  4021. %@NL@%
  4022. %@4@%  A 256-byte stack (100 hexadecimal) is adequate for most small programs.%@EH@%
  4023.   For this sample program, which makes one interrupt call but no procedure
  4024.   calls, 256 bytes provides an ample margin of error.%@NL@%
  4025. %@NL@%
  4026. %@4@%  You can also create a stack by using full segment definitions. See Section%@EH@%
  4027.   5.2%@BO:       4b9a0@%, "Full Segment Definitions," for more information.%@NL@%
  4028. %@NL@%
  4029. %@NL@%
  4030. %@2@%%@CR:SC4.5       @%%@AB@%4.5  Inside the Data Segment%@AE@%%@EH@%%@NL@%
  4031. %@NL@%
  4032. %@4@%%@CR:IX4.15      @%  A single keyword declares the beginning of the segment:%@EH@%%@NL@%
  4033. %@NL@%
  4034.   %@AS@%            .DATA%@AE@%%@NL@%
  4035. %@NL@%
  4036. %@4@%  QuickAssembler considers all statements following this line to lie in the%@EH@%
  4037.   data segment, up until the next segment declaration or %@AB@%END%@AE@% directive. The
  4038.   %@AB@%END%@AE@% directive marks the end of the source file.%@NL@%
  4039. %@NL@%
  4040. %@4@%%@CR:IX4.16      @%%@CR:IX4.17      @%  The next two statements are directives that declare a string of characters%@EH@%
  4041.   and a symbolic constant:%@NL@%
  4042. %@NL@%
  4043.   %@AS@%message     DB     "Hello, world.",13,10  ; Message to print%@AE@%%@NL@%
  4044.   %@AS@%lmessage    EQU    $ - message            ; Determine length of message%@AE@%%@NL@%
  4045. %@NL@%
  4046. %@4@%%@CR:IX4.18      @%%@CR:IX4.19      @%  The first statement above declares a series of bytes. The label %@AS@%message %@AE@%is%@EH@%
  4047.   a symbolic name that QuickAssembler associates with the string's starting
  4048.   address.%@NL@%
  4049. %@NL@%
  4050. %@4@%  The assembler allocates 15 bytes in the data segment, and initializes%@EH@%
  4051.   these bytes to the ASCII values for %@AS@%H%@AE@%, %@AS@%e%@AE@%, %@AS@%l%@AE@%, %@AS@%l%@AE@%, %@AS@%o%@AE@%, and so forth. The
  4052.   values %@AS@%13 %@AE@%and %@AS@%10 %@AE@%indicate a carriage return and line feed, respectively,
  4053.   causing the program to move the cursor to the beginning of the next line
  4054.   when it prints the string.%@NL@%
  4055. %@NL@%
  4056. %@4@%  The second directive in the data segment declares a symbolic constant%@EH@%
  4057.   equal to the length of the string:%@NL@%
  4058. %@NL@%
  4059.   %@AS@%lmessage    EQU    $ - message            ; Determine length of message%@AE@%%@NL@%
  4060. %@NL@%
  4061. %@4@%%@CR:IX4.20      @%%@CR:IX4.21      @%  Again, the item in the first column, %@AS@%lmessage%@AE@%, is the label of the%@EH@%
  4062.   statement. The %@AB@%EQU%@AE@% directive equates the label with the value of the
  4063.   operand itself. %@AB@%EQU%@AE@% does not allocate memory.%@NL@%
  4064. %@NL@%
  4065. %@4@%  The operand field contains %@AS@%$ - message%@AE@%, which in this case equals 15. We%@EH@%
  4066.   could just as easily have entered 15 in the operand field. However, the
  4067.   item %@AS@%$ - message%@AE@% is guaranteed to be equal to the length of the string,
  4068.   even if you later rewrite the initial string value.%@NL@%
  4069. %@NL@%
  4070. %@4@%%@CR:IX4.22      @%%@CR:IX4.23      @%  The dollar sign (%@AS@%$%@AE@%) is the "location counter," which represents the%@EH@%
  4071.   current address of the statement. QuickAssembler translates the full
  4072.   expression as "Take the current address (%@AS@%$%@AE@%) and subtract the address of
  4073.   %@AS@%message%@AE@%." The current address is one byte after the end of the string.
  4074.   Thus, %@AS@%$ - message %@AE@%is automatically equal to the length of the string.%@NL@%
  4075. %@NL@%
  4076. %@NL@%
  4077. %@2@%%@CR:SC4.6       @%%@AB@%4.6  Inside the Code Segment%@AE@%%@EH@%%@NL@%
  4078. %@NL@%
  4079. %@4@%%@CR:IX4.24      @%  A single keyword declares the beginning of the code segment:%@EH@%%@NL@%
  4080. %@NL@%
  4081.   %@AS@%            .CODE%@AE@%%@NL@%
  4082. %@NL@%
  4083. %@4@%%@CR:IX4.25      @%  The code segment consists of all statements between %@AB@%.CODE%@AE@% and the %@AB@%END%@AE@%%@EH@%
  4084.   statement, which marks the end of the source code. In this example, all
  4085.   the statements in the code segment, aside from %@AB@%.STARTUP%@AE@%, are instructions.%@NL@%
  4086. %@NL@%
  4087. %@4@%  The program has three basic tasks. Each instruction helps carry out one of%@EH@%
  4088.   these operations:%@NL@%
  4089. %@NL@%
  4090.   1. Initialize registers%@NL@%
  4091. %@NL@%
  4092.   2. Call a DOS function to print the message%@NL@%
  4093. %@NL@%
  4094.   3. Call a DOS function to exit the program gracefully%@NL@%
  4095. %@NL@%
  4096. %@4@%%@CR:IX4.26      @%%@CR:IX4.27      @%  The %@AB@%.STARTUP%@AE@% directive initializes registers. If you write a main module%@EH@%
  4097.   without this directive, you must explicitly initialize DS, CS, and IP.
  4098.   Furthermore, if you want SS to equal DS (which gives some programming
  4099.   advantages), you must adjust both SS and SP.%@NL@%
  4100. %@NL@%
  4101. %@4@%  To see how to initialize registers without the use of %@AB@%.STARTUP%@AE@%, see%@EH@%
  4102.   Chapter 5%@BO:       3ffad@%, "Defining Segment Structure."%@NL@%
  4103. %@NL@%
  4104. %@4@%  After registers are initialized, a series of five instructions makes the%@EH@%
  4105.   call to DOS that prints the message:%@NL@%
  4106. %@NL@%
  4107.   %@AS@%            mov   bx,1                   ; Load 1 - file handle for%@AE@%%@NL@%
  4108.   %@AS@%                                         ;   standard output%@AE@%%@NL@%
  4109.   %@AS@%            mov   cx,lmessage            ; Load length of message%@AE@%%@NL@%
  4110.   %@AS@%            mov   dx,OFFSET message      ; Load address of message%@AE@%%@NL@%
  4111.   %@AS@%            mov   ah,40h                 ; Load no. of DOS Write function%@AE@%%@NL@%
  4112.   %@AS@%            int   21h                    ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  4113. %@NL@%
  4114. %@4@%%@CR:IX4.28      @%%@CR:IX4.29      @%  The first four instructions prepare for the DOS call. Interrupt calls%@EH@%
  4115.   generally use registers to receive parameters. Unlike procedure calls,
  4116.   they do not reference the stack for this information. The DOS Write
  4117.   function uses the following registers to receive data:%@NL@%
  4118. %@NL@%
  4119.   %@AB@%Register%@AE@%            %@AB@%Data%@AE@%%@NL@%
  4120.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4121.   AH                  Selects the DOS function. 40H is the Write function.%@NL@%
  4122. %@NL@%
  4123.   BX                  File handle to which to write. The number 1 is a
  4124.                       reserved file handle that always corresponds to
  4125.                       standard output. "Standard output" is normally
  4126.                       synonymous with the computer screen, unless you
  4127.                       redirect program output. If you were writing to a
  4128.                       file, you would first open the file and use the file
  4129.                       handle returned by the DOS open-file function.%@NL@%
  4130. %@NL@%
  4131. %@CR:IX4.30      @%%@CR:IX4.31      @%  CX                  Length of the message. The second statement in the
  4132.                       data segment determined this length.%@NL@%
  4133. %@NL@%
  4134.   DS:DX               The beginning address of the actual message text.
  4135.                       Remember that DS was loaded earlier with the address
  4136.                       of the data segment, so it does not need to be
  4137.                       reloaded now.%@NL@%
  4138. %@NL@%
  4139. %@NL@%
  4140. %@4@%  This procedure uses the %@AB@%OFFSET%@AE@% operator to load DX with the address of the%@EH@%
  4141.   message. Although variables are translated to addresses, the processor
  4142.   normally interprets a variable address as a memory operand──that is, the
  4143.   processor operates on the data at the address, not the address itself.%@NL@%
  4144. %@NL@%
  4145. %@4@%  The %@AB@%OFFSET%@AE@% operator extracts the offset portion of the address and turns%@EH@%
  4146.   it into an immediate operand. If the %@AB@%OFFSET%@AE@% operator was not used the DOS
  4147.   routine would not receive the address of %@AS@%message%@AE@%, but would instead
  4148.   receive the value of the first byte. The %@AB@%OFFSET%@AE@% operator is similar to the
  4149.   address operator (%@AB@%&%@AE@%) in C. Use it whenever you need to pass an address
  4150.   rather than a value.%@NL@%
  4151. %@NL@%
  4152. %@4@%  After the interrupt service returns, the AX register contains the number%@EH@%
  4153.   of bytes written. The programs in this chapter do not use this return
  4154.   value, but a more sophisticated program might. In particular, if AX
  4155.   (number of bytes written) is less than CX (number of bytes requested to be
  4156.   written), then an error has occurred.%@NL@%
  4157. %@NL@%
  4158. %@4@%  Each DOS function has its own conventions for receiving data in different%@EH@%
  4159.   registers. Consult the %@AI@%Microsoft%@AE@% %@AI@%MS-DOS%@AE@% %@AI@%Programmer's%@AE@% %@AI@%Reference%@AE@% for a
  4160.   complete description of each function. The Assembler Contents selection
  4161.   from the Help menu also describes the major DOS functions.%@NL@%
  4162. %@NL@%
  4163.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4164.   %@AB@%NOTE%@AE@%  Each DOS function has conventions for getting and returning values
  4165.   in registers and flags. Bear in mind that values placed in any of these
  4166.   registers may change. If you need to preserve register values before
  4167.   making a DOS call, use the %@AB@%PUSH%@AE@% and %@AB@%POP%@AE@% instructions. See Section 13.4.1%@BO:       ab441@%,
  4168.   "Pushing and Popping," for more information on how to preserve register
  4169.   values.%@NL@%
  4170.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4171. %@NL@%
  4172. %@4@%  The%@AB@% INT%@AE@% instruction makes the actual call to DOS. The interrupt number for%@EH@%
  4173.   the majority of DOS functions is 21H. You use different interrupt numbers
  4174.   to call ROM-BIOS services.%@NL@%
  4175. %@NL@%
  4176. %@4@%  The final two instructions cause the program to terminate operation and%@EH@%
  4177.   return control to DOS. High-level language programmers can ignore the need
  4178.   to exit a program explicitly, if they like. But when you write a
  4179.   stand-alone assembly program, you don't have this luxury. The program must
  4180.   exit explicitly. Otherwise, the processor continues to execute random
  4181.   instructions after the end of the program, making the system appear to
  4182.   crash.%@NL@%
  4183. %@NL@%
  4184. %@4@%%@CR:IX4.32      @%%@CR:IX4.33      @%%@CR:IX4.34      @%%@CR:IX4.35      @%%@CR:IX4.36      @%%@CR:IX4.37      @%  The DOS Exit function (service 4CH) is the preferred method for exiting%@EH@%
  4185.   back to DOS. This function uses two register values:%@NL@%
  4186. %@NL@%
  4187. %@CR:IX4.38      @%%@CR:IX4.39      @%%@CR:IX4.40      @%  %@AB@%Register%@AE@%            %@AB@%Data%@AE@%%@NL@%
  4188.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4189.   AH                  Selects the DOS function. 4CH is the Exit function.%@NL@%
  4190. %@NL@%
  4191.   AL                  Exit code. Batch files can use this exit code as an
  4192.                       "errorlevel" indicator. An exit code of 0 usually
  4193.                       indicates no error.%@NL@%
  4194. %@NL@%
  4195. %@NL@%
  4196. %@4@%  A single instruction loads both registers:%@EH@%%@NL@%
  4197. %@NL@%
  4198.   %@AS@%            mov   ax,4c00h                   ; Load number of DOS Exit function%@AE@%%@NL@%
  4199.   %@AS@%                                             ;   in AH, and 0 exit code in AL%@AE@%%@NL@%
  4200. %@NL@%
  4201. %@4@%  A single %@AB@%MOV%@AE@% instruction actually moves data into two registers──AH and%@EH@%
  4202.   AL. AH is loaded with 4CH, the function number for the DOS exit function,
  4203.   and AL is loaded with 0, an exit code indicating no error.%@NL@%
  4204. %@NL@%
  4205. %@4@%  Finally, another %@AB@%INT%@AE@% instruction calls DOS.%@EH@%%@NL@%
  4206. %@NL@%
  4207.   %@AS@%            int   21h                        ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  4208. %@NL@%
  4209. %@NL@%
  4210. %@2@%%@CR:SC4.7       @%%@AB@%4.7  Making the Program Repeat Itself%@AE@%%@EH@%%@NL@%
  4211. %@NL@%
  4212. %@4@%  Once you understand the template for writing stand-alone programs, you can%@EH@%
  4213.   alter the sample program given above and generate your own code. This
  4214.   section alters the sample program so that it prints out a different
  4215.   message, and prints it ten times.%@NL@%
  4216. %@NL@%
  4217. %@4@%  The new sample program is listed below:%@EH@%%@NL@%
  4218. %@NL@%
  4219.   %@AS@%            .MODEL  small                    ; Use small model%@AE@%%@NL@%
  4220. %@NL@%
  4221.   %@AS@%            .STACK  100h                     ; Allocate 256-byte stack%@AE@%%@NL@%
  4222. %@NL@%
  4223.   %@AS@%            .DATA%@AE@%%@NL@%
  4224.   %@AS@%message     DB    "Hello, ten times.",13,10  ; Message to print%@AE@%%@NL@%
  4225.   %@AS@%lmessage    EQU   $ - message                ; Determine length of message%@AE@%%@NL@%
  4226.   %@AS@%count       DW    10%@AE@%%@NL@%
  4227. %@AS@%%@AE@%%@NL@%
  4228.   %@AS@%            .CODE%@AE@%%@NL@%
  4229.   %@AS@%            .STARTUP                         ; Use standard startup code%@AE@%%@NL@%
  4230. %@NL@%
  4231.   %@AS@%            mov   bx,1                       ; Load 1 - file handle for%@AE@%%@NL@%
  4232.   %@AS@%                                             ;   standard output%@AE@%%@NL@%
  4233.   %@AS@%            mov   cx,lmessage                ; Load length of message%@AE@%%@NL@%
  4234.   %@AS@%            mov   dx,OFFSET message          ; Load address of message%@AE@%%@NL@%
  4235.   %@AS@%printit:    mov   ah,40h                     ; Load no. of DOS Write function%@AE@%%@NL@%
  4236.   %@AS@%            int   21h                        ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  4237. %@NL@%
  4238.   %@AS@%            dec   count                      ; count = count-1%@AE@%%@NL@%
  4239.   %@AS@%            jnz   printit                    ; if count > 0, print again%@AE@%%@NL@%
  4240. %@NL@%
  4241.   %@AS@%            mov   ax,4c00h                   ; Load DOS 4C function number%@AE@%%@NL@%
  4242.   %@AS@%                                             ;   in AH, and 0 exit code in AL%@AE@%%@NL@%
  4243.   %@AS@%            int   21h                        ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  4244. %@NL@%
  4245.   %@AS@%            END%@AE@%%@NL@%
  4246. %@NL@%
  4247. %@4@%  Note the following changes:%@EH@%%@NL@%
  4248. %@NL@%
  4249.   ■  The string data is different.%@NL@%
  4250. %@NL@%
  4251.   ■  The data segment includes a new variable, %@AS@%count%@AE@%.%@NL@%
  4252. %@NL@%
  4253.   ■  One of the instructions is now labeled %@AS@%printit%@AE@%.%@NL@%
  4254. %@NL@%
  4255.   ■  Two additional instructions decrement %@AS@%count%@AE@%, then loop back to the
  4256.      label %@AS@%printit %@AE@%if %@AS@%count %@AE@%is greater than zero.%@NL@%
  4257. %@NL@%
  4258. %@4@%  The string data is longer than before, and QuickAssembler must allocate%@EH@%
  4259.   more bytes than in the previous version of the program. However, the %@AB@%EQU%@AE@%
  4260.   statement that follows guarantees that the assembler still calculates
  4261.   string length correctly:%@NL@%
  4262. %@NL@%
  4263.   %@AS@%message     DB    "Hello, ten times.",13,10 ; Message to print%@AE@%%@NL@%
  4264.   %@AS@%lmessage    EQU   $ - message               ; Determine length of message%@AE@%%@NL@%
  4265. %@NL@%
  4266. %@4@%%@CR:IX4.41      @%%@CR:IX4.42      @%  The new variable is actually a memory location of word size (two bytes).%@EH@%
  4267.   QuickAssembler allocates another two bytes in the data segment, and
  4268.   initializes these bytes:%@NL@%
  4269. %@NL@%
  4270.   %@AS@%count       DW    10%@AE@%%@NL@%
  4271. %@NL@%
  4272. %@4@%  The label %@AS@%count %@AE@%becomes associated with the address of the data, and the%@EH@%
  4273.   number %@AS@%10 %@AE@%is the initial value placed at this memory location. However,
  4274.   the value can change.%@NL@%
  4275. %@NL@%
  4276. %@4@%  The instruction %@AS@%mov ah,40h %@AE@%now has a label, because the program needs to%@EH@%
  4277.   return here to repeat the print operation. Not all instructions need a
  4278.   label──only those that the program may need to jump to directly.%@NL@%
  4279. %@NL@%
  4280. %@4@%  The two new instructions cause the program to repeat the print operation%@EH@%
  4281.   ten times:%@NL@%
  4282. %@NL@%
  4283.   %@AS@%            dec   count                     ; count = count-1%@AE@%%@NL@%
  4284.   %@AS@%            jnz   printit                   ; if count > 0, print again%@AE@%%@NL@%
  4285. %@NL@%
  4286. %@4@%%@CR:IX4.43      @%%@CR:IX4.44      @%  The %@AB@%DEC%@AE@% instruction subtracts 1 from the memory location %@AS@%count%@AE@%, and sets%@EH@%
  4287.   processor flags according to the result of the operation. %@AB@%JNZ%@AE@% then jumps
  4288.   to the specified label if the result was not zero. The combined effect of
  4289.   these two instructions is to repeat the previous instructions (from
  4290.   %@AS@%printit %@AE@%onward) ten times. To change the number of repetitions, initialize
  4291.   %@AS@%count %@AE@%with a different value.%@NL@%
  4292. %@NL@%
  4293. %@4@%  Note that the DOS print function returns a value in the register%@EH@%
  4294.   AX──specifically, the number of bytes written. The program jumps back to
  4295.   %@AS@%printit %@AE@%so that AH is reloaded before the call to DOS.%@NL@%
  4296. %@NL@%
  4297. %@4@%  You can optimize this program further by using a register instead of the%@EH@%
  4298.   memory location %@AS@%count%@AE@%. For example, to use the register SI as the counter,
  4299.   follow these steps:%@NL@%
  4300. %@NL@%
  4301.   ■  Remove the declaration of %@AS@%count%@AE@%.%@NL@%
  4302. %@NL@%
  4303.   ■  Initialize SI to %@AS@%10 %@AE@%at the beginning of the program with the
  4304.      instruction %@AS@%mov si,10%@AE@%.%@NL@%
  4305. %@NL@%
  4306.   ■  Decrement SI instead of %@AS@%count %@AE@%near the bottom of the loop.%@NL@%
  4307. %@NL@%
  4308. %@4@%  With this program, it's safe to use SI as the counter, since SI is not%@EH@%
  4309.   needed for any other purpose. However, some programs make special use of
  4310.   SI. In these cases, it may be more efficient to place the count in a
  4311.   variable.%@NL@%
  4312. %@NL@%
  4313. %@CR:IX4.45      @%%@NL@%
  4314. %@2@%%@CR:SC4.8       @%%@AB@%4.8  Creating .COM Files%@AE@%%@EH@%%@NL@%
  4315. %@NL@%
  4316. %@4@%  You can use QuickAssembler to produce .COM files as well as .EXE files.%@EH@%
  4317.   (However, these programs cannot contain any C modules.) Most of the memory
  4318.   models, ranging from small to large, produce a .EXE file. The tiny memory
  4319.   model is special because it alone supports creation of a .COM file.%@NL@%
  4320. %@NL@%
  4321.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4322.   %@AB@%NOTE%@AE@%  To produce a .COM file, you must not only use tiny memory model, but
  4323.   also select Generate COM File from the Linker Flags dialog box (choose
  4324.   Make from the Options menu), or else give the /TINY linker option on the
  4325.   QCL command line.%@NL@%
  4326.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4327. %@NL@%
  4328. %@4@%  Each .COM file has only one physical segment and is limited in size to a%@EH@%
  4329.   total of 64K. A .COM file has no executable-file header or
  4330.   relocation-table entries. Because DOS doesn't have to examine a file
  4331.   header or adjust relocatable segment addresses, it loads the .COM file
  4332.   slightly faster.%@NL@%
  4333. %@NL@%
  4334. %@4@%  DOS initializes all segment registers (including DS) to point to the first%@EH@%
  4335.   available memory address. The Stack Pointer, SP, is set to 64K above the
  4336.   start of the program. Unlike .EXE files, .COM files have no definite stack
  4337.   area. Instead, the stack starts at offset address FFFE hexadecimal and
  4338.   continues to grow downward until it overlaps code and data areas. At that
  4339.   point, program failure is likely.%@NL@%
  4340. %@NL@%
  4341. %@4@%  Simplified segment directives in QuickAssembler now provide direct support%@EH@%
  4342.   for .COM files. The template is, in fact, smaller than the template for a
  4343.   .EXE file.%@NL@%
  4344. %@NL@%
  4345. %@4@%%@CR:IX4.46      @%  The code below shows the example in Section 4.3%@BO:       3793a@%, "A Program That Says%@EH@%
  4346.   Hello," revised to produce a .COM file:%@NL@%
  4347. %@NL@%
  4348.   %@AS@%            .MODEL  tiny                 ; Produce a .COM file%@AE@%%@NL@%
  4349. %@NL@%
  4350.   %@AS@%            .DATA%@AE@%%@NL@%
  4351.   %@AS@%message     DB    "Hello, world.",13,10  ; Message to print%@AE@%%@NL@%
  4352.   %@AS@%lmessage    EQU   $ - message            ; Determine length of message%@AE@%%@NL@%
  4353.   %@AS@%            .CODE%@AE@%%@NL@%
  4354.   %@AS@%            .STARTUP%@AE@%%@NL@%
  4355.   %@AS@%            mov   bx,1                   ; Load 1 - file handle for%@AE@%%@NL@%
  4356.   %@AS@%                                         ;   standard output%@AE@%%@NL@%
  4357.   %@AS@%            mov   cx,lmessage            ; Load length of message%@AE@%%@NL@%
  4358.   %@AS@%            mov   dx,OFFSET message      ; Load address of message%@AE@%%@NL@%
  4359.   %@AS@%            mov   ah,40h                 ; Load no. of DOS Write function%@AE@%%@NL@%
  4360.   %@AS@%            int   21h                    ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  4361. %@NL@%
  4362.   %@AS@%            mov   ax,4c00h               ; Load no. of DOS Exit function%@AE@%%@NL@%
  4363.   %@AS@%                                         ;   in AH, and 0 exit code in AL%@AE@%%@NL@%
  4364.   %@AS@%            int   21h                    ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  4365. %@NL@%
  4366.   %@AS@%            END%@AE@%%@NL@%
  4367. %@NL@%
  4368. %@4@%%@CR:IX4.47      @%  A tiny-model program could be produced by simply taking the small-model%@EH@%
  4369.   version from earlier in the chapter, and changing the first line to the
  4370.   following:%@NL@%
  4371. %@NL@%
  4372.   %@AS@%            .MODEL tiny%@AE@%%@NL@%
  4373. %@NL@%
  4374. %@4@%  The code would then run correctly. However, the sample code in this%@EH@%
  4375.   section takes advantage of tiny model by eliminating the stack segment.
  4376.   DOS initializes the SS (Stack Segment) register and SP (Stack Pointer)
  4377.   register for you, so you need not declare a stack. The assembler ignores
  4378.   stack segments in tiny model.%@NL@%
  4379. %@NL@%
  4380. %@4@%  The program still includes the %@AB@%.STARTUP%@AE@% directive. With tiny model, all%@EH@%
  4381.   this directive does is generate the statement %@AS@%ORG 100h%@AE@%.%@NL@%
  4382. %@NL@%
  4383. %@CR:IX4.48      @%%@CR:IX4.49      @%  ──────────────────────────────────────────────────────────────────────────%@NL@%
  4384.   %@AB@%NOTE %@AE@%  The statement %@AS@%ORG 100h %@AE@%is necessary for programs in the .COM
  4385.   format, and must appear just before the first line of executable code. %@AS@%ORG%@AE@%
  4386.   %@AS@%100h %@AE@%starts the location counter at 100 hexadecimal, reflecting the way
  4387.   that DOS loads .COM files into memory. (DOS reserves the first 256 bytes
  4388.   for the Program Segment Prefix (PSP).) See Section 6.6%@BO:       67109@%, "Setting the
  4389.   Location Counter," for more information on the %@AB@%ORG%@AE@% directive.%@NL@%
  4390.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4391. %@NL@%
  4392. %@4@%%@CR:IX4.50      @%  With tiny-model programs, QuickAssembler lets you define separate code and%@EH@%
  4393.   data segments, but combines these segments into a single physical segment,
  4394.   called a "group." QuickAssembler places the code segment first regardless
  4395.   of how you write your source code. The resulting .COM file assumes a
  4396.   single segment address for the whole program (as required by the structure
  4397.   of a .COM file), and execution automatically begins at the proper address.
  4398.   Finally, Quick-Assembler directs the linker to output a file in the .COM
  4399.   format rather than the .EXE format.%@NL@%
  4400. %@NL@%
  4401.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4402.   %@AB@%NOTE%@AE@%  "Groups" are a standard concept in 8086 assembly language. You can
  4403.   place a series of segments into a group. The total size must not exceed
  4404.   64K. The linker responds by combining all the segments into a single
  4405.   physical segment in which all addresses share the same segment address.
  4406.   For a fuller explanation of groups and segments, see Chapter 5%@BO:       3ffad@%.%@NL@%
  4407.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4408. %@NL@%
  4409. %@4@%  When you write .COM files, you must observe some important restrictions.%@EH@%
  4410.   You cannot use program-defined segment addresses. Similarly, you have no
  4411.   access to defined segment addresses, such as %@AB@%@data%@AE@% and %@AB@%@code%@AE@%.%@NL@%
  4412. %@NL@%
  4413. %@4@%%@CR:IX4.51      @%  Because .COM files lack relocation-table entries, DOS cannot adjust%@EH@%
  4414.   segment addresses at load time. The program must use absolute segment
  4415.   addresses or else assume the loading segment address that DOS assigns. The
  4416.   principal restriction is that you cannot refer to program-defined segment
  4417.   addresses. Therefore, memory references can be of three kinds:%@NL@%
  4418. %@NL@%
  4419.   1. Any memory location within the 64K program area. For these memory
  4420.      references, you do not load a new value into any of the segment
  4421.      registers.%@NL@%
  4422. %@NL@%
  4423.   2. Hard-coded locations in memory that have special meaning at the system
  4424.      or hardware level. A video-page address, such as %@AS@%B800:0000%@AE@%, is such a
  4425.      special segment address.%@NL@%
  4426. %@NL@%
  4427.   3. An address returned to you by a DOS or ROM-BIOS function. For example,
  4428.      DOS function 48H, Allocate Memory, returns a pointer to a block of
  4429.      dynamically allocated memory.%@NL@%
  4430. %@NL@%
  4431. %@NL@%
  4432. %@2@%%@CR:SC4.9       @%%@AB@%4.9  Creating .COM Files with Full Segment Definitions%@AE@%%@EH@%%@NL@%
  4433. %@NL@%
  4434. %@4@%%@CR:IX4.52      @%%@CR:IX4.53      @%  You don't generally need to use full segment definitions to create .COM%@EH@%
  4435.   files. However, when you do use these directives with programs written in
  4436.   .COM format, you need to follow certain rules. The assembler automatically
  4437.   follows most of these rules when you use simplified segment directives.%@NL@%
  4438. %@NL@%
  4439. %@4@%  The guidelines for .COM format are listed below:%@EH@%%@NL@%
  4440. %@NL@%
  4441.   ■  Place the entire program into one physical segment. It's possible to
  4442.      divide your program into separate logical segments, then group them
  4443.      into one physical segment with the %@AB@%GROUP%@AE@% directive. Simplified segment
  4444.      directives, in fact, use this technique with tiny model.%@NL@%
  4445. %@NL@%
  4446.      However, you must ensure that code, not data, appears at the beginning
  4447.      of the .COM file. A number of different factors affect segment
  4448.      ordering, so it may be hard to ensure that the code segment appears
  4449.      first. Thus, creating just one segment is the more reliable method.%@NL@%
  4450. %@NL@%
  4451.      In contrast, when you use simplified segment directives with tiny
  4452.      model, the assembler %@AI@%always%@AE@% places the code segment at the beginning of
  4453.      the .COM file.%@NL@%
  4454. %@NL@%
  4455.   ■  Use the %@AB@%ASSUME%@AE@% directive to inform the assembler that all segment
  4456.      registers will point to the beginning of the segment. At load time, DOS
  4457.      sets all segment registers to this address. The %@AB@%ASSUME%@AE@% directive
  4458.      informs the assembler of this fact so that it can correctly calculate
  4459.      offset addresses. This directive is not necessary when you use
  4460.      simplified segment directives.%@NL@%
  4461. %@NL@%
  4462.   ■  Use the %@AB@%ORG%@AE@% directive to set the location counter. At load time, DOS
  4463.      sets the starting address to 100H. The first 100H bytes are reserved
  4464.      for the Program Segment Prefix (PSP). The statement %@AS@%ORG 100h %@AE@%is
  4465.      necessary for the assembler to assign addresses in a way consistent
  4466.      with run-time conditions. Otherwise, jump instructions and data
  4467.      references will be wrong.%@NL@%
  4468. %@NL@%
  4469.      When you use simplified segments directives with tiny model, the
  4470.      assembler automatically sets the location counter to 100H.%@NL@%
  4471. %@NL@%
  4472.   ■  Use the %@AB@%END%@AE@% statement to take one argument: a starting address. This
  4473.      argument is not necessary if you use the %@AB@%.STARTUP%@AE@% simplified segment
  4474.      directive, because the program automatically begins execution wherever
  4475.      you place %@AB@%.STARTUP%@AE@%.%@NL@%
  4476. %@NL@%
  4477. %@4@%  The modified procedure is shown below:%@EH@%%@NL@%
  4478. %@NL@%
  4479.   %@AS@%_TEXT       SEGMENT 'CODE'                 ; Define code segment%@AE@%%@NL@%
  4480.   %@AS@%            ASSUME  cs:_TEXT,ds:_TEXT,ss:_TEXT%@AE@%%@NL@%
  4481.   %@AS@%            ORG     100h%@AE@%%@NL@%
  4482.   %@AS@%start:      jmp     begin%@AE@%%@NL@%
  4483. %@NL@%
  4484.   %@AS@%message     DB      "Hello, world.",13,10  ; Message to print%@AE@%%@NL@%
  4485.   %@AS@%lmessage    EQU     $ - message            ; Determine length of message%@AE@%%@NL@%
  4486.   %@AS@%begin:      mov     bx,1                   ; Load 1 - file handle%@AE@%%@NL@%
  4487.   %@AS@%                                           ;   for standard output%@AE@%%@NL@%
  4488.   %@AS@%            mov     cx,lmessage            ; Load length of message%@AE@%%@NL@%
  4489.   %@AS@%            mov     dx,OFFSET message      ; Load address of message%@AE@%%@NL@%
  4490.   %@AS@%            mov     ah,40h                 ; Load no. of DOS Write function%@AE@%%@NL@%
  4491.   %@AS@%            int     21h                    ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  4492. %@NL@%
  4493.   %@AS@%            mov     ax,4c00h               ; Load no. of DOS Exit function%@AE@%%@NL@%
  4494.   %@AS@%                                           ;   in AH, and 0 exit code in AL%@AE@%%@NL@%
  4495.   %@AS@%            int     21h                    ; Call interrupt 21H (DOS)%@AE@%%@NL@%
  4496. %@NL@%
  4497.   %@AS@%_TEXT       ENDS%@AE@%%@NL@%
  4498.   %@AS@%            END     start%@AE@%%@NL@%
  4499. %@NL@%
  4500. %@4@%  The first three statements are new. The %@AB@%SEGMENT%@AE@% statement defines the%@EH@%
  4501.   beginning of a segment named %@AS@%_TEXT%@AE@%. (Instead of using the name %@AS@%_TEXT%@AE@%, you
  4502.   can choose any other valid symbolic name.) The %@AB@%ASSUME%@AE@% statement then
  4503.   informs the assembler that the CS, DS, and SS segment registers will all
  4504.   point to the beginning of this segment at run time. Finally, the %@AB@%ORG%@AE@%
  4505.   statement informs the assembler that the instruction pointer will be set
  4506.   to 100H.%@NL@%
  4507. %@NL@%
  4508.   %@AS@%_TEXT       SEGMENT                        ; Define code segment%@AE@%%@NL@%
  4509.   %@AS@%            ASSUME  cs:_TEXT,ds:_TEXT,ss:_TEXT%@AE@%%@NL@%
  4510.   %@AS@%            ORG     100h%@AE@%%@NL@%
  4511. %@NL@%
  4512. %@4@%  The body of the procedure now includes code and data together in the same%@EH@%
  4513.   segment. The first item in the segment %@AI@%must%@AE@% be an instruction, because
  4514.   .COM files always begin execution at the start of the file. Attempting to
  4515.   execute data would almost certainly cause program failure. Since there is
  4516.   no separate data segment, the first instruction jumps around the data
  4517.   declarations.%@NL@%
  4518. %@NL@%
  4519.   %@AS@%start:      jmp     begin%@AE@%%@NL@%
  4520. %@NL@%
  4521.   %@AS@%message     DB      "Hello, world.",13,10  ; Message to print%@AE@%%@NL@%
  4522.   %@AS@%lmessage    EQU     $ - message            ; Determine length of message%@AE@%%@NL@%
  4523.   %@AS@%begin:      mov     bx,1                   ; Load 1 - file handle for%@AE@%%@NL@%
  4524.   %@AS@%                                           ;   standard output%@AE@%%@NL@%
  4525. %@NL@%
  4526. %@4@%  Another way to write a program for .COM format is to place data%@EH@%
  4527.   declarations after the end of the instructions. However, the assembler
  4528.   often produces better results if you place data declarations early in the
  4529.   source file. That way, you avoid forward references to data.%@NL@%
  4530. %@NL@%
  4531. %@4@%  The source file ends by giving an argument to the %@AB@%END%@AE@% statement. This%@EH@%
  4532.   statement is necessary because the program does not use the %@AB@%.STARTUP%@AE@%
  4533.   directive. The argument to %@AB@%END%@AE@% must be the label of the first instruction
  4534.   executed:%@NL@%
  4535. %@NL@%
  4536.   %@AS@%            END     start%@AE@%%@NL@%
  4537. %@NL@%
  4538. %@NL@%
  4539. %@NL@%
  4540. ────────────────────────────────────────────────────────────────────────────%@NL@%
  4541. %@1@%%@CR:PT2         @%%@AB@%PART 2:  Using Directives%@AE@%%@EH@%%@NL@%
  4542. %@NL@%
  4543. %@NL@%
  4544. %@4@%  Part 2%@BO:       3faf8@% of the Programmer's Guide (comprising Chapters 5%@BO:       3ffad@%-12) describes%@EH@%
  4545.   the directives and operators recognized by the Microsoft QuickAssembler.
  4546.   Directives are nonexecutable statements that give general information to
  4547.   the assembler. Some of the more important directives declare program
  4548.   structure, define data, and create macros. Operators indicate calculations
  4549.   to be performed at assembly time.%@NL@%
  4550. %@NL@%
  4551. %@4@%  Chapters 5%@BO:       3ffad@%-8 present the basic directives you need to write a program,%@EH@%
  4552.   including segment, data, multimodule, and structure directives. Chapter
  4553.   9%@BO:       78a1d@% deals specifically with operators. Chapter 10%@BO:       867d7@% describes conditional
  4554.   assembly, and Chapter 11%@BO:       8d6e4@% presents macros, a technique for replacing a
  4555.   series of frequently used instructions with a single statement. The
  4556.   directives that control your output are covered in Chapter 12%@BO:       a2236@%.%@NL@%
  4557. %@NL@%
  4558. %@NL@%
  4559. %@NL@%
  4560. %@NL@%
  4561. ────────────────────────────────────────────────────────────────────────────%@NL@%
  4562. %@1@%%@CR:CH5         @%%@AB@%Chapter 5:  Defining Segment Structure%@AE@%%@EH@%%@NL@%
  4563. %@NL@%
  4564. %@NL@%
  4565. %@4@%%@CR:IX5.1       @%  A segment is an area in memory up to 64K in size, in which all locations%@EH@%
  4566.   share the same segment address. The 8086 assembly-language modules use
  4567.   segments for two reasons:%@NL@%
  4568. %@NL@%
  4569.   ■  Segments provide a convenient means for dividing a program into its
  4570.      major divisions──code, data, constant data, and stack.%@NL@%
  4571. %@NL@%
  4572.   ■  The architecture of the 8086 requires some use of segments. Every
  4573.      reference to memory must be relative to one of the four segment
  4574.      registers, as described in Section 2.7%@BO:       28c1c@%, "Segmented Addressing and
  4575.      Segment Registers." Segment definitions make it possible for
  4576.      QuickAssembler to assume the use of the same segment register for a
  4577.      large number of different addresses.%@NL@%
  4578. %@NL@%
  4579. %@4@%  You can define segments by using simplified segment directives or full%@EH@%
  4580.   segment definitions.%@NL@%
  4581. %@NL@%
  4582. %@4@%%@CR:IX5.2       @%  In most cases, simplified segment directives are a better choice. They are%@EH@%
  4583.   easier to use and more consistent, yet you seldom sacrifice any
  4584.   functionality by using them. Simplified segment directives automatically
  4585.   define the segment structure required when combining assembler modules
  4586.   with modules prepared with Microsoft high-level languages.%@NL@%
  4587. %@NL@%
  4588. %@4@%%@CR:IX5.3       @%  Although more difficult to use, full segment definitions give more%@EH@%
  4589.   complete control over segments. A few complex programs may require full
  4590.   segment definitions in order to get unusual segment orders and types.%@NL@%
  4591. %@NL@%
  4592. %@4@%  This chapter describes both methods. If you choose to use simplified%@EH@%
  4593.   segment directives, you will probably not need to read about full segment
  4594.   definitions.%@NL@%
  4595. %@NL@%
  4596. %@NL@%
  4597. %@2@%%@CR:SC5.1       @%%@AB@%5.1  Simplified Segment Directives%@AE@%%@EH@%%@NL@%
  4598. %@NL@%
  4599. %@4@%  Simplified segment directives provide an easy way to write%@EH@%
  4600.   assembly-language programs. They handle some of the difficult aspects of
  4601.   segment definition automatically, and assume the same conventions adopted
  4602.   by Microsoft high-level languages.%@NL@%
  4603. %@NL@%
  4604. %@4@%  When you write stand-alone assembler programs, the simplified segment%@EH@%
  4605.   directives make programming easier. The Microsoft conventions are flexible
  4606.   enough to work for most kinds of programs.%@NL@%
  4607. %@NL@%
  4608. %@4@%  When you write assembler routines to be linked with Microsoft high-level%@EH@%
  4609.   languages, the simplified segment directives ensure against mistakes that
  4610.   would make your modules incompatible. The names are automatically defined
  4611.   consistently and correctly.%@NL@%
  4612. %@NL@%
  4613. %@4@%%@CR:IX5.4       @%%@CR:IX5.5       @%  The simplified segment directives automatically generate the same %@AB@%ASSUME%@AE@%%@EH@%
  4614.   and %@AB@%GROUP%@AE@% statements used by Microsoft high-level languages. You can learn
  4615.   more about the %@AB@%ASSUME%@AE@% and %@AB@%GROUP%@AE@% directives in Sections 5.3%@BO:       512db@% and 5.4%@BO:       52503@%.%@NL@%
  4616. %@NL@%
  4617. %@4@%  However, for most programs you do not need to understand these directives.%@EH@%
  4618.   Simply use the simplified segment directives in the format shown in the
  4619.   examples.%@NL@%
  4620. %@NL@%
  4621. %@NL@%
  4622. %@3@%%@CR:SC5.1.1     @%%@AB@%5.1.1  Understanding Memory Models%@AE@%%@EH@%%@NL@%
  4623. %@NL@%
  4624. %@4@%%@CR:IX5.6       @%  To use simplified segment directives, you must declare a memory model for%@EH@%
  4625.   your program. The memory model specifies the default size of data and code
  4626.   used in a program.%@NL@%
  4627. %@NL@%
  4628. %@4@%%@CR:IX5.7       @%  Microsoft high-level languages require that each program have a default%@EH@%
  4629.   size (or memory model). Any assembly-language routine called from a
  4630.   high-level language program should have the same memory model as the
  4631.   calling program. The C compiler provided with QuickAssembler supports all
  4632.   models except tiny. If you use assembly modules with a different compiler,
  4633.   the compiler documentation should tell what memory models are supported.%@NL@%
  4634. %@NL@%
  4635. %@4@%%@CR:IX5.8       @%  The most commonly used memory models are described below:%@EH@%%@NL@%
  4636. %@NL@%
  4637.   %@AB@%Model%@AE@%               %@AB@%Description%@AE@%%@NL@%
  4638.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4639. %@CR:IX5.9       @%%@CR:IX5.10      @%  Tiny                All data and code fit in a single physical segment
  4640.                       (group). Tiny-model programs can be converted to
  4641.                       .COM-file format with the Generate COM File option in
  4642.                       the Linker Flags dialog box (or the linker /TINY
  4643.                       option used with QCL). Tiny-model programs have
  4644.                       restrictions described in Chapter 4%@BO:       34dba@%, "Writing
  4645.                       Stand-Alone Assembly Programs."%@NL@%
  4646. %@NL@%
  4647. %@CR:IX5.11      @%%@CR:IX5.12      @%%@CR:IX5.13      @%  Small               All data fits within a single 64K segment, and all
  4648.                       code fits within a 64K segment. Therefore, all code
  4649.                       and data can be accessed as near. This is the most
  4650.                       common model for stand-alone assembler programs. C is
  4651.                       the only Microsoft language that supports this model.%@NL@%
  4652. %@NL@%
  4653. %@CR:IX5.14      @%  Medium              All data fits within a single 64K segment, but code
  4654.                       may be greater than 64K. Therefore, data is near, but
  4655.                       code is far. Most recent versions of Microsoft
  4656.                       high-level languages support this model.%@NL@%
  4657. %@NL@%
  4658. %@CR:IX5.15      @%%@CR:IX5.16      @%  Compact             All code fits within a single 64K segment, but the
  4659.                       total amount of data may be greater than 64K (although
  4660.                       no array can be larger than 64K). Therefore, code is
  4661.                       near, but data is far. C is the only Microsoft
  4662.                       high-level language that supports this model.%@NL@%
  4663. %@NL@%
  4664. %@CR:IX5.17      @%  Large               Both code and data may be greater than 64K (although
  4665.                       no array can be larger than 64K). Therefore, both code
  4666.                       and data are far. All Microsoft high-level languages
  4667.                       support this model.%@NL@%
  4668. %@NL@%
  4669. %@CR:IX5.18      @%  Huge                Both code and data may be greater than 64K. In
  4670.                       addition, any individual data array can be larger than
  4671.                       64K. From the standpoint of QuickAssembler, this
  4672.                       memory model is almost equivalent to large model (the
  4673.                       only exception is the meaning of the predefined equate
  4674.                       %@AB@%@DataSize%@AE@%). If you want to support arrays larger than
  4675.                       64K, you must provide the program logic to support
  4676.                       these arrays.%@NL@%
  4677. %@NL@%
  4678. %@NL@%
  4679. %@4@%  Stand-alone assembler programs can have any model. Tiny and small model%@EH@%
  4680.   are adequate for most programs written entirely in assembly language.
  4681.   Since near data or code can be accessed more quickly, the smallest memory
  4682.   model that can accommodate your code and data is usually the most
  4683.   efficient.%@NL@%
  4684. %@NL@%
  4685. %@4@%  Mixed-model programs use the default size for most code and data but%@EH@%
  4686.   override the default for particular data items. Stand-alone assembler
  4687.   programs can be written as mixed-model programs by making specific
  4688.   procedures or variables near or far. Some Microsoft high-level languages
  4689.   have %@AB@%NEAR%@AE@%, %@AB@%FAR%@AE@%, and %@AB@%HUGE%@AE@% keywords that enable you to override the default
  4690.   size of individual data or code items.%@NL@%
  4691. %@NL@%
  4692. %@NL@%
  4693. %@3@%%@CR:SC5.1.2     @%%@AB@%5.1.2  Specifying DOS Segment Order%@AE@%%@EH@%%@NL@%
  4694. %@NL@%
  4695. %@4@%%@CR:IX5.19      @%%@CR:IX5.20      @%%@CR:IX5.21      @%%@CR:IX5.22      @%%@CR:IX5.23      @%  The %@AB@%DOSSEG%@AE@% directive specifies that segments be ordered according to the%@EH@%
  4696.   DOS segment-order convention. This is the convention used by Microsoft
  4697.   high-level-language compilers.%@NL@%
  4698. %@NL@%
  4699. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  4700. %@NL@%
  4701. %@4@%  %@AB@%DOSSEG%@AE@%%@EH@%%@NL@%
  4702. %@NL@%
  4703. %@4@%  Using the %@AB@%DOSSEG%@AE@% directive enables you to maintain a consistent, logical%@EH@%
  4704.   segment order without actually defining segments in that order in your
  4705.   source file. Without this directive, the final segment order of the
  4706.   executable file depends on a variety of factors, such as segment order,
  4707.   class name, and order of linking. These factors are described in Section
  4708.   5.2%@BO:       4b9a0@%, "Full Segment Definitions."%@NL@%
  4709. %@NL@%
  4710. %@4@%  Since segment order is not crucial to the proper functioning of most%@EH@%
  4711.   stand-alone assembler programs, you can simply use the %@AB@%DOSSEG%@AE@% directive
  4712.   and ignore the whole issue of segment order.%@NL@%
  4713. %@NL@%
  4714.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4715.   %@AB@%NOTE%@AE@%  Using the %@AB@%DOSSEG %@AE@%directive (or the /DOSSEG linker option) has two
  4716.   side effects. The linker generates symbols called _end and _edata. You
  4717.   should not use these names in programs that contain the %@AB@%DOSSEG %@AE@%directive.
  4718.   Also, the linker increases the offset of the first byte of the code
  4719.   segment by 16 bytes in small and compact models. This is to give proper
  4720.   alignment to executable files created with Microsoft compilers.%@NL@%
  4721.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4722. %@NL@%
  4723. %@4@%  If you want to use the DOS segment-order convention in stand-alone%@EH@%
  4724.   assembler programs, you should use the %@AB@%DOSSEG%@AE@% argument in the main module.
  4725.   Modules called from the main module need not use the %@AB@%DOSSEG%@AE@% directive.%@NL@%
  4726. %@NL@%
  4727. %@4@%  You do not need to use the %@AB@%DOSSEG%@AE@% directive for modules called from%@EH@%
  4728.   Microsoft high-level languages, since the compiler already defines DOS
  4729.   segment order.%@NL@%
  4730. %@NL@%
  4731. %@4@%  Under the DOS segment-order convention, segments have the following order:%@EH@%%@NL@%
  4732. %@NL@%
  4733. %@CR:IX5.24      @%  1. All segment names having the class name 'CODE'%@NL@%
  4734. %@NL@%
  4735. %@CR:IX5.25      @%  2. Any segments that do not have class name 'CODE' and are not part of the
  4736.      group DGROUP%@NL@%
  4737. %@NL@%
  4738.   3. Segments that are part of DGROUP, in the following order:%@NL@%
  4739. %@NL@%
  4740.      a. Any segments of class BEGDATA (this class name is reserved for
  4741.         Microsoft use)%@NL@%
  4742. %@NL@%
  4743.      b. Any segments not of class BEGDATA, BSS, or STACK%@NL@%
  4744. %@NL@%
  4745.      c. Segments of class BSS%@NL@%
  4746. %@NL@%
  4747.      d. Segments of class STACK%@NL@%
  4748. %@NL@%
  4749. %@4@%%@CR:IX5.26      @%  Using the %@AB@%DOSSEG%@AE@% directive has the same effect as using the /DOSSEG linker%@EH@%
  4750.   option.%@NL@%
  4751. %@NL@%
  4752. %@4@%%@CR:IX5.27      @%%@CR:IX5.28      @%  The directive works by writing to the comment record of the object file.%@EH@%
  4753.   The Intel(R) title for this record is %@AB@%COMENT%@AE@%. If the linker detects a
  4754.   certain sequence of bytes in this record, it automatically puts segments
  4755.   in the DOS order.%@NL@%
  4756. %@NL@%
  4757. %@NL@%
  4758. %@3@%%@CR:SC5.1.3     @%%@AB@%5.1.3  Defining Basic Attributes of the Module%@AE@%%@EH@%%@NL@%
  4759. %@NL@%
  4760. %@4@%%@CR:IX5.29      @%%@CR:IX5.30      @%  The %@AB@%.MODEL%@AE@% directive defines attributes that affect the entire module:%@EH@%
  4761.   memory model, default calling and naming conventions, and stack type. This
  4762.   directive should appear before any other simplified segment directive.%@NL@%
  4763. %@NL@%
  4764. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  4765. %@NL@%
  4766. %@4@%  %@AB@%.MODEL%@AE@% %@AI@%memorymodel%@AE@%[[[[%@AB@%,%@AE@%%@AI@%language%@AE@%]]%@AB@%,%@AE@%%@AI@%stacktype%@AE@%]]%@EH@%%@NL@%
  4767. %@NL@%
  4768. %@4@%  Each of the three fields defines a basic attribute. The %@AI@%memorymodel%@AE@% field%@EH@%
  4769.   defines the segment structure of the module. The %@AI@%language%@AE@% field defines
  4770.   the default calling and naming conventions assumed by %@AB@%PROC%@AE@% statements.
  4771.   These conventions correspond to the high-level language you specify. The
  4772.   %@AI@%stacktype%@AE@% field determines whether or not the assembler assumes that the
  4773.   SS register is equal to the DS register.%@NL@%
  4774. %@NL@%
  4775. %@4@%%@CR:IX5.31      @%%@CR:IX5.32      @%%@CR:IX5.33      @%%@CR:IX5.34      @%%@CR:IX5.35      @%%@CR:IX5.36      @%  The %@AI@%memorymodel%@AE@% field can be %@AB@%TINY%@AE@%, %@AB@%SMALL%@AE@%,%@AB@% MEDIUM%@AE@%,%@AB@% COMPACT%@AE@%, %@AB@%LARGE%@AE@%, or %@AB@%HUGE%@AE@%.%@EH@%
  4776.   The assembler defines segments the same way for large and huge models, but
  4777.   the %@AB@%@DataSize%@AE@% equate (explained in Section 5.1.5%@BO:       47722@%, "Using Predefined
  4778.   Segment Equates") gives a different value for these two models.%@NL@%
  4779. %@NL@%
  4780. %@4@%%@CR:IX5.37      @%  If you write an assembler routine for a high-level language, the%@EH@%
  4781.   %@AI@%memorymodel%@AE@% field should match the memory model used by the compiler or
  4782.   interpreter. If you write a stand-alone assembler program, you can use any
  4783.   model. Section 5.1.1%@BO:       40c7f@% describes each memory model.%@NL@%
  4784. %@NL@%
  4785. %@4@%%@CR:IX5.38      @%%@CR:IX5.39      @%%@CR:IX5.40      @%%@CR:IX5.41      @%  The optional %@AI@%language%@AE@% field tells the assembler to follow the naming,%@EH@%
  4786.   calling, and return conventions appropriate to the indicated language. In
  4787.   addition, if you use the %@AI@%language%@AE@% argument, the assembler automatically
  4788.   makes all procedure names public. You can use %@AB@%C%@AE@%, %@AB@%Pascal%@AE@%, %@AB@%FORTRAN%@AE@%, or %@AB@%BASIC%@AE@%
  4789.   as the %@AI@%language%@AE@% argument. The last three are equivalent, since these
  4790.   languages share the same naming and calling conventions.%@NL@%
  4791. %@NL@%
  4792. %@4@%  Note that although the %@AI@%language%@AE@% field is optional, you will not be able to%@EH@%
  4793.   use the high-level language features of the %@AB@%PROC%@AE@% directive if you do not
  4794.   give it. Normally, you should specify a language with %@AB@%.MODEL%@AE@%. If you use %@AB@%C%@AE@%
  4795.   for the language argument, all public and external names are by default
  4796.   prefixed with an underscore (_) in the .OBJ file. Specifying any other
  4797.   language has no effect on the names.%@NL@%
  4798. %@NL@%
  4799.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4800.   %@AB@%NOTE%@AE@%  The assembler does not truncate names in order to match the
  4801.   conventions of specific languages, such as FORTRAN or Pascal. Moreover,
  4802.   using the C type specifier does not cause the assembler to preserve case.
  4803.   To preserve lowercase names in public symbols, choose one of the assembler
  4804.   flags that preserves case (Preserve Extrn or Preserve Case), or assemble
  4805.   with /Cx or /Cl on the QCL command line. Within the environment, the
  4806.   Preserve Extrn flag is on by default.%@NL@%
  4807.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4808. %@NL@%
  4809. %@4@%  See Appendix A%@BO:       ed697@% for an explanation of how the different calling%@EH@%
  4810.   conventions are implemented. You should also note that each language has
  4811.   different defaults for passing parameters by value or by reference.
  4812.   Depending on which method is used, a high-level language passes a
  4813.   parameter either as a value or as a pointer to the value.%@NL@%
  4814. %@NL@%
  4815. %@4@%  The optional %@AI@%stacktype%@AE@% field determines whether or not the assembler%@EH@%
  4816.   assumes that SS is equal to DS. The default value is %@AB@%nearStack%@AE@%, which
  4817.   assumes that SS is part of the default data area, so that SS is equal to
  4818.   DS, and SP is set to the top of the data area. You can also use %@AB@%farStack%@AE@%,
  4819.   which assumes that the stack segment is in a separate physical segment
  4820.   from the default data area.%@NL@%
  4821. %@NL@%
  4822. %@4@%%@CR:IX5.42      @%  If you write a module called from QuickC, you should always use the%@EH@%
  4823.   default (in other words, just leave the field blank), since QuickC always
  4824.   assumes DS equals SS. If you write modules for a compiler (such as the
  4825.   Microsoft Optimized C Compiler) that supports customized memory models,
  4826.   use %@AB@%farStack%@AE@% for models in which SS does not equal DS. If you write a
  4827.   stand-alone assembler program, you can choose either setting. If you use
  4828.   the %@AB@%.STARTUP%@AE@% directive, the assembler automatically generates the proper
  4829.   code for setting up the indicated stack type.%@NL@%
  4830. %@NL@%
  4831. %@4@%%@CR:IX5.43      @%%@CR:IX5.44      @%%@CR:IX5.45      @%  If you write a stand-alone module without using %@AB@%.STARTUP%@AE@%, you should%@EH@%
  4832.   exercise caution. If you initialize DS but do not adjust SS and SP (as
  4833.   described in Section 5.5.3%@BO:       55651@%, "Initializing the SS and SP Registers), use
  4834.   the %@AB@%farStack%@AE@% keyword. If you do adjust SS and SP as described in Section
  4835.   5.5.3%@BO:       55651@%, you can use the default value, %@AB@%nearStack%@AE@%.%@NL@%
  4836. %@NL@%
  4837. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  4838. %@NL@%
  4839.   %@AS@%            DOSSEG%@AE@%%@NL@%
  4840.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  4841. %@NL@%
  4842. %@4@%  This statement defines default segments for small-model programs and%@EH@%
  4843.   creates the %@AB@%ASSUME%@AE@% and %@AB@%GROUP%@AE@% statements used by small-model programs. The
  4844.   segments are automatically ordered according to the Microsoft convention.
  4845.   The example statements might be used at the start of the main (or only)
  4846.   module of a stand-alone assembler program.%@NL@%
  4847. %@NL@%
  4848. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  4849. %@NL@%
  4850.   %@AS@%            .MODEL  large,pascal%@AE@%%@NL@%
  4851. %@NL@%
  4852. %@4@%  This statement defines default segments for large-model programs and%@EH@%
  4853.   creates the %@AB@%ASSUME%@AE@% and %@AB@%GROUP%@AE@% statements used by large-model programs. It
  4854.   does not automatically order segments according to the Microsoft
  4855.   convention. The example statement might be used at the start of an
  4856.   assembly module that would be called from a large-model Pascal program or
  4857.   a C program in which the Pascal calling convention was specified.%@NL@%
  4858. %@NL@%
  4859. %@4@%  %@AB@%Example 3%@AE@%%@EH@%%@NL@%
  4860. %@NL@%
  4861.   %@AS@%            .MODEL  small,c,farStack%@AE@%%@NL@%
  4862. %@NL@%
  4863. %@4@%  This statement defines default segments for a small-model program and%@EH@%
  4864.   creates the appropriate %@AB@%ASSUME%@AE@% and %@AB@%GROUP%@AE@% statements. In addition, this
  4865.   statement makes all procedures public, and directs the assembler to prefix
  4866.   an underscore to the beginning of each public name, so that the naming
  4867.   convention is compatible with C. If you later use the %@AB@%PROC%@AE@% statement to
  4868.   declare parameters, the assembler will assume that the parameters are
  4869.   placed on the stack in the order specified by the C calling convention. In
  4870.   addition, the statement uses %@AB@%farStack%@AE@%, indicating that SS is not equal to
  4871.   DS.%@NL@%
  4872. %@NL@%
  4873. %@4@%  The last example would be appropriate for a module called by a C module%@EH@%
  4874.   with a customized memory model, compiled with a setting that did not
  4875.   assume SS equal to DS. Note that QuickC does not support customized memory
  4876.   models.%@NL@%
  4877. %@NL@%
  4878.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4879.   %@AB@%NOTE%@AE@%  The assembler does not normally display the code generated by the
  4880.   high-level-language support features. You can see the code produced by
  4881.   these features by using the %@AB@%.LALL%@AE@% directive or the /LA command-line
  4882.   option.%@NL@%
  4883.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  4884. %@NL@%
  4885. %@4@%  To write procedures for use with more than one language and memory model,%@EH@%
  4886.   you can use text macros for the memory model and language arguments, and
  4887.   define the values from the command line or in the Assembler Flags dialog
  4888.   box. For example, the following %@AB@%.MODEL%@AE@% directive uses text macros for the
  4889.   %@AI@%memorymodel%@AE@% and %@AI@%language%@AE@% arguments:%@NL@%
  4890. %@NL@%
  4891.   %@AS@%%           .MODEL memmodel,lang  ; Use % to evaluate memmodel, lang%@AE@%%@NL@%
  4892. %@NL@%
  4893. %@4@%  The values of the two text macros can be defined from the command line%@EH@%
  4894.   using the /D switch:%@NL@%
  4895. %@NL@%
  4896.   %@AS@%QCL /Dmemmodel=MEDIUM /Dlang=C /AM /Cx main.c proc.asm%@AE@%%@NL@%
  4897. %@NL@%
  4898. %@NL@%
  4899. %@3@%%@CR:SC5.1.4     @%%@AB@%5.1.4  Defining Simplified Segments%@AE@%%@EH@%%@NL@%
  4900. %@NL@%
  4901. %@4@%  Each of the directives %@AB@%.CODE%@AE@%, %@AB@%.STACK%@AE@%, %@AB@%.DATA%@AE@%, %@AB@%.DATA?%@AE@%, %@AB@%.CONST%@AE@%, %@AB@%.FARDATA%@AE@%,%@EH@%
  4902.   %@AB@%.FARDATA?%@AE@%, and %@AB@%.STARTUP%@AE@% indicate the start of a segment. They also end the
  4903.   immediately preceding segment definition.%@NL@%
  4904. %@NL@%
  4905. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  4906. %@NL@%
  4907. %@4@%  %@AB@%.CODE%@AE@% [[%@AI@%name%@AE@%]]       Code segment%@EH@%%@NL@%
  4908.   %@AB@%.STACK%@AE@% [[%@AI@%size%@AE@%]]      Stack segment%@NL@%
  4909.   %@AB@%.DATA%@AE@%                Initialized near-data segment%@NL@%
  4910.   %@AB@%.DATA?%@AE@%               Uninitialized near-data segment%@NL@%
  4911.   %@AB@%.CONST%@AE@%               Constant-data segment%@NL@%
  4912.   %@AB@%.FARDATA%@AE@% [[%@AI@%name%@AE@%]]    Initialized far-data segment%@NL@%
  4913.   %@AB@%.FARDATA?%@AE@% [[%@AI@%name%@AE@%]]   Uninitialized far-data segment%@NL@%
  4914.   %@AB@%.STARTUP%@AE@%             Code to initialize segment registers%@NL@%
  4915. %@NL@%
  4916. %@4@%%@CR:IX5.46      @%  For segments that take an optional %@AI@%name%@AE@%, the base file name of the source%@EH@%
  4917.   module is used if you do not specify a value yourself.%@NL@%
  4918. %@NL@%
  4919. %@4@%%@CR:IX5.47      @%%@CR:IX5.48      @%%@CR:IX5.49      @%  Each new segment directive ends the previous segment. The %@AB@%END%@AE@% directive%@EH@%
  4920.   closes the last segment in the source file.%@NL@%
  4921. %@NL@%
  4922. %@NL@%
  4923. %@3@%%@CR:SC5.1.4.1   @%%@AB@%5.1.4.1  How to Use Simplified Segments%@AE@%%@EH@%%@NL@%
  4924. %@NL@%
  4925. %@4@%  The %@AB@%.CODE%@AE@%, %@AB@%.DATA%@AE@%, and %@AB@%.STACK%@AE@% directives create the three basic segments%@EH@%
  4926.   that programs generally need to have. Chapter 4%@BO:       34dba@%, "Writing Stand-Alone
  4927.   Assembly Programs," demonstrates how to use these directives to write
  4928.   code, data, and stack segments. Chapter 4%@BO:       34dba@% also explains the purpose of
  4929.   each of these segments.%@NL@%
  4930. %@NL@%
  4931. %@4@%  The %@AB@%.STARTUP %@AE@%directive initializes segment registers to the appropriate%@EH@%
  4932.   segment values. Chapter 4%@BO:       34dba@% describes the use of %@AB@%.STARTUP%@AE@%, and Section
  4933.   5.5%@BO:       53a35@% tells more about how %@AB@%.STARTUP%@AE@% works and what code it generates.%@NL@%
  4934. %@NL@%
  4935. %@4@%%@CR:IX5.50      @%%@CR:IX5.51      @%%@CR:IX5.52      @%  When you write a mixed-language program, you generally don't need to%@EH@%
  4936.   declare a stack segment, because the start-up code in the C main module
  4937.   creates a stack for you. When you write a stand-alone program, you should
  4938.   declare a stack segment in the main module only.%@NL@%
  4939. %@NL@%
  4940. %@4@%%@CR:IX5.53      @%  Your programs can also use the %@AB@%.DATA?%@AE@% and %@AB@%.CONST%@AE@% directives to create%@EH@%
  4941.   segments for uninitialized and constant data, respectively. With
  4942.   stand-alone assembler programs, the use of these directives is optional,
  4943.   because you can place all data in the segment defined by %@AB@%.DATA%@AE@% if you
  4944.   want. With mixed-language programs, use %@AB@%.DATA?%@AE@% and %@AB@%.CONST%@AE@% to ensure
  4945.   compatibility with the way C handles uninitialized and constant data. Once
  4946.   you define these segments, it is up to you to place the appropriate data
  4947.   in each segment.%@NL@%
  4948. %@NL@%
  4949. %@4@%%@CR:IX5.54      @%%@CR:IX5.55      @%%@CR:IX5.56      @%%@CR:IX5.57      @%%@CR:IX5.58      @%%@CR:IX5.59      @%%@CR:IX5.60      @%%@CR:IX5.61      @%%@CR:IX5.62      @%%@CR:IX5.63      @%  If your program is written in compact, large, or huge model, you can use%@EH@%
  4950.   the %@AB@%.FARDATA%@AE@% and %@AB@%.FARDATA?%@AE@% directives to define additional data segments.
  4951.   All the data in the other data segments (defined by %@AB@%.DATA%@AE@%, %@AB@%.DATA?%@AE@%, and
  4952.   %@AB@%.CONST%@AE@%) must not exceed a total of 64K across all modules. In addition,
  4953.   the stack segment is also placed into this 64K area unless you specify
  4954.   %@AB@%farStack%@AE@% with the %@AB@%.MODEL%@AE@% directive.%@NL@%
  4955. %@NL@%
  4956. %@4@%  Data in the %@AB@%.FARDATA%@AE@% and %@AB@%.FARDATA?%@AE@% segments takes slightly longer to%@EH@%
  4957.   access. However, there is generally much more room in these segments for
  4958.   data definitions. For each module, the %@AB@%.FARDATA%@AE@% and %@AB@%.FARDATA?%@AE@% directives
  4959.   each create a separate physical segment that can be up to 64K in size. The
  4960.   recommended procedure is to use %@AB@%.FARDATA%@AE@% for initialized data, and
  4961.   %@AB@%.FARDATA?%@AE@% for uninitialized data, although this is optional.%@NL@%
  4962. %@NL@%
  4963. %@4@%  With medium, large, and huge model, you can use the %@AI@%name%@AE@% attribute to%@EH@%
  4964.   create multiple code segments within a source module. With compact, large,
  4965.   and huge model, you can also use the %@AI@%name%@AE@% attribute to create multiple
  4966.   far-data segments.%@NL@%
  4967. %@NL@%
  4968. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  4969. %@NL@%
  4970.   %@AS@%            DOSSEG%@AE@%%@NL@%
  4971.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  4972.   %@AS@%            .STACK  100h%@AE@%%@NL@%
  4973.   %@AS@%            .DATA%@AE@%%@NL@%
  4974.   %@AS@%ivariable   DB      5%@AE@%%@NL@%
  4975.   %@AS@%iarray      DW      50 DUP (5)%@AE@%%@NL@%
  4976.   %@AS@%string      DB      "This is a string"%@AE@%%@NL@%
  4977.   %@AS@%uarray      DW      50 DUP (?)%@AE@%%@NL@%
  4978.   %@AS@%            EXTRN   xvariable:WORD%@AE@%%@NL@%
  4979.   %@AS@%            .CODE%@AE@%%@NL@%
  4980.   %@AS@%            .STARTUP%@AE@%%@NL@%
  4981.   %@AS@%            EXTRN   xprocedure:NEAR%@AE@%%@NL@%
  4982.   %@AS@%            call    xprocedure%@AE@%%@NL@%
  4983.   %@AS@%            .%@AE@%%@NL@%
  4984.   %@AS@%            .%@AE@%%@NL@%
  4985.   %@AS@%            .%@AE@%%@NL@%
  4986.   %@AS@%            END%@AE@%%@NL@%
  4987. %@NL@%
  4988. %@4@%  This code uses simplified segment directives for a small-model,%@EH@%
  4989.   stand-alone assembler program. Notice that initialized data, uninitialized
  4990.   data, and a string constant are all defined in the same data segment. See
  4991.   Section 5.1.7%@BO:       493ed@%, "Default Segment Names," for an equivalent version that
  4992.   uses full segment definitions.%@NL@%
  4993. %@NL@%
  4994. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  4995. %@NL@%
  4996.   %@AS@%            .MODEL, large,c%@AE@%%@NL@%
  4997.   %@AS@%            .FARDATA?%@AE@%%@NL@%
  4998.   %@AS@%fuarray     DW      10 DUP (?)         ; Far uninitialized data%@AE@%%@NL@%
  4999.   %@AS@%            .CONST%@AE@%%@NL@%
  5000.   %@AS@%string      DB      "This is a string" ; String constant%@AE@%%@NL@%
  5001.   %@AS@%            .DATA%@AE@%%@NL@%
  5002.   %@AS@%niarray     DB      100 DUP (5)        ; Near initialized data%@AE@%%@NL@%
  5003.   %@AS@%            .FARDATA%@AE@%%@NL@%
  5004.   %@AS@%            EXTRN   xvariable:FAR%@AE@%%@NL@%
  5005.   %@AS@%fiarray     DW      100 DUP (10)       ; Far initialized data%@AE@%%@NL@%
  5006.   %@AS@%            .CODE   TASK%@AE@%%@NL@%
  5007.   %@AS@%            EXTRN   xprocedure:PROC%@AE@%%@NL@%
  5008.   %@AS@%task        PROC%@AE@%%@NL@%
  5009.   %@AS@%            .%@AE@%%@NL@%
  5010.   %@AS@%            .%@AE@%%@NL@%
  5011.   %@AS@%            .%@AE@%%@NL@%
  5012.   %@AS@%            ret%@AE@%%@NL@%
  5013.   %@AS@%task        ENDP%@AE@%%@NL@%
  5014.   %@AS@%            END%@AE@%%@NL@%
  5015. %@NL@%
  5016. %@4@%  This example uses simplified segment directives to create a module that%@EH@%
  5017.   might be called from a large-model, high-level-language program. Notice
  5018.   that different types of data are put in different segments to conform to
  5019.   Microsoft compiler conventions. See Section 5.1.7%@BO:       493ed@%, "Default Segment
  5020.   Names," for an equivalent version using full segment definitions.%@NL@%
  5021. %@NL@%
  5022. %@NL@%
  5023. %@3@%%@CR:SC5.1.4.2   @%%@AB@%5.1.4.2  How Simplified Segments Are Implemented%@AE@%%@EH@%%@NL@%
  5024. %@NL@%
  5025. %@4@%  When you use the simplified segment directives described above, the%@EH@%
  5026.   assembler defines segments in a way compatible with Microsoft high-level
  5027.   languages.%@NL@%
  5028. %@NL@%
  5029. %@4@%  This section makes a number of references to groups and %@AB@%ASSUME%@AE@% statements.%@EH@%
  5030.   Both of these concepts arise from the need to deal with the 8086 segmented
  5031.   architecture. A "group" consists of one or more segments, totaling no more
  5032.   than 64K. When multiple segments are placed into a group, the linker
  5033.   combines these segments into a single physical segment. All addresses in
  5034.   the physical segment are adjusted so that they share the same segment
  5035.   address. Use of groups is convenient because it removes the need to
  5036.   constantly reload the DS register.%@NL@%
  5037. %@NL@%
  5038. %@4@%%@CR:IX5.64      @%%@CR:IX5.65      @%  The %@AB@%ASSUME%@AE@% directive is described at greater length in Section 5.4%@BO:       52503@%,%@EH@%
  5039.   "Associating Segments with Registers." This directive informs the
  5040.   assembler where a segment register will point to at run time so that the
  5041.   assembler can correctly calculate offset addresses relative to the value
  5042.   in the appropriate segment register.%@NL@%
  5043. %@NL@%
  5044. %@4@%  Unless you use tiny model, the code segment (defined with %@AB@%.CODE%@AE@%) is placed%@EH@%
  5045.   in its own physical segment, separate from all the data and stack
  5046.   segments. With medium, large, or huge model, you can define multiple code
  5047.   segments within one source model by using %@AB@%.CODE%@AE@% repeatedly, each time with
  5048.   a different %@AI@%name%@AE@% attribute. When you use this technique, each %@AB@%.CODE%@AE@%
  5049.   directive generates a new %@AB@%ASSUME%@AE@% statement so that the assembler knows
  5050.   where CS points to at run time.%@NL@%
  5051. %@NL@%
  5052. %@4@%%@CR:IX5.66      @%  Segments defined with the %@AB@%.STACK%@AE@%, %@AB@%.CONST%@AE@%, %@AB@%.DATA,%@AE@% or %@AB@%.DATA?%@AE@% directives are%@EH@%
  5053.   placed in a group called DGROUP. Segments defined with the %@AB@%.FARDATA%@AE@% or
  5054.   %@AB@%.FARDATA?%@AE@% directives are not placed in any group. See Section 5.3%@BO:       512db@% for
  5055.   more information on segment groups. When initializing the DS register to
  5056.   access data in a group-associated segment, the value of DGROUP should be
  5057.   loaded into DS. The %@AB@%.STARTUP%@AE@% directive does this initialization
  5058.   automatically.%@NL@%
  5059. %@NL@%
  5060. %@4@%  The %@AB@%.MODEL%@AE@% directive generates %@AB@%ASSUME%@AE@% statements to inform the assembler%@EH@%
  5061.   that at run time, DS, SS, and ES will all point to the beginning of
  5062.   DGROUP. You don't need to write these %@AB@%ASSUME%@AE@% statements yourself.%@NL@%
  5063. %@NL@%
  5064. %@4@%  If you specify %@AB@%farStack%@AE@% with the %@AB@%.MODEL%@AE@% directive, the stack is placed in%@EH@%
  5065.   a separate physical segment and the %@AB@%.MODEL%@AE@% directive generates an %@AB@%ASSUME%@AE@%
  5066.   statement to inform the assembler that SS does not point to the same
  5067.   segment address that DS does.%@NL@%
  5068. %@NL@%
  5069. %@NL@%
  5070. %@3@%%@CR:SC5.1.5     @%%@AB@%5.1.5  Using Predefined Segment Equates%@AE@%%@EH@%%@NL@%
  5071. %@NL@%
  5072. %@4@%  Several equates are predefined for you. You can use the equate names at%@EH@%
  5073.   any point in your code to represent the equate values. You should not
  5074.   assign equates having these names. The predefined equates are listed
  5075.   below:%@NL@%
  5076. %@NL@%
  5077.   %@AB@%Name%@AE@%                %@AB@%Value%@AE@%%@NL@%
  5078.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5079. %@CR:IX5.67      @%%@CR:IX5.68      @%  %@AB@%@CodeSize %@AE@%and       If the %@AB@%.MODEL%@AE@% directive has been used, the value of
  5080.   %@AB@%@DataSize%@AE@%           %@AB@%@CodeSize%@AE@% is 0 for the models that use near-code
  5081.                       labels (tiny, small, and compact) or 1 for models that
  5082.                       use far-code labels (medium, large, and huge). The
  5083.                       value of%@AB@% @DataSize%@AE@% is 0 for models that use near-data
  5084.                       labels (tiny, small, and medium), 1 for compact and
  5085.                       large models, and 2 for huge models. These values can
  5086.                       be used in conditional-assembly statements.%@NL@%
  5087. %@NL@%
  5088.   %@AS@%            IF      @DataSize%@AE@%%@NL@%
  5089.   %@AS@%            les     bx,pointer             ; Load far pointer%@AE@%%@NL@%
  5090.   %@AS@%            mov     ax,es:WORD PTR [bx]%@AE@%%@NL@%
  5091.   %@AS@%            ELSE%@AE@%%@NL@%
  5092.   %@AS@%            mov     bx,WORD PTR pointer    ; Load near pointer%@AE@%%@NL@%
  5093.   %@AS@%            mov     ax,WORD PTR [bx]%@AE@%%@NL@%
  5094.   %@AS@%            ENDIF%@AE@%%@NL@%
  5095. %@NL@%
  5096. %@4@%%@CR:IX5.69      @%  %@AB@%@CurSeg%@AE@%             This name has the segment name of the current segment.%@EH@%
  5097.                       This value may be convenient for %@AB@%ASSUME%@AE@% statements,
  5098.                       segment overrides, or other cases in which you need to
  5099.                       access the current segment. It can also be used to end
  5100.                       a segment.%@NL@%
  5101. %@NL@%
  5102. %@4@%%@CR:IX5.70      @%%@CR:IX5.71      @%  %@AB@%@FileName%@AE@%           This value represents the base name of the current%@EH@%
  5103.                       source file. For example, if the current source file
  5104.                       is TASK.ASM, the value of %@AB@%@FileName%@AE@% is TASK. This
  5105.                       value can be used in any name you would like to change
  5106.                       if the file name changes. For example, it can be used
  5107.                       as a procedure name:%@NL@%
  5108. %@NL@%
  5109. %@NL@%
  5110.   %@AS@%@FileName   PROC%@AE@%%@NL@%
  5111.   %@AS@%            .%@AE@%%@NL@%
  5112.   %@AS@%            .%@AE@%%@NL@%
  5113.   %@AS@%            .%@AE@%%@NL@%
  5114.   %@AS@%@FileName   ENDP%@AE@%%@NL@%
  5115. %@NL@%
  5116. %@4@%%@CR:IX5.72      @%%@CR:IX5.73      @%  %@AB@%@Model%@AE@%              As with the %@AB@%@CodeSize%@AE@% and %@AB@%@DataSize%@AE@% predefined%@EH@%
  5117.                       equates, you must first use the %@AB@%.MODEL%@AE@% directive
  5118.                       before using the %@AB@%@Model%@AE@% equate. The value of %@AB@%@Model%@AE@% is
  5119.                       1 for tiny model, 2 for small, 3 for compact, 4 for
  5120.                       medium, 5 for large, and 6 for huge. %@AB@%@Model%@AE@% can be
  5121.                       used in conditional-assembly statements.%@NL@%
  5122. %@NL@%
  5123. %@4@%%@CR:IX5.74      @%%@CR:IX5.75      @%%@CR:IX5.76      @%%@CR:IX5.77      @%%@CR:IX5.78      @%%@CR:IX5.79      @%%@CR:IX5.80      @%  Segment equates     For each of the primary segment directives, there is a%@EH@%
  5124.                       corresponding equate with the same name, except that
  5125.                       the equate starts with an "at sign" (%@AB@%@%@AE@%) instead of a
  5126.                       period. For example, the %@AB@%@code%@AE@% equate represents the
  5127.                       segment name defined by the %@AB@%.CODE%@AE@% directive.
  5128.                       Similarly, %@AB@%@fardata %@AE@%represents the%@AB@% .FARDATA%@AE@% segment
  5129.                       name and %@AB@%@fardata?%@AE@% represents the %@AB@%.FARDATA?%@AE@% segment
  5130.                       name. The %@AB@%@data%@AE@% equate represents the group name
  5131.                       shared by all the near-data segments. It can be used
  5132.                       to access the segments created by the %@AB@%.DATA%@AE@%, %@AB@%.DATA?%@AE@%,
  5133.                       %@AB@%.CONST%@AE@%, and %@AB@%.STACK%@AE@% segments.%@NL@%
  5134. %@NL@%
  5135. %@4@%                      These equates can be used in %@AB@%ASSUME%@AE@% statements and at%@EH@%
  5136.                       any other time a segment must be referred to by name.%@NL@%
  5137. %@NL@%
  5138. %@NL@%
  5139.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5140.   %@AB@%NOTE%@AE@%  Although predefined equates are part of the simplified segment
  5141.   system, the %@AB@%@CurSeg%@AE@% and %@AB@%@FileName %@AE@%equates are also available when using
  5142.   full segment definitions. If you use the /Cl option or set Preserve Case
  5143.   in the Assembler Flags dialog box, predefined equates will be case
  5144.   sensitive with the exact names shown above.%@NL@%
  5145.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5146. %@NL@%
  5147. %@NL@%
  5148. %@3@%%@CR:SC5.1.6     @%%@AB@%5.1.6  Simplified Segment Defaults%@AE@%%@EH@%%@NL@%
  5149. %@NL@%
  5150. %@4@%%@CR:IX5.81      @%%@CR:IX5.82      @%  Although your program can combine full segment definitions and simplified%@EH@%
  5151.   segment directives, the %@AB@%.MODEL%@AE@% directive enables certain features of
  5152.   simplified segment directives that change defaults. Defaults that change
  5153.   are listed below:%@NL@%
  5154. %@NL@%
  5155. %@CR:IX5.83      @%%@CR:IX5.84      @%  ■  If you do not use the %@AB@%.MODEL%@AE@% directive, the default size for the %@AB@%PROC%@AE@%
  5156.      directive is always %@AB@%NEAR%@AE@%. If you use the %@AB@%.MODEL%@AE@% directive, the %@AB@%PROC%@AE@%
  5157.      directive is associated with the specified memory model: %@AB@%NEAR%@AE@% for tiny,
  5158.      small, and compact models and %@AB@%FAR%@AE@% for medium, large, and huge models.
  5159.      See Section 6.4.3%@BO:       5ea93@%, "Procedure Labels," for further discussion of the
  5160.      %@AB@%PROC%@AE@% directive.%@NL@%
  5161. %@NL@%
  5162. %@CR:IX5.85      @%%@CR:IX5.86      @%%@CR:IX5.87      @%  ■  If you use the %@AB@%.MODEL%@AE@% directive, the %@AB@%OFFSET%@AE@% operator returns an offset
  5163.      relative to the beginning of a group, whenever a data item is defined
  5164.      within a group. If you do not use the %@AB@%.MODEL%@AE@% directive, the %@AB@%OFFSET%@AE@%
  5165.      operator always returns an offset relative to the beginning of the
  5166.      segment. The simplified segment directives %@AB@%.DATA%@AE@%, %@AB@%.DATA?%@AE@%, and %@AB@%.STACK%@AE@%
  5167.      all create segments that are part of the group DGROUP.%@NL@%
  5168. %@NL@%
  5169.      For example, assume the variable %@AS@%test1 %@AE@%was declared in a segment
  5170.      defined with the %@AB@%.DATA%@AE@% directive and %@AS@%test2 %@AE@%was declared in a segment
  5171.      defined with the %@AB@%.FARDATA%@AE@% directive. The statement%@NL@%
  5172. %@NL@%
  5173. %@NL@%
  5174.      %@AS@%               mov     ax,OFFSET test1%@AE@%%@NL@%
  5175. %@NL@%
  5176.      loads the address of %@AS@%test1 %@AE@%relative to DGROUP. The statement%@NL@%
  5177. %@NL@%
  5178. %@NL@%
  5179.      %@AS@%               mov     ax,OFFSET test2%@AE@%%@NL@%
  5180. %@NL@%
  5181.      loads the address of %@AS@%test2 %@AE@%relative to the segment defined by the
  5182.      %@AB@%.FARDATA%@AE@% directive. See Section 5.3%@BO:       512db@% for more information on groups.%@NL@%
  5183. %@NL@%
  5184. %@NL@%
  5185. %@3@%%@CR:SC5.1.7     @%%@AB@%5.1.7  Default Segment Names%@AE@%%@EH@%%@NL@%
  5186. %@NL@%
  5187. %@4@%%@CR:IX5.88      @%  If you use the simplified segment directives by themselves, you do not%@EH@%
  5188.   need to know the names assigned for each segment. However, it is possible
  5189.   to mix full segment definitions with simplified segment directives.
  5190.   Therefore, some programmers may wish to know the actual names assigned to
  5191.   all segments.%@NL@%
  5192. %@NL@%
  5193. %@4@%%@CR:IX5.89      @%  Table 5.1 shows the default segment names created by each directive.%@EH@%%@NL@%
  5194. %@NL@%
  5195.   %@AB@%Table 5.1 Default Segments and Types for Standard Memory Models%@AE@%%@NL@%
  5196. %@NL@%
  5197.   %@AB@%Model%@AE@%     %@AB@%Directive%@AE@% %@AB@%Name%@AE@%      %@AB@%Align%@AE@%     %@AB@%Combine%@AE@%   %@AB@%Class%@AE@%       %@AB@%Group%@AE@%%@NL@%
  5198.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5199.   Tiny      %@AB@%.CODE%@AE@%     _TEXT     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CODE'      DGROUP%@NL@%
  5200. %@NL@%
  5201.             %@AB@%.DATA%@AE@%     _DATA     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'DATA'      DGROUP%@NL@%
  5202. %@NL@%
  5203.             %@AB@%.CONST%@AE@%    CONST     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CONST'     DGROUP%@NL@%
  5204. %@NL@%
  5205.             %@AB@%.DATA?%@AE@%    _BSS      %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'BSS'       DGROUP%@NL@%
  5206. %@NL@%
  5207.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5208.   Small     %@AB@%.CODE%@AE@%     _TEXT     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CODE'%@NL@%
  5209. %@NL@%
  5210.             %@AB@%.DATA%@AE@%     _DATA     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'DATA'      DGROUP%@NL@%
  5211. %@NL@%
  5212.             %@AB@%.CONST%@AE@%    CONST     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CONST'     DGROUP%@NL@%
  5213. %@NL@%
  5214.             %@AB@%.DATA?%@AE@%    _BSS      %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'BSS'       DGROUP%@NL@%
  5215. %@NL@%
  5216.             %@AB@%.STACK%@AE@%    STACK     %@AB@%PARA%@AE@%      %@AB@%STACK%@AE@%     'STACK'     DGROUP%@NL@%
  5217. %@NL@%
  5218.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5219.   Medium    %@AB@%.CODE%@AE@%     %@AI@%name%@AE@%_TEXT %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CODE'%@NL@%
  5220. %@NL@%
  5221.             %@AB@%.DATA%@AE@%     _DATA     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'DATA'      DGROUP%@NL@%
  5222. %@NL@%
  5223.             %@AB@%.CONST%@AE@%    CONST     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CONST'     DGROUP%@NL@%
  5224. %@NL@%
  5225.             %@AB@%.DATA?%@AE@%    _BSS      %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'BSS'       DGROUP%@NL@%
  5226. %@NL@%
  5227.             %@AB@%.STACK%@AE@%    STACK     %@AB@%PARA%@AE@%      %@AB@%STACK%@AE@%     'STACK'     DGROUP%@NL@%
  5228. %@NL@%
  5229.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5230.   Compact   %@AB@%.CODE%@AE@%     _TEXT     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CODE'%@NL@%
  5231. %@NL@%
  5232.             %@AB@%.FARDATA%@AE@%  FAR_DATA  %@AB@%PARA%@AE@%      private   'FAR_DATA'%@NL@%
  5233. %@NL@%
  5234.             %@AB@%.FARDATA?%@AE@% FAR_BSS   %@AB@%PARA%@AE@%      private   'FAR_BSS'%@NL@%
  5235. %@NL@%
  5236.             %@AB@%.DATA%@AE@%     _DATA     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'DATA'      DGROUP%@NL@%
  5237. %@NL@%
  5238.             %@AB@%.CONST%@AE@%    CONST     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CONST'     DGROUP%@NL@%
  5239. %@NL@%
  5240.             %@AB@%.DATA?%@AE@%    _BSS      %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'BSS'       DGROUP%@NL@%
  5241. %@NL@%
  5242.             %@AB@%.STACK%@AE@%    STACK     %@AB@%PARA%@AE@%      %@AB@%STACK%@AE@%     'STACK'     DGROUP%@NL@%
  5243. %@NL@%
  5244.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5245.   Large or  %@AB@%.CODE%@AE@%     %@AI@%name%@AE@%_TEXT %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CODE'%@NL@%
  5246. %@NL@%
  5247.   huge      %@AB@%.FARDATA%@AE@%  FAR_DATA  %@AB@%PARA%@AE@%      private   'FAR_DATA'%@NL@%
  5248. %@NL@%
  5249.             %@AB@%.FARDATA?%@AE@% FAR_BSS   %@AB@%PARA%@AE@%      private   'FAR_BSS'%@NL@%
  5250. %@NL@%
  5251.             %@AB@%.DATA%@AE@%     _DATA     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'DATA'      DGROUP%@NL@%
  5252. %@NL@%
  5253.             %@AB@%.CONST%@AE@%    CONST     %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'CONST'     DGROUP%@NL@%
  5254. %@NL@%
  5255.             %@AB@%.DATA?%@AE@%    _BSS      %@AB@%WORD%@AE@%      %@AB@%PUBLIC%@AE@%    'BSS'       DGROUP%@NL@%
  5256. %@NL@%
  5257.             %@AB@%.STACK%@AE@%    STACK     %@AB@%PARA%@AE@%      %@AB@%STACK%@AE@%     'STACK'     DGROUP%@NL@%
  5258. %@NL@%
  5259.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5260. %@NL@%
  5261. %@NL@%
  5262. %@4@%  The name used as part of far-code segment names is the file name of the%@EH@%
  5263.   module. The default name associated with the %@AB@%.CODE%@AE@% directive can be
  5264.   overridden in medium and large models. The default names for the %@AB@%.FARDATA%@AE@%
  5265.   and %@AB@%.FARDATA?%@AE@% directives can always be overridden.%@NL@%
  5266. %@NL@%
  5267. %@4@%  The segment and group table at the end of listings always shows the actual%@EH@%
  5268.   segment names. However, the %@AB@%GROUP%@AE@% and %@AB@%ASSUME%@AE@% statements generated by the
  5269.   %@AB@%.MODEL%@AE@% directive are not shown in listing files. For a program that uses
  5270.   all possible segments, group statements equivalent to the following would
  5271.   be generated:%@NL@%
  5272. %@NL@%
  5273.   %@AS@%DGROUP      GROUP    _DATA,CONST,_BSS,STACK%@AE@%%@NL@%
  5274. %@NL@%
  5275. %@4@%  For tiny model, the following would be generated:%@EH@%%@NL@%
  5276. %@NL@%
  5277.   %@AS@%            ASSUME   cs:DGROUP,ds:DGROUP,ss:DGROUP%@AE@%%@NL@%
  5278. %@NL@%
  5279. %@4@%  For small and compact models, the following would be generated:%@EH@%%@NL@%
  5280. %@NL@%
  5281.   %@AS@%            ASSUME   cs:_TEXT,ds:DGROUP,ss:DGROUP%@AE@%%@NL@%
  5282. %@NL@%
  5283. %@4@%  For medium, large, and huge models, the following statement is given:%@EH@%%@NL@%
  5284. %@NL@%
  5285.   %@AS@%            ASSUME   cs: name_TEXT,ds:DGROUP,ss:DGROUP%@AE@%%@NL@%
  5286. %@NL@%
  5287. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  5288. %@NL@%
  5289.   %@AS@%            EXTRN   xvariable:WORD%@AE@%%@NL@%
  5290.   %@AS@%            EXTRN   xprocedure:NEAR%@AE@%%@NL@%
  5291.   %@AS@%DGROUP      GROUP   _DATA,_BSS%@AE@%%@NL@%
  5292.   %@AS@%            ASSUME  cs:_TEXT,ds:DGROUP,ss:DGROUP%@AE@%%@NL@%
  5293.   %@AS@%_TEXT       SEGMENT WORD PUBLIC 'CODE'%@AE@%%@NL@%
  5294.   %@AS@%start:      mov     ax,DGROUP                    ; Initialize data segment%@AE@%%@NL@%
  5295.   %@AS@%            mov     ds,ax%@AE@%%@NL@%
  5296.   %@AS@%            cli%@AE@%%@NL@%
  5297.   %@AS@%            mov     ss,ax                        ; Move DGROUP into SS%@AE@%%@NL@%
  5298. %@NL@%
  5299.   %@AS@%            add     sp,OFFSET STACK              ; Adjust SP to top of stack%@AE@%%@NL@%
  5300.   %@AS@%            sti%@AE@%%@NL@%
  5301.   %@AS@%            .%@AE@%%@NL@%
  5302.   %@AS@%            .%@AE@%%@NL@%
  5303.   %@AS@%            .%@AE@%%@NL@%
  5304.   %@AS@%TEXT        ENDS%@AE@%%@NL@%
  5305.   %@AS@%_DATA       SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  5306.   %@AS@%ivariable   DB      5%@AE@%%@NL@%
  5307.   %@AS@%iarray      DW      50 DUP (5)%@AE@%%@NL@%
  5308.   %@AS@%string      DB      "This is a string"%@AE@%%@NL@%
  5309.   %@AS@%uarray      DW      50 DUP (?)%@AE@%%@NL@%
  5310.   %@AS@%_DATA       ENDS%@AE@%%@NL@%
  5311.   %@AS@%STACK       SEGMENT PARA STACK 'STACK'%@AE@%%@NL@%
  5312.   %@AS@%            DB      100h DUP (?)%@AE@%%@NL@%
  5313.   %@AS@%STACK       ENDS%@AE@%%@NL@%
  5314.   %@AS@%            END     start%@AE@%%@NL@%
  5315. %@NL@%
  5316. %@4@%  This example is equivalent to Example 1 in Section 5.1.4%@BO:       44e63@%, "Defining%@EH@%
  5317.   Simplified Segments." Notice that the segment order must be different in
  5318.   this version to achieve the segment order specified by using the %@AB@%DOSSEG%@AE@%
  5319.   directive in the first Section 5.1.4%@BO:       44e63@% example. The external variables are
  5320.   declared at the start of the source code in this example. With simplified
  5321.   segment directives, external variables can be declared in the segment in
  5322.   which they are used. The code generated by%@AB@% .STARTUP%@AE@% is discussed in more
  5323.   detail in Section 5.5.3%@BO:       55651@%.%@NL@%
  5324. %@NL@%
  5325. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  5326. %@NL@%
  5327.   %@AS@%DGROUP      GROUP   _DATA,CONST,STACK%@AE@%%@NL@%
  5328.   %@AS@%            ASSUME  cs:TASK_TEXT,ds:FAR_DATA,ss:STACK%@AE@%%@NL@%
  5329.   %@AS@%            EXTRN   xprocedure:FAR%@AE@%%@NL@%
  5330.   %@AS@%            EXTR    xvariable:FAR%@AE@%%@NL@%
  5331.   %@AS@%FAR_BSS     SEGMENT PARA 'FAR_DATA'%@AE@%%@NL@%
  5332.   %@AS@%fuarray     DW      10 DUP (?)         ; Far uninitialized data%@AE@%%@NL@%
  5333.   %@AS@%FAR_BSS     ENDS%@AE@%%@NL@%
  5334.   %@AS@%CONST       SEGMENT WORD PUBLIC 'CONST'%@AE@%%@NL@%
  5335.   %@AS@%string      DB      "This is a string" ; String constant%@AE@%%@NL@%
  5336.   %@AS@%CONST       ENDS%@AE@%%@NL@%
  5337.   %@AS@%_DATA       SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  5338.   %@AS@%niarray     DB      100 DUP (5)        ; Near initialized data%@AE@%%@NL@%
  5339.   %@AS@%_DATA       ENDS%@AE@%%@NL@%
  5340.   %@AS@%FAR_DATA    SEGMENT WORD 'FAR_DATA'%@AE@%%@NL@%
  5341.   %@AS@%fiarray     DW      100 DUP (10)%@AE@%%@NL@%
  5342.   %@AS@%FAR_DATA    ENDS%@AE@%%@NL@%
  5343.   %@AS@%TASK_TEXT   SEGMENT WORD PUBLIC 'CODE'%@AE@%%@NL@%
  5344.   %@AS@%task        PROC    FAR%@AE@%%@NL@%
  5345.   %@AS@%            .%@AE@%%@NL@%
  5346.   %@AS@%            .%@AE@%%@NL@%
  5347.   %@AS@%            .%@AE@%%@NL@%
  5348.   %@AS@%            ret%@AE@%%@NL@%
  5349.   %@AS@%task        ENDP%@AE@%%@NL@%
  5350.   %@AS@%TASK_TEXT   ENDS%@AE@%%@NL@%
  5351.   %@AS@%            END%@AE@%%@NL@%
  5352. %@NL@%
  5353. %@4@%  This example is equivalent to Example 2 in Section 5.1.4%@BO:       44e63@%, "Defining%@EH@%
  5354.   Simplified Segments." Notice that the segment order is the same in both
  5355.   versions. The segment order shown here is written to the object file, but
  5356.   it is different in the executable file. The segment order specified by the
  5357.   compiler (the DOS segment order) overrides the segment order in the module
  5358.   object file.%@NL@%
  5359. %@NL@%
  5360. %@NL@%
  5361. %@2@%%@CR:SC5.2       @%%@AB@%5.2  Full Segment Definitions%@AE@%%@EH@%%@NL@%
  5362. %@NL@%
  5363. %@4@%%@CR:IX5.90      @%%@CR:IX5.91      @%%@CR:IX5.92      @%%@CR:IX5.93      @%%@CR:IX5.94      @%%@CR:IX5.95      @%  If you need complete control over segments, you may want to give complete%@EH@%
  5364.   segment definitions. The section below explains all aspects of segment
  5365.   definitions, including how to order segments and how to define all the
  5366.   segment types.%@NL@%
  5367. %@NL@%
  5368. %@NL@%
  5369. %@3@%%@CR:SC5.2.1     @%%@AB@%5.2.1  Setting the Segment-Order Method%@AE@%%@EH@%%@NL@%
  5370. %@NL@%
  5371. %@4@%%@CR:IX5.96      @%  The order in which QuickAssembler writes segments to the object file can%@EH@%
  5372.   be either sequential or alphabetical. If the sequential method is
  5373.   specified, segments are written in the order in which they appear in the
  5374.   source code. If the alphabetical method is specified, segments are written
  5375.   in the alphabetical order of their segment names.%@NL@%
  5376. %@NL@%
  5377. %@4@%  The default is sequential. If no segment-order directive or option is%@EH@%
  5378.   given, segments are ordered sequentially. The segment-order method is only
  5379.   one factor in determining the final order of segments in memory. The
  5380.   %@AB@%DOSSEG%@AE@% directive (see Section 5.1.2%@BO:       41df5@%, "Specifying DOS Segment Order") and
  5381.   class type (see Section 5.2.2.3%@BO:       4f990@%, "Controlling Segment Structure with
  5382.   Class Type") can also affect segment order.%@NL@%
  5383. %@NL@%
  5384. %@4@%%@CR:IX5.97      @%%@CR:IX5.98      @%%@CR:IX5.99      @%%@CR:IX5.100     @%%@CR:IX5.101     @%%@CR:IX5.102     @%%@CR:IX5.103     @%%@CR:IX5.104     @%  The ordering method can be set by using the %@AB@%.ALPHA%@AE@% or %@AB@%.SEQ%@AE@% directive in%@EH@%
  5385.   the source code. The method can also be set using the /s (sequential) or
  5386.   /a (alphabetical) assembler options (see Appendix B%@BO:       f653b@%, Section B.1%@BO:       f7a41@%,
  5387.   "Specifying the Segment-Order Method"). The directives have precedence
  5388.   over the options. For example, if the source code contains the %@AB@%.ALPHA%@AE@%
  5389.   directive, but the /s option is given on the command line, the segments
  5390.   are ordered alphabetically.%@NL@%
  5391. %@NL@%
  5392. %@4@%%@CR:IX5.105     @%%@CR:IX5.106     @%  Changing the segment order is an advanced technique. In most cases, you%@EH@%
  5393.   can simply leave the default sequential order in effect. If you are
  5394.   linking with high-level-language modules, the compiler automatically sets
  5395.   the segment order. The %@AB@%DOSSEG%@AE@% directive also overrides any segment-order
  5396.   directives or options.%@NL@%
  5397. %@NL@%
  5398.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5399.   %@AB@%NOTE %@AE@%  Some previous versions of the IBM Macro Assembler ordered segments
  5400.   alphabetically by default. If you have trouble assembling and linking
  5401.   source-code listings from books or magazines, try using the /a option.
  5402.   Listings written for previous IBM versions of the assembler may not work
  5403.   without this option. The distinction between %@AB@%ENDS %@AE@%as the end of a segment
  5404.   and %@AB@%ENDS%@AE@% as the end of a structure is also made by the content of the
  5405.   program.%@NL@%
  5406.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5407. %@NL@%
  5408. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  5409. %@NL@%
  5410.   %@AS@%            .SEQ%@AE@%%@NL@%
  5411.   %@AS@%DATA        SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  5412.   %@AS@%DATA        ENDS%@AE@%%@NL@%
  5413.   %@AS@%CODE        SEGMENT WORD PUBLIC 'CODE'%@AE@%%@NL@%
  5414.   %@AS@%CODE        ENDS%@AE@%%@NL@%
  5415. %@NL@%
  5416. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  5417. %@NL@%
  5418.   %@AS@%            .ALPHA%@AE@%%@NL@%
  5419.   %@AS@%DATA        SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  5420.   %@AS@%DATA        ENDS%@AE@%%@NL@%
  5421.   %@AS@%CODE        SEGMENT WORD PUBLIC 'CODE'%@AE@%%@NL@%
  5422.   %@AS@%CODE        ENDS%@AE@%%@NL@%
  5423. %@NL@%
  5424. %@4@%  In Example 1, the %@AS@%DATA %@AE@%segment is written to the object file first because%@EH@%
  5425.   it appears first in the source code. In Example 2, the %@AS@%CODE %@AE@%segment is
  5426.   written to the object file first because its name comes first
  5427.   alphabetically.%@NL@%
  5428. %@NL@%
  5429. %@NL@%
  5430. %@3@%%@CR:SC5.2.2     @%%@AB@%5.2.2  Defining Full Segments%@AE@%%@EH@%%@NL@%
  5431. %@NL@%
  5432. %@4@%%@CR:IX5.107     @%%@CR:IX5.108     @%%@CR:IX5.109     @%%@CR:IX5.110     @%  The beginning of a program segment is defined with the %@AB@%SEGMENT%@AE@% directive,%@EH@%
  5433.   and the end of the segment is defined with the %@AB@%ENDS%@AE@% directive.%@NL@%
  5434. %@NL@%
  5435. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  5436. %@NL@%
  5437. %@4@%  %@AI@%name%@AE@% %@AB@%SEGMENT%@AE@% [[%@AI@%align%@AE@%]] [[%@AI@%combine%@AE@%]] [[%@AI@%use%@AE@%]] [[%@AB@%'%@AE@%%@AI@%class%@AE@%%@AB@%'%@AE@%]]%@EH@%%@NL@%
  5438.   %@AI@%statements%@AE@%%@NL@%
  5439.   %@AI@%name%@AE@% %@AB@%ENDS%@AE@%%@NL@%
  5440. %@NL@%
  5441. %@4@%  The %@AI@%name%@AE@% defines the name of the segment. This name can be unique, or it%@EH@%
  5442.   can be the same name given to other segments in the program. Segments with
  5443.   identical names are treated as the same segment. For example, if it is
  5444.   convenient to put different portions of a single segment in different
  5445.   source modules, the segment is given the same name in both modules.%@NL@%
  5446. %@NL@%
  5447. %@4@%  The optional %@AI@%align%@AE@%, %@AI@%combine%@AE@%, %@AI@%use%@AE@%, and '%@AI@%class%@AE@%' types give the linker and%@EH@%
  5448.   the assembler instructions on how to set up and combine segments. Types
  5449.   can be specified in any order; it is not necessary to enter all types, or
  5450.   any type, for a given segment.%@NL@%
  5451. %@NL@%
  5452. %@4@%  Defining segment types is an advanced technique. Beginning%@EH@%
  5453.   assembly-language programmers might try using the simplified segment
  5454.   directives discussed in Section 5.1%@BO:       406ed@%.%@NL@%
  5455. %@NL@%
  5456.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5457.   %@AB@%NOTE %@AE@%  Don't confuse the %@AB@%PAGE %@AE@%align type and the %@AB@%PUBLIC%@AE@% combine type with
  5458.   the %@AB@%PAGE %@AE@%and %@AB@%PUBLIC %@AE@%directives. The distinction should be clear from
  5459.   context since the align and combine types are only used on the same line
  5460.   as the %@AB@%SEGMENT %@AE@%directive.%@NL@%
  5461.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5462. %@NL@%
  5463. %@NL@%
  5464. %@3@%%@CR:SC5.2.2.1   @%%@AB@%5.2.2.1  Controlling Alignment with Align Type%@AE@%%@EH@%%@NL@%
  5465. %@NL@%
  5466. %@4@%%@CR:IX5.111     @%%@CR:IX5.112     @%%@CR:IX5.113     @%%@CR:IX5.114     @%%@CR:IX5.115     @%  The optional %@AI@%align%@AE@% type defines the range of memory addresses from which a%@EH@%
  5467.   starting address for the segment can be selected. The %@AI@%align%@AE@% type can be
  5468.   any one of the following:%@NL@%
  5469. %@NL@%
  5470.   %@AB@%Align Type%@AE@%          %@AB@%Meaning%@AE@%%@NL@%
  5471.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5472. %@CR:IX5.116     @%  %@AB@%BYTE%@AE@%                Uses the next available byte address%@NL@%
  5473. %@NL@%
  5474. %@CR:IX5.117     @%  %@AB@%WORD%@AE@%                Uses the next available word address (2 bytes per
  5475.                       word)%@NL@%
  5476. %@NL@%
  5477.   %@AB@%DWORD%@AE@%               Uses the next available doubleword address (4 bytes
  5478.                       per doubleword)%@NL@%
  5479. %@NL@%
  5480. %@CR:IX5.118     @%  %@AB@%PARA%@AE@%                Uses the next available paragraph address (16 bytes
  5481.                       per paragraph)%@NL@%
  5482. %@NL@%
  5483. %@CR:IX5.119     @%  %@AB@%PAGE%@AE@%                Uses the next available page address (256 bytes per
  5484.                       page)%@NL@%
  5485. %@NL@%
  5486. %@NL@%
  5487. %@4@%  If no %@AI@%align%@AE@% type is given, %@AB@%PARA%@AE@% is used by default.%@EH@%%@NL@%
  5488. %@NL@%
  5489. %@4@%  The linker uses the alignment information to determine the relative start%@EH@%
  5490.   address for each segment. DOS uses the information to calculate the actual
  5491.   start address when the program is loaded.%@NL@%
  5492. %@NL@%
  5493. %@4@%  Align types are illustrated in Figure 5.1 in the next section.%@EH@%%@NL@%
  5494. %@NL@%
  5495. %@NL@%
  5496. %@3@%%@CR:SC5.2.2.2   @%%@AB@%5.2.2.2  Defining Segment Combinations with Combine Type%@AE@%%@EH@%%@NL@%
  5497. %@NL@%
  5498. %@4@%%@CR:IX5.120     @%%@CR:IX5.121     @%%@CR:IX5.122     @%  The optional %@AI@%combine%@AE@% type defines how to combine segments having the same%@EH@%
  5499.   name. The combine type can be any one of the following:%@NL@%
  5500. %@NL@%
  5501.   %@AB@%Combine Type%@AE@%        %@AB@%Meaning%@AE@%%@NL@%
  5502.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5503. %@CR:IX5.123     @%  %@AB@%PUBLIC%@AE@%              Concatenates all segments having the same name to form
  5504.                       a single, contiguous segment. The total size of the
  5505.                       resulting segment is equal to the sum of all
  5506.                       contributing segments.%@NL@%
  5507. %@NL@%
  5508.                       All instruction and data addresses in the new segment
  5509.                       are relative to a single segment register, and all
  5510.                       offsets are adjusted to represent the distance from
  5511.                       the beginning of the segment.%@NL@%
  5512. %@NL@%
  5513. %@CR:IX5.124     @%%@CR:IX5.125     @%  %@AB@%STACK%@AE@%               Concatenates all segments having the same name to form
  5514.                       a single, contiguous segment. This combine type is the
  5515.                       same as the %@AB@%PUBLIC%@AE@% combine type, except that all
  5516.                       addresses in the new segment are relative to the SS
  5517.                       segment register. The total size of the resulting
  5518.                       segment is equal to the sum of all contributing
  5519.                       segments.%@NL@%
  5520. %@NL@%
  5521.                       The Stack Pointer (SP) register is initialized to the
  5522.                       length of the segment. The stack segment of your
  5523.                       program should normally use the %@AB@%STACK%@AE@% type, since this
  5524.                       automatically initializes the SS register, as
  5525.                       described in Section 5.5.3%@BO:       55651@%. If you create a stack
  5526.                       segment and do not use the %@AB@%STACK%@AE@% type, you must give
  5527.                       instructions to initialize the SS and SP registers.%@NL@%
  5528. %@NL@%
  5529.                       For each individual segment, all initialized data is
  5530.                       placed at the high end of the resulting stack segment.
  5531.                       Consequently, if more than one stack segment contains
  5532.                       initialized data, the linker overwrites this data as
  5533.                       it links in each segment. Note that stack data cannot
  5534.                       be initialized with simplified segment directives.%@NL@%
  5535. %@NL@%
  5536. %@CR:IX5.126     @%  %@AB@%COMMON%@AE@%              Creates overlapping segments by placing the start of
  5537.                       all segments having the same name at the same address.
  5538. %@NL@%
  5539.                       The length of the resulting area is the length of the
  5540.                       longest segment. All addresses in the segments are
  5541.                       relative to the same base address. If variables are
  5542.                       initialized in more than one segment having the same
  5543.                       name and %@AB@%COMMON%@AE@% type, the most recently initialized
  5544.                       data replaces any previously initialized data.%@NL@%
  5545. %@NL@%
  5546. %@CR:IX5.127     @%%@CR:IX5.128     @%  %@AB@%MEMORY%@AE@%              Concatenates all segments having the same name to form
  5547.                       a single, contiguous segment.%@NL@%
  5548. %@NL@%
  5549.                       The Microsoft Overlay Linker treats %@AB@%MEMORY%@AE@% segments
  5550.                       exactly the same as %@AB@%PUBLIC%@AE@% segments. QuickAssembler
  5551.                       allows you to use %@AB@%MEMORY%@AE@% type even though LINK does
  5552.                       not recognize a separate %@AB@%MEMORY%@AE@% type. This feature is
  5553.                       compatible with other linkers that may support a
  5554.                       combine type conforming to the Intel definition of
  5555.                       %@AB@%MEMORY%@AE@% type.%@NL@%
  5556. %@NL@%
  5557. %@CR:IX5.129     @%%@CR:IX5.130     @%%@CR:IX5.131     @%  %@AB@%AT%@AE@% %@AI@%address%@AE@%          Causes all label and variable addresses defined in the
  5558.                       segment to be relative to %@AI@%address%@AE@%.%@NL@%
  5559. %@NL@%
  5560. %@CR:IX5.132     @%                      The %@AI@%address%@AE@% can be any valid expression but must not
  5561.                       contain a forward reference──that is, a reference to a
  5562.                       symbol defined later in the source file. An %@AB@%AT%@AE@% segment
  5563.                       typically contains no code or initialized data.
  5564.                       Instead, it represents an address template that can be
  5565.                       placed over code or data already in memory, such as a
  5566.                       screen buffer or other absolute memory locations
  5567.                       defined by hardware. The linker will not generate any
  5568.                       code or data for %@AB@%AT%@AE@% segments, but existing code or
  5569.                       data can be accessed by name if it is given a label in
  5570.                       an %@AB@%AT%@AE@% segment. Section 6.6%@BO:       67109@%, "Setting the Location
  5571.                       Counter," shows an example of a segment with %@AB@%AT%@AE@%
  5572.                       combine type.%@NL@%
  5573. %@NL@%
  5574. %@NL@%
  5575. %@4@%  If no %@AI@%combine%@AE@% type is given, the segment has private type. Segments having%@EH@%
  5576.   the same name are not combined. Instead, each segment receives its own
  5577.   physical segment when loaded into memory.%@NL@%
  5578. %@NL@%
  5579. %@CR:IX5.133     @%  ──────────────────────────────────────────────────────────────────────────%@NL@%
  5580.   %@AB@%NOTE %@AE@%  Although a given segment name can be used more than once in a
  5581.   source file, each segment definition using that name must have either
  5582.   exactly the same attributes, or attributes that do not conflict. If types
  5583.   are given for an initial segment definition, subsequent definitions for
  5584.   that segment need not specify any types.%@NL@%
  5585. %@NL@%
  5586.   Normally, you should provide at least one stack segment (having %@AB@%STACK%@AE@%
  5587.   combine type) in a program. If no stack segment is declared, LINK displays
  5588.   a warning message. You can ignore this message if you have a specific
  5589.   reason for not declaring a stack segment. For example, you would not have
  5590.   a separate stack segment in a program in the %@AB@%.COM%@AE@% format.%@NL@%
  5591. %@CR:IX5.134     @%%@CR:IX5.135     @%%@CR:IX5.136     @%  ──────────────────────────────────────────────────────────────────────────%@NL@%
  5592. %@NL@%
  5593. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  5594. %@NL@%
  5595. %@4@%  The following source-code shell illustrates one way in which the %@AI@%combine%@AE@%%@EH@%
  5596.   and %@AI@%align%@AE@% types can be used. Figure 5.1 shows the way LINK would load the
  5597.   sample program into memory.%@NL@%
  5598. %@NL@%
  5599.   %@AS@%            NAME module_1%@AE@%%@NL@%
  5600. %@NL@%
  5601.   %@AS@%ASEG        SEGMENT BYTE PUBLIC 'CODE'%@AE@%%@NL@%
  5602.   %@AS@%start:      .%@AE@%%@NL@%
  5603.   %@AS@%            .%@AE@%%@NL@%
  5604.   %@AS@%            .%@AE@%%@NL@%
  5605.   %@AS@%ASEG        ENDS%@AE@%%@NL@%
  5606. %@NL@%
  5607.   %@AS@%BSEG        SEGMENT WORD COMMON 'DATA'%@AE@%%@NL@%
  5608.   %@AS@%            .%@AE@%%@NL@%
  5609.   %@AS@%            .%@AE@%%@NL@%
  5610.   %@AS@%            .%@AE@%%@NL@%
  5611.   %@AS@%BSEG        ENDS%@AE@%%@NL@%
  5612. %@NL@%
  5613.   %@AS@%CSEG        SEGMENT PARA STACK 'STACK'%@AE@%%@NL@%
  5614.   %@AS@%            .%@AE@%%@NL@%
  5615.   %@AS@%            .%@AE@%%@NL@%
  5616.   %@AS@%            .%@AE@%%@NL@%
  5617.   %@AS@%CSEG        ENDS%@AE@%%@NL@%
  5618. %@NL@%
  5619.   %@AS@%DSEG        SEGMENT AT 0B800H%@AE@%%@NL@%
  5620.   %@AS@%            .%@AE@%%@NL@%
  5621.   %@AS@%            .%@AE@%%@NL@%
  5622.   %@AS@%            .%@AE@%%@NL@%
  5623.   %@AS@%DSEG        ENDS%@AE@%%@NL@%
  5624.   %@AS@%            END start%@AE@%%@NL@%
  5625. %@NL@%
  5626.   %@AS@%            NAME module_2%@AE@%%@NL@%
  5627. %@NL@%
  5628.   %@AS@%ASEG        SEGMENT BYTE PUBLIC 'CODE'%@AE@%%@NL@%
  5629.   %@AS@%            .%@AE@%%@NL@%
  5630.   %@AS@%            .%@AE@%%@NL@%
  5631.   %@AS@%            .%@AE@%%@NL@%
  5632.   %@AS@%ASEG        ENDS%@AE@%%@NL@%
  5633. %@NL@%
  5634.   %@AS@%BSEG        SEGMENT WORD COMMON 'DATA'%@AE@%%@NL@%
  5635.   %@AS@%            .%@AE@%%@NL@%
  5636.   %@AS@%            .%@AE@%%@NL@%
  5637.   %@AS@%            .%@AE@%%@NL@%
  5638.   %@AS@%BSEG        ENDS%@AE@%%@NL@%
  5639. %@NL@%
  5640.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  5641.   │ This figure can be found in Section 5.2.2.2 of the manual              │%@NL@%
  5642.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  5643. %@NL@%
  5644. %@CR:IX5.137     @%%@CR:IX5.138     @%%@NL@%
  5645. %@3@%%@CR:SC5.2.2.3   @%%@AB@%5.2.2.3  Controlling Segment Structure with Class Type%@AE@%%@EH@%%@NL@%
  5646. %@NL@%
  5647. %@4@%%@CR:IX5.139     @%%@CR:IX5.140     @%  Class type is a means of associating segments that have different names,%@EH@%
  5648.   but similar purposes. It can be used to control segment order and to
  5649.   identify the code segment.%@NL@%
  5650. %@NL@%
  5651. %@4@%%@CR:IX5.141     @%%@CR:IX5.142     @%  The %@AI@%class%@AE@% name must be enclosed in single quotation marks (%@AB@%'%@AE@%). Class names%@EH@%
  5652.   are not case sensitive unless the /Cl or /Cx option is used during
  5653.   assembly.%@NL@%
  5654. %@NL@%
  5655. %@4@%  All segments belong to a class. Segments for which no class name is%@EH@%
  5656.   explicitly stated have the null class name. LINK imposes no restriction on
  5657.   the number or size of segments in a class. The total size of all segments
  5658.   in a class can exceed 64K.%@NL@%
  5659. %@NL@%
  5660.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5661.   %@AB@%NOTE %@AE@%  The names assigned for class types of segments should not be used
  5662.   for other symbol definitions in the source file. For example, if you give
  5663.   a segment the class name %@AS@%'CONSTANT'%@AE@%, you should not give the name %@AS@%constant%@AE@%
  5664.   to variables or labels in the source file.%@NL@%
  5665.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5666. %@NL@%
  5667. %@4@%  The linker expects segments having the class name CODE or a class name%@EH@%
  5668.   with the suffix CODE to contain program code. You should always assign
  5669.   this class name to segments containing code.%@NL@%
  5670. %@NL@%
  5671. %@4@%%@CR:IX5.143     @%  Class type is one of two factors that control the final order of segments%@EH@%
  5672.   in an executable file. The other factor is the order of the segments in
  5673.   the source file (with the /s option or the %@AB@%.SEQ%@AE@% directive) or the
  5674.   alphabetical order of segments (with the /a option or the %@AB@%.ALPHA%@AE@%
  5675.   directive).%@NL@%
  5676. %@NL@%
  5677. %@4@%  These factors control different internal behavior, but both affect the%@EH@%
  5678.   final order of segments in the executable file. The sequential or
  5679.   alphabetical order of segments in the source file determines the order in
  5680.   which the assembler writes segments to the object file. The class type can
  5681.   affect the order in which the linker writes segments from object files to
  5682.   the executable file.%@NL@%
  5683. %@NL@%
  5684. %@4@%  Segments having the same class type are loaded into memory together,%@EH@%
  5685.   regardless of their sequential or alphabetical order in the source file.%@NL@%
  5686. %@NL@%
  5687.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5688.   %@AB@%NOTE %@AE@%  The %@AB@%DOSSEG %@AE@%directive (see Section 5.1.2%@BO:       41df5@%, "Specifying DOS Segment
  5689.   Order") overrides all other factors in determining segment order.%@NL@%
  5690.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5691. %@NL@%
  5692. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  5693. %@NL@%
  5694.   %@AS@%A_SEG       SEGMENT 'SEG_1'%@AE@%%@NL@%
  5695.   %@AS@%A_SEG       ENDS%@AE@%%@NL@%
  5696. %@NL@%
  5697.   %@AS@%B_SEG       SEGMENT 'SEG_2'%@AE@%%@NL@%
  5698.   %@AS@%B_SEG       ENDS%@AE@%%@NL@%
  5699. %@NL@%
  5700.   %@AS@%C_SEG       SEGMENT 'SEG_1'%@AE@%%@NL@%
  5701.   %@AS@%C_SEG       ENDS%@AE@%%@NL@%
  5702. %@NL@%
  5703. %@4@%%@CR:IX5.144     @%%@CR:IX5.145     @%  When QuickAssembler assembles the preceding program fragment, it writes%@EH@%
  5704.   the segments to the object file in sequential or alphabetical order,
  5705.   depending on whether the /a option or the %@AB@%.ALPHA%@AE@% directive was used. In
  5706.   the example above, the sequential and alphabetical order are the same, so
  5707.   the order will be %@AS@%A_SEG%@AE@%, %@AS@%B_SEG%@AE@%, %@AS@%C_SEG %@AE@%in either case.%@NL@%
  5708. %@NL@%
  5709. %@4@%  When the linker writes the segments to the executable file, it first%@EH@%
  5710.   checks to see if any segments have the same class type. If they do, it
  5711.   writes them to the executable file together. Thus, %@AS@%A_SEG %@AE@%and %@AS@%C_SEG %@AE@%are
  5712.   placed together because they both have class type %@AS@%'SEG_1'%@AE@%. The final order
  5713.   in memory is %@AS@%A_SEG%@AE@%, %@AS@%C_SEG%@AE@%, %@AS@%B_SEG%@AE@%.%@NL@%
  5714. %@NL@%
  5715. %@4@%  Since LINK processes modules in the order it receives them on the command%@EH@%
  5716.   line, you may not always be able to easily specify the order in which you
  5717.   want segments to be loaded. For example, assume your program has four
  5718.   segments that you want loaded in the following order: %@AS@%_TEXT%@AE@%, %@AS@%_DATA%@AE@%, %@AS@%CONST%@AE@%,
  5719.   and %@AS@%STACK%@AE@%.%@NL@%
  5720. %@NL@%
  5721. %@4@%  The %@AS@%_TEXT%@AE@%, %@AS@%CONST%@AE@%, and %@AS@%STACK%@AE@% segments are defined in the first module of%@EH@%
  5722.   your program, but the %@AS@%_DATA%@AE@% segment is defined in the second module. LINK
  5723.   will not put the segments in the proper order because it first loads the
  5724.   segments encountered in the first module.%@NL@%
  5725. %@NL@%
  5726. %@4@%%@CR:IX5.146     @%  You can avoid this problem by starting your program with dummy segment%@EH@%
  5727.   definitions in the order you wish to load your real segments. The dummy
  5728.   segments can either go at the start of the first module, or they can be
  5729.   placed in a separate include file that is called at the start of the first
  5730.   module. You can then put the actual segment definitions in any order or
  5731.   any module you find convenient.%@NL@%
  5732. %@NL@%
  5733. %@4@%  For example, you might call the following include file at the start of the%@EH@%
  5734.   first module of your program:%@NL@%
  5735. %@NL@%
  5736.   %@AS@%_TEXT       SEGMENT WORD PUBLIC 'CODE'%@AE@%%@NL@%
  5737.   %@AS@%_TEXT       ENDS%@AE@%%@NL@%
  5738.   %@AS@%_DATA       SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  5739.   %@AS@%_DATA       ENDS%@AE@%%@NL@%
  5740.   %@AS@%CONST       SEGMENT WORD PUBLIC 'CONST'%@AE@%%@NL@%
  5741.   %@AS@%CONST       ENDS%@AE@%%@NL@%
  5742.   %@AS@%STACK       SEGMENT PARA STACK 'STACK'%@AE@%%@NL@%
  5743.   %@AS@%STACK       ENDS%@AE@%%@NL@%
  5744. %@NL@%
  5745. %@4@%  The %@AB@%DOSSEG%@AE@% directive may be more convenient for defining segment order if%@EH@%
  5746.   you are willing to accept the %@AB@%DOS%@AE@% segment-order conventions.%@NL@%
  5747. %@NL@%
  5748. %@4@%  Once a segment has been defined, you do not need to specify the align,%@EH@%
  5749.   combine, use, and class types on subsequent definitions. For example, if
  5750.   your code defined dummy segments as shown above, you could define an
  5751.   actual data segment with the following statements:%@NL@%
  5752. %@NL@%
  5753.   %@AS@%_DATA       SEGMENT%@AE@%%@NL@%
  5754.   %@AS@%            .%@AE@%%@NL@%
  5755.   %@AS@%            .%@AE@%%@NL@%
  5756.   %@AS@%            .%@AE@%%@NL@%
  5757.   %@AS@%_DATA       ENDS%@AE@%%@NL@%
  5758. %@NL@%
  5759. %@NL@%
  5760. %@2@%%@CR:SC5.3       @%%@AB@%5.3  Defining Segment Groups%@AE@%%@EH@%%@NL@%
  5761. %@NL@%
  5762. %@4@%%@CR:IX5.147     @%%@CR:IX5.148     @%%@CR:IX5.149     @%%@CR:IX5.150     @%  A group is a collection of segments associated with the same starting%@EH@%
  5763.   address. You may wish to use a group if you want several types of data to
  5764.   be organized in separate segments in your source code, but want them all
  5765.   to be accessible from a single, common segment register at run time.%@NL@%
  5766. %@NL@%
  5767. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  5768. %@NL@%
  5769. %@4@%  %@AI@%name%@AE@% %@AB@%GROUP%@AE@% %@AI@%segment%@AE@% [[%@AB@%,%@AE@%%@AI@%segment%@AE@%]]...%@EH@%%@NL@%
  5770. %@NL@%
  5771. %@4@%  The %@AI@%name%@AE@% is the symbol assigned to the starting address of the group. All%@EH@%
  5772.   labels and variables defined within the segments of the group are relative
  5773.   to the start of the group, rather than to the start of the segments in
  5774.   which they are defined.%@NL@%
  5775. %@NL@%
  5776. %@4@%%@CR:IX5.151     @%%@CR:IX5.152     @%%@CR:IX5.153     @%  The %@AI@%segment%@AE@% can be any previously defined segment or a %@AB@%SEG%@AE@% expression (see%@EH@%
  5777.   Section 9.2.4.5%@BO:       80576@%).%@NL@%
  5778. %@NL@%
  5779. %@4@%  Segments can be added to a group one at a time. For example, you can%@EH@%
  5780.   define and add segments to a group one by one.%@NL@%
  5781. %@NL@%
  5782. %@4@%  The %@AB@%GROUP%@AE@% directive does not affect the order in which segments of a group%@EH@%
  5783.   are loaded. Loading order depends on each segment's class, or on the order
  5784.   in which object modules are given to the linker.%@NL@%
  5785. %@NL@%
  5786. %@4@%%@CR:IX5.154     @%  Segments in a group need not be contiguous. Segments that do not belong to%@EH@%
  5787.   the group can be loaded between segments that do. The only restriction is
  5788.   that the distance (in bytes) between the first byte in the first segment
  5789.   of the group and the last byte in the last segment must not exceed 65,535
  5790.   bytes.%@NL@%
  5791. %@NL@%
  5792.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5793. %@CR:IX5.155     @%%@CR:IX5.156     @%%@CR:IX5.157     @%  %@AB@%NOTE %@AE@%  When the %@AB@%.MODEL %@AE@%directive is used, the offset of a group-relative
  5794.   segment refers to the ending address of the segment, not the beginning.
  5795.   For example, the expression %@AS@%OFFSET STACK%@AE@% evaluates to the end of the stack
  5796.   segment.%@NL@%
  5797.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5798. %@NL@%
  5799. %@4@%%@CR:IX5.158     @%%@CR:IX5.159     @%  Group names can be used with the %@AB@%ASSUME%@AE@% directive (discussed in Section%@EH@%
  5800.   5.4%@BO:       52503@%, "Associating Segments with Registers") and as an operand prefix with
  5801.   the segment-override operator (discussed in Section 9.2.3%@BO:       7e029@%).%@NL@%
  5802. %@NL@%
  5803. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  5804. %@NL@%
  5805.   %@AS@%DGROUP      GROUP   ASEG,CSEG%@AE@%%@NL@%
  5806.   %@AS@%            ASSUME  ds:DGROUP%@AE@%%@NL@%
  5807. %@NL@%
  5808.   %@AS@%ASEG        SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  5809.   %@AS@%            .%@AE@%%@NL@%
  5810.   %@AS@%asym        .%@AE@%%@NL@%
  5811.   %@AS@%            .%@AE@%%@NL@%
  5812.   %@AS@%ASEG        ENDS%@AE@%%@NL@%
  5813. %@NL@%
  5814.   %@AS@%BSEG        SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  5815.   %@AS@%            .%@AE@%%@NL@%
  5816.   %@AS@%bsym        .%@AE@%%@NL@%
  5817.   %@AS@%            .%@AE@%%@NL@%
  5818.   %@AS@%BSEG        ENDS%@AE@%%@NL@%
  5819. %@NL@%
  5820.   %@AS@%CSEG        SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  5821.   %@AS@%            .%@AE@%%@NL@%
  5822.   %@AS@%csym        .%@AE@%%@NL@%
  5823.   %@AS@%            .%@AE@%%@NL@%
  5824.   %@AS@%CSEG        ENDS%@AE@%%@NL@%
  5825.   %@AS@%            END%@AE@%%@NL@%
  5826. %@NL@%
  5827. %@4@%%@CR:IX5.160     @%%@CR:IX5.161     @%  Figure 5.2 shows the order of the example segments in memory. They are%@EH@%
  5828.   loaded in the order in which they appear in the source code (or in
  5829.   alphabetical order if the %@AB@%.ALPHA%@AE@% directive or /s option is specified).%@NL@%
  5830. %@NL@%
  5831.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  5832.   │ This figure can be found in Section 5.3 of the manual                  │%@NL@%
  5833.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  5834. %@NL@%
  5835. %@4@%  Since %@AS@%ASEG %@AE@%and %@AS@%CSEG %@AE@%are declared part of the same group, they have the%@EH@%
  5836.   same base despite their separation in memory. This means that the symbols
  5837.   %@AS@%asym %@AE@%and %@AS@%csym %@AE@%have offsets from the beginning of the group, which is also
  5838.   the beginning of %@AS@%ASEG%@AE@%. The offset of %@AS@%bsym %@AE@%is from the beginning of %@AS@%BSEG%@AE@%,
  5839.   since it is not part of the group. This sample illustrates the way LINK
  5840.   organizes segments in a group. It is not intended as a typical use of a
  5841.   group.%@NL@%
  5842. %@NL@%
  5843. %@NL@%
  5844. %@2@%%@CR:SC5.4       @%%@AB@%5.4  Associating Segments with Registers%@AE@%%@EH@%%@NL@%
  5845. %@NL@%
  5846. %@4@%%@CR:IX5.162     @%%@CR:IX5.163     @%%@CR:IX5.164     @%%@CR:IX5.165     @%%@CR:IX5.166     @%%@CR:IX5.167     @%%@CR:IX5.168     @%%@CR:IX5.169     @%%@CR:IX5.170     @%%@CR:IX5.171     @%%@CR:IX5.172     @%  Many of the assembler instructions assume a default segment. For example,%@EH@%
  5847.   %@AB@%JMP%@AE@% instructions assume the segment associated with the CS register; %@AB@%PUSH%@AE@%
  5848.   and %@AB@%POP%@AE@% instructions assume the segment associated with the SS register;
  5849.   %@AB@%MOV%@AE@% instructions assume the segment associated with the DS register.%@NL@%
  5850. %@NL@%
  5851. %@4@%  When the assembler needs to reference an address, it must know what%@EH@%
  5852.   segment the address is in. It does this by using the default segment or
  5853.   group addresses assigned with the %@AB@%ASSUME%@AE@% directive.%@NL@%
  5854. %@NL@%
  5855.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5856.   %@AB@%NOTE %@AE@%  Using the %@AB@%ASSUME %@AE@%directive to tell the assembler which segment to
  5857.   associate with a segment register is not the same as telling the
  5858.   processor. The %@AB@%ASSUME%@AE@% directive only affects assembly-time assumptions.
  5859.   You may need to use instructions to change run-time assumptions.
  5860.   Initializing segment registers at run time is discussed in Section 5.5%@BO:       53a35@%.%@NL@%
  5861.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5862. %@NL@%
  5863. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  5864. %@NL@%
  5865. %@4@%  %@AB@%ASSUME%@AE@% %@AI@%segmentregister%@AE@%:%@AI@%name%@AE@% [[%@AB@%,%@AE@%%@AI@%segmentregister%@AE@%:%@AI@%name%@AE@%]]...%@EH@%%@NL@%
  5866.   %@AB@%ASSUME%@AE@% %@AI@%segmentregister%@AE@%:%@AB@%NOTHING%@AE@%%@NL@%
  5867.   %@AB@%ASSUME NOTHING%@AE@%%@NL@%
  5868. %@NL@%
  5869. %@4@%  The %@AI@%name%@AE@% must be the name of the segment or group that is to be associated%@EH@%
  5870.   with %@AI@%segmentregister%@AE@%. Subsequent instructions that assume a default
  5871.   register for referencing labels or variables automatically assume that if
  5872.   the default segment is %@AI@%segmentregister%@AE@%, the label or variable is in the
  5873.   %@AI@%name%@AE@% segment or group.%@NL@%
  5874. %@NL@%
  5875. %@4@%  The %@AB@%ASSUME%@AE@% directive can define a segment for each of the segment%@EH@%
  5876.   registers. The %@AI@%segmentregister%@AE@% can be CS, DS, ES, or SS. The %@AI@%name%@AE@% must be
  5877.   one of the following:%@NL@%
  5878. %@NL@%
  5879.   ■  The name of a segment defined in the source file with the %@AB@%SEGMENT%@AE@%
  5880.      directive%@NL@%
  5881. %@NL@%
  5882.   ■  The name of a group defined in the source file with the %@AB@%GROUP%@AE@% directive%@NL@%
  5883. %@NL@%
  5884.   ■  The keyword %@AB@%NOTHING%@AE@%%@NL@%
  5885. %@NL@%
  5886.   ■  A %@AB@%SEG%@AE@% expression (see Section 9.2.4.5%@BO:       80576@%, "SEG Operator")%@NL@%
  5887. %@NL@%
  5888.   ■  A string equate that evaluates to a segment or group name (but not a
  5889.      string equate that evaluates to a %@AB@%SEG%@AE@% expression)%@NL@%
  5890. %@NL@%
  5891. %@4@%  The keyword %@AB@%NOTHING%@AE@% cancels the current segment selection. For example,%@EH@%
  5892.   the statement %@AB@%ASSUME NOTHING%@AE@% cancels all register selections made by
  5893.   previous %@AB@%ASSUME%@AE@% statements.%@NL@%
  5894. %@NL@%
  5895. %@4@%  Usually, a single %@AB@%ASSUME %@AE@%statement defines all four segment registers at%@EH@%
  5896.   the start of the source file. However, you can use the %@AB@%ASSUME%@AE@% directive at
  5897.   any point to change segment assumptions.%@NL@%
  5898. %@NL@%
  5899. %@4@%  Using the %@AB@%ASSUME%@AE@% directive to change segment assumptions is often%@EH@%
  5900.   equivalent to changing assumptions with the segment-override operator (%@AB@%:%@AE@%)
  5901.   (see Section 9.2.3%@BO:       7e029@%). The segment-override operator is more convenient for
  5902.   one-time overrides, whereas the %@AB@%ASSUME%@AE@% directive may be more convenient if
  5903.   previous assumptions must be overridden for a sequence of instructions.%@NL@%
  5904. %@NL@%
  5905. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  5906. %@NL@%
  5907.   %@AS@%            DOSSEG%@AE@%%@NL@%
  5908.   %@AS@%            .MODEL  large       ; DS automatically assumed to @data%@AE@%%@NL@%
  5909.   %@AS@%            .STACK  100h%@AE@%%@NL@%
  5910.   %@AS@%            .DATA%@AE@%%@NL@%
  5911.   %@AS@%d1          DW      7%@AE@%%@NL@%
  5912.   %@AS@%            .FARDATA%@AE@%%@NL@%
  5913.   %@AS@%d2          DW      9%@AE@%%@NL@%
  5914. %@NL@%
  5915.   %@AS@%            .CODE%@AE@%%@NL@%
  5916.   %@AS@%start:      mov     ax,@data    ; Initialize near data%@AE@%%@NL@%
  5917.   %@AS@%            mov     ds,ax%@AE@%%@NL@%
  5918.   %@AS@%            mov     ax,@fardata ; Initialize far data%@AE@%%@NL@%
  5919.   %@AS@%            mov     es,ax%@AE@%%@NL@%
  5920.   %@AS@%            .%@AE@%%@NL@%
  5921.   %@AS@%            .%@AE@%%@NL@%
  5922.   %@AS@%            .%@AE@%%@NL@%
  5923. %@NL@%
  5924.   %@AS@%; Method 1 for series of instructions that need override%@AE@%%@NL@%
  5925.   %@AS@%; Use segment override for each statement%@AE@%%@NL@%
  5926. %@NL@%
  5927.   %@AS@%            mov     ax,es:d2%@AE@%%@NL@%
  5928.   %@AS@%            .%@AE@%%@NL@%
  5929.   %@AS@%            .%@AE@%%@NL@%
  5930.   %@AS@%            .%@AE@%%@NL@%
  5931.   %@AS@%            mov     es:d2,bx%@AE@%%@NL@%
  5932. %@NL@%
  5933.   %@AS@%; Method 2 for series of instructions that need override%@AE@%%@NL@%
  5934.   %@AS@%; Use ASSUME at beginning of series of instructions%@AE@%%@NL@%
  5935. %@NL@%
  5936.   %@AS@%            ASSUME  es:@fardata%@AE@%%@NL@%
  5937.   %@AS@%            mov     cx,d2%@AE@%%@NL@%
  5938.   %@AS@%            .%@AE@%%@NL@%
  5939.   %@AS@%            .%@AE@%%@NL@%
  5940.   %@AS@%            .%@AE@%%@NL@%
  5941.   %@AS@%            mov     d2,dx%@AE@%%@NL@%
  5942. %@NL@%
  5943. %@NL@%
  5944. %@2@%%@CR:SC5.5       @%%@AB@%5.5  Initializing Segment Registers%@AE@%%@EH@%%@NL@%
  5945. %@NL@%
  5946. %@4@%%@CR:IX5.173     @%%@CR:IX5.174     @%  Assembly-language programs must initialize segment values for each segment%@EH@%
  5947.   register before instructions that reference the segment register can be
  5948.   used in the source program.%@NL@%
  5949. %@NL@%
  5950. %@4@%  Initializing segment registers is different from assigning default values%@EH@%
  5951.   for segment registers with the %@AB@%ASSUME%@AE@% statement. The %@AB@%ASSUME%@AE@% directive
  5952.   tells the assembler what segments to use at assembly time. Initializing
  5953.   segments gives them an initial value that will be used at run time.%@NL@%
  5954. %@NL@%
  5955. %@4@%  The %@AB@%.STARTUP%@AE@% directive generates all the initialization code described in%@EH@%
  5956.   this section. This directive must be preceded by the %@AB@%.MODEL%@AE@% directive. If
  5957.   the %@AB@%.MODEL%@AE@% directive was followed by the %@AB@%farStack%@AE@% attribute, %@AB@%.STARTUP%@AE@% does
  5958.   not adjust SS and SP. Otherwise, it assumes the %@AB@%nearStack%@AE@% default, which
  5959.   sets SS equal to DS as described in Section 5.5.3%@BO:       55651@%, "Initializing the SS
  5960.   and SP Registers." When you use this default, the combined stack and near
  5961.   data must not exceed 64K.%@NL@%
  5962. %@NL@%
  5963. %@4@%  If you use %@AB@%.STARTUP%@AE@%, you don't need to enter any of the code in this%@EH@%
  5964.   section, except for the %@AB@%END%@AE@% statement. (However, if you use %@AB@%.STARTUP%@AE@%, you
  5965.   don't need to specify a starting address.) Make sure that you place the
  5966.   %@AB@%.STARTUP%@AE@% directive at the point you want your program to start executing,
  5967.   because the assembler automatically initializes CS:IP to point to the
  5968.   beginning of the code generated by %@AB@%.STARTUP%@AE@%.%@NL@%
  5969. %@NL@%
  5970. %@NL@%
  5971. %@3@%%@CR:SC5.5.1     @%%@AB@%5.5.1  Initializing the CS and IP Registers%@AE@%%@EH@%%@NL@%
  5972. %@NL@%
  5973. %@4@%%@CR:IX5.175     @%  The CS and IP registers are initialized by specifying a starting address%@EH@%
  5974.   with the %@AB@%END%@AE@% directive.%@NL@%
  5975. %@NL@%
  5976. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  5977. %@NL@%
  5978. %@4@%  %@AB@%END%@AE@% [[%@AI@%startaddress%@AE@%]]%@EH@%%@NL@%
  5979. %@NL@%
  5980. %@4@%%@CR:IX5.176     @%%@CR:IX5.177     @%  The %@AI@%startaddress%@AE@% is a label or expression identifying the address where%@EH@%
  5981.   you want execution to begin when the program is loaded. Normally, a label
  5982.   for the start address should be placed at the address of the first
  5983.   instruction in the code segment.%@NL@%
  5984. %@NL@%
  5985. %@4@%%@CR:IX5.178     @%%@CR:IX5.179     @%%@CR:IX5.180     @%  The CS segment is initialized to the value of %@AI@%startaddress%@AE@%. The IP%@EH@%
  5986.   register is normally initialized to 0. You can change the initial value of
  5987.   the IP register by using the %@AB@%ORG%@AE@% directive (see Section 6.6%@BO:       67109@%, "Setting the
  5988.   Location Counter") just before the %@AI@%startaddress%@AE@% label. For example,
  5989.   programs in the %@AB@%.COM%@AE@% format use %@AS@%ORG 100h %@AE@%to initialize the IP register to
  5990.   256 (100 hexadecimal).%@NL@%
  5991. %@NL@%
  5992. %@4@%  If a program consists of a single source module, the start address is%@EH@%
  5993.   required for that module. If a program has several modules, all modules
  5994.   must terminate with an %@AB@%END%@AE@% directive, but only one of them can define a
  5995.   start address.%@NL@%
  5996. %@NL@%
  5997.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  5998.   %@AB@%WARNING %@AE@%  One, and only one, module must define a start address. If you do
  5999.   not specify a start address, none is assumed. Neither QuickAssembler nor
  6000.   LINK will generate an error message, but your program will probably start
  6001.   execution at the wrong address.%@NL@%
  6002.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6003. %@NL@%
  6004. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  6005. %@NL@%
  6006.   %@AS@%; Module 1%@AE@%%@NL@%
  6007.   %@AS@%            .CODE%@AE@%%@NL@%
  6008.   %@AS@%start:      .                  ; First executable instruction%@AE@%%@NL@%
  6009.   %@AS@%            .%@AE@%%@NL@%
  6010.   %@AS@%            .%@AE@%%@NL@%
  6011.   %@AS@%            EXTRN   task:NEAR%@AE@%%@NL@%
  6012.   %@AS@%            call    task%@AE@%%@NL@%
  6013.   %@AS@%            .%@AE@%%@NL@%
  6014.   %@AS@%            .%@AE@%%@NL@%
  6015.   %@AS@%            .%@AE@%%@NL@%
  6016.   %@AS@%            END     start      ; Starting address defined in main module%@AE@%%@NL@%
  6017. %@NL@%
  6018.   %@AS@%; Module 2%@AE@%%@NL@%
  6019.   %@AS@%            PUBLIC  task%@AE@%%@NL@%
  6020.   %@AS@%            .CODE%@AE@%%@NL@%
  6021.   %@AS@%task        PROC%@AE@%%@NL@%
  6022.   %@AS@%            .%@AE@%%@NL@%
  6023.   %@AS@%            .%@AE@%%@NL@%
  6024.   %@AS@%            .%@AE@%%@NL@%
  6025.   %@AS@%task        ENDP%@AE@%%@NL@%
  6026.   %@AS@%            END                ; No starting address in secondary module%@AE@%%@NL@%
  6027. %@NL@%
  6028. %@4@%  If %@AS@%Module 1 %@AE@%and %@AS@%Module 2%@AE@% are linked into a single program, it is essential%@EH@%
  6029.   that only the calling module define a starting address.%@NL@%
  6030. %@NL@%
  6031. %@NL@%
  6032. %@3@%%@CR:SC5.5.2     @%%@AB@%5.5.2  Initializing the DS Register%@AE@%%@EH@%%@NL@%
  6033. %@NL@%
  6034. %@4@%%@CR:IX5.181     @%  The DS register must be initialized to the address of the segment that%@EH@%
  6035.   will be used for data.%@NL@%
  6036. %@NL@%
  6037. %@4@%  The address of the segment or group for the initial data segment must be%@EH@%
  6038.   loaded into the DS register. This is done in two statements because a
  6039.   memory value cannot be loaded directly into a segment register. The
  6040.   segment-setup lines typically appear at the start or very near the start
  6041.   of the code segment.%@NL@%
  6042. %@NL@%
  6043. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  6044. %@NL@%
  6045.   %@AS@%_DATA       SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  6046.   %@AS@%            .%@AE@%%@NL@%
  6047.   %@AS@%            .%@AE@%%@NL@%
  6048.   %@AS@%            .%@AE@%%@NL@%
  6049.   %@AS@%_DATA       ENDS%@AE@%%@NL@%
  6050.   %@AS@%_TEXT       SEGMENT BYTE PUBLIC 'CODE'%@AE@%%@NL@%
  6051.   %@AS@%            ASSUME  cs:_TEXT,ds:_DATA%@AE@%%@NL@%
  6052.   %@AS@%start:      mov     ax,_DATA           ; Load start of data segment%@AE@%%@NL@%
  6053.   %@AS@%            mov     ds,ax              ; Transfer to DS register%@AE@%%@NL@%
  6054.   %@AS@%            .%@AE@%%@NL@%
  6055.   %@AS@%            .%@AE@%%@NL@%
  6056.   %@AS@%            .%@AE@%%@NL@%
  6057.   %@AS@%_TEXT       ENDS%@AE@%%@NL@%
  6058.   %@AS@%            END     start%@AE@%%@NL@%
  6059. %@NL@%
  6060. %@4@%%@CR:IX5.182     @%  If you are using the Microsoft naming convention and segment order, the%@EH@%
  6061.   address loaded into the DS register is not a segment address but the
  6062.   address of DGROUP, as shown in Example 2. With simplified segment
  6063.   directives, the address of DGROUP is represented by the predefined equate
  6064.   %@AB@%@data%@AE@%.%@NL@%
  6065. %@NL@%
  6066. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  6067. %@NL@%
  6068.   %@AS@%            DOSSEG%@AE@%%@NL@%
  6069.   %@AS@%            .MODEL  SMALL%@AE@%%@NL@%
  6070.   %@AS@%            .DATA%@AE@%%@NL@%
  6071.   %@AS@%            .%@AE@%%@NL@%
  6072.   %@AS@%            .%@AE@%%@NL@%
  6073.   %@AS@%            .%@AE@%%@NL@%
  6074.   %@AS@%            .CODE%@AE@%%@NL@%
  6075.   %@AS@%start:      mov     ax,@data          ; Load start of DGROUP (@data)%@AE@%%@NL@%
  6076.   %@AS@%            mov     ds,ax             ; Transfer to DS register%@AE@%%@NL@%
  6077.   %@AS@%            .%@AE@%%@NL@%
  6078.   %@AS@%            .%@AE@%%@NL@%
  6079.   %@AS@%            .%@AE@%%@NL@%
  6080.   %@AS@%            END     start%@AE@%%@NL@%
  6081. %@NL@%
  6082. %@NL@%
  6083. %@3@%%@CR:SC5.5.3     @%%@AB@%5.5.3  Initializing the SS and SP Registers%@AE@%%@EH@%%@NL@%
  6084. %@NL@%
  6085. %@4@%%@CR:IX5.183     @%  At load time, DOS sets SS to the segment address of the last segment%@EH@%
  6086.   having combine type %@AB@%STACK%@AE@%, and SP to the size of the stack. (The linker
  6087.   actually determines the value of SS:SP and places this value in the
  6088.   executable-file header. DOS sets SS and SP as indicated in the file
  6089.   header.)%@NL@%
  6090. %@NL@%
  6091. %@4@%  If you use a stack segment with combine type %@AB@%STACK%@AE@% or use the %@AB@%.STACK%@AE@%%@EH@%
  6092.   directive, the program automatically loads with SS and SP initialized, as
  6093.   described above.%@NL@%
  6094. %@NL@%
  6095. %@4@%  However, this basic initialization does not set SS equal to DS. If the%@EH@%
  6096.   program contains the statement %@AS@%ASSUME SS:DGROUP%@AE@%, it will be prone to
  6097.   errors. The following code resets SS and SP so that SS has the same value
  6098.   as DS. The code then adjusts SP upward so that SS:SP points to the 
  6099.   same physical address it did before. Since hardware interrupts use
  6100.   the same stack as the program, you should turn off interrupts while
  6101.   changing the stack. Most 8086-family processors turn off interrupts
  6102.   automatically when you adjust SS or SP, but early versions of the 8088 do not.%@NL@%
  6103. %@NL@%
  6104. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  6105. %@NL@%
  6106.   %@AS@%            .MODEL  small%@AE@%%@NL@%
  6107.   %@AS@%            .STACK  100h               ; Initialize "STACK"%@AE@%%@NL@%
  6108.   %@AS@%            .DATA%@AE@%%@NL@%
  6109.   %@AS@%            .%@AE@%%@NL@%
  6110.   %@AS@%            .%@AE@%%@NL@%
  6111.   %@AS@%            .%@AE@%%@NL@%
  6112.   %@AS@%            .CODE%@AE@%%@NL@%
  6113.   %@AS@%start:      mov     ax,@data           ; Load segment location%@AE@%%@NL@%
  6114.   %@AS@%            mov     ds,ax              ;   into DS register%@AE@%%@NL@%
  6115.   %@AS@%            cli                        ; Turn off interrupts%@AE@%%@NL@%
  6116.   %@AS@%            mov     ss,ax              ; Load same value as DS into SS%@AE@%%@NL@%
  6117.   %@AS@%            mov     sp,OFFSET STACK    ; Give SP new stack size%@AE@%%@NL@%
  6118.   %@AS@%            sti                        ; Turn interrupts back on%@AE@%%@NL@%
  6119.   %@AS@%            .%@AE@%%@NL@%
  6120.   %@AS@%            .%@AE@%%@NL@%
  6121.   %@AS@%            .%@AE@%%@NL@%
  6122. %@NL@%
  6123. %@4@%  This example reinitializes SS so that it has the same value as DS, and it%@EH@%
  6124.   adjusts SP to reflect the new stack offset. Microsoft high-level-language
  6125.   compilers do this so that stack variables in near procedures can be
  6126.   accessed relative to either SS or DS.%@NL@%
  6127. %@NL@%
  6128. %@4@%%@CR:IX5.184     @%%@CR:IX5.185     @%  However, this code only works correctly if you use %@AB@%.MODEL%@AE@% and you declare%@EH@%
  6129.   a stack segment in just one module. The following code handles the more
  6130.   general case. The %@AB@%.STARTUP%@AE@% directive generates this code:%@NL@%
  6131. %@NL@%
  6132. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  6133. %@NL@%
  6134.   %@AS@%start_label:%@AE@%%@NL@%
  6135.   %@AS@%            mov     dx,DGROUP    ; Move DGROUP into DS and DX%@AE@%%@NL@%
  6136.   %@AS@%            mov     ds,dx%@AE@%%@NL@%
  6137.   %@AS@%            mov     bx,ss        ; BX = STACK - DGROUP%@AE@%%@NL@%
  6138.   %@AS@%            sub     bx,dx        ;%@AE@%%@NL@%
  6139.   %@AS@%            shl     bx,1         ; Multiply difference by 16%@AE@%%@NL@%
  6140.   %@AS@%            shl     bx,1         ;   and leave result in BX%@AE@%%@NL@%
  6141.   %@AS@%            shl     bx,1%@AE@%%@NL@%
  6142.   %@AS@%            shl     bx,1%@AE@%%@NL@%
  6143.   %@AS@%            cli%@AE@%%@NL@%
  6144.   %@AS@%            mov     ss,dx        ; Move DGROUP into SS%@AE@%%@NL@%
  6145.   %@AS@%            add     sp,bx        ; Adjust SP upward by%@AE@%%@NL@%
  6146.   %@AS@%            sti                  ;   (STACK - DGROUP) * 16%@AE@%%@NL@%
  6147. %@NL@%
  6148. %@4@%  The code above sets SS and SP so that SS equals DS. This code works%@EH@%
  6149.   correctly no matter how many modules declare a stack segment.%@NL@%
  6150. %@NL@%
  6151. %@NL@%
  6152. %@3@%%@CR:SC5.5.4     @%%@AB@%5.5.4  Initializing the ES Register%@AE@%%@EH@%%@NL@%
  6153. %@NL@%
  6154. %@4@%  The ES register is not automatically initialized. If your program uses the%@EH@%
  6155.   ES register, you must initialize it by moving the appropriate segment
  6156.   value into the register.%@NL@%
  6157. %@NL@%
  6158. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  6159. %@NL@%
  6160.   %@AS@%            ASSUME  es:@fardata        ; Tell the assembler%@AE@%%@NL@%
  6161.   %@AS@%            mov     ax,@fardata        ; Tell the processor%@AE@%%@NL@%
  6162.   %@AS@%            mov     es,ax%@AE@%%@NL@%
  6163. %@NL@%
  6164. %@NL@%
  6165. %@2@%%@CR:SC5.6       @%%@AB@%5.6  Nesting Segments%@AE@%%@EH@%%@NL@%
  6166. %@NL@%
  6167. %@4@%%@CR:IX5.186     @%%@CR:IX5.187     @%  Segments can be nested. When QuickAssembler encounters a nested segment,%@EH@%
  6168.   it temporarily suspends assembly of the enclosing segment and begins
  6169.   assembly of the nested segment. When the nested segment has been
  6170.   assembled, Quick-Assembler continues assembly of the enclosing segment.%@NL@%
  6171. %@NL@%
  6172. %@4@%  Nesting of segments makes it possible to mix segment definitions in%@EH@%
  6173.   programs that use simplified segment directives for most segment
  6174.   definitions. When a full segment definition is given, the new segment is
  6175.   nested in the simplified segment in which it is defined.%@NL@%
  6176. %@NL@%
  6177. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  6178. %@NL@%
  6179.   %@AS@%; Macro to print message on the screen%@AE@%%@NL@%
  6180.   %@AS@%; Uses full segment definitions - segments nested%@AE@%%@NL@%
  6181. %@NL@%
  6182.   %@AS@%message     MACRO   text%@AE@%%@NL@%
  6183.   %@AS@%            LOCAL   symbol%@AE@%%@NL@%
  6184.   %@AS@%_DATA       SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  6185.   %@AS@%symbol      DB      &text%@AE@%%@NL@%
  6186.   %@AS@%            DB      13,10,"$"%@AE@%%@NL@%
  6187.   %@AS@%_DATA       ENDS%@AE@%%@NL@%
  6188.   %@AS@%            mov     ah,09h%@AE@%%@NL@%
  6189.   %@AS@%            mov     dx,OFFSET symbol%@AE@%%@NL@%
  6190.   %@AS@%            int     21h%@AE@%%@NL@%
  6191.   %@AS@%            ENDM%@AE@%%@NL@%
  6192. %@NL@%
  6193.   %@AS@%_TEXT       SEGMENT BYTE PUBLIC 'CODE'%@AE@%%@NL@%
  6194.   %@AS@%            .%@AE@%%@NL@%
  6195.   %@AS@%            .%@AE@%%@NL@%
  6196.   %@AS@%            .%@AE@%%@NL@%
  6197.   %@AS@%            message "Please insert disk"%@AE@%%@NL@%
  6198. %@NL@%
  6199. %@4@%  In the example above, a macro called from inside of the code segment%@EH@%
  6200.   (%@AS@%_TEXT%@AE@%) allocates a variable within a nested data segment (%@AS@%_DATA%@AE@%). This
  6201.   has the effect of allocating more data space on the end of the data
  6202.   segment each time the macro is called. The macro can be used for messages
  6203.   appearing only once in the source code.%@NL@%
  6204. %@NL@%
  6205. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  6206. %@NL@%
  6207.   %@AS@%; Macro to print message on the screen%@AE@%%@NL@%
  6208.   %@AS@%; Uses simplified segment directives - segments not nested%@AE@%%@NL@%
  6209. %@NL@%
  6210.   %@AS@%message     MACRO   text%@AE@%%@NL@%
  6211.   %@AS@%            LOCAL   symbol%@AE@%%@NL@%
  6212.   %@AS@%            .DATA%@AE@%%@NL@%
  6213.   %@AS@%symbol      DB      &text%@AE@%%@NL@%
  6214.   %@AS@%            DB      13,10,"$"%@AE@%%@NL@%
  6215.   %@AS@%            .CODE%@AE@%%@NL@%
  6216.   %@AS@%            mov     ah,09h%@AE@%%@NL@%
  6217.   %@AS@%            mov     dx,OFFSET symbol%@AE@%%@NL@%
  6218.   %@AS@%            int     21h%@AE@%%@NL@%
  6219.   %@AS@%            ENDM%@AE@%%@NL@%
  6220. %@NL@%
  6221.   %@AS@%            .CODE%@AE@%%@NL@%
  6222.   %@AS@%            .%@AE@%%@NL@%
  6223.   %@AS@%            .%@AE@%%@NL@%
  6224.   %@AS@%            .%@AE@%%@NL@%
  6225.   %@AS@%            message "Please insert disk"%@AE@%%@NL@%
  6226. %@NL@%
  6227. %@4@%  Although Example 2 has the same practical effect as Example 1,%@EH@%
  6228.   Quick-Assembler handles the two macros differently. In Example 1, assembly
  6229.   of the outer (code) segment is suspended rather than terminated. In
  6230.   Example 2, assembly of the code segment terminates, assembly of the data
  6231.   segment starts and terminates, and then assembly of the code segment is
  6232.   restarted.%@NL@%
  6233. %@NL@%
  6234. %@NL@%
  6235. %@NL@%
  6236. ────────────────────────────────────────────────────────────────────────────%@NL@%
  6237. %@1@%%@CR:CH6         @%%@AB@%Chapter 6:  Defining Constants, Labels, and Variables%@AE@%%@EH@%%@NL@%
  6238. %@NL@%
  6239. %@NL@%
  6240. %@4@%  This chapter explains how to define constants, labels, variables, and%@EH@%
  6241.   other symbols that refer to instruction and data locations within
  6242.   segments.%@NL@%
  6243. %@NL@%
  6244. %@4@%  Constants are important in QuickAssembler, just as they are in other%@EH@%
  6245.   languages. You can use constants as immediate operands in instructions and
  6246.   as initial values in data declarations. QuickAssembler supports a number
  6247.   of useful radixes (including binary and hexadecimal), as described in
  6248.   Section 6.1%@BO:       57adf@%.%@NL@%
  6249. %@NL@%
  6250. %@4@%  QuickAssembler lets you use symbols as well as constants. Sections 6.2%@BO:       5b018@%,%@EH@%
  6251.   "Assigning Names to Symbols," and 6.3%@BO:       5b018@%, "Using Type Specifiers," present
  6252.   the basic principles of generating symbolic names.%@NL@%
  6253. %@NL@%
  6254. %@4@%  Most symbols are either code labels or variable names. Section 6.4%@BO:       5d761@%,%@EH@%
  6255.   "Defining Code Labels," and Section 6.5%@BO:       5ff03@%, "Defining and Initializing
  6256.   Data," describe how to define these symbols.%@NL@%
  6257. %@NL@%
  6258. %@4@%  This chapter tells you how to assign labels and most kinds of variables.%@EH@%
  6259.   (Multifield variables, such as structures and records, are discussed in
  6260.   Chapter 7%@BO:       69661@%, "Using Structures and Records.") Chapter 6%@BO:       5749b@% also discusses
  6261.   related directives, including those that control the location counter
  6262.   directly. The assembler uses the location counter to assign addresses to
  6263.   symbols.%@NL@%
  6264. %@NL@%
  6265. %@NL@%
  6266. %@2@%%@CR:SC6.1       @%%@AB@%6.1  Constants%@AE@%%@EH@%%@NL@%
  6267. %@NL@%
  6268. %@4@%%@CR:IX6.1       @%  Constants can be used in source files to specify numbers or strings that%@EH@%
  6269.   are set or initialized at assembly time. The assembler recognizes four
  6270.   types of constant values:%@NL@%
  6271. %@NL@%
  6272.   1. Integers%@NL@%
  6273. %@NL@%
  6274.   2. Packed binary coded decimals%@NL@%
  6275. %@NL@%
  6276.   3. Real numbers%@NL@%
  6277. %@NL@%
  6278.   4. Strings%@NL@%
  6279. %@NL@%
  6280. %@NL@%
  6281. %@3@%%@CR:SC6.1.1     @%%@AB@%6.1.1  Integer Constants%@AE@%%@EH@%%@NL@%
  6282. %@NL@%
  6283. %@4@%%@CR:IX6.2       @%%@CR:IX6.3       @%  Integer constants represent integer values. They can be used in a variety%@EH@%
  6284.   of contexts in assembly-language source code. For example, they can be
  6285.   used in data declarations and equates, or as immediate operands.%@NL@%
  6286. %@NL@%
  6287. %@4@%%@CR:IX6.4       @%%@CR:IX6.5       @%  Packed decimal integers are a special kind of integer constant that can%@EH@%
  6288.   only be used to initialize binary coded decimal (BCD) variables. They are
  6289.   described in Sections 6.1.2%@BO:       59313@%, "Packed Binary Coded Decimal Constants," and
  6290.   6.5.1.2%@BO:       59313@%, "Binary Coded Decimal Variables."%@NL@%
  6291. %@NL@%
  6292. %@4@%  Integer constants can be specified in binary, octal, decimal, or%@EH@%
  6293.   hexadecimal values. Table 6.1 shows the legal digits for each of these
  6294.   radixes. For hexadecimal radix, the digits can be either uppercase or
  6295.   lowercase letters.%@NL@%
  6296. %@NL@%
  6297.   %@AB@%Table 6.1 Digits Used with Each Radix%@AE@%%@NL@%
  6298. %@NL@%
  6299.   %@AB@%Radix%@AE@%           %@AB@%Base%@AE@%            %@AB@%Digits%@AE@%%@NL@%
  6300.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6301.   Binary          2               0 1%@NL@%
  6302. %@NL@%
  6303.   Octal           8               0 1 2 3 4 5 6 7%@NL@%
  6304. %@NL@%
  6305.   Decimal         10              0 1 2 3 4 5 6 7 8 9%@NL@%
  6306. %@NL@%
  6307.   Hexadecimal     16              0 1 2 3 4 5 6 7 8 9 A B C D E F%@NL@%
  6308. %@NL@%
  6309.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6310. %@NL@%
  6311. %@NL@%
  6312. %@4@%  The radix for an integer can be defined for a specific integer by using%@EH@%
  6313.   radix specifiers, or a default radix can be defined globally with the
  6314.   %@AB@%.RADIX%@AE@% directive.%@NL@%
  6315. %@NL@%
  6316. %@NL@%
  6317. %@3@%%@CR:SC6.1.1.1   @%%@AB@%6.1.1.1  Specifying Integers with Radix Specifiers%@AE@%%@EH@%%@NL@%
  6318. %@NL@%
  6319. %@4@%%@CR:IX6.6       @%%@CR:IX6.7       @%%@CR:IX6.8       @%%@CR:IX6.9       @%%@CR:IX6.10      @%%@CR:IX6.11      @%  The radix for an integer constant can be given by putting one of the%@EH@%
  6320.   following radix specifiers after the last digit of the number:%@NL@%
  6321. %@NL@%
  6322.   %@AB@%Radix%@AE@%               %@AB@%Specifier%@AE@%%@NL@%
  6323.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6324.   Binary              B%@NL@%
  6325. %@NL@%
  6326.   Octal               Q or O%@NL@%
  6327. %@NL@%
  6328.   Decimal             D%@NL@%
  6329. %@NL@%
  6330.   Hexadecimal         H%@NL@%
  6331. %@NL@%
  6332. %@NL@%
  6333. %@4@%  Radix specifiers can be given in either uppercase or lowercase letters;%@EH@%
  6334.   sample code in this manual uses lowercase letters.%@NL@%
  6335. %@NL@%
  6336. %@4@%%@CR:IX6.12      @%  Hexadecimal numbers must always start with a decimal digit (0-9). If%@EH@%
  6337.   necessary, put a leading 0 at the left of the number to distinguish
  6338.   between symbols and hexadecimal numbers that start with a letter. For
  6339.   example, %@AS@%0ABCh %@AE@%is interpreted as a hexadecimal number, but %@AS@%ABCh %@AE@%is
  6340.   interpreted as a symbol. The hexadecimal digits A through F can be either
  6341.   uppercase or lowercase letters. Sample code in this manual uses uppercase
  6342.   letters.%@NL@%
  6343. %@NL@%
  6344. %@4@%  If no radix is given, the assembler interprets the integer by using the%@EH@%
  6345.   current default radix. The initial default radix is decimal, but you can
  6346.   change the default with the %@AB@%.RADIX%@AE@% directive.%@NL@%
  6347. %@NL@%
  6348. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  6349. %@NL@%
  6350.   %@AS@%n360        EQU    01011010b + 132q + 5Ah + 90d  ; 4 * 90%@AE@%%@NL@%
  6351.   %@AS@%n60         EQU    00001111b +  17o + 0Fh + 15d  ; 4 * 15%@AE@%%@NL@%
  6352. %@NL@%
  6353. %@NL@%
  6354. %@3@%%@CR:SC6.1.1.2   @%%@AB@%6.1.1.2  Setting the Default Radix%@AE@%%@EH@%%@NL@%
  6355. %@NL@%
  6356. %@4@%%@CR:IX6.13      @%%@CR:IX6.14      @%%@CR:IX6.15      @%%@CR:IX6.16      @%%@CR:IX6.17      @%%@CR:IX6.18      @%%@CR:IX6.19      @%%@CR:IX6.20      @%%@CR:IX6.21      @%  The %@AB@%.RADIX%@AE@% directive sets the default radix for integer constants in the%@EH@%
  6357.   source file.%@NL@%
  6358. %@NL@%
  6359. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  6360. %@NL@%
  6361. %@4@%  .%@AB@%RADIX%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  6362. %@NL@%
  6363. %@4@%  The %@AI@%expression%@AE@% must evaluate to a number in the range 2-16. It defines%@EH@%
  6364.   whether the numbers are binary, octal, decimal, hexadecimal, or numbers of
  6365.   some other base.%@NL@%
  6366. %@NL@%
  6367. %@4@%  Numbers given in %@AI@%expression%@AE@% are always considered decimal, regardless of%@EH@%
  6368.   the current default radix. The initial default radix is decimal.%@NL@%
  6369. %@NL@%
  6370. %@4@%  Note that the %@AB@%.RADIX%@AE@% directive does not affect real numbers initialized as%@EH@%
  6371.   variables with the %@AB@%DD%@AE@%, %@AB@%DQ%@AE@%, or %@AB@%DT%@AE@% directive. Initial values for real-number
  6372.   variables declared with these directives are always evaluated as decimal
  6373.   unless a radix specifier is appended.%@NL@%
  6374. %@NL@%
  6375. %@4@%  Also, the %@AB@%.RADIX %@AE@%directive does not affect the optional radix specifiers,%@EH@%
  6376.   B and D, used with integer numbers. When the letters B or D appear at the
  6377.   end of any integer, they are always considered to be a radix specifier
  6378.   even if the current radix is 16.%@NL@%
  6379. %@NL@%
  6380. %@4@%  For example, if the input radix is 16, the number %@AS@%0ABCD %@AE@%will be%@EH@%
  6381.   interpreted as 0ABC decimal, an illegal number, instead of as 0ABCD
  6382.   hexadecimal, as intended. Type %@AS@%0ABCDh %@AE@%to specify 0ABCD in hexadecimal.
  6383.   Similarly, the number %@AS@%11B %@AE@%will be treated as 11 binary, a legal number,
  6384.   but not as 11B hexadecimal as intended. Type %@AS@%11Bh %@AE@%to specify 11B in
  6385.   hexadecimal.%@NL@%
  6386. %@NL@%
  6387. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  6388. %@NL@%
  6389.   %@AS@%            .RADIX  16         ; Set default radix to hexadecimal%@AE@%%@NL@%
  6390.   %@AS@%            .RADIX  2          ; Set default radix to binary%@AE@%%@NL@%
  6391. %@NL@%
  6392. %@NL@%
  6393. %@3@%%@CR:SC6.1.2     @%%@AB@%6.1.2  Packed Binary Coded Decimal Constants%@AE@%%@EH@%%@NL@%
  6394. %@NL@%
  6395. %@4@%%@CR:IX6.22      @%%@CR:IX6.23      @%%@CR:IX6.24      @%  When an integer constant is used with the%@AB@% DT%@AE@% directive, the number is%@EH@%
  6396.   interpreted by default as a packed binary coded decimal (BCD) number. You
  6397.   can use the D radix specifier to override the default and initialize
  6398.   10-byte integers as binary-format integers.%@NL@%
  6399. %@NL@%
  6400. %@4@%  The syntax for specifying binary coded decimals is exactly the same as for%@EH@%
  6401.   other integers. However, the assembler encodes binary coded decimals in a
  6402.   completely different way. See Section 6.5.1.2%@BO:       61d5d@%, "Binary Coded Decimal
  6403.   Variables," for complete information on storage of binary coded decimals.%@NL@%
  6404. %@NL@%
  6405. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  6406. %@NL@%
  6407.   %@AS@%positive    DT     1234567890  ; Encoded as 00000000001234567890h%@AE@%%@NL@%
  6408.   %@AS@%negative    DT     -1234567890 ; Encoded as 80000000001234567890h%@AE@%%@NL@%
  6409. %@NL@%
  6410. %@NL@%
  6411. %@3@%%@CR:SC6.1.3     @%%@AB@%6.1.3  Real-Number Constants%@AE@%%@EH@%%@NL@%
  6412. %@NL@%
  6413. %@4@%%@CR:IX6.25      @%%@CR:IX6.26      @%  A real number is a number consisting of an integer part, a fractional%@EH@%
  6414.   part, and an exponent. Real numbers are usually represented in decimal
  6415.   format.%@NL@%
  6416. %@NL@%
  6417. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  6418. %@NL@%
  6419. %@4@%  [[%@AB@%+%@AE@% | %@AB@%-%@AE@%]] %@AI@%integer%@AE@%%@AB@%.%@AE@%%@AI@%fraction%@AE@%[[%@AB@%E%@AE@%[[%@AB@%+%@AE@% | %@AB@%-%@AE@%]]%@AI@%exponent%@AE@%]]%@EH@%%@NL@%
  6420. %@NL@%
  6421. %@4@%%@CR:IX6.27      @%%@CR:IX6.28      @%  The %@AI@%integer%@AE@% and %@AI@%fraction%@AE@% parts combine to form the value of the number.%@EH@%
  6422.   This value is stored internally as a unit and is called the mantissa. It
  6423.   may be signed. The optional %@AI@%exponent%@AE@% follows the exponent indicator (E).
  6424.   It represents the magnitude of the value and is stored internally as a
  6425.   unit. If no exponent is given, 1 is assumed. If an exponent is given, it
  6426.   may be signed.%@NL@%
  6427. %@NL@%
  6428. %@4@%%@CR:IX6.29      @%%@CR:IX6.30      @%  During assembly, the assembler converts real-number constants given in%@EH@%
  6429.   decimal format to a binary format. The sign, exponent, and mantissa of the
  6430.   real number are encoded as bit fields within the number. See Section
  6431.   6.5.1.4%@BO:       62baf@%, "Real-Number Variables," for an explanation of how real numbers
  6432.   are encoded.%@NL@%
  6433. %@NL@%
  6434. %@4@%  You can specify the encoded format directly using hexadecimal digits (0-9%@EH@%
  6435.   or A-F). The number must begin with a decimal digit (0-9) and cannot be
  6436.   signed. It must be followed by the real-number designator (R). This
  6437.   designator is used the same as a radix designator except it specifies that
  6438.   the given hexadecimal number should be interpreted as a real number.%@NL@%
  6439. %@NL@%
  6440. %@4@%  Real numbers can only be used to initialize variables with the %@AB@%DD%@AE@%, %@AB@%DQ%@AE@%, and%@EH@%
  6441.   %@AB@%DT%@AE@% directives. They cannot be used in expressions. The maximum number of
  6442.   digits in the number and the maximum range of exponent values depend on
  6443.   the directive. The number of digits for encoded numbers used with%@AB@% DD%@AE@%, %@AB@%DQ%@AE@%,
  6444.   and %@AB@%DT%@AE@% must be 8, 16, and 20 digits, respectively. (If a leading 0 is
  6445.   supplied, the number must be 9, 17, or 21 digits.) See Section 6.5.1.4%@BO:       62baf@%,
  6446.   "Real-Number Variables," for an explanation of how real numbers are
  6447.   encoded.%@NL@%
  6448. %@NL@%
  6449.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6450. %@CR:IX6.31      @%%@CR:IX6.32      @%  %@AB@%NOTE%@AE@%  Real numbers will be encoded differently depending upon whether you
  6451.   use the %@AB@%.MSFLOAT %@AE@%directive. By default, real numbers are encoded in the
  6452.   IEEE format. The %@AB@%.MSFLOAT %@AE@%directive overrides the default and specifies
  6453.   Microsoft Binary format. See Section 6.5.1.4%@BO:       62baf@%, "Real-Number Variables,"
  6454.   for a description of these formats.%@NL@%
  6455.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6456. %@NL@%
  6457. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  6458. %@NL@%
  6459.   %@AS@%; Real numbers%@AE@%%@NL@%
  6460.   %@AS@%shrt        DD     25.23%@AE@%%@NL@%
  6461.   %@AS@%long        DQ     2.523E1%@AE@%%@NL@%
  6462.   %@AS@%ten_byte    DT     2523.0E-2%@AE@%%@NL@%
  6463. %@NL@%
  6464.   %@AS@%; Assumes .MSFLOAT%@AE@%%@NL@%
  6465.   %@AS@%mbshort     DD     81000000r             ; 1.0 as Microsoft Binary short%@AE@%%@NL@%
  6466.   %@AS@%mblong      DQ     8100000000000000r     ; 1.0 as Microsoft Binary long%@AE@%%@NL@%
  6467. %@NL@%
  6468.   %@AS@%; Assumes default IEEE format%@AE@%%@NL@%
  6469.   %@AS@%ieeeshort   DD     3F800000r             ; 1.0 as IEEE short%@AE@%%@NL@%
  6470.   %@AS@%ieeelong    DQ     3FF0000000000000r     ; 1.0 as IEEE long%@AE@%%@NL@%
  6471. %@NL@%
  6472.   %@AS@%; The same regardless of processor directives%@AE@%%@NL@%
  6473.   %@AS@%temporary   DT     3FFF8000000000000000r ; 1.0 as 10-byte temporary real%@AE@%%@NL@%
  6474. %@NL@%
  6475. %@NL@%
  6476. %@3@%%@CR:SC6.1.4     @%%@AB@%6.1.4  String Constants%@AE@%%@EH@%%@NL@%
  6477. %@NL@%
  6478. %@4@%%@CR:IX6.33      @%%@CR:IX6.34      @%%@CR:IX6.35      @%  A string constant consists of one or more ASCII characters enclosed in%@EH@%
  6479.   single or double quotation marks. Strings are interpreted as lists of
  6480.   characters having the ASCII values of the characters in the string.%@NL@%
  6481. %@NL@%
  6482. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  6483. %@NL@%
  6484. %@4@%  %@AB@%'%@AE@%%@AI@%characters%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@%
  6485.   %@AB@%"%@AE@%%@AI@%characters%@AE@%%@AB@%"%@AE@%%@NL@%
  6486. %@NL@%
  6487. %@4@%  String constants are case sensitive. A string constant consisting of a%@EH@%
  6488.   single character is sometimes called a character constant.%@NL@%
  6489. %@NL@%
  6490. %@4@%  Single quotation marks must be encoded twice when used literally within%@EH@%
  6491.   string constants that are also enclosed by single quotation marks.
  6492.   Similarly, double quotation marks must be encoded twice when used in
  6493.   string constants that are also enclosed by double quotation marks.%@NL@%
  6494. %@NL@%
  6495. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  6496. %@NL@%
  6497.   %@AS@%char        DB      'a'%@AE@%%@NL@%
  6498.   %@AS@%char2       DB      "a"%@AE@%%@NL@%
  6499.   %@AS@%message     DB      "This is a message."%@AE@%%@NL@%
  6500.   %@AS@%warn        DB      'Can"t find file.'          ; Can't find file.%@AE@%%@NL@%
  6501.   %@AS@%warn2       DB      "Can't find file."          ; Can't find file.%@AE@%%@NL@%
  6502.   %@AS@%string      DB      "This ""value"" not found." ; This "value" not found.%@AE@%%@NL@%
  6503.   %@AS@%string2     DB      'This "value" not found.'   ; This "value" not found.%@AE@%%@NL@%
  6504. %@NL@%
  6505. %@NL@%
  6506. %@3@%%@CR:SC6.1.5     @%%@AB@%6.1.5  Determining Floating-Point Format%@AE@%%@EH@%%@NL@%
  6507. %@NL@%
  6508. %@4@%%@CR:IX6.36      @%%@CR:IX6.37      @%  The %@AB@%.MSFLOAT%@AE@% directive disables all coprocessor instructions and specifies%@EH@%
  6509.   that initialized real-number variables be encoded in the Microsoft Binary
  6510.   format. Without this directive, initialized real-number variables are
  6511.   encoded in the IEEE format. This is a change from Versions 4.0 and earlier
  6512.   of the Microsoft Macro Assembler, which used Microsoft Binary format by
  6513.   default and required a coprocessor directive or the /R option to specify
  6514.   IEEE format. %@AB@%.MSFLOAT %@AE@%must be used for programs that require real-number
  6515.   data in the Microsoft Binary format. Section 6.5.1.4%@BO:       62baf@%, "Real-Number
  6516.   Variables," describes real-number data formats and the factors to consider
  6517.   in choosing a format.%@NL@%
  6518. %@NL@%
  6519. %@NL@%
  6520. %@2@%%@CR:SC6.2       @%%@AB@%6.2  Assigning Names to Symbols%@AE@%%@EH@%%@NL@%
  6521. %@NL@%
  6522. %@4@%%@CR:IX6.38      @%  A symbol is a name that represents a value. Symbols are one of the most%@EH@%
  6523.   important elements of assembly-language programs. Elements that must be
  6524.   represented symbolically in assembly-language source code include
  6525.   variables, address labels, macros, segments, procedures, records, and
  6526.   structures. Constants, expressions, and strings can also be represented
  6527.   symbolically.%@NL@%
  6528. %@NL@%
  6529. %@4@%%@CR:IX6.39      @%%@CR:IX6.40      @%  Symbol names are combinations of letters (both uppercase and lowercase),%@EH@%
  6530.   digits, and special characters. The QuickAssembler recognizes the
  6531.   following character set:%@NL@%
  6532. %@NL@%
  6533. %@4@%  %@AS@%A-Z a-z 0-9%@AE@%%@EH@%%@NL@%
  6534. %@NL@%
  6535. %@4@%  %@AS@%? @ _ $ : . [ ] ( ) < > { } + - / *%@AE@%%@EH@%%@NL@%
  6536. %@NL@%
  6537. %@4@%  %@AS@%& % ! ' ~ | \ = # ^ ; , ` "%@AE@%%@EH@%%@NL@%
  6538. %@NL@%
  6539. %@4@%  Letters, digits, and some characters can be used in symbol names, but some%@EH@%
  6540.   restrictions on how certain characters can be used or combined are listed
  6541.   below:%@NL@%
  6542. %@NL@%
  6543.   ■  A name can have any combination of uppercase and lowercase letters.
  6544.      Within the QC integrated environment, the default behavior (Preserve
  6545.      Extrn) is for the assembler to convert all symbol names to uppercase
  6546.      unless they are public or external. When you use simplified segment
  6547.      directives, all procedure labels declared with %@AB@%PROC%@AE@% are automatically
  6548.      public.%@NL@%
  6549. %@NL@%
  6550.      When you use QCL, all lowercase letters are converted to uppercase by
  6551.      the assembler, unless you give the /Cl assembly option, or you declare
  6552.      the name with a %@AB@%PROC%@AE@%, %@AB@%PUBLIC%@AE@%, or %@AB@%EXTRN%@AE@% directive and you give the /Cx
  6553.      option. The /Cl and /Cx options correspond to the assembler flags
  6554.      Preserve Case and Preserve Extrn, respectively, within the QC
  6555.      environment.%@NL@%
  6556. %@NL@%
  6557.   ■  Digits may be used within a name, but not as the first character.%@NL@%
  6558. %@NL@%
  6559.   ■  A name can be given any number of characters, but only the first 31 are
  6560.      used. All other characters are ignored.%@NL@%
  6561. %@NL@%
  6562. %@CR:IX6.41      @%%@CR:IX6.42      @%%@CR:IX6.43      @%%@CR:IX6.44      @%%@CR:IX6.45      @%%@CR:IX6.46      @%%@CR:IX6.47      @%  ■  The following characters may be used at the beginning of a name or
  6563.      within a name: underscore (_), question mark (?), dollar sign ($), and
  6564.      at sign (@).%@NL@%
  6565. %@NL@%
  6566. %@CR:IX6.48      @%%@CR:IX6.49      @%  ■  The period (.) is an operator and cannot be used within a name, but it
  6567.      can be used as the first character of a name.%@NL@%
  6568. %@NL@%
  6569.   ■  A name may not be the same as any reserved name. Note that two special
  6570.      characters, the question mark (?) and the dollar sign ($), are reserved
  6571.      names and therefore can't stand alone as symbol names.%@NL@%
  6572. %@NL@%
  6573. %@4@%%@CR:IX6.50      @%%@CR:IX6.51      @%  A reserved name is any name with a special, predefined meaning to the%@EH@%
  6574.   assembler. Reserved names include instruction and directive mnemonics,
  6575.   register names, and operator names. All uppercase and lowercase letter
  6576.   combinations of these names are treated as the same name.%@NL@%
  6577. %@NL@%
  6578. %@4@%  The following is a list of names that are always reserved by the%@EH@%
  6579.   assembler. Using any of these names for a symbol results in an error.%@NL@%
  6580. %@NL@%
  6581. %@4@%%@AB@%  $                 DWORD               GE                  %OUT%@AE@%%@EH@%%@NL@%
  6582. %@4@%%@AB@%  *                 ELSE                GROUP               PAGE%@AE@%%@EH@%%@NL@%
  6583. %@4@%%@AB@%  +                 ELSEIF              GT                  PROC%@AE@%%@EH@%%@NL@%
  6584. %@4@%%@AB@%  -                 ELSEIF1             HIGH                PTR%@AE@%%@EH@%%@NL@%
  6585. %@4@%%@AB@%  .                 ELSEIF2             IF                  PUBLIC%@AE@%%@EH@%%@NL@%
  6586. %@4@%%@AB@%  /                 ELSEIFB             IF1                 PURGE%@AE@%%@EH@%%@NL@%
  6587. %@4@%%@AB@%  =                 ELSEIFDEF           IF2                 QWORD%@AE@%%@EH@%%@NL@%
  6588. %@4@%%@AB@%  ?                 ELSEIFDIF           IFB                 .RADIX%@AE@%%@EH@%%@NL@%
  6589. %@4@%%@AB@%  []                ELSEIFDIFI          IFDEF               RECORD%@AE@%%@EH@%%@NL@%
  6590. %@4@%%@AB@%  .186              ELSEIFE             IFDIF               REPT%@AE@%%@EH@%%@NL@%
  6591. %@4@%%@AB@%  .286              ELSEIFIDN           IFE                 .SALL%@AE@%%@EH@%%@NL@%
  6592. %@4@%%@AB@%  .286P             ELSEIFIDNI          IFIDN               SEG%@AE@%%@EH@%%@NL@%
  6593. %@4@%%@AB@%  .287              ELSEIFNB            IFNB                SEGMENT%@AE@%%@EH@%%@NL@%
  6594. %@4@%%@AB@%  .386              ELSEIFNDEF          IFNDEF              .SEQ%@AE@%%@EH@%%@NL@%
  6595. %@4@%%@AB@%  .386P             END                 INCLUDE             .SFCOND%@AE@%%@EH@%%@NL@%
  6596. %@4@%%@AB@%  .387              ENDIF               INCLUDELIB          SHL%@AE@%%@EH@%%@NL@%
  6597. %@4@%%@AB@%  .8086             ENDM                IRP                 SHORT%@AE@%%@EH@%%@NL@%
  6598. %@4@%%@AB@%  .8087             ENDP                IRPC                SHR%@AE@%%@EH@%%@NL@%
  6599. %@4@%%@AB@%  ALIGN             ENDS                LABEL               SIZE%@AE@%%@EH@%%@NL@%
  6600. %@4@%%@AB@%  .ALPHA            EQ                  .LALL               SIZESTR%@AE@%%@EH@%%@NL@%
  6601. %@4@%%@AB@%  AND               EQU                 LE                  .STACK%@AE@%%@EH@%%@NL@%
  6602. %@4@%%@AB@%  ASSUME            .ERR                LENGTH              .STARTUP%@AE@%%@EH@%%@NL@%
  6603. %@4@%%@AB@%  BYTE              .ERR1               .LFCOND             STRUC%@AE@%%@EH@%%@NL@%
  6604. %@4@%%@AB@%  CATSTR            .ERR2               .LIST               SUBSTR%@AE@%%@EH@%%@NL@%
  6605. %@4@%%@AB@%  .CODE             .ERRB               LOCAL               SUBTTL%@AE@%%@EH@%%@NL@%
  6606. %@4@%%@AB@%  COMM              .ERRDEF             LOW                 TBYTE%@AE@%%@EH@%%@NL@%
  6607. %@4@%%@AB@%  COMMENT           .ERRDIF             LT                  .TFCOND%@AE@%%@EH@%%@NL@%
  6608. %@4@%%@AB@%  .CONST            .ERRE               MACRO               THIS%@AE@%%@EH@%%@NL@%
  6609. %@4@%%@AB@%  .CREF             .ERRIDN             MASK                TITLE%@AE@%%@EH@%%@NL@%
  6610. %@4@%%@AB@%  .DATA             .ERRNB              MOD                 TYPE%@AE@%%@EH@%%@NL@%
  6611. %@4@%%@AB@%  .DATA?            .ERRNDEF            .MODEL              .TYPE%@AE@%%@EH@%%@NL@%
  6612. %@4@%%@AB@%  DB                .ERRNZ              NAME                WIDTH%@AE@%%@EH@%%@NL@%
  6613. %@4@%%@AB@%  DD                EVEN                NE                  WORD%@AE@%%@EH@%%@NL@%
  6614. %@4@%%@AB@%  DOSSEG            EXITM               NEAR                .XALL%@AE@%%@EH@%%@NL@%
  6615. %@4@%%@AB@%  DQ                EXTRN               NOT                 .XCREF%@AE@%%@EH@%%@NL@%
  6616. %@4@%%@AB@%  DS                FAR                 OFFSET              .XLIST%@AE@%%@EH@%%@NL@%
  6617. %@4@%%@AB@%  DT                .FARDATA            OR                  XOR%@AE@%%@EH@%%@NL@%
  6618. %@NL@%
  6619. %@4@%  In addition to the names listed above, instruction mnemonics and register%@EH@%
  6620.   names are considered reserved names. Instructions can vary depending on
  6621.   the processor directives given in the source file. For example,%@AB@% ENTER%@AE@% is
  6622.   recognized as a reserved word if you have enabled 286 instructions with
  6623.   the %@AB@%.286%@AE@% directive. Section 18.3%@BO:       ebd6e@% describes processor directives.
  6624.   Instruction mnemonics for each processor are listed in the on-line Help
  6625.   system. Register names are listed in Section 2.6.2%@BO:       25a37@%, "Register Operands."%@NL@%
  6626. %@NL@%
  6627. %@NL@%
  6628. %@2@%%@CR:SC6.3       @%%@AB@%6.3  Using Type Specifiers%@AE@%%@EH@%%@NL@%
  6629. %@NL@%
  6630. %@4@%%@CR:IX6.52      @%  Some statements require type specifiers to give the size or type of an%@EH@%
  6631.   operand. There are two kinds of type specifiers: those that specify the
  6632.   size of a variable or other memory operand, and those that specify the
  6633.   distance of a label.%@NL@%
  6634. %@NL@%
  6635. %@4@%%@CR:IX6.53      @%%@CR:IX6.54      @%%@CR:IX6.55      @%%@CR:IX6.56      @%%@CR:IX6.57      @%%@CR:IX6.58      @%%@CR:IX6.59      @%  The type specifiers that give the size of a memory operand are listed%@EH@%
  6636.   below with the number of bytes specified by each:%@NL@%
  6637. %@NL@%
  6638.   %@AB@%Specifier%@AE@%           %@AB@%Number of Bytes%@AE@%%@NL@%
  6639.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6640.   %@AB@%BYTE%@AE@%                1%@NL@%
  6641. %@NL@%
  6642.   %@AB@%WORD%@AE@%                2%@NL@%
  6643. %@NL@%
  6644.   %@AB@%DWORD%@AE@%               4%@NL@%
  6645. %@NL@%
  6646.   %@AB@%QWORD%@AE@%               8%@NL@%
  6647. %@NL@%
  6648.   %@AB@%TBYTE%@AE@%               10%@NL@%
  6649. %@NL@%
  6650. %@NL@%
  6651. %@4@%  In some contexts, %@AB@%ABS%@AE@% can also be used as a type specifier that indicates%@EH@%
  6652.   an operand is a constant rather than a memory operand.%@NL@%
  6653. %@NL@%
  6654. %@4@%%@CR:IX6.60      @%%@CR:IX6.61      @%%@CR:IX6.62      @%  The type specifiers that give the distance of a label are listed below:%@EH@%%@NL@%
  6655. %@NL@%
  6656.   %@AB@%Specifier%@AE@%           %@AB@%Description%@AE@%%@NL@%
  6657.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6658.   %@AB@%FAR%@AE@%                 The label references both the segment and offset of
  6659.                       the label.%@NL@%
  6660. %@NL@%
  6661.   %@AB@%NEAR%@AE@%                The label references only the offset of the label.%@NL@%
  6662. %@NL@%
  6663.   %@AB@%PROC%@AE@%                The label has the default type (%@AB@%NEAR%@AE@% or%@AB@% FAR%@AE@%) of the
  6664.                       current memory model. The default size is always %@AB@%NEAR%@AE@%
  6665.                       if you use full segment definitions. If you use
  6666.                       simplified segment directives (see Section 5.1%@BO:       406ed@%), the
  6667.                       default type is%@AB@% NEAR%@AE@% for small and compact models or
  6668.                       %@AB@%FAR%@AE@% for medium, large, and huge models.%@NL@%
  6669. %@NL@%
  6670. %@NL@%
  6671. %@4@%  Directives that use type specifiers include %@AB@%LABEL%@AE@%, %@AB@%PROC%@AE@%, %@AB@%EXTRN%@AE@%, and %@AB@%COMM%@AE@%.%@EH@%
  6672.   Operators that use type specifiers include %@AB@%PTR%@AE@% and %@AB@%THIS%@AE@%.%@NL@%
  6673. %@NL@%
  6674. %@NL@%
  6675. %@2@%%@CR:SC6.4       @%%@AB@%6.4  Defining Code Labels%@AE@%%@EH@%%@NL@%
  6676. %@NL@%
  6677. %@4@%  Code labels give symbolic names to the addresses of instructions in the%@EH@%
  6678.   code segment. These labels can be used as the operands to jump, call, and
  6679.   loop instructions to transfer program control to a new instruction.%@NL@%
  6680. %@NL@%
  6681. %@NL@%
  6682. %@3@%%@CR:SC6.4.1     @%%@AB@%6.4.1  Near-Code Labels%@AE@%%@EH@%%@NL@%
  6683. %@NL@%
  6684. %@4@%%@CR:IX6.63      @%  Near-label definitions create instruction labels that have %@AB@%NEAR%@AE@% type.%@EH@%
  6685.   These instruction labels can be used to access the address of the label
  6686.   from other statements.%@NL@%
  6687. %@NL@%
  6688. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  6689. %@NL@%
  6690. %@4@%  %@AI@%name%@AE@%%@AB@%:%@AE@%%@EH@%%@NL@%
  6691. %@NL@%
  6692. %@4@%  The %@AI@%name%@AE@% must be followed by a colon (%@AB@%:%@AE@%). The segment containing the%@EH@%
  6693.   definition must be the one that the assembler currently associates with
  6694.   the CS register. The %@AB@%ASSUME%@AE@% directive is used to associate a segment with
  6695.   a segment register (see Section 5.4%@BO:       52503@%, "Associating Segments with
  6696.   Registers"). A near label can appear on a line by itself or on a line with
  6697.   an instruction.%@NL@%
  6698. %@NL@%
  6699. %@4@%  Near-code labels have different behavior depending on whether they are%@EH@%
  6700.   used in a procedure with the extended %@AB@%PROC%@AE@% syntax. When the extended %@AB@%PROC%@AE@%
  6701.   feature is used (which requires that %@AB@%.MODEL%@AE@% and a language must be
  6702.   specified), near labels are local to the procedure. This functionality is
  6703.   explained in Section 15.3.7%@BO:       cc4c8@%, "Variable Scope."%@NL@%
  6704. %@NL@%
  6705. %@4@%%@CR:IX6.64      @%%@CR:IX6.65      @%%@CR:IX6.66      @%%@CR:IX6.67      @%%@CR:IX6.68      @%  If the full segments are used or if the language argument is not supplied%@EH@%
  6706.   to the %@AB@%.MODEL%@AE@% directive, near labels are known throughout the module in
  6707.   which they occur. The same label name can be used in different modules as
  6708.   long as each label is only referenced by instructions in its own module.
  6709.   If a label must be referenced by instructions in another module, it must
  6710.   be given a unique name and declared with the %@AB@%PUBLIC%@AE@% and %@AB@%EXTRN%@AE@% directives,
  6711.   as described in Chapter 8%@BO:       70f6e@%, "Creating Programs from Multiple Modules."%@NL@%
  6712. %@NL@%
  6713. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  6714. %@NL@%
  6715.   %@AS@%            cmp    ax,5        ; Compare with 5%@AE@%%@NL@%
  6716.   %@AS@%            ja     bigger%@AE@%%@NL@%
  6717.   %@AS@%            jb     smaller%@AE@%%@NL@%
  6718.   %@AS@%            .                  ; Instructions if AX = 5%@AE@%%@NL@%
  6719.   %@AS@%            .%@AE@%%@NL@%
  6720.   %@AS@%            .%@AE@%%@NL@%
  6721.   %@AS@%            jmp    done%@AE@%%@NL@%
  6722.   %@AS@%bigger:     .                  ; Instructions if AX > 5%@AE@%%@NL@%
  6723.   %@AS@%            .%@AE@%%@NL@%
  6724.   %@AS@%            .%@AE@%%@NL@%
  6725.   %@AS@%            jmp    done%@AE@%%@NL@%
  6726.   %@AS@%smaller:    .                  ; Instructions if AX < 5%@AE@%%@NL@%
  6727.   %@AS@%            .%@AE@%%@NL@%
  6728.   %@AS@%            .%@AE@%%@NL@%
  6729.   %@AS@%done:%@AE@%%@NL@%
  6730. %@NL@%
  6731. %@NL@%
  6732. %@3@%%@CR:SC6.4.2     @%%@AB@%6.4.2  Anonymous Labels%@AE@%%@EH@%%@NL@%
  6733. %@NL@%
  6734. %@4@%  The assembler provides a way to generate automatic labels for jump%@EH@%
  6735.   instructions. To define a label, use two at signs (@@) followed by a colon
  6736.   (:). To jump to the nearest preceding anonymous label, use @B (back) in
  6737.   the jump instruction's operand field; to jump to the nearest following
  6738.   anonymous label, use @F (forward) in the operand field.%@NL@%
  6739. %@NL@%
  6740. %@4@%  You can use two at signs (@@) to define any number of anonymous labels in%@EH@%
  6741.   your program. The items @B and @F always refer to the nearest occurrences
  6742.   of @@, so there is never any conflict between different anonymous labels.%@NL@%
  6743. %@NL@%
  6744. %@4@%  Anonymous labels are best used for conditionally executing a few lines of%@EH@%
  6745.   code. The advantage is that you do not need to continually think up new
  6746.   label names. The disadvantage is that they do not provide a meaningful
  6747.   name. You should mark major divisions of a program with actual named
  6748.   labels.%@NL@%
  6749. %@NL@%
  6750. %@4@%  The following example shows a typical sequence of code with a%@EH@%
  6751.   jump-to-label instruction:%@NL@%
  6752. %@NL@%
  6753.   %@AS@%; DX is 20, unless CX is less than -20, then make DX 30%@AE@%%@NL@%
  6754.   %@AS@%            mov    dx,20%@AE@%%@NL@%
  6755.   %@AS@%            cmp    cx,-20%@AE@%%@NL@%
  6756.   %@AS@%            jge    greatequ%@AE@%%@NL@%
  6757.   %@AS@%            mov    dx,30%@AE@%%@NL@%
  6758.   %@AS@%greatequ:%@AE@%%@NL@%
  6759. %@NL@%
  6760. %@4@%  Here are the same lines rewritten to use an anonymous label:%@EH@%%@NL@%
  6761. %@NL@%
  6762.   %@AS@%; DX is 20, unless CX is less than -20, then make DX 30%@AE@%%@NL@%
  6763.   %@AS@%            mov    dx,20%@AE@%%@NL@%
  6764.   %@AS@%            cmp    cx,-20%@AE@%%@NL@%
  6765.   %@AS@%            jge    @F%@AE@%%@NL@%
  6766.   %@AS@%            mov    dx,30%@AE@%%@NL@%
  6767.   %@AS@%@@:%@AE@%%@NL@%
  6768. %@NL@%
  6769. %@NL@%
  6770. %@3@%%@CR:SC6.4.3     @%%@AB@%6.4.3  Procedure Labels%@AE@%%@EH@%%@NL@%
  6771. %@NL@%
  6772. %@4@%%@CR:IX6.69      @%%@CR:IX6.70      @%%@CR:IX6.71      @%%@CR:IX6.72      @%  The easiest way to declare a procedure is to use the %@AB@%PROC%@AE@% and %@AB@%ENDP%@AE@%%@EH@%
  6773.   directives. The former declares the beginning of the procedure, and the
  6774.   latter declares the end.%@NL@%
  6775. %@NL@%
  6776. %@4@%  The%@AB@% PROC%@AE@% directive has the following syntax:%@EH@%%@NL@%
  6777. %@NL@%
  6778. %@4@%  %@AI@%label%@AE@% %@AB@%PROC%@AE@% [[%@AB@%NEAR%@AE@%|%@AB@%FAR%@AE@%]]%@EH@%%@NL@%
  6779.   %@AI@%statements%@AE@%%@NL@%
  6780.   %@AB@%RET%@AE@% [[%@AI@%constant%@AE@%]]%@NL@%
  6781.   %@AI@%label%@AE@% ENDP%@NL@%
  6782. %@NL@%
  6783. %@4@%%@CR:IX6.73      @%%@CR:IX6.74      @%  The %@AI@%label%@AE@% assigns a symbol to the procedure. The distance can be %@AB@%NEAR%@AE@% or%@EH@%
  6784.   %@AB@%FAR%@AE@%. Any %@AB@%RET%@AE@% instructions within the procedure automatically have the same
  6785.   distance (%@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@%) as the procedure.%@NL@%
  6786. %@NL@%
  6787. %@4@%  The syntax shown here is always available. In addition, there is an%@EH@%
  6788.   extended %@AB@%PROC%@AE@% syntax available if you use %@AB@%.MODEL%@AE@% and specify a language.
  6789.   The extended %@AB@%PROC%@AE@% syntax is explained in Section 15.3.4%@BO:       c7284@%, "Declaring
  6790.   Parameters with the PROC Directive."%@NL@%
  6791. %@NL@%
  6792. %@4@%%@CR:IX6.75      @%%@CR:IX6.76      @%%@CR:IX6.77      @%  The %@AB@%ENDP%@AE@% directive labels the address where the procedure ends. Every%@EH@%
  6793.   procedure label must have a matching %@AB@%ENDP%@AE@% label to mark the end of the
  6794.   procedure. QuickAssembler generates an error message if it does not find
  6795.   an %@AB@%ENDP%@AE@% directive to match each %@AB@%PROC%@AE@% directive.%@NL@%
  6796. %@NL@%
  6797. %@4@%  When the %@AB@%PROC%@AE@% label definition is encountered, the assembler sets the%@EH@%
  6798.   label's value to the current value of the location counter and sets its
  6799.   type to %@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@%. If the label has %@AB@%FAR%@AE@% type, the assembler also sets
  6800.   its segment value to that of the enclosing segment. If you have specified
  6801.   full segment definitions, the default distance is %@AB@%NEAR%@AE@%. If you are using
  6802.   simplified segment directives, the default distance is the distance
  6803.   associated with the declared memory model──that is, %@AB@%NEAR%@AE@% for small and
  6804.   compact models or %@AB@%FAR%@AE@% for medium, large, and huge models.%@NL@%
  6805. %@NL@%
  6806. %@4@%%@CR:IX6.78      @%%@CR:IX6.79      @%  The procedure label can be used in a %@AB@%CALL%@AE@% instruction to direct execution%@EH@%
  6807.   control to the first instruction of the procedure. Control can be
  6808.   transferred to a %@AB@%NEAR%@AE@% procedure label from any address in the same segment
  6809.   as the label. Control can be transferred to a %@AB@%FAR%@AE@% procedure label from an
  6810.   address in any segment.%@NL@%
  6811. %@NL@%
  6812. %@4@%%@CR:IX6.80      @%  Procedure labels must be declared with the %@AB@%PUBLIC%@AE@% and %@AB@%EXTRN%@AE@% directives if%@EH@%
  6813.   they are located in one module but called from another module, as
  6814.   described in Chapter 8%@BO:       70f6e@%, "Creating Programs from Multiple Modules."%@NL@%
  6815. %@NL@%
  6816. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  6817. %@NL@%
  6818.   %@AS@%            call   task        ; Call procedure%@AE@%%@NL@%
  6819.   %@AS@%            .%@AE@%%@NL@%
  6820.   %@AS@%            .%@AE@%%@NL@%
  6821.   %@AS@%            .%@AE@%%@NL@%
  6822.   %@AS@%task        PROC   NEAR        ; Start of procedure%@AE@%%@NL@%
  6823.   %@AS@%            .%@AE@%%@NL@%
  6824.   %@AS@%            .%@AE@%%@NL@%
  6825.   %@AS@%            .%@AE@%%@NL@%
  6826.   %@AS@%            ret%@AE@%%@NL@%
  6827.   %@AS@%task        ENDP               ; End of procedure%@AE@%%@NL@%
  6828. %@NL@%
  6829. %@NL@%
  6830. %@3@%%@CR:SC6.4.4     @%%@AB@%6.4.4  Code Labels Defined with the LABEL Directive%@AE@%%@EH@%%@NL@%
  6831. %@NL@%
  6832. %@4@%%@CR:IX6.81      @%%@CR:IX6.82      @%  The %@AB@%LABEL%@AE@% directive provides an alternative method of defining code%@EH@%
  6833.   labels.%@NL@%
  6834. %@NL@%
  6835. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  6836. %@NL@%
  6837. %@4@%  %@AI@%name%@AE@% %@AB@%LABEL%@AE@% %@AI@%distance%@AE@%%@EH@%%@NL@%
  6838. %@NL@%
  6839. %@4@%  The %@AI@%name%@AE@% is the symbol name assigned to the label. The %@AI@%distance%@AE@% can be a%@EH@%
  6840.   type specifier, such as %@AB@%NEAR%@AE@%, %@AB@%FAR%@AE@%, or %@AB@%PROC%@AE@%. %@AB@%PROC%@AE@% means %@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@%,
  6841.   depending on the default memory model, as described in Section 5.1.3%@BO:       42b44@%,
  6842.   "Defining Basic Attributes of the Module." You can use the %@AB@%LABEL%@AE@% directive
  6843.   to define a second entry point into a procedure. %@AB@%FAR%@AE@% code labels can also
  6844.   be the destination of far jumps or of far calls that use the %@AB@%RETF%@AE@%
  6845.   instruction (see Section 15.3.2%@BO:       c4c26@%, "Defining Procedures").%@NL@%
  6846. %@NL@%
  6847. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  6848. %@NL@%
  6849.   %@AS@%task        PROC   FAR         ; Main entry point%@AE@%%@NL@%
  6850.   %@AS@%            .%@AE@%%@NL@%
  6851.   %@AS@%            .%@AE@%%@NL@%
  6852.   %@AS@%            .%@AE@%%@NL@%
  6853.   %@AS@%task1       LABEL  FAR         ; Secondary entry point%@AE@%%@NL@%
  6854.   %@AS@%            .%@AE@%%@NL@%
  6855.   %@AS@%            .%@AE@%%@NL@%
  6856.   %@AS@%            .%@AE@%%@NL@%
  6857.   %@AS@%            ret%@AE@%%@NL@%
  6858.   %@AS@%task        ENDP               ; End of procedure%@AE@%%@NL@%
  6859. %@NL@%
  6860. %@NL@%
  6861. %@2@%%@CR:SC6.5       @%%@AB@%6.5  Defining and Initializing Data%@AE@%%@EH@%%@NL@%
  6862. %@NL@%
  6863. %@4@%%@CR:IX6.83      @%  The data-definition directives enable you to allocate memory for data. At%@EH@%
  6864.   the same time, you can specify the initial values for the allocated data.
  6865.   Data can be specified as numbers, strings, or expressions that evaluate to
  6866.   constants. The assembler translates these constant values into binary
  6867.   bytes, words, or other units of data. The encoded data is written to the
  6868.   object file at assembly time.%@NL@%
  6869. %@NL@%
  6870. %@NL@%
  6871. %@3@%%@CR:SC6.5.1     @%%@AB@%6.5.1  Variables%@AE@%%@EH@%%@NL@%
  6872. %@NL@%
  6873. %@4@%%@CR:IX6.84      @%  Variables consist of one or more named data objects of a specified size.%@EH@%%@NL@%
  6874. %@NL@%
  6875. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  6876. %@NL@%
  6877. %@4@%  [[%@AI@%name%@AE@%]] %@AI@%directive%@AE@% %@AI@%initializer%@AE@% [[%@AB@%,%@AE@%%@AI@%initializer%@AE@%]]...%@EH@%%@NL@%
  6878. %@NL@%
  6879. %@4@%  The %@AI@%name%@AE@% is the symbol name assigned to the variable. If no name is%@EH@%
  6880.   assigned, the data is allocated; but the starting address of the variable
  6881.   has no symbolic name.%@NL@%
  6882. %@NL@%
  6883. %@4@%%@CR:IX6.85      @%%@CR:IX6.86      @%%@CR:IX6.87      @%%@CR:IX6.88      @%%@CR:IX6.89      @%%@CR:IX6.90      @%%@CR:IX6.91      @%%@CR:IX6.92      @%%@CR:IX6.93      @%%@CR:IX6.94      @%  The size of the variable is determined by %@AI@%directive%@AE@%. The directives that%@EH@%
  6884.   can be used to define single-item data objects are listed below:%@NL@%
  6885. %@NL@%
  6886.   %@AB@%Directive%@AE@%           %@AB@%Meaning%@AE@%%@NL@%
  6887.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6888.   %@AB@%DB%@AE@%                  Defines byte%@NL@%
  6889. %@NL@%
  6890.   %@AB@%DW%@AE@%                  Defines word (2 bytes)%@NL@%
  6891. %@NL@%
  6892.   %@AB@%DD%@AE@%                  Defines doubleword (4 bytes)%@NL@%
  6893. %@NL@%
  6894.   %@AB@%DQ%@AE@%                  Defines quadword (8 bytes)%@NL@%
  6895. %@NL@%
  6896.   %@AB@%DT%@AE@%                  Defines 10-byte variable%@NL@%
  6897. %@NL@%
  6898. %@NL@%
  6899. %@4@%%@CR:IX6.95      @%%@CR:IX6.96      @%  The optional %@AI@%initializer%@AE@% can be a constant, an expression that evaluates%@EH@%
  6900.   to a constant, or a question mark (%@AB@%?%@AE@%). The question mark is the symbol
  6901.   indicating that the value of the variable is undefined. You can define
  6902.   multiple values by using multiple initializers separated by commas, or by
  6903.   using the %@AB@%DUP%@AE@% operator, as explained in Section 6.5.2%@BO:       65365@%, "Arrays and
  6904.   Buffers."%@NL@%
  6905. %@NL@%
  6906. %@4@%  Simple data types can allocate memory for integers, strings, addresses, or%@EH@%
  6907.   real numbers.%@NL@%
  6908. %@NL@%
  6909. %@NL@%
  6910. %@3@%%@CR:SC6.5.1.1   @%%@AB@%6.5.1.1  Integer Variables%@AE@%%@EH@%%@NL@%
  6911. %@NL@%
  6912. %@4@%%@CR:IX6.97      @%  When defining an integer variable, you can specify an initial value as an%@EH@%
  6913.   integer constant or as a constant expression. QuickAssembler generates an
  6914.   error if you specify an initial value too large for the specified
  6915.   variable.%@NL@%
  6916. %@NL@%
  6917. %@4@%%@CR:IX6.98      @%%@CR:IX6.99      @%  Integer values for all sizes except 10-byte variables are stored in binary%@EH@%
  6918.   form. They can be interpreted as either signed or unsigned numbers. For
  6919.   instance, the hexadecimal value 0FFCD can be interpreted either as the
  6920.   signed number -51 or the unsigned number 65,485.%@NL@%
  6921. %@NL@%
  6922. %@4@%  The processor cannot tell the difference between signed and unsigned%@EH@%
  6923.   numbers. Some instructions are designed specifically for signed numbers.
  6924.   It is the programmer's responsibility to decide whether a value is to be
  6925.   interpreted as signed or unsigned, and then to use the appropriate
  6926.   instructions to handle the value correctly.%@NL@%
  6927. %@NL@%
  6928. %@4@%  Figure 6.1 shows various integer storage formats.%@EH@%%@NL@%
  6929. %@NL@%
  6930.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  6931.   │ This figure can be found in Section 6.5.1.1 of the manual              │%@NL@%
  6932.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  6933. %@NL@%
  6934. %@4@%%@CR:IX6.100     @%  The directives for defining integer variables are listed below with the%@EH@%
  6935.   sizes of integer they can define:%@NL@%
  6936. %@NL@%
  6937. %@CR:IX6.101     @%%@CR:IX6.102     @%%@CR:IX6.103     @%%@CR:IX6.104     @%%@CR:IX6.105     @%%@CR:IX6.106     @%%@CR:IX6.107     @%  %@AB@%Directive%@AE@%           %@AB@%Size of Directive%@AE@%%@NL@%
  6938.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  6939.   %@AB@%DB%@AE@% (bytes)          Allocates unsigned numbers from 0 to 255 or signed
  6940.                       numbers from -128 to 127.%@NL@%
  6941. %@NL@%
  6942.   %@AB@%DW%@AE@% (words)          Allocates unsigned numbers from 0 to 65,535 or signed
  6943.                       numbers from -32,768 to 32,767. The bytes of a word
  6944.                       integer are stored in the format shown in Figure 6.1.
  6945.                       Note that in assembler listings and in most debuggers
  6946.                       the bytes of a word are shown in the opposite
  6947.                       order──high byte first──since this is the way most
  6948.                       people think of numbers.%@NL@%
  6949. %@NL@%
  6950.                       Word values can be used directly in 8086-family
  6951.                       instructions. They can also be loaded, used in
  6952.                       calculations, and stored with 8087-family
  6953.                       instructions.%@NL@%
  6954. %@NL@%
  6955.   %@AB@%DD%@AE@% (doublewords)    Allocates unsigned numbers from 0 to 4,294,967,295 or
  6956.                       signed numbers from -2,147,483,648 to 2,147,483,647.
  6957.                       The words of a doubleword integer are stored in the
  6958.                       format shown in Figure 6.1.%@NL@%
  6959. %@NL@%
  6960.                       These 32-bit values (called long integers) can be
  6961.                       loaded, used in calculations, and stored with
  6962.                       8087-family instructions. Some calculations can be
  6963.                       done on these numbers directly with 16-bit 8086-family
  6964.                       processors; others involve an indirect method of doing
  6965.                       calculations on each word separately (see Chapter 14%@BO:       ae658@%,
  6966.                       "Doing Arithmetic and Bit Calculations").%@NL@%
  6967. %@NL@%
  6968.   %@AB@%DQ%@AE@% (quadwords)      Allocates 64-bit integers. The doublewords of a
  6969.                       quadword integer are stored in the format shown in
  6970.                       Figure 6.1.%@NL@%
  6971. %@NL@%
  6972.                       These values can be loaded, used in calculations, and
  6973.                       stored with 8087-family instructions. You must write
  6974.                       your own routines to use them with 16-bit 8086-family
  6975.                       processors.%@NL@%
  6976. %@NL@%
  6977.   %@AB@%DT%@AE@%                  Allocates 10-byte (80-bit) integers if the D radix
  6978.                       specifier is used.%@NL@%
  6979. %@NL@%
  6980.                       By default, %@AB@%DT%@AE@% allocates packed binary coded decimal
  6981.                       (BCD) numbers, as described in Section 6.5.1.2%@BO:       61d5d@%,
  6982.                       "Binary Coded Decimal Variables." If you define binary
  6983.                       10-byte integers, you must write your own routines to
  6984.                       use routines in calculations.%@NL@%
  6985. %@NL@%
  6986. %@NL@%
  6987. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  6988. %@NL@%
  6989.   %@AS@%integer     DB     16          ; Initialize byte to 16%@AE@%%@NL@%
  6990.   %@AS@%expression  DW     4*3         ; Initialize word to 12%@AE@%%@NL@%
  6991.   %@AS@%empty       DQ     ?           ; Allocate uninitialized long integer%@AE@%%@NL@%
  6992.   %@AS@%            DB     1,2,3,4,5,6 ; Initialize six unnamed bytes%@AE@%%@NL@%
  6993.   %@AS@%long        DD     4294967295  ; Initialize double word to 4,294,967,295%@AE@%%@NL@%
  6994.   %@AS@%tb          DT     2345d       ; Initialize 10-byte binary integer%@AE@%%@NL@%
  6995. %@NL@%
  6996. %@NL@%
  6997. %@3@%%@CR:SC6.5.1.2   @%%@AB@%6.5.1.2  Binary Coded Decimal Variables%@AE@%%@EH@%%@NL@%
  6998. %@NL@%
  6999. %@4@%%@CR:IX6.108     @%  Binary coded decimal (BCD) numbers provide a method of doing calculations%@EH@%
  7000.   on large numbers without rounding errors. They are sometimes used in
  7001.   financial applications. There are two kinds: packed and unpacked.%@NL@%
  7002. %@NL@%
  7003. %@4@%%@CR:IX6.109     @%  Unpacked BCD numbers are stored one digit to a byte, with the value in the%@EH@%
  7004.   lower four bits. They can be defined with the %@AB@%DB%@AE@% directive. For example,
  7005.   an unpacked BCD number could be defined and initialized as shown below:%@NL@%
  7006. %@NL@%
  7007.   %@AS@%unpackedr   DB     1,5,8,2,5,2,9       ; Initialized to 9,252,851%@AE@%%@NL@%
  7008.   %@AS@%unpackedf   DB     9,2,5,2,8,5,1       ; Initialized to 9,252,851%@AE@%%@NL@%
  7009. %@NL@%
  7010. %@4@%  Whether least-significant digits can come either first or last depends on%@EH@%
  7011.   how you write the calculation routines that handle the numbers.
  7012.   Calculations with unpacked BCD numbers are discussed in Section 14.5.1%@BO:       b53c9@%.%@NL@%
  7013. %@NL@%
  7014. %@4@%%@CR:IX6.110     @%  Packed BCD numbers are stored two digits to a byte, with one digit in the%@EH@%
  7015.   lower four bits and one in the upper four bits. The leftmost bit holds the
  7016.   sign (0 for positive or 1 for negative).%@NL@%
  7017. %@NL@%
  7018. %@4@%  Packed BCD variables can be defined with the %@AB@%DT%@AE@% directive as shown below:%@EH@%%@NL@%
  7019. %@NL@%
  7020.   %@AS@%packed      DT     9252851             ; Allocate 9,252,851%@AE@%%@NL@%
  7021. %@NL@%
  7022. %@4@%  The 8087-family processors can do fast calculations with packed BCD%@EH@%
  7023.   numbers, as described in Chapter 17%@BO:       d965a@%, "Calculating with a Math
  7024.   Coprocessor." The 8086-family processors can also do some calculations
  7025.   with packed BCD numbers, but the process is slower and more complicated.
  7026.   See Section 14.5.2%@BO:       b69dc@% for details.%@NL@%
  7027. %@NL@%
  7028. %@NL@%
  7029. %@3@%%@CR:SC6.5.1.3   @%%@AB@%6.5.1.3  String Variables%@AE@%%@EH@%%@NL@%
  7030. %@NL@%
  7031. %@4@%%@CR:IX6.111     @%%@CR:IX6.112     @%%@CR:IX6.113     @%  Strings are normally initialized with the %@AB@%DB%@AE@% directive. The initializing%@EH@%
  7032.   value is specified as a string constant. Strings can also be initialized
  7033.   by specifying each value in the string. For example, the following
  7034.   definitions are equivalent:%@NL@%
  7035. %@NL@%
  7036.   %@AS@%version1    DB     97,98,99            ; As ASCII values%@AE@%%@NL@%
  7037.   %@AS@%version2    DB     'a','b','c'         ; As characters%@AE@%%@NL@%
  7038.   %@AS@%version3    DB     "abc"               ; As a string%@AE@%%@NL@%
  7039. %@NL@%
  7040. %@4@%  One- and two-character strings can also be initialized with any of the%@EH@%
  7041.   other data-definition directives. The last (or only) character in the
  7042.   string is placed in the byte with the lowest address. Either 0 or the
  7043.   first character is placed in the next byte. The unused portion of such
  7044.   variables is filled with zeros.%@NL@%
  7045. %@NL@%
  7046. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  7047. %@NL@%
  7048.   %@AS@%function9   DB     'Hello',13,10,'$'   ; Use with DOS INT 21h%@AE@%%@NL@%
  7049.   %@AS@%                                       ;   function 9%@AE@%%@NL@%
  7050.   %@AS@%asciiz      DB     "\ASM\TEST.ASM",0   ; Use as ASCIIZ string%@AE@%%@NL@%
  7051. %@NL@%
  7052.   %@AS@%message     DB     "Enter file name: " ; Use with DOS INT 21h%@AE@%%@NL@%
  7053.   %@AS@%l_message   EQU    $-message           ;   function 40h%@AE@%%@NL@%
  7054.   %@AS@%a_message   EQU    OFFSET message%@AE@%%@NL@%
  7055. %@NL@%
  7056.   %@AS@%str1        DB     "ab"                ; Stored as 61 62%@AE@%%@NL@%
  7057.   %@AS@%str2        DD     "ab"                ; Stored as 62 61 00 00%@AE@%%@NL@%
  7058.   %@AS@%str3        DD     "a"                 ; Stored as 61 00 00 00%@AE@%%@NL@%
  7059. %@NL@%
  7060. %@NL@%
  7061. %@3@%%@CR:SC6.5.1.4   @%%@AB@%6.5.1.4  Real-Number Variables%@AE@%%@EH@%%@NL@%
  7062. %@NL@%
  7063. %@4@%  Real numbers must be stored in binary format. However, when initializing%@EH@%
  7064.   variables, you can specify decimal or hexadecimal constants and let the
  7065.   assembler automatically encode them into their binary equivalents.
  7066.   QuickAssembler can use two different binary formats for real numbers: IEEE
  7067.   or Microsoft Binary. You can specify the format by using directives (IEEE
  7068.   is the default).%@NL@%
  7069. %@NL@%
  7070. %@4@%  This section tells you how to initialize real-number variables, describes%@EH@%
  7071.   the two binary formats, and explains real-number encoding.%@NL@%
  7072. %@NL@%
  7073. %@3@%  %@AB@%Initializing and Allocating Real-Number Variables%@AE@%%@EH@%%@NL@%
  7074. %@NL@%
  7075. %@4@%%@CR:IX6.114     @%%@CR:IX6.115     @%%@CR:IX6.116     @%  Real numbers can be defined by initializing them either with real-number%@EH@%
  7076.   constants or with encoded hexadecimal constants. The real-number
  7077.   designator (R) must follow numbers specified in encoded format.%@NL@%
  7078. %@NL@%
  7079. %@4@%%@CR:IX6.117     @%%@CR:IX6.118     @%%@CR:IX6.119     @%%@CR:IX6.120     @%%@CR:IX6.121     @%  The directives for defining real numbers are listed below with the sizes%@EH@%
  7080.   of the numbers they can allocate:%@NL@%
  7081. %@NL@%
  7082.   %@AB@%Directive%@AE@%           %@AB@%Size%@AE@%%@NL@%
  7083.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7084.   %@AB@%DD%@AE@%                  Allocates short (32-bit) real numbers in either the
  7085.                       IEEE or Microsoft Binary format.%@NL@%
  7086. %@NL@%
  7087.   %@AB@%DQ%@AE@%                  Allocates long (64-bit) real numbers in either the
  7088.                       IEEE or Microsoft Binary format.%@NL@%
  7089. %@NL@%
  7090.   %@AB@%DT%@AE@%                  Allocates temporary or 10-byte (80-bit) real numbers.
  7091.                       The format of these numbers is similar to the IEEE
  7092.                       format. They are always encoded the same regardless of
  7093.                       the real-number format. Their size is nonstandard and
  7094.                       incompatible with most Microsoft high-level languages.
  7095.                       Temporary-real format is provided for those who want
  7096.                       to initialize real numbers in the format used
  7097.                       internally by 8087-family processors.%@NL@%
  7098. %@NL@%
  7099. %@NL@%
  7100. %@4@%  The 8086-family microprocessors do not have any instructions for handling%@EH@%
  7101.   real numbers. You must write your own routines, use a library that
  7102.   includes real-number calculation routines, or use a coprocessor. The
  7103.   8087-family coprocessors can load real numbers in the IEEE format; they
  7104.   can also use the values in calculations and store the results back to
  7105.   memory, as explained in Chapter 17%@BO:       d965a@%, "Calculating with a Math
  7106.   Coprocessor."%@NL@%
  7107. %@NL@%
  7108. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  7109. %@NL@%
  7110.   %@AS@%shrt        DD      98.6                ; QuickAsm automatically encodes%@AE@%%@NL@%
  7111.   %@AS@%long        DQ      5.391E-4            ;   in current format%@AE@%%@NL@%
  7112.   %@AS@%ten_byte    DT      -7.31E7%@AE@%%@NL@%
  7113.   %@AS@%eshrt       DD      87453333r           ; 98.6 encoded in Microsoft%@AE@%%@NL@%
  7114.   %@AS@%                                        ;   Binary format%@AE@%%@NL@%
  7115.   %@AS@%elong       DQ      3F41AA4C6F445B7Ar   ; 5.391E-4 encoded in IEEE format%@AE@%%@NL@%
  7116. %@NL@%
  7117. %@4@%  The real-number designator (R) used to specify encoded numbers is%@EH@%
  7118.   explained in Section 6.1.3%@BO:       5971d@%, "Real-Number Constants."%@NL@%
  7119. %@NL@%
  7120. %@3@%  %@AB@%Selecting a Real-Number Format%@AE@%%@EH@%%@NL@%
  7121. %@NL@%
  7122. %@4@%%@CR:IX6.122     @%%@CR:IX6.123     @%  QuickAssembler can encode four-byte and eight-byte real numbers in two%@EH@%
  7123.   different formats: IEEE and Microsoft Binary. Your choice depends on the
  7124.   type of program you are writing. The four primary alternatives are listed
  7125.   below:%@NL@%
  7126. %@NL@%
  7127.   1. If your program requires a coprocessor for calculations, you must use
  7128.      the IEEE format.%@NL@%
  7129. %@NL@%
  7130. %@CR:IX6.124     @%%@CR:IX6.125     @%%@CR:IX6.126     @%  2. Most high-level languages use the IEEE format. If you are writing
  7131.      modules that will be called from such a language, your program should
  7132.      use the IEEE format. All versions of the C, FORTRAN, and Pascal
  7133.      compilers sold by Microsoft and IBM use the IEEE format.%@NL@%
  7134. %@NL@%
  7135.   3. If you are writing a module that will be called from early versions of
  7136.      Microsoft or IBM BASIC, your program should use the Microsoft Binary
  7137.      format. Versions that support only the Microsoft Binary format include:%@NL@%
  7138. %@NL@%
  7139. %@CR:IX6.127     @%     ■  Microsoft QuickBASIC through Version 2.01%@NL@%
  7140. %@NL@%
  7141.      ■  Microsoft BASIC Compiler through Version 5.3%@NL@%
  7142. %@NL@%
  7143.      ■  IBM BASIC Compiler through Version 2.0%@NL@%
  7144. %@NL@%
  7145.      ■  Microsoft GW-BASIC(R) interpreter (all versions)%@NL@%
  7146. %@NL@%
  7147.      ■  IBM BASICA interpreter (all versions)%@NL@%
  7148. %@NL@%
  7149.      Microsoft QuickBASIC Version 3.0 supported both the Microsoft Binary
  7150.      and IEEE formats as options. Current and future versions of Microsoft
  7151.      QuickBASIC and the Microsoft and IBM BASIC compilers support only the
  7152.      IEEE format.%@NL@%
  7153. %@NL@%
  7154.   4. If you are creating a stand-alone program that does not use a
  7155.      coprocessor, you can choose either format. The IEEE format is better
  7156.      for overall compatibility with high-level languages. The Microsoft
  7157.      Binary format may be necessary for compatibility with existing source
  7158.      code.%@NL@%
  7159. %@NL@%
  7160.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7161.   %@AB@%NOTE%@AE@%  When you interface assembly-language modules with high-level
  7162.   languages, the real-number format only matters if you initialize
  7163.   real-number variables in the assembly module. If your assembly module does
  7164.   not use real numbers, or if all real numbers are initialized in the
  7165.   high-level-language module, the real-number format does not make any
  7166.   difference.%@NL@%
  7167.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7168. %@NL@%
  7169. %@4@%  By default, QuickAssembler assembles real-number data in the IEEE format.%@EH@%
  7170.   If you wish to use the Microsoft Binary format, you must put the %@AB@%.MSFLOAT%@AE@%
  7171.   directive at the start of your source file before initializing any
  7172.   real-number variables.%@NL@%
  7173. %@NL@%
  7174. %@3@%%@CR:IX6.128     @%%@CR:IX6.129     @%%@CR:IX6.130     @%%@CR:IX6.131     @%  %@AB@%Real-Number Encoding%@AE@%%@EH@%%@NL@%
  7175. %@NL@%
  7176. %@4@%%@CR:IX6.132     @%%@CR:IX6.133     @%%@CR:IX6.134     @%  The IEEE format for encoding four- and eight-byte real numbers is%@EH@%
  7177.   illustrated in Figure 6.2. Although this figure places the
  7178.   most-significant bit first for illustration, low bytes actually appear
  7179.   first in memory.%@NL@%
  7180. %@NL@%
  7181.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  7182.   │ This figure can be found in Section 6.5.1.4 of the manual              │%@NL@%
  7183.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  7184. %@NL@%
  7185. %@4@%  The parts of the real numbers are described below:%@EH@%%@NL@%
  7186. %@NL@%
  7187.   1. Sign bit (0 for positive or 1 for negative) in the upper bit of the
  7188.      first byte.%@NL@%
  7189. %@NL@%
  7190.   2. Exponent in the next bits in sequence (8 bits for short real number or
  7191.      11 bits for long real number).%@NL@%
  7192. %@NL@%
  7193.   3. All except the first set bit of mantissa in the remaining bits of the
  7194.      variable. Since the first significant bit is known to be set, it need
  7195.      not be actually stored. The length is 23 bits for short real numbers
  7196.      and 52 bits for long real numbers.%@NL@%
  7197. %@NL@%
  7198. %@4@%  The Microsoft Binary format for encoding real numbers is illustrated in%@EH@%
  7199.   Figure 6.3.%@NL@%
  7200. %@NL@%
  7201.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  7202.   │ This figure can be found in Section 6.5.1.4 of the manual              │%@NL@%
  7203.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  7204. %@NL@%
  7205. %@4@%  The three parts of real numbers are described below:%@EH@%%@NL@%
  7206. %@NL@%
  7207.   1. Biased exponent (8 bits) in the high-address byte. The bias is 81H for
  7208.      short real numbers and 401H for long real numbers.%@NL@%
  7209. %@NL@%
  7210.   2. Sign bit (0 for positive or 1 for negative) in the upper bit of the
  7211.      second-highest byte.%@NL@%
  7212. %@NL@%
  7213.   3. All except the first set bit of mantissa in the remaining 7 bits of the
  7214.      second-highest byte and in the remaining bytes of the variable. Since
  7215.      the first significant bit is known to be set, it need not be actually
  7216.      stored. The length is 23 bits for short real numbers and 55 bits for
  7217.      long real numbers.%@NL@%
  7218. %@NL@%
  7219. %@4@%%@CR:IX6.135     @%%@CR:IX6.136     @%  QuickAssembler also supports the 10-byte temporary-real format used%@EH@%
  7220.   internally by 8087-family coprocessors. This format is similar to IEEE
  7221.   format. The size is nonstandard and is not used by Microsoft compilers or
  7222.   interpreters. Since the coprocessors can load and automatically convert
  7223.   numbers in the more standard 4-byte and 8-byte formats, the 10-byte format
  7224.   is seldom used in assembly-language programming.%@NL@%
  7225. %@NL@%
  7226. %@4@%  The temporary-real format for encoding real numbers is illustrated in%@EH@%
  7227.   Figure 6.4.%@NL@%
  7228. %@NL@%
  7229.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  7230.   │ This figure can be found in Section 6.5.1.4 of the manual              │%@NL@%
  7231.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  7232. %@NL@%
  7233. %@4@%  The four parts of the real numbers are described below:%@EH@%%@NL@%
  7234. %@NL@%
  7235.   1. Sign bit (0 for positive or 1 for negative) in the upper bit of the
  7236.      first byte.%@NL@%
  7237. %@NL@%
  7238.   2. Exponent in the next bits in sequence (15 bits for 10-byte real).%@NL@%
  7239. %@NL@%
  7240.   3. The integer part of mantissa in the next bit in sequence (bit 63).%@NL@%
  7241. %@NL@%
  7242.   4. Remaining bits of mantissa in the remaining bits of the variable. The
  7243.      length is 63 bits.%@NL@%
  7244. %@NL@%
  7245. %@4@%  Notice that the 10-byte temporary-real format stores the integer part of%@EH@%
  7246.   the mantissa. This differs from the 4-byte and 8-byte formats, in which
  7247.   the integer part is implicit.%@NL@%
  7248. %@NL@%
  7249. %@NL@%
  7250. %@3@%%@CR:SC6.5.2     @%%@AB@%6.5.2  Arrays and Buffers%@AE@%%@EH@%%@NL@%
  7251. %@NL@%
  7252. %@4@%%@CR:IX6.137     @%%@CR:IX6.138     @%%@CR:IX6.139     @%%@CR:IX6.140     @%  Arrays, buffers, and other data structures consisting of multiple data%@EH@%
  7253.   objects of the same size can be defined with the %@AB@%DUP%@AE@% operator. This
  7254.   operator can be used with any of the data-definition directives described
  7255.   in this chapter.%@NL@%
  7256. %@NL@%
  7257. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7258. %@NL@%
  7259. %@4@%  %@AI@%count%@AE@% %@AB@%DUP%@AE@% %@AB@%(%@AE@%%@AI@%initialvalue%@AE@%[[%@AB@%,%@AE@%%@AI@%initialvalue%@AE@%]]...%@AB@%)%@AE@%%@EH@%%@NL@%
  7260. %@NL@%
  7261. %@4@%%@CR:IX6.141     @%  The %@AI@%count%@AE@% sets the number of times to define %@AI@%initialvalue%@AE@%. The initial%@EH@%
  7262.   value can be any expression that evaluates to an integer value, a
  7263.   character constant, or another %@AB@%DUP%@AE@% operator. It can also be the undefined
  7264.   symbol (%@AB@%?%@AE@%) if there is no initial value.%@NL@%
  7265. %@NL@%
  7266. %@4@%  Multiple initial values must be separated by commas. If multiple values%@EH@%
  7267.   are specified within the parentheses, the sequence of values is allocated
  7268.   %@AI@%count%@AE@% times. For example, the statement%@NL@%
  7269. %@NL@%
  7270.   %@AS@%            DB     5 DUP ("Text ")%@AE@%%@NL@%
  7271. %@NL@%
  7272. %@4@%  allocates the string %@AS@%"Text " %@AE@%five times for a total of 25 bytes.%@EH@%%@NL@%
  7273. %@NL@%
  7274. %@4@%%@CR:IX6.142     @%  %@AB@%DUP%@AE@% operators can be nested up to 17 levels. The initial value (or values)%@EH@%
  7275.   must always be placed within parentheses.%@NL@%
  7276. %@NL@%
  7277. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  7278. %@NL@%
  7279.   %@AS@%array       DD     10 DUP (1)                 ; 10 doublewords%@AE@%%@NL@%
  7280.   %@AS@%                                              ;   initialized to 1%@AE@%%@NL@%
  7281. %@NL@%
  7282.   %@AS@%buffer      DB     256 DUP (?)                ; 256 byte buffer%@AE@%%@NL@%
  7283. %@NL@%
  7284.   %@AS@%masks       DB     20 DUP (040h,020h,04h,02h) ; 80 byte buffer%@AE@%%@NL@%
  7285.   %@AS@%                                              ;   with bit masks%@AE@%%@NL@%
  7286.   %@AS@%            DB     32 DUP ("I am here ")      ; 320 byte buffer with%@AE@%%@NL@%
  7287.   %@AS@%                                              ;   signature for debugging%@AE@%%@NL@%
  7288.   %@AS@%three_d     DD     5 DUP (5 DUP (5 DUP (0)))  ; 125 doublewords%@AE@%%@NL@%
  7289.   %@AS@%                                              ;   initialized to 0%@AE@%%@NL@%
  7290. %@NL@%
  7291. %@4@%  Note that QuickAssembler %@AI@%s%@AE@%ometimes generates different object code when%@EH@%
  7292.   the %@AB@%DUP %@AE@%operator is used rather than when multiple values are given. For
  7293.   example, the statement%@NL@%
  7294. %@NL@%
  7295.   %@AS@%test1       DB      ?,?,?,?,?  ; Indeterminate%@AE@%%@NL@%
  7296. %@NL@%
  7297. %@4@%  is "indeterminate." It causes QuickAssembler to write five zero-value%@EH@%
  7298.   bytes to the object file. The statement%@NL@%
  7299. %@NL@%
  7300.   %@AS@%test2       DB      5 DUP (?)  ; Undefined%@AE@%%@NL@%
  7301. %@NL@%
  7302. %@4@%  is "undefined." It causes QuickAssembler to increase the offset of the%@EH@%
  7303.   next record in the object file by five bytes. Therefore, an object file
  7304.   created with the first statement will be larger than one created with the
  7305.   second statement.%@NL@%
  7306. %@NL@%
  7307. %@4@%%@CR:IX6.143     @%%@CR:IX6.144     @%%@CR:IX6.145     @%%@CR:IX6.146     @%  In most cases, the distinction between indeterminate and undefined%@EH@%
  7308.   definitions is trivial. The linker adjusts the offsets so that the same
  7309.   executable file is generated in either case. However, the difference is
  7310.   significant in segments with the %@AB@%COMMON%@AE@% combine type. If %@AB@%COMMON%@AE@% segments
  7311.   in two modules contain definitions for the same variable, one with an
  7312.   indeterminate value and one with an explicit value, the actual value in
  7313.   the executable file varies depending on link order. If the module with the
  7314.   indeterminate value is linked last, the 0 initialized for it overrides the
  7315.   explicit value. You can prevent this by always using undefined rather than
  7316.   indeterminate values in %@AB@%COMMON%@AE@% segments. For example, use the first of the
  7317.   following statements:%@NL@%
  7318. %@NL@%
  7319.   %@AS@%test3       DB      1 DUP (?)  ; Undefined - doesn't initialize%@AE@%%@NL@%
  7320.   %@AS@%test4       DB      ?          ; Indeterminate - initializes 0%@AE@%%@NL@%
  7321. %@NL@%
  7322. %@4@%  If you use the undefined definition, the explicit value is always used in%@EH@%
  7323.   the executable file regardless of link order.%@NL@%
  7324. %@NL@%
  7325. %@NL@%
  7326. %@3@%%@CR:SC6.5.3     @%%@AB@%6.5.3  Labeling Variables%@AE@%%@EH@%%@NL@%
  7327. %@NL@%
  7328. %@4@%%@CR:IX6.147     @%%@CR:IX6.148     @%  The %@AB@%LABEL%@AE@% directive can be used to define a variable of a given size at a%@EH@%
  7329.   specified location. It is useful if you want to refer to the same data as
  7330.   variables of different sizes.%@NL@%
  7331. %@NL@%
  7332. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7333. %@NL@%
  7334. %@4@%  %@AI@%name%@AE@% %@AB@%LABEL%@AE@% %@AI@%type%@AE@%%@EH@%%@NL@%
  7335. %@NL@%
  7336. %@4@%  The %@AI@%name%@AE@% is the symbol assigned to the variable, and %@AI@%type%@AE@% is the variable%@EH@%
  7337.   size. The type can be any one of the following type specifiers: %@AB@%BYTE%@AE@%,
  7338.   %@AB@%WORD%@AE@%, %@AB@%DWORD%@AE@%, %@AB@%QWORD%@AE@%, or %@AB@%TBYTE%@AE@%. It can also be the name of a previously
  7339.   defined structure.%@NL@%
  7340. %@NL@%
  7341. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  7342. %@NL@%
  7343.   %@AS@%warray      LABEL   WORD       ; Access array as 50 words%@AE@%%@NL@%
  7344.   %@AS@%darray      LABEL   DWORD      ; Access same array as 25 doublewords%@AE@%%@NL@%
  7345.   %@AS@%barray      DB      100 DUP(?) ; Access same array as 100 bytes%@AE@%%@NL@%
  7346. %@NL@%
  7347. %@NL@%
  7348. %@3@%%@CR:SC6.5.4     @%%@AB@%6.5.4  Pointer Variables%@AE@%%@EH@%%@NL@%
  7349. %@NL@%
  7350. %@4@%%@CR:IX6.149     @%%@CR:IX6.150     @%  The assembler lets you explicitly allocate pointers. A pointer (address)%@EH@%
  7351.   variable is either two or four bytes in size; consequently, any word or
  7352.   doubleword data definition can create a pointer variable. However,
  7353.   declaring pointer variables explicitly gives more accurate debugging
  7354.   information to the environment.%@NL@%
  7355. %@NL@%
  7356. %@4@%  Pointer-variable definitions have the following form:%@EH@%%@NL@%
  7357. %@NL@%
  7358. %@4@%  %@AI@%symbol%@AE@% [[%@AB@%DW%@AE@% |%@AB@% DD%@AE@%]] %@AI@%type%@AE@% %@AB@%PTR%@AE@% %@AI@%initialvalue%@AE@%%@EH@%%@NL@%
  7359. %@NL@%
  7360. %@4@%  The %@AI@%type%@AE@% can consist of the name of a record, structure, or one of the%@EH@%
  7361.   standard types described in Section 6.3%@BO:       5cd7a@%, "Using Type Specifiers."%@NL@%
  7362. %@NL@%
  7363. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  7364. %@NL@%
  7365.   %@AS@%string      DB  "from swerve of shore to bend of bay", 0%@AE@%%@NL@%
  7366.   %@AS@%pstring     DW  BYTE PTR string  ; Declares a near pointer to string.%@AE@%%@NL@%
  7367.   %@AS@%fpstring    DD  BYTE PTR string  ; Declares a far pointer to string.%@AE@%%@NL@%
  7368. %@NL@%
  7369. %@4@%  In this example, near (two-byte) and far (four-byte) pointers are declared%@EH@%
  7370.   and initialized to the value of a null terminated string. This is the
  7371.   format used in C language, and the pointer variables in the example could
  7372.   be used in C functions that process strings.%@NL@%
  7373. %@NL@%
  7374. %@4@%  Using an explicit pointer declaration generates debugging information,%@EH@%
  7375.   causing the variable to be viewed as a pointer during debugging.
  7376.   Consequently, the environment properly interprets the variable when you
  7377.   enter it as a Watch expression. No special syntax is required.%@NL@%
  7378. %@NL@%
  7379. %@4@%  This use of %@AB@%PTR%@AE@% is distinct from the use of%@AB@% PTR %@AE@%to alter the type of a%@EH@%
  7380.   variable during an instruction. The assembler uses the context of the
  7381.   program to determine which way you are using the %@AB@%PTR%@AE@% keyword.%@NL@%
  7382. %@NL@%
  7383. %@NL@%
  7384. %@2@%%@CR:SC6.6       @%%@AB@%6.6  Setting the Location Counter%@AE@%%@EH@%%@NL@%
  7385. %@NL@%
  7386. %@4@%%@CR:IX6.151     @%%@CR:IX6.152     @%%@CR:IX6.153     @%  As the assembler encounters labels and data declarations, it needs to know%@EH@%
  7387.   what address to assign. This function is fulfilled by the location
  7388.   counter, which indicates the offset address corresponding to the current
  7389.   line of source code. This value is generally equal to the value that IP
  7390.   will have at run time.%@NL@%
  7391. %@NL@%
  7392. %@4@%  The assembler increments the location counter as it processes each%@EH@%
  7393.   statement. However, you can set the location counter directly by using the
  7394.   %@AB@%ORG%@AE@% directive.%@NL@%
  7395. %@NL@%
  7396. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7397. %@NL@%
  7398. %@4@%  %@AB@%ORG %@AE@%%@AI@%expression%@AE@%%@EH@%%@NL@%
  7399. %@NL@%
  7400. %@4@%  Subsequent code and data offsets begin at the new offset specified set by%@EH@%
  7401.   %@AI@%expression%@AE@%. The expression must resolve to a constant number. In other
  7402.   words, all symbols used in the expression must be known on the first pass
  7403.   of the assembler.%@NL@%
  7404. %@NL@%
  7405.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7406. %@CR:IX6.154     @%%@CR:IX6.155     @%%@CR:IX6.156     @%  %@AB@%NOTE%@AE@%  The value of the location counter, represented by the dollar sign
  7407.   (%@AB@%$%@AE@%), can be used in the expression, as described in Section 9.3%@BO:       83a2d@%, "Using
  7408.   the Location Counter."%@NL@%
  7409.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7410. %@NL@%
  7411. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  7412. %@NL@%
  7413.   %@AS@%; Labeling absolute addresses%@AE@%%@NL@%
  7414. %@NL@%
  7415.   %@AS@%STUFF       SEGMENT AT 0        ; Segment has constant value 0%@AE@%%@NL@%
  7416.   %@AS@%            ORG     410h        ; Offset has constant value 410h%@AE@%%@NL@%
  7417.   %@AS@%equipment   LABEL   WORD        ; Value at 0000:0410 labeled "equipment"%@AE@%%@NL@%
  7418.   %@AS@%            ORG     417h        ; Offset has constant value 417h%@AE@%%@NL@%
  7419.   %@AS@%keyboard    LABEL   WORD        ; Value at 0000:0417 labeled "keyboard"%@AE@%%@NL@%
  7420.   %@AS@%STUFF       ENDS%@AE@%%@NL@%
  7421. %@NL@%
  7422.   %@AS@%            .CODE%@AE@%%@NL@%
  7423.   %@AS@%            .%@AE@%%@NL@%
  7424.   %@AS@%            .%@AE@%%@NL@%
  7425.   %@AS@%            .%@AE@%%@NL@%
  7426.   %@AS@%            ASSUME  ds:STUFF    ; Tell the assembler%@AE@%%@NL@%
  7427.   %@AS@%            mov     ax,STUFF    ; Tell the processor%@AE@%%@NL@%
  7428.   %@AS@%            mov     ds,ax%@AE@%%@NL@%
  7429. %@NL@%
  7430.   %@AS@%            mov     dx,equipment%@AE@%%@NL@%
  7431.   %@AS@%            mov     keyboard,ax%@AE@%%@NL@%
  7432. %@NL@%
  7433. %@4@%  Example 1 illustrates one way of assigning symbolic names to absolute%@EH@%
  7434.   addresses.%@NL@%
  7435. %@NL@%
  7436. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  7437. %@NL@%
  7438.   %@AS@%; Format for .COM files%@AE@%%@NL@%
  7439. %@NL@%
  7440.   %@AS@%_TEXT       SEGMENT%@AE@%%@NL@%
  7441.   %@AS@%            ASSUME   cs:_TEXT,ds:_TEXT,ss:_TEXT,es:_TEXT%@AE@%%@NL@%
  7442.   %@AS@%            ORG      100h        ; Skip 100h bytes of DOS header%@AE@%%@NL@%
  7443. %@NL@%
  7444.   %@AS@%entry:      jmp      begin       ; Jump over data%@AE@%%@NL@%
  7445.   %@AS@%variable    DW       ?           ; Put more data here%@AE@%%@NL@%
  7446.   %@AS@%            .%@AE@%%@NL@%
  7447.   %@AS@%begin:      .                    ; First line of code%@AE@%%@NL@%
  7448.   %@AS@%            .                    ; Put more code here%@AE@%%@NL@%
  7449.   %@AS@%_TEXT       ENDS%@AE@%%@NL@%
  7450.   %@AS@%            END      entry%@AE@%%@NL@%
  7451. %@NL@%
  7452. %@4@%  Example 2 illustrates how the %@AB@%ORG%@AE@% directive is used to initialize the%@EH@%
  7453.   starting execution point in %@AB@%.COM%@AE@% files.%@NL@%
  7454. %@NL@%
  7455. %@NL@%
  7456. %@2@%%@CR:SC6.7       @%%@AB@%6.7  Aligning Data%@AE@%%@EH@%%@NL@%
  7457. %@NL@%
  7458. %@4@%%@CR:IX6.157     @%%@CR:IX6.158     @%%@CR:IX6.159     @%%@CR:IX6.160     @%%@CR:IX6.161     @%%@CR:IX6.162     @%  Some operations are more efficient when the variable used in the operation%@EH@%
  7459.   is lined up on a boundary of a particular size. The %@AB@%EVEN%@AE@% and %@AB@%ALIGN%@AE@%
  7460.   directives can be used to pad the object file so that the next variable is
  7461.   aligned on a specified boundary.%@NL@%
  7462. %@NL@%
  7463. %@4@%  %@AB@%Syntax 1%@AE@%%@EH@%%@NL@%
  7464. %@NL@%
  7465. %@4@%  %@AB@%EVEN%@AE@%%@EH@%%@NL@%
  7466. %@NL@%
  7467. %@4@%  %@AB@%Syntax 2%@AE@%%@EH@%%@NL@%
  7468. %@NL@%
  7469. %@4@%  %@AB@%ALIGN%@AE@% %@AI@%number%@AE@%%@EH@%%@NL@%
  7470. %@NL@%
  7471. %@4@%  The %@AB@%EVEN%@AE@% directive always aligns on the next even byte. The %@AB@%ALIGN%@AE@%%@EH@%
  7472.   directive aligns on the next byte that is a multiple of %@AI@%number%@AE@%. The number
  7473.   must be a power of 2. For example, use %@AS@%ALIGN 2 %@AE@%or %@AS@%EVEN %@AE@%to align on word
  7474.   boundaries, or use %@AS@%ALIGN 4 %@AE@%to align on doubleword boundaries.%@NL@%
  7475. %@NL@%
  7476. %@4@%%@CR:IX6.163     @%  If the value of the location counter is not on the specified boundary when%@EH@%
  7477.   an %@AB@%ALIGN%@AE@% directive is encountered, the location counter is incremented to
  7478.   a value on the boundary. If the location counter is already on the
  7479.   boundary, the directive has no effect.%@NL@%
  7480. %@NL@%
  7481. %@4@%  When the assembler increments the location counter, it also pads the%@EH@%
  7482.   skipped memory locations by inserting certain values. If the segment is a
  7483.   data segment, the assembler always pads these locations with zeros. If the
  7484.   segment is a code segment, the assembler pads skipped memory locations
  7485.   with a two-byte no-op instruction (instruction that performed no
  7486.   operation) where possible:%@NL@%
  7487. %@NL@%
  7488.   %@AS@%            xchg  bx,bx%@AE@%%@NL@%
  7489. %@NL@%
  7490. %@4@%  This instruction, which assembles as 87D8 hexadecimal, does nothing, but%@EH@%
  7491.   it executes faster than two %@AB@%NOP%@AE@% instructions. Where there is no room for
  7492.   the two-byte no-op, the assembler inserts the one-byte%@AB@% NOP%@AE@% instruction.%@NL@%
  7493. %@NL@%
  7494. %@4@%  The %@AB@%ALIGN%@AE@% and %@AB@%EVEN%@AE@% directives give no efficiency improvements on%@EH@%
  7495.   processors that have an 8-bit data bus (such as the 8088). These
  7496.   processors always fetch data one byte at a time, regardless of the
  7497.   alignment. However, using %@AB@%EVEN%@AE@% can speed certain operation on processors
  7498.   that have a 16-bit data bus (such as the 8086), since the processor can
  7499.   fetch a word if the data is word aligned, but must do two memory fetches
  7500.   if the data is not word aligned.%@NL@%
  7501. %@NL@%
  7502.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7503.   %@AB@%NOTE%@AE@%  The %@AB@%ALIGN %@AE@%directive is a new feature of recent versions of Microsoft
  7504.   assemblers, starting with 5.0. In previous versions, data could be word
  7505.   aligned by using the %@AB@%EVEN%@AE@% directive, but other alignments could not be
  7506.   specified.%@NL@%
  7507. %@NL@%
  7508.   The %@AB@%EVEN %@AE@%directive should not be used in segments with %@AB@%BYTE%@AE@% align type.
  7509.   Similarly, the number specified with the %@AB@%ALIGN %@AE@%directive should be no
  7510.   greater than the size of the align type of the current segment (thus
  7511.   ensuring that number is a divisor of the align type of the segment).%@NL@%
  7512.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7513. %@NL@%
  7514. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  7515. %@NL@%
  7516.   %@AS@%            DOSSEG%@AE@%%@NL@%
  7517.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  7518.   %@AS@%            .STACK  100h%@AE@%%@NL@%
  7519.   %@AS@%            .DATA%@AE@%%@NL@%
  7520.   %@AS@%            .%@AE@%%@NL@%
  7521.   %@AS@%            .%@AE@%%@NL@%
  7522.   %@AS@%            .%@AE@%%@NL@%
  7523.   %@AS@%            ALIGN   2                   ; For faster data access%@AE@%%@NL@%
  7524.   %@AS@%stuff       DW      66,124,573,99,75%@AE@%%@NL@%
  7525.   %@AS@%            .%@AE@%%@NL@%
  7526.   %@AS@%            .%@AE@%%@NL@%
  7527.   %@AS@%            .%@AE@%%@NL@%
  7528.   %@AS@%            ALIGN   2                   ; For faster data access%@AE@%%@NL@%
  7529.   %@AS@%evenstuff   DW      ?,?,?,?,?%@AE@%%@NL@%
  7530.   %@AS@%            .CODE%@AE@%%@NL@%
  7531.   %@AS@%start:      mov     ax,@data            ; Load segment location%@AE@%%@NL@%
  7532.   %@AS@%            mov     ds,ax               ;   into DS%@AE@%%@NL@%
  7533.   %@AS@%            mov     es,ax               ;   and ES registers%@AE@%%@NL@%
  7534. %@NL@%
  7535.   %@AS@%            mov     cx,5                ; Load count%@AE@%%@NL@%
  7536.   %@AS@%            mov     si,OFFSET stuff     ; Point to source%@AE@%%@NL@%
  7537.   %@AS@%            mov     di,OFFSET evenstuff ;   and destination%@AE@%%@NL@%
  7538.   %@AS@%            ALIGN   2                   ; Align for faster loop access%@AE@%%@NL@%
  7539.   %@AS@%mloop:      lodsw                       ; Load a word%@AE@%%@NL@%
  7540.   %@AS@%            inc     ax                  ; Make it even by incrementing%@AE@%%@NL@%
  7541.   %@AS@%            and     ax,NOT 1            ;   and turning off first bit%@AE@%%@NL@%
  7542.   %@AS@%            stosw                       ; Store%@AE@%%@NL@%
  7543.   %@AS@%            loop    mloop               ; Again%@AE@%%@NL@%
  7544.   %@AS@%            .%@AE@%%@NL@%
  7545.   %@AS@%            .%@AE@%%@NL@%
  7546.   %@AS@%            .%@AE@%%@NL@%
  7547. %@NL@%
  7548. %@4@%  In this example, the words at %@AS@%stuff %@AE@%and %@AS@%evenstuff %@AE@%are forced to word%@EH@%
  7549.   boundaries. This makes access to the data faster with processors that have
  7550.   a 16-bit data bus. Without this alignment, the initial data might start on
  7551.   an odd boundary and the processor would have to fetch half of each word at
  7552.   a time.%@NL@%
  7553. %@NL@%
  7554. %@4@%  Similarly, the alignment in the code segment speeds up repeated access to%@EH@%
  7555.   the code at the start of the loop. The sample code sacrifices program size
  7556.   in order to achieve moderate improvements on the 8086 and 80286. There is
  7557.   no speed advantage on the 8088.%@NL@%
  7558. %@NL@%
  7559. %@NL@%
  7560. %@NL@%
  7561. ────────────────────────────────────────────────────────────────────────────%@NL@%
  7562. %@1@%%@CR:CH7         @%%@AB@%Chapter 7:  Using Structures and Records%@AE@%%@EH@%%@NL@%
  7563. %@NL@%
  7564. %@NL@%
  7565. %@4@%  QuickAssembler can define and use two kinds of multifield variables:%@EH@%
  7566.   structures and records.%@NL@%
  7567. %@NL@%
  7568. %@4@%%@CR:IX7.1       @%  "Structures" are templates for data objects made up of smaller data%@EH@%
  7569.   objects. A structure can be used to define structure variables, which are
  7570.   made up of smaller variables called fields. Fields within a structure can
  7571.   be different sizes, and each can be accessed individually.%@NL@%
  7572. %@NL@%
  7573. %@4@%%@CR:IX7.2       @%%@CR:IX7.3       @%%@CR:IX7.4       @%  "Records" are templates for data objects whose bits can be described as%@EH@%
  7574.   groups of bits called fields. A record can be used to define record
  7575.   variables. Each bit field in a record variable can be used separately in
  7576.   constant operands or expressions. The processor cannot access bits
  7577.   individually at run time, but bit fields can be used with logical bit
  7578.   instructions to change bits indirectly.%@NL@%
  7579. %@NL@%
  7580. %@4@%  This chapter describes structures and records and tells how to use them.%@EH@%%@NL@%
  7581. %@NL@%
  7582. %@NL@%
  7583. %@2@%%@CR:SC7.1       @%%@AB@%7.1  Structures%@AE@%%@EH@%%@NL@%
  7584. %@NL@%
  7585. %@4@%%@CR:IX7.5       @%  A structure variable is a collection of data objects that can be accessed%@EH@%
  7586.   symbolically as a single data object. Objects within the structure can
  7587.   have different sizes and can be accessed symbolically.%@NL@%
  7588. %@NL@%
  7589. %@4@%  There are two steps in using structure variables:%@EH@%%@NL@%
  7590. %@NL@%
  7591.   1. Declare a structure type. A structure type is a template for data. It
  7592.      declares the sizes and, optionally, the initial values for objects in
  7593.      the structure. By itself the structure type does not define any data.
  7594.      The structure type is used by QuickAssembler during assembly but is not
  7595.      saved as part of the object file.%@NL@%
  7596. %@NL@%
  7597. %@CR:IX7.6       @%  2. Define one or more variables having the structure type. For each
  7598.      variable defined, memory is allocated to the object file in the format
  7599.      declared by the structure type.%@NL@%
  7600. %@NL@%
  7601. %@4@%  The structure variable can then be used as an operand in assembler%@EH@%
  7602.   statements. The structure variable can be accessed as a whole by using the
  7603.   structure name, or individual fields can be accessed by using structure
  7604.   and field names.%@NL@%
  7605. %@NL@%
  7606. %@NL@%
  7607. %@3@%%@CR:SC7.1.1     @%%@AB@%7.1.1  Declaring Structure Types%@AE@%%@EH@%%@NL@%
  7608. %@NL@%
  7609. %@4@%%@CR:IX7.7       @%%@CR:IX7.8       @%%@CR:IX7.9       @%%@CR:IX7.10      @%%@CR:IX7.11      @%%@CR:IX7.12      @%%@CR:IX7.13      @%%@CR:IX7.14      @%  The %@AB@%STRUC%@AE@% and %@AB@%ENDS%@AE@% directives mark the beginning and end of a type%@EH@%
  7610.   declaration for a structure.%@NL@%
  7611. %@NL@%
  7612. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7613. %@NL@%
  7614. %@4@%  %@AI@%name%@AE@% %@AB@%STRUC%@AE@%%@EH@%%@NL@%
  7615.   %@AI@%fielddeclarations%@AE@%%@NL@%
  7616.   %@AI@%name%@AE@% %@AB@%ENDS%@AE@%%@NL@%
  7617. %@NL@%
  7618. %@4@%%@CR:IX7.15      @%%@CR:IX7.16      @%  The %@AI@%name%@AE@% declares the name of the structure type. It must be unique. The%@EH@%
  7619.   %@AI@%fielddeclarations%@AE@% declare the fields of the structure. Any number of field
  7620.   declarations may be given. They must follow the form of data definitions
  7621.   described in Section 6.5%@BO:       5ff03@%, "Defining and Initializing Data." Default
  7622.   initial values may be declared individually or with the %@AB@%DUP%@AE@% operator.%@NL@%
  7623. %@NL@%
  7624. %@4@%%@CR:IX7.17      @%  The names given to fields must be unique within the source file where they%@EH@%
  7625.   are declared. When variables are defined, the field names will represent
  7626.   the offset from the beginning of the structure to the corresponding field.
  7627. %@NL@%
  7628. %@4@%%@CR:IX7.18      @%  When declaring strings in a structure type, make sure the initial values%@EH@%
  7629.   are long enough to accommodate the largest possible string. Strings
  7630.   smaller than the field size can be placed in the structure variable, but
  7631.   larger strings will be truncated.%@NL@%
  7632. %@NL@%
  7633. %@4@%  A structure declaration can contain both field declarations and comments.%@EH@%
  7634.   Conditional-assembly statements are allowed in structure declarations; no
  7635.   other kinds of statements are allowed. Since the %@AB@%STRUC%@AE@% directive is not
  7636.   allowed inside structure declarations, structures cannot be nested.%@NL@%
  7637. %@NL@%
  7638.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7639.   %@AB@%NOTE%@AE@%  The %@AB@%ENDS%@AE@% directive that marks the end of a structure has the same
  7640.   mnemonic as the %@AB@%ENDS %@AE@%directive that marks the end of a segment. The
  7641.   assembler recognizes the meaning of the directive from context. Make sure
  7642.   each %@AB@%SEGMENT %@AE@%directive and each %@AB@%STRUC%@AE@% directive has its own %@AB@%ENDS%@AE@%
  7643.   directive.%@NL@%
  7644.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  7645. %@NL@%
  7646. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  7647. %@NL@%
  7648.   %@AS@%student     STRUC                ; Structure for student records%@AE@%%@NL@%
  7649.   %@AS@%id          DW     ?             ; Field for identification #%@AE@%%@NL@%
  7650.   %@AS@%sname       DB     "Last, First Middle    "%@AE@%%@NL@%
  7651.   %@AS@%scores      DB     10 DUP (100)  ; Field for 10 scores%@AE@%%@NL@%
  7652.   %@AS@%student     ENDS%@AE@%%@NL@%
  7653. %@NL@%
  7654. %@4@%  Within the sample structure %@AS@%student%@AE@%, the fields %@AS@%id%@AE@%, %@AS@%sname%@AE@%, and %@AS@%scores %@AE@%have%@EH@%
  7655.   the offset values 0, 2, and 24, respectively.%@NL@%
  7656. %@NL@%
  7657. %@NL@%
  7658. %@3@%%@CR:SC7.1.2     @%%@AB@%7.1.2  Defining Structure Variables%@AE@%%@EH@%%@NL@%
  7659. %@NL@%
  7660. %@4@%%@CR:IX7.19      @%%@CR:IX7.20      @%%@CR:IX7.21      @%%@CR:IX7.22      @%  A structure variable is a variable with one or more fields of different%@EH@%
  7661.   sizes. The sizes and initial values of the fields are determined by the
  7662.   structure type with which the variable is defined.%@NL@%
  7663. %@NL@%
  7664. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7665. %@NL@%
  7666. %@4@%  [[%@AI@%name%@AE@%]] %@AI@%structurename%@AE@% %@AB@%<%@AE@%[[%@AI@%initialvalue%@AE@% [[%@AB@%,%@AE@%%@AI@%initialvalue%@AE@%]]...]]%@AB@%>%@AE@%%@EH@%%@NL@%
  7667. %@NL@%
  7668. %@4@%  The %@AI@%name%@AE@% is the name assigned to the variable. If no name is given, the%@EH@%
  7669.   assembler allocates space for the variable, but does not give it a
  7670.   symbolic name. The %@AI@%structurename%@AE@% is the name of a structure type
  7671.   previously declared by using the %@AB@%STRUC%@AE@% and %@AB@%ENDS%@AE@% directives.%@NL@%
  7672. %@NL@%
  7673. %@4@%  An %@AI@%initialvalue%@AE@% can be given for each field in the structure. Its type%@EH@%
  7674.   must not be incompatible with the type of the corresponding field. The
  7675.   angle brackets (%@AB@%< >%@AE@%) are required even if no initial value is given. If
  7676.   initial values are given for more than one field, the values must be
  7677.   separated by commas.%@NL@%
  7678. %@NL@%
  7679. %@4@%%@CR:IX7.23      @%%@CR:IX7.24      @%  If the %@AB@%DUP%@AE@% operator (see Section 6.5.2%@BO:       65365@%, "Arrays and Buffers") is used to%@EH@%
  7680.   initialize multiple structure variables, only the angle brackets and
  7681.   initial values, if given, need to be enclosed in parentheses. For example,
  7682.   you can define an array of structure variables as shown below:%@NL@%
  7683. %@NL@%
  7684.   %@AS@%war         date    365 DUP (<,,1940>)%@AE@%%@NL@%
  7685. %@NL@%
  7686. %@4@%  You need not initialize all fields in a structure. If an initial value is%@EH@%
  7687.   left blank, the assembler automatically uses the default initial value of
  7688.   the field, which was originally determined by the structure type. If there
  7689.   is no default value, the field is undefined.%@NL@%
  7690. %@NL@%
  7691. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  7692. %@NL@%
  7693. %@4@%  The following examples use the student type declared in the example in%@EH@%
  7694.   Section 7.1.1%@BO:       69fa7@%, "Declaring Structure Types":%@NL@%
  7695. %@NL@%
  7696.   %@AS@%s1          student <>           ; Uses default values of type%@AE@%%@NL@%
  7697. %@NL@%
  7698. %@NL@%
  7699.   %@AS@%s2          student <1467,"White, Robert D.",>%@AE@%%@NL@%
  7700.   %@AS@%                                 ; Override default values of first two%@AE@%%@NL@%
  7701.   %@AS@%                                 ;   fields--use default value of third%@AE@%%@NL@%
  7702. %@NL@%
  7703.   %@AS@%sarray      student 100 DUP (<>) ; Declare 100 student variables%@AE@%%@NL@%
  7704.   %@AS@%                                 ;   with default initial values%@AE@%%@NL@%
  7705. %@NL@%
  7706. %@4@%%@CR:IX7.25      @%%@CR:IX7.26      @%  Note that you cannot initialize any structure field that has multiple%@EH@%
  7707.   values if this field was given a default initial value when the structure
  7708.   was declared. For example, assume the following structure declaration:%@NL@%
  7709. %@NL@%
  7710.   %@AS@%stuff       STRUC%@AE@%%@NL@%
  7711.   %@AS@%buffer      DB     100 DUP (?)      ; Can't override%@AE@%%@NL@%
  7712.   %@AS@%crlf        DB     13,10            ; Can't override%@AE@%%@NL@%
  7713.   %@AS@%query       DB     'Filename: '     ; String <= can override%@AE@%%@NL@%
  7714.   %@AS@%endmark     DB     36               ; Can override%@AE@%%@NL@%
  7715.   %@AS@%stuff       ENDS%@AE@%%@NL@%
  7716. %@NL@%
  7717. %@4@%  The %@AS@%buffer %@AE@%and %@AS@%crlf %@AE@%fields cannot be overridden by initial values in the%@EH@%
  7718.   structure definition because they have multiple values. The %@AS@%query %@AE@%field
  7719.   can be overridden as long as the overriding string is no longer than %@AS@%query%@AE@%
  7720.   (10 bytes). A longer string would generate an error. The %@AS@%endmark %@AE@%field can
  7721.   be overridden by any byte value.%@NL@%
  7722. %@NL@%
  7723. %@NL@%
  7724. %@3@%%@CR:SC7.1.3     @%%@AB@%7.1.3  Using Structure Operands%@AE@%%@EH@%%@NL@%
  7725. %@NL@%
  7726. %@4@%%@CR:IX7.27      @%%@CR:IX7.28      @%%@CR:IX7.29      @%  Like other variables, structure variables can be accessed by name. Fields%@EH@%
  7727.   within structure variables can also be accessed by using the syntax shown
  7728.   below:%@NL@%
  7729. %@NL@%
  7730. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7731. %@NL@%
  7732. %@4@%  %@AI@%variable%@AE@%%@AB@%.%@AE@%%@AI@%field%@AE@%%@EH@%%@NL@%
  7733. %@NL@%
  7734. %@4@%  The %@AI@%variable%@AE@% must be the name of a structure (or an operand that resolves%@EH@%
  7735.   to the address of a structure). The %@AI@%field%@AE@% must be the name of a field
  7736.   within that structure. The variable is separated from the field by a
  7737.   period. The period is discussed as a structure-field-name operator in
  7738.   Section 9.2.1.2%@BO:       7afe8@%.%@NL@%
  7739. %@NL@%
  7740. %@4@%  The address of a structure operand is the sum of the offsets of %@AI@%variable%@AE@%%@EH@%
  7741.   and %@AI@%field%@AE@%. The address is relative to the segment or group in which the
  7742.   variable is declared.%@NL@%
  7743. %@NL@%
  7744. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  7745. %@NL@%
  7746.   %@AS@%date        STRUC                       ; Declare structure%@AE@%%@NL@%
  7747.   %@AS@%month       DB      ?%@AE@%%@NL@%
  7748.   %@AS@%day         DB      ?%@AE@%%@NL@%
  7749.   %@AS@%year        DW      ?%@AE@%%@NL@%
  7750.   %@AS@%date        ENDS%@AE@%%@NL@%
  7751. %@NL@%
  7752.   %@AS@%            .DATA%@AE@%%@NL@%
  7753.   %@AS@%yesterday   date    <9,30,1987>         ; Declare structure%@AE@%%@NL@%
  7754.   %@AS@%today       date    <10,1,1987>         ;   variables%@AE@%%@NL@%
  7755.   %@AS@%tomorrow    date    <10,2,1987>%@AE@%%@NL@%
  7756. %@NL@%
  7757.   %@AS@%            .CODE%@AE@%%@NL@%
  7758.   %@AS@%            .%@AE@%%@NL@%
  7759.   %@AS@%            .%@AE@%%@NL@%
  7760.   %@AS@%            .%@AE@%%@NL@%
  7761.   %@AS@%            mov     al,yesterday.day    ; Use structure variables%@AE@%%@NL@%
  7762.   %@AS@%            mov     ah,today.month      ;   as operands%@AE@%%@NL@%
  7763.   %@AS@%            mov     tomorrow.year,dx%@AE@%%@NL@%
  7764.   %@AS@%            mov     bx,OFFSET yesterday ; Load structure address%@AE@%%@NL@%
  7765.   %@AS@%            mov     ax,[bx].month       ; Use as indirect operand%@AE@%%@NL@%
  7766.   %@AS@%            .%@AE@%%@NL@%
  7767.   %@AS@%            .%@AE@%%@NL@%
  7768.   %@AS@%            .%@AE@%%@NL@%
  7769. %@NL@%
  7770. %@NL@%
  7771. %@2@%%@CR:SC7.2       @%%@AB@%7.2  Records%@AE@%%@EH@%%@NL@%
  7772. %@NL@%
  7773. %@4@%  A record variable is a byte or word variable in which specific bit fields%@EH@%
  7774.   can be accessed symbolically. Bit fields within the record can have
  7775.   different sizes.%@NL@%
  7776. %@NL@%
  7777. %@4@%  There are two steps in declaring record variables:%@EH@%%@NL@%
  7778. %@NL@%
  7779.   1. Declare a record type. A record type is a template for data. It
  7780.      declares the sizes and, optionally, the initial values for bit fields
  7781.      in the record. By itself, the record type does not define any data. The
  7782.      record type is used by Quick-Assembler during assembly but is not saved
  7783.      as part of the object file.%@NL@%
  7784. %@NL@%
  7785.   2. Define one or more variables having the record type. For each variable
  7786.      defined, memory is allocated to the object file in the format declared
  7787.      by the type.%@NL@%
  7788. %@NL@%
  7789. %@4@%  The record variable can then be used as an operand in assembler%@EH@%
  7790.   statements. The record variable can be accessed as a whole by using the
  7791.   record name, or individual fields can be specified by using the record
  7792.   name and a field name combined with the field-name operator. A record type
  7793.   can also be used as a constant (immediate data).%@NL@%
  7794. %@NL@%
  7795. %@NL@%
  7796. %@3@%%@CR:SC7.2.1     @%%@AB@%7.2.1  Declaring Record Types%@AE@%%@EH@%%@NL@%
  7797. %@NL@%
  7798. %@4@%%@CR:IX7.30      @%%@CR:IX7.31      @%%@CR:IX7.32      @%%@CR:IX7.33      @%%@CR:IX7.34      @%%@CR:IX7.35      @%%@CR:IX7.36      @%%@CR:IX7.37      @%%@CR:IX7.38      @%  The %@AB@%RECORD%@AE@% directive declares a record type for an 8-bit or 16-bit record%@EH@%
  7799.   that contains one or more bit fields.%@NL@%
  7800. %@NL@%
  7801. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7802. %@NL@%
  7803. %@4@%  %@AI@%recordname%@AE@% %@AB@%RECORD%@AE@% %@AI@%field%@AE@% [[%@AB@%,%@AE@%%@AI@%field%@AE@%]]...%@EH@%%@NL@%
  7804. %@NL@%
  7805. %@4@%  The %@AI@%recordname%@AE@% is the name of the record type to be used when creating the%@EH@%
  7806.   record. The %@AI@%field%@AE@% declares the name, width, and initial value for the
  7807.   field.%@NL@%
  7808. %@NL@%
  7809. %@4@%  The syntax for each %@AI@%field%@AE@% is shown below:%@EH@%%@NL@%
  7810. %@NL@%
  7811. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7812. %@NL@%
  7813. %@4@%  %@AI@%fieldname%@AE@%%@AB@%:%@AE@%%@AI@%width%@AE@%[[%@AB@%=%@AE@%%@AI@%expression%@AE@%]]%@EH@%%@NL@%
  7814. %@NL@%
  7815. %@4@%  The %@AI@%fieldname%@AE@% is the name of a field in the record, %@AI@%width%@AE@% is the number of%@EH@%
  7816.   bits in the field, and %@AI@%expression%@AE@% is the initial (or default) value for
  7817.   the field.%@NL@%
  7818. %@NL@%
  7819. %@4@%  Any number of field combinations can be given for a record, as long as%@EH@%
  7820.   each is separated from its predecessor by a comma. The sum of the widths
  7821.   for all fields must not exceed 16 bits.%@NL@%
  7822. %@NL@%
  7823. %@4@%%@CR:IX7.39      @%  The width must be a constant. If the total width of all declared fields is%@EH@%
  7824.   larger than eight bits, the assembler uses two bytes. Otherwise, only one
  7825.   byte is used.%@NL@%
  7826. %@NL@%
  7827. %@4@%  If %@AI@%expression%@AE@% is given, it declares the initial value for the field. An%@EH@%
  7828.   error message is generated if an initial value is too large for the width
  7829.   of its field. If the field is at least seven bits wide, you can use an
  7830.   ASCII character for %@AI@%expression%@AE@%. The expression must not contain a forward
  7831.   reference to any symbol.%@NL@%
  7832. %@NL@%
  7833. %@4@%  In all cases, the first field you declare goes into the most significant%@EH@%
  7834.   bits of the record. Successively declared fields are placed in the
  7835.   succeeding bits to the right. If the fields you declare do not total
  7836.   exactly 8 bits or exactly 16 bits, the entire record is shifted right so
  7837.   that the last bit of the last field is the lowest bit of the record.
  7838.   Unused bits in the high end of the record are initialized to 0.%@NL@%
  7839. %@NL@%
  7840. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  7841. %@NL@%
  7842.   %@AS@%color       RECORD  blink:1,back:3,intense:1,fore:3%@AE@%%@NL@%
  7843. %@NL@%
  7844. %@4@%%@CR:IX7.40      @%  Example 1 creates a byte record type %@AS@%color %@AE@%having four fields: %@AS@%blink%@AE@%,%@EH@%
  7845.   %@AS@%back%@AE@%, %@AS@%intense%@AE@%, and %@AS@%fore%@AE@%. The contents of the record type are shown below:%@NL@%
  7846. %@NL@%
  7847.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  7848.   │ This figure can be found in Section 7.2.1 of the manual                │%@NL@%
  7849.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  7850. %@NL@%
  7851. %@4@%  Since no initial values are given, all bits are set to 0. Note that this%@EH@%
  7852.   is only a template maintained by the assembler. No data is created.%@NL@%
  7853. %@NL@%
  7854. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  7855. %@NL@%
  7856.   %@AS@%cw          RECORD   r1:3=0,ic:1=0,rc:2=0,pc:2=3,r2:2=1,masks:6=63%@AE@%%@NL@%
  7857. %@NL@%
  7858. %@4@%%@CR:IX7.41      @%  Example 2 creates a record type %@AS@%cw %@AE@%having six fields. Each record declared%@EH@%
  7859.   by using this type occupies 16 bits of memory. The bit diagram below shows
  7860.   the contents of the record type:%@NL@%
  7861. %@NL@%
  7862.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  7863.   │ This figure can be found in Section 7.2.1 of the manual                │%@NL@%
  7864.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  7865. %@NL@%
  7866. %@4@%  Default values are given for each field. They can be used when data is%@EH@%
  7867.   declared for the record.%@NL@%
  7868. %@NL@%
  7869. %@NL@%
  7870. %@3@%%@CR:SC7.2.2     @%%@AB@%7.2.2  Defining Record Variables%@AE@%%@EH@%%@NL@%
  7871. %@NL@%
  7872. %@4@%%@CR:IX7.42      @%%@CR:IX7.43      @%%@CR:IX7.44      @%%@CR:IX7.45      @%  A record variable is an 8-bit or 16-bit variable whose bits are divided%@EH@%
  7873.   into one or more fields.%@NL@%
  7874. %@NL@%
  7875. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7876. %@NL@%
  7877. %@4@%  [[%@AI@%name%@AE@%]] %@AI@%recordname%@AE@% %@AB@%<%@AE@%[[%@AI@%initialvalue%@AE@% [[%@AB@%,%@AE@%%@AI@%initialvalue%@AE@%]]...]]%@AB@%>%@AE@%%@EH@%%@NL@%
  7878. %@NL@%
  7879. %@4@%  The %@AI@%name%@AE@% is the symbolic name of the variable. If no name is given, the%@EH@%
  7880.   assembler allocates space for the variable, but does not give it a
  7881.   symbolic name. The %@AI@%recordname%@AE@% is the name of a record type that was
  7882.   previously declared by using the %@AB@%RECORD%@AE@% directive.%@NL@%
  7883. %@NL@%
  7884. %@4@%  An %@AI@%initialvalue%@AE@% for each field in the record can be given as an integer, a%@EH@%
  7885.   character constant, or an expression that resolves to a value compatible
  7886.   with the size of the field. Angle brackets (%@AB@%< >%@AE@%) are required even if no
  7887.   initial value is given. If initial values for more than one field are
  7888.   given, the values must be separated by commas.%@NL@%
  7889. %@NL@%
  7890. %@4@%%@CR:IX7.46      @%%@CR:IX7.47      @%  If the %@AB@%DUP%@AE@% operator (see Section 6.5.2%@BO:       65365@%, "Arrays and Buffers") is used to%@EH@%
  7891.   initialize multiple record variables, only the angle brackets and initial
  7892.   values, if given, need to be enclosed in parentheses. For example, you can
  7893.   define an array of record variables as shown below:%@NL@%
  7894. %@NL@%
  7895.   %@AS@%xmas        color   50 DUP (<1,2,0,4>)%@AE@%%@NL@%
  7896. %@NL@%
  7897. %@4@%  You do not have to initialize all fields in a record. If an initial value%@EH@%
  7898.   is left blank, the assembler automatically uses the default initial value
  7899.   of the field. This is declared by the record type. If there is no default
  7900.   value, each bit in the field is cleared.%@NL@%
  7901. %@NL@%
  7902. %@4@%  Sections 7.2.3%@BO:       6e990@%, "Using Record Operands and Record Variables," and 7.2.4%@BO:       6e991@%,%@EH@%
  7903.   "Record Operators," illustrate ways to use record data after it has been
  7904.   declared.%@NL@%
  7905. %@NL@%
  7906. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  7907. %@NL@%
  7908.   %@AS@%color       RECORD  blink:1,back:3,intense:1,fore:3 ; Record declaration%@AE@%%@NL@%
  7909.   %@AS@%warning     color   <1,0,1,4>                       ; Record definition%@AE@%%@NL@%
  7910. %@NL@%
  7911. %@4@%%@CR:IX7.48      @%  The definition above creates a variable named %@AS@%warning %@AE@%whose type is given%@EH@%
  7912.   by the record type %@AS@%color%@AE@%. The initial values of the fields in the variable
  7913.   are set to the values given in the record definition. The initial values
  7914.   would override the default record values, had any been given in the
  7915.   declaration. The contents of the record variable are shown below:%@NL@%
  7916. %@NL@%
  7917.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  7918.   │ This figure can be found in Section 7.2.2 of the manual                │%@NL@%
  7919.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  7920. %@NL@%
  7921. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  7922. %@NL@%
  7923.   %@AS@%color       RECORD  blink:1,back:3,intense:1,fore:3 ; Record declaration%@AE@%%@NL@%
  7924.   %@AS@%colors      color   16 DUP (<>)                     ; Record declaration%@AE@%%@NL@%
  7925. %@NL@%
  7926. %@4@%  Example 2 creates an array named %@AS@%colors %@AE@%containing 16 variables of type%@EH@%
  7927.   %@AS@%color%@AE@%. Since no initial values are given in either the declaration or the
  7928.   definition, the variables have undefined (0) values.%@NL@%
  7929. %@NL@%
  7930. %@4@%  %@AB@%Example 3%@AE@%%@EH@%%@NL@%
  7931. %@NL@%
  7932.   %@AS@%cw          RECORD   r1:3=0,ic:1=0,rc:2=0,pc:2=3,r2:2=1,masks:6=63%@AE@%%@NL@%
  7933.   %@AS@%newcw       cw       <,,2,,,>%@AE@%%@NL@%
  7934. %@NL@%
  7935. %@4@%%@CR:IX7.49      @%  Example 3 creates a variable named %@AS@%newcw %@AE@%with type %@AS@%cw%@AE@%. The default values%@EH@%
  7936.   set in the type declaration are used for all fields except the %@AS@%rc %@AE@%field.
  7937.   This field is set to 2. The contents of the variable are shown below:%@NL@%
  7938. %@NL@%
  7939.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  7940.   │ This figure can be found in Section 7.2.2 of the manual                │%@NL@%
  7941.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  7942. %@NL@%
  7943. %@NL@%
  7944. %@3@%%@CR:SC7.2.3     @%%@AB@%7.2.3  Using Record Operands and Record Variables%@AE@%%@EH@%%@NL@%
  7945. %@NL@%
  7946. %@4@%%@CR:IX7.50      @%%@CR:IX7.51      @%%@CR:IX7.52      @%%@CR:IX7.53      @%%@CR:IX7.54      @%  A record operand refers to the value of a record type. It should not be%@EH@%
  7947.   confused with a record variable. A record operand is a constant; a record
  7948.   variable is a value stored in memory. A record operand can be used with
  7949.   the following syntax:%@NL@%
  7950. %@NL@%
  7951. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  7952. %@NL@%
  7953. %@4@%  %@AI@%recordname%@AE@% %@AB@%<%@AE@%[[%@AI@%value%@AE@%[[%@AB@%,%@AE@%%@AI@%value%@AE@%]]...]]%@AB@%>%@AE@%%@EH@%%@NL@%
  7954. %@NL@%
  7955. %@4@%  The %@AI@%recordname%@AE@% must be the name of a record type declared in the source%@EH@%
  7956.   file. The optional %@AI@%value%@AE@% is the value of a field in the record. If more
  7957.   than one %@AI@%value%@AE@% is given, each value must be separated by a comma. Values
  7958.   can include expressions or symbols that evaluate to constants. The
  7959.   enclosing angle brackets (%@AB@%<>%@AE@%) are required, even if no value is given. If
  7960.   no value for a field is given, the default value for that field is used.%@NL@%
  7961. %@NL@%
  7962. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  7963. %@NL@%
  7964.   %@AS@%            .DATA%@AE@%%@NL@%
  7965.   %@AS@%color       RECORD  blink:1,back:3,intense:1,fore:3 ; Record declaration%@AE@%%@NL@%
  7966.   %@AS@%window      color   <0,6,1,6>                       ; Record definition%@AE@%%@NL@%
  7967. %@NL@%
  7968.   %@AS@%            .CODE%@AE@%%@NL@%
  7969.   %@AS@%            .%@AE@%%@NL@%
  7970.   %@AS@%            .%@AE@%%@NL@%
  7971.   %@AS@%            .%@AE@%%@NL@%
  7972.   %@AS@%            mov     ah,color <0,3,0,2>              ; Load record operand%@AE@%%@NL@%
  7973.   %@AS@%                                                    ;   (constant value 32h)%@AE@%%@NL@%
  7974.   %@AS@%            mov     bh,window                       ; Load record variable%@AE@%%@NL@%
  7975.   %@AS@%                                                    ;   (memory value 6Eh)%@AE@%%@NL@%
  7976. %@NL@%
  7977. %@4@%%@CR:IX7.55      @%%@CR:IX7.56      @%  In this example, the record operand %@AS@%color <0,3,0,2> %@AE@%and the record%@EH@%
  7978.   variable %@AS@%warning %@AE@%are loaded into registers. The contents of the values are
  7979.   shown below:%@NL@%
  7980. %@NL@%
  7981.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  7982.   │ This figure can be found in Section 7.2.3 of the manual                │%@NL@%
  7983.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  7984. %@NL@%
  7985. %@NL@%
  7986. %@3@%%@CR:SC7.2.4     @%%@AB@%7.2.4  Record Operators%@AE@%%@EH@%%@NL@%
  7987. %@NL@%
  7988. %@4@%  The %@AB@%WIDTH%@AE@% and %@AB@%MASK%@AE@% operators are used exclusively with records to return%@EH@%
  7989.   constant values representing different aspects of previously declared
  7990.   records.%@NL@%
  7991. %@NL@%
  7992. %@NL@%
  7993. %@3@%%@CR:SC7.2.4.1   @%%@AB@%7.2.4.1  The MASK Operator%@AE@%%@EH@%%@NL@%
  7994. %@NL@%
  7995. %@4@%%@CR:IX7.57      @%%@CR:IX7.58      @%%@CR:IX7.59      @%  The %@AB@%MASK%@AE@% operator returns a bit mask for the bit positions in a record%@EH@%
  7996.   occupied by the given record field. A bit in the mask contains a 1 if that
  7997.   bit corresponds to a field bit. All other bits contain 0.%@NL@%
  7998. %@NL@%
  7999. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8000. %@NL@%
  8001. %@4@%  %@AB@%MASK%@AE@% {%@AI@%recordfieldname%@AE@% | %@AI@%record%@AE@%}%@EH@%%@NL@%
  8002. %@NL@%
  8003. %@4@%  The %@AI@%recordfieldname%@AE@% may be the name of any field in a previously defined%@EH@%
  8004.   record. The %@AI@%record%@AE@% may be the name of any previously defined record. The
  8005.   %@AB@%NOT%@AE@% operator is sometimes used with the %@AB@%MASK%@AE@% operator to reverse the bits
  8006.   of a mask.%@NL@%
  8007. %@NL@%
  8008. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  8009. %@NL@%
  8010.   %@AS@%            .DATA%@AE@%%@NL@%
  8011.   %@AS@%color       RECORD  blink:1,back:3,intense:1,fore:3%@AE@%%@NL@%
  8012.   %@AS@%message     color   <0,5,1,1>%@AE@%%@NL@%
  8013.   %@AS@%            .CODE%@AE@%%@NL@%
  8014.   %@AS@%            .%@AE@%%@NL@%
  8015.   %@AS@%            .%@AE@%%@NL@%
  8016.   %@AS@%            .%@AE@%%@NL@%
  8017.   %@AS@%            mov     ah,message           ; Load initial   0101 1001%@AE@%%@NL@%
  8018.   %@AS@%            and     ah,NOT MASK back     ; Turn off   AND 1000 1111%@AE@%%@NL@%
  8019.   %@AS@%                                         ; "back"         ---------%@AE@%%@NL@%
  8020.   %@AS@%                                         ;                0000 1001%@AE@%%@NL@%
  8021.   %@AS@%            or      ah,MASK blink        ; Turn on     OR 1000 0000%@AE@%%@NL@%
  8022.   %@AS@%                                         ; "blink"        ---------%@AE@%%@NL@%
  8023.   %@AS@%                                         ;                1000 1001%@AE@%%@NL@%
  8024.   %@AS@%            xor     ah,MASK intense      ; Toggle     XOR 0000 1000%@AE@%%@NL@%
  8025.   %@AS@%                                         ; "intense"      ---------%@AE@%%@NL@%
  8026.   %@AS@%                                         ;                1000 0001%@AE@%%@NL@%
  8027. %@NL@%
  8028. %@NL@%
  8029. %@3@%%@CR:SC7.2.4.2   @%%@AB@%7.2.4.2  The WIDTH Operator%@AE@%%@EH@%%@NL@%
  8030. %@NL@%
  8031. %@4@%%@CR:IX7.60      @%%@CR:IX7.61      @%%@CR:IX7.62      @%  The %@AB@%WIDTH%@AE@% operator returns the width (in bits) of a record or record%@EH@%
  8032.   field.%@NL@%
  8033. %@NL@%
  8034. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8035. %@NL@%
  8036. %@4@%  %@AB@%WIDTH%@AE@% {%@AI@%recordfieldname%@AE@% | %@AI@%record%@AE@%}%@EH@%%@NL@%
  8037. %@NL@%
  8038. %@4@%  The %@AI@%recordfieldname%@AE@% may be the name of any field defined in any record.%@EH@%
  8039.   The %@AI@%record%@AE@% may be the name of any defined record.%@NL@%
  8040. %@NL@%
  8041. %@4@%  Note that the width of a field is the number of bits assigned for that%@EH@%
  8042.   field; the value of the field is the starting position (from the right) of
  8043.   the field.%@NL@%
  8044. %@NL@%
  8045. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  8046. %@NL@%
  8047.   %@AS@%            .DATA%@AE@%%@NL@%
  8048.   %@AS@%color       RECORD  blink:1,back:3,intense:1,fore:3%@AE@%%@NL@%
  8049. %@NL@%
  8050.   %@AS@%wblink      EQU     WIDTH blink        ; "wblink"   = 1   "blink"   = 7%@AE@%%@NL@%
  8051.   %@AS@%wback       EQU     WIDTH back         ; "wback"    = 3   "back"    = 4%@AE@%%@NL@%
  8052.   %@AS@%wintense    EQU     WIDTH intense      ; "wintense" = 1   "intense" = 3%@AE@%%@NL@%
  8053.   %@AS@%wfore       EQU     WIDTH fore         ; "wfore"    = 3   "fore"    = 0%@AE@%%@NL@%
  8054.   %@AS@%wcolor      EQU     WIDTH color        ; "wcolor"   = 8%@AE@%%@NL@%
  8055. %@NL@%
  8056.   %@AS@%prompt      color   <1,5,1,1>%@AE@%%@NL@%
  8057. %@NL@%
  8058.   %@AS@%            .CODE%@AE@%%@NL@%
  8059.   %@AS@%            .%@AE@%%@NL@%
  8060.   %@AS@%            .%@AE@%%@NL@%
  8061.   %@AS@%            .%@AE@%%@NL@%
  8062.   %@AS@%            IF      (WIDTH color) GE 8 ; If color is 16 bit, load%@AE@%%@NL@%
  8063.   %@AS@%            mov     ax,prompt          ;   into 16-bit register%@AE@%%@NL@%
  8064.   %@AS@%            ELSE                       ; else%@AE@%%@NL@%
  8065.   %@AS@%            mov     al,prompt          ;   load into low 8-bit register%@AE@%%@NL@%
  8066.   %@AS@%            xor     ah,ah              ;   and clear high 8-bit register%@AE@%%@NL@%
  8067.   %@AS@%            ENDIF%@AE@%%@NL@%
  8068. %@NL@%
  8069. %@NL@%
  8070. %@3@%%@CR:SC7.2.5     @%%@AB@%7.2.5  Using Record-Field Operands%@AE@%%@EH@%%@NL@%
  8071. %@NL@%
  8072. %@4@%%@CR:IX7.63      @%%@CR:IX7.64      @%  Record-field operands represent the location of a field in its%@EH@%
  8073.   corresponding record. The operand evaluates to the bit position of the
  8074.   low-order bit in the field and can be used as a constant operand. The
  8075.   field name must be from a previously declared record.%@NL@%
  8076. %@NL@%
  8077. %@4@%  Record-field operands are often used with the %@AB@%WIDTH%@AE@% and %@AB@%MASK%@AE@% operators, as%@EH@%
  8078.   described in Sections 7.2.4.1%@BO:       6f465@% and 7.2.4.2%@BO:       6fc80@%.%@NL@%
  8079. %@NL@%
  8080. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  8081. %@NL@%
  8082.   %@AS@%            .DATA%@AE@%%@NL@%
  8083.   %@AS@%color       RECORD  blink:1,back:3,intense:1,fore:3  ; Record declaration%@AE@%%@NL@%
  8084.   %@AS@%cursor      color   <1,5,1,1>                        ; Record definition%@AE@%%@NL@%
  8085.   %@AS@%            .CODE%@AE@%%@NL@%
  8086.   %@AS@%            .%@AE@%%@NL@%
  8087.   %@AS@%            .%@AE@%%@NL@%
  8088.   %@AS@%            .%@AE@%%@NL@%
  8089. %@NL@%
  8090.   %@AS@%; Rotate "back" of "cursor" without changing other values%@AE@%%@NL@%
  8091. %@NL@%
  8092.   %@AS@%            mov     al,cursor        ; Load value from memory%@AE@%%@NL@%
  8093.   %@AS@%            mov     ah,al            ; Save a copy for work      1101 1001=ah/al%@AE@%%@NL@%
  8094.   %@AS@%            and     al,NOT MASK back ; Mask out old bits     AND 1000 1111=mask%@AE@%%@NL@%
  8095.   %@AS@%                                     ;   to save old cursor      ---------%@AE@%%@NL@%
  8096.   %@AS@%                                     ;                           1000 1001=al%@AE@%%@NL@%
  8097.   %@AS@%            mov     cl,back          ; Load bit position%@AE@%%@NL@%
  8098.   %@AS@%            shr     ah,cl            ; Shift to right            0000 1101=ah%@AE@%%@NL@%
  8099.   %@AS@%            inc     ah               ; Increment                 0000 1110=ah%@AE@%%@NL@%
  8100. %@NL@%
  8101.   %@AS@%            shl     ah,cl            ; Shift left again          1110 0000=ah%@AE@%%@NL@%
  8102.   %@AS@%            and     ah,MASK back     ; Mask off extra bits   AND 0111 0000=mask%@AE@%%@NL@%
  8103.   %@AS@%                                     ;   to get new cursor       ---------%@AE@%%@NL@%
  8104.   %@AS@%                                     ;                           0110 0000 ah%@AE@%%@NL@%
  8105.   %@AS@%            or      ah,al            ; Combine old and new    OR 1000 1001 al%@AE@%%@NL@%
  8106.   %@AS@%                                     ;                           ---------%@AE@%%@NL@%
  8107.   %@AS@%            mov     cursor,ah        ; Write back to memory      1110 1001 ah%@AE@%%@NL@%
  8108. %@NL@%
  8109. %@4@%  This example illustrates several ways in which record fields can be used%@EH@%
  8110.   as operands and in expressions.%@NL@%
  8111. %@NL@%
  8112. %@NL@%
  8113. %@NL@%
  8114. ────────────────────────────────────────────────────────────────────────────%@NL@%
  8115. %@1@%%@CR:CH8         @%%@AB@%Chapter 8:  Creating Programs from Multiple Modules%@AE@%%@EH@%%@NL@%
  8116. %@NL@%
  8117. %@NL@%
  8118. %@4@%%@CR:IX8.1       @%%@CR:IX8.2       @%%@CR:IX8.3       @%%@CR:IX8.4       @%  Most medium and large assembly-language programs are created from several%@EH@%
  8119.   source files or modules. When several modules are used, the scope of
  8120.   symbols becomes important. This chapter discusses the scope of symbols and
  8121.   explains how to declare global symbols that can be accessed from any
  8122.   module. It also tells you how to specify a module that will be accessed
  8123.   from a library.%@NL@%
  8124. %@NL@%
  8125. %@4@%%@CR:IX8.5       @%%@CR:IX8.6       @%%@CR:IX8.7       @%  Symbols, such as labels and variable names, can be either local or global%@EH@%
  8126.   in scope. By default, all symbols are local; they are specific to the
  8127.   source file in which they are defined. Symbols must be declared global if
  8128.   they must be accessed from modules other than the one in which they are
  8129.   defined.%@NL@%
  8130. %@NL@%
  8131. %@4@%%@CR:IX8.8       @%%@CR:IX8.9       @%%@CR:IX8.10      @%%@CR:IX8.11      @%%@CR:IX8.12      @%%@CR:IX8.13      @%%@CR:IX8.14      @%%@CR:IX8.15      @%  To declare symbols global, they must be declared public in the source%@EH@%
  8132.   module in which they are defined. They must also be declared external in
  8133.   any module that must access the symbol. If the symbol represents
  8134.   uninitialized data, it can be declared communal──meaning that the symbol
  8135.   is both public and external. The %@AB@%PUBLIC%@AE@%, %@AB@%EXTRN%@AE@%, and %@AB@%COMM %@AE@%directives are
  8136.   used to declare symbols public, external, and communal, respectively.%@NL@%
  8137. %@NL@%
  8138.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8139.   %@AB@%NOTE%@AE@%  The term "local" often has a different meaning in assembly language
  8140.   than in many high-level languages. Local symbols in compiled languages are
  8141.   symbols that are known only within a procedure (called a function,
  8142.   routine, subprogram, or subroutine, depending on the language). You can
  8143.   use QuickAssembler to generate these kinds of variables, as explained in
  8144.   Section 15.3.6%@BO:       cb138@%, "Creating Locals Automatically."%@NL@%
  8145. %@CR:IX8.16      @%%@CR:IX8.17      @%%@NL@%
  8146.   By default, the assembler converts all lowercase letters in names declared
  8147.   with the %@AB@%PUBLIC%@AE@%, %@AB@%EXTRN%@AE@%, and %@AB@%COMM%@AE@% directives to uppercase letters before
  8148.   copying the name to the object file. To preserve lowercase names in public
  8149.   symbols, choose Preserve Case or Preserve Extrn from the Assembler Flags
  8150.   dialog box, or assemble with /Cx or /Cl on the QCL command line. This
  8151.   should be done when preparing assembler modules to be linked with modules
  8152.   from C and other case-sensitive languages.%@NL@%
  8153.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8154. %@NL@%
  8155. %@NL@%
  8156. %@2@%%@CR:SC8.1       @%%@AB@%8.1  Declaring Symbols Public%@AE@%%@EH@%%@NL@%
  8157. %@NL@%
  8158. %@4@%%@CR:IX8.18      @%%@CR:IX8.19      @%%@CR:IX8.20      @%%@CR:IX8.21      @%%@CR:IX8.22      @%%@CR:IX8.23      @%%@CR:IX8.24      @%  The %@AB@%PUBLIC%@AE@% directive is used to declare symbols public so that they can be%@EH@%
  8159.   accessed from other modules. If a symbol is not declared public, the
  8160.   symbol name is not written to the object file. The symbol has the value of
  8161.   its offset address during assembly, but the name and address are not
  8162.   available to the linker.%@NL@%
  8163. %@NL@%
  8164. %@4@%  If the symbol is declared public, its name is associated with its offset%@EH@%
  8165.   address in the object file. During linking, symbols in different
  8166.   modules──but with the same name──are resolved to a single address.%@NL@%
  8167. %@NL@%
  8168. %@4@%%@CR:IX8.25      @%  Public symbol names are also used by some symbolic debuggers (such as%@EH@%
  8169.   SYMDEB) to associate addresses with symbols.%@NL@%
  8170. %@NL@%
  8171. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8172. %@NL@%
  8173. %@4@%  %@AB@%PUBLIC%@AE@% %@AI@%declaration%@AE@% [[%@AB@%,%@AE@%%@AI@%declaration%@AE@%]]...%@EH@%%@NL@%
  8174. %@NL@%
  8175. %@4@%  Each %@AI@%declaration%@AE@% has the following syntax:%@EH@%%@NL@%
  8176. %@NL@%
  8177. %@4@%  [[%@AI@%lang%@AE@%]] %@AI@%name%@AE@%%@EH@%%@NL@%
  8178. %@NL@%
  8179. %@4@%%@CR:IX8.26      @%%@CR:IX8.27      @%  The optional %@AI@%lang%@AE@% field contains a language specifier that overrides the%@EH@%
  8180.   language specified by the %@AB@%.MODEL%@AE@% directive. With this statement, the
  8181.   language specifier determines naming conventions for the variable that it
  8182.   precedes. The specifier can be %@AB@%C%@AE@%, %@AB@%FORTRAN%@AE@%, %@AB@%Pascal%@AE@%, or %@AB@%BASIC%@AE@%. The C naming
  8183.   convention prefixes each variable with an underscore (_); the other
  8184.   conventions do not. If you specify %@AI@%lang%@AE@% with the %@AB@%.MODEL%@AE@% directive, all
  8185.   procedures are automatically public. However, you must use the %@AB@%PUBLIC%@AE@%
  8186.   directive for any data that you want to access from other modules.%@NL@%
  8187. %@NL@%
  8188. %@4@%  Note that using the %@AB@%C%@AE@% type specifier does not preserve case. You must%@EH@%
  8189.   choose one of the assembler flags or options that preserve case.%@NL@%
  8190. %@NL@%
  8191. %@4@%  The %@AI@%name%@AE@% must be the name of a variable, label, or numeric equate defined%@EH@%
  8192.   within the current source file. %@AB@%PUBLIC%@AE@% declarations can be placed anywhere
  8193.   in the source file. Equate names, if given, can only represent one-byte or
  8194.   two-byte integer or string values. Text macros (or text equates) cannot be
  8195.   declared public.%@NL@%
  8196. %@NL@%
  8197. %@4@%  Note that although absolute symbols can be declared public, aliases for%@EH@%
  8198.   public symbols may cause errors. For example, the following statements are
  8199.   illegal:%@NL@%
  8200. %@NL@%
  8201.   %@AS@%            PUBLIC  lines      ; Declare absolute symbol public%@AE@%%@NL@%
  8202.   %@AS@%lines       EQU     rows       ; Declare alias for lines%@AE@%%@NL@%
  8203.   %@AS@%rows        EQU     25         ; Illegal - Assign value to alias%@AE@%%@NL@%
  8204. %@NL@%
  8205. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  8206. %@NL@%
  8207.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  8208.   %@AS@%            PUBLIC  true,status,first,clear%@AE@%%@NL@%
  8209.   %@AS@%true        EQU     -1        ; Public constant%@AE@%%@NL@%
  8210.   %@AS@%            .DATA%@AE@%%@NL@%
  8211.   %@AS@%status      DB      1         ; Public variable%@AE@%%@NL@%
  8212.   %@AS@%            .CODE%@AE@%%@NL@%
  8213.   %@AS@%            .%@AE@%%@NL@%
  8214.   %@AS@%            .%@AE@%%@NL@%
  8215.   %@AS@%            .%@AE@%%@NL@%
  8216.   %@AS@%first       LABEL   FAR       ; Public label%@AE@%%@NL@%
  8217.   %@AS@%clear       PROC              ; Procedure names are automatically public%@AE@%%@NL@%
  8218.   %@AS@%            .                 ;   with .MODEL model, lang%@AE@%%@NL@%
  8219.   %@AS@%            .%@AE@%%@NL@%
  8220.   %@AS@%            .%@AE@%%@NL@%
  8221.   %@AS@%clear       ENDP%@AE@%%@NL@%
  8222. %@NL@%
  8223. %@NL@%
  8224. %@2@%%@CR:SC8.2       @%%@AB@%8.2  Declaring Symbols External%@AE@%%@EH@%%@NL@%
  8225. %@NL@%
  8226. %@4@%%@CR:IX8.28      @%%@CR:IX8.29      @%%@CR:IX8.30      @%%@CR:IX8.31      @%%@CR:IX8.32      @%%@CR:IX8.33      @%%@CR:IX8.34      @%  If a symbol undeclared in a module must be accessed by instructions in%@EH@%
  8227.   that module, it must be declared with the %@AB@%EXTRN%@AE@% directive.%@NL@%
  8228. %@NL@%
  8229. %@4@%%@CR:IX8.35      @%  This directive tells the assembler not to generate an error, even though%@EH@%
  8230.   the symbol is not in the current module. The assembler assumes that the
  8231.   symbol occurs in another module. However, the symbol must actually exist
  8232.   and must be declared public in some module. Otherwise, the linker
  8233.   generates an error.%@NL@%
  8234. %@NL@%
  8235. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8236. %@NL@%
  8237. %@4@%  %@AB@%EXTRN%@AE@% %@AI@%declaration%@AE@%%@AB@% %@AE@%[[%@AB@%,%@AE@%%@AI@%declaration%@AE@%]]...%@EH@%%@NL@%
  8238. %@NL@%
  8239. %@4@%  Each %@AI@%declaration%@AE@% has the following syntax:%@EH@%%@NL@%
  8240. %@NL@%
  8241. %@4@%  [[%@AI@%lang%@AE@%]]%@AI@%name%@AE@%%@AB@%:%@AE@%%@AI@%type%@AE@%%@EH@%%@NL@%
  8242. %@NL@%
  8243. %@4@%  The optional %@AI@%lang%@AE@% field contains a language specifier that overrides the%@EH@%
  8244.   language specified by the %@AB@%.MODEL%@AE@% directive. With this statement, the
  8245.   language specifier determines naming conventions for the variable that it
  8246.   precedes. The specifier can be %@AB@%C%@AE@%, %@AB@%FORTRAN%@AE@%, %@AB@%Pascal%@AE@%, or %@AB@%BASIC%@AE@%. The C naming
  8247.   convention prefixes each variable with an underscore (_); the other
  8248.   conventions do not.%@NL@%
  8249. %@NL@%
  8250. %@4@%  Note that using the %@AB@%C%@AE@% type specifier does not preserve case. You must%@EH@%
  8251.   choose one of the assembler flags or options that preserve case.%@NL@%
  8252. %@NL@%
  8253. %@4@%  The %@AB@%EXTRN%@AE@% directive defines an external variable, label, or symbol of the%@EH@%
  8254.   specified %@AI@%name%@AE@% and %@AI@%type%@AE@%. The %@AI@%type%@AE@% must match the type given to the item in
  8255.   its actual definition in some other module. It can be any one of the
  8256.   following:%@NL@%
  8257. %@NL@%
  8258.   %@AB@%Description%@AE@%         %@AB@%Types%@AE@%%@NL@%
  8259.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8260.   Distance specifier  %@AB@%NEAR%@AE@%, %@AB@%FAR%@AE@%, or %@AB@%PROC%@AE@%%@NL@%
  8261. %@NL@%
  8262.   Size specifier      %@AB@%BYTE%@AE@%, %@AB@%WORD%@AE@%, %@AB@%DWORD%@AE@%, %@AB@%QWORD%@AE@%, or %@AB@%TBYTE%@AE@%%@NL@%
  8263. %@NL@%
  8264.   Absolute            %@AB@%ABS%@AE@%%@NL@%
  8265. %@NL@%
  8266. %@NL@%
  8267. %@4@%%@CR:IX8.36      @%%@CR:IX8.37      @%%@CR:IX8.38      @%%@CR:IX8.39      @%%@CR:IX8.40      @%%@CR:IX8.41      @%%@CR:IX8.42      @%  The %@AB@%ABS%@AE@% type is for symbols that represent constant numbers, such as%@EH@%
  8268.   equates declared with the %@AB@%EQU%@AE@% and %@AB@%=%@AE@% directives (see Section 11.1%@BO:       8dc18@%, "Using
  8269.   Equates").%@NL@%
  8270. %@NL@%
  8271. %@4@%%@CR:IX8.43      @%%@CR:IX8.44      @%%@CR:IX8.45      @%%@CR:IX8.46      @%%@CR:IX8.47      @%  The %@AB@%PROC%@AE@% type represents the default type for a procedure. For programs%@EH@%
  8272.   that use simplified segment directives, the type of an external symbol
  8273.   declared with %@AB@%PROC%@AE@% will be %@AB@%NEAR%@AE@% for small or compact model, or %@AB@%FAR%@AE@% for
  8274.   medium, large, or huge model. Section 5.1.3%@BO:       42b44@%, "Defining Basic Attributes
  8275.   of the Model," tells you how to declare the memory model using the %@AB@%.MODEL%@AE@%
  8276.   directive. If full segment definitions are used, the default type
  8277.   represented by %@AB@%PROC%@AE@% is always %@AB@%NEAR%@AE@%.%@NL@%
  8278. %@NL@%
  8279. %@4@%  Although the actual address of an external symbol is not determined until%@EH@%
  8280.   link time, the assembler assumes a default segment for the item, based on
  8281.   where the %@AB@%EXTRN%@AE@% directive is placed in the source code. Placement of %@AB@%EXTRN%@AE@%
  8282.   directives should follow these rules:%@NL@%
  8283. %@NL@%
  8284.   ■  %@AB@%NEAR%@AE@% code labels (such as procedures) must be declared in the code
  8285.      segment from which they are accessed.%@NL@%
  8286. %@NL@%
  8287.   ■  %@AB@%FAR%@AE@% code labels can be declared anywhere in the source code. It may be
  8288.      convenient to declare them in the code segment from which they are
  8289.      accessed if the label may be %@AB@%FAR%@AE@% in one context or %@AB@%NEAR%@AE@% in another.%@NL@%
  8290. %@NL@%
  8291.   ■  Data must be declared in the segment in which it occurs. This may
  8292.      require that you define a dummy data segment for the external
  8293.      declaration.%@NL@%
  8294. %@NL@%
  8295.   ■  Absolute symbols can be declared anywhere in the source code.%@NL@%
  8296. %@NL@%
  8297. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  8298. %@NL@%
  8299.   %@AS@%            EXTRN   max:ABS,act:FAR     ; Constant or FAR label anywhere%@AE@%%@NL@%
  8300.   %@AS@%            DOSSEG%@AE@%%@NL@%
  8301.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  8302.   %@AS@%            .STACK  100h%@AE@%%@NL@%
  8303.   %@AS@%            .DATA%@AE@%%@NL@%
  8304.   %@AS@%            EXTRN   nvar:BYTE           ; NEAR variable in near data%@AE@%%@NL@%
  8305.   %@AS@%            .FARDATA%@AE@%%@NL@%
  8306.   %@AS@%            EXTRN   fvar:WORD           ; FAR variable in far data%@AE@%%@NL@%
  8307. %@NL@%
  8308.   %@AS@%            .CODE%@AE@%%@NL@%
  8309.   %@AS@%            .STARTUP%@AE@%%@NL@%
  8310.   %@AS@%            EXTRN   task:PROC           ; PROC or NEAR in near code%@AE@%%@NL@%
  8311.   %@AS@%            ASSUME  es:SEG fvar         ; Tell assembler%@AE@%%@NL@%
  8312.   %@AS@%            mov     ax,SEG fvar         ; Tell processor that ES%@AE@%%@NL@%
  8313.   %@AS@%            mov     es,ax               ;   has far data segment%@AE@%%@NL@%
  8314. %@NL@%
  8315.   %@AS@%            .%@AE@%%@NL@%
  8316.   %@AS@%            .%@AE@%%@NL@%
  8317.   %@AS@%            .%@AE@%%@NL@%
  8318.   %@AS@%            mov     ah,nvar             ; Load external NEAR variable%@AE@%%@NL@%
  8319.   %@AS@%            mov     bx,fvar             ; Load external FAR variable%@AE@%%@NL@%
  8320.   %@AS@%            mov     cx,max              ; Load external constant%@AE@%%@NL@%
  8321.   %@AS@%            call    task                ; Call procedure (NEAR or FAR)%@AE@%%@NL@%
  8322.   %@AS@%            jmp     act                 ; Jump to FAR label%@AE@%%@NL@%
  8323.   %@AS@%            END%@AE@%%@NL@%
  8324. %@NL@%
  8325. %@4@%  The example above shows how each type of external symbol could be declared%@EH@%
  8326.   and used in a small-model program that uses simplified segment directives.
  8327.   Notice the use of the %@AB@%PROC%@AE@% type specifier to make the external-procedure
  8328.   memory model independent. The jump and its external declaration are
  8329.   written so that they will be %@AB@%FAR%@AE@% regardless of the memory model. Using
  8330.   these techniques, you can change the memory model without breaking code.%@NL@%
  8331. %@NL@%
  8332. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  8333. %@NL@%
  8334.   %@AS@%            EXTRN   max:ABS,act:FAR     ; Constant or FAR label anywhere%@AE@%%@NL@%
  8335.   %@AS@%STACK       SEGMENT PARA STACK 'STACK'%@AE@%%@NL@%
  8336.   %@AS@%            DB      100h DUP (?)%@AE@%%@NL@%
  8337.   %@AS@%STACK       ENDS%@AE@%%@NL@%
  8338.   %@AS@%_DATA       SEGMENT WORD PUBLIC 'DATA'%@AE@%%@NL@%
  8339.   %@AS@%            EXTRN   nvar:BYTE           ; NEAR variable in near data%@AE@%%@NL@%
  8340.   %@AS@%_DATA       ENDS%@AE@%%@NL@%
  8341.   %@AS@%FAR_DATA    SEGMENT PARA 'FAR_DATA'%@AE@%%@NL@%
  8342.   %@AS@%            EXTRN   fvar:WORD           ; FAR variable in far data%@AE@%%@NL@%
  8343.   %@AS@%FAR_DATA    ENDS%@AE@%%@NL@%
  8344. %@NL@%
  8345.   %@AS@%DGROUP      GROUP   _DATA,STACK%@AE@%%@NL@%
  8346.   %@AS@%_TEXT       SEGMENT BYTE PUBLIC 'CODE'%@AE@%%@NL@%
  8347.   %@AS@%            EXTRN   task:NEAR           ; NEAR procedure in near code%@AE@%%@NL@%
  8348.   %@AS@%            ASSUME  cs:_TEXT,ds:DGROUP,ss:STACK%@AE@%%@NL@%
  8349.   %@AS@%start:      mov     ax,DGROUP           ; Load segment%@AE@%%@NL@%
  8350.   %@AS@%            mov     ds,ax               ;   into DS%@AE@%%@NL@%
  8351.   %@AS@%            ASSUME  es:SEG fvar         ; Tell assembler%@AE@%%@NL@%
  8352.   %@AS@%            mov     ax,SEG fvar         ; Tell processor that ES%@AE@%%@NL@%
  8353.   %@AS@%            mov     es,ax               ;   has far data segment%@AE@%%@NL@%
  8354.   %@AS@%            .%@AE@%%@NL@%
  8355.   %@AS@%            .%@AE@%%@NL@%
  8356.   %@AS@%            .%@AE@%%@NL@%
  8357.   %@AS@%            mov     ah,nvar             ; Load external NEAR variable%@AE@%%@NL@%
  8358.   %@AS@%            mov     bx,fvar             ; Load external FAR variable%@AE@%%@NL@%
  8359.   %@AS@%            mov     cx,max              ; Load external constant%@AE@%%@NL@%
  8360.   %@AS@%            call    task                ; Call NEAR procedure%@AE@%%@NL@%
  8361.   %@AS@%            jmp     act                 ; Jump to FAR label%@AE@%%@NL@%
  8362.   %@AS@%_TEXT       ENDS%@AE@%%@NL@%
  8363.   %@AS@%            END     start%@AE@%%@NL@%
  8364. %@NL@%
  8365. %@4@%  Example 2 shows a fragment similar to the one in Example 1, but with full%@EH@%
  8366.   segment definitions. Notice that the types of code labels must be declared
  8367.   specifically. If you wanted to change the memory model, you would have to
  8368.   specifically change each external declaration and each call or jump.%@NL@%
  8369. %@NL@%
  8370. %@NL@%
  8371. %@2@%%@CR:SC8.3       @%%@AB@%8.3  Using Multiple Modules%@AE@%%@EH@%%@NL@%
  8372. %@NL@%
  8373. %@4@%%@CR:IX8.48      @%%@CR:IX8.49      @%%@CR:IX8.50      @%  The following source files illustrate a program that uses public and%@EH@%
  8374.   external declarations to access instruction labels. The program consists
  8375.   of two modules called %@AS@%hello %@AE@%and %@AS@%display%@AE@%.%@NL@%
  8376. %@NL@%
  8377. %@4@%  The %@AS@%hello %@AE@%module is the program's initializing module. Execution starts at%@EH@%
  8378.   the instruction labeled %@AS@%start %@AE@%in the %@AS@%hello %@AE@%module. After initializing the
  8379.   data segment, the program calls the procedure %@AS@%display %@AE@%in the %@AS@%display%@AE@%
  8380.   module, where a DOS call is used to display a message on the screen.
  8381.   Execution then returns to the address after the call in the %@AS@%hello %@AE@%module.%@NL@%
  8382. %@NL@%
  8383. %@4@%  The %@AS@%hello %@AE@%module is shown below:%@EH@%%@NL@%
  8384. %@NL@%
  8385.   %@AS@%            TITLE   hello%@AE@%%@NL@%
  8386.   %@AS@%            DOSSEG%@AE@%%@NL@%
  8387.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  8388.   %@AS@%            .STACK  256%@AE@%%@NL@%
  8389. %@NL@%
  8390.   %@AS@%            .DATA%@AE@%%@NL@%
  8391.   %@AS@%            PUBLIC  message, lmessage%@AE@%%@NL@%
  8392.   %@AS@%message     DB      "Hello, world.",13,10%@AE@%%@NL@%
  8393.   %@AS@%lmessage    EQU     $ - message%@AE@%%@NL@%
  8394. %@NL@%
  8395.   %@AS@%            .CODE%@AE@%%@NL@%
  8396.   %@AS@%            EXTRN   display:PROC       ; Declare in near code segment%@AE@%%@NL@%
  8397.   %@AS@%            .STARTUP%@AE@%%@NL@%
  8398.   %@AS@%            call    display            ; Call other module%@AE@%%@NL@%
  8399.   %@AS@%            mov     ax,04C00h          ; Terminate with exit code 0%@AE@%%@NL@%
  8400.   %@AS@%            int     21h                ; Call DOS%@AE@%%@NL@%
  8401.   %@AS@%            END%@AE@%%@NL@%
  8402. %@NL@%
  8403. %@4@%  The %@AS@%display %@AE@%module is shown below:%@EH@%%@NL@%
  8404. %@NL@%
  8405.   %@AS@%            TITLE   display%@AE@%%@NL@%
  8406.   %@AS@%            EXTRN   lmessage:ABS       ; Declare anywhere%@AE@%%@NL@%
  8407.   %@AS@%            .MODEL  small%@AE@%%@NL@%
  8408.   %@AS@%            .DATA%@AE@%%@NL@%
  8409.   %@AS@%            EXTRN   message:BYTE       ; Declare in near data segment%@AE@%%@NL@%
  8410. %@NL@%
  8411.   %@AS@%            .CODE%@AE@%%@NL@%
  8412.   %@AS@%display     PROC%@AE@%%@NL@%
  8413.   %@AS@%            mov     bx,1               ; File handle for standard output%@AE@%%@NL@%
  8414.   %@AS@%            mov     cx,lmessage        ; Message length%@AE@%%@NL@%
  8415.   %@AS@%            mov     dx,OFFSET message  ; Message address%@AE@%%@NL@%
  8416.   %@AS@%            mov     ah,40h             ; Write function%@AE@%%@NL@%
  8417.   %@AS@%            int     21h                ; Call DOS%@AE@%%@NL@%
  8418.   %@AS@%            ret%@AE@%%@NL@%
  8419. %@NL@%
  8420.   %@AS@%display     ENDP%@AE@%%@NL@%
  8421.   %@AS@%            END%@AE@%%@NL@%
  8422. %@NL@%
  8423. %@4@%  The sample program is a variation of the HELLO.ASM program used in the%@EH@%
  8424.   examples in Chapter 4%@BO:       34dba@%, "Writing Stand-Alone Assembly Programs," except
  8425.   that it uses an external procedure to display to the screen. Notice that
  8426.   all symbols defined in one module but used in another are declared %@AB@%PUBLIC%@AE@%
  8427.   in the defining module and declared %@AB@%EXTRN%@AE@% in the using module.%@NL@%
  8428. %@NL@%
  8429. %@4@%  For instance, %@AS@%message %@AE@%and %@AS@%lmessage %@AE@%are declared %@AB@%PUBLIC%@AE@% in the program%@EH@%
  8430.   HELLO.ASM and declared %@AB@%EXTRN%@AE@% in DISPLAY.ASM. The procedure %@AS@%display %@AE@%is
  8431.   declared %@AB@%EXTRN%@AE@% in HELLO.ASM. The symbol display is automatically public in
  8432.   the simplified segment version, but you would have to specifically declare
  8433.   it %@AB@%PUBLIC%@AE@% if you used full segments.%@NL@%
  8434. %@NL@%
  8435. %@4@%  To create an executable file for these modules, you can add both files to%@EH@%
  8436.   the environment's Program List dialog box. You can also assemble the
  8437.   modules with the following command line:%@NL@%
  8438. %@NL@%
  8439.   %@AS@%QCL hello.asm display.asm%@AE@%%@NL@%
  8440. %@NL@%
  8441. %@4@%%@CR:IX8.51      @%%@CR:IX8.52      @%  The output is placed in the executable file HELLO.EXE.%@EH@%%@NL@%
  8442. %@NL@%
  8443. %@4@%  For each source module, QuickAssembler writes a module name to the object%@EH@%
  8444.   file. The module name is used by some debuggers and by the linker when it
  8445.   displays error messages. With QuickAssembler, the module name is always
  8446.   the base name of the source module file.%@NL@%
  8447. %@NL@%
  8448. %@4@%%@CR:IX8.53      @%  For compatibility, QuickAssembler recognizes the %@AB@%NAME%@AE@% directive. However,%@EH@%
  8449.   %@AB@%NAME%@AE@% has no effect. Arguments to the directive are ignored.%@NL@%
  8450. %@NL@%
  8451. %@NL@%
  8452. %@2@%%@CR:SC8.4       @%%@AB@%8.4  Declaring Symbols Communal%@AE@%%@EH@%%@NL@%
  8453. %@NL@%
  8454. %@4@%%@CR:IX8.54      @%%@CR:IX8.55      @%%@CR:IX8.56      @%%@CR:IX8.57      @%%@CR:IX8.58      @%  Communal variables are uninitialized variables that are both public and%@EH@%
  8455.   external. They are often declared in include files.%@NL@%
  8456. %@NL@%
  8457. %@4@%  If a variable must be used by several assembly routines, you can declare%@EH@%
  8458.   the variable communal in an include file, and then include the file in
  8459.   each of the assembly routines. Although the variable is declared in each
  8460.   source module, it exists at only one address. Using a communal variable in
  8461.   an include file and including it in several source modules is an
  8462.   alternative to defining the variable and declaring it public in one source
  8463.   module and then declaring it external in other modules.%@NL@%
  8464. %@NL@%
  8465. %@4@%  If a variable is declared communal in one module and public in another,%@EH@%
  8466.   the public declaration takes precedence and the communal declaration has
  8467.   the same effect as an external declaration.%@NL@%
  8468. %@NL@%
  8469. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8470. %@NL@%
  8471. %@4@%  %@AB@%COMM %@AE@%%@AI@%definition%@AE@%[[%@AB@%,%@AE@%%@AI@%definition%@AE@%]]...%@EH@%%@NL@%
  8472. %@NL@%
  8473. %@4@%  Each %@AI@%definition%@AE@% has the following syntax:%@EH@%%@NL@%
  8474. %@NL@%
  8475. %@4@%  [[%@AB@%NEAR%@AE@% | %@AB@%FAR%@AE@%]] [[%@AI@%lang%@AE@%]] %@AI@%label%@AE@%:%@AI@%size%@AE@%[[:%@AI@%count%@AE@%]]%@EH@%%@NL@%
  8476. %@NL@%
  8477. %@4@%  A communal variable can be %@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@%. If neither is specified, the type%@EH@%
  8478.   will be that of the default memory model. If you use simplified segment
  8479.   directives, the default type is %@AB@%NEAR%@AE@% for small and medium models, or %@AB@%FAR%@AE@%
  8480.   for compact, large, and huge models. If you use full segment definitions,
  8481.   the default type is %@AB@%NEAR%@AE@%.%@NL@%
  8482. %@NL@%
  8483. %@4@%%@CR:IX8.59      @%  The optional %@AI@%lang%@AE@% field can be %@AB@%C%@AE@%, %@AB@%BASIC%@AE@%, %@AB@%FORTRAN%@AE@%, or %@AB@%Pascal%@AE@%. The use of%@EH@%
  8484.   the %@AB@%C%@AE@% keyword turns on the C naming convention──the assembler prefixes the
  8485.   name of the variable with an underscore (_). The use of any of the other
  8486.   language types turns off the C naming convention, even if you specified %@AB@%C%@AE@%
  8487.   with the %@AB@%.MODEL%@AE@% directive. Note that the use of %@AB@%C%@AE@% does not preserve case.
  8488.   You must choose one of the assembler flags or options that preserve case.%@NL@%
  8489. %@NL@%
  8490. %@4@%  The %@AI@%label%@AE@% is the name of the variable. The %@AI@%size%@AE@% can be %@AB@%BYTE%@AE@%, %@AB@%WORD%@AE@%, %@AB@%DWORD%@AE@%,%@EH@%
  8491.   %@AB@%QWORD%@AE@%, %@AB@%TBYTE%@AE@%, or the name of a structure. The %@AI@%count%@AE@% is the number of
  8492.   elements. If no %@AI@%count%@AE@% is given, one element is assumed. Multiple variables
  8493.   can be defined with one %@AB@%COMM%@AE@% statement by separating each definition with
  8494.   a comma.%@NL@%
  8495. %@NL@%
  8496.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8497.   %@AB@%NOTE%@AE@%  C variables declared outside functions (except static variables) are
  8498.   communal unless explicitly initialized; they are the same as
  8499.   assembly-language communal variables. If you are writing assembly-language
  8500.   modules for C, you can declare the same communal variables in C include
  8501.   files and in QuickAssembler include files.%@NL@%
  8502.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8503. %@NL@%
  8504. %@4@%  QuickAssembler cannot tell whether a communal variable has been used in%@EH@%
  8505.   another module. Allocation of communal variables is handled by LINK. As a
  8506.   result, communal variables have the following limitations that other
  8507.   variables declared in assembly language do not have:%@NL@%
  8508. %@NL@%
  8509.   ■  Communal variables cannot be initialized. Under DOS, initial values are
  8510.      not guaranteed to be 0 or any other value. The variables can be used
  8511.      for data, such as file buffers, that is not given a value until run
  8512.      time.%@NL@%
  8513. %@NL@%
  8514.   ■  Communal variables are not guaranteed to be allocated in the sequence
  8515.      in which they are declared. Assembly-language techniques that depend on
  8516.      the sequence and position in which data is defined should not be used
  8517.      with communal variables. For example, the following statements do not
  8518.      work:%@NL@%
  8519. %@NL@%
  8520. %@NL@%
  8521.      %@AS@%            COMM    wbuffer:WORD:128%@AE@%%@NL@%
  8522.      %@AS@%lbuffer     EQU     $ - buffer        ; "lbuffer" won't have desired value%@AE@%%@NL@%
  8523. %@NL@%
  8524.      %@AS@%bbuffer     LABEL   BYTE              ; "bbuffer" won't have desired address%@AE@%%@NL@%
  8525.      %@AS@%            COMM    wbuffer:WORD:40%@AE@%%@NL@%
  8526. %@NL@%
  8527.   ■  If a communal variable references a variable that is allocated and
  8528.      declared public inside a module, the variable has the segment of the
  8529.      allocated instance. If all references to the variable are communal, the
  8530.      variable will be placed in one of the segments described below.%@NL@%
  8531. %@NL@%
  8532. %@CR:IX8.60      @%     Near communal variables are placed in a segment called c_common, which
  8533.      is part of DGROUP. This group is created and initialized automatically
  8534.      if you use simplified segment directives. If you use full segment
  8535.      definitions, you must create a group called DGROUP and use the %@AB@%ASSUME%@AE@%
  8536.      directive to associate it with the DS register.%@NL@%
  8537. %@NL@%
  8538. %@CR:IX8.61      @%%@CR:IX8.62      @%     Far communal variables are placed in a segment called FAR_BSS. This
  8539.      segment has combine type private and class type 'FAR_BSS'. This means
  8540.      that multiple segments with the same name can be created. Such segments
  8541.      cannot be accessed by name. They must be initialized indirectly using
  8542.      the %@AB@%SEG%@AE@% operator. For example, if a far communal variable (with word
  8543.      size) is called %@AS@%comvar%@AE@%, its segment can be initialized with the
  8544.      following lines:%@NL@%
  8545. %@NL@%
  8546.   %@AS@%            ASSUME  ds:SEG comvar      ; Tell the assembler%@AE@%%@NL@%
  8547.   %@AS@%            mov     ax,SEG comvar      ; Tell the processor%@AE@%%@NL@%
  8548.   %@AS@%            mov     ds,ax%@AE@%%@NL@%
  8549.   %@AS@%            mov     bx,comvar          ; Use the variable%@AE@%%@NL@%
  8550. %@NL@%
  8551. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  8552. %@NL@%
  8553.   %@AS@%            .DATA%@AE@%%@NL@%
  8554.   %@AS@%            COMM    temp:BYTE:128%@AE@%%@NL@%
  8555. %@NL@%
  8556.   %@AS@%ASCIIZ      MACRO   address         ;; Name of address for string%@AE@%%@NL@%
  8557.   %@AS@%            mov     temp,128        ;; Insert maximum length%@AE@%%@NL@%
  8558.   %@AS@%            mov     dx,OFFSET temp  ;; Address of string buffer%@AE@%%@NL@%
  8559.   %@AS@%            mov     ah,0Ah          ;; Get string%@AE@%%@NL@%
  8560.   %@AS@%            int     21h%@AE@%%@NL@%
  8561.   %@AS@%            mov     dl,temp[1]      ;; Get length of string%@AE@%%@NL@%
  8562.   %@AS@%            xor     dh,dh%@AE@%%@NL@%
  8563.   %@AS@%            mov     bx,dx%@AE@%%@NL@%
  8564.   %@AS@%            mov     temp[bx+2],0    ;; Overwrite CR with null%@AE@%%@NL@%
  8565.   %@AS@%address     EQU     OFFSET temp+2%@AE@%%@NL@%
  8566.   %@AS@%            ENDM%@AE@%%@NL@%
  8567. %@NL@%
  8568. %@4@%  Example 1 shows an include file that declares a buffer for temporary data.%@EH@%
  8569.   The buffer is then used in a macro in the same include file. An example of
  8570.   how the macro could be used in a source file is shown below:%@NL@%
  8571. %@NL@%
  8572.   %@AS@%            DOSSEG%@AE@%%@NL@%
  8573.   %@AS@%            .MODEL  small,c%@AE@%%@NL@%
  8574.   %@AS@%            INCLUDE communal.inc%@AE@%%@NL@%
  8575.   %@AS@%            .STACK%@AE@%%@NL@%
  8576.   %@AS@%            .DATA%@AE@%%@NL@%
  8577.   %@AS@%message     DB      "Enter file name: $"%@AE@%%@NL@%
  8578.   %@AS@%            .CODE%@AE@%%@NL@%
  8579.   %@AS@%            .STARTUP%@AE@%%@NL@%
  8580.   %@AS@%            .%@AE@%%@NL@%
  8581.   %@AS@%            .%@AE@%%@NL@%
  8582.   %@AS@%            .%@AE@%%@NL@%
  8583. %@NL@%
  8584.   %@AS@%            mov     dx,OFFSET message      ; Load offset of file prompt%@AE@%%@NL@%
  8585.   %@AS@%            mov     ah,09h                 ; Display prompt%@AE@%%@NL@%
  8586.   %@AS@%            int     21h%@AE@%%@NL@%
  8587. %@NL@%
  8588.   %@AS@%            ASCIIZ  place                  ; Get file name and%@AE@%%@NL@%
  8589.   %@AS@%                                           ;   return address as "place"%@AE@%%@NL@%
  8590. %@NL@%
  8591.   %@AS@%            mov     al,00000010b           ; Load access code%@AE@%%@NL@%
  8592.   %@AS@%            mov     dx,place               ; Load address of ASCIIZ string%@AE@%%@NL@%
  8593.   %@AS@%            mov     ah,3Dh                 ; Open the file%@AE@%%@NL@%
  8594.   %@AS@%            int     21h%@AE@%%@NL@%
  8595.   %@AS@%            .%@AE@%%@NL@%
  8596.   %@AS@%            .%@AE@%%@NL@%
  8597.   %@AS@%            .%@AE@%%@NL@%
  8598. %@NL@%
  8599. %@4@%  Note that once the macro is written, the user does not need to know the%@EH@%
  8600.   name of the temporary buffer or how it is used in the macro.%@NL@%
  8601. %@NL@%
  8602. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  8603. %@NL@%
  8604.   %@AS@%date        STRUC%@AE@%%@NL@%
  8605. %@NL@%
  8606.   %@AS@%  month     DB   ?%@AE@%%@NL@%
  8607.   %@AS@%  day       DB   ?%@AE@%%@NL@%
  8608.   %@AS@%  year      DB   ?%@AE@%%@NL@%
  8609. %@NL@%
  8610.   %@AS@%date        ENDS%@AE@%%@NL@%
  8611. %@NL@%
  8612.   %@AS@%            .DATA%@AE@%%@NL@%
  8613.   %@AS@%            COMM   today:date%@AE@%%@NL@%
  8614.   %@AS@%            .%@AE@%%@NL@%
  8615.   %@AS@%            .%@AE@%%@NL@%
  8616.   %@AS@%            .%@AE@%%@NL@%
  8617. %@NL@%
  8618. %@4@%  The example above uses the %@AB@%COMM%@AE@% directive to make the structure variable%@EH@%
  8619.   %@AS@%today %@AE@%a communal variable.%@NL@%
  8620. %@NL@%
  8621. %@NL@%
  8622. %@2@%%@CR:SC8.5       @%%@AB@%8.5  Specifying Library Files%@AE@%%@EH@%%@NL@%
  8623. %@NL@%
  8624. %@4@%%@CR:IX8.63      @%%@CR:IX8.64      @%%@CR:IX8.65      @%%@CR:IX8.66      @%  The %@AB@%INCLUDELIB%@AE@% directive instructs the linker to link with a specified%@EH@%
  8625.   library file. If you are writing a program that calls library routines,
  8626.   you can use this directive to specify the library file in the assembly
  8627.   source file rather than in the LINK command line.%@NL@%
  8628. %@NL@%
  8629. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8630. %@NL@%
  8631. %@4@%  %@AB@%INCLUDELIB%@AE@% %@AI@%libraryname%@AE@%%@EH@%%@NL@%
  8632. %@NL@%
  8633. %@4@%  The %@AI@%libraryname%@AE@% is written to the comment record of the object file. The%@EH@%
  8634.   Intel title for this record is %@AB@%COMENT%@AE@%. At link time, the linker reads this
  8635.   record and links with the specified library file.%@NL@%
  8636. %@NL@%
  8637. %@4@%  The %@AI@%libraryname%@AE@% must be a file name rather than a complete file%@EH@%
  8638.   specification. If you do not specify an extension, the default extension
  8639.   .LIB is assumed. LINK searches directories for the library file in the
  8640.   following order:%@NL@%
  8641. %@NL@%
  8642.   1. The current directory%@NL@%
  8643. %@NL@%
  8644.   2. Any directories given in the library field of the LINK command line%@NL@%
  8645. %@NL@%
  8646.   3. Any directories listed in the LIB environment variable%@NL@%
  8647. %@NL@%
  8648. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  8649. %@NL@%
  8650.   %@AS@%            INCLUDELIB graphics%@AE@%%@NL@%
  8651. %@NL@%
  8652. %@4@%  This statement passes a message from QuickAssembler telling LINK to use%@EH@%
  8653.   library routines from the file GRAPHICS.LIB. If this statement is included
  8654.   in a source file called DRAW.ASM, the program might be linked with the
  8655.   following command line:%@NL@%
  8656. %@NL@%
  8657.   %@AS@%LINK draw;%@AE@%%@NL@%
  8658. %@NL@%
  8659. %@4@%  Without the %@AB@%INCLUDELIB%@AE@% directive, the program would have to be linked with%@EH@%
  8660.   the following command line:%@NL@%
  8661. %@NL@%
  8662.   %@AS@%LINK draw,,,graphics;%@AE@%%@NL@%
  8663. %@NL@%
  8664. %@NL@%
  8665. %@NL@%
  8666. ────────────────────────────────────────────────────────────────────────────%@NL@%
  8667. %@1@%%@CR:CH9         @%%@AB@%Chapter 9:  Using Operands and Expressions%@AE@%%@EH@%%@NL@%
  8668. %@NL@%
  8669. %@NL@%
  8670. %@4@%%@CR:IX9.1       @%%@CR:IX9.2       @%  Operands are the arguments that define values to be acted on by%@EH@%
  8671.   instructions or directives. Operands can be constants, variables,
  8672.   expressions, or keywords, depending on the instruction or directive and
  8673.   the context of the statement.%@NL@%
  8674. %@NL@%
  8675. %@4@%%@CR:IX9.3       @%  A common type of operand is an expression. An expression consists of%@EH@%
  8676.   several operands that are combined to describe a value or memory location.
  8677.   Operators indicate the operations to be performed when combining the
  8678.   operands of an expression.%@NL@%
  8679. %@NL@%
  8680. %@4@%  Expressions are evaluated at assembly time. By using expressions, you can%@EH@%
  8681.   instruct the assembler to calculate values that would be difficult or
  8682.   inconvenient to calculate when you are writing source code.%@NL@%
  8683. %@NL@%
  8684. %@4@%  This chapter discusses operands, expressions, and operators as they are%@EH@%
  8685.   evaluated at assembly time. See Section 2.6%@BO:       2404d@%, "Addressing Modes," for a
  8686.   discussion of the addressing modes that can be used to calculate operand
  8687.   values at run time. This chapter also discusses the location-counter
  8688.   operand, forward references, and strong typing of operands.%@NL@%
  8689. %@NL@%
  8690. %@NL@%
  8691. %@2@%%@CR:SC9.1       @%%@AB@%9.1  Using Operands with Directives%@AE@%%@EH@%%@NL@%
  8692. %@NL@%
  8693. %@4@%  Each directive requires a specific type of operand. Most directives take%@EH@%
  8694.   string or numeric constants, or symbols or expressions that evaluate to
  8695.   such constants.%@NL@%
  8696. %@NL@%
  8697. %@4@%  The type of operand varies for each directive, but the operand must always%@EH@%
  8698.   evaluate to a value that is known at assembly time. This differs from
  8699.   instructions, whose operands may not be known at assembly time and may
  8700.   vary at run time. Operands used with instructions are discussed in Section
  8701.   2.6%@BO:       2404d@%, "Addressing Modes."%@NL@%
  8702. %@NL@%
  8703. %@4@%  Some directives, such as those used in data declarations, accept labels or%@EH@%
  8704.   variables as operands. When a symbol that refers to a memory location is
  8705.   used as an operand to a directive, the symbol represents the address of
  8706.   the symbol rather than its contents. This is because the contents may
  8707.   change at run time and are therefore not known at assembly time.%@NL@%
  8708. %@NL@%
  8709. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  8710. %@NL@%
  8711.   %@AS@%            ORG     100h               ; Set address to 100h%@AE@%%@NL@%
  8712.   %@AS@%var         DB      10h                ; Address of "var" is 100h%@AE@%%@NL@%
  8713.   %@AS@%                                       ; Value of "var" is 10h%@AE@%%@NL@%
  8714.   %@AS@%pvar        DW      var                ; Address of "pvar" is 101h%@AE@%%@NL@%
  8715.   %@AS@%                                       ; Value of "pvar" is%@AE@%%@NL@%
  8716.   %@AS@%                                       ;   address of "var" (100h)%@AE@%%@NL@%
  8717. %@NL@%
  8718. %@4@%  In Example 1, the operand of the %@AB@%DW%@AE@% directive in the third statement%@EH@%
  8719.   represents the address of %@AS@%var %@AE@%(%@AS@%100h%@AE@%) rather than its contents (%@AS@%10h%@AE@%). The
  8720.   address is relative to the start of the segment in which%@AS@% var%@AE@% is defined.%@NL@%
  8721. %@NL@%
  8722. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  8723. %@NL@%
  8724.   %@AS@%            TITLE   doit               ; String%@AE@%%@NL@%
  8725.   %@AS@%_TEXT       SEGMENT BYTE PUBLIC 'CODE' ; Key words%@AE@%%@NL@%
  8726.   %@AS@%            INCLUDE \include\bios.inc  ; Pathname%@AE@%%@NL@%
  8727.   %@AS@%            .RADIX  16                 ; Numeric constant%@AE@%%@NL@%
  8728.   %@AS@%tst         DW      a / b              ; Numeric expression%@AE@%%@NL@%
  8729.   %@AS@%            PAGE    +                  ; Special character%@AE@%%@NL@%
  8730.   %@AS@%sum         EQU     x * y              ; Numeric expression%@AE@%%@NL@%
  8731.   %@AS@%here        LABEL   WORD               ; Type specifier%@AE@%%@NL@%
  8732. %@NL@%
  8733. %@4@%  Example 2 illustrates the different kinds of values that can be used as%@EH@%
  8734.   directive operands.%@NL@%
  8735. %@NL@%
  8736. %@NL@%
  8737. %@2@%%@CR:SC9.2       @%%@AB@%9.2  Using Operators%@AE@%%@EH@%%@NL@%
  8738. %@NL@%
  8739. %@4@%  The assembler provides a variety of operators for combining, comparing,%@EH@%
  8740.   changing, or analyzing operands. Some operators work with integer
  8741.   constants, some with memory values, and some with both. Operators cannot
  8742.   be used with floating-point constants since QuickAssembler%@AB@% %@AE@%does not
  8743.   recognize real numbers in expressions.%@NL@%
  8744. %@NL@%
  8745. %@4@%  It is important to understand the difference between operators and%@EH@%
  8746.   instructions. Operators handle calculations of constant values that are
  8747.   known at assembly time. Instructions handle calculations of values that
  8748.   may not be known until run time. For example, the addition operator (%@AB@%+%@AE@%)
  8749.   handles assembly-time addition, while the %@AB@%ADD %@AE@%and %@AB@%ADC%@AE@% instructions handle
  8750.   run-time addition.%@NL@%
  8751. %@NL@%
  8752. %@4@%  This section describes the different kinds of operators used in%@EH@%
  8753.   assembly-language statements and gives examples of expressions formed with
  8754.   them. In addition to the operators described in this chapter, you can use
  8755.   the %@AB@%DUP%@AE@% operator (Section 6.5.2%@BO:       65365@%, "Arrays and Buffers"), the record
  8756.   operators (Section 7.2.4%@BO:       6f341@%, "Record Operators"), and the macro operators
  8757.   (Section 11.4%@BO:       982dc@%, "Using Macro Operators").%@NL@%
  8758. %@NL@%
  8759. %@NL@%
  8760. %@3@%%@CR:SC9.2.1     @%%@AB@%9.2.1  Calculation Operators%@AE@%%@EH@%%@NL@%
  8761. %@NL@%
  8762. %@4@%%@CR:IX9.4       @%  QuickAssembler provides the common arithmetic operators as well as several%@EH@%
  8763.   other operators for adding, shifting, or doing bit manipulations. The
  8764.   sections below describe operators that can be used for doing numeric
  8765.   calculations.%@NL@%
  8766. %@NL@%
  8767. %@NL@%
  8768. %@3@%%@CR:SC9.2.1.1   @%%@AB@%9.2.1.1  Arithmetic Operators%@AE@%%@EH@%%@NL@%
  8769. %@NL@%
  8770. %@4@%%@CR:IX9.5       @%%@CR:IX9.6       @%  QuickAssembler recognizes a variety of arithmetic operators for common%@EH@%
  8771.   mathematical operations. Table 9.1 lists the arithmetic operators.%@NL@%
  8772. %@NL@%
  8773.   %@AB@%Table 9.1 Arithmetic Operators%@AE@%%@NL@%
  8774. %@NL@%
  8775.   %@AB@%Operator%@AE@%      %@AB@%Syntax%@AE@%                        %@AB@%Meaning%@AE@%%@NL@%
  8776.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8777.   %@AB@%+%@AE@%             %@AB@%+%@AE@%%@AI@%expression%@AE@%                   Positive (unary)%@NL@%
  8778. %@NL@%
  8779.   %@AB@%-%@AE@%             %@AB@%-%@AE@%%@AI@%expression%@AE@%                   Negative (unary)%@NL@%
  8780. %@NL@%
  8781.   %@AB@%*%@AE@%             %@AI@%expression1%@AE@%%@AB@% * %@AE@%%@AI@%expression2%@AE@%     Multiplication%@NL@%
  8782. %@NL@%
  8783.   %@AB@%/%@AE@%             %@AI@%expression1%@AE@%%@AB@% / %@AE@%%@AI@%expression2%@AE@%     Integer division%@NL@%
  8784. %@NL@%
  8785.   %@AB@%MOD%@AE@%           %@AI@%expression1%@AE@% %@AB@%MOD%@AE@% %@AI@%expression2%@AE@%   Remainder (modulus)%@NL@%
  8786. %@NL@%
  8787.   %@AB@%+%@AE@%             %@AI@%expression1%@AE@%%@AB@% + %@AE@%%@AI@%expression2%@AE@%     Addition%@NL@%
  8788. %@NL@%
  8789.   %@AB@%-%@AE@%             %@AI@%expression1%@AE@%%@AB@% - %@AE@%%@AI@%expression2%@AE@%     Subtraction%@NL@%
  8790. %@NL@%
  8791.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8792. %@NL@%
  8793. %@NL@%
  8794. %@4@%  For all arithmetic operators except the addition operator (%@AB@%+%@AE@%) and the%@EH@%
  8795.   subtraction operator (%@AB@%-%@AE@%), the expressions operated on must be integer
  8796.   constants.%@NL@%
  8797. %@NL@%
  8798. %@4@%  The addition and subtraction operators can be used to add or subtract an%@EH@%
  8799.   integer constant and a memory operand. The result can be used as a memory
  8800.   operand.%@NL@%
  8801. %@NL@%
  8802. %@4@%  The subtraction operator can also be used to subtract one memory operand%@EH@%
  8803.   from another, but only if the operands refer to locations within the same
  8804.   segment. The result will be a constant, not a memory operand.%@NL@%
  8805. %@NL@%
  8806.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8807.   %@AB@%NOTE%@AE@%  The unary plus and minus operators (used to designate positive or
  8808.   negative numbers) are not the same as the binary plus and minus operators
  8809.   (used to designate addition or subtraction). The unary plus and minus
  8810.   operators have a higher level of precedence, as described in Section
  8811.   9.2.5%@BO:       83028@%, "Operator Precedence."%@NL@%
  8812.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8813. %@NL@%
  8814. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  8815. %@NL@%
  8816.   %@AS@%intgr       =       14  *  3           ; = 42%@AE@%%@NL@%
  8817.   %@AS@%intgr       =       intgr /  4         ; 42 / 4 = 10%@AE@%%@NL@%
  8818.   %@AS@%intgr       =       intgr  MOD  4      ; 10 mod 4 = 2%@AE@%%@NL@%
  8819.   %@AS@%intgr       =       intgr +  4         ; 2 + 4 = 6%@AE@%%@NL@%
  8820.   %@AS@%intgr       =       intgr -  3         ; 6 - 3 = 3%@AE@%%@NL@%
  8821.   %@AS@%intgr       =       -intgr - 8         ; -3 - 8 = -11%@AE@%%@NL@%
  8822.   %@AS@%intgr       =       -intgr - intgr     ; 11 - -11 = 22%@AE@%%@NL@%
  8823. %@NL@%
  8824. %@4@%  Example 1 illustrates arithmetic operators used in integer expressions.%@EH@%%@NL@%
  8825. %@NL@%
  8826. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  8827. %@NL@%
  8828.   %@AS@%            ORG     100h%@AE@%%@NL@%
  8829.   %@AS@%a           DB      ?                  ; Address is 100h%@AE@%%@NL@%
  8830.   %@AS@%b           DB      ?                  ; Address is 101h%@AE@%%@NL@%
  8831.   %@AS@%mem1        EQU     a + 5              ; mem1 = 100h + 5 = 105h%@AE@%%@NL@%
  8832.   %@AS@%mem2        EQU     a - 5              ; mem2 = 100h - 5 = 0FBh%@AE@%%@NL@%
  8833.   %@AS@%const       EQU     b - a              ; const = 101h - 100h = 1%@AE@%%@NL@%
  8834. %@NL@%
  8835. %@4@%  Example 2 illustrates arithmetic operators used in memory expressions.%@EH@%%@NL@%
  8836. %@NL@%
  8837. %@NL@%
  8838. %@3@%%@CR:SC9.2.1.2   @%%@AB@%9.2.1.2  Structure-Field-Name Operator%@AE@%%@EH@%%@NL@%
  8839. %@NL@%
  8840. %@4@%%@CR:IX9.7       @%%@CR:IX9.8       @%  The structure-field-name operator (%@AB@%.%@AE@%) indicates addition. It is used to%@EH@%
  8841.   designate a field within a structure.%@NL@%
  8842. %@NL@%
  8843. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8844. %@NL@%
  8845. %@4@%  %@AI@%variable%@AE@%%@AB@%.%@AE@%%@AI@%field%@AE@%%@EH@%%@NL@%
  8846. %@NL@%
  8847. %@4@%  The %@AI@%variable%@AE@% is a memory operand (usually a previously declared structure%@EH@%
  8848.   variable), and %@AI@%field%@AE@% is the name of a field within the structure. See
  8849.   Section 7.1%@BO:       69ad4@%, "Structures," for more information.%@NL@%
  8850. %@NL@%
  8851. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  8852. %@NL@%
  8853.   %@AS@%            .DATA%@AE@%%@NL@%
  8854.   %@AS@%date        STRUC                      ; Declare structure%@AE@%%@NL@%
  8855.   %@AS@%  month     DB      ?%@AE@%%@NL@%
  8856.   %@AS@%  day       DB      ?%@AE@%%@NL@%
  8857.   %@AS@%  year      DW      ?%@AE@%%@NL@%
  8858.   %@AS@%date        ENDS%@AE@%%@NL@%
  8859.   %@AS@%yesterday   date    <12,31,1987>       ; Define structure variables%@AE@%%@NL@%
  8860.   %@AS@%today       date    <1,1,1988>%@AE@%%@NL@%
  8861. %@NL@%
  8862.   %@AS@%            .CODE%@AE@%%@NL@%
  8863.   %@AS@%            .%@AE@%%@NL@%
  8864.   %@AS@%            .%@AE@%%@NL@%
  8865.   %@AS@%            .%@AE@%%@NL@%
  8866.   %@AS@%            mov     bh,yesterday.day   ; Load structure variable%@AE@%%@NL@%
  8867.   %@AS@%            mov     bx,OFFSET today    ; Load structure variable address%@AE@%%@NL@%
  8868.   %@AS@%            inc     [bx].year          ; Use in indirect memory operand%@AE@%%@NL@%
  8869. %@NL@%
  8870. %@NL@%
  8871. %@3@%%@CR:SC9.2.1.3   @%%@AB@%9.2.1.3  Index Operator%@AE@%%@EH@%%@NL@%
  8872. %@NL@%
  8873. %@4@%%@CR:IX9.9       @%%@CR:IX9.10      @%%@CR:IX9.11      @%%@CR:IX9.12      @%  The index operator (%@AB@%[ ]%@AE@%) indicates addition. It is similar to the addition%@EH@%
  8874.   (%@AB@%+%@AE@%) operator. When used with a register, the index operator also indicates
  8875.   that the operand is an indirect memory operand rather than a
  8876.   register-direct operand.%@NL@%
  8877. %@NL@%
  8878. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8879. %@NL@%
  8880. %@4@%  [[%@AI@%expression1%@AE@%]][%@AI@%expression2%@AE@%]%@EH@%%@NL@%
  8881. %@NL@%
  8882. %@4@%  In most cases %@AI@%expression1%@AE@% is simply added to %@AI@%expression2%@AE@%. The limitations%@EH@%
  8883.   of the addition operator for adding memory operands also apply to the
  8884.   index operator. For example, two direct memory operands cannot be added.
  8885.   The expression %@AS@%label1[label2]%@AE@% is illegal if both are memory operands.%@NL@%
  8886. %@NL@%
  8887. %@4@%  The index operator has an extended function in specifying indirect memory%@EH@%
  8888.   operands. Section 2.6.4%@BO:       27375@% explains the use of indirect memory operands. The
  8889.   index brackets must be outside the register or registers that specify the
  8890.   indirect displacement. However, any of the three operators that indicate
  8891.   addition (the addition operator, the index operator, or the
  8892.   structure-field-name operator) may be used for multiple additions within
  8893.   the expression.%@NL@%
  8894. %@NL@%
  8895. %@4@%  For example, the following statements are equivalent:%@EH@%%@NL@%
  8896. %@NL@%
  8897.   %@AS@%           mov     ax,table[bx][di]%@AE@%%@NL@%
  8898.   %@AS@%           mov     ax,table[bx+di]%@AE@%%@NL@%
  8899.   %@AS@%           mov     ax,[table+bx+di]%@AE@%%@NL@%
  8900.   %@AS@%           mov     ax,[table][bx][di]%@AE@%%@NL@%
  8901. %@NL@%
  8902. %@4@%  The following statements are illegal because the index operator does not%@EH@%
  8903.   enclose the registers that specify indirect displacement:%@NL@%
  8904. %@NL@%
  8905.   %@AS@%            mov     ax,table+bx+di     ; Illegal - no index operator%@AE@%%@NL@%
  8906.   %@AS@%            mov     ax,[table]+bx+di   ; Illegal - registers not%@AE@%%@NL@%
  8907.   %@AS@%                                       ;   inside index operator%@AE@%%@NL@%
  8908. %@NL@%
  8909. %@4@%  The index operator is typically used to index elements of a data object,%@EH@%
  8910.   such as variables in an array or characters in a string.%@NL@%
  8911. %@NL@%
  8912. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  8913. %@NL@%
  8914.   %@AS@%            mov     al,string[3]       ; Get 4th element of string%@AE@%%@NL@%
  8915.   %@AS@%            add     ax,array[4]        ; Add 5th element of array%@AE@%%@NL@%
  8916.   %@AS@%            mov     string[7],al       ; Load into 8th element of string%@AE@%%@NL@%
  8917. %@NL@%
  8918. %@4@%  Example 1 illustrates the index operator used with direct memory operands.%@EH@%%@NL@%
  8919. %@NL@%
  8920. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  8921. %@NL@%
  8922.   %@AS@%            mov     ax,[bx]            ; Get element BX points to%@AE@%%@NL@%
  8923.   %@AS@%            add     ax,array[si]       ; Add element SI points to%@AE@%%@NL@%
  8924.   %@AS@%            mov     string[di],al      ; Load element DI points to%@AE@%%@NL@%
  8925.   %@AS@%            cmp     cx,table[bx][di]   ; Compare to element BX and DI point to%@AE@%%@NL@%
  8926. %@NL@%
  8927. %@4@%  Example 2 illustrates the index operator used with indirect memory%@EH@%
  8928.   operands.%@NL@%
  8929. %@NL@%
  8930. %@NL@%
  8931. %@3@%%@CR:SC9.2.1.4   @%%@AB@%9.2.1.4  Shift Operators%@AE@%%@EH@%%@NL@%
  8932. %@NL@%
  8933. %@4@%%@CR:IX9.13      @%%@CR:IX9.14      @%%@CR:IX9.15      @%%@CR:IX9.16      @%%@CR:IX9.17      @%%@CR:IX9.18      @%  The %@AB@%SHR%@AE@% and %@AB@%SHL%@AE@% operators can be used to shift bits in constant values.%@EH@%
  8934.   Both perform logical shifts. Bits on the right for %@AB@%SHL%@AE@% and on the left for
  8935.   %@AB@%SHR%@AE@% are zero-filled as their contents are shifted out of position.%@NL@%
  8936. %@NL@%
  8937. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  8938. %@NL@%
  8939. %@4@%  %@AI@%expression%@AE@% %@AB@%SHR%@AE@% %@AI@%count%@AE@%%@EH@%%@NL@%
  8940.   %@AI@%expression%@AE@% %@AB@%SHL%@AE@% %@AI@%count%@AE@%%@NL@%
  8941. %@NL@%
  8942. %@4@%  The %@AI@%expression%@AE@% is shifted right or left by %@AI@%count%@AE@% number of bits. Bits%@EH@%
  8943.   shifted off either end of the expression are lost. If %@AI@%count%@AE@% is greater
  8944.   than or equal to 16, the result is 0.%@NL@%
  8945. %@NL@%
  8946. %@4@%  Do not confuse the %@AB@%SHR%@AE@% and %@AB@%SHL%@AE@% operators with the processor instructions%@EH@%
  8947.   having the same names. The operators work on integer constants only at
  8948.   assembly time. The processor instructions work on register or memory
  8949.   values at run time. The assembler can tell the difference between
  8950.   instructions and operands from context.%@NL@%
  8951. %@NL@%
  8952. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  8953. %@NL@%
  8954.   %@AS@%mov     ax,01110111b SHL 3 ; Load 01110111000b%@AE@%%@NL@%
  8955.   %@AS@%mov     ah,01110111b SHR 3 ; Load 01110b%@AE@%%@NL@%
  8956. %@NL@%
  8957. %@NL@%
  8958. %@3@%%@CR:SC9.2.1.5   @%%@AB@%9.2.1.5  Bitwise Logical Operators%@AE@%%@EH@%%@NL@%
  8959. %@CR:IX9.19      @%%@CR:IX9.20      @%%@CR:IX9.21      @%%@CR:IX9.22      @%%@CR:IX9.23      @%%@CR:IX9.24      @%%@CR:IX9.25      @%%@NL@%
  8960. %@4@%%@CR:IX9.26      @%%@CR:IX9.27      @%%@CR:IX9.28      @%%@CR:IX9.29      @%%@CR:IX9.30      @%  The bitwise operators perform logical operations on each bit of an%@EH@%
  8961.   expression. The expressions must resolve to constant values. Table 9.2
  8962.   lists the logical operators and their meanings.%@NL@%
  8963. %@NL@%
  8964.   %@AB@%Table 9.2 Logical Operators%@AE@%%@NL@%
  8965. %@NL@%
  8966.   %@AB@%Operator%@AE@%      %@AB@%Syntax%@AE@%                        %@AB@%Meaning%@AE@%%@NL@%
  8967.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8968.   %@AB@%NOT%@AE@%           %@AB@%NOT%@AE@% %@AI@%expression%@AE@%                Bitwise complement%@NL@%
  8969. %@NL@%
  8970.   %@AB@%AND%@AE@%           %@AI@%expression1%@AE@% %@AB@%AND%@AE@% %@AI@%expression2%@AE@%   Bitwise %@AB@%AND%@AE@%%@NL@%
  8971. %@NL@%
  8972.   %@AB@%OR%@AE@%            %@AI@%expression1%@AE@%%@AB@% OR%@AE@% %@AI@%expression2%@AE@%    Bitwise inclusive %@AB@%OR%@AE@%%@NL@%
  8973. %@NL@%
  8974.   %@AB@%XOR%@AE@%           %@AI@%expression1%@AE@%%@AB@% XOR%@AE@% %@AI@%expression2%@AE@%   Bitwise exclusive %@AB@%XOR%@AE@%%@NL@%
  8975. %@NL@%
  8976.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8977. %@NL@%
  8978. %@NL@%
  8979. %@4@%  Do not confuse the %@AB@%NOT%@AE@%, %@AB@%AND%@AE@%, %@AB@%OR%@AE@%, and %@AB@%XOR%@AE@% operators with the processor%@EH@%
  8980.   instructions having the same names. The operators work on integer
  8981.   constants only at assembly time. The processor instructions work on
  8982.   register or memory values at run time. The assembler can tell the
  8983.   difference between instructions and operands from context.%@NL@%
  8984. %@NL@%
  8985.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8986.   %@AB@%NOTE%@AE@%  Although calculations on expressions using the %@AB@%AND%@AE@%, %@AB@%OR,%@AE@% and %@AB@%XOR%@AE@%
  8987.   operators are done using 17-bit numbers, the results are truncated to 16
  8988.   bits.%@NL@%
  8989.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  8990. %@NL@%
  8991. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  8992. %@NL@%
  8993.   %@AS@%     mov     ax,NOT 11110000b            ; Load 1111111100001111b%@AE@%%@NL@%
  8994.   %@AS@%     mov     ah,NOT 11110000b            ; Load 00001111b%@AE@%%@NL@%
  8995.   %@AS@%     mov     ah,01010101b AND 11110000b  ; Load 01010000b%@AE@%%@NL@%
  8996.   %@AS@%     mov     ah,01010101b OR  11110000b  ; Load 11110101b%@AE@%%@NL@%
  8997.   %@AS@%     mov     ah,01010101b XOR 11110000b  ; Load 10100101b%@AE@%%@NL@%
  8998. %@NL@%
  8999. %@NL@%
  9000. %@3@%%@CR:SC9.2.2     @%%@AB@%9.2.2  Relational Operators%@AE@%%@EH@%%@NL@%
  9001. %@CR:IX9.31      @%%@CR:IX9.32      @%%@CR:IX9.33      @%%@CR:IX9.34      @%%@CR:IX9.35      @%%@CR:IX9.36      @%%@CR:IX9.37      @%%@CR:IX9.38      @%%@CR:IX9.39      @%%@CR:IX9.40      @%%@NL@%
  9002. %@4@%%@CR:IX9.41      @%%@CR:IX9.42      @%%@CR:IX9.43      @%%@CR:IX9.44      @%%@CR:IX9.45      @%%@CR:IX9.46      @%  The relational operators compare two expressions and return true (-1) if%@EH@%
  9003.   the condition specified by the operator is satisfied, or false (0) if it
  9004.   is not. The expressions must resolve to constant values. Relational
  9005.   operators are typically used with conditional directives. Table 9.3 lists
  9006.   the operators and the values they return if the specified condition is
  9007.   satisfied.%@NL@%
  9008. %@NL@%
  9009.   %@AB@%Table 9.3 Relational Operators%@AE@%%@NL@%
  9010. %@NL@%
  9011.   %@AB@%Operator%@AE@%      %@AB@%Syntax%@AE@%                        %@AB@%Returned Value%@AE@%%@NL@%
  9012.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9013.   %@AB@%EQ%@AE@%            %@AI@%expression1%@AE@% %@AB@%EQ%@AE@% %@AI@%expression2%@AE@%    True if expressions are equal%@NL@%
  9014. %@NL@%
  9015.   %@AB@%NE%@AE@%            %@AI@%expression1%@AE@% %@AB@%NE%@AE@% %@AI@%expression2%@AE@%    True if expressions are not
  9016.                                               equal%@NL@%
  9017. %@NL@%
  9018.   %@AB@%LT%@AE@%            %@AI@%expression1%@AE@% %@AB@%LT%@AE@% %@AI@%expression2%@AE@%    True if left expression is
  9019.                                               less than right%@NL@%
  9020. %@NL@%
  9021.   %@AB@%LE%@AE@%            %@AI@%expression1%@AE@% %@AB@%LE%@AE@% %@AI@%expression2%@AE@%    True if left expression is
  9022.                                               less than or equal to right%@NL@%
  9023. %@NL@%
  9024.   %@AB@%GT%@AE@%            %@AI@%expression1%@AE@% %@AB@%GT%@AE@% %@AI@%expression2%@AE@%    True if left expression is
  9025.                                               greater than right%@NL@%
  9026. %@NL@%
  9027.   %@AB@%GE%@AE@%            %@AI@%expression1%@AE@% %@AB@%GE%@AE@% %@AI@%expression2%@AE@%    True if left expression is
  9028.                                               greater than or equal to right%@NL@%
  9029. %@NL@%
  9030.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9031. %@NL@%
  9032. %@NL@%
  9033. %@4@%  Note that the %@AB@%EQ%@AE@% and %@AB@%NE%@AE@% operators treat their arguments as 16-bit numbers.%@EH@%
  9034.   Numbers specified with the 16th bit set are considered negative. For
  9035.   example, the expression %@AS@%-1 EQ OFFFFh %@AE@%is true, but the expression %@AS@%-1 NE%@AE@%
  9036.   %@AS@%OFFFFh %@AE@%is false.%@NL@%
  9037. %@NL@%
  9038. %@4@%  The %@AB@%LT%@AE@%, %@AB@%LE%@AE@%, %@AB@%GT%@AE@%, and %@AB@%GE%@AE@% operators treat their arguments as 17-bit numbers,%@EH@%
  9039.   in which the 17th bit specifies the sign. For example, %@AS@%OFFFFh %@AE@%is 65,535,
  9040.   not -1. The expression %@AS@%1 GT -1 %@AE@%is true, but the expression %@AS@%1 GT OFFFFh %@AE@%is
  9041.   false.%@NL@%
  9042. %@NL@%
  9043. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  9044. %@NL@%
  9045.   %@AS@%        mov     ax,4 EQ 3  ; Load false( 0)%@AE@%%@NL@%
  9046.   %@AS@%        mov     ax,4 NE 3  ; Load true  (-1)%@AE@%%@NL@%
  9047.   %@AS@%        mov     ax,4 LT 3  ; Load false( 0)%@AE@%%@NL@%
  9048.   %@AS@%        mov     ax,4 LE 3  ; Load false( 0)%@AE@%%@NL@%
  9049.   %@AS@%        mov     ax,4 GT 3  ; Load true (-1)%@AE@%%@NL@%
  9050.   %@AS@%        mov     ax,4 GE 3  ; Load true(-1)%@AE@%%@NL@%
  9051. %@NL@%
  9052. %@NL@%
  9053. %@3@%%@CR:SC9.2.3     @%%@AB@%9.2.3  Segment-Override Operator%@AE@%%@EH@%%@NL@%
  9054. %@NL@%
  9055. %@4@%%@CR:IX9.47      @%%@CR:IX9.48      @%%@CR:IX9.49      @%%@CR:IX9.50      @%%@CR:IX9.51      @%%@CR:IX9.52      @%%@CR:IX9.53      @%%@CR:IX9.54      @%%@CR:IX9.55      @%  The segment-override operator (%@AB@%:%@AE@%) forces the address of a variable or%@EH@%
  9056.   label to be computed relative to a specific segment.%@NL@%
  9057. %@NL@%
  9058. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9059. %@NL@%
  9060. %@4@%  %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%expression%@AE@%%@EH@%%@NL@%
  9061. %@NL@%
  9062. %@4@%  The %@AI@%segment%@AE@% can be specified in several ways. It can be one of the segment%@EH@%
  9063.   registers: CS,%@AB@% %@AE@%DS,%@AB@% %@AE@%SS, or%@AB@% %@AE@%ES. It can also be a segment or group name. In
  9064.   this case, the name must have been previously defined with a %@AB@%SEGMENT%@AE@% or
  9065.   %@AB@%GROUP%@AE@% directive and assigned to a segment register with an %@AB@%ASSUME%@AE@%
  9066.   directive. The %@AI@%expression%@AE@% can be a constant, expression, or a %@AB@%SEG%@AE@%
  9067.   expression. See Section 9.2.4.5%@BO:       80576@% for more information on the %@AB@%SEG%@AE@% operator.%@NL@%
  9068. %@NL@%
  9069. %@4@%  Note that when a segment override is given with an indexed operand, the%@EH@%
  9070.   segment must be specified outside the index operators. For example,
  9071.   %@AS@%es:[di] %@AE@%is correct, but %@AS@%[es:di] %@AE@%generates an error.%@NL@%
  9072. %@NL@%
  9073. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  9074. %@NL@%
  9075.   %@AS@%            mov     ax,ss:[bx+4]       ; Override default assume (DS)%@AE@%%@NL@%
  9076.   %@AS@%            mov     al,es:082h         ; Load from ES%@AE@%%@NL@%
  9077. %@NL@%
  9078.   %@AS@%            ASSUME  ds:FAR_DATA        ; Tell the assembler and%@AE@%%@NL@%
  9079.   %@AS@%            mov     bx,FAR_DATA:count  ;   load from a far segment%@AE@%%@NL@%
  9080. %@NL@%
  9081. %@4@%  As shown in the last two statements, a segment override with a segment%@EH@%
  9082.   name is not enough if no segment register is assumed for the segment name.
  9083.   You must use the %@AB@%ASSUME%@AE@% directive to assign a segment register, as
  9084.   explained in Section 5.4%@BO:       52503@%, "Associating Segments with Registers."%@NL@%
  9085. %@NL@%
  9086. %@NL@%
  9087. %@3@%%@CR:SC9.2.4     @%%@AB@%9.2.4  Type Operators%@AE@%%@EH@%%@NL@%
  9088. %@NL@%
  9089. %@4@%%@CR:IX9.56      @%  This section describes the assembler operators that specify or analyze the%@EH@%
  9090.   types of memory operands and other expressions.%@NL@%
  9091. %@NL@%
  9092. %@NL@%
  9093. %@3@%%@CR:SC9.2.4.1   @%%@AB@%9.2.4.1  PTR Operator%@AE@%%@EH@%%@NL@%
  9094. %@NL@%
  9095. %@4@%%@CR:IX9.57      @%%@CR:IX9.58      @%  The %@AB@%PTR%@AE@% operator specifies the type for a variable or label.%@EH@%%@NL@%
  9096. %@NL@%
  9097. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9098. %@NL@%
  9099. %@4@%  %@AI@%type%@AE@% %@AB@%PTR%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  9100. %@NL@%
  9101. %@4@%  The operator forces %@AI@%expression%@AE@% to be treated as having %@AI@%type%@AE@%. The%@EH@%
  9102.   expression can be any operand. The type can be %@AB@%BYTE%@AE@%, %@AB@%WORD%@AE@%, %@AB@%DWORD%@AE@%, %@AB@%QWORD%@AE@%,
  9103.   or %@AB@%TBYTE%@AE@% for memory operands. It can be %@AB@%NEAR%@AE@%, %@AB@%FAR%@AE@%, or %@AB@%PROC%@AE@% for labels.%@NL@%
  9104. %@NL@%
  9105. %@4@%  The %@AB@%PTR%@AE@% operator is typically used with forward references to define%@EH@%
  9106.   explicitly what size or distance a reference has. If it is not used, the
  9107.   assembler assumes a default size or distance for the reference. See
  9108.   Section 9.4%@BO:       84253@% for more information on forward references.%@NL@%
  9109. %@NL@%
  9110. %@4@%  The %@AB@%PTR%@AE@% operator is also used to enable instructions to access variables%@EH@%
  9111.   in ways that would otherwise generate errors. For example, you could use
  9112.   the %@AB@%PTR%@AE@% operator to access the high-order byte of a %@AB@%WORD%@AE@% size variable.
  9113.   The %@AB@%PTR%@AE@% operator is required for %@AB@%FAR%@AE@% calls and jumps to forward-referenced
  9114.   labels.%@NL@%
  9115. %@NL@%
  9116. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  9117. %@NL@%
  9118.   %@AS@%            .DATA%@AE@%%@NL@%
  9119.   %@AS@%stuff       DD      ?%@AE@%%@NL@%
  9120.   %@AS@%buffer      DB      20 DUP (?)%@AE@%%@NL@%
  9121. %@NL@%
  9122.   %@AS@%            .CODE%@AE@%%@NL@%
  9123.   %@AS@%            .%@AE@%%@NL@%
  9124.   %@AS@%            .%@AE@%%@NL@%
  9125.   %@AS@%            .%@AE@%%@NL@%
  9126.   %@AS@%            call    FAR PTR task            ; Call a far procedure%@AE@%%@NL@%
  9127.   %@AS@%            jmp     FAR PTR place           ; Jump far%@AE@%%@NL@%
  9128. %@NL@%
  9129.   %@AS@%            mov     bx,WORD PTR stuff[0]    ; Load a word from a%@AE@%%@NL@%
  9130.   %@AS@%                                            ;   doubleword variable%@AE@%%@NL@%
  9131.   %@AS@%            add     ax,WORD PTR buffer[bx]  ; Add a word from a byte variable%@AE@%%@NL@%
  9132. %@NL@%
  9133. %@4@%  The %@AB@%PTR%@AE@% operator can be used to specify the size of an indirect register%@EH@%
  9134.   operand for a %@AB@%CALL%@AE@% or %@AB@%JMP%@AE@% instruction. However, the size cannot be
  9135.   specified with %@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@%. Use %@AB@%WORD%@AE@% or %@AB@%DWORD%@AE@% instead. Examples are shown
  9136.   below:%@NL@%
  9137. %@NL@%
  9138. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  9139. %@NL@%
  9140.   %@AS@%          jmp     WORD PTR [bx]           ; Legal near jump%@AE@%%@NL@%
  9141.   %@AS@%          call    NEAR PTR [bx]           ; Illegal near call%@AE@%%@NL@%
  9142.   %@AS@%          call    DWORD PTR [bx]          ; Legal far call%@AE@%%@NL@%
  9143.   %@AS@%          jmp     FAR PTR [bx]            ; Illegal far jump%@AE@%%@NL@%
  9144. %@NL@%
  9145. %@4@%  This limitation only applies to indirect register operands. %@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@%%@EH@%
  9146.   can be applied to operands associated with labels, as shown in Example 1.
  9147.   Furthermore, use %@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@% with an indirect operand that combines a
  9148.   register with a label.%@NL@%
  9149. %@NL@%
  9150. %@NL@%
  9151. %@3@%%@CR:SC9.2.4.2   @%%@AB@%9.2.4.2  SHORT Operator%@AE@%%@EH@%%@NL@%
  9152. %@NL@%
  9153. %@4@%%@CR:IX9.59      @%%@CR:IX9.60      @%  The %@AB@%SHORT%@AE@% operator sets the type of a specified label to %@AB@%SHORT%@AE@%. Short%@EH@%
  9154.   labels can be used in %@AB@%JMP%@AE@% instructions whenever the distance from the
  9155.   label to the instruction is less than 128 bytes.%@NL@%
  9156. %@NL@%
  9157. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9158. %@NL@%
  9159. %@4@%  %@AB@%SHORT%@AE@% %@AI@%label%@AE@%%@EH@%%@NL@%
  9160. %@NL@%
  9161. %@4@%  Instructions using short labels are a byte smaller than identical%@EH@%
  9162.   instructions using the default near labels. See Section 9.4.1%@BO:       845be@%, "Forward
  9163.   References to Labels," for information on using the %@AB@%SHORT%@AE@% operator with
  9164.   jump instructions.%@NL@%
  9165. %@NL@%
  9166. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9167. %@NL@%
  9168.   %@AS@%            jmp     again              ; Jump 128 bytes or more%@AE@%%@NL@%
  9169.   %@AS@%            .%@AE@%%@NL@%
  9170.   %@AS@%            .%@AE@%%@NL@%
  9171.   %@AS@%            .%@AE@%%@NL@%
  9172.   %@AS@%            jmp     SHORT again        ; Jump less than 128 bytes%@AE@%%@NL@%
  9173.   %@AS@%            .%@AE@%%@NL@%
  9174.   %@AS@%            .%@AE@%%@NL@%
  9175.   %@AS@%            .%@AE@%%@NL@%
  9176.   %@AS@%again:%@AE@%%@NL@%
  9177. %@NL@%
  9178. %@NL@%
  9179. %@3@%%@CR:SC9.2.4.3   @%%@AB@%9.2.4.3  THIS Operator%@AE@%%@EH@%%@NL@%
  9180. %@NL@%
  9181. %@4@%%@CR:IX9.61      @%%@CR:IX9.62      @%  The %@AB@%THIS%@AE@% operator creates an operand whose offset and segment values are%@EH@%
  9182.   equal to the current location-counter value and whose type is specified by
  9183.   the operator.%@NL@%
  9184. %@NL@%
  9185. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9186. %@NL@%
  9187. %@4@%  %@AB@%THIS%@AE@% %@AI@%type%@AE@%%@EH@%%@NL@%
  9188. %@NL@%
  9189. %@4@%  The %@AI@%type%@AE@% can be %@AB@%BYTE%@AE@%, %@AB@%WORD%@AE@%, %@AB@%DWORD%@AE@%, %@AB@%QWORD%@AE@%, or %@AB@%TBYTE%@AE@% for memory operands. It%@EH@%
  9190.   can be %@AB@%NEAR%@AE@%, %@AB@%FAR%@AE@%, or %@AB@%PROC%@AE@% for labels.%@NL@%
  9191. %@NL@%
  9192. %@4@%  The %@AB@%THIS%@AE@% operator is typically used with the %@AB@%EQU%@AE@% or equal-sign (%@AB@%=%@AE@%)%@EH@%
  9193.   directive to create labels and variables. The result is similar to using
  9194.   the %@AB@%LABEL%@AE@% directive.%@NL@%
  9195. %@NL@%
  9196. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9197. %@NL@%
  9198.   %@AS@%tag1        EQU     THIS BYTE  ; Both represent the same variable%@AE@%%@NL@%
  9199.   %@AS@%tag2        LABEL   BYTE%@AE@%%@NL@%
  9200. %@NL@%
  9201.   %@AS@%check1      EQU     THIS NEAR  ; All represent the same address%@AE@%%@NL@%
  9202.   %@AS@%check2      LABEL   NEAR%@AE@%%@NL@%
  9203.   %@AS@%check3:%@AE@%%@NL@%
  9204.   %@AS@%check4      PROC    NEAR%@AE@%%@NL@%
  9205.   %@AS@%check4      ENDP%@AE@%%@NL@%
  9206. %@NL@%
  9207. %@NL@%
  9208. %@3@%%@CR:SC9.2.4.4   @%%@AB@%9.2.4.4  HIGH and LOW Operators%@AE@%%@EH@%%@NL@%
  9209. %@NL@%
  9210. %@4@%%@CR:IX9.63      @%%@CR:IX9.64      @%%@CR:IX9.65      @%%@CR:IX9.66      @%  The %@AB@%HIGH%@AE@% and %@AB@%LOW%@AE@% operators return the high and low bytes, respectively, of%@EH@%
  9211.   an expression.%@NL@%
  9212. %@NL@%
  9213. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9214. %@NL@%
  9215. %@4@%  %@AB@%HIGH%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  9216.   %@AB@%LOW%@AE@% %@AI@%expression%@AE@%%@NL@%
  9217. %@NL@%
  9218. %@4@%  The %@AB@%HIGH%@AE@% operator returns the high-order eight bits of %@AI@%expression%@AE@%; the %@AB@%LOW%@AE@%%@EH@%
  9219.   operator returns the low-order eight bits. The expression must evaluate to
  9220.   a constant. You cannot use the %@AB@%HIGH%@AE@% and %@AB@%LOW%@AE@% operators on the contents of a
  9221.   memory operand since the contents may change at run time.%@NL@%
  9222. %@NL@%
  9223. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  9224. %@NL@%
  9225.   %@AS@%stuff       EQU     0ABCDh%@AE@%%@NL@%
  9226.   %@AS@%            mov     ah,HIGH stuff      ; Load 0ABh%@AE@%%@NL@%
  9227.   %@AS@%            mov     al,LOW stuff       ; Load 0CDh%@AE@%%@NL@%
  9228. %@NL@%
  9229. %@4@%  The %@AB@%HIGH%@AE@% and %@AB@%LOW%@AE@% operators work reliably only with constants and with%@EH@%
  9230.   offsets to external symbols. %@AB@%HIGH%@AE@% and %@AB@%LOW%@AE@% operations are not supported for
  9231.   offsets to local symbols.%@NL@%
  9232. %@NL@%
  9233. %@NL@%
  9234. %@3@%%@CR:SC9.2.4.5   @%%@AB@%9.2.4.5  SEG Operator%@AE@%%@EH@%%@NL@%
  9235. %@NL@%
  9236. %@4@%%@CR:IX9.67      @%%@CR:IX9.68      @%  The %@AB@%SEG%@AE@% operator returns the segment address of an expression.%@EH@%%@NL@%
  9237. %@NL@%
  9238. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9239. %@NL@%
  9240. %@4@%  %@AB@%SEG%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  9241. %@NL@%
  9242. %@4@%  The %@AI@%expression%@AE@% can be any label, variable, segment name, group name, or%@EH@%
  9243.   other memory operand. The %@AB@%SEG%@AE@% operator cannot be used with constant
  9244.   expressions. The returned value can be used as a memory operand.%@NL@%
  9245. %@NL@%
  9246. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9247. %@NL@%
  9248.   %@AS@%            .DATA%@AE@%%@NL@%
  9249.   %@AS@%var         DB      ?%@AE@%%@NL@%
  9250.   %@AS@%            .CODE%@AE@%%@NL@%
  9251.   %@AS@%            .%@AE@%%@NL@%
  9252.   %@AS@%            .%@AE@%%@NL@%
  9253.   %@AS@%            .%@AE@%%@NL@%
  9254.   %@AS@%            ASSUME  ds:SEG var         ; Assume segment of variable%@AE@%%@NL@%
  9255.   %@AS@%            mov     ax,SEG var         ; Get address of segment%@AE@%%@NL@%
  9256.   %@AS@%            mov     ds,ax              ;   where variable is declared%@AE@%%@NL@%
  9257. %@NL@%
  9258. %@NL@%
  9259. %@3@%%@CR:SC9.2.4.6   @%%@AB@%9.2.4.6  OFFSET Operator%@AE@%%@EH@%%@NL@%
  9260. %@NL@%
  9261. %@4@%%@CR:IX9.69      @%%@CR:IX9.70      @%  The %@AB@%OFFSET%@AE@% operator returns the offset address of an expression.%@EH@%%@NL@%
  9262. %@NL@%
  9263. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9264. %@NL@%
  9265. %@4@%  %@AB@%OFFSET%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  9266. %@NL@%
  9267. %@4@%  The %@AI@%expression%@AE@% can be any label, variable, or other direct memory operand.%@EH@%
  9268.   Constant expressions return meaningless values. The value returned by the
  9269.   %@AB@%OFFSET%@AE@% operand is an immediate (constant) operand.%@NL@%
  9270. %@NL@%
  9271. %@4@%  If the %@AB@%MODEL%@AE@% directive is used, the value returned by the %@AB@%OFFSET%@AE@% operator%@EH@%
  9272.   is relative to a group, whenever the data item is declared in a segment
  9273.   that is part of a group. The %@AB@%OFFSET%@AE@% operator returns the number of bytes
  9274.   between the beginning of the group and the data object. If the object is
  9275.   declared in a segment not part of a group, %@AB@%OFFSET%@AE@% returns the number of
  9276.   bytes between the beginning of the segment and the data object.%@NL@%
  9277. %@NL@%
  9278. %@4@%  If the %@AB@%MODEL%@AE@% directive is not used, %@AB@%OFFSET%@AE@% returns a value relative to the%@EH@%
  9279.   beginning of the segment, regardless of whether the segment is part of a
  9280.   group.%@NL@%
  9281. %@NL@%
  9282. %@4@%  If full segment definitions are given, the returned value is a memory%@EH@%
  9283.   operand equal to the number of bytes between the item and the beginning of
  9284.   the segment in which it is defined.%@NL@%
  9285. %@NL@%
  9286. %@4@%%@CR:IX9.71      @%%@CR:IX9.72      @%  The segment-override operator (%@AB@%:%@AE@%) can be used to force %@AB@%OFFSET%@AE@% to return%@EH@%
  9287.   the number of bytes between the item in %@AI@%expression%@AE@% and the beginning of a
  9288.   named segment or group. This is the method used to generate valid offsets
  9289.   for items in a group when full segment definitions are used. For example,
  9290.   the statement%@NL@%
  9291. %@NL@%
  9292.   %@AS@%            mov     bx,OFFSET DGROUP:array%@AE@%%@NL@%
  9293. %@NL@%
  9294. %@4@%  is not the same as%@EH@%%@NL@%
  9295. %@NL@%
  9296.   %@AS@%            mov     bx,OFFSET array%@AE@%%@NL@%
  9297. %@NL@%
  9298. %@4@%  if %@AS@%array %@AE@%is not in the first segment in %@AS@%DGROUP%@AE@%.%@EH@%%@NL@%
  9299. %@NL@%
  9300. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9301. %@NL@%
  9302.   %@AS@%            .DATA%@AE@%%@NL@%
  9303.   %@AS@%string      DB      "This is it."%@AE@%%@NL@%
  9304.   %@AS@%            .CODE%@AE@%%@NL@%
  9305.   %@AS@%            .%@AE@%%@NL@%
  9306.   %@AS@%            .%@AE@%%@NL@%
  9307.   %@AS@%            .%@AE@%%@NL@%
  9308.   %@AS@%            mov     dx,OFFSET string   ; Load offset of variable%@AE@%%@NL@%
  9309. %@NL@%
  9310. %@NL@%
  9311. %@3@%%@CR:SC9.2.4.7   @%%@AB@%9.2.4.7  .TYPE Operator%@AE@%%@EH@%%@NL@%
  9312. %@NL@%
  9313. %@4@%%@CR:IX9.73      @%%@CR:IX9.74      @%  The %@AB@%.TYPE%@AE@% operator returns a byte that defines the mode and scope of an%@EH@%
  9314.   expression.%@NL@%
  9315. %@NL@%
  9316. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9317. %@NL@%
  9318. %@4@%  %@AB@%.TYPE%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  9319. %@NL@%
  9320. %@4@%  If %@AI@%expression%@AE@% is not valid, %@AB@%.TYPE%@AE@% returns 0. Otherwise, %@AB@%.TYPE%@AE@% returns a%@EH@%
  9321.   byte having the bit setting shown in Table 9.4. The %@AB@%.%@AE@%TYPE operator sets
  9322.   all bits except bit 6. Future versions of the assembler may reserve a use
  9323.   for this bit.%@NL@%
  9324. %@NL@%
  9325.   %@AB@%Table 9.4 .TYPE Operator and Variable Attributes%@AE@%%@NL@%
  9326. %@NL@%
  9327.   %@AB@%Bit Position%@AE@%  %@AB@%If Bit = 0%@AE@%                    %@AB@%If Bit = 1%@AE@%%@NL@%
  9328.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9329.   0             Not program related           Program related%@NL@%
  9330. %@NL@%
  9331.   1             Not data related              Data related%@NL@%
  9332. %@NL@%
  9333.   2             Not a constant value          Constant value%@NL@%
  9334. %@NL@%
  9335.   3             Addressing mode is not direct Addressing mode is direct%@NL@%
  9336. %@NL@%
  9337.   4             Not a register                Expression is a register%@NL@%
  9338. %@NL@%
  9339.   5             Not defined                   Defined%@NL@%
  9340. %@NL@%
  9341.   7             Local or public scope         External scope%@NL@%
  9342. %@NL@%
  9343.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9344. %@NL@%
  9345. %@NL@%
  9346. %@4@%  The %@AB@%.TYPE%@AE@% operator is typically used in macros in which different kinds of%@EH@%
  9347.   arguments may need to be handled differently.%@NL@%
  9348. %@NL@%
  9349. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9350. %@NL@%
  9351.   %@AS@%display     MACRO   string%@AE@%%@NL@%
  9352.   %@AS@%            IF      ((.TYPE string) SHL 14) NE 8000h%@AE@%%@NL@%
  9353.   %@AS@%            IF2%@AE@%%@NL@%
  9354.   %@AS@%            %OUT    Argument must be a variable%@AE@%%@NL@%
  9355.   %@AS@%            ENDIF%@AE@%%@NL@%
  9356.   %@AS@%            ENDIF%@AE@%%@NL@%
  9357.   %@AS@%            mov     dx,OFFSET string%@AE@%%@NL@%
  9358.   %@AS@%            mov     ah,09h%@AE@%%@NL@%
  9359.   %@AS@%            int     21h%@AE@%%@NL@%
  9360.   %@AS@%            ENDM%@AE@%%@NL@%
  9361. %@NL@%
  9362. %@4@%  This macro checks to see if the argument passed to it is data related (a%@EH@%
  9363.   variable). It does this by shifting all bits except the relevant bits (1
  9364.   and 0) to the left so that they can be checked. If the data bit is not
  9365.   set, an error message is generated.%@NL@%
  9366. %@NL@%
  9367. %@NL@%
  9368. %@3@%%@CR:SC9.2.4.8   @%%@AB@%9.2.4.8  TYPE Operator%@AE@%%@EH@%%@NL@%
  9369. %@NL@%
  9370. %@4@%%@CR:IX9.75      @%%@CR:IX9.76      @%  The %@AB@%TYPE%@AE@% operator returns a number that represents the type of an%@EH@%
  9371.   expression.%@NL@%
  9372. %@NL@%
  9373. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9374. %@NL@%
  9375. %@4@%  %@AB@%TYPE%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  9376. %@NL@%
  9377. %@4@%  If %@AI@%expression%@AE@% evaluates to a variable, the operator returns the number of%@EH@%
  9378.   bytes in each data object in the variable. Each byte in a string is
  9379.   considered a separate data object, so the %@AB@%TYPE%@AE@% operator returns 1 for
  9380.   strings.%@NL@%
  9381. %@NL@%
  9382. %@4@%  If %@AI@%expression%@AE@% evaluates to a structure or structure variable, the operator%@EH@%
  9383.   returns the number of bytes in the structure. If the expression is a
  9384.   label, the operator returns 0FFFFH for %@AB@%NEAR%@AE@% labels and 0FFFEH for %@AB@%FAR%@AE@%
  9385.   labels. If the expression is a constant, the operator returns 0.%@NL@%
  9386. %@NL@%
  9387. %@NL@%
  9388. %@3@%%@CR:SC9.2.4.9   @%%@AB@%9.2.4.9  LENGTH Operator%@AE@%%@EH@%%@NL@%
  9389. %@NL@%
  9390. %@4@%%@CR:IX9.77      @%%@CR:IX9.78      @%  The %@AB@%LENGTH%@AE@% operator returns the number of data elements in an array or%@EH@%
  9391.   other variable defined with the %@AB@%DUP%@AE@% operator.%@NL@%
  9392. %@NL@%
  9393. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9394. %@NL@%
  9395. %@4@%  %@AB@%LENGTH%@AE@% %@AI@%variable%@AE@%%@EH@%%@NL@%
  9396. %@NL@%
  9397. %@4@%  The returned value is the number of elements of the declared size in%@EH@%
  9398.   %@AI@%variable%@AE@%. If the variable was declared with nested %@AB@%DUP%@AE@% operators, only the
  9399.   value given for the outer %@AB@%DUP%@AE@% operator is returned. If the variable was
  9400.   not declared with the %@AB@%DUP%@AE@% operator, the value returned is always 1.%@NL@%
  9401. %@NL@%
  9402. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9403. %@NL@%
  9404.   %@AS@%array       DD      100 DUP(0FFFFFFh)%@AE@%%@NL@%
  9405.   %@AS@%table       DW      100 DUP(1,10 DUP(?))%@AE@%%@NL@%
  9406.   %@AS@%string      DB      'This is a string'%@AE@%%@NL@%
  9407.   %@AS@%var         DT      ?%@AE@%%@NL@%
  9408.   %@AS@%larray      EQU     LENGTH array       ; 100 - number of elements%@AE@%%@NL@%
  9409.   %@AS@%ltable      EQU     LENGTH table       ; 100 - inner DUP not counted%@AE@%%@NL@%
  9410.   %@AS@%lstring     EQU     LENGTH string      ; 1 - string is one element%@AE@%%@NL@%
  9411.   %@AS@%lvar        EQU     LENGTH var         ; 1%@AE@%%@NL@%
  9412.   %@AS@%            .%@AE@%%@NL@%
  9413.   %@AS@%            .%@AE@%%@NL@%
  9414.   %@AS@%            .%@AE@%%@NL@%
  9415.   %@AS@%            mov     cx,LENGTH array    ; Load number of elements%@AE@%%@NL@%
  9416.   %@AS@%again:      .                          ; Perform some operation on%@AE@%%@NL@%
  9417.   %@AS@%            .                          ;   each element%@AE@%%@NL@%
  9418.   %@AS@%            .%@AE@%%@NL@%
  9419.   %@AS@%            loop    again%@AE@%%@NL@%
  9420. %@NL@%
  9421. %@NL@%
  9422. %@3@%%@CR:SC9.2.4.10  @%%@AB@%9.2.4.10  SIZE Operator%@AE@%%@EH@%%@NL@%
  9423. %@NL@%
  9424. %@4@%%@CR:IX9.79      @%%@CR:IX9.80      @%  The %@AB@%SIZE%@AE@% operator returns the total number of bytes allocated for an array%@EH@%
  9425.   or other variable defined with the %@AB@%DUP%@AE@% operator.%@NL@%
  9426. %@NL@%
  9427. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9428. %@NL@%
  9429. %@4@%  %@AB@%SIZE%@AE@% %@AI@%variable%@AE@%%@EH@%%@NL@%
  9430. %@NL@%
  9431. %@4@%  The returned value is equal to the value of %@AB@%LENGTH%@AE@% %@AI@%variable%@AE@% times the%@EH@%
  9432.   value of %@AB@%TYPE%@AE@% %@AI@%variable%@AE@%. If the variable was declared with nested %@AB@%DUP%@AE@%
  9433.   operators, only the value given for the outside %@AB@%DUP%@AE@% operator is
  9434.   considered. If the variable was not declared with the %@AB@%DUP%@AE@% operator, the
  9435.   value returned is always %@AB@%TYPE%@AE@% %@AI@%variable%@AE@%.%@NL@%
  9436. %@NL@%
  9437. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9438. %@NL@%
  9439.   %@AS@%array       DD      100 DUP(1)%@AE@%%@NL@%
  9440.   %@AS@%table       DW      100 DUP(1,10 DUP(?))%@AE@%%@NL@%
  9441.   %@AS@%string      DB      'This is a string'%@AE@%%@NL@%
  9442.   %@AS@%var         DT      ?%@AE@%%@NL@%
  9443.   %@AS@%sarray      EQU     SIZE array         ; 400 - elements times size%@AE@%%@NL@%
  9444.   %@AS@%stable      EQU     SIZE table         ; 200 - inner DUP ignored%@AE@%%@NL@%
  9445.   %@AS@%sstring     EQU     SIZE string        ; 1 - string is one element%@AE@%%@NL@%
  9446.   %@AS@%svar        EQU     SIZE var           ; 10 - bytes in variable%@AE@%%@NL@%
  9447.   %@AS@%            .%@AE@%%@NL@%
  9448.   %@AS@%            .%@AE@%%@NL@%
  9449.   %@AS@%            .%@AE@%%@NL@%
  9450.   %@AS@%            mov     cx,SIZE array      ; Load number of bytes%@AE@%%@NL@%
  9451.   %@AS@%again:      .                          ; Perform some operation on%@AE@%%@NL@%
  9452.   %@AS@%            .                          ;   each byte%@AE@%%@NL@%
  9453.   %@AS@%            .%@AE@%%@NL@%
  9454.   %@AS@%            loop    again%@AE@%%@NL@%
  9455. %@NL@%
  9456. %@NL@%
  9457. %@3@%%@CR:SC9.2.5     @%%@AB@%9.2.5  Operator Precedence%@AE@%%@EH@%%@NL@%
  9458. %@NL@%
  9459. %@4@%%@CR:IX9.81      @%%@CR:IX9.82      @%  Expressions are evaluated according to the following rules:%@EH@%%@NL@%
  9460. %@NL@%
  9461.   ■  Operations of highest precedence are performed first.%@NL@%
  9462. %@NL@%
  9463.   ■  Operations of equal precedence are performed from left to right.%@NL@%
  9464. %@NL@%
  9465.   ■  The order of evaluation can be overridden by using parentheses.
  9466.      Operations in parentheses are always performed before any adjacent
  9467.      operations.%@NL@%
  9468. %@NL@%
  9469. %@4@%  The order of precedence for all operators is listed in Table 9.5.%@EH@%
  9470.   Operators on the same line have equal precedence.%@NL@%
  9471. %@NL@%
  9472.   %@AB@%Table 9.5 Operator Precedence%@AE@%%@NL@%
  9473. %@NL@%
  9474.   %@AB@%Precedence%@AE@%         %@AB@%Operators%@AE@%%@NL@%
  9475.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9476.   (Highest)%@NL@%
  9477. %@NL@%
  9478.   1                  %@AB@%LENGTH%@AE@%, %@AB@%SIZE%@AE@%, %@AB@%WIDTH%@AE@%, %@AB@%MASK%@AE@%, (), [],<>%@NL@%
  9479. %@NL@%
  9480.   2                  %@AB@%.%@AE@% (structure-field-name operator)%@NL@%
  9481. %@NL@%
  9482.   3                  %@AB@%:%@AE@%%@NL@%
  9483. %@NL@%
  9484.   4                  %@AB@%PTR%@AE@%, %@AB@%OFFSET%@AE@%, %@AB@%SEG%@AE@%, %@AB@%TYPE%@AE@%, %@AB@%THIS%@AE@%%@NL@%
  9485. %@NL@%
  9486.   5                  %@AB@%HIGH%@AE@%, %@AB@%LOW%@AE@%%@NL@%
  9487. %@NL@%
  9488.   6                  %@AB@%+%@AE@%,%@AB@%-%@AE@% (unary)%@NL@%
  9489. %@NL@%
  9490.   7                  %@AB@%*%@AE@%,%@AB@%/%@AE@%, %@AB@%MOD%@AE@%, %@AB@%SHL%@AE@%, %@AB@%SHR%@AE@%%@NL@%
  9491. %@NL@%
  9492.   8                  %@AB@%+%@AE@%, %@AB@%-%@AE@% (binary)%@NL@%
  9493. %@NL@%
  9494.   9                  %@AB@%EQ%@AE@%, %@AB@%NE%@AE@%, %@AB@%LT%@AE@%, %@AB@%LE%@AE@%, %@AB@%GT%@AE@%, %@AB@%GE%@AE@%%@NL@%
  9495. %@NL@%
  9496.   10                 %@AB@%NOT%@AE@%%@NL@%
  9497. %@NL@%
  9498.   11                 %@AB@%AND%@AE@%%@NL@%
  9499. %@NL@%
  9500.   12                 %@AB@%OR%@AE@%, %@AB@%XOR%@AE@%%@NL@%
  9501. %@NL@%
  9502.   13                 %@AB@%SHORT%@AE@%, %@AB@%.TYPE%@AE@%%@NL@%
  9503. %@NL@%
  9504.   (Lowest)%@NL@%
  9505. %@NL@%
  9506.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9507. %@NL@%
  9508. %@NL@%
  9509. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  9510. %@NL@%
  9511.   %@AS@%a           EQU     8 / 4 * 2          ; Equals 4%@AE@%%@NL@%
  9512.   %@AS@%b           EQU     8 / (4 * 2)        ; Equals 1%@AE@%%@NL@%
  9513.   %@AS@%c           EQU     8 + 4 * 2          ; Equals 16%@AE@%%@NL@%
  9514.   %@AS@%d           EQU     (8 + 4) * 2        ; Equals 24%@AE@%%@NL@%
  9515.   %@AS@%e           EQU     8 OR 4 AND 2       ; Equals 8%@AE@%%@NL@%
  9516.   %@AS@%f           EQU     (8 OR 4) AND 3     ; Equals 0%@AE@%%@NL@%
  9517. %@NL@%
  9518. %@NL@%
  9519. %@2@%%@CR:SC9.3       @%%@AB@%9.3  Using the Location Counter%@AE@%%@EH@%%@NL@%
  9520. %@NL@%
  9521. %@4@%%@CR:IX9.83      @%%@CR:IX9.84      @%  The location counter is a special operand that, during assembly,%@EH@%
  9522.   represents the address of the statement currently being assembled. At
  9523.   assembly time, the location counter keeps changing, but when used in
  9524.   source code, it resolves to a constant representing an address.%@NL@%
  9525. %@NL@%
  9526. %@4@%  The location counter has the same attributes as a near label. It%@EH@%
  9527.   represents an offset that is relative to the current segment and is equal
  9528.   to the number of bytes generated for the segment to that point.%@NL@%
  9529. %@NL@%
  9530. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  9531. %@NL@%
  9532.   %@AS@%string      DB      "Who wants to count every byte in a string, "%@AE@%%@NL@%
  9533.   %@AS@%            DB      "especially if you might change it later."%@AE@%%@NL@%
  9534.   %@AS@%lstring     EQU     $-string   ; Let the assembler do it%@AE@%%@NL@%
  9535. %@NL@%
  9536. %@4@%  Example 1 shows one way of using the location-counter operand in%@EH@%
  9537.   expressions relating to data.%@NL@%
  9538. %@NL@%
  9539. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  9540. %@NL@%
  9541.   %@AS@%            cmp     ax,bx%@AE@%%@NL@%
  9542.   %@AS@%            jl      shortjump  ; If ax < bx, go to "shortjump"%@AE@%%@NL@%
  9543.   %@AS@%            .                  ;   else if ax >= bx, continue%@AE@%%@NL@%
  9544.   %@AS@%            .%@AE@%%@NL@%
  9545.   %@AS@%shortjump:  .%@AE@%%@NL@%
  9546. %@NL@%
  9547.   %@AS@%            cmp     ax,bx%@AE@%%@NL@%
  9548.   %@AS@%            jge     $+5        ; If ax >= bx, continue%@AE@%%@NL@%
  9549.   %@AS@%            jmp     longjump   ;   else if ax < bx, go to "longjump"%@AE@%%@NL@%
  9550.   %@AS@%            .                  ; This is "$+5"%@AE@%%@NL@%
  9551.   %@AS@%            .%@AE@%%@NL@%
  9552.   %@AS@%longjump:   .%@AE@%%@NL@%
  9553. %@NL@%
  9554. %@4@%  Example 2 illustrates how you can use the location counter to do%@EH@%
  9555.   conditional jumps of more than 128 bytes. The first part shows the normal
  9556.   way of coding jumps of less than 128 bytes, and the second part shows how
  9557.   to code the same jump when the label is more than 128 bytes away.%@NL@%
  9558. %@NL@%
  9559. %@NL@%
  9560. %@2@%%@CR:SC9.4       @%%@AB@%9.4  Using Forward References%@AE@%%@EH@%%@NL@%
  9561. %@NL@%
  9562. %@4@%%@CR:IX9.85      @%  The assembler permits you to refer to labels, variable names, segment%@EH@%
  9563.   names, and other symbols before they are declared in the source code. Such
  9564.   references are called forward references.%@NL@%
  9565. %@NL@%
  9566. %@4@%  The assembler handles forward references by making assumptions about them%@EH@%
  9567.   on the first pass and then attempting to correct the assumptions, if
  9568.   necessary, on the second pass. Checking and correcting assumptions on the
  9569.   second pass takes processing time, so source code with forward references
  9570.   assembles more slowly than source code with no forward references.%@NL@%
  9571. %@NL@%
  9572. %@4@%  In addition, the assembler may make incorrect assumptions that it cannot%@EH@%
  9573.   correct, or corrects at a cost in program efficiency.%@NL@%
  9574. %@NL@%
  9575. %@NL@%
  9576. %@3@%%@CR:SC9.4.1     @%%@AB@%9.4.1  Forward References to Labels%@AE@%%@EH@%%@NL@%
  9577. %@NL@%
  9578. %@4@%%@CR:IX9.86      @%  Forward references to labels may result in incorrect or inefficient code.%@EH@%%@NL@%
  9579. %@NL@%
  9580. %@4@%  In the statement below, the label %@AS@%target %@AE@%is a forward reference:%@EH@%%@NL@%
  9581. %@NL@%
  9582.   %@AS@%            jmp     target             ; Generates 3 bytes in 16-bit segment%@AE@%%@NL@%
  9583.   %@AS@%            .%@AE@%%@NL@%
  9584.   %@AS@%            .%@AE@%%@NL@%
  9585.   %@AS@%            .%@AE@%%@NL@%
  9586.   %@AS@%target:%@AE@%%@NL@%
  9587. %@NL@%
  9588. %@4@%%@CR:IX9.87      @%%@CR:IX9.88      @%  Since the assembler processes source files sequentially, %@AS@%target %@AE@%is unknown%@EH@%
  9589.   when it is first encountered. It could be one of three types: short (-128
  9590.   to 127 bytes from the jump), near (-32,768 to 32,767 bytes from the jump),
  9591.   or far (in a different segment than the jump). QuickAssembler assumes that
  9592.   %@AS@%target %@AE@%is a near label, and assembles the number of bytes necessary to
  9593.   specify a near label: one byte for the instruction and two bytes for the
  9594.   operand.%@NL@%
  9595. %@NL@%
  9596. %@4@%%@CR:IX9.89      @%%@CR:IX9.90      @%  If, on the second pass, the assembler learns that %@AS@%target%@AE@% is a short label,%@EH@%
  9597.   it will need only two bytes: one for the instruction and one for the
  9598.   operand. However, it will not be able to change its previous assembly and
  9599.   the three-byte version of the assembly will stand. If the assembler learns
  9600.   that %@AS@%target%@AE@% is a far label, it will need five bytes. Since it can't make
  9601.   this adjustment, it will generate a phase error.%@NL@%
  9602. %@NL@%
  9603. %@4@%%@CR:IX9.91      @%%@CR:IX9.92      @%  You can override the assembler's assumptions by specifying the exact size%@EH@%
  9604.   of the jump. For example, if you know that a %@AB@%JMP%@AE@% instruction refers to a
  9605.   label less than 128 bytes from the jump, you can use the %@AB@%SHORT%@AE@% operator,
  9606.   as shown below:%@NL@%
  9607. %@NL@%
  9608.   %@AS@%            jmp     SHORT target       ; Generates 2 bytes%@AE@%%@NL@%
  9609.   %@AS@%            .%@AE@%%@NL@%
  9610.   %@AS@%            .%@AE@%%@NL@%
  9611.   %@AS@%            .%@AE@%%@NL@%
  9612.   %@AS@%target:%@AE@%%@NL@%
  9613. %@NL@%
  9614. %@4@%  Using the %@AB@%SHORT%@AE@% operator makes the code smaller and slightly faster. If%@EH@%
  9615.   the assembler has to use the three-byte form when the two-byte form would
  9616.   be acceptable, it will generate a warning message if the warning level is
  9617.   2. (The warning level can be set with the /W option, as described in
  9618.   Appendix B%@BO:       f653b@%, Section B.16%@BO:       fc9ca@%.) You can ignore the warning, or you can go
  9619.   back to the source code and change the code to eliminate the forward
  9620.   references.%@NL@%
  9621. %@NL@%
  9622.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9623.   %@AB@%NOTE%@AE@%  The %@AB@%SHORT%@AE@% operator in the example above would not be needed if
  9624.   %@AS@%target %@AE@%were located before the jump. The assembler would have already
  9625.   processed %@AS@%target%@AE@% and would be able to make adjustments based on its
  9626.   distance.%@NL@%
  9627.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9628. %@NL@%
  9629. %@4@%%@CR:IX9.93      @%  If you use the %@AB@%SHORT%@AE@% operator when the label being jumped to is more than%@EH@%
  9630.   128 bytes away, QuickAssembler generates an error message. You can either
  9631.   remove the %@AB@%SHORT%@AE@% operator, or try to reorganize your program to reduce the
  9632.   distance.%@NL@%
  9633. %@NL@%
  9634. %@4@%%@CR:IX9.94      @%  If a far jump to a forward-referenced label is required, you must override%@EH@%
  9635.   the assembler's assumptions with the %@AB@%FAR%@AE@% and %@AB@%PTR%@AE@% operators, as shown
  9636.   below:%@NL@%
  9637. %@NL@%
  9638.   %@AS@%            jmp     FAR PTR target     ; Generates 5 bytes%@AE@%%@NL@%
  9639.   %@AS@%            .%@AE@%%@NL@%
  9640.   %@AS@%            .%@AE@%%@NL@%
  9641.   %@AS@%            .%@AE@%%@NL@%
  9642.   %@AS@%target:                                ; In different segment%@AE@%%@NL@%
  9643. %@NL@%
  9644. %@4@%  If the type of a label has been established earlier in the source code%@EH@%
  9645.   with an %@AB@%EXTRN%@AE@% directive, the type does not need to be specified in the
  9646.   jump statement.%@NL@%
  9647. %@NL@%
  9648. %@NL@%
  9649. %@3@%%@CR:SC9.4.2     @%%@AB@%9.4.2  Forward References to Variables%@AE@%%@EH@%%@NL@%
  9650. %@NL@%
  9651. %@4@%%@CR:IX9.95      @%  When QuickAssembler encounters code referencing variables that have not%@EH@%
  9652.   yet been defined in pass 1, it makes assumptions about the segment where
  9653.   the variable will be defined. If on pass 2 the assumptions turn out to be
  9654.   wrong, an error will occur.%@NL@%
  9655. %@NL@%
  9656. %@4@%  These problems usually occur with complex segment structures that do not%@EH@%
  9657.   follow the Microsoft segment conventions. The problems never appear if
  9658.   simplified segment directives are used.%@NL@%
  9659. %@NL@%
  9660. %@4@%  By default, QuickAssembler assumes that variables are referenced to the DS%@EH@%
  9661.   register. If a statement must access a variable in a segment not
  9662.   associated with the DS register, and if the variable has not been defined
  9663.   earlier in the source code, you must use the segment-override operator to
  9664.   specify the segment.%@NL@%
  9665. %@NL@%
  9666. %@4@%  The situation is different if neither the variable nor the segment in%@EH@%
  9667.   which it is defined has been defined earlier in the source code. In this
  9668.   case, you must assign the segment to a group earlier in the source code.
  9669.   QuickAssembler will then know about the existence of the segment even
  9670.   though it has not yet been defined.%@NL@%
  9671. %@NL@%
  9672. %@NL@%
  9673. %@2@%%@CR:SC9.5       @%%@AB@%9.5  Strong Typing for Memory Operands%@AE@%%@EH@%%@NL@%
  9674. %@NL@%
  9675. %@4@%%@CR:IX9.96      @%%@CR:IX9.97      @%%@CR:IX9.98      @%  The assembler carries out strict syntax checks for all instruction%@EH@%
  9676.   statements, including strong typing for operands that refer to memory
  9677.   locations. This means that when an instruction uses two operands with
  9678.   implied data types, the operand types must match. Warning messages are
  9679.   generated for nonmatching types.%@NL@%
  9680. %@NL@%
  9681. %@4@%  For example, in the following fragment, the variable %@AS@%string%@AE@% is incorrectly%@EH@%
  9682.   used in a move instruction:%@NL@%
  9683. %@NL@%
  9684.   %@AS@%            .DATA%@AE@%%@NL@%
  9685.   %@AS@%string      DB      "A message."%@AE@%%@NL@%
  9686.   %@AS@%            .CODE%@AE@%%@NL@%
  9687.   %@AS@%            .%@AE@%%@NL@%
  9688.   %@AS@%            .%@AE@%%@NL@%
  9689.   %@AS@%            .%@AE@%%@NL@%
  9690.   %@AS@%            mov     ax,string[1]%@AE@%%@NL@%
  9691. %@NL@%
  9692. %@4@%  The %@AS@%ax%@AE@% register has %@AB@%WORD%@AE@% type, but %@AS@%string%@AE@% has %@AB@%BYTE%@AE@% type. Therefore, the%@EH@%
  9693.   statement generates the following warning message:%@NL@%
  9694. %@NL@%
  9695.   %@AS@%Operand types must match%@AE@%%@NL@%
  9696. %@NL@%
  9697. %@4@%  To avoid all ambiguity and prevent the warning error, use the %@AB@%PTR%@AE@% operator%@EH@%
  9698.   to override the variable's type, as shown below:%@NL@%
  9699. %@NL@%
  9700.   %@AS@%            mov     ax,WORD PTR string[1]%@AE@%%@NL@%
  9701. %@NL@%
  9702. %@4@%%@CR:IX9.99      @%  You can ignore the warnings if you are willing to trust the assembler's%@EH@%
  9703.   assumptions. When a register and memory operand are mixed, the assembler
  9704.   assumes that the register operand is always the correct size. For example,
  9705.   in the statement%@NL@%
  9706. %@NL@%
  9707.   %@AS@%            mov     ax,string[1]%@AE@%%@NL@%
  9708. %@NL@%
  9709. %@4@%  the assembler assumes that the programmer wishes the word size of the%@EH@%
  9710.   register to override the byte size of the variable. A word starting at
  9711.   %@AS@%string[1]%@AE@% will be moved into AX. In the statement%@NL@%
  9712. %@NL@%
  9713.   %@AS@%            mov     string[1],ax%@AE@%%@NL@%
  9714. %@NL@%
  9715. %@4@%  the assembler assumes that the programmer wishes to move the word value in%@EH@%
  9716.   AX into the word starting at %@AS@%string[1]%@AE@%. However, the assembler's
  9717.   assumptions are not always as clear as in these examples. You should not
  9718.   ignore warnings about type mismatches unless you are sure you understand
  9719.   how your code will be assembled.%@NL@%
  9720. %@NL@%
  9721.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9722. %@CR:IX9.100     @%%@CR:IX9.101     @%%@CR:IX9.102     @%%@CR:IX9.103     @%  %@AB@%NOTE%@AE@%  Some assemblers (including early versions of the IBM Macro
  9723.   Assembler) do not do strict type checking. For compatibility with these
  9724.   assemblers, type errors are warnings rather than severe errors. Many
  9725.   assembly-language program listings in books and magazines are written for
  9726.   assemblers with weak type checking. Such programs may produce warning
  9727.   messages, but assemble correctly. You can use the /W option to turn off
  9728.   type warnings if you are sure the code is correct.%@NL@%
  9729.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  9730. %@NL@%
  9731. %@NL@%
  9732. %@NL@%
  9733. ────────────────────────────────────────────────────────────────────────────%@NL@%
  9734. %@1@%%@CR:CH10        @%%@AB@%Chapter 10:  Assembling Conditionally%@AE@%%@EH@%%@NL@%
  9735. %@NL@%
  9736. %@NL@%
  9737. %@4@%%@CR:IX10.1      @%%@CR:IX10.2      @%  QuickAssembler provides two types of conditional directives,%@EH@%
  9738.   conditional-assembly and conditional-error directives.
  9739.   Conditional-assembly directives test for a specified condition and
  9740.   assemble a block of statements if the condition is true. Conditional-error
  9741.   directives test for a specified condition and generate an assembly error
  9742.   if the condition is true.%@NL@%
  9743. %@NL@%
  9744. %@4@%  Both kinds of conditional directives test assembly-time conditions. They%@EH@%
  9745.   cannot test run-time conditions. Only expressions that evaluate to
  9746.   constants during assembly can be compared or tested.%@NL@%
  9747. %@NL@%
  9748. %@4@%  Since macros and conditional-assembly directives are often used together,%@EH@%
  9749.   you may need to refer to Chapter 11%@BO:       8d6e4@%, "Using Equates, Macros, and Repeat
  9750.   Blocks," to understand some of the examples in this chapter. In
  9751.   particular, conditional directives are frequently used with the operators
  9752.   described in Section 11.5%@BO:       9a1b8@%, "Using Macro Operators."%@NL@%
  9753. %@NL@%
  9754. %@NL@%
  9755. %@2@%%@CR:SC10.1      @%%@AB@%10.1  Using Conditional-Assembly Directives%@AE@%%@EH@%%@NL@%
  9756. %@NL@%
  9757. %@4@%%@CR:IX10.3      @%  The conditional-assembly directives include the following:%@EH@%%@NL@%
  9758. %@NL@%
  9759. %@4@%  %@AB@%ELSE          IFB          IFIDN%@AE@%%@EH@%%@NL@%
  9760.   %@AB@%ENDIF         IFDEF        IFIDNI%@AE@%%@NL@%
  9761.   %@AB@%IF            IFDIF        IFNB%@AE@%%@NL@%
  9762.   %@AB@%IF1           IFDIFI       IFNDEF%@AE@%%@NL@%
  9763.   %@AB@%IF2           IFE%@AE@%%@NL@%
  9764. %@NL@%
  9765. %@4@%  The %@AB@%IF%@AE@% directives and the %@AB@%ENDIF%@AE@% and %@AB@%ELSE%@AE@% directives can be used to enclose%@EH@%
  9766.   the statements to be considered for conditional assembly.%@NL@%
  9767. %@NL@%
  9768. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9769. %@NL@%
  9770. %@4@%  %@AB@%IF%@AE@%%@AI@%condition%@AE@%%@EH@%%@NL@%
  9771.   %@AI@%statements%@AE@%%@NL@%
  9772.   [[%@AB@%ELSEIF%@AE@%%@AI@%condition%@AE@%%@NL@%
  9773.   %@AI@%statements%@AE@%]]%@NL@%
  9774.   %@AB@%.%@AE@%%@NL@%
  9775.   %@AB@%.%@AE@%%@NL@%
  9776.   %@AB@%.%@AE@%%@NL@%
  9777.   [[%@AB@%ELSE%@AE@%%@NL@%
  9778.   %@AI@%statements%@AE@%]]%@NL@%
  9779.   %@AB@%ENDIF%@AE@%%@NL@%
  9780. %@NL@%
  9781. %@4@%  The %@AI@%statements%@AE@% following the %@AB@%IF%@AE@% directive can be any valid statements,%@EH@%
  9782.   including other conditional blocks. The %@AB@%ELSEIF%@AE@% and %@AB@%ELSE%@AE@% blocks are
  9783.   optional. The conditional block can contain any number of %@AB@%ELSEIF%@AE@% blocks.
  9784.   (The %@AB@%ELSEIF%@AE@% directives are listed in Section 10.1.6%@BO:       89a62@%.) %@AB@%ENDIF%@AE@% ends the
  9785.   block.%@NL@%
  9786. %@NL@%
  9787. %@4@%%@CR:IX10.4      @%%@CR:IX10.5      @%%@CR:IX10.6      @%%@CR:IX10.7      @%  The statements following the %@AB@%IF%@AE@% directive are assembled only if the%@EH@%
  9788.   corresponding %@AI@%condition%@AE@% is true. If the condition is not true and an
  9789.   %@AB@%ELSEIF%@AE@% directive is used, the assembler checks to see if the corresponding
  9790.   condition is true. If so, it assembles the statements following the %@AB@%ELSEIF%@AE@%
  9791.   directive. If no %@AB@%IF%@AE@% or %@AB@%ELSEIF%@AE@% conditions are satisifed, the statements
  9792.   following the %@AB@%ELSE%@AE@% directive are assembled.%@NL@%
  9793. %@NL@%
  9794. %@4@%%@CR:IX10.8      @%%@CR:IX10.9      @%  %@AB@%IF%@AE@% statements can be nested up to 20 levels. A nested %@AB@%ELSE%@AE@% or %@AB@%ELSEIF%@AE@%%@EH@%
  9795.   directive always belongs to the nearest preceding %@AB@%IF%@AE@% statement that does
  9796.   not have its own %@AB@%ELSE%@AE@% directive.%@NL@%
  9797. %@NL@%
  9798. %@NL@%
  9799. %@3@%%@CR:SC10.1.1    @%%@AB@%10.1.1  Testing Expressions with IF and IFE Directives%@AE@%%@EH@%%@NL@%
  9800. %@NL@%
  9801. %@4@%%@CR:IX10.10     @%%@CR:IX10.11     @%%@CR:IX10.12     @%%@CR:IX10.13     @%%@CR:IX10.14     @%  The %@AB@%IF%@AE@% and %@AB@%IFE%@AE@% directives test the value of an expression and grant%@EH@%
  9802.   assembly based on the result.%@NL@%
  9803. %@NL@%
  9804. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9805. %@NL@%
  9806. %@4@%  %@AB@%IF%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  9807.   %@AB@%IFE%@AE@% %@AI@%expression%@AE@%%@NL@%
  9808. %@NL@%
  9809. %@4@%  The %@AB@%IF%@AE@% directive grants assembly if the value of %@AI@%expression%@AE@% is true%@EH@%
  9810.   (nonzero). The %@AB@%IFE%@AE@% directive grants assembly if the value of %@AI@%expression%@AE@% is
  9811.   false (0). The expression must evaluate to a constant value and must not
  9812.   contain forward references.%@NL@%
  9813. %@NL@%
  9814. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9815. %@NL@%
  9816.   %@AS@%            IF      debug GT 20%@AE@%%@NL@%
  9817.   %@AS@%            push    debug%@AE@%%@NL@%
  9818.   %@AS@%            call    adebug%@AE@%%@NL@%
  9819.   %@AS@%            ELSEIF  debug GT 10%@AE@%%@NL@%
  9820.   %@AS@%            call    bdebug%@AE@%%@NL@%
  9821.   %@AS@%            ELSE%@AE@%%@NL@%
  9822.   %@AS@%            call    cdebug%@AE@%%@NL@%
  9823.   %@AS@%            ENDIF%@AE@%%@NL@%
  9824. %@NL@%
  9825. %@4@%  In this example, a different debug routine will be called, depending on%@EH@%
  9826.   the value of %@AS@%debug%@AE@%.%@NL@%
  9827. %@NL@%
  9828. %@NL@%
  9829. %@3@%%@CR:SC10.1.2    @%%@AB@%10.1.2  Testing the Pass with IF1 and IF2 Directives%@AE@%%@EH@%%@NL@%
  9830. %@NL@%
  9831. %@4@%%@CR:IX10.15     @%%@CR:IX10.16     @%%@CR:IX10.17     @%%@CR:IX10.18     @%%@CR:IX10.19     @%  The %@AB@%IF1%@AE@% and %@AB@%IF2%@AE@% directives test the current assembly pass and grant%@EH@%
  9832.   assembly only on the pass specified by the directive. Multiple passes of
  9833.   the assembler are discussed in Appendix C%@BO:       fd1fd@%, Section C.7%@BO:      101a0c@%, "Reading a Pass
  9834.   1 Listing."%@NL@%
  9835. %@NL@%
  9836. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9837. %@NL@%
  9838. %@4@%  %@AB@%IF1%@AE@%%@EH@%%@NL@%
  9839.   %@AB@%IF2%@AE@%%@NL@%
  9840. %@NL@%
  9841. %@4@%  The %@AB@%IF1%@AE@% directive grants assembly only on pass 1. The %@AB@%IF2%@AE@% directive grants%@EH@%
  9842.   assembly only on pass 2. The directives take no arguments. If you turn on
  9843.   the One-Pass Assembly option, the %@AB@%IF2%@AE@% directive produces an error.%@NL@%
  9844. %@NL@%
  9845. %@4@%  Macros usually only need to be processed once. You can enclose blocks of%@EH@%
  9846.   macros in %@AB@%IF1%@AE@% blocks to prevent them from being reprocessed on the second
  9847.   pass.%@NL@%
  9848. %@NL@%
  9849. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9850. %@NL@%
  9851.   %@AS@%            IF1                ; Define on first pass only%@AE@%%@NL@%
  9852.   %@AS@%dostuff     MACRO   argument%@AE@%%@NL@%
  9853.   %@AS@%            .%@AE@%%@NL@%
  9854.   %@AS@%            .%@AE@%%@NL@%
  9855.   %@AS@%            .%@AE@%%@NL@%
  9856.   %@AS@%            ENDM%@AE@%%@NL@%
  9857.   %@AS@%            ENDIF%@AE@%%@NL@%
  9858. %@NL@%
  9859. %@NL@%
  9860. %@3@%%@CR:SC10.1.3    @%%@AB@%10.1.3  Testing Symbol Definition with IFDEF and IFNDEF Directives%@AE@%%@EH@%%@NL@%
  9861. %@NL@%
  9862. %@4@%%@CR:IX10.20     @%%@CR:IX10.21     @%%@CR:IX10.22     @%%@CR:IX10.23     @%%@CR:IX10.24     @%  The %@AB@%IFDEF%@AE@% and %@AB@%IFNDEF%@AE@% directives test whether a symbol has been defined and%@EH@%
  9863.   grant assembly based on the result.%@NL@%
  9864. %@NL@%
  9865. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9866. %@NL@%
  9867. %@4@%  %@AB@%IFDEF%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@%
  9868.   %@AB@%IFNDEF%@AE@% %@AI@%name%@AE@%%@NL@%
  9869. %@NL@%
  9870. %@4@%  The %@AB@%IFDEF%@AE@% directive grants assembly only if %@AI@%name%@AE@% is a defined label,%@EH@%
  9871.   variable, or symbol. The %@AB@%IFNDEF%@AE@% directive grants assembly if %@AI@%name%@AE@% has not
  9872.   yet been defined.%@NL@%
  9873. %@NL@%
  9874. %@4@%  The name can be any valid name. Note that if %@AI@%name%@AE@% is a forward reference,%@EH@%
  9875.   it is considered undefined on pass 1, but defined on pass 2.%@NL@%
  9876. %@NL@%
  9877. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9878. %@NL@%
  9879.   %@AS@%            IFDEF   buffer%@AE@%%@NL@%
  9880.   %@AS@%buff        DB      buffer DUP(?)%@AE@%%@NL@%
  9881.   %@AS@%            ENDIF%@AE@%%@NL@%
  9882. %@NL@%
  9883. %@4@%  In this example, %@AS@%buff%@AE@% is allocated only if %@AS@%buffer%@AE@% has been previously%@EH@%
  9884.   defined.%@NL@%
  9885. %@NL@%
  9886. %@4@%  One way to use this conditional block is to leave %@AS@%buffer %@AE@%undefined in the%@EH@%
  9887.   source file and define it if needed by using the /D%@AI@%symbol%@AE@% option (see
  9888.   Appendix B%@BO:       f653b@%, Section B.4%@BO:       f8ea4@%, "Defining Assembler Symbols") when you start
  9889.   QuickAssembler. For example, if the conditional block is in TEST.ASM, you
  9890.   could start the assembler with the following command line:%@NL@%
  9891. %@NL@%
  9892.   %@AS@%QCL /Dbuffer=1024 test.asm%@AE@%%@NL@%
  9893. %@NL@%
  9894. %@4@%  You could also define the symbol %@AS@%buffer %@AE@%by entering %@AS@%buffer=1024 %@AE@%in the%@EH@%
  9895.   Defines field of the Assembler Flags dialog box.%@NL@%
  9896. %@NL@%
  9897. %@4@%  The command line would define the symbol %@AS@%buffer%@AE@%. As a result, the%@EH@%
  9898.   conditional-assembly block would allocate %@AS@%buff%@AE@%. However, if you didn't
  9899.   need %@AS@%buff%@AE@%, you could use the following command line:%@NL@%
  9900. %@NL@%
  9901.   %@AS@%QCL test.asm%@AE@%%@NL@%
  9902. %@NL@%
  9903. %@NL@%
  9904. %@3@%%@CR:SC10.1.4    @%%@AB@%10.1.4  Verifying Macro Parameters with IFB and IFNB Directives%@AE@%%@EH@%%@NL@%
  9905. %@NL@%
  9906. %@4@%%@CR:IX10.25     @%%@CR:IX10.26     @%%@CR:IX10.27     @%%@CR:IX10.28     @%%@CR:IX10.29     @%%@CR:IX10.30     @%%@CR:IX10.31     @%%@CR:IX10.32     @%  The %@AB@%IFB%@AE@% and %@AB@%IFNB%@AE@% directives test to see if a specified argument was passed%@EH@%
  9907.   to a macro and grant assembly based on the result.%@NL@%
  9908. %@NL@%
  9909. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9910. %@NL@%
  9911. %@4@%  %@AB@%IFB%@AE@% %@AB@%<%@AE@%%@AI@%argument%@AE@% %@AB@%>%@AE@%%@EH@%%@NL@%
  9912.   %@AB@%IFNB%@AE@% %@AB@%<%@AE@%%@AI@%argument%@AE@%%@AB@%>%@AE@%%@NL@%
  9913. %@NL@%
  9914. %@4@%  These directives are always used inside macros, and they always test%@EH@%
  9915.   whether a real argument was passed for a specified dummy argument. The %@AB@%IFB%@AE@%
  9916.   directive grants assembly if %@AI@%argument%@AE@% is blank. The %@AB@%IFNB%@AE@% directive grants
  9917.   assembly if %@AI@%argument%@AE@% is not blank. The arguments can be any name, number,
  9918.   or expression. Angle brackets (%@AB@%< >%@AE@%) are required.%@NL@%
  9919. %@NL@%
  9920. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9921. %@NL@%
  9922.   %@AS@%Write       MACRO   buffer,bytes,handle%@AE@%%@NL@%
  9923.   %@AS@%            IFNB    <handle>%@AE@%%@NL@%
  9924.   %@AS@%            mov     bx,handle        ; (1=stdout,2=stderr,3=aux,4=printer)%@AE@%%@NL@%
  9925.   %@AS@%            ELSE%@AE@%%@NL@%
  9926.   %@AS@%            mov     bx,1             ; Default standard out%@AE@%%@NL@%
  9927.   %@AS@%            ENDIF%@AE@%%@NL@%
  9928.   %@AS@%            mov     dx,OFFSET buffer ; Address of buffer to write to%@AE@%%@NL@%
  9929.   %@AS@%            mov     cx,bytes         ; Number of bytes to write%@AE@%%@NL@%
  9930.   %@AS@%            mov     ah,40h%@AE@%%@NL@%
  9931.   %@AS@%            int     21h%@AE@%%@NL@%
  9932.   %@AS@%            ENDM%@AE@%%@NL@%
  9933. %@NL@%
  9934. %@4@%%@CR:IX10.33     @%  In this example, a default value is used if no value is specified for the%@EH@%
  9935.   third macro argument.%@NL@%
  9936. %@NL@%
  9937. %@NL@%
  9938. %@3@%%@CR:SC10.1.5    @%%@AB@%10.1.5  Comparing Macro Arguments with IFIDN and IFDIF Directives%@AE@%%@EH@%%@NL@%
  9939. %@NL@%
  9940. %@4@%%@CR:IX10.34     @%%@CR:IX10.35     @%%@CR:IX10.36     @%%@CR:IX10.37     @%%@CR:IX10.38     @%%@CR:IX10.39     @%  The %@AB@%IFIDN%@AE@% and %@AB@%IFDIF%@AE@% directives compare two macro arguments and grant%@EH@%
  9941.   assembly based on the result.%@NL@%
  9942. %@NL@%
  9943. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  9944. %@NL@%
  9945. %@4@%  %@AB@%IFIDN%@AE@%[[%@AB@%I%@AE@%]] %@AB@%<%@AE@%%@AI@%argument1%@AE@%%@AB@%>,<%@AE@%%@AI@%argument2%@AE@%%@AB@%>%@AE@%%@EH@%%@NL@%
  9946.   %@AB@%IFDIF%@AE@%[[%@AB@%I%@AE@%]] %@AB@%<%@AE@%%@AI@%argument1%@AE@%%@AB@%>,<%@AE@%%@AI@%argument2%@AE@%%@AB@%>%@AE@%%@NL@%
  9947. %@NL@%
  9948. %@4@%  These directives are always used inside macros, and they always test%@EH@%
  9949.   whether real arguments passed for two specified arguments are the same.
  9950.   The %@AB@%IFIDN%@AE@% directive grants assembly if %@AI@%argument1%@AE@% and %@AI@%argument2%@AE@% are
  9951.   identical. The %@AB@%IFDIF%@AE@% directive grants assembly if %@AI@%argument1%@AE@% and %@AI@%argument2%@AE@%
  9952.   are different. The arguments can be names, numbers, or expressions. They
  9953.   must be enclosed in angle brackets and separated by a comma.%@NL@%
  9954. %@NL@%
  9955. %@4@%  The optional %@AB@%I%@AE@% at the end of the directive name specifies that the%@EH@%
  9956.   directive is case insensitive. Arguments that are spelled the same will be
  9957.   evaluated the same, regardless of case. If the %@AB@%I%@AE@% is not given, the
  9958.   directive is case sensitive.%@NL@%
  9959. %@NL@%
  9960. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  9961. %@NL@%
  9962.   %@AS@%divide8     MACRO   numerator,denominator%@AE@%%@NL@%
  9963.   %@AS@%            IFDIFI  <numerator>,<al>        ;; If numerator isn't AL%@AE@%%@NL@%
  9964.   %@AS@%            mov     al,numerator            ;;   make it AL%@AE@%%@NL@%
  9965.   %@AS@%            ENDIF%@AE@%%@NL@%
  9966.   %@AS@%            xor     ah,ah%@AE@%%@NL@%
  9967.   %@AS@%            div     denominator%@AE@%%@NL@%
  9968.   %@AS@%            ENDM%@AE@%%@NL@%
  9969. %@NL@%
  9970. %@4@%  In this example, a macro uses the %@AB@%IFDIFI%@AE@% directive to check one of the%@EH@%
  9971.   arguments and take a different action, depending on the text of the
  9972.   string. The sample macro could be enhanced further by checking for other
  9973.   values that would require adjustment (such as a denominator passed in AL
  9974.   or passed in AH).%@NL@%
  9975. %@NL@%
  9976. %@NL@%
  9977. %@3@%%@CR:SC10.1.6    @%%@AB@%10.1.6  ELSEIF Directives%@AE@%%@EH@%%@NL@%
  9978. %@NL@%
  9979. %@4@%%@CR:IX10.40     @%%@CR:IX10.41     @%  The assembler includes an %@AB@%ELSEIF%@AE@% conditional-assembly directive%@EH@%
  9980.   corresponding to each of the %@AB@%IF%@AE@% directives. The %@AB@%ELSEIF%@AE@% directives provide
  9981.   a more compact and better structured way of writing some sequences of %@AB@%ELSE%@AE@%
  9982.   and %@AB@%IF%@AE@% directives. QuickAssembler supports the following directives:%@NL@%
  9983. %@NL@%
  9984. %@4@%  %@AB@%ELSEIF           ELSEIFDEF           ELSEIFIDN%@AE@%%@EH@%%@NL@%
  9985.   %@AB@%ELSEIF1          ELSEIFDIF           ELSEIFIDNI%@AE@%%@NL@%
  9986.   %@AB@%ELSEIF2          ELSEIFDIFI          ELSEIFNB%@AE@%%@NL@%
  9987.   %@AB@%ELSEIFB          ELSEIFE             ELSEIFNDEF%@AE@%%@NL@%
  9988. %@NL@%
  9989. %@4@%  The following macro contains nested %@AB@%IF%@AE@% and%@AB@% ELSE%@AE@% blocks:%@EH@%%@NL@%
  9990. %@NL@%
  9991.   %@AS@%; Macro to load register for high-level-language return%@AE@%%@NL@%
  9992.   %@AS@%FuncRet MACRO arg,length%@AE@%%@NL@%
  9993.   %@AS@%        LOCAL tmploc%@AE@%%@NL@%
  9994.   %@AS@%        IF length EQ 1%@AE@%%@NL@%
  9995.   %@AS@%           mov al,arg%@AE@%%@NL@%
  9996.   %@AS@%        ELSE%@AE@%%@NL@%
  9997.   %@AS@%           IF length EQ 2%@AE@%%@NL@%
  9998.   %@AS@%              mov ax,arg%@AE@%%@NL@%
  9999.   %@AS@%           ELSE%@AE@%%@NL@%
  10000.   %@AS@%              IF length EQ 4%@AE@%%@NL@%
  10001.   %@AS@%                 .DATA%@AE@%%@NL@%
  10002.   %@AS@%        tmploc   DW     ?%@AE@%%@NL@%
  10003.   %@AS@%                 DW     ?%@AE@%%@NL@%
  10004.   %@AS@%                 .CODE%@AE@%%@NL@%
  10005.   %@AS@%                 mov ax,WORD PTR arg%@AE@%%@NL@%
  10006.   %@AS@%                 mov tmploc,ax%@AE@%%@NL@%
  10007.   %@AS@%                 mov ax,WORD PTR arg+2%@AE@%%@NL@%
  10008.   %@AS@%                 mov tmploc+2,ax%@AE@%%@NL@%
  10009.   %@AS@%                 mov dx,SEG tmploc%@AE@%%@NL@%
  10010.   %@AS@%                 mov ax,OFFSET tmploc%@AE@%%@NL@%
  10011.   %@AS@%              ELSE%@AE@%%@NL@%
  10012.   %@AS@%                 %OUT Error in FuncRet expansion%@AE@%%@NL@%
  10013.   %@AS@%                 .ERR%@AE@%%@NL@%
  10014.   %@AS@%              ENDIF%@AE@%%@NL@%
  10015.   %@AS@%           ENDIF%@AE@%%@NL@%
  10016.   %@AS@%        ENDIF%@AE@%%@NL@%
  10017.   %@AS@%        ENDM%@AE@%%@NL@%
  10018. %@NL@%
  10019. %@4@%  The macro can be rewritten as follows, using the %@AB@%ELSEIF%@AE@% directives:%@EH@%%@NL@%
  10020. %@NL@%
  10021.   %@AS@%FuncRet MACRO arg,length%@AE@%%@NL@%
  10022.   %@AS@%        LOCAL tmploc%@AE@%%@NL@%
  10023.   %@AS@%        IF length EQ 1%@AE@%%@NL@%
  10024.   %@AS@%                 mov al,arg%@AE@%%@NL@%
  10025.   %@AS@%        ELSEIF length EQ 2%@AE@%%@NL@%
  10026.   %@AS@%                 mov ax,arg%@AE@%%@NL@%
  10027.   %@AS@%        ELSEIF length EQ 4%@AE@%%@NL@%
  10028.   %@AS@%                 .DATA%@AE@%%@NL@%
  10029. %@NL@%
  10030.   %@AS@%        tmploc   DW     ?%@AE@%%@NL@%
  10031.   %@AS@%                 DW     ?%@AE@%%@NL@%
  10032.   %@AS@%                 .CODE%@AE@%%@NL@%
  10033.   %@AS@%                 mov ax,WORD PTR arg%@AE@%%@NL@%
  10034.   %@AS@%                 mov tmploc,ax%@AE@%%@NL@%
  10035.   %@AS@%                 mov ax,WORD PTR arg+2%@AE@%%@NL@%
  10036.   %@AS@%                 mov tmploc+2,ax%@AE@%%@NL@%
  10037.   %@AS@%                 mov dx,SEG tmploc%@AE@%%@NL@%
  10038.   %@AS@%                 mov ax,OFFSET tmploc%@AE@%%@NL@%
  10039.   %@AS@%        ELSE%@AE@%%@NL@%
  10040.   %@AS@%                 %OUT Error in FuncRet expansion%@AE@%%@NL@%
  10041.   %@AS@%                 .ERR%@AE@%%@NL@%
  10042.   %@AS@%        ENDIF%@AE@%%@NL@%
  10043.   %@AS@%        ENDM%@AE@%%@NL@%
  10044. %@NL@%
  10045. %@NL@%
  10046. %@2@%%@CR:SC10.2      @%%@AB@%10.2  Using Conditional-Error Directives%@AE@%%@EH@%%@NL@%
  10047. %@NL@%
  10048. %@4@%%@CR:IX10.42     @%%@CR:IX10.43     @%  Conditional-error directives can be used to debug programs and check for%@EH@%
  10049.   assembly-time errors. By inserting a conditional-error directive at a key
  10050.   point in your code, you can test assembly-time conditions at that point.
  10051.   You can also use conditional-error directives to test for boundary
  10052.   conditions in macros.%@NL@%
  10053. %@NL@%
  10054. %@4@%  The conditional-error directives and the error messages they produce are%@EH@%
  10055.   listed in Table 10.1.%@NL@%
  10056. %@NL@%
  10057.   %@AB@%Table 10.1 Conditional-Error Directives%@AE@%%@NL@%
  10058. %@NL@%
  10059.   %@AB@%Directive%@AE@%       %@AB@%Number%@AE@%          %@AB@%Message%@AE@%%@NL@%
  10060.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10061.   %@AB@%.ERR1%@AE@%           2087            %@AS@%Forced error - pass1%@AE@%%@NL@%
  10062. %@NL@%
  10063.   %@AB@%.ERR2%@AE@%           2088            %@AS@%Forced error - pass2%@AE@%%@NL@%
  10064. %@NL@%
  10065.   %@AB@%.ERR%@AE@%            2089            %@AS@%Forced error%@AE@%%@NL@%
  10066. %@NL@%
  10067.   %@AB@%.ERRE%@AE@%           2090            %@AS@%Forced error - expression equals 0%@AE@%%@NL@%
  10068. %@NL@%
  10069.   %@AB@%.ERRNZ%@AE@%          2091            %@AS@%Forced error - expression not equal 0%@AE@%%@NL@%
  10070. %@NL@%
  10071.   %@AB@%.ERRNDEF%@AE@%        2092            %@AS@%Forced error - symbol not defined%@AE@%%@NL@%
  10072. %@NL@%
  10073.   %@AB@%.ERRDEF%@AE@%         2093            %@AS@%Forced error - symbol defined%@AE@%%@NL@%
  10074. %@NL@%
  10075.   %@AB@%.ERRB%@AE@%           2094            %@AS@%Forced error - string blank%@AE@%%@NL@%
  10076. %@NL@%
  10077.   %@AB@%.ERRNB%@AE@%          2095            %@AS@%Forced error - string not blank%@AE@%%@NL@%
  10078. %@NL@%
  10079.   %@AB@%.ERRIDN%@AE@% [[%@AB@%I%@AE@%]]   2096            %@AS@%Forced error - strings identical%@AE@%%@NL@%
  10080. %@NL@%
  10081.   %@AB@%.ERRDIF%@AE@% [[%@AB@%I%@AE@%]]   2097            %@AS@%Forced error - strings different%@AE@%%@NL@%
  10082. %@NL@%
  10083.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10084. %@NL@%
  10085. %@NL@%
  10086. %@4@%%@CR:IX10.44     @%%@CR:IX10.45     @%  Like other severe errors, those generated by conditional-error directives%@EH@%
  10087.   cause the assembler to return exit code 7. If a severe error is
  10088.   encountered during assembly, QuickAssembler will delete the object module.
  10089.   All conditional-error directives except %@AB@%ERR1%@AE@% generate severe errors.%@NL@%
  10090. %@NL@%
  10091. %@NL@%
  10092. %@3@%%@CR:SC10.2.1    @%%@AB@%10.2.1  Generating Unconditional Errors%@AE@%%@EH@%
  10093.         %@AB@%with .ERR, .ERR1, and .ERR2 Directives%@AE@%%@NL@%
  10094. %@NL@%
  10095. %@4@%%@CR:IX10.46     @%%@CR:IX10.47     @%%@CR:IX10.48     @%%@CR:IX10.49     @%%@CR:IX10.50     @%%@CR:IX10.51     @%%@CR:IX10.52     @%%@CR:IX10.53     @%%@CR:IX10.54     @%  The %@AB@%.ERR%@AE@%, %@AB@%.ERR1%@AE@%, and %@AB@%.ERR2%@AE@% directives force an error where the directives%@EH@%
  10096.   occur in the source file. The error is generated unconditionally when the
  10097.   directive is encountered, but the directives can be placed within
  10098.   conditional-assembly blocks to limit the errors to certain situations.%@NL@%
  10099. %@NL@%
  10100. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10101. %@NL@%
  10102. %@4@%  %@AB@%.ERR%@AE@%%@EH@%%@NL@%
  10103.   %@AB@%.ERR1%@AE@%%@NL@%
  10104.   %@AB@%.ERR2%@AE@%%@NL@%
  10105. %@NL@%
  10106. %@4@%  The %@AB@%.ERR%@AE@% directive forces an error regardless of the pass. The %@AB@%.ERR1%@AE@% and%@EH@%
  10107.   %@AB@%.ERR2%@AE@% directives force the error only on their respective passes. The
  10108.   %@AB@%.ERR1%@AE@% directive appears only on the screen or in the listing file if you
  10109.   use the /D option to request a pass 1 listing.%@NL@%
  10110. %@NL@%
  10111. %@4@%  You can place these directives within conditional-assembly blocks or%@EH@%
  10112.   macros to see which blocks are being expanded.%@NL@%
  10113. %@NL@%
  10114. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10115. %@NL@%
  10116.   %@AS@%IFDEF       dos%@AE@%%@NL@%
  10117.   %@AS@%            .%@AE@%%@NL@%
  10118.   %@AS@%            .%@AE@%%@NL@%
  10119.   %@AS@%            .%@AE@%%@NL@%
  10120.   %@AS@%ELSEIFDEF   xenix%@AE@%%@NL@%
  10121.   %@AS@%            .%@AE@%%@NL@%
  10122.   %@AS@%            .%@AE@%%@NL@%
  10123.   %@AS@%            .%@AE@%%@NL@%
  10124.   %@AS@%            ELSE%@AE@%%@NL@%
  10125.   %@AS@%            .ERR%@AE@%%@NL@%
  10126.   %@AS@%            %OUT dos or xenix must be defined%@AE@%%@NL@%
  10127.   %@AS@%            ENDIF%@AE@%%@NL@%
  10128.   %@AS@%            ENDIF%@AE@%%@NL@%
  10129. %@NL@%
  10130. %@4@%  This example makes sure that either the symbol %@AS@%dos%@AE@% or the symbol %@AS@%xenix%@AE@% is%@EH@%
  10131.   defined. If neither is defined, the nested %@AB@%ELSE%@AE@% condition is assembled and
  10132.   an error message is generated. Since the %@AB@%.ERR%@AE@% directive is used, an error
  10133.   would be generated on each pass. You could use %@AB@%.ERR1%@AE@% or %@AB@%.ERR2%@AE@% to check if
  10134.   you want the error to be generated only on the corresponding pass.%@NL@%
  10135. %@NL@%
  10136. %@NL@%
  10137. %@3@%%@CR:SC10.2.2    @%%@AB@%10.2.2  Testing Expressions with .ERRE or .ERRNZ Directives%@AE@%%@EH@%%@NL@%
  10138. %@NL@%
  10139. %@4@%%@CR:IX10.55     @%%@CR:IX10.56     @%%@CR:IX10.57     @%%@CR:IX10.58     @%%@CR:IX10.59     @%  The %@AB@%.ERRE%@AE@% and%@AB@% .ERRNZ%@AE@% directives test the value of an expression and%@EH@%
  10140.   conditionally generate an error based on the result.%@NL@%
  10141. %@NL@%
  10142. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10143. %@NL@%
  10144. %@4@%  %@AB@%.ERRE%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  10145.   %@AB@%.ERRNZ%@AE@% %@AI@%expression%@AE@%%@NL@%
  10146. %@NL@%
  10147. %@4@%%@CR:IX10.60     @%  The %@AB@%.ERRE%@AE@% directive generates an error if %@AI@%expression%@AE@% is false (0). The%@EH@%
  10148.   %@AB@%.ERRNZ%@AE@% directive generates an error if %@AI@%expression%@AE@% is true (nonzero). The
  10149.   expression must evaluate to a constant value and must not contain forward
  10150.   references.%@NL@%
  10151. %@NL@%
  10152. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10153. %@NL@%
  10154.   %@AS@%buffer      MACRO   count,bname%@AE@%%@NL@%
  10155.   %@AS@%            .ERRE   count LE 128       ;; Allocate memory, but%@AE@%%@NL@%
  10156.   %@AS@%bname       DB      count DUP(0)       ;;   no more than 128 bytes%@AE@%%@NL@%
  10157.   %@AS@%            ENDM%@AE@%%@NL@%
  10158.   %@AS@%            .%@AE@%%@NL@%
  10159.   %@AS@%            .%@AE@%%@NL@%
  10160.   %@AS@%            .%@AE@%%@NL@%
  10161.   %@AS@%            buffer  128,buf1           ; Data allocated - no error%@AE@%%@NL@%
  10162.   %@AS@%            buffer  129,buf2           ; Error generated%@AE@%%@NL@%
  10163. %@NL@%
  10164. %@4@%  In this example, the %@AB@%.ERRE%@AE@% directive is used to check the boundaries of a%@EH@%
  10165.   parameter passed to the macro %@AS@%buffer%@AE@%. If %@AS@%count%@AE@% is less than or equal to
  10166.   %@AS@%128%@AE@%, the expression being tested by the error directive will be true
  10167.   (nonzero) and no error will be generated. If %@AS@%count%@AE@% is greater than %@AS@%128%@AE@%,
  10168.   the expression will be false (0) and the error will be generated.%@NL@%
  10169. %@NL@%
  10170. %@NL@%
  10171. %@3@%%@CR:SC10.2.3    @%%@AB@%10.2.3  Verifying Symbol Definition with .ERRDEF and .ERRNDEF Directives%@AE@%%@EH@%%@NL@%
  10172. %@NL@%
  10173. %@4@%%@CR:IX10.61     @%%@CR:IX10.62     @%%@CR:IX10.63     @%%@CR:IX10.64     @%%@CR:IX10.65     @%  The %@AB@%.ERRDEF%@AE@% and %@AB@%.ERRNDEF%@AE@% directives test whether a symbol is defined and%@EH@%
  10174.   conditionally generate an error based on the result.%@NL@%
  10175. %@NL@%
  10176. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10177. %@NL@%
  10178. %@4@%  %@AB@%.ERRDEF%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@%
  10179.   %@AB@%.ERRNDEF%@AE@% %@AI@%name%@AE@%%@NL@%
  10180. %@NL@%
  10181. %@4@%  The %@AB@%.ERRDEF%@AE@% directive produces an error if %@AI@%name%@AE@% is defined as a label,%@EH@%
  10182.   variable, or symbol. The %@AB@%.ERRNDEF%@AE@% directive produces an error if %@AI@%name%@AE@% has
  10183.   not yet been defined. If %@AI@%name%@AE@% is a forward reference, it is considered
  10184.   undefined on pass 1, but defined on pass 2.%@NL@%
  10185. %@NL@%
  10186. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10187. %@NL@%
  10188.   %@AS@%            .ERRNDEF publevel%@AE@%%@NL@%
  10189.   %@AS@%            IF       publevel LE 2%@AE@%%@NL@%
  10190.   %@AS@%            PUBLIC   var1, var2%@AE@%%@NL@%
  10191.   %@AS@%            ELSE%@AE@%%@NL@%
  10192.   %@AS@%            PUBLIC   var1, var2, var3%@AE@%%@NL@%
  10193.   %@AS@%            ENDIF%@AE@%%@NL@%
  10194. %@NL@%
  10195. %@4@%  In this example, the %@AB@%.ERRNDEF%@AE@% directive at the beginning of the%@EH@%
  10196.   conditional block makes sure that a symbol being tested in the block
  10197.   actually exists.%@NL@%
  10198. %@NL@%
  10199. %@NL@%
  10200. %@3@%%@CR:SC10.2.4    @%%@AB@%10.2.4  Testing for Macro Parameters with .ERRB and .ERRNB Directives%@AE@%%@EH@%%@NL@%
  10201. %@NL@%
  10202. %@4@%%@CR:IX10.66     @%%@CR:IX10.67     @%%@CR:IX10.68     @%%@CR:IX10.69     @%%@CR:IX10.70     @%  The %@AB@%.ERRB%@AE@% and %@AB@%.ERRNB%@AE@% directives test whether a specified argument was%@EH@%
  10203.   passed to a macro and conditionally generate an error based on the result.
  10204. %@NL@%
  10205. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10206. %@NL@%
  10207. %@4@%  %@AB@%.ERRB%@AE@% %@AB@%<%@AE@%%@AI@%argument%@AE@%%@AB@%>%@AE@%%@EH@%%@NL@%
  10208.   %@AB@%.ERRNB%@AE@% %@AB@%<%@AE@%%@AI@%argument%@AE@%%@AB@%>%@AE@%%@NL@%
  10209. %@NL@%
  10210. %@4@%  These directives are always used inside macros, and they always test%@EH@%
  10211.   whether a real argument was passed for a specified dummy argument. The
  10212.   %@AB@%.ERRB%@AE@% directive generates an error if %@AI@%argument%@AE@% is blank. The %@AB@%.ERRNB%@AE@%
  10213.   directive generates an error if %@AI@%argument%@AE@% is not blank. The argument can be
  10214.   any name, number, or expression. Angle brackets (%@AB@%<>%@AE@%) are required.%@NL@%
  10215. %@NL@%
  10216. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10217. %@NL@%
  10218.   %@AS@%work        MACRO   realarg,testarg%@AE@%%@NL@%
  10219.   %@AS@%            .ERRB   <realarg>       ;; Error if no parameters%@AE@%%@NL@%
  10220.   %@AS@%            .ERRNB  <testarg>       ;; Error if more than one parameter%@AE@%%@NL@%
  10221.   %@AS@%            .%@AE@%%@NL@%
  10222.   %@AS@%            .%@AE@%%@NL@%
  10223.   %@AS@%            .%@AE@%%@NL@%
  10224.   %@AS@%            ENDM%@AE@%%@NL@%
  10225. %@NL@%
  10226. %@4@%  In this example, error directives are used to make sure that one, and only%@EH@%
  10227.   one, argument is passed to the macro. The %@AB@%.ERRB%@AE@% directive generates an
  10228.   error if no argument is passed to the macro. The %@AB@%.ERRNB%@AE@% directive
  10229.   generates an error if more than one argument is passed to the macro.%@NL@%
  10230. %@NL@%
  10231. %@NL@%
  10232. %@3@%%@CR:SC10.2.5    @%%@AB@%10.2.5  Comparing Macro Arguments with .ERRIDN and .ERRDIF Directives%@AE@%%@EH@%%@NL@%
  10233. %@NL@%
  10234. %@4@%%@CR:IX10.71     @%%@CR:IX10.72     @%%@CR:IX10.73     @%%@CR:IX10.74     @%%@CR:IX10.75     @%%@CR:IX10.76     @%  The %@AB@%.ERRIDN%@AE@% and %@AB@%.ERRDIF%@AE@% directives compare two macro arguments and%@EH@%
  10235.   conditionally generate an error based on the result.%@NL@%
  10236. %@NL@%
  10237. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10238. %@NL@%
  10239. %@4@%  %@AB@%.ERRIDN%@AE@%[[%@AB@%I%@AE@%]] %@AB@%<%@AE@%%@AI@%argument1%@AE@%%@AB@%>,<%@AE@%%@AI@%argument2%@AE@%%@AB@%>%@AE@%%@EH@%%@NL@%
  10240.   %@AB@%.ERRDIF%@AE@%[[%@AB@%I%@AE@%]] %@AB@%<%@AE@%%@AI@%argument1%@AE@%%@AB@%>,<%@AE@%%@AI@%argument2%@AE@%%@AB@%>%@AE@%%@NL@%
  10241. %@NL@%
  10242. %@4@%  These directives are always used inside macros, and they always compare%@EH@%
  10243.   the real arguments specified for two parameters. The %@AB@%.ERRIDN%@AE@% directive
  10244.   generates an error if the arguments are identical. The %@AB@%.ERRDIF%@AE@% directive
  10245.   generates an error if the arguments are different. The arguments can be
  10246.   names, numbers, or expressions. They must be enclosed in angle brackets
  10247.   and separated by a comma.%@NL@%
  10248. %@NL@%
  10249. %@4@%  The optional %@AB@%I%@AE@% at the end of the directive name specifies that the%@EH@%
  10250.   directive is case insensitive. Arguments that are spelled the same will be
  10251.   evaluated the same regardless of case. If the %@AB@%I%@AE@% is not given, the
  10252.   directive is case sensitive.%@NL@%
  10253. %@NL@%
  10254. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10255. %@NL@%
  10256.   %@AS@%addem       MACRO    ad1,ad2,sum%@AE@%%@NL@%
  10257.   %@AS@%            .ERRIDNI <ax>,<ad2>    ;; Error if ad2 is "ax"%@AE@%%@NL@%
  10258.   %@AS@%            mov      ax,ad1        ;; Would overwrite if ad2 were AX%@AE@%%@NL@%
  10259.   %@AS@%            add      ax,ad2%@AE@%%@NL@%
  10260.   %@AS@%            mov      sum,ax        ;; Sum must be register or memory%@AE@%%@NL@%
  10261.   %@AS@%            ENDM%@AE@%%@NL@%
  10262. %@NL@%
  10263. %@4@%  In this example, the %@AB@%.ERRIDNI%@AE@% directive is used to protect against passing%@EH@%
  10264.   the AX register as the second parameter, since this would cause the macro
  10265.   to fail.%@NL@%
  10266. %@NL@%
  10267. %@NL@%
  10268. %@NL@%
  10269. ────────────────────────────────────────────────────────────────────────────%@NL@%
  10270. %@1@%%@CR:CH11        @%%@AB@%Chapter 11:  Using Equates, Macros, and Repeat Blocks%@AE@%%@EH@%%@NL@%
  10271. %@NL@%
  10272. %@NL@%
  10273. %@4@%%@CR:IX11.1      @%%@CR:IX11.2      @%%@CR:IX11.3      @%  This chapter explains how to use equates, macros, and repeat blocks.%@EH@%
  10274.   "Equates" are constant values assigned to symbols so that the symbol can
  10275.   be used in place of the value. "Macros" are a series of statements that
  10276.   are assigned a symbolic name (and, optionally, parameters) so that the
  10277.   symbol can be used in place of the statements. "Repeat blocks" are a
  10278.   special form of macro used to do repeated statements.%@NL@%
  10279. %@NL@%
  10280. %@4@%  Both equates and macros are processed at assembly time. They can simplify%@EH@%
  10281.   writing source code by allowing the user to substitute mnemonic names for
  10282.   constants and repetitive code. By changing a macro or equate, a programmer
  10283.   can change the effect of statements throughout the source code.%@NL@%
  10284. %@NL@%
  10285. %@4@%%@CR:IX11.4      @%  In exchange for these conveniences, the programmer loses some%@EH@%
  10286.   assembly-time efficiency. Assembly may be slightly slower for a program
  10287.   that uses macros and equates extensively than for the same program written
  10288.   without them. However, the program without macros and equates usually
  10289.   takes longer to write and is more difficult to maintain.%@NL@%
  10290. %@NL@%
  10291. %@NL@%
  10292. %@2@%%@CR:SC11.1      @%%@AB@%11.1  Using Equates%@AE@%%@EH@%%@NL@%
  10293. %@NL@%
  10294. %@4@%%@CR:IX11.5      @%  The equate directives enable you to use symbols that represent numeric or%@EH@%
  10295.   string constants. QuickAssembler recognizes three kinds of equates:%@NL@%
  10296. %@NL@%
  10297.   1. Redefinable numeric equates%@NL@%
  10298. %@NL@%
  10299.   2. Nonredefinable numeric equates%@NL@%
  10300. %@NL@%
  10301.   3. String equates (also called text macros)%@NL@%
  10302. %@NL@%
  10303. %@NL@%
  10304. %@3@%%@CR:SC11.1.1    @%%@AB@%11.1.1  Redefinable Numeric Equates%@AE@%%@EH@%%@NL@%
  10305. %@NL@%
  10306. %@4@%%@CR:IX11.6      @%%@CR:IX11.7      @%%@CR:IX11.8      @%%@CR:IX11.9      @%%@CR:IX11.10     @%  Redefinable numeric equates are used to assign a numeric constant to a%@EH@%
  10307.   symbol. The value of the symbol can be redefined at any point during
  10308.   assembly time. Although the value of a redefinable equate may be different
  10309.   at different points in the source code, a constant value will be assigned
  10310.   for each use, and that value will not change at run time.%@NL@%
  10311. %@NL@%
  10312. %@4@%  Redefinable equates are often used for assembly-time calculations in%@EH@%
  10313.   macros and repeat blocks.%@NL@%
  10314. %@NL@%
  10315. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10316. %@NL@%
  10317. %@4@%  %@AI@%name%@AE@%%@AB@%=%@AE@%%@AI@%expression%@AE@%%@EH@%%@NL@%
  10318. %@NL@%
  10319. %@4@%  The equal-sign (%@AB@%=%@AE@%) directive creates or redefines a constant symbol by%@EH@%
  10320.   assigning the numeric value of %@AI@%expression%@AE@% to %@AI@%name%@AE@%. No storage is allocated
  10321.   for the symbol. The symbol can be used in subsequent statements as an
  10322.   immediate operand having the assigned value. It can be redefined at any
  10323.   time.%@NL@%
  10324. %@NL@%
  10325. %@4@%  The expression can be an integer, a constant expression, a one- or%@EH@%
  10326.   two-character string constant, or an expression that evaluates to an
  10327.   address. The name must be either a unique name or a name previously
  10328.   defined by using the equal-sign (%@AB@%=%@AE@%) directive.%@NL@%
  10329. %@NL@%
  10330.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10331.   %@AB@%NOTE%@AE@%  Redefinable equates must be assigned numeric values. String
  10332.   constants longer than two characters cannot be used.%@NL@%
  10333.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10334. %@NL@%
  10335. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10336. %@NL@%
  10337.   %@AS@%counter     =       0                  ; Initialize counter%@AE@%%@NL@%
  10338.   %@AS@%array       LABEL   BYTE               ; Label array of increasing numbers%@AE@%%@NL@%
  10339.   %@AS@%            REPT    100                ; Repeat 100 times%@AE@%%@NL@%
  10340.   %@AS@%            DB      counter            ; Initialize number%@AE@%%@NL@%
  10341.   %@AS@%counter     =       counter + 1        ; Increment counter%@AE@%%@NL@%
  10342.   %@AS@%            ENDM%@AE@%%@NL@%
  10343. %@NL@%
  10344. %@4@%  This example redefines equates inside a repeat block to declare an array%@EH@%
  10345.   initialized to increasing values from%@AS@% 0 %@AE@%to%@AS@% 100%@AE@%. The equal-sign directive
  10346.   is used to increment the %@AS@%counter %@AE@%symbol for each loop. See Section 11.4%@BO:       982dc@%
  10347.   for more information on repeat blocks.%@NL@%
  10348. %@NL@%
  10349. %@NL@%
  10350. %@3@%%@CR:SC11.1.2    @%%@AB@%11.1.2  Nonredefinable Numeric Equates%@AE@%%@EH@%%@NL@%
  10351. %@NL@%
  10352. %@4@%%@CR:IX11.11     @%%@CR:IX11.12     @%%@CR:IX11.13     @%%@CR:IX11.14     @%  Nonredefinable numeric equates are used to assign a numeric constant to a%@EH@%
  10353.   symbol. The value of the symbol cannot be redefined.%@NL@%
  10354. %@NL@%
  10355. %@4@%  Nonredefinable numeric equates are often used for assigning mnemonic names%@EH@%
  10356.   to constant values. This can make the code more readable and easier to
  10357.   maintain. If a constant value used in numerous places in the source code
  10358.   needs to be changed, the equate can be changed in one place rather than
  10359.   throughout the source code.%@NL@%
  10360. %@NL@%
  10361. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10362. %@NL@%
  10363. %@4@%  %@AI@%name%@AE@% %@AB@%EQU%@AE@% %@AI@%expression%@AE@%%@EH@%%@NL@%
  10364. %@NL@%
  10365. %@4@%  The %@AB@%EQU%@AE@% directive creates constant symbols by assigning %@AI@%expression%@AE@% to%@EH@%
  10366.   %@AI@%name%@AE@%. The assembler replaces each subsequent occurrence of %@AI@%name%@AE@% with the
  10367.   value of %@AI@%expression%@AE@%. Once a numeric equate has been defined with the %@AB@%EQU%@AE@%
  10368.   directive, it cannot be redefined. Attempting to do so generates an error.%@NL@%
  10369. %@NL@%
  10370.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10371.   %@AB@%NOTE%@AE@%  String constants can also be defined with the %@AB@%EQU %@AE@%directive, but the
  10372.   syntax is different, as described in Section 11.1.3%@BO:       8f1c6@%, "String Equates."%@NL@%
  10373.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10374. %@NL@%
  10375. %@4@%  No storage is allocated for the symbol. Symbols defined with numeric%@EH@%
  10376.   values can be used in subsequent statements as immediate operands having
  10377.   the assigned value.%@NL@%
  10378. %@NL@%
  10379. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  10380. %@NL@%
  10381.   %@AS@%column      EQU     80                 ; Numeric constant 80%@AE@%%@NL@%
  10382.   %@AS@%row         EQU     25                 ; Numeric constant 25%@AE@%%@NL@%
  10383.   %@AS@%screenful   EQU     column * row       ; Numeric constant 2000%@AE@%%@NL@%
  10384.   %@AS@%line        EQU     row                ; Alias for "row"%@AE@%%@NL@%
  10385. %@NL@%
  10386.   %@AS@%            .DATA%@AE@%%@NL@%
  10387.   %@AS@%buffer      DW      screenful%@AE@%%@NL@%
  10388. %@NL@%
  10389.   %@AS@%            .CODE%@AE@%%@NL@%
  10390.   %@AS@%            .%@AE@%%@NL@%
  10391.   %@AS@%            .%@AE@%%@NL@%
  10392.   %@AS@%            .%@AE@%%@NL@%
  10393.   %@AS@%            mov     cx,column%@AE@%%@NL@%
  10394.   %@AS@%            mov     bx,line%@AE@%%@NL@%
  10395. %@NL@%
  10396. %@NL@%
  10397. %@3@%%@CR:SC11.1.3    @%%@AB@%11.1.3  String Equates%@AE@%%@EH@%%@NL@%
  10398. %@NL@%
  10399. %@4@%%@CR:IX11.15     @%%@CR:IX11.16     @%%@CR:IX11.17     @%%@CR:IX11.18     @%%@CR:IX11.19     @%%@CR:IX11.20     @%  String equates (or text macros) are used to assign a string constant to a%@EH@%
  10400.   symbol. String equates can be used in a variety of contexts, including
  10401.   defining aliases and string constants.%@NL@%
  10402. %@NL@%
  10403. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10404. %@NL@%
  10405. %@4@%  %@AI@%name%@AE@% %@AB@%EQU%@AE@%{%@AI@%string%@AE@% | %@AB@%<%@AE@%%@AI@%string%@AE@%%@AB@%>%@AE@%}%@EH@%%@NL@%
  10406. %@NL@%
  10407. %@4@%  The %@AB@%EQU%@AE@% directive creates constant symbols by assigning %@AI@%string%@AE@% to %@AI@%name%@AE@%.%@EH@%
  10408.   The assembler replaces each subsequent occurrence of %@AI@%name%@AE@% with %@AI@%string%@AE@%.
  10409.   Symbols defined to represent strings with the %@AB@%EQU%@AE@% directive can be
  10410.   redefined to new strings. Symbols cannot be defined to represent strings
  10411.   with the equal-sign (%@AB@%=%@AE@%) directive.%@NL@%
  10412. %@NL@%
  10413. %@4@%%@CR:IX11.21     @%  An alias is a special kind of string equate. It is a symbol that is%@EH@%
  10414.   equated to another symbol or keyword.%@NL@%
  10415. %@NL@%
  10416. %@4@%  If you want an equate to be a string equate, you should use angle brackets%@EH@%
  10417.   to force the assembler to evaluate it as a string. If you do not use angle
  10418.   brackets, the assembler will try to guess from context whether a numric or
  10419.   string equate is appropriate. This can lead to unexpected results. For
  10420.   example, the statement%@NL@%
  10421. %@NL@%
  10422.   %@AS@%rt          EQU      run-time%@AE@%%@NL@%
  10423. %@NL@%
  10424. %@4@%  would be evaluated as %@AS@%run %@AE@%minus %@AS@%time%@AE@%, even though the user might intend to%@EH@%
  10425.   define the string %@AS@%run-time%@AE@%. If %@AS@%run %@AE@%and %@AS@%time %@AE@%were not already defined as
  10426.   numeric equates, the statement would generate an error. Using angle
  10427.   brackets solves this problem. The statement%@NL@%
  10428. %@NL@%
  10429.   %@AS@%rt          EQU      <run-time>%@AE@%%@NL@%
  10430. %@NL@%
  10431. %@4@%  is evaluated as the string %@AS@%run-time%@AE@%.%@EH@%%@NL@%
  10432. %@NL@%
  10433. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  10434. %@NL@%
  10435.   %@AS@%;String equate definitions%@AE@%%@NL@%
  10436.   %@AS@%pi          EQU      <3.1415>           ; String constant "3.1415"%@AE@%%@NL@%
  10437.   %@AS@%prompt      EQU      <'Type Name: '>    ; String constant "'Type Name: '",%@AE@%%@NL@%
  10438.   %@AS@%WPT         EQU      <WORD PTR>         ; String constant for "WORD PTR"%@AE@%%@NL@%
  10439.   %@AS@%argl        EQU      <[bp+4]>           ; String constant for "[bp+4]"%@AE@%%@NL@%
  10440. %@NL@%
  10441.   %@AS@%; Use of string equates%@AE@%%@NL@%
  10442.   %@AS@%            .DATA%@AE@%%@NL@%
  10443.   %@AS@%message     DB       prompt             ; Allocate string "Type Name:"%@AE@%%@NL@%
  10444.   %@AS@%pie         DQ       pi                 ; Allocate real number 3.1415%@AE@%%@NL@%
  10445. %@NL@%
  10446.   %@AS@%            .CODE%@AE@%%@NL@%
  10447.   %@AS@%            .%@AE@%%@NL@%
  10448.   %@AS@%            .%@AE@%%@NL@%
  10449.   %@AS@%            .%@AE@%%@NL@%
  10450.   %@AS@%            inc      WPT parm1          ; Increment word value of%@AE@%%@NL@%
  10451.   %@AS@%                                        ;   argument passed on stack%@AE@%%@NL@%
  10452. %@NL@%
  10453. %@4@%  Section 11.3%@BO:       95341@%, "Text-Macro String Directives," describes directives that%@EH@%
  10454.   enable you to manipulate strings. They are particularly powerful when you
  10455.   use them from within macros and repeat blocks, described later.%@NL@%
  10456. %@NL@%
  10457. %@NL@%
  10458. %@3@%%@CR:SC11.1.4    @%%@AB@%11.1.4  Predefined Equates%@AE@%%@EH@%%@NL@%
  10459. %@NL@%
  10460. %@4@%  The assembler includes several predefined equates. The ones related to%@EH@%
  10461.   segments are described in Section 5.1.5%@BO:       47722@%, "Using Predefined Segment
  10462.   Equates." In addition, the following equates are available: %@AB@%@WordSize%@AE@%,
  10463.   %@AB@%@Cpu%@AE@%, and %@AB@%@Version%@AE@%.%@NL@%
  10464. %@NL@%
  10465. %@4@%%@CR:IX11.22     @%%@CR:IX11.23     @%  The%@AB@% @WordSize%@AE@% equate returns the size of a word for the current segment.%@EH@%
  10466.   With QuickAssembler, this value is always equal to 2. However, other
  10467.   versions of the assembler can assign a different value to %@AB@%@WordSize%@AE@% when
  10468.   working with 80386 extended features.%@NL@%
  10469. %@NL@%
  10470.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10471.   %@AB@%NOTE%@AE@%  If you set the Preserve Case assembler flag or use the /Cl option,
  10472.   QuickAssembler considers predefined equates to be case-sensitive. The
  10473.   case-sensitive names of predefined equates are %@AB@%@WordSize%@AE@%, %@AB@%@Cpu%@AE@%, %@AB@%@Version%@AE@%,
  10474.   %@AB@%@CurSeg%@AE@%, %@AB@%@FileName%@AE@%, %@AB@%@CodeSize%@AE@%, %@AB@%@DataSize%@AE@%, %@AB@%@Model%@AE@%, %@AB@%@data%@AE@%, %@AB@%@data?%@AE@%, %@AB@%@fardata%@AE@%,
  10475.   %@AB@%@fardata?%@AE@%, and %@AB@%@code%@AE@%.%@NL@%
  10476.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10477. %@NL@%
  10478. %@4@%%@CR:IX11.24     @%%@CR:IX11.25     @%  The%@AB@% @Cpu%@AE@% equate returns a 16-bit value containing information about the%@EH@%
  10479.   selected processor. You select a processor by using one of the processor
  10480.   directives, such as the %@AB@%.286%@AE@% directive. You can use the %@AB@%@Cpu%@AE@% text macro to
  10481.   control assembly of processor-specific code. Individual bits in the value
  10482.   returned by %@AB@%@Cpu%@AE@% indicate information about the selected processor.%@NL@%
  10483. %@NL@%
  10484.   %@AB@%Bit%@AE@%                 %@AB@%If Bit = 1%@AE@%%@NL@%
  10485.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10486.   0                   8086 processor%@NL@%
  10487. %@NL@%
  10488.   1                   80186 processor%@NL@%
  10489. %@NL@%
  10490.   2                   80286 processor%@NL@%
  10491. %@NL@%
  10492.   8                   8087 coprocessor instructions enabled%@NL@%
  10493. %@NL@%
  10494.   10                  80287 coprocessor instructions enabled%@NL@%
  10495. %@NL@%
  10496. %@NL@%
  10497. %@4@%  Because the processors are upwardly compatible, selecting a%@EH@%
  10498.   higher-numbered processor automatically sets the bits indicating
  10499.   lower-numbered processors. For example, selecting an 80286 processor
  10500.   automatically sets the 80186 and 8086 bits.%@NL@%
  10501. %@NL@%
  10502. %@4@%  Bits 4 through 6, 9, and 12 through 15 are reserved for future use and%@EH@%
  10503.   should be masked off when testing. Bits 3, 7, and 11 have special meaning
  10504.   to Versions 5.1 and later of the Microsoft Macro Assembler: bit 3
  10505.   indicates an 80386 processor, bit 7 indicates privilege mode enabled, and
  10506.   bit 11 indicates that 80387 coprocessor instructions are enabled.%@NL@%
  10507. %@NL@%
  10508.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10509.   %@AB@%NOTE%@AE@%  The %@AB@%@Cpu%@AE@% equate only provides information about the processor
  10510.   selected during assembly by one of the processor directives. It does not
  10511.   provide information about the processor actually used when a program is
  10512.   run.%@NL@%
  10513.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10514. %@NL@%
  10515. %@4@%  The following example uses the %@AB@%@Cpu %@AE@%text macro to select more efficient%@EH@%
  10516.   instructions available only on the 80186 processor and above:%@NL@%
  10517. %@NL@%
  10518.   %@AS@%; Use the 186/286/386 pusha instruction if possible%@AE@%%@NL@%
  10519.   %@AS@%P186        EQU (@Cpu AND 0002h)           ; Only test 186 bit--286 and%@AE@%%@NL@%
  10520.   %@AS@%                                           ;   386 set 186 bit as well%@AE@%%@NL@%
  10521.   %@AS@%            .%@AE@%%@NL@%
  10522.   %@AS@%            .%@AE@%%@NL@%
  10523.   %@AS@%            .%@AE@%%@NL@%
  10524. %@NL@%
  10525.   %@AS@%            IF P186                         ; Non-zero if 186 processor%@AE@%%@NL@%
  10526.   %@AS@%               pusha                        ;   or above%@AE@%%@NL@%
  10527.   %@AS@%            ELSE%@AE@%%@NL@%
  10528.   %@AS@%               push ax                      ; Do what the single%@AE@%%@NL@%
  10529.   %@AS@%               push cx                      ;   pusha instruction does%@AE@%%@NL@%
  10530.   %@AS@%               push dx%@AE@%%@NL@%
  10531.   %@AS@%               push bx%@AE@%%@NL@%
  10532.   %@AS@%               push sp%@AE@%%@NL@%
  10533.   %@AS@%               push bp%@AE@%%@NL@%
  10534.   %@AS@%               push si%@AE@%%@NL@%
  10535.   %@AS@%               push di%@AE@%%@NL@%
  10536.   %@AS@%            ENDIF%@AE@%%@NL@%
  10537. %@NL@%
  10538. %@4@%%@CR:IX11.26     @%%@CR:IX11.27     @%  The %@AB@%@Version%@AE@% equate returns the version of the assembler in use. With the%@EH@%
  10539.   %@AB@%@Version%@AE@% equate, you can write macros that take appropriate actions for
  10540.   different versions of the assembler. Currently, the %@AB@%@Version%@AE@% equate
  10541.   returns 520 as a string of three characters.%@NL@%
  10542. %@NL@%
  10543.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10544.   %@AB@%NOTE%@AE@%  Although the version number of QuickAssembler is 2.01, the %@AB@%@Version%@AE@%
  10545.   equate returns 520 rather than 201. The number 520 was selected because
  10546.   QuickAssembler is an enhancement of Version 5.1 of the Microsoft Macro
  10547.   Assembler.%@AB@% %@AE@%The %@AB@%@Version %@AE@%equate was first assembled for Version 5.1.%@NL@%
  10548.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10549. %@NL@%
  10550. %@4@%  You can use the %@AB@%IF%@AE@% and%@AB@% IFE%@AE@% conditional assembly directives to test for%@EH@%
  10551.   different versions of the assembler and to assemble different code
  10552.   depending on the version.%@NL@%
  10553. %@NL@%
  10554.   %@AS@%IFNDEF       @Version%@AE@%%@NL@%
  10555.   %@AS@%   %OUT MASM 5.0 or earlier has no extended PROC or .STARTUP%@AE@%%@NL@%
  10556.   %@AS@%ELSEIF       @Version EQ 510%@AE@%%@NL@%
  10557.   %@AS@%   %OUT MASM 5.1 has extended PROC, but not .STARTUP%@AE@%%@NL@%
  10558.   %@AS@%ELSEIF       @Version EQ 520%@AE@%%@NL@%
  10559.   %@AS@%   %OUT QuickAssembler 2.01 has extended PROC and .STARTUP%@AE@%%@NL@%
  10560.   %@AS@%ELSE%@AE@%%@NL@%
  10561.   %@AS@%   %OUT Future assembler%@AE@%%@NL@%
  10562.   %@AS@%ENDIF%@AE@%%@NL@%
  10563. %@NL@%
  10564. %@NL@%
  10565. %@2@%%@CR:SC11.2      @%%@AB@%11.2  Using Macros%@AE@%%@EH@%%@NL@%
  10566. %@NL@%
  10567. %@4@%%@CR:IX11.28     @%  Macros enable you to assign a symbolic name to a block of source%@EH@%
  10568.   statements and then to use that name in your source file to represent the
  10569.   statements. Parameters can also be defined to represent arguments passed
  10570.   to the macro.%@NL@%
  10571. %@NL@%
  10572. %@4@%  Macro expansion is a text-processing function that occurs at assembly%@EH@%
  10573.   time. Each time QuickAssembler encounters the text associated with a macro
  10574.   name, it replaces that text with the text of the statements in the macro
  10575.   definition. Similarly, the text of parameter names is replaced with the
  10576.   text of the corresponding actual arguments.%@NL@%
  10577. %@NL@%
  10578. %@4@%%@CR:IX11.29     @%%@CR:IX11.30     @%  A macro can be defined any place in the source file as long as the%@EH@%
  10579.   definition precedes the first source line that calls the macro. Macros and
  10580.   equates are often kept in a separate file and made available to the
  10581.   program through an %@AB@%INCLUDE%@AE@% directive (see Section 11.7.1%@BO:       a0d21@%, "Using Include
  10582.   Files") at the start of the source code.%@NL@%
  10583. %@NL@%
  10584. %@4@%%@CR:IX11.31     @%%@CR:IX11.32     @%  Often a task can be done by using either a macro or procedure. For%@EH@%
  10585.   example, the %@AS@%addup %@AE@%procedure shown in Section 15.3.3%@BO:       c60b0@%, "Passing Arguments
  10586.   on the Stack," does the same thing as the %@AS@%addup%@AE@% macro in Section 11.2.1%@BO:       91f51@%,
  10587.   "Defining Macros." Macros are expanded on every occurrence of the macro
  10588.   name, so they can increase the length of the executable file if called
  10589.   repeatedly. Procedures are coded only once in the executable file, but the
  10590.   increased overhead of saving and restoring addresses and parameters can
  10591.   make them slower.%@NL@%
  10592. %@NL@%
  10593. %@4@%  The section below tells how to define and call macros. Repeat blocks, a%@EH@%
  10594.   special form of macro for doing repeated operations, are discussed
  10595.   separately in Section 11.4%@BO:       982dc@%.%@NL@%
  10596. %@NL@%
  10597. %@NL@%
  10598. %@3@%%@CR:SC11.2.1    @%%@AB@%11.2.1  Defining Macros%@AE@%%@EH@%%@NL@%
  10599. %@NL@%
  10600. %@4@%%@CR:IX11.33     @%%@CR:IX11.34     @%%@CR:IX11.35     @%%@CR:IX11.36     @%  The %@AB@%MACRO%@AE@% and %@AB@%ENDM%@AE@% directives are used to define macros. %@AB@%MACRO%@AE@% designates%@EH@%
  10601.   the beginning of the macro block, and %@AB@%ENDM%@AE@% designates the end of the macro
  10602.   block.%@NL@%
  10603. %@NL@%
  10604. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10605. %@NL@%
  10606. %@4@%  %@AI@%name%@AE@% %@AB@%MACRO%@AE@% [[%@AI@%parameter%@AE@% [[%@AB@%,%@AE@%%@AI@%parameter%@AE@%]]...]]%@EH@%%@NL@%
  10607.   %@AI@%statements%@AE@%%@NL@%
  10608.   %@AB@%ENDM%@AE@%%@NL@%
  10609. %@NL@%
  10610. %@4@%  The %@AI@%name%@AE@% must be unique and a valid symbol name. It can be used later in%@EH@%
  10611.   the source file to invoke the macro.%@NL@%
  10612. %@NL@%
  10613. %@4@%%@CR:IX11.37     @%%@CR:IX11.38     @%%@CR:IX11.39     @%%@CR:IX11.40     @%%@CR:IX11.41     @%  The %@AI@%parameters%@AE@% (sometimes called dummy parameters) are names that act as%@EH@%
  10614.   placeholders for values to be passed as arguments to the macro when it is
  10615.   called. Any number of parameters can be specified, but they must all fit
  10616.   on one line. If you give more than one parameter, you must separate them
  10617.   with commas, spaces, or tabs. Commas can always be used as separators;
  10618.   spaces and tabs may cause ambiguity if the arguments are expressions.%@NL@%
  10619. %@NL@%
  10620.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10621.   %@AB@%NOTE%@AE@%  This manual uses the term "parameter" to refer to a placeholder for
  10622.   a value that will be passed to a macro or procedure. Parameters appear in
  10623.   macro or procedure definitions. The term "argument" is used to refer to an
  10624.   actual value passed to the macro or procedure when it is called.%@NL@%
  10625.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10626. %@NL@%
  10627. %@4@%  Any valid assembler statements may be placed within a macro, including%@EH@%
  10628.   statements that call or define other macros. Any number of statements can
  10629.   be used. The parameters can be used any number of times in the statements.
  10630.   Macros can be nested, redefined, or used recursively, as explained in
  10631.   Section 11.6%@BO:       9e5c9@%, "Using Recursive, Nested, and Redefined Macros."%@NL@%
  10632. %@NL@%
  10633. %@4@%  QuickAssembler assembles the statements in a macro only if the macro is%@EH@%
  10634.   called and only at the point in the source file from which it is called.
  10635.   The macro definition itself is never assembled.%@NL@%
  10636. %@NL@%
  10637. %@4@%  A macro definition can include the %@AB@%LOCAL%@AE@% directive, which lets you define%@EH@%
  10638.   labels used only within a macro, or the %@AB@%EXITM%@AE@% directive, which allows you
  10639.   to exit from a macro before all the statements in the block are expanded.
  10640.   These directives are discussed in Sections 11.2.3%@BO:       93a20@%, "Using Local Symbols,"
  10641.   and 11.2.4%@BO:       93a20@%, "Exiting from a Macro." Macro operators can also be used in
  10642.   macro definitions, as described in Section 11.5%@BO:       9a1b8@%, "Using Macro Operators."%@NL@%
  10643. %@NL@%
  10644. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10645. %@NL@%
  10646.   %@AS@%addup       MACRO   ad1,ad2,ad3%@AE@%%@NL@%
  10647.   %@AS@%            mov     ax,ad1      ;; First parameter in AX%@AE@%%@NL@%
  10648.   %@AS@%            add     ax,ad2      ;; Add next two parameters%@AE@%%@NL@%
  10649.   %@AS@%            add     ax,ad3      ;;   and leave sum in AX%@AE@%%@NL@%
  10650.   %@AS@%            ENDM%@AE@%%@NL@%
  10651. %@NL@%
  10652. %@4@%  This example defines a macro named %@AS@%addup%@AE@%, which uses three parameters to%@EH@%
  10653.   add three values and leave their sum in the AX register. The three
  10654.   parameters will be replaced with arguments when the macro is called.%@NL@%
  10655. %@NL@%
  10656. %@NL@%
  10657. %@3@%%@CR:SC11.2.2    @%%@AB@%11.2.2  Calling Macros%@AE@%%@EH@%%@NL@%
  10658. %@NL@%
  10659. %@4@%%@CR:IX11.42     @%  A macro call directs QuickAssembler to copy the statements of the macro to%@EH@%
  10660.   the point of the call and to replace any parameters in the macro
  10661.   statements with the corresponding actual arguments.%@NL@%
  10662. %@NL@%
  10663. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10664. %@NL@%
  10665. %@4@%  %@AI@%name%@AE@% [[%@AI@%argument%@AE@% [[%@AB@%,%@AE@%%@AI@%argument%@AE@%]]...]]%@EH@%%@NL@%
  10666. %@NL@%
  10667. %@4@%  The %@AI@%name%@AE@% must be the name of a macro defined earlier in the source file.%@EH@%
  10668.   The %@AI@%arguments%@AE@% can be any text. For example, symbols, constants, and
  10669.   registers are often given as arguments. Any number of arguments can be
  10670.   given, but they must all fit on one logical line. You can use the
  10671.   continuation character (\) to continue long macro calls on multiple
  10672.   physical lines. Multiple arguments must be separated by commas, spaces, or
  10673.   tabs.%@NL@%
  10674. %@NL@%
  10675. %@4@%%@CR:IX11.43     @%%@CR:IX11.44     @%  QuickAssembler replaces the first parameter with the first argument, the%@EH@%
  10676.   second parameter with the second argument, and so on. If a macro call has
  10677.   more arguments than the macro has parameters, the extra arguments are
  10678.   ignored. If a call has fewer arguments than the macro has parameters, any
  10679.   remaining parameters are replaced with a null (empty) string.%@NL@%
  10680. %@NL@%
  10681. %@4@%%@CR:IX11.45     @%%@CR:IX11.46     @%  You can use conditional statements to enable macros to check for null%@EH@%
  10682.   strings or other types of arguments. The macro can then take appropriate
  10683.   action to adjust to different kinds of arguments. See Chapter 10%@BO:       867d7@%,
  10684.   "Assembling Conditionally," for more information on using
  10685.   conditional-assembly and conditional-error directives to test macro
  10686.   arguments.%@NL@%
  10687. %@NL@%
  10688. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10689. %@NL@%
  10690.   %@AS@%addup       MACRO   ad1,ad2,ad3        ; Macro definition%@AE@%%@NL@%
  10691.   %@AS@%            mov     ax,ad1             ;; First parameter in AX%@AE@%%@NL@%
  10692.   %@AS@%            add     ax,ad2             ;; Add next two parameters%@AE@%%@NL@%
  10693.   %@AS@%            add     ax,ad3             ;;   and leave sum in AX%@AE@%%@NL@%
  10694.   %@AS@%            ENDM%@AE@%%@NL@%
  10695.   %@AS@%            .%@AE@%%@NL@%
  10696.   %@AS@%            .%@AE@%%@NL@%
  10697.   %@AS@%            .%@AE@%%@NL@%
  10698.   %@AS@%            addup   bx,2,count         ; Macro call%@AE@%%@NL@%
  10699. %@NL@%
  10700. %@4@%  When the %@AS@%addup%@AE@% macro is called, QuickAssembler replaces the parameters%@EH@%
  10701.   with the actual parameters given in the macro call. In the example above,
  10702.   the assembler would expand the macro call to the following code:%@NL@%
  10703. %@NL@%
  10704.   %@AS@%            mov     ax,bx%@AE@%%@NL@%
  10705.   %@AS@%            add     ax,2%@AE@%%@NL@%
  10706.   %@AS@%            add     ax,count%@AE@%%@NL@%
  10707. %@NL@%
  10708. %@4@%%@CR:IX11.47     @%%@CR:IX11.48     @%%@CR:IX11.49     @%%@CR:IX11.50     @%%@CR:IX11.51     @%%@CR:IX11.52     @%  This code could be shown in an assembler listing, depending on whether the%@EH@%
  10709.   %@AB@%.LALL%@AE@%, %@AB@%.XALL%@AE@%, or %@AB@%.SALL%@AE@% directive was in effect (see Section 12.3%@BO:       a47ae@%,
  10710.   "Controlling the Contents of Listings").%@NL@%
  10711. %@NL@%
  10712. %@NL@%
  10713. %@3@%%@CR:SC11.2.3    @%%@AB@%11.2.3  Using Local Symbols%@AE@%%@EH@%%@NL@%
  10714. %@NL@%
  10715. %@4@%%@CR:IX11.53     @%%@CR:IX11.54     @%%@CR:IX11.55     @%%@CR:IX11.56     @%  The %@AB@%LOCAL%@AE@% directive can be used within a macro to define symbols that are%@EH@%
  10716.   available only within the defined macro.%@NL@%
  10717. %@NL@%
  10718.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10719.   %@AB@%NOTE%@AE@%  In this context, the term "local" is not related to the public
  10720.   availability of a symbol, as described in Chapter 8%@BO:       70f6e@%, "Creating Programs
  10721.   from Multiple Modules," or to variables that are defined to be local to a
  10722.   procedure, as described in Section 15.3.5%@BO:       c9deb@%, "Using Local Variables." Local
  10723.   simply means that the symbol is not known outside the macro where it is
  10724.   defined.%@NL@%
  10725.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10726. %@NL@%
  10727. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10728. %@NL@%
  10729. %@4@%  %@AB@%LOCAL%@AE@% %@AI@%localname%@AE@% [[%@AB@%,%@AE@%%@AI@%localname%@AE@%]]...%@EH@%%@NL@%
  10730. %@NL@%
  10731. %@4@%  The %@AI@%localname%@AE@% is a temporary symbol name that is to be replaced by a%@EH@%
  10732.   unique symbol name when the macro is expanded. At least one local name is
  10733.   required for each %@AB@%LOCAL%@AE@% directive. If more than one local symbol is given,
  10734.   the names must be separated with commas. Once declared, local name can be
  10735.   used in any statement within the macro definition.%@NL@%
  10736. %@NL@%
  10737. %@4@%  QuickAssembler creates a new actual name for %@AI@%localname%@AE@% each time the macro%@EH@%
  10738.   is expanded. The actual name has the following form:%@NL@%
  10739. %@NL@%
  10740. %@4@%  %@AB@%??%@AE@%%@AI@%number%@AE@%%@EH@%%@NL@%
  10741. %@NL@%
  10742. %@4@%  The %@AI@%number%@AE@% is a hexadecimal number in the range 0000 to 0FFFF. You should%@EH@%
  10743.   not give other symbols names in this format, since doing so may produce a
  10744.   symbol with multiple definitions. In listings, the local name is shown in
  10745.   the macro definition, but the actual name is shown in expansions of macro
  10746.   calls.%@NL@%
  10747. %@NL@%
  10748. %@4@%%@CR:IX11.57     @%  Nonlocal labels may be used in a macro; but if the macro is used more than%@EH@%
  10749.   once, the same label will appear in both expansions, and QuickAssembler
  10750.   will display an error message, indicating that the file contains a symbol
  10751.   with multiple definitions. To avoid this problem, use only local labels
  10752.   (or redefinable equates) in macros.%@NL@%
  10753. %@NL@%
  10754.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10755.   %@AB@%NOTE%@AE@%  The %@AB@%LOCAL %@AE@%directive in macro definitions must precede all other
  10756.   statements in the definition. If you try another statement (such as a
  10757.   comment directive) before the %@AB@%LOCAL %@AE@%directive, an error will be generated.%@NL@%
  10758.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10759. %@NL@%
  10760. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10761. %@NL@%
  10762.   %@AS@%power       MACRO   factor,exponent    ;; Use for unsigned only%@AE@%%@NL@%
  10763.   %@AS@%            LOCAL   again,gotzero      ;; Declare symbols for macro%@AE@%%@NL@%
  10764.   %@AS@%            xor     dx,dx              ;; Clear DX%@AE@%%@NL@%
  10765.   %@AS@%            mov     cx,exponent        ;; Exponent is count for loop%@AE@%%@NL@%
  10766.   %@AS@%            mov     ax,1               ;; Multiply by 1 first time%@AE@%%@NL@%
  10767.   %@AS@%            jcxz    gotzero            ;; Get out if exponent is zero%@AE@%%@NL@%
  10768.   %@AS@%            mov     bx,factor%@AE@%%@NL@%
  10769.   %@AS@%again:      mul     bx                 ;; Multiply until done%@AE@%%@NL@%
  10770.   %@AS@%            loop    again%@AE@%%@NL@%
  10771.   %@AS@%gotzero:%@AE@%%@NL@%
  10772.   %@AS@%            ENDM%@AE@%%@NL@%
  10773. %@NL@%
  10774. %@4@%  In this example, the %@AB@%LOCAL%@AE@% directive defines the local names %@AS@%again%@AE@% and%@EH@%
  10775.   %@AS@%gotzero%@AE@% as labels to be used within the %@AS@%power%@AE@% macro. These local names
  10776.   will be replaced with unique names each time the macro is expanded. For
  10777.   example, the first time the macro is called, %@AS@%again%@AE@% will be assigned the
  10778.   name %@AS@%??0000%@AE@% and %@AS@%gotzero%@AE@% will be assigned %@AS@%??0001%@AE@%. The second time through,
  10779.   %@AS@%again%@AE@% will be assigned %@AS@%??0002%@AE@% and %@AS@%gotzero %@AE@%will be assigned %@AS@%??0003%@AE@%, and so
  10780.   on.%@NL@%
  10781. %@NL@%
  10782. %@NL@%
  10783. %@3@%%@CR:SC11.2.4    @%%@AB@%11.2.4  Exiting from a Macro%@AE@%%@EH@%%@NL@%
  10784. %@NL@%
  10785. %@4@%%@CR:IX11.58     @%%@CR:IX11.59     @%%@CR:IX11.60     @%  Normally, QuickAssembler processes all the statements in a macro%@EH@%
  10786.   definition and then continues with the next statement after the macro
  10787.   call. However, you can use the %@AB@%EXITM%@AE@% directive to tell the assembler to
  10788.   terminate macro expansion before all the statements in the macro have been
  10789.   assembled.%@NL@%
  10790. %@NL@%
  10791. %@4@%  When the %@AB@%EXITM%@AE@% directive is encountered, the assembler exits the macro or%@EH@%
  10792.   repeat block immediately. Any remaining statements in the macro or repeat
  10793.   block are not processed. If %@AB@%EXITM%@AE@% is encountered in a nested macro or
  10794.   repeat block, QuickAssembler returns to expanding the outer block.%@NL@%
  10795. %@NL@%
  10796. %@4@%  The %@AB@%EXITM%@AE@% directive is typically used with conditional directives to skip%@EH@%
  10797.   the last statements in a macro under specified conditions. Often macros
  10798.   using the %@AB@%EXITM%@AE@% directive contain repeat blocks or are called recursively.%@NL@%
  10799. %@NL@%
  10800. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  10801. %@NL@%
  10802.   %@AS@%allocate    MACRO   times      ; Macro definition%@AE@%%@NL@%
  10803.   %@AS@%x           =       0%@AE@%%@NL@%
  10804.   %@AS@%            REPT    times      ;; Repeat up to 256 times%@AE@%%@NL@%
  10805.   %@AS@%            IF      x GT 0FFh  ;; Is x > 255 yet?%@AE@%%@NL@%
  10806.   %@AS@%            EXITM              ;; If so, quit%@AE@%%@NL@%
  10807.   %@AS@%            ELSE%@AE@%%@NL@%
  10808.   %@AS@%            DB      x          ;; Else allocate x%@AE@%%@NL@%
  10809.   %@AS@%            ENDIF%@AE@%%@NL@%
  10810.   %@AS@%x           =       x + 1      ;; Increment x%@AE@%%@NL@%
  10811.   %@AS@%            ENDM%@AE@%%@NL@%
  10812.   %@AS@%            ENDM%@AE@%%@NL@%
  10813. %@NL@%
  10814. %@4@%  This example defines a macro that allocates a variable amount of data, but%@EH@%
  10815.   no more than 255 bytes. The macro contains an %@AB@%IF%@AE@% directive that checks the
  10816.   expression %@AS@%x - 0FFh%@AE@%. When the value of this expression is true (x-255 =
  10817.   0), the %@AB@%EXITM%@AE@% directive is processed and expansion of the macro stops.%@NL@%
  10818. %@NL@%
  10819. %@NL@%
  10820. %@2@%%@CR:SC11.3      @%%@AB@%11.3  Text-Macro String Directives%@AE@%%@EH@%%@NL@%
  10821. %@NL@%
  10822. %@4@%%@CR:IX11.61     @%  The assembler includes four text-macro string directives that let you%@EH@%
  10823.   manipulate literal strings or text-macro values. You use the four
  10824.   directives in much the same way you use the equal-sign (%@AB@%=%@AE@%) directive. For
  10825.   example, the following line assigns the first three characters (%@AS@%abc%@AE@%) of
  10826.   the literal string to the label %@AS@%three%@AE@% by using the %@AB@%SUBSTR%@AE@% directive:%@NL@%
  10827. %@NL@%
  10828.   %@AS@%three       SUBSTR  <abcdefghijklmnopqrstuvwxyz>,1,3%@AE@%%@NL@%
  10829. %@NL@%
  10830. %@4@%%@CR:IX11.62     @%%@CR:IX11.63     @%  Each of the directives assigns its value──depending on the directive──to a%@EH@%
  10831.   numeric label or a text macro. The following list summarizes the four
  10832.   directives and the type of label that the directives should be used with:%@NL@%
  10833. %@NL@%
  10834.   %@AB@%Directive%@AE@%           %@AB@%Description%@AE@%%@NL@%
  10835.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10836.   %@AB@%SUBSTR%@AE@%              Returns a substring of its text macro or literal
  10837.                       string argument.%@AB@% SUBSTR %@AE@%requires a text-macro label.%@NL@%
  10838. %@NL@%
  10839.   %@AB@%CATSTR%@AE@%              Concatenates a variable number of strings (text macros
  10840.                       or literal strings) to form a single string. %@AB@%CATSTR%@AE@%
  10841.                       requires a text-macro label.%@NL@%
  10842. %@NL@%
  10843.   %@AB@%SIZESTR%@AE@%             Returns the length, in characters, of its argument
  10844.                       string. %@AB@%SIZESTR%@AE@% requires a numeric label.%@NL@%
  10845. %@NL@%
  10846.   %@AB@%INSTR%@AE@%               Returns an index indicating the starting position of a
  10847.                       substring within another string. %@AB@%INSTR%@AE@% requires a
  10848.                       numeric label.%@NL@%
  10849. %@NL@%
  10850. %@NL@%
  10851. %@4@%  Strings used as arguments in the directives must be text enclosed in angle%@EH@%
  10852.   brackets (%@AB@%<%@AE@% %@AB@%>%@AE@%), previously defined text macros, or expressions starting
  10853.   with a percent sign (%@AB@%%%@AE@%). Numeric arguments can be numeric constants or
  10854.   expressions that evaluate to constants during assembly.%@NL@%
  10855. %@NL@%
  10856. %@4@%  The next four sections describe the directives in more detail.%@EH@%%@NL@%
  10857. %@NL@%
  10858. %@NL@%
  10859. %@3@%%@CR:SC11.3.1    @%%@AB@%11.3.1  The SUBSTR Directive%@AE@%%@EH@%%@NL@%
  10860. %@NL@%
  10861. %@4@%%@CR:IX11.64     @%%@CR:IX11.65     @%%@CR:IX11.66     @%  The %@AB@%SUBSTR%@AE@% directive returns a substring from a given string.%@EH@%%@NL@%
  10862. %@NL@%
  10863. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10864. %@NL@%
  10865. %@4@%  %@AI@%textlabel%@AE@%%@AB@% SUBSTR%@AE@% %@AI@%string%@AE@%%@AB@%,%@AE@%%@AI@%start%@AE@%[[%@AB@%, %@AE@%%@AI@%length%@AE@%]]%@EH@%%@NL@%
  10866. %@NL@%
  10867. %@4@%  The %@AB@%SUBSTR%@AE@% directive takes the following arguments:%@EH@%%@NL@%
  10868. %@NL@%
  10869.   %@AB@%Argument%@AE@%            %@AB@%Description%@AE@%%@NL@%
  10870.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10871.   %@AI@%textlabel%@AE@%           The text label the result is assigned to.%@NL@%
  10872. %@NL@%
  10873.   %@AI@%string%@AE@%              The string the substring is extracted from.%@NL@%
  10874. %@NL@%
  10875.   %@AI@%start%@AE@%               The starting position of the substring. The first
  10876.                       character in the string has a position of one.%@NL@%
  10877. %@NL@%
  10878.   %@AI@%length%@AE@%              The number of characters to extract. If omitted,
  10879.                       %@AB@%SUBSTR%@AE@% returns all characters to the right of position
  10880.                       %@AI@%start%@AE@%, including the character at position %@AI@%start%@AE@%.%@NL@%
  10881. %@NL@%
  10882. %@NL@%
  10883. %@4@%  In the following lines, the text macro %@AS@%freg %@AE@%is assigned the first two%@EH@%
  10884.   characters of the text macro %@AS@%reglist%@AE@%:%@NL@%
  10885. %@NL@%
  10886.   %@AS@%reglist     EQU     <ax,bx,cx,dx>%@AE@%%@NL@%
  10887.   %@AS@%            .%@AE@%%@NL@%
  10888.   %@AS@%            .%@AE@%%@NL@%
  10889.   %@AS@%            .%@AE@%%@NL@%
  10890.   %@AS@%freg        SUBSTR  reglist,1,2   ; freg = ax%@AE@%%@NL@%
  10891. %@NL@%
  10892. %@NL@%
  10893. %@3@%%@CR:SC11.3.2    @%%@AB@%11.3.2  The CATSTR %@AE@%Directive%@EH@%%@NL@%
  10894. %@NL@%
  10895. %@4@%%@CR:IX11.67     @%%@CR:IX11.68     @%%@CR:IX11.69     @%  The %@AB@%CATSTR%@AE@% directive concatenates a series of strings.%@EH@%%@NL@%
  10896. %@NL@%
  10897. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10898. %@NL@%
  10899. %@4@%  %@AI@%textlabel%@AE@%%@AB@% CATSTR %@AE@%%@AI@%string%@AE@%[[%@AB@%,%@AE@% %@AI@%string%@AE@%]]...%@EH@%%@NL@%
  10900. %@NL@%
  10901. %@4@%  The %@AB@%CATSTR%@AE@% directive takes the following arguments:%@EH@%%@NL@%
  10902. %@NL@%
  10903.   %@AB@%Argument%@AE@%            %@AB@%Description%@AE@%%@NL@%
  10904.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10905.   %@AI@%textlabel%@AE@%           The text label the result is assigned to%@NL@%
  10906. %@NL@%
  10907.   %@AI@%string%@AE@%              The string or strings concatenated and assigned to
  10908.                       %@AI@%textlabel%@AE@%%@NL@%
  10909. %@NL@%
  10910. %@NL@%
  10911. %@4@%  The following lines concatenate the two literal strings and assign the%@EH@%
  10912.   result to the text macro %@AS@%lstring%@AE@%:%@NL@%
  10913. %@NL@%
  10914.   %@AS@%lstring     CATSTR   <a b c>, <d e f>,       ; lstring = a b c d e f%@AE@%%@NL@%
  10915. %@NL@%
  10916. %@NL@%
  10917. %@3@%%@CR:SC11.3.3    @%%@AB@%11.3.3  The SIZESTR%@AE@% Directive%@EH@%%@NL@%
  10918. %@NL@%
  10919. %@4@%%@CR:IX11.70     @%%@CR:IX11.71     @%  The %@AB@%SIZESTR%@AE@% directive assigns the length of its argument string to a%@EH@%
  10920.   numeric label.%@NL@%
  10921. %@NL@%
  10922. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10923. %@NL@%
  10924. %@4@%  %@AI@%numericlabel%@AE@%%@AB@% SIZESTR %@AE@%%@AI@%string%@AE@%%@EH@%%@NL@%
  10925. %@NL@%
  10926. %@4@%  The %@AB@%SIZESTR%@AE@% directive takes the following arguments:%@EH@%%@NL@%
  10927. %@NL@%
  10928.   %@AB@%Argument%@AE@%            %@AB@%Description%@AE@%%@NL@%
  10929.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10930.   %@AI@%numericlabel%@AE@%        The numeric label that the assembler assigns the
  10931.                       string length to%@NL@%
  10932. %@NL@%
  10933.   %@AI@%string%@AE@%              The string whose length is returned%@NL@%
  10934. %@NL@%
  10935. %@NL@%
  10936. %@4@%  The following lines set %@AS@%slength %@AE@%to%@AS@% 8%@AE@%──the length of the text macro%@EH@%
  10937.   %@AS@%tstring%@AE@%:%@NL@%
  10938. %@NL@%
  10939.   %@AS@%tstring     EQU      <ax bx cx>%@AE@%%@NL@%
  10940.   %@AS@%            .%@AE@%%@NL@%
  10941.   %@AS@%            .%@AE@%%@NL@%
  10942.   %@AS@%            .%@AE@%%@NL@%
  10943.   %@AS@%slength     SIZESTR  tstring                 ; slength = 8%@AE@%%@NL@%
  10944. %@NL@%
  10945. %@4@%  A null string has a length of zero.%@EH@%%@NL@%
  10946. %@NL@%
  10947. %@NL@%
  10948. %@3@%%@CR:SC11.3.4    @%%@AB@%11.3.4  The INSTR Directive%@AE@%%@EH@%%@NL@%
  10949. %@NL@%
  10950. %@4@%%@CR:IX11.72     @%%@CR:IX11.73     @%  The %@AB@%INSTR%@AE@% directive returns the position of a string within another%@EH@%
  10951.   string. The directive returns 0 if the string is not found. The first
  10952.   character in a string has a position of one.%@NL@%
  10953. %@NL@%
  10954. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  10955. %@NL@%
  10956. %@4@%  %@AI@%numericlabel%@AE@%%@AB@% INSTR%@AE@% [[%@AI@%start%@AE@%%@AB@%,%@AE@%]]%@AI@%string1%@AE@%%@AB@%,%@AE@% %@AI@%string2%@AE@%%@EH@%%@NL@%
  10957. %@NL@%
  10958. %@4@%  The%@AB@% INSTR%@AE@% directive takes the following arguments:%@EH@%%@NL@%
  10959. %@NL@%
  10960.   %@AB@%Argument%@AE@%            %@AB@%Description%@AE@%%@NL@%
  10961.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  10962.   %@AI@%numbericlabel%@AE@%       The numeric label the substring's position is assigned
  10963.                       to.%@NL@%
  10964. %@NL@%
  10965.   %@AI@%start%@AE@%               The starting position for the search. When omitted,
  10966.                       the %@AB@%INSTR%@AE@% directive starts searching at the first
  10967.                       character. The first character in the string has a
  10968.                       position of one.%@NL@%
  10969. %@NL@%
  10970.   %@AI@%string1%@AE@%             The string being searched.%@NL@%
  10971. %@NL@%
  10972.   %@AI@%string2%@AE@%             The string to look for.%@NL@%
  10973. %@NL@%
  10974. %@NL@%
  10975. %@4@%  The following lines set %@AS@%colpos %@AE@%to the character position of the first%@EH@%
  10976.   colon in %@AS@%segarg%@AE@%:%@NL@%
  10977. %@NL@%
  10978.   %@AS@%segarg      EQU    <ES:AX>%@AE@%%@NL@%
  10979.   %@AS@%            .%@AE@%%@NL@%
  10980.   %@AS@%            .%@AE@%%@NL@%
  10981.   %@AS@%            .%@AE@%%@NL@%
  10982.   %@AS@%colpos      INSTR  segarg,<:> ; colpos = 3%@AE@%%@NL@%
  10983. %@NL@%
  10984. %@NL@%
  10985. %@3@%%@CR:SC11.3.5    @%%@AB@%11.3.5  Using String Directives Inside Macros%@AE@%%@EH@%%@NL@%
  10986. %@NL@%
  10987. %@4@%  The following example uses the text-macro string directives %@AB@%CATSTR%@AE@%, %@AB@%INSTR%@AE@%,%@EH@%
  10988.   %@AB@%SIZESTR%@AE@%, and %@AB@%SUBSTR%@AE@%. It defines two macros, %@AS@%SaveRegs %@AE@%and %@AS@%RestRegs%@AE@%, that
  10989.   save and restore registers on the stack. The macros are written so that
  10990.   %@AS@%RestRegs %@AE@%restores only the most recently saved group of registers.%@NL@%
  10991. %@NL@%
  10992. %@4@%  The %@AS@%SaveRegs %@AE@%macro uses a text macro, %@AS@%regpushed%@AE@%, to keep track of the%@EH@%
  10993.   registers pushed onto the stack. The %@AS@%RestRegs %@AE@%macro uses this string to
  10994.   restore the proper registers. Each time the %@AS@%SaveRegs %@AE@%macro is invoked, it
  10995.   adds a pound sign (#) to the string to mark the start of a new group of
  10996.   registers. The %@AS@%RestRegs %@AE@%macro restores the most recently saved group by
  10997.   finding the first pound sign in the string, creating a substring
  10998.   containing the saved register names, and then looping and generating %@AB@%PUSH%@AE@%
  10999.   instructions.%@NL@%
  11000. %@NL@%
  11001.   %@AS@%; Initialize regpushed to the null string%@AE@%%@NL@%
  11002.   %@AS@%regpushed       EQU     <>%@AE@%%@NL@%
  11003. %@NL@%
  11004.   %@AS@%; SaveRegs%@AE@%%@NL@%
  11005.   %@AS@%; Loops and generates a push for each argument register.%@AE@%%@NL@%
  11006.   %@AS@%; Saves each register name in regpushed.%@AE@%%@NL@%
  11007. %@NL@%
  11008.   %@AS@%SaveRegs        MACRO   r1,r2,r3,r4,r5,r6,r7,r8,r9%@AE@%%@NL@%
  11009.   %@AS@%   regpushed    CATSTR  <#>,regpushed   ;; Mark a new group of regs%@AE@%%@NL@%
  11010.   %@AS@%                IRP reg,<r1,r2,r3,r4,r5,r6,r7,r8,r9>%@AE@%%@NL@%
  11011.   %@AS@%                   IFNB <reg>%@AE@%%@NL@%
  11012.   %@AS@%                      push reg          ;; Push and record a register%@AE@%%@NL@%
  11013.   %@AS@%   regpushed          CATSTR    <reg>,<,>,regpushed%@AE@%%@NL@%
  11014.   %@AS@%                   ELSE%@AE@%%@NL@%
  11015.   %@AS@%                      EXITM             ;; Quit on blank argument%@AE@%%@NL@%
  11016.   %@AS@%                   ENDIF%@AE@%%@NL@%
  11017.   %@AS@%                ENDM%@AE@%%@NL@%
  11018.   %@AS@%                ENDM%@AE@%%@NL@%
  11019. %@NL@%
  11020.   %@AS@%; RestRegs%@AE@%%@NL@%
  11021.   %@AS@%; Generates a pop for each register in the most recently saved groups%@AE@%%@NL@%
  11022. %@AS@%%@AE@%%@NL@%
  11023.   %@AS@%RestRegs        MACRO%@AE@%%@NL@%
  11024.   %@AS@%   numloc       INSTR  regpushed,<#>    ;; Find location of #%@AE@%%@NL@%
  11025.   %@AS@%   reglist      SUBSTR regpushed,1,numloc-1 ;; Get list of registers to pop%@AE@%%@NL@%
  11026.   %@AS@%    reglen       SIZESTR regpushed       ;; Adjust numloc if # is notlast%@AE@%%@NL@%
  11027.   %@AS@%                 IF reglen GT numloc     ;; item in the string%@AE@%%@NL@%
  11028.   %@AS@%                   numloc = numloc + 1%@AE@%%@NL@%
  11029.   %@AS@%                ENDIF%@AE@%%@NL@%
  11030.   %@AS@%   regpushed    SUBSTR regpushed,numloc ;; Remove list from regpushed%@AE@%%@NL@%
  11031.   %@AS@%   %            IRP reg,<reglist>       ;; Generate pop for each register%@AE@%%@NL@%
  11032.   %@AS@%                IFNB <reg>%@AE@%%@NL@%
  11033.   %@AS@%                   pop reg%@AE@%%@NL@%
  11034.   %@AS@%                ENDIF%@AE@%%@NL@%
  11035.   %@AS@%                ENDM%@AE@%%@NL@%
  11036.   %@AS@%                ENDM%@AE@%%@NL@%
  11037. %@NL@%
  11038. %@4@%  The following lines from a listing file show the sample code that the%@EH@%
  11039.   macros would generate (a %@AS@%2 %@AE@%marks lines generated by the macros):%@NL@%
  11040. %@NL@%
  11041.   %@AS@%SaveRegs      ax,bx%@AE@%%@NL@%
  11042.   %@AS@%2                     push ax           ;%@AE@%%@NL@%
  11043.   %@AS@%2                     push bx           ;%@AE@%%@NL@%
  11044.   %@AS@%  SaveRegs      cx%@AE@%%@NL@%
  11045.   %@AS@%2                     push cx           ;%@AE@%%@NL@%
  11046.   %@AS@%  SaveRegs      dx%@AE@%%@NL@%
  11047.   %@AS@%2                     push dx           ;%@AE@%%@NL@%
  11048.   %@AS@%  RestRegs%@AE@%%@NL@%
  11049.   %@AS@%2                     pop dx%@AE@%%@NL@%
  11050.   %@AS@%  RestRegs%@AE@%%@NL@%
  11051.   %@AS@%2                     pop cx%@AE@%%@NL@%
  11052.   %@AS@%  RestRegs%@AE@%%@NL@%
  11053.   %@AS@%2                     pop bx%@AE@%%@NL@%
  11054.   %@AS@%2                     pop ax%@AE@%%@NL@%
  11055. %@NL@%
  11056. %@NL@%
  11057. %@2@%%@CR:SC11.4      @%%@AB@%11.4  Defining Repeat Blocks%@AE@%%@EH@%%@NL@%
  11058. %@CR:IX11.74     @%%@CR:IX11.75     @%%@CR:IX11.76     @%%@CR:IX11.77     @%%@CR:IX11.78     @%%@CR:IX11.79     @%%@CR:IX11.80     @%%@NL@%
  11059. %@4@%%@CR:IX11.81     @%%@CR:IX11.82     @%%@CR:IX11.83     @%%@CR:IX11.84     @%%@CR:IX11.85     @%  Repeat blocks are a special form of macro that allows you to create blocks%@EH@%
  11060.   of repeated statements. They differ from macros in that they are not
  11061.   named, and thus cannot be called. However, like macros, they can have
  11062.   parameters that are replaced by actual arguments during assembly. Macro
  11063.   operators, symbols declared with the %@AB@%LOCAL%@AE@% directive, and the %@AB@%EXITM%@AE@%
  11064.   directive can be used in repeat blocks. Like macros, repeat blocks are
  11065.   always terminated by an %@AB@%ENDM %@AE@%directive.%@NL@%
  11066. %@NL@%
  11067. %@4@%  Repeat blocks are frequently placed in macros in order to repeat some of%@EH@%
  11068.   the statements in the macro. They can also be used independently, usually
  11069.   for declaring arrays with repeated data elements.%@NL@%
  11070. %@NL@%
  11071. %@4@%  Repeat blocks are processed at assembly time and should not be confused%@EH@%
  11072.   with the %@AB@%REP%@AE@% instruction, which causes string instructions to be repeated
  11073.   at run time, as explained in Chapter 16%@BO:       d1833@%, "Processing Strings."%@NL@%
  11074. %@NL@%
  11075. %@4@%  Three different kinds of repeat blocks can be defined by using the %@AB@%REPT%@AE@%,%@EH@%
  11076.   %@AB@%IRP%@AE@%, and %@AB@%IRPC%@AE@% directives. The difference between them is in how the number
  11077.   of repetitions is specified.%@NL@%
  11078. %@NL@%
  11079. %@NL@%
  11080. %@3@%%@CR:SC11.4.1    @%%@AB@%11.4.1  The REPT Directive%@AE@%%@EH@%%@NL@%
  11081. %@NL@%
  11082. %@4@%%@CR:IX11.86     @%%@CR:IX11.87     @%%@CR:IX11.88     @%%@CR:IX11.89     @%%@CR:IX11.90     @%  The %@AB@%REPT%@AE@% directive is used to create repeat blocks in which the number of%@EH@%
  11083.   repetitions is specified with a numeric argument.%@NL@%
  11084. %@NL@%
  11085. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11086. %@NL@%
  11087. %@4@%  %@AB@%REPT %@AE@%  %@AI@%expression%@AE@%%@EH@%%@NL@%
  11088.   %@AI@%statements%@AE@%%@NL@%
  11089.   %@AB@%ENDM%@AE@%%@NL@%
  11090. %@NL@%
  11091. %@4@%  The %@AI@%expression%@AE@% must evaluate to a numeric constant (a 16-bit unsigned%@EH@%
  11092.   number). It specifies the number of repetitions. Any valid assembler
  11093.   %@AI@%statements%@AE@% may be placed within the repeat block.%@NL@%
  11094. %@NL@%
  11095. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11096. %@NL@%
  11097.   %@AS@%alphabet    LABEL   BYTE%@AE@%%@NL@%
  11098.   %@AS@%x           =       0          ;; Initialize%@AE@%%@NL@%
  11099.   %@AS@%            REPT    26         ;; Specify 26 repetitions%@AE@%%@NL@%
  11100.   %@AS@%            DB      'A' + x    ;; Allocate ASCII code for letter%@AE@%%@NL@%
  11101.   %@AS@%x           =       x + 1      ;; Increment%@AE@%%@NL@%
  11102.   %@AS@%            ENDM%@AE@%%@NL@%
  11103. %@NL@%
  11104. %@4@%  This example repeats the equal-sign (%@AB@%=%@AE@%) and %@AB@%DB%@AE@% directives to initialize%@EH@%
  11105.   ASCII values for each uppercase letter of the alphabet.%@NL@%
  11106. %@NL@%
  11107. %@NL@%
  11108. %@3@%%@CR:SC11.4.2    @%%@AB@%11.4.2  The IRP Directive%@AE@%%@EH@%%@NL@%
  11109. %@NL@%
  11110. %@4@%%@CR:IX11.91     @%%@CR:IX11.92     @%%@CR:IX11.93     @%%@CR:IX11.94     @%%@CR:IX11.95     @%  The %@AB@%IRP%@AE@% directive is used to create repeat blocks in which the number of%@EH@%
  11111.   repetitions, as well as parameters for each repetition, is specified in a
  11112.   list of arguments.%@NL@%
  11113. %@NL@%
  11114. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11115. %@NL@%
  11116. %@4@%  %@AB@%IRP%@AE@% %@AI@%parameter%@AE@%%@AB@%,<%@AE@%%@AI@%argument%@AE@%[[%@AB@%,%@AE@%%@AI@%argument%@AE@%]]...%@AB@%>%@AE@%%@EH@%%@NL@%
  11117.   %@AI@%statements%@AE@%%@NL@%
  11118.   %@AB@%ENDM%@AE@%%@NL@%
  11119. %@NL@%
  11120. %@4@%  The assembler %@AI@%statements%@AE@% inside the block are repeated once for each%@EH@%
  11121.   %@AI@%argument%@AE@% in the list enclosed by angle brackets (%@AB@%< >%@AE@%). The %@AI@%parameter%@AE@% is a
  11122.   name for a placeholder to be replaced by the current argument. Each
  11123.   argument can be text, such as a symbol, string, or numeric constant. Any
  11124.   number of arguments can be given. If multiple arguments are given, they
  11125.   must be separated by commas. The angle brackets %@AB@%(< >)%@AE@% around the argument
  11126.   list are required. The parameter can be used any number of times in the
  11127.   statements.%@NL@%
  11128. %@NL@%
  11129. %@4@%  When QuickAssembler encounters an %@AB@%IRP%@AE@% directive, it makes one copy of the%@EH@%
  11130.   statements for each argument in the enclosed list. While copying the
  11131.   statements, it substitutes the current argument for all occurrences of
  11132.   %@AI@%parameter%@AE@% in these statements. If a null argument (%@AB@%< >%@AE@%) is found in the
  11133.   list, the dummy name is replaced with a blank value. If the argument list
  11134.   is empty, the %@AB@%IRP%@AE@% directive is ignored and no statements are copied.%@NL@%
  11135. %@NL@%
  11136. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11137. %@NL@%
  11138.   %@AS@%numbers     LABEL   BYTE%@AE@%%@NL@%
  11139.   %@AS@%            IRP     x,<0,1,2,3,4,5,6,7,8,9>%@AE@%%@NL@%
  11140.   %@AS@%            DB      10 DUP(x)%@AE@%%@NL@%
  11141.   %@AS@%            ENDM%@AE@%%@NL@%
  11142. %@NL@%
  11143. %@4@%  This example repeats the %@AB@%DB%@AE@% directive 10 times, allocating 10 bytes for%@EH@%
  11144.   each number in the list. The resulting statements create 100 bytes of
  11145.   data, starting with 10 zeros, followed by 10 ones, and so on.%@NL@%
  11146. %@NL@%
  11147. %@NL@%
  11148. %@3@%%@CR:SC11.4.3    @%%@AB@%11.4.3  The IRPC Directive%@AE@%%@EH@%%@NL@%
  11149. %@NL@%
  11150. %@4@%%@CR:IX11.96     @%%@CR:IX11.97     @%%@CR:IX11.98     @%%@CR:IX11.99     @%%@CR:IX11.100    @%  The %@AB@%IRPC%@AE@% directive is used to create repeat blocks in which the number of%@EH@%
  11151.   repetitions, as well as arguments for each repetition, is specified in a
  11152.   string.%@NL@%
  11153. %@NL@%
  11154. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11155. %@NL@%
  11156. %@4@%  %@AB@%IRPC%@AE@% %@AI@%parameter%@AE@%%@AB@%,%@AE@%%@AI@%string%@AE@%%@EH@%%@NL@%
  11157.   %@AI@%statements%@AE@%%@NL@%
  11158.   %@AB@%ENDM%@AE@%%@NL@%
  11159. %@NL@%
  11160. %@4@%  The assembler %@AI@%statements%@AE@% inside the block are repeated as many times as%@EH@%
  11161.   there are characters in %@AI@%string%@AE@%. The %@AI@%parameter%@AE@% is a name for a placeholder
  11162.   to be replaced by the current character in the string. The string can be
  11163.   any combination of letters, digits, and other characters. It should be
  11164.   enclosed with angle brackets (%@AB@%< >%@AE@%) if it contains spaces, commas, or other
  11165.   separating characters. The parameter can be used any number of times in
  11166.   these statements.%@NL@%
  11167. %@NL@%
  11168. %@4@%  When QuickAssembler encounters an %@AB@%IRPC%@AE@% directive, it makes one copy of the%@EH@%
  11169.   statements for each character in the string. While copying the statements,
  11170.   it substitutes the current character for all occurrences of %@AI@%parameter%@AE@% in
  11171.   these statements.%@NL@%
  11172. %@NL@%
  11173. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  11174. %@NL@%
  11175.   %@AS@%ten         LABEL   BYTE%@AE@%%@NL@%
  11176.   %@AS@%            IRPC    x,0123456789%@AE@%%@NL@%
  11177.   %@AS@%            DB      x%@AE@%%@NL@%
  11178.   %@AS@%            ENDM%@AE@%%@NL@%
  11179. %@NL@%
  11180. %@4@%  Example 1 repeats the %@AB@%DB%@AE@% directive 10 times, once for each character in%@EH@%
  11181.   the string %@AS@%0123456789%@AE@%. The resulting statements create 10 bytes of data
  11182.   having the values 0-9.%@NL@%
  11183. %@NL@%
  11184. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  11185. %@NL@%
  11186.   %@AS@%            IRPC    letter,ABCDEFGHIJKLMNOPQRSTUVWXYZ%@AE@%%@NL@%
  11187.   %@AS@%            DB      '&letter'          ; Allocate uppercase letter%@AE@%%@NL@%
  11188.   %@AS@%            DB      '&letter'+20h      ; Allocate lowercase letter%@AE@%%@NL@%
  11189.   %@AS@%            DB      '&letter'-40h      ; Allocate number of letter%@AE@%%@NL@%
  11190.   %@AS@%            ENDM%@AE@%%@NL@%
  11191. %@NL@%
  11192. %@4@%  Example 2 allocates the ASCII codes for uppercase, lowercase, and numeric%@EH@%
  11193.   versions of each letter in the string. Notice that the substitute operator
  11194.   (%@AB@%&%@AE@%) is required so that %@AS@%letter %@AE@%will be treated as an argument rather than
  11195.   a string. See Section 11.5.1%@BO:       9a58b@%, "Substitute Operator," for more
  11196.   information.%@NL@%
  11197. %@NL@%
  11198. %@NL@%
  11199. %@2@%%@CR:SC11.5      @%%@AB@%11.5  Using Macro Operators%@AE@%%@EH@%%@NL@%
  11200. %@NL@%
  11201. %@4@%%@CR:IX11.101    @%%@CR:IX11.102    @%%@CR:IX11.103    @%  Macro and conditional directives use the following special set of macro%@EH@%
  11202.   operators:%@NL@%
  11203. %@NL@%
  11204.   %@AB@%Operator%@AE@%            %@AB@%Definition%@AE@%%@NL@%
  11205.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  11206.   %@AB@%&%@AE@%                   Substitute operator%@NL@%
  11207. %@NL@%
  11208.   %@AB@%<>%@AE@%                  Literal-text operator%@NL@%
  11209. %@NL@%
  11210.   %@AB@%!%@AE@%                   Literal-character operator%@NL@%
  11211. %@NL@%
  11212.   %@AB@%%%@AE@%                   Expression operator%@NL@%
  11213. %@NL@%
  11214.   %@AB@%;;%@AE@%                  Macro comment%@NL@%
  11215. %@NL@%
  11216. %@NL@%
  11217. %@4@%  When used in a macro definition, a macro call, a repeat block, or as the%@EH@%
  11218.   argument of a conditional-assembly directive, these operators carry out
  11219.   special control operations, such as text substitution.%@NL@%
  11220. %@NL@%
  11221. %@NL@%
  11222. %@3@%%@CR:SC11.5.1    @%%@AB@%11.5.1  Substitute Operator%@AE@%%@EH@%%@NL@%
  11223. %@NL@%
  11224. %@4@%%@CR:IX11.104    @%%@CR:IX11.105    @%%@CR:IX11.106    @%%@CR:IX11.107    @%  The substitute operator (%@AB@%&%@AE@%) enables substitution of macro parameters to%@EH@%
  11225.   take place, even when the parameter occurs within a larger word or within
  11226.   a quoted string.%@NL@%
  11227. %@NL@%
  11228. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11229. %@NL@%
  11230. %@4@%  You can use the substitute operator in any one of three different ways:%@EH@%%@NL@%
  11231. %@NL@%
  11232. %@4@%  %@AI@%name1%@AE@%%@AB@%&%@AE@%%@AI@%name2%@AE@%%@EH@%%@NL@%
  11233.   %@AI@%name%@AE@%%@AB@%&%@AE@%%@NL@%
  11234.   %@AB@%&%@AE@%%@AI@%name%@AE@%%@NL@%
  11235. %@NL@%
  11236. %@4@%  The assembler responds by analyzing %@AI@%name1%@AE@% and %@AI@%name2%@AE@% separately, then%@EH@%
  11237.   joining them together. If either %@AI@%name1%@AE@% or %@AI@%name2%@AE@% is a parameter, the
  11238.   assembler replaces each parameter by an actual argument before joining the
  11239.   names. You can join any number of names with the substitute operator, so
  11240.   that items such as %@AS@%a&b&c %@AE@%are valid.%@NL@%
  11241. %@NL@%
  11242. %@4@%  The last two forms are useful when a parameter name appears within a%@EH@%
  11243.   quoted string. The assembler responds by substituting the actual argument
  11244.   for the parameter; when not next to an ampersand (%@AB@%&%@AE@%), the assembler
  11245.   considers the parameter name just part of the string data.%@NL@%
  11246. %@NL@%
  11247. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11248. %@NL@%
  11249.   %@AS@%declare     MACRO   x,y%@AE@%%@NL@%
  11250.   %@AS@%xy          DW      0%@AE@%%@NL@%
  11251.   %@AS@%x&y         DW      0%@AE@%%@NL@%
  11252.   %@AS@%x&str       DB      'x and y params are &x and &y'%@AE@%%@NL@%
  11253.   %@AS@%            ENDM%@AE@%%@NL@%
  11254. %@NL@%
  11255. %@4@%  The example above demonstrates how the presence or absence of the%@EH@%
  11256.   substitute operator affects macro substitution. Given the macro definition
  11257.   above, the statement%@NL@%
  11258. %@NL@%
  11259.   %@AS@%            declare foot,ball%@AE@%%@NL@%
  11260. %@NL@%
  11261. %@4@%  is expanded to%@EH@%%@NL@%
  11262. %@NL@%
  11263.   %@AS@%xy          DW%@AE@%%@NL@%
  11264.   %@AS@%football    DW      0%@AE@%%@NL@%
  11265.   %@AS@%footstr     DB      'x and y params are foot and ball'%@AE@%%@NL@%
  11266. %@NL@%
  11267. %@4@%  In the first statement of the macro, %@AS@%xy %@AE@%is not identified with either of%@EH@%
  11268.   the parameters %@AS@%x %@AE@%or %@AS@%y%@AE@%; instead, %@AS@%xy %@AE@%forms a distinct name. No substitution
  11269.   takes place. In the second statement, the assembler interprets %@AS@%x&y %@AE@%by
  11270.   analyzing %@AS@%x %@AE@%and %@AS@%y %@AE@%as separate names, performing the appropriate parameter
  11271.   substitution in each case, and then joining the resulting names together.%@NL@%
  11272. %@NL@%
  11273. %@4@%  When you use the substitute operator with nested macros and repeat blocks,%@EH@%
  11274.   the assembler applies the following rules to expressions outside of
  11275.   quotes:%@NL@%
  11276. %@NL@%
  11277.   1. Perform parameter substitution as described above.%@NL@%
  11278. %@NL@%
  11279.   2. Remove exactly one of the substitute operators (%@AB@%&%@AE@%) from the group. The
  11280.      assembler strips off an operator whether or not a parameter was
  11281.      substituted.%@NL@%
  11282. %@NL@%
  11283. %@4@%  The number of ampersands (%@AB@%&%@AE@%) you use should never be greater than the%@EH@%
  11284.   number of levels of nesting. If you use too few ampersands, proper
  11285.   substitution will not take place. If you use too many ampersands, text
  11286.   such as%@AS@% x&y %@AE@%will remain after macro expansion is complete. Such
  11287.   expressions are invalid.%@NL@%
  11288. %@NL@%
  11289. %@4@%  When an ampersand appears inside quotes, the assembler removes ampersands%@EH@%
  11290.   on either side of a macro parameter when substitution is possible. When
  11291.   substitution is not possible (because the parameter name is not defined at
  11292.   the current level of nesting), the assembler leaves the ampersand as it
  11293.   is. With this method, parameter substitution automatically takes place at
  11294.   the appropriate level of nesting.%@NL@%
  11295. %@NL@%
  11296. %@NL@%
  11297. %@3@%%@CR:SC11.5.2    @%%@AB@%11.5.2  Literal-Text Operator%@AE@%%@EH@%%@NL@%
  11298. %@NL@%
  11299. %@4@%%@CR:IX11.108    @%  The literal-text operator (%@AB@%< >%@AE@%) directs QuickAssembler to treat a list as%@EH@%
  11300.   a single string rather than as separate arguments.%@NL@%
  11301. %@NL@%
  11302. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11303. %@NL@%
  11304. %@4@%  %@AB@%<%@AE@%%@AI@%text%@AE@% %@AB@%>%@AE@%%@EH@%%@NL@%
  11305. %@NL@%
  11306. %@4@%  The %@AI@%text%@AE@% is considered a single literal element even if it contains%@EH@%
  11307.   commas, spaces, or tabs. The literal-text operator is most often used in
  11308.   macro calls and with the %@AB@%IRP%@AE@% directive to ensure that values in a
  11309.   parameter list are treated as a single parameter.%@NL@%
  11310. %@NL@%
  11311. %@4@%  The literal-text operator can also be used to force QuickAssembler to%@EH@%
  11312.   treat special characters, such as the semicolon or the ampersand,
  11313.   literally. For example, the semicolon inside angle brackets %@AB@%<;>%@AE@% becomes a
  11314.   semicolon, not a comment indicator.%@NL@%
  11315. %@NL@%
  11316. %@4@%  QuickAssembler removes one set of angle brackets each time the parameter%@EH@%
  11317.   is used in a macro. When using nested macros, you will need to supply as
  11318.   many sets of angle brackets as there are levels of nesting.%@NL@%
  11319. %@NL@%
  11320. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11321. %@NL@%
  11322.   %@AS@%            work    1,2,3,4,5          ; Passes five parameters to "work"%@AE@%%@NL@%
  11323. %@NL@%
  11324.   %@AS@%            work    <1,2,3,4,5>        ; Passes one five-element%@AE@%%@NL@%
  11325.   %@AS@%                                       ;   parameter to "work"%@AE@%%@NL@%
  11326. %@NL@%
  11327. %@4@%  When the%@AB@% IRP%@AE@% directive is used inside a macro definition and when the%@EH@%
  11328.   argument list of the %@AB@%IRP%@AE@% directive is also a parameter of the macro, you
  11329.   must use the literal-text operator (%@AB@%< >%@AE@%) to enclose the macro parameter.%@NL@%
  11330. %@NL@%
  11331. %@4@%  For example, in the following macro definition, the parameter %@AS@%x %@AE@%is used as%@EH@%
  11332.   the argument list for the%@AB@% IRP%@AE@% directive:%@NL@%
  11333. %@NL@%
  11334.   %@AS@%init        MACRO   x%@AE@%%@NL@%
  11335.   %@AS@%            IRP     y,<x>%@AE@%%@NL@%
  11336.   %@AS@%            DB      y%@AE@%%@NL@%
  11337.   %@AS@%            ENDM%@AE@%%@NL@%
  11338.   %@AS@%            ENDM%@AE@%%@NL@%
  11339. %@NL@%
  11340. %@4@%  If this macro is called with%@EH@%%@NL@%
  11341. %@NL@%
  11342.   %@AS@%            init    <0,1,2,3,4,5,6,7,8,9>%@AE@%%@NL@%
  11343. %@NL@%
  11344. %@4@%  the macro removes the angle brackets from the parameter so that it is%@EH@%
  11345.   expanded as %@AS@%0,1,2,3,4,5,6,7,8,9%@AE@%. The brackets inside the repeat block are
  11346.   necessary to put the angle brackets back on. The repeat block is then
  11347.   expanded as shown below:%@NL@%
  11348. %@NL@%
  11349.   %@AS@%            IRP     y,<0,1,2,3,4,5,6,7,8,9>%@AE@%%@NL@%
  11350.   %@AS@%            DB      y%@AE@%%@NL@%
  11351.   %@AS@%            ENDM%@AE@%%@NL@%
  11352. %@NL@%
  11353. %@NL@%
  11354. %@3@%%@CR:SC11.5.3    @%%@AB@%11.5.3  Literal-Character Operator%@AE@%%@EH@%%@NL@%
  11355. %@NL@%
  11356. %@4@%%@CR:IX11.109    @%%@CR:IX11.110    @%%@CR:IX11.111    @%%@CR:IX11.112    @%  The literal-character operator (%@AB@%!%@AE@%) forces the assembler to treat a%@EH@%
  11357.   specified character literally rather than as a symbol.%@NL@%
  11358. %@NL@%
  11359. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11360. %@NL@%
  11361. %@4@%  %@AB@%!%@AE@%%@AI@%character%@AE@%%@EH@%%@NL@%
  11362. %@NL@%
  11363. %@4@%  The literal-character operator is used with special characters, such as%@EH@%
  11364.   the semicolon or ampersand, when meaning of the special character must be
  11365.   suppressed. Using the literal-character operator is the same as enclosing
  11366.   a single character in brackets. For example, %@AS@%!!%@AE@% is the same as %@AS@%<!>.%@AE@%%@NL@%
  11367. %@NL@%
  11368. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11369. %@NL@%
  11370.   %@AS@%errgen      MACRO   y,x%@AE@%%@NL@%
  11371.   %@AS@%            PUBLIC  err&y%@AE@%%@NL@%
  11372.   %@AS@%err&y       DB      'Error &y: &x'%@AE@%%@NL@%
  11373.   %@AS@%            ENDMW%@AE@%%@NL@%
  11374. %@NL@%
  11375.   %@AS@%            .%@AE@%%@NL@%
  11376.   %@AS@%            .%@AE@%%@NL@%
  11377.   %@AS@%            .%@AE@%%@NL@%
  11378.   %@AS@%            errgen  103,<Expression !> 255>%@AE@%%@NL@%
  11379. %@NL@%
  11380. %@4@%  The example macro call is expanded to allocate the string %@AS@%Error 103:%@AE@%%@EH@%
  11381.   %@AS@%Expression > 255%@AE@%. Without the literal-character operator, the greater-than
  11382.   symbol would be interpreted as the end of the argument and an error would
  11383.   result.%@NL@%
  11384. %@NL@%
  11385. %@NL@%
  11386. %@3@%%@CR:SC11.5.4    @%%@AB@%11.5.4  Expression Operator%@AE@%%@EH@%%@NL@%
  11387. %@NL@%
  11388. %@4@%%@CR:IX11.113    @%%@CR:IX11.114    @%%@CR:IX11.115    @%%@CR:IX11.116    @%  The expression operator (%@AB@%%%@AE@%) causes the assembler to treat the argument%@EH@%
  11389.   following the operator as an expression.%@NL@%
  11390. %@NL@%
  11391. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11392. %@NL@%
  11393. %@4@%  %@AB@%%%@AE@%%@AI@%text%@AE@%%@EH@%%@NL@%
  11394. %@NL@%
  11395. %@4@%  QuickAssembler computes the expression's value and replaces %@AI@%text%@AE@% with the%@EH@%
  11396.   result. The expression can be either a numeric expression or a text
  11397.   equate. Additional arguments after an argument that uses the expression
  11398.   operator must be preceded by a comma, not a space or tab.%@NL@%
  11399. %@NL@%
  11400. %@4@%  The expression operator is typically used in macro calls when the%@EH@%
  11401.   programmer needs to pass the result of an expression rather than the
  11402.   actual expression to a macro.%@NL@%
  11403. %@NL@%
  11404. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11405. %@NL@%
  11406.   %@AS@%printe      MACRO   exp,val%@AE@%%@NL@%
  11407.   %@AS@%            IF1                        ;; On pass 1 only%@AE@%%@NL@%
  11408.   %@AS@%            %OUT    exp = val          ;; Display expression and result%@AE@%%@NL@%
  11409.   %@AS@%            ENDIF                      ;;   to screen%@AE@%%@NL@%
  11410.   %@AS@%            ENDM%@AE@%%@NL@%
  11411. %@NL@%
  11412.   %@AS@%sym1        EQU     100%@AE@%%@NL@%
  11413.   %@AS@%sym2        EQU     200%@AE@%%@NL@%
  11414.   %@AS@%msg         EQU     <"Hello, World.">%@AE@%%@NL@%
  11415. %@NL@%
  11416.   %@AS@%            printe  <sym1 + sym2>,%(sym1 + sym2)%@AE@%%@NL@%
  11417.   %@AS@%            printe  msg,%msg%@AE@%%@NL@%
  11418. %@NL@%
  11419. %@4@%  In the first macro call, the text literal %@AS@%sym1 + sym2 = %@AE@%is passed to the%@EH@%
  11420.   parameter %@AS@%exp%@AE@%, and the result of the expression is passed to the parameter
  11421.   %@AS@%val%@AE@%. In the second macro call, the equate name %@AS@%msg%@AE@% is passed to the
  11422.   parameter %@AS@%exp%@AE@%, and the text of the equate is passed to the parameter %@AS@%val%@AE@%.
  11423.   As a result, Quick-Assembler displays the following messages:%@NL@%
  11424. %@NL@%
  11425.   %@AS@%sym1 + sym2 = 300%@AE@%%@NL@%
  11426.   %@AS@%msg = "Hello, World."%@AE@%%@NL@%
  11427. %@NL@%
  11428. %@4@%  The %@AB@%%OUT%@AE@% directive, which sends a message to the screen, is described in%@EH@%
  11429.   Section 12.1%@BO:       a2455@%, "Sending Messages to the Standard Output Device"; the %@AB@%IF1%@AE@%
  11430.   directive is described in Section 10.1.2%@BO:       87b1f@%, "Testing the Pass with IF1 and
  11431.   IF2 Directives."%@NL@%
  11432. %@NL@%
  11433. %@4@%  You can also use the expression operator (%@AB@%%%@AE@%) to substitute the values of%@EH@%
  11434.   text macros for the macro names anywhere a text-macro name appears. When
  11435.   the expression operator is the first item on a line and is followed by one
  11436.   or more blanks or tabs, the line is scanned for text macros and the values
  11437.   of the macros are substituted. Using the expression operator, you can
  11438.   force substitution of text macros wherever they appear in a line. The
  11439.   assembler re-scans the line until all substitutions have been made.%@NL@%
  11440. %@NL@%
  11441.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  11442.   %@AB@%NOTE%@AE@%  Text macros are always evaluated when they appear in the name or
  11443.   operation fields. The expression operator is required to evaluate a text
  11444.   macro only when the macro appears in the operand field.%@NL@%
  11445.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  11446. %@NL@%
  11447. %@4@%  This use of the expression operator eliminates the need to do a macro call%@EH@%
  11448.   in order to evaluate a text macro. For example, the following macro uses a
  11449.   separate macro, %@AS@%popregs%@AE@%, to evaluate the text macro %@AS@%regpushed%@AE@%:%@NL@%
  11450. %@NL@%
  11451.   %@AS@%regpushed   EQU     <ax,bx,cx>%@AE@%%@NL@%
  11452.   %@AS@%            .%@AE@%%@NL@%
  11453.   %@AS@%            .%@AE@%%@NL@%
  11454.   %@AS@%            .%@AE@%%@NL@%
  11455.   %@AS@%RestRegs    MACRO%@AE@%%@NL@%
  11456.   %@AS@%            popregs %regpushed%@AE@%%@NL@%
  11457.   %@AS@%            ENDM%@AE@%%@NL@%
  11458. %@NL@%
  11459.   %@AS@%popregs     MACRO   reglist%@AE@%%@NL@%
  11460.   %@AS@%            IRP     reg,<reglist>%@AE@%%@NL@%
  11461.   %@AS@%               pop  reg%@AE@%%@NL@%
  11462.   %@AS@%            ENDM%@AE@%%@NL@%
  11463.   %@AS@%            ENDM%@AE@%%@NL@%
  11464. %@NL@%
  11465. %@4@%  The use of the expression operator to evaluate text macros in a line makes%@EH@%
  11466.   the %@AS@%popregs %@AE@%macro unnecessary:%@NL@%
  11467. %@NL@%
  11468.   %@AS@%regpushed   EQU     <ax,bx,cx>%@AE@%%@NL@%
  11469.   %@AS@%            .%@AE@%%@NL@%
  11470.   %@AS@%            .%@AE@%%@NL@%
  11471.   %@AS@%            .%@AE@%%@NL@%
  11472.   %@AS@%RestRegs    MACRO%@AE@%%@NL@%
  11473.   %@AS@%  %         IRP     reg,<regpushed>   ;; % operator makes%@AE@%%@NL@%
  11474.   %@AS@%                                      ;;   separate macro unnecessary%@AE@%%@NL@%
  11475.   %@AS@%               pop  reg%@AE@%%@NL@%
  11476.   %@AS@%            ENDM%@AE@%%@NL@%
  11477.   %@AS@%            ENDM%@AE@%%@NL@%
  11478. %@NL@%
  11479. %@4@%  You cannot use the %@AB@%EQU%@AE@% directive to assign a value to a text macro in a%@EH@%
  11480.   line evaluated with the expression operator. For example, the following
  11481.   lines generate an error:%@NL@%
  11482. %@NL@%
  11483.   %@AS@%strpos      EQU  <[si]+12>%@AE@%%@NL@%
  11484.   %@AS@%.%@AE@%%@NL@%
  11485.   %@AS@%.%@AE@%%@NL@%
  11486.   %@AS@%.%@AE@%%@NL@%
  11487.   %@AS@%% wpstrpos  EQU  <WORD PTR strpos>%@AE@%%@NL@%
  11488. %@NL@%
  11489. %@4@%  On pass 1, %@AS@%wpstrpos %@AE@%is defined as a text macro that is expanded on pass 2.%@EH@%
  11490.   Thus, on pass 2 the second %@AB@%EQU%@AE@% directive becomes%@NL@%
  11491. %@NL@%
  11492.   %@AS@%WORD PTR [si]+12     EQU  <WORD PTR [si]+12>%@AE@%%@NL@%
  11493. %@NL@%
  11494. %@4@%  and generates an error.%@EH@%%@NL@%
  11495. %@NL@%
  11496. %@4@%  Instead, use the %@AB@%CATSTR%@AE@% directive to assign values to text macros (see%@EH@%
  11497.   Section 11.3%@BO:       95341@%, "Text-Macro String Directives," for more information about
  11498.   %@AB@%CATSTR%@AE@% and other text-macro string directives). The previous example
  11499.   should be rewritten as follows:%@NL@%
  11500. %@NL@%
  11501.   %@AS@%strpos      EQU  <[si]+12>%@AE@%%@NL@%
  11502.   %@AS@%.%@AE@%%@NL@%
  11503.   %@AS@%.%@AE@%%@NL@%
  11504.   %@AS@%.%@AE@%%@NL@%
  11505.   %@AS@%wpstrpos    CATSTR  <WORD PTR >, strpos%@AE@%%@NL@%
  11506. %@NL@%
  11507. %@4@%  If the text macro evaluates to a valid name, there is no error when you%@EH@%
  11508.   use %@AB@%EQU%@AE@%. The following lines do not generate an error, but define two
  11509.   names, one (%@AS@%numlabel%@AE@%) with the value %@AS@%5%@AE@%, the other (%@AS@%tmacro%@AE@%) with the value
  11510.   %@AS@%<numlabel>%@AE@%:%@NL@%
  11511. %@NL@%
  11512.   %@AS@%tmacro      EQU  <numlabel>%@AE@%%@NL@%
  11513.   %@AS@%% tmacro    EQU  5%@AE@%%@NL@%
  11514. %@NL@%
  11515. %@4@%  You can also use the substitution operator (%@AB@%&%@AE@%) with text macros just as%@EH@%
  11516.   you would inside a macro:%@NL@%
  11517. %@NL@%
  11518.   %@AS@%SegName          EQU   <MySeg>%@AE@%%@NL@%
  11519.   %@AS@%.%@AE@%%@NL@%
  11520.   %@AS@%.%@AE@%%@NL@%
  11521.   %@AS@%.%@AE@%%@NL@%
  11522.   %@AS@%% SegName&_text  SEGMENT PUBLIC 'CODE'%@AE@%%@NL@%
  11523. %@NL@%
  11524. %@4@%  The final line, after expanding the text macro, becomes:%@EH@%%@NL@%
  11525. %@NL@%
  11526.   %@AS@%MySeg_text       SEGMENT PUBLIC 'CODE'%@AE@%%@NL@%
  11527. %@NL@%
  11528. %@4@%  The substitution operator separates the text-macro name from the text that%@EH@%
  11529.   immediately follows it. The name appears to the assembler as %@AS@%segName_text%@AE@%
  11530.   without the substitution operator, and the assembler fails to recognize
  11531.   the text macro.%@NL@%
  11532. %@NL@%
  11533. %@NL@%
  11534. %@3@%%@CR:SC11.5.5    @%%@AB@%11.5.5  Macro Comments%@AE@%%@EH@%%@NL@%
  11535. %@NL@%
  11536. %@4@%%@CR:IX11.117    @%%@CR:IX11.118    @%%@CR:IX11.119    @%%@CR:IX11.120    @%  A macro comment is any text in a macro definition that does not need to be%@EH@%
  11537.   copied in the macro expansion. A double semicolon (%@AB@%;;%@AE@%) is used to start a
  11538.   macro comment.%@NL@%
  11539. %@NL@%
  11540. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11541. %@NL@%
  11542. %@4@%  %@AB@%;;%@AE@%%@AI@%text%@AE@%%@EH@%%@NL@%
  11543. %@NL@%
  11544. %@4@%  All %@AI@%text%@AE@% following the double semicolon (%@AB@%;;%@AE@%) is ignored by the assembler%@EH@%
  11545.   and will appear only in the macro definition when the source listing is
  11546.   created.%@NL@%
  11547. %@NL@%
  11548. %@4@%  The regular comment operator (%@AB@%;%@AE@%) can also be used in macros. However,%@EH@%
  11549.   regular comments may appear in listings when the macro is expanded. Macro
  11550.   comments will appear in the macro definition, but not in macro expansions.
  11551.   Whether or not regular comments are listed in macro expansions depends on
  11552.   the use of the %@AB@%.LALL%@AE@%, %@AB@%.XALL%@AE@%, and %@AB@%.SALL%@AE@% directives, as described in Section
  11553.   12.2.3%@BO:       a39b9@%, "Controlling Page Breaks."%@NL@%
  11554. %@NL@%
  11555. %@NL@%
  11556. %@2@%%@CR:SC11.6      @%%@AB@%11.6  Using Recursive, Nested, and Redefined Macros%@AE@%%@EH@%%@NL@%
  11557. %@NL@%
  11558. %@4@%  The concept of replacing macro names with predefined macro text is simple,%@EH@%
  11559.   but in practice it has many implications and potentially unexpected side
  11560.   effects. The following sections discuss advanced macro features (such as
  11561.   nesting, recursion, and redefinition) and point out some side effects of
  11562.   macros.%@NL@%
  11563. %@NL@%
  11564. %@NL@%
  11565. %@3@%%@CR:SC11.6.1    @%%@AB@%11.6.1  Using Recursion%@AE@%%@EH@%%@NL@%
  11566. %@NL@%
  11567. %@4@%%@CR:IX11.121    @%%@CR:IX11.122    @%  Macro definitions can be recursive: that is, they can call themselves.%@EH@%
  11568.   Using recursive macros is one way of doing repeated operations. The macro
  11569.   does a task, and then calls itself to do the task again. The recursion is
  11570.   repeated until a specified condition is met.%@NL@%
  11571. %@NL@%
  11572. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11573. %@NL@%
  11574.   %@AS@%pushall     MACRO   reg1,reg2,reg3,reg4,reg5,reg6%@AE@%%@NL@%
  11575.   %@AS@%            IFNB    <reg1>         ;; If parameter not blank%@AE@%%@NL@%
  11576.   %@AS@%            push    reg1           ;;   push one register and repeat%@AE@%%@NL@%
  11577.   %@AS@%            pushall reg2,reg3,reg4,reg5,reg6%@AE@%%@NL@%
  11578.   %@AS@%            ENDIF%@AE@%%@NL@%
  11579.   %@AS@%            ENDM%@AE@%%@NL@%
  11580.   %@AS@%            .%@AE@%%@NL@%
  11581.   %@AS@%            .%@AE@%%@NL@%
  11582.   %@AS@%            .%@AE@%%@NL@%
  11583.   %@AS@%pushall     ax,bx,si,ds%@AE@%%@NL@%
  11584.   %@AS@%pushall     cs,es%@AE@%%@NL@%
  11585. %@NL@%
  11586. %@4@%  In this example, the %@AS@%pushall%@AE@% macro repeatedly calls itself to push a%@EH@%
  11587.   register given in a parameter until no parameters are left to push. A
  11588.   variable number of parameters (up to six) can be given.%@NL@%
  11589. %@NL@%
  11590. %@NL@%
  11591. %@3@%%@CR:SC11.6.2    @%%@AB@%11.6.2  Nesting Macro Definitions%@AE@%%@EH@%%@NL@%
  11592. %@NL@%
  11593. %@4@%%@CR:IX11.123    @%%@CR:IX11.124    @%  One macro can define another. QuickAssembler does not process nested%@EH@%
  11594.   definitions until the outer macro has been called. Therefore, nested
  11595.   macros cannot be called until the outer macro has been called at least
  11596.   once. Macro definitions can be nested to any depth. Nesting is limited
  11597.   only by the amount of memory available when the source file is assembled.
  11598.   Using a macro to create similar macros can make maintenance easier. If you
  11599.   want to change all the macros, change the outer macro and it automatically
  11600.   changes the others.%@NL@%
  11601. %@NL@%
  11602. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11603. %@NL@%
  11604.   %@AS@%shifts      MACRO   opname             ; Define macro that defines macros%@AE@%%@NL@%
  11605.   %@AS@%opname&s    MACRO   operand,rotates%@AE@%%@NL@%
  11606.   %@AS@%            IF      rotates LE 4%@AE@%%@NL@%
  11607.   %@AS@%            REPT    rotates%@AE@%%@NL@%
  11608.   %@AS@%            opname  operand,1          ;; One at a time is faster%@AE@%%@NL@%
  11609.   %@AS@%            ENDM                       ;;   for 4 or less on 8088/8086%@AE@%%@NL@%
  11610.   %@AS@%            ELSE%@AE@%%@NL@%
  11611.   %@AS@%            mov     cl,rotates         ;; Using CL is faster%@AE@%%@NL@%
  11612.   %@AS@%            opname  operand,cl         ;;   for more than 4 on 8088/8086%@AE@%%@NL@%
  11613.   %@AS@%            ENDIF%@AE@%%@NL@%
  11614.   %@AS@%            ENDM%@AE@%%@NL@%
  11615.   %@AS@%            ENDM%@AE@%%@NL@%
  11616. %@NL@%
  11617.   %@AS@%            shifts  ror                ; Call macro to new macros%@AE@%%@NL@%
  11618.   %@AS@%            shifts  rol%@AE@%%@NL@%
  11619.   %@AS@%            shifts  shr%@AE@%%@NL@%
  11620.   %@AS@%            shifts  shl%@AE@%%@NL@%
  11621.   %@AS@%            shifts  rcl%@AE@%%@NL@%
  11622.   %@AS@%            shifts  rcr%@AE@%%@NL@%
  11623.   %@AS@%            shifts  sal%@AE@%%@NL@%
  11624.   %@AS@%            shifts  sar%@AE@%%@NL@%
  11625.   %@AS@%            .%@AE@%%@NL@%
  11626.   %@AS@%            .%@AE@%%@NL@%
  11627.   %@AS@%            .%@AE@%%@NL@%
  11628.   %@AS@%            shrs    ax,5               ; Call defined macros%@AE@%%@NL@%
  11629.   %@AS@%            rols    bx,3%@AE@%%@NL@%
  11630. %@NL@%
  11631. %@4@%  This macro, when called as shown, creates macros for multiple shifts with%@EH@%
  11632.   each of the shift and rotate instructions. All the macro names are
  11633.   identical except for the instruction. For example, the macro for the %@AB@%SHR%@AE@%
  11634.   instruction is called %@AS@%shrs%@AE@%; the macro for the %@AB@%ROL%@AE@% instruction is called
  11635.   %@AS@%rols%@AE@%. If you want to enhance the macros by doing more parameter checking,
  11636.   you can modify the original macro. Doing so will change the created macros
  11637.   automatically. This macro uses the substitute operator, as described in
  11638.   Section 11.5.1%@BO:       9a58b@%.%@NL@%
  11639. %@NL@%
  11640. %@NL@%
  11641. %@3@%%@CR:SC11.6.3    @%%@AB@%11.6.3  Nesting Macro Calls%@AE@%%@EH@%%@NL@%
  11642. %@NL@%
  11643. %@4@%  Macro definitions can contain calls to other macros. Nested macro calls%@EH@%
  11644.   are expanded like any other macro call, but only when the outer macro is
  11645.   called.%@NL@%
  11646. %@NL@%
  11647. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11648. %@NL@%
  11649.   %@AS@%ex          MACRO   text,val   ; Inner macro definition%@AE@%%@NL@%
  11650.   %@AS@%            IF2%@AE@%%@NL@%
  11651.   %@AS@%            %OUT    The expression (text) has the value: &val%@AE@%%@NL@%
  11652.   %@AS@%            ENDIF%@AE@%%@NL@%
  11653.   %@AS@%            ENDM%@AE@%%@NL@%
  11654. %@NL@%
  11655.   %@AS@%express     MACRO   expression ; Outer macro definition%@AE@%%@NL@%
  11656.   %@AS@%            ex      <expression>,%(expression)%@AE@%%@NL@%
  11657.   %@AS@%            ENDM%@AE@%%@NL@%
  11658.   %@AS@%            .%@AE@%%@NL@%
  11659.   %@AS@%            .%@AE@%%@NL@%
  11660.   %@AS@%            .%@AE@%%@NL@%
  11661.   %@AS@%            express <4 + 2 * 7 - 3 MOD 4>%@AE@%%@NL@%
  11662. %@NL@%
  11663. %@4@%  The two sample macros enable you to print the result of a complex%@EH@%
  11664.   expression to the screen by using the %@AB@%%OUT%@AE@% directive, even though that
  11665.   directive expects text rather than an expression (see Section 12.1%@BO:       a2455@%,
  11666.   "Sending Messages to the Standard Output Device"). Being able to see the
  11667.   value of an expression is convenient during debugging.%@NL@%
  11668. %@NL@%
  11669. %@4@%  Both macros are necessary. The %@AS@%express%@AE@% macro calls the %@AS@%ex%@AE@% macro, using%@EH@%
  11670.   operators to pass the expression both as text and as the value of the
  11671.   expression. With the call in the example, the assembler sends the
  11672.   following line to the standard output:%@NL@%
  11673. %@NL@%
  11674.   %@AS@%The expression (4 + 2 * 7 - 3 MOD 4) has the value: 15%@AE@%%@NL@%
  11675. %@NL@%
  11676. %@4@%  You could get the same output by using only the %@AS@%ex%@AE@% macro, but you would%@EH@%
  11677.   have to type the expression twice and supply the macro operators in the
  11678.   correct places yourself. The %@AS@%express%@AE@% macro does this for you
  11679.   automatically. Notice that expressions containing spaces must still be
  11680.   enclosed in angle brackets. Section 11.5.2%@BO:       9b48f@%, "Literal-Text Operator,"
  11681.   explains why.%@NL@%
  11682. %@NL@%
  11683. %@NL@%
  11684. %@3@%%@CR:SC11.6.4    @%%@AB@%11.6.4  Redefining Macros%@AE@%%@EH@%%@NL@%
  11685. %@NL@%
  11686. %@4@%%@CR:IX11.125    @%%@CR:IX11.126    @%  Macros can be redefined. You do not need to purge the macro before%@EH@%
  11687.   redefining it. The new definition automatically replaces the old
  11688.   definition. If you redefine a macro from within the macro itself, make
  11689.   sure there are no statements or comments between the %@AB@%ENDM%@AE@% directive of the
  11690.   nested redefinition and the %@AB@%ENDM%@AE@% directive of the original macro.%@NL@%
  11691. %@NL@%
  11692. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11693. %@NL@%
  11694.   %@AS@%getasciiz   MACRO%@AE@%%@NL@%
  11695.   %@AS@%            .DATA%@AE@%%@NL@%
  11696.   %@AS@%max         DB      80%@AE@%%@NL@%
  11697.   %@AS@%actual      DB      ?%@AE@%%@NL@%
  11698.   %@AS@%tmpstr      DB      80 DUP (?)%@AE@%%@NL@%
  11699.   %@AS@%            .CODE%@AE@%%@NL@%
  11700.   %@AS@%            mov     ah,0Ah%@AE@%%@NL@%
  11701.   %@AS@%            mov     dx,OFFSET max%@AE@%%@NL@%
  11702.   %@AS@%            int     21h%@AE@%%@NL@%
  11703.   %@AS@%            mov     bl,actual%@AE@%%@NL@%
  11704.   %@AS@%            xor     bh,bh%@AE@%%@NL@%
  11705.   %@AS@%            mov     tmpstr[bx],0%@AE@%%@NL@%
  11706.   %@AS@%getasciiz   MACRO%@AE@%%@NL@%
  11707.   %@AS@%            mov     ah,0Ah%@AE@%%@NL@%
  11708.   %@AS@%            mov     dx,OFFSET max%@AE@%%@NL@%
  11709.   %@AS@%            int     21h%@AE@%%@NL@%
  11710.   %@AS@%            mov     bl,actual%@AE@%%@NL@%
  11711.   %@AS@%            xor     bh,bh%@AE@%%@NL@%
  11712.   %@AS@%            mov     tmpstr[bx],0%@AE@%%@NL@%
  11713.   %@AS@%            ENDM%@AE@%%@NL@%
  11714.   %@AS@%            ENDM%@AE@%%@NL@%
  11715. %@NL@%
  11716. %@4@%  This macro allocates data space the first time it is called, and then%@EH@%
  11717.   redefines itself so that it doesn't try to reallocate the data on
  11718.   subsequent calls.%@NL@%
  11719. %@NL@%
  11720. %@NL@%
  11721. %@3@%%@CR:SC11.6.5    @%%@AB@%11.6.5  Avoiding Inadvertent Substitutions%@AE@%%@EH@%%@NL@%
  11722. %@NL@%
  11723. %@4@%%@CR:IX11.127    @%%@CR:IX11.128    @%%@CR:IX11.129    @%%@CR:IX11.130    @%%@CR:IX11.131    @%  QuickAssembler replaces all parameters when they occur with the%@EH@%
  11724.   corresponding argument, even if the substitution is inappropriate. For
  11725.   example, if you use a register name, such as AX or BH, as a parameter,
  11726.   QuickAssembler replaces all occurrences of that name when it expands the
  11727.   macro. If the macro definition contains statements that use the register,
  11728.   not the parameter, the macro will be incorrectly expanded. QuickAssembler
  11729.   will not warn you about using reserved names as macro parameters.%@NL@%
  11730. %@NL@%
  11731. %@4@%%@CR:IX11.132    @%%@CR:IX11.133    @%  QuickAssembler does give a warning if you use a reserved name as a macro%@EH@%
  11732.   name. You can ignore the warning, but be aware that the reserved name will
  11733.   no longer have its original meaning. For example, if you define a macro
  11734.   called %@AS@%ADD%@AE@%, the %@AB@%ADD%@AE@% instruction will no longer be available. Your %@AS@%ADD%@AE@%
  11735.   macro takes its place.%@NL@%
  11736. %@NL@%
  11737. %@NL@%
  11738. %@2@%%@CR:SC11.7      @%%@AB@%11.7  Managing Macros and Equates%@AE@%%@EH@%%@NL@%
  11739. %@NL@%
  11740. %@4@%  Macros and equates are often kept in a separate file and read into the%@EH@%
  11741.   assembler source file at assembly time. In this way, libraries of related
  11742.   macros and equates can be used by many different source files.%@NL@%
  11743. %@NL@%
  11744. %@4@%  The%@AB@% INCLUDE %@AE@%directive is used to read an include file into a source file.%@EH@%
  11745.   Memory can be saved by using the %@AB@%PURGE%@AE@% directive to delete the unneeded
  11746.   macros from memory.%@NL@%
  11747. %@NL@%
  11748. %@NL@%
  11749. %@3@%%@CR:SC11.7.1    @%%@AB@%11.7.1  Using Include Files%@AE@%%@EH@%%@NL@%
  11750. %@NL@%
  11751. %@4@%%@CR:IX11.134    @%%@CR:IX11.135    @%%@CR:IX11.136    @%%@CR:IX11.137    @%%@CR:IX11.138    @%  The INCLUDE directive inserts source code from a specified file into the%@EH@%
  11752.   source file from which the directive is given.%@NL@%
  11753. %@NL@%
  11754. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11755. %@NL@%
  11756. %@4@%  %@AB@%INCLUDE %@AE@%%@AI@%filespec%@AE@%%@EH@%%@NL@%
  11757. %@NL@%
  11758. %@4@%%@CR:IX11.139    @%  The %@AI@%filespec%@AE@% must specify an existing file containing valid assembler%@EH@%
  11759.   statements. When the assembler encounters an %@AB@%INCLUDE%@AE@% directive, it opens
  11760.   the specified source file and begins processing its statements. When all
  11761.   statements have been read, QuickAssembler continues with the statement
  11762.   immediately following the %@AB@%INCLUDE%@AE@% directive.%@NL@%
  11763. %@NL@%
  11764. %@4@%  The %@AI@%filespec%@AE@% can be given either as a file name, or as a complete or%@EH@%
  11765.   relative file specification, including drive or directory name.%@NL@%
  11766. %@NL@%
  11767. %@4@%%@CR:IX11.140    @%  If a complete or relative file specification is given, QuickAssembler%@EH@%
  11768.   looks for the include file only in the specified directory. If a file name
  11769.   is given without a directory or drive name, QuickAssembler looks for the
  11770.   file in the following order:%@NL@%
  11771. %@NL@%
  11772. %@CR:IX11.141    @%%@CR:IX11.142    @%%@CR:IX11.143    @%%@CR:IX11.144    @%  1. If paths are specified with the /I option, QuickAssembler looks for the
  11773.      include file in the specified directory or directories.%@NL@%
  11774. %@NL@%
  11775.   2. QuickAssembler looks for the include file in the current directory.%@NL@%
  11776. %@NL@%
  11777.   3. If an %@AB@%INCLUDE%@AE@% environment variable is defined, QuickAssembler looks for
  11778.      the include file in the directory or directories specified in the
  11779.      environment variable.%@NL@%
  11780. %@NL@%
  11781. %@4@%%@CR:IX11.145    @%  Nested %@AB@%INCLUDE%@AE@% directives are allowed. QuickAssembler marks included%@EH@%
  11782.   statements with the letter "C" in assembly listings.%@NL@%
  11783. %@NL@%
  11784. %@4@%%@CR:IX11.146    @%  Directories can be specified in %@AB@%INCLUDE%@AE@% path names with either the%@EH@%
  11785.   backslash (%@AB@%\%@AE@%) or the forward slash (%@AB@%/%@AE@%). This is for XENIX(R)
  11786.   compatibility.%@NL@%
  11787. %@NL@%
  11788.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  11789.   %@AB@%NOTE%@AE@%  Any standard code can be placed in an include file. However, include
  11790.   files are usually used only for macros, equates, and standard segment
  11791.   definitions. Standard procedures are usually assembled into separate
  11792.   object files and linked with the main source modules.%@NL@%
  11793.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  11794. %@NL@%
  11795. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  11796. %@NL@%
  11797.   %@AS@%INCLUDE fileio.mac                   ; File name only; use with%@AE@%%@NL@%
  11798.   %@AS@%                                     ;   /I or environment%@AE@%%@NL@%
  11799.   %@AS@%INCLUDE b:\include\keybd.inc         ; Complete file specification%@AE@%%@NL@%
  11800. %@NL@%
  11801.   %@AS@%INCLUDE /usr/jons/include/stdio.mac  ; Path name in XENIX format%@AE@%%@NL@%
  11802. %@NL@%
  11803.   %@AS@%INCLUDE masm_inc\define.inc          ; Partial path name in DOS format%@AE@%%@NL@%
  11804.   %@AS@%                                     ;   (relative to current directory)%@AE@%%@NL@%
  11805. %@NL@%
  11806. %@NL@%
  11807. %@3@%%@CR:SC11.7.2    @%%@AB@%11.7.2  Purging Macros from Memory%@AE@%%@EH@%%@NL@%
  11808. %@NL@%
  11809. %@4@%%@CR:IX11.147    @%%@CR:IX11.148    @%%@CR:IX11.149    @%  The %@AB@%PURGE%@AE@% directive can be used to delete a currently defined macro from%@EH@%
  11810.   memory.%@NL@%
  11811. %@NL@%
  11812. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11813. %@NL@%
  11814. %@4@%  %@AB@%PURGE%@AE@% %@AI@%macroname%@AE@%[[%@AB@%,%@AE@%%@AI@%macroname%@AE@%]]...%@EH@%%@NL@%
  11815. %@NL@%
  11816. %@4@%  Each %@AI@%macroname%@AE@% is deleted from memory when the directive is encountered at%@EH@%
  11817.   assembly time. Any subsequent call to that macro causes the assembler to
  11818.   generate an error.%@NL@%
  11819. %@NL@%
  11820. %@4@%%@CR:IX11.150    @%%@CR:IX11.151    @%  The %@AB@%PURGE%@AE@% directive is intended to clear memory space no longer needed by%@EH@%
  11821.   a macro. If a macro has been used to redefine a reserved name, the
  11822.   reserved name is restored to its previous meaning.%@NL@%
  11823. %@NL@%
  11824. %@4@%%@CR:IX11.152    @%%@CR:IX11.153    @%  The %@AB@%PURGE%@AE@% directive can be used to clear memory if a macro or group of%@EH@%
  11825.   macros is needed only for part of a source file.%@NL@%
  11826. %@NL@%
  11827. %@4@%%@CR:IX11.154    @%  It is not necessary to purge a macro before redefining it. Any%@EH@%
  11828.   redefinition of a macro automatically purges the previous definition.
  11829.   Also, a macro can purge itself as long as the %@AB@%PURGE%@AE@% directive is on the
  11830.   last line of the macro.%@NL@%
  11831. %@NL@%
  11832. %@4@%  The %@AB@%PURGE%@AE@% directive works by redefining the macro to a null string.%@EH@%
  11833.   Therefore, calling a purged macro does not cause an error. The macro name
  11834.   is simply ignored.%@NL@%
  11835. %@NL@%
  11836. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  11837. %@NL@%
  11838.   %@AS@%            GetStuff%@AE@%%@NL@%
  11839.   %@AS@%            PURGE   GetStuff%@AE@%%@NL@%
  11840. %@NL@%
  11841. %@4@%  These examples call a macro and then purge it. You might need to purge%@EH@%
  11842.   macros in this way if your system does not have enough memory to keep all
  11843.   of the macros needed for a source file in memory at the same time.%@NL@%
  11844. %@NL@%
  11845. %@NL@%
  11846. %@NL@%
  11847. %@NL@%
  11848. ────────────────────────────────────────────────────────────────────────────%@NL@%
  11849. %@1@%%@CR:CH12        @%%@AB@%Chapter 12:  Controlling Assembly Output%@AE@%%@EH@%%@NL@%
  11850. %@NL@%
  11851. %@NL@%
  11852. %@4@%  QuickAssembler has two ways of communicating results. It can write%@EH@%
  11853.   information to a listing or object file, or it can display messages to the
  11854.   standard output device (normally the screen).%@NL@%
  11855. %@NL@%
  11856. %@4@%  Both kinds of output can be controlled by menu commands and by source-file%@EH@%
  11857.   statements. This chapter explains the directives that directly control
  11858.   output through source-file statements.%@NL@%
  11859. %@NL@%
  11860. %@NL@%
  11861. %@2@%%@CR:SC12.1      @%%@AB@%12.1  Sending Messages to the Standard Output Device%@AE@%%@EH@%%@NL@%
  11862. %@NL@%
  11863. %@4@%%@CR:IX12.1      @%%@CR:IX12.2      @%%@CR:IX12.3      @%%@CR:IX12.4      @%  The %@AB@%%OUT%@AE@% directive instructs the assembler to display text to the program%@EH@%
  11864.   output window.%@NL@%
  11865. %@NL@%
  11866. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11867. %@NL@%
  11868. %@4@%  %@AB@%%OUT%@AE@% %@AI@%text%@AE@%%@EH@%%@NL@%
  11869. %@NL@%
  11870. %@4@%  The %@AI@%text%@AE@% can be any line of ASCII characters. If you want to display%@EH@%
  11871.   multiple lines, you must use a separate %@AB@%%OUT%@AE@% directive for each line.%@NL@%
  11872. %@NL@%
  11873. %@4@%  The directive is useful for displaying messages at specific points of a%@EH@%
  11874.   long assembly. It can be used inside conditional-assembly blocks to
  11875.   display messages when certain conditions are met.%@NL@%
  11876. %@NL@%
  11877. %@4@%%@CR:IX12.5      @%%@CR:IX12.6      @%%@CR:IX12.7      @%%@CR:IX12.8      @%  The %@AB@%%OUT%@AE@% directive generates output for both assembly passes. The %@AB@%IF1%@AE@% and%@EH@%
  11878.   %@AB@%IF2%@AE@% directives can be used for control when the directive is processed.
  11879.   Macros that enable you to output the value of expressions are shown in
  11880.   Section 11.6.3%@BO:       9f74e@%, "Nesting Macro Calls."%@NL@%
  11881. %@NL@%
  11882. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11883. %@NL@%
  11884.   %@AS@%            IF1%@AE@%%@NL@%
  11885.   %@AS@%            %OUT    First Pass - OK%@AE@%%@NL@%
  11886.   %@AS@%            ENDIF%@AE@%%@NL@%
  11887. %@NL@%
  11888. %@4@%  This sample block could be placed at the end of a source file so that the%@EH@%
  11889.   message %@AS@%First Pass - OK %@AE@%would be displayed at the end of the first pass,
  11890.   but ignored on the second pass.%@NL@%
  11891. %@NL@%
  11892. %@NL@%
  11893. %@2@%%@CR:SC12.2      @%%@AB@%12.2  Controlling Page Format in Listings%@AE@%%@EH@%%@NL@%
  11894. %@NL@%
  11895. %@4@%%@CR:IX12.9      @%%@CR:IX12.10     @%%@CR:IX12.11     @%  QuickAssembler provides several directives for controlling the page format%@EH@%
  11896.   of listings. These directives include the following:%@NL@%
  11897. %@NL@%
  11898.   %@AB@%Directive%@AE@%           %@AB@%Action%@AE@%%@NL@%
  11899.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  11900.   %@AB@%TITLE%@AE@%               Sets title for listings%@NL@%
  11901. %@NL@%
  11902.   %@AB@%SUBTTL%@AE@%              Sets title for sections in listings%@NL@%
  11903. %@NL@%
  11904.   %@AB@%PAGE%@AE@%                Sets page length and width, and controls page and
  11905.                       section breaks%@NL@%
  11906. %@NL@%
  11907. %@NL@%
  11908. %@NL@%
  11909. %@3@%%@CR:SC12.2.1    @%%@AB@%12.2.1  Setting the Listing Title%@AE@%%@EH@%%@NL@%
  11910. %@NL@%
  11911. %@4@%%@CR:IX12.12     @%%@CR:IX12.13     @%%@CR:IX12.14     @%  The %@AB@%TITLE%@AE@% directive specifies a title to be used on each page of assembly%@EH@%
  11912.   listings. In editor-based listing files (the default inside the QC
  11913.   environment), the title is only printed once, at the top of the file.%@NL@%
  11914. %@NL@%
  11915. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11916. %@NL@%
  11917. %@4@%  %@AB@%TITLE %@AE@%%@AI@%text%@AE@%%@EH@%%@NL@%
  11918. %@NL@%
  11919. %@4@%  The %@AI@%text%@AE@% can be any combination of characters up to 60 in length. The%@EH@%
  11920.   title is printed flush left on the second line of each page of the
  11921.   listing.%@NL@%
  11922. %@NL@%
  11923. %@4@%  If no %@AB@%TITLE%@AE@% directive is given, the title will be blank. No more than one%@EH@%
  11924.   %@AB@%TITLE%@AE@% directive per module is allowed.%@NL@%
  11925. %@NL@%
  11926. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11927. %@NL@%
  11928.   %@AS@%            TITLE Graphics Routines%@AE@%%@NL@%
  11929. %@NL@%
  11930. %@4@%  This example sets the listing title. A page heading that reflects this%@EH@%
  11931.   title is shown below:%@NL@%
  11932. %@NL@%
  11933.   %@AS@%Microsoft (R) QuickC with QuickAssembler Version 2.01     9/25/89 12:00:00%@AE@%%@NL@%
  11934.   %@AS@%Graphics Routines%@AE@%%@NL@%
  11935.   %@AS@%Page     1-2%@AE@%%@NL@%
  11936. %@NL@%
  11937. %@NL@%
  11938. %@3@%%@CR:SC12.2.2    @%%@AB@%12.2.2  Setting the Listing Subtitle%@AE@%%@EH@%%@NL@%
  11939. %@NL@%
  11940. %@4@%%@CR:IX12.15     @%%@CR:IX12.16     @%%@CR:IX12.17     @%%@CR:IX12.18     @%%@CR:IX12.19     @%%@CR:IX12.20     @%  The %@AB@%SUBTTL%@AE@% directive specifies the subtitle used on each page of assembly%@EH@%
  11941.   listings. In editor-based listing files (the default inside the QC
  11942.   environment), the subtitle is ignored.%@NL@%
  11943. %@NL@%
  11944. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11945. %@NL@%
  11946. %@4@%  %@AB@%SUBTTL%@AE@% %@AI@%text%@AE@%%@EH@%%@NL@%
  11947. %@NL@%
  11948. %@4@%  The %@AI@%text%@AE@% can be any combination of characters up to 60 in length. The%@EH@%
  11949.   subtitle is printed flush left on the third line of the listing pages.%@NL@%
  11950. %@NL@%
  11951. %@4@%  If no %@AB@%SUBTTL%@AE@% directive is used, or if no text is given for a %@AB@%SUBTTL%@AE@%%@EH@%
  11952.   directive, the subtitle line is left blank.%@NL@%
  11953. %@NL@%
  11954. %@4@%  Any number of %@AB@%SUBTTL%@AE@% directives can be given in a program. Each new%@EH@%
  11955.   directive replaces the current subtitle with the new text. %@AB@%SUBTTL%@AE@%
  11956.   directives are often used just before a %@AB@%PAGE%@AE@% + statement, which creates a
  11957.   new section (see Section 12.2.3%@BO:       a39b9@%, "Controlling Page Breaks").%@NL@%
  11958. %@NL@%
  11959. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  11960. %@NL@%
  11961.   %@AS@%            SUBTTL Point Plotting Procedure%@AE@%%@NL@%
  11962.   %@AS@%            PAGE    +%@AE@%%@NL@%
  11963. %@NL@%
  11964. %@4@%  The example above creates a section title and then creates a page break%@EH@%
  11965.   and a new section. A page heading that reflects this title is shown below:%@NL@%
  11966. %@NL@%
  11967.   %@AS@%Microsoft (R) QuickC with QuickAssembler Version 2.01     9/25/89 12:00:00%@AE@%%@NL@%
  11968.   %@AS@%Graphics Routines%@AE@%%@NL@%
  11969.   %@AS@%Page     3-1%@AE@%%@NL@%
  11970.   %@AS@%Point Plotting Procedure%@AE@%%@NL@%
  11971. %@NL@%
  11972. %@NL@%
  11973. %@3@%%@CR:SC12.2.3    @%%@AB@%12.2.3  Controlling Page Breaks%@AE@%%@EH@%%@NL@%
  11974. %@NL@%
  11975. %@4@%%@CR:IX12.21     @%%@CR:IX12.22     @%%@CR:IX12.23     @%%@CR:IX12.24     @%%@CR:IX12.25     @%%@CR:IX12.26     @%  The %@AB@%PAGE%@AE@% directive can be used to designate the line length and width for%@EH@%
  11976.   the program listing, to increment the section and adjust the section
  11977.   number accordingly, or to generate a page break in the listing. In
  11978.   editor-based listing files (the default inside the QC environment),
  11979.   page-break directives are ignored, except for the page width specifier.%@NL@%
  11980. %@NL@%
  11981. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  11982. %@NL@%
  11983. %@4@%  %@AB@%PAGE%@AE@% [[[[%@AI@%length%@AE@%]]%@AB@%,%@AE@%%@AI@%width%@AE@%]]%@EH@%%@NL@%
  11984.   %@AB@%PAGE%@AE@% %@AB@%+%@AE@%%@NL@%
  11985. %@NL@%
  11986. %@4@%  If %@AI@%length%@AE@% and %@AI@%width%@AE@% are specified, the %@AB@%PAGE%@AE@% directive sets the maximum%@EH@%
  11987.   number of lines per page to %@AI@%length%@AE@% and the maximum number of characters
  11988.   per line to %@AI@%width%@AE@%. The length must be in the range of 10-255 lines. The
  11989.   default page length is 50 lines. The width must be in the range of 60-132
  11990.   characters. The default page width is 80 characters. With editor-based
  11991.   listing files, the default page width is 255. To specify the width without
  11992.   changing the default length, use a comma before %@AI@%width%@AE@%.%@NL@%
  11993. %@NL@%
  11994. %@4@%  If no argument is given, %@AB@%PAGE%@AE@% starts a new page in the program listing by%@EH@%
  11995.   copying a form-feed character to the file and generating new title and
  11996.   subtitle lines.%@NL@%
  11997. %@NL@%
  11998. %@4@%%@CR:IX12.27     @%  If a plus sign follows %@AB@%PAGE%@AE@%, a page break occurs, the section number is%@EH@%
  11999.   incremented, and the page number is reset to 1. Program-listing page
  12000.   numbers have the following format:%@NL@%
  12001. %@NL@%
  12002. %@4@%  %@AI@%section%@AE@%-%@AI@%page%@AE@%%@EH@%%@NL@%
  12003. %@NL@%
  12004. %@4@%  The %@AI@%section%@AE@% is the section number within the module, and %@AI@%page%@AE@% is the page%@EH@%
  12005.   number within the section. By default, section and page numbers begin with
  12006.   1-1. The %@AB@%SUBTTL%@AE@% directive and the %@AB@%PAGE%@AE@% directive can be used together to
  12007.   start a new section with a new subtitle. See Section 12.2.2%@BO:       a32b6@%, "Setting the
  12008.   Listing Subtitle," for an example.%@NL@%
  12009. %@NL@%
  12010. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  12011. %@NL@%
  12012.   %@AS@%            PAGE%@AE@%%@NL@%
  12013. %@NL@%
  12014. %@4@%  Example 1 creates a page break.%@EH@%%@NL@%
  12015. %@NL@%
  12016. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  12017. %@NL@%
  12018.   %@AS@%            PAGE 58,90%@AE@%%@NL@%
  12019. %@NL@%
  12020. %@4@%  Example 2 sets the maximum page length to 58 lines and the maximum width%@EH@%
  12021.   to 90 characters.%@NL@%
  12022. %@NL@%
  12023. %@4@%  %@AB@%Example 3%@AE@%%@EH@%%@NL@%
  12024. %@NL@%
  12025.   %@AS@%            PAGE ,132%@AE@%%@NL@%
  12026. %@NL@%
  12027. %@4@%  Example 3 sets the maximum width to 132 characters. The current page%@EH@%
  12028.   length (either the default of 50 or a previously set value) remains
  12029.   unchanged.%@NL@%
  12030. %@NL@%
  12031. %@4@%  %@AB@%Example 4%@AE@%%@EH@%%@NL@%
  12032. %@NL@%
  12033.   %@AS@%            PAGE +%@AE@%%@NL@%
  12034. %@NL@%
  12035. %@4@%  Example 4 creates a page break, increments the current section number, and%@EH@%
  12036.   sets the page number to 1. For example, if the preceding page was 3-6, the
  12037.   new page would be 4-1.%@NL@%
  12038. %@NL@%
  12039. %@NL@%
  12040. %@3@%%@CR:SC12.2.4    @%%@AB@%12.2.4  Naming the Module%@AE@%%@EH@%%@NL@%
  12041. %@NL@%
  12042. %@4@%  The assembler automatically uses the base file name of the source file as%@EH@%
  12043.   the name of the module. This name is used to identify error messages when
  12044.   you run the assembler from the command line.%@NL@%
  12045. %@NL@%
  12046. %@NL@%
  12047. %@2@%%@CR:SC12.3      @%%@AB@%12.3  Controlling the Contents of Listings%@AE@%%@EH@%%@NL@%
  12048. %@NL@%
  12049. %@4@%%@CR:IX12.28     @%  QuickAssembler provides several directives for controlling what text will%@EH@%
  12050.   be shown in listings. The directives that control the contents of listings
  12051.   are shown below:%@NL@%
  12052. %@NL@%
  12053.   %@AB@%Directive%@AE@%           %@AB@%Action%@AE@%%@NL@%
  12054.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  12055.   %@AB@%.LIST%@AE@%               Lists statements in program listing%@NL@%
  12056. %@NL@%
  12057.   %@AB@%.XLIST%@AE@%              Suppresses listing of statements%@NL@%
  12058. %@NL@%
  12059.   %@AB@%.LFCOND%@AE@%             Lists false-conditional blocks in program listing%@NL@%
  12060. %@NL@%
  12061.   %@AB@%.SFCOND%@AE@%             Suppresses false-conditional listing%@NL@%
  12062. %@NL@%
  12063.   %@AB@%.TFCOND%@AE@%             Toggles false-conditional listing%@NL@%
  12064. %@NL@%
  12065.   %@AB@%.LALL%@AE@%               Includes macro expansions in program listing%@NL@%
  12066. %@NL@%
  12067.   %@AB@%.SALL%@AE@%               Suppresses listing of macro expansions%@NL@%
  12068. %@NL@%
  12069.   %@AB@%.XALL%@AE@%               Excludes comments from macro listing%@NL@%
  12070. %@NL@%
  12071. %@NL@%
  12072. %@NL@%
  12073. %@3@%%@CR:SC12.3.1    @%%@AB@%12.3.1  Suppressing and Restoring Listing Output%@AE@%%@EH@%%@NL@%
  12074. %@NL@%
  12075. %@4@%%@CR:IX12.29     @%%@CR:IX12.30     @%%@CR:IX12.31     @%%@CR:IX12.32     @%%@CR:IX12.33     @%%@CR:IX12.34     @%%@CR:IX12.35     @%  The %@AB@%.LIST%@AE@% and %@AB@%.XLIST%@AE@% directives specify which source lines are included in%@EH@%
  12076.   the program listing.%@NL@%
  12077. %@NL@%
  12078. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12079. %@NL@%
  12080. %@4@%  %@AB@%.LIST%@AE@%%@EH@%%@NL@%
  12081.   %@AB@%.XLIST%@AE@%%@NL@%
  12082. %@NL@%
  12083. %@4@%  The %@AB@%.XLIST%@AE@% directive suppresses copying of subsequent source lines to the%@EH@%
  12084.   program listing. The %@AB@%.LIST%@AE@% directive restores copying. The directives are
  12085.   typically used in pairs to prevent a particular section of a source file
  12086.   from being copied to the program listing.%@NL@%
  12087. %@NL@%
  12088. %@4@%  The %@AB@%.XLIST%@AE@% directive overrides other listing directives, such as %@AB@%.SFCOND%@AE@%%@EH@%
  12089.   or %@AB@%.LALL%@AE@%.%@NL@%
  12090. %@NL@%
  12091. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12092. %@NL@%
  12093.   %@AS@%            .XLIST         ; Listing suspended here%@AE@%%@NL@%
  12094.   %@AS@%            .%@AE@%%@NL@%
  12095.   %@AS@%            .%@AE@%%@NL@%
  12096.   %@AS@%            .%@AE@%%@NL@%
  12097.   %@AS@%            .LIST          ; Listing resumes here%@AE@%%@NL@%
  12098.   %@AS@%            .%@AE@%%@NL@%
  12099.   %@AS@%            .%@AE@%%@NL@%
  12100.   %@AS@%            .%@AE@%%@NL@%
  12101. %@NL@%
  12102. %@NL@%
  12103. %@3@%%@CR:SC12.3.2    @%%@AB@%12.3.2  Controlling Listing of Conditional Blocks%@AE@%%@EH@%%@NL@%
  12104. %@NL@%
  12105. %@4@%%@CR:IX12.36     @%%@CR:IX12.37     @%%@CR:IX12.38     @%%@CR:IX12.39     @%%@CR:IX12.40     @%%@CR:IX12.41     @%%@CR:IX12.42     @%%@CR:IX12.43     @%%@CR:IX12.44     @%  The %@AB@%.SFCOND%@AE@%, %@AB@%.LFCOND%@AE@%, and %@AB@%.TFCOND%@AE@% directives control whether%@EH@%
  12106.   false-conditional blocks should be included in assembly listings.%@NL@%
  12107. %@NL@%
  12108. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12109. %@NL@%
  12110. %@4@%  %@AB@%.SFCOND%@AE@%%@EH@%%@NL@%
  12111.   %@AB@%.LFCOND%@AE@%%@NL@%
  12112.   %@AB@%.TFCOND%@AE@%%@NL@%
  12113. %@NL@%
  12114. %@4@%  The %@AB@%.SFCOND%@AE@% directive suppresses the listing of any subsequent conditional%@EH@%
  12115.   blocks whose condition is false. The %@AB@%.LFCOND%@AE@% directive restores the
  12116.   listing of these blocks. Like %@AB@%.LIST%@AE@% and %@AB@%.XLIST%@AE@%, conditional-listing
  12117.   directives can be used to suppress listing of conditional blocks in
  12118.   sections of a program.%@NL@%
  12119. %@NL@%
  12120. %@4@%%@CR:IX12.45     @%%@CR:IX12.46     @%  The %@AB@%.TFCOND%@AE@% directive toggles the current status of listing of conditional%@EH@%
  12121.   blocks. This directive can be used in conjunction with the /Sx option of
  12122.   the assembler. By default, conditional blocks are not listed on start-up.
  12123.   However, they will be listed on start-up if the /Sx option is given. This
  12124.   means that using /Sx reverses the meaning of the first %@AB@%.TFCOND%@AE@% directive
  12125.   in the source file. The /Sx option is discussed in Appendix B%@BO:       f653b@%, Section
  12126.   B.14%@BO:       fbf3d@%, "Listing False Conditionals."%@NL@%
  12127. %@NL@%
  12128. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12129. %@NL@%
  12130.   %@AS@%test1       EQU     0          ; Defined to make all conditionals false%@AE@%%@NL@%
  12131. %@NL@%
  12132.   %@AS@%                               ; /Sx not used      /Sx used%@AE@%%@NL@%
  12133.   %@AS@%            .TFCOND%@AE@%%@NL@%
  12134.   %@AS@%            IFNDEF  test1      ; Listed            Not listed%@AE@%%@NL@%
  12135.   %@AS@%test2       DB      128%@AE@%%@NL@%
  12136.   %@AS@%            ENDIF%@AE@%%@NL@%
  12137.   %@AS@%            .TFCOND%@AE@%%@NL@%
  12138.   %@AS@%            IFNDEF  test1      ; Not listed        Listed%@AE@%%@NL@%
  12139.   %@AS@%test3       DB      128%@AE@%%@NL@%
  12140.   %@AS@%            ENDIF%@AE@%%@NL@%
  12141.   %@AS@%            .SFCOND%@AE@%%@NL@%
  12142.   %@AS@%            IFNDEF  test1      ; Not listed        Not listed%@AE@%%@NL@%
  12143. %@NL@%
  12144.   %@AS@%test4       DB      128%@AE@%%@NL@%
  12145.   %@AS@%            ENDIF%@AE@%%@NL@%
  12146.   %@AS@%            .LFCOND%@AE@%%@NL@%
  12147.   %@AS@%            IFNDEF  test1      ; Listed            Listed%@AE@%%@NL@%
  12148.   %@AS@%test5       DB      128%@AE@%%@NL@%
  12149.   %@AS@%            ENDIF%@AE@%%@NL@%
  12150. %@NL@%
  12151. %@4@%  In the example above, the listing status for the first two conditional%@EH@%
  12152.   blocks would be different, depending on whether the /X option was used.
  12153.   The blocks with %@AB@%.SFCOND%@AE@% and %@AB@%.LFCOND%@AE@% would not be affected by the /X
  12154.   option.%@NL@%
  12155. %@NL@%
  12156. %@NL@%
  12157. %@3@%%@CR:SC12.3.3    @%%@AB@%12.3.3  Controlling Listing of Macros%@AE@%%@EH@%%@NL@%
  12158. %@NL@%
  12159. %@4@%%@CR:IX12.47     @%%@CR:IX12.48     @%%@CR:IX12.49     @%%@CR:IX12.50     @%%@CR:IX12.51     @%%@CR:IX12.52     @%%@CR:IX12.53     @%%@CR:IX12.54     @%%@CR:IX12.55     @%  The %@AB@%.LALL%@AE@%, %@AB@%.XALL%@AE@%, and %@AB@%.SALL%@AE@% directives control the listing of the expanded%@EH@%
  12160.   macro calls. The assembler always lists the full macro definition. The
  12161.   directives only affect expansion of macro calls.%@NL@%
  12162. %@NL@%
  12163. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12164. %@NL@%
  12165. %@4@%  %@AB@%.LALL%@AE@%%@EH@%%@NL@%
  12166.   %@AB@%.XALL%@AE@%%@NL@%
  12167.   %@AB@%.SALL%@AE@%%@NL@%
  12168. %@NL@%
  12169. %@4@%  The %@AB@%.LALL%@AE@% directive causes QuickAssembler to list all the source%@EH@%
  12170.   statements in a macro expansion, including normal comments (preceded by a
  12171.   single semicolon) but not macro comments (preceded by a double semicolon).%@NL@%
  12172. %@NL@%
  12173. %@4@%  The %@AB@%.XALL%@AE@% directive causes QuickAssembler to list only those source%@EH@%
  12174.   statements in a macro expansion that generate code or data. For instance,
  12175.   comments, equates, and segment definitions are ignored.%@NL@%
  12176. %@NL@%
  12177. %@4@%  The %@AB@%.SALL%@AE@% directive causes QuickAssembler to suppress listing of all macro%@EH@%
  12178.   expansions. The listing shows the macro call, but not the source lines
  12179.   generated by the call.%@NL@%
  12180. %@NL@%
  12181. %@4@%  The %@AB@%.XALL%@AE@% directive is in effect when QuickAssembler first begins%@EH@%
  12182.   execution.%@NL@%
  12183. %@NL@%
  12184. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12185. %@NL@%
  12186.   %@AS@%tryout      MACRO   param%@AE@%%@NL@%
  12187.   %@AS@%                               ;; Macro comment%@AE@%%@NL@%
  12188.   %@AS@%                               ; Normal comment%@AE@%%@NL@%
  12189.   %@AS@%it          EQU     3          ; No code or data%@AE@%%@NL@%
  12190.   %@AS@%            ASSUME  es:_DATA   ; No code or data%@AE@%%@NL@%
  12191.   %@AS@%            DW      param      ; Generates data%@AE@%%@NL@%
  12192.   %@AS@%            mov     ax,it      ; Generates code%@AE@%%@NL@%
  12193.   %@AS@%            ENDM%@AE@%%@NL@%
  12194.   %@AS@%            .%@AE@%%@NL@%
  12195.   %@AS@%            .%@AE@%%@NL@%
  12196.   %@AS@%            .%@AE@%%@NL@%
  12197.   %@AS@%            .LALL%@AE@%%@NL@%
  12198.   %@AS@%            tryout  6          ; Call with .LALL%@AE@%%@NL@%
  12199. %@NL@%
  12200.   %@AS@%            .XALL%@AE@%%@NL@%
  12201.   %@AS@%            tryout  6          ; Call with .XALL%@AE@%%@NL@%
  12202. %@NL@%
  12203.   %@AS@%            .SALL%@AE@%%@NL@%
  12204.   %@AS@%            tryout  6          ; Call with .SALL%@AE@%%@NL@%
  12205. %@NL@%
  12206. %@4@%  The macro calls in the example generate the following listing lines:%@EH@%%@NL@%
  12207. %@NL@%
  12208.   %@AS@%                               .LALL%@AE@%%@NL@%
  12209.   %@AS@%                               tryout  6         ; Call with .LALL%@AE@%%@NL@%
  12210.   %@AS@%                     1                           ; Normal comment%@AE@%%@NL@%
  12211.   %@AS@%= 0003               1 it      EQU     3         ; No code or data%@AE@%%@NL@%
  12212.   %@AS@%                     1         ASSUME  es:_TEXT  ; No code or data%@AE@%%@NL@%
  12213.   %@AS@%0015  0006           1         DW      6         ; Generates data%@AE@%%@NL@%
  12214.   %@AS@%0017  B8 0003        1         mov     ax,it     ; Generates code%@AE@%%@NL@%
  12215. %@NL@%
  12216. %@AS@%%@AE@%%@NL@%
  12217.   %@AS@%                               .XALL%@AE@%%@NL@%
  12218.   %@AS@%                               tryout  6         ; Call with .XALL%@AE@%%@NL@%
  12219.   %@AS@%001A  0006           1         DW      6         ; Generates data%@AE@%%@NL@%
  12220.   %@AS@%001C  B8 0003        1         mov     ax,it     ; Generates code%@AE@%%@NL@%
  12221. %@NL@%
  12222. %@AS@%%@AE@%%@NL@%
  12223.   %@AS@%                               .SALL%@AE@%%@NL@%
  12224.   %@AS@%                               tryout  6         ; Call with .SALL%@AE@%%@NL@%
  12225. %@NL@%
  12226. %@4@%  Notice that the macro comment is never listed in macro expansions. Normal%@EH@%
  12227.   comments are listed only with the %@AB@%.LALL%@AE@% directive.%@NL@%
  12228. %@NL@%
  12229. %@NL@%
  12230. %@NL@%
  12231. ────────────────────────────────────────────────────────────────────────────%@NL@%
  12232. %@1@%%@CR:PT3         @%%@AB@%PART 3:  Using Instructions%@AE@%%@EH@%%@NL@%
  12233. %@NL@%
  12234. %@NL@%
  12235. %@4@%  Part 3%@BO:       a6c61@% of the Programmer's Guide (comprising Chapters 13%@BO:       a71ac@%-18) explains%@EH@%
  12236.   how to use instructions in assembly-language source code. Instructions
  12237.   constitute the actual steps of your program and are translated into
  12238.   machine-code statements that the processor executes at run time.%@NL@%
  12239. %@NL@%
  12240. %@4@%  Part 3%@BO:       a6c61@% is organized topically, with related instructions discussed%@EH@%
  12241.   together. Chapter 13%@BO:       a71ac@% explains the instructions for moving data from one
  12242.   location to another. The instructions for performing calculations on
  12243.   numbers and bits are covered in Chapter 14%@BO:       ae658@%.%@NL@%
  12244. %@NL@%
  12245. %@4@%  The 8086-family processors provide four major types of instructions for%@EH@%
  12246.   controlling program flow, as described in Chapter 15%@BO:       bcdd3@%. Chapter 16%@BO:       d1833@%
  12247.   explains the instructions and techniques for processing strings. The
  12248.   8087-family coprocessors and their instructions are explained in Chapter
  12249.   17%@BO:       d965a@%. Finally, Chapter 18%@BO:       eab36@% summarizes the instructions available for
  12250.   processor control.%@NL@%
  12251. %@NL@%
  12252. %@NL@%
  12253. %@NL@%
  12254. %@NL@%
  12255. ────────────────────────────────────────────────────────────────────────────%@NL@%
  12256. %@1@%%@CR:CH13        @%%@AB@%Chapter 13:  Loading, Storing, and Moving Data%@AE@%%@EH@%%@NL@%
  12257. %@NL@%
  12258. %@NL@%
  12259. %@4@%  The 8086-family processors provide several instructions for loading,%@EH@%
  12260.   storing, or moving various kinds of data. Among the types of transferable
  12261.   data are variables, pointers, and flags. Data can be moved to and from
  12262.   registers, memory, ports, and the stack. This chapter explains the
  12263.   instructions for moving data from one location to another.%@NL@%
  12264. %@NL@%
  12265. %@NL@%
  12266. %@2@%%@CR:SC13.1      @%%@AB@%13.1  Transferring Data%@AE@%%@EH@%%@NL@%
  12267. %@NL@%
  12268. %@4@%  Moving data is one of the most common tasks in assembly-language%@EH@%
  12269.   programming. Data can be moved between registers or between memory and
  12270.   registers. Immediate data can be loaded into registers or into memory.%@NL@%
  12271. %@NL@%
  12272. %@4@%  Furthermore, all memory-to-memory operations are illegal. To move data%@EH@%
  12273.   from one memory location to another, you must first move the data to an
  12274.   intermediate register.%@NL@%
  12275. %@NL@%
  12276. %@NL@%
  12277. %@3@%%@CR:SC13.1.1    @%%@AB@%13.1.1  Copying Data%@AE@%%@EH@%%@NL@%
  12278. %@NL@%
  12279. %@4@%%@CR:IX13.1      @%%@CR:IX13.2      @%%@CR:IX13.3      @%  The %@AB@%MOV%@AE@% instruction is the most common method of moving data. This%@EH@%
  12280.   instruction can be thought of as a copy instruction, since it always
  12281.   copies the source operand to the destination operand. Immediately after a
  12282.   %@AB@%MOV%@AE@% instruction, the source and destination operands both contain the same
  12283.   value. The old value in the destination operand is destroyed.%@NL@%
  12284. %@NL@%
  12285. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12286. %@NL@%
  12287. %@4@%  %@AB@%MOV%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@EH@%%@NL@%
  12288. %@NL@%
  12289. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  12290. %@NL@%
  12291.   %@AS@%            mov     ax,7       ; Immediate to register%@AE@%%@NL@%
  12292.   %@AS@%            mov     mem,7      ; Immediate to memory direct%@AE@%%@NL@%
  12293.   %@AS@%            mov     mem[bx],7  ; Immediate to memory indirect%@AE@%%@NL@%
  12294. %@NL@%
  12295.   %@AS@%            mov     mem,ds     ; Segment register to memory%@AE@%%@NL@%
  12296.   %@AS@%            mov     mem,ax     ; Register to memory direct%@AE@%%@NL@%
  12297.   %@AS@%            mov     mem[bx],ax ; Register to memory indirect%@AE@%%@NL@%
  12298. %@NL@%
  12299.   %@AS@%            mov     ax,mem     ; Memory direct to register%@AE@%%@NL@%
  12300.   %@AS@%            mov     ax,mem[bx] ; Memory indirect to register%@AE@%%@NL@%
  12301.   %@AS@%            mov     ds,mem     ; Memory to segment register%@AE@%%@NL@%
  12302. %@NL@%
  12303.   %@AS@%            mov     ax,bx      ; Register to register%@AE@%%@NL@%
  12304.   %@AS@%            mov     ds,ax      ; General register to segment register%@AE@%%@NL@%
  12305.   %@AS@%            mov     ax,ds      ; Segment register to general register%@AE@%%@NL@%
  12306. %@NL@%
  12307. %@4@%  The statements in Example 1 illustrate each type of memory move that can%@EH@%
  12308.   be done with a single instruction. Example 2 illustrates several common
  12309.   types of moves that require two instructions.%@NL@%
  12310. %@NL@%
  12311. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  12312. %@NL@%
  12313.   %@AS@%; Move immediate to segment register%@AE@%%@NL@%
  12314.   %@AS@%            mov     ax,DGROUP  ; Load immediate to general register%@AE@%%@NL@%
  12315.   %@AS@%            mov     ds,ax      ; Store general register to segment register%@AE@%%@NL@%
  12316. %@NL@%
  12317.   %@AS@%; Move memory to memory%@AE@%%@NL@%
  12318.   %@AS@%            mov     ax,mem1    ; Load memory to general register%@AE@%%@NL@%
  12319.   %@AS@%            mov     mem2,ax    ; Store general register to memory%@AE@%%@NL@%
  12320. %@NL@%
  12321.   %@AS@%; Move segment register to segment register%@AE@%%@NL@%
  12322.   %@AS@%            mov     ax,ds      ; Load segment register to general register%@AE@%%@NL@%
  12323.   %@AS@%            mov     es,ax      ; Store general register to segment register%@AE@%%@NL@%
  12324. %@NL@%
  12325. %@NL@%
  12326. %@3@%%@CR:SC13.1.2    @%%@AB@%13.1.2  Exchanging Data%@AE@%%@EH@%%@NL@%
  12327. %@NL@%
  12328. %@4@%%@CR:IX13.4      @%%@CR:IX13.5      @%  The %@AB@%XCHG%@AE@% (Exchange) instruction exchanges the data in the source and%@EH@%
  12329.   destination operands. Data can be exchanged between registers or between
  12330.   registers and memory.%@NL@%
  12331. %@NL@%
  12332. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12333. %@NL@%
  12334. %@4@%  %@AB@%XCHG%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@EH@%%@NL@%
  12335. %@NL@%
  12336. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  12337. %@NL@%
  12338.   %@AS@%            xchg    ax,bx      ; Put AX in BX and BX in AX%@AE@%%@NL@%
  12339.   %@AS@%            xchg    memory,ax  ; Put "memory" in AX and AX in "memory"%@AE@%%@NL@%
  12340. %@NL@%
  12341. %@NL@%
  12342. %@3@%%@CR:SC13.1.3    @%%@AB@%13.1.3  Looking Up Data%@AE@%%@EH@%%@NL@%
  12343. %@NL@%
  12344. %@4@%%@CR:IX13.6      @%%@CR:IX13.7      @%  The %@AB@%XLAT%@AE@% (Translate) instruction is used to load data from a table in%@EH@%
  12345.   memory. The instruction is useful for translating bytes from one coding
  12346.   system to another.%@NL@%
  12347. %@NL@%
  12348. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12349. %@NL@%
  12350. %@4@%  %@AB@%XLAT%@AE@%[[%@AB@%B%@AE@%]] [[[[%@AI@%segment%@AE@%%@AB@%:%@AE@%]]%@AI@%memory%@AE@%]]%@EH@%%@NL@%
  12351. %@NL@%
  12352. %@4@%%@CR:IX13.8      @%%@CR:IX13.9      @%  The BX register must contain the address of the start of the table. By%@EH@%
  12353.   default, the DS register contains the segment of the table, but a segment
  12354.   override can be used to specify a different segment. The operand need not
  12355.   be given except when specifying a segment override.%@NL@%
  12356. %@NL@%
  12357. %@4@%  Before the %@AB@%XLAT%@AE@% instruction is called, the AL register should contain a%@EH@%
  12358.   value that points into the table (the start of the table is considered 0).
  12359.   After the instruction is called, AL will contain the table value pointed
  12360.   to. For example, if AL contains 7, the 8th byte of the table will be
  12361.   placed in the AL register.%@NL@%
  12362. %@NL@%
  12363.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  12364.   %@AB@%NOTE%@AE@%  For compatibility with Intel 80386 mnemonics, QuickAssembler
  12365.   recognizes %@AB@%XLATB %@AE@%as a synonym for %@AB@%XLAT%@AE@%. In the Intel syntax,%@AB@% XLAT %@AE@%requires
  12366.   an operand; %@AB@%XLATB %@AE@%does not allow one. Quick-Assembler never requires an
  12367.   operand, but always allows one.%@NL@%
  12368.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  12369. %@NL@%
  12370. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12371. %@NL@%
  12372.   %@AS@%            ; Table of Hexadecimal digits%@AE@%%@NL@%
  12373.   %@AS@%hex         DB      "0123456789ABCDEF"%@AE@%%@NL@%
  12374.   %@AS@%convert     DB      "You pressed the key with ASCII code "%@AE@%%@NL@%
  12375.   %@AS@%key         DB      ?,?,"h",13,10,"$"%@AE@%%@NL@%
  12376.   %@AS@%            .CODE%@AE@%%@NL@%
  12377.   %@AS@%            .%@AE@%%@NL@%
  12378.   %@AS@%            .%@AE@%%@NL@%
  12379.   %@AS@%            .%@AE@%%@NL@%
  12380.   %@AS@%            mov     ah,8               ; Get a key in AL%@AE@%%@NL@%
  12381.   %@AS@%            int     21h                ; Call DOS%@AE@%%@NL@%
  12382.   %@AS@%            mov     bx,OFFSET hex      ; Load table address%@AE@%%@NL@%
  12383.   %@AS@%            mov     ah,al              ; Save a copy in high byte%@AE@%%@NL@%
  12384.   %@AS@%            and     al,00001111b       ; Mask out top character%@AE@%%@NL@%
  12385.   %@AS@%            xlat                       ; Translate%@AE@%%@NL@%
  12386.   %@AS@%            mov     key[1],al          ; Store the character%@AE@%%@NL@%
  12387.   %@AS@%            mov     cl,12              ; Load shift count%@AE@%%@NL@%
  12388.   %@AS@%            shr     ax,cl              ; Shift high character into position%@AE@%%@NL@%
  12389.   %@AS@%            xlat                       ; Translate%@AE@%%@NL@%
  12390.   %@AS@%            mov     key,al             ; Store the character%@AE@%%@NL@%
  12391.   %@AS@%            mov     dx,OFFSET convert  ; Load message%@AE@%%@NL@%
  12392.   %@AS@%            mov     ah,9               ; Display it%@AE@%%@NL@%
  12393.   %@AS@%            int     21h                ; Call DOS%@AE@%%@NL@%
  12394. %@NL@%
  12395. %@4@%  This example looks up hexadecimal characters in a table in order to%@EH@%
  12396.   convert an eight-bit binary number to a string representing a hexadecimal
  12397.   number.%@NL@%
  12398. %@NL@%
  12399. %@NL@%
  12400. %@3@%%@CR:SC13.1.4    @%%@AB@%13.1.4  Transferring Flags%@AE@%%@EH@%%@NL@%
  12401. %@NL@%
  12402. %@4@%%@CR:IX13.10     @%%@CR:IX13.11     @%%@CR:IX13.12     @%%@CR:IX13.13     @%  The 8086-family processors provide instructions for loading and storing%@EH@%
  12403.   flags in the AH%@AB@% %@AE@%register.%@NL@%
  12404. %@NL@%
  12405. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12406. %@NL@%
  12407. %@4@%  %@AB@%LAHF%@AE@%%@EH@%%@NL@%
  12408.   %@AB@%SAHF%@AE@%%@NL@%
  12409. %@NL@%
  12410. %@4@%%@CR:IX13.14     @%  The status of the lower byte of the flags register can be saved to the AH%@EH@%
  12411.   register with %@AB@%LAHF%@AE@% and then later restored with %@AB@%SAHF%@AE@%. If you need to save
  12412.   and restore the entire flags register, use %@AB@%PUSHF%@AE@% and %@AB@%POPF%@AE@%, as described in
  12413.   Section 13.4.3%@BO:       acdc0@%, "Saving Flags on the Stack."%@NL@%
  12414. %@NL@%
  12415. %@4@%  %@AB@%SAHF%@AE@% is often used with a coprocessor to transfer coprocessor control%@EH@%
  12416.   flags to processor control flags. Section 17.7%@BO:       e64cc@%, "Controlling Program
  12417.   Flow," explains and illustrates this technique.%@NL@%
  12418. %@NL@%
  12419. %@NL@%
  12420. %@2@%%@CR:SC13.2      @%%@AB@%13.2  Converting between Data Sizes%@AE@%%@EH@%%@NL@%
  12421. %@NL@%
  12422. %@4@%%@CR:IX13.15     @%%@CR:IX13.16     @%%@CR:IX13.17     @%%@CR:IX13.18     @%%@CR:IX13.19     @%%@CR:IX13.20     @%  Since moving data between registers of different sizes is illegal, you%@EH@%
  12423.   must take special steps if you need to extend a register value to a larger
  12424.   register or register pair.%@NL@%
  12425. %@NL@%
  12426. %@4@%  The procedure is different for signed and unsigned values. The processor%@EH@%
  12427.   cannot tell the difference between signed and unsigned numbers; the
  12428.   programmer has to understand this difference and program accordingly.%@NL@%
  12429. %@NL@%
  12430. %@NL@%
  12431. %@3@%%@CR:SC13.2.1    @%%@AB@%13.2.1  Extending Signed Values%@AE@%%@EH@%%@NL@%
  12432. %@NL@%
  12433. %@4@%%@CR:IX13.21     @%%@CR:IX13.22     @%%@CR:IX13.23     @%%@CR:IX13.24     @%  The %@AB@%CBW%@AE@% (Convert Byte to Word) and %@AB@%CWD%@AE@% (Convert Word to Doubleword)%@EH@%
  12434.   instructions are provided to sign-extend values. Sign-extending means
  12435.   copying the sign bit of the unextended operand to all bits of the extended
  12436.   operand.%@NL@%
  12437. %@NL@%
  12438. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12439. %@NL@%
  12440. %@4@%  %@AB@%CBW%@AE@%%@EH@%%@NL@%
  12441.   %@AB@%CWD%@AE@%%@NL@%
  12442. %@NL@%
  12443. %@4@%%@CR:IX13.25     @%%@CR:IX13.26     @%  The %@AB@%CBW%@AE@% instruction converts an 8-bit signed value in AL to a 16-bit%@EH@%
  12444.   signed value in AX. The %@AB@%CWD%@AE@% instruction is similar except that it
  12445.   sign-extends a 16-bit value in AX to a 32-bit value in the DX:AX register
  12446.   pair. Both instructions work only on values in the accumulator register.%@NL@%
  12447. %@NL@%
  12448. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12449. %@NL@%
  12450.   %@AS@%            .DATA%@AE@%%@NL@%
  12451.   %@AS@%mem8        DB      -5%@AE@%%@NL@%
  12452.   %@AS@%mem16       DW      -5%@AE@%%@NL@%
  12453.   %@AS@%            .CODE%@AE@%%@NL@%
  12454.   %@AS@%            .%@AE@%%@NL@%
  12455.   %@AS@%            .%@AE@%%@NL@%
  12456.   %@AS@%            .%@AE@%%@NL@%
  12457.   %@AS@%            mov     al,mem8    ; Load 8-bit -5 (FBh)%@AE@%%@NL@%
  12458.   %@AS@%            cbw                ; Convert to 16-bit -5 (FFFBh) in AX%@AE@%%@NL@%
  12459. %@NL@%
  12460.   %@AS@%            mov     ax,mem16   ; Load 16-bit -5 (FFFBh)%@AE@%%@NL@%
  12461.   %@AS@%            cwd                ; Convert to 32-bit -5 (FFFF:FFFBh)%@AE@%%@NL@%
  12462.   %@AS@%                               ;   in DX:AX%@AE@%%@NL@%
  12463. %@NL@%
  12464. %@NL@%
  12465. %@3@%%@CR:SC13.2.2    @%%@AB@%13.2.2  Extending Unsigned Values%@AE@%%@EH@%%@NL@%
  12466. %@NL@%
  12467. %@4@%  To extend unsigned numbers, set the value of the upper register to 0.%@EH@%%@NL@%
  12468. %@NL@%
  12469. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12470. %@NL@%
  12471.   %@AS@%            .DATA%@AE@%%@NL@%
  12472.   %@AS@%mem8        DB      251%@AE@%%@NL@%
  12473.   %@AS@%mem16       DW      251%@AE@%%@NL@%
  12474.   %@AS@%            .CODE%@AE@%%@NL@%
  12475.   %@AS@%            .%@AE@%%@NL@%
  12476.   %@AS@%            .%@AE@%%@NL@%
  12477.   %@AS@%            .%@AE@%%@NL@%
  12478.   %@AS@%            mov     al,mem8    ; Load 251 (FBh) from 8-bit memory%@AE@%%@NL@%
  12479.   %@AS@%            xor     ah,ah      ; Zero upper half (AH)%@AE@%%@NL@%
  12480. %@NL@%
  12481.   %@AS@%            mov     ax,mem16   ; Load 251 (FBh) from 16-bit memory%@AE@%%@NL@%
  12482.   %@AS@%            xor     dx,dx      ; Zero upper half (DX)%@AE@%%@NL@%
  12483. %@NL@%
  12484. %@NL@%
  12485. %@2@%%@CR:SC13.3      @%%@AB@%13.3  Loading Pointers%@AE@%%@EH@%%@NL@%
  12486. %@NL@%
  12487. %@4@%%@CR:IX13.27     @%  The 8086-family processors provide several instructions for loading%@EH@%
  12488.   pointer values into registers or register pairs. They can be used to load
  12489.   either near or far pointers.%@NL@%
  12490. %@NL@%
  12491. %@NL@%
  12492. %@3@%%@CR:SC13.3.1    @%%@AB@%13.3.1  Loading Near Pointers%@AE@%%@EH@%%@NL@%
  12493. %@NL@%
  12494. %@4@%%@CR:IX13.28     @%  The %@AB@%LEA%@AE@% instruction loads a near pointer into a specified register.%@EH@%%@NL@%
  12495. %@NL@%
  12496. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12497. %@NL@%
  12498. %@4@%  %@AB@%LEA%@AE@% %@AI@%register%@AE@%%@AB@%,%@AE@%%@AI@%memory%@AE@%%@EH@%%@NL@%
  12499. %@NL@%
  12500. %@4@%%@CR:IX13.29     @%%@CR:IX13.30     @%  %@AI@%The%@AE@% %@AI@%destination%@AE@% %@AI@%register%@AE@% may be any general-purpose register. The source%@EH@%
  12501.   operand may be any %@AI@%memory%@AE@% operand. The effective address of the source
  12502.   operand is placed in the destination register.%@NL@%
  12503. %@NL@%
  12504. %@4@%  The %@AB@%LEA%@AE@% instruction can be used to calculate the effective address of a%@EH@%
  12505.   direct memory operand, but this is usually not efficient, since the
  12506.   address of a direct memory operand is a constant known at assembly time.
  12507.   For example, the following statements have the same effect, but the second
  12508.   version is faster:%@NL@%
  12509. %@NL@%
  12510.   %@AS@%            lea     dx,string        ; Load effective address - slow%@AE@%%@NL@%
  12511.   %@AS@%            mov     dx,OFFSET string ; Load offset - fast%@AE@%%@NL@%
  12512. %@NL@%
  12513. %@4@%  The %@AB@%LEA%@AE@% instruction is more useful for calculating the address of indirect%@EH@%
  12514.   memory operands:%@NL@%
  12515. %@NL@%
  12516.   %@AS@%            lea     dx,string[si]    ; Load effective address%@AE@%%@NL@%
  12517. %@NL@%
  12518. %@NL@%
  12519. %@3@%%@CR:SC13.3.2    @%%@AB@%13.3.2  Loading Far Pointers%@AE@%%@EH@%%@NL@%
  12520. %@NL@%
  12521. %@4@%%@CR:IX13.31     @%%@CR:IX13.32     @%%@CR:IX13.33     @%%@CR:IX13.34     @%%@CR:IX13.35     @%  The %@AB@%LDS%@AE@% and %@AB@%LES%@AE@% instructions load far pointers.%@EH@%%@NL@%
  12522. %@NL@%
  12523. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12524. %@NL@%
  12525. %@4@%  %@AB@%LDS%@AE@% %@AI@%register%@AE@%%@AB@%,%@AE@%%@AI@%memory%@AE@%%@EH@%%@NL@%
  12526.   %@AB@%LES%@AE@% %@AI@%register%@AE@%%@AB@%,%@AE@%%@AI@%memory%@AE@%%@NL@%
  12527. %@NL@%
  12528. %@4@%  The %@AI@%memory%@AE@% address being pointed to is specified in the source operand,%@EH@%
  12529.   and the %@AI@%register%@AE@% where the offset will be stored is specified in the
  12530.   destination operand.%@NL@%
  12531. %@NL@%
  12532. %@4@%  The address must be stored in memory with the segment in the upper word%@EH@%
  12533.   and the offset in the lower word. The segment register where the segment
  12534.   will be stored is specified in the instruction name. For example, %@AB@%LDS%@AE@% puts
  12535.   the segment in DS, and %@AB@%LES%@AE@% puts the segment in ES. The instructions are
  12536.   often used with string instructions, as explained in Chapter 16%@BO:       d1833@%,
  12537.   "Processing Strings."%@NL@%
  12538. %@NL@%
  12539. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12540. %@NL@%
  12541.   %@AS@%            .DATA%@AE@%%@NL@%
  12542.   %@AS@%string      DB      "This is a string."%@AE@%%@NL@%
  12543.   %@AS@%fpstring    DD      string             ; Far pointer to string%@AE@%%@NL@%
  12544.   %@AS@%pointers    DD      100 DUP (?)%@AE@%%@NL@%
  12545.   %@AS@%            .CODE%@AE@%%@NL@%
  12546.   %@AS@%            .%@AE@%%@NL@%
  12547.   %@AS@%            .%@AE@%%@NL@%
  12548.   %@AS@%            .%@AE@%%@NL@%
  12549.   %@AS@%            les     di,fpstring        ; Put address in ES:DI pair%@AE@%%@NL@%
  12550.   %@AS@%            lds     si,pointers[bx]    ; Put address in DS:SI pair%@AE@%%@NL@%
  12551. %@NL@%
  12552. %@NL@%
  12553. %@2@%%@CR:SC13.4      @%%@AB@%13.4  Transferring Data to and from the Stack%@AE@%%@EH@%%@NL@%
  12554. %@CR:IX13.36     @%%@CR:IX13.37     @%%@CR:IX13.38     @%%@CR:IX13.39     @%%@CR:IX13.40     @%%@CR:IX13.41     @%%@CR:IX13.42     @%%@CR:IX13.43     @%%@CR:IX13.44     @%%@CR:IX13.45     @%%@NL@%
  12555. %@4@%%@CR:IX13.46     @%%@CR:IX13.47     @%%@CR:IX13.48     @%%@CR:IX13.49     @%  A "stack" is an area of memory for storing temporary data. Unlike other%@EH@%
  12556.   segments in which data is stored starting from low memory, data on the
  12557.   stack is stored in reverse order starting from high memory.%@NL@%
  12558. %@NL@%
  12559. %@4@%  Initially, the stack is an uninitialized segment of a finite size. As data%@EH@%
  12560.   is added to the stack at run time, the stack grows downward from high
  12561.   memory to low memory. When items are removed from the stack, it shrinks
  12562.   upward from low memory to high memory.%@NL@%
  12563. %@NL@%
  12564. %@4@%  The stack has several purposes in the 8086-family processors. The %@AB@%CALL%@AE@%,%@EH@%
  12565.   %@AB@%INT%@AE@%, %@AB@%RET%@AE@%, and %@AB@%IRET%@AE@% instructions automatically use the stack to store the
  12566.   calling addresses of procedures and interrupts (see Sections 15.3%@BO:       c3a3e@%, "Using
  12567.   Procedures," and 15.4%@BO:       c3a3e@%, "Using Interrupts"). You can also use the %@AB@%PUSH%@AE@% and
  12568.   %@AB@%POP%@AE@% instructions and their variations to store values on the stack.%@NL@%
  12569. %@NL@%
  12570. %@NL@%
  12571. %@3@%%@CR:SC13.4.1    @%%@AB@%13.4.1  Pushing and Popping%@AE@%%@EH@%%@NL@%
  12572. %@NL@%
  12573. %@4@%%@CR:IX13.50     @%%@CR:IX13.51     @%%@CR:IX13.52     @%%@CR:IX13.53     @%  In 8086-family processors, the SP (Stack Pointer) register always points%@EH@%
  12574.   to the current location in the stack. The %@AB@%PUSH%@AE@% and %@AB@%POP%@AE@% instructions use
  12575.   the SP register to keep track of the current position in the stack.%@NL@%
  12576. %@NL@%
  12577. %@4@%  The values pointed to by the BP and SP registers are relative to the SS%@EH@%
  12578.   (Stack Segment) register. The BP register is often used to point to the
  12579.   base of a frame of reference (a stack frame) within the stack.%@NL@%
  12580. %@NL@%
  12581. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12582. %@NL@%
  12583. %@4@%  %@AB@%PUSH %@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@EH@%%@NL@%
  12584.   %@AB@%POP%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@NL@%
  12585.   %@AB@%PUSH%@AE@% %@AI@%immediate%@AE@%                 (80186-80386 only)%@NL@%
  12586. %@NL@%
  12587. %@4@%  The %@AB@%PUSH%@AE@% instruction is used to store a two-byte operand on the stack. The%@EH@%
  12588.   %@AB@%POP%@AE@% instruction is used to retrieve a previously pushed value. When a
  12589.   value is pushed onto the stack, the SP register is decreased by 2. When a
  12590.   value is popped off the stack, the SP register is increased by 2. Although
  12591.   the stack always contains word values, the SP register points to bytes.
  12592.   Thus, SP changes in multiples of 2.%@NL@%
  12593. %@NL@%
  12594.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  12595.   %@AB@%NOTE%@AE@%  The 8088 and 8086 processors differ from later Intel processors in
  12596.   how they push and pop the SP register. If you give the statement %@AS@%push sp%@AE@%
  12597.   with the 8088 or 8086, the word %@AS@%pushed%@AE@% will be the word in SP after the
  12598.   push operation.%@NL@%
  12599.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  12600. %@NL@%
  12601. %@4@%%@CR:IX13.54     @%  Figure 13.1 illustrates how pushes and pops change the SP register.%@EH@%%@NL@%
  12602. %@NL@%
  12603.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  12604.   │ This figure can be found in Section 13.4.1 of the manual               │%@NL@%
  12605.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  12606. %@NL@%
  12607. %@4@%  The %@AB@%PUSH%@AE@% and %@AB@%POP%@AE@% instructions are almost always used in pairs. Words are%@EH@%
  12608.   popped off the stack in reverse order from the order in which they are
  12609.   pushed onto the stack. You should normally do the same number of pops as
  12610.   pushes to return the stack to its original status. However, it is possible
  12611.   to return the stack to its original status by subtracting the correct
  12612.   number of words from the SP register.%@NL@%
  12613. %@NL@%
  12614. %@4@%  Values on the stack can be accessed by using indirect memory operands with%@EH@%
  12615.   BP as the base register.%@NL@%
  12616. %@NL@%
  12617. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12618. %@NL@%
  12619.   %@AS@%            mov     bp,sp              ; Set stack frame%@AE@%%@NL@%
  12620.   %@AS@%            push    ax                 ; Push first;  SP = BP + 2%@AE@%%@NL@%
  12621.   %@AS@%            push    bx                 ; Push second; SP = BP + 4%@AE@%%@NL@%
  12622.   %@AS@%            push    cx                 ; Push third;  SP = BP + 6%@AE@%%@NL@%
  12623.   %@AS@%            .%@AE@%%@NL@%
  12624.   %@AS@%            .%@AE@%%@NL@%
  12625.   %@AS@%            .%@AE@%%@NL@%
  12626.   %@AS@%            mov     ax,[bp+6]          ; Put third in AX%@AE@%%@NL@%
  12627.   %@AS@%            mov     bx,[bp+4]          ; Put second in BX%@AE@%%@NL@%
  12628.   %@AS@%            mov     cx,[bp+2]          ; Put first in CX%@AE@%%@NL@%
  12629.   %@AS@%            .%@AE@%%@NL@%
  12630.   %@AS@%            .%@AE@%%@NL@%
  12631.   %@AS@%            .%@AE@%%@NL@%
  12632.   %@AS@%            sub     sp,6               ; Restore stack pointer%@AE@%%@NL@%
  12633.   %@AS@%                                       ;   two bytes per push%@AE@%%@NL@%
  12634. %@NL@%
  12635. %@4@%  %@AB@%80186/286/386 Only%@AE@%%@EH@%%@NL@%
  12636. %@NL@%
  12637. %@4@%  Starting with the 80186 processor, the %@AB@%PUSH%@AE@% instruction can be given with%@EH@%
  12638.   an immediate operand. For example, the following statement is legal on the
  12639.   80186, 80286, and 80386 processors:%@NL@%
  12640. %@NL@%
  12641.   %@AS@%            push    7                  ; 3 clocks on 80286%@AE@%%@NL@%
  12642. %@NL@%
  12643. %@4@%  This statement is faster than the following equivalent statements, which%@EH@%
  12644.   are required on the 8088 or 8086:%@NL@%
  12645. %@NL@%
  12646.   %@AS@%            mov     ax,7               ; 2 clocks on 80286%@AE@%%@NL@%
  12647.   %@AS@%            push    ax                 ; 3 clocks on 80286%@AE@%%@NL@%
  12648. %@NL@%
  12649. %@NL@%
  12650. %@3@%%@CR:SC13.4.2    @%%@AB@%13.4.2  Using the Stack%@AE@%%@EH@%%@NL@%
  12651. %@NL@%
  12652. %@4@%%@CR:IX13.55     @%  The stack can be used to store temporary data. For example, in the%@EH@%
  12653.   Microsoft calling convention, the stack is used to pass arguments to a
  12654.   procedure. The arguments are pushed onto the stack before the call. The
  12655.   procedure retrieves and uses them. Then the stack is restored to its
  12656.   original position at the end of the procedure. The stack can also be used
  12657.   to store variables that are local to a procedure. Both of these techniques
  12658.   are discussed in Section 15.3%@BO:       c3a3e@%, "Using Procedures."%@NL@%
  12659. %@NL@%
  12660. %@4@%  Another common use of the stack is to store temporary data when there are%@EH@%
  12661.   no free registers available or when a particular register must hold more
  12662.   than one value. For example, the CX register usually holds the count for
  12663.   loops. If two loops are nested, the outer count is loaded into CX at the
  12664.   start. When the inner loop starts, the outer count is pushed onto the
  12665.   stack and the inner count loaded into CX. When the inner loop finishes,
  12666.   the original count is popped back into CX.%@NL@%
  12667. %@NL@%
  12668. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12669. %@NL@%
  12670.   %@AS@%            mov     cx,10      ; Load outer loop counter%@AE@%%@NL@%
  12671.   %@AS@%outer:      .%@AE@%%@NL@%
  12672.   %@AS@%            .                  ; Start outer loop task%@AE@%%@NL@%
  12673.   %@AS@%            .%@AE@%%@NL@%
  12674.   %@AS@%            push    cx         ; Save outer loop value%@AE@%%@NL@%
  12675.   %@AS@%            mov     cx,20      ; Load inner loop counter%@AE@%%@NL@%
  12676.   %@AS@%inner:      .%@AE@%%@NL@%
  12677.   %@AS@%            .                  ; Do inner loop task%@AE@%%@NL@%
  12678.   %@AS@%            .%@AE@%%@NL@%
  12679.   %@AS@%            loop    inner%@AE@%%@NL@%
  12680.   %@AS@%            pop     cx         ; Restore outer loop counter%@AE@%%@NL@%
  12681.   %@AS@%            .%@AE@%%@NL@%
  12682.   %@AS@%            .                  ; Continue outer loop task%@AE@%%@NL@%
  12683.   %@AS@%            .%@AE@%%@NL@%
  12684.   %@AS@%            loop    outer%@AE@%%@NL@%
  12685. %@NL@%
  12686. %@NL@%
  12687. %@3@%%@CR:SC13.4.3    @%%@AB@%13.4.3  Saving Flags on the Stack%@AE@%%@EH@%%@NL@%
  12688. %@NL@%
  12689. %@4@%%@CR:IX13.56     @%%@CR:IX13.57     @%%@CR:IX13.58     @%%@CR:IX13.59     @%  Flags can be pushed and popped onto the stack using the %@AB@%PUSHF%@AE@% and %@AB@%POPF%@AE@%%@EH@%
  12690.   instructions.%@NL@%
  12691. %@NL@%
  12692. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12693. %@NL@%
  12694. %@4@%  %@AB@%PUSHF%@AE@%%@EH@%%@NL@%
  12695.   %@AB@%POPF%@AE@%%@NL@%
  12696. %@NL@%
  12697. %@4@%  These instructions are sometimes used to save the status of flags before a%@EH@%
  12698.   procedure call and then to restore the same status after the procedure.
  12699.   They can also be used within a procedure to save and restore the flag
  12700.   status of the caller.%@NL@%
  12701. %@NL@%
  12702. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12703. %@NL@%
  12704.   %@AS@%            pushf%@AE@%%@NL@%
  12705.   %@AS@%            call    systask%@AE@%%@NL@%
  12706.   %@AS@%            popf%@AE@%%@NL@%
  12707. %@NL@%
  12708. %@NL@%
  12709. %@3@%%@CR:SC13.4.4    @%%@AB@%13.4.4  Saving All Registers on the Stack%@AE@%%@EH@%%@NL@%
  12710. %@NL@%
  12711. %@4@%  %@AB@%80186/286/386 Only%@AE@%%@EH@%%@NL@%
  12712. %@NL@%
  12713. %@4@%%@CR:IX13.60     @%%@CR:IX13.61     @%%@CR:IX13.62     @%%@CR:IX13.63     @%  Starting with the 80186 processor, the %@AB@%PUSHA%@AE@% and %@AB@%POPA%@AE@% instructions were%@EH@%
  12714.   implemented to push or pop all the general-purpose registers with one
  12715.   instruction.%@NL@%
  12716. %@NL@%
  12717. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12718. %@NL@%
  12719. %@4@%  %@AB@%PUSHA%@AE@%%@EH@%%@NL@%
  12720.   %@AB@%POPA%@AE@%%@NL@%
  12721. %@NL@%
  12722. %@4@%  %@AB@%These instructions can be used to save the status of all registers before%@AE@%%@EH@%
  12723.   %@AB@%a procedure call and then to restore them after the return. Using%@AE@% %@AB@%PUSHA%@AE@%
  12724.   and %@AB@%POPA%@AE@% instructions is significantly faster and takes fewer bytes of
  12725.   code than pushing and popping each register individually.%@NL@%
  12726. %@NL@%
  12727. %@4@%  The registers are pushed in the following order: AX,%@AB@% %@AE@%CX,%@AB@% %@AE@%DX,%@AB@% %@AE@%BX,%@AB@% %@AE@%SP, BP,%@EH@%
  12728.   SI, and DI. The SP word pushed is the value before the first register is
  12729.   pushed. The registers are popped in the opposite order.%@NL@%
  12730. %@NL@%
  12731. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12732. %@NL@%
  12733.   %@AS@%            pusha%@AE@%%@NL@%
  12734.   %@AS@%            call    systask%@AE@%%@NL@%
  12735.   %@AS@%            popa%@AE@%%@NL@%
  12736. %@NL@%
  12737. %@NL@%
  12738. %@2@%%@CR:SC13.5      @%%@AB@%13.5  Transferring Data to and from Ports%@AE@%%@EH@%%@NL@%
  12739. %@NL@%
  12740. %@4@%%@CR:IX13.64     @%%@CR:IX13.65     @%%@CR:IX13.66     @%%@CR:IX13.67     @%%@CR:IX13.68     @%  "Ports" are the gateways between hardware devices and the processor. Each%@EH@%
  12741.   port has a unique number through which it can be accessed. Ports can be
  12742.   used for low-level communication with devices, such as disks, the video
  12743.   display, or the keyboard. The %@AB@%OUT%@AE@% instruction is used to send data to a
  12744.   port; the %@AB@%IN%@AE@% instruction receives data from a port.%@NL@%
  12745. %@NL@%
  12746. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12747. %@NL@%
  12748. %@4@%  %@AB@%IN%@AE@% %@AI@%accumulator%@AE@%%@AB@%,%@AE@%{%@AI@%portnumber%@AE@% | %@AB@%DX%@AE@%}%@EH@%%@NL@%
  12749.   %@AB@%OUT%@AE@% {%@AI@%portnumber%@AE@% | %@AB@%DX%@AE@%}%@AB@%,%@AE@%%@AI@%accumulator%@AE@%%@NL@%
  12750. %@NL@%
  12751. %@4@%  When using the %@AB@%IN%@AE@% and %@AB@%OUT%@AE@% instructions, the number of the port can either%@EH@%
  12752.   be an eight-bit immediate value or the DX register. You must use DX for
  12753.   ports with a number higher than 256. The value to be received from the
  12754.   port must be in the accumulator register (AX for word values or AL for
  12755.   byte values).%@NL@%
  12756. %@NL@%
  12757. %@4@%  When using the %@AB@%IN%@AE@% instruction, the number of the port is given as the%@EH@%
  12758.   source operand and the value to be sent to the port is the destination
  12759.   operand. When using the %@AB@%OUT%@AE@% instruction, the number of the port is given
  12760.   as the destination operand and the value to be sent to the port is the
  12761.   source operand.%@NL@%
  12762. %@NL@%
  12763. %@4@%  In applications programming, most communication with hardware is done with%@EH@%
  12764.   DOS or ROM-BIOS calls. Ports are more often used in systems programming.
  12765.   Since systems programming is beyond the scope of this manual and since
  12766.   ports differ depending on hardware, the %@AB@%IN%@AE@% and %@AB@%OUT%@AE@% instructions are not
  12767.   explained in detail here.%@NL@%
  12768. %@NL@%
  12769. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12770. %@NL@%
  12771.   %@AS@%; Actual values are hardware dependent%@AE@%%@NL@%
  12772.   %@AS@%sound       EQU     61h        ; Port to chip that controls speaker%@AE@%%@NL@%
  12773.   %@AS@%timer       EQU     42h        ; Port to chip that pulses speaker%@AE@%%@NL@%
  12774.   %@AS@%on          EQU     00000011b  ; Bits 0 and 1 turn on speaker%@AE@%%@NL@%
  12775. %@NL@%
  12776.   %@AS@%            in      al,sound   ; Get current port setting%@AE@%%@NL@%
  12777.   %@AS@%            or      al,on      ; Turn on speaker and connect timer%@AE@%%@NL@%
  12778.   %@AS@%            out     sound,al   ; Put value back in port%@AE@%%@NL@%
  12779. %@NL@%
  12780.   %@AS@%            mov     al,50      ; Start at 50%@AE@%%@NL@%
  12781.   %@AS@%sounder:    out     timer,al   ; Send byte to timer port...%@AE@%%@NL@%
  12782. %@NL@%
  12783.   %@AS@%            mov     cx,2000    ; Loop 2000 times to delay%@AE@%%@NL@%
  12784.   %@AS@%hold:       loop    hold%@AE@%%@NL@%
  12785. %@NL@%
  12786.   %@AS@%            dec     al         ; Go down one step%@AE@%%@NL@%
  12787.   %@AS@%            jnz     sounder    ; Repeat for each step%@AE@%%@NL@%
  12788. %@NL@%
  12789.   %@AS@%            in      al,sound   ; Get port value%@AE@%%@NL@%
  12790.   %@AS@%            and     al,NOT on  ; Turn it back off%@AE@%%@NL@%
  12791.   %@AS@%            out     sound,al   ; Put it back in port%@AE@%%@NL@%
  12792. %@NL@%
  12793. %@4@%  This example creates a sound of ascending frequency on the IBM PC and%@EH@%
  12794.   IBM-compatible computers. The technique of making sound or the port values
  12795.   used may be different on other hardware.%@NL@%
  12796. %@NL@%
  12797. %@4@%  %@AB@%80186/286/386 Only%@AE@%%@EH@%%@NL@%
  12798. %@NL@%
  12799. %@4@%  Starting with the 80186 processor, instructions were implemented to send%@EH@%
  12800.   strings of data to and from ports. The instructions are %@AB@%INS%@AE@%,%@AB@% INSB%@AE@%,%@AB@% INSW%@AE@%,
  12801.   %@AB@%OUTS%@AE@%, %@AB@%OUTSB%@AE@%, and %@AB@%OUTSW%@AE@%. The operation of these instructions is much like
  12802.   the operation of other string instructions. They are discussed in Section
  12803.   16.7%@BO:       d8b5c@%, "Transferring Strings to and from Ports."%@NL@%
  12804. %@NL@%
  12805. %@NL@%
  12806. %@NL@%
  12807. ────────────────────────────────────────────────────────────────────────────%@NL@%
  12808. %@1@%%@CR:CH14        @%%@AB@%Chapter 14:  Doing Arithmetic and Bit Manipulations%@AE@%%@EH@%%@NL@%
  12809. %@NL@%
  12810. %@NL@%
  12811. %@4@%  The 8086-family processors provide instructions for doing calculations on%@EH@%
  12812.   byte, word, and doubleword values. Operations include addition,
  12813.   subtraction, multiplication, and division. You can also do calculations at
  12814.   the bit level. This includes the AND, OR, XOR, and NOT logical operations.
  12815.   Bits can also be shifted or rotated to the right or left.%@NL@%
  12816. %@NL@%
  12817. %@4@%  This chapter tells you how to use the instructions that do calculations on%@EH@%
  12818.   numbers and bits.%@NL@%
  12819. %@NL@%
  12820. %@NL@%
  12821. %@2@%%@CR:SC14.1      @%%@AB@%14.1  Adding%@AE@%%@EH@%%@NL@%
  12822. %@NL@%
  12823. %@4@%%@CR:IX14.1      @%%@CR:IX14.2      @%%@CR:IX14.3      @%%@CR:IX14.4      @%%@CR:IX14.5      @%%@CR:IX14.6      @%%@CR:IX14.7      @%%@CR:IX14.8      @%  The %@AB@%ADD%@AE@%, %@AB@%ADC%@AE@%, and %@AB@%INC%@AE@% instructions are used for adding and incrementing%@EH@%
  12824.   values.%@NL@%
  12825. %@NL@%
  12826. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12827. %@NL@%
  12828. %@4@%  %@AB@%ADD %@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@EH@%%@NL@%
  12829.   %@AB@%ADC%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@NL@%
  12830.   %@AB@%INC%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@NL@%
  12831. %@NL@%
  12832. %@4@%  These instructions can work directly on 8-bit or 16-bit values. They can%@EH@%
  12833.   also be used in combination to do calculations on values that are too
  12834.   large to be held in a single register (such as 32-bit values). When used
  12835.   with %@AB@%AAA%@AE@% and %@AB@%DAA%@AE@%, they can be used to do calculations on binary coded
  12836.   decimal (BCD) numbers, as described in Section 14.5%@BO:       b4ede@%.%@NL@%
  12837. %@NL@%
  12838. %@NL@%
  12839. %@3@%%@CR:SC14.1.1    @%%@AB@%14.1.1  Adding Values Directly%@AE@%%@EH@%%@NL@%
  12840. %@NL@%
  12841. %@4@%%@CR:IX14.9      @%%@CR:IX14.10     @%%@CR:IX14.11     @%%@CR:IX14.12     @%  The %@AB@%ADD%@AE@% and %@AB@%INC%@AE@% instructions are used for adding to values in registers or%@EH@%
  12842.   memory.%@NL@%
  12843. %@NL@%
  12844. %@4@%  The %@AB@%INC%@AE@% instruction takes a single %@AI@%register%@AE@% or %@AI@%memory%@AE@% operand. The value%@EH@%
  12845.   of the operand is incremented. The value is treated as an unsigned
  12846.   integer, so the carry flag is not updated for signed carries.%@NL@%
  12847. %@NL@%
  12848. %@4@%  The %@AB@%ADD%@AE@% instruction adds values given in source and destination operands.%@EH@%
  12849.   The destination can be either a %@AI@%register%@AE@% or a %@AI@%memory%@AE@% operand. Its contents
  12850.   will be destroyed by the operation. The source operand can be an
  12851.   %@AI@%immediate%@AE@%, %@AI@%memory%@AE@%, or %@AI@%register%@AE@% operand. Since memory-to-memory operations
  12852.   are never allowed, the source and destination operands can never both be
  12853.   memory operands.%@NL@%
  12854. %@NL@%
  12855. %@4@%  The result of the operation is stored in the source operand. The operands%@EH@%
  12856.   can be either 8-bit or 16-bit, but both must be the same size.%@NL@%
  12857. %@NL@%
  12858. %@4@%%@CR:IX14.13     @%%@CR:IX14.14     @%  An addition operation can be interpreted as addition of either signed%@EH@%
  12859.   numbers or unsigned numbers. It is the programmer's responsibility to
  12860.   decide how the addition should be interpreted and to take appropriate
  12861.   action if the sum is too large for the destination operand. When an
  12862.   addition overflows the possible range for signed numbers, the overflow
  12863.   flag is set. When an addition overflows the range for unsigned numbers,
  12864.   the carry flag is set.%@NL@%
  12865. %@NL@%
  12866. %@4@%  There are two ways to take action on an overflow: you can use the %@AB@%JO%@AE@% or%@EH@%
  12867.   %@AB@%JNO%@AE@% instruction to direct program flow to or around instructions that
  12868.   handle the overflow (see Section 15.1.2.3%@BO:       c19f4@%, "Testing Bits and Jumping").
  12869.   You can also use the %@AB@%INTO%@AE@% instruction to trigger the overflow interrupt
  12870.   (interrupt 4) if the overflow flag is set. This requires writing an
  12871.   interrupt handler for interrupt 4, since the DOS overflow routine simply
  12872.   returns without taking any action. Section 15.4.2%@BO:       cf793@%, "Defining and
  12873.   Redefining Interrupt Routines," gives a sample of an overflow interrupt
  12874.   handler.%@NL@%
  12875. %@NL@%
  12876. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12877. %@NL@%
  12878.   %@AS@%            .DATA%@AE@%%@NL@%
  12879.   %@AS@%mem8        DB      39%@AE@%%@NL@%
  12880.   %@AS@%            .CODE%@AE@%%@NL@%
  12881.   %@AS@%            .%@AE@%%@NL@%
  12882.   %@AS@%            .%@AE@%%@NL@%
  12883.   %@AS@%            .                  ;                  unsigned  signed%@AE@%%@NL@%
  12884.   %@AS@%            mov     al,26      ; Start with register   26     26%@AE@%%@NL@%
  12885.   %@AS@%            inc     al         ; Increment              1      1%@AE@%%@NL@%
  12886.   %@AS@%            add     al,76      ; Add immediate       + 76     76%@AE@%%@NL@%
  12887.   %@AS@%                               ;                     ----   ----%@AE@%%@NL@%
  12888.   %@AS@%                               ;                      103    103%@AE@%%@NL@%
  12889.   %@AS@%            add     al,mem8    ; Add memory          + 39     39%@AE@%%@NL@%
  12890.   %@AS@%                               ;                     ----   ----%@AE@%%@NL@%
  12891.   %@AS@%            mov     ah,al      ; Copy to AH           142   -114+overflow%@AE@%%@NL@%
  12892.   %@AS@%            add     al,ah      ; Add register         142%@AE@%%@NL@%
  12893.   %@AS@%                               ;                     ----%@AE@%%@NL@%
  12894.   %@AS@%                               ;                       28+carry%@AE@%%@NL@%
  12895. %@NL@%
  12896. %@4@%%@CR:IX14.15     @%%@CR:IX14.16     @%%@CR:IX14.17     @%%@CR:IX14.18     @%%@CR:IX14.19     @%  This example shows 8-bit addition. When the sum exceeds 127, the overflow%@EH@%
  12897.   flag is set. A %@AB@%JO%@AE@% (Jump On Overflow) or %@AB@%INTO%@AE@% (Interrupt On Overflow)
  12898.   instruction at this point could transfer control to error-recovery
  12899.   statements. When the sum exceeds 255, the carry flag is set. A %@AB@%JC%@AE@% (Jump On
  12900.   Carry) instruction at this point could transfer control to error-recovery
  12901.   statements.%@NL@%
  12902. %@NL@%
  12903. %@NL@%
  12904. %@3@%%@CR:SC14.1.2    @%%@AB@%14.1.2  Adding Values in Multiple Registers%@AE@%%@EH@%%@NL@%
  12905. %@NL@%
  12906. %@4@%%@CR:IX14.20     @%%@CR:IX14.21     @%%@CR:IX14.22     @%%@CR:IX14.23     @%  The %@AB@%ADC%@AE@% (Add with Carry) instruction makes it possible to add numbers%@EH@%
  12907.   larger than can be held in a single register.%@NL@%
  12908. %@NL@%
  12909. %@4@%%@CR:IX14.24     @%  The %@AB@%ADC%@AE@% instruction adds two numbers in the same fashion as the %@AB@%ADD%@AE@%%@EH@%
  12910.   instruction, except that the value of the carry flag is included in the
  12911.   addition. If a previous calculation has set the carry flag, then 1 will be
  12912.   added to the sum of the numbers. If the carry flag is not set, the %@AB@%ADC%@AE@%
  12913.   instruction has the same effect as the %@AB@%ADD%@AE@% instruction.%@NL@%
  12914. %@NL@%
  12915. %@4@%%@CR:IX14.25     @%%@CR:IX14.26     @%  When adding numbers in multiple registers, the carry flag should be%@EH@%
  12916.   ignored for the least-significant portion, but taken into account for the
  12917.   most-significant portion. This can be done by using the %@AB@%ADD%@AE@% instruction
  12918.   for the least-significant portion and the %@AB@%ADC%@AE@% instruction for
  12919.   most-significant portion.%@NL@%
  12920. %@NL@%
  12921. %@4@%  You can add and carry repeatedly inside a loop for calculations that%@EH@%
  12922.   require more than two registers. Use the %@AB@%ADC%@AE@% instruction in each
  12923.   iteration, but turn off the carry flag with the %@AB@%CLC%@AE@% (Clear Carry Flag)
  12924.   instruction before entering the loop so that it will not be used for the
  12925.   first iteration. You could also do the first add outside the loop.%@NL@%
  12926. %@NL@%
  12927. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12928. %@NL@%
  12929.   %@AS@%            .DATA%@AE@%%@NL@%
  12930.   %@AS@%mem32       DD      316423%@AE@%%@NL@%
  12931.   %@AS@%            .CODE%@AE@%%@NL@%
  12932.   %@AS@%            .%@AE@%%@NL@%
  12933.   %@AS@%            .%@AE@%%@NL@%
  12934.   %@AS@%            .%@AE@%%@NL@%
  12935.   %@AS@%            mov     ax,43981             ; Load immediate     43981%@AE@%%@NL@%
  12936.   %@AS@%            sub     dx,dx                ;   into DX:AX%@AE@%%@NL@%
  12937.   %@AS@%            add     ax,WORD PTR mem32[0] ; Add to both     + 316423%@AE@%%@NL@%
  12938.   %@AS@%            adc     dx,WORD PTR mem32[2] ;   memory words    ------%@AE@%%@NL@%
  12939.   %@AS@%                                         ; Result in DX:AX   360404%@AE@%%@NL@%
  12940. %@NL@%
  12941. %@NL@%
  12942. %@2@%%@CR:SC14.2      @%%@AB@%14.2  Subtracting%@AE@%%@EH@%%@NL@%
  12943. %@CR:IX14.27     @%%@CR:IX14.28     @%%@CR:IX14.29     @%%@CR:IX14.30     @%%@CR:IX14.31     @%%@CR:IX14.32     @%%@CR:IX14.33     @%%@NL@%
  12944. %@4@%%@CR:IX14.34     @%%@CR:IX14.35     @%%@CR:IX14.36     @%  The %@AB@%SUB%@AE@%, %@AB@%SBB%@AE@%, %@AB@%DEC%@AE@%, and %@AB@%NEG%@AE@% instructions are used for subtracting and%@EH@%
  12945.   decrementing values.%@NL@%
  12946. %@NL@%
  12947. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  12948. %@NL@%
  12949. %@4@%  %@AB@%SUB%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@EH@%%@NL@%
  12950.   %@AB@%SBB%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@NL@%
  12951.   %@AB@%DEC%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@NL@%
  12952.   %@AB@%NEG %@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@NL@%
  12953. %@NL@%
  12954. %@4@%  These instructions can work directly on 8-bit or 16-bit values. They can%@EH@%
  12955.   also be used in combination to do calculations on values too large to be
  12956.   held in a single register. When used with %@AB@%AAA%@AE@% and %@AB@%DAA%@AE@%, they can be used to
  12957.   do calculations on BCD numbers, as described in Section 14.5%@BO:       b4ede@%,
  12958.   "Calculating with Binary Coded Decimals."%@NL@%
  12959. %@NL@%
  12960. %@NL@%
  12961. %@3@%%@CR:SC14.2.1    @%%@AB@%14.2.1  Subtracting Values Directly%@AE@%%@EH@%%@NL@%
  12962. %@NL@%
  12963. %@4@%%@CR:IX14.37     @%%@CR:IX14.38     @%%@CR:IX14.39     @%%@CR:IX14.40     @%%@CR:IX14.41     @%  The %@AB@%SUB%@AE@% and %@AB@%DEC%@AE@% instructions are used for subtracting from values in%@EH@%
  12964.   registers or memory. A related instruction, %@AB@%NEG%@AE@% (Negate), reverses the
  12965.   sign of a number.%@NL@%
  12966. %@NL@%
  12967. %@4@%  The %@AB@%DEC%@AE@% instruction takes a single %@AI@%register%@AE@% or %@AI@%memory%@AE@% operand. The value%@EH@%
  12968.   of the operand is decremented. The value is treated as an unsigned
  12969.   integer, so the carry flag is not updated for signed borrows.%@NL@%
  12970. %@NL@%
  12971. %@4@%%@CR:IX14.42     @%%@CR:IX14.43     @%  The %@AB@%NEG%@AE@% instruction takes a single %@AI@%register%@AE@% or %@AI@%memory%@AE@% operand. The sign of%@EH@%
  12972.   the value of the operand is reversed. The %@AB@%NEG%@AE@% instruction should only be
  12973.   used on signed numbers.%@NL@%
  12974. %@NL@%
  12975. %@4@%  The %@AB@%SUB%@AE@% instruction subtracts the values given in the source operand from%@EH@%
  12976.   the value of the destination operand. The destination can be either a
  12977.   %@AI@%register%@AE@% or a %@AI@%memory%@AE@% operand. It will be destroyed by the operation. The
  12978.   source operand can be an %@AI@%immediate%@AE@%, %@AI@%memory%@AE@%, or %@AI@%register%@AE@% operand. It will
  12979.   not be destroyed by the operation. Since memory-to-memory operations are
  12980.   never allowed, the source and destination operands cannot both be memory
  12981.   operands.%@NL@%
  12982. %@NL@%
  12983. %@4@%  The result of the operation is stored in the source operand. The operands%@EH@%
  12984.   can be either 8-bit or 16-bit, but both must be the same size.%@NL@%
  12985. %@NL@%
  12986. %@4@%%@CR:IX14.44     @%%@CR:IX14.45     @%  A subtraction operation can be interpreted as subtraction of either signed%@EH@%
  12987.   numbers or unsigned numbers. It is the programmer's responsibility to
  12988.   decide how the subtraction should be interpreted and to take appropriate
  12989.   action if the result is too small for the destination operand. When a
  12990.   subtraction overflows the possible range for signed numbers, the carry
  12991.   flag is set. When a subtraction underflows the range for unsigned numbers
  12992.   (becomes negative), the sign flag is set.%@NL@%
  12993. %@NL@%
  12994. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  12995. %@NL@%
  12996.   %@AS@%            .DATA%@AE@%%@NL@%
  12997.   %@AS@%mem8        DB      122%@AE@%%@NL@%
  12998.   %@AS@%            .CODE%@AE@%%@NL@%
  12999.   %@AS@%            .%@AE@%%@NL@%
  13000.   %@AS@%            .%@AE@%%@NL@%
  13001.   %@AS@%            .                  ;                   signed  unsigned%@AE@%%@NL@%
  13002.   %@AS@%            mov     al,95      ; Load register         95     95%@AE@%%@NL@%
  13003.   %@AS@%            dec     al         ; Decrement          -   1  -   1%@AE@%%@NL@%
  13004.   %@AS@%            sub     al,23      ; Subtract immediate -  23  -  23%@AE@%%@NL@%
  13005.   %@AS@%                               ;                     ----   ----%@AE@%%@NL@%
  13006.   %@AS@%                               ;                       71     71%@AE@%%@NL@%
  13007.   %@AS@%            sub     al,mem8    ; Subtract memory    - 122  - 122%@AE@%%@NL@%
  13008.   %@AS@%                               ;                     ----   ----%@AE@%%@NL@%
  13009.   %@AS@%                               ;                    -  51    205+sign%@AE@%%@NL@%
  13010. %@NL@%
  13011.   %@AS@%            mov     ah,119     ; Load register        119%@AE@%%@NL@%
  13012.   %@AS@%            sub     al,ah      ;   and subtract     -  51%@AE@%%@NL@%
  13013.   %@AS@%                               ;                     ----%@AE@%%@NL@%
  13014.   %@AS@%                               ;                       86+overflow%@AE@%%@NL@%
  13015. %@NL@%
  13016. %@4@%%@CR:IX14.46     @%%@CR:IX14.47     @%%@CR:IX14.48     @%%@CR:IX14.49     @%  This example shows 8-bit subtraction. When the result goes below 0, the%@EH@%
  13017.   sign flag is set. A %@AB@%JS%@AE@% (Jump On Sign) instruction at this point could
  13018.   transfer control to error-recovery statements. When the result goes below
  13019.   -128, the carry flag is set. A %@AB@%JC%@AE@% (Jump On Carry) instruction at this
  13020.   point could transfer control to error-recovery statements.%@NL@%
  13021. %@NL@%
  13022. %@NL@%
  13023. %@3@%%@CR:SC14.2.2    @%%@AB@%14.2.2  Subtracting with Values in Multiple Registers%@AE@%%@EH@%%@NL@%
  13024. %@NL@%
  13025. %@4@%%@CR:IX14.50     @%%@CR:IX14.51     @%%@CR:IX14.52     @%  The %@AB@%SBB%@AE@% (Subtract with Borrow) instruction makes it possible to subtract%@EH@%
  13026.   from numbers larger than can be held in a single register.%@NL@%
  13027. %@NL@%
  13028. %@4@%  The %@AB@%SBB%@AE@% instruction subtracts two numbers in the same fashion as the %@AB@%SUB%@AE@%%@EH@%
  13029.   instruction except that the value of the carry flag is included in the
  13030.   subtraction. If a previous calculation has set the carry flag, then 1 will
  13031.   be subtracted from the result. If the carry flag is not set, the %@AB@%SBB%@AE@%
  13032.   instruction has the same effect as the %@AB@%SUB%@AE@% instruction.%@NL@%
  13033. %@NL@%
  13034. %@4@%%@CR:IX14.53     @%%@CR:IX14.54     @%%@CR:IX14.55     @%  When subtracting numbers in multiple registers, the carry flag should be%@EH@%
  13035.   ignored for the least-significant portion, but taken into account for the
  13036.   most-significant portion. This can be done by using the %@AB@%SUB%@AE@% instruction
  13037.   for the least-significant portion and the %@AB@%SBB%@AE@% instruction for
  13038.   most-significant portions.%@NL@%
  13039. %@NL@%
  13040. %@4@%  You can subtract and borrow repeatedly inside a loop for calculations that%@EH@%
  13041.   require more than two registers. Use the %@AB@%SBB%@AE@% instruction in each
  13042.   iteration, but turn off the carry flag with the %@AB@%CLC%@AE@% (Clear Carry Flag)
  13043.   instruction before entering the loop so that it will not be used for the
  13044.   first iteration. You could also do the first subtraction outside the loop.%@NL@%
  13045. %@NL@%
  13046. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  13047. %@NL@%
  13048.   %@AS@%            .DATA%@AE@%%@NL@%
  13049.   %@AS@% mem32a     DD      316423%@AE@%%@NL@%
  13050.   %@AS@% mem32b     DD      156739%@AE@%%@NL@%
  13051.   %@AS@%            .CODE%@AE@%%@NL@%
  13052.   %@AS@%            .%@AE@%%@NL@%
  13053.   %@AS@%            .%@AE@%%@NL@%
  13054.   %@AS@%            .%@AE@%%@NL@%
  13055.   %@AS@%            mov     ax,WORD PTR mem32a[0]  ; Load mem32        316423%@AE@%%@NL@%
  13056.   %@AS@%            mov     dx,WORD PTR mem32a[2]  ;   into DX:AX%@AE@%%@NL@%
  13057.   %@AS@%            sub     ax,WORD PTR mem32b[0]  ; Subtract low      156739%@AE@%%@NL@%
  13058.   %@AS@%            sbb     dx,WORD PTR mem32b[2]  ;   then high       ------%@AE@%%@NL@%
  13059.   %@AS@%                                           ; Result in DX:AX   159684%@AE@%%@NL@%
  13060. %@NL@%
  13061. %@NL@%
  13062. %@2@%%@CR:SC14.3      @%%@AB@%14.3  Multiplying%@AE@%%@EH@%%@NL@%
  13063. %@NL@%
  13064. %@4@%%@CR:IX14.56     @%%@CR:IX14.57     @%%@CR:IX14.58     @%%@CR:IX14.59     @%%@CR:IX14.60     @%  The %@AB@%MUL%@AE@% and %@AB@%IMUL%@AE@% instructions are used to multiply numbers. The %@AB@%MUL%@AE@%%@EH@%
  13065.   instruction should be used for unsigned numbers; the %@AB@%IMUL%@AE@% instruction
  13066.   should be used for signed numbers. This is the only difference between the
  13067.   two.%@NL@%
  13068. %@NL@%
  13069. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13070. %@NL@%
  13071. %@4@%  %@AB@%MUL%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@EH@%%@NL@%
  13072.   %@AB@%IMUL%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@NL@%
  13073. %@NL@%
  13074. %@4@%  The multiply instructions require that one of the factors be in the%@EH@%
  13075.   accumulator register (AL for 8-bit numbers or AX for 16-bit numbers). This
  13076.   register is implied; it should not be specified in the source code. Its
  13077.   contents will be destroyed by the operation.%@NL@%
  13078. %@NL@%
  13079. %@4@%  The other factor to be multiplied must be specified in a single %@AI@%register%@AE@%%@EH@%
  13080.   or %@AI@%memory%@AE@% operand. The operand will not be destroyed by the operation,
  13081.   unless it is DX, AX, AH, or AL. A number may be squared by loading it into
  13082.   the accumulator, and then executing a multiplication instruction with the
  13083.   accumulator as the operand.%@NL@%
  13084. %@NL@%
  13085. %@4@%  Note that multiplying two 8-bit numbers will produce a 16-bit number. If%@EH@%
  13086.   the product is a 16-bit number, it will be placed in AX and the overflow
  13087.   and carry flags will be set.%@NL@%
  13088. %@NL@%
  13089. %@4@%  Similarly, multiplying two 16-bit numbers will produce a 32-bit number in%@EH@%
  13090.   the DX:AX%@AB@% %@AE@%register pair. If the product is a 32-bit number, the
  13091.   least-significant bits will be in AX, the most-significant bits will be in
  13092.   DX, and the overflow and carry flags will be set.%@NL@%
  13093. %@NL@%
  13094.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13095.   %@AB@%NOTE%@AE@%  Multiplication is one of the slower operations on 8086-family
  13096.   processors (especially the 8086 and 8088). Multiplying by certain common
  13097.   constants is often faster when done by shifting bits (see Section 14.7.1%@BO:       bb18b@%,
  13098.   "Multiplying and Dividing by Constants").%@NL@%
  13099.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13100. %@NL@%
  13101. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  13102. %@NL@%
  13103.   %@AS@%            .DATA%@AE@%%@NL@%
  13104.   %@AS@%mem16       DW      -30000%@AE@%%@NL@%
  13105.   %@AS@%            .CODE%@AE@%%@NL@%
  13106.   %@AS@%            .%@AE@%%@NL@%
  13107.   %@AS@%            .%@AE@%%@NL@%
  13108.   %@AS@%            .                  ; 8-bit unsigned multiply%@AE@%%@NL@%
  13109.   %@AS@%            mov     al,23      ; Load AL                   23%@AE@%%@NL@%
  13110.   %@AS@%            mov     bl,24      ; Load BL                 * 24%@AE@%%@NL@%
  13111.   %@AS@%            mul     bl         ; Multiply BL            -----%@AE@%%@NL@%
  13112.   %@AS@%                               ; 16-bit signed multiply%@AE@%%@NL@%
  13113.   %@AS@%            mov     ax,50      ; Load AX                   50%@AE@%%@NL@%
  13114.   %@AS@%                               ;                       -30000%@AE@%%@NL@%
  13115.   %@AS@%            imul    mem16      ; Multiply memory        -----%@AE@%%@NL@%
  13116.   %@AS@%                               ; Product in DX:AX    -1500000%@AE@%%@NL@%
  13117.   %@AS@%                               ;   overflow and carry set%@AE@%%@NL@%
  13118. %@NL@%
  13119. %@4@%  %@AB@%80186/286/386 Only%@AE@%%@EH@%%@NL@%
  13120. %@NL@%
  13121. %@4@%%@CR:IX14.61     @%%@CR:IX14.62     @%  Starting with the 80186 processor, the %@AB@%IMUL%@AE@% instruction has two additional%@EH@%
  13122.   syntaxes that allow for 16-bit multiples that produce a 16-bit product.%@NL@%
  13123. %@NL@%
  13124. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13125. %@NL@%
  13126. %@4@%  %@AB@%IMUL%@AE@% %@AI@%register16%@AE@%%@AB@%,%@AE@% %@AI@%immediate%@AE@%%@EH@%%@NL@%
  13127.   %@AB@%IMUL%@AE@% %@AI@%register16%@AE@%%@AB@%,%@AE@% %@AI@%memory16%@AE@%%@AB@%,%@AE@% %@AI@%immediate%@AE@%%@NL@%
  13128. %@NL@%
  13129. %@4@%  You can specify a 16-bit %@AI@%immediate%@AE@% value as the source instruction and a%@EH@%
  13130.   word %@AI@%register%@AE@% as the destination operand. The product appears in the
  13131.   destination operand. The 16-bit result will be placed in the destination
  13132.   operand. If the product is too large to fit in 16 bits, the carry and
  13133.   overflow flags will be set. In this context, %@AB@%IMUL%@AE@% can be used for either
  13134.   signed or unsigned multiplication, since the 16-bit product is the same.%@NL@%
  13135. %@NL@%
  13136. %@4@%  You can also specify three operands for %@AB@%IMUL%@AE@%. The first operand must be a%@EH@%
  13137.   16-bit %@AI@%register%@AE@% operand, the second a 16-bit %@AI@%memory%@AE@% operand, and the third
  13138.   a 16-bit %@AI@%immediate%@AE@% operand. The second and third operands are multiplied
  13139.   and the product stored in the first operand.%@NL@%
  13140. %@NL@%
  13141. %@4@%  With both of these syntaxes, the carry and overflow flags will be set if%@EH@%
  13142.   the product is too large to fit in 16 bits. The %@AB@%IMUL%@AE@% instruction with
  13143.   multiple operands can be used for either signed or unsigned
  13144.   multiplication, since the 16-bit product is the same in either case. If
  13145.   you need to get a 32-bit result, you must use the single-operand version
  13146.   of %@AB@%MUL%@AE@% or %@AB@%IMUL%@AE@%.%@NL@%
  13147. %@NL@%
  13148. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  13149. %@NL@%
  13150.   %@AS@%            imul    dx,456     ; Multiply DX times 456%@AE@%%@NL@%
  13151.   %@AS@%            imul    ax,[bx],6  ; Multiply the value pointed to by BX%@AE@%%@NL@%
  13152.   %@AS@%                               ;   times 6 and put the result in AX%@AE@%%@NL@%
  13153. %@NL@%
  13154. %@NL@%
  13155. %@2@%%@CR:SC14.4      @%%@AB@%14.4  Dividing%@AE@%%@EH@%%@NL@%
  13156. %@NL@%
  13157. %@4@%%@CR:IX14.63     @%%@CR:IX14.64     @%%@CR:IX14.65     @%%@CR:IX14.66     @%%@CR:IX14.67     @%  The %@AB@%DIV%@AE@% and %@AB@%IDIV%@AE@% instructions are used to divide integers. Both a quotient%@EH@%
  13158.   and a remainder are returned. The %@AB@%DIV%@AE@% instruction should be used for
  13159.   unsigned integers; the %@AB@%IDIV%@AE@% instruction should be used for signed
  13160.   integers. This is the only difference between the two.%@NL@%
  13161. %@NL@%
  13162. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13163. %@NL@%
  13164. %@4@%  %@AB@%DIV%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@EH@%%@NL@%
  13165.   %@AB@%IDIV%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@NL@%
  13166. %@NL@%
  13167. %@4@%  To divide a 16-bit number by an 8-bit number, put the number to be divided%@EH@%
  13168.   (the dividend) in the AX register. The contents of this register will be
  13169.   destroyed by the operation. Specify the dividing number (the divisor) in
  13170.   any 8-bit memory or register operand (except AL or AH). This operand will
  13171.   not be changed by the operation. After the multiplication, the result
  13172.   (quotient) will be in AL and the remainder will be in AH.%@NL@%
  13173. %@NL@%
  13174. %@4@%  To divide a 32-bit number by a 16-bit number, put the dividend in the%@EH@%
  13175.   DX:AX register pair. The least-significant bits go in AX. The contents of
  13176.   these registers will be destroyed by the operation. Specify the divisor in
  13177.   any 16-bit memory or register operand (except AX or DX). This operand will
  13178.   not be changed by the operation. After the division, the quotient will be
  13179.   in AX and the remainder will be in DX.%@NL@%
  13180. %@NL@%
  13181. %@4@%  To divide a 16-bit number by a 16-bit number, you must first sign-extend%@EH@%
  13182.   or zero-extend (see Section 13.2%@BO:       a94e2@%, "Converting between Data Sizes") the
  13183.   dividend to 32 bits; then divide as described above. You cannot divide a
  13184.   32-bit number by another 32-bit number.%@NL@%
  13185. %@NL@%
  13186. %@4@%  If division by zero is specified, or if the quotient exceeds the capacity%@EH@%
  13187.   of its register (AL or AX), the processor automatically generates an
  13188.   interrupt 0. By default, the program terminates and returns to DOS. This
  13189.   problem can be handled in two ways: check the divisor before division and
  13190.   go to an error routine if you can determine it to be invalid, or write
  13191.   your own interrupt routine to replace the processor's interrupt 0 routine.
  13192.   See Section 15.4%@BO:       cdbc9@% for more information on interrupts.%@NL@%
  13193. %@NL@%
  13194.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13195.   %@AB@%NOTE%@AE@%  Division is one of the slower operations on 8086-family processors
  13196.   (especially the 8086 and 8088). Dividing by common constants that are
  13197.   powers of two is often faster when done by shifting bits, as described in
  13198.   Section 14.7.1%@BO:       bb18b@%, "Multiplying and Dividing by Constants."%@NL@%
  13199.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13200. %@NL@%
  13201. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  13202. %@NL@%
  13203.   %@AS@%            .DATA%@AE@%%@NL@%
  13204. %@NL@%
  13205.   %@AS@%mem16       DW      -2000%@AE@%%@NL@%
  13206.   %@AS@%mem32       DD      500000%@AE@%%@NL@%
  13207.   %@AS@%            .CODE%@AE@%%@NL@%
  13208.   %@AS@%            .%@AE@%%@NL@%
  13209.   %@AS@%            .                            ; Divide 16-bit unsigned by 8-bit%@AE@%%@NL@%
  13210.   %@AS@%            .%@AE@%%@NL@%
  13211.   %@AS@%            mov     ax,700               ; Load dividend          700%@AE@%%@NL@%
  13212.   %@AS@%            mov     bl,36                ; Load divisor      DIV   36%@AE@%%@NL@%
  13213.   %@AS@%            div     bl                   ; Divide BL            -----%@AE@%%@NL@%
  13214.   %@AS@%                                         ; Quotient in AL          19%@AE@%%@NL@%
  13215.   %@AS@%                                         ; Remainder in AH            16%@AE@%%@NL@%
  13216. %@NL@%
  13217.   %@AS@%                                         ; Divide 32-bit signed by 16-bit%@AE@%%@NL@%
  13218. %@AS@%%@AE@%%@NL@%
  13219.   %@AS@%            mov     ax,WORD PTR mem32[0] ; Load into DX:AX%@AE@%%@NL@%
  13220.   %@AS@%            mov     dx,WORD PTR mem32[2] ;                     500000%@AE@%%@NL@%
  13221.   %@AS@%            idiv    mem16                ;                  DIV -2000%@AE@%%@NL@%
  13222.   %@AS@%                                         ; Divide memory       ------%@AE@%%@NL@%
  13223.   %@AS@%                                         ; Quotient in AX        -250%@AE@%%@NL@%
  13224.   %@AS@%                                         ; Remainder in DX             0%@AE@%%@NL@%
  13225. %@NL@%
  13226.   %@AS@%                                         ; Divide 16-bit signed by 16-bit%@AE@%%@NL@%
  13227. %@AS@%%@AE@%%@NL@%
  13228.   %@AS@%            mov     ax,WORD PTR mem16    ; Load into AX         -2000%@AE@%%@NL@%
  13229.   %@AS@%            cwd                          ; Extend to DX:AX%@AE@%%@NL@%
  13230.   %@AS@%            mov     bx,-421              ;                   DIV -421%@AE@%%@NL@%
  13231.   %@AS@%            idiv    bx                   ; Divide by BX         -----%@AE@%%@NL@%
  13232.   %@AS@%                                         ; Quotient in AX           4%@AE@%%@NL@%
  13233.   %@AS@%                                         ; Remainder in DX            -316%@AE@%%@NL@%
  13234. %@NL@%
  13235. %@NL@%
  13236. %@2@%%@CR:SC14.5      @%%@AB@%14.5  Calculating with Binary Coded Decimals%@AE@%%@EH@%%@NL@%
  13237. %@NL@%
  13238. %@4@%%@CR:IX14.68     @%  The 8086-family processors provide several instructions for adjusting BCD%@EH@%
  13239.   numbers. The BCD format is seldom used for applications programming in
  13240.   assembly language. Programmers who wish to use BCD numbers usually use a
  13241.   high-level language. However, BCD instructions are used to develop
  13242.   compilers, function libraries, and other systems tools.%@NL@%
  13243. %@NL@%
  13244. %@4@%  Since systems programming is beyond the scope of this manual, this section%@EH@%
  13245.   provides only a brief overview of calculations on the two kinds of BCD
  13246.   numbers, unpacked and packed.%@NL@%
  13247. %@NL@%
  13248.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13249. %@CR:IX14.69     @%%@CR:IX14.70     @%%@CR:IX14.71     @%%@CR:IX14.72     @%  %@AB@%NOTE%@AE@%  Intel mnemonics use the term "ASCII" to refer to unpacked BCD
  13250.   numbers and "decimal" to refer to packed BCD numbers. Thus %@AB@%AAA%@AE@% (ASCII
  13251.   Adjust After Addition) adjusts unpacked numbers, while %@AB@%DAA (%@AE@%Decimal Adjust
  13252.   After Addition) adjusts packed numbers.%@NL@%
  13253.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13254. %@NL@%
  13255. %@NL@%
  13256. %@3@%%@CR:SC14.5.1    @%%@AB@%14.5.1  Unpacked BCD Numbers%@AE@%%@EH@%%@NL@%
  13257. %@NL@%
  13258. %@4@%  Unpacked BCD numbers are made up of bytes containing a single decimal%@EH@%
  13259.   digit in the lower four bits of each byte. The 8086-family processors
  13260.   provide instructions for adjusting unpacked values with the four
  13261.   arithmetic operations──addition, subtraction, multiplication, and
  13262.   division.%@NL@%
  13263. %@NL@%
  13264. %@4@%  To do arithmetic on unpacked BCD numbers, you must do the eight-bit%@EH@%
  13265.   arithmetic calculations on each digit separately. The result should always
  13266.   be in the AL register. After each operation, use the corresponding BCD
  13267.   instruction to adjust the result. The ASCII-adjust instructions do not
  13268.   take an operand. They always work on the value in the AL register.%@NL@%
  13269. %@NL@%
  13270. %@4@%  When a calculation using two one-digit values produces a two-digit result,%@EH@%
  13271.   the ASCII-adjust instructions put the first digit in AL and the second in
  13272.   AH. If the digit in AL needs to carry to or borrow from the digit in AH,
  13273.   the carry and auxiliary carry flags are set.%@NL@%
  13274. %@NL@%
  13275. %@4@%  The four ASCII-adjust instructions are described below:%@EH@%%@NL@%
  13276. %@NL@%
  13277.   %@AB@%Instruction%@AE@%         %@AB@%Description%@AE@%%@NL@%
  13278.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13279. %@CR:IX14.73     @%%@CR:IX14.74     @%  %@AB@%AAA%@AE@%                 Adjusts after an addition operation. For example, to
  13280.                       add 9 and 3, use the following lines:%@NL@%
  13281. %@NL@%
  13282. %@NL@%
  13283.   %@AS@%mov     ax,9    ; Load 9%@AE@%%@NL@%
  13284.   %@AS@%mov     bx,3    ;   and 3 as unpacked BCD%@AE@%%@NL@%
  13285.   %@AS@%add     al,bl   ; Add 09h and 03h to get 0Ch%@AE@%%@NL@%
  13286.   %@AS@%aaa             ; Adjust 0Ch in AL to 02h,%@AE@%%@NL@%
  13287.   %@AS@%                ;   increment AH to 01h, set carry%@AE@%%@NL@%
  13288.   %@AS@%                ; Result 12 unpacked BCD in AX%@AE@%%@NL@%
  13289. %@NL@%
  13290. %@4@%%@CR:IX14.75     @%%@CR:IX14.76     @%  %@AB@%AAS%@AE@%                 Adjusts after a subtraction operation. For example, to%@EH@%
  13291.                       subtract 4 from 13, use the following lines:%@NL@%
  13292. %@NL@%
  13293. %@NL@%
  13294.   %@AS@%mov     ax,103h ; Load 13%@AE@%%@NL@%
  13295.   %@AS@%mov     bx,4    ;   and 4 as unpacked BCD%@AE@%%@NL@%
  13296.   %@AS@%sub     al,bl   ; Subtract 4 from 3 to get FFh (-1)%@AE@%%@NL@%
  13297.   %@AS@%aas             ; Adjust 0FFh in AL to 9,%@AE@%%@NL@%
  13298.   %@AS@%                ;   decrement AH to 0, set carry%@AE@%%@NL@%
  13299.   %@AS@%                ; Result 9 unpacked BCD in AX%@AE@%%@NL@%
  13300. %@NL@%
  13301. %@4@%%@CR:IX14.77     @%%@CR:IX14.78     @%  %@AB@%AAM%@AE@%                 Adjusts after a multiplication operation. Always use%@EH@%
  13302.                       %@AB@%MUL%@AE@%, not %@AB@%IMUL%@AE@%. For example, to multiply 9 times 3, use
  13303.                       the following lines:%@NL@%
  13304. %@NL@%
  13305. %@NL@%
  13306.   %@AS@%mov     ax,903h ; Load 9 and 3 as unpacked BCD%@AE@%%@NL@%
  13307.   %@AS@%mul     ah      ; Multiply 9 and 3 to get 1Bh%@AE@%%@NL@%
  13308.   %@AS@%aam             ; Adjust 1Bh in AL%@AE@%%@NL@%
  13309.   %@AS@%                ;   to get 27 unpacked BCD in AX%@AE@%%@NL@%
  13310. %@NL@%
  13311. %@4@%%@CR:IX14.79     @%%@CR:IX14.80     @%  %@AB@%AAD%@AE@%                 Adjusts before a division operation. Unlike other BCD%@EH@%
  13312.                       instructions, this one converts a BCD value to a
  13313.                       binary value before the operation. After the
  13314.                       operation, the quotient must still be adjusted by
  13315.                       using %@AB@%AAM%@AE@%. For example, to divide 25 by 2, use the
  13316.                       following lines:%@NL@%
  13317. %@NL@%
  13318. %@NL@%
  13319.   %@AS@%mov     ax,205h ; Load 25%@AE@%%@NL@%
  13320.   %@AS@%mov     bl,2    ;   and 2 as unpacked BCD%@AE@%%@NL@%
  13321.   %@AS@%aad             ; Adjust 0205h in AX%@AE@%%@NL@%
  13322.   %@AS@%                ;   to get 19h in AX%@AE@%%@NL@%
  13323.   %@AS@%div     bl      ; Divide by 2 to get%@AE@%%@NL@%
  13324.   %@AS@%                ;   quotient 0Ch in AL%@AE@%%@NL@%
  13325.   %@AS@%                ;   remainder 1 in AH%@AE@%%@NL@%
  13326.   %@AS@%aam             ; Adjust 0Ch in AL%@AE@%%@NL@%
  13327.   %@AS@%                ;   to 12 unpacked BCD in AX%@AE@%%@NL@%
  13328.   %@AS@%                ;   (remainder destroyed)%@AE@%%@NL@%
  13329. %@NL@%
  13330. %@4@%  Notice that the remainder is lost. If you need the remainder, save it in%@EH@%
  13331.   another register before adjusting the quotient. Then move it back to AL
  13332.   and adjust if necessary.%@NL@%
  13333. %@NL@%
  13334. %@NL@%
  13335. %@4@%%@CR:IX14.81     @%%@CR:IX14.82     @%  Multidigit BCD numbers are usually processed in loops. Each digit is%@EH@%
  13336.   processed and adjusted in turn. In addition to their use for processing
  13337.   unpacked BCD numbers, the ASCII-adjust instructions can be used in
  13338.   routines that convert between different number bases.%@NL@%
  13339. %@NL@%
  13340. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  13341. %@NL@%
  13342.   %@AS@%            mov     al,79      ; Load 79 (04Fh)%@AE@%%@NL@%
  13343.   %@AS@%            aam                ; Adjust to BCD (0709h)%@AE@%%@NL@%
  13344.   %@AS@%            add     ah,'0'     ; Adjust to ASCII characters%@AE@%%@NL@%
  13345.   %@AS@%            add     al,'0'     ;   (3739h)%@AE@%%@NL@%
  13346.   %@AS@%            mov     dx,ax      ; Copy to DX%@AE@%%@NL@%
  13347.   %@AS@%            xchg    dl,dh      ; Trade for most significant digit%@AE@%%@NL@%
  13348.   %@AS@%            mov     ah,2       ; DOS display character function%@AE@%%@NL@%
  13349.   %@AS@%            int     21h        ; Call DOS%@AE@%%@NL@%
  13350.   %@AS@%            mov     dl,dh      ; Load least significant digit%@AE@%%@NL@%
  13351.   %@AS@%            int     21h        ; Call DOS%@AE@%%@NL@%
  13352. %@NL@%
  13353. %@4@%  The example converts an eight-bit binary number to hexadecimal and%@EH@%
  13354.   displays it on the screen. The routine could be enhanced to handle large
  13355.   numbers.%@NL@%
  13356. %@NL@%
  13357. %@NL@%
  13358. %@3@%%@CR:SC14.5.2    @%%@AB@%14.5.2  Packed BCD Numbers%@AE@%%@EH@%%@NL@%
  13359. %@NL@%
  13360. %@4@%%@CR:IX14.83     @%  Packed BCD numbers are made up of bytes containing two decimal digits: one%@EH@%
  13361.   in the upper four bits and one in the lower four bits. The 8086-family
  13362.   processors provide instructions for adjusting packed BCD numbers after
  13363.   addition and subtraction. You must write your own routines to adjust for
  13364.   multiplication and division.%@NL@%
  13365. %@NL@%
  13366. %@4@%  To do arithmetic on packed BCD numbers, you must do the eight-bit%@EH@%
  13367.   arithmetic calculations on each byte separately. The result should always
  13368.   be in the AL register. After each operation, use the corresponding BCD
  13369.   instruction to adjust the result. The decimal-adjust instructions do not
  13370.   take an operand. They always work on the value in the AL register.%@NL@%
  13371. %@NL@%
  13372. %@4@%  Unlike the ASCII-adjust instructions, the decimal-adjust instructions%@EH@%
  13373.   never affect AH. The auxiliary carry flag is set if the digit in the lower
  13374.   four bits carries to or borrows from the digit in the upper four bits. The
  13375.   carry flag is set if the digit in the upper four bits needs to carry to or
  13376.   borrow from another byte.%@NL@%
  13377. %@NL@%
  13378. %@4@%  The decimal-adjust instructions are described below:%@EH@%%@NL@%
  13379. %@NL@%
  13380.   %@AB@%Instruction%@AE@%         %@AB@%Description%@AE@%%@NL@%
  13381.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13382. %@CR:IX14.84     @%%@CR:IX14.85     @%  %@AB@%DAA%@AE@%                 Adjusts after an addition operation. For example, to
  13383.                       add 88 and 33, use the following lines:%@NL@%
  13384. %@NL@%
  13385. %@NL@%
  13386.   %@AS@%            mov     ax,8833h ; Load 88 and 33 as packed BCD%@AE@%%@NL@%
  13387.   %@AS@%            add     al,ah    ; Add 88 and 33 to get 0BBh%@AE@%%@NL@%
  13388.   %@AS@%            daa              ; Adjust 0BBh to 121 packed BCD:%@AE@%%@NL@%
  13389.   %@AS@%                             ;   1 in carry and 21 in AL%@AE@%%@NL@%
  13390. %@NL@%
  13391. %@4@%%@CR:IX14.86     @%%@CR:IX14.87     @%%@CR:IX14.88     @%  %@AB@%DAS%@AE@%                 Adjusts after a subtraction operation. For example, to%@EH@%
  13392.                       subtract 38 from 83, put 83 in AL and 38 in AH in
  13393.                       packed BCD format. Then use the following lines to
  13394.                       subtract them:%@NL@%
  13395. %@NL@%
  13396. %@NL@%
  13397.   %@AS@%            mov     ax,3883h ; Load 83 and 38 as packed BCD%@AE@%%@NL@%
  13398.   %@AS@%            sub     al,ah    ; Subtract 38 from 83 to get 04Bh%@AE@%%@NL@%
  13399.   %@AS@%            das              ; Adjust 04Bh to 45 packed BCD:%@AE@%%@NL@%
  13400.   %@AS@%                             ;   0 in carry and 45 in AL%@AE@%%@NL@%
  13401. %@NL@%
  13402. %@NL@%
  13403. %@4@%  Multidigit BCD numbers are usually processed in loops. Each byte is%@EH@%
  13404.   processed and adjusted in turn.%@NL@%
  13405. %@NL@%
  13406. %@NL@%
  13407. %@2@%%@CR:SC14.6      @%%@AB@%14.6  Doing Logical Bit Manipulations%@AE@%%@EH@%%@NL@%
  13408. %@NL@%
  13409. %@4@%%@CR:IX14.89     @%  The logical instructions do Boolean operations on individual bits. The%@EH@%
  13410.   AND, OR, XOR, and NOT operations are supported by the 8086-family
  13411.   instructions.%@NL@%
  13412. %@NL@%
  13413. %@4@%  AND compares two bits and sets the result if both bits are set. OR%@EH@%
  13414.   compares two bits and sets the result if either bit is set. XOR compares
  13415.   two bits and sets the result if the bits are different. NOT reverses a
  13416.   single bit. Table 14.1 shows a truth table for the logical operations.%@NL@%
  13417. %@NL@%
  13418.   %@AB@%Table 14.1 Values Returned by Logical Operations%@AE@%%@NL@%
  13419. %@NL@%
  13420.   %@AB@%X%@AE@%           %@AB@%Y%@AE@%           %@AB@%NOT X%@AE@%       %@AB@%X AND Y%@AE@%     %@AB@%X OR Y%@AE@%      %@AB@%X XOR Y%@AE@%%@NL@%
  13421.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13422.   1           1           0           1           1           0%@NL@%
  13423. %@NL@%
  13424.   1           0           0           0           1           1%@NL@%
  13425. %@NL@%
  13426.   0           1           1           0           1           1%@NL@%
  13427. %@NL@%
  13428.   0           0           1           0           0           0%@NL@%
  13429. %@NL@%
  13430.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13431. %@NL@%
  13432. %@NL@%
  13433. %@4@%%@CR:IX14.90     @%%@CR:IX14.91     @%%@CR:IX14.92     @%%@CR:IX14.93     @%%@CR:IX14.94     @%%@CR:IX14.95     @%%@CR:IX14.96     @%%@CR:IX14.97     @%  The syntax of the %@AB@%AND%@AE@%, %@AB@%OR%@AE@%, and %@AB@%XOR%@AE@% instructions is the same. The only%@EH@%
  13434.   difference is the operation performed. For all instructions, the target
  13435.   value to be changed by the operation is placed in one operand. A mask
  13436.   showing the positions of bits to be changed is placed in the other
  13437.   operand. The format of the mask differs for each logical instruction. The
  13438.   destination operand can be register or memory. The source operand can be
  13439.   register, memory, or immediate. However, the source and destination
  13440.   operands cannot both be memory operands.%@NL@%
  13441. %@NL@%
  13442. %@4@%  Either of the values can be in either operand. However, the source operand%@EH@%
  13443.   will be unchanged by the operation, while the destination operand will be
  13444.   destroyed by it. Your choice of operands depends on whether you want to
  13445.   save a copy of the mask or of the target value.%@NL@%
  13446. %@NL@%
  13447.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13448. %@CR:IX14.98     @%%@CR:IX14.99     @%%@CR:IX14.100    @%  %@AB@%NOTE%@AE@%  The logical instructions should not be confused with the logical
  13449.   operators. They specify completely different behavior. The instructions
  13450.   control run-time bit calculations. The operators control assembly-time bit
  13451.   calculations. Although the instructions and operators have the same name,
  13452.   the assembler can distinguish them from context.%@NL@%
  13453.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13454. %@NL@%
  13455. %@NL@%
  13456. %@3@%%@CR:SC14.6.1    @%%@AB@%14.6.1  AND Operations%@AE@%%@EH@%%@NL@%
  13457. %@NL@%
  13458. %@4@%%@CR:IX14.101    @%%@CR:IX14.102    @%  The %@AB@%AND%@AE@% instruction does an AND operation on the bits of the source and%@EH@%
  13459.   destination operands. The original destination operand is replaced by the
  13460.   resulting bits.%@NL@%
  13461. %@NL@%
  13462. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13463. %@NL@%
  13464. %@4@%  %@AB@%AND%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@EH@%%@NL@%
  13465. %@NL@%
  13466. %@4@%  The %@AB@%AND%@AE@% instruction can be used to clear the value of specific bits%@EH@%
  13467.   regardless of their current settings. To do this, put the target value in
  13468.   one operand and a mask of the bits you want to clear in the other. The
  13469.   bits of the mask should be 0 for any bit positions you want to clear and 1
  13470.   for any bit positions you want to remain unchanged.%@NL@%
  13471. %@NL@%
  13472. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  13473. %@NL@%
  13474.   %@AS@%            mov     ax,035h      ; Load value                  00110101%@AE@%%@NL@%
  13475.   %@AS@%            and     ax,0FBh      ; Mask off bit 2          AND 11111011%@AE@%%@NL@%
  13476.   %@AS@%                                 ;                             --------%@AE@%%@NL@%
  13477.   %@AS@%                                 ; Value is now 31h            00110001%@AE@%%@NL@%
  13478.   %@AS@%            and     ax,0F8h      ; Mask off bits 2,1,0     AND 11111000%@AE@%%@NL@%
  13479.   %@AS@%                                 ;                             --------%@AE@%%@NL@%
  13480.   %@AS@%                                 ; Value is now 30h            00110000%@AE@%%@NL@%
  13481. %@NL@%
  13482. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  13483. %@NL@%
  13484.   %@AS@%            mov     ah,7         ; Get character without echo%@AE@%%@NL@%
  13485.   %@AS@%            int     21h%@AE@%%@NL@%
  13486.   %@AS@%            and     al,11011111b ; Convert to uppercase by clearing bit 5%@AE@%%@NL@%
  13487.   %@AS@%            cmp     al,'Y'       ; Is it Y?%@AE@%%@NL@%
  13488.   %@AS@%            je      yes          ; If so, do Yes stuff%@AE@%%@NL@%
  13489.   %@AS@%            .                    ;   else do No stuff%@AE@%%@NL@%
  13490.   %@AS@%            .%@AE@%%@NL@%
  13491.   %@AS@%yes:        .%@AE@%%@NL@%
  13492. %@NL@%
  13493. %@4@%  Example 2 illustrates how to use the %@AB@%AND%@AE@% instruction to convert a%@EH@%
  13494.   character to uppercase. If the character is already uppercase, the %@AB@%AND%@AE@%
  13495.   instruction has no effect, since bit 5 is always clear in uppercase
  13496.   letters. If the character is lowercase, clearing bit 5 converts it to
  13497.   uppercase.%@NL@%
  13498. %@NL@%
  13499. %@NL@%
  13500. %@3@%%@CR:SC14.6.2    @%%@AB@%14.6.2  OR Operations%@AE@%%@EH@%%@NL@%
  13501. %@NL@%
  13502. %@4@%%@CR:IX14.103    @%%@CR:IX14.104    @%  The %@AB@%OR%@AE@% instruction does an OR operation on the bits of the source and%@EH@%
  13503.   destination operands. The original destination operand is replaced by the
  13504.   resulting bits.%@NL@%
  13505. %@NL@%
  13506. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13507. %@NL@%
  13508. %@4@%  %@AB@%OR%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@EH@%%@NL@%
  13509. %@NL@%
  13510. %@4@%  The %@AB@%OR%@AE@% instruction can be used to set the value of specific bits%@EH@%
  13511.   regardless of their current settings. To do this, put the target value in
  13512.   one operand and a mask of the bits you want to clear in the other. The
  13513.   bits of the mask should be 1 for any bit positions you want to set and 0
  13514.   for any bit positions you want to remain unchanged.%@NL@%
  13515. %@NL@%
  13516. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  13517. %@NL@%
  13518.   %@AS@%            mov     ax,035h    ; Move value to register      00110101%@AE@%%@NL@%
  13519.   %@AS@%            or      ax,08h     ; Mask on bit 3            OR 00001000%@AE@%%@NL@%
  13520.   %@AS@%                               ;                             --------%@AE@%%@NL@%
  13521.   %@AS@%                               ; Value is now 3Dh            00111101%@AE@%%@NL@%
  13522.   %@AS@%            or      ax,07h     ; Mask on bits 2,1,0       OR 00000111%@AE@%%@NL@%
  13523.   %@AS@%                               ;                             --------%@AE@%%@NL@%
  13524.   %@AS@%                               ; Value is now 3Fh            00111111%@AE@%%@NL@%
  13525. %@NL@%
  13526. %@4@%%@CR:IX14.105    @%  Another common use for %@AB@%OR%@AE@% is to compare an operand to 0:%@EH@%%@NL@%
  13527. %@NL@%
  13528.   %@AS@%            or      bx,bx      ; Compare to 0%@AE@%%@NL@%
  13529.   %@AS@%                               ;   2 bytes, 2 clocks on 8088%@AE@%%@NL@%
  13530.   %@AS@%            jg      positive   ; BX is positive%@AE@%%@NL@%
  13531.   %@AS@%            jl      negative   ; BX is negative%@AE@%%@NL@%
  13532.   %@AS@%                               ; BX is zero%@AE@%%@NL@%
  13533. %@NL@%
  13534. %@4@%  The first statement has the same effect as the following statement, but is%@EH@%
  13535.   faster and smaller:%@NL@%
  13536. %@NL@%
  13537.   %@AS@%            cmp     bx,0       ; 3 bytes, 3 clocks on 8088%@AE@%%@NL@%
  13538. %@NL@%
  13539. %@NL@%
  13540. %@3@%%@CR:SC14.6.3    @%%@AB@%14.6.3  XOR Operations%@AE@%%@EH@%%@NL@%
  13541. %@NL@%
  13542. %@4@%%@CR:IX14.106    @%%@CR:IX14.107    @%  The %@AB@%XOR%@AE@% (Exclusive OR) instruction does an XOR operation on the bits of%@EH@%
  13543.   the source and destination operands. The original destination operand is
  13544.   replaced by the resulting bits.%@NL@%
  13545. %@NL@%
  13546. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13547. %@NL@%
  13548. %@4@%  %@AB@%XOR%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@EH@%%@NL@%
  13549. %@NL@%
  13550. %@4@%  The %@AB@%XOR%@AE@% instruction can be used to toggle the value of specific bits%@EH@%
  13551.   (reverse them from their current settings). To do this, put the target
  13552.   value in one operand and a mask of the bits you want to toggle in the
  13553.   other. The bits of the mask should be 1 for any bit positions you want to
  13554.   toggle and 0 for any bit positions you want to remain unchanged.%@NL@%
  13555. %@NL@%
  13556. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  13557. %@NL@%
  13558.   %@AS@%            mov     ax,035h    ; Move value to register      00110101%@AE@%%@NL@%
  13559.   %@AS@%            xor     ax,08h     ; Mask on bit 3           XOR 00001000%@AE@%%@NL@%
  13560.   %@AS@%                               ;                             --------%@AE@%%@NL@%
  13561.   %@AS@%                               ; Value is now 3Dh            00111101%@AE@%%@NL@%
  13562.   %@AS@%            xor     ax,07h     ; Mask on bits 2,1,0      XOR 00000111%@AE@%%@NL@%
  13563.   %@AS@%                               ;                             --------%@AE@%%@NL@%
  13564.   %@AS@%                               ; Value is now 3Ah            00111010%@AE@%%@NL@%
  13565. %@NL@%
  13566. %@4@%%@CR:IX14.108    @%  Another common use for the %@AB@%XOR%@AE@% instruction is to set a register to 0:%@EH@%%@NL@%
  13567. %@NL@%
  13568.   %@AS@%            xor     cx,cx      ; 2 bytes, 3 clocks on 8088%@AE@%%@NL@%
  13569. %@NL@%
  13570. %@4@%  This sets the CX register to 0. When the %@AB@%XOR%@AE@% instruction takes identical%@EH@%
  13571.   operands, each bit cancels itself, producing 0. The statement%@NL@%
  13572. %@NL@%
  13573.   %@AS@%            mov     cx,0       ; 3 bytes, 4 clocks on 8088%@AE@%%@NL@%
  13574. %@NL@%
  13575. %@4@%  is the obvious way of doing this, but it is larger and slower. The%@EH@%
  13576.   statement%@NL@%
  13577. %@NL@%
  13578.   %@AS@%            sub     cx,cx      ; 2 bytes, 3 clocks on 8088%@AE@%%@NL@%
  13579. %@NL@%
  13580. %@4@%  is also smaller than the %@AB@%MOV%@AE@% version. The only advantage of using %@AB@%MOV%@AE@% is%@EH@%
  13581.   that it does not affect any flags.%@NL@%
  13582. %@NL@%
  13583. %@NL@%
  13584. %@3@%%@CR:SC14.6.4    @%%@AB@%14.6.4  NOT Operations%@AE@%%@EH@%%@NL@%
  13585. %@NL@%
  13586. %@4@%%@CR:IX14.109    @%%@CR:IX14.110    @%  The %@AB@%NOT%@AE@% instruction does a NOT operation on the bits of a single operand.%@EH@%
  13587.   It is used to toggle the value of all bits at once.%@NL@%
  13588. %@NL@%
  13589. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13590. %@NL@%
  13591. %@4@%  NOT {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@EH@%%@NL@%
  13592. %@NL@%
  13593. %@4@%%@CR:IX14.111    @%  The %@AB@%NOT%@AE@% instruction is often used to reverse the sense of a bit mask from%@EH@%
  13594.   masking certain bits on to masking them off. Use the %@AB@%NOT%@AE@% instruction if
  13595.   the value of the mask is not known until run time; use the%@AB@% NOT%@AE@% operator
  13596.   (see Section 9.2.1.5%@BO:       7c89d@%, "Bitwise Logical Operators") if the mask is a
  13597.   constant.%@NL@%
  13598. %@NL@%
  13599. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  13600. %@NL@%
  13601.   %@AS@%            .DATA%@AE@%%@NL@%
  13602.   %@AS@%masker      DB      00010000b  ; Value may change at run time%@AE@%%@NL@%
  13603.   %@AS@%            .CODE%@AE@%%@NL@%
  13604.   %@AS@%            .%@AE@%%@NL@%
  13605.   %@AS@%            .%@AE@%%@NL@%
  13606.   %@AS@%            .%@AE@%%@NL@%
  13607.   %@AS@%            mov     ax,0D743h  ; Load 0D7h to AH, 43h to AL  01000011%@AE@%%@NL@%
  13608.   %@AS@%            or      al,masker  ; Turn on bit 4 in AL      OR 00010000%@AE@%%@NL@%
  13609.   %@AS@%                               ;                             --------%@AE@%%@NL@%
  13610.   %@AS@%                               ; Result is 53h               01010011%@AE@%%@NL@%
  13611. %@NL@%
  13612.   %@AS@%            not     masker     ; Reverse sense of mask       11101111%@AE@%%@NL@%
  13613.   %@AS@%            and     ah,masker  ; Turn off bit 4 in AH    AND 11010111%@AE@%%@NL@%
  13614.   %@AS@%                               ;                             --------%@AE@%%@NL@%
  13615.   %@AS@%                               ; Result is 0C7h              11000111%@AE@%%@NL@%
  13616. %@NL@%
  13617. %@NL@%
  13618. %@2@%%@CR:SC14.7      @%%@AB@%14.7  Shifting and Rotating Bits%@AE@%%@EH@%%@NL@%
  13619. %@NL@%
  13620. %@4@%%@CR:IX14.112    @%  The 8086-family processors provide a complete set of instructions for%@EH@%
  13621.   shifting and rotating bits. Bits can be moved right (toward the
  13622.   most-significant bits) or left (toward the 0 bit). Values shifted off the
  13623.   end of the operand go into the carry flag.%@NL@%
  13624. %@NL@%
  13625. %@4@%  Shift instructions move bits a specified number of places to the right or%@EH@%
  13626.   left. The last bit in the direction of the shift goes into the carry flag,
  13627.   and the first bit is filled with 0 or with the previous value of the first
  13628.   bit.%@NL@%
  13629. %@NL@%
  13630. %@4@%%@CR:IX14.113    @%%@CR:IX14.114    @%  Rotate instructions move bits a specified number of places to the right or%@EH@%
  13631.   left. For each bit rotated, the last bit in the direction of the rotate
  13632.   operation is moved into the first bit position at the other end of the
  13633.   operand. With some variations, the carry bit is used as an additional bit
  13634.   of the operand. Figure 14.1 illustrates the eight variations of shift and
  13635.   rotate instructions for eight-bit operands. Notice that %@AB@%SHL%@AE@% and %@AB@%SAL%@AE@% are
  13636.   identical.%@NL@%
  13637. %@NL@%
  13638.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  13639.   │ This figure can be found in Section 14.7 of the manual                 │%@NL@%
  13640.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  13641. %@NL@%
  13642. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13643. %@NL@%
  13644. %@4@%  %@AB@%SHL%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AB@%CL%@AE@% | %@AB@%1%@AE@%} %@AB@%SHR%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AB@%CL%@AE@% | %@AB@%1%@AE@%} %@AB@%SAL%@AE@%%@EH@%
  13645.   {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AB@%CL%@AE@% | %@AB@%1%@AE@%} %@AB@%SAR%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AB@%CL%@AE@% | %@AB@%1%@AE@%} %@AB@%ROL%@AE@%
  13646.   {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AB@%CL%@AE@% | %@AB@%1%@AE@%} %@AB@%ROR%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AB@%CL%@AE@% | %@AB@%1%@AE@%} %@AB@%RCL%@AE@%
  13647.   {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AB@%CL%@AE@% | %@AB@%1%@AE@%} %@AB@%RCR%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AB@%CL%@AE@% | %@AB@%1%@AE@%}%@NL@%
  13648. %@NL@%
  13649. %@4@%  The format of all the shift instructions is the same. The destination%@EH@%
  13650.   operand should contain the value to be shifted. It will contain the
  13651.   shifted operand after the instruction. The source operand should contain
  13652.   the number of bits to shift or rotate. It can be the immediate value 1 or
  13653.   the CL register. No other value or register is accepted on the 8088 and
  13654.   8086 processors.%@NL@%
  13655. %@NL@%
  13656. %@4@%  %@AB@%80186/286/386 Only%@AE@%%@EH@%%@NL@%
  13657. %@NL@%
  13658. %@4@%  Starting with the 80186 processor, eight-bit immediate values larger than%@EH@%
  13659.   1 can be given as the source operand for shift or rotate instructions, as
  13660.   shown below:%@NL@%
  13661. %@NL@%
  13662.   %@AS@%            shr     bx,4       ;  9 clocks, 3 bytes on 80286%@AE@%%@NL@%
  13663. %@NL@%
  13664. %@4@%  The following statements are equivalent if the program must run the 8088%@EH@%
  13665.   or 8086:%@NL@%
  13666. %@NL@%
  13667.   %@AS@%            mov     cl,4       ;  2 clocks, 3 bytes on 80286%@AE@%%@NL@%
  13668.   %@AS@%            shr     bx,cl      ;  9 clocks, 2 bytes on 80286%@AE@%%@NL@%
  13669.   %@AS@%                               ; 11 clocks, 5 bytes%@AE@%%@NL@%
  13670. %@NL@%
  13671. %@NL@%
  13672. %@3@%%@CR:SC14.7.1    @%%@AB@%14.7.1  Multiplying and Dividing by Constants%@AE@%%@EH@%%@NL@%
  13673. %@NL@%
  13674. %@4@%%@CR:IX14.115    @%%@CR:IX14.116    @%%@CR:IX14.117    @%  Shifting right by one has the effect of dividing by two; shifting left by%@EH@%
  13675.   one has the effect of multiplying by two. You can take advantage of this
  13676.   to do fast multiplication and division by common constants. The easiest
  13677.   constants are the powers of two. Shifting left twice multiplies by four,
  13678.   shifting left three times multiplies by eight, and so on.%@NL@%
  13679. %@NL@%
  13680. %@4@%  %@AB@%SHR%@AE@% is used to divide unsigned numbers. %@AB@%SAR%@AE@% can be used to divide signed%@EH@%
  13681.   numbers, but %@AB@%SAR%@AE@% rounds negative numbers down──%@AB@%IDIV%@AE@% always rounds up. Code
  13682.   that divides by using %@AB@%SAR%@AE@% must adjust for this difference. Multiplication
  13683.   by shifting is the same for signed and unsigned numbers, so either %@AB@%SAL%@AE@% or
  13684.   %@AB@%SHL%@AE@% can be used. Both instructions do the same operation.%@NL@%
  13685. %@NL@%
  13686. %@4@%  Since the multiply and divide instructions are the slowest on the 8088 and%@EH@%
  13687.   8086 processors, using shifts instead can often speed operations by a
  13688.   factor of 10 or more. For example, on the 8088 or 8086 processor, the
  13689.   following statements take four clocks:%@NL@%
  13690. %@NL@%
  13691.   %@AS@%            xor     ah,ah      ; Clear AH%@AE@%%@NL@%
  13692.   %@AS@%            shl     ax,1       ; Multiply byte in AL by 2%@AE@%%@NL@%
  13693. %@NL@%
  13694. %@4@%  The following statements have the same effect, but take between 74 and 81%@EH@%
  13695.   clocks on the 8088 or 8086:%@NL@%
  13696. %@NL@%
  13697.   %@AS@%            mov     bl,2       ; Multiply byte in AL by 2%@AE@%%@NL@%
  13698.   %@AS@%            mul     bl%@AE@%%@NL@%
  13699. %@NL@%
  13700. %@4@%  The same statements take 15 clocks on the 80286. See the on-line Help%@EH@%
  13701.   system for complete information on timing of instructions.%@NL@%
  13702. %@NL@%
  13703. %@4@%  Shift instructions can be combined with add or subtract instructions to do%@EH@%
  13704.   multiplication by common constants. These operations are best put in
  13705.   macros so that they can be changed if the constants in a program change.%@NL@%
  13706. %@NL@%
  13707. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  13708. %@NL@%
  13709.   %@AS@%mul_10      MACRO   factor      ; Factor must be unsigned%@AE@%%@NL@%
  13710.   %@AS@%            mov     ax,factor   ; Load into AX%@AE@%%@NL@%
  13711.   %@AS@%            shl     ax,1        ; AX = factor * 2%@AE@%%@NL@%
  13712.   %@AS@%            mov     bx,ax       ; Save copy in BX%@AE@%%@NL@%
  13713.   %@AS@%            shl     ax,1        ; AX = factor * 4%@AE@%%@NL@%
  13714.   %@AS@%            shl     ax,1        ; AX = factor * 8%@AE@%%@NL@%
  13715.   %@AS@%            add     ax,bx       ; AX = (factor * 8) + (factor * 2)%@AE@%%@NL@%
  13716.   %@AS@%            ENDM                ; AX = factor * 10%@AE@%%@NL@%
  13717. %@NL@%
  13718. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  13719. %@NL@%
  13720.   %@AS@%div_u512    MACRO   dividend    ; Dividend must be unsigned%@AE@%%@NL@%
  13721.   %@AS@%            mov     ax,dividend ; Load into AX%@AE@%%@NL@%
  13722.   %@AS@%            shr     ax,1        ;   AX = dividend / 2 (unsigned)%@AE@%%@NL@%
  13723.   %@AS@%            xchg    al,ah       ; xchg is like rotate right 8%@AE@%%@NL@%
  13724.   %@AS@%                                ;   AL = (dividend / 2) / 256%@AE@%%@NL@%
  13725.   %@AS@%            cbw                 ; Clear upper byte%@AE@%%@NL@%
  13726.   %@AS@%            ENDM                ;   AX = (dividend / 512%@AE@%%@NL@%
  13727. %@NL@%
  13728. %@NL@%
  13729. %@3@%%@CR:SC14.7.2    @%%@AB@%14.7.2  Moving Bits to the Least-Significant Position%@AE@%%@EH@%%@NL@%
  13730. %@NL@%
  13731. %@4@%  Sometimes a group of bits within an operand needs to be treated as a%@EH@%
  13732.   single unit──for example, to do an arithmetic operation on those bits
  13733.   without affecting other bits. This can be done by masking off the bits and
  13734.   then shifting them into the least-significant positions. After the
  13735.   arithmetic operation is done, the bits are shifted back to the original
  13736.   position and merged with the original bits by using %@AB@%OR%@AE@%. See Section
  13737.   7.2.5%@BO:       7047a@%, "Using Record-Field Operands," for an example of this operation.%@NL@%
  13738. %@NL@%
  13739. %@NL@%
  13740. %@3@%%@CR:SC14.7.3    @%%@AB@%14.7.3  Adjusting Masks%@AE@%%@EH@%%@NL@%
  13741. %@NL@%
  13742. %@4@%%@CR:IX14.118    @%  Masks for logical instructions can be shifted to new bit positions. For%@EH@%
  13743.   example, an operand that masks off a bit or group of bits can be shifted
  13744.   to move the mask to a different position.%@NL@%
  13745. %@NL@%
  13746. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  13747. %@NL@%
  13748.   %@AS@%            .DATA%@AE@%%@NL@%
  13749.   %@AS@%masker      DB      00000010b  ; Mask that may change at run time%@AE@%%@NL@%
  13750.   %@AS@%            .CODE%@AE@%%@NL@%
  13751.   %@AS@%            .%@AE@%%@NL@%
  13752.   %@AS@%            .%@AE@%%@NL@%
  13753.   %@AS@%            .%@AE@%%@NL@%
  13754.   %@AS@%            mov     cl,2       ; Rotate two at a time%@AE@%%@NL@%
  13755.   %@AS@%            mov     bl,57h     ; Load value to be changed    01010111b%@AE@%%@NL@%
  13756.   %@AS@%            rol     masker,cl  ; Rotate two to left          00001000b%@AE@%%@NL@%
  13757.   %@AS@%            or      bl,masker  ; Turn on masked values       ---------%@AE@%%@NL@%
  13758.   %@AS@%                               ; New value is 05Fh           01011111b%@AE@%%@NL@%
  13759.   %@AS@%            rol     masker,cl  ; Rotate two more             00100000b%@AE@%%@NL@%
  13760.   %@AS@%            or      bl,masker  ; Turn on masked values       ---------%@AE@%%@NL@%
  13761.   %@AS@%                               ; New value is 07Fh           01111111b%@AE@%%@NL@%
  13762. %@NL@%
  13763. %@4@%  This technique is useful only if the mask value is unknown until run time.%@EH@%%@NL@%
  13764. %@NL@%
  13765. %@NL@%
  13766. %@3@%%@CR:SC14.7.4    @%%@AB@%14.7.4  Shifting Multiword Values%@AE@%%@EH@%%@NL@%
  13767. %@NL@%
  13768. %@4@%%@CR:IX14.119    @%%@CR:IX14.120    @%  Sometimes it is necessary to shift a value that is too large to fit in a%@EH@%
  13769.   register. In this case, you can shift each part separately, passing the
  13770.   shifted bits through the carry flag. The %@AB@%RCR%@AE@% or %@AB@%RCL%@AE@% instructions must be
  13771.   used to move the carry value from the first register to the second.%@NL@%
  13772. %@NL@%
  13773. %@4@%  %@AB@%RCR%@AE@% and %@AB@%RCL%@AE@% can also be used to initialize the high or low bit of an%@EH@%
  13774.   operand. Since the carry flag is treated as part of the operand (like
  13775.   using a nine-bit operand), the flag value before the operation is crucial.
  13776.   The carry flag may be set by a previous instruction, or you can set it
  13777.   directly using the %@AB@%CLC%@AE@% (Clear Carry Flag), %@AB@%CMC%@AE@% (Complement Carry Flag),
  13778.   and %@AB@%STC%@AE@% (Set Carry Flag) instructions.%@NL@%
  13779. %@NL@%
  13780. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  13781. %@NL@%
  13782.   %@AS@%            .DATA%@AE@%%@NL@%
  13783.   %@AS@%mem32       DD      500000%@AE@%%@NL@%
  13784.   %@AS@%            .CODE%@AE@%%@NL@%
  13785.   %@AS@%            .%@AE@%%@NL@%
  13786.   %@AS@%            .                            ; Divide 32-bit unsigned by 16%@AE@%%@NL@%
  13787.   %@AS@%            .%@AE@%%@NL@%
  13788.   %@AS@%            mov     cx,4                 ; Shift right 4        500000%@AE@%%@NL@%
  13789.   %@AS@%again:      shr     WORD PTR mem32[2],1  ; Shift into carry  DIV    16%@AE@%%@NL@%
  13790.   %@AS@%            rcr     WORD PTR mem32[0],1  ; Rotate carry in      ------%@AE@%%@NL@%
  13791.   %@AS@%            loop    again                ;                       31250%@AE@%%@NL@%
  13792. %@NL@%
  13793. %@NL@%
  13794. %@NL@%
  13795. ────────────────────────────────────────────────────────────────────────────%@NL@%
  13796. %@1@%%@CR:CH15        @%%@AB@%Chapter 15:  Controlling Program Flow%@AE@%%@EH@%%@NL@%
  13797. %@NL@%
  13798. %@NL@%
  13799. %@4@%%@CR:IX15.1      @%%@CR:IX15.2      @%  The 8086-family processors provide a variety of instructions for%@EH@%
  13800.   controlling the flow of a program. The four major types of program-flow
  13801.   instructions are jumps, loops, procedure calls, and interrupts.%@NL@%
  13802. %@NL@%
  13803. %@4@%  This chapter tells you how to use these instructions and how to test%@EH@%
  13804.   conditions for the instructions that change program flow conditionally.%@NL@%
  13805. %@NL@%
  13806. %@NL@%
  13807. %@2@%%@CR:SC15.1      @%%@AB@%15.1  Jumping%@AE@%%@EH@%%@NL@%
  13808. %@NL@%
  13809. %@4@%%@CR:IX15.3      @%%@CR:IX15.4      @%  Jumps are the most direct method of changing program control from one%@EH@%
  13810.   location to another. At the internal level, jumps work by changing the
  13811.   value of the IP (Instruction Pointer) register from the address of the
  13812.   current instruction to a target address.%@NL@%
  13813. %@NL@%
  13814. %@4@%  Jumps can be short, near, or far. QuickAssembler automatically handles%@EH@%
  13815.   near and short jumps, although it may not always generate the most
  13816.   efficient code if the label being jumped to is a forward reference. The
  13817.   size and control of jumps are discussed in Section 9.4.1%@BO:       845be@%, "Forward
  13818.   References to Labels."%@NL@%
  13819. %@NL@%
  13820. %@NL@%
  13821. %@3@%%@CR:SC15.1.1    @%%@AB@%15.1.1  Jumping Unconditionally%@AE@%%@EH@%%@NL@%
  13822. %@NL@%
  13823. %@4@%%@CR:IX15.5      @%%@CR:IX15.6      @%%@CR:IX15.7      @%  The %@AB@%JMP%@AE@% instruction is used to jump unconditionally to a specified%@EH@%
  13824.   address.%@NL@%
  13825. %@NL@%
  13826. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13827. %@NL@%
  13828. %@4@%  %@AB@%JMP%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@EH@%%@NL@%
  13829. %@NL@%
  13830. %@4@%  The operand should contain the address to be jumped to. Unlike conditional%@EH@%
  13831.   jumps, whose target address must be short (within 128 bytes), the target
  13832.   address for unconditional jumps can be short, near, or far. See Section
  13833.   9.4.1%@BO:       845be@% for more information on specifying the distance for conditional
  13834.   jumps.%@NL@%
  13835. %@NL@%
  13836. %@4@%  If a conditional jump must be greater than 128 bytes, the construction%@EH@%
  13837.   must be reorganized. This can be done by reversing the sense of the
  13838.   conditional jump and adding an unconditional jump, as shown in Example 1.%@NL@%
  13839. %@NL@%
  13840. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  13841. %@NL@%
  13842.   %@AS@%            cmp     ax,7       ; If AX is 7 and jump is short%@AE@%%@NL@%
  13843.   %@AS@%            je      close      ;   then jump close%@AE@%%@NL@%
  13844. %@NL@%
  13845.   %@AS@%            cmp     ax,6       ; If AX is 6 and jump is near%@AE@%%@NL@%
  13846.   %@AS@%            jne     close      ;   then test opposite and skip over%@AE@%%@NL@%
  13847.   %@AS@%            jmp     distant    ; Now jump%@AE@%%@NL@%
  13848.   %@AS@%            .%@AE@%%@NL@%
  13849.   %@AS@%            .%@AE@%%@NL@%
  13850.   %@AS@%            .%@AE@%%@NL@%
  13851.   %@AS@%close:                         ; Less than 128 bytes from jump%@AE@%%@NL@%
  13852.   %@AS@%            .%@AE@%%@NL@%
  13853.   %@AS@%            .%@AE@%%@NL@%
  13854.   %@AS@%            .%@AE@%%@NL@%
  13855.   %@AS@%distant:                       ; More than 128 bytes from jump%@AE@%%@NL@%
  13856. %@NL@%
  13857. %@4@%%@CR:IX15.8      @%%@CR:IX15.9      @%%@CR:IX15.10     @%%@CR:IX15.11     @%%@CR:IX15.12     @%  An unconditional jump can be used as a form of conditional jump by%@EH@%
  13858.   specifying the address in a register or indirect memory operand. The value
  13859.   of the operand can be calculated at run time, based on user interaction or
  13860.   other factors. You can use indirect memory operands to construct jump
  13861.   tables that work like C %@AB@%switch%@AE@% statements, BASIC %@AB@%ON GOTO%@AE@% statements, or
  13862.   Pascal %@AB@%case%@AE@% statements.%@NL@%
  13863. %@NL@%
  13864. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  13865. %@NL@%
  13866.   %@AS@%            .CODE%@AE@%%@NL@%
  13867.   %@AS@%            .%@AE@%%@NL@%
  13868.   %@AS@%            .%@AE@%%@NL@%
  13869.   %@AS@%            .%@AE@%%@NL@%
  13870.   %@AS@%            jmp     process            ; Jump over data%@AE@%%@NL@%
  13871.   %@AS@%ctl_tbl     LABEL   WORD               ;   (required in overlay procedures)%@AE@%%@NL@%
  13872.   %@AS@%            DW      extended           ; Null key (extended code)%@AE@%%@NL@%
  13873.   %@AS@%            DW      ctrla              ; Address of CONTROL-A key routine%@AE@%%@NL@%
  13874.   %@AS@%            DW      ctrlb              ; Address of CONTROL-B key routine%@AE@%%@NL@%
  13875.   %@AS@%process:    mov     ah,8h              ; Get a key%@AE@%%@NL@%
  13876.   %@AS@%            int     21h%@AE@%%@NL@%
  13877.   %@AS@%            cbw                        ; Convert AL to AX%@AE@%%@NL@%
  13878.   %@AS@%            mov     bx,ax              ; Copy%@AE@%%@NL@%
  13879.   %@AS@%            shl     bx,1               ; Convert to address%@AE@%%@NL@%
  13880. %@NL@%
  13881.   %@AS@%            jmp     ctl_tbl[bx]        ; Jump to key routine%@AE@%%@NL@%
  13882. %@NL@%
  13883.   %@AS@%extended:   mov     ah,8h              ; Get second key of extended%@AE@%%@NL@%
  13884.   %@AS@%            int     21h%@AE@%%@NL@%
  13885.   %@AS@%            .                          ; Use another jump table%@AE@%%@NL@%
  13886.   %@AS@%            .                          ;   for extended keys%@AE@%%@NL@%
  13887.   %@AS@%            .%@AE@%%@NL@%
  13888.   %@AS@%ctrla:      .                          ; CONTROL-A routine here%@AE@%%@NL@%
  13889.   %@AS@%            .%@AE@%%@NL@%
  13890.   %@AS@%            .%@AE@%%@NL@%
  13891.   %@AS@%            jmp     next%@AE@%%@NL@%
  13892. %@NL@%
  13893.   %@AS@%ctrlb:      .                          ; CONTROL-B routine here%@AE@%%@NL@%
  13894.   %@AS@%            .%@AE@%%@NL@%
  13895.   %@AS@%            .%@AE@%%@NL@%
  13896.   %@AS@%            jmp     next%@AE@%%@NL@%
  13897.   %@AS@%            .%@AE@%%@NL@%
  13898.   %@AS@%            .%@AE@%%@NL@%
  13899.   %@AS@%next:       .                          ; Continue%@AE@%%@NL@%
  13900. %@NL@%
  13901. %@4@%  In Example 2, an indirect memory operand points to addresses of routines%@EH@%
  13902.   for handling different keystrokes. Notice that the jump table is placed in
  13903.   the code segment. This technique is optional in stand-alone assembler
  13904.   programs, but it may be required for procedures called from some
  13905.   languages.%@NL@%
  13906. %@NL@%
  13907. %@NL@%
  13908. %@3@%%@CR:SC15.1.2    @%%@AB@%15.1.2  Jumping Conditionally%@AE@%%@EH@%%@NL@%
  13909. %@NL@%
  13910. %@4@%%@CR:IX15.13     @%%@CR:IX15.14     @%  The most common way of transferring control in assembly language is with%@EH@%
  13911.   conditional jumps. This is a two-step process: first test the condition,
  13912.   and then jump if the condition is true or continue if it is false.%@NL@%
  13913. %@NL@%
  13914. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13915. %@NL@%
  13916. %@4@%  %@AB@%J%@AE@%%@AI@%condition%@AE@% %@AI@%label%@AE@%%@EH@%%@NL@%
  13917. %@NL@%
  13918. %@4@%  Conditional-jump instructions take a single operand containing the address%@EH@%
  13919.   to be jumped to. The distance from the jump instruction to the specified
  13920.   address must be short (less than 128 bytes). If a longer distance is
  13921.   specified, an error will be generated telling the distance of the jump in
  13922.   bytes. See Section 15.1.1%@BO:       bd2e4@%, "Jumping Unconditionally," for information on
  13923.   arranging longer conditional jumps.%@NL@%
  13924. %@NL@%
  13925. %@4@%%@CR:IX15.15     @%%@CR:IX15.16     @%%@CR:IX15.17     @%%@CR:IX15.18     @%%@CR:IX15.19     @%%@CR:IX15.20     @%  Conditional-jump instructions (except %@AB@%JCXZ%@AE@%) use the status of one or more%@EH@%
  13926.   flags as their condition. Thus, any statement that sets a flag under
  13927.   specified conditions can be the test statement. The most common test
  13928.   statements use the %@AB@%CMP%@AE@% or %@AB@%TEST%@AE@% instructions. The jump statement can be any
  13929.   one of 31 conditional-jump instructions.%@NL@%
  13930. %@NL@%
  13931. %@4@%  Because conditional jumps cannot refer to labels more than 128 bytes away,%@EH@%
  13932.   they are often used in combination with unconditional jumps, which have no
  13933.   such limitation. For example, the following statement is valid as long as
  13934.   %@AS@%target %@AE@%is not far away:%@NL@%
  13935. %@NL@%
  13936.   %@AS@%            jz      target     ; If previous operation resulted in%@AE@%%@NL@%
  13937.   %@AS@%                               ;   zero, jump to target%@AE@%%@NL@%
  13938. %@NL@%
  13939. %@4@%  Once %@AS@%target %@AE@%becomes too distant, the following sequence must be used to%@EH@%
  13940.   enable a longer jump. Note that this sequence is logically equivalent to
  13941.   the example above:%@NL@%
  13942. %@NL@%
  13943.   %@AS@%            jnz     skip       ; If previous operation resulted in NOT zero,%@AE@%%@NL@%
  13944.   %@AS@%                               ;   jump to "skip"%@AE@%%@NL@%
  13945.   %@AS@%            jmp     target     ; Otherwise, jump to target%@AE@%%@NL@%
  13946.   %@AS@%skip:%@AE@%%@NL@%
  13947. %@NL@%
  13948. %@4@%  The instructions above first test for the logical %@AI@%inverse%@AE@% of the desired%@EH@%
  13949.   condition. If the test condition (in this case, equality to zero) is %@AI@%not%@AE@%
  13950.   true, the jump to %@AS@%target %@AE@%is avoided. Yet if a zero condition is true, the
  13951.   program falls through to the instruction %@AS@%jmp target%@AE@%, which can jump any
  13952.   distance. The effect, of course, is to jump to %@AS@%target %@AE@%if the previous
  13953.   operation resulted in zero.%@NL@%
  13954. %@NL@%
  13955. %@4@%  The problem with this technique is that if used often, you may have to%@EH@%
  13956.   think up a label name just to jump around one instruction. Anonymous
  13957.   labels, described in Section 6.4.2%@BO:       5e370@%, let you avoid having to invent so
  13958.   many label names. For example, you could use an anonymous label to rewrite
  13959.   the example above:%@NL@%
  13960. %@NL@%
  13961.   %@AS@%            jnz     @F      ; If previous operation resulted in NOT zero,%@AE@%%@NL@%
  13962.   %@AS@%                            ;   jump forward to next @ label%@AE@%%@NL@%
  13963.   %@AS@%            jmp     target  ; Otherwise, jump to target%@AE@%%@NL@%
  13964.   %@AS@%@:%@AE@%%@NL@%
  13965. %@NL@%
  13966. %@NL@%
  13967. %@3@%%@CR:SC15.1.2.1  @%%@AB@%15.1.2.1  Comparing and Jumping%@AE@%%@EH@%%@NL@%
  13968. %@NL@%
  13969. %@4@%  The %@AB@%CMP%@AE@% instruction is specifically designed to test for conditional%@EH@%
  13970.   jumps. It does not change the destination operand, so it can be used to
  13971.   compare two values without changing either of them. Instructions that
  13972.   change operands (such as %@AB@%SUB%@AE@% or %@AB@%AND%@AE@%) can also be used to test conditions.%@NL@%
  13973. %@NL@%
  13974. %@4@%%@CR:IX15.21     @%%@CR:IX15.22     @%  The %@AB@%CMP%@AE@% instruction compares two operands and sets flags based on the%@EH@%
  13975.   result. It is used to test the following relationships: equal; not equal;
  13976.   greater than; less than; greater than or equal; or less than or equal.%@NL@%
  13977. %@NL@%
  13978. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  13979. %@NL@%
  13980. %@4@%  %@AB@%CMP %@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@EH@%%@NL@%
  13981. %@NL@%
  13982. %@4@%  The destination operand can be %@AI@%memory%@AE@% or %@AI@%register%@AE@%. The source operand can%@EH@%
  13983.   be %@AI@%immediate%@AE@%, %@AI@%memory%@AE@%, or %@AI@%register%@AE@%. However, they cannot both be memory
  13984.   operands.%@NL@%
  13985. %@NL@%
  13986. %@4@%  The jump instructions that can be used with %@AB@%CMP%@AE@% are made up of mnemonic%@EH@%
  13987.   letters combined to indicate the type of jump. The letters are shown
  13988.   below:%@NL@%
  13989. %@NL@%
  13990.   %@AB@%Letter%@AE@%              %@AB@%Meaning%@AE@%%@NL@%
  13991.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  13992.   J                   Jump%@NL@%
  13993. %@NL@%
  13994.   G                   Greater than (for unsigned comparisons)%@NL@%
  13995. %@NL@%
  13996.   L                   Less than (for unsigned comparisons)%@NL@%
  13997. %@NL@%
  13998.   A                   Above (for signed comparisons)%@NL@%
  13999. %@NL@%
  14000.   B                   Below (for signed comparisons)%@NL@%
  14001. %@NL@%
  14002.   E                   Equal%@NL@%
  14003. %@NL@%
  14004.   N                   Not%@NL@%
  14005. %@NL@%
  14006. %@NL@%
  14007. %@4@%  The mnemonic names always refer to the relationship that the first operand%@EH@%
  14008.   of the %@AB@%CMP%@AE@% instruction has to the second operand of the %@AB@%CMP%@AE@% instruction.
  14009.   For instance, %@AB@%JG%@AE@% tests whether the first operand is greater than the
  14010.   second. Several conditional instructions have two names. You can use
  14011.   whichever name seems more mnemonic in context.%@NL@%
  14012. %@NL@%
  14013. %@4@%  Comparisons and conditional jumps can be thought of as statements in the%@EH@%
  14014.   following format:%@NL@%
  14015. %@NL@%
  14016. %@4@%  %@AB@%IF%@AE@% (%@AI@%value1%@AE@% %@AI@%relationship%@AE@% %@AI@%value2%@AE@%) %@AB@%THEN GOTO%@AE@% %@AI@%truelabel:%@AE@%%@EH@%%@NL@%
  14017. %@NL@%
  14018. %@4@%  Statements of this type can be coded in assembly language by using the%@EH@%
  14019.   following syntax:%@NL@%
  14020. %@NL@%
  14021. %@4@%  %@AB@%CMP %@AE@%%@AI@%value1%@AE@%,%@AI@%value2%@AE@%%@EH@%%@NL@%
  14022.   %@AB@%J%@AE@%%@AI@%relationship%@AE@% %@AI@%truelabel%@AE@%%@NL@%
  14023.   .%@NL@%
  14024.   .%@NL@%
  14025.   .%@NL@%
  14026.   %@AI@%truelabel%@AE@%:%@NL@%
  14027. %@NL@%
  14028. %@4@%%@CR:IX15.23     @%%@CR:IX15.24     @%%@CR:IX15.25     @%%@CR:IX15.26     @%%@CR:IX15.27     @%  Table 15.1 lists conditional-jump instructions for each %@AI@%relationship%@AE@% and%@EH@%
  14029.   shows the flags that are tested in order to see if %@AI@%relationship%@AE@% is true.%@NL@%
  14030. %@NL@%
  14031.   %@AB@%Table 15.1 Conditional-Jump Instructions Used after Compare%@AE@%%@NL@%
  14032. %@NL@%
  14033.   %@AB@%Jump Condition%@AE@%  %@AB@%Signed%@AE@%        %@AB@%Jump if:%@AE@%    %@AB@%Unsigned%@AE@%      %@AB@%Jump if:%@AE@%
  14034.                   %@AB@%Compare%@AE@%                   %@AB@%Compare%@AE@%%@NL@%
  14035.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14036.   = Equal         %@AB@%JE%@AE@%            ZF = 1      %@AB@%JE%@AE@%            ZF = 1%@NL@%
  14037. %@NL@%
  14038.   ╪ Not equal     %@AB@%JNE%@AE@%           ZF = 1      %@AB@%JNE%@AE@%           ZF = 1%@NL@%
  14039. %@NL@%
  14040.   > Greater than  %@AB@%JG%@AE@% or %@AB@%JNLE%@AE@%    ZF = 0 and  %@AB@%JA%@AE@% or %@AB@%JNBE%@AE@%    CF = 0 and ZF = 0
  14041.                                 SF = OF%@NL@%
  14042.   <= Less than or %@AB@%JLE%@AE@% or %@AB@%JNG%@AE@%    ZF = 1 and  %@AB@%JBE%@AE@% or %@AB@%JNA%@AE@%    CF = 1 or ZF = 1
  14043.   equal                         SF ╪ OF%@NL@%
  14044.   < Less than     %@AB@%JL%@AE@% or %@AB@%JNGE%@AE@%    SF ╪ OF     %@AB@%JB%@AE@% or %@AB@%JNAE%@AE@%    CF = 1%@NL@%
  14045. %@NL@%
  14046.   >= Greater than %@AB@%JGE%@AE@% or %@AB@%JNL%@AE@%    SF = OF     %@AB@%JAE%@AE@% or %@AB@%JNB%@AE@%    CF = 0
  14047.   or equal%@NL@%
  14048.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14049. %@NL@%
  14050. %@NL@%
  14051. %@4@%%@CR:IX15.28     @%%@CR:IX15.29     @%  Internally, the %@AB@%CMP%@AE@% instruction is exactly the same as the %@AB@%SUB%@AE@%%@EH@%
  14052.   instruction, except that the destination operand is not changed. The flags
  14053.   are set according to the result that would have been generated by a
  14054.   subtraction.%@NL@%
  14055. %@NL@%
  14056. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  14057. %@NL@%
  14058.   %@AS@%; If CX is less than -20, then make DX 30, else make DX 20%@AE@%%@NL@%
  14059. %@NL@%
  14060.   %@AS@%            cmp     cx,-20     ; If signed CX is smaller than -20%@AE@%%@NL@%
  14061.   %@AS@%            jl      less       ;   then do stuff at "less"%@AE@%%@NL@%
  14062.   %@AS@%            mov     dx,20      ; Else set DX to 20%@AE@%%@NL@%
  14063.   %@AS@%            jmp     skip       ; Finished%@AE@%%@NL@%
  14064.   %@AS@%less:       mov     dx,30      ; Then set DX to 30%@AE@%%@NL@%
  14065.   %@AS@%skip:%@AE@%%@NL@%
  14066. %@NL@%
  14067. %@4@%  Example 1 shows the basic form of conditional jumps. Notice that in%@EH@%
  14068.   assembly language, if-then-else constructions are usually written in the
  14069.   form if-else-then.%@NL@%
  14070. %@NL@%
  14071. %@4@%  This theme has many variations. For example, you may find it more mnemonic%@EH@%
  14072.   to code in the if-then-else format. However, you must then use the
  14073.   opposite jump condition, as shown in Example 2.%@NL@%
  14074. %@NL@%
  14075. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  14076. %@NL@%
  14077.   %@AS@%; If CX is greater than or equal to -20, then make DX 20, else make DX 30%@AE@%%@NL@%
  14078. %@NL@%
  14079.   %@AS@%            cmp     cx,-20     ; If signed CX is smaller than -20%@AE@%%@NL@%
  14080.   %@AS@%            jnl     notless    ;   else do stuff at "notless"%@AE@%%@NL@%
  14081.   %@AS@%            mov     dx,30      ; Then set DX to 30%@AE@%%@NL@%
  14082.   %@AS@%            jmp     continue   ; Finished%@AE@%%@NL@%
  14083.   %@AS@%notless:    mov     dx,20      ; Else set DX to 20%@AE@%%@NL@%
  14084.   %@AS@%continue:%@AE@%%@NL@%
  14085. %@NL@%
  14086. %@4@%  The then-if-else format shown in Example 3 is often more efficient. Do the%@EH@%
  14087.   work for the most likely case, and then compare for the opposite
  14088.   condition. If the condition is true, you are finished.%@NL@%
  14089. %@NL@%
  14090. %@4@%  %@AB@%Example 3%@AE@%%@EH@%%@NL@%
  14091. %@NL@%
  14092.   %@AS@%; DX is 20, unless CX is less than -20, then make DX 30%@AE@%%@NL@%
  14093. %@NL@%
  14094.   %@AS@%            mov     dx,20      ; DX is 20%@AE@%%@NL@%
  14095.   %@AS@%            cmp     cx,-20     ; If signed CX is greater than -20%@AE@%%@NL@%
  14096.   %@AS@%            jge     greatequ   ;   then done%@AE@%%@NL@%
  14097.   %@AS@%            mov     dx,30      ; Else set DX to 30%@AE@%%@NL@%
  14098.   %@AS@%greatequ:%@AE@%%@NL@%
  14099. %@NL@%
  14100. %@4@%  This example avoids the unconditional jump used in Examples 1 and 2 and%@EH@%
  14101.   thus is faster even if the less likely condition is true.%@NL@%
  14102. %@NL@%
  14103. %@NL@%
  14104. %@3@%%@CR:SC15.1.2.2  @%%@AB@%15.1.2.2  Jumping Based on Flag Status%@AE@%%@EH@%%@NL@%
  14105. %@NL@%
  14106. %@4@%%@CR:IX15.30     @%%@CR:IX15.31     @%  The %@AB@%CMP%@AE@% instruction is the most mnemonic way to set the flags for%@EH@%
  14107.   conditional jumps, but any instruction that changes flags can be used as
  14108.   the test condition. The conditional-jump instructions listed below enable
  14109.   you to jump based on the condition of flags rather than on relationships
  14110.   of operands. Some of these instructions have the same effect as
  14111.   instructions listed in Table 15.1.%@NL@%
  14112. %@NL@%
  14113.   %@AB@%Instruction%@AE@%         %@AB@%Action%@AE@%%@NL@%
  14114.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14115. %@CR:IX15.32     @%  %@AB@%JO%@AE@%                  Jumps if the overflow flag is set%@NL@%
  14116. %@NL@%
  14117.   %@AB@%JNO%@AE@%                 Jumps if the overflow flag is clear%@NL@%
  14118. %@NL@%
  14119.   %@AB@%JC%@AE@%                  Jumps if the carry flag is set (same as %@AB@%JB%@AE@%)%@NL@%
  14120. %@NL@%
  14121.   %@AB@%JNC%@AE@%                 Jumps if the carry flag is clear (same as %@AB@%JAE%@AE@%)%@NL@%
  14122. %@NL@%
  14123.   %@AB@%JZ%@AE@%                  Jumps if the zero flag is set (same as %@AB@%JE%@AE@%)%@NL@%
  14124. %@NL@%
  14125.   %@AB@%JNZ%@AE@%                 Jumps if the zero flag is clear (same as %@AB@%JNE%@AE@%)%@NL@%
  14126. %@NL@%
  14127.   %@AB@%JS%@AE@%                  Jumps if the sign flag is set%@NL@%
  14128. %@NL@%
  14129.   %@AB@%JNS%@AE@%                 Jumps if the sign flag is clear%@NL@%
  14130. %@NL@%
  14131.   %@AB@%JP%@AE@%                  Jumps if the parity flag is set%@NL@%
  14132. %@NL@%
  14133.   %@AB@%JNP%@AE@%                 Jumps if the parity flag is clear%@NL@%
  14134. %@NL@%
  14135.   %@AB@%JPE%@AE@%                 Jumps if parity is even (parity flag set)%@NL@%
  14136. %@NL@%
  14137.   %@AB@%JPO%@AE@%                 Jumps if parity is odd (parity flag clear)%@NL@%
  14138. %@NL@%
  14139.   %@AB@%JCXZ%@AE@%                Jumps if %@AB@%CX%@AE@% is 0%@NL@%
  14140. %@NL@%
  14141. %@NL@%
  14142. %@4@%  Notice that %@AB@%JCXZ%@AE@% is the only conditional jump based on the condition of a%@EH@%
  14143.   register (CX) rather than flags. Since %@AB@%JCXZ%@AE@% is usually used with loop
  14144.   instructions, it is discussed in more detail in Section 15.2%@BO:       c265d@%, "Looping."%@NL@%
  14145. %@NL@%
  14146. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  14147. %@NL@%
  14148.   %@AS@%            add     ax,bx      ; Add two values%@AE@%%@NL@%
  14149.   %@AS@%            jo      overflow   ; If value too large, adjust%@AE@%%@NL@%
  14150.   %@AS@%            .%@AE@%%@NL@%
  14151.   %@AS@%            .%@AE@%%@NL@%
  14152.   %@AS@%            .%@AE@%%@NL@%
  14153.   %@AS@%overflow:                      ; Adjustment routine here%@AE@%%@NL@%
  14154. %@NL@%
  14155. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  14156. %@NL@%
  14157.   %@AS@%            sub     ax,dx      ; Subtract%@AE@%%@NL@%
  14158.   %@AS@%            jnz     skip       ; If the result is not zero, continue%@AE@%%@NL@%
  14159.   %@AS@%            call    zhandler   ;   else do special case%@AE@%%@NL@%
  14160.   %@AS@%skip:%@AE@%%@NL@%
  14161. %@NL@%
  14162. %@NL@%
  14163. %@3@%%@CR:SC15.1.2.3  @%%@AB@%15.1.2.3  Testing Bits and Jumping%@AE@%%@EH@%%@NL@%
  14164. %@NL@%
  14165. %@4@%%@CR:IX15.33     @%%@CR:IX15.34     @%  Like the %@AB@%CMP%@AE@% instruction, the %@AB@%TEST%@AE@% instruction is designed to test for%@EH@%
  14166.   conditional jumps. However, specific bits are compared rather than entire
  14167.   operands.%@NL@%
  14168. %@NL@%
  14169. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  14170. %@NL@%
  14171. %@4@%  %@AB@%TEST%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@AB@%,%@AE@%{%@AI@%register%@AE@% | %@AI@%memory%@AE@% | %@AI@%immediate%@AE@%}%@EH@%%@NL@%
  14172. %@NL@%
  14173. %@4@%  The destination operand can be %@AI@%memory%@AE@% or %@AI@%register%@AE@%. The source operand can%@EH@%
  14174.   be %@AI@%immediate%@AE@%, %@AI@%memory%@AE@%, or %@AI@%register%@AE@%. However, they cannot both be memory
  14175.   operands.%@NL@%
  14176. %@NL@%
  14177. %@4@%%@CR:IX15.35     @%%@CR:IX15.36     @%  Normally, one of the operands is a mask in which the bits to be tested are%@EH@%
  14178.   the only bits set. The other operand contains the value to be tested. If
  14179.   all the bits set in the mask are clear in the operand being tested, the
  14180.   zero flag will be set. If any of the flags set in the mask are also set in
  14181.   the operand, the zero flag will be cleared.%@NL@%
  14182. %@NL@%
  14183. %@4@%%@CR:IX15.37     @%%@CR:IX15.38     @%  The %@AB@%TEST%@AE@% instruction is actually the same as the %@AB@%AND%@AE@% instruction, except%@EH@%
  14184.   that neither operand is changed. If the result of the operation is 0, the
  14185.   zero flag is set, but the 0 is not actually written to the destination
  14186.   operand.%@NL@%
  14187. %@NL@%
  14188. %@4@%%@CR:IX15.39     @%%@CR:IX15.40     @%  You can use the %@AB@%JZ%@AE@% and %@AB@%JNZ%@AE@% instructions to jump after the test. %@AB@%JE%@AE@% and %@AB@%JNE%@AE@%%@EH@%
  14189.   are the same and can be used if you find them more mnemonic.%@NL@%
  14190. %@NL@%
  14191. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  14192. %@NL@%
  14193.   %@AS@%            .DATA%@AE@%%@NL@%
  14194.   %@AS@%bits        DB      ?%@AE@%%@NL@%
  14195.   %@AS@%            .CODE%@AE@%%@NL@%
  14196.   %@AS@%            .%@AE@%%@NL@%
  14197.   %@AS@%            .%@AE@%%@NL@%
  14198.   %@AS@%            .%@AE@%%@NL@%
  14199.   %@AS@%; If bit 2 or bit 4 is set, then call taska%@AE@%%@NL@%
  14200. %@NL@%
  14201.   %@AS@%                                 ; Assume "bits" is 0D3h       11010011%@AE@%%@NL@%
  14202.   %@AS@%            test    bits,10100b  ; If 2 or 4 is set        AND 00010100%@AE@%%@NL@%
  14203.   %@AS@%            jz      skip1        ; Else continue               --------%@AE@%%@NL@%
  14204.   %@AS@%            call    taska        ; Then call taska             00010000%@AE@%%@NL@%
  14205.   %@AS@%skip1:                           ; Jump not taken%@AE@%%@NL@%
  14206.   %@AS@%            .%@AE@%%@NL@%
  14207.   %@AS@%            .%@AE@%%@NL@%
  14208.   %@AS@%            .%@AE@%%@NL@%
  14209.   %@AS@%; If bits 2 and 4 are clear, then call taskb%@AE@%%@NL@%
  14210. %@NL@%
  14211.   %@AS@%                                 ; Assume "bits" is 0E9h       11101001%@AE@%%@NL@%
  14212.   %@AS@%           test    bits,10100b   ; If 2 and 4 are clear    AND 00010100%@AE@%%@NL@%
  14213.   %@AS@%           jnz     skip2         ; Else continue               --------%@AE@%%@NL@%
  14214.   %@AS@%           call    taskb         ; Then call taskb             00000000%@AE@%%@NL@%
  14215.   %@AS@%skip2:                           ; Jump not taken%@AE@%%@NL@%
  14216. %@NL@%
  14217. %@NL@%
  14218. %@2@%%@CR:SC15.2      @%%@AB@%15.2  Looping%@AE@%%@EH@%%@NL@%
  14219. %@NL@%
  14220. %@4@%  The 8086-family processors have several instructions specifically designed%@EH@%
  14221.   for creating loops of repeated instructions. In addition, you can create
  14222.   loops using conditional jumps.%@NL@%
  14223. %@NL@%
  14224. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  14225. %@NL@%
  14226. %@4@%  %@AB@%LOOP%@AE@% %@AI@%label%@AE@%%@EH@%%@NL@%
  14227.   %@AB@%LOOPE%@AE@% %@AI@%label%@AE@%%@NL@%
  14228.   %@AB@%LOOPZ %@AE@%%@AI@%label%@AE@%%@NL@%
  14229.   %@AB@%LOOPNE%@AE@% %@AI@%label%@AE@%%@NL@%
  14230.   %@AB@%LOOPNZ%@AE@% %@AI@%label%@AE@%%@NL@%
  14231.   %@AB@%JCXZ%@AE@% %@AI@%label%@AE@%%@NL@%
  14232. %@NL@%
  14233. %@4@%%@CR:IX15.41     @%%@CR:IX15.42     @%%@CR:IX15.43     @%%@CR:IX15.44     @%%@CR:IX15.45     @%%@CR:IX15.46     @%  The %@AB@%LOOP%@AE@% instruction is used for loops with a set number of iterations.%@EH@%
  14234.   For example, it can be used in constructions similar to the "for" loops of
  14235.   BASIC, C, and Pascal, and the "do" loops of FORTRAN.%@NL@%
  14236. %@NL@%
  14237. %@4@%  A single operand specifies the address to jump to each time through the%@EH@%
  14238.   loop. The CX register is used as a counter for the number of times to
  14239.   loop. On each iteration, CX is decremented. When CX reaches 0, control
  14240.   passes to the instruction after the loop.%@NL@%
  14241. %@NL@%
  14242. %@4@%%@CR:IX15.47     @%%@CR:IX15.48     @%%@CR:IX15.49     @%  The%@AB@% LOOPE%@AE@%, %@AB@%LOOPZ%@AE@%, %@AB@%LOOPNE%@AE@%, and %@AB@%LOOPNZ%@AE@% instructions are used in loops that%@EH@%
  14243.   check for a condition. For example, they can be used in constructions
  14244.   similar to the "while" loops of BASIC, C, and Pascal; the "repeat" loops
  14245.   of Pascal; and the "do" loops of C.%@NL@%
  14246. %@NL@%
  14247. %@4@%%@CR:IX15.50     @%%@CR:IX15.51     @%%@CR:IX15.52     @%%@CR:IX15.53     @%%@CR:IX15.54     @%%@CR:IX15.55     @%  The %@AB@%LOOPE%@AE@% (also called %@AB@%LOOPZ%@AE@%) instruction can be thought of as meaning%@EH@%
  14248.   "loop while equal." Similarly, the %@AB@%LOOPNE%@AE@% (also called %@AB@%LOOPNZ%@AE@%) instruction
  14249.   can be thought of as meaning "loop while not equal." A single short memory
  14250.   operand specifies the address to loop to each time through. The CX
  14251.   register can specify a maximum number of times to go through the loop. The
  14252.   CX register can be set to a number that is out of range if you do not want
  14253.   a maximum count.%@NL@%
  14254. %@NL@%
  14255. %@4@%%@CR:IX15.56     @%%@CR:IX15.57     @%  The %@AB@%JCXZ%@AE@% instruction is often used in loop structures. For example, it may%@EH@%
  14256.   be used in loops that check a condition at the start of the loop rather
  14257.   than at the end. Unlike the loop instruction, %@AB@%JCXZ%@AE@% does not decrement CX,
  14258.   so the programmer must use another statement to decrement the count. You
  14259.   can also use %@AB@%JCX2%@AE@% with string instructions, as described in Chapter 16%@BO:       d1833@%,
  14260.   "Processing Strings."%@NL@%
  14261. %@NL@%
  14262. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  14263. %@NL@%
  14264.   %@AS@%; For 0 to 200 do task%@AE@%%@NL@%
  14265. %@NL@%
  14266.   %@AS@%            mov     cx,200             ; Set counter%@AE@%%@NL@%
  14267.   %@AS@%next:       .                          ; Do the task here%@AE@%%@NL@%
  14268.   %@AS@%            .%@AE@%%@NL@%
  14269.   %@AS@%            .%@AE@%%@NL@%
  14270.   %@AS@%            loop    next               ; Do again%@AE@%%@NL@%
  14271.   %@AS@%                                       ; Continue after loop%@AE@%%@NL@%
  14272. %@NL@%
  14273. %@4@%  This loop has the same effect as the following statements:%@EH@%%@NL@%
  14274. %@NL@%
  14275.   %@AS@%; For 0 to 200, do task%@AE@%%@NL@%
  14276. %@NL@%
  14277.   %@AS@%            mov     cx,200             ; Set counter%@AE@%%@NL@%
  14278.   %@AS@%next:       .%@AE@%%@NL@%
  14279.   %@AS@%            .                          ; Do the task here%@AE@%%@NL@%
  14280.   %@AS@%            .%@AE@%%@NL@%
  14281.   %@AS@%            dec     cx%@AE@%%@NL@%
  14282.   %@AS@%            cmp     cx,0%@AE@%%@NL@%
  14283.   %@AS@%            jne     next               ; Do again%@AE@%%@NL@%
  14284.   %@AS@%                                       ; Continue after loop%@AE@%%@NL@%
  14285. %@NL@%
  14286. %@4@%  The first version is more efficient as well as easier to understand.%@EH@%
  14287.   However, there are situations in which you must use conditional-jump
  14288.   instructions rather than loop instructions. For example, conditional jumps
  14289.   are often required for loops that test several conditions.%@NL@%
  14290. %@NL@%
  14291. %@4@%  If the counter in CX is variable because of previous instructions, you%@EH@%
  14292.   should use the %@AB@%JCXZ%@AE@% instruction to check for 0, as shown in Example 2.
  14293.   Otherwise, if CX is 0, it will be decremented to -1 in the first iteration
  14294.   and will continue through 65,535 iterations before it reaches 0 again.%@NL@%
  14295. %@NL@%
  14296. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  14297. %@NL@%
  14298.   %@AS@%; For 0 to CX do task%@AE@%%@NL@%
  14299. %@NL@%
  14300.   %@AS@%                                       ; CX counter set previously%@AE@%%@NL@%
  14301.   %@AS@%            jcxz    done               ; Check for 0%@AE@%%@NL@%
  14302.   %@AS@%next:       .                          ; Do the task here%@AE@%%@NL@%
  14303.   %@AS@%            .%@AE@%%@NL@%
  14304.   %@AS@%            .%@AE@%%@NL@%
  14305.   %@AS@%            loop    next               ; Do again%@AE@%%@NL@%
  14306.   %@AS@%done:                                  ; Continue after loop%@AE@%%@NL@%
  14307. %@NL@%
  14308. %@NL@%
  14309. %@2@%%@CR:SC15.3      @%%@AB@%15.3  Using Procedures%@AE@%%@EH@%%@NL@%
  14310. %@NL@%
  14311. %@4@%%@CR:IX15.58     @%%@CR:IX15.59     @%  A "procedure" is a program subdivision that typically executes a specific%@EH@%
  14312.   task. Once you write a procedure, you can execute it from anywhere in the
  14313.   program. This technique lets you avoid writing the same block of code over
  14314.   and over, thus saving space.%@NL@%
  14315. %@NL@%
  14316. %@4@%  Even if you execute it only once, writing a procedure can be a useful way%@EH@%
  14317.   of dividing a large program into manageable units. You can place a
  14318.   procedure in its own source module and test it separately.
  14319.   Assembly-language procedures are comparable to functions in C;
  14320.   subprograms, functions, and subroutines in BASIC; procedures and functions
  14321.   in Pascal; or routines and functions in FORTRAN.%@NL@%
  14322. %@NL@%
  14323. %@4@%%@CR:IX15.60     @%  Two instructions control the use of assembly-language procedures. The %@AB@%CALL%@AE@%%@EH@%
  14324.   instruction can appear anywhere in a program. It temporarily transfers
  14325.   program control to a specified procedure. The %@AB@%RET%@AE@% instruction appears at
  14326.   the end of a procedure. It returns control back to the location that
  14327.   issued the call.%@NL@%
  14328. %@NL@%
  14329. %@4@%  These instructions use the stack to properly return from each call. The%@EH@%
  14330.   instruction immediately following the %@AB@%CALL%@AE@% instruction is called the
  14331.   "return address," and the procedure should return to this location when
  14332.   done. %@AB@%CALL%@AE@% pushes the return address onto the stack; %@AB@%RET%@AE@% pops this address
  14333.   off the stack and transfers program control there.%@NL@%
  14334. %@NL@%
  14335. %@4@%  Along with the%@AB@% RET%@AE@% instruction (which terminates a procedure), two%@EH@%
  14336.   directives help define a procedure. The %@AB@%PROC%@AE@% and %@AB@%ENDP%@AE@% directives normally
  14337.   mark the beginning and end of a procedure definition, as described in
  14338.   Section 15.3.2%@BO:       c4c26@%, "Defining Procedures."%@NL@%
  14339. %@NL@%
  14340. %@4@%  In addition, the %@AB@%PROC%@AE@% directive can save you time and effort by automating%@EH@%
  14341.   the following tasks:%@NL@%
  14342. %@NL@%
  14343.   ■  Preserving register values that should not change, but that the
  14344.      procedure might otherwise alter%@NL@%
  14345. %@NL@%
  14346.   ■  Setting up a framepointer, so that you can access parameters placed on
  14347.      the stack%@NL@%
  14348. %@NL@%
  14349.   ■  Creating text macros, so that your source code can refer to each
  14350.      parameter by a meaningful name%@NL@%
  14351. %@NL@%
  14352. %@4@%  Section 15.3.4%@BO:       c7284@%, "Declaring Parameters with the PROC Directive," describes%@EH@%
  14353.   how to use these features. Section 15.3.3%@BO:       c60b0@%, "Passing Arguments on the
  14354.   Stack," gives background information on the technique for accessing
  14355.   parameters.%@NL@%
  14356. %@NL@%
  14357. %@4@%  When you write procedures, you can create local variables, which exist%@EH@%
  14358.   only during execution of the procedure. The advantage of these variables
  14359.   is that they use memory dynamically, taking up space only in the procedure
  14360.   that uses them. Section 15.3.5%@BO:       c9deb@%, "Using Local Variables," describes the
  14361.   basic technique for allocating and accessing local variables. Section
  14362.   15.3.6%@BO:       cb138@%, "Creating Locals Automatically," describes how to make the
  14363.   assembler generate the necessary code for you.%@NL@%
  14364. %@NL@%
  14365. %@NL@%
  14366. %@3@%%@CR:SC15.3.1    @%%@AB@%15.3.1  Calling Procedures%@AE@%%@EH@%%@NL@%
  14367. %@NL@%
  14368. %@4@%%@CR:IX15.61     @%%@CR:IX15.62     @%  The %@AB@%CALL%@AE@% instruction saves the address following the instruction on the%@EH@%
  14369.   stack and passes control to a specified address.%@NL@%
  14370. %@NL@%
  14371. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  14372. %@NL@%
  14373. %@4@%  %@AB@%CALL%@AE@% {%@AI@%register%@AE@% | %@AI@%memory%@AE@%}%@EH@%%@NL@%
  14374. %@NL@%
  14375. %@4@%%@CR:IX15.63     @%  The address is usually specified as a direct memory operand. However, the%@EH@%
  14376.   operand can also be a register or indirect memory operand containing a
  14377.   value calculated at run time. This enables you to write call tables
  14378.   similar to the jump table illustrated in Section 15.1.2.1%@BO:       bf2c9@%, "Comparing and
  14379.   Jumping."%@NL@%
  14380. %@NL@%
  14381. %@4@%  Calls can be near or far. Near calls push only the offset portion of the%@EH@%
  14382.   calling address. Far calls push both the segment and offset. You must give
  14383.   the type of far calls to forward-referenced labels using the %@AB@%FAR%@AE@% type
  14384.   specifier and the %@AB@%PTR%@AE@% operator. For example, use the following statement
  14385.   to make a far call to a label that has not been earlier defined or
  14386.   declared external in the source code:%@NL@%
  14387. %@NL@%
  14388.   %@AS@%            call    FAR PTR task%@AE@%%@NL@%
  14389. %@NL@%
  14390. %@NL@%
  14391. %@3@%%@CR:SC15.3.2    @%%@AB@%15.3.2  Defining Procedures%@AE@%%@EH@%%@NL@%
  14392. %@NL@%
  14393. %@4@%  Procedures are defined by labeling the start of the procedure and placing%@EH@%
  14394.   an %@AB@%ENDP%@AE@% directive at the end. The code should not fall through past the
  14395.   end of the procedure. Exit the procedure with a%@AB@% RET%@AE@%,%@AB@% RETF%@AE@%, %@AB@%RETN%@AE@%, or %@AB@%IRET%@AE@%
  14396.   instruction. There are several variations of this syntax.%@NL@%
  14397. %@NL@%
  14398. %@4@%  %@AB@%Syntax 1%@AE@%%@EH@%%@NL@%
  14399. %@NL@%
  14400. %@4@%  %@AI@%label%@AE@% %@AB@%PROC%@AE@% [[%@AB@%NEAR%@AE@%|%@AB@%FAR%@AE@%]]%@AB@% RET%@AE@% [[%@AI@%constant%@AE@%]] %@AI@%label%@AE@% %@AB@%ENDP%@AE@%%@EH@%%@NL@%
  14401. %@NL@%
  14402. %@4@%%@CR:IX15.64     @%%@CR:IX15.65     @%%@CR:IX15.66     @%  Procedures are normally defined by using the %@AB@%PROC%@AE@% directive at the start%@EH@%
  14403.   of the procedure and the %@AB@%ENDP%@AE@% directive at the end. The %@AB@%RET%@AE@% instruction is
  14404.   normally placed immediately before the %@AB@%ENDP%@AE@% directive. The size of the %@AB@%RET%@AE@%
  14405.   instruction automatically matches the size defined by the %@AB@%PROC%@AE@% directive.%@NL@%
  14406. %@NL@%
  14407. %@4@%  The syntax shown is always available. In addition, there is an extended%@EH@%
  14408.   %@AB@%PROC%@AE@% syntax available if you use %@AB@%.MODEL%@AE@% and specify a language. The
  14409.   extended %@AB@%PROC%@AE@% syntax is explained in Section 15.3.4%@BO:       c7284@%, "Declaring
  14410.   Parameters with the PROC Directive." These language features automate many
  14411.   of the details of accessing parameters and saving registers.%@NL@%
  14412. %@NL@%
  14413. %@4@%  %@AB@%Syntax 2%@AE@%%@EH@%%@NL@%
  14414. %@NL@%
  14415. %@4@%  %@AI@%label%@AE@%%@AB@%:%@AE@%%@EH@%%@NL@%
  14416.   %@AI@%statements%@AE@%%@NL@%
  14417.   %@AB@%RETN%@AE@% [[%@AI@%constant%@AE@%]]%@NL@%
  14418. %@NL@%
  14419. %@4@%  %@AB@%Syntax 3%@AE@%%@EH@%%@NL@%
  14420. %@NL@%
  14421. %@4@%  %@AI@%label%@AE@% %@AB@%LABEL FAR%@AE@%%@EH@%%@NL@%
  14422.   %@AI@%statements%@AE@%%@NL@%
  14423.   %@AB@%RETF%@AE@% [[%@AI@%constant%@AE@%]]%@NL@%
  14424. %@NL@%
  14425. %@4@%%@CR:IX15.67     @%%@CR:IX15.68     @%%@CR:IX15.69     @%%@CR:IX15.70     @%  The %@AB@%RET%@AE@% instruction can be extended to %@AB@%RETN%@AE@% (Return Near) or %@AB@%RETF%@AE@% (Return%@EH@%
  14426.   Far) to override the default size. This enables you to define and use
  14427.   procedures without the %@AB@%PROC%@AE@% and %@AB@%ENDP%@AE@% directives, as shown in Syntax 2 and
  14428.   Syntax 3, above. However, with this method, the programmer is responsible
  14429.   for making sure the size of the %@AB@%CALL%@AE@% matches the size of the %@AB@%RET%@AE@%.%@NL@%
  14430. %@NL@%
  14431. %@4@%  The %@AB@%RET%@AE@% instruction (and its %@AB@%RETF%@AE@% and %@AB@%RETN%@AE@% variations) allows a constant%@EH@%
  14432.   operand that specifies a number of bytes to be added to the value of the
  14433.   SP register after the return. This operand can be used to adjust for
  14434.   arguments passed to the procedure before the call, as shown in the example
  14435.   in Section 15.3.5%@BO:       c9deb@%, "Using Local Variables."%@NL@%
  14436. %@NL@%
  14437. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  14438. %@NL@%
  14439.   %@AS@%            call    task          ; Call is near because procedure is near%@AE@%%@NL@%
  14440.   %@AS@%            .                     ; Return comes to here%@AE@%%@NL@%
  14441.   %@AS@%            .%@AE@%%@NL@%
  14442.   %@AS@%            .%@AE@%%@NL@%
  14443.   %@AS@%task        PROC    NEAR          ; Define "task" to be near%@AE@%%@NL@%
  14444.   %@AS@%            .%@AE@%%@NL@%
  14445.   %@AS@%            .                     ; Instructions of "task" go here%@AE@%%@NL@%
  14446.   %@AS@%            .%@AE@%%@NL@%
  14447.   %@AS@%            ret                   ; Return to instruction after call%@AE@%%@NL@%
  14448.   %@AS@%task        ENDP                  ; End "task" definition%@AE@%%@NL@%
  14449. %@NL@%
  14450. %@4@%  Example 1 shows the recommended way of making calls with QuickAssembler.%@EH@%
  14451.   Example 2 shows another method that programmers who are used to other
  14452.   assemblers may find more familiar.%@NL@%
  14453. %@NL@%
  14454. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  14455. %@NL@%
  14456.   %@AS@%            call    NEAR PTR task ; Call is declared near%@AE@%%@NL@%
  14457.   %@AS@%            .                     ; Return comes to here%@AE@%%@NL@%
  14458.   %@AS@%            .%@AE@%%@NL@%
  14459.   %@AS@%            .%@AE@%%@NL@%
  14460.   %@AS@%task:                             ; Procedure begins with near label%@AE@%%@NL@%
  14461.   %@AS@%            .%@AE@%%@NL@%
  14462.   %@AS@%            .                     ; Instructions go here%@AE@%%@NL@%
  14463.   %@AS@%            .%@AE@%%@NL@%
  14464.   %@AS@%            retn                  ; Return declared near%@AE@%%@NL@%
  14465. %@NL@%
  14466. %@4@%  This method gives more direct control over procedures, but the programmer%@EH@%
  14467.   must make sure that calls have the same size as corresponding returns.%@NL@%
  14468. %@NL@%
  14469. %@4@%  For example, if a call is made with the statement%@EH@%%@NL@%
  14470. %@NL@%
  14471.   %@AS@%            call    NEAR PTR task%@AE@%%@NL@%
  14472. %@NL@%
  14473. %@4@%  the assembler does a near call. This means that one word (the offset%@EH@%
  14474.   following the calling address) is pushed onto the stack. If the return is
  14475.   made with the statement%@NL@%
  14476. %@NL@%
  14477.   %@AS@%            retf%@AE@%%@NL@%
  14478. %@NL@%
  14479. %@4@%  two words are popped off the stack. The first will be the offset, but the%@EH@%
  14480.   second will be whatever happened to be on the stack before the call. Not
  14481.   only will the popped value be meaningless, but the stack status will be
  14482.   incorrect, causing the program to fail.%@NL@%
  14483. %@NL@%
  14484. %@NL@%
  14485. %@3@%%@CR:SC15.3.3    @%%@AB@%15.3.3  Passing Arguments on the Stack%@AE@%%@EH@%%@NL@%
  14486. %@NL@%
  14487. %@4@%%@CR:IX15.71     @%%@CR:IX15.72     @%  Procedure arguments can be passed in various ways. For example, values can%@EH@%
  14488.   be passed to a procedure in registers or in variables. However, the most
  14489.   common method of passing arguments is to use the stack. Microsoft
  14490.   languages have a specific convention for doing this.%@NL@%
  14491. %@NL@%
  14492. %@4@%  This section describes how a procedure accesses the parameters passed to%@EH@%
  14493.   it on the stack. Each parameter is accessed as an offset from BP, and you
  14494.   must calculate this offset. However, if you use the %@AB@%PROC%@AE@% directive to
  14495.   declare parameters, the assembler calculates these offsets for you and
  14496.   lets you refer to parameters by name. The next section explains how to use
  14497.   %@AB@%PROC%@AE@% this way.%@NL@%
  14498. %@NL@%
  14499. %@4@%  The arguments are pushed onto the stack before the call. After the call,%@EH@%
  14500.   the procedure retrieves and processes them. At the end of the procedure,
  14501.   the stack is adjusted to account for the arguments.%@NL@%
  14502. %@NL@%
  14503. %@4@%%@CR:IX15.73     @%  Although the same basic method is used for all Microsoft high-level%@EH@%
  14504.   languages, the details vary. For instance, in some languages, pointers to
  14505.   the arguments are passed to the procedure; in others, the arguments
  14506.   themselves are passed. The order in which arguments are passed (whether
  14507.   the first argument is pushed first or last) also varies according to the
  14508.   language. Finally, in some languages, the stack is adjusted by the %@AB@%RET%@AE@%
  14509.   instruction in the called procedure; in others, the code immediately
  14510.   following the %@AB@%CALL%@AE@% instruction adjusts the stack. See Appendix A%@BO:       ed697@%,
  14511.   "Mixed-Language Mechanics," for details on calling conventions.%@NL@%
  14512. %@NL@%
  14513. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  14514. %@NL@%
  14515.   %@AS@%; C-style procedure call and definition%@AE@%%@NL@%
  14516. %@NL@%
  14517.   %@AS@%            mov     ax,10      ; Load and%@AE@%%@NL@%
  14518.   %@AS@%            push    ax         ;   push constant as third argument%@AE@%%@NL@%
  14519.   %@AS@%            push    arg2       ; Push memory as second argument%@AE@%%@NL@%
  14520.   %@AS@%            push    cx         ; Push register as first argument%@AE@%%@NL@%
  14521.   %@AS@%            call    addup      ; Call the procedure%@AE@%%@NL@%
  14522.   %@AS@%            add     sp,6       ; Destroy the pushed arguments%@AE@%%@NL@%
  14523.   %@AS@%            .                  ;   (equivalent to three pops)%@AE@%%@NL@%
  14524.   %@AS@%            .%@AE@%%@NL@%
  14525.   %@AS@%            .%@AE@%%@NL@%
  14526.   %@AS@%addup       PROC    NEAR       ; Return address for near call%@AE@%%@NL@%
  14527.   %@AS@%                               ;   takes two bytes%@AE@%%@NL@%
  14528.   %@AS@%            push    bp         ; Save base pointer - takes two bytes%@AE@%%@NL@%
  14529.   %@AS@%                               ;   so arguments start at 4th byte%@AE@%%@NL@%
  14530.   %@AS@%            mov     bp,sp      ; Load stack into base pointer%@AE@%%@NL@%
  14531.   %@AS@%            mov     ax,[bp+4]  ; Get first argument from%@AE@%%@NL@%
  14532.   %@AS@%                               ;   4th byte above pointer%@AE@%%@NL@%
  14533.   %@AS@%            add     ax,[bp+6]  ; Add second argument from%@AE@%%@NL@%
  14534.   %@AS@%                               ;   6th byte above pointer%@AE@%%@NL@%
  14535.   %@AS@%            add     ax,[bp+8]  ; Add third argument from%@AE@%%@NL@%
  14536.   %@AS@%                               ;   8th byte above pointer%@AE@%%@NL@%
  14537.   %@AS@%            pop     bp         ; Restore BP%@AE@%%@NL@%
  14538.   %@AS@%            ret                ; Return result in AX%@AE@%%@NL@%
  14539.   %@AS@%addup       ENDP%@AE@%%@NL@%
  14540. %@NL@%
  14541. %@4@%%@CR:IX15.74     @%%@CR:IX15.75     @%  The example shows one method of passing arguments to a procedure. This%@EH@%
  14542.   method is similar to the way procedures are called in the C language.
  14543.   Figure 15.1 shows the stack condition at key points in the process.%@NL@%
  14544. %@NL@%
  14545.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  14546.   │ This figure can be found in Section 15.3.3 of the manual               │%@NL@%
  14547.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  14548. %@NL@%
  14549.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14550.   %@AB@%NOTE%@AE@%  Arguments passed on the stack in assembler routines cannot be
  14551.   accessed by name in debugging commands, unless you declare parameters with
  14552.   the %@AB@%PROC%@AE@% directive, as explained in the next section.%@NL@%
  14553.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14554. %@NL@%
  14555. %@NL@%
  14556. %@3@%%@CR:SC15.3.4    @%%@AB@%15.3.4  Declaring Parameters with the PROC Directive%@AE@%%@EH@%%@NL@%
  14557. %@NL@%
  14558. %@4@%  This section describes how to use the%@AB@% PROC%@AE@% directive in order to automate%@EH@%
  14559.   the parameter-accessing techniques described in the last section.%@NL@%
  14560. %@NL@%
  14561. %@4@%  The %@AB@%PROC%@AE@% directive lets you specify registers to be saved, define%@EH@%
  14562.   arguments to the procedure, and set up text macros so that you can refer
  14563.   to parameters by name (rather than as an offset to BP). For example, the
  14564.   following %@AB@%PROC%@AE@% directive could be placed at the beginning of a procedure
  14565.   called from BASIC that takes a single argument passed by value and that
  14566.   uses (and must save) the DI and SI registers:%@NL@%
  14567. %@NL@%
  14568.   %@AS@%myproc      PROC  FAR BASIC USES DI SI, arg1:WORD%@AE@%%@NL@%
  14569. %@NL@%
  14570. %@4@%  Note that you must use the %@AB@%.MODEL%@AE@% directive and specify a language in%@EH@%
  14571.   order to use the extended features of %@AB@%PROC%@AE@%, including the %@AI@%lang%@AE@% type,
  14572.   %@AI@%reglist%@AE@%, and %@AI@%arguments%@AE@%.%@NL@%
  14573. %@NL@%
  14574. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  14575. %@NL@%
  14576. %@4@%  %@AI@%label%@AE@% %@AB@%PROC%@AE@% [[%@AB@%NEAR%@AE@%|%@AB@%FAR%@AE@%]] [[%@AI@%lang%@AE@%]] [[%@AB@%USES %@AE@%%@AI@%reglist%@AE@%]] [[%@AI@%arguments%@AE@%]]%@EH@%%@NL@%
  14577. %@NL@%
  14578. %@4@%  The%@AB@% NEAR %@AE@%and %@AB@%FAR%@AE@% keywords indicate whether you invoke the procedure with a%@EH@%
  14579.   near call or a far call, as described in Section 15.3.2%@BO:       c4c26@%, "Defining
  14580.   Procedures."%@NL@%
  14581. %@NL@%
  14582. %@4@%  The following list describes the other parts of the %@AB@%PROC%@AE@% directive:%@EH@%%@NL@%
  14583. %@NL@%
  14584.   %@AB@%Argument%@AE@%            %@AB@%Description%@AE@%%@NL@%
  14585.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14586.   %@AI@%label%@AE@%               The name of the procedure. The assembler automatically
  14587.                       adds an underscore to the beginning of the name if you
  14588.                       specify %@AB@%C%@AE@% as the language in the %@AB@%.MODEL%@AE@% directive or
  14589.                       if you specify%@AB@% C %@AE@%as the %@AI@%lang%@AE@%.%@NL@%
  14590. %@NL@%
  14591. %@CR:IX15.76     @%%@CR:IX15.77     @%%@CR:IX15.78     @%  %@AI@%lang%@AE@%                An optional language specifier that overrides language
  14592.                       conventions specified by the %@AB@%.MODEL%@AE@% directive. The
  14593.                       language type may be %@AB@%C%@AE@%, %@AB@%Pascal%@AE@%, %@AB@%FORTRAN%@AE@%, or %@AB@%BASIC%@AE@%.%@NL@%
  14594. %@NL@%
  14595.                       The language type determines the calling convention
  14596.                       used to access parameters and restore the stack. It
  14597.                       also determines whether an underscore is prefixed to
  14598.                       the procedure name, as required by the C naming
  14599.                       convention. Note that use of the %@AB@%C%@AE@% specifier does not
  14600.                       preserve lowercase letters in the procedure name. To
  14601.                       guarantee compatibility with C naming conventions,
  14602.                       choose Preserve Case or Preserve Extrn from the
  14603.                       Assembler Flags dialog box, or assemble with /Cl or
  14604.                       /Cx from the QCL command line.%@NL@%
  14605. %@NL@%
  14606. %@CR:IX15.79     @%  %@AI@%reglist%@AE@%             A list of registers that the procedure uses and that
  14607.                       should be saved on entry. Registers in the list must
  14608.                       be separated by blanks or tabs. The assembler
  14609.                       generates code to push these registers on the stack.
  14610.                       When you exit, the assembler generates code to pop the
  14611.                       saved register values off the stack.%@NL@%
  14612. %@NL@%
  14613.   %@AI@%arguments%@AE@%           The list of arguments passed to the procedure on the
  14614.                       stack. See the discussion below for the syntax of the
  14615.                       %@AI@%argument%@AE@%.%@NL@%
  14616. %@NL@%
  14617. %@NL@%
  14618. %@4@%  The %@AI@%arguments%@AE@% indicate each of the procedure's arguments and are separated%@EH@%
  14619.   from the %@AI@%reglist%@AE@% argument by a comma if there is a list of registers. Each
  14620.   %@AI@%argument%@AE@% has the following syntax:%@NL@%
  14621. %@NL@%
  14622. %@4@%  %@AI@%argname%@AE@% [[%@AB@% :%@AE@%[[[[%@AB@%NEAR%@AE@%|%@AB@%FAR%@AE@%]]%@AB@%PTR%@AE@%]]%@AI@%type%@AE@%]]%@EH@%%@NL@%
  14623. %@NL@%
  14624. %@4@%%@CR:IX15.80     @%  If you have more than one argument, separate each by a comma.%@EH@%%@NL@%
  14625. %@NL@%
  14626. %@4@%  The %@AI@%argname%@AE@% is the name of the argument. The %@AI@%type%@AE@% is the type of the%@EH@%
  14627.   argument and may be %@AB@%WORD%@AE@%, %@AB@%DWORD%@AE@%,%@AB@% QWORD%@AE@%,%@AB@% TBYTE%@AE@%, or the name of a structure
  14628.   defined by a %@AB@%STRUC%@AE@% structure declaration (see Chapter 6%@BO:       5749b@%, "Defining
  14629.   Labels, Constants, and Variables" for more information about types). If
  14630.   you omit %@AI@%type%@AE@%, the default is the%@AB@% WORD %@AE@%type.%@NL@%
  14631. %@NL@%
  14632. %@4@%  The%@AB@% FAR%@AE@%,%@AB@% NEAR%@AE@%, %@AB@%PTR%@AE@%, and %@AI@%type%@AE@% arguments are all optional. If you omit all%@EH@%
  14633.   of them, the assembler assumes the variable is a %@AB@%WORD%@AE@% type. If you use
  14634.   only the %@AI@%type%@AE@% argument, the assembler assumes the variable has the
  14635.   indicated type.%@NL@%
  14636. %@NL@%
  14637.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14638.   %@AB@%Note%@AE@%  If you are writing a routine to be called from BASIC, FORTRAN, or
  14639.   Pascal, and the routine returns a function value, you must declare an
  14640.   additional parameter if you return anything other than a two- or four-byte
  14641.   integer. See Appendix A%@BO:       ed697@%, "Mixed-Language Mechanics," for more
  14642.   information.%@NL@%
  14643.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14644. %@NL@%
  14645. %@4@%%@CR:IX15.81     @%%@CR:IX15.82     @%  The %@AB@%PTR%@AE@% type generates debugging information so that the variable is%@EH@%
  14646.   treated as a pointer during debugging. The assembler assumes specific
  14647.   sizes for the variable, depending on the combination of %@AB@%NEAR%@AE@%, %@AB@%FAR%@AE@%, and %@AB@%PTR%@AE@%
  14648.   arguments you specify. The lines below show some example combinations of
  14649.   %@AB@%NEAR%@AE@%,%@AB@% FAR%@AE@%, %@AB@%PTR%@AE@%, and %@AI@%type%@AE@%:%@NL@%
  14650. %@NL@%
  14651.   %@AS@%myproc      PROC var1:PTR WORD, var2:PTR DWORD%@AE@%%@NL@%
  14652.   %@AS@%            .%@AE@%%@NL@%
  14653.   %@AS@%            .%@AE@%%@NL@%
  14654.   %@AS@%            .%@AE@%%@NL@%
  14655.   %@AS@%myproc      ENDP%@AE@%%@NL@%
  14656. %@NL@%
  14657.   %@AS@%proc2       PROC var3:FAR PTR WORD, var4:NEAR PTR BYTE%@AE@%%@NL@%
  14658.   %@AS@%            .%@AE@%%@NL@%
  14659.   %@AS@%            .%@AE@%%@NL@%
  14660.   %@AS@%            .%@AE@%%@NL@%
  14661.   %@AS@%proc2       ENDP%@AE@%%@NL@%
  14662. %@NL@%
  14663. %@4@%  If you omit %@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@%, the default data size established by .%@AB@%MODEL%@AE@% is%@EH@%
  14664.   used. All %@AB@%PTR%@AE@% declarations are translated into a word-size variable if the
  14665.   data size is near or a doubleword variable if the data size is far.%@NL@%
  14666. %@NL@%
  14667. %@4@%  For example, the following declarations of %@AS@%procvar %@AE@%produce the same code%@EH@%
  14668.   for the variable name, although they generate different debugging
  14669.   information:%@NL@%
  14670. %@NL@%
  14671.   %@AS@%aproc       PROC procvar:PTR WORD%@AE@%%@NL@%
  14672. %@NL@%
  14673.   %@AS@%aproc       PROC procvar:PTR DWORD%@AE@%%@NL@%
  14674. %@NL@%
  14675.   %@AS@%aproc       PROC procvar:PTR BYTE%@AE@%%@NL@%
  14676. %@NL@%
  14677. %@4@%  Specifying a particular type changes only the debugging information, not%@EH@%
  14678.   the code produced for accessing the argument.%@NL@%
  14679. %@NL@%
  14680. %@4@%  If you specify a%@AB@% NEAR PTR%@AE@% or %@AB@%FAR PTR%@AE@% argument, as in the declarations of%@EH@%
  14681.   %@AS@%var3 %@AE@%and %@AS@%var4%@AE@%, the assembler ignores the memory model you selected and
  14682.   assigns a %@AB@%WORD%@AE@% type for a%@AB@% NEAR PTR%@AE@% argument and a %@AB@%DWORD%@AE@% type for a %@AB@%FAR PTR%@AE@%
  14683.   argument.%@NL@%
  14684. %@NL@%
  14685. %@4@%  The assembler does not generate any code to get the value or values the%@EH@%
  14686.   pointer references; your program must still explicitly treat the argument
  14687.   as a pointer. For example, the procedure in Section 5.1%@BO:       406ed@% can be rewritten
  14688.   for use with BASIC so that it gets its argument by near reference (the
  14689.   BASIC default):%@NL@%
  14690. %@NL@%
  14691.   %@AS@%; Call from BASIC as a FUNCTION returning an integer%@AE@%%@NL@%
  14692. %@NL@%
  14693.   %@AS@%            .MODEL medium, basic%@AE@%%@NL@%
  14694.   %@AS@%            .CODE%@AE@%%@NL@%
  14695.   %@AS@%myadd       PROC   arg1:NEAR PTR WORD, arg2:NEAR PTR WORD%@AE@%%@NL@%
  14696. %@NL@%
  14697.   %@AS@%            mov    bx,arg1  ; Load first argument%@AE@%%@NL@%
  14698.   %@AS@%            mov    ax,[bx]%@AE@%%@NL@%
  14699.   %@AS@%            mov    bx,arg2  ; Add second argument%@AE@%%@NL@%
  14700.   %@AS@%            add    ax,[bx]%@AE@%%@NL@%
  14701. %@NL@%
  14702.   %@AS@%            ret%@AE@%%@NL@%
  14703. %@NL@%
  14704.   %@AS@%myadd       ENDP%@AE@%%@NL@%
  14705.   %@AS@%            END%@AE@%%@NL@%
  14706. %@NL@%
  14707. %@4@%  In the example above, even though the arguments are declared as near%@EH@%
  14708.   pointers, you still must code two move instructions in order to get the
  14709.   values of the arguments──the first move gets the address of the argument;
  14710.   the second move gets the argument.%@NL@%
  14711. %@NL@%
  14712. %@4@%  You can use conditional-assembly directives to make sure that your pointer%@EH@%
  14713.   arguments are loaded correctly for the memory model. For example, the
  14714.   following version of %@AS@%myadd %@AE@%treats the arguments as far arguments if
  14715.   necessary:%@NL@%
  14716. %@NL@%
  14717.   %@AS@%            .MODEL   medium,c                        ;Could be any model%@AE@%%@NL@%
  14718.   %@AS@%            .CODE%@AE@%%@NL@%
  14719.   %@AS@%myadd       PROC     arg1:PTR WORD,   arf2:PTR WORD%@AE@%%@NL@%
  14720. %@NL@%
  14721.   %@AS@%            IF       @DataSize%@AE@%%@NL@%
  14722.   %@AS@%                     les     bx,arg1                 ;Far arguments%@AE@%%@NL@%
  14723.   %@AS@%                     mov     ax,es:[bx]%@AE@%%@NL@%
  14724.   %@AS@%                     les     bx,arg2%@AE@%%@NL@%
  14725.   %@AS@%                     add     ax,es:[bx]%@AE@%%@NL@%
  14726.   %@AS@%            ELSE%@AE@%%@NL@%
  14727.   %@AS@%                     mov     bx,arg1                 ;Near arguments%@AE@%%@NL@%
  14728.   %@AS@%                     mov     ax,[bx]%@AE@%%@NL@%
  14729.   %@AS@%                     mov     bx,arg2%@AE@%%@NL@%
  14730.   %@AS@%                     add     ax,[bx]%@AE@%%@NL@%
  14731.   %@AS@%            ENDIF%@AE@%%@NL@%
  14732. %@NL@%
  14733.   %@AS@%            ret%@AE@%%@NL@%
  14734.   %@AS@%myadd       ENDP%@AE@%%@NL@%
  14735. %@NL@%
  14736.   %@AS@%            END%@AE@%%@NL@%
  14737. %@NL@%
  14738.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14739.   %@AB@%Note%@AE@%  When you use the high-level-language features and the assembler
  14740.   encounters a %@AB@%RET %@AE@%instruction, it automatically generates instructions to
  14741.   pop saved registers, remove local variables from the stack, and, if
  14742.   necessary, remove arguments. The assembler does not generate this code if
  14743.   you use a %@AB@%RETF%@AE@% or %@AB@%RETN%@AE@% instruction. It generates this code for each %@AB@%RET%@AE@%
  14744.   instruction it encounters. You can save code by having only one exit and
  14745.   jumping to it from various points.%@NL@%
  14746.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14747. %@NL@%
  14748. %@NL@%
  14749. %@3@%%@CR:SC15.3.5    @%%@AB@%15.3.5  Using Local Variables%@AE@%%@EH@%%@NL@%
  14750. %@NL@%
  14751. %@4@%%@CR:IX15.83     @%%@CR:IX15.84     @%  In high-level languages, local variables are known only within a%@EH@%
  14752.   procedure. In Microsoft languages, these variables are usually stored on
  14753.   the stack. Assembly-language programs can use the same technique. These
  14754.   variables should not be confused with labels or variable names that are
  14755.   local to a module, as described in Chapter 8%@BO:       70f6e@%, "Creating Programs from
  14756.   Multiple Modules."%@NL@%
  14757. %@NL@%
  14758.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14759.   %@AB@%NOTE%@AE@%  If your procedure has relatively few variables, you can usually
  14760.   write the most efficient code by placing these values in registers. Local
  14761.   (stack) data is efficient when you have a large amount of local data for
  14762.   the procedure.%@NL@%
  14763.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14764. %@NL@%
  14765. %@4@%  This section outlines the standard methods for creating local variables.%@EH@%
  14766.   The next section shows how to use the %@AB@%LOCAL%@AE@% directive to make the
  14767.   assembler generate local variables for you automatically. When you use
  14768.   this directive, the assembler generates the same instructions as those
  14769.   used in this section, but hides some of the details from you.%@NL@%
  14770. %@NL@%
  14771. %@4@%  If you want to use%@AB@% LOCAL%@AE@% right away, you may want to skip directly to the%@EH@%
  14772.   next section. However, this section gives useful background.%@NL@%
  14773. %@NL@%
  14774. %@4@%  Local variables are created by saving stack space for the variable at the%@EH@%
  14775.   start of the procedure. The variable can then be accessed by its position
  14776.   in the stack. At the end of the procedure, the stack pointer is restored
  14777.   to restore the memory used by local variables.%@NL@%
  14778. %@NL@%
  14779. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  14780. %@NL@%
  14781.   %@AS@%            push    ax         ; Push one argument%@AE@%%@NL@%
  14782.   %@AS@%            call    task       ; Call%@AE@%%@NL@%
  14783.   %@AS@%            .%@AE@%%@NL@%
  14784.   %@AS@%            .%@AE@%%@NL@%
  14785.   %@AS@%            .%@AE@%%@NL@%
  14786.   %@AS@%arg         EQU     <[bp+4]>   ; Name for argument%@AE@%%@NL@%
  14787.   %@AS@%loc         EQU     <[bp-2]>   ; Name for local variable%@AE@%%@NL@%
  14788. %@NL@%
  14789.   %@AS@%task        PROC    NEAR%@AE@%%@NL@%
  14790.   %@AS@%            push    bp         ; Save base pointer%@AE@%%@NL@%
  14791.   %@AS@%            mov     bp,sp      ; Load stack into base pointer%@AE@%%@NL@%
  14792.   %@AS@%            sub     sp,2       ; Save two bytes for local variable%@AE@%%@NL@%
  14793.   %@AS@%            .%@AE@%%@NL@%
  14794.   %@AS@%            .%@AE@%%@NL@%
  14795.   %@AS@%            .%@AE@%%@NL@%
  14796.   %@AS@%            mov     loc,3      ; Initialize local variable%@AE@%%@NL@%
  14797.   %@AS@%            add     ax,loc     ; Add local variable to AX%@AE@%%@NL@%
  14798.   %@AS@%            sub     arg,ax     ; Subtract local from argument%@AE@%%@NL@%
  14799.   %@AS@%            .                  ; Use "loc" and "arg" in other operations%@AE@%%@NL@%
  14800.   %@AS@%            .%@AE@%%@NL@%
  14801.   %@AS@%            .%@AE@%%@NL@%
  14802.   %@AS@%            mov     sp,bp      ; Adjust for stack variable%@AE@%%@NL@%
  14803.   %@AS@%            pop     bp         ; Restore base%@AE@%%@NL@%
  14804.   %@AS@%            ret     2          ; Return result in AX and pop%@AE@%%@NL@%
  14805.   %@AS@%task        ENDP               ;   two bytes to adjust stack%@AE@%%@NL@%
  14806. %@CR:IX15.85     @%%@CR:IX15.86     @%%@NL@%
  14807. %@4@%  In this example, two bytes are subtracted from the SP register to make%@EH@%
  14808.   room for a local word variable. This variable can then be accessed as
  14809.   %@AS@%[bp-2]%@AE@%. In the example, this value is given the name %@AS@%loc%@AE@% with a text
  14810.   equate. Notice that the instruction %@AS@%mov sp,bp%@AE@% is given at the end to
  14811.   restore the original value of SP. The statement is only required if the
  14812.   value of SP is changed inside the procedure (usually by allocating local
  14813.  variables). The argument passed to the procedure is returned with the
  14814.  %@AB@%RET%@AE@% instruction. Contrast this to the example in Section 15.3.3%@BO:       c60b0@%, 
  14815. "Passing Arguments on the Stack," in which the calling code adjusts for
  14816.  the argument. Figure 15.2 shows the state of the stack at key points in
  14817.  the process.%@NL@%
  14818. %@NL@%
  14819.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  14820.   │ This figure can be found in Section 15.3.5 of the manual               │%@NL@%
  14821.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  14822. %@NL@%
  14823.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14824. %@CR:IX15.87     @%  %@AB@%NOTE%@AE@%  Local variables created in assembler routines cannot be accessed by
  14825.   name with debugging commands, unless you declare local variables with the
  14826.   %@AB@%LOCAL%@AE@% directive, as explained in the next section.%@NL@%
  14827.   %@AB@%──────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14828. %@NL@%
  14829. %@NL@%
  14830. %@3@%%@CR:SC15.3.6    @%%@AB@%15.3.6  Creating Locals Automatically%@AE@%%@EH@%%@NL@%
  14831. %@NL@%
  14832. %@4@%  This section describes how to automate the techniques for local-variable%@EH@%
  14833.   creation described in the last section.%@NL@%
  14834. %@NL@%
  14835. %@4@%%@CR:IX15.88     @%%@CR:IX15.89     @%  You can use the %@AB@%LOCAL%@AE@% directive to save time and effort when working with%@EH@%
  14836.   local variables. When you use this directive, simply list the variables
  14837.   you want to create, giving a type for each one. The assembler calculates
  14838.   how much space is required on the stack. It also generates instructions to
  14839.   properly decrement SP (as described in the previous section) and to later
  14840.   reset SP when you return from the procedure.%@NL@%
  14841. %@NL@%
  14842. %@4@%  The %@AB@%LOCAL%@AE@% directive can only be used inside procedures created with the%@EH@%
  14843.   extended %@AB@%PROC%@AE@% directive. This means that you must first use %@AB@%.MODEL%@AE@% and
  14844.   specify a language.%@NL@%
  14845. %@NL@%
  14846. %@4@%  When you create local variables this way, your source code can then refer%@EH@%
  14847.   to each local variable by name rather than as an offset. Moreover, the
  14848.   assembler generates debugging information for each local variable, so that
  14849.   you can enter the name of the local variable as part of a Watch
  14850.   expression.%@NL@%
  14851. %@NL@%
  14852. %@4@%  The procedure in Section 15.3.5%@BO:       c9deb@% can be generated more simply with the%@EH@%
  14853.   following code:%@NL@%
  14854. %@NL@%
  14855.   %@AS@%task        PROC        NEAR     arg:WORD%@AE@%%@NL@%
  14856.   %@AS@%            LOCAL       loc:WORD%@AE@%%@NL@%
  14857.   %@AS@%            .%@AE@%%@NL@%
  14858.   %@AS@%            .%@AE@%%@NL@%
  14859.   %@AS@%            .%@AE@%%@NL@%
  14860.   %@AS@%            mov         loc,3         ; Initialize local variable%@AE@%%@NL@%
  14861.   %@AS@%            add         ax,loc        ; Add local variable to AX%@AE@%%@NL@%
  14862.   %@AS@%            sub         arg,ax        ; Subtract local from argument%@AE@%%@NL@%
  14863.   %@AS@%            .                         ; Use "Loc" and "arg" in other operations%@AE@%%@NL@%
  14864.   %@AS@%            .%@AE@%%@NL@%
  14865.   %@AS@%            .%@AE@%%@NL@%
  14866.   %@AS@%            ret%@AE@%%@NL@%
  14867.   %@AS@%task        ENDP%@AE@%%@NL@%
  14868. %@NL@%
  14869. %@4@%  The %@AB@%LOCAL%@AE@% directive has the following syntax:%@EH@%%@NL@%
  14870. %@NL@%
  14871. %@4@%  %@AB@%LOCAL %@AE@%%@AI@%vardef%@AE@%%@AB@% %@AE@%[[%@AB@%,%@AE@%%@AI@%vardef%@AE@%]]...%@EH@%%@NL@%
  14872. %@NL@%
  14873. %@4@%  Each %@AI@%vardef%@AE@% has the form:%@EH@%%@NL@%
  14874. %@NL@%
  14875. %@4@%  %@AI@%label%@AE@%[[[%@AI@%count%@AE@%]]][[%@AB@%:%@AE@%[[[[%@AB@%NEAR %@AE@%| %@AB@%FAR]]PTR%@AE@%]]%@AI@%type%@AE@%]]]]...%@EH@%%@NL@%
  14876. %@NL@%
  14877. %@4@%  The %@AB@%LOCAL%@AE@% directive arguments are as follows:%@EH@%%@NL@%
  14878. %@NL@%
  14879.   %@AB@%Argument%@AE@%            %@AB@%Description%@AE@%%@NL@%
  14880.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  14881.   %@AI@%label%@AE@%               The name given to the local variable. The assembler
  14882.                       automatically defines a text macro you may use to
  14883.                       access the variable.%@NL@%
  14884. %@NL@%
  14885.   %@AI@%count%@AE@%               The number of elements of this name and type to
  14886.                       allocate on the stack. Using %@AI@%count%@AE@% allows you to
  14887.                       allocate a simple array on the stack. The brackets
  14888.                       around %@AI@%count%@AE@% are required. If this field is omitted,
  14889.                       one data object is assumed.%@NL@%
  14890. %@NL@%
  14891.   %@AI@%type%@AE@%                The type of variable to allocate. The %@AI@%type%@AE@% argument
  14892.                       may be one of the following: %@AB@%WORD%@AE@%, %@AB@%DWORD%@AE@%, %@AB@%QWORD%@AE@%,
  14893.                       %@AB@%TBYTE%@AE@%, or the name of a structure defined by a %@AB@%STRUC%@AE@%
  14894.                       structure declaration.%@NL@%
  14895. %@NL@%
  14896. %@NL@%
  14897. %@4@%  The assembler sets aside space on the stack, following the same rules as%@EH@%
  14898.   for procedure arguments.%@NL@%
  14899. %@NL@%
  14900. %@4@%  The assembler does not initialize local variables. Your program must%@EH@%
  14901.   include code to perform any necessary initializations. For example, the
  14902.   following code fragment sets up a local array and initializes it to zero:%@NL@%
  14903. %@NL@%
  14904.   %@AS@%arraysz     EQU   20%@AE@%%@NL@%
  14905. %@NL@%
  14906.   %@AS@%aproc       PROC%@AE@%%@NL@%
  14907.   %@AS@%            LOCAL var1[arraysz]:WORD, var2:WORD%@AE@%%@NL@%
  14908.   %@AS@%            .%@AE@%%@NL@%
  14909.   %@AS@%            .%@AE@%%@NL@%
  14910.   %@AS@%            .%@AE@%%@NL@%
  14911.   %@AS@%; Initialize local array to zero%@AE@%%@NL@%
  14912.   %@AS@%            mov   cx,arraysz%@AE@%%@NL@%
  14913.   %@AS@%            xor   ax,ax%@AE@%%@NL@%
  14914.   %@AS@%            xor   di,di           ; Use di as array index%@AE@%%@NL@%
  14915.   %@AS@%repeat:     mov   var1[di],ax%@AE@%%@NL@%
  14916.   %@AS@%            inc   di%@AE@%%@NL@%
  14917.   %@AS@%            inc   di%@AE@%%@NL@%
  14918.   %@AS@%            loop  repeat%@AE@%%@NL@%
  14919.   %@AS@%; Use the array...%@AE@%%@NL@%
  14920.   %@AS@%            .%@AE@%%@NL@%
  14921.   %@AS@%            .%@AE@%%@NL@%
  14922.   %@AS@%            .%@AE@%%@NL@%
  14923.   %@AS@%            ret%@AE@%%@NL@%
  14924.   %@AS@%aproc%@AE@%%@NL@%
  14925. %@NL@%
  14926. %@NL@%
  14927. %@3@%%@CR:SC15.3.7    @%%@AB@%15.3.7  Variable Scope%@AE@%%@EH@%%@NL@%
  14928. %@NL@%
  14929. %@4@%  When you use the extended form of the %@AB@%.MODEL%@AE@% directive, the assembler%@EH@%
  14930.   makes all identifiers inside a procedure local to the procedure. Labels
  14931.   ending with a colon (:), procedure arguments, and local variables declared
  14932.   in a %@AB@%LOCAL%@AE@% directive are undefined outside of the procedure. Variables
  14933.   defined outside of any procedure are available inside a procedure. For
  14934.   example, in the following fragment, %@AS@%var1 %@AE@%can be used in %@AS@%proc1 %@AE@%and %@AS@%proc2%@AE@%,
  14935.   while %@AS@%var2%@AE@%──because it is defined in %@AS@%proc2%@AE@%──is not available to %@AS@%proc1%@AE@%:%@NL@%
  14936. %@NL@%
  14937.   %@AS@%          .MODEL medium,c%@AE@%%@NL@%
  14938.   %@AS@%            .DATA%@AE@%%@NL@%
  14939.   %@AS@%var1        DW     256          ; Available to proc1 and proc2%@AE@%%@NL@%
  14940. %@NL@%
  14941.   %@AS@%            .CODE%@AE@%%@NL@%
  14942.   %@AS@%proc1       PROC%@AE@%%@NL@%
  14943.   %@AS@%            .%@AE@%%@NL@%
  14944.   %@AS@%            .%@AE@%%@NL@%
  14945.   %@AS@%            .%@AE@%%@NL@%
  14946.   %@AS@%exit:       ret%@AE@%%@NL@%
  14947.   %@AS@%proc1       ENDP%@AE@%%@NL@%
  14948. %@NL@%
  14949.   %@AS@%proc2       PROC%@AE@%%@NL@%
  14950.   %@AS@%            LOCAL   var2:WORD   ; This var2 only available in proc2%@AE@%%@NL@%
  14951.   %@AS@%            .%@AE@%%@NL@%
  14952.   %@AS@%            .%@AE@%%@NL@%
  14953.   %@AS@%            .%@AE@%%@NL@%
  14954.   %@AS@%exit:       ret%@AE@%%@NL@%
  14955.   %@AS@%proc2       ENDP%@AE@%%@NL@%
  14956. %@NL@%
  14957. %@4@%  If %@AS@%proc1 %@AE@%contained a%@AB@% LOCAL %@AE@%directive defining %@AS@%var2%@AE@%, that %@AS@%var2 %@AE@%would be a%@EH@%
  14958.   completely different variable than the %@AS@%var2 %@AE@%in %@AS@%proc2%@AE@%.%@NL@%
  14959. %@NL@%
  14960. %@4@%  Notice that both procedures contain the label %@AS@%exit%@AE@%. Because labels are%@EH@%
  14961.   local when you use the language option on the %@AB@%.MODEL%@AE@% directive, you may
  14962.   use the same labels in different procedures. You can make a label in a
  14963.   procedure global (make it available outside the procedure) by ending it
  14964.   with two colons:%@NL@%
  14965. %@NL@%
  14966.   %@AS@%proc3       PROC%@AE@%%@NL@%
  14967.   %@AS@%            .%@AE@%%@NL@%
  14968.   %@AS@%            .%@AE@%%@NL@%
  14969.   %@AS@%            .%@AE@%%@NL@%
  14970.   %@AS@%label1::%@AE@%%@NL@%
  14971.   %@AS@%            .%@AE@%%@NL@%
  14972.   %@AS@%            .%@AE@%%@NL@%
  14973.   %@AS@%            .%@AE@%%@NL@%
  14974.   %@AS@%proc3       ENDP%@AE@%%@NL@%
  14975. %@NL@%
  14976. %@4@%  In the preceding example, %@AS@%label1 %@AE@%is available throughout the file%@EH@%
  14977.   containing %@AS@%proc3%@AE@%.%@NL@%
  14978. %@NL@%
  14979. %@NL@%
  14980. %@3@%%@CR:SC15.3.8    @%%@AB@%15.3.8  Setting Up Stack Frames%@AE@%%@EH@%%@NL@%
  14981. %@NL@%
  14982. %@4@%  %@AB@%80186/286/386 Only%@AE@%%@EH@%%@NL@%
  14983. %@NL@%
  14984. %@4@%%@CR:IX15.90     @%%@CR:IX15.91     @%%@CR:IX15.92     @%%@CR:IX15.93     @%%@CR:IX15.94     @%  Starting with the 80186 processor, the %@AB@%ENTER%@AE@% and %@AB@%LEAVE%@AE@% instructions are%@EH@%
  14985.   provided for setting up a stack frame. These instructions do the same
  14986.   thing as the multiple instructions at the start and end of procedures in
  14987.   the Microsoft calling conventions (see the examples in Section 15.3.3%@BO:       c60b0@%,
  14988.   "Passing Arguments on the Stack").%@NL@%
  14989. %@NL@%
  14990. %@4@%  The%@AB@% PROC%@AE@% statement takes advantage of these instructions if you enable the%@EH@%
  14991.   extended instruction set with the%@AB@% .186%@AE@% or%@AB@% .286 %@AE@%directive.%@NL@%
  14992. %@NL@%
  14993. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  14994. %@NL@%
  14995. %@4@%  %@AB@%ENTER%@AE@% %@AI@%framesize%@AE@%%@AB@%,%@AE@% %@AI@%nestinglevel%@AE@%%@EH@%%@NL@%
  14996.   %@AI@%statements%@AE@%%@NL@%
  14997.   %@AB@%LEAVE%@AE@%%@NL@%
  14998. %@NL@%
  14999. %@4@%%@CR:IX15.95     @%%@CR:IX15.96     @%%@CR:IX15.97     @%%@CR:IX15.98     @%%@CR:IX15.99     @%  The %@AB@%ENTER%@AE@% instruction takes two constant operands. The %@AI@%framesize%@AE@% (a 16-bit%@EH@%
  15000.   constant) specifies the number of bytes to reserve for local variables.
  15001.   The %@AI@%nestinglevel%@AE@% (an 8-bit constant) specifies the level at which the
  15002.   procedure is nested. This operand should always be 0 when writing
  15003.   procedures for BASIC, C, and FORTRAN. The %@AI@%nestinglevel%@AE@% can be greater than
  15004.   0 with Pascal and other languages that enable procedures to access the
  15005.   local variables of calling procedures.%@NL@%
  15006. %@NL@%
  15007. %@4@%  The %@AB@%LEAVE%@AE@% instruction reverses the effect of the last %@AB@%ENTER%@AE@% instruction by%@EH@%
  15008.   restoring BP and SP to their values before the procedure call.%@NL@%
  15009. %@NL@%
  15010. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  15011. %@NL@%
  15012.   %@AS@%task        PROC    NEAR%@AE@%%@NL@%
  15013.   %@AS@%            enter   6,0        ; Set stack frame and reserve 6%@AE@%%@NL@%
  15014.   %@AS@%            .                  ;   bytes for local variables%@AE@%%@NL@%
  15015.   %@AS@%            .                  ; Do task here%@AE@%%@NL@%
  15016.   %@AS@%            .%@AE@%%@NL@%
  15017.   %@AS@%            leave              ; Restore stack frame%@AE@%%@NL@%
  15018.   %@AS@%            ret                ; Return%@AE@%%@NL@%
  15019.   %@AS@%task        ENDP%@AE@%%@NL@%
  15020. %@NL@%
  15021. %@4@%  Example 1 has the same effect as the code in Example 2.%@EH@%%@NL@%
  15022. %@NL@%
  15023. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  15024. %@NL@%
  15025.   %@AS@%task        PROC    NEAR%@AE@%%@NL@%
  15026.   %@AS@%            push    bp         ; Save base pointer%@AE@%%@NL@%
  15027.   %@AS@%            mov     bp,sp      ; Load stack into base pointer%@AE@%%@NL@%
  15028.   %@AS@%            sub     sp,6       ; Reserve 6 bytes for local variables%@AE@%%@NL@%
  15029.   %@AS@%            .%@AE@%%@NL@%
  15030.   %@AS@%            .                  ; Do task here%@AE@%%@NL@%
  15031.   %@AS@%            .%@AE@%%@NL@%
  15032. %@NL@%
  15033.   %@AS@%            mov     sp,bp      ; Restore stack pointer%@AE@%%@NL@%
  15034.   %@AS@%            pop     bp         ; Restore base%@AE@%%@NL@%
  15035.   %@AS@%            ret                ; Return%@AE@%%@NL@%
  15036.   %@AS@%task        ENDP%@AE@%%@NL@%
  15037. %@NL@%
  15038. %@4@%  The code in Example 1 takes fewer bytes, but is slightly slower. See%@EH@%
  15039.   on-line Help on instructions for exact comparisons of size and timing.%@NL@%
  15040. %@NL@%
  15041. %@NL@%
  15042. %@2@%%@CR:SC15.4      @%%@AB@%15.4  Using Interrupts%@AE@%%@EH@%%@NL@%
  15043. %@NL@%
  15044. %@4@%%@CR:IX15.100    @%  "Interrupts" are a special form of routines that are called by number%@EH@%
  15045.   instead of by address. They can be initiated by hardware devices as well
  15046.   as by software. Hardware interrupts are called automatically whenever
  15047.   certain events occur in the hardware.%@NL@%
  15048. %@NL@%
  15049. %@4@%  Interrupts can have any number from 0 to 255. Most of the interrupts with%@EH@%
  15050.   lower numbers are reserved for use by the processor, DOS, or the ROM BIOS.%@NL@%
  15051. %@NL@%
  15052. %@4@%  The programmer can call existing interrupts with the %@AB@%INT%@AE@% instruction.%@EH@%
  15053.   Interrupt routines can also be defined or redefined to be called later.
  15054.   For example, an interrupt routine that is called automatically by a
  15055.   hardware device can be redefined so that its action is different.%@NL@%
  15056. %@NL@%
  15057. %@4@%  DOS defines several interrupt handlers. Two that are sometimes used by%@EH@%
  15058.   applications programmers are listed below:%@NL@%
  15059. %@NL@%
  15060.   %@AB@%Interrupt%@AE@%           %@AB@%Description%@AE@%%@NL@%
  15061.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15062. %@CR:IX15.101    @%  0                   Divide overflow. Called automatically when the
  15063.                       quotient of a divide operation is too large for the
  15064.                       source operand or when a divide by zero is attempted.%@NL@%
  15065. %@NL@%
  15066. %@CR:IX15.102    @%  4                   Overflow. Called by the %@AB@%INTO%@AE@% instruction if the
  15067.                       overflow flag is set.%@NL@%
  15068. %@NL@%
  15069. %@NL@%
  15070. %@4@%  Interrupt 21H is the normal method of using DOS functions. To call a%@EH@%
  15071.   function, place the function number in AH, put arguments in registers as
  15072.   appropriate, then call the interrupt. For complete documentation of DOS
  15073.   functions, see the %@AI@%Microsoft%@AE@% %@AI@%MS-DOS%@AE@% %@AI@%Programmer's%@AE@% %@AI@%Reference%@AE@%, one of the
  15074.   many other books on DOS functions, or the on-line Help system.%@NL@%
  15075. %@NL@%
  15076. %@4@%  DOS has several other interrupts, but they should not normally be called.%@EH@%
  15077.   Some (such as 20H and 27H) have been replaced by DOS functions. Others are
  15078.   used internally by DOS.%@NL@%
  15079. %@NL@%
  15080. %@4@%%@CR:IX15.103    @%  You can also access ROM-BIOS services through interrupt calls. See the%@EH@%
  15081.   on-line Help system for a description of all these services.%@NL@%
  15082. %@NL@%
  15083. %@NL@%
  15084. %@3@%%@CR:SC15.4.1    @%%@AB@%15.4.1  Calling Interrupts%@AE@%%@EH@%%@NL@%
  15085. %@NL@%
  15086. %@4@%%@CR:IX15.104    @%%@CR:IX15.105    @%%@CR:IX15.106    @%%@CR:IX15.107    @%  Interrupts are called with the %@AB@%INT%@AE@% instruction.%@EH@%%@NL@%
  15087. %@NL@%
  15088. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15089. %@NL@%
  15090. %@4@%  %@AB@%INT%@AE@% %@AI@%interruptnumber%@AE@%%@EH@%%@NL@%
  15091.   %@AB@%INTO%@AE@%%@NL@%
  15092. %@NL@%
  15093. %@4@%  The %@AB@%INT%@AE@% instruction takes an immediate operand with a value between 0 and%@EH@%
  15094.   255.%@NL@%
  15095. %@NL@%
  15096. %@4@%%@CR:IX15.108    @%%@CR:IX15.109    @%  When calling DOS and ROM-BIOS interrupts, a function number is usually%@EH@%
  15097.   placed in the AH register. Other registers may be used to pass arguments
  15098.   to functions. Some interrupts and functions return values in certain
  15099.   registers. Register use varies for each interrupt.%@NL@%
  15100. %@NL@%
  15101. %@4@%  When the instruction is called, the processor takes the following six%@EH@%
  15102.   steps:%@NL@%
  15103. %@NL@%
  15104.   1. Looks up the address of the interrupt routine in the interrupt
  15105.      descriptor table. In real mode, this table starts at the lowest point
  15106.      in memory (segment 0, offset 0) and consists of four bytes (two segment
  15107.      and two offset) for each interrupt. Thus, the address of an interrupt
  15108.      routine can be found by multiplying the number of the interrupt by 4.%@NL@%
  15109. %@NL@%
  15110.   2. Pushes the flags register, the current code segment (CS), and the
  15111.      current instruction pointer (IP).%@NL@%
  15112. %@NL@%
  15113. %@CR:IX15.110    @%%@CR:IX15.111    @%  3. Clears the trap (TF) and interrupt enable (IF) flags.%@NL@%
  15114. %@NL@%
  15115.   4. Jumps to the address of the interrupt routine, as specified in the
  15116.      interrupt description table.%@NL@%
  15117. %@NL@%
  15118. %@CR:IX15.112    @%%@CR:IX15.113    @%  5. Executes the code of the interrupt routine until it encounters an %@AB@%IRET%@AE@%
  15119.      instruction.%@NL@%
  15120. %@NL@%
  15121.   6. Pops the instruction pointer, code segment, and flags.%@NL@%
  15122. %@NL@%
  15123. %@4@%%@CR:IX15.114    @%  Figure 15.3 illustrates how interrupts work.%@EH@%%@NL@%
  15124. %@NL@%
  15125.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  15126.   │ This figure can be found in Section 15.4.1 of the manual               │%@NL@%
  15127.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  15128. %@NL@%
  15129. %@4@%%@CR:IX15.115    @%%@CR:IX15.116    @%%@CR:IX15.117    @%%@CR:IX15.118    @%%@CR:IX15.119    @%%@CR:IX15.120    @%%@CR:IX15.121    @%  The %@AB@%INTO%@AE@% (Interrupt On Overflow) instruction is a variation of the %@AB@%INT%@AE@%%@EH@%
  15130.   instruction. It calls interrupt 04H if called when the overflow flag is
  15131.   set. By default, the routine for interrupt 4 simply consists of an %@AB@%IRET%@AE@% so
  15132.   that it returns without doing anything. However, you can write your own
  15133.   overflow interrupt routine. Using %@AB@%INTO%@AE@% is an alternative to using %@AB@%JO%@AE@% (Jump
  15134.   On Overflow) to jump to an overflow routine. Section 15.4.2%@BO:       cf793@%, "Defining
  15135.   and Redefining Interrupt Routines," gives an example of this.%@NL@%
  15136. %@NL@%
  15137. %@4@%%@CR:IX15.122    @%%@CR:IX15.123    @%%@CR:IX15.124    @%%@CR:IX15.125    @%%@CR:IX15.126    @%  The %@AB@%CLI%@AE@% (Clear Interrupt Flag) and %@AB@%STI%@AE@% (Set Interrupt Flag) instructions%@EH@%
  15138.   can be used to turn interrupts on or off. You can use %@AB@%CLI%@AE@% to turn
  15139.   interrupt processing off so that an important routine cannot be stopped by
  15140.   a hardware interrupt. After the routine has finished, use %@AB@%STI %@AE@%to turn
  15141.   interrupt processing back on. Interrupts received while interrupt
  15142.   processing was turned off by %@AB@%CLI%@AE@% are saved and executed when %@AB@%STI%@AE@% turns
  15143.   interrupts back on.%@NL@%
  15144. %@NL@%
  15145. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  15146. %@NL@%
  15147.   %@AS@%; DOS call (Display String)%@AE@%%@NL@%
  15148. %@NL@%
  15149.   %@AS@%            mov     ah,09h             ; Load function number%@AE@%%@NL@%
  15150.   %@AS@%            mov     dx,OFFSET string   ; Load argument%@AE@%%@NL@%
  15151.   %@AS@%            int     21h                ; Call DOS%@AE@%%@NL@%
  15152. %@NL@%
  15153. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  15154. %@NL@%
  15155.   %@AS@%; BIOS call (Read Character from Keyboard)%@AE@%%@NL@%
  15156. %@NL@%
  15157.   %@AS@%            xor     ah,ah              ; Load function number 0 in AH%@AE@%%@NL@%
  15158.   %@AS@%            int     16h                ; Call BIOS%@AE@%%@NL@%
  15159.   %@AS@%                                       ; Return scan code in AH%@AE@%%@NL@%
  15160.   %@AS@%                                       ; Return ascii code in AL%@AE@%%@NL@%
  15161. %@NL@%
  15162. %@4@%  Example 1 is a call to a DOS function.%@EH@%%@NL@%
  15163. %@NL@%
  15164. %@4@%  Example 2 is a ROM-BIOS call that works on IBM Personal Computers and%@EH@%
  15165.   IBM-compatible computers. See the on-line Help system for complete
  15166.   information on DOS and BIOS calls.%@NL@%
  15167. %@NL@%
  15168. %@NL@%
  15169. %@3@%%@CR:SC15.4.2    @%%@AB@%15.4.2  Defining and Redefining Interrupt Routines%@AE@%%@EH@%%@NL@%
  15170. %@NL@%
  15171. %@4@%%@CR:IX15.127    @%  You can write your own interrupt routines, either to replace an existing%@EH@%
  15172.   routine or to use an undefined interrupt number.%@NL@%
  15173. %@NL@%
  15174. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15175. %@NL@%
  15176. %@4@%  %@AI@%label%@AE@% PROC FAR[[%@AB@%USES %@AE@%%@AI@%reglist%@AE@%]]%@EH@%%@NL@%
  15177.   %@AI@%statements%@AE@%%@NL@%
  15178.   %@AB@%IRET%@AE@%%@NL@%
  15179.   label%@AB@% ENDP%@AE@%%@NL@%
  15180. %@NL@%
  15181. %@4@%%@CR:IX15.128    @%%@CR:IX15.129    @%%@CR:IX15.130    @%%@CR:IX15.131    @%%@CR:IX15.132    @%%@CR:IX15.133    @%  An interrupt routine can be written like a procedure by using the %@AB@%PROC%@AE@% and%@EH@%
  15182.   %@AB@%ENDP%@AE@% directives. The only differences are that the routine should always
  15183.   be defined as far and the routine should be terminated by an %@AB@%IRET%@AE@%
  15184.   instruction instead of a %@AB@%RET%@AE@% instruction.%@NL@%
  15185. %@NL@%
  15186.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15187.   %@AB@%NOTE%@AE@%  Since the assembler doesn't know whether you are going to terminate
  15188.   with a %@AB@%RET %@AE@%or an %@AB@%IRET%@AE@%, it is possible to use the full extended %@AB@%PROC %@AE@%syntax
  15189.   (described in Section 15.3.4%@BO:       c7284@%) for interrupt procedures. However, making
  15190.   interrupt procedures %@AB@%NEAR %@AE@%or specifying arguments for them makes no sense.
  15191.   The %@AB@%USES%@AE@% keyword does correctly generate code to save and restore a
  15192.   register list in interrupt procedures.%@NL@%
  15193.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15194. %@NL@%
  15195. %@4@%  Your program should replace the address in the interrupt descriptor table%@EH@%
  15196.   with the address of your routine. DOS calls are provided for this task.
  15197.   Another common technique is to jump to the old interrupt routine and let
  15198.   it do the %@AB@%IRET%@AE@% instruction.%@NL@%
  15199. %@NL@%
  15200. %@4@%  It is usually a good idea to save the old address and restore it before%@EH@%
  15201.   your program ends.%@NL@%
  15202. %@NL@%
  15203. %@4@%  Interrupt routines you may want to replace include the processor's%@EH@%
  15204.   divide-overflow (0H) and overflow (04H) interrupts. You can also replace
  15205.   DOS interrupts, such as the critical-error (24H) and CONTROL+C (23H)
  15206.   handlers. Interrupt routines can be part of device drivers. Writing
  15207.   interrupt routines is usually a systems task. The example below
  15208.   illustrates a simple routine. For complete information, see the %@AI@%Microsoft%@AE@%
  15209.   %@AI@%MS-DOS%@AE@% %@AI@%Programmer's%@AE@% %@AI@%Reference%@AE@% or one of the other reference books on DOS.%@NL@%
  15210. %@NL@%
  15211. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  15212. %@NL@%
  15213.   %@AS@%            .DATA%@AE@%%@NL@%
  15214.   %@AS@%message     DB      "Overflow - result set to 0",13,10,"$"%@AE@%%@NL@%
  15215.   %@AS@%vector      DD      ?%@AE@%%@NL@%
  15216.   %@AS@%            .CODE%@AE@%%@NL@%
  15217.   %@AS@%            .STARTUP%@AE@%%@NL@%
  15218. %@NL@%
  15219.   %@AS@%            mov     ax,3504h              ; Load interrupt 4 and call DOS%@AE@%%@NL@%
  15220.   %@AS@%            int     21h                   ;   get interrupt vector function%@AE@%%@NL@%
  15221.   %@AS@%            mov     WORD PTR vector[2],es ; Save segment%@AE@%%@NL@%
  15222.   %@AS@%            mov     WORD PTR vector[0],bx ;   and offset%@AE@%%@NL@%
  15223. %@NL@%
  15224.   %@AS@%            push    ds                    ; Save DS%@AE@%%@NL@%
  15225.   %@AS@%            mov     ax,cs                 ; Load segment of new routine%@AE@%%@NL@%
  15226.   %@AS@%            mov     ds,ax%@AE@%%@NL@%
  15227.   %@AS@%            mov     dx,OFFSET overflow    ; Load offset of new routine%@AE@%%@NL@%
  15228.   %@AS@%            mov     ax,2504h              ; Load interrupt 4 and call DOS%@AE@%%@NL@%
  15229.   %@AS@%            int     21h                   ;   set interrupt vector function%@AE@%%@NL@%
  15230.   %@AS@%            pop     ds                    ; Restore%@AE@%%@NL@%
  15231.   %@AS@%            .%@AE@%%@NL@%
  15232.   %@AS@%            .%@AE@%%@NL@%
  15233.   %@AS@%            .%@AE@%%@NL@%
  15234.   %@AS@%            add     ax,bx                 ; Do addition (or multiplication)%@AE@%%@NL@%
  15235.   %@AS@%            into                          ; Call interrupt 4 if overflow%@AE@%%@NL@%
  15236.   %@AS@%            .%@AE@%%@NL@%
  15237.   %@AS@%            .%@AE@%%@NL@%
  15238.   %@AS@%            .%@AE@%%@NL@%
  15239.   %@AS@%            lds     dx,vector             ; Load original interrupt address%@AE@%%@NL@%
  15240.   %@AS@%            mov     ax,2504h              ; Restore interrupt number 4%@AE@%%@NL@%
  15241.   %@AS@%            int     21h                   ;   with DOS set vector function%@AE@%%@NL@%
  15242.   %@AS@%            mov     ax,4C00h              ; Terminate function%@AE@%%@NL@%
  15243.   %@AS@%            int     21h%@AE@%%@NL@%
  15244. %@NL@%
  15245.   %@AS@%overflow    PROC    FAR%@AE@%%@NL@%
  15246.   %@AS@%            sti                           ; Enable interrupts%@AE@%%@NL@%
  15247.   %@AS@%                                          ;   (turned off by INT)%@AE@%%@NL@%
  15248.   %@AS@%            mov     ah,09h                ; Display string function%@AE@%%@NL@%
  15249.   %@AS@%            mov     dx,OFFSET message     ; Load address%@AE@%%@NL@%
  15250.   %@AS@%            int     21h                   ; Call DOS%@AE@%%@NL@%
  15251.   %@AS@%            xor     ax,ax                 ; Set AX to 0%@AE@%%@NL@%
  15252.   %@AS@%            xor     dx,dx                 ; Set DX to 0%@AE@%%@NL@%
  15253.   %@AS@%            iret                          ; Return%@AE@%%@NL@%
  15254.   %@AS@%overflow    ENDP%@AE@%%@NL@%
  15255.   %@AS@%            END     start%@AE@%%@NL@%
  15256. %@NL@%
  15257. %@4@%  In this example, DOS functions are used to save the address of the initial%@EH@%
  15258.   interrupt routine in a variable and to put the address of the new
  15259.   interrupt routine in the interrupt table. Once the new address has been
  15260.   set, the new routine is called any time the interrupt is called. The
  15261.   sample interrupt handler sets the result of a calculation that causes an
  15262.   overflow (either in AX or AX:DX) to 0. It is good practice to restore the
  15263.   original interrupt address before terminating the program.%@NL@%
  15264. %@NL@%
  15265. %@NL@%
  15266. %@2@%%@CR:SC15.5      @%%@AB@%15.5  Checking Memory Ranges%@AE@%%@EH@%%@NL@%
  15267. %@NL@%
  15268. %@4@%  %@AB@%80186/286/386 Only%@AE@%%@EH@%%@NL@%
  15269. %@NL@%
  15270. %@4@%%@CR:IX15.134    @%%@CR:IX15.135    @%%@CR:IX15.136    @%%@CR:IX15.137    @%%@CR:IX15.138    @%  Starting with the 80186 processor, the %@AB@%BOUND%@AE@% instruction can check to see%@EH@%
  15271.   if a value is within a specified range. This instruction is usually used
  15272.   to check a signed index value to see if it is within the range of an
  15273.   array. %@AB@%BOUND%@AE@% is a conditional interrupt instruction like %@AB@%INTO%@AE@%. If the
  15274.   condition is not met (the index is out of range), an interrupt 5 is
  15275.   executed.%@NL@%
  15276. %@NL@%
  15277. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15278. %@NL@%
  15279. %@4@%  %@AB@%BOUND%@AE@% %@AI@%register16%@AE@%%@AB@%,%@AE@% %@AI@%memory32%@AE@%%@EH@%%@NL@%
  15280. %@NL@%
  15281. %@4@%  To use it for this purpose, the starting and ending values of the array mu%@EH@%
  15282.   st be stored as 16-bit values in the low and high words of a doubleword me
  15283.   mory operand. This operand is given as the source operand. The index value
  15284.    to be checked is given as the destination operand. If the index value is
  15285.   out of range, the instruction issues interrupt 5. This means that the oper
  15286.   ating system or the program must provide an interrupt routine for interrup
  15287.   t 5. DOS does not provide such a routine, so you must write your own. See
  15288.   Section 15.4%@BO:       cdbc9@%, "Using Interrupts," for more information.%@NL@%
  15289. %@NL@%
  15290. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  15291. %@NL@%
  15292.   %@AS@%            .DATA%@AE@%%@NL@%
  15293.   %@AS@%bottom      EQU     0%@AE@%%@NL@%
  15294.   %@AS@%top         EQU     19%@AE@%%@NL@%
  15295.   %@AS@%dbounds     LABEL   DWORD              ; Allocate boundaries%@AE@%%@NL@%
  15296.   %@AS@%wbounds     DW      bottom,top         ;   initialized to bounds%@AE@%%@NL@%
  15297.   %@AS@%array       DB      top+1 DUP (?)      ; Allocate array%@AE@%%@NL@%
  15298.   %@AS@%            .CODE%@AE@%%@NL@%
  15299.   %@AS@%            .%@AE@%%@NL@%
  15300.   %@AS@%            .%@AE@%%@NL@%
  15301.   %@AS@%            .                          ; Assume index in DI%@AE@%%@NL@%
  15302.   %@AS@%            bound   di,dbounds         ; Check to see if it is in range%@AE@%%@NL@%
  15303.   %@AS@%                                       ;   if out of range, interrupt 5%@AE@%%@NL@%
  15304.   %@AS@%            mov     dx,array[di]       ; If in range, use it%@AE@%%@NL@%
  15305. %@NL@%
  15306. %@NL@%
  15307. %@NL@%
  15308. ────────────────────────────────────────────────────────────────────────────%@NL@%
  15309. %@1@%%@CR:CH16        @%%@AB@%Chapter 16:  Processing Strings%@AE@%%@EH@%%@NL@%
  15310. %@NL@%
  15311. %@NL@%
  15312. %@4@%%@CR:IX16.1      @%%@CR:IX16.2      @%  The 8086-family processors have a full set of instructions for%@EH@%
  15313.   manipulating strings. In the discussion of these instructions, the term
  15314.   "string" refers not only to the common definition of a string──a sequence
  15315.   of bytes containing characters──but to any sequence of bytes or words%@NL@%
  15316. %@NL@%
  15317. %@4@%  The following instructions are provided for 8086-family string functions:%@EH@%%@NL@%
  15318. %@NL@%
  15319.   %@AB@%Instruction%@AE@%         %@AB@%Description%@AE@%%@NL@%
  15320.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15321.   %@AB@%MOVS%@AE@%                Moves string from one location to another%@NL@%
  15322. %@NL@%
  15323.   %@AB@%SCAS%@AE@%                Scans string for specified values%@NL@%
  15324. %@NL@%
  15325.   %@AB@%CMPS%@AE@%                Compares values in one string with values in another%@NL@%
  15326. %@NL@%
  15327.   %@AB@%LODS%@AE@%                Loads values from a string to accumulator register%@NL@%
  15328. %@NL@%
  15329.   %@AB@%STOS%@AE@%                Stores values from accumulator register to a string%@NL@%
  15330. %@NL@%
  15331.   %@AB@%INS%@AE@%                 Transfers values from a port to memory%@NL@%
  15332. %@NL@%
  15333.   %@AB@%OUTS%@AE@%                Transfers values from memory to a port%@NL@%
  15334. %@NL@%
  15335. %@NL@%
  15336. %@4@%  All these instructions use registers in the same way and have a similar%@EH@%
  15337.   syntax. Most are used with the repeat instruction prefixes: %@AB@%REP%@AE@%, %@AB@%REPE%@AE@%,
  15338.   %@AB@%REPNE%@AE@%, %@AB@%REPZ%@AE@%, and %@AB@%REPNZ%@AE@%.%@NL@%
  15339. %@NL@%
  15340. %@4@%  This chapter first explains the general format for string instructions and%@EH@%
  15341.   then tells you how to use each instruction.%@NL@%
  15342. %@NL@%
  15343. %@NL@%
  15344. %@2@%%@CR:SC16.1      @%%@AB@%16.1  Setting Up String Operations%@AE@%%@EH@%%@NL@%
  15345. %@NL@%
  15346. %@4@%  The string instructions all work in a similar way. Once you understand the%@EH@%
  15347.   gen-eral procedure, it is easy to adapt the format for a particular string
  15348.   operation. The five steps are listed below:%@NL@%
  15349. %@NL@%
  15350. %@CR:IX16.3      @%%@CR:IX16.4      @%%@CR:IX16.5      @%%@CR:IX16.6      @%%@CR:IX16.7      @%  1. Make sure the direction flag indicates the direction in which you want
  15351.      the string to be processed. If the direction flag is clear, the string
  15352.      will be pro-cessed up (from low addresses to high addresses). If the
  15353.      direction flag is set, the string will be processed down (from high
  15354.      addresses to low addresses). The %@AB@%CLD%@AE@% instruction clears the flag, while
  15355.      %@AB@%STD%@AE@% sets it. Under DOS, the direction flag will normally be cleared if
  15356.      your program has not changed it.%@NL@%
  15357. %@NL@%
  15358.   2. Load the number of iterations for the string instruction into the CX
  15359.      register. For instance, if you want to process a 100-byte string, load
  15360.      100. If a string instruction will be terminated conditionally, load the
  15361.      maximum number of iterations that can be done without an error.%@NL@%
  15362. %@NL@%
  15363. %@CR:IX16.8      @%%@CR:IX16.9      @%%@CR:IX16.10     @%%@CR:IX16.11     @%%@CR:IX16.12     @%  3. Load the starting offset address of the source string into DS:SI and
  15364.      the starting address of the destination string into ES:DI. Some string
  15365.      instructions take only a destination or source (shown in Table 16.1
  15366.      below). Normally, the segment address of the source string should be
  15367.      DS, but you can use a segment override with the string instruction to
  15368.      specify a different segment. You cannot override the segment address
  15369.      for the destination string. Therefore, you may need to change the value
  15370.      of ES.%@NL@%
  15371. %@NL@%
  15372.   4. Choose the appropriate repeat-prefix instruction. Table 16.1 shows the
  15373.      repeat prefixes that can be used with each instruction.%@NL@%
  15374. %@NL@%
  15375.   5. Put the appropriate string instruction immediately after the repeat
  15376.      prefix (on the same line).%@NL@%
  15377. %@NL@%
  15378. %@4@%  String instructions have two basic forms, as shown below:%@EH@%%@NL@%
  15379. %@NL@%
  15380. %@4@%  %@AB@%Syntax 1%@AE@%%@EH@%%@NL@%
  15381. %@NL@%
  15382. %@4@%  [[%@AI@%repeatprefix%@AE@%]] %@AI@%stringinstruction%@AE@%[[%@AB@%ES:%@AE@%[[%@AI@%destination%@AE@%%@AB@%,%@AE@%]]]]%@EH@%%@NL@%
  15383.   [[[[%@AI@%segmentregister%@AE@%%@AB@%:%@AE@%]]%@AI@%source%@AE@%]]%@NL@%
  15384. %@NL@%
  15385. %@4@%%@CR:IX16.13     @%  The string instruction can be given with the source and/or destination as%@EH@%
  15386.   operands. The size of the operand or operands indicates the size of the
  15387.   objects to be processed by the string. Note that the operands only specify
  15388.   the size. The actual values to be worked on are the ones pointed to by
  15389.   DS:SI and/or ES:DI. No error is generated if the operand is not the same
  15390.   as the actual source or destination. One important advantage of this
  15391.   syntax is that the source operand can have a segment override. The
  15392.   destination operand is always relative to ES and cannot be overridden.%@NL@%
  15393. %@NL@%
  15394. %@4@%  %@AB@%Syntax 2%@AE@%%@EH@%%@NL@%
  15395. %@NL@%
  15396. %@4@%  [[%@AI@%repeatprefix%@AE@%]] %@AI@%stringinstruction%@AE@%%@AB@%B%@AE@%%@EH@%%@NL@%
  15397.   [[%@AI@%repeatprefix%@AE@%]] %@AI@%stringinstruction%@AE@%%@AB@%W%@AE@%%@NL@%
  15398. %@NL@%
  15399. %@4@%  The letter %@AB@%B%@AE@% or %@AB@%W%@AE@% appended to %@AI@%stringinstruction%@AE@% indicates bytes or words.%@EH@%
  15400.   With a letter appended to a string instruction, no operand is allowed.%@NL@%
  15401. %@NL@%
  15402. %@4@%  For instance, %@AB@%MOVS%@AE@% can be given with byte operands to move bytes or with%@EH@%
  15403.   word operands to move words. As an alternative, %@AB@%MOVSB%@AE@% can be given with no
  15404.   operands to move bytes, or %@AB@%MOVSW%@AE@% can be given with no operands to move
  15405.   words.%@NL@%
  15406. %@NL@%
  15407. %@4@%  Note that instructions that specify the size in the name never accept%@EH@%
  15408.   operands. Therefore, the following statement is illegal:%@NL@%
  15409. %@NL@%
  15410.   %@AS@%            lodsb     es:0               ; Illegal - no operand allowed%@AE@%%@NL@%
  15411. %@NL@%
  15412. %@4@%  Instead, the statement must be coded as shown below:%@EH@%%@NL@%
  15413. %@NL@%
  15414.   %@AS@%            lods      BYTE PTR es:0      ; Legal - use type specifier%@AE@%%@NL@%
  15415. %@NL@%
  15416. %@4@%  If a repeat prefix is used, it can be one of the following instructions:%@EH@%%@NL@%
  15417. %@NL@%
  15418.   %@AB@%Instruction%@AE@%         %@AB@%Description%@AE@%%@NL@%
  15419.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15420. %@CR:IX16.14     @%%@CR:IX16.15     @%  %@AB@%REP%@AE@%                 Repeats for a specified number of iterations. The
  15421.                       number is given in CX.%@NL@%
  15422. %@NL@%
  15423. %@CR:IX16.16     @%%@CR:IX16.17     @%%@CR:IX16.18     @%%@CR:IX16.19     @%  %@AB@%REPE%@AE@% or %@AB@%REPZ%@AE@%        Repeats while equal. The maximum number of iterations
  15424.                       should be specified in CX.%@NL@%
  15425. %@NL@%
  15426. %@CR:IX16.20     @%%@CR:IX16.21     @%%@CR:IX16.22     @%%@CR:IX16.23     @%  %@AB@%REPNE%@AE@% or %@AB@%REPNZ%@AE@%      Repeats while not equal. The maximum number of
  15427.                       iterations should be specified in CX.%@NL@%
  15428. %@NL@%
  15429. %@NL@%
  15430. %@4@%  %@AB@%REPE%@AE@% is the same as %@AB@%REPZ%@AE@%, and %@AB@%REPNE%@AE@% is the same as %@AB@%REPNZ%@AE@%. You can use%@EH@%
  15431.   whichever name you find more mnemonic. The prefixes ending with %@AB@%E%@AE@% are used
  15432.   in syntax listings and tables in the rest of this chapter.%@NL@%
  15433. %@NL@%
  15434. %@4@%%@CR:IX16.24     @%  Table 16.1 lists each string instruction with the type of repeat prefix it%@EH@%
  15435.   uses and whether the instruction works on a source, a destination, or
  15436.   both.%@NL@%
  15437. %@NL@%
  15438.   %@AB@%Table 16.1 Requirements for String Instructions%@AE@%%@NL@%
  15439. %@NL@%
  15440.   %@AB@%Instruction%@AE@%   %@AB@%Repeat Prefix%@AE@%   %@AB@%Source/Destination%@AE@%  %@AB@%Register Pair%@AE@%%@NL@%
  15441.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15442.   %@AB@%MOVS%@AE@%          %@AB@%REP%@AE@%             Both                DS:SI, ES:DI%@NL@%
  15443. %@NL@%
  15444.   %@AB@%SCAS%@AE@%          %@AB@%REPE/REPNE%@AE@%      Destination         ES:DI%@NL@%
  15445. %@NL@%
  15446.   %@AB@%CMPS%@AE@%          %@AB@%REPE/REPNE%@AE@%      Both                ES:DI, DS:SI%@NL@%
  15447. %@NL@%
  15448.   %@AB@%LODS%@AE@%          None            Source              DS:SI%@NL@%
  15449. %@NL@%
  15450.   %@AB@%STOS%@AE@%          %@AB@%REP%@AE@%             Destination         ES:DI%@NL@%
  15451. %@NL@%
  15452.   %@AB@%INS%@AE@%           %@AB@%REP%@AE@%             Destination         ES:DI%@NL@%
  15453. %@NL@%
  15454.   %@AB@%OUTS%@AE@%          %@AB@%REP%@AE@%             Source              DS:SI%@NL@%
  15455. %@NL@%
  15456.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15457. %@NL@%
  15458. %@NL@%
  15459. %@4@%  At run time, a string instruction preceded by a repeat sequence causes the%@EH@%
  15460.   processor to take the following steps:%@NL@%
  15461. %@NL@%
  15462.   1. Checks the CX registers and exits from the string instruction if CX is
  15463.      0.%@NL@%
  15464. %@NL@%
  15465.   2. Performs the string operation once.%@NL@%
  15466. %@NL@%
  15467.   3. Increases SI and/or DI if the direction flag is cleared. Decreases SI
  15468.      and/or DI if the direction flag is set. The amount of increase or
  15469.      decrease is 1 for byte operations, 2 for word operations.%@NL@%
  15470. %@NL@%
  15471.   4. Decrements CX (no flags are modified).%@NL@%
  15472. %@NL@%
  15473.   5. If the string instruction is %@AB@%SCAS%@AE@% or %@AB@%CMPS%@AE@%, checks the zero flag and
  15474.      exits if the repeat condition is false──that is, if the flag is set
  15475.      with %@AB@%REPE%@AE@% or %@AB@%REPZ%@AE@% or if it is clear with %@AB@%REPNE%@AE@% or %@AB@%REPNZ%@AE@%.%@NL@%
  15476. %@NL@%
  15477.   6. Goes to the next iteration (step 1).%@NL@%
  15478. %@NL@%
  15479. %@4@%  Although string instructions (except %@AB@%LODS%@AE@%) are most often used with repeat%@EH@%
  15480.   prefixes, they can also be used by themselves. In this case, the SI and/or
  15481.   DI registers are adjusted as specified by the direction flag and the size
  15482.   of operands. However, you must decrement the CX register and set up a loop
  15483.   for the repeated action.%@NL@%
  15484. %@NL@%
  15485.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15486.   %@AB@%NOTE%@AE@%  Although you can use a segment override on the source operand, a
  15487.   segment override combined with a repeat prefix can cause problems in
  15488.   certain situations. If an interrupt occurs during the string operation,
  15489.   the segment override is lost and the rest of the string operation
  15490.   processes incorrectly. Segment overrides can be used safely when
  15491.   interrupts are turned off.%@NL@%
  15492.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15493. %@NL@%
  15494. %@NL@%
  15495. %@2@%%@CR:SC16.2      @%%@AB@%16.2  Moving Strings%@AE@%%@EH@%%@NL@%
  15496. %@NL@%
  15497. %@4@%%@CR:IX16.25     @%%@CR:IX16.26     @%%@CR:IX16.27     @%  The %@AB@%MOVS%@AE@% instruction is used to move data from one area of memory to%@EH@%
  15498.   another.%@NL@%
  15499. %@NL@%
  15500. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15501. %@NL@%
  15502. %@4@%  [[%@AB@%REP%@AE@%]] %@AB@%MOVS%@AE@% [[%@AB@%ES:%@AE@%]]%@AI@%destination%@AE@%%@AB@%,%@AE@%[[%@AI@%segmentregister%@AE@%%@AB@%:%@AE@%]]%@AI@%source%@AE@%%@EH@%%@NL@%
  15503.   [[%@AB@%REP%@AE@%]] %@AB@%MOVSB%@AE@%%@NL@%
  15504.   [[%@AB@%REP%@AE@%]] %@AB@%MOVSW%@AE@%%@NL@%
  15505. %@NL@%
  15506. %@4@%  To move the data, load the count and the source and destination addresses%@EH@%
  15507.   into the appropriate registers. Then use %@AB@%REP%@AE@% with the %@AB@%MOVS%@AE@% instruction.%@NL@%
  15508. %@NL@%
  15509. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  15510. %@NL@%
  15511.   %@AS@%            .MODEL  small%@AE@%%@NL@%
  15512.   %@AS@%            .DATA%@AE@%%@NL@%
  15513.   %@AS@%source      DB      10 DUP ('0123456789')%@AE@%%@NL@%
  15514.   %@AS@%destin      DB      100 DUP (?)%@AE@%%@NL@%
  15515.   %@AS@%            .CODE%@AE@%%@NL@%
  15516.   %@AS@%            mov     ax,@data           ; Load same segment%@AE@%%@NL@%
  15517.   %@AS@%            mov     ds,ax              ;   to both DS%@AE@%%@NL@%
  15518.   %@AS@%            mov     es,ax              ;   and ES%@AE@%%@NL@%
  15519.   %@AS@%            .%@AE@%%@NL@%
  15520.   %@AS@%            .%@AE@%%@NL@%
  15521.   %@AS@%            .%@AE@%%@NL@%
  15522.   %@AS@%            cld                        ; Work upward%@AE@%%@NL@%
  15523.   %@AS@%            mov     cx,100             ; Set iteration count to 100%@AE@%%@NL@%
  15524.   %@AS@%            mov     si,OFFSET source   ; Load address of source%@AE@%%@NL@%
  15525.   %@AS@%            mov     di,OFFSET destin   ; Load address of destination%@AE@%%@NL@%
  15526.   %@AS@%            rep     movsb              ; Move 100 bytes%@AE@%%@NL@%
  15527. %@NL@%
  15528. %@4@%  Example 1 shows how to move a string by using string instructions. For%@EH@%
  15529.   comparison, Example 2 shows a much less efficient way of doing the same
  15530.   operation without string instructions.%@NL@%
  15531. %@NL@%
  15532. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  15533. %@NL@%
  15534.   %@AS@%            .MODEL  small%@AE@%%@NL@%
  15535.   %@AS@%            .DATA%@AE@%%@NL@%
  15536.   %@AS@%source      DB      10 DUP ('0123456789')%@AE@%%@NL@%
  15537.   %@AS@%destin      DB      100 DUP (?)%@AE@%%@NL@%
  15538.   %@AS@%            .CODE%@AE@%%@NL@%
  15539.   %@AS@%            .                          ; Assume ES = DS%@AE@%%@NL@%
  15540.   %@AS@%            .%@AE@%%@NL@%
  15541.   %@AS@%            .%@AE@%%@NL@%
  15542.   %@AS@%            mov     cx,100             ; Set iteration count to 100%@AE@%%@NL@%
  15543.   %@AS@%            mov     si,OFFSET source   ; Load offset of source%@AE@%%@NL@%
  15544.   %@AS@%            mov     di,OFFSET destin   ; Load offset of destination%@AE@%%@NL@%
  15545.   %@AS@%repeat:     mov     al,[si]            ; Get a byte from source%@AE@%%@NL@%
  15546.   %@AS@%            mov     [di],al            ; Put it in destination%@AE@%%@NL@%
  15547.   %@AS@%            inc     si                 ; Increment source pointer%@AE@%%@NL@%
  15548.   %@AS@%            inc     di                 ; Increment destination pointer%@AE@%%@NL@%
  15549.   %@AS@%            loop    repeat             ; Do it again%@AE@%%@NL@%
  15550. %@NL@%
  15551. %@4@%  Both examples illustrate how to move byte strings in a small-model program%@EH@%
  15552.   in which DS already points to the segment containing the variables. In
  15553.   such programs, ES can be set to the same value as DS.%@NL@%
  15554. %@NL@%
  15555. %@4@%  There are several variations on this. If the source string was not in the%@EH@%
  15556.   current data segment, you could load the starting address of its segment
  15557.   into ES. Another option would be to use the %@AB@%MOVS%@AE@% instruction with operands
  15558.   and give a segment override on the source operand. For example, you could
  15559.   use the following statement if ES pointed to both the source and the
  15560.   destination strings:%@NL@%
  15561. %@NL@%
  15562.   %@AS@%            rep     movs destin,es:source%@AE@%%@NL@%
  15563. %@NL@%
  15564. %@4@%  It is sometimes faster to move a string of bytes as words. You must adjust%@EH@%
  15565.   for any odd bytes, as shown in Example 3. Assume the source and
  15566.   destination are already loaded.%@NL@%
  15567. %@NL@%
  15568. %@4@%  %@AB@%Example 3%@AE@%%@EH@%%@NL@%
  15569. %@NL@%
  15570.   %@AS@%            mov     cx,count           ; Load count%@AE@%%@NL@%
  15571.   %@AS@%            shr     cx,1               ; Divide by 2 (carry will be set%@AE@%%@NL@%
  15572.   %@AS@%                                       ;   if count is odd)%@AE@%%@NL@%
  15573.   %@AS@%            rep     movsw              ; Move words%@AE@%%@NL@%
  15574.   %@AS@%            rcl     cx,1               ; If odd, make CX 1%@AE@%%@NL@%
  15575.   %@AS@%            rep     movsb              ; Move odd byte if there is one%@AE@%%@NL@%
  15576. %@NL@%
  15577. %@NL@%
  15578. %@2@%%@CR:SC16.3      @%%@AB@%16.3  Searching Strings%@AE@%%@EH@%%@NL@%
  15579. %@NL@%
  15580. %@4@%%@CR:IX16.28     @%%@CR:IX16.29     @%%@CR:IX16.30     @%%@CR:IX16.31     @%  The %@AB@%SCAS %@AE@%instruction is used to scan a string for a specified value.%@EH@%%@NL@%
  15581. %@NL@%
  15582. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15583. %@NL@%
  15584. %@4@%  [[%@AB@%REPE%@AE@% | %@AB@%REPNE%@AE@%]] %@AB@%SCAS%@AE@% [[%@AB@%ES:%@AE@%]]%@AI@%destination%@AE@%%@EH@%%@NL@%
  15585.   [[%@AB@%REPE%@AE@% | %@AB@%REPNE%@AE@%]] %@AB@%SCASB%@AE@%%@NL@%
  15586.   [[%@AB@%REPE%@AE@% | %@AB@%REPNE%@AE@%]] %@AB@%SCASW%@AE@%%@NL@%
  15587. %@NL@%
  15588. %@4@%  %@AB@%SCAS%@AE@% and its variations work only on a destination string, which must be%@EH@%
  15589.   pointed to by ES:DI. The value to scan for must be in the accumulator
  15590.   register──AL for bytes, AX for words.%@NL@%
  15591. %@NL@%
  15592. %@4@%  The %@AB@%SCAS%@AE@% instruction works by comparing the value pointed to by DI with%@EH@%
  15593.   the value in the accumulator. If the values are the same, the zero flag is
  15594.   set. Thus, the instruction only makes sense when used with one of the
  15595.   repeat prefixes that checks the zero flag.%@NL@%
  15596. %@NL@%
  15597. %@4@%%@CR:IX16.32     @%%@CR:IX16.33     @%%@CR:IX16.34     @%%@CR:IX16.35     @%  If you want to search for the first occurrence of a specified value, use%@EH@%
  15598.   the %@AB@%REPNE%@AE@% or %@AB@%REPNZ%@AE@% instruction. If the value is found, ES:DI will point to
  15599.   the value immediately after the first occurrence. You can decrement DI to
  15600.   make it point to the first matching value.%@NL@%
  15601. %@NL@%
  15602. %@4@%%@CR:IX16.36     @%%@CR:IX16.37     @%%@CR:IX16.38     @%%@CR:IX16.39     @%  If you want to search for the first value that does not have a specified%@EH@%
  15603.   value, use %@AB@%REPE%@AE@% or %@AB@%REPZ%@AE@%. If the value is found, ES:DI will point to the
  15604.   position after the first nonmatching value. You can decrement DI to make
  15605.   it point to the first non-matching value.%@NL@%
  15606. %@NL@%
  15607. %@4@%%@CR:IX16.40     @%  After a %@AB@%REPNE SCAS%@AE@%, the zero flag will be cleared if no match was found.%@EH@%
  15608.   After a %@AB@%REPE SCAS%@AE@%, the zero flag will be set if no nonmatch was found.%@NL@%
  15609. %@NL@%
  15610. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  15611. %@NL@%
  15612.   %@AS@%           .DATA%@AE@%%@NL@%
  15613.   %@AS@%string      DB      "The quick brown fox jumps over the lazy dog"%@AE@%%@NL@%
  15614.   %@AS@%lstring     EQU     $-string           ; Length of string%@AE@%%@NL@%
  15615.   %@AS@%pstring     DD      string             ; Far pointer to string%@AE@%%@NL@%
  15616.   %@AS@%            .CODE%@AE@%%@NL@%
  15617.   %@AS@%            .%@AE@%%@NL@%
  15618.   %@AS@%            .%@AE@%%@NL@%
  15619.   %@AS@%            .%@AE@%%@NL@%
  15620.   %@AS@%            cld                        ; Work upward%@AE@%%@NL@%
  15621.   %@AS@%            mov     cx,lstring         ; Load length of string%@AE@%%@NL@%
  15622.   %@AS@%            les     di,pstring         ; Load address of string%@AE@%%@NL@%
  15623.   %@AS@%            mov     al,'z'             ; Load character to find%@AE@%%@NL@%
  15624.   %@AS@%            repne   scasb              ; Search%@AE@%%@NL@%
  15625.   %@AS@%            jnz     notfound           ; CX is 0 if not found%@AE@%%@NL@%
  15626.   %@AS@%            .                          ; ES:DI points to character%@AE@%%@NL@%
  15627.   %@AS@%            .                          ;   after first 'z'%@AE@%%@NL@%
  15628.   %@AS@%            .%@AE@%%@NL@%
  15629.   %@AS@%notfound:                              ; Special case for not found%@AE@%%@NL@%
  15630. %@NL@%
  15631. %@4@%%@CR:IX16.41     @%%@CR:IX16.42     @%  This example assumes that ES is not the same as DS, but that the address%@EH@%
  15632.   of the string is stored in a pointer variable. The %@AB@%LES%@AE@% instruction is used
  15633.   to load the far address of the string into %@AB@%ES:DI%@AE@%.%@NL@%
  15634. %@NL@%
  15635. %@NL@%
  15636. %@2@%%@CR:SC16.4      @%%@AB@%16.4  Comparing Strings%@AE@%%@EH@%%@NL@%
  15637. %@NL@%
  15638. %@4@%%@CR:IX16.43     @%%@CR:IX16.44     @%%@CR:IX16.45     @%%@CR:IX16.46     @%  The %@AB@%CMPS%@AE@% instruction is used to compare two strings and point to the%@EH@%
  15639.   address where a match or nonmatch occurs.%@NL@%
  15640. %@NL@%
  15641. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15642. %@NL@%
  15643. %@4@%  [[%@AB@%REPE%@AE@% | %@AB@%REPNE%@AE@%]] %@AB@%CMPS%@AE@% [[%@AI@%segmentregister%@AE@%%@AB@%:%@AE@%]]%@AI@%source%@AE@%%@AB@%,%@AE@%[[%@AB@%ES:%@AE@%]]%@AB@%,%@AE@%%@AI@%destination%@AE@%%@EH@%%@NL@%
  15644.   [[%@AB@%REPE%@AE@% | %@AB@%REPNE%@AE@%]] %@AB@%CMPSB%@AE@%%@NL@%
  15645.   [[%@AB@%REPE%@AE@% | %@AB@%REPNE%@AE@%]] %@AB@%CMPSW%@AE@%%@NL@%
  15646. %@NL@%
  15647. %@4@%  The count and the addresses of the strings are loaded into registers, as%@EH@%
  15648.   described in Section 16.1%@BO:       d1f06@%, "Setting Up String Operations." Either string
  15649.   can be considered the destination or source string unless a segment
  15650.   override is used. Notice that unlike other instructions, %@AB@%CMPS%@AE@% requires
  15651.   that the source be on the left.%@NL@%
  15652. %@NL@%
  15653. %@4@%  The %@AB@%CMPS%@AE@% instruction works by comparing, in turn, each value pointed to by%@EH@%
  15654.   DI with the value pointed to by SI. If the values are the same, the zero
  15655.   flag is set. Thus, the instruction makes sense only when used with one of
  15656.   the repeat prefixes that checks the zero flag.%@NL@%
  15657. %@NL@%
  15658. %@4@%%@CR:IX16.47     @%%@CR:IX16.48     @%%@CR:IX16.49     @%%@CR:IX16.50     @%  If you want to search for the first match between the strings, use the%@EH@%
  15659.   %@AB@%REPNE%@AE@% or %@AB@%REPNZ%@AE@% instruction. If a match is found, ES:DI and DS:SI will
  15660.   point to the position after the first match in the respective strings. You
  15661.   can decrement DI or SI to point to the match. (Conversely, you would
  15662.   increment DI or SI if the direction flag was set.)%@NL@%
  15663. %@NL@%
  15664. %@4@%%@CR:IX16.51     @%%@CR:IX16.52     @%%@CR:IX16.53     @%%@CR:IX16.54     @%  If you want to search for a nonmatch, use %@AB@%REPE%@AE@% or %@AB@%REPZ%@AE@%. If a nonmatch is%@EH@%
  15665.   found, ES:DI and DS:SI will point to the position after the first nonmatch
  15666.   in the respective strings. You can decrement DI or SI to point to the
  15667.   nonmatch.%@NL@%
  15668. %@NL@%
  15669. %@4@%%@CR:IX16.55     @%  After a %@AB@%REPNE CMPS%@AE@%, the zero flag will be cleared if no match was found.%@EH@%
  15670.   After a %@AB@%REPE CMPS%@AE@%, the zero flag will be set if no nonmatch was found.%@NL@%
  15671. %@NL@%
  15672. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  15673. %@NL@%
  15674.   %@AS@%            .MODEL  large%@AE@%%@NL@%
  15675.   %@AS@%            .DATA%@AE@%%@NL@%
  15676.   %@AS@%string1     DB      "The quick brown fox jumps over the lazy dog"%@AE@%%@NL@%
  15677.   %@AS@%            .FARDATA%@AE@%%@NL@%
  15678.   %@AS@%string2     DB      "The quick brown dog jumps over the lazy fox"%@AE@%%@NL@%
  15679.   %@AS@%lstring     EQU     $-string2%@AE@%%@NL@%
  15680.   %@AS@%            .CODE%@AE@%%@NL@%
  15681.   %@AS@%            mov     ax,@data           ; Load data segment%@AE@%%@NL@%
  15682.   %@AS@%            mov     ds,ax              ;   into DS%@AE@%%@NL@%
  15683.   %@AS@%            mov     ax,@fardata        ; Load far data segment%@AE@%%@NL@%
  15684.   %@AS@%            mov     es,ax              ;   into ES%@AE@%%@NL@%
  15685.   %@AS@%            .%@AE@%%@NL@%
  15686.   %@AS@%            .%@AE@%%@NL@%
  15687.   %@AS@%            .%@AE@%%@NL@%
  15688.   %@AS@%            cld                        ; Work upward%@AE@%%@NL@%
  15689.   %@AS@%            mov     cx,lstring         ; Load length of string%@AE@%%@NL@%
  15690.   %@AS@%            mov     si,OFFSET string1  ; Load offset of string1%@AE@%%@NL@%
  15691.   %@AS@%            mov     di,OFFSET string2  ; Load offset of string2%@AE@%%@NL@%
  15692.   %@AS@%            repe    cmpsb              ; Compare%@AE@%%@NL@%
  15693.   %@AS@%            jnz     allmatch           ; CX is 0 if no nonmatch%@AE@%%@NL@%
  15694.   %@AS@%            dec     si                 ; Adjust to point to nonmatch%@AE@%%@NL@%
  15695.   %@AS@%            dec     di                 ;   in each string%@AE@%%@NL@%
  15696.   %@AS@%            .%@AE@%%@NL@%
  15697.   %@AS@%            .%@AE@%%@NL@%
  15698.   %@AS@%allmatch:   .                          ; Special case for all match%@AE@%%@NL@%
  15699. %@NL@%
  15700. %@4@%  This example assumes that the strings are in different segments. Both%@EH@%
  15701.   segments must be initialized to the appropriate segment register.%@NL@%
  15702. %@NL@%
  15703. %@NL@%
  15704. %@2@%%@CR:SC16.5      @%%@AB@%16.5  Filling Strings%@AE@%%@EH@%%@NL@%
  15705. %@NL@%
  15706. %@4@%%@CR:IX16.56     @%%@CR:IX16.57     @%%@CR:IX16.58     @%  The %@AB@%STOS%@AE@% instruction is used to store a specified value in each position%@EH@%
  15707.   of a string.%@NL@%
  15708. %@NL@%
  15709. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15710. %@NL@%
  15711. %@4@%  [[%@AB@%REP%@AE@%]]%@AB@% STOS %@AE@%[[%@AB@%ES:%@AE@%]]%@AI@%destination%@AE@%%@EH@%%@NL@%
  15712.   [[%@AB@%REP%@AE@%]]%@AB@% STOSB%@AE@%%@NL@%
  15713.   [[%@AB@%REP%@AE@%]]%@AB@% STOSW%@AE@%%@NL@%
  15714. %@NL@%
  15715. %@4@%  The string is considered the destination, so it must be pointed to by%@EH@%
  15716.   ES:DI. The length and address of the string must be loaded into registers,
  15717.   as described in Section 16.1%@BO:       d1f06@%, "Setting Up String Operations." The value
  15718.   to store must be in the accumulator register──AL for bytes, AX for words.%@NL@%
  15719. %@NL@%
  15720. %@4@%%@CR:IX16.59     @%%@CR:IX16.60     @%  For each iteration specified by the %@AB@%REP%@AE@% instruction prefix, the value in%@EH@%
  15721.   the accumulator is loaded into the string.%@NL@%
  15722. %@NL@%
  15723. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  15724. %@NL@%
  15725.   %@AS@%            .MODEL  small%@AE@%%@NL@%
  15726.   %@AS@%            .DATA%@AE@%%@NL@%
  15727.   %@AS@%destin      DB      100 DUP ?%@AE@%%@NL@%
  15728.   %@AS@%            .CODE%@AE@%%@NL@%
  15729.   %@AS@%            .                          ; Assume ES = DS%@AE@%%@NL@%
  15730.   %@AS@%            .%@AE@%%@NL@%
  15731.   %@AS@%            .%@AE@%%@NL@%
  15732.   %@AS@%            cld                        ; Work upward%@AE@%%@NL@%
  15733.   %@AS@%            mov     ax,'aa'            ; Load character to fill%@AE@%%@NL@%
  15734.   %@AS@%            mov     cx,50              ; Load length of string%@AE@%%@NL@%
  15735.   %@AS@%            mov     di,OFFSET destin   ; Load address of destination%@AE@%%@NL@%
  15736.   %@AS@%            rep     stosw              ; Store 'a' into array%@AE@%%@NL@%
  15737. %@NL@%
  15738. %@4@%  This example loads 100 bytes containing the character %@AS@%'a'%@AE@%. Notice that%@EH@%
  15739.   this is done by storing 50 words rather than 100 bytes. This makes the
  15740.   code faster by reducing the number of iterations. You would have to adjust
  15741.   for the last byte if you wanted to fill an odd number of bytes.%@NL@%
  15742. %@NL@%
  15743. %@NL@%
  15744. %@2@%%@CR:SC16.6      @%%@AB@%16.6  Loading Values from Strings%@AE@%%@EH@%%@NL@%
  15745. %@NL@%
  15746. %@4@%%@CR:IX16.61     @%%@CR:IX16.62     @%%@CR:IX16.63     @%%@CR:IX16.64     @%  The %@AB@%LODS%@AE@% instruction is used to load a value from a string into a%@EH@%
  15747.   register.%@NL@%
  15748. %@NL@%
  15749. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15750. %@NL@%
  15751. %@4@%  %@AB@%LODS%@AE@% [[%@AI@%segmentregister%@AE@%%@AB@%:%@AE@%]]%@AI@%source%@AE@%%@EH@%%@NL@%
  15752.   %@AB@%LODSB%@AE@%%@NL@%
  15753.   %@AB@%LODSW%@AE@%%@NL@%
  15754. %@NL@%
  15755. %@4@%  The string is considered the source, so it must be pointed to by DS:SI.%@EH@%
  15756.   The value is always loaded from the string into the accumulator
  15757.   register──AL for bytes, AX for words.%@NL@%
  15758. %@NL@%
  15759. %@4@%  Unlike other string instructions, %@AB@%LODS%@AE@% is not normally used with a repeat%@EH@%
  15760.   prefix since there is no reason to move a value repeatedly to a register.
  15761.   However, %@AB@%LODS%@AE@% does adjust the SI register as specified by the direction
  15762.   flag and the size of operands. The programmer must code the instructions
  15763.   to use the value after it is loaded.%@NL@%
  15764. %@NL@%
  15765. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  15766. %@NL@%
  15767.   %@AS@%            .DATA%@AE@%%@NL@%
  15768.   %@AS@%stuff       DB      0,1,2,3,4,5,6,7,8,9%@AE@%%@NL@%
  15769.   %@AS@%            .CODE%@AE@%%@NL@%
  15770.   %@AS@%            .%@AE@%%@NL@%
  15771.   %@AS@%            .%@AE@%%@NL@%
  15772.   %@AS@%            .%@AE@%%@NL@%
  15773.   %@AS@%            cld                          ; Work upward%@AE@%%@NL@%
  15774.   %@AS@%            mov     cx,10                ; Load length%@AE@%%@NL@%
  15775.   %@AS@%            mov     si,OFFSET stuff      ; Load offset of source%@AE@%%@NL@%
  15776.   %@AS@%            mov     ah,2                 ; Display character function%@AE@%%@NL@%
  15777.   %@AS@%get:        lodsb                        ; Get a character%@AE@%%@NL@%
  15778.   %@AS@%            add     al,'0'               ; Convert to ASCII%@AE@%%@NL@%
  15779.   %@AS@%            mov     dl,al                ; Move to DL%@AE@%%@NL@%
  15780.   %@AS@%            int     21h                  ; Call DOS to display character%@AE@%%@NL@%
  15781.   %@AS@%            loop    get                  ; Repeat%@AE@%%@NL@%
  15782. %@NL@%
  15783. %@4@%  Example 1 loads, processes, and displays each byte in a string of bytes.%@EH@%%@NL@%
  15784. %@NL@%
  15785. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  15786. %@NL@%
  15787.   %@AS@%            .DATA%@AE@%%@NL@%
  15788.   %@AS@%buffer      DB      80 DUP(?)            ; Create buffer for argument string%@AE@%%@NL@%
  15789.   %@AS@%            .CODE%@AE@%%@NL@%
  15790.   %@AS@%start:      mov     ax,@data             ; Initialize DS%@AE@%%@NL@%
  15791.   %@AS@%            mov     ds,ax%@AE@%%@NL@%
  15792.   %@AS@%                                         ; On start-up ES points to PSP%@AE@%%@NL@%
  15793.   %@AS@%            cld                          ; Work upward%@AE@%%@NL@%
  15794.   %@AS@%            mov     cl,BYTE PTR es:[80h] ; Load length of arguments%@AE@%%@NL@%
  15795.   %@AS@%            xor     ch,ch%@AE@%%@NL@%
  15796.   %@AS@%            mov     di,OFFSET buffer     ; Load offset of buffer%@AE@%%@NL@%
  15797.   %@AS@%            mov     si,82h               ; Load position of argument string%@AE@%%@NL@%
  15798.   %@AS@%            mov     dx,es                ; Exchange ES and DS%@AE@%%@NL@%
  15799.   %@AS@%            mov     ax,ds%@AE@%%@NL@%
  15800.   %@AS@%            mov     es,ax%@AE@%%@NL@%
  15801.   %@AS@%            mov     ds,dx%@AE@%%@NL@%
  15802.   %@AS@%another:    lodsb                        ; Get a character%@AE@%%@NL@%
  15803.   %@AS@%            cmp     al,'a'               ; Is it high enough to be upper?%@AE@%%@NL@%
  15804.   %@AS@%            jb      noway                ; No? Check%@AE@%%@NL@%
  15805.   %@AS@%            cmp     al,'z'               ; Is it low enough to be letter?%@AE@%%@NL@%
  15806.   %@AS@%            ja      noway%@AE@%%@NL@%
  15807.   %@AS@%            sub     al,32                ; Yes? Convert to uppercase%@AE@%%@NL@%
  15808. %@NL@%
  15809.   %@AS@%noway:      stosb%@AE@%%@NL@%
  15810.   %@AS@%            loop    another              ; Repeat%@AE@%%@NL@%
  15811.   %@AS@%            mov     dx,es                ; Restore ES and DS%@AE@%%@NL@%
  15812.   %@AS@%            mov     ax,ds%@AE@%%@NL@%
  15813.   %@AS@%            mov     es,ax%@AE@%%@NL@%
  15814.   %@AS@%            mov     ds,dx%@AE@%%@NL@%
  15815. %@NL@%
  15816. %@4@%  Example 2 copies the command arguments from position 82H in the DOS%@EH@%
  15817.   Program Segment Prefix (PSP) while converting them to uppercase. See the
  15818.   %@AI@%Microsoft%@AE@% %@AI@%MS-DOS%@AE@% %@AI@%Programmer's%@AE@% %@AI@%Reference%@AE@% or one of the many other books on
  15819.   DOS for information about the PSP. Notice that both %@AB@%LODSB%@AE@% and %@AB@%STOSB%@AE@% are
  15820.   used without repeat prefixes.%@NL@%
  15821. %@NL@%
  15822. %@NL@%
  15823. %@2@%%@CR:SC16.7      @%%@AB@%16.7  Transferring Strings to and from Ports%@AE@%%@EH@%%@NL@%
  15824. %@NL@%
  15825. %@4@%  %@AB@%80186/286/386 Only%@AE@%%@EH@%%@NL@%
  15826. %@NL@%
  15827. %@4@%%@CR:IX16.65     @%%@CR:IX16.66     @%%@CR:IX16.67     @%%@CR:IX16.68     @%%@CR:IX16.69     @%%@CR:IX16.70     @%%@CR:IX16.71     @%  The %@AB@%INS%@AE@% instruction reads a string from a port to memory, and the %@AB@%OUTS%@AE@%%@EH@%
  15828.   instruction writes a string from memory to a port.%@NL@%
  15829. %@NL@%
  15830. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  15831. %@NL@%
  15832. %@4@%  %@AB@%OUTS DX%@AE@%%@AB@%,%@AE@%[[%@AI@%segmentregister%@AE@%%@AB@%:%@AE@%]]%@AI@%source%@AE@%%@EH@%%@NL@%
  15833.   %@AB@%OUTSB%@AE@%%@NL@%
  15834.   %@AB@%OUTSW%@AE@%%@NL@%
  15835. %@NL@%
  15836.   %@AB@%INS%@AE@% [[%@AB@%ES:%@AE@%]]%@AI@%destination%@AE@%%@AB@%,%@AE@%%@AB@%DX%@AE@%%@NL@%
  15837.   %@AB@%INSB%@AE@%%@NL@%
  15838.   %@AB@%INSW%@AE@%%@NL@%
  15839. %@NL@%
  15840. %@4@%  The %@AB@%INS%@AE@% and %@AB@%OUTS%@AE@% instructions require that the number of the port be in%@EH@%
  15841.   DX. The port cannot be specified as an immediate value, as it can be with
  15842.   %@AB@%IN%@AE@% and %@AB@%OUT%@AE@%.%@NL@%
  15843. %@NL@%
  15844. %@4@%  To move the data, load the count into CX. The string to be transferred by%@EH@%
  15845.   %@AB@%INS%@AE@% is considered the destination string, so it must be pointed to by
  15846.   ES:DI. The string to be transferred by %@AB@%OUTS%@AE@% is considered the source
  15847.   string, so it must be pointed to by DS:SI.%@NL@%
  15848. %@NL@%
  15849. %@4@%  If you specify the source or destination as an operand, DX must be%@EH@%
  15850.   specified. Otherwise, DX is assumed and should be omitted.%@NL@%
  15851. %@NL@%
  15852. %@4@%%@CR:IX16.72     @%%@CR:IX16.73     @%  If you need to process the string as it is transferred (for instance, to%@EH@%
  15853.   check for the end of a null-terminated string), you must set up the loop
  15854.   yourself instead of using the %@AB@%REP%@AE@% instruction prefix.%@NL@%
  15855. %@NL@%
  15856. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  15857. %@NL@%
  15858.   %@AS@%            .DATA%@AE@%%@NL@%
  15859.   %@AS@%count       EQU     100%@AE@%%@NL@%
  15860.   %@AS@%buffer      DB      count DUP (?)%@AE@%%@NL@%
  15861.   %@AS@%inport      DW      ?%@AE@%%@NL@%
  15862.   %@AS@%            .CODE%@AE@%%@NL@%
  15863.   %@AS@%            .                          ; Assume ES = DS%@AE@%%@NL@%
  15864.   %@AS@%            .%@AE@%%@NL@%
  15865.   %@AS@%            .%@AE@%%@NL@%
  15866.   %@AS@%            cld                        ; Work upward%@AE@%%@NL@%
  15867.   %@AS@%            mov     cx,count           ; Load length to transfer%@AE@%%@NL@%
  15868.   %@AS@%            mov     di,OFFSET buffer   ; Load address of destination%@AE@%%@NL@%
  15869.   %@AS@%            mov     dx,inport          ; Load port number%@AE@%%@NL@%
  15870.   %@AS@%            rep     insb               ; Transfer the string%@AE@%%@NL@%
  15871.   %@AS@%                                       ;   from port to buffer%@AE@%%@NL@%
  15872. %@NL@%
  15873. %@NL@%
  15874. %@NL@%
  15875. ────────────────────────────────────────────────────────────────────────────%@NL@%
  15876. %@1@%%@CR:CH17        @%%@AB@%Chapter 17:  Calculating with a Math Coprocessor%@AE@%%@EH@%%@NL@%
  15877. %@NL@%
  15878. %@NL@%
  15879. %@4@%  The 8087-family coprocessors are used to do fast mathematical%@EH@%
  15880.   calculations. When used with real numbers, packed binary coded decimal
  15881.   (BCD) numbers, or long integers, they do calculations many times faster
  15882.   than the same operations done with 8086-family processors.%@NL@%
  15883. %@NL@%
  15884. %@4@%  This chapter explains how to use the 8087-family processors to transfer%@EH@%
  15885.   and process data. The approach taken is from an applications standpoint.
  15886.   Features that would be used by systems programmers (such the flags used
  15887.   when writing exception handlers) are not explained. This chapter is
  15888.   intended as a reference, not a tutorial.%@NL@%
  15889. %@NL@%
  15890.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15891.   %@AB@%NOTE%@AE@%  This manual does not attempt to explain the mathematical concepts
  15892.   involved in using certain coprocessor features. It assumes that you will
  15893.   not need to use a feature unless you understand the mathematics involved.
  15894.   For example, you need to understand logarithms to use the %@AB@%FYL2X %@AE@%and
  15895.   %@AB@%FYL2XP1 %@AE@%instructions.%@NL@%
  15896.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  15897. %@NL@%
  15898. %@NL@%
  15899. %@2@%%@CR:SC17.1      @%%@AB@%17.1  Coprocessor Architecture%@AE@%%@EH@%%@NL@%
  15900. %@NL@%
  15901. %@4@%%@CR:IX17.1      @%%@CR:IX17.2      @%  The math coprocessor works simultaneously with the main processor.%@EH@%
  15902.   However, since the coprocessor cannot handle device input or output, most
  15903.   data originates in the main processor.%@NL@%
  15904. %@NL@%
  15905. %@4@%  The main processor and the coprocessor have their own registers, which are%@EH@%
  15906.   completely separate and inaccessible to the other. They exchange data
  15907.   through memory, since memory is available to both.%@NL@%
  15908. %@NL@%
  15909. %@4@%  Ordinarily you follow these three steps when using the coprocessor:%@EH@%%@NL@%
  15910. %@NL@%
  15911.   1. Load data from memory to coprocessor registers.%@NL@%
  15912. %@NL@%
  15913.   2. Process the data.%@NL@%
  15914. %@NL@%
  15915.   3. Store the data from coprocessor registers back to memory.%@NL@%
  15916. %@NL@%
  15917. %@4@%  Step 2, processing the data, can occur while the main processor is%@EH@%
  15918.   handling other tasks. Steps 1 and 3 must be coordinated with the main
  15919.   processor so that the processor and coprocessor do not try to access the
  15920.   same memory at the same time, as explained in Section 17.5%@BO:       dedf8@%, "Transferring
  15921.   Data."%@NL@%
  15922. %@NL@%
  15923. %@NL@%
  15924. %@3@%%@CR:SC17.1.1    @%%@AB@%17.1.1  Coprocessor Data Registers%@AE@%%@EH@%%@NL@%
  15925. %@NL@%
  15926. %@4@%%@CR:IX17.3      @%  The 8087-family coprocessors have eight 80-bit data registers. Unlike%@EH@%
  15927.   8086-family registers, the coprocessor data registers are organized as a
  15928.   stack. As data is pushed into the top register, previous data items move
  15929.   into higher-numbered registers. Register 0 is the top of the stack;
  15930.   register 7 is the bottom. The syntax for specifying registers is shown
  15931.   below:%@NL@%
  15932. %@NL@%
  15933. %@4@%  %@AB@%ST%@AE@%[[(%@AI@%number%@AE@%)]]%@EH@%%@NL@%
  15934. %@NL@%
  15935. %@4@%  The %@AI@%number%@AE@% must be a digit between 0 and 7, or a constant expression that%@EH@%
  15936.   evaluates to a number from 0 to 7. If %@AI@%number%@AE@% is omitted, register 0 (top
  15937.   of stack) is assumed.%@NL@%
  15938. %@NL@%
  15939. %@4@%%@CR:IX17.4      @%%@CR:IX17.5      @%  All coprocessor data is stored in registers in the temporary-real format.%@EH@%
  15940.   This is the 10-byte IEEE format described in Section 6.5.1.4%@BO:       62baf@%,
  15941.   "Real-Number Variables." The registers and the register format are shown
  15942.   in Figure 17.1.%@NL@%
  15943. %@NL@%
  15944.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  15945.   │ This figure can be found in Section 17.1.1 of the manual               │%@NL@%
  15946.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  15947. %@NL@%
  15948. %@4@%  Internally, all calculations are done on numbers of the same type. Since%@EH@%
  15949.   temporary-real numbers have the greatest precision, lower-precision
  15950.   numbers are guaranteed not to lose precision as a result of calculations.
  15951.   The instructions that transfer values between the main processor and the
  15952.   coprocessor automatically convert numbers to and from the temporary-real
  15953.   format.%@NL@%
  15954. %@NL@%
  15955. %@NL@%
  15956. %@3@%%@CR:SC17.1.2    @%%@AB@%17.1.2  Coprocessor Control Registers%@AE@%%@EH@%%@NL@%
  15957. %@NL@%
  15958. %@4@%%@CR:IX17.6      @%  The 8087-family coprocessors have seven 16-bit control registers. The most%@EH@%
  15959.   useful control registers are made up of bit fields or flags. Some flags
  15960.   control coprocessor operations, while others maintain the current status
  15961.   of the coprocessor. In this sense, they are much like the 8086-family
  15962.   flags registers.%@NL@%
  15963. %@NL@%
  15964. %@4@%  You do not need to understand these registers to do most coprocessor%@EH@%
  15965.   operations. Control flags are set by default to the values appropriate for
  15966.   most programs. Errors and exceptions are reported in the status-word
  15967.   register. However, the coprocessor already has a default system for
  15968.   handling exceptions. Applications programmers can usually accept the
  15969.   defaults. Systems programmers may want to use the status-word and
  15970.   control-word registers when writing exception handlers, but such problems
  15971.   are beyond the scope of this manual.%@NL@%
  15972. %@NL@%
  15973. %@4@%%@CR:IX17.7      @%%@CR:IX17.8      @%  Figure 17.2 shows the overall layout of the control registers, including%@EH@%
  15974.   the control word, status word, tag word, instruction pointer, and operand
  15975.   pointer. The format of each of the registers is not shown, since these
  15976.   registers are generally of use only to systems programmers. The exception
  15977.   is the condition-code bits of the status-word register. These bits are
  15978.   explained in Section 17.7%@BO:       e64cc@%, "Controlling Program Flow."%@NL@%
  15979. %@NL@%
  15980.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  15981.   │ This figure can be found in Section 17.1.2 of the manual               │%@NL@%
  15982.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  15983. %@NL@%
  15984. %@4@%  The control registers are explained in more detail in the on-line Help%@EH@%
  15985.   system.%@NL@%
  15986. %@NL@%
  15987. %@NL@%
  15988. %@2@%%@CR:SC17.2      @%%@AB@%17.2  Emulation%@AE@%%@EH@%%@NL@%
  15989. %@NL@%
  15990. %@4@%  You can write assembly-language procedures that use the emulator library%@EH@%
  15991.   when called from QuickC. First write the procedure by using coprocessor
  15992.   instructions, then assemble it using the /E option, and finally link it
  15993.   with your high-level-language modules. When compiling modules, use the
  15994.   compiler options that specify emulation.%@NL@%
  15995. %@NL@%
  15996. %@4@%  Some coprocessor instructions are not emulated by Microsoft emulation%@EH@%
  15997.   libraries. Which instructions are emulated varies depending on the
  15998.   language and version. If you use a coprocessor instruction that is not
  15999.   emulated, the program will generate a run-time error when it tries to
  16000.   execute the unemulated instruction. You cannot use a Microsoft emulation
  16001.   library with stand-alone assembler programs, since the library depends on
  16002.   the compiler start-up code.%@NL@%
  16003. %@NL@%
  16004. %@4@%  See Appendix B%@BO:       f653b@%, Section B.6%@BO:       f9a75@%, "Creating Code for a Floating-Point%@EH@%
  16005.   Emulator," for information on the /E option. See Appendix A%@BO:       ed697@%,
  16006.   "Mixed-Language Mechanics," for information on writing assembly-language
  16007.   procedures for high-level languages.%@NL@%
  16008. %@NL@%
  16009. %@NL@%
  16010. %@2@%%@CR:SC17.3      @%%@AB@%17.3  Using Coprocessor Instructions%@AE@%%@EH@%%@NL@%
  16011. %@NL@%
  16012. %@4@%  Coprocessor instructions are readily recognizable because, unlike all%@EH@%
  16013.   8086-family instruction mnemonics, they start with the letter %@AB@%F%@AE@%.%@NL@%
  16014. %@NL@%
  16015. %@4@%%@CR:IX17.9      @%  Most coprocessor instructions have two operands, but in many cases, one or%@EH@%
  16016.   both operands are implied. Often, one operand can be a memory operand; in
  16017.   this case, the other operand is always implied as the stack-top register.
  16018.   Coprocessor instructions can never have immediate operands, and with the
  16019.   exception of the %@AB@%FSTSW%@AE@% instruction (see Section 17.5.2%@BO:       e11e1@%, "Loading
  16020.   Constants"), they cannot have processor registers as operands. As with
  16021.   8086-family instructions, memory-to-memory operations are never allowed.
  16022.   One operand must be a coprocessor register.%@NL@%
  16023. %@NL@%
  16024. %@4@%  Instructions usually have a source and a destination operand. The source%@EH@%
  16025.   specifies one of the values to be processed. It is never changed by the
  16026.   operation. The destination specifies the value to be operated on and
  16027.   replaced with the result of the operation. If two operands are specified,
  16028.   the first is the destination and the second is the source.%@NL@%
  16029. %@NL@%
  16030. %@4@%%@CR:IX17.10     @%%@CR:IX17.11     @%  The stack organization of registers gives the programmer flexibility to%@EH@%
  16031.   think of registers either as elements on a stack or as registers much like
  16032.   8086-family registers. Table 17.1 lists the variations of coprocessor
  16033.   instructions along with the syntax for each.%@NL@%
  16034. %@NL@%
  16035.   %@AB@%Table 17.1 Coprocessor Operand Forms%@AE@%%@NL@%
  16036. %@NL@%
  16037.   %@AB@%Instruction Form%@AE@%  %@AB@%Implied Syntax%@AE@%    %@AB@%Operands%@AE@%      %@AB@%Example%@AE@%%@NL@%
  16038.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16039.   Classical-stack   %@AB@%F%@AE@%%@AI@%action%@AE@%           ST(1), ST     %@AS@%fadd%@AE@%%@NL@%
  16040. %@NL@%
  16041.   Memory            %@AB@%F%@AE@%%@AI@%action%@AE@% %@AI@%memory%@AE@%    ST            %@AS@%fadd memloc%@AE@%%@NL@%
  16042. %@NL@%
  16043.   Register          %@AB@%F%@AE@%%@AI@%action%@AE@%%@AB@% ST(%@AE@%%@AI@%num%@AE@%%@AB@%),%@AE@%  %@AS@%fadd st(5),st%@AE@% F%@AI@%action%@AE@%%@AB@% ST, ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%
  16044.                     %@AB@%ST%@AE@%                              %@AS@%fadd st,st(3)%@AE@%%@NL@%
  16045. %@NL@%
  16046.   Register pop      %@AB@%F%@AE@%%@AI@%action%@AE@%%@AB@%P ST(%@AE@%%@AI@%num%@AE@%%@AB@%),%@AE@%               %@AS@%faddp st(4),st%@AE@%
  16047.                     %@AB@%ST%@AE@%%@NL@%
  16048.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16049. %@NL@%
  16050. %@NL@%
  16051. %@4@%  Not all instructions accept all operand variations. For example, load and%@EH@%
  16052.   store instructions always require the memory form. Load-constant
  16053.   instructions always take the classical-stack form. Arithmetic instructions
  16054.   can usually take any form.%@NL@%
  16055. %@NL@%
  16056. %@4@%  Some instructions that accept the memory form can have the letter %@AB@%I%@AE@%%@EH@%
  16057.   (integer) or %@AB@%B%@AE@% (BCD) following the initial %@AB@%F%@AE@% to specify how a memory
  16058.   operand is to be interpreted. For example, %@AB@%FILD%@AE@% interprets its operand as
  16059.   an integer and %@AB@%FBLD%@AE@% interprets its operand as a BCD number. If no type
  16060.   letter is included in the instruction name, the instruction works on real
  16061.   numbers.%@NL@%
  16062. %@NL@%
  16063. %@NL@%
  16064. %@3@%%@CR:SC17.3.1    @%%@AB@%17.3.1  Using Implied Operands in the Classical-Stack Form%@AE@%%@EH@%%@NL@%
  16065. %@NL@%
  16066. %@4@%%@CR:IX17.12     @%%@CR:IX17.13     @%%@CR:IX17.14     @%%@CR:IX17.15     @%%@CR:IX17.16     @%%@CR:IX17.17     @%  The classical-stack form treats coprocessor registers like items on a%@EH@%
  16067.   stack. Items are pushed onto or popped off the top elements of the stack.
  16068.   Since only the top item can be accessed on a traditional stack, there is
  16069.   no need to specify operands. The first register (and the second if there
  16070.   are two operands) is always assumed.%@NL@%
  16071. %@NL@%
  16072. %@4@%  In arithmetic operations (see Section 17.6%@BO:       e24a3@%), the top of the stack (ST) is%@EH@%
  16073.   the source operand, and the second register (ST(1)) is the destination.
  16074.   The result of the operation goes into the destination operand, and the
  16075.   source is popped off the stack. The effect is that both of the values used
  16076.   in the operation are destroyed and the result is left at the top of the
  16077.   stack.%@NL@%
  16078. %@NL@%
  16079. %@4@%  Instructions that load constants always use the stack form (see Section%@EH@%
  16080.   17.5.1%@BO:       defb7@%, "Transferring Data to and from Registers"). In this case, the
  16081.   constant created by the instruction is the implied source, and the top of
  16082.   the stack (ST) is the destination. The source is pushed into the
  16083.   destination.%@NL@%
  16084. %@NL@%
  16085. %@4@%  Note that the classical-stack form with its implied operands is similar to%@EH@%
  16086.   the register-pop form, not to the register form. For example, %@AS@%fadd%@AE@%, with
  16087.   the implied operands ST(1),ST, is equivalent to %@AS@%faddp st(1),st%@AE@%, rather
  16088.   than to %@AS@%fadd st(1),st%@AE@%.%@NL@%
  16089. %@NL@%
  16090. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  16091. %@NL@%
  16092.   %@AS@%            fld1               ; Push 1 into first position%@AE@%%@NL@%
  16093.   %@AS@%            fldpi              ; Push pi into first position%@AE@%%@NL@%
  16094.   %@AS@%            fadd               ; Add pi and 1 and pop%@AE@%%@NL@%
  16095. %@NL@%
  16096. %@4@%%@CR:IX17.18     @%  The status of the register stack after each instruction is shown below:%@EH@%%@NL@%
  16097. %@NL@%
  16098.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  16099.   │ This figure can be found in Section 17.3.1 of the manual               │%@NL@%
  16100.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  16101. %@NL@%
  16102. %@NL@%
  16103. %@3@%%@CR:SC17.3.2    @%%@AB@%17.3.2  Using Memory Operands%@AE@%%@EH@%%@NL@%
  16104. %@NL@%
  16105. %@4@%%@CR:IX17.19     @%  The memory form treats coprocessor registers like items on a stack. Items%@EH@%
  16106.   are pushed from memory onto the top element of the stack, or popped from
  16107.   the top element to memory. Since only the top item can be accessed on a
  16108.   traditional stack, there is no need to specify the stack operand. The top
  16109.   register (ST) is always assumed. However, the memory operand must be
  16110.   specified.%@NL@%
  16111. %@NL@%
  16112. %@4@%  Memory operands can be used in load and store instructions (see Section%@EH@%
  16113.   17.5.1%@BO:       defb7@%, "Transferring Data to and from Registers"). Load instructions
  16114.   push source values from memory to an implied destination register (ST).
  16115.   Store instructions pop source values from an implied source register (ST)
  16116.   to the destination in memory. Some versions of store instructions pop the
  16117.   register stack so that the source is destroyed. Others simply copy the
  16118.   source without changing the stack.%@NL@%
  16119. %@NL@%
  16120. %@4@%  Memory operands can also be used in calculation instructions that operate%@EH@%
  16121.   on two values (see Section 17.6%@BO:       e24a3@%, "Doing Arithmetic Calculations"). The
  16122.   memory operand is always the source. The stack top (ST) is always the
  16123.   implied destination. The result of the operation replaces the destination
  16124.   without changing its stack position.%@NL@%
  16125. %@NL@%
  16126. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  16127. %@NL@%
  16128.   %@AS@%            .DATA%@AE@%%@NL@%
  16129.   %@AS@%m1          DD      1.0%@AE@%%@NL@%
  16130.   %@AS@%m2          DD      2.0%@AE@%%@NL@%
  16131.   %@AS@%            .CODE%@AE@%%@NL@%
  16132.   %@AS@%            .%@AE@%%@NL@%
  16133.   %@AS@%            .%@AE@%%@NL@%
  16134.   %@AS@%            .%@AE@%%@NL@%
  16135.   %@AS@%            fld     m1         ; Push m1 into first position%@AE@%%@NL@%
  16136.   %@AS@%            fld     m2         ; Push m2 into first position%@AE@%%@NL@%
  16137.   %@AS@%            fadd    m1         ; Add m2 to first position%@AE@%%@NL@%
  16138.   %@AS@%            fstp    m1         ; Pop first position into m1%@AE@%%@NL@%
  16139.   %@AS@%            fst     m2         ; Copy first position to m2%@AE@%%@NL@%
  16140. %@NL@%
  16141. %@4@%%@CR:IX17.20     @%  The status of the register stack and the memory locations used in the%@EH@%
  16142.   instructions is shown below:%@NL@%
  16143. %@NL@%
  16144.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  16145.   │ This figure can be found in Section 17.3.2 of the manual               │%@NL@%
  16146.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  16147. %@NL@%
  16148. %@NL@%
  16149. %@3@%%@CR:SC17.3.3    @%%@AB@%17.3.3  Specifying Operands in the Register Form%@AE@%%@EH@%%@NL@%
  16150. %@NL@%
  16151. %@4@%%@CR:IX17.21     @%  The register form treats coprocessor registers as traditional registers.%@EH@%
  16152.   Registers are specified the same as 8086-family instructions with two
  16153.   register operands. The only limitation is that one of the two registers
  16154.   must be the stack top (ST).%@NL@%
  16155. %@NL@%
  16156. %@4@%  In the register form, operands are specified by name. The second operand%@EH@%
  16157.   is the source; it is not affected by the operation. The first operand is
  16158.   the destination; its value is replaced with the result of the operation.
  16159.   The stack position of the operands does not change.%@NL@%
  16160. %@NL@%
  16161. %@4@%  The register form can only be used with the %@AB@%FXCH%@AE@% instruction and with%@EH@%
  16162.   arithmetic instructions that do calculations on two values. With the %@AB@%FXCH%@AE@%
  16163.   instruction, the stack top is implied and need not be specified.%@NL@%
  16164. %@NL@%
  16165. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  16166. %@NL@%
  16167.   %@AS@%            fadd    st(1),st   ; Add second position to first -%@AE@%%@NL@%
  16168.   %@AS@%                               ;   result goes in second position%@AE@%%@NL@%
  16169.   %@AS@%            fadd    st,st(2)   ; Add first position to second -%@AE@%%@NL@%
  16170.   %@AS@%                               ;   result goes in first position%@AE@%%@NL@%
  16171.   %@AS@%            fxch    st(1)      ; Exchange first and second positions%@AE@%%@NL@%
  16172. %@NL@%
  16173. %@4@%%@CR:IX17.22     @%  The status of the register stack if the registers were previously%@EH@%
  16174.   initialized to 1.0, 2.0, and 3.0 is shown below:%@NL@%
  16175. %@NL@%
  16176.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  16177.   │ This figure can be found in Section 17.3.3 of the manual               │%@NL@%
  16178.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  16179. %@NL@%
  16180. %@NL@%
  16181. %@3@%%@CR:SC17.3.4    @%%@AB@%17.3.4  Specifying Operands in the Register-Pop Form%@AE@%%@EH@%%@NL@%
  16182. %@NL@%
  16183. %@4@%%@CR:IX17.23     @%  The register-pop form treats coprocessor registers as a modified stack.%@EH@%
  16184.   This form has some of the aspects of both a stack and registers. The
  16185.   destination register can be specified by name, but the source register
  16186.   must always be the stack top.%@NL@%
  16187. %@NL@%
  16188. %@4@%  The result of the operation will be placed in the destination operand, and%@EH@%
  16189.   the stack top will be popped off the stack. The effect is that both values
  16190.   being operated on will be destroyed and the result of the operation will
  16191.   be saved in the specified destination register. The register-pop form is
  16192.   only used for instructions that do calculations on two values.%@NL@%
  16193. %@NL@%
  16194. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  16195. %@NL@%
  16196.   %@AS@%            faddp   st(2),st   ; Add first and third positions and pop -%@AE@%%@NL@%
  16197.   %@AS@%                               ;   first position destroyed%@AE@%%@NL@%
  16198.   %@AS@%                               ;   third moves to second and holds result%@AE@%%@NL@%
  16199. %@NL@%
  16200. %@4@%%@CR:IX17.24     @%  The status of the register stack if the registers were already initialized%@EH@%
  16201.   to 1.0, 2.0, and 3.0 is shown below:%@NL@%
  16202. %@NL@%
  16203.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  16204.   │ This figure can be found in Section 17.3.4 of the manual               │%@NL@%
  16205.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  16206. %@NL@%
  16207. %@NL@%
  16208. %@2@%%@CR:SC17.4      @%%@AB@%17.4  Coordinating Memory Access%@AE@%%@EH@%%@NL@%
  16209. %@NL@%
  16210. %@4@%%@CR:IX17.25     @%  Problems of coordinating memory access can occur when the coprocessor and%@EH@%
  16211.   the main processor both try to access a memory location at the same time.
  16212.   Since the processor and coprocessor work independently, they may not
  16213.   finish working on memory in the order in which you give instructions.
  16214.   There are two separate cases, and they are handled in different ways.%@NL@%
  16215. %@NL@%
  16216. %@4@%  In the first case, if a processor instruction is given and then followed%@EH@%
  16217.   by a coprocessor instruction, the coprocessor must wait until the
  16218.   processor is finished before it can start the next instruction. This is
  16219.   handled automatically by Quick-Assembler for the 8088 and 8086 or by the
  16220.   processor for the 80186 and 80286.%@NL@%
  16221. %@NL@%
  16222.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16223. %@CR:IX17.26     @%%@CR:IX17.27     @%%@CR:IX17.28     @%%@CR:IX17.29     @%%@CR:IX17.30     @%  %@AB@%Coprocessor Differences%@AE@%  To synchronize operations between the 8088 or
  16224.   8086 processor and the 8087 coprocessor, each 8087 instruction must be
  16225.   preceded by a %@AB@%WAIT i%@AE@%nstruction. This is not necessary for the 80287. If
  16226.   you use the %@AB@%.8087 %@AE@%directive, QuickAssembler inserts %@AB@%WAIT %@AE@%instructions
  16227.   automatically. However, if you use the %@AB@%.286 %@AE@%directive, QuickAssembler
  16228.   assumes the instructions are for the 80287 or 80387 and does not insert
  16229.   the %@AB@%WAIT %@AE@%instructions. If your code will never need to run on an 8086 or
  16230.   8088 processor, you can make your programs shorter and more efficient by
  16231.   using the %@AB@%.286 %@AE@%directive.%@NL@%
  16232.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16233. %@NL@%
  16234. %@4@%  In the second case, if a coprocessor instruction that accesses memory is%@EH@%
  16235.   followed by a processor instruction attempting to access the same memory
  16236.   location, memory access is not automatically synchronized. For instance,
  16237.   if you store a coprocessor register to a variable and then try to load
  16238.   that variable into a processor register, the coprocessor may not be
  16239.   finished. Thus, the processor gets the value that was in memory before the
  16240.   coprocessor finished, rather than the value stored by the coprocessor. Use
  16241.   the %@AB@%WAIT%@AE@% or %@AB@%FWAIT%@AE@% instruction (they are mnemonics for the same
  16242.   instruction) to ensure that the coprocessor finishes before the processor
  16243.   begins.%@NL@%
  16244. %@NL@%
  16245. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  16246. %@NL@%
  16247.   %@AS@%; Coprocessor instruction first - Wait needed%@AE@%%@NL@%
  16248. %@NL@%
  16249.   %@AS@%            fist    mem32                ; Store to memory%@AE@%%@NL@%
  16250.   %@AS@%            fwait                        ; Wait until coprocessor is done%@AE@%%@NL@%
  16251.   %@AS@%            mov     ax,WORD PTR mem32    ; Move to register%@AE@%%@NL@%
  16252.   %@AS@%            mov     dx,WORD PTR mem32[2]%@AE@%%@NL@%
  16253. %@NL@%
  16254.   %@AS@%; Processor instruction first - No wait needed%@AE@%%@NL@%
  16255. %@NL@%
  16256.   %@AS@%            mov     WORD PTR mem32,ax    ; Load memory%@AE@%%@NL@%
  16257.   %@AS@%            mov     WORD PTR mem32[2],dx%@AE@%%@NL@%
  16258.   %@AS@%            fild    mem32                ; Load to register%@AE@%%@NL@%
  16259. %@NL@%
  16260. %@NL@%
  16261. %@2@%%@CR:SC17.5      @%%@AB@%17.5  Transferring Data%@AE@%%@EH@%%@NL@%
  16262. %@NL@%
  16263. %@4@%  The 8087-family coprocessors have separate instructions for each of the%@EH@%
  16264.   following types of transfers:%@NL@%
  16265. %@NL@%
  16266.   1. Transferring data between memory and registers, or between different
  16267.      registers%@NL@%
  16268. %@NL@%
  16269.   2. Loading certain common constants into registers%@NL@%
  16270. %@NL@%
  16271.   3. Transferring control data to and from memory%@NL@%
  16272. %@NL@%
  16273. %@NL@%
  16274. %@3@%%@CR:SC17.5.1    @%%@AB@%17.5.1  Transferring Data to and from Registers%@AE@%%@EH@%%@NL@%
  16275. %@NL@%
  16276. %@4@%  Data-transfer instructions transfer data between main memory and the%@EH@%
  16277.   coprocessor registers, or between different coprocessor registers. Two
  16278.   basic principles govern data transfers:%@NL@%
  16279. %@NL@%
  16280.   ■  The instruction determines whether a value in memory will be considered
  16281.      an integer, a BCD number, or a real number. The value is always
  16282.      considered a temporary-real number once it is transferred to the
  16283.      coprocessor.%@NL@%
  16284. %@NL@%
  16285.   ■  The size of the operand determines the size of a value in memory.
  16286.      Values in the coprocessor always take up 10 bytes.%@NL@%
  16287. %@NL@%
  16288. %@4@%%@CR:IX17.31     @%%@CR:IX17.32     @%  The adjustments between formats are made automatically. Notice that%@EH@%
  16289.   floating-point numbers must be stored in the IEEE format, not in the
  16290.   Microsoft Binary format. Data is automatically stored correctly by
  16291.   default. It is stored incorrectly and the coprocessor instructions
  16292.   disabled if you use the %@AB@%.MSFLOAT%@AE@% directive. Data formats for real numbers
  16293.   are explained in Section 6.5.1.4%@BO:       62baf@%, "Real-Number Variables."%@NL@%
  16294. %@NL@%
  16295. %@4@%%@CR:IX17.33     @%%@CR:IX17.34     @%%@CR:IX17.35     @%  Data is transferred to stack registers by using load commands. These%@EH@%
  16296.   commands push data onto the stack from memory or coprocessor registers.
  16297.   Data is removed by using store commands. Some store commands pop data off
  16298.   the register stack into memory or coprocessor registers, whereas others
  16299.   simply copy the data without changing it on the stack.%@NL@%
  16300. %@NL@%
  16301. %@NL@%
  16302. %@3@%%@CR:SC17.5.1.1  @%%@AB@%17.5.1.1  Real Transfers%@AE@%%@EH@%%@NL@%
  16303. %@NL@%
  16304. %@4@%%@CR:IX17.36     @%%@CR:IX17.37     @%  The following instructions are available for transferring real numbers:%@EH@%%@NL@%
  16305. %@NL@%
  16306.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16307.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16308. %@CR:IX17.38     @%%@CR:IX17.39     @%  %@AB@%FLD %@AE@%%@AI@%mem%@AE@%             Pushes a copy of %@AI@%mem%@AE@% into ST. The source must be a 4-,
  16309.                       8-, or 10-byte memory operand. It is automatically
  16310.                       converted to the temporary-real format.%@NL@%
  16311. %@NL@%
  16312.   %@AB@%FLD ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%         Pushes a copy of the specified register into ST.%@NL@%
  16313. %@NL@%
  16314. %@CR:IX17.40     @%%@CR:IX17.41     @%  %@AB@%FST %@AE@%%@AI@%mem%@AE@%             Copies ST to %@AI@%mem%@AE@% without affecting the register stack.
  16315.                       The destination can be a 4- or 8-byte memory operand.
  16316.                       It is automatically converted from temporary-real
  16317.                       format to short real or long real format, depending on
  16318.                       the size of the operand. It cannot be stored in the
  16319.                       10-byte-real format.%@NL@%
  16320. %@NL@%
  16321.   %@AB@%FST ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%         Copies ST to the specified register. The current value
  16322.                       of the specified register is replaced.%@NL@%
  16323. %@NL@%
  16324. %@CR:IX17.42     @%%@CR:IX17.43     @%  %@AB@%FSTP %@AE@%%@AI@%mem%@AE@%            Pops a copy of ST into %@AI@%mem%@AE@%. The destination can be a
  16325.                       4-, 8-, or 10-byte memory operand. It is automatically
  16326.                       converted from temporary-real format to the
  16327.                       appropriate real-number format, depending on the size
  16328.                       of the operand.%@NL@%
  16329. %@NL@%
  16330.   %@AB@%FSTP ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%        Pops ST into the specified register. The current value
  16331.                       of the specified register is replaced.%@NL@%
  16332. %@NL@%
  16333. %@CR:IX17.44     @%%@CR:IX17.45     @%  %@AB@%FXCH %@AE@%[[%@AB@%ST%@AE@%(%@AI@%num%@AE@%%@AB@%)%@AE@%]]    Exchanges the value in ST with the value in ST(%@AI@%num%@AE@%).
  16334.                       If no operand is specified, ST(0) and ST(1) are
  16335.                       exchanged.%@NL@%
  16336. %@NL@%
  16337. %@NL@%
  16338. %@NL@%
  16339. %@3@%%@CR:SC17.5.1.2  @%%@AB@%17.5.1.2  Integer Transfers%@AE@%%@EH@%%@NL@%
  16340. %@NL@%
  16341. %@4@%%@CR:IX17.46     @%%@CR:IX17.47     @%  The following instructions are available for transferring binary integers:%@EH@%%@NL@%
  16342. %@NL@%
  16343.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16344.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16345. %@CR:IX17.48     @%  %@AB@%FILD %@AE@%%@AI@%mem%@AE@%            The source must be a 2-, 4-, or 8-byte integer memory
  16346.                       operand. It is interpreted as an integer and converted
  16347.                       to temporary-real format.%@NL@%
  16348. %@NL@%
  16349. %@CR:IX17.49     @%%@CR:IX17.50     @%  %@AB@%FIST %@AE@%%@AI@%mem%@AE@%            Copies ST to %@AI@%mem%@AE@%. The destination must be a 2- or
  16350.                       4-byte memory operand. It is automatically converted
  16351.                       from temporary-real format to a word or a doubleword,
  16352.                       depending on the size of the operand. It cannot be
  16353.                       converted to a quadword integer.%@NL@%
  16354. %@NL@%
  16355. %@CR:IX17.51     @%%@CR:IX17.52     @%  %@AB@%FISTP %@AE@%%@AI@%mem%@AE@%           Pops ST into %@AI@%mem%@AE@%. The destination must be a 2-, 4-, or
  16356.                       8-byte memory operand. It is automatically converted
  16357.                       from temporary-real format to a word, doubleword, or
  16358.                       quadword integer, depending on the size of the
  16359.                       operand.%@NL@%
  16360. %@NL@%
  16361. %@NL@%
  16362. %@NL@%
  16363. %@3@%%@CR:SC17.5.1.3  @%%@AB@%17.5.1.3  Packed BCD Transfers%@AE@%%@EH@%%@NL@%
  16364. %@NL@%
  16365. %@4@%%@CR:IX17.53     @%%@CR:IX17.54     @%  The following instructions are available for transferring BCD integers:%@EH@%%@NL@%
  16366. %@NL@%
  16367.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16368.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16369. %@CR:IX17.55     @%%@CR:IX17.56     @%  %@AB@%FBLD %@AE@%%@AI@%mem%@AE@%            Pushes a copy of %@AI@%mem%@AE@% into ST. The source must be a
  16370.                       10-byte memory operand. It should contain a packed BCD
  16371.                       value, although no check is made to see that the data
  16372.                       is valid.%@NL@%
  16373. %@NL@%
  16374. %@CR:IX17.57     @%%@CR:IX17.58     @%  %@AB@%FBSTP %@AE@%%@AI@%mem%@AE@%           Pops ST into %@AI@%mem%@AE@%. The destination must be a 10-byte
  16375.                       memory operand. The value is rounded to an integer if
  16376.                       necessary and converted to a packed BCD value.%@NL@%
  16377. %@NL@%
  16378. %@NL@%
  16379. %@4@%  The following examples illustrate instructions described throughout this%@EH@%
  16380.   section:%@NL@%
  16381. %@NL@%
  16382. %@4@%  %@AB@%Example 1%@AE@%%@EH@%%@NL@%
  16383. %@NL@%
  16384.   %@AS@%            fld     m1                 ; Push m1 into first item%@AE@%%@NL@%
  16385.   %@AS@%            fld     st(2)              ; Push third item into first%@AE@%%@NL@%
  16386.   %@AS@%            fst     m2                 ; Copy first item to m2%@AE@%%@NL@%
  16387.   %@AS@%            fxch    st(2)              ; Exchange first and third items%@AE@%%@NL@%
  16388.   %@AS@%            fstp    m1                 ; Pop first item into m1%@AE@%%@NL@%
  16389. %@NL@%
  16390. %@4@%%@CR:IX17.59     @%  Assuming that registers ST and ST(1) were previously initialized to 3.0%@EH@%
  16391.   and 4.0, the status of the register stack is shown below:%@NL@%
  16392. %@NL@%
  16393.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  16394.   │ This figure can be found in Section 17.5.1.3 of the manual             │%@NL@%
  16395.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  16396. %@NL@%
  16397. %@4@%  %@AB@%Example 2%@AE@%%@EH@%%@NL@%
  16398. %@NL@%
  16399.   %@AS@%            .DATA%@AE@%%@NL@%
  16400.   %@AS@%shortreal   DD      100 DUP (?)%@AE@%%@NL@%
  16401.   %@AS@%longreal    DQ      100 DUP (?)%@AE@%%@NL@%
  16402.   %@AS@%            .CODE%@AE@%%@NL@%
  16403.   %@AS@%            .                      ; Assume array shortreal has been%@AE@%%@NL@%
  16404.   %@AS@%            .                      ;   filled by previous code%@AE@%%@NL@%
  16405.   %@AS@%            .%@AE@%%@NL@%
  16406.   %@AS@%            mov     cx,100         ; Initialize loop%@AE@%%@NL@%
  16407.   %@AS@%            xor     si,si          ; Clear pointer into shortreal%@AE@%%@NL@%
  16408.   %@AS@%            xor     di,di          ; Clear pointer into longreal%@AE@%%@NL@%
  16409.   %@AS@%again:      fld     shortreal[si]  ; Push shortreal%@AE@%%@NL@%
  16410.   %@AS@%            fstp    longreal[di]   ; Pop longreal%@AE@%%@NL@%
  16411.   %@AS@%            add     si,4           ; Increment source pointer%@AE@%%@NL@%
  16412.   %@AS@%            add     di,8           ; Increment destination pointer%@AE@%%@NL@%
  16413.   %@AS@%            loop    again          ; Do it again%@AE@%%@NL@%
  16414. %@NL@%
  16415. %@4@%  Example 2 illustrates one way of doing run-time type conversions.%@EH@%%@NL@%
  16416. %@NL@%
  16417. %@NL@%
  16418. %@3@%%@CR:SC17.5.2    @%%@AB@%17.5.2  Loading Constants%@AE@%%@EH@%%@NL@%
  16419. %@NL@%
  16420. %@4@%%@CR:IX17.60     @%  Constants cannot be given as operands and loaded directly into coprocessor%@EH@%
  16421.   registers. You must allocate memory and initialize the variable to a
  16422.   constant value. The variable can then be loaded by using one of the load
  16423.   instructions described in Section 17.5.1%@BO:       defb7@%, "Transferring Data to and from
  16424.   Registers."%@NL@%
  16425. %@NL@%
  16426. %@4@%%@CR:IX17.61     @%%@CR:IX17.62     @%  However, special instructions are provided for loading certain constants.%@EH@%
  16427.   You can load 0, 1, pi, and several common logarithmic values directly.
  16428.   Using these instructions is faster and often more precise than loading the
  16429.   values from initialized variables.%@NL@%
  16430. %@NL@%
  16431. %@4@%%@CR:IX17.63     @%  The instructions that load constants all have the stack top as the implied%@EH@%
  16432.   destination operand. The constant to be loaded is the implied source
  16433.   operand. The instructions are listed below:%@NL@%
  16434. %@NL@%
  16435.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16436.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16437. %@CR:IX17.64     @%%@CR:IX17.65     @%  %@AB@%FLDZ%@AE@%                Pushes 0 into ST%@NL@%
  16438. %@NL@%
  16439. %@CR:IX17.66     @%%@CR:IX17.67     @%  %@AB@%FLD1%@AE@%                Pushes 1 into ST%@NL@%
  16440. %@NL@%
  16441. %@CR:IX17.68     @%%@CR:IX17.69     @%  %@AB@%FLDPI%@AE@%               Pushes the value of pi into ST%@NL@%
  16442. %@NL@%
  16443. %@CR:IX17.70     @%%@CR:IX17.71     @%  %@AB@%FLDL2E%@AE@%              Pushes the value of log2^e into ST%@NL@%
  16444. %@NL@%
  16445. %@CR:IX17.72     @%%@CR:IX17.73     @%  %@AB@%FLDL2T%@AE@%              Pushes log2^10 into ST%@NL@%
  16446. %@NL@%
  16447. %@CR:IX17.74     @%%@CR:IX17.75     @%  %@AB@%FLDLG2%@AE@%              Pushes log10^2 into ST%@NL@%
  16448. %@NL@%
  16449. %@CR:IX17.76     @%%@CR:IX17.77     @%  %@AB@%FLDLN2%@AE@%              Pushes loge^2 ST%@NL@%
  16450. %@NL@%
  16451. %@NL@%
  16452. %@NL@%
  16453. %@3@%%@CR:SC17.5.3    @%%@AB@%17.5.3  Transferring Control Data%@AE@%%@EH@%%@NL@%
  16454. %@NL@%
  16455. %@4@%%@CR:IX17.78     @%%@CR:IX17.79     @%  The coprocessor data area, or parts of it, can be stored to memory and%@EH@%
  16456.   later loaded back. One reason for doing this is to save a snapshot of the
  16457.   coprocessor state before going into a procedure, and restore the same
  16458.   status after the procedure. Another reason is to modify coprocessor
  16459.   behavior by storing certain data to main memory, operating on the data
  16460.   with 8086-family instructions, and then loading it back to the coprocessor
  16461.   data area.%@NL@%
  16462. %@NL@%
  16463. %@4@%  You can choose to transfer the entire coprocessor data area, the control%@EH@%
  16464.   registers, or just the status or control word. Applications programmers
  16465.   seldom need to load anything other than the status word.%@NL@%
  16466. %@NL@%
  16467. %@4@%  All the control-transfer instructions take a single memory operand. Load%@EH@%
  16468.   instructions use the memory operand as the destination; store instructions
  16469.   use it as the source. The coprocessor data area is the implied source for
  16470.   load instructions and the implied destination for store instructions.%@NL@%
  16471. %@NL@%
  16472. %@4@%  Each store instruction has two forms. The "wait form" checks for unmasked%@EH@%
  16473.   numeric-error exceptions and waits until they have been handled. The
  16474.   "no-wait" form (which always begins with %@AB@%FN%@AE@%) ignores unmasked exceptions.
  16475.   The instructions are listed below:%@NL@%
  16476. %@NL@%
  16477.   %@AB@%Syntax%@AE@%                      %@AB@%Description%@AE@%%@NL@%
  16478.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16479. %@CR:IX17.80     @%%@CR:IX17.81     @%  %@AB@%FLDCW %@AE@%%@AI@%mem2byte%@AE@%              Loads control word%@NL@%
  16480. %@NL@%
  16481. %@CR:IX17.82     @%%@CR:IX17.83     @%  %@AB@%F%@AE@%[[%@AB@%N%@AE@%]]%@AB@%STCW%@AE@% %@AI@%mem2byte%@AE@%         Stores control word%@NL@%
  16482. %@NL@%
  16483. %@CR:IX17.84     @%%@CR:IX17.85     @%  %@AB@%F%@AE@%[[%@AB@%N%@AE@%]]%@AB@%STSW%@AE@% %@AI@%mem2byte%@AE@%         Stores status word%@NL@%
  16484. %@NL@%
  16485.   %@AB@%FLENV %@AE@%%@AI@%mem14byte%@AE@%             Loads environment%@NL@%
  16486. %@NL@%
  16487.   %@AB@%F%@AE@%[[%@AB@%N%@AE@%]]%@AB@%STENV%@AE@% %@AI@%mem14byte%@AE@%       Stores environment%@NL@%
  16488. %@NL@%
  16489.   %@AB@%FRSTOR %@AE@%%@AI@%mem94byte%@AE@%            Restores state%@NL@%
  16490. %@NL@%
  16491.   %@AB@%F%@AE@%[[%@AB@%N%@AE@%]]%@AB@%SAVE%@AE@% %@AI@%mem94byte%@AE@%        Saves state%@NL@%
  16492. %@NL@%
  16493. %@NL@%
  16494. %@4@%  %@AB@%80287/80387 Only%@AE@%%@EH@%%@NL@%
  16495. %@NL@%
  16496. %@4@%%@CR:IX17.86     @%%@CR:IX17.87     @%  Starting with the 80287 coprocessor, the %@AB@%FSTSW%@AE@% and %@AB@%FNSTSW%@AE@% instructions can%@EH@%
  16497.   store data directly to the AX register. This is the only case in which
  16498.   data can be transferred directly between processor and coprocessor
  16499.   registers, as shown below:%@NL@%
  16500. %@NL@%
  16501.   %@AS@%            fstsw   ax%@AE@%%@NL@%
  16502. %@NL@%
  16503. %@NL@%
  16504. %@2@%%@CR:SC17.6      @%%@AB@%17.6  Doing Arithmetic Calculations%@AE@%%@EH@%%@NL@%
  16505. %@NL@%
  16506. %@4@%  The math coprocessors offer a rich set of instructions for doing%@EH@%
  16507.   arithmetic. Most arithmetic instructions accept operands in any of the
  16508.   formats discussed in Section 17.3%@BO:       db35c@%, "Using Coprocessor Instructions."%@NL@%
  16509. %@NL@%
  16510. %@4@%%@CR:IX17.88     @%%@CR:IX17.89     @%%@CR:IX17.90     @%  When using memory operands with an arithmetic instruction, make sure you%@EH@%
  16511.   indicate in the name whether you want the memory operand to be treated as
  16512.   a real number or an integer. For example, use %@AB@%FADD%@AE@% to add a real number to
  16513.   the stack top or %@AB@%FIADD%@AE@% to add an integer to the stack top. You do not need
  16514.   to specify the operand type in the instruction if both operands are stack
  16515.   registers, since register values are always real numbers. You cannot do
  16516.   arithmetic on BCD numbers in memory. You must use %@AB@%FBLD%@AE@% to load the numbers
  16517.   into stack registers.%@NL@%
  16518. %@NL@%
  16519. %@4@%%@CR:IX17.91     @%  The arithmetic instructions are listed below.%@EH@%%@NL@%
  16520. %@NL@%
  16521. %@3@%  %@AB@%Addition%@AE@%%@EH@%%@NL@%
  16522. %@NL@%
  16523. %@4@%  The following instructions add the source and destination and put the%@EH@%
  16524.   result in the destination:%@NL@%
  16525. %@NL@%
  16526.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16527.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16528. %@CR:IX17.92     @%%@CR:IX17.93     @%  %@AB@%FADD%@AE@%                Classical-stack form. Adds ST and ST(1) and pops the
  16529.                       result into ST. Both operands are destroyed.%@NL@%
  16530. %@NL@%
  16531.   %@AB@%FADD ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%     Register form with stack top as source. Adds the two
  16532.                       register values and replaces ST(%@AI@%num%@AE@%) with the result.%@NL@%
  16533. %@NL@%
  16534.   %@AB@%FADD ST,ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%     Register form with stack top as destination. Adds the
  16535.                       two register values and replaces ST with the result.%@NL@%
  16536. %@NL@%
  16537.   %@AB@%FADD %@AE@%%@AI@%mem%@AE@%            Real-memory form. Adds a real number in %@AI@%mem%@AE@% to ST. The
  16538.                       result replaces ST.%@NL@%
  16539. %@NL@%
  16540. %@CR:IX17.94     @%%@CR:IX17.95     @%  %@AB@%FIADD %@AE@%%@AI@%mem%@AE@%           Integer-memory form. Adds an integer in %@AI@%mem%@AE@% to ST. The
  16541.                       result replaces ST.%@NL@%
  16542. %@NL@%
  16543. %@CR:IX17.96     @%%@CR:IX17.97     @%  %@AB@%FADDP ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%    Register-pop form. Adds the two register values and
  16544.                       pops the result into ST(%@AI@%num%@AE@%).%@NL@%
  16545. %@NL@%
  16546. %@NL@%
  16547. %@3@%  %@AB@%Normal Subtraction%@AE@%%@EH@%%@NL@%
  16548. %@NL@%
  16549. %@4@%%@CR:IX17.98     @%  The following instructions subtract the source from the destination and%@EH@%
  16550.   put the difference in the destination. Thus, the number being subtracted
  16551.   from is replaced by the result.%@NL@%
  16552. %@NL@%
  16553.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16554.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16555. %@CR:IX17.99     @%%@CR:IX17.100    @%  %@AB@%FSUB%@AE@%                Classical-stack form. Subtracts ST from ST(1) and pops
  16556.                       the result into ST. Both operands are destroyed.%@NL@%
  16557. %@NL@%
  16558.   %@AB@%FSUB ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%     Register form with stack top as source. Subtracts ST
  16559.                       from ST(%@AI@%num%@AE@%) and replaces ST(%@AI@%num%@AE@%) with the result.%@NL@%
  16560. %@NL@%
  16561.   %@AB@%FSUB ST,ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%     Register form with stack top as destination. Subtracts
  16562.                       ST(%@AI@%num%@AE@%) from ST and replaces ST with the result.%@NL@%
  16563. %@NL@%
  16564.   %@AB@%FSUB %@AE@%%@AI@%mem%@AE@%            Real-memory form. Subtracts the real number in %@AI@%mem%@AE@%
  16565.                       from ST. The result replaces ST.%@NL@%
  16566. %@NL@%
  16567. %@CR:IX17.101    @%%@CR:IX17.102    @%  %@AB@%FISUB %@AE@%%@AI@%mem%@AE@%           Integer-memory form. Subtracts the integer in %@AI@%mem%@AE@% from
  16568.                       ST. The result replaces ST.%@NL@%
  16569. %@NL@%
  16570. %@CR:IX17.103    @%%@CR:IX17.104    @%  %@AB@%FSUBP ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%    Register-pop form. Subtracts ST from ST(%@AI@%num%@AE@%) and pops
  16571.                       the result into ST(%@AI@%num%@AE@%). Both operands are destroyed.%@NL@%
  16572. %@NL@%
  16573. %@NL@%
  16574. %@3@%  %@AB@%Reversed Subtraction%@AE@%%@EH@%%@NL@%
  16575. %@NL@%
  16576. %@4@%%@CR:IX17.105    @%  The following instructions subtract the destination from the source and%@EH@%
  16577.   put the difference in the destination. Thus, the number subtracted is
  16578.   replaced by the result.%@NL@%
  16579. %@NL@%
  16580.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16581.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16582. %@CR:IX17.106    @%%@CR:IX17.107    @%  %@AB@%FSUBR%@AE@%               Classical-stack form. Subtracts ST(1) from ST and pops
  16583.                       the result into ST. Both operands are destroyed.%@NL@%
  16584. %@NL@%
  16585.   %@AB@%FSUBR ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%    Register form with stack top as source. Subtracts
  16586.                       ST(%@AI@%num%@AE@%) from ST and replaces ST(%@AI@%num%@AE@%) with the result.%@NL@%
  16587. %@NL@%
  16588.   %@AB@%FSUBR ST,ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%    Register form with stack top as destination. Subtracts
  16589.                       ST from ST(%@AI@%num%@AE@%) and replaces ST%@AB@% %@AE@%with the result.%@NL@%
  16590. %@NL@%
  16591.   %@AB@%FSUBR %@AE@%%@AI@%mem%@AE@%           Real-memory form. Subtracts ST from the real number in
  16592.                       %@AI@%mem%@AE@%. The result replaces ST.%@NL@%
  16593. %@NL@%
  16594. %@CR:IX17.108    @%%@CR:IX17.109    @%  %@AB@%FISUBR %@AE@%%@AI@%mem%@AE@%          Integer-memory form. Subtracts ST from the integer in
  16595.                       %@AI@%mem%@AE@%. The result replaces ST.%@NL@%
  16596. %@NL@%
  16597. %@CR:IX17.110    @%%@CR:IX17.111    @%  %@AB@%FSUBRP ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%   Register-pop form. Subtracts ST(%@AI@%num%@AE@%) from ST and pops
  16598.                       the result into ST(%@AI@%num%@AE@%). Both operands are destroyed.%@NL@%
  16599. %@NL@%
  16600. %@NL@%
  16601. %@3@%  %@AB@%Multiplication%@AE@%%@EH@%%@NL@%
  16602. %@NL@%
  16603. %@4@%%@CR:IX17.112    @%  The following instructions multiply the source and destination and put the%@EH@%
  16604.   product in the destination:%@NL@%
  16605. %@NL@%
  16606.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16607.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16608. %@CR:IX17.113    @%%@CR:IX17.114    @%  %@AB@%FMUL%@AE@%                Classical-stack form. Multiplies ST by ST(1) and pops
  16609.                       the result into ST. Both operands are destroyed.%@NL@%
  16610. %@NL@%
  16611.   %@AB@%FMUL ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%     Register form with stack top as source. Multiplies the
  16612.                       two register values and replaces ST%@AB@%(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@% with the
  16613.                       result.%@NL@%
  16614. %@NL@%
  16615.   %@AB@%FMUL ST,ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%     Register form with stack top as destination.
  16616.                       Multiplies the two register values and replaces ST
  16617.                       with the result.%@NL@%
  16618. %@NL@%
  16619.   %@AB@%FMUL %@AE@%%@AI@%mem%@AE@%            Real-memory form. Multiplies a real number in %@AI@%mem%@AE@% by
  16620.                       ST. The result replaces ST.%@NL@%
  16621. %@NL@%
  16622. %@CR:IX17.115    @%%@CR:IX17.116    @%  %@AB@%FIMUL %@AE@%%@AI@%mem%@AE@%           Integer-memory form. Multiplies an integer in %@AI@%mem%@AE@% by
  16623.                       ST. The result replaces ST.%@NL@%
  16624. %@NL@%
  16625. %@CR:IX17.117    @%%@CR:IX17.118    @%  %@AB@%FMULP ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%    Register-pop form. Multiplies the two register values
  16626.                       and pops the result into ST(%@AI@%num%@AE@%%@AB@%)%@AE@%. Both operands are
  16627.                       destroyed.%@NL@%
  16628. %@NL@%
  16629. %@NL@%
  16630. %@3@%  %@AB@%Normal Division%@AE@%%@EH@%%@NL@%
  16631. %@NL@%
  16632. %@4@%%@CR:IX17.119    @%  The following instructions divide the destination by the source and put%@EH@%
  16633.   the quotient in the destination. Thus, the dividend is replaced by the
  16634.   quotient.%@NL@%
  16635. %@NL@%
  16636.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16637.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16638. %@CR:IX17.120    @%%@CR:IX17.121    @%  %@AB@%FDIV%@AE@%                Classical-stack form. Divides ST(1) by ST and pops the
  16639.                       result into ST. Both operands are destroyed.%@NL@%
  16640. %@NL@%
  16641.   %@AB@%FDIV ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%     Register form with stack top as source. Divides
  16642.                       ST(%@AI@%num%@AE@%) by ST and replaces ST(%@AI@%num%@AE@%) with the result.%@NL@%
  16643. %@NL@%
  16644.   %@AB@%FDIV ST,ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%     Register form with stack top as destination. Divides
  16645.                       ST by ST(%@AI@%num%@AE@%) and replaces ST with the result.%@NL@%
  16646. %@NL@%
  16647.   %@AB@%FDIV %@AE@%%@AI@%mem%@AE@%            Real-memory form. Divides ST by the real number in
  16648.                       %@AI@%mem%@AE@%. The result replaces ST.%@NL@%
  16649. %@NL@%
  16650. %@CR:IX17.122    @%%@CR:IX17.123    @%  %@AB@%FIDIV %@AE@%%@AI@%mem%@AE@%           Integer-memory form. Divides ST by the integer in %@AI@%mem%@AE@%.
  16651.                       The result replaces ST.%@NL@%
  16652. %@NL@%
  16653. %@CR:IX17.124    @%%@CR:IX17.125    @%  %@AB@%FDIVP ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%    Register-pop form. Divides ST(%@AI@%num%@AE@%) by ST and pops the
  16654.                       result into ST(%@AI@%num%@AE@%). Both operands are destroyed.%@NL@%
  16655. %@NL@%
  16656. %@NL@%
  16657. %@3@%  %@AB@%Reversed Division%@AE@%%@EH@%%@NL@%
  16658. %@NL@%
  16659. %@4@%%@CR:IX17.126    @%  The following instructions divide the source by the destination and put%@EH@%
  16660.   the quotient in the destination. Thus, the divisor is replaced by the
  16661.   quotient.%@NL@%
  16662. %@NL@%
  16663.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16664.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16665. %@CR:IX17.127    @%%@CR:IX17.128    @%  %@AB@%FDIVR%@AE@%               Classical-stack form. Divides ST by ST(1) and pops the
  16666.                       result into ST. Both operands are destroyed.%@NL@%
  16667. %@NL@%
  16668.   %@AB@%FDIVR ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%    Register form with stack top as source. Divides ST by
  16669.                       ST(%@AI@%num%@AE@%) and replaces ST(%@AI@%num%@AE@%) with the result.%@NL@%
  16670. %@NL@%
  16671.   %@AB@%FDIVR ST,ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%    Register form with stack top as destination. Divides
  16672.                       ST(%@AI@%num%@AE@%) by ST and replaces ST with the result.%@NL@%
  16673. %@NL@%
  16674.   %@AB@%FDIVR %@AE@%%@AI@%mem%@AE@%           Real-memory form. Divides the real number in %@AI@%mem%@AE@% by
  16675.                       ST. The result replaces ST.%@NL@%
  16676. %@NL@%
  16677. %@CR:IX17.129    @%%@CR:IX17.130    @%  %@AB@%FIDIVR %@AE@%%@AI@%mem%@AE@%          Integer-memory form. Divides the integer in %@AI@%mem%@AE@% by ST.
  16678.                       The result replaces ST.%@NL@%
  16679. %@NL@%
  16680. %@CR:IX17.131    @%%@CR:IX17.132    @%  %@AB@%FDIVRP ST(%@AE@%%@AI@%num%@AE@%%@AB@%),ST%@AE@%   Register-pop form. Divides ST by ST(%@AI@%num%@AE@%) and pops the
  16681.                       result into ST(%@AI@%num%@AE@%). Both operands are destroyed.%@NL@%
  16682. %@NL@%
  16683. %@NL@%
  16684. %@3@%  %@AB@%Other Operations%@AE@%%@EH@%%@NL@%
  16685. %@NL@%
  16686. %@4@%  The following instructions all use the stack top (ST) as an implied%@EH@%
  16687.   destination operand. The result of the operation replaces the value in the
  16688.   stack top. No operand should be given.%@NL@%
  16689. %@NL@%
  16690.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16691.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16692. %@CR:IX17.133    @%%@CR:IX17.134    @%  %@AB@%FABS%@AE@%                Sets the sign of ST to positive.%@NL@%
  16693. %@NL@%
  16694. %@CR:IX17.135    @%%@CR:IX17.136    @%  %@AB@%FCHS%@AE@%                Reverses the sign of ST.%@NL@%
  16695. %@NL@%
  16696. %@CR:IX17.137    @%%@CR:IX17.138    @%  %@AB@%FRNDINT%@AE@%             Rounds ST to an integer.%@NL@%
  16697. %@NL@%
  16698. %@CR:IX17.139    @%%@CR:IX17.140    @%%@CR:IX17.141    @%  %@AB@%FSQRT%@AE@%               Replaces the contents of ST%@AB@% %@AE@%with its square root.%@NL@%
  16699. %@NL@%
  16700. %@CR:IX17.142    @%  %@AB@%FSCALE%@AE@%              Scales by powers of 2 by adding the value of ST(1) to
  16701.                       the exponent of the value in ST. This effectively
  16702.                       multiplies the stack-top value by 2 to the power
  16703.                       contained in ST(1). Since the exponent field is an
  16704.                       integer, the value in ST(1) should normally be an
  16705.                       integer.%@NL@%
  16706. %@NL@%
  16707. %@CR:IX17.143    @%%@CR:IX17.144    @%%@CR:IX17.145    @%%@CR:IX17.146    @%%@CR:IX17.147    @%%@CR:IX17.148    @%  %@AB@%FPREM%@AE@%               Calculates the partial remainder by performing modulo
  16708.                       division on the top two stack registers. The value in
  16709.                       ST is divided by the value in ST(1). The remainder
  16710.                       replaces the value in ST. The value in ST(1) is
  16711.                       unchanged. Since this instruction works by repeated
  16712.                       subtractions, it can take a lot of execution time if
  16713.                       the operands are very different in magnitude. %@AB@%FRPEM%@AE@% is
  16714.                       sometimes used with trigonometric functions.%@NL@%
  16715. %@NL@%
  16716. %@CR:IX17.149    @%%@CR:IX17.150    @%  %@AB@%FXTRACT%@AE@%             Breaks a number down into its exponent and mantissa
  16717.                       and pushes the mantissa onto the register stack.
  16718.                       Following the operation, ST contains the value of the
  16719.                       original mantissa and ST(1) contains the value of the
  16720.                       unbiased exponent.%@NL@%
  16721. %@NL@%
  16722. %@NL@%
  16723. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  16724. %@NL@%
  16725.   %@AS@%            .DATA%@AE@%%@NL@%
  16726.   %@AS@%a           DD      3.0%@AE@%%@NL@%
  16727.   %@AS@%b           DD      7.0%@AE@%%@NL@%
  16728.   %@AS@%c           DD      2.0%@AE@%%@NL@%
  16729.   %@AS@%posx        DD      0.0%@AE@%%@NL@%
  16730.   %@AS@%negx        DD      0.0%@AE@%%@NL@%
  16731. %@NL@%
  16732.   %@AS@%            .CODE%@AE@%%@NL@%
  16733.   %@AS@%            .%@AE@%%@NL@%
  16734.   %@AS@%            .%@AE@%%@NL@%
  16735.   %@AS@%            .%@AE@%%@NL@%
  16736.   %@AS@%; Solve quadratic equation - no error checking%@AE@%%@NL@%
  16737.   %@AS@%            fld1               ; Get constants 2 and 4%@AE@%%@NL@%
  16738.   %@AS@%            fadd    st,st      ; 2 at bottom%@AE@%%@NL@%
  16739.   %@AS@%            fld     st         ; Copy it%@AE@%%@NL@%
  16740.   %@AS@%            fmul    a          ; = 2a%@AE@%%@NL@%
  16741. %@NL@%
  16742.   %@AS@%            fmul    st(1),st   ; = 4a%@AE@%%@NL@%
  16743.   %@AS@%            fxch               ; Exchange%@AE@%%@NL@%
  16744.   %@AS@%            fmul    c          ; = 4ac%@AE@%%@NL@%
  16745. %@NL@%
  16746.   %@AS@%            fld     b          ; Load b%@AE@%%@NL@%
  16747.   %@AS@%            fmul    st,st      ; = b^2%@AE@%%@NL@%
  16748.   %@AS@%            fsubr              ; = b^2 - 4ac%@AE@%%@NL@%
  16749.   %@AS@%                               ; Negative value here produces error%@AE@%%@NL@%
  16750.   %@AS@%            fsqrt              ; = square root(b^2 - 4ac)%@AE@%%@NL@%
  16751.   %@AS@%            fld     b          ; Load b%@AE@%%@NL@%
  16752.   %@AS@%            fchs               ; Make it negative%@AE@%%@NL@%
  16753.   %@AS@%            fxch               ; Exchange%@AE@%%@NL@%
  16754. %@NL@%
  16755.   %@AS@%            fld     st         ; Copy square root%@AE@%%@NL@%
  16756.   %@AS@%            fadd    st,st(2)   ; Plus version = -b + root((b^2 - 4ac)%@AE@%%@NL@%
  16757.   %@AS@%            fxch               ; Exchange%@AE@%%@NL@%
  16758.   %@AS@%            fsubp   st(2),st   ; Minus version = -b - root((b^2 - 4ac)%@AE@%%@NL@%
  16759. %@NL@%
  16760.   %@AS@%            fdiv    st,st(2)   ; Divide plus version%@AE@%%@NL@%
  16761.   %@AS@%            fstp    posx       ; Store it%@AE@%%@NL@%
  16762.   %@AS@%            fdivr              ; Divide minus version%@AE@%%@NL@%
  16763.   %@AS@%            fstp    negx       ; Store it%@AE@%%@NL@%
  16764. %@NL@%
  16765. %@4@%  This example solves quadratic equations. It does no error checking and%@EH@%
  16766.   fails for some values because it attempts to find the square root of a
  16767.   negative number. You could enhance the code by using the %@AB@%FTST%@AE@% instruction
  16768.   (see Section 17.7.1%@BO:       e6d88@%, "Comparing Operands to Control Program Flow") to
  16769.   check for a negative number or 0 just before the square root is
  16770.   calculated. If %@AS@%b^2 - 4ac %@AE@%is negative or 0, the code can jump to routines
  16771.   that handle special cases for no solution or one solution, respectively.%@NL@%
  16772. %@NL@%
  16773. %@NL@%
  16774. %@2@%%@CR:SC17.7      @%%@AB@%17.7  Controlling Program Flow%@AE@%%@EH@%%@NL@%
  16775. %@NL@%
  16776. %@4@%%@CR:IX17.151    @%  The math coprocessors have several instructions that set control flags in%@EH@%
  16777.   the status word. The 8087-family control flags can be used with
  16778.   conditional jumps to direct program flow in the same way that 8086-family
  16779.   flags are used. Since the coprocessor does not have jump instructions, you
  16780.   must transfer the status word to memory so that the flags can be used by
  16781.   8086-family instructions.%@NL@%
  16782. %@NL@%
  16783. %@4@%  An easy way to use the status word with conditional jumps is to move its%@EH@%
  16784.   upper byte into the lower byte of the processor flags. For example, use
  16785.   the following statements:%@NL@%
  16786. %@NL@%
  16787.   %@AS@%            fstsw   mem16      ; Store status word in memory%@AE@%%@NL@%
  16788.   %@AS@%            fwait              ; Make sure coprocessor is done%@AE@%%@NL@%
  16789.   %@AS@%            mov     ax,mem16   ; Move to AX%@AE@%%@NL@%
  16790.   %@AS@%            sahf               ; Store upper word in flags%@AE@%%@NL@%
  16791. %@NL@%
  16792. %@4@%  As noted in Section 17.5.3%@BO:       e1971@%, "Transferring Control Data," you can save%@EH@%
  16793.   several steps by loading the status word directly to AX on the 80287.%@NL@%
  16794. %@NL@%
  16795. %@4@%%@CR:IX17.152    @%%@CR:IX17.153    @%  Figure 17.3 shows how the coprocessor control flags line up with the%@EH@%
  16796.   processor flags. C3 overwrites the zero flag, C2 overwrites the parity
  16797.   flag, and C0 overwrites the carry flag. C1 overwrites an undefined bit, so
  16798.   it cannot be used directly with conditional jumps, although you can use
  16799.   the %@AB@%TEST%@AE@% instruction to check C1 in memory or in a register. The sign and
  16800.   auxiliary-carry flags are also overwritten, so you cannot count on them
  16801.   being unchanged after the operation.%@NL@%
  16802. %@NL@%
  16803.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  16804.   │ This figure can be found in Section 17.7 of the manual                 │%@NL@%
  16805.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  16806. %@NL@%
  16807. %@4@%%@CR:IX17.154    @%%@CR:IX17.155    @%  See Section 15.1.2%@BO:       be4fa@% for more information on using conditional-jump%@EH@%
  16808.   instructions based on flag status.%@NL@%
  16809. %@NL@%
  16810. %@NL@%
  16811. %@3@%%@CR:SC17.7.1    @%%@AB@%17.7.1  Comparing Operands to Control Program Flow%@AE@%%@EH@%%@NL@%
  16812. %@NL@%
  16813. %@4@%  The 8087-family coprocessors provide several instructions for comparing%@EH@%
  16814.   operands. All these instructions compare the stack top (ST) to a source
  16815.   operand, which may either be specified or implied as ST(1).%@NL@%
  16816. %@NL@%
  16817. %@4@%%@CR:IX17.156    @%  The compare instructions affect the C3, C2, and C0 control flags. The C1%@EH@%
  16818.   flag is not affected. Table 17.2 shows the flags set for each possible
  16819.   result of a comparison or test.%@NL@%
  16820. %@NL@%
  16821. %@4@%  Variations on the compare instructions allow you to pop the stack once or%@EH@%
  16822.   twice, and to compare integers and zero. For each instruction, the stack
  16823.   top is always the implied destination operand. If you do not give an
  16824.   operand, ST(1) is the implied source. Some compare instructions allow you
  16825.   to specify the source as a memory or register operand.%@NL@%
  16826. %@NL@%
  16827. %@CR:IX17.157    @%%@CR:IX17.158    @%%@CR:IX17.159    @%%@CR:IX17.160    @%%@CR:IX17.161    @%%@AB@%  Table 17.2 Control-Flag Settings after Compare or Test%@AE@%%@NL@%
  16828. %@NL@%
  16829.   %@AB@%After FCOM%@AE@%      %@AB@%After FTEST%@AE@%       %@AB@%C3%@AE@%        %@AB@%C2%@AE@%          %@AB@%C0%@AE@%%@NL@%
  16830.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16831.   ST > %@AI@%source%@AE@%     ST is positive    0         0           0%@NL@%
  16832. %@NL@%
  16833.   ST < %@AI@%source%@AE@%     ST is negative    0         0           1%@NL@%
  16834. %@NL@%
  16835.   ST = %@AI@%source%@AE@%     ST is 0           1         0           0%@NL@%
  16836. %@NL@%
  16837.   Not comparable  ST is NAN or      1         1           1
  16838.                   projective
  16839.                   infinity%@NL@%
  16840.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16841. %@NL@%
  16842. %@NL@%
  16843. %@4@%  The compare instructions are listed below.%@EH@%%@NL@%
  16844. %@NL@%
  16845. %@NL@%
  16846. %@3@%%@CR:SC17.7.1.1  @%%@AB@%17.7.1.1  Compare%@AE@%%@EH@%%@NL@%
  16847. %@NL@%
  16848. %@4@%  These instructions compare the stack top to the source. The source and%@EH@%
  16849.   destination are unaffected by the comparison.%@NL@%
  16850. %@NL@%
  16851.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16852.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16853. %@CR:IX17.162    @%%@CR:IX17.163    @%  %@AB@%FCOM%@AE@%                Compares ST to ST(1).%@NL@%
  16854. %@NL@%
  16855.   %@AB@%FCOM ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%        Compares ST to ST(%@AI@%num%@AE@%).%@NL@%
  16856. %@NL@%
  16857.   %@AB@%FCOM %@AE@%%@AI@%mem%@AE@%            Compares ST to %@AI@%mem%@AE@%. The memory operand can be a four-
  16858.                       or eight-byte real number.%@NL@%
  16859. %@NL@%
  16860. %@CR:IX17.164    @%%@CR:IX17.165    @%  %@AB@%FICOM %@AE@%%@AI@%mem%@AE@%           Compares ST to %@AI@%mem%@AE@%. The memory operand can be a two-
  16861.                       or four-byte integer.%@NL@%
  16862. %@NL@%
  16863. %@CR:IX17.166    @%%@CR:IX17.167    @%  %@AB@%FTST%@AE@%                Compares ST to 0. The control registers will be
  16864.                       affected as if ST had been compared to 0 in ST(1).
  16865.                       Table 17.2 above shows the possible results.%@NL@%
  16866. %@NL@%
  16867. %@NL@%
  16868. %@NL@%
  16869. %@3@%%@CR:SC17.7.1.2  @%%@AB@%17.7.1.2  Compare and Pop%@AE@%%@EH@%%@NL@%
  16870. %@NL@%
  16871. %@4@%  These instructions compare the stack top to the source and then pop the%@EH@%
  16872.   stack. Thus, the destination is destroyed by the comparison.%@NL@%
  16873. %@NL@%
  16874.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  16875.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16876. %@CR:IX17.168    @%%@CR:IX17.169    @%  %@AB@%FCOMP%@AE@%               Compares ST to ST(1) and pops ST off the register
  16877.                       stack.%@NL@%
  16878. %@NL@%
  16879.   %@AB@%FCOMP ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%       Compares ST to ST(%@AI@%num%@AE@%) and pops ST off the register
  16880.                       stack.%@NL@%
  16881. %@NL@%
  16882.   %@AB@%FCOMP %@AE@%%@AI@%mem%@AE@%           Compares ST to %@AI@%mem%@AE@% and pops ST off the register stack.
  16883.                       The operand can be a four- or eight-byte real number.%@NL@%
  16884. %@NL@%
  16885. %@CR:IX17.170    @%%@CR:IX17.171    @%  %@AB@%FICOMP %@AE@%%@AI@%mem%@AE@%          Compares ST to %@AI@%mem%@AE@% and pops ST off the register stack.
  16886.                       The operand can be a two- or four-byte integer.%@NL@%
  16887. %@NL@%
  16888. %@CR:IX17.172    @%%@CR:IX17.173    @%  %@AB@%FCOMPP%@AE@%              Compares ST to ST(1) and then pops the stack twice.
  16889.                       Both the source and destination are destroyed by the
  16890.                       comparison.%@NL@%
  16891. %@NL@%
  16892. %@NL@%
  16893. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  16894. %@NL@%
  16895.   %@AS@%            IFDEF   c287%@AE@%%@NL@%
  16896.   %@AS@%            .287%@AE@%%@NL@%
  16897.   %@AS@%            ENDIF%@AE@%%@NL@%
  16898.   %@AS@%            .DATA%@AE@%%@NL@%
  16899.   %@AS@%down        DD      10.35      ; Sides of a rectangle%@AE@%%@NL@%
  16900.   %@AS@%across      DD      13.07%@AE@%%@NL@%
  16901.   %@AS@%diameter    DD      12.93      ; Diameter of a circle%@AE@%%@NL@%
  16902.   %@AS@%status      DW      ?%@AE@%%@NL@%
  16903.   %@AS@%            .CODE%@AE@%%@NL@%
  16904.   %@AS@%            .%@AE@%%@NL@%
  16905.   %@AS@%            .%@AE@%%@NL@%
  16906.   %@AS@%            .%@AE@%%@NL@%
  16907.   %@AS@%; Get area of rectangle%@AE@%%@NL@%
  16908.   %@AS@%            fld     across     ; Load one side%@AE@%%@NL@%
  16909.   %@AS@%            fmul    down       ; Multiply by the other%@AE@%%@NL@%
  16910. %@NL@%
  16911.   %@AS@%; Get area of circle%@AE@%%@NL@%
  16912.   %@AS@%            fld1               ; Load one and%@AE@%%@NL@%
  16913.   %@AS@%            fadd    st,st      ;   double it to get constant 2%@AE@%%@NL@%
  16914.   %@AS@%            fdivr   diameter   ; Divide diameter to get radius%@AE@%%@NL@%
  16915.   %@AS@%            fmul    st,st      ; Square radius%@AE@%%@NL@%
  16916.   %@AS@%            fldpi              ; Load pi%@AE@%%@NL@%
  16917.   %@AS@%            fmul               ; Multiply it%@AE@%%@NL@%
  16918. %@NL@%
  16919.   %@AS@%; Compare area of circle and rectangle%@AE@%%@NL@%
  16920.   %@AS@%            fcompp             ; Compare and throw both away%@AE@%%@NL@%
  16921.   %@AS@%            IFNDEF  c287%@AE@%%@NL@%
  16922.   %@AS@%            fstsw   status     ; Load from coprocessor to memory%@AE@%%@NL@%
  16923.   %@AS@%            fwait              ; Wait for coprocessor%@AE@%%@NL@%
  16924.   %@AS@%            mov     ax,status  ; Memory to register%@AE@%%@NL@%
  16925.   %@AS@%            ELSE%@AE@%%@NL@%
  16926.   %@AS@%            fstsw   ax         ;   (for 287+, skip memory)%@AE@%%@NL@%
  16927.   %@AS@%            ENDIF%@AE@%%@NL@%
  16928.   %@AS@%            sahf               ;   to flags%@AE@%%@NL@%
  16929.   %@AS@%            jp      nocomp     ; If parity set, can't compare%@AE@%%@NL@%
  16930.   %@AS@%            jz      same       ; If zero set, they're the same%@AE@%%@NL@%
  16931.   %@AS@%            jc      rectangle  ; If carry set, rectangle is bigger%@AE@%%@NL@%
  16932.   %@AS@%            jmp     circle     ;   else circle is bigger%@AE@%%@NL@%
  16933. %@NL@%
  16934.   %@AS@%nocomp:     .                  ; Error handler%@AE@%%@NL@%
  16935.   %@AS@%            .%@AE@%%@NL@%
  16936.   %@AS@%same:       .                  ; Both equal%@AE@%%@NL@%
  16937.   %@AS@%            .%@AE@%%@NL@%
  16938.   %@AS@%rectangle:  .                  ; Rectangle bigger%@AE@%%@NL@%
  16939.   %@AS@%            .%@AE@%%@NL@%
  16940.   %@AS@%circle:     .                  ; Circle bigger%@AE@%%@NL@%
  16941. %@NL@%
  16942. %@4@%  Notice how conditional blocks are used to enhance 80287 code. If you%@EH@%
  16943.   define the symbol %@AS@%c287 %@AE@%from the command line by using the /D%@AB@% %@AE@%%@AI@%symbol%@AE@% option
  16944.   (see Section B.4%@BO:       f8ea4@%, "Defining Assembler Symbols"), the code is smaller and
  16945.   faster, but does not run on an 8087.%@NL@%
  16946. %@NL@%
  16947. %@NL@%
  16948. %@3@%%@CR:SC17.7.2    @%%@AB@%17.7.2  Testing Control Flags after Other Instructions%@AE@%%@EH@%%@NL@%
  16949. %@NL@%
  16950. %@4@%%@CR:IX17.174    @%%@CR:IX17.175    @%  In addition to the compare instructions, the %@AB@%FXAM%@AE@% and %@AB@%FPREM%@AE@% instructions%@EH@%
  16951.   affect coprocessor control flags.%@NL@%
  16952. %@NL@%
  16953. %@4@%  The %@AB@%FXAM%@AE@% instruction sets the value of the control flags based on the type%@EH@%
  16954.   of the number in the stack top (ST). This instruction is used to identify
  16955.   and handle special values, such as infinity, zero, unnormal numbers,
  16956.   denormal numbers, and NANs (not a number). Certain math operations are
  16957.   capable of producing these special-format numbers. A description of them
  16958.   is beyond the scope of this manual. The possible settings of the flags are
  16959.   shown in the on-line Help system.%@NL@%
  16960. %@NL@%
  16961. %@4@%%@CR:IX17.176    @%%@CR:IX17.177    @%  %@AB@%FPREM%@AE@% also sets control flags. Since this instruction must sometimes be%@EH@%
  16962.   repeated to get a correct remainder for large operands, it uses the C2
  16963.   flag to indicate whether the remainder returned is partial (C2 is set) or
  16964.   complete (C2 is clear). If the bit is set, the operation should be
  16965.   repeated.%@NL@%
  16966. %@NL@%
  16967. %@4@%  %@AB@%FPREM%@AE@% also returns the least-significant three bits of the quotient in C0,%@EH@%
  16968.   C3, and C1. These bits are useful for reducing operands of periodic
  16969.   transcendental functions, such as sine and cosine, to an acceptable range.
  16970.   The technique is not explained here. The possible settings for each flag
  16971.   are shown in the on-line Help system.%@NL@%
  16972. %@NL@%
  16973. %@NL@%
  16974. %@2@%%@CR:SC17.8      @%%@AB@%17.8  Using Transcendental Instructions%@AE@%%@EH@%%@NL@%
  16975. %@NL@%
  16976. %@4@%%@CR:IX17.178    @%%@CR:IX17.179    @%%@CR:IX17.180    @%%@CR:IX17.181    @%  The 8087-family coprocessors provide a variety of instructions for doing%@EH@%
  16977.   transcendental calculations, including exponentiation, logarithmic
  16978.   calculations, and some trigonometric functions.%@NL@%
  16979. %@NL@%
  16980. %@4@%  Use of these advanced instructions is beyond the scope of this manual.%@EH@%
  16981.   However, the instructions are listed below for reference. All
  16982.   transcendental instructions have implied operands──either ST as a
  16983.   single-destination operand, or ST as the destination and ST(1) as the
  16984.   source.%@NL@%
  16985. %@NL@%
  16986.   %@AB@%Instruction%@AE@%         %@AB@%Description%@AE@%%@NL@%
  16987.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  16988. %@CR:IX17.182    @%%@CR:IX17.183    @%  %@AB@%F2XM1%@AE@%               Calculates 2^x-1, where %@AI@%x%@AE@% is the value of the stack
  16989.                       top. The value %@AI@%x%@AE@% must be between 0 and .5, inclusive.
  16990.                       Returning 2^x-1 instead of 2^x allows the instruction
  16991.                       to return the value with greater accuracy. The
  16992.                       programmer can adjust the result to get 2^x.%@NL@%
  16993. %@NL@%
  16994. %@CR:IX17.184    @%%@CR:IX17.185    @%  %@AB@%FYL2X%@AE@%               Calculates %@AI@%Y%@AE@% times log2 %@AI@%X%@AE@%, where %@AI@%X%@AE@% is in ST and %@AI@%Y%@AE@% is
  16995.                       in ST(1). The stack is popped, so both %@AI@%X%@AE@% and %@AI@%Y%@AE@% are
  16996.                       destroyed, leaving the result in ST. The value of %@AI@%X%@AE@%
  16997.                       must be positive.%@NL@%
  16998. %@NL@%
  16999. %@CR:IX17.186    @%%@CR:IX17.187    @%  %@AB@%FYL2XP1%@AE@%             Calculates %@AI@%Y%@AE@% times log2 (%@AI@%X%@AE@%+1), where %@AI@%X%@AE@% is in ST and %@AI@%Y%@AE@%
  17000.                       is in ST(1). The stack is popped, so both %@AI@%X%@AE@% and %@AI@%Y%@AE@% are
  17001.                       destroyed, leaving the result in ST. The absolute
  17002.                       value of %@AI@%X%@AE@% must be between 0 and the square root of 2
  17003.                       divided by 2. This instruction is more accurate than
  17004.                       %@AB@%FYL2X%@AE@% when computing the log of a number close to 1.%@NL@%
  17005. %@NL@%
  17006. %@CR:IX17.188    @%%@CR:IX17.189    @%  %@AB@%FPTAN%@AE@%               Calculates the tangent of the value in ST. The result
  17007.                       is a ratio %@AI@%Y%@AE@%/%@AI@%X%@AE@%, with %@AI@%Y%@AE@% replacing the value in ST and %@AI@%X%@AE@%
  17008.                       pushed onto the stack so that after the instruction,
  17009.                       ST contains %@AI@%Y%@AE@% and ST(1) contains %@AI@%X%@AE@%. The value being
  17010.                       calculated must be a positive number less than pi/4.
  17011.                       The result of the %@AB@%FPTAN%@AE@% instruction can be used to
  17012.                       calculate other trigonometric functions, including
  17013.                       sine and cosine.%@NL@%
  17014. %@NL@%
  17015. %@CR:IX17.190    @%%@CR:IX17.191    @%  %@AB@%FPATAN%@AE@%              Calculates the arctangent of the ratio %@AI@%Y%@AE@%/%@AI@%X%@AE@%, where %@AI@%X%@AE@% is
  17016.                       in ST and %@AI@%Y%@AE@% is in ST(1). The stack is popped, so both
  17017.                       %@AI@%X%@AE@% and %@AI@%Y%@AE@% are destroyed, leaving the result in ST. Both
  17018.                       %@AI@%X%@AE@% and %@AI@%Y%@AE@% must be positive numbers less than infinity,
  17019.                       and %@AI@%Y%@AE@% must be less than %@AI@%X%@AE@%. The result of the %@AB@%FPATAN%@AE@%
  17020.                       instruction can be used to calculate other inverse
  17021.                       trigonometric functions, including arcsine and
  17022.                       arccosine.%@NL@%
  17023. %@NL@%
  17024. %@NL@%
  17025. %@NL@%
  17026. %@2@%%@CR:SC17.9      @%%@AB@%17.9  Controlling the Coprocessor%@AE@%%@EH@%%@NL@%
  17027. %@NL@%
  17028. %@4@%%@CR:IX17.192    @%%@CR:IX17.193    @%  Additional instructions are available for controlling various aspects of%@EH@%
  17029.   the coprocessor. With the exception of %@AB@%FINIT%@AE@%, these instructions are
  17030.   generally used only by systems programmers. They are summarized below, but
  17031.   not fully explained or illustrated. Some instructions have a wait version
  17032.   and a no-wait version. The no-wait versions have %@AB@%N%@AE@% as the second letter.%@NL@%
  17033. %@NL@%
  17034.   %@AB@%Syntax%@AE@%              %@AB@%Description%@AE@%%@NL@%
  17035.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17036. %@CR:IX17.194    @%%@CR:IX17.195    @%%@CR:IX17.196    @%  %@AB@%F%@AE@%[[%@AB@%N%@AE@%]]%@AB@%INIT%@AE@%          Resets the coprocessor and restores all the default
  17037.                       conditions in the control and status words. It is a
  17038.                       good idea to use this instruction at the start and end
  17039.                       of your program. Placing it at the start ensures that
  17040.                       no register values from previous programs affect your
  17041.                       program. Placing it at the end ensures that register
  17042.                       values from your program will not affect later
  17043.                       programs.%@NL@%
  17044. %@NL@%
  17045.   %@AB@%F%@AE@%[[%@AB@%N%@AE@%]]%@AB@%CLEX%@AE@%          Clears all exception flags and the busy flag of the
  17046.                       status word. It also clears the error-status flag on
  17047.                       the 80287, or the interrupt-request flag on the 8087.%@NL@%
  17048. %@NL@%
  17049.   %@AB@%FINCSTP%@AE@%             Adds 1 to the stack pointer in the status word. Do not
  17050.                       use to pop the register stack. No tags or registers
  17051.                       are altered.%@NL@%
  17052. %@NL@%
  17053.   %@AB@%FDECSTP%@AE@%             Subtracts 1 from the stack pointer in the status word.
  17054.                       No tags or registers are altered.%@NL@%
  17055. %@NL@%
  17056.   %@AB@%FREE ST(%@AE@%%@AI@%num%@AE@%%@AB@%)%@AE@%        Marks the specified register as empty.%@NL@%
  17057. %@NL@%
  17058.   %@AB@%FNOP%@AE@%                Copies the stack top to itself, thus padding the
  17059.                       executable file and taking up processing time without
  17060.                       having any effect on registers or memory.%@NL@%
  17061. %@NL@%
  17062. %@NL@%
  17063. %@4@%  %@AB@%8087 Only%@AE@%%@EH@%%@NL@%
  17064. %@NL@%
  17065. %@4@%  The 8087 has the instructions %@AB@%FDISI%@AE@%, %@AB@%FNDISI%@AE@%, %@AB@%FENI%@AE@%, and %@AB@%FNENI%@AE@%. These%@EH@%
  17066.   instructions can be used to enable or disable interrupts. The 80287
  17067.   coprocessor permits these instructions, but ignores them. Applications
  17068.   programmers will not normally need these instructions. Systems programmers
  17069.   should avoid using them so that their programs are portable to all
  17070.   coprocessors.%@NL@%
  17071. %@NL@%
  17072. %@NL@%
  17073. %@NL@%
  17074. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17075. %@1@%%@CR:CH18        @%%@AB@%Chapter 18:  Controlling the Processor%@AE@%%@EH@%%@NL@%
  17076. %@NL@%
  17077. %@NL@%
  17078. %@4@%  The 8086-family processors provide instructions for processor control.%@EH@%
  17079.   These instructions are available on all 8086-family processors.%@NL@%
  17080. %@NL@%
  17081. %@4@%  System-control instructions have limited use in applications programming.%@EH@%
  17082.   They are primarily used by systems programmers who write operating systems
  17083.   and other control software. Since systems programming is beyond the scope
  17084.   of this manual, the systems-control instructions are summarized, but not
  17085.   explained in detail, in the sections below.%@NL@%
  17086. %@NL@%
  17087. %@4@%  This chapter ends with a description of all the directives that enable the%@EH@%
  17088.   instruction sets for the various processors in the 8086 family.%@NL@%
  17089. %@NL@%
  17090. %@NL@%
  17091. %@2@%%@CR:SC18.1      @%%@AB@%18.1  Controlling Timing and Alignment%@AE@%%@EH@%%@NL@%
  17092. %@NL@%
  17093. %@4@%%@CR:IX18.1      @%%@CR:IX18.2      @%  The %@AB@%NOP%@AE@% instruction takes up one byte of memory but does not have any%@EH@%
  17094.   effect when executed. The purpose of this instruction is generally to fill
  17095.   up space in the code segment; primarily, it is used to pad executable code
  17096.   for alignment.%@NL@%
  17097. %@NL@%
  17098. %@4@%  Although%@AB@% NOP%@AE@% has no effect, it does take a few clock cycles to execute. In%@EH@%
  17099.   a sense,%@AB@% NOP%@AE@% does do something──it is exactly equivalent to the following
  17100.   instruction:%@NL@%
  17101. %@NL@%
  17102.   %@AS@%            xchg    ax,ax       ; Exchange AX with itself%@AE@%%@NL@%
  17103. %@NL@%
  17104. %@4@%  Because %@AB@%NOP%@AE@% does use up some clock time, you can use it in timing loops by%@EH@%
  17105.   executing it many times. However, when writing a program for use on
  17106.   different machines, avoid using this technique. Timing loops that use %@AB@%NOP%@AE@%
  17107.   take different lengths of time on different machines. A better way to
  17108.   control timing is to use the DOS Get Time function, since it is based on
  17109.   the computer's internal clock rather than on the speed of the processor.%@NL@%
  17110. %@NL@%
  17111. %@4@%  QuickAssembler automatically inserts %@AB@%NOP%@AE@% instructions for padding when you%@EH@%
  17112.   use the %@AB@%ALIGN%@AE@% or %@AB@%EVEN%@AE@% directive (see Section 6.7%@BO:       67efe@%, "Aligning Data") to
  17113.   align data or code on a given boundary.%@NL@%
  17114. %@NL@%
  17115. %@NL@%
  17116. %@2@%%@CR:SC18.2      @%%@AB@%18.2  Controlling the Processor%@AE@%%@EH@%%@NL@%
  17117. %@NL@%
  17118. %@4@%  The %@AB@%LOCK%@AE@%, %@AB@%WAIT%@AE@%, %@AB@%ESC%@AE@%, and %@AB@%HLT%@AE@% instructions control different aspects of the%@EH@%
  17119.   processor.%@NL@%
  17120. %@NL@%
  17121. %@4@%  These instructions can be used to control processes handled by external%@EH@%
  17122.   coprocessors. The 8087-family coprocessors are the coprocessors most
  17123.   commonly used with 8086-family processors, but 8086-based machines can
  17124.   work with other coprocessors if they have the proper hardware and control
  17125.   software.%@NL@%
  17126. %@NL@%
  17127. %@4@%%@CR:IX18.3      @%  These instructions are summarized below:%@EH@%%@NL@%
  17128. %@NL@%
  17129.   %@AB@%Instruction%@AE@%         %@AB@%Description%@AE@%%@NL@%
  17130.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17131. %@CR:IX18.4      @%%@CR:IX18.5      @%  %@AB@%LOCK%@AE@%                Locks out other processors until a specified
  17132.                       instruction is finished. This is a prefix that
  17133.                       precedes the instruction. It can be used to make sure
  17134.                       that a coprocessor does not change data being worked
  17135.                       on by the processor.%@NL@%
  17136. %@NL@%
  17137. %@CR:IX18.6      @%%@CR:IX18.7      @%  %@AB@%WAIT%@AE@%                Instructs the processor to do nothing until it
  17138.                       receives a signal that a coprocessor has finished with
  17139.                       a task being performed at the same time. See Section
  17140.                       17.4%@BO:       de11e@%, "Coordinating Memory Access," for information
  17141.                       on using %@AB@%WAIT%@AE@% or its coprocessor equivalent, %@AB@%FWAIT%@AE@%,
  17142.                       with the 8087-family coprocessors.%@NL@%
  17143. %@NL@%
  17144. %@CR:IX18.8      @%%@CR:IX18.9      @%  %@AB@%ESC%@AE@%                 Provides an instruction and possibly a memory operand
  17145.                       for use by a coprocessor. QuickAssembler automatically
  17146.                       inserts %@AB@%ESC%@AE@% instructions when required for use with
  17147.                       8087-family coprocessors.%@NL@%
  17148. %@NL@%
  17149. %@CR:IX18.10     @%%@CR:IX18.11     @%  %@AB@%HLT%@AE@%                 Stops the processor until an interrupt is received. It
  17150.                       can be used in place of an endless loop if a program
  17151.                       needs to wait for an interrupt.%@NL@%
  17152. %@NL@%
  17153. %@NL@%
  17154. %@NL@%
  17155. %@2@%%@CR:SC18.3      @%%@AB@%18.3  Processor Directives%@AE@%%@EH@%%@NL@%
  17156. %@NL@%
  17157. %@4@%%@CR:IX18.12     @%%@CR:IX18.13     @%%@CR:IX18.14     @%  Processor and coprocessor directives define the instruction set that is%@EH@%
  17158.   recognized by QuickAssembler. They are listed and explained below:%@NL@%
  17159. %@NL@%
  17160.   %@AB@%Directive%@AE@%           %@AB@%Description%@AE@%%@NL@%
  17161.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17162. %@CR:IX18.15     @%%@CR:IX18.16     @%%@CR:IX18.17     @%  %@AB@%.8086%@AE@%               The %@AB@%.8086%@AE@% directive enables assembly of instructions
  17163.                       for the 8086 and 8088 processors and the 8087
  17164.                       coprocessor. It disables assembly of the instructions
  17165.                       unique to the 80186, 80286, and 80386 processors.%@NL@%
  17166. %@NL@%
  17167.                       This is the default mode and is used if no instruction
  17168.                       set directive is specified. Using the default
  17169.                       instruction set ensures that your program can be used
  17170.                       on all 8086-family processors. However, if you choose
  17171.                       this directive, your program will not take advantage
  17172.                       of the more powerful instructions available on more
  17173.                       advanced processors.%@NL@%
  17174. %@NL@%
  17175. %@CR:IX18.18     @%%@CR:IX18.19     @%  %@AB@%.186%@AE@%                The %@AB@%.186%@AE@% directive enables assembly of the 8086
  17176.                       processor instructions, 8087 coprocessor instructions,
  17177.                       and the additional instructions for the 80186
  17178.                       processor.%@NL@%
  17179. %@NL@%
  17180. %@CR:IX18.20     @%%@CR:IX18.21     @%  %@AB@%.286%@AE@%                The %@AB@%.286%@AE@% directive enables assembly of the 8086
  17181.                       instructions plus the additional nonprivileged
  17182.                       instructions of the 80286 processor. It also enables
  17183.                       80287 coprocessor instructions. If privileged
  17184.                       instructions were previously enabled, the %@AB@%.286%@AE@%
  17185.                       directive disables them.%@NL@%
  17186. %@NL@%
  17187.                       This directive should be used for programs that will
  17188.                       be executed only by an 80186, 80286, or 80386
  17189.                       processor. For compatibility with early versions of
  17190.                       the Macro Assembler, the %@AB@%.286C%@AE@% directive is also
  17191.                       available. It is equivalent to the %@AB@%.286%@AE@% directive.%@NL@%
  17192. %@NL@%
  17193. %@CR:IX18.22     @%%@CR:IX18.23     @%  %@AB@%.8087%@AE@%               The %@AB@%.8087%@AE@% directive enables assembly of instructions
  17194.                       for the 8087 math coprocessor and disables assem-bly
  17195.                       of instructions unique to the 80287 coprocessor. It
  17196.                       also specifies the IEEE format for encoding
  17197.                       floating-point variables.%@NL@%
  17198. %@NL@%
  17199.                       This is the default mode and is used if no coprocessor
  17200.                       directive is specified. This directive should be used
  17201.                       for programs that must run with either the 8087,
  17202.                       80287, or 80387 coprocessors.%@NL@%
  17203. %@NL@%
  17204. %@CR:IX18.24     @%%@CR:IX18.25     @%  %@AB@%.287%@AE@%                The %@AB@%.287%@AE@% directive enables assembly of instructions
  17205.                       for the 8087 floating-point coprocessor and the
  17206.                       additional instructions for the 80287. It also
  17207.                       specifies the IEEE format for encoding floating-point
  17208.                       variables.%@NL@%
  17209. %@NL@%
  17210.                       Coprocessor instructions are optimized if you use this
  17211.                       directive rather than the %@AB@%.8087%@AE@% directive. Therefore,
  17212.                       you should use it if you know your program will never
  17213.                       need to run under an 8087 coprocessor. See Section
  17214.                       17.4%@BO:       de11e@%, "Coordinating Memory Access," for an
  17215.                       explanation.%@NL@%
  17216. %@NL@%
  17217. %@NL@%
  17218. %@4@%  If you do not specify any processor directives, QuickAssembler uses the%@EH@%
  17219.   following defaults:%@NL@%
  17220. %@NL@%
  17221.   1. 8086/8088 processor instruction set%@NL@%
  17222. %@NL@%
  17223.   2. 8087 coprocessor instruction set%@NL@%
  17224. %@NL@%
  17225.   3. IEEE format for floating-point variables%@NL@%
  17226. %@NL@%
  17227. %@4@%  Normally, the processor and coprocessor directives can be used at the%@EH@%
  17228.   start of the source file to define the instruction sets for the entire
  17229.   assembly. However, it is possible to use different processor directives at
  17230.   different points in the source file to change assumptions for a section of
  17231.   code. For instance, you might have processor-specific code in different
  17232.   parts of the same source file. You can also turn privileged instructions
  17233.   on and off or allow unusual combinations of the processor and coprocessor.%@NL@%
  17234. %@NL@%
  17235. %@4@%  There are two limitations on changing the processor or coprocessor:%@EH@%%@NL@%
  17236. %@NL@%
  17237.   1. The directives must be given outside segments. You must end the current
  17238.      segment, give the processor directive, and then open another segment.
  17239.      See Section 5.1.5%@BO:       47722@%, "Using Predefined Segment Equates," for an example
  17240.      of changing the processor directives with simplified segment
  17241.      directives.%@NL@%
  17242. %@NL@%
  17243.   2. You can specify a lower-level coprocessor with a higher-level
  17244.      coprocessor, but an error message will be generated if you try to
  17245.      specify a lower-level processor with a higher-level coprocessor.%@NL@%
  17246. %@NL@%
  17247. %@4@%  The coprocessor directives have the opposite effect of the %@AB@%.MSFLOAT%@AE@%%@EH@%
  17248.   directive. %@AB@%.MSFLOAT%@AE@% turns off coprocessor instruction sets and enables the
  17249.   Microsoft Binary format for floating-point variables. Any coprocessor
  17250.   instruction turns on the specified coprocessor instruction set and enables
  17251.   IEEE format for floating-point variables.%@NL@%
  17252. %@NL@%
  17253. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  17254. %@NL@%
  17255.   %@AS@%; .MSFLOAT affects the source file until turned off%@AE@%%@NL@%
  17256.   %@AS@%            .MSFLOAT%@AE@%%@NL@%
  17257.   %@AS@%            .8087              ; Ignored%@AE@%%@NL@%
  17258. %@NL@%
  17259.   %@AS@%; Illegal - can't use 8086 with 80287%@AE@%%@NL@%
  17260.   %@AS@%            .8086%@AE@%%@NL@%
  17261.   %@AS@%            .287%@AE@%%@NL@%
  17262. %@NL@%
  17263. %@NL@%
  17264. %@NL@%
  17265. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17266. %@1@%%@CR:CHA         @%%@AB@%Appendix A:  Mixed-Language Mechanics%@AE@%%@EH@%%@NL@%
  17267. %@NL@%
  17268. %@NL@%
  17269. %@4@%%@CR:IXA.1       @%%@CR:IXA.2       @%%@CR:IXA.3       @%%@CR:IXA.4       @%  The QuickAssembler %@AB@%PROC%@AE@% statement automates most details of interfacing to%@EH@%
  17270.   QuickC, as well as to other Microsoft high-level languages. When you use
  17271.   %@AB@%PROC%@AE@% with a parameter list or %@AB@%USES%@AE@% clause as described in Section 15.3.4%@BO:       c7284@%,
  17272.   or when you use the %@AB@%LOCAL%@AE@% directive, the assembler generates code that
  17273.   properly enters and exits the procedure. The assembler also determines the
  17274.   location of each parameter on the stack for you. You refer to each
  17275.   parameter by a meaningful name, and the assembler translates each
  17276.   parameter name into the actual memory reference.%@NL@%
  17277. %@NL@%
  17278. %@4@%  The main purpose of this appendix is to show you what code the assembler%@EH@%
  17279.   generates when you use the %@AB@%LOCAL%@AE@% directive or expanded features of the
  17280.   %@AB@%PROC%@AE@% directive. However, you can write this code yourself rather than
  17281.   letting the assembler generate it. Doing so requires significant extra
  17282.   work, but it does give you complete control over your procedure.%@NL@%
  17283. %@NL@%
  17284. %@4@%  Using simplified segment directives is the easiest way to interface with a%@EH@%
  17285.   Microsoft high-level language (including QuickC). The simplified segment
  17286.   directives generate segment definitions similar to the ones generated by
  17287.   high-level languages and guarantee compatibility in the use of segment
  17288.   names and conventions. If you want to use full segment definitions, see
  17289.   Chapter 5%@BO:       3ffad@%, "Defining Segment Structure," for a description of the
  17290.   segments used in Microsoft languages.%@NL@%
  17291. %@NL@%
  17292. %@NL@%
  17293. %@2@%%@CR:SCA.1       @%%@AB@%A.1  Writing the Assembly Procedure%@AE@%%@EH@%%@NL@%
  17294. %@NL@%
  17295. %@4@%  The Microsoft BASIC, C, FORTRAN, and Pascal compilers use roughly the same%@EH@%
  17296.   interface for procedure calls. This section describes the interface, so
  17297.   that you can call assembly procedures using essentially the same methods
  17298.   as Microsoft compiler-generated code. Procedures written with these
  17299.   methods can be called recursively.%@NL@%
  17300. %@NL@%
  17301. %@4@%  The standard assembly-interface method consists of these steps:%@EH@%%@NL@%
  17302. %@NL@%
  17303.   1. Setting up the procedure%@NL@%
  17304. %@NL@%
  17305.   2. Entering the procedure%@NL@%
  17306. %@NL@%
  17307.   3. Allocating local data (optional)%@NL@%
  17308. %@NL@%
  17309.   4. Preserving register values%@NL@%
  17310. %@NL@%
  17311.   5. Accessing parameters%@NL@%
  17312. %@NL@%
  17313.   6. Returning a value (optional)%@NL@%
  17314. %@NL@%
  17315.   7. Exiting the procedure%@NL@%
  17316. %@NL@%
  17317. %@4@%  The %@AB@%PROC%@AE@% statement, when used with a parameter list or %@AB@%USES%@AE@% clause,%@EH@%
  17318.   automates steps 1 and 2, and simplifies step 5 for you. The %@AB@%LOCAL%@AE@%
  17319.   directive automates step 3, and the %@AB@%USES%@AE@% clause automates step 4. Finally,
  17320.   if you use any of these features, the assembler automatically generates
  17321.   all the proper code to exit (step 7) wherever it encounters a %@AB@%RET%@AE@%
  17322.   directive. (However, the %@AB@%RETF%@AE@% and %@AB@%RETN%@AE@% statements never generate automatic
  17323.   code.)%@NL@%
  17324. %@NL@%
  17325. %@4@%  Sections A.1.1%@BO:       ee356@%-A.1.7 describe these steps.%@EH@%%@NL@%
  17326. %@NL@%
  17327. %@NL@%
  17328. %@3@%%@CR:SCA.1.1     @%%@AB@%A.1.1  Setting Up the Procedure%@AE@%%@EH@%%@NL@%
  17329. %@NL@%
  17330. %@4@%  The linker cannot combine the assembly procedure with the calling program%@EH@%
  17331.   unless compatible segments are used and unless the procedure itself is
  17332.   declared properly. The following points may be helpful:%@NL@%
  17333. %@NL@%
  17334. %@CR:IXA.5       @%%@CR:IXA.6       @%%@CR:IXA.7       @%%@CR:IXA.8       @%%@CR:IXA.9       @%%@CR:IXA.10      @%  1. Use the %@AB@%.MODEL%@AE@% directive at the beginning of the source file; this
  17335.      directive automatically causes the appropriate kind of returns to be
  17336.      generated (%@AB@%NEAR%@AE@% for small or compact model, %@AB@%FAR%@AE@% otherwise). Modules
  17337.      called from Pascal should be declared as %@AB@%.MODEL LARGE%@AE@%; modules called
  17338.      from BASIC should be %@AB@%.MODEL MEDIUM%@AE@%.%@NL@%
  17339. %@NL@%
  17340. %@CR:IXA.11      @%%@CR:IXA.12      @%  2. Use the simplified segment directives: %@AB@%.CODE%@AE@% to declare the code
  17341.      segment and %@AB@%.DATA%@AE@% to declare the data segment. (Having a code segment
  17342.      is sufficient if you do not have data declarations.)%@NL@%
  17343. %@NL@%
  17344.   3. Tie procedure label must be public. This makes the procedure available
  17345.      to be called by other modules. If you specify a language type with the
  17346.      %@AB@%.MODEL%@AE@% directive, the assembler automatically makes all procedure names
  17347.      public, but you must use the %@AB@%PUBLIC%@AE@% directive if you don't specify the
  17348.      language. Also, any data you want to make public to other modules must
  17349.      be declared as %@AB@%PUBLIC%@AE@%.%@NL@%
  17350. %@NL@%
  17351.   4. Global data or procedures accessed by the routine (but defined in other
  17352.      modules) must be declared %@AB@%EXTRN%@AE@%.%@NL@%
  17353. %@NL@%
  17354. %@NL@%
  17355. %@3@%%@CR:SCA.1.2     @%%@AB@%A.1.2  Entering the Procedure%@AE@%%@EH@%%@NL@%
  17356. %@NL@%
  17357. %@4@%%@CR:IXA.13      @%  Two instructions begin the procedure:%@EH@%%@NL@%
  17358. %@NL@%
  17359.   %@AS@%            push    bp%@AE@%%@NL@%
  17360.   %@AS@%            mov     bp,sp%@AE@%%@NL@%
  17361. %@NL@%
  17362. %@4@%%@CR:IXA.14      @%  This sequence establishes BP as the framepointer. The framepointer is used%@EH@%
  17363.   to access parameters and local data, which are located on the stack. SP
  17364.   cannot be used for this purpose because it is not an index or base
  17365.   register. Also, the value of SP may change as more data is pushed onto the
  17366.   stack. However, the value of the base register (BP) will remain constant
  17367.   throughout the procedure, so that each parameter can be addressed as a
  17368.   fixed displacement from the location pointed to by BP.%@NL@%
  17369. %@NL@%
  17370. %@4@%  The instruction sequence above first saves the value of BP, since it will%@EH@%
  17371.   be needed by the calling procedure as soon as the current procedure
  17372.   terminates. Then BP is loaded with the value of SP in order to capture the
  17373.   value of the stack pointer at the time of entry to the procedure.%@NL@%
  17374. %@NL@%
  17375. %@4@%  The %@AB@%PROC%@AE@% statement generates these two lines of code automatically if you%@EH@%
  17376.   use a parameter list, %@AB@%LOCAL%@AE@% directive, or %@AB@%USES%@AE@% clause.%@NL@%
  17377. %@NL@%
  17378.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17379.   %@AB@%NOTE%@AE@%  If you alter the direction flag with the %@AB@%STD%@AE@% instruction, make sure
  17380.   you reset this flag with the %@AB@%CLD%@AE@% instruction before you exit.%@NL@%
  17381.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17382. %@NL@%
  17383. %@NL@%
  17384. %@3@%%@CR:SCA.1.3     @%%@AB@%A.1.3  Allocating Local Data (Optional)%@AE@%%@EH@%%@NL@%
  17385. %@NL@%
  17386. %@4@%%@CR:IXA.15      @%%@CR:IXA.16      @%%@CR:IXA.17      @%%@CR:IXA.18      @%%@CR:IXA.19      @%  Local variables are also called dynamic, stack, or automatic variables.%@EH@%%@NL@%
  17387. %@NL@%
  17388. %@4@%%@CR:IXA.20      @%  An assembly procedure can use the same technique for implementing local%@EH@%
  17389.   data used by high-level languages. To set up local data space, decrease
  17390.   the contents of SP in the third instruction of the procedure. (To ensure
  17391.   correct execution, you should always increase or decrease SP by an even
  17392.   amount.) Decreasing SP reserves space on the stack for the local data. The
  17393.   space must be restored at the end of the procedure.%@NL@%
  17394. %@NL@%
  17395.   %@AS@%            push   bp%@AE@%%@NL@%
  17396.   %@AS@%            mov    bp,sp%@AE@%%@NL@%
  17397.   %@AS@%            sub    sp,%@AE@%%@AI@%space%@AE@%%@NL@%
  17398. %@NL@%
  17399. %@4@%  In the code above, %@AI@%space%@AE@% is the total size in bytes of the local data.%@EH@%
  17400.   Local variables are then accessed as fixed, negative displacements from
  17401.   the location pointed to by BP.%@NL@%
  17402. %@NL@%
  17403. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  17404. %@NL@%
  17405.   %@AS@%            push   bp%@AE@%%@NL@%
  17406.   %@AS@%            mov    bp,sp%@AE@%%@NL@%
  17407.   %@AS@%            sub    sp,4%@AE@%%@NL@%
  17408.   %@AS@%            .%@AE@%%@NL@%
  17409.   %@AS@%            .%@AE@%%@NL@%
  17410.   %@AS@%            .%@AE@%%@NL@%
  17411.   %@AS@%            mov    WORD PTR [bp-2],0%@AE@%%@NL@%
  17412.   %@AS@%            mov    WORD PTR [bp-4],0%@AE@%%@NL@%
  17413. %@NL@%
  17414. %@4@%  The example above uses two local variables, each of which is two bytes in%@EH@%
  17415.   size. SP is decreased by 4, since there are four bytes total of local
  17416.   data. Later, each of the variables is initialized to 0. These variables
  17417.   are never formally declared with any assembler directive; the programmer
  17418.   must keep track of them manually.%@NL@%
  17419. %@NL@%
  17420. %@4@%  The %@AB@%LOCAL%@AE@% directive uses this same method for creating local variables.%@EH@%
  17421.   However, when you use %@AB@%LOCAL%@AE@%, you can refer to a local variable by a
  17422.   symbolic name rather than by a reference, such as %@AS@%WORD PTR [bp-2]%@AE@%.%@NL@%
  17423. %@NL@%
  17424. %@NL@%
  17425. %@3@%%@CR:SCA.1.4     @%%@AB@%A.1.4  Preserving Register Values%@AE@%%@EH@%%@NL@%
  17426. %@NL@%
  17427. %@4@%%@CR:IXA.21      @%  A procedure called from any of the Microsoft high-level languages should%@EH@%
  17428.   preserve the values of SI, DI, SS, and DS (in addition to BP, which is
  17429.   already saved). Therefore, push any of these register values that the
  17430.   procedure alters. If the procedure does not change the value of any of
  17431.   these registers, the registers do not need to be pushed.%@NL@%
  17432. %@NL@%
  17433. %@4@%%@CR:IXA.22      @%  The recommended method (used by high-level languages) is to save registers%@EH@%
  17434.   after the framepointer is set and local data (if any) is allocated.%@NL@%
  17435. %@NL@%
  17436.   %@AS@%            push   bp           ; Save old framepointer%@AE@%%@NL@%
  17437.   %@AS@%            mov    bp,sp        ; Establish current framepointer%@AE@%%@NL@%
  17438.   %@AS@%            sub    sp,4         ; Allocate local data space%@AE@%%@NL@%
  17439.   %@AS@%            push   si           ; Save SI and DI%@AE@%%@NL@%
  17440.   %@AS@%            push   di%@AE@%%@NL@%
  17441.   %@AS@%            .%@AE@%%@NL@%
  17442.   %@AS@%            .%@AE@%%@NL@%
  17443.   %@AS@%            .%@AE@%%@NL@%
  17444. %@NL@%
  17445. %@4@%  In the example above, DI and SI (in that order) must be popped from the%@EH@%
  17446.   stack before the end of the procedure.%@NL@%
  17447. %@NL@%
  17448. %@4@%  The %@AB@%USES%@AE@% clause in a %@AB@%PROC%@AE@% statement causes the assembler to generate this%@EH@%
  17449.   same code.%@NL@%
  17450. %@NL@%
  17451. %@NL@%
  17452. %@3@%%@CR:SCA.1.5     @%%@AB@%A.1.5  Accessing Parameters%@AE@%%@EH@%%@NL@%
  17453. %@NL@%
  17454. %@4@%  When you use %@AB@%PROC%@AE@% with a parameter list, the assembler calculates the%@EH@%
  17455.   location of each parameter on the stack. This section shows how the
  17456.   assembler determines these locations. If you do not use a parameter list,
  17457.   you must calculate parameter locations yourself and refer to them
  17458.   explicitly by their offsets from BP. Otherwise, you can refer to each
  17459.   parameter by the name you gave it in the parameter list.%@NL@%
  17460. %@NL@%
  17461. %@4@%%@CR:IXA.23      @%%@CR:IXA.24      @%  To write instructions that can access parameters, consider the general%@EH@%
  17462.   picture of the stack frame after a procedure call, as illustrated in
  17463.   Figure A.1.%@NL@%
  17464. %@NL@%
  17465.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  17466.   │ This figure can be found in Section A.1.5 of the manual                │%@NL@%
  17467.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  17468. %@NL@%
  17469. %@4@%  When determining the order of parameters on the stack, note that the C%@EH@%
  17470.   calling convention (the default for QuickC) specifies that parameters are
  17471.   passed in the reverse order they appear in source code. The non-C calling
  17472.   convention (which you can specify in QuickC with the %@AB@%pascal%@AE@% or %@AB@%fortran%@AE@%
  17473.   keyword) specifies that parameters are passed in the same order they
  17474.   appear in source code.%@NL@%
  17475. %@NL@%
  17476. %@4@%%@CR:IXA.25      @%  The stack frame for the procedure is established by the following%@EH@%
  17477.   sequence:%@NL@%
  17478. %@NL@%
  17479.   1. The calling program pushes each of the parameters on the stack, after
  17480.      which SP points to the last parameter pushed.%@NL@%
  17481. %@NL@%
  17482.   2. The calling program issues a %@AB@%CALL%@AE@% instruction, which causes the return
  17483.      address (the place in the calling program to which control will
  17484.      ultimately return) to be placed on the stack. This address may be
  17485.      either two bytes long (for near calls) or four bytes long (for far
  17486.      calls). SP now points to this address.%@NL@%
  17487. %@NL@%
  17488. %@CR:IXA.26      @%  3. The first instruction of the called procedure saves the old value of
  17489.      BP, with the instruction %@AS@%push bp%@AE@%. SP now points to the saved copy of
  17490.      BP.%@NL@%
  17491. %@NL@%
  17492.   4. BP is used to capture the current value of SP, with the instruction %@AS@%mov%@AE@%
  17493.      %@AS@%bp,sp%@AE@%. BP therefore now points to the old value of BP.%@NL@%
  17494. %@NL@%
  17495. %@CR:IXA.27      @%  5. Whereas BP remains constant throughout the procedure, SP may be
  17496.      decreased to provide room on the stack for local data or saved
  17497.      registers.%@NL@%
  17498. %@NL@%
  17499. %@4@%  In general, the displacement (from the location pointed to by BP) for a%@EH@%
  17500.   parameter %@AS@%X%@AE@% is equal to:%@NL@%
  17501. %@NL@%
  17502.   %@AS@%2 + size of return address + total size of parameters between X and BP%@AE@%%@NL@%
  17503. %@NL@%
  17504. %@4@%  For example, consider a %@AB@%FAR%@AE@% procedure that has received one parameter, a%@EH@%
  17505.   two-byte address. The displacement of the parameter would be:%@NL@%
  17506. %@NL@%
  17507.   %@AS@%Argument's displacement =  2 + size of return address%@AE@%%@NL@%
  17508.   %@AS@%                        =  2 + 4%@AE@%%@NL@%
  17509.   %@AS@%                        =  6%@AE@%%@NL@%
  17510. %@NL@%
  17511. %@4@%  The argument can thus be loaded into BX with the following instruction:%@EH@%%@NL@%
  17512. %@NL@%
  17513.   %@AS@%            mov     bx,[bp+6]%@AE@%%@NL@%
  17514. %@NL@%
  17515. %@4@%%@CR:IXA.28      @%  Once you determine the displacement of each parameter, you may want to use%@EH@%
  17516.   string equates or structures so that the parameter can be referenced with
  17517.   a single identifier name in your assembly source code. For example, the
  17518.   parameter above at BP+6 can be conveniently accessed if you put the
  17519.   following statement at the beginning of the assembly source file:%@NL@%
  17520. %@NL@%
  17521.   %@AS@%Arg1        EQU     <[bp+6]>%@AE@%%@NL@%
  17522. %@NL@%
  17523. %@4@%  You could then refer to this parameter as %@AS@%Arg1 %@AE@%in any instruction. Use of%@EH@%
  17524.   this feature is optional.%@NL@%
  17525. %@NL@%
  17526.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17527.   %@AB@%NOTE%@AE@%  Microsoft high-level languages always push segment addresses before
  17528.   pushing offset addresses. Furthermore, when pushing arguments larger than
  17529.   two bytes, high-order words are always pushed before low-order words.%@NL@%
  17530. %@CR:IXA.29      @%%@NL@%
  17531.   This standard for pushing segment addresses before pushing offset
  17532.   addresses facilitates the use of the %@AB@%LES%@AE@% and %@AB@%LDS%@AE@% instructions, as
  17533.   described in Chapter 3%@BO:       2aca0@%, "Writing Assembly Modules for C Programs."%@NL@%
  17534.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17535. %@NL@%
  17536. %@NL@%
  17537. %@3@%%@CR:SCA.1.6     @%%@AB@%A.1.6  Returning a Value (Optional)%@AE@%%@EH@%%@NL@%
  17538. %@NL@%
  17539. %@4@%  The assembler does not generate code to return a value. If you want your%@EH@%
  17540.   procedure to return a value, you must take care of the details yourself.%@NL@%
  17541. %@NL@%
  17542. %@4@%%@CR:IXA.30      @%  Microsoft BASIC, C, FORTRAN, and Pascal share similar conventions for%@EH@%
  17543.   receiving return values. The conventions are the same when the data type
  17544.   to be returned is simple (that is, not an array or structured type) and is
  17545.   no more than four bytes long. This includes all %@AB@%NEAR%@AE@% and %@AB@%FAR%@AE@% address types
  17546.   (in other words, all pointers and all parameters passed by reference).%@NL@%
  17547. %@NL@%
  17548.   %@AB@%Data Size%@AE@%           %@AB@%Returned in Register%@AE@%%@NL@%
  17549.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17550.   1 byte              AL%@NL@%
  17551. %@NL@%
  17552.   2 bytes             AX%@NL@%
  17553. %@NL@%
  17554.   4 bytes             High-order portion (or segment address) in DX;
  17555.                       low-order portion (or offset address) in AX%@NL@%
  17556. %@NL@%
  17557. %@NL@%
  17558. %@4@%%@CR:IXA.31      @%  When the return value is larger than four bytes, a procedure called by C%@EH@%
  17559.   must allocate space for the return value and then place its address in
  17560.   DX:AX. You can create space for the return value by simply declaring it in
  17561.   a data segment.%@NL@%
  17562. %@NL@%
  17563. %@4@%  If your assembly procedure uses the non-C calling convention, it must use%@EH@%
  17564.   a special convention in order to return floating-point values, records,
  17565.   user-defined types and arrays, and values larger than four bytes. This
  17566.   convention is presented below.%@NL@%
  17567. %@NL@%
  17568. %@4@%  %@AB@%BASIC/FORTRAN/Pascal Long Return Values%@AE@%%@EH@%%@NL@%
  17569. %@NL@%
  17570. %@4@%%@CR:IXA.32      @%%@CR:IXA.33      @%  To create an interface for long return values, modules using the non-C%@EH@%
  17571.   calling convention take the following actions before they call your
  17572.   procedure:%@NL@%
  17573. %@NL@%
  17574.   1. The calling modules create space, somewhere in the stack segment, to
  17575.      hold the actual return value.%@NL@%
  17576. %@NL@%
  17577. %@CR:IXA.34      @%  2. When the call to your procedure is made, an extra parameter is passed
  17578.      containing the offset address of the actual return value. This
  17579.      parameter is placed immediately above the return address. (In other
  17580.      words, this parameter is the last one pushed.)%@NL@%
  17581. %@NL@%
  17582.   3. The segment address of the return value is contained in both SS and DS.%@NL@%
  17583. %@NL@%
  17584. %@4@%%@CR:IXA.35      @%  The extra parameter (containing the offset address of the return value) is%@EH@%
  17585.   always located at BP+6. Furthermore, its presence automatically increases
  17586.   the displacement of all other parameters by 2, as shown in Figure A.2.%@NL@%
  17587. %@NL@%
  17588.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  17589.   │ This figure can be found in Section A.1.6 of the manual                │%@NL@%
  17590.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  17591. %@NL@%
  17592. %@4@%  Your assembly procedure will successfully return a long value if you%@EH@%
  17593.   follow these steps:%@NL@%
  17594. %@NL@%
  17595.   1. Put the data for the return value at the location pointed to by the
  17596.      return value offset.%@NL@%
  17597. %@NL@%
  17598.   2. Copy the return-value offset (located at BP+6) to AX, and copy SS to
  17599.      DX. This is necessary because the calling module expects DX:AX to point
  17600.      to the return value.%@NL@%
  17601. %@NL@%
  17602.   3. Exit the procedure as described in the next section.%@NL@%
  17603. %@NL@%
  17604. %@NL@%
  17605. %@3@%%@CR:SCA.1.7     @%%@AB@%A.1.7  Exiting the Procedure%@AE@%%@EH@%%@NL@%
  17606. %@NL@%
  17607. %@4@%%@CR:IXA.36      @%  Several steps may be involved in terminating the procedure:%@EH@%%@NL@%
  17608. %@NL@%
  17609.   1. If any of the registers SS, DS, SI, or DI have been saved, these must
  17610.      be popped off the stack in the reverse order that they were saved.%@NL@%
  17611. %@NL@%
  17612.   2. If local data space was allocated at the beginning of the procedure, SP
  17613.      must be restored with the instruction %@AS@%mov sp,bp%@AE@%.%@NL@%
  17614. %@NL@%
  17615.   3. Restore BP with %@AS@%pop bp%@AE@%. This step is always necessary.%@NL@%
  17616. %@NL@%
  17617.   4. Finally, return to the calling program with %@AS@%ret%@AE@%. If the BASIC, FORTRAN,
  17618.      or Pascal calling convention is in use, you can use the %@AS@%ret%@AE@% %@AI@%n%@AE@% form of
  17619.      the instruction to adjust the stack with respect to the parameters that
  17620.      were pushed by the caller. (If the procedure is called by a C module,
  17621.      the calling module will perform this adjustment.)%@NL@%
  17622. %@NL@%
  17623. %@4@%  %@AB@%Examples%@AE@%%@EH@%%@NL@%
  17624. %@NL@%
  17625.   %@AS@%            pop    bp%@AE@%%@NL@%
  17626.   %@AS@%            ret%@AE@%%@NL@%
  17627. %@NL@%
  17628. %@4@%  The example above shows the simplest possible exit sequence. No registers%@EH@%
  17629.   were saved, no local data space was allocated, and the C calling
  17630.   convention is in use.%@NL@%
  17631. %@NL@%
  17632.   %@AS@%            pop    di           ; Pop saved regs%@AE@%%@NL@%
  17633.   %@AS@%            pop    si%@AE@%%@NL@%
  17634.   %@AS@%            mov    sp,bp        ; Remove local data space%@AE@%%@NL@%
  17635.   %@AS@%            pop    bp           ; Restore old framepointer%@AE@%%@NL@%
  17636.   %@AS@%            ret    6            ; Exit, and restore 6 byte of args%@AE@%%@NL@%
  17637. %@NL@%
  17638. %@4@%  The example above shows an exit sequence for a procedure that has%@EH@%
  17639.   previously saved SI and DI, allocated local data space, and uses a non-C
  17640.   calling convention. The procedure must therefore use %@AS@%ret 6 %@AE@%(where %@AI@%n%@AE@% is 6)
  17641.   to restore the six bytes of parameters on the stack.%@NL@%
  17642. %@NL@%
  17643. %@4@%  Assuming you use one of the automated features described above (such as a%@EH@%
  17644.   parameter list or %@AB@%LOCAL%@AE@% directive), the assembler generates all the code
  17645.   to properly exit from a procedure whenever it encounters a %@AB@%RET%@AE@%
  17646.   instruction. However, the assembler does not generate any exit code when
  17647.   you use the directives %@AB@%RETN%@AE@% or %@AB@%RETF%@AE@%.%@NL@%
  17648. %@NL@%
  17649. %@NL@%
  17650. %@2@%%@CR:SCA.2       @%%@AB@%A.2  Calls from Modules Using C Conventions%@AE@%%@EH@%%@NL@%
  17651. %@NL@%
  17652. %@4@%  Most of the details below are automated when you use simplified segment%@EH@%
  17653.   directives and the expanded features of the %@AB@%PROC%@AE@% directive. Make sure to
  17654.   declare both a language type and a memory model with the %@AB@%.MODEL%@AE@% directive.%@NL@%
  17655. %@NL@%
  17656. %@4@%  This section reviews all the steps taken when you use the %@AB@%C%@AE@% language type.%@EH@%
  17657.   In addition to the steps outlined in Section A.1%@BO:       edd84@%, the assembler observes
  17658.   the following rules to set up an interface to C.%@NL@%
  17659. %@NL@%
  17660. %@4@%%@CR:IXA.37      @%%@CR:IXA.38      @%  Follow these rules if you want to manually establish this interface:%@EH@%%@NL@%
  17661. %@NL@%
  17662.   1. Declare procedures called from C as %@AB@%FAR%@AE@% if the C module is compiled in
  17663.      large, huge, or medium model, and %@AB@%NEAR%@AE@% if the C module is compiled in
  17664.      small or compact model (although the%@AB@% near%@AE@% and %@AB@%far%@AE@% keywords can override
  17665.      these defaults). The correct declaration for the procedure is made
  17666.      implicitly when you use the %@AB@%.MODEL%@AE@% directive. Note that tiny memory
  17667.      model is not supported by QuickC 2.0.%@NL@%
  17668. %@NL@%
  17669. %@CR:IXA.39      @%  2. Observe the C calling convention.%@NL@%
  17670. %@NL@%
  17671.      a. Return with a simple %@AS@%ret%@AE@% instruction. Do not restore the stack with
  17672.         %@AS@%ret%@AE@% %@AI@%size%@AE@%, since the calling C routine will restore the stack itself
  17673.         as soon as it resumes control.%@NL@%
  17674. %@NL@%
  17675.      b. Parameters are placed on the stack in the reverse order that they
  17676.         appear in the C source code. The first parameter will be lowest in
  17677.         memory (because it is placed on the stack last and the stack grows
  17678.         downward).%@NL@%
  17679. %@NL@%
  17680. %@CR:IXA.40      @%%@CR:IXA.41      @%%@CR:IXA.42      @%     c. By default, C parameters are passed by value, except for arrays,
  17681.         which are passed by reference. As a rule, do not expect an address
  17682.         to be placed on the stack, unless the C code specifically refers to
  17683.         a pointer or array in the function call or prototype.%@NL@%
  17684. %@NL@%
  17685.      3. Observe the C naming convention.%@NL@%
  17686. %@NL@%
  17687.      Include an underscore (_) in front of any name that will be shared
  17688.      publicly with C. C recognizes only the first eight characters of any
  17689.      name, so do not make names shared with C longer than eight characters.
  17690.      Also, if you plan to link with the /NOIGNORECASE option, remember that
  17691.      C is case sensitive and does not convert names to uppercase. To
  17692.      preserve lowercase names in public symbols, choose Preserve Case or
  17693.      Preserve Extrn from the Assembler Flags dialog box, or assemble with
  17694.      the /Cl or /Cx option on the QCL command line.%@NL@%
  17695. %@NL@%
  17696.   In the example program below, C calls an assembly procedure that
  17697.   calculates "A x 2^B," where A and B are the first and second parameters,
  17698.   respectively. The calculation is performed by shifting the bits in A to
  17699.   the left, B times.%@NL@%
  17700. %@NL@%
  17701.   %@AS@%extern int power2( int, int ),%@AE@%%@NL@%
  17702. %@NL@%
  17703.   %@AS@%main  ()%@AE@%%@NL@%
  17704.   %@AS@%{%@AE@%%@NL@%
  17705.   %@AS@%      printf( "3 times 2 to the power of 5 is %d\n",%@AE@%%@NL@%
  17706.   %@AS@%               power2( 3, 5 ) );%@AE@%%@NL@%
  17707.   %@AS@%}%@AE@%%@NL@%
  17708. %@NL@%
  17709. %@4@%  The C program uses an %@AB@%extern%@AE@% declaration to create an interface with the%@EH@%
  17710.   assembly procedure. No special keywords are required because the assembly
  17711.   procedure will use the C calling convention.%@NL@%
  17712. %@NL@%
  17713. %@4@%%@CR:IXA.43      @%  To understand how to write the assembly procedure, consider how the%@EH@%
  17714.   parameters are placed on the stack, as illustrated in Figure A.3.%@NL@%
  17715. %@NL@%
  17716.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  17717.   │ This figure can be found in Section A.2 of the manual                  │%@NL@%
  17718.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  17719. %@NL@%
  17720. %@4@%  The return address is two bytes long, assuming that the C module is%@EH@%
  17721.   compiled in small or compact model. If the C module is compiled in large,
  17722.   huge, or medium model, the addresses of Arg 1 and Arg 2 are each increased
  17723.   by 2, to BP+6 and BP+8, respectively, because the return address will be
  17724.   four bytes long.%@NL@%
  17725. %@NL@%
  17726. %@4@%%@CR:IXA.44      @%%@CR:IXA.45      @%  Arg 1 (parameter 1) is lower in memory than Arg 2, because C pushes%@EH@%
  17727.   arguments in the reverse order that they appear. Each argument is passed
  17728.   by value.%@NL@%
  17729. %@NL@%
  17730. %@4@%  The assembly procedure can be written as follows:%@EH@%%@NL@%
  17731. %@NL@%
  17732.   %@AS@%            .MODEL      small%@AE@%%@NL@%
  17733.   %@AS@%            .CODE%@AE@%%@NL@%
  17734.   %@AS@%            PUBLIC      _power2%@AE@%%@NL@%
  17735.   %@AS@%_power2           PROC%@AE@%%@NL@%
  17736.   %@AS@%            push                bp      ; Entry sequence - save old BP%@AE@%%@NL@%
  17737.   %@AS@%            mov         bp,sp           ; Set stack framepointer%@AE@%%@NL@%
  17738. %@NL@%
  17739.   %@AS@%            mov         ax,[bp+4]       ; Load Arg1 into AX%@AE@%%@NL@%
  17740.   %@AS@%            mov         cx,[bp+6]       ; Load Arg2 into CX%@AE@%%@NL@%
  17741.   %@AS@%            shl         ax,cl           ; AX = AX * (2 to power of CX)%@AE@%%@NL@%
  17742.   %@AS@%                                        ; Leave return value in AX%@AE@%%@NL@%
  17743. %@NL@%
  17744.   %@AS@%            pop         bp              ; Exit sequence - restore old BP%@AE@%%@NL@%
  17745.   %@AS@%            ret                         ; Return%@AE@%%@NL@%
  17746.   %@AS@%_power2           ENDP%@AE@%%@NL@%
  17747.   %@AS@%            END%@AE@%%@NL@%
  17748. %@NL@%
  17749. %@4@%%@CR:IXA.46      @%  The example above assumes that the C module is compiled in small model.%@EH@%
  17750.   The parameter offsets and the %@AB@%.MODEL%@AE@% directive will change for different
  17751.   models.%@NL@%
  17752. %@NL@%
  17753. %@4@%  Note that %@AS@%ret %@AE@%without a size variable is used, since the caller will%@EH@%
  17754.   adjust the stack upon return from the call.%@NL@%
  17755. %@NL@%
  17756. %@NL@%
  17757. %@2@%%@CR:SCA.3       @%%@AB@%A.3  Calls from Non-C Modules%@AE@%%@EH@%%@NL@%
  17758. %@NL@%
  17759. %@4@%  In your C programs you can specify the %@AB@%pascal%@AE@% or %@AB@%fortran%@AE@% function type.%@EH@%
  17760.   These keywords are equivalent: they both specify use of non-C calling and
  17761.   naming conventions. Furthermore, you may want to interface to languages
  17762.   other than C (which you can do by linking .OBJ files together outside the
  17763.   environment). In all these cases, make sure you specify %@AB@%BASIC%@AE@%, %@AB@%FORTRAN%@AE@%, or
  17764.   %@AB@%Pascal%@AE@% as the language type with the %@AB@%.MODEL%@AE@% directive. Alternately, you
  17765.   can specify the language as part of the procedure if you are using the
  17766.   extended %@AB@%PROC%@AE@% directive.%@NL@%
  17767. %@NL@%
  17768. %@4@%  This section reviews all the steps taken when you use a non-C language%@EH@%
  17769.   type. In addition to the steps outlined in Section A.1%@BO:       edd84@%, the assembler
  17770.   observes the following rules to set up an interface to a language using a
  17771.   non-C calling convention.%@NL@%
  17772. %@NL@%
  17773. %@4@%%@CR:IXA.47      @%%@CR:IXA.48      @%  Follow these rules if you want to manually establish an interface to a%@EH@%
  17774.   high-level language:%@NL@%
  17775. %@NL@%
  17776.   1. If the procedure is called from Microsoft BASIC, Pascal, or FORTRAN,
  17777.      make sure to declare the procedure as %@AB@%FAR%@AE@%, or use the %@AB@%.MODEL%@AE@% directive
  17778.      to specify medium or large memory model. BASIC always uses medium
  17779.      memory model; Pascal uses large memory model.%@NL@%
  17780. %@NL@%
  17781. %@CR:IXA.49      @%  2. Observe the non-C calling convention.%@NL@%
  17782. %@NL@%
  17783.      a. Upon exit, the procedure must reset SP to the value it had before
  17784.         the parameters were placed on the stack. This is accomplished with
  17785.         the instruction %@AS@%ret%@AE@% %@AI@%size%@AE@%, where %@AI@%size%@AE@% is the total size in bytes of
  17786.         all the parameters.%@NL@%
  17787. %@NL@%
  17788.      b. Parameters are placed on the stack in the same order in which they
  17789.         appear in the high-level language source code. The first parameter
  17790.         will be highest in memory (because it is placed on the stack first
  17791.         and the stack grows downward).%@NL@%
  17792. %@NL@%
  17793.      c. Each language has different defaults for passing parameters by value
  17794.         or reference. When a language passes by reference, it places a data
  17795.         pointer on the stack. When it passes by value, it places a complete
  17796.         copy of the parameter on the stack. Consult your language
  17797.         documentation for the details of when the language passes by value
  17798.         or reference. (In C, the default is by value except for arrays.)%@NL@%
  17799. %@NL@%
  17800.      3. Observe the language naming convention.%@NL@%
  17801. %@NL@%
  17802.      Microsoft BASIC, FORTRAN, and Pascal output symbolic names in uppercase
  17803.      characters, which is also the default behavior of the assembler. Each
  17804.      language recognizes a different number of characters in a name. For
  17805.      example, BASIC recognizes up to 40 characters of a name, whereas the
  17806.      assembler recognizes only the first 31.%@NL@%
  17807. %@NL@%
  17808.   In the following example program, QuickBASIC 4.0 calls an assembly
  17809.   procedure that calculates "A x 2B," where A and B are the first and second
  17810.   parameters, respectively. The calculation is performed by shifting the
  17811.   bits in A to the left, B times. (Note: with earlier versions of BASIC, you
  17812.   need to rewrite the example so that it calls a subprogram, not a
  17813.   function.)%@NL@%
  17814. %@NL@%
  17815.   %@AS@%' BASIC program%@AE@%%@NL@%
  17816.   %@AS@%DEFINT A-Z%@AE@%%@NL@%
  17817.   %@AS@%PRINT "3 times 2 to the power of 5 is ";%@AE@%%@NL@%
  17818.   %@AS@%PRINT Power2(3,5)%@AE@%%@NL@%
  17819.   %@AS@%END%@AE@%%@NL@%
  17820. %@NL@%
  17821. %@4@%  To understand how to write the assembly procedure, consider how the%@EH@%
  17822.   parameters are placed on the stack, as illustrated in Figure A.4.%@NL@%
  17823. %@NL@%
  17824.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  17825.   │ This figure can be found in Section A.3 of the manual                  │%@NL@%
  17826.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  17827. %@NL@%
  17828. %@4@%%@CR:IXA.50      @%%@CR:IXA.51      @%%@CR:IXA.52      @%  The return address is four bytes long because procedures called from BASIC%@EH@%
  17829.   must be %@AB@%FAR%@AE@%. Arg 1 (parameter 1) is higher in memory than Arg 2 because
  17830.   BASIC pushes arguments (parameters) in the same order in which they
  17831.   appear. Also, each argument is passed as a two-byte offset address, the
  17832.   BASIC default.%@NL@%
  17833. %@NL@%
  17834. %@4@%%@CR:IXA.53      @%  The assembly procedure can be written as follows:%@EH@%%@NL@%
  17835. %@NL@%
  17836.   %@AS@%            .MODEL      medium%@AE@%%@NL@%
  17837.   %@AS@%            .CODE%@AE@%%@NL@%
  17838.   %@AS@%            PUBLIC      Power2%@AE@%%@NL@%
  17839.   %@AS@%Power2      PROC%@AE@%%@NL@%
  17840.   %@AS@%            push        bp              ; Entry sequence - save old BP%@AE@%%@NL@%
  17841.   %@AS@%            mov         bpsp            ; Set stack framepointer%@AE@%%@NL@%
  17842. %@NL@%
  17843.   %@AS@%            mov         bx,[bp+8]       ; Load Arg1 into%@AE@%%@NL@%
  17844.   %@AS@%            mov         ax,[bx]         ;   AX%@AE@%%@NL@%
  17845.   %@AS@%            mov         bx,[bp]         ; Load Arg2 into%@AE@%%@NL@%
  17846.   %@AS@%            mov         cx,[bx]         ;   CX%@AE@%%@NL@%
  17847.   %@AS@%            shl         ax,cl           ; AX = AX * (2 to power of CX)%@AE@%%@NL@%
  17848.   %@AS@%                                        ; Leave return value in AX%@AE@%%@NL@%
  17849. %@NL@%
  17850.   %@AS@%            pop         bp              ; Exit sequence - restore old BP%@AE@%%@NL@%
  17851.   %@AS@%            ret         4               ; Return, and restore 4 bytes%@AE@%%@NL@%
  17852.   %@AS@%Power2      ENDP%@AE@%%@NL@%
  17853.   %@AS@%            END%@AE@%%@NL@%
  17854. %@NL@%
  17855. %@4@%  Note that each parameter must be loaded in a two-step process because the%@EH@%
  17856.   %@AI@%address%@AE@% of each is passed rather than the value. Also, note that the stack
  17857.   is restored with the instruction %@AS@%ret 4%@AE@%, since the total size of the
  17858.   parameters is four bytes.%@NL@%
  17859. %@NL@%
  17860. %@NL@%
  17861. %@2@%%@CR:SCA.4       @%%@AB@%A.4  Calling High-Level Languages from Assembly Language%@AE@%%@EH@%%@NL@%
  17862. %@NL@%
  17863. %@4@%%@CR:IXA.54      @%  Many high-level-language routines assume that certain initialization code%@EH@%
  17864.   has previously been executed; you can ensure that the proper
  17865.   initialization is performed by starting in a high-level-language module,
  17866.   and then calling an assembly procedure. The assembly procedure can then
  17867.   call high-level-language routines as needed, as shown in Figure A.5.%@NL@%
  17868. %@NL@%
  17869.   ┌────────────────────────────────────────────────────────────────────────┐%@NL@%
  17870.   │ This figure can be found in Section A.4 of the manual                  │%@NL@%
  17871.   └────────────────────────────────────────────────────────────────────────┘%@NL@%
  17872. %@NL@%
  17873. %@4@%  To execute an assembly call to a high-level language, you need to observe%@EH@%
  17874.   the following guidelines:%@NL@%
  17875. %@NL@%
  17876.   1. Push each parameter onto the stack, observing the calling convention of
  17877.      the high-level language. Constants, such as offset addresses, must
  17878.      first be loaded into a register before being pushed.%@NL@%
  17879. %@NL@%
  17880.   2. With long parameters, always push the segment or high-order portion of
  17881.      the parameter first, regardless of the calling convention.%@NL@%
  17882. %@NL@%
  17883.   3. If you are using the BASIC/FORTRAN/Pascal calling convention with a
  17884.      function that returns a noninteger value, allocate an additional
  17885.      two-byte parameter. This additional parameter should contain the offset
  17886.      of the location where you want the value returned and must be pushed on
  17887.      the stack last.%@NL@%
  17888. %@NL@%
  17889.   4. Execute a call. The call must be far unless the high-level-language
  17890.      routine is small model.%@NL@%
  17891. %@NL@%
  17892.   5. If the routine used the C calling convention, after the call you must
  17893.      immediately clear the stack of parameters with the instruction %@AS@%add sp,%@AE@%
  17894.      %@AI@%size%@AE@%, where %@AI@%size%@AE@% is the total size in bytes of all parameters that were
  17895.      pushed.%@NL@%
  17896. %@NL@%
  17897. %@NL@%
  17898. %@2@%%@CR:SCA.5       @%%@AB@%A.5  Using Full Segment Definitions%@AE@%%@EH@%%@NL@%
  17899. %@NL@%
  17900. %@4@%%@CR:IXA.55      @%%@CR:IXA.56      @%%@CR:IXA.57      @%  If you use the simplified segment directives by themselves, you do not%@EH@%
  17901.   need to know the names assigned for each segment. However, if you choose
  17902.   to use full segment definitions, you should use the %@AB@%SEGMENT%@AE@%, %@AB@%GROUP%@AE@%,
  17903.   %@AB@%ASSUME%@AE@%, and %@AB@%ENDS%@AE@% directives equivalent to the simplified segment
  17904.   directives.%@NL@%
  17905. %@NL@%
  17906. %@4@%  The following example shows the C-assembly program from Section A.3%@BO:       f3f49@%,%@EH@%
  17907.   without the simplified segment directives:%@NL@%
  17908. %@NL@%
  17909.   %@AS@%_TEXT       SEGMENT     WORD PUBLIC 'CODE'%@AE@%%@NL@%
  17910.   %@AS@%            ASSUME      cs:_TEXT%@AE@%%@NL@%
  17911.   %@AS@%            PUBLIC      _Power2%@AE@%%@NL@%
  17912.   %@AS@%_Power2     PROC%@AE@%%@NL@%
  17913.   %@AS@%            push        bp             ; Entry sequence - save BP%@AE@%%@NL@%
  17914.   %@AS@%            mov         bp,sp          ; Set stack frame%@AE@%%@NL@%
  17915. %@NL@%
  17916.   %@AS@%            mov         ax,[bp+4]      ; Load Arg1 into AX%@AE@%%@NL@%
  17917.   %@AS@%            mov         cx,[bp+6]      ; Load Arg2 into CX%@AE@%%@NL@%
  17918.   %@AS@%            shl         ax,cl          ; AX = AX * (2 to power of CX)%@AE@%%@NL@%
  17919.   %@AS@%                                       ; Leave return value in AX%@AE@%%@NL@%
  17920. %@NL@%
  17921.   %@AS@%            pop         bp             ; Exit sequence - restore BP%@AE@%%@NL@%
  17922.   %@AS@%            ret                        ; Return%@AE@%%@NL@%
  17923.   %@AS@%_Power2     ENDP%@AE@%%@NL@%
  17924.   %@AS@%_TEXT       ENDS%@AE@%%@NL@%
  17925.   %@AS@%            END%@AE@%%@NL@%
  17926. %@NL@%
  17927. %@NL@%
  17928. %@NL@%
  17929. ────────────────────────────────────────────────────────────────────────────%@NL@%
  17930. %@1@%%@CR:CHB         @%%@AB@%Appendix B:  Using Assembler Options with QCL%@AE@%%@EH@%%@NL@%
  17931. %@NL@%
  17932. %@NL@%
  17933. %@4@%%@CR:IXB.1       @%%@CR:IXB.2       @%  You can use the QCL driver for both compiling and assembling. The driver%@EH@%
  17934.   compiles .C files and assembles .ASM files. Unless the /c option is given,
  17935.   the QCL driver then links together all resulting .OBJ files, as well as
  17936.   any .OBJ files specified on the command line. The default file extension
  17937.   is .OBJ.%@NL@%
  17938. %@NL@%
  17939. %@4@%  If you acquired QuickAssembler as an upgrade, make sure you use the%@EH@%
  17940.   version of QCL that came with the QuickAssembler package. This driver
  17941.   program is an updated and expanded version, and it supports assembly
  17942.   options in addition to all the compile options listed in the QuickC %@AI@%Tool%@AE@%
  17943.   %@AI@%Kit%@AE@%.%@NL@%
  17944. %@NL@%
  17945. %@4@%  The following options may affect work with .ASM files, but are not%@EH@%
  17946.   described here because they work precisely the same way as described in
  17947.   the QuickC %@AI@%Tool%@AE@% %@AI@%Kit%@AE@%:%@NL@%
  17948. %@NL@%
  17949.   %@AB@%Option%@AE@%              %@AB@%Action%@AE@%%@NL@%
  17950.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17951.   /help               Print help listing for QCL%@NL@%
  17952. %@NL@%
  17953.   /link %@AI@%flags%@AE@%         Specify linker flags%@NL@%
  17954. %@NL@%
  17955.   /Fe%@AI@%file%@AE@%             Specify output file%@NL@%
  17956. %@NL@%
  17957.   /Fo%@AI@%file%@AE@%             Name object file%@NL@%
  17958. %@NL@%
  17959.   /Z{d|i}             Generate debugging information.%@NL@%
  17960. %@NL@%
  17961. %@NL@%
  17962. %@4@%  The /c, /D, and /W options are documented in the QuickC %@AI@%Tool%@AE@% %@AI@%Kit%@AE@%, but are%@EH@%
  17963.   also documented here because their meaning and usage change somewhat for
  17964.   assembly-language files.%@NL@%
  17965. %@NL@%
  17966. %@4@%%@CR:IXB.3       @%%@CR:IXB.4       @%%@CR:IXB.5       @%  In addition to the linker options documented in the QuickC %@AI@%Tool%@AE@% %@AI@%Kit%@AE@%, QCL%@EH@%
  17967.   supports one other option, /TINY. This option causes the linker to output
  17968.   a .COM file, if possible. The linker can only create a .COM file if the
  17969.   program is entirely written in assembly language, and all the modules
  17970.   observe the rules for the .COM format. (The easiest way to do this is to
  17971.   use tiny memory model as described in Chapter 5%@BO:       3ffad@%.) The following example
  17972.   generates a .COM file:%@NL@%
  17973. %@NL@%
  17974.   %@AS@%QCL /AT TINYPROG.ASM /link /TINY%@AE@%%@NL@%
  17975. %@NL@%
  17976. %@4@%  The /AT option causes the assembler to check the assembly code for%@EH@%
  17977.   adherence to the .COM format. The /TINY linker option causes the linker to
  17978.   generate a .COM file.%@NL@%
  17979. %@NL@%
  17980. %@4@%%@CR:IXB.6       @%  The QuickAssembler version of QCL supports the following options in%@EH@%
  17981.   addition to the ones supported for use with C-language modules:%@NL@%
  17982. %@NL@%
  17983.   %@AB@%Option%@AE@%              %@AB@%Action%@AE@%%@NL@%
  17984.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  17985. %@CR:IXB.7       @%  /a                  Writes segments in alphabetical order%@NL@%
  17986. %@NL@%
  17987.   /AT                 Requires program to use tiny memory model; gives error
  17988.                       messages for code that violates requirements of .COM
  17989.                       format%@NL@%
  17990. %@NL@%
  17991.   /C{l|u|x}           Determines case sensitivity (l=preserve case,
  17992.                       u=convert to upper, x=preserve case of external and
  17993.                       public symbols)%@NL@%
  17994. %@NL@%
  17995.   /D                  Defines symbols%@NL@%
  17996. %@NL@%
  17997.   /Ez                 Displays error lines on screen%@NL@%
  17998. %@NL@%
  17999.   /Fl%@AI@%file%@AE@%             Generates an assembly-listing file with given file
  18000.                       name%@NL@%
  18001. %@NL@%
  18002.   /FPi                Creates code for emulated floating-point instructions%@NL@%
  18003. %@NL@%
  18004.   /l                  Generates an assembly-listing file%@NL@%
  18005. %@NL@%
  18006.   /P1                 Enables one-pass assembly%@NL@%
  18007. %@NL@%
  18008. %@CR:IXB.8       @%  /s                  Writes segments in source-code order (reverses effect
  18009.                       of /a)%@NL@%
  18010. %@NL@%
  18011.   /Sa                 Lists all lines of macro expansions (assumes /Fl%@AI@%file%@AE@%
  18012.                       or /l is given)%@NL@%
  18013. %@NL@%
  18014.   /Sd                 Adds pass 1 information to listing (assumes /Fl%@AI@%file%@AE@% or
  18015.                       /l is given)%@NL@%
  18016. %@NL@%
  18017.   /Se                 Creates editor-oriented listing file; the resulting
  18018.                       listing has no page breaks or page headings (assumes
  18019.                       /Fl%@AI@%file%@AE@% or /l is given)%@NL@%
  18020. %@NL@%
  18021.   /Sn                 Suppresses symbol-table in listing (assumes /Fl%@AI@%file%@AE@% or
  18022.                       /l is given)%@NL@%
  18023. %@NL@%
  18024.   /Sq                 Generates an editor-based listing file with a
  18025.                       source-line index at the end (assumes Fl%@AI@%file%@AE@% or /l is
  18026.                       given)%@NL@%
  18027. %@NL@%
  18028.   /Sx                 Suppresses listing of false conditionals (assumes
  18029.                       Fl%@AI@%file%@AE@% or /l is given)%@NL@%
  18030. %@NL@%
  18031.   /t                  Suppresses messages if assembly is successful%@NL@%
  18032. %@NL@%
  18033.   /v                  Displays extra statistics during assembly%@NL@%
  18034. %@NL@%
  18035. %@CR:IXB.9       @%%@CR:IXB.10      @%  /w                  Equivalent to /W0%@NL@%
  18036. %@NL@%
  18037.   /W{0|1|2}           Sets warning-message level%@NL@%
  18038. %@NL@%
  18039. %@NL@%
  18040. %@CR:IXB.11      @%%@CR:IXB.12      @%%@CR:IXB.13      @%%@CR:IXB.14      @%%@CR:IXB.15      @%%@NL@%
  18041. %@2@%%@CR:SCB.1       @%%@AB@%B.1  Specifying the Segment-Order Method%@AE@%%@EH@%%@NL@%
  18042. %@NL@%
  18043. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18044. %@NL@%
  18045. %@4@%  /s           Default%@EH@%%@NL@%
  18046.   /a%@NL@%
  18047. %@NL@%
  18048. %@4@%  The /a option directs QuickAssembler to place the assembled segments in%@EH@%
  18049.   alphabetical order before copying them to the object file. The /s option
  18050.   directs the assembler to write segments in the order in which they appear
  18051.   in the source code.%@NL@%
  18052. %@NL@%
  18053. %@4@%%@CR:IXB.16      @%  Source-code order is the default. If no option is given, QuickAssembler%@EH@%
  18054.   copies the segments in the order encountered in the source file. The /s
  18055.   option is provided for compatibility with the XENIX(R) operating system
  18056.   and for overriding a default option in the QuickAssembler environment
  18057.   variable.%@NL@%
  18058. %@NL@%
  18059.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  18060.   %@AB@%NOTE%@AE@%  Some previous versions of the IBM Macro Assembler ordered segments
  18061.   alphabetically by default. Listings in some books and magazines have been
  18062.   written with these early versions in mind. If you have trouble assembling
  18063.   and linking a listing taken from a book or magazine, try using the /a
  18064.   option.%@NL@%
  18065.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  18066. %@NL@%
  18067. %@4@%  The order in which segments are written to the object file is only one%@EH@%
  18068.   factor in determining the order in which they will appear in the
  18069.   executable file. The significance of segment order and ways to control it
  18070.   are discussed in Sections 5.2.1%@BO:       4bb75@%, "Setting the Segment-Order Method" and
  18071.   5.2.2.2%@BO:       4bb75@%, "Defining Segment Combinations with Combine Type."%@NL@%
  18072. %@NL@%
  18073. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18074. %@NL@%
  18075.   %@AS@%QCL /a file.asm%@AE@%%@NL@%
  18076. %@NL@%
  18077. %@4@%  The example above creates an object file, FILE.OBJ, whose segments are%@EH@%
  18078.   arranged in alphabetical order. If the /s option were used instead, or if
  18079.   no option were specified, the segments would be arranged in sequential
  18080.   order.%@NL@%
  18081. %@NL@%
  18082. %@CR:IXB.17      @%%@CR:IXB.18      @%%@CR:IXB.19      @%%@NL@%
  18083. %@2@%%@CR:SCB.2       @%%@AB@%B.2  Checking Code for Tiny Model%@AE@%%@EH@%%@NL@%
  18084. %@NL@%
  18085. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18086. %@NL@%
  18087. %@4@%  /AT%@EH@%%@NL@%
  18088. %@NL@%
  18089. %@4@%  The /AT option causes the assembler to enforce the requirements of .COM%@EH@%
  18090.   format. If the %@AB@%.MODEL%@AE@% directive is used, /AT generates an error unless the
  18091.   directive specifies tiny memory model. If the %@AB@%.MODEL%@AE@% directive is not
  18092.   used, the /AT option generates an error if any program-defined segments
  18093.   are referenced (since these references violate conditions of .COM format).%@NL@%
  18094. %@NL@%
  18095. %@4@%  The use of /AT alone does not generate a .COM file. You must also use the%@EH@%
  18096.   /TINY linker option, as in the following example:%@NL@%
  18097. %@NL@%
  18098.   %@AS@%QCL /AT TINYPROG.ASM /link /TINY%@AE@%%@NL@%
  18099. %@NL@%
  18100. %@CR:IXB.20      @%%@CR:IXB.21      @%%@CR:IXB.22      @%%@CR:IXB.23      @%%@CR:IXB.24      @%%@CR:IXB.25      @%%@CR:IXB.26      @%%@NL@%
  18101. %@2@%%@CR:SCB.3       @%%@AB@%B.3  Selecting Case Sensitivity%@AE@%%@EH@%%@NL@%
  18102. %@NL@%
  18103. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18104. %@NL@%
  18105. %@4@%  /Cu          Default%@EH@%%@NL@%
  18106.   /Cl%@NL@%
  18107.   /Cx%@NL@%
  18108. %@NL@%
  18109. %@4@%  The /Cl option directs the assembler to make all names case sensitive. The%@EH@%
  18110.   /Cx option directs the assembler to make public and external names case
  18111.   sensitive. The /Cu option directs the assembler to convert all names to
  18112.   uppercase.%@NL@%
  18113. %@NL@%
  18114. %@4@%  By default, QuickAssembler converts all names to uppercase (/Cu).%@EH@%%@NL@%
  18115. %@NL@%
  18116. %@4@%%@CR:IXB.27      @%%@CR:IXB.28      @%%@CR:IXB.29      @%%@CR:IXB.30      @%  If case sensitivity is turned on, all names that have the same spelling%@EH@%
  18117.   but use letters of different cases are considered distinct. For example,
  18118.   with the /Cl option, %@AS@%DATA %@AE@%and %@AS@%data %@AE@%are different. They would also be
  18119.   different with the /Cx option if they were declared external or public.
  18120.   Public and external names include any label, variable, or symbol names
  18121.   defined by using the %@AB@%EXTRN%@AE@%, %@AB@%PUBLIC%@AE@%, or %@AB@%COMM%@AE@% directives (see Chapter 8%@BO:       70f6e@%,
  18122.   "Creating Programs from Multiple Modules").%@NL@%
  18123. %@NL@%
  18124. %@4@%  If you use the /Zi or /Zd option (these cause QCL to include debugging%@EH@%
  18125.   information), the /Cx, /Cl, and /Cu options affect the case of the
  18126.   symbolic data that will be available to a symbolic debugger.%@NL@%
  18127. %@NL@%
  18128. %@4@%%@CR:IXB.31      @%%@CR:IXB.32      @%%@CR:IXB.33      @%  The /Cl and /Cx options are typically used when object modules created%@EH@%
  18129.   with QuickAssembler are to be linked with object modules created by a
  18130.   case-sensitive compiler such as the Microsoft C compiler. If case
  18131.   sensitivity is important, you should also use the linker /NOI option.%@NL@%
  18132. %@NL@%
  18133. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18134. %@NL@%
  18135.   %@AS@%QCL /Cx module.asm%@AE@%%@NL@%
  18136. %@NL@%
  18137. %@4@%  This example shows how to use the /Cx option with QuickAssembler to%@EH@%
  18138.   assemble a file with case-sensitive public symbols.%@NL@%
  18139. %@NL@%
  18140. %@CR:IXB.34      @%%@CR:IXB.35      @%%@CR:IXB.36      @%%@CR:IXB.37      @%%@NL@%
  18141. %@2@%%@CR:SCB.4       @%%@AB@%B.4  Defining Assembler Symbols%@AE@%%@EH@%%@NL@%
  18142. %@NL@%
  18143. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18144. %@NL@%
  18145. %@4@%  /D%@AI@%symbol%@AE@%[[=%@AI@%value%@AE@%]]%@EH@%%@NL@%
  18146. %@NL@%
  18147. %@4@%%@CR:IXB.38      @%%@CR:IXB.39      @%%@CR:IXB.40      @%  The /D option, when given with a %@AI@%symbol%@AE@% argument, directs QuickAssembler%@EH@%
  18148.   to define a symbol that can be used during the assembly as if it were
  18149.   defined as a text equate in the source file. Multiple symbols can be
  18150.   defined in a single command line.%@NL@%
  18151. %@NL@%
  18152. %@4@%  The %@AI@%value%@AE@% can be any text string that does not include a space, comma, or%@EH@%
  18153.   semicolon. If %@AI@%value%@AE@% is not given, the symbol is assigned a null string.%@NL@%
  18154. %@NL@%
  18155. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18156. %@NL@%
  18157.   %@AS@%QCL /Dwide /Dmode=3 file,,;%@AE@%%@NL@%
  18158. %@NL@%
  18159. %@4@%  This example defines the symbol %@AS@%wide %@AE@%and gives it a null value. The symbol%@EH@%
  18160.   could then be used in the following conditional-assembly block:%@NL@%
  18161. %@NL@%
  18162.   %@AS@%            IFDEF wide%@AE@%%@NL@%
  18163.   %@AS@%            PAGE 50,132%@AE@%%@NL@%
  18164.   %@AS@%            ENDIF%@AE@%%@NL@%
  18165. %@NL@%
  18166. %@4@%  When the symbol is defined in the command line, the listing file is%@EH@%
  18167.   formatted for a 132-column printer. When the symbol is not defined in the
  18168.   command line, the listing file is given the default width of 80 (see the
  18169.   description of the %@AB@%PAGE%@AE@% directive in Section 12.2%@BO:       a2ad0@%, "Controlling Page
  18170.   Format in Listings").%@NL@%
  18171. %@NL@%
  18172. %@4@%  The example also defines the symbol %@AS@%mode %@AE@%and gives it the value 3. The%@EH@%
  18173.   symbol could then be used in a variety of contexts, as shown below:%@NL@%
  18174. %@NL@%
  18175.   %@AS@%            IF      mode LT 15         ; Use in expression%@AE@%%@NL@%
  18176.   %@AS@%scrmode     DB      mode               ; Initialize to mode%@AE@%%@NL@%
  18177.   %@AS@%            ELSE%@AE@%%@NL@%
  18178.   %@AS@%scrmode     DB      15                 ; Initialize to 15%@AE@%%@NL@%
  18179.   %@AS@%            ENDIF%@AE@%%@NL@%
  18180. %@NL@%
  18181. %@CR:IXB.41      @%%@CR:IXB.42      @%%@CR:IXB.43      @%%@NL@%
  18182. %@2@%%@CR:SCB.5       @%%@AB@%B.5  Displaying Error Lines on the Screen%@AE@%%@EH@%%@NL@%
  18183. %@NL@%
  18184. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18185. %@NL@%
  18186. %@4@%  /Ez%@EH@%%@NL@%
  18187. %@NL@%
  18188. %@4@%  The /Ez option directs QuickAssembler to display lines containing errors%@EH@%
  18189.   on the screen. Normally, when the assembler encounters an error, it
  18190.   displays only an error message describing the problem. When you use the
  18191.   /Ez option in the command line, the assembler displays the source line
  18192.   that produced the error in addition to the error message. QuickAssembler
  18193.   assembles faster without the /Ez option, but you may find the convenience
  18194.   of seeing the incorrect source lines worth the slight cost in processing
  18195.   speed.%@NL@%
  18196. %@NL@%
  18197. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18198. %@NL@%
  18199.   %@AS@%QCL /Ez file.asm%@AE@%%@NL@%
  18200. %@NL@%
  18201. %@CR:IXB.44      @%%@CR:IXB.45      @%%@CR:IXB.46      @%%@CR:IXB.47      @%%@CR:IXB.48      @%%@CR:IXB.49      @%%@NL@%
  18202. %@2@%%@CR:SCB.6       @%%@AB@%B.6  Creating Code for a Floating-Point Emulator%@AE@%%@EH@%%@NL@%
  18203. %@NL@%
  18204. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18205. %@NL@%
  18206. %@4@%  /FPi 87 /FPi%@EH@%%@NL@%
  18207. %@NL@%
  18208. %@4@%  The /FPi and /FPi87 options control how instructions for a math%@EH@%
  18209.   coprocessor (such as the 8087, 80287, or 80387) are assembled. The /FPi
  18210.   option tells the assembler to generate code for a coprocessor emulator
  18211.   library. The /FPi87 option tells the assembler to generate code for a
  18212.   coprocessor. These options are different than most other QuickAssembler
  18213.   options in that the default for C files is /FPi, but the default for
  18214.   assembler files is /FPi87. They are also different in that the options
  18215.   must be specified separately for each file.%@NL@%
  18216. %@NL@%
  18217. %@4@%  An emulator library uses the instructions of a coprocessor if one is%@EH@%
  18218.   present; otherwise, the library executes interrupts that emulate
  18219.   coprocessor instructions. Emulator libraries are available for QuickC and
  18220.   other high-level language compilers, including Microsoft Pascal, BASIC,
  18221.   and FORTRAN compilers.%@NL@%
  18222. %@NL@%
  18223. %@4@%  With QuickAssembler, you should specify /FPi only for assembly modules%@EH@%
  18224.   that will be linked with a main C module, since the emulator code requires
  18225.   the start-up code generated by the C compiler. A stand-alone assembler
  18226.   program generated with /FPi will execute emulator interrupts, but the
  18227.   program will not work because the interrupts will not be initialized. If
  18228.   you are programming in the QC environment and you want the emulator
  18229.   library to be used with an assembler module, you must specify /FPi in the
  18230.   Global Custom Flags field of the Assembler Flags dialog box (reached from
  18231.   the Options menu). This will affect all assembly modules in the program
  18232.   list.%@NL@%
  18233. %@NL@%
  18234. %@4@%  To the applications programmer, writing code for the emulator is like%@EH@%
  18235.   writing code for a coprocessor. The instruction sets are the same (except
  18236.   as noted in Chapter 17%@BO:       d965a@%, "Calculating with a Math Coprocessor"). However,
  18237.   at run time the coprocessor instructions are used only if there is a
  18238.   coprocessor available on the machine. If there is no coprocessor, the
  18239.   slower code from the emulator library is used instead.%@NL@%
  18240. %@NL@%
  18241. %@4@%  The /FPi87 option specifies that coprocessor instructions should be%@EH@%
  18242.   generated directly. It does not need to be given directly for assembly
  18243.   modules, since it is the default, but it must be specified for C modules.
  18244.   Programs that use this option can be run only on a system that has a
  18245.   coprocessor. If the program contains a main C module, it will fail with a
  18246.   warning if the system has no coprocessor. If the program is a stand-alone
  18247.   assembler program, you should write the code to check for a coprocessor
  18248.   and terminate with an error message if no coprocessor exists.%@NL@%
  18249. %@NL@%
  18250. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18251. %@NL@%
  18252.   %@AS@%QCL calc.c /FPi /Cx math.asm%@AE@%%@NL@%
  18253. %@NL@%
  18254. %@4@%  The example above assembles MATH.ASM with the /FPi option and compiles the%@EH@%
  18255.   C source file CALC.C. The resulting object files are then linked together
  18256.   to produce the file CALC.EXE. The C compiler generates emulator code for
  18257.   floating-point instructions. The FORTRAN, BASIC, and Pascal compilers
  18258.   generate similar code.%@NL@%
  18259. %@NL@%
  18260. %@CR:IXB.50      @%%@CR:IXB.51      @%%@CR:IXB.52      @%%@CR:IXB.53      @%%@CR:IXB.54      @%%@CR:IXB.55      @%%@NL@%
  18261. %@2@%%@CR:SCB.7       @%%@AB@%B.7  Creating Listing Files%@AE@%%@EH@%%@NL@%
  18262. %@NL@%
  18263. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18264. %@NL@%
  18265. %@4@%  /l%@EH@%%@NL@%
  18266.   /Fl%@AI@%file%@AE@%%@NL@%
  18267. %@NL@%
  18268. %@4@%  The /l option directs QuickAssembler to create a listing file. Files%@EH@%
  18269.   specified with this option always have the base name of the source file
  18270.   plus a .LST extension. You cannot specify any other file name. The /Fl
  18271.   option has the same purpose as /l, but lets you specify any file name as
  18272.   the listing file. The default file name is the base file name plus a .LST
  18273.   extension.%@NL@%
  18274. %@NL@%
  18275. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18276. %@NL@%
  18277.   %@AS@%QCL /l prog.asm%@AE@%%@NL@%
  18278. %@NL@%
  18279. %@4@%  This example causes the assembler to generate the file PROG.LST during%@EH@%
  18280.   assembly.%@NL@%
  18281. %@NL@%
  18282. %@CR:IXB.56      @%%@CR:IXB.57      @%%@CR:IXB.58      @%%@NL@%
  18283. %@2@%%@CR:SCB.8       @%%@AB@%B.8  Enabling One-Pass Assembly%@AE@%%@EH@%%@NL@%
  18284. %@NL@%
  18285. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18286. %@NL@%
  18287. %@4@%  /P1%@EH@%%@NL@%
  18288. %@NL@%
  18289. %@4@%  The /P1 option causes the assembler to attempt translation of source code%@EH@%
  18290.   in one pass. If successful, the translation is significantly faster than
  18291.   the default two-pass assembly. Assembly modules cannot be successfully
  18292.   assembled with this option if they contain conditional-assembly directives
  18293.   that make references to pass 1 or pass 2.%@NL@%
  18294. %@NL@%
  18295.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  18296.   %@AB@%NOTE%@AE@%  One-pass assembly is not compatible with the generation of listing
  18297.   files or the /a option for specifying alphabetical segment order.%@NL@%
  18298.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  18299. %@NL@%
  18300. %@4@%  If the assembler generates a message reporting that one-pass assembly is%@EH@%
  18301.   not possible, simply assemble the file again without using this option.%@NL@%
  18302. %@NL@%
  18303. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18304. %@NL@%
  18305.   %@AS@%QCL /P1 file.asm%@AE@%%@NL@%
  18306. %@NL@%
  18307. %@CR:IXB.59      @%%@CR:IXB.60      @%%@CR:IXB.61      @%%@NL@%
  18308. %@2@%%@CR:SCB.9       @%%@AB@%B.9  Listing All Lines of Macro Expansions%@AE@%%@EH@%%@NL@%
  18309. %@NL@%
  18310. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18311. %@NL@%
  18312. %@4@%  /Sa%@EH@%%@NL@%
  18313. %@NL@%
  18314. %@4@%  The /Sa option causes the listing file to contain all statements generated%@EH@%
  18315.   by the assembler. It overrides directives that limit listings such as
  18316.   %@AB@%.XLIST%@AE@%,%@AB@% .XALL%@AE@%, and %@AB@%.SFCOND%@AE@%. It forces display of all statements generated
  18317.   automatically by simplified segment directives and the extended %@AB@%PROC%@AE@%
  18318.   syntax. The /Sa option has no effect unless /l or /Fl is also specified.%@NL@%
  18319. %@NL@%
  18320. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18321. %@NL@%
  18322.   %@AS@%QCL /l /Sa file.asm%@AE@%%@NL@%
  18323. %@NL@%
  18324. %@CR:IXB.62      @%%@CR:IXB.63      @%%@CR:IXB.64      @%%@CR:IXB.65      @%%@NL@%
  18325. %@2@%%@CR:SCB.10      @%%@AB@%B.10  Creating a Pass 1 Listing%@AE@%%@EH@%%@NL@%
  18326. %@NL@%
  18327. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18328. %@NL@%
  18329. %@4@%  /Sd%@EH@%%@NL@%
  18330. %@NL@%
  18331. %@4@%%@CR:IXB.66      @%  The /Sd option causes the listing file to contain the results of both%@EH@%
  18332.   assembler passes. A pass 1 listing is typically used to locate phase
  18333.   errors. Phase errors occur when the assembler makes assumptions about the
  18334.   program in pass 1 that are not valid in pass 2. The /Sd option has no
  18335.   effect unless /l or /Fl is also specified.%@NL@%
  18336. %@NL@%
  18337. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18338. %@NL@%
  18339.   %@AS@%QCL /l /Sd file.asm%@AE@%%@NL@%
  18340. %@NL@%
  18341. %@CR:IXB.67      @%%@CR:IXB.68      @%%@CR:IXB.69      @%%@NL@%
  18342. %@2@%%@CR:SCB.11      @%%@AB@%B.11  Specifying an Editor-Oriented Listing%@AE@%%@EH@%%@NL@%
  18343. %@NL@%
  18344. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18345. %@NL@%
  18346. %@4@%  /Se%@EH@%%@NL@%
  18347. %@NL@%
  18348. %@4@%  The /Se option causes the assembler to generate the listing file in a%@EH@%
  18349.   format suited to text editors. This format does not contain page breaks or
  18350.   page headings. The default behavior, which is designed for files output to
  18351.   a printer, assumes a page break and heading at periodic intervals. The /Se
  18352.   option has no effect unless /l or /Fl is also specified.%@NL@%
  18353. %@NL@%
  18354. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18355. %@NL@%
  18356.   %@AS@%QCL /l /Se file.asm%@AE@%%@NL@%
  18357. %@NL@%
  18358. %@CR:IXB.70      @%%@CR:IXB.71      @%%@CR:IXB.72      @%%@NL@%
  18359. %@2@%%@CR:SCB.12      @%%@AB@%B.12  Suppressing Tables in the Listing File%@AE@%%@EH@%%@NL@%
  18360. %@NL@%
  18361. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18362. %@NL@%
  18363. %@4@%  /Sn%@EH@%%@NL@%
  18364. %@NL@%
  18365. %@4@%  The /Sn option tells the assembler to omit all tables from the end of the%@EH@%
  18366.   listing file. If this option is not chosen, QuickAssembler includes tables
  18367.   of macros, structures, records, segments and groups, and symbols. The code
  18368.   portion of the listing file is not changed by the /Sn option. The /Sn
  18369.   option has no effect unless /l or /Fl is also specified.%@NL@%
  18370. %@NL@%
  18371. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18372. %@NL@%
  18373.   %@AS@%QCL /l /Sn file.asm%@AE@%%@NL@%
  18374. %@NL@%
  18375. %@CR:IXB.73      @%%@CR:IXB.74      @%%@CR:IXB.75      @%%@NL@%
  18376. %@2@%%@CR:SCB.13      @%%@AB@%B.13  Adding a Line-Number Index to the Listing%@AE@%%@EH@%%@NL@%
  18377. %@NL@%
  18378. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18379. %@NL@%
  18380. %@4@%  /Sq%@EH@%%@NL@%
  18381. %@NL@%
  18382. %@4@%  The /Sq option generates an editor-based listing file just as the /Se%@EH@%
  18383.   option does, but it also adds a source-line index to the end of the
  18384.   listing file. This index contains pairs of corresponding line numbers for
  18385.   the listing file and appropriate source files. The QuickC/QuickAssembler
  18386.   environment uses this information to let you move from a source file to
  18387.   the corresponding position in a listing file.%@NL@%
  18388. %@NL@%
  18389. %@4@%  When you create a listing file from within the QuickC/QuickAssembler%@EH@%
  18390.   environment, QC.EXE automatically passes this option to the assembler. The
  18391.   /Sq option has no effect unless /l or /Fl is also specified.%@NL@%
  18392. %@NL@%
  18393. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18394. %@NL@%
  18395.   %@AS@%QCL /l /Sq file.asm%@AE@%%@NL@%
  18396. %@NL@%
  18397. %@CR:IXB.76      @%%@CR:IXB.77      @%%@CR:IXB.78      @%%@NL@%
  18398. %@2@%%@CR:SCB.14      @%%@AB@%B.14  Listing False Conditionals%@AE@%%@EH@%%@NL@%
  18399. %@NL@%
  18400. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18401. %@NL@%
  18402. %@4@%  /Sx%@EH@%%@NL@%
  18403. %@NL@%
  18404. %@4@%%@CR:IXB.79      @%  The /Sx option directs QuickAssembler to copy to the assembly listing all%@EH@%
  18405.   statements forming the body of conditional-assembly blocks whose condition
  18406.   is false. If you do not give the /Sx option in the command line,
  18407.   QuickAssembler suppresses all such statements. The /Sx option lets you
  18408.   display conditionals that do not generate code. Conditional-assembly
  18409.   directives are explained in Chapter 12%@BO:       a2236@%, "Controlling Assembly Output."%@NL@%
  18410. %@NL@%
  18411. %@4@%%@CR:IXB.80      @%%@CR:IXB.81      @%%@CR:IXB.82      @%%@CR:IXB.83      @%%@CR:IXB.84      @%%@CR:IXB.85      @%  The %@AB@%.LFCOND%@AE@%, %@AB@%.SFCOND%@AE@%, and %@AB@%.TFCOND%@AE@% directives can override the effect of%@EH@%
  18412.   the /Sx option, as described in Section 12.3.2%@BO:       a518f@%, "Controlling Listing of
  18413.   Conditional Blocks." The /Sx option does not affect the assembly listing
  18414.   unless you direct the assembler to create an assembly-listing file.%@NL@%
  18415. %@NL@%
  18416. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18417. %@NL@%
  18418.   %@AS@%QCL /Sx file,,;%@AE@%%@NL@%
  18419. %@NL@%
  18420. %@4@%  Listing of false conditionals is turned on when FILE.ASM is assembled.%@EH@%
  18421.   Directives in the source file can override the /Sx option to change the
  18422.   status of false-conditional listing.%@NL@%
  18423. %@NL@%
  18424. %@CR:IXB.86      @%%@CR:IXB.87      @%%@CR:IXB.88      @%%@CR:IXB.89      @%%@CR:IXB.90      @%%@CR:IXB.91      @%%@NL@%
  18425. %@2@%%@CR:SCB.15      @%%@AB@%B.15  Controlling Display of Assembly Statistics%@AE@%%@EH@%%@NL@%
  18426. %@NL@%
  18427. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18428. %@NL@%
  18429. %@4@%  /v%@EH@%%@NL@%
  18430.   /t%@NL@%
  18431. %@NL@%
  18432. %@4@%  The /v and /t options specify the level of information displayed to the%@EH@%
  18433.   screen at the end of assembly (/v is a mnemonic for verbose; /t is a
  18434.   mnemonic for terse).%@NL@%
  18435. %@NL@%
  18436. %@4@%  If neither option is given, QuickAssembler outputs a line telling the%@EH@%
  18437.   amount of symbol space free and the number of warnings and errors.%@NL@%
  18438. %@NL@%
  18439. %@4@%  If the /v option is given, QuickAssembler also reports the number of lines%@EH@%
  18440.   and symbols processed.%@NL@%
  18441. %@NL@%
  18442. %@4@%  If the /t option is given, QuickAssembler does not output anything to the%@EH@%
  18443.   screen unless errors are encountered. This option may be useful in batch
  18444.   or make files if you do not want the output cluttered with unnecessary
  18445.   messages.%@NL@%
  18446. %@NL@%
  18447. %@4@%  If errors are encountered, they will be displayed whether these options%@EH@%
  18448.   are given or not.%@NL@%
  18449. %@NL@%
  18450. %@CR:IXB.92      @%%@CR:IXB.93      @%%@CR:IXB.94      @%%@CR:IXB.95      @%%@NL@%
  18451. %@2@%%@CR:SCB.16      @%%@AB@%B.16  Setting the Warning Level%@AE@%%@EH@%%@NL@%
  18452. %@NL@%
  18453. %@4@%  %@AB@%Syntax%@AE@%%@EH@%%@NL@%
  18454. %@NL@%
  18455. %@4@%  /W{0 | 1 | 2}%@EH@%%@NL@%
  18456.   /w%@NL@%
  18457. %@NL@%
  18458. %@4@%  The /W option sets the assembler warning level. QuickAssembler gives%@EH@%
  18459.   warning messages for assembly statements that are ambiguous or
  18460.   questionable but not necessarily illegal. Some programmers purposely use
  18461.   practices that generate warnings. By setting the appropriate warning
  18462.   level, they can turn off warnings if they are aware of the problem and do
  18463.   not wish to take action to remedy it. The /w option is equivalent to /W0.%@NL@%
  18464. %@NL@%
  18465. %@4@%%@CR:IXB.96      @%%@CR:IXB.97      @%%@CR:IXB.98      @%  QuickAssembler has three levels of errors, as shown in Table B.1.%@EH@%%@NL@%
  18466. %@NL@%
  18467.   %@AB@%Table B.1 Warning Levels%@AE@%%@NL@%
  18468. %@NL@%
  18469.   %@AB@%Level%@AE@%           %@AB@%Type%@AE@%            %@AB@%Description%@AE@%%@NL@%
  18470.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  18471.   0               Severe errors   Illegal statements%@NL@%
  18472. %@NL@%
  18473.   1               Serious         Ambiguous statements or questionable
  18474.                   warnings        programming practices%@NL@%
  18475. %@NL@%
  18476.   2               Advisory        Statements that may produce inefficient
  18477.                   warnings        code%@NL@%
  18478. %@NL@%
  18479.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  18480. %@NL@%
  18481. %@NL@%
  18482. %@4@%  The default warning level is 1. A higher warning level includes all of the%@EH@%
  18483.   messages reported by a lower level. Level 2 includes severe errors,
  18484.   serious warnings, and advisory warnings. If severe errors are encountered,
  18485.   no object file is produced.%@NL@%
  18486. %@NL@%
  18487. %@4@%  Warning level 0 reports error messages in the range 1000-2999. Warning%@EH@%
  18488.   level 1 reports warning and error messages in the ranges 1000-2999 and
  18489.   4000-4999. Warning level 2 reports all warning and error messages,
  18490.   including those numbered 5000 and above.%@NL@%
  18491. %@NL@%
  18492. %@NL@%
  18493. %@NL@%
  18494. ────────────────────────────────────────────────────────────────────────────%@NL@%
  18495. %@1@%%@CR:CHC         @%%@AB@%Appendix C:  Reading Assembly Listings%@AE@%%@EH@%%@NL@%
  18496. %@NL@%
  18497. %@NL@%
  18498. %@4@%%@CR:IXC.1       @%%@CR:IXC.2       @%  QuickAssembler creates an assembly listing of your source file whenever%@EH@%
  18499.   you give an assembly-listing option on the QCL command line or select a
  18500.   listing file option in the Assembler Flags dialog box. The assembly
  18501.   listing contains both the statements in the source file and the object
  18502.   code (if any) generated for each statement. The listing also shows the
  18503.   names and values of all labels, variables, and symbols in your source
  18504.   file.%@NL@%
  18505. %@NL@%
  18506. %@4@%%@CR:IXC.3       @%  The assembler creates tables for macros, structures, records, segments,%@EH@%
  18507.   groups, and other symbols. These tables are placed at the end of the
  18508.   assembly listing (unless you suppress them with the QCL /Sn option).
  18509.   QuickAssembler lists only the types of symbols encountered in the program.
  18510.   All symbol names will be shown in uppercase letters unless you choose
  18511.   Preserve Case or Preserve Extrn from the Assembler Flags dialog box or use
  18512.   a QCL option (/Cx or /Cl) that supports case sensitivity.%@NL@%
  18513. %@NL@%
  18514. %@NL@%
  18515. %@2@%%@CR:SCC.1       @%%@AB@%C.1  Reading Code in a Listing%@AE@%%@EH@%%@NL@%
  18516. %@NL@%
  18517. %@4@%  The assembler lists the code generated from the statements of a source%@EH@%
  18518.   file. Each line has the syntax shown below:%@NL@%
  18519. %@NL@%
  18520. %@4@%  %@AI@%offset%@AE@% [[%@AI@%code%@AE@%]] %@AI@%statement%@AE@%%@EH@%%@NL@%
  18521. %@NL@%
  18522. %@4@%  The %@AI@%offset%@AE@% is the offset from the beginning of the current segment to the%@EH@%
  18523.   code. If the statement generates code or data, %@AI@%code%@AE@% shows the numeric
  18524.   value in hexadecimal if the value is known at assembly time. If the value
  18525.   is calculated at run time, the assembler indicates what action is
  18526.   necessary to compute the value. The %@AI@%statement%@AE@% is the source statement
  18527.   shown exactly as it appears in the source file, or as expanded by a macro.%@NL@%
  18528. %@NL@%
  18529. %@4@%%@CR:IXC.4       @%  If any errors occur during assembly, each error message and error number%@EH@%
  18530.   will appear directly below the statement where the error occurred. An
  18531.   example of an error line and message is shown below:%@NL@%
  18532. %@NL@%
  18533.   %@AS@%0012  E8 001C R                            call    doit%@AE@%%@NL@%
  18534.   %@AS@%test.ASM(46): error A2071: Forward needs override or FAR%@AE@%%@NL@%
  18535. %@CR:IXC.5       @%%@CR:IXC.6       @%%@CR:IXC.7       @%%@CR:IXC.8       @%%@CR:IXC.9       @%%@CR:IXC.10      @%%@CR:IXC.11      @%%@CR:IXC.12      @%%@CR:IXC.13      @%%@CR:IXC.14      @%%@NL@%
  18536. %@4@%%@CR:IXC.15      @%%@CR:IXC.16      @%%@CR:IXC.17      @%%@CR:IXC.18      @%%@CR:IXC.19      @%%@CR:IXC.20      @%%@CR:IXC.21      @%  The assembler uses the symbols and abbreviations in Table C.1 to indicate%@EH@%
  18537.   addresses that need to be resolved by the linker or values that were
  18538.   generated in a special way.%@NL@%
  18539. %@NL@%
  18540.   %@AB@%Table C.1 Symbols and Abbreviations in Listings%@AE@%%@NL@%
  18541. %@NL@%
  18542.   %@AB@%Character%@AE@%          %@AB@%Meaning%@AE@%%@NL@%
  18543.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  18544.   R                  Relocatable address (linker must resolve)%@NL@%
  18545. %@NL@%
  18546.   E                  External address (linker must resolve)%@NL@%
  18547. %@NL@%
  18548.   ----               Segment/group address (linker must resolve)%@NL@%
  18549. %@NL@%
  18550.   =                  %@AB@%EQU%@AE@% or equal-sign (%@AB@%=%@AE@%) directive%@NL@%
  18551. %@NL@%
  18552.   %@AI@%nn%@AE@%:                Segment override in statement%@NL@%
  18553. %@NL@%
  18554.   %@AI@%nn%@AE@%/                %@AB@%REP%@AE@% or %@AB@%LOCK%@AE@% prefix instruction%@NL@%
  18555. %@NL@%
  18556.   %@AI@%nn%@AE@%[%@AI@%xx%@AE@%]             %@AB@%DUP%@AE@% expression: %@AI@%nn%@AE@% copies of the value %@AI@%xx%@AE@%%@NL@%
  18557. %@NL@%
  18558.   %@AI@%n%@AE@%                  Macro-expansion nesting level (+ if more than nine)%@NL@%
  18559. %@NL@%
  18560.   C                  Line from include file%@NL@%
  18561. %@NL@%
  18562.   ──────────────────────────────────────────────────────────────────────────%@NL@%
  18563. %@NL@%
  18564. %@NL@%
  18565. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18566. %@NL@%
  18567. %@4@%  The sample listing shown in this section is produced using the /Se option,%@EH@%
  18568.   which produces an editor-oriented listing. The QuickC/QuickAssembler
  18569.   environment always produces this kind of listing. The editor-oriented
  18570.   environment produces no page headings and is thus ideal for viewing within
  18571.   the environment or another editor. If you are using QCL to generate a
  18572.   listing file that you intend to print, you may want to generate a
  18573.   printer-oriented listing file by giving the /Sp option:%@NL@%
  18574. %@NL@%
  18575.   %@AS@%QCL /l /Sp listdemo.asm%@AE@%%@NL@%
  18576. %@NL@%
  18577. %@4@%  The code portion of the resulting listing is shown below. The tables%@EH@%
  18578.   normally seen at the end of the listing are explained later, in Sections
  18579.   C.2%@BO:       ff16e@%-C.7.%@NL@%
  18580. %@NL@%
  18581.   %@AS@%Microsoft(R) QuickC with QuickAssembler Version 2.01 Listing features demo%@AE@%%@NL@%
  18582. %@NL@%
  18583.   %@AS@%                                        PAGE    65,132%@AE@%%@NL@%
  18584.   %@AS@%                                        TITLE   Listing features  demo%@AE@%%@NL@%
  18585.   %@AS@%                             C          INCLUDE dos.mac%@AE@%%@NL@%
  18586.   %@AS@%                             C  StrAlloc    MACRO   name,text%@AE@%%@NL@%
  18587.   %@AS@%                             C  name        DB      &text%@AE@%%@NL@%
  18588.   %@AS@%                             C              DB      13d,10d%@AE@%%@NL@%
  18589.   %@AS@%                             C  l&name      EQU     $-name%@AE@%%@NL@%
  18590.   %@AS@%                             C              ENDM%@AE@%%@NL@%
  18591. %@NL@%
  18592.   %@AS@%= 0080                         larg    EQU     80h%@AE@%%@NL@%
  18593. %@NL@%
  18594.   %@AS@%                                       DOSSEG%@AE@%%@NL@%
  18595.   %@AS@%                                       .MODEL  small%@AE@%%@NL@%
  18596. %@NL@%
  18597.   %@AS@%0100                                   .STACK  256%@AE@%%@NL@%
  18598. %@NL@%
  18599.   %@AS@%                               color   RECORD  b:1,r:3=1,i:1=1,f:3=7%@AE@%%@NL@%
  18600. %@NL@%
  18601.   %@AS@%                               date    STRUC%@AE@%%@NL@%
  18602.   %@AS@%0000  05                       month   DB      5%@AE@%%@NL@%
  18603.   %@AS@%0001  07                       day     DB      7%@AE@%%@NL@%
  18604.   %@AS@%0002  07C3                     year    DW      1987%@AE@%%@NL@%
  18605.   %@AS@%0004                           date    ENDS%@AE@%%@NL@%
  18606. %@NL@%
  18607.   %@AS@%0000                                   .DATA%@AE@%%@NL@%
  18608.   %@AS@%0000  1F                       text    color   <>%@AE@%%@NL@%
  18609.   %@AS@%0001  09                       today   date    <9,22,1987>%@AE@%%@NL@%
  18610.   %@AS@%0002  16%@AE@%%@NL@%
  18611.   %@AS@%0003  07C3%@AE@%%@NL@%
  18612. %@NL@%
  18613.   %@AS@%0005  0064[                    buffer  DW      100 DUP(?)%@AE@%%@NL@%
  18614.   %@AS@%            ????%@AE@%%@NL@%
  18615. %@NL@%
  18616. %@NL@%
  18617. %@NL@%
  18618.   %@AS@%                                       StrAlloc ending,"Finished."%@AE@%%@NL@%
  18619.   %@AS@%00CD  46 69 6E 69 73 68 65  1  ending        DB      "Finished."%@AE@%%@NL@%
  18620.   %@AS@%00D6  0D 0A                 1              DB      13d,10d%@AE@%%@NL@%
  18621. %@NL@%
  18622.   %@AS@%0000                                   .CODE%@AE@%%@NL@%
  18623. %@NL@%
  18624.   %@AS@%0000  B8 ---- R                start:  mov     ax,@DATA%@AE@%%@NL@%
  18625.   %@AS@%0003  8E D8                            mov     ds,ax%@AE@%%@NL@%
  18626. %@NL@%
  18627.   %@AS@%0005  B8 0063                          mov     ax,'c'%@AE@%%@NL@%
  18628.   %@AS@%0008  26: 8B 0E 0080                   mov     cx,es:larg%@AE@%%@NL@%
  18629.   %@AS@%000D  BF 0052                          mov     di,82%@AE@%%@NL@%
  18630.   %@AS@%0010  F2/ AE                           repne   scasb%@AE@%%@NL@%
  18631.   %@AS@%0012  57                               push    di%@AE@%%@NL@%
  18632. %@NL@%
  18633.   %@AS@%                                       EXTRN   work:NEAR%@AE@%%@NL@%
  18634.   %@AS@%0013  E8 0000 E                        call    work%@AE@%%@NL@%
  18635. %@NL@%
  18636.   %@AS@%0016  B8 170C                          mov     ax,4C00%@AE@%%@NL@%
  18637.   %@AS@%listdemo.ASM(40): error A2107: Non-digit in number%@AE@%%@NL@%
  18638.   %@AS@%0019  CD 21                            int     21h%@AE@%%@NL@%
  18639. %@NL@%
  18640.   %@AS@%001B                                   END     start%@AE@%%@NL@%
  18641. %@NL@%
  18642. %@NL@%
  18643. %@2@%%@CR:SCC.2       @%%@AB@%C.2  Reading a Macro Table%@AE@%%@EH@%%@NL@%
  18644. %@NL@%
  18645. %@4@%%@CR:IXC.22      @%%@CR:IXC.23      @%  A macro table at the end of a listing file gives the names and sizes (in%@EH@%
  18646.   lines) of all macros called or defined in the source file. The macros
  18647.   appear in alphabetical order.%@NL@%
  18648. %@NL@%
  18649. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18650. %@NL@%
  18651.   %@AS@%Macros:%@AE@%%@NL@%
  18652. %@NL@%
  18653.   %@AS@%                N a m e                 Lines%@AE@%%@NL@%
  18654. %@NL@%
  18655.   %@AS@%STRALLOC . . . . . . . . . . . .           3%@AE@%%@NL@%
  18656. %@NL@%
  18657. %@NL@%
  18658. %@2@%%@CR:SCC.3       @%%@AB@%C.3  Reading a Structure and Record Table%@AE@%%@EH@%%@NL@%
  18659. %@NL@%
  18660. %@4@%%@CR:IXC.24      @%%@CR:IXC.25      @%%@CR:IXC.26      @%%@CR:IXC.27      @%  All structures and records declared in the source file are given at the%@EH@%
  18661.   end of the listing file. The names are listed in alphabetical order. Each
  18662.   name is followed by the fields in the order in which they are declared.%@NL@%
  18663. %@NL@%
  18664. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18665. %@NL@%
  18666.   %@AS@%Structures and Records:%@AE@%%@NL@%
  18667. %@NL@%
  18668.   %@AS@%                N a m e                 Width   # fields%@AE@%%@NL@%
  18669.   %@AS@%                                        Shift   Width   Mask    Initial%@AE@%%@NL@%
  18670. %@NL@%
  18671.   %@AS@%COLOR  . . . . . . . . . . . . .        0008    0004%@AE@%%@NL@%
  18672.   %@AS@%  B  . . . . . . . . . . . . . .        0007    0001    0080    0000%@AE@%%@NL@%
  18673.   %@AS@%  R  . . . . . . . . . . . . . .        0004    0003    0070    0010%@AE@%%@NL@%
  18674.   %@AS@%  I  . . . . . . . . . . . . . .        0003    0001    0008    0008%@AE@%%@NL@%
  18675.   %@AS@%  F  . . . . . . . . . . . . . .        0000    0003    0007    0007%@AE@%%@NL@%
  18676.   %@AS@%DATE . . . . . . . . . . . . . .        0004    0003%@AE@%%@NL@%
  18677.   %@AS@%  MONTH  . . . . . . . . . . . .        0000%@AE@%%@NL@%
  18678.   %@AS@%  DAY  . . . . . . . . . . . . .        0001%@AE@%%@NL@%
  18679.   %@AS@%  YEAR . . . . . . . . . . . . .        0002%@AE@%%@NL@%
  18680. %@NL@%
  18681. %@4@%  The first row of headings only applies to the record or structure itself.%@EH@%
  18682.   For a record, the "Width" column shows the width in bits while the "#
  18683.   fields" column tells the total number of fields.%@NL@%
  18684. %@NL@%
  18685. %@4@%  The second row of headings applies only to fields of the record or%@EH@%
  18686.   structure. For records, the "Shift" column lists the offset (in bits) from
  18687.   the low-order bit of the record to the low-order bit in the field. The
  18688.   "Width" column lists the number of bits in the field. The "Mask" column
  18689.   lists the maximum value of the field, expressed in hexadecimal. The
  18690.   "Initial" column lists the initial value of the field, if any. For each
  18691.   field, the table shows the mask and initial values as if they were placed
  18692.   in the record and all other fields were set to 0.%@NL@%
  18693. %@NL@%
  18694. %@4@%  For a structure, the "Width" column lists the size of the structure in%@EH@%
  18695.   bytes. The "# fields" column lists the number of fields in the structure.
  18696.   Both values are in hexadecimal.%@NL@%
  18697. %@NL@%
  18698. %@4@%  For structure fields, the "Shift" column lists the offset in bytes from%@EH@%
  18699.   the beginning of the structure to the field. This value is in hexadecimal.
  18700.   The other columns are not used.%@NL@%
  18701. %@NL@%
  18702. %@NL@%
  18703. %@2@%%@CR:SCC.4       @%%@AB@%C.4  Reading a Segment and Group Table%@AE@%%@EH@%%@NL@%
  18704. %@NL@%
  18705. %@4@%%@CR:IXC.28      @%%@CR:IXC.29      @%%@CR:IXC.30      @%%@CR:IXC.31      @%  Segments and groups used in the source file are listed at the end of the%@EH@%
  18706.   program with their size, align type, combine type, and class. If you used
  18707.   simplified segment directives in the source file, the actual segment names
  18708.   generated by QuickAssembler will be listed in the table.%@NL@%
  18709. %@NL@%
  18710. %@4@%  %@AB@%Example%@AE@%%@EH@%%@NL@%
  18711. %@NL@%
  18712.   %@AS@%Segments and Groups:%@AE@%%@