PCjs Machines
Home of the original IBM PC emulator for browsers.
QuickAssembler 2.01 Programmer's Guide
The following document is from the Microsoft Programmer’s Library 1.3 CD-ROM.
Microsoft(R) QuickAssembler Programmer's Guide Version 2.01
════════════════════════════════════════════════════════════════════════════
Microsoft(R) QuickAssembler Programmer's Guide Version 2.01
════════════════════════════════════════════════════════════════════════════
Information in this document is subject to change without notice and does
not represent a commitment on the part of Microsoft Corporation. The
software described in this document is furnished under a license agreement
or nondisclosure agreement. The software may be used or copied only in
accordance with the terms of the agreement. It is against the law to copy
the software on any medium except as specifically allowed in the license
or nondisclosure agreement. No part of this manual may be reproduced or
transmitted in any form or by any means, electronic or mechanical,
including photocopying and recording, for any purpose without the express
written permission of Microsoft.
(C)Copyright Microsoft Corporation, 1989. All rights reserved.
Simultaneously published in the U.S. and Canada.
Printed and bound in the United States of America.
Microsoft, MS, MS-DOS, GW-BASIC, QuickC, and XENIX are registered
trademarks of Microsoft Corporation.
IBM is a registered trademark of International Business Machines
Corporation.
Intel is a registered trademark of Intel Corporation.
Document No. LN0114-201-R00-0689
Part No. 06792
10 9 8 7 6 5 4 3 2 1
────────────────────────────────────────────────────────────────────────────
Table of Contents
Introduction
Chapter 1 The QuickAssembler Interface
1.1 Creating the Program
1.2 Building and Running a Program
1.3 Assembling from the Command Line
1.4 Choosing C or Assembler Defaults
1.5 Using the Quick Advisor (Help)
1.6 Debugging Assembly Code
1.6.1 Debugging .COM Files
1.6.2 Specifying Expressions
1.6.3 Tracing Execution
1.6.4 Modifying Registers and Flags
1.7 Viewing a Listing File
Chapter 2 Introducing 8086 Assembly Language
2.1 Programming the 8086 Family
2.2 Instructions, Directives, and Operands
2.2.1 The Name Field
2.2.2 The Operation Field
2.2.3 The Operand Field
2.2.4 The Comment Field
2.2.5 Entering Numbers in Different Bases
2.2.6 Line-Continuation Character
2.3 8086-Family Instructions
2.3.1 Data-Manipulation Instructions
2.3.1.1 The MOV Instruction
2.3.1.2 The ADD Instruction
2.3.1.3 The SUB Instruction
2.3.1.4 The INC and DEC Instructions
2.3.1.5 The AND Instruction
2.3.1.6 The MUL Instruction
2.3.2 Control-Flow Instructions
2.3.2.1 The JMP Instruction
2.3.2.2 The CMP Instruction
2.3.2.3 The Conditional Jump Instructions
2.4 Declaring Simple Data Objects
2.5 8086-Family Registers
2.5.1 The General-Purpose Registers
2.5.1.1 The AX Register
2.5.1.2 The BX Register
2.5.1.3 The CX Register
2.5.1.4 The DX Register
2.5.2 The Index Registers
2.5.3 The Pointer Registers
2.5.3.1 The BP Register
2.5.3.2 The SP Register
2.5.3.3 The IP Register
2.5.4 The Flags Register
2.6 Addressing Modes
2.6.1 Immediate Operands
2.6.2 Register Operands
2.6.3 Direct Memory Operands
2.6.4 Indirect Memory Operands
2.7 Segmented Addressing and Segment Registers
Chapter 3 Writing Assembly Modules for C Programs
3.1 A Skeleton for Procedure Modules
3.1.1 The .MODEL Directive
3.1.2 The .CODE Directive
3.1.3 The PROC Directive
3.1.4 The ENDP and END Statements
3.2 Instructions Used in This Chapter
3.3 Decimal Conversion Example
3.4 Decimal Conversion with Far Data Pointers
3.4.1 Writing a Model-Independent Procedure
3.4.2 Accessing Far Data through ES
3.5 Hexadecimal Conversion Example
Chapter 4 Writing Stand-Alone Assembly Programs
4.1 A Skeleton for Stand-Alone Programs
4.1.1 The .MODEL Directive
4.1.2 The .STACK, .CODE, and .DATA Directives
4.1.3 The .STARTUP Directive
4.2 Instructions Used in This Chapter
4.3 A Program That Says Hello
4.4 Inside the Stack Segment
4.5 Inside the Data Segment
4.6 Inside the Code Segment
4.7 Making the Program Repeat Itself
4.8 Creating .COM Files
4.9 Creating .COM Files with Full Segment Definitions
Chapter 5 Defining Segment Structure
5.1 Simplified Segment Directives
5.1.1 Understanding Memory Models
5.1.2 Specifying DOS Segment Order
5.1.3 Defining Basic Attributes of the Module
5.1.4 Defining Simplified Segments
5.1.4.1 How to Use Simplified Segments
5.1.4.2 How Simplified Segments Are Implemented
5.1.5 Using Predefined Segment Equates
5.1.6 Simplified Segment Defaults
5.1.7 Default Segment Names
5.2 Full Segment Definitions
5.2.1 Setting the Segment-Order Method
5.2.2 Defining Full Segments
5.2.2.1 Controlling Alignment with Align Type
5.2.2.2 Defining Segment Combinations with Combine Type
5.2.2.3 Controlling Segment Structure with Class Type
5.3 Defining Segment Groups
5.4 Associating Segments with Registers
5.5 Initializing Segment Registers
5.5.1 Initializing the CS and IP Registers
5.5.2 Initializing the DS Register
5.5.3 Initializing the SS and SP Registers
5.5.4 Initializing the ES Register
5.6 Nesting Segments
Chapter 6 Defining Constants, Labels, and Variables
6.1 Constants
6.1.1 Integer Constants
6.1.1.1 Specifying Integers with Radix Specifiers
6.1.1.2 Setting the Default Radix
6.1.2 Packed Binary Coded Decimal Constants
6.1.3 Real-Number Constants
6.1.4 String Constants
6.1.5 Determining Floating-Point Format
6.2 Assigning Names to Symbols
6.3 Using Type Specifiers
6.4 Defining Code Labels
6.4.1 Near-Code Labels
6.4.2 Anonymous Labels
6.4.3 Procedure Labels
6.4.4 Code Labels Defined with the LABEL Directive
6.5 Defining and Initializing Data
6.5.1 Variables
6.5.1.1 Integer Variables
6.5.1.2 Binary Coded Decimal Variables
6.5.1.3 String Variables
6.5.1.4 Real-Number Variables
6.5.2 Arrays and Buffers
6.5.3 Labeling Variables
6.5.4 Pointer Variables
6.6 Setting the Location Counter
6.7 Aligning Data
Chapter 7 Using Structures and Records
7.1 Structures
7.1.1 Declaring Structure Types
7.1.2 Defining Structure Variables
7.1.3 Using Structure Operands
7.2 Records
7.2.1 Declaring Record Types
7.2.2 Defining Record Variables
7.2.3 Using Record Operands and Record Variables
7.2.4 Record Operators
7.2.4.1 The MASK Operator
7.2.4.2 The WIDTH Operator
7.2.5 Using Record-Field Operands
Chapter 8 Creating Programs from Multiple Modules
8.1 Declaring Symbols Public
8.2 Declaring Symbols External
8.3 Using Multiple Modules
8.4 Declaring Symbols Communal
8.5 Specifying Library Files
Chapter 9 Using Operands and Expressions
9.1 Using Operands with Directives
9.2 Using Operators
9.2.1 Calculation Operators
9.2.1.1 Arithmetic Operators
9.2.1.2 Structure-Field-Name Operator
9.2.1.3 Index Operator
9.2.1.4 Shift Operators
9.2.1.5 Bitwise Logical Operators
9.2.2 Relational Operators
9.2.3 Segment-Override Operator
9.2.4 Type Operators
9.2.4.1 PTR Operator
9.2.4.2 SHORT Operator
9.2.4.3 THIS Operator
9.2.4.4 HIGH and LOW Operators
9.2.4.5 SEG Operator
9.2.4.6 OFFSET Operator
9.2.4.7 .TYPE Operator
9.2.4.8 TYPE Operator
9.2.4.9 LENGTH Operator
9.2.4.10 SIZE Operator
9.2.5 Operator Precedence
9.3 Using the Location Counter
9.4 Using Forward References
9.4.1 Forward References to Labels
9.4.2 Forward References to Variables
9.5 Strong Typing for Memory Operands
Chapter 10 Assembling Conditionally
10.1 Using Conditional-Assembly Directives
10.1.1 Testing Expressions with IF and IFE Directives
10.1.2 Testing the Pass with IF1 and IF2 Directives
10.1.3 Testing Symbol Definition with IFDEF and IFNDEF Directi
10.1.4 Verifying Macro Parameters with IFB and IFNB Directives
10.1.5 Comparing Macro Arguments with IFIDN and IFDIF Directiv
10.1.6 ELSEIF Directives
10.2 Using Conditional-Error Directives
10.2.1 Generating Unconditional Errors with .ERR, .ERR1, and .
Directives
10.2.2 Testing Expressions with .ERRE or .ERRNZ Directives
10.2.3 Verifying Symbol Definition with .ERRDEF and .ERRNDEF
Directives
10.2.4 Testing for Macro Parameters with .ERRB and .ERRNB
Directives
10.2.5 Comparing Macro Arguments with .ERRIDN and .ERRDIF
Directives
Chapter 11 Using Equates, Macros, and Repeat Blocks
11.1 Using Equates
11.1.1 Redefinable Numeric Equates
11.1.2 Nonredefinable Numeric Equates
11.1.3 String Equates
11.1.4 Predefined Equates
11.2 Using Macros
11.2.1 Defining Macros
11.2.2 Calling Macros
11.2.3 Using Local Symbols
11.2.4 Exiting from a Macro
11.3 Text-Macro String Directives
11.3.1 The SUBSTR Directive
11.3.2 The CATSTR Directive
11.3.3 The SIZESTR Directive
11.3.4 The INSTR Directive
11.3.5 Using String Directives Inside Macros
11.4 Defining Repeat Blocks
11.4.1 The REPT Directive
11.4.2 The IRP Directive
11.4.3 The IRPC Directive
11.5 Using Macro Operators
11.5.1 Substitute Operator
11.5.2 Literal-Text Operator
11.5.3 Literal-Character Operator
11.5.4 Expression Operator
11.5.5 Macro Comments
11.6 Using Recursive, Nested, and Redefined Macros
11.6.1 Using Recursion
11.6.2 Nesting Macro Definitions
11.6.3 Nesting Macro Calls
11.6.4 Redefining Macros
11.6.5 Avoiding Inadvertent Substitutions
11.7 Managing Macros and Equates
11.7.1 Using Include Files
11.7.2 Purging Macros from Memory
Chapter 12 Controlling Assembly Output
12.1 Sending Messages to the Standard Output Device
12.2 Controlling Page Format in Listings
12.2.1 Setting the Listing Title
12.2.2 Setting the Listing Subtitle
12.2.3 Controlling Page Breaks
12.2.4 Naming the Module
12.3 Controlling the Contents of Listings
12.3.1 Suppressing and Restoring Listing Output
12.3.2 Controlling Listing of Conditional Blocks
12.3.3 Controlling Listing of Macros
Chapter 13 Loading, Storing, and Moving Data
13.1 Transferring Data
13.1.1 Copying Data
13.1.2 Exchanging Data
13.1.3 Looking Up Data
13.1.4 Transferring Flags
13.2 Converting between Data Sizes
13.2.1 Extending Signed Values
13.2.2 Extending Unsigned Values
13.3 Loading Pointers
13.3.1 Loading Near Pointers
13.3.2 Loading Far Pointers
13.4 Transferring Data to and from the Stack
13.4.1 Pushing and Popping
13.4.2 Using the Stack
13.4.3 Saving Flags on the Stack
13.4.4 Saving All Registers on the Stack
13.5 Transferring Data to and from Ports
Chapter 14 Doing Arithmetic and Bit Manipulations
14.1 Adding
14.1.1 Adding Values Directly
14.1.2 Adding Values in Multiple Registers
14.2 Subtracting
14.2.1 Subtracting Values Directly
14.2.2 Subtracting with Values in Multiple Registers
14.3 Multiplying
14.4 Dividing
14.5 Calculating with Binary Coded Decimals
14.5.1 Unpacked BCD Numbers
14.5.2 Packed BCD Numbers
14.6 Doing Logical Bit Manipulations
14.6.1 AND Operations
14.6.2 OR Operations
14.6.3 XOR Operations
14.6.4 NOT Operations
14.7 Shifting and Rotating Bits
14.7.1 Multiplying and Dividing by Constants
14.7.2 Moving Bits to the Least-Significant Position
14.7.3 Adjusting Masks
14.7.4 Shifting Multiword Values
Chapter 15 Controlling Program Flow
15.1 Jumping
15.1.1 Jumping Unconditionally
15.1.2 Jumping Conditionally
15.1.2.1 Comparing and Jumping
15.1.2.2 Jumping Based on Flag Status
15.1.2.3 Testing Bits and Jumping
15.2 Looping
15.3 Using Procedures
15.3.1 Calling Procedures
15.3.2 Defining Procedures
15.3.3 Passing Arguments on the Stack
15.3.4 Declaring Parameters with the PROC Directive
15.3.5 Using Local Variables
15.3.6 Creating Locals Automatically
15.3.7 Variable Scope
15.3.8 Setting Up Stack Frames
15.4 Using Interrupts
15.4.1 Calling Interrupts
15.4.2 Defining and Redefining Interrupt Routines
15.5 Checking Memory Ranges
Chapter 16 Processing Strings
16.1 Setting Up String Operations
16.2 Moving Strings
16.3 Searching Strings
16.4 Comparing Strings
16.5 Filling Strings
16.6 Loading Values from Strings
16.7 Transferring Strings to and from Ports
Chapter 17 Calculating with a Math Coprocessor
17.1 Coprocessor Architecture
17.1.1 Coprocessor Data Registers
17.1.2 Coprocessor Control Registers
17.2 Emulation
17.3 Using Coprocessor Instructions
17.3.1 Using Implied Operands in the Classical-Stack Form
17.3.2 Using Memory Operands
17.3.3 Specifying Operands in the Register Form
17.3.4 Specifying Operands in the Register-Pop Form
17.4 Coordinating Memory Access
17.5 Transferring Data
17.5.1 Transferring Data to and from Registers
17.5.1.1 Real Transfers
17.5.1.2 Integer Transfers
17.5.1.3 Packed BCD Transfers
17.5.2 Loading Constants
17.5.3 Transferring Control Data
17.6 Doing Arithmetic Calculations
17.7 Controlling Program Flow
17.7.1 Comparing Operands to Control Program Flow
17.7.1.1 Compare
17.7.1.2 Compare and Pop
17.7.2 Testing Control Flags after Other Instructions
17.8 Using Transcendental Instructions
17.9 Controlling the Coprocessor
Chapter 18 Controlling the Processor
18.1 Controlling Timing and Alignment
18.2 Controlling the Processor
18.3 Processor Directives
Appendix A Mixed-Language Mechanics
A.1 Writing the Assembly Procedure
A.1.1 Setting Up the Procedure
A.1.2 Entering the Procedure
A.1.3 Allocating Local Data (Optional)
A.1.4 Preserving Register Values
A.1.5 Accessing Parameters
A.1.6 Returning a Value (Optional)
A.1.7 Exiting the Procedure
A.2 Calls from Modules Using C Conventions
A.3 Calls from Non-C Modules
A.4 Calling High-Level Languages from Assembly Language
A.5 Using Full Segment Definitions
Appendix B Using Assembler Options with QCL
B.1 Specifying the Segment-Order Method
B.2 Checking Code for Tiny Model
B.3 Selecting Case Sensitivity
B.4 Defining Assembler Symbols
B.5 Displaying Error Lines on the Screen
B.6 Creating Code for a Floating-Point Emulator
B.7 Creating Listing Files
B.8 Enabling One-Pass Assembly
B.9 Listing All Lines of Macro Expansions
B.10 Creating a Pass 1 Listing
B.11 Specifying an Editor-Oriented Listing
B.12 Suppressing Tables in the Listing File
B.13 Adding a Line-Number Index to the Listing
B.14 Listing False Conditionals
B.15 Controlling Display of Assembly Statistics
B.16 Setting the Warning Level
Appendix C Reading Assembly Listings
C.1 Reading Code in a Listing
C.2 Reading a Macro Table
C.3 Reading a Structure and Record Table
C.4 Reading a Segment and Group Table
C.5 Reading a Symbol Table
C.6 Reading Assembly Statistics
C.7 Reading a Pass 1 Listing
Index
────────────────────────────────────────────────────────────────────────────
Introduction
If you're a C programmer who has been wanting to try out the full power of
assembly language, this is the product for you.
Microsoft(R) QuickC(R) with QuickAssembler is a package you install along
with Microsoft QuickC Version 2.0 in order to create a single powerful
environment in which you can develop C, assembly, and mixed-language
programs. What's more, QuickAssembler is an integrated environment,
containing tools for editing, assembling, compiling, and linking.
Integrated tools help you achieve faster development of assembly-language
programs.
Each MS-DOS(R) and IBM(R) PC-DOS computer is driven by one of the
processors in the 8086 family. A processor is the central motor of a
computer. It responds to its own numeric language, called "machine code."
Assembly language is very close to machine code, but it lets you use
meaningful keywords and variable names instead of difficult-to-remember
numeric codes. As a result, assembly language is convenient to use, but
gives you the ultimate in ability to control hardware and optimize code.
To support the low-level operations of assembly language, QuickAssembler
expands the general power of the QuickC environment. Increased debugging
capabilities let you change flag settings and modify registers──including
registers of the 8087 math coprocessor. Furthermore, the Quick Advisor
(the on-line Help system) is expanded to provide help on QuickAssembler
keywords as well as DOS and ROM-BIOS services.
A Note about Operating-System Terms
Microsoft documentation uses the term "OS/2" to refer to the OS/2 system──
Microsoft Operating System/2 (MS(R) OS/2) and IBM OS/2. Similarly, the
term "DOS" refers to both the MS-DOS and IBM Personal Computer DOS
operating systems. The name of a specific operating system is used when it
is necessary to note features unique to that system.
General Features
QuickAssembler does not replace the QuickC in-line assembler, which you
can continue to use inside .C files. The joint QuickC/QuickAssembler
environment puts both QuickAssember and the in-line assembler at your
disposal. But Microsoft QuickAssembler supports a number of features
beyond those supported by the in-line assembler:
■ You can write stand-alone assembly programs. These programs begin and
end with assembly code and do not include the C start-up code. Unlike
programs written from within C modules, useful stand-alone assembly
programs can be 1K (kilobyte) or even smaller.
■ You can use the assembler's rich set of macro-definition capabilities,
which go far beyond the macro capabilities supported by C. An
assembly-language macro can handle variable parameter lists, recursion,
and repeated operations. These macros are roughly as powerful and
flexible as procedure calls, but execute faster.
■ Your assembly modules can be shared by many different programs. Since
an assembly-language module is in its own file, you can write the
module once and link it to any program you want.
■ QuickAssembler is a full implementation of 8086 assembly language. You
can use the full set of the Microsoft Macro Assembler 5.1 directives
and operators.
In addition, QuickAssembler provides the best set of keywords yet
available for simplifying tedious programming tasks, such as initializing
registers at the beginning of a program or determining how to access
parameters on the stack. (Part 1 of this manual focuses on the use of
these keywords.)
QuickAssembler for QuickC is a DOS-based product, and it does not include
the following extensions to 8086 assembly language:
■ 80386 extended registers and special instructions
■ 80387 extended instructions
■ OS/2 protected-mode operation
QuickAssembler does support the 80286 extended instruction set, as well as
the 8087 and 80287 coprocessors. The 80386 processor can run all
QuickAssembler programs; the only limitation is that QuickAssembler does
not support extended capabilities of the 80386.
The Microsoft Macro Assembler supports 80386 extended features and
development of protected-mode applications.
System Requirements
In addition to a computer with one of the 8086-family processors, you must
have Version 2.1 or later of the MS-DOS or IBM PC-DOS operating system.
You can also run QuickAssembler in the 3.x compatibility box of OS/2
systems. Your computer system must have approximately 512K of memory. A
hard-disk setup is strongly recommended.
To enable the use of QuickAssembler, you should first choose Full Menus
from the Options menu.
──────────────────────────────────────────────────────────────────────────
NOTE The 8086 family is a set of processors that all support the same
basic instruction set. This family includes the 8088, 8086, 80188, 80186,
80286, and 80386 chips. All of these processors support the entire
instruction set of the 8086 itself; some support additional instructions.
Rather than list the entire set of chips, this manual often discusses the
core instruction set by referring only to the 8086.
──────────────────────────────────────────────────────────────────────────
Installing QuickAssembler
If you purchased QuickC and QuickAssembler together, the installation
procedure described in Up and Running automatically installs both
products. A few of the questions shown in that booklet are reworded in the
install program to make more sense for the joint QuickC/QuickAssembler
installation.
If you purchased QuickAssembler separately, run the installation program
on the QuickAssembler distribution disks. The first screen asks you the
following questions:
Source of assembler files [A:]:
Installing on a hard disk drive [Y]:
Copy QuickAssembler documentation files [Y]:
Copy sample Assembler programs [N]:
Do you want to change any of the above options? [N]
As with the QuickC installation program, the default responses are
indicated in brackets ([]). Each of these questions is accompanied by an
explanation at the bottom of the screen. To accept a default response,
press ENTER. If you enter an incorrect response, just answer no (N) to the
last question.
The second screen asks you the following questions:
Directory for QuickC executable files [C:\QC2\BIN]:
Directory for Sample files [C:\QC2\SAMPLES]:
Do you want to change any of the above options? [N]
The QuickAssembler installation program replaces some of the existing
QuickC files. QuickAssembler must be installed in the directory that
currently contains QC.EXE. Make sure you enter the location of your
current QuickC executable files. If you're not sure, press CTRL+C to stop
the installation and examine your setup.
Getting Information about Assembly Language
The combined paper and on-line documentation with QuickAssembler gives you
a complete reference to the language. This manual provides three basic
kinds of information:
■ Part 1, "Introducing QuickAssembler," provides a basic introduction to
programming in assembly language. Chapter 1 describes how the
interface changes when you install QuickAssembler. Chapter 2 gives a
general background to 8086 architecture and assembly-language concepts.
Chapters 3 and 4 demonstrate how to use special QuickAssembler
keywords to simplify programming. Even if you have used assembly
language before, you should take a look at these chapters.
■ Parts 2 ("Using Directives") and 3 ("Using Instructions") give a
reference to the use of directives and instructions. This material is
much less tutorial than Part 1, but it does illustrate the use of each
directive and instruction in context.
■ The appendixes explain low-level mixed-language techniques, the use of
assembly options with the QCL driver, and how to read listing files.
This manual does not teach systems programming or advanced programming
techniques. Even with the tutorial material provided in this manual, you
may want to purchase other books on assembly language, such as the ones
listed in the next section.
In addition, this manual assumes you understand certain basic concepts of
programming, such as modules, variables, and pointers. If you need more
background in one of these topics, you should first read the appropriate
sections in C For Yourself. Part 1 of this manual often explains concepts
by comparing a language feature to C.
The Quick Advisor (the on-line Help system) is an integral part of the
overall documentation. As explained in Section 1.5, "Using the Quick
Advisor (Help)," QuickAssembler provides help on all keywords──in
particular, you get instant reference information on each instruction,
including timing, encoding, and flag settings. The Help Contents and Index
screens also provide information on each DOS service.
Books on Assembly Language
The following books may be useful in learning to program in assembly
language:
Duncan, Ray. Advanced MS-DOS. Redmond, WA: Microsoft Corporation, 1986.
An intermediate book on writing C and assembly-language programs that
interact with MS-DOS (includes DOS and BIOS function descriptions)
Jourdain, Robert. Programmer's Problem Solver for the IBM PC, XT and AT.
New York: Brady Communications Company, Inc., 1986.
Reference of routines and techniques for interacting with hardware
devices through DOS, BIOS, and ports (high-level routines in BASIC and
low- or medium-level routines in assembler)
Lafore, Robert. Assembly Language Primer for the IBM PC & XT. New York:
Plume/Waite, 1984.
An introduction to assembly language, including some information on DOS
function calls and IBM-type BIOS
Metcalf, Christopher D., and Sugiyama, Marc B. COMPUTE!'s Beginner's Guide
to Machine Language on the IBM PC & PCjr. Greensboro, NC: COMPUTE!
Publications, Inc., 1985.
Beginning discussion of assembly language, including information on the
instruction set and MS-DOS function calls
Microsoft MS-DOS Programmer's Reference. Redmond, WA: Microsoft Press,
1986, 1987.
Reference manual for MS-DOS
Morgan, Christopher, and the Waite Group. Bluebook of Assembly Routines
for the IBM PC. New York: New American Library, 1984.
Sample assembly routines that can be integrated into assembly or
high-level-language programs
Norton, Peter. The Peter Norton Programmer's Guide to the IBM PC. Redmond,
WA: Microsoft Press, 1985.
Information on using IBM-type BIOS and MS-DOS function calls
Scanlon, Leo J. IBM PC Assembly Language: A Guide for Programmers. Bowie,
MD: Robert J. Brady Co., 1983.
An introduction to assembly language, including information on DOS
function calls
Schneider, Al. Fundamentals of IBM PC Assembly Language. Blue Ridge
Summit, PA: Tab Books Inc., 1984.
An introduction to assembly language, including information on DOS
function calls
These books are listed for your convenience only. Microsoft Corporation
does not endorse these books (with the exception of those published by
Microsoft) or recommend them over others on the same subjects.
Document Conventions
The following document conventions are used throughout this manual:
Example of Description
Convention
──────────────────────────────────────────────────────────────────────────
SAMPLE2.ASM Uppercase letters indicate file names, segment names,
registers, and terms used at the DOS-command level.
.MODEL Boldface type indicates assembly-language directives,
instructions, type specifiers, and predefined equates,
as well as keywords in other programming languages.
placeholders Italic letters indicate placeholders for information
you must supply, such as a file name. Italics are also
occasionally used for emphasis in the text.
target This font is used to indicate example programs, user
input, and screen output.
SHIFT Names of keys on the keyboard appear in small capital
letters. Notice that a plus (+) indicates a
combination of keys. For example, CTRL+E means to hold
down the CTRL key while pressing the E key.
[[argument ]] Items inside double square brackets are optional.
{register | memory} Braces and a vertical bar indicate a choice between
two or more items. You must choose one of the items
unless double square brackets surround the braces.
Repeating Three dots following an item indicate that more items
elements... having the same form may appear.
Program A column of three dots tells you that part of a
. program has been intentionally omitted.
.
.
Fragment
"processor flag" The first time a new term is defined, it is enclosed
in quotation marks.
Color Graphics The first time an acronym is used, it is spelled out.
Adapter (CGA)
Getting Assistance or Reporting Problems
If you need help or feel you have discovered a problem in the software,
please provide the following information to help us locate the problem:
■ The version of DOS you are running (use the DOS VER command)
■ Your system configuration (the type of machine you are using, its total
memory, and its total free memory at assembler execution time, as well
as any other information you think might be useful)
■ The assembly command line used (or the link command line if the problem
occurred during linking)
■ Any object files or libraries you linked with if the problem occurred
at link time
If your program is very large, please try to reduce its size to the
smallest possible program that still produces the problem.
Use the Product Assistance Request form at the back of this manual to send
this information to Microsoft.
If you have comments or suggestions regarding any of the manuals
accompanying this product, please indicate them on the Document Feedback
card at the back of this manual.
If you are not already a registered QuickAssembler owner, you should fill
out and return the Registration Card. This enables Microsoft to keep you
informed of updates and other information about the assembler.
────────────────────────────────────────────────────────────────────────────
PART 1: Using Assembler Programs
Part 1 of the Programmer's Guide (comprising Chapters 1-4) will help
you start using assembly language quickly.
Chapter 1 summarizes all the differences between the standard QuickC
interface and the expanded QuickC/QuickAssembler interface. Read this
chapter to learn how to enter, assemble, and run an assembly-language
program.
Read Chapter 2 if you are new to 8086 assembly language or need to review
basic concepts. Chapter 2 explains the architecture of 8086-family
processors, as well as how to write simple code and data statements.
Whether or not you're new to assembly language, you'll want to read
Chapters 3 and 4, which show the use of QuickAssembler's simplified
keywords in useful examples. These keywords make programming easier.
────────────────────────────────────────────────────────────────────────────
Chapter 1: The QuickAssembler Interface
After you install Microsoft QuickC with QuickAssembler, you'll have a
single environment for both compiling and assembling. You can create C
programs, assembly-language programs, and programs that combine both
languages.
The environment completely supports the standard QuickC features,
including all editing commands as well as mouse, keyboard, and menu
techniques. This manual assumes you have read QuickC Up and Running and
have used the on-line Help system to learn how to use each menu. Refer to
these sources of information for basic help on using the interface.
The combined QuickC/QuickAssembler interface provides some new menu
selections and dialog boxes to support development of assembly-language
programs. This chapter describes the new features, focusing on areas where
the interface adds new functionality: creating a program, building a
program, getting help, debugging, and viewing a listing file. To enable
all the features described in this chapter, you should first choose Full
Menus from the Options menu if you are not already using full menus.
1.1 Creating the Program
Start the environment with the QC command, regardless of whether you're
creating a C or assembly-language source file. You can type QC by itself
or QC followed by the name of a file.
By default, QC assumes that a file name on the command line has a .C
extension. You'll learn how to change this behavior later (by choosing
Display from the Options menu), but for now, make sure you include the
.ASM file extension when you want to create an assembly-language module:
QC SAMPLE.ASM
If the file is new, the QuickC/QuickAssembler environment asks you if you
would like to create the file.
Once inside the QuickC/QuickAssembler environment, you can enter a program
by using all the QuickC editing commands. You can get started by entering
the following stand-alone assembly program. By default, QuickAssembler is
not case sensitive (except for external symbols), so you can enter
statements as uppercase or lowercase.
.MODEL small
.STACK
.CODE
.STARTUP
mov ah,2
mov dl,7
int 21h
mov ax,4c00h
int 21h
END
Enter the program above in a file with a .ASM extension. No other modules
and no special assembly or link flags are required. When run, the program
beeps and exits.
For now, you may just want to run the program to see how the
QuickC/Quick-Assembler environment works. However, you can read the rest
of this section to get a brief explanation of why the program works.
The four statements are directives──nonexecutable statements that give
basic structure to the program by declaring a memory model, stack segment,
and code segment.
The next five statements perform the actions of the program. The first
three set up a call to a DOS function that prints the beep character. (The
QuickAssembler Advisor, which you access through the Help menu, provides
information on each DOS function.) The first three statements are shown
below, with comments:
mov ah,2 ; Move 2 to AH (select Print function)
mov dl,7 ; Move 7 to DL (select Beep character)
int 21h ; Call DOS function
The next two statements, shown below with comments, call DOS to exit
gracefully. Unlike C programs, assembly-language programs must make an
explicit function call to exit, or else cause the processor to execute
meaningless instructions beyond the end of the program.
mov ax,4c00h ; Move 4c00h to AX (select Exit
; function and 0 return code)
int 21h ; Call DOS function
The last statement ends the module.
1.2 Building and Running a Program
Once inside the QuickC/QuickAssembler environment, you build an
assembly-language program the same way you build a C program. Choose the
Go command from the Run menu, or press the F5 key.
The environment assembles and links the program if it needs to be built.
Then, if there are no errors, it executes the program. You can also
assemble a program by using the Make menu. The Compile File command
assembles your file rather than compiling it, assuming the current file
has a .ASM extension.
To help you create assembly-language programs, the QuickC/QuickAssembler
interface adds the following extensions to QuickC:
■ A program list can now have .ASM files as well as .C, .OBJ, and .LIB
files if you work with multiple modules.
■ The Make dialog box from the Options menu has a new option button:
Assembler Flags.
■ The Assembler Flags dialog box lets you control how .ASM files are
assembled.
If your program has multiple modules, you can add .ASM files to the
program list as well as other kinds of files. When you build the program,
the environment compiles each .C file module that needs to be built and
assembles each .ASM module that needs to be built.
For example, the program list in Figure 1.1 creates a mixed-language
program with both C and assembly-language source files.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 1.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The environment sets the default file extension by looking at the
extension of the last file loaded. If the last file loaded had a .ASM
extension, the File List field now displays all the .ASM files for the
current directory. If the last file loaded had a .C extension, the File
List field displays all .C files.
You can alter this behavior by choosing Display from the Options menu, as
explained in Section 1.4, "Choosing C or Assembler Defaults." In any
case, you can always control which files are displayed by entering a
wildcard expression, such as *.asm, in the File Name field.
The environment lets you set assembler options as well as compiler
options. When you open the Options menu and choose Make, the dialog box
shown in Figure 1.2 appears.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 1.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
This dialog box contains one new field: Assembler Flags. When you choose
this field, a new dialog box, shown in Figure 1.3, appears.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 1.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
By setting flags in the Assembler Flags dialog box, you control the action
of the assembler whenever it builds a program. These settings have no
effect on .C modules, but do affect how each .ASM module is assembled.
This dialog box contains a Debug Flags section, which has options that
apply only to Debug builds, and a Global Flags section, which has options
that apply to every build. Choose the Help button for an explanation of
each option.
──────────────────────────────────────────────────────────────────────────
NOTE You control the type of build operation (Debug or Release) by
choosing the appropriate option button in the dialog box shown in Figure
1.2. You can return to that dialog box by choosing the OK or Cancel
command button. By choosing Debug (the default), you can use all of the
QuickC debugging commands while running the program. By choosing Release,
you produce a program that cannot be debugged but is somewhat smaller.
──────────────────────────────────────────────────────────────────────────
The Custom Flags section lets you enter additional options. In the three
Custom Flags text boxes, you can type any of the assembly options accepted
by the QCL driver. See Appendix B for a description of these options. The
next section describes how to use the QCL driver to assemble programs.
1.3 Assembling from the Command Line
You can run QuickAssembler from the command line, just as you can run
QuickC. One utility, QCL, invokes both the assembler and compiler. You can
even use it to compile, assemble, and link mixed-language programs in one
step. However, make sure you use the version of QCL copied during
QuickAssembler installation.
If you type a file name that has a .C extension, QCL invokes the C
compiler. For example, the following command compiles and links the file
SAMPLE1.C:
QCL SAMPLE1.C
If you type a file name that has a .ASM extension, QCL invokes the
QuickAssembler. For example, the following command assembles and links the
file SAMPLE2.ASM:
QCL SAMPLE2.ASM
In any case, QCL links all resulting object files to create a .EXE file,
unless you specify /c on the command line. (You can also create a .COM
file if the program is written entirely in assembly language.) For
example, the following command compiles SAMPLE1.C and assembles
SAMPLE2.ASM, but does not link the resulting object files:
QCL /c SAMPLE1.C /Cl SAMPLE2.ASM
As always, you can specify .LIB files and .OBJ files on the QCL command
line. A file with no extension is assumed to have a .OBJ extension by
default. For example, the following QCL command compiles M1.C, assembles
M2.ASM (with lowercase symbols preserved), and links M1.OBJ, M2.OBJ, and
M3.OBJ. Finally, QCL searches M4.LIB for any unresolved references.
QCL /Cx M1.C M2.ASM M3 M4.LIB
You can specify a number of QuickAssembler options, in addition to the
ones provided specifically for C. See Appendix B, "Using Assembler
Options with QCL," for a description of all these options.
1.4 Choosing C or Assembler Defaults
At all times, you can use the QuickC/QuickAssembler environment to create
either C modules or assembly-language modules. However, there are some
details of operation that make it a little easier to work with one
language or another.
For example, one consideration is whether the dialog box starts by
displaying all the C files in the directory (*.c) or all the
assembly-language files (*.asm) when you choose the Open command from the
File menu. You can control this behavior by choosing Display from the
Options menu. Figure 1.4 shows the dialog box that appears.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 1.4 of the manual │
└────────────────────────────────────────────────────────────────────────┘
In the Language section of this dialog box, select either C, Assembler, or
Auto. The Auto selection uses C or Assembler defaults, depending on what
file was last loaded into the active window. For example, if you load the
PROG.ASM file into the source window, all the defaults (described below)
change to assembly-language settings.
──────────────────────────────────────────────────────────────────────────
NOTE When you first use QuickAssembler, the environment starts up in Auto
mode. Thereafter, it looks at the settings in QC.INI to determine what
mode to start in; this feature has the effect of saving display-mode
settings between sessions.
──────────────────────────────────────────────────────────────────────────
The following items change when the display mode changes──either because
you change the mode manually or because you are in Auto mode and load a
different kind of file:
■ For commands on the File menu, the default file name changes to *.c or
*.asm.
■ The Include command on the View menu responds to .H files if the
display mode is C, or .INC files if the display mode is Assembler.
■ The Index and Contents items from the Help menu bring up lists of
topics for either C or Assembly, as determined by the display mode.
Auto display mode assumes C defaults until you load a .ASM file. When you
start the environment with the QC command, QC assumes that file names on
the command line have .C extensions, unless the environment is in
Assembler display mode.
1.5 Using the Quick Advisor (Help)
QuickAssembler extends the number of topics you can get information on,
and updates QCENV.HLP so you can get context-sensitive help on the new
menu items and dialog boxes. In addition, you still continue to get help
on all of the C-language topics. The new topics, added for use with
assembly language, are shown below:
■ QuickAssembler instructions
■ QuickAssembler directives and operators
■ DOS and ROM-BIOS services
You can get help on assembly-language topics by using one of two different
methods:
1. Topical Help (press F1)
2. The Help menu
At all times, the expanded environment provides topical Help for both
assembler and C keywords. Place the cursor on the keyword, then press F1.
You can also get topical Help by moving the mouse cursor to the desired
word and clicking the Right mouse button. The display mode (described in
the previous section) determines whether C help files or assembly help
files are searched first.
──────────────────────────────────────────────────────────────────────────
NOTE If the keyword starts with a dot (.), do not place the cursor on the
dot or click on the dot to get topical Help. Place the cursor on the
keyword or click on the keyword.
──────────────────────────────────────────────────────────────────────────
QuickAssembler keywords include instructions, directives, and operators.
Chapter 2, "Introducing 8086 Assembly Language" provides information on
each of these concepts. An "instruction" is a specific action that the
processor executes. Instructions are the primary building blocks of an
assembly-language program.
The Help screens on instructions are particularly useful, because they
provide detailed information on timing, syntax, and processor flags. This
manual features a topical discussion of instructions, but provides only
limited information on timing and flags. To write the most efficient
assembly-language programs, you should refer often to the on-line Help for
instructions.
To get help on DOS or ROM-BIOS services, select Contents or Index from the
Help menu. These menu items give you help on assembly-language topics
rather than C topics whenever the display mode (described in the previous
section) is set to Assembler.
The Help system offers other paths to get to information on DOS and BIOS
functions. Move the mouse cursor to an interrupt number (such as 21H or
33) and click the Right mouse button, or move the cursor to the number and
press F1. The Help system responds by showing a screen listing of all the
functions accessed through that interrupt number. You can then go to the
specific Help screen you want. You can also get help on interrupt
functions by selecting context-sensitive help for the INT keyword.
You call these DOS and BIOS functions by using the INT instruction, as
described in Chapter 4. These services perform basic input and output
functions for you, giving you access to DOS and to hardware.
By default, the Smart Help display option is on. This option makes the
system more flexible by ignoring the presence or absence of a leading
underscore (_) in front of a name. Consequently, pressing F1 while on
_printf gives you help for the printf function.
1.6 Debugging Assembly Code
You can run a Debug build by choosing Debug in the dialog box opened by
the Options menu's Make command. Debug is the default setting, so you
probably won't need to choose it.
You can use all of QuickC's debugging commands with programs written in
assembly language. But keep in mind these considerations:
■ You must use an extra file with a .DBG file extension to debug programs
in .COM format.
■ You must use C syntax to specify expressions to watch or modify, even
when you debug assembly code. In addition, you can use the BY, WO, and
DW memory operators, register names, and the colon (:) operator. The
colon operator helps to specify segmented addresses.
■ When you trace execution of an assembly-language module, the behavior
of the environment changes. Screen swapping is turned on by default,
and the first line of code is never highlighted.
■ You can alter flag values and registers from within the environment.
Sections 1.6.1-1.6.4 discuss each debugging feature in turn.
1.6.1 Debugging .COM Files
Section 4.8, "Creating .COM Files," explains how to use tiny memory
model, along with a linker flag, to generate a program in the .COM-file
format. A .COM file has a total size limitation of 64K, but is slightly
smaller and loads faster than a similar .EXE file.
When you run a Debug build that creates a .COM file, the linker places
debugging information in a separate file with the same base name as the
program and with a .DBG extension. If you delete the .DBG file, you cannot
debug your program until you run another Debug build.
Otherwise, all the considerations that apply to debugging .EXE files apply
to .COM files as well.
1.6.2 Specifying Expressions
The Debug menu provides two commands──Watch Value and Watchpoint──that let
you specify an expression for the QuickC/QuickAssembler environment to
dynamically update and display. The environment displays the updated
values in the Watch window. When you choose one of these commands, a
dialog box appears, prompting you to enter an expression. Figure 1.5 shows
the dialog box for the Watch Value command.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 1.6.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
You can enter any combination of variable names, constants, and C-language
syntax. You cannot enter assembly-language keywords. However, the
environment does recognize all valid register names (including names of
both 8-bit and 16-bit registers). See Chapter 2, "Introducing 8086
Assembly Language," for information on registers.
In addition to register names, the expanded environment supports the
optional use of the colon operator (:) for specifying segmented addresses:
segment:offset
In the syntax display above, segment can be a constant or a register;
offset can be any expression. The QuickC/QuickAssembler environment
combines the segment and offset addresses to determine a physical address,
as described in Section 2.7, "Segmented Addressing and Segment
Registers."
The following examples demonstrate the use of the colon in valid
expressions. Note that you use C-language syntax to specify hexadecimal
numbers:
0xb000:0x0000
es:0x0100
es:(array[2])
ss:bp
The QuickC/QuickAssembler environment considers a segmented-address
expression to be a pointer to a character, which the Watch window
evaluates by displaying the character pointed to. However, you can use
QuickC type specifiers to alter how an expression is displayed. For
example, the Watch window evaluates the following expression by displaying
the numeric value of the address es:(warray+3):
es:(warray+3),p
You can use the three memory operators──BY, WO, and DW──to view the byte,
word, or doubleword of memory at a given address.
With pointer expressions and registers, BY returns the byte pointed to by
the expression. (Segmented addresses are pointer expressions, as are
procedure parameters declared with PTR.) With nonpointer variables, BY
returns the byte at the same address as the variable. WO and DW work the
same way, but return a word or doubleword, respectively.
The rest of this section demonstrates how to use the three memory
operators to specify useful expressions.
To watch the contents of a register, enter just the register's name. To
examine the value that the register points to, enter the BY, WO, and DW
operators followed by the register name.
Example Value Specified
──────────────────────────────────────────────────────────────────────────
bx The contents of the BX register
BY bx The byte pointed to by the BX register
WO bx The word pointed to by the BX register
DW es:si The doubleword pointed to by the SI register, relative
to the segment address in ES
To watch the value of a variable, enter the variable's name. To watch the
byte, word, or doubleword at the same address as the variable, use the BY,
WO, and DW operators. In this context, these operators function as the
QuickAssembler PTR operator does: they change the size of data to be
examined. They are similar, but not identical, to C type casts. In the
following examples, assume that Var is a word variable defined with DW:
Example Value Specified
──────────────────────────────────────────────────────────────────────────
Var The variable Var (the word at the address of Var)
BY Var The byte at the address of Var
DW Var The doubleword at the address of Var
You can use BY, WO, and DW to specify an array element, but you must
understand that expressions in the Debug window are treated like C
expressions rather than assembler expressions. As a result, the syntax you
use to watch a memory location in the Debug window is often different from
the syntax in your assembly source. For example, assume you have the
following data and code:
warr DW 1, 2, 3, 4, 5, 6
.
.
.
mov bx,0
mov cx,5
loop1: add ax,warr[bx]
add bx,2
loop loop1
You cannot watch the assembler expression warr[bx] directly. However, you
can put an equivalent C expression in the Debug window:
WO (char*)&warr + bx
The address-of operator is necessary to make the C debugger look at the
MASM array as a C array──that is, as an address. The value must cast to a
character pointer because the debugger looks at it as a scaled C index
rather than an unscaled assembler index. In this case, the assembler code
adds 2 to the pointer BX to adjust for the variable size. You must tell
the debugger to ignore its normal word scaling.
Expressions are only scaled when there is a variable in the expression. In
the expression WO BP+6 the 6 is not scaled──the expression means, "look at
the word six bytes beyond the address that is in BP." However, in the
expression WO &warr+6, the 6 is scaled because of the word size of the
variable. Note that the variable size, not the expression type ( BY, WO,
or DW), determines the size of scaling.
If you are comfortable with C, you can also use C expressions to look at
assembler expressions. Here are some examples you might find useful:
Example Value Specified
──────────────────────────────────────────────────────────────────────────
&Var The address of Var
es:0x81,s The string at es:[81h] (the DOS command line when a
program is started)
&Arr[3] The third element of an array (note that the 3 will be
scaled)
*(&Arr+3) Equivalent to the previous expression
1.6.3 Tracing Execution
The Run menu's Trace Into, Animate, and Step Over commands execute one
statement of your program at a time. These commands are fully functional
with assembly-language programs. However, debugging commands behave
differently when you trace execution of an assembly-language module, as
summarized below:
■ By default, screen swapping is on.
■ If the main module of the program is an assembly-language module, the
first line of the program is never highlighted.
■ The Calls menu does not function unless you write your program
according to certain guidelines.
The rest of this section elaborates on these differences.
When you trace execution of an assembly-language module, screen swapping
is turned on. The environment does not support an Auto screen-swapping
mode for assembly-language programs because it cannot detect when a
program writes to the screen. Therefore, when executing a .ASM file, the
environment equates the Auto screen-swapping selection with screen
swapping turned on.
You can always turn screen swapping off manually by choosing the Run/Debug
command from the Options menu. When a dialog box appears, choose the Off
option button in the Screen Swapping field.
Screen swapping causes the environment to switch to a full output screen
each time the program executes code. The effect is particularly noticeable
when you choose the Animate command. Leaving screen swapping on preserves
program output. However, if large portions of your program do not write to
the video display, you may want to turn screen swapping off temporarily.
The second debugging feature that operates differently for assembly-
language programs is current-line highlighting. When you restart a
program, the environment does not highlight the first line of code. The
debugging facility does not know which line of code is the first to be
executed, since this information is stored in the executable-file header.
After you execute a trace, the second program line is highlighted, and
thereafter current-line highlighting works as you would expect.
The third feature that operates differently is the Calls command from the
Debug menu. To ensure that the command works with assembly-language
modules, either use the PROC directive with an argument list or local
variables, as described in Chapter 3, "Writing Assembly Modules for C
Programs," or else set up the framepointer (the BP register) as described
in Appendix A, "Mixed-Language Mechanics." Both these methods set up a
stack frame for each procedure, using the standard Microsoft methods. The
environment checks stack frames to see what procedures have been called,
and with what parameters.
1.6.4 Modifying Registers and Flags
With the expanded QuickC/QuickAssembler environment, you can get much
greater use from the Registers window. The Registers window displays more
information than it does in the simple QuickC environment, and you can
also use the window to alter register and flag values.
──────────────────────────────────────────────────────────────────────────
NOTE By default, the environment does not display the Registers window.
To open this window, choose the Window command from the View menu. A
dialog box appears that lists all windows. Move the cursor to Registers
and press the ENTER key, or move the mouse cursor to Registers and double
click the Left mouse button. To close the window, repeat the procedure.
──────────────────────────────────────────────────────────────────────────
The Registers window displays the contents of both 8086 and 8087
registers. You can remove 8087 registers from the Registers window by
choosing Display from the Options menu. When the dialog box appears, turn
the Show 8087 option button off. The environment only displays 8087
registers if you have a math coprocessor or have a program that calls
floating-point emulator routines from a high-level language.
You can alter values in the window by either using the mouse or the
keyboard. To alter a value, you first select the item you want to change:
■ To alter a value with the mouse, select an item by clicking the Left
mouse button.
■ To alter a value with the keyboard, first place the cursor on an item
in the window. (Press TAB or SHIFT+TAB to cycle quickly through the
items.) Then select the item by pressing the ENTER key. The List field
has no function in this context and should be ignored.
Choosing a flag toggles the flag to the opposite setting. Choosing a
register brings up a dialog box. Type the new value for the register and
press ENTER.
1.7 Viewing a Listing File
When you assemble a module with the Debug build setting (the default),
QuickAssembler can create a listing file. Choose the type of listing by
using the Assembler Flags dialog box. (To access this dialog box, choose
Make from the Options menu, then choose Assembler Flags.) You should also
make sure that the One Pass Assembly option is not selected.
A QuickAssembler listing file shows precisely how the assembler translated
each line of code during the last program build. Each instruction in the
source code is listed next to its corresponding numeric code (machine
instruction).
Listing files are particularly useful if your program uses macro calls or
include files. The listing file displays each statement generated by a
macro call and each line of code copied from an include file. Tables at
the end of the listing file give information on macros, symbols,
structures, groups, and records. Part 2 of this manual describes each of
these features of assembly language.
To view the listing file, assemble the source code at least once. You can
view the listing file for the current module by choosing the Listing
command from the View menu. You can also view the file with the CTRL+F2
shortcut key.
The listing file is then displayed in the Source window, as shown in
Figure 1.6. You can page through this file by using all the normal
cursor-movement commands. When you want to return to the previous file,
press F2 or use the File menu. You can also leave the listing file by
choosing the Listing command again; this action causes the environment to
switch to the original line of source code that generated the current line
of code. In particular, if you are in a listing file and move the cursor
to a line generated from an include file (.INC), the Listing command
switches directly to that include file.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 1.7 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Normally, you would choose the Listing command when in a .LST file or in a
.ASM file with a corresponding .LST file (previously generated by a
program build). If you are not in either of these types of files, the
environment responds by displaying a dialog box for opening a file; *.lst
is the default file name.
────────────────────────────────────────────────────────────────────────────
Chapter 2: Introducing 8086 Assembly Language
Assembly-language programs control hardware directly, giving you the
ability to write the fastest, smallest programs possible and to execute
any operation. But assembly-language programming also requires an
understanding of the architecture of 8086-family processors.
Assembly language is close to machine code──the processor's numeric
language of 1's and 0's. Each QuickAssembler instruction corresponds to an
8086 instruction but consists of a meaningful name (mnemonic) instead of a
number. For example, the ADD instruction computes the sum of two items.
QuickAssembler translates this instruction to produce a numeric code, such
as 10000010 binary. The processor responds to this code when you run the
program.
This process of translation is called "assembling." Before you can
assemble a program, you need to understand the basic concepts of the
processor and of assembly language. This chapter presents these concepts.
2.1 Programming the 8086 Family
If you have programmed in C, you can get a good grasp of 8086 assembly
language by focusing on the differences between the two languages:
1. A C statement may combine many complex operations, but each line of
assembly language specifies just one limited action called an
"instruction." QuickAssembler also supports a number of nonexecutable
statements called "directives," which provide structure to the program,
declare data objects, and provide other information.
Sections 2.2-2.4 explain the basics of writing instructions and
directives.
2. C programs deal with memory locations (known as variables), but
assembly-language programs must deal with registers as well. A
"register" is a special memory location inside the processor itself,
having a permanent name rather than a numeric address.
Section 2.5, "8086-Family Registers," describes the use of each
register.
3. A data object in a C program can be arbitrarily complicated.
Assembly-language statements work on objects accessed through four
specific modes: immediate, register, direct memory, and indirect
memory. Each mode has specific properties and limitations imposed by
the processor.
Section 2.6, "Addressing Modes," explains each of these four modes and
gives examples.
4. The processor combines two 16-bit addresses to access each memory
location. This mechanism is called "segmented addressing." Assembly
language often requires a more complete understanding of segmented
addressing than C does.
Section 2.7, "Segmented Addressing and Segment Registers," explains
the full implications of segmented addressing.
Of the features listed above, segmented addressing is unique to the 8086
family. The 8086 is further distinguished from other processors by its set
of string operations, which permit fast initialization and copying of
blocks of data. You can read more about the string operations in Chapter
16, "Processing Strings."
2.2 Instructions, Directives, and Operands
The 8086-family processors understand only one kind of statement: an
instruction. QuickAssembler understands two kinds of statements:
instructions and directives.
As explained above, an instruction corresponds to a specific action that
the processor executes at run time. The fundamental task of the assembler
is to correctly translate each of these statements to specific
machine-code instructions.
As nonexecutable statements, directives are not translated to machine
actions. However, they give information to the assembler that affects how
other statements are translated. For example, some of the most important
directives declare data. These directives, in turn, help the assembler
correctly interpret instructions that refer to the data.
The rest of this section explains each part of an assembly-language
statement; the general syntax applies to both instructions and directives.
The section ends by stating the basics of entering numbers in different
radixes.
Syntax
Each line of source code consists of a blank line or a statement. Each
statement is an instruction or directive, and can contain as many as 512
characters. Statements can have up to four fields, as shown below:
[[name]] [[operation]] [[operands]] [[;comment]]
Each field (except the comment field) must be separated from the other
fields by a space or tab character. You can enter statements in uppercase
or lowercase letters. By default, QuickAssembler is not case sensitive,
but it does preserve case for external variables──thus providing
compatibility with C, which is case sensitive. You can control case
sensitivity by using the Assembler Flags dialog box.
As a convention, sample code in this manual uses uppercase letters for
directives, hexadecimal letter digits, and segment definitions.
2.2.1 The Name Field
The name field labels the statement with a symbolic name that other parts
of the program can reference. The meaning of the name depends on the type
of statement.
One of the most important uses of this field occurs in data declarations.
These declarations are much like variable declarations in C. The statement
defines the type and initial value. You use the name elsewhere in the
program, when you want to access the data.
QuickAssembler is different from C, however, in that the symbolic name
occurs in the first field. For example, the following DB directive
(Declare Bytes) associates the name string with a series of characters:
string DB "Hello, world"
In instructions, the name field functions like a program label in C: it
provides a target for a jump or call instruction elsewhere in the program.
To label an instruction, follow the name field with a colon (:). You can
place the name on the same line as the rest of the instruction or, to
improve readability, on a separate line. The following example shows the
latter case:
top: ; This label marks the top of the loop
mov ax,1 ; This is first instruction in the loop
There are other ways to label instructions. See Section 6.4, "Defining
Code Labels," for more information on how to declare labels.
2.2.2 The Operation Field
The operation field states the action of the statement. This field
determines the fundamental type of the statement──instruction or
directive. It also determines what additional syntax, if any, is required.
Some operations require an entry in the name field; most do not. If the
operation is an instruction, it strictly determines how many and what kind
of operands are legal.
This field contains exactly one item──an instruction or directive
mnemonic. "Mnemonics" are abbreviated, easy-to-remember names that each
symbolize a different operation (for instance, ADD, SUB, and OR). Examples
of directive mnemonics include EQU (Equate) and DB (Declare Bytes).
2.2.3 The Operand Field
The operand field lists the objects on which the statement operates.
Multiple operands are separated by commas. These objects can be registers,
constants, or memory locations. A memory location is typically represented
as a variable, although it can also be expressed as a numeric address or
complex expression.
Registers and constants require no previous declaration. To refer to a
variable, however, you should first declare the name with a data
directive, such as DB (Declare Bytes). The following example declares the
variable count and then uses it in an instruction:
count DB 7 ; Declare count as a byte variable
.
.
.
inc count ; count = count + 1
In the first statement, count appears in the name field and the number 7
appears in the operand field. The DB directive associates count with the
address of a byte initialized to 7. In the second statement, count appears
in the operand field. The INC instruction (increment) adds 1 to count,
thus increasing the value of the data to 8.
The next section gives more information on how to declare memory locations
as data types. Section 2.6, "Addressing Modes," gives a complete
description of all the different methods for specifying operands.
2.2.4 The Comment Field
The comment field lets you add text that appears in source code but is
ignored by the assembler. You can enter any text you want in this field.
Typically, you would use it to document the purpose of the statement. The
purpose of an assembly-language statement is not always self-explanatory,
and for this reason, programs often contain at least one comment for each
instruction.
Single-line comments always begin with a semicolon (;). You can also
create a multiline comment by one of two methods. You can enter successive
comment lines as shown below:
add count,5 ; Add 5 to count.
; ADD is the operation.
; count and 5 are operands.
sub Sum,12 ; Subtract 12 from Sum.
; SUB is the operation.
; Sum and 12 are operands.
You can also use the COMMENT directive, which lets you enter multiline
comments without using the semicolon. This directive has the following
syntax:
COMMENT delimiter [[text]]
text
[[text]] delimiter [[text]]
All text between the first delimiter and the line containing a second
delimiter is ignored by the assembler. The delimiter character is the
first nonblank character after the COMMENT directive. The text includes
the comments up to and including the line containing the next occurrence
of the delimiter.
Example
COMMENT + The plus
sign is the delimiter. The
assembler ignores the statement
following the last delimiter
+ mov ax,1 (ignored)
2.2.5 Entering Numbers in Different Bases
As with C, you can enter assembly-language constants as decimal,
hexadecimal, or octal. You can also enter binary constants. By default,
all constants are decimal, but you specify a different default with the
RADIX directive.
Hexadecimal constants appear frequently in assembly-language programs. To
indicate a hexadecimal constant, add an uppercase or lowercase H suffix.
If the first digit is one of the letters A-F, prefix the constant with a
leading 0 to indicate that the number is not a symbolic name.
Examples
100H
10FAh
0be03H
0FFh
You may often want to enter binary constants as well, particularly when
constructing bit masks. To indicate a binary constant, simply add an
uppercase or lowercase B suffix.
For more information on using different bases and using the RADIX
directive, see Section 6.1.1.2, "Setting the Default Radix."
2.2.6 Line-Continuation Character
You can create program lines that extend over more than one physical line
by using the backslash (\) as a line-continuation character. The backslash
must be the last character on the line. Comments cannot follow it. A
backslash is not considered a continuation character if it occurs in a
comment.
Example
BigProc PROC FAR \
USES DS SI DI, \
IntArg:WORD, \
String:FAR PTR BYTE, \
Ptr:FAR PTR BIGSTRUC, \
Long:DWORD
.
.
.
ret
BigProc ENDP
In this example, the line continuation-character is used to specify
multiple procedure arguments with the extended PROC syntax. All the
arguments must be placed on a single logical line, but they would go past
the edge of the editor screen if not placed on separate lines. The
continuation character is also useful for long macro calls and data
initializations.
2.3 8086-Family Instructions
The 8086-family processors support more than 80 instructions, but you
don't need to memorize the entire instruction set. Once inside the
expanded QuickC environment, you can get instant information on any
instruction. Move the cursor to an instruction keyword on the screen, then
press F1. To find the appropriate instruction for the action you want to
perform, refer to Part 3 of this book, which provides a topical survey of
instructions.
Many programs can be written with just a few of the most common
instructions. Sections 2.3.1 and 2.3.2 introduce some of these
instructions, grouping them into two sets: instructions that manipulate
data and instructions that control program flow. The programs in Chapters
3 and 4 use these same instructions to illustrate basic concepts of 8086
assembly language.
2.3.1 Data-Manipulation Instructions
The first group of instructions manipulate data. Each causes the processor
to copy data or perform a calculation at run time. Some of the simpler C
statements translate directly into a single instruction, so this section
uses C statements for illustration. Here are the six basic data-
manipulation instructions introduced in this section:
■ MOV (move data)
■ ADD (add second operand to first)
■ SUB (subtract second operand from first)
■ INC (increment operand)
■ DEC (decrement operand)
■ MUL (integer multiplication)
The processor supports a great many other data-manipulation instructions,
which are covered in Part 3 of this manual.
2.3.1.1 The MOV Instruction
The MOV instruction, probably the most frequently used 8086 instruction,
copies data from one location to another. The instruction leaves the
source data unaffected, so it is more a copy than a move. The MOV
instruction takes two operands:
MOV destination,source
The instruction copies the value of the source to the destination. It
might seem more logical to place the source operand first, until you
consider that C and BASIC assignments use the same order. For example, the
instruction
mov count,5
places the value 5 at the memory location count and thus performs the same
action as the C statement
count = 5;
The destination operand is similar to an "lvalue" in C. Instructions that
have two operands always interpret the leftmost operand as the
destination, or lvalue. The destination is the operand that the
instruction can alter; thus, it can't be a constant. Another limitation on
instructions with two operands is that the operands cannot both be memory
locations.
2.3.1.2 The ADD Instruction
The ADD instruction, like MOV, takes two operands: a destination and a
source. The processor adds the two operands together, storing the result
in the destination (on the left). This action will be familiar to C
programmers, since the instruction
add sum,10
adds 10 to the memory location sum and thus performs the same action as
the C statement
sum += 10;
The 8086 does not perform automatic scaling for pointer addition as C
does. The program itself must perform scaling for all pointer arithmetic.
2.3.1.3 The SUB Instruction
The SUB instruction is the counterpart of ADD: it subtracts the source
operand from the destination operand, storing the result in the
destination (on the left). Thus, the instruction
sub total,7
performs the same action as the C statement
total -= 7;
2.3.1.4 The INC and DEC Instructions
The INC (Increment) and DEC (Decrement) instructions add and subtract 1,
respectively. They are similar to, but faster than, ADD and SUB, and are
provided because adding and subtracting by 1 are such common operations.
The instruction
inc count
performs the same action as the C statement
count++;
2.3.1.5 The AND Instruction
The AND instruction is one of several bitwise logic operations supported
by the 8086. AND provides an efficient way to mask out bits. The
instruction
and stuff,0FFF0h
masks out the four lowest bits of stuff, as does the C statement
stuff &= 0x0FFF0;
2.3.1.6 The MUL Instruction
The MUL instruction multiplies two items, but one of these items is an
"implied operand"──that is, an operand you do not specify. For example,
the 16-bit version of the MUL instruction takes one explicit 16-bit
operand:
mul factor
The other operand is the AX register. The processor multiplies factor by
the value of AX, storing the low 16 bits of the result in AX. The
description of the AX register in Section 2.5.1, "The General-Purpose
Registers," gives more information on MUL.
2.3.2 Control-Flow Instructions
The control-flow instructions enable the program to execute loops and to
make decisions. Some of these instructions transfer control of the program
to a new address. The conditional jump instructions let you provide
program logic: they look at the result of a previous operation, and then
decide whether to jump or not. Here are the five basic control-flow
instructions introduced in this section:
■ JMP (Jump unconditionally)
■ CMP (Compare──subtract without storing result)
■ JE (Jump If Equal)
■ JA (Jump If Above)
■ JB (Jump If Below)
The processor supports a number of other control-flow instructions,
including several conditional jumps. See Section 15.1.2, "Jumping
Conditionally," for a description of these instructions.
2.3.2.1 The JMP Instruction
The JMP instruction causes the processor to jump to a new program address.
Like the C goto statement, JMP takes one operand: a label associated with
another statement. The instruction
jmp begin
jumps to the label begin, and thus performs the same action as the C
statement
goto begin;
2.3.2.2 The CMP Instruction
The CMP instruction, like SUB, performs a subtraction. But CMP doesn't
store the result; instead, it just sets processor flags in preparation for
a conditional jump (such as JE, JA, or JB).
A "processor flag" is a bit that resides in the processor and indicates
whether a specific condition is on or off. For example, the Zero flag
indicates that the result of the last operation produced zero. The JE
instruction (Jump If Equal) checks this one flag only, jumping if it is
set. Other conditional jumps determine a result by checking a combination
of flag settings. See Section 2.5.4, "The Flags Register," for a
description of all the flags.
Many instructions, including SUB, set processor flags. However, some of
these instructions have strong side effects. Use ADD or SUB to prepare for
a conditional jump when convenient. But use CMP when you need to make a
simple comparison without altering data.
2.3.2.3 The Conditional Jump Instructions
The JE, JA, and JB instructions are conditional jumps (meaning Jump On
Equal, Jump If Above, and Jump If Below, respectively). Like JMP, they
each take one argument: a program label to which to jump. Unlike JMP, they
cause the processor to jump only when certain flag settings are detected.
The result is that when you use CMP in combination with a conditional jump
instruction, you create an if-then relationship similar to an if statement
in a high-level language. Consider the following instructions:
cmp sum,10 ; Compare sum to 10
ja top ; If sum > 10, jump to top
This logic is a little different from a C program. The first instruction
makes the comparison. The second states, "If the result of the previous
instruction was above zero, then jump." Taken together, these two
instructions perform the same action as the C statement
if( sum > 10 )
goto top;
Of course, most C programmers do not use many goto statements. Typically,
you would test for a condition and execute a series of statements if the
condition is true, as in the following code:
if( sum >= 10 )
{
sum = 1;
count += 2;
delta = 5;
}
To implement this code in assembly language, test for the opposite
condition, then jump past statements if they should not be executed. For
example, the following code executes the three statements inside the if
block only if sum is greater than or equal to 10:
TopOfBlock:
cmp sum,10 ; Compare sum to 10
jb SumNotGreater ; If sum < 10, do NOT do
; next three statements
mov sum,1 ; sum = 1
add count,2 ; count = count + 2
mov delta,5 ; delta = 5
SumNotGreater:
──────────────────────────────────────────────────────────────────────────
NOTE JA (Jump If Above) and JB (Jump If Below) each work properly when
you compare unsigned integers. To compare signed integers, use JG (Jump If
Greater) and JL (Jump If Less Than). See Section 15.1.2, "Jumping
Conditionally," for a complete list of conditional jump instructions.
──────────────────────────────────────────────────────────────────────────
2.4 Declaring Simple Data Objects
This section describes how to declare global variables──often called
"static" because each corresponds to a fixed memory location.
Programs generally require data. If you wrote a program in machine code,
you'd have to reserve locations in memory for data, determine the address
of each data object, and remember these addresses whenever you operated on
memory. Fortunately, the assembler reserves memory locations for you and
associates each location with a symbolic name.
You use data directives to tell the assembler how to allocate and refer to
memory. The most common data directives for characters and integers are:
Directive Description
──────────────────────────────────────────────────────────────────────────
DB Declare byte (either a small integer or a character)
DW Declare word (2-byte integer)
DD Declare doubleword (4-byte integer)
To use these directives, place the name of the variable first, then enter
the data directive. The third column (operand field) contains one or more
initial values. Use a question mark to indicate an item with no initial
value.
aByte DB 1 ; aByte is a 1-byte integer, initialized to 1
area DW 500 ; area is a 2-byte integer, initialized to 500
population DD ? ; population is a 4-byte integer, no initial value
These directives correspond roughly to the following C statements:
char aByte = 1;
int area = 500;
long population;
Assembly data declarations are different from C declarations, however, in
that assembly data declarations are not declared signed or unsigned.
Instead, you must remember whether you intend to treat a variable as
signed or unsigned, and choose the appropriate operations.
Data directives reserve memory in the object file. They also associate
each variable with a name and a size attribute.
The assembler uses this information to correctly assemble instructions
that operate on variables. For example, at the machine-code level, the INC
instruction can be encoded to increment either a byte or a word of data.
The way the assembler encodes the instruction
inc myvar
depends on whether myvar was declared as a byte or word. (If it was
declared a doubleword, the instruction is illegal.) Another important use
of size attributes is in checking the validity of two operands. For
example, the following instruction causes the assembler to print a warning
message, because aByte and bx do not share the size attribute:
mov bx,aByte ; Move aByte into a word register
Moving a byte into a word location is not possible. After issuing the
warning, the assembler adjusts the instruction as if it were written as
follows:
mov bx,WORD PTR aByte ; Move the word at aByte to BX
The PTR operator temporarily modifies the size attribute of the object
that follows it. PTR can be used with a number of different data types, as
shown below:
Keywords Refers to
──────────────────────────────────────────────────────────────────────────
BYTE PTR object The byte at address of object
WORD PTR object The word at address of object
DWORD PTR object The doubleword at address of object
However, this adjustment may not produce the action you really want. The
PTR operator is not quite the same as a type cast in C. The C (int) type
cast manipulates data so that it represents the same value, but in a
different format. WORD PTR does no data manipulation──it simply causes the
instruction to operate on the word at the given address. In the example
above, the use of WORD PTR causes two adjacent bytes of data to be loaded
from memory into BX. If what you really want is to move a single byte of
data to BX, but convert it to a word, use the following code:
mov bl,aByte ; Lower byte of BX = aByte
sub bh,bh ; Higher byte of BX = 0
The example above only works properly when handling unsigned numbers. When
working with signed quantities, use the CBW instruction, as described in
Section 13.2.1, "Extending Signed Values."
By far the most common use of WORD PTR is in operations on objects 32 bits
or longer. An 8086 instruction can operate only on a byte or a word. You
use WORD PTR to tell the assembler to operate on one word at a time. For
example, the following code uses two moves to copy the 32-bit integer X to
a similar integer, Y:
X DD 80000 ; X is a long integer = 80,000
Y DD ? ; Y is a long integer
.
.
.
mov ax, WORD PTR X ; Move word at X to word at Y
mov WORD PTR Y, ax ; (using AX as intermediate register)
mov ax, WORD PTR X[2] ; Move word 2 bytes past X to
mov WORD PTR Y[2], ax ; word 2 bytes past Y
Brackets ([ ]) are used with arrays as well as portions of large data
objects as shown here; they also let you add a displacement to an address.
The use of brackets is further explained in the next few paragraphs.
Assembly language makes almost no distinction between simple variables and
arrays. You refer to the first element of an array just as you would a
simple variable──index brackets are optional. To declare an array or
string, just give a series of initial values:
warray DW ?,?,?,?
xarray DW 1,2,3,4
mystring DB "Hello, there."
To refer to the first element of warray, type warray into your program (no
brackets required). To refer to the next element, use either of these two
forms, each of which refers to the object two bytes past the beginning of
warray:
warray+2
warray[2]
When used with a variable name, the brackets do nothing but add a number
to the address. If warray refers to the address 2400h, then warray[2]
refers to the address 2402h. However, the brackets have an additional
function when used with registers. See Section 2.6.4, "Indirect Memory
Operands," for more information.
In assembly language, array indexes are zero-based, as in C; but unlike C,
they are unscaled. The number inside brackets always represents an
absolute distance in bytes.
In practical terms, the fact that indexes are unscaled means that if the
size of an element is larger than one byte, you must multiply the index of
the element by its size (in this case, 2), then add the result to the
address of the array. Thus, the expression warray[4] represents the third
element, which is 4 bytes past the beginning of the array. Similarly, the
expression warray[6] represents the fourth element.
In general, the numeric offset required to access an array element can be
calculated as shown in the following formula:
Nth element of Array = Array[(N-1) * size of element]
2.5 8086-Family Registers
A "register" is a special memory location inside the processor itself.
Operations on registers execute faster than operations on main memory. The
processor has a limited number of registers. Moreover, many operations on
the 8086 are impossible without the use of registers at some point. For
example, you cannot copy data between two memory locations without first
moving it into a register.
Figure 2.1 shows the registers common to all the 8086-family processors.
The 8086 registers can be grouped by function into the following sets:
general-purpose registers, index registers, pointer registers, and segment
registers. Each set corresponds to a different ending letter (X, I, P, or
S). The registers in each set are as follows:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 2.5 of the manual │
└────────────────────────────────────────────────────────────────────────┘
■ The four general-purpose registers are AX, BX, CX, and DX. These
registers exist for the general use of the program. You can use these
registers to store temporary values and perform calculations.
■ The two index registers are SI (Source Index) and DI (Destination
Index). These registers can also be used for general storage, but are
less flexible than the general-purpose registers. SI and DI have a
special purpose in string instructions.
■ The pointer registers are IP (Instruction Pointer), SP (Stack Pointer),
and BP (Base Pointer). These registers should not be confused with BX,
which is the register normally used for pointer indirection. IP, SP,
and BP each have a special purpose in conjunction with procedure calls.
SP and BP should be altered with care; IP cannot be altered or
referenced directly at all.
■ The segment registers are CS, DS, SS, and ES. This section does not
describe these registers. You generally don't alter or reference them
except when starting the program or accessing data from multiple
segments. Section 2.7, "Segmented Addressing and Segment Registers,"
describes each segment register and how it is important to programs.
In addition, there is a flags register that indicates the status of the
process.
2.5.1 The General-Purpose Registers
The general-purpose registers have many important uses in an 8086
assembly-language program, including:
■ Storing the values most frequently used. Operations on registers are
much faster than operations on memory. Therefore, place the program's
principal values in registers. In larger programs, you will probably
have too many variables to place them all into registers. You can,
however, place a value in a register while it is in heavy use.
■ Supporting operations with two or more variables. Direct
memory-to-memory operations are illegal with 8086 processors. To
operate on two memory locations, you need to first load one of the
values into a register.
■ Enabling use of all the instructions. Many instructions require the use
of a particular register. For example, the MUL instruction always works
with the AX register (or AL, if you specify a byte operand).
■ Passing or returning values in a procedure or interrupt call.
Each of the general-purpose registers──AX, BX, CX, and DX──can be accessed
as single 16-bit registers, or as two 8-bit registers. As shown in Figure
2.1, the AH, BH, CH, and DH registers represent the high-order 8 bits of
the corresponding registers. Similarly, AL, BL, CL, and DL represent the
low-order 8 bits.
This design lets you operate directly on two-byte and one-byte objects. It
also lets you load a two-byte object and then manipulate one byte at a
time.
Each of the general-purpose registers has special uses, discussed below.
2.5.1.1 The AX Register
The AX (Accumulator) register is ideal for repeated calculations. It
accumulates totals as well as the results of multiplication and division.
Using AX can add speed to your program, because some instructions have
special encodings optimized for use with AX.
Multiplication instructions always use AX. In the 16-bit version of the
MUL instruction, you specify one 16-bit value. The processor multiplies
this value by the contents of AX and stores the 16 least significant
binary digits of the result in AX. (The 16 most significant digits are
stored in DX.)
The following example multiplies base times height, and stores the result
in area. These instructions are sufficient if the result does not exceed
the limit for two-byte numbers (otherwise, the DX register will contain
the overflow):
base DW 5 ; base is a word, initialized to 5
height DW 3 ; height is a word, initialized to 3
area DW ? ; area stores 16-bit (word) product
.
.
.
mov ax,base ; AX = base
mul height ; AX = AX * height
mov area,ax ; area = result
AX has a similar use in division instructions (DIV and IDIV). See Section
14.4, "Dividing," for examples of division. Also, in port I/O
instructions, AX holds the data to write to a port and receives data read
from a port.
By convention, AX has another special use. Microsoft high-level languages
expect AX to contain a function's return value. If the return value is
longer than four bytes, the high-level languages expect DX:AX to point to
the location of the return value.
2.5.1.2 The BX Register
The BX (Base) register has great importance as a pointer or address
register. All 16-bit registers can hold addresses, but not all registers
can be used to retrieve the contents of an address. In C this operation is
called "pointer dereferencing," or "indirection." The C source code to
implement this action might look like this:
value = *pVar;
The following assembly code achieves the same effect:
mov bx,pVar ; BX = pVar
mov value,[bx] ; value = object pointed to by BX
The brackets around BX in the second instruction direct QuickAssembler to
consider BX a pointer to the actual operand. The item [bx] is an example
of an indirect memory operand. See Section 2.6.4, "Indirect Memory
Operands," for more information.
2.5.1.3 The CX Register
The CX (Count) register has special meaning to instructions with a
repeat-operation feature. The contents of CX indicate how many times to
repeat execution. Loops, string operations, certain jump instructions, and
shifts and rotates all use CX this way.
A common instruction that uses CX to repeat execution is LOOP, which is
analogous to the C for statement. This instruction subtracts one from CX,
then jumps to the given label if CX is not equal to 0. Thus, the following
loop executes 20 times:
mov cx,20
top:
.
.
.
loop top
In the case of shifts and rotates, CL (the lower byte of CX) indicates how
many bit positions to shift. See Section 14.7, "Shifting and Rotating
Bits," for more information. Also, when an instruction has a REP (repeat)
prefix, the value in CX determines how many times the instruction is
executed.
2.5.1.4 The DX Register
The DX (Data) register often is used only for storage of temporary values.
However, DX has a special function in some versions of the multiplication,
division, and port instructions. Each of these uses is closely related to
AX. In fact, DX is located next to AX in the actual physical layout of the
8086 chip. (Figure 2.1 places the registers in the order AX, BX, CX, and
DX merely for ease of reference.)
When you multiply 16-bit values with MUL, DX holds the high 16 bits of the
32-bit result. The following example is a variation of the one given for
AX. In this example, Area is a 32-bit value (a long integer), and it
stores the entire 32-bit result of the MUL instruction:
base DW 500 ; base is a word, initialized to 500
height DW 300 ; height is a word, initialized to 3
area DD ? ; area stores doubleword product
.
.
.
mov ax,base ; AX = base
mul height ; DX:AX = AX * height
mov WORD PTR area[0],ax ; Store low 16 bits
mov WORD PTR area[2],dx ; Store high 16 bits
By convention, Microsoft high-level languages use both DX and AX to return
four-byte values from procedures. The high 16 bits are placed in DX.
2.5.2 The Index Registers
The two index registers are SI (Source Index) and DI (Destination Index).
These registers are similar to the general-purpose registers, but cannot
be accessed one byte at a time. Index registers are efficient places to
store general data, pointers, array indexes, and pointers to blocks of
memory. They have the following special uses:
■ You can use both SI and DI for pointer indirection, as you can BX and
BP. "Pointer indirection" is the process of retrieving the value that a
pointer points to.
■ You can use SI or DI to hold an array index. Indirect memory operands
can combine this index with a base address stored in BX or BP.
■ You prepare for string instructions, which execute highly efficient
block operations, by loading SI with a source address and DI with a
destination address.
See Chapter 16, "Processing Strings," for information on how to use
string instructions.
When you write a procedure to be called by C, be careful to leave SI and
DI in the same state they were in before C called your procedure.
Microsoft QuickC allocates register variables in SI and DI.
2.5.3 The Pointer Registers
The pointer registers──BP, SP, and IP──are all special-purpose registers
that help implement procedure calls. The processor alters SP (Stack
Pointer) and IP (Instruction Pointer) whenever you call a procedure, and
you can use BP (Base Pointer) to access parameters placed on the stack.
Despite their names, pointer registers are not good places to store
pointer variables or other general program data; you should generally use
BX, SI, and DI for that purpose.
2.5.3.1 The BP Register
You can use BP (Base Pointer) to retrieve the contents pointed to by an
address. However, by default, the BP register points into the stack
segment rather than the data segment. Therefore, BP is typically used to
access items on the stack.
The "stack" is the area of memory that holds parameters, local variables,
and return addresses for each procedure being executed. Although you can
store general data in BP, it is commonly used to access parameters of the
current procedure.
When you use the PROC statement with a parameter list as explained in the
next chapter, avoid altering the value of BP. The PROC directive generates
instructions that set BP to point to the procedure's local stack area, and
then use BP to access parameters and local data. If BP changes, all your
references to parameters will be wrong.
To learn how to set BP yourself, see Section 15.3.3, "Passing Arguments
on the Stack," or Appendix A, "Mixed-Language Mechanics."
2.5.3.2 The SP Register
The SP (Stack Pointer) register points to the current location within the
stack segment. As you add or remove items from the stack, the processor
changes the value of SP, so that SP always points to the top of the stack.
The processor stack works like a stack of dishes: you push items onto the
top of the stack as you need to save them, then pop them off the stack
when you're ready to use them again. The stack is a last-in-first-out
mechanism. You can only remove the item currently at the top of the stack.
Items must be removed in the reverse order they were placed there.
The processor automatically pushes and pops return addresses for you when
you call or return from a procedure. A "return address" is the place a
procedure or routine returns to when done. You can also place other values
on the stack by using the PUSH and POP instructions.
The PUSH instruction saves the value of a register or memory location by
placing it on the stack. POP removes the value from the stack and places
it back in the original location. (You can also pop the contents into some
other location if you wish.) Use these instructions when you need to
preserve a value. In the following example, BX holds an important value,
but the program needs temporary use of BX:
push bx ; Save BX on the stack
mov bx,pointer ; Load pointer into BX
mov value,[bx] ; value = *pointer
pop bx ; Pop old value back into BX
The stack also holds parameters and local variables during procedure
calls. Sections 13.4.2, "Using the Stack," and 15.3.3, "Passing
Arguments on the Stack," provide more information on using the stack.
Appendix A, "Mixed-Language Mechanics," explains how to manipulate the
stack to make room for local variables──one of the few times you should
change the value of SP directly.
2.5.3.3 The IP Register
You cannot adjust the IP (Instruction Pointer) register directly; it can
only be adjusted indirectly, through control-flow instructions. For this
reason, Quick-Assembler does not even recognize IP as a keyword.
The IP register contains the address of the next instruction to execute.
The instructions that control program flow (calls, jumps, loops, and
interrupts) automatically set the instruction pointer to the proper value.
The processor pushes the address of the next instruction onto the stack
when you call a procedure. The processor pops this instruction into IP
when the procedure returns. Normally, the processor increments IP to point
to the next instruction in memory.
2.5.4 The Flags Register
The flags register, shown in Figure 2.2, is a 16-bit register made up of
bits that each indicate some specific condition. Most of the flags help
determine the behavior of conditional jump instructions. Many
instructions──most notably CMP──set these flags in a meaningful way. Other
flags (Trap, Interrupt Enable, and Direction) do not affect conditional
jump instructions but control the processor's general operation.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 2.5.4 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The nine flags common to all 8086-family processors are summarized below,
progressing from the low-order to high-order flags. In these descriptions,
the term "set" means the bit value is 1, and "cleared" means the bit value
is 0.
Instructions actively set and clear various flags. For example, if the
result of a SUB or CMP instruction is zero, it sets the Zero flag. This
flag setting can, in turn, affect subsequent instructions──in particular,
conditional jumps. Some instructions do not set the flags at all, or have
random effects on some flags. Consult on-line Help for each instruction to
see precisely how it affects flag settings.
Flag Description
──────────────────────────────────────────────────────────────────────────
Carry Is set if an operation generates a carry to or a
borrow from a destination operand. (Operation viewed
as unsigned.)
Parity Is set if the low-order bits of the result of an
operation contain an even number of set bits.
Auxiliary Carry Is set if an operation generates a carry to or a
borrow from the low-order four bits of an operand.
This flag is used for binary coded decimal arithmetic.
Zero Is set if the result of an operation is 0.
Sign Equal to the high-order bit of the result of an
operation (0 is positive, 1 is negative).
Trap If set, the processor generates a single-step
interrupt after each instruction. Debugging programs,
including the QuickC/QuickAssembler debugging
facility, use this feature to execute a program one
instruction at a time.
Interrupt Enable If set, interrupts will be recognized and acted on as
they are received. The bit can be cleared to
temporarily turn off interrupt processing.
Direction Can be set to make string operations process down from
high addresses to low addresses, or can be cleared to
make string operations process up from low addresses
to high addresses.
Overflow Is set if the result of an operation is too large or
small to fit in the destination operand. (Operation
viewed as signed.)
The Carry and Overflow flags are similar, but have one major difference:
the Carry flag is set according to the rules of unsigned operations, and
the Overflow flag is set according to the rules of signed operations. A
signed operation uses two's complement arithmetic to represent negative
numbers. One of the features of this system is that a number is negative
if the most significant bit is set. Unsigned operations do not view any
number as negative.
Thus, the same ADD operation can be viewed as adding FFFFH to FFFEH
(unsigned) or -1 to -2 (signed). This operation would set the Carry flag
(because the maximum unsigned value is FFFFH), but not the Overflow flag.
──────────────────────────────────────────────────────────────────────────
NOTE This manual does not describe the details of two's-complement
arithmetic. For more information, see one of the references listed in the
Introduction.
──────────────────────────────────────────────────────────────────────────
Each of the conditional jump instructions responds to a particular flag or
combination of flags. For example, the JZ (Jump If Zero) instruction jumps
if the Zero flag is set. The JBE (Jump If Below or Equal) jumps if either
the Zero flag or the Carry flag is set. For a description of all the
conditional jump instructions, see Section 15.1.2, "Jumping
Conditionally."
2.6 Addressing Modes
You can specify several kinds of operands: immediate, register, direct
memory, and indirect memory. Each type of operand corresponds to a
different addressing mode. The "addressing mode" is the method that the
processor uses to calculate the actual value of the operand at run time.
You don't specify addressing modes explicitly. You simply give an operand,
and the assembler determines the corresponding addressing mode.
The four types of operands are summarized below, and described at length
in the rest of this section.
Operand Type Description
──────────────────────────────────────────────────────────────────────────
Immediate A constant value contained in the instruction itself
Register A 16-bit or 8-bit register
Direct memory A fixed location in memory
Indirect memory A memory location determined at run time by using the
address stored in one or two registers
Direct memory and indirect memory operands are closely related. Syntax
displays in this manual, as well as in on-line Help, often refer to memory
operands. You can use either type of memory operand wherever memory is
specified. From the processor's viewpoint, the only difference between
these types of operands is how the address is determined. The address
specified in the memory operand is called the "effective address" of the
instruction.
Most two-operand instructions require operands of the same size. When one
of the operands is a register, QuickAssembler adjusts the size of the
other, if possible, to be the size of the register──either 8 or 16 bits.
An instruction that operates on AX and BL is illegal, since these
registers are different sizes.
If the sizes conflict, you can sometimes use the PTR operator to override
the size attribute of an operand.
Sections 2.6.1-2.6.4 discuss each of the four operand types (and
corresponding addressing modes) in detail.
2.6.1 Immediate Operands
An "immediate operand" is a constant value on which the instruction
operates directly. This is the only addressing mode that involves no
further access of registers or memory. The data follows the instruction
right inside the executable code, thus giving rise to the name
"immediate."
Use immediate operands for the same reasons you would use a literal or
symbolic constant in C. The value of an immediate operand never changes.
An immediate operand can be a symbolic constant declared with the EQU
operand. This operand is often used for the same purpose as the C #define
directive. For example, consider the constant declaration:
magic EQU 7243
You could use this the same way as the C statement:
#define magic 7243
Chapter 11, "Using Equates, Macros, and Repeat Blocks," tells more about
defining constants with the EQU or = operator.
An immediate operand can also be an expression made up of constants. For
example, the following code directs QuickAssembler to calculate the
difference between two ASCII values, then use this difference as the
source (rightmost) operand:
mov bigdiff,'a'-'A'
The assembler interprets the one-byte strings 'a' and 'A' as the ASCII
values 97 and 65. The assembler calculates the difference──in this case,
32──and places the resulting value into the object code. At run time, this
value is fixed. Each time the instruction is executed, the processor moves
the value 32 into the memory location bigdiff. This instruction is
precisely equivalent to, but more readable than, the following:
mov bigdiff,32
One-byte and two-byte strings can be immediate operands. Larger strings
cannot be processed by a single 8086 instruction. Chapter 3, "Writing
Assembly Modules for C Programs," explains how to process longer strings,
one character at a time.
The OFFSET and SEG operators turn variable names (which normally are
memory operands) into immediate operands. These operators are similar to
the address operator (&) in C. In Chapter 4, "Writing Stand-Alone
Assembly Programs," you'll see how to use the OFFSET operator to treat an
address as immediate data.
When an instruction has two operands, you cannot place immediate data in
the destination (leftmost) operand. (The OUT instruction is the one
exception.)
Examples
var DW ?
college DW 1636
nine EQU 5+4 ; Declare nine as symbolic constant
.
.
.
mov var,nine ; Move immediate data to memory
mov bx,'ab' ; Move ASCII values for 'a' and 'b'
; into BH and BL
mov college,1701 ; Move immediate data to memory
mov ax,1+2+3+4 ; Move immediate data to AX
mov ax,OFFSET var ; Move address of var to AX
int 21h ; Immediate data is single operand
; 21 hexadecimal (33 decimal)
2.6.2 Register Operands
A register operand consists of one of the 20 register names. The processor
operates directly on the data stored in the register. "Register-direct"
mode refers to the direct use of the value of the register rather than a
memory location. Registers can also be used indirectly, to point to memory
locations as described in Section 2.6.4, "Indirect Memory Operands."
Most instructions can take one or more register operands. You generally
can use any of the general-purpose registers with these instructions,
although some instructions require specific registers. The use of segment
registers (CS, DS, SS, and ES) is restricted. You can refer to segment
registers only under special circumstances.
Table 2.1 shows all the valid register names for 8086 processors. You can
use any of these names as a register-direct operand.
Table 2.1 Register Operands
Register Type Register
Name
──────────────────────────────────────────────────────────────────────────
8-bit high registers AH BH CH DH
8-bit low registers AL BL CL DL
16-bit general AX BX CX DX
purpose
16-bit pointer and SP BP SI DI
index
16-bit segment CS DS SS ES
──────────────────────────────────────────────────────────────────────────
Section 2.5, "8086-Family Registers," discusses registers in more detail.
Limitations on register use for specific instructions are discussed in
sections on the specific instructions throughout Part 3, "Using
Instructions."
Examples
mov ds,ax ; Both operands are register direct
mov stuff,dx ; Source operand is register direct
mov ax,1 ; Destination is register direct
mul bx ; Single operand, register direct
2.6.3 Direct Memory Operands
A direct memory operand specifies a fixed address in main memory
containing the data to operate on. At the machine level, a direct memory
operand is a numeric address. In your QuickAssembler source code, you
usually represent a direct memory operand by entering a symbolic name
previously declared with a data directive such as DB (Declare Bytes).
A direct memory operand is similar to a simple variable in C or an array
element with a constant index. Any object in memory can be a direct memory
operand as long as the exact location is fixed in the executable code. The
data at the location can change, but the location itself is the same each
time the processor executes the instruction. This fact gives direct memory
operands a static character. For more dynamic operations, use indirect
memory operands.
Examples
mov ax,count ; Source operand is direct memory
mov count,ax ; Destination operand is direct memory
inc total ; Single operand is direct memory
Typically, a direct memory operand is a simple label. As with immediate
operands, you can specify a direct memory operand by entering an
expression. As long as the address can be determined at assembly time, the
operand is direct memory.
──────────────────────────────────────────────────────────────────────────
NOTE Technically, a program address is not determined until link time (in
the case of near addresses) or load time (in the case of segment
addresses). These adjustments are necessary to support multiple modules
and to enable the program to run anywhere in memory. However, you can
ignore these details. If the assembler can determine the operand's address
relative to the rest of the module, the operand is direct memory.
──────────────────────────────────────────────────────────────────────────
The following example uses an expression that translates to a direct
memory operand. This example could be used to load the value of DX into
the third element of an array of bytes. QuickAssembler considers area[2]
as equivalent to area+2.
mov area[2],dx ; Move DX to memory location 2 bytes
; past the address of "area"
In the statement above, the assembler calculates an address by adding 2 to
the address of area. The resulting address will be the same no matter what
values are stored in registers. At run time, the address is fixed. Thus,
the operand is direct memory.
You can use a numeric constant as a direct memory operand. Normally,
Quick-Assembler interprets a numeric constant as an immediate operand. To
ensure interpretation as a memory operand, prefix the number with a
segment register and colon (:). Brackets are optional. The following
instructions each load AX with the contents of memory address 100
hexadecimal in the data segment:
mov ax,ds:[100h]
mov ax,ds:100h
Section 2.7, "Segmented Addressing and Segment Registers," provides more
information on segment registers and the use of the colon (:). By default,
the processor assumes that data references lie in the segment pointed to
by DS.
2.6.4 Indirect Memory Operands
With indirect memory operands, the processor calculates the address of the
data at execution time, by referring to the contents of one or two
registers. Since values in the registers can change at run time, indirect
memory operands provide the most dynamic method for accessing data.
Indirect memory operands make possible run-time operations such as pointer
indirection, dynamic indexing of array elements──including indexing of
multi-dimensional arrays──and dynamic accessing of members of a structure.
All these operations are similar to operations in high-level languages.
The major difference is that assembly language requires you to use one of
several specific registers: BX, BP, SI, and DI.
You indicate an indirect memory operand by using at least one pair of
brackets. Use of the index operator ([ ]) is explained in more detail in
Section 9.2.1.3.
When you place a register name in brackets, the processor uses the data
pointed to by the register. For example, the following instruction
accesses the data at the address contained in BX, and then moves this data
into AX:
mov ax,[bx]
When you specify more than one register, the processor adds the contents
together to determine the effective address (the address of the data to
operate on). One register must be a base register (BX or BP), and the
other must be an index register (SI or DI):
mov ax,[bx+si]
You can specify one or more displacements. A "displacement" is a constant
value to add to the effective address. A simple use of a displacement is
to add a base address to a register:
mov ax,table[si]
In the example above, the displacement table is the address of an array;
SI holds an index to an array element. (Unlike C, an assembly-language
index always indicates the distance in bytes between the beginning of the
array and the element.) Each time the instruction executes, it may load a
different element into AX. The value of SI determines which array element
to load.
Each displacement can be an address or numeric constant. If there is more
than one displacement, the assembler adds them all together at assembly
time, and places the total displacement into the executable code. For
example, in the statement
mov ax,table[bx][di]+6
both table and 6 are displacements. The assembler adds the value of table
to 6 to get the total displacement.
Table 2.2 shows the modes in which registers can be used to specify
indirect memory operands.
Table 2.2 Indirect Addressing Modes
Mode Syntax Description
──────────────────────────────────────────────────────────────────────────
Register indirect [BX] [BP] [DI] [DI] Effective address is contents
of register
──────────────────────────────────────────────────────────────────────────
Based or indexed displacement[BX] Effective address is contents
displacement[BP] of register plus displacement
displacement[DI]
displacement[SI]
──────────────────────────────────────────────────────────────────────────
Based indexed [BX][DI] [BP][DI] Effective address is contents
[BX][SI] [BP][SI] of base register plus contents
of index register
──────────────────────────────────────────────────────────────────────────
Based indexed with displacement[BX][DI] Effective address is the sum
displacement displacement[BP][DI] of base register, index
displacement[BX][SI] register, plus displacement
displacement[BP][SI]
──────────────────────────────────────────────────────────────────────────
You can enclose each register in its own pair of brackets, or you can
place the registers in the same pair of brackets separated by a plus sign
(+). The period (.) is normally used with structures, but it also
indicates addition. The following statements are equivalent:
mov ax,table[bx][di]
mov ax,table[bx+di]
mov ax,[table+bx+di]
mov ax,[bx][di].table
mov ax,[bx][di]+table
mov ax,table[di][bx]
2.7 Segmented Addressing and Segment Registers
"Segmented addressing" is the internal mechanism that enables the
processor to address up to one megabyte of main memory. This mechanism
accesses each physical memory location by combining two 16-bit addresses.
The two addresses can be represented in source code as follows:
segment:offset
The first 16-bit address is the "segment address." The second 16-bit
address is the "offset address." In effect, the segment address selects a
64K region of memory, and the offset address selects a byte within this
region. Here's how it works:
1. The processor shifts the segment address left by four places, producing
a 20-bit address ending in four zeros. This operation has the effect of
multiplying the segment address by 16.
2. The processor adds this 20-bit address to the 16-bit offset address.
The offset address is not shifted.
3. The processor uses the resulting 20-bit address, often called the
"physical address," to access an actual location in the one-megabyte
address space.
Figure 2.3 illustrates this process. The 8086-family processors were
developed to use this mechanism because 16 bits (the size of an 8086
register) can only address 64K at a time. However, the combined 20-bit
address is sufficient to address a full megabyte. Note that DOS and ROM
BIOS reserve part of this area, so that no more than 640K is available for
program addresses.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 2.7 of the manual │
└────────────────────────────────────────────────────────────────────────┘
A "segment" consists of a series of addresses that share the same segment
address, but different offsets. Segments can be no more than 64K in size.
To create large programs, you need to divide your program into multiple
segments. Even with smaller programs, it is convenient to have separate
code, data, and stack segments. (With tiny-model programs, the linker
combines these segments into a single physical segment.)
The following example helps illustrate segmented-address calculations
further. The processor calculates the address 53C2:107A by multiplying the
segment portion of the address by 16 (10H), and then adding the offset
portion, as shown below:
53C20h Segment times 10h
+ 107Ah Offset
54C9Ah Physical address
The use of segmented architecture doesn't mean that you have to specify
two addresses every time you access memory. The 8086-family processors use
four segment registers, which simplify programming in the following ways:
■ Normally, you don't specify a segment address when you access data.
Every data reference is relative to one of the four segment
registers──CS, DS, SS, or ES──so the segment address is implied.
■ Most of the time, you don't need to tell the processor which segment
register to use. By default, the processor uses CS for code addresses,
DS for data addresses, and SS for stack addresses, except where
otherwise noted in this section.
■ You initialize segment registers at the beginning of your program. Once
initialized, you can continue to use the segment addresses stored in
those registers.
If the program uses medium, large, huge, or compact model, you may need to
periodically reload one or more of the segment registers. These memory
models let you use more than 64K of code or 64K of data.
However, if the program uses small or tiny model, you never reload a
segment register except in the following situations: to access a special
hardware-defined location in memory, such as the video-display area, or to
access far memory allocated to the program by DOS function 48H.
Although each memory operand has a default segment register (usually DS,
unless the operand uses BP), you can specify another segment register by
using the segment override operator (:). The following example loads the
variable far_away residing in the segment pointed to by ES:
mov ax,es:far_away
For more information on this operator, see Section 9.2.3,
"Segment-Override Operator."
The CS Register
The processor always uses the CS (Code Segment) register as the segment
address of the next instruction to execute; IP (Instruction Pointer) holds
the offset address. CS:IP represents the full address of the next
instruction.
Near jumps and procedure calls alter the value of IP. Far jumps and
procedure calls alter both CS and IP. You never alter CS directly because
the far jump and call instructions do so automatically. Furthermore, DOS
initializes CS for you at the beginning of the program.
The DS Register
By default, the processor uses the DS (Data Segment) register as the
segment address for program data. String instructions and indirect memory
operands present some exceptions to this rule. With indirect memory
operands, the use of BP anywhere in the operand causes SS to be the
default segment register. Otherwise, DS is the default.
All the Microsoft standard memory models place the most frequently used
data in an area pointed to by DS. This area is commonly called the
"default data area," and it can be no larger than 64K. These memory models
use the ES register to access data outside the default data area. Your own
programs can either use this technique, or else reload DS whenever you
enter a new module. The standard method has the advantage of providing
fast access to the most frequently used data.
The SS Register
When the processor accesses data on the stack, it uses the SS (Stack
Segment) register as the segment register. (See the description of SP in
Section 2.5.3 for more information about the stack.) Thus, SS:SP always
points to the current stack position. Indirect memory operands involving
BP also use SS as the default segment register.
The Microsoft standard memory models set SS equal to DS. This setting
makes some programming tasks easier. In particular, it lets you address
stack or data addresses with either register. If you have to reload DS,
you can always access items in the default data area by using an SS
override.
The ES Register
The ES (Extra Segment) register is convenient for accessing data outside
of the default data area. As demonstrated in Section 3.4, "Decimal
Conversion with Far Data Pointers," you access far data by loading ES with
the desired segment address, and then giving a segment override. Section
13.3.2, "Loading Far Pointers," provides further information.
ES also plays a role in string instructions. With these instructions, the
DI (Destination Index) register is always relative to the segment address
in ES.
────────────────────────────────────────────────────────────────────────────
Chapter 3: Writing Assembly Modules for C Programs
As a C programmer, you can take advantage of the superior speed and
compactness of assembly-language routines. You can write most of your
program in C, then write time-critical routines in assembly language.
This chapter presents QuickAssembler programming techniques for
interfacing to C. You can use similar techniques to interface with other
languages. By using C with assembly language, however, you gain the
advantage of being able to develop the entire program from within the
integrated environment.
If you've read Chapter 2, read this chapter to see how to use assembly
language in a complete example module. If you skipped over Chapter 2, you
may want to refer to it occasionally for basic concepts, such as
instructions and registers.
3.1 A Skeleton for Procedure Modules
Let's start by looking at the skeleton of a module with one procedure. The
"skeleton" consists of statements that give basic structure to the module.
Within this structure, you can supply most any instructions you want.
Later sections of this chapter flesh out the skeleton by supplying useful
code.
The following skeleton assumes that the module is called by a small-model
C program, and consists of one procedure which takes a single parameter, a
pointer to a byte:
.MODEL small,c
.CODE
dectoint PROC Array:PTR BYTE
;
; (supply executable code here)
;
dectoint ENDP
END
Some features of the skeleton change when you write different procedures.
Other parts may remain the same. In particular, you'll need to add a PROC
and ENDP statement each time you add another procedure to the module.
Before looking at a full program example, let's examine each part of the
skeleton.
3.1.1 The .MODEL Directive
The .MODEL directive gives general information about the module. It uses
the following syntax:
.MODEL memorymodel [[,langtype [[,stacktype]]]]
The last two fields are optional. Commas are field separators and are only
required if you use more than one field. Usually, you'll want to enter
values in the first two fields.
The memorymodel and langtype fields correspond to the memory model and
language, respectively, of the calling module. If your C program declares
your procedure to be of type pascal or fortran, use Pascal, BASIC, or
FORTRAN in the langtype field. These keywords specify the use of the non-C
calling and naming conventions. Otherwise, specify C as the langtype.
Although the langtype field is optional, you should supply it since the
PROC features described later in this chapter require it.
Don't use the stacktype field unless the calling C program is compiled
with SS not equal to DS, in which case you should type in farStack.
(QuickC does not generate code that sets SS not equal to DS, but other
versions of Microsoft C do support this option.) The default is nearStack,
which assumes SS is equal to DS.
3.1.2 The .CODE Directive
The .CODE directive marks the beginning of the code segment, which is the
section of your program that contains the actual steps to execute:
.CODE
Statements that follow this directive are considered part of the code
segment. The segment continues to the end of the module or the next
segment directive. Typically, the code segment consists of instructions
and procedure definitions. It can also contain macro calls.
Some procedures work with static data. In Chapter 4, "Writing Stand-Alone
Assembly Programs," you'll see how to declare a data segment in which you
can place data declarations.
3.1.3 The PROC Directive
Use the PROC directive to define a procedure. The name of the procedure
appears in the first column:
dectoint PROC Array:PTR BYTE
Because the .MODEL statement specified C-language conventions, the
assembler prefixes the name dectoint with an underscore (_), and places
the name into object code as a public code label.
If your procedure alters registers that should be preserved, the optional
USES keyword automatically generates code to push the value of these
registers on the stack and pop them when the procedure returns. Procedures
called by C should not corrupt the value of SI, DI, or the segment
registers CS, DS, or SS. (The value of BP is automatically preserved.) The
following example shows how to preserve SI and DI for a procedure that
changes these registers:
dectoint PROC USES si di, Array:PTR BYTE
The last part of the statement declares one or more parameters. In this
case, the procedure declares a single parameter, Array, as a pointer to a
byte. The most common parameter types you can declare are listed below:
Declaration Meaning
──────────────────────────────────────────────────────────────────────────
WORD Word (two bytes)
DWORD Doubleword (four bytes)
PTR BYTE Pointer to a byte; most commonly, a pointer to a
character string
PTR WORD Pointer to a word; typically, the address of an array
of integers
PTR DWORD Pointer to a doubleword
For example, the following procedure definition declares a procedure named
MidStr, which takes as parameters two pointers to character strings and
one integer:
MidStr PROC Str1:PTR BYTE, Str2:PTR BYTE, Index:WORD
References to parameters are really references to locations on the stack.
C modules pass parameters by pushing them on the stack just before calling
the procedure. The BP register serves as a framepointer (a pointer to the
procedure's stack area), and each parameter is an offset from BP. The
exact offset of each parameter depends on the memory model and calling
convention, both established by the .MODEL directive.
When you use QuickAssembler procedure definitions, the assembler automates
the work of referring to parameters. Instead of setting up the
framepointer or calculating parameter offsets, you simply refer to
parameters by name. You can also use these names with debugging commands.
Appendix A, "Mixed-Language Mechanics," shows the actual code that
establishes BP as the framepointer. It also shows how to calculate
parameter offsets.
Section 6.4.3, "Procedure Labels," gives the complete syntax and rules
for using the PROC statement.
3.1.4 The ENDP and END Statements
The module ends with two statements: ENDP, which declares the end of a
procedure, and END, which declares the end of the module:
dectoint ENDP
END
You can place any number of procedures in the same module. Each time you
end a procedure, use ENDP. However, END should only occur once, at the end
of the module.
3.2 Instructions Used in This Chapter
The instructions below were introduced in Chapter 2, "Introducing 8086
Assembly Language." They are summarized here briefly for review. The first
group of instructions manipulates data:
Instruction Description
──────────────────────────────────────────────────────────────────────────
MOV destination, source Copies value of source to destination
ADD destination, source Adds source to destination, storing result in
destination
SUB destination, source Subtracts source from destination, storing
result in destination
INC destination Increment──adds 1 to destination
DEC destination Decrement──subtracts 1 from destination
MUL source Multiplies source by AX (if operand is 16 bits),
storing high 16 bits in DX and low 16 bits in AX
The second group of instructions controls the flow of program execution:
Instruction Description
──────────────────────────────────────────────────────────────────────────
CMP destination, Compare──subtracts source from destination, ignoring
source result but setting processor flags appropriately
JE label Jumps to label if result of last operation was equal
to zero
JAE label Jumps to label if result of last operation was equal
to or above zero (unsigned operations)
JMP label Jumps unconditionally to label
3.3 Decimal Conversion Example
This section uses a decimal-conversion example to illustrate the use of
some basic instructions and directives. It features an assembly module
that takes a pointer to a null-terminated string of characters as input
and returns an unsigned integer value. This chapter assumes that the value
is unsigned.
You can compute the value of a decimal string by multiplying each digit by
a power of 10:
2035 = 2 x 10 cubed + 0 x 10 squared + 3 x 10 + 5
One way to calculate the value of the number is to calculate each power of
10 separately, then multiply each digit by the corresponding power. For
example, you can calculate 10 cubed, and then multiply by 2.
A much more efficient algorithm combines the calculations for powers of
10. The algorithm adds each digit to a running total, then multiplies the
total by 10 after every digit but the last. The following pseudo-code
represents this algorithm, and assumes that the first character in the
string is the most significant digit:
initialize total to 0
while there's another digit
add value of digit to total
advance to next digit
if no more digits
we're done
else
multiply total by 10
A simple C program that calls the procedure might look like this:
extern unsigned int dectoint( char * );
main()
{
char digits[81];
gets( digits );
printf( "Numeric value is: %d", dectoint( digits ) );
}
The procedure itself could be written in C as:
unsigned int dectoint( char *Array)
{
unsigned int total = 0; /* Initialize total */
while( *Array != '\0' ) /* While there's another digit
{
total += *Array - '0'; /* Add value to total */
Array++; /* Advance to next digit */
if( *Array == '\0' ) /* If no more digits, */
break; /* we're done */
total *= 10; /* Else, multiply by 10 */
}
return( total );
}
This chapter shows how to write the same procedure in assembly language.
The assembly-language version will be faster because it can make strategic
use of registers and choose optimal instructions. You can write a main
module with C code, place the assembly routine in a separate module with a
.ASM extension, then link them together by creating a program list.
──────────────────────────────────────────────────────────────────────────
NOTE You can build mixed-language programs by placing both .C and .ASM
files in a program list. Place the main module first. In the Assembler
Flags dialog box, make sure that you select either Preserve Case or
Preserve Extrn (the default). From the QCL command line, use the /Cl
(preserve case) or /Cx (preserve case of external symbols) option. QC
calls the linker with case sensitivity on, so C and assembler symbols must
match exactly.
──────────────────────────────────────────────────────────────────────────
Before writing the assembly procedure, we first need to develop a strategy
for using registers.
The AX (Accumulator) register is ideal for keeping the running total. The
algorithm changes this total through both addition and multiplication. The
MUL instruction requires the use of AX. By keeping the total in AX at all
times, the procedure avoids having to constantly reload this register.
The BX register should be used to access the individual digits. The
procedure receives the address of the digit string, and then retrieves
each ASCII byte through pointer indirection. BX is one of the few
registers that supports this operation. SI and DI could also be used this
way, but C-generated code requires that SI and DI be preserved. BX can be
freely altered.
The procedure needs to allocate two more registers: one for holding the
multiplication factor (10), and another for adjusting the binary value of
the digit. The procedure uses CX and DX for these purposes. In this case,
CX and DX are interchangeable. However, we use CX for multiplication now,
because in the hex conversion example, CX will be needed for a special
kind of multiplication──shifting bits. We use DX as an intermediate
location to receive a byte and then add a word to AX.
The complete assembly-language module is shown below:
.MODEL small,c
.CODE
dectoint PROC Array:PTR BYTE
sub ax,ax ; ax = 0
mov bx,Array ; bx = Array
mov cx,10 ; factor = CX = 10
sub dx,dx ; dx = 0
cmp BYTE PTR [bx],0 ; Compare byte to NULL
je done ; If byte=0 we're done
top:
mov dl,BYTE PTR [bx] ; Get next digit
sub dl,'0' ; Convert numeral
add ax,dx ; Add to total
inc bx ; Point to next byte
cmp BYTE PTR [bx],0 ; Compare byte to NULL
je done ; If byte=0 we're done
mul cx ; AX = AX * 10
jmp SHORT top ; Goto top of loop
done:
ret ; Exit procedure
dectoint ENDP
END
We'll examine each section of the module in turn. The first three
statements are directives that form part of the module's skeleton. The
PROC directive, when used with one or more parameters as it is here,
generates code to set the framepointer (BP) properly so that you can
access parameters.
.MODEL small,c
.CODE
dectoint PROC Array:PTR BYTE
The rest of the module consists of instructions──the actual core of the
program. The first four instructions initialize the registers AX, BX, CX,
and DX. Note that when initializing a register to 0, the procedure uses
SUB in preference to MOV. Any value subtracted from itself leaves zero in
the destination operand. Although the result is the same, the SUB
instruction is smaller and faster because it involves no immediate data.
sub ax,ax ; ax = 0
mov bx,Array ; bx = Array
mov cx,10 ; factor = CX = 10
sub dx,dx ; dx = 0
The next two instructions handle a special case──that of a string
containing no digits at all. Recall that the procedure is passed a
null-terminated string. The operand BYTE PTR [bx] is a memory operand
referring to the byte pointed to by BX. If the string is empty, Array
points to a null byte. The two instructions test for a 0 (null) value and
jump to the end of the procedure if 0 is detected:
cmp BYTE PTR [bx],0 ; Compare byte to NULL
je done ; If byte=0 we're done
In the CMP instruction above, the BYTE PTR operator is strictly required,
because otherwise the assembler would have no way of knowing whether to
compare 0 to the byte or a word pointed to by BX. However, when one of the
operands is a register (as is the case with the MOV instruction below),
the BYTE PTR operator is optional.
The next eight instructions consist of a loop executed once for every
digit character in the string. The label top indicates the top of the
loop, and the first three instructions add the value of the digit to AX:
top:
mov dl,BYTE PTR [bx] ; Get next digit
sub dl,'0' ; Convert numeral
add ax,dx ; Add to total
The first instruction above retrieves the digit. The next instruction
converts the digit's ASCII value to the numeric value by subtracting the
value of the character '0' (48 decimal). This statement works because the
ASCII character set places all digit characters in sequence from 0 to 9.
Finally, the procedure adds the resulting value to the running total
stored in AX. Note that the operands in each case are the same size. The
first two instructions above access DL, the low byte of DX.
The next three instructions advance to the next byte in the string, and
test it for equality to zero. Getting the next byte is just a matter of
adding the value 1 to BX (with the INC instruction), so that BX points to
the next byte. The other two instructions are identical to previous
instructions that tested for zero value.
inc bx ; Point to next byte
cmp BYTE PTR [bx],0 ; Compare byte to NULL
je done ; If byte=0 we're done
If the next byte is a null byte, the processor jumps to the end of the
program. Otherwise, the processor continues executing the bottom of the
loop, which multiplies the current total by 10 (stored in CX), and then
jumps to the top:
mul CX ; AX = AX * 10
jmp SHORT top ; Goto top of loop
Notice the operator SHORT used with the jmp instruction. This optional
operator makes the encoded instruction smaller and faster, but it can be
used only if the destination of the jump is less than 128 bytes away.
SHORT is explained in more detail in Section 9.2.4.2.
The loop is now complete. The rest of the module exits and marks the end
of the segment and the module. The RET statement causes the assembler to
generate instructions to do the following: restore the stack, restore the
framepointer (BP), and return properly for the memory model (small) and
calling convention (C).
done:
ret ; Exit procedure
dectoint ENDP
END
Microsoft high-level languages always look for function return values in
AX, if two bytes long, or in DX and AX, if four bytes long. If the return
value is longer than four bytes, DX:AX points to the value returned. If
the return value is one byte, AL contains the value.
The C module that calls this procedure looks in AX for the return
value──as does all high-level-language code that calls a function
returning a two-byte value. In this case, AX already contains the results
of the calculation. No further action is required.
3.4 Decimal Conversion with Far Data Pointers
This section uses the same basic algorithm introduced in the last section,
but presents coding techniques for different memory models.
The .MODEL directive resolves all differences in the size of code
addresses. However, when you use memory models that use far data pointers
(compact, large, and huge), you must make some additional adjustments.
The program below shows the module rewritten for large memory model. This
example works for compact model if large in the first line is replaced
with compact.
.MODEL large,c
.CODE
dectoint PROC USES ds, Array:PTR BYTE
sub ax,ax ; ax = 0
lds bx,Array ; ds:bx = Array
mov cx,10 ; factor = CX = 10
sub dx,dx ; dx = 0
cmp BYTE PTR [bx],0 ; Compare byte to NULL
je done ; If byte=0 we're done
top:
mov dl,BYTE PTR [bx] ; Get next digit
sub dl,'0' ; Convert numeral
add ax,dx ; Add to total
inc bx ; Point to next byte
cmp BYTE PTR [bx],0 ; Compare byte to NULL
je done ; If byte=0 we're done
mul cx ; AX = AX * 10
jmp SHORT top ; Goto top of loop
done:
ret ; Exit procedure
dectoint ENDP
END
This procedure is the same as the one in the last section, except for two
lines. The PROC directive now includes a USES clause, and the LDS
instruction replaces the first MOV instruction.
The procedure loads the DS register with the segment address of Array,
thus causing subsequent data references to be relative to the new segment
address. However, procedures called from C must preserve DS. The PROC
statement, therefore, includes USES ds, which generates code to place DS
on the stack.
The LDS instruction (Load Data Segment) does the actual loading of the DS
register. This instruction is similar to the MOV instruction:
mov bx,Array ; bx = Array
; 2-byte data pointer
lds bx,Array ; ds:bx = Array
; 4-byte data pointer
The LDS instruction accomplishes two moves. First, it loads the offset
portion of the pointer into the specified register (BX). Second, it loads
the segment portion of the pointer into DS.
──────────────────────────────────────────────────────────────────────────
NOTE For the LDS and LES instructions to work properly, the segment
portion must be stored in the upper word of the four-byte (far) pointer. C
meets this requirement by always pushing the segment portion of the
pointer on the stack first. (The stack grows downward.) In your own
programs, you declare far pointers with the DD directive. You initialize
them by loading a segment address into the upper word of the pointer
variable and an offset address into the lower word.
──────────────────────────────────────────────────────────────────────────
3.4.1 Writing a Model-Independent Procedure
In the case of this procedure, the use of the LDS instruction is most
convenient. Once DS is loaded with the new segment address, all subsequent
memory references are automatically correct. No further adjustments are
needed.
The simplicity of this technique makes it easy to write a module that is
completely independent of memory models. This module can then be linked
with any C program. To adjust memory model, you simply change the .MODEL
directive, and recompile. In fact, the memory model itself can even be
specified with a compile flag so that source code never need change.
The model-independent version contains only a few lines different from the
previous example:
% .MODEL mem,c
.CODE
dectoint PROC USES ds, Array:PTR BYTE
sub ax,ax ; ax = 0
IF @DataSize
lds bx,Array ; ds:bx = Array
ELSE
mov bx,Array ; bx = Array
ENDIF
The .MODEL directive operates on an undefined variable, mem. You define
this variable on the QCL command line or in the Assembler Flags dialog
box. For example, to assemble with QCL in compact model, enter the
following text in the defines text box:
/Dmem=compact
The IF, ELSE, and ENDIF directives cause conditional assembly. The
@DataSize predefined macro is equal to 1 (true) if the memory model uses
far data pointers, and 0 (false) otherwise. The statement IF @DataSize
begins a conditional-assembly block that assembles the LDS instruction if
the memory model uses far data pointers; it assembles the MOV instruction
otherwise.
For more information on conditional assembly, see Chapter 10, "Assembling
Conditionally."
The USES clause is retained for all memory models, since even with small
model it does no harm. However, to increase efficiency, you may wish to
include the PROC statement inside conditional-assembly blocks.
3.4.2 Accessing Far Data through ES
The LDS instruction is inconvenient if you need to access items in the
default data segment, because you have no guarantee that DS still points
to that area of memory. Therefore, it's sometimes more efficient to leave
DS alone and use the ES register to access far data.
The standard C memory models all use the LES instruction to access far
data. You can also use this method, but it is not required, since it has
no effect on the interface between modules. Give the LES instruction to
load a far data pointer, which will load the ES register with the new
segment address. Then give the ES override whenever you refer to data in
the far segment. This method requires alteration of all instructions that
access the string data:
les bx,Array ; es:bx = Array
.
.
.
cmp es:BYTE PTR [bx],0 ; Compare byte to NULL
Once ES is loaded with the segment address of far data, access objects in
the default data area (the segment containing near data) as you normally
would. Use the ES override to access the far data.
3.5 Hexadecimal Conversion Example
The following example builds on the decimal example in Section 3.3,
adding the additional logic needed to convert hexadecimal rather than
decimal strings.
Hexadecimal conversion can use an algorithm similar to the one used
earlier for decimal conversion, with these adjustments made:
■ The procedure multiplies the running total by 16, not 10.
■ The procedure converts the letters A-F to numeric values, in addition
to converting the numerals 0-9.
You could make the first adjustment by loading CX with 16 instead of 10. A
much more efficient method is to use the SHL (Shift Left) instruction to
shift an object's bits left by four places. This effectively multiplies
the object by 16.
The second adjustment requires more complex logic. Hexadecimal digits can
consist of either letters or numerals. The procedure must consider three
different cases──one for each sequence of hexadecimal characters:
Range of Characters Conversion Required
──────────────────────────────────────────────────────────────────────────
0-9 Convert to face value. Subtract ASCII value of '0'.
A-F, and a-f Convert to values 10-15. Convert all letters to
uppercase, then subtract ASCII value of 'A' and add
10.
We convert all letters to uppercase in an optimized fashion by taking
advantage of the ASCII coding sequence. Uppercase letters are coded as 41H
onward. Lowercase letters are coded as 61H onward. Consequently, each
lowercase letter differs from the corresponding uppercase letter by
exactly one bit. We use the AND instruction, with the immediate operand
0DFH, to mask out this bit. This operation has the effect of setting the
third highest bit to 0.
0110 0001 61h = 'a' 0100 0001 41h = 'A'
AND 1101 1111 DFh 1101 1111 DFh
====================== ======================
result 0100 0001 41h = 'A' 0100 0001 41h = 'A'
0110 0010 62h = 'b' 0100 0010 42h = 'B'
AND 1101 1111 DFh 1101 1111 DFh
====================== ======================
result 0100 0010 42h = 'B' 0100 0010 42h = 'B'
The beauty of the operation is that it converts lowercase letters to
uppercase, but leaves uppercase letters alone. If the third highest bit is
already 0 (as is the case with uppercase letters), doing an AND operation
with 0DFH has no effect. This operation removes the need to handle
lowercase letters as a separate case.
The revised algorithm does the following:
initialize total to zero
while there's another digit
move byte to temporary location
if ascii value < 'A'
Subtract '0'
else
Convert lowercase to uppercase
Subtract 'A'-10
add byte value to total
advance to next digit
if no more digits
we're done
else
shift total left by four bits
The assembly-language code below implements this algorithm. The code tests
for each range, performing a different conversion for each case. Note the
use of JB (Jump If Below), which jumps to the specified label if the
previous comparison or subtraction produced a negative value──that is, if
the first operand is less than the second.
.MODEL small,c
.CODE
hextoint PROC Array:PTR BYTE
sub ax,ax ; ax = 0
mov bx,Array ; bx = Array
mov cl,4 ; Prepare to shift left by 4
sub dx,dx ; dx = 0
cmp BYTE PTR [bx],0 ; Compare byte to NULL
je done ; if byte=0 we're done
top:
mov dl,BYTE PTR [bx] ; Move byte to DL
cmp dl,'A' ; ASCII value >= 'A'?
jae isletter ; If so, goto isletter
sub dl,'0' ; Convert ascii to numeric
jmp addbyte ; Go add value of byte
isletter:
and dl,0DFh ; Convert to uppercase
sub dl,'A'-10 ; Convert ascii to numeric
addbyte:
add ax,dx ; Add value to total
inc bx ; Point to next byte
cmp BYTE PTR [bx],0 ; Compare byte to NULL
je done ; If byte=0 we're done
shl ax,cl ; AX = AX * 16
jmp SHORT top ; Goto top of loop
done:
ret
hextoint ENDP
END
The beginning of the procedure initializes the CL register to 4. This step
is necessary, because you can use the SHL instruction (Shift Left) in only
two ways: you can shift by exactly one bit, or you can shift by the number
of places indicated in CL. Clearly, using CL is more efficient than a
sequence of four shift instructions.
The main loop reads a character, tests it, and makes one basic decision:
is the character a letter or not? This test takes advantage of the ASCII
coding sequence. If the value of the character is equal to or greater than
'A', it cannot be one of the digits 0-9. The procedure uses the JAE
instruction (Jump If Above or Equal) to test for this condition.
top:
mov dl,BYTE PTR [bx] ; Move byte to DL
cmp dl,'a' ; ASCII value >= 'A'?
jae isletter ; If so, goto isletter
If the character is a letter, the procedure first converts the letter to
uppercase──using an AND instruction that converts lowercase letters but
leaves uppercase letters unchanged. The following instruction can then
properly handle all letters the same way, regardless of their original
case:
isletter:
and dl,0DFh ; Convert to uppercase
sub dl,'A'-10 ; Convert ascii to numeric
For simplicity, the procedure accepts invalid letters. You could easily
enhance it to verify that the letters are hexadecimal.
────────────────────────────────────────────────────────────────────────────
Chapter 4: Writing Stand-Alone Assembly Programs
With QuickAssembler, you can write stand-alone assembly programs to
produce small, efficient utilities. For example, you might write a utility
in assembly language to count the number of lines or paragraphs in a file.
These programs start and end with assembly code and generally do not
involve any links to high-level languages.
Stand-alone assembly programs can yield remarkably small .EXE files. They
require relatively little space, because they do not include the start-up
code for a high-level language. And often you can make your assembly
program even smaller by converting it to a .COM file as shown in this
chapter. Some useful .COM files take up less than 100 bytes of memory.
This chapter first describes the directives you need to write stand-alone
assembly programs, reviews instructions used in the chapter's examples,
and then presents a simple stand-alone program. Next, Sections 4.4-4.6
look closely at each segment of the program: stack, data, and code.
Finally, the chapter describes how to create a program in the .COM format.
4.1 A Skeleton for Stand-Alone Programs
This chapter uses the simplified segment directives described in the
previous chapter, and introduces three more directives──.STACK, .DATA, and
.STARTUP. The simplified segment directives produce programs using the
Microsoft standard segment format.
This format is not required, since your stand-alone program need not be
compatible with a high-level-language module. However, the standard format
is convenient because you can specify a number of different memory models,
and you are freed from having to specify segment names, attributes, and
register assumptions.
──────────────────────────────────────────────────────────────────────────
NOTE Occasionally, you may need a customized segment structure. Linking
assembly code to a non-Microsoft language is the most common situation
that requires customized segments. QuickAssembler lets you use full
segment definitions any time you need to customize segments. However, you
should find that simplified segment directives support the vast majority
of assembly-language programming you do──even when you write .COM files.
──────────────────────────────────────────────────────────────────────────
The skeleton for the programs in this chapter includes a stack, data, and
code segment. Note that one of the directives, .MODEL, will change when
you alter the memory model. The other statements remain the same.
.MODEL small ; Use small memory model
.STACK 100h ; Declare 256-byte stack
.DATA
;
; (place data declarations here)
;
.CODE
.STARTUP ; Set up DS, SS, and SP registers
;
; (place executable code here)
;
END
Sections 4.1.1-4.1.3 examine each of the statements in this skeleton more
closely.
4.1.1 The .MODEL Directive
The .MODEL directive performs the same role that it did in the previous
chapter; it defines the overall attributes of the module. Note, however,
that with a stand-alone program, a language type is not always required. A
language type is useful when a module contains one or more procedures.
Otherwise, you need only type .MODEL followed by a memory model:
.MODEL small ; Use small memory model
The memory model can be TINY, SMALL, MEDIUM, COMPACT, LARGE, or HUGE. Most
of these memory models may be familiar to you if you have used QuickC. For
a complete description of each memory model, see Section 5.1.1.
The TINY memory model is new; it alone results in the creation of a .COM
file rather than a .EXE file. Section 4.8, "Creating .COM Files," gives a
complete example featuring the use of tiny memory model.
Generally, to change memory model you change the .MODEL directive. You
also change the way you load and use data pointers, as described in
Chapter 3, "Writing Assembly Modules for C Programs." With these changes
made, many programs can readily be reassembled for a new memory model.
(However, as you'll see in Chapter 5, "Defining Segment Structure," you
cannot use .FARDATA segments in tiny, small, or medium model, and this may
require further revision of code in some cases.)
4.1.2 The .STACK, .CODE, and .DATA Directives
Each of the segment directives──.STACK, .CODE, and .DATA──declares the
beginning of a segment.
The code and data segments begin with .CODE and .DATA, respectively. Each
of these segments continues to the next segment directive or the end of
the program. The data segment contains data and symbolic constant
declarations. The code segment contains instructions.
However, the stack segment consists of only one line:
.STACK [[size]]
By default, QuickAssembler interprets size according to the current radix,
which by default is decimal. You can specify a hexadecimal constant by
using the H suffix. (Example: 200h.) The size argument is optional. If you
leave it out, the assembler creates a stack 1024 bytes long.
Unless the program is written in tiny memory model, you should always
declare a stack segment in your main module. Section 4.4, "Inside the
Stack Segment," explains the purpose of this segment.
4.1.3 The .STARTUP Directive
Unlike C programs, assembly-language programs have to initialize register
values. Specifically, the program has to initialize DS, the Data Segment
register; CS and IP, which point to the first instruction to execute; and
SS and SP, the stack registers.
By far the easiest way to initialize all these registers is to just
include .STARTUP, a simple directive that takes no arguments:
.STARTUP ; Set up DS, SS, and SP registers
When you use this directive, the assembler generates code to initialize
your registers the way Microsoft high-level languages do. The generated
code is similar to some of the instructions in the C start-up code. The
directive takes care of minimal start-up, but many programs will need to
do additional start-up tasks, such as releasing unused memory.
──────────────────────────────────────────────────────────────────────────
NOTE The start-up sequence adjusts SS and SP so that SS is equal to DS.
This starting condition gives you some advantages. If you later have to
alter the value of DS, you can always access a data object as an indirect
operand using BP, or through an SS segment override. To avoid this
starting sequence, so that the stack and data are separate physical
segments, use the farStack keyword with the .MODEL directive, as described
in Section 5.1.3.
──────────────────────────────────────────────────────────────────────────
4.2 Instructions Used in This Chapter
This section summarizes the instructions used in this chapter. Because the
program examples are simple, only a very few of the 80-odd instructions of
the 8086 are featured here.
This chapter features four instructions:
Instruction Description
──────────────────────────────────────────────────────────────────────────
MOV destination, Moves source to destination
source
INT number Generates the indicated interrupt signal, causing
processor to call a memory-resident interrupt routine
DEC destination Decrement──subtracts 1 from destination
JNZ label Jump If Not Zero──jumps to label if result of last
operation was not zero
Most of the instructions above were introduced in Chapter 2, "Introducing
8086 Assembly Language." The new instruction is INT.
The INT instruction generates a software interrupt signal, causing the
processor to call an interrupt service routine usually residing in a DOS
or ROM-BIOS memory area. This call is much like a procedure call; the
processor executes a specific function and returns to the program when the
routine is complete.
There are two major differences between an interrupt call and a procedure
call. First, instead of calling a procedure you have written, an INT
instruction calls a DOS system routine or ROM-BIOS service. These
low-level routines carry out a variety of basic operations, such as
reading the keyboard, writing to the screen, or using the file system.
Most DOS services are accessed through interrupt 21H (33 decimal).
The second major difference is syntactic. You follow the INT keyword by an
interrupt number (in the range 0 to 255), rather than a procedure name. In
many cases, you further specify the interrupt routine by loading AH with a
function number.
4.3 A Program That Says Hello
The following sample program prints Hello world and then successfully
exits back to DOS. You can use this program as a template and insert your
own code and data.
.MODEL small ; Use small model
.STACK 100h ; Allocate 256-byte stack
.DATA
message DB "Hello, world.",13,10 ; Message to print
lmessage EQU $ - message ; Determine length of message
.CODE
.STARTUP ; Use standard startup code
mov bx,1 ; Load 1 - file handle
; for standard output
mov cx,lmessage ; Load length of message
mov dx,OFFSET message ; Load address of message
mov ah,40h ; Load no. of DOS Write function
int 21h ; Call interrupt 21H (DOS)
mov ax,4c00h ; Load no. of DOS Exit function
; in AH, and 0 exit code in AL
int 21h ; Call interrupt 21H (DOS)
END
The first statement determines the memory model of the program:
.MODEL small ; Use small model
This statement specifies small memory model, which places code and data in
two separate segments, each of which cannot exceed 64K.
The next few sections consider the rest of this program──stack, data, and
code.
4.4 Inside the Stack Segment
The stack segment is the easiest to create, because with simplified
segment directives you enter only one statement:
.STACK 100h ; Allocate 256-byte stack
Each processor or interrupt call uses up stack space. The stack stores
return addresses, parameters, and local variables for each procedure
called. When a procedure or interrupt routine returns, the stack space it
used is restored. The more procedure calls your program makes without
returning, the more stack area it requires. Programs that nest many
procedures or use recursion (in which a procedure calls itself repeatedly)
may require large stacks. Unfortunately, there is no formula for
determining how large a stack is needed.
A 256-byte stack (100 hexadecimal) is adequate for most small programs.
For this sample program, which makes one interrupt call but no procedure
calls, 256 bytes provides an ample margin of error.
You can also create a stack by using full segment definitions. See Section
5.2, "Full Segment Definitions," for more information.
4.5 Inside the Data Segment
A single keyword declares the beginning of the segment:
.DATA
QuickAssembler considers all statements following this line to lie in the
data segment, up until the next segment declaration or END directive. The
END directive marks the end of the source file.
The next two statements are directives that declare a string of characters
and a symbolic constant:
message DB "Hello, world.",13,10 ; Message to print
lmessage EQU $ - message ; Determine length of message
The first statement above declares a series of bytes. The label message is
a symbolic name that QuickAssembler associates with the string's starting
address.
The assembler allocates 15 bytes in the data segment, and initializes
these bytes to the ASCII values for H, e, l, l, o, and so forth. The
values 13 and 10 indicate a carriage return and line feed, respectively,
causing the program to move the cursor to the beginning of the next line
when it prints the string.
The second directive in the data segment declares a symbolic constant
equal to the length of the string:
lmessage EQU $ - message ; Determine length of message
Again, the item in the first column, lmessage, is the label of the
statement. The EQU directive equates the label with the value of the
operand itself. EQU does not allocate memory.
The operand field contains $ - message, which in this case equals 15. We
could just as easily have entered 15 in the operand field. However, the
item $ - message is guaranteed to be equal to the length of the string,
even if you later rewrite the initial string value.
The dollar sign ($) is the "location counter," which represents the
current address of the statement. QuickAssembler translates the full
expression as "Take the current address ($) and subtract the address of
message." The current address is one byte after the end of the string.
Thus, $ - message is automatically equal to the length of the string.
4.6 Inside the Code Segment
A single keyword declares the beginning of the code segment:
.CODE
The code segment consists of all statements between .CODE and the END
statement, which marks the end of the source code. In this example, all
the statements in the code segment, aside from .STARTUP, are instructions.
The program has three basic tasks. Each instruction helps carry out one of
these operations:
1. Initialize registers
2. Call a DOS function to print the message
3. Call a DOS function to exit the program gracefully
The .STARTUP directive initializes registers. If you write a main module
without this directive, you must explicitly initialize DS, CS, and IP.
Furthermore, if you want SS to equal DS (which gives some programming
advantages), you must adjust both SS and SP.
To see how to initialize registers without the use of .STARTUP, see
Chapter 5, "Defining Segment Structure."
After registers are initialized, a series of five instructions makes the
call to DOS that prints the message:
mov bx,1 ; Load 1 - file handle for
; standard output
mov cx,lmessage ; Load length of message
mov dx,OFFSET message ; Load address of message
mov ah,40h ; Load no. of DOS Write function
int 21h ; Call interrupt 21H (DOS)
The first four instructions prepare for the DOS call. Interrupt calls
generally use registers to receive parameters. Unlike procedure calls,
they do not reference the stack for this information. The DOS Write
function uses the following registers to receive data:
Register Data
──────────────────────────────────────────────────────────────────────────
AH Selects the DOS function. 40H is the Write function.
BX File handle to which to write. The number 1 is a
reserved file handle that always corresponds to
standard output. "Standard output" is normally
synonymous with the computer screen, unless you
redirect program output. If you were writing to a
file, you would first open the file and use the file
handle returned by the DOS open-file function.
CX Length of the message. The second statement in the
data segment determined this length.
DS:DX The beginning address of the actual message text.
Remember that DS was loaded earlier with the address
of the data segment, so it does not need to be
reloaded now.
This procedure uses the OFFSET operator to load DX with the address of the
message. Although variables are translated to addresses, the processor
normally interprets a variable address as a memory operand──that is, the
processor operates on the data at the address, not the address itself.
The OFFSET operator extracts the offset portion of the address and turns
it into an immediate operand. If the OFFSET operator was not used the DOS
routine would not receive the address of message, but would instead
receive the value of the first byte. The OFFSET operator is similar to the
address operator (&) in C. Use it whenever you need to pass an address
rather than a value.
After the interrupt service returns, the AX register contains the number
of bytes written. The programs in this chapter do not use this return
value, but a more sophisticated program might. In particular, if AX
(number of bytes written) is less than CX (number of bytes requested to be
written), then an error has occurred.
Each DOS function has its own conventions for receiving data in different
registers. Consult the Microsoft MS-DOS Programmer's Reference for a
complete description of each function. The Assembler Contents selection
from the Help menu also describes the major DOS functions.
──────────────────────────────────────────────────────────────────────────
NOTE Each DOS function has conventions for getting and returning values
in registers and flags. Bear in mind that values placed in any of these
registers may change. If you need to preserve register values before
making a DOS call, use the PUSH and POP instructions. See Section 13.4.1,
"Pushing and Popping," for more information on how to preserve register
values.
──────────────────────────────────────────────────────────────────────────
The INT instruction makes the actual call to DOS. The interrupt number for
the majority of DOS functions is 21H. You use different interrupt numbers
to call ROM-BIOS services.
The final two instructions cause the program to terminate operation and
return control to DOS. High-level language programmers can ignore the need
to exit a program explicitly, if they like. But when you write a
stand-alone assembly program, you don't have this luxury. The program must
exit explicitly. Otherwise, the processor continues to execute random
instructions after the end of the program, making the system appear to
crash.
The DOS Exit function (service 4CH) is the preferred method for exiting
back to DOS. This function uses two register values:
Register Data
──────────────────────────────────────────────────────────────────────────
AH Selects the DOS function. 4CH is the Exit function.
AL Exit code. Batch files can use this exit code as an
"errorlevel" indicator. An exit code of 0 usually
indicates no error.
A single instruction loads both registers:
mov ax,4c00h ; Load number of DOS Exit func
; in AH, and 0 exit code in
A single MOV instruction actually moves data into two registers──AH and
AL. AH is loaded with 4CH, the function number for the DOS exit function,
and AL is loaded with 0, an exit code indicating no error.
Finally, another INT instruction calls DOS.
int 21h ; Call interrupt 21H (DOS)
4.7 Making the Program Repeat Itself
Once you understand the template for writing stand-alone programs, you can
alter the sample program given above and generate your own code. This
section alters the sample program so that it prints out a different
message, and prints it ten times.
The new sample program is listed below:
.MODEL small ; Use small model
.STACK 100h ; Allocate 256-byte stack
.DATA
message DB "Hello, ten times.",13,10 ; Message to print
lmessage EQU $ - message ; Determine length of message
count DW 10
.CODE
.STARTUP ; Use standard startup code
mov bx,1 ; Load 1 - file handle for
; standard output
mov cx,lmessage ; Load length of message
mov dx,OFFSET message ; Load address of message
printit: mov ah,40h ; Load no. of DOS Write functi
int 21h ; Call interrupt 21H (DOS)
dec count ; count = count-1
jnz printit ; if count > 0, print again
mov ax,4c00h ; Load DOS 4C function number
; in AH, and 0 exit code in
int 21h ; Call interrupt 21H (DOS)
END
Note the following changes:
■ The string data is different.
■ The data segment includes a new variable, count.
■ One of the instructions is now labeled printit.
■ Two additional instructions decrement count, then loop back to the
label printit if count is greater than zero.
The string data is longer than before, and QuickAssembler must allocate
more bytes than in the previous version of the program. However, the EQU
statement that follows guarantees that the assembler still calculates
string length correctly:
message DB "Hello, ten times.",13,10 ; Message to print
lmessage EQU $ - message ; Determine length of message
The new variable is actually a memory location of word size (two bytes).
QuickAssembler allocates another two bytes in the data segment, and
initializes these bytes:
count DW 10
The label count becomes associated with the address of the data, and the
number 10 is the initial value placed at this memory location. However,
the value can change.
The instruction mov ah,40h now has a label, because the program needs to
return here to repeat the print operation. Not all instructions need a
label──only those that the program may need to jump to directly.
The two new instructions cause the program to repeat the print operation
ten times:
dec count ; count = count-1
jnz printit ; if count > 0, print again
The DEC instruction subtracts 1 from the memory location count, and sets
processor flags according to the result of the operation. JNZ then jumps
to the specified label if the result was not zero. The combined effect of
these two instructions is to repeat the previous instructions (from
printit onward) ten times. To change the number of repetitions, initialize
count with a different value.
Note that the DOS print function returns a value in the register
AX──specifically, the number of bytes written. The program jumps back to
printit so that AH is reloaded before the call to DOS.
You can optimize this program further by using a register instead of the
memory location count. For example, to use the register SI as the counter,
follow these steps:
■ Remove the declaration of count.
■ Initialize SI to 10 at the beginning of the program with the
instruction mov si,10.
■ Decrement SI instead of count near the bottom of the loop.
With this program, it's safe to use SI as the counter, since SI is not
needed for any other purpose. However, some programs make special use of
SI. In these cases, it may be more efficient to place the count in a
variable.
4.8 Creating .COM Files
You can use QuickAssembler to produce .COM files as well as .EXE files.
(However, these programs cannot contain any C modules.) Most of the memory
models, ranging from small to large, produce a .EXE file. The tiny memory
model is special because it alone supports creation of a .COM file.
──────────────────────────────────────────────────────────────────────────
NOTE To produce a .COM file, you must not only use tiny memory model, but
also select Generate COM File from the Linker Flags dialog box (choose
Make from the Options menu), or else give the /TINY linker option on the
QCL command line.
──────────────────────────────────────────────────────────────────────────
Each .COM file has only one physical segment and is limited in size to a
total of 64K. A .COM file has no executable-file header or
relocation-table entries. Because DOS doesn't have to examine a file
header or adjust relocatable segment addresses, it loads the .COM file
slightly faster.
DOS initializes all segment registers (including DS) to point to the first
available memory address. The Stack Pointer, SP, is set to 64K above the
start of the program. Unlike .EXE files, .COM files have no definite stack
area. Instead, the stack starts at offset address FFFE hexadecimal and
continues to grow downward until it overlaps code and data areas. At that
point, program failure is likely.
Simplified segment directives in QuickAssembler now provide direct support
for .COM files. The template is, in fact, smaller than the template for a
.EXE file.
The code below shows the example in Section 4.3, "A Program That Says
Hello," revised to produce a .COM file:
.MODEL tiny ; Produce a .COM file
.DATA
message DB "Hello, world.",13,10 ; Message to print
lmessage EQU $ - message ; Determine length of message
.CODE
.STARTUP
mov bx,1 ; Load 1 - file handle for
; standard output
mov cx,lmessage ; Load length of message
mov dx,OFFSET message ; Load address of message
mov ah,40h ; Load no. of DOS Write function
int 21h ; Call interrupt 21H (DOS)
mov ax,4c00h ; Load no. of DOS Exit function
; in AH, and 0 exit code in AL
int 21h ; Call interrupt 21H (DOS)
END
A tiny-model program could be produced by simply taking the small-model
version from earlier in the chapter, and changing the first line to the
following:
.MODEL tiny
The code would then run correctly. However, the sample code in this
section takes advantage of tiny model by eliminating the stack segment.
DOS initializes the SS (Stack Segment) register and SP (Stack Pointer)
register for you, so you need not declare a stack. The assembler ignores
stack segments in tiny model.
The program still includes the .STARTUP directive. With tiny model, all
this directive does is generate the statement ORG 100h.
──────────────────────────────────────────────────────────────────────────
NOTE The statement ORG 100h is necessary for programs in the .COM
format, and must appear just before the first line of executable code. ORG
100h starts the location counter at 100 hexadecimal, reflecting the way
that DOS loads .COM files into memory. (DOS reserves the first 256 bytes
for the Program Segment Prefix (PSP).) See Section 6.6, "Setting the
Location Counter," for more information on the ORG directive.
──────────────────────────────────────────────────────────────────────────
With tiny-model programs, QuickAssembler lets you define separate code and
data segments, but combines these segments into a single physical segment,
called a "group." QuickAssembler places the code segment first regardless
of how you write your source code. The resulting .COM file assumes a
single segment address for the whole program (as required by the structure
of a .COM file), and execution automatically begins at the proper address.
Finally, Quick-Assembler directs the linker to output a file in the .COM
format rather than the .EXE format.
──────────────────────────────────────────────────────────────────────────
NOTE "Groups" are a standard concept in 8086 assembly language. You can
place a series of segments into a group. The total size must not exceed
64K. The linker responds by combining all the segments into a single
physical segment in which all addresses share the same segment address.
For a fuller explanation of groups and segments, see Chapter 5.
──────────────────────────────────────────────────────────────────────────
When you write .COM files, you must observe some important restrictions.
You cannot use program-defined segment addresses. Similarly, you have no
access to defined segment addresses, such as @data and @code.
Because .COM files lack relocation-table entries, DOS cannot adjust
segment addresses at load time. The program must use absolute segment
addresses or else assume the loading segment address that DOS assigns. The
principal restriction is that you cannot refer to program-defined segment
addresses. Therefore, memory references can be of three kinds:
1. Any memory location within the 64K program area. For these memory
references, you do not load a new value into any of the segment
registers.
2. Hard-coded locations in memory that have special meaning at the system
or hardware level. A video-page address, such as B800:0000, is such a
special segment address.
3. An address returned to you by a DOS or ROM-BIOS function. For example,
DOS function 48H, Allocate Memory, returns a pointer to a block of
dynamically allocated memory.
4.9 Creating .COM Files with Full Segment Definitions
You don't generally need to use full segment definitions to create .COM
files. However, when you do use these directives with programs written in
.COM format, you need to follow certain rules. The assembler automatically
follows most of these rules when you use simplified segment directives.
The guidelines for .COM format are listed below:
■ Place the entire program into one physical segment. It's possible to
divide your program into separate logical segments, then group them
into one physical segment with the GROUP directive. Simplified segment
directives, in fact, use this technique with tiny model.
However, you must ensure that code, not data, appears at the beginning
of the .COM file. A number of different factors affect segment
ordering, so it may be hard to ensure that the code segment appears
first. Thus, creating just one segment is the more reliable method.
In contrast, when you use simplified segment directives with tiny
model, the assembler always places the code segment at the beginning of
the .COM file.
■ Use the ASSUME directive to inform the assembler that all segment
registers will point to the beginning of the segment. At load time, DOS
sets all segment registers to this address. The ASSUME directive
informs the assembler of this fact so that it can correctly calculate
offset addresses. This directive is not necessary when you use
simplified segment directives.
■ Use the ORG directive to set the location counter. At load time, DOS
sets the starting address to 100H. The first 100H bytes are reserved
for the Program Segment Prefix (PSP). The statement ORG 100h is
necessary for the assembler to assign addresses in a way consistent
with run-time conditions. Otherwise, jump instructions and data
references will be wrong.
When you use simplified segments directives with tiny model, the
assembler automatically sets the location counter to 100H.
■ Use the END statement to take one argument: a starting address. This
argument is not necessary if you use the .STARTUP simplified segment
directive, because the program automatically begins execution wherever
you place .STARTUP.
The modified procedure is shown below:
_TEXT SEGMENT 'CODE' ; Define code segment
ASSUME cs:_TEXT,ds:_TEXT,ss:_TEXT
ORG 100h
start: jmp begin
message DB "Hello, world.",13,10 ; Message to print
lmessage EQU $ - message ; Determine length of message
begin: mov bx,1 ; Load 1 - file handle
; for standard output
mov cx,lmessage ; Load length of message
mov dx,OFFSET message ; Load address of message
mov ah,40h ; Load no. of DOS Write function
int 21h ; Call interrupt 21H (DOS)
mov ax,4c00h ; Load no. of DOS Exit function
; in AH, and 0 exit code in AL
int 21h ; Call interrupt 21H (DOS)
_TEXT ENDS
END start
The first three statements are new. The SEGMENT statement defines the
beginning of a segment named _TEXT. (Instead of using the name _TEXT, you
can choose any other valid symbolic name.) The ASSUME statement then
informs the assembler that the CS, DS, and SS segment registers will all
point to the beginning of this segment at run time. Finally, the ORG
statement informs the assembler that the instruction pointer will be set
to 100H.
_TEXT SEGMENT ; Define code segment
ASSUME cs:_TEXT,ds:_TEXT,ss:_TEXT
ORG 100h
The body of the procedure now includes code and data together in the same
segment. The first item in the segment must be an instruction, because
.COM files always begin execution at the start of the file. Attempting to
execute data would almost certainly cause program failure. Since there is
no separate data segment, the first instruction jumps around the data
declarations.
start: jmp begin
message DB "Hello, world.",13,10 ; Message to print
lmessage EQU $ - message ; Determine length of message
begin: mov bx,1 ; Load 1 - file handle for
; standard output
Another way to write a program for .COM format is to place data
declarations after the end of the instructions. However, the assembler
often produces better results if you place data declarations early in the
source file. That way, you avoid forward references to data.
The source file ends by giving an argument to the END statement. This
statement is necessary because the program does not use the .STARTUP
directive. The argument to END must be the label of the first instruction
executed:
END start
────────────────────────────────────────────────────────────────────────────
PART 2: Using Directives
Part 2 of the Programmer's Guide (comprising Chapters 5-12) describes
the directives and operators recognized by the Microsoft QuickAssembler.
Directives are nonexecutable statements that give general information to
the assembler. Some of the more important directives declare program
structure, define data, and create macros. Operators indicate calculations
to be performed at assembly time.
Chapters 5-8 present the basic directives you need to write a program,
including segment, data, multimodule, and structure directives. Chapter
9 deals specifically with operators. Chapter 10 describes conditional
assembly, and Chapter 11 presents macros, a technique for replacing a
series of frequently used instructions with a single statement. The
directives that control your output are covered in Chapter 12.
────────────────────────────────────────────────────────────────────────────
Chapter 5: Defining Segment Structure
A segment is an area in memory up to 64K in size, in which all locations
share the same segment address. The 8086 assembly-language modules use
segments for two reasons:
■ Segments provide a convenient means for dividing a program into its
major divisions──code, data, constant data, and stack.
■ The architecture of the 8086 requires some use of segments. Every
reference to memory must be relative to one of the four segment
registers, as described in Section 2.7, "Segmented Addressing and
Segment Registers." Segment definitions make it possible for
QuickAssembler to assume the use of the same segment register for a
large number of different addresses.
You can define segments by using simplified segment directives or full
segment definitions.
In most cases, simplified segment directives are a better choice. They are
easier to use and more consistent, yet you seldom sacrifice any
functionality by using them. Simplified segment directives automatically
define the segment structure required when combining assembler modules
with modules prepared with Microsoft high-level languages.
Although more difficult to use, full segment definitions give more
complete control over segments. A few complex programs may require full
segment definitions in order to get unusual segment orders and types.
This chapter describes both methods. If you choose to use simplified
segment directives, you will probably not need to read about full segment
definitions.
5.1 Simplified Segment Directives
Simplified segment directives provide an easy way to write
assembly-language programs. They handle some of the difficult aspects of
segment definition automatically, and assume the same conventions adopted
by Microsoft high-level languages.
When you write stand-alone assembler programs, the simplified segment
directives make programming easier. The Microsoft conventions are flexible
enough to work for most kinds of programs.
When you write assembler routines to be linked with Microsoft high-level
languages, the simplified segment directives ensure against mistakes that
would make your modules incompatible. The names are automatically defined
consistently and correctly.
The simplified segment directives automatically generate the same ASSUME
and GROUP statements used by Microsoft high-level languages. You can learn
more about the ASSUME and GROUP directives in Sections 5.3 and 5.4.
However, for most programs you do not need to understand these directives.
Simply use the simplified segment directives in the format shown in the
examples.
5.1.1 Understanding Memory Models
To use simplified segment directives, you must declare a memory model for
your program. The memory model specifies the default size of data and code
used in a program.
Microsoft high-level languages require that each program have a default
size (or memory model). Any assembly-language routine called from a
high-level language program should have the same memory model as the
calling program. The C compiler provided with QuickAssembler supports all
models except tiny. If you use assembly modules with a different compiler,
the compiler documentation should tell what memory models are supported.
The most commonly used memory models are described below:
Model Description
──────────────────────────────────────────────────────────────────────────
Tiny All data and code fit in a single physical segment
(group). Tiny-model programs can be converted to
.COM-file format with the Generate COM File option in
the Linker Flags dialog box (or the linker /TINY
option used with QCL). Tiny-model programs have
restrictions described in Chapter 4, "Writing
Stand-Alone Assembly Programs."
Small All data fits within a single 64K segment, and all
code fits within a 64K segment. Therefore, all code
and data can be accessed as near. This is the most
common model for stand-alone assembler programs. C is
the only Microsoft language that supports this model.
Medium All data fits within a single 64K segment, but code
may be greater than 64K. Therefore, data is near, but
code is far. Most recent versions of Microsoft
high-level languages support this model.
Compact All code fits within a single 64K segment, but the
total amount of data may be greater than 64K (although
no array can be larger than 64K). Therefore, code is
near, but data is far. C is the only Microsoft
high-level language that supports this model.
Large Both code and data may be greater than 64K (although
no array can be larger than 64K). Therefore, both code
and data are far. All Microsoft high-level languages
support this model.
Huge Both code and data may be greater than 64K. In
addition, any individual data array can be larger than
64K. From the standpoint of QuickAssembler, this
memory model is almost equivalent to large model (the
only exception is the meaning of the predefined equate
@DataSize). If you want to support arrays larger than
64K, you must provide the program logic to support
these arrays.
Stand-alone assembler programs can have any model. Tiny and small model
are adequate for most programs written entirely in assembly language.
Since near data or code can be accessed more quickly, the smallest memory
model that can accommodate your code and data is usually the most
efficient.
Mixed-model programs use the default size for most code and data but
override the default for particular data items. Stand-alone assembler
programs can be written as mixed-model programs by making specific
procedures or variables near or far. Some Microsoft high-level languages
have NEAR, FAR, and HUGE keywords that enable you to override the default
size of individual data or code items.
5.1.2 Specifying DOS Segment Order
The DOSSEG directive specifies that segments be ordered according to the
DOS segment-order convention. This is the convention used by Microsoft
high-level-language compilers.
Syntax
DOSSEG
Using the DOSSEG directive enables you to maintain a consistent, logical
segment order without actually defining segments in that order in your
source file. Without this directive, the final segment order of the
executable file depends on a variety of factors, such as segment order,
class name, and order of linking. These factors are described in Section
5.2, "Full Segment Definitions."
Since segment order is not crucial to the proper functioning of most
stand-alone assembler programs, you can simply use the DOSSEG directive
and ignore the whole issue of segment order.
──────────────────────────────────────────────────────────────────────────
NOTE Using the DOSSEG directive (or the /DOSSEG linker option) has two
side effects. The linker generates symbols called _end and _edata. You
should not use these names in programs that contain the DOSSEG directive.
Also, the linker increases the offset of the first byte of the code
segment by 16 bytes in small and compact models. This is to give proper
alignment to executable files created with Microsoft compilers.
──────────────────────────────────────────────────────────────────────────
If you want to use the DOS segment-order convention in stand-alone
assembler programs, you should use the DOSSEG argument in the main module.
Modules called from the main module need not use the DOSSEG directive.
You do not need to use the DOSSEG directive for modules called from
Microsoft high-level languages, since the compiler already defines DOS
segment order.
Under the DOS segment-order convention, segments have the following order:
1. All segment names having the class name 'CODE'
2. Any segments that do not have class name 'CODE' and are not part of the
group DGROUP
3. Segments that are part of DGROUP, in the following order:
a. Any segments of class BEGDATA (this class name is reserved for
Microsoft use)
b. Any segments not of class BEGDATA, BSS, or STACK
c. Segments of class BSS
d. Segments of class STACK
Using the DOSSEG directive has the same effect as using the /DOSSEG linker
option.
The directive works by writing to the comment record of the object file.
The Intel(R) title for this record is COMENT. If the linker detects a
certain sequence of bytes in this record, it automatically puts segments
in the DOS order.
5.1.3 Defining Basic Attributes of the Module
The .MODEL directive defines attributes that affect the entire module:
memory model, default calling and naming conventions, and stack type. This
directive should appear before any other simplified segment directive.
Syntax
.MODEL memorymodel[[[[,language]],stacktype]]
Each of the three fields defines a basic attribute. The memorymodel field
defines the segment structure of the module. The language field defines
the default calling and naming conventions assumed by PROC statements.
These conventions correspond to the high-level language you specify. The
stacktype field determines whether or not the assembler assumes that the
SS register is equal to the DS register.
The memorymodel field can be TINY, SMALL, MEDIUM, COMPACT, LARGE, or HUGE.
The assembler defines segments the same way for large and huge models, but
the @DataSize equate (explained in Section 5.1.5, "Using Predefined
Segment Equates") gives a different value for these two models.
If you write an assembler routine for a high-level language, the
memorymodel field should match the memory model used by the compiler or
interpreter. If you write a stand-alone assembler program, you can use any
model. Section 5.1.1 describes each memory model.
The optional language field tells the assembler to follow the naming,
calling, and return conventions appropriate to the indicated language. In
addition, if you use the language argument, the assembler automatically
makes all procedure names public. You can use C, Pascal, FORTRAN, or BASIC
as the language argument. The last three are equivalent, since these
languages share the same naming and calling conventions.
Note that although the language field is optional, you will not be able to
use the high-level language features of the PROC directive if you do not
give it. Normally, you should specify a language with .MODEL. If you use C
for the language argument, all public and external names are by default
prefixed with an underscore (_) in the .OBJ file. Specifying any other
language has no effect on the names.
──────────────────────────────────────────────────────────────────────────
NOTE The assembler does not truncate names in order to match the
conventions of specific languages, such as FORTRAN or Pascal. Moreover,
using the C type specifier does not cause the assembler to preserve case.
To preserve lowercase names in public symbols, choose one of the assembler
flags that preserves case (Preserve Extrn or Preserve Case), or assemble
with /Cx or /Cl on the QCL command line. Within the environment, the
Preserve Extrn flag is on by default.
──────────────────────────────────────────────────────────────────────────
See Appendix A for an explanation of how the different calling
conventions are implemented. You should also note that each language has
different defaults for passing parameters by value or by reference.
Depending on which method is used, a high-level language passes a
parameter either as a value or as a pointer to the value.
The optional stacktype field determines whether or not the assembler
assumes that SS is equal to DS. The default value is nearStack, which
assumes that SS is part of the default data area, so that SS is equal to
DS, and SP is set to the top of the data area. You can also use farStack,
which assumes that the stack segment is in a separate physical segment
from the default data area.
If you write a module called from QuickC, you should always use the
default (in other words, just leave the field blank), since QuickC always
assumes DS equals SS. If you write modules for a compiler (such as the
Microsoft Optimized C Compiler) that supports customized memory models,
use farStack for models in which SS does not equal DS. If you write a
stand-alone assembler program, you can choose either setting. If you use
the .STARTUP directive, the assembler automatically generates the proper
code for setting up the indicated stack type.
If you write a stand-alone module without using .STARTUP, you should
exercise caution. If you initialize DS but do not adjust SS and SP (as
described in Section 5.5.3, "Initializing the SS and SP Registers), use
the farStack keyword. If you do adjust SS and SP as described in Section
5.5.3, you can use the default value, nearStack.
Example 1
DOSSEG
.MODEL small,c
This statement defines default segments for small-model programs and
creates the ASSUME and GROUP statements used by small-model programs. The
segments are automatically ordered according to the Microsoft convention.
The example statements might be used at the start of the main (or only)
module of a stand-alone assembler program.
Example 2
.MODEL large,pascal
This statement defines default segments for large-model programs and
creates the ASSUME and GROUP statements used by large-model programs. It
does not automatically order segments according to the Microsoft
convention. The example statement might be used at the start of an
assembly module that would be called from a large-model Pascal program or
a C program in which the Pascal calling convention was specified.
Example 3
.MODEL small,c,farStack
This statement defines default segments for a small-model program and
creates the appropriate ASSUME and GROUP statements. In addition, this
statement makes all procedures public, and directs the assembler to prefix
an underscore to the beginning of each public name, so that the naming
convention is compatible with C. If you later use the PROC statement to
declare parameters, the assembler will assume that the parameters are
placed on the stack in the order specified by the C calling convention. In
addition, the statement uses farStack, indicating that SS is not equal to
DS.
The last example would be appropriate for a module called by a C module
with a customized memory model, compiled with a setting that did not
assume SS equal to DS. Note that QuickC does not support customized memory
models.
──────────────────────────────────────────────────────────────────────────
NOTE The assembler does not normally display the code generated by the
high-level-language support features. You can see the code produced by
these features by using the .LALL directive or the /LA command-line
option.
──────────────────────────────────────────────────────────────────────────
To write procedures for use with more than one language and memory model,
you can use text macros for the memory model and language arguments, and
define the values from the command line or in the Assembler Flags dialog
box. For example, the following .MODEL directive uses text macros for the
memorymodel and language arguments:
% .MODEL memmodel,lang ; Use % to evaluate memmodel, lang
The values of the two text macros can be defined from the command line
using the /D switch:
QCL /Dmemmodel=MEDIUM /Dlang=C /AM /Cx main.c proc.asm
5.1.4 Defining Simplified Segments
Each of the directives .CODE, .STACK, .DATA, .DATA?, .CONST, .FARDATA,
.FARDATA?, and .STARTUP indicate the start of a segment. They also end the
immediately preceding segment definition.
Syntax
.CODE [[name]] Code segment
.STACK [[size]] Stack segment
.DATA Initialized near-data segment
.DATA? Uninitialized near-data segment
.CONST Constant-data segment
.FARDATA [[name]] Initialized far-data segment
.FARDATA? [[name]] Uninitialized far-data segment
.STARTUP Code to initialize segment registers
For segments that take an optional name, the base file name of the source
module is used if you do not specify a value yourself.
Each new segment directive ends the previous segment. The END directive
closes the last segment in the source file.
5.1.4.1 How to Use Simplified Segments
The .CODE, .DATA, and .STACK directives create the three basic segments
that programs generally need to have. Chapter 4, "Writing Stand-Alone
Assembly Programs," demonstrates how to use these directives to write
code, data, and stack segments. Chapter 4 also explains the purpose of
each of these segments.
The .STARTUP directive initializes segment registers to the appropriate
segment values. Chapter 4 describes the use of .STARTUP, and Section
5.5 tells more about how .STARTUP works and what code it generates.
When you write a mixed-language program, you generally don't need to
declare a stack segment, because the start-up code in the C main module
creates a stack for you. When you write a stand-alone program, you should
declare a stack segment in the main module only.
Your programs can also use the .DATA? and .CONST directives to create
segments for uninitialized and constant data, respectively. With
stand-alone assembler programs, the use of these directives is optional,
because you can place all data in the segment defined by .DATA if you
want. With mixed-language programs, use .DATA? and .CONST to ensure
compatibility with the way C handles uninitialized and constant data. Once
you define these segments, it is up to you to place the appropriate data
in each segment.
If your program is written in compact, large, or huge model, you can use
the .FARDATA and .FARDATA? directives to define additional data segments.
All the data in the other data segments (defined by .DATA, .DATA?, and
.CONST) must not exceed a total of 64K across all modules. In addition,
the stack segment is also placed into this 64K area unless you specify
farStack with the .MODEL directive.
Data in the .FARDATA and .FARDATA? segments takes slightly longer to
access. However, there is generally much more room in these segments for
data definitions. For each module, the .FARDATA and .FARDATA? directives
each create a separate physical segment that can be up to 64K in size. The
recommended procedure is to use .FARDATA for initialized data, and
.FARDATA? for uninitialized data, although this is optional.
With medium, large, and huge model, you can use the name attribute to
create multiple code segments within a source module. With compact, large,
and huge model, you can also use the name attribute to create multiple
far-data segments.
Example 1
DOSSEG
.MODEL small,c
.STACK 100h
.DATA
ivariable DB 5
iarray DW 50 DUP (5)
string DB "This is a string"
uarray DW 50 DUP (?)
EXTRN xvariable:WORD
.CODE
.STARTUP
EXTRN xprocedure:NEAR
call xprocedure
.
.
.
END
This code uses simplified segment directives for a small-model,
stand-alone assembler program. Notice that initialized data, uninitialized
data, and a string constant are all defined in the same data segment. See
Section 5.1.7, "Default Segment Names," for an equivalent version that
uses full segment definitions.
Example 2
.MODEL, large,c
.FARDATA?
fuarray DW 10 DUP (?) ; Far uninitialized data
.CONST
string DB "This is a string" ; String constant
.DATA
niarray DB 100 DUP (5) ; Near initialized data
.FARDATA
EXTRN xvariable:FAR
fiarray DW 100 DUP (10) ; Far initialized data
.CODE TASK
EXTRN xprocedure:PROC
task PROC
.
.
.
ret
task ENDP
END
This example uses simplified segment directives to create a module that
might be called from a large-model, high-level-language program. Notice
that different types of data are put in different segments to conform to
Microsoft compiler conventions. See Section 5.1.7, "Default Segment
Names," for an equivalent version using full segment definitions.
5.1.4.2 How Simplified Segments Are Implemented
When you use the simplified segment directives described above, the
assembler defines segments in a way compatible with Microsoft high-level
languages.
This section makes a number of references to groups and ASSUME statements.
Both of these concepts arise from the need to deal with the 8086 segmented
architecture. A "group" consists of one or more segments, totaling no more
than 64K. When multiple segments are placed into a group, the linker
combines these segments into a single physical segment. All addresses in
the physical segment are adjusted so that they share the same segment
address. Use of groups is convenient because it removes the need to
constantly reload the DS register.
The ASSUME directive is described at greater length in Section 5.4,
"Associating Segments with Registers." This directive informs the
assembler where a segment register will point to at run time so that the
assembler can correctly calculate offset addresses relative to the value
in the appropriate segment register.
Unless you use tiny model, the code segment (defined with .CODE) is placed
in its own physical segment, separate from all the data and stack
segments. With medium, large, or huge model, you can define multiple code
segments within one source model by using .CODE repeatedly, each time with
a different name attribute. When you use this technique, each .CODE
directive generates a new ASSUME statement so that the assembler knows
where CS points to at run time.
Segments defined with the .STACK, .CONST, .DATA, or .DATA? directives are
placed in a group called DGROUP. Segments defined with the .FARDATA or
.FARDATA? directives are not placed in any group. See Section 5.3 for
more information on segment groups. When initializing the DS register to
access data in a group-associated segment, the value of DGROUP should be
loaded into DS. The .STARTUP directive does this initialization
automatically.
The .MODEL directive generates ASSUME statements to inform the assembler
that at run time, DS, SS, and ES will all point to the beginning of
DGROUP. You don't need to write these ASSUME statements yourself.
If you specify farStack with the .MODEL directive, the stack is placed in
a separate physical segment and the .MODEL directive generates an ASSUME
statement to inform the assembler that SS does not point to the same
segment address that DS does.
5.1.5 Using Predefined Segment Equates
Several equates are predefined for you. You can use the equate names at
any point in your code to represent the equate values. You should not
assign equates having these names. The predefined equates are listed
below:
Name Value
──────────────────────────────────────────────────────────────────────────
@CodeSize and If the .MODEL directive has been used, the value of
@DataSize @CodeSize is 0 for the models that use near-code
labels (tiny, small, and compact) or 1 for models that
use far-code labels (medium, large, and huge). The
value of @DataSize is 0 for models that use near-data
labels (tiny, small, and medium), 1 for compact and
large models, and 2 for huge models. These values can
be used in conditional-assembly statements.
IF @DataSize
les bx,pointer ; Load far pointer
mov ax,es:WORD PTR [bx]
ELSE
mov bx,WORD PTR pointer ; Load near pointer
mov ax,WORD PTR [bx]
ENDIF
@CurSeg This name has the segment name of the current segment.
This value may be convenient for ASSUME statements,
segment overrides, or other cases in which you need to
access the current segment. It can also be used to end
a segment.
@FileName This value represents the base name of the current
source file. For example, if the current source file
is TASK.ASM, the value of @FileName is TASK. This
value can be used in any name you would like to change
if the file name changes. For example, it can be used
as a procedure name:
@FileName PROC
.
.
.
@FileName ENDP
@Model As with the @CodeSize and @DataSize predefined
equates, you must first use the .MODEL directive
before using the @Model equate. The value of @Model is
1 for tiny model, 2 for small, 3 for compact, 4 for
medium, 5 for large, and 6 for huge. @Model can be
used in conditional-assembly statements.
Segment equates For each of the primary segment directives, there is a
corresponding equate with the same name, except that
the equate starts with an "at sign" (@) instead of a
period. For example, the @code equate represents the
segment name defined by the .CODE directive.
Similarly, @fardata represents the .FARDATA segment
name and @fardata? represents the .FARDATA? segment
name. The @data equate represents the group name
shared by all the near-data segments. It can be used
to access the segments created by the .DATA, .DATA?,
.CONST, and .STACK segments.
These equates can be used in ASSUME statements and at
any other time a segment must be referred to by name.
──────────────────────────────────────────────────────────────────────────
NOTE Although predefined equates are part of the simplified segment
system, the @CurSeg and @FileName equates are also available when using
full segment definitions. If you use the /Cl option or set Preserve Case
in the Assembler Flags dialog box, predefined equates will be case
sensitive with the exact names shown above.
──────────────────────────────────────────────────────────────────────────
5.1.6 Simplified Segment Defaults
Although your program can combine full segment definitions and simplified
segment directives, the .MODEL directive enables certain features of
simplified segment directives that change defaults. Defaults that change
are listed below:
■ If you do not use the .MODEL directive, the default size for the PROC
directive is always NEAR. If you use the .MODEL directive, the PROC
directive is associated with the specified memory model: NEAR for tiny,
small, and compact models and FAR for medium, large, and huge models.
See Section 6.4.3, "Procedure Labels," for further discussion of the
PROC directive.
■ If you use the .MODEL directive, the OFFSET operator returns an offset
relative to the beginning of a group, whenever a data item is defined
within a group. If you do not use the .MODEL directive, the OFFSET
operator always returns an offset relative to the beginning of the
segment. The simplified segment directives .DATA, .DATA?, and .STACK
all create segments that are part of the group DGROUP.
For example, assume the variable test1 was declared in a segment
defined with the .DATA directive and test2 was declared in a segment
defined with the .FARDATA directive. The statement
mov ax,OFFSET test1
loads the address of test1 relative to DGROUP. The statement
mov ax,OFFSET test2
loads the address of test2 relative to the segment defined by the
.FARDATA directive. See Section 5.3 for more information on groups.
5.1.7 Default Segment Names
If you use the simplified segment directives by themselves, you do not
need to know the names assigned for each segment. However, it is possible
to mix full segment definitions with simplified segment directives.
Therefore, some programmers may wish to know the actual names assigned to
all segments.
Table 5.1 shows the default segment names created by each directive.
Table 5.1 Default Segments and Types for Standard Memory Models
Model Directive Name Align Combine Class Group
──────────────────────────────────────────────────────────────────────────
Tiny .CODE _TEXT WORD PUBLIC 'CODE' DGROUP
.DATA _DATA WORD PUBLIC 'DATA' DGROUP
.CONST CONST WORD PUBLIC 'CONST' DGROUP
.DATA? _BSS WORD PUBLIC 'BSS' DGROUP
──────────────────────────────────────────────────────────────────────────
Small .CODE _TEXT WORD PUBLIC 'CODE'
.DATA _DATA WORD PUBLIC 'DATA' DGROUP
.CONST CONST WORD PUBLIC 'CONST' DGROUP
.DATA? _BSS WORD PUBLIC 'BSS' DGROUP
.STACK STACK PARA STACK 'STACK' DGROUP
──────────────────────────────────────────────────────────────────────────
Medium .CODE name_TEXT WORD PUBLIC 'CODE'
.DATA _DATA WORD PUBLIC 'DATA' DGROUP
.CONST CONST WORD PUBLIC 'CONST' DGROUP
.DATA? _BSS WORD PUBLIC 'BSS' DGROUP
.STACK STACK PARA STACK 'STACK' DGROUP
──────────────────────────────────────────────────────────────────────────
Compact .CODE _TEXT WORD PUBLIC 'CODE'
.FARDATA FAR_DATA PARA private 'FAR_DATA'
.FARDATA? FAR_BSS PARA private 'FAR_BSS'
.DATA _DATA WORD PUBLIC 'DATA' DGROUP
.CONST CONST WORD PUBLIC 'CONST' DGROUP
.DATA? _BSS WORD PUBLIC 'BSS' DGROUP
.STACK STACK PARA STACK 'STACK' DGROUP
──────────────────────────────────────────────────────────────────────────
Large or .CODE name_TEXT WORD PUBLIC 'CODE'
huge .FARDATA FAR_DATA PARA private 'FAR_DATA'
.FARDATA? FAR_BSS PARA private 'FAR_BSS'
.DATA _DATA WORD PUBLIC 'DATA' DGROUP
.CONST CONST WORD PUBLIC 'CONST' DGROUP
.DATA? _BSS WORD PUBLIC 'BSS' DGROUP
.STACK STACK PARA STACK 'STACK' DGROUP
──────────────────────────────────────────────────────────────────────────
The name used as part of far-code segment names is the file name of the
module. The default name associated with the .CODE directive can be
overridden in medium and large models. The default names for the .FARDATA
and .FARDATA? directives can always be overridden.
The segment and group table at the end of listings always shows the actual
segment names. However, the GROUP and ASSUME statements generated by the
.MODEL directive are not shown in listing files. For a program that uses
all possible segments, group statements equivalent to the following would
be generated:
DGROUP GROUP _DATA,CONST,_BSS,STACK
For tiny model, the following would be generated:
ASSUME cs:DGROUP,ds:DGROUP,ss:DGROUP
For small and compact models, the following would be generated:
ASSUME cs:_TEXT,ds:DGROUP,ss:DGROUP
For medium, large, and huge models, the following statement is given:
ASSUME cs: name_TEXT,ds:DGROUP,ss:DGROUP
Example 1
EXTRN xvariable:WORD
EXTRN xprocedure:NEAR
DGROUP GROUP _DATA,_BSS
ASSUME cs:_TEXT,ds:DGROUP,ss:DGROUP
_TEXT SEGMENT WORD PUBLIC 'CODE'
start: mov ax,DGROUP ; Initialize data segment
mov ds,ax
cli
mov ss,ax ; Move DGROUP into SS
add sp,OFFSET STACK ; Adjust SP to top of stac
sti
.
.
.
TEXT ENDS
_DATA SEGMENT WORD PUBLIC 'DATA'
ivariable DB 5
iarray DW 50 DUP (5)
string DB "This is a string"
uarray DW 50 DUP (?)
_DATA ENDS
STACK SEGMENT PARA STACK 'STACK'
DB 100h DUP (?)
STACK ENDS
END start
This example is equivalent to Example 1 in Section 5.1.4, "Defining
Simplified Segments." Notice that the segment order must be different in
this version to achieve the segment order specified by using the DOSSEG
directive in the first Section 5.1.4 example. The external variables are
declared at the start of the source code in this example. With simplified
segment directives, external variables can be declared in the segment in
which they are used. The code generated by .STARTUP is discussed in more
detail in Section 5.5.3.
Example 2
DGROUP GROUP _DATA,CONST,STACK
ASSUME cs:TASK_TEXT,ds:FAR_DATA,ss:STACK
EXTRN xprocedure:FAR
EXTR xvariable:FAR
FAR_BSS SEGMENT PARA 'FAR_DATA'
fuarray DW 10 DUP (?) ; Far uninitialized data
FAR_BSS ENDS
CONST SEGMENT WORD PUBLIC 'CONST'
string DB "This is a string" ; String constant
CONST ENDS
_DATA SEGMENT WORD PUBLIC 'DATA'
niarray DB 100 DUP (5) ; Near initialized data
_DATA ENDS
FAR_DATA SEGMENT WORD 'FAR_DATA'
fiarray DW 100 DUP (10)
FAR_DATA ENDS
TASK_TEXT SEGMENT WORD PUBLIC 'CODE'
task PROC FAR
.
.
.
ret
task ENDP
TASK_TEXT ENDS
END
This example is equivalent to Example 2 in Section 5.1.4, "Defining
Simplified Segments." Notice that the segment order is the same in both
versions. The segment order shown here is written to the object file, but
it is different in the executable file. The segment order specified by the
compiler (the DOS segment order) overrides the segment order in the module
object file.
5.2 Full Segment Definitions
If you need complete control over segments, you may want to give complete
segment definitions. The section below explains all aspects of segment
definitions, including how to order segments and how to define all the
segment types.
5.2.1 Setting the Segment-Order Method
The order in which QuickAssembler writes segments to the object file can
be either sequential or alphabetical. If the sequential method is
specified, segments are written in the order in which they appear in the
source code. If the alphabetical method is specified, segments are written
in the alphabetical order of their segment names.
The default is sequential. If no segment-order directive or option is
given, segments are ordered sequentially. The segment-order method is only
one factor in determining the final order of segments in memory. The
DOSSEG directive (see Section 5.1.2, "Specifying DOS Segment Order") and
class type (see Section 5.2.2.3, "Controlling Segment Structure with
Class Type") can also affect segment order.
The ordering method can be set by using the .ALPHA or .SEQ directive in
the source code. The method can also be set using the /s (sequential) or
/a (alphabetical) assembler options (see Appendix B, Section B.1,
"Specifying the Segment-Order Method"). The directives have precedence
over the options. For example, if the source code contains the .ALPHA
directive, but the /s option is given on the command line, the segments
are ordered alphabetically.
Changing the segment order is an advanced technique. In most cases, you
can simply leave the default sequential order in effect. If you are
linking with high-level-language modules, the compiler automatically sets
the segment order. The DOSSEG directive also overrides any segment-order
directives or options.
──────────────────────────────────────────────────────────────────────────
NOTE Some previous versions of the IBM Macro Assembler ordered segments
alphabetically by default. If you have trouble assembling and linking
source-code listings from books or magazines, try using the /a option.
Listings written for previous IBM versions of the assembler may not work
without this option. The distinction between ENDS as the end of a segment
and ENDS as the end of a structure is also made by the content of the
program.
──────────────────────────────────────────────────────────────────────────
Example 1
.SEQ
DATA SEGMENT WORD PUBLIC 'DATA'
DATA ENDS
CODE SEGMENT WORD PUBLIC 'CODE'
CODE ENDS
Example 2
.ALPHA
DATA SEGMENT WORD PUBLIC 'DATA'
DATA ENDS
CODE SEGMENT WORD PUBLIC 'CODE'
CODE ENDS
In Example 1, the DATA segment is written to the object file first because
it appears first in the source code. In Example 2, the CODE segment is
written to the object file first because its name comes first
alphabetically.
5.2.2 Defining Full Segments
The beginning of a program segment is defined with the SEGMENT directive,
and the end of the segment is defined with the ENDS directive.
Syntax
name SEGMENT [[align]] [[combine]] [[use]] [['class']]
statements
name ENDS
The name defines the name of the segment. This name can be unique, or it
can be the same name given to other segments in the program. Segments with
identical names are treated as the same segment. For example, if it is
convenient to put different portions of a single segment in different
source modules, the segment is given the same name in both modules.
The optional align, combine, use, and 'class' types give the linker and
the assembler instructions on how to set up and combine segments. Types
can be specified in any order; it is not necessary to enter all types, or
any type, for a given segment.
Defining segment types is an advanced technique. Beginning
assembly-language programmers might try using the simplified segment
directives discussed in Section 5.1.
──────────────────────────────────────────────────────────────────────────
NOTE Don't confuse the PAGE align type and the PUBLIC combine type with
the PAGE and PUBLIC directives. The distinction should be clear from
context since the align and combine types are only used on the same line
as the SEGMENT directive.
──────────────────────────────────────────────────────────────────────────
5.2.2.1 Controlling Alignment with Align Type
The optional align type defines the range of memory addresses from which a
starting address for the segment can be selected. The align type can be
any one of the following:
Align Type Meaning
──────────────────────────────────────────────────────────────────────────
BYTE Uses the next available byte address
WORD Uses the next available word address (2 bytes per
word)
DWORD Uses the next available doubleword address (4 bytes
per doubleword)
PARA Uses the next available paragraph address (16 bytes
per paragraph)
PAGE Uses the next available page address (256 bytes per
page)
If no align type is given, PARA is used by default.
The linker uses the alignment information to determine the relative start
address for each segment. DOS uses the information to calculate the actual
start address when the program is loaded.
Align types are illustrated in Figure 5.1 in the next section.
5.2.2.2 Defining Segment Combinations with Combine Type
The optional combine type defines how to combine segments having the same
name. The combine type can be any one of the following:
Combine Type Meaning
──────────────────────────────────────────────────────────────────────────
PUBLIC Concatenates all segments having the same name to form
a single, contiguous segment. The total size of the
resulting segment is equal to the sum of all
contributing segments.
All instruction and data addresses in the new segment
are relative to a single segment register, and all
offsets are adjusted to represent the distance from
the beginning of the segment.
STACK Concatenates all segments having the same name to form
a single, contiguous segment. This combine type is the
same as the PUBLIC combine type, except that all
addresses in the new segment are relative to the SS
segment register. The total size of the resulting
segment is equal to the sum of all contributing
segments.
The Stack Pointer (SP) register is initialized to the
length of the segment. The stack segment of your
program should normally use the STACK type, since this
automatically initializes the SS register, as
described in Section 5.5.3. If you create a stack
segment and do not use the STACK type, you must give
instructions to initialize the SS and SP registers.
For each individual segment, all initialized data is
placed at the high end of the resulting stack segment.
Consequently, if more than one stack segment contains
initialized data, the linker overwrites this data as
it links in each segment. Note that stack data cannot
be initialized with simplified segment directives.
COMMON Creates overlapping segments by placing the start of
all segments having the same name at the same address.
The length of the resulting area is the length of the
longest segment. All addresses in the segments are
relative to the same base address. If variables are
initialized in more than one segment having the same
name and COMMON type, the most recently initialized
data replaces any previously initialized data.
MEMORY Concatenates all segments having the same name to form
a single, contiguous segment.
The Microsoft Overlay Linker treats MEMORY segments
exactly the same as PUBLIC segments. QuickAssembler
allows you to use MEMORY type even though LINK does
not recognize a separate MEMORY type. This feature is
compatible with other linkers that may support a
combine type conforming to the Intel definition of
MEMORY type.
AT address Causes all label and variable addresses defined in the
segment to be relative to address.
The address can be any valid expression but must not
contain a forward reference──that is, a reference to a
symbol defined later in the source file. An AT segment
typically contains no code or initialized data.
Instead, it represents an address template that can be
placed over code or data already in memory, such as a
screen buffer or other absolute memory locations
defined by hardware. The linker will not generate any
code or data for AT segments, but existing code or
data can be accessed by name if it is given a label in
an AT segment. Section 6.6, "Setting the Location
Counter," shows an example of a segment with AT
combine type.
If no combine type is given, the segment has private type. Segments having
the same name are not combined. Instead, each segment receives its own
physical segment when loaded into memory.
──────────────────────────────────────────────────────────────────────────
NOTE Although a given segment name can be used more than once in a
source file, each segment definition using that name must have either
exactly the same attributes, or attributes that do not conflict. If types
are given for an initial segment definition, subsequent definitions for
that segment need not specify any types.
Normally, you should provide at least one stack segment (having STACK
combine type) in a program. If no stack segment is declared, LINK displays
a warning message. You can ignore this message if you have a specific
reason for not declaring a stack segment. For example, you would not have
a separate stack segment in a program in the .COM format.
──────────────────────────────────────────────────────────────────────────
Example
The following source-code shell illustrates one way in which the combine
and align types can be used. Figure 5.1 shows the way LINK would load the
sample program into memory.
NAME module_1
ASEG SEGMENT BYTE PUBLIC 'CODE'
start: .
.
.
ASEG ENDS
BSEG SEGMENT WORD COMMON 'DATA'
.
.
.
BSEG ENDS
CSEG SEGMENT PARA STACK 'STACK'
.
.
.
CSEG ENDS
DSEG SEGMENT AT 0B800H
.
.
.
DSEG ENDS
END start
NAME module_2
ASEG SEGMENT BYTE PUBLIC 'CODE'
.
.
.
ASEG ENDS
BSEG SEGMENT WORD COMMON 'DATA'
.
.
.
BSEG ENDS
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 5.2.2.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
5.2.2.3 Controlling Segment Structure with Class Type
Class type is a means of associating segments that have different names,
but similar purposes. It can be used to control segment order and to
identify the code segment.
The class name must be enclosed in single quotation marks ('). Class names
are not case sensitive unless the /Cl or /Cx option is used during
assembly.
All segments belong to a class. Segments for which no class name is
explicitly stated have the null class name. LINK imposes no restriction on
the number or size of segments in a class. The total size of all segments
in a class can exceed 64K.
──────────────────────────────────────────────────────────────────────────
NOTE The names assigned for class types of segments should not be used
for other symbol definitions in the source file. For example, if you give
a segment the class name 'CONSTANT', you should not give the name constant
to variables or labels in the source file.
──────────────────────────────────────────────────────────────────────────
The linker expects segments having the class name CODE or a class name
with the suffix CODE to contain program code. You should always assign
this class name to segments containing code.
Class type is one of two factors that control the final order of segments
in an executable file. The other factor is the order of the segments in
the source file (with the /s option or the .SEQ directive) or the
alphabetical order of segments (with the /a option or the .ALPHA
directive).
These factors control different internal behavior, but both affect the
final order of segments in the executable file. The sequential or
alphabetical order of segments in the source file determines the order in
which the assembler writes segments to the object file. The class type can
affect the order in which the linker writes segments from object files to
the executable file.
Segments having the same class type are loaded into memory together,
regardless of their sequential or alphabetical order in the source file.
──────────────────────────────────────────────────────────────────────────
NOTE The DOSSEG directive (see Section 5.1.2, "Specifying DOS Segment
Order") overrides all other factors in determining segment order.
──────────────────────────────────────────────────────────────────────────
Example
A_SEG SEGMENT 'SEG_1'
A_SEG ENDS
B_SEG SEGMENT 'SEG_2'
B_SEG ENDS
C_SEG SEGMENT 'SEG_1'
C_SEG ENDS
When QuickAssembler assembles the preceding program fragment, it writes
the segments to the object file in sequential or alphabetical order,
depending on whether the /a option or the .ALPHA directive was used. In
the example above, the sequential and alphabetical order are the same, so
the order will be A_SEG, B_SEG, C_SEG in either case.
When the linker writes the segments to the executable file, it first
checks to see if any segments have the same class type. If they do, it
writes them to the executable file together. Thus, A_SEG and C_SEG are
placed together because they both have class type 'SEG_1'. The final order
in memory is A_SEG, C_SEG, B_SEG.
Since LINK processes modules in the order it receives them on the command
line, you may not always be able to easily specify the order in which you
want segments to be loaded. For example, assume your program has four
segments that you want loaded in the following order: _TEXT, _DATA, CONST,
and STACK.
The _TEXT, CONST, and STACK segments are defined in the first module of
your program, but the _DATA segment is defined in the second module. LINK
will not put the segments in the proper order because it first loads the
segments encountered in the first module.
You can avoid this problem by starting your program with dummy segment
definitions in the order you wish to load your real segments. The dummy
segments can either go at the start of the first module, or they can be
placed in a separate include file that is called at the start of the first
module. You can then put the actual segment definitions in any order or
any module you find convenient.
For example, you might call the following include file at the start of the
first module of your program:
_TEXT SEGMENT WORD PUBLIC 'CODE'
_TEXT ENDS
_DATA SEGMENT WORD PUBLIC 'DATA'
_DATA ENDS
CONST SEGMENT WORD PUBLIC 'CONST'
CONST ENDS
STACK SEGMENT PARA STACK 'STACK'
STACK ENDS
The DOSSEG directive may be more convenient for defining segment order if
you are willing to accept the DOS segment-order conventions.
Once a segment has been defined, you do not need to specify the align,
combine, use, and class types on subsequent definitions. For example, if
your code defined dummy segments as shown above, you could define an
actual data segment with the following statements:
_DATA SEGMENT
.
.
.
_DATA ENDS
5.3 Defining Segment Groups
A group is a collection of segments associated with the same starting
address. You may wish to use a group if you want several types of data to
be organized in separate segments in your source code, but want them all
to be accessible from a single, common segment register at run time.
Syntax
name GROUP segment [[,segment]]...
The name is the symbol assigned to the starting address of the group. All
labels and variables defined within the segments of the group are relative
to the start of the group, rather than to the start of the segments in
which they are defined.
The segment can be any previously defined segment or a SEG expression (see
Section 9.2.4.5).
Segments can be added to a group one at a time. For example, you can
define and add segments to a group one by one.
The GROUP directive does not affect the order in which segments of a group
are loaded. Loading order depends on each segment's class, or on the order
in which object modules are given to the linker.
Segments in a group need not be contiguous. Segments that do not belong to
the group can be loaded between segments that do. The only restriction is
that the distance (in bytes) between the first byte in the first segment
of the group and the last byte in the last segment must not exceed 65,535
bytes.
──────────────────────────────────────────────────────────────────────────
NOTE When the .MODEL directive is used, the offset of a group-relative
segment refers to the ending address of the segment, not the beginning.
For example, the expression OFFSET STACK evaluates to the end of the stack
segment.
──────────────────────────────────────────────────────────────────────────
Group names can be used with the ASSUME directive (discussed in Section
5.4, "Associating Segments with Registers") and as an operand prefix with
the segment-override operator (discussed in Section 9.2.3).
Example
DGROUP GROUP ASEG,CSEG
ASSUME ds:DGROUP
ASEG SEGMENT WORD PUBLIC 'DATA'
.
asym .
.
ASEG ENDS
BSEG SEGMENT WORD PUBLIC 'DATA'
.
bsym .
.
BSEG ENDS
CSEG SEGMENT WORD PUBLIC 'DATA'
.
csym .
.
CSEG ENDS
END
Figure 5.2 shows the order of the example segments in memory. They are
loaded in the order in which they appear in the source code (or in
alphabetical order if the .ALPHA directive or /s option is specified).
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 5.3 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Since ASEG and CSEG are declared part of the same group, they have the
same base despite their separation in memory. This means that the symbols
asym and csym have offsets from the beginning of the group, which is also
the beginning of ASEG. The offset of bsym is from the beginning of BSEG,
since it is not part of the group. This sample illustrates the way LINK
organizes segments in a group. It is not intended as a typical use of a
group.
5.4 Associating Segments with Registers
Many of the assembler instructions assume a default segment. For example,
JMP instructions assume the segment associated with the CS register; PUSH
and POP instructions assume the segment associated with the SS register;
MOV instructions assume the segment associated with the DS register.
When the assembler needs to reference an address, it must know what
segment the address is in. It does this by using the default segment or
group addresses assigned with the ASSUME directive.
──────────────────────────────────────────────────────────────────────────
NOTE Using the ASSUME directive to tell the assembler which segment to
associate with a segment register is not the same as telling the
processor. The ASSUME directive only affects assembly-time assumptions.
You may need to use instructions to change run-time assumptions.
Initializing segment registers at run time is discussed in Section 5.5.
──────────────────────────────────────────────────────────────────────────
Syntax
ASSUME segmentregister:name [[,segmentregister:name]]...
ASSUME segmentregister:NOTHING
ASSUME NOTHING
The name must be the name of the segment or group that is to be associated
with segmentregister. Subsequent instructions that assume a default
register for referencing labels or variables automatically assume that if
the default segment is segmentregister, the label or variable is in the
name segment or group.
The ASSUME directive can define a segment for each of the segment
registers. The segmentregister can be CS, DS, ES, or SS. The name must be
one of the following:
■ The name of a segment defined in the source file with the SEGMENT
directive
■ The name of a group defined in the source file with the GROUP directive
■ The keyword NOTHING
■ A SEG expression (see Section 9.2.4.5, "SEG Operator")
■ A string equate that evaluates to a segment or group name (but not a
string equate that evaluates to a SEG expression)
The keyword NOTHING cancels the current segment selection. For example,
the statement ASSUME NOTHING cancels all register selections made by
previous ASSUME statements.
Usually, a single ASSUME statement defines all four segment registers at
the start of the source file. However, you can use the ASSUME directive at
any point to change segment assumptions.
Using the ASSUME directive to change segment assumptions is often
equivalent to changing assumptions with the segment-override operator (:)
(see Section 9.2.3). The segment-override operator is more convenient for
one-time overrides, whereas the ASSUME directive may be more convenient if
previous assumptions must be overridden for a sequence of instructions.
Example
DOSSEG
.MODEL large ; DS automatically assumed to @data
.STACK 100h
.DATA
d1 DW 7
.FARDATA
d2 DW 9
.CODE
start: mov ax,@data ; Initialize near data
mov ds,ax
mov ax,@fardata ; Initialize far data
mov es,ax
.
.
.
; Method 1 for series of instructions that need override
; Use segment override for each statement
mov ax,es:d2
.
.
.
mov es:d2,bx
; Method 2 for series of instructions that need override
; Use ASSUME at beginning of series of instructions
ASSUME es:@fardata
mov cx,d2
.
.
.
mov d2,dx
5.5 Initializing Segment Registers
Assembly-language programs must initialize segment values for each segment
register before instructions that reference the segment register can be
used in the source program.
Initializing segment registers is different from assigning default values
for segment registers with the ASSUME statement. The ASSUME directive
tells the assembler what segments to use at assembly time. Initializing
segments gives them an initial value that will be used at run time.
The .STARTUP directive generates all the initialization code described in
this section. This directive must be preceded by the .MODEL directive. If
the .MODEL directive was followed by the farStack attribute, .STARTUP does
not adjust SS and SP. Otherwise, it assumes the nearStack default, which
sets SS equal to DS as described in Section 5.5.3, "Initializing the SS
and SP Registers." When you use this default, the combined stack and near
data must not exceed 64K.
If you use .STARTUP, you don't need to enter any of the code in this
section, except for the END statement. (However, if you use .STARTUP, you
don't need to specify a starting address.) Make sure that you place the
.STARTUP directive at the point you want your program to start executing,
because the assembler automatically initializes CS:IP to point to the
beginning of the code generated by .STARTUP.
5.5.1 Initializing the CS and IP Registers
The CS and IP registers are initialized by specifying a starting address
with the END directive.
Syntax
END [[startaddress]]
The startaddress is a label or expression identifying the address where
you want execution to begin when the program is loaded. Normally, a label
for the start address should be placed at the address of the first
instruction in the code segment.
The CS segment is initialized to the value of startaddress. The IP
register is normally initialized to 0. You can change the initial value of
the IP register by using the ORG directive (see Section 6.6, "Setting the
Location Counter") just before the startaddress label. For example,
programs in the .COM format use ORG 100h to initialize the IP register to
256 (100 hexadecimal).
If a program consists of a single source module, the start address is
required for that module. If a program has several modules, all modules
must terminate with an END directive, but only one of them can define a
start address.
──────────────────────────────────────────────────────────────────────────
WARNING One, and only one, module must define a start address. If you do
not specify a start address, none is assumed. Neither QuickAssembler nor
LINK will generate an error message, but your program will probably start
execution at the wrong address.
──────────────────────────────────────────────────────────────────────────
Example
; Module 1
.CODE
start: . ; First executable instruction
.
.
EXTRN task:NEAR
call task
.
.
.
END start ; Starting address defined in main module
; Module 2
PUBLIC task
.CODE
task PROC
.
.
.
task ENDP
END ; No starting address in secondary module
If Module 1 and Module 2 are linked into a single program, it is essential
that only the calling module define a starting address.
5.5.2 Initializing the DS Register
The DS register must be initialized to the address of the segment that
will be used for data.
The address of the segment or group for the initial data segment must be
loaded into the DS register. This is done in two statements because a
memory value cannot be loaded directly into a segment register. The
segment-setup lines typically appear at the start or very near the start
of the code segment.
Example 1
_DATA SEGMENT WORD PUBLIC 'DATA'
.
.
.
_DATA ENDS
_TEXT SEGMENT BYTE PUBLIC 'CODE'
ASSUME cs:_TEXT,ds:_DATA
start: mov ax,_DATA ; Load start of data segment
mov ds,ax ; Transfer to DS register
.
.
.
_TEXT ENDS
END start
If you are using the Microsoft naming convention and segment order, the
address loaded into the DS register is not a segment address but the
address of DGROUP, as shown in Example 2. With simplified segment
directives, the address of DGROUP is represented by the predefined equate
@data.
Example 2
DOSSEG
.MODEL SMALL
.DATA
.
.
.
.CODE
start: mov ax,@data ; Load start of DGROUP (@data)
mov ds,ax ; Transfer to DS register
.
.
.
END start
5.5.3 Initializing the SS and SP Registers
At load time, DOS sets SS to the segment address of the last segment
having combine type STACK, and SP to the size of the stack. (The linker
actually determines the value of SS:SP and places this value in the
executable-file header. DOS sets SS and SP as indicated in the file
header.)
If you use a stack segment with combine type STACK or use the .STACK
directive, the program automatically loads with SS and SP initialized, as
described above.
However, this basic initialization does not set SS equal to DS. If the
program contains the statement ASSUME SS:DGROUP, it will be prone to
errors. The following code resets SS and SP so that SS has the same value
as DS. The code then adjusts SP upward so that SS:SP points to the
same physical address it did before. Since hardware interrupts use
the same stack as the program, you should turn off interrupts while
changing the stack. Most 8086-family processors turn off interrupts
automatically when you adjust SS or SP, but early versions of the 8088 do n
Example 1
.MODEL small
.STACK 100h ; Initialize "STACK"
.DATA
.
.
.
.CODE
start: mov ax,@data ; Load segment location
mov ds,ax ; into DS register
cli ; Turn off interrupts
mov ss,ax ; Load same value as DS into SS
mov sp,OFFSET STACK ; Give SP new stack size
sti ; Turn interrupts back on
.
.
.
This example reinitializes SS so that it has the same value as DS, and it
adjusts SP to reflect the new stack offset. Microsoft high-level-language
compilers do this so that stack variables in near procedures can be
accessed relative to either SS or DS.
However, this code only works correctly if you use .MODEL and you declare
a stack segment in just one module. The following code handles the more
general case. The .STARTUP directive generates this code:
Example 2
start_label:
mov dx,DGROUP ; Move DGROUP into DS and DX
mov ds,dx
mov bx,ss ; BX = STACK - DGROUP
sub bx,dx ;
shl bx,1 ; Multiply difference by 16
shl bx,1 ; and leave result in BX
shl bx,1
shl bx,1
cli
mov ss,dx ; Move DGROUP into SS
add sp,bx ; Adjust SP upward by
sti ; (STACK - DGROUP) * 16
The code above sets SS and SP so that SS equals DS. This code works
correctly no matter how many modules declare a stack segment.
5.5.4 Initializing the ES Register
The ES register is not automatically initialized. If your program uses the
ES register, you must initialize it by moving the appropriate segment
value into the register.
Example
ASSUME es:@fardata ; Tell the assembler
mov ax,@fardata ; Tell the processor
mov es,ax
5.6 Nesting Segments
Segments can be nested. When QuickAssembler encounters a nested segment,
it temporarily suspends assembly of the enclosing segment and begins
assembly of the nested segment. When the nested segment has been
assembled, Quick-Assembler continues assembly of the enclosing segment.
Nesting of segments makes it possible to mix segment definitions in
programs that use simplified segment directives for most segment
definitions. When a full segment definition is given, the new segment is
nested in the simplified segment in which it is defined.
Example 1
; Macro to print message on the screen
; Uses full segment definitions - segments nested
message MACRO text
LOCAL symbol
_DATA SEGMENT WORD PUBLIC 'DATA'
symbol DB &text
DB 13,10,"$"
_DATA ENDS
mov ah,09h
mov dx,OFFSET symbol
int 21h
ENDM
_TEXT SEGMENT BYTE PUBLIC 'CODE'
.
.
.
message "Please insert disk"
In the example above, a macro called from inside of the code segment
(_TEXT) allocates a variable within a nested data segment (_DATA). This
has the effect of allocating more data space on the end of the data
segment each time the macro is called. The macro can be used for messages
appearing only once in the source code.
Example 2
; Macro to print message on the screen
; Uses simplified segment directives - segments not nested
message MACRO text
LOCAL symbol
.DATA
symbol DB &text
DB 13,10,"$"
.CODE
mov ah,09h
mov dx,OFFSET symbol
int 21h
ENDM
.CODE
.
.
.
message "Please insert disk"
Although Example 2 has the same practical effect as Example 1,
Quick-Assembler handles the two macros differently. In Example 1, assembly
of the outer (code) segment is suspended rather than terminated. In
Example 2, assembly of the code segment terminates, assembly of the data
segment starts and terminates, and then assembly of the code segment is
restarted.
────────────────────────────────────────────────────────────────────────────
Chapter 6: Defining Constants, Labels, and Variables
This chapter explains how to define constants, labels, variables, and
other symbols that refer to instruction and data locations within
segments.
Constants are important in QuickAssembler, just as they are in other
languages. You can use constants as immediate operands in instructions and
as initial values in data declarations. QuickAssembler supports a number
of useful radixes (including binary and hexadecimal), as described in
Section 6.1.
QuickAssembler lets you use symbols as well as constants. Sections 6.2,
"Assigning Names to Symbols," and 6.3, "Using Type Specifiers," present
the basic principles of generating symbolic names.
Most symbols are either code labels or variable names. Section 6.4,
"Defining Code Labels," and Section 6.5, "Defining and Initializing
Data," describe how to define these symbols.
This chapter tells you how to assign labels and most kinds of variables.
(Multifield variables, such as structures and records, are discussed in
Chapter 7, "Using Structures and Records.") Chapter 6 also discusses
related directives, including those that control the location counter
directly. The assembler uses the location counter to assign addresses to
symbols.
6.1 Constants
Constants can be used in source files to specify numbers or strings that
are set or initialized at assembly time. The assembler recognizes four
types of constant values:
1. Integers
2. Packed binary coded decimals
3. Real numbers
4. Strings
6.1.1 Integer Constants
Integer constants represent integer values. They can be used in a variety
of contexts in assembly-language source code. For example, they can be
used in data declarations and equates, or as immediate operands.
Packed decimal integers are a special kind of integer constant that can
only be used to initialize binary coded decimal (BCD) variables. They are
described in Sections 6.1.2, "Packed Binary Coded Decimal Constants," and
6.5.1.2, "Binary Coded Decimal Variables."
Integer constants can be specified in binary, octal, decimal, or
hexadecimal values. Table 6.1 shows the legal digits for each of these
radixes. For hexadecimal radix, the digits can be either uppercase or
lowercase letters.
Table 6.1 Digits Used with Each Radix
Radix Base Digits
──────────────────────────────────────────────────────────────────────────
Binary 2 0 1
Octal 8 0 1 2 3 4 5 6 7
Decimal 10 0 1 2 3 4 5 6 7 8 9
Hexadecimal 16 0 1 2 3 4 5 6 7 8 9 A B C D E F
──────────────────────────────────────────────────────────────────────────
The radix for an integer can be defined for a specific integer by using
radix specifiers, or a default radix can be defined globally with the
.RADIX directive.
6.1.1.1 Specifying Integers with Radix Specifiers
The radix for an integer constant can be given by putting one of the
following radix specifiers after the last digit of the number:
Radix Specifier
──────────────────────────────────────────────────────────────────────────
Binary B
Octal Q or O
Decimal D
Hexadecimal H
Radix specifiers can be given in either uppercase or lowercase letters;
sample code in this manual uses lowercase letters.
Hexadecimal numbers must always start with a decimal digit (0-9). If
necessary, put a leading 0 at the left of the number to distinguish
between symbols and hexadecimal numbers that start with a letter. For
example, 0ABCh is interpreted as a hexadecimal number, but ABCh is
interpreted as a symbol. The hexadecimal digits A through F can be either
uppercase or lowercase letters. Sample code in this manual uses uppercase
letters.
If no radix is given, the assembler interprets the integer by using the
current default radix. The initial default radix is decimal, but you can
change the default with the .RADIX directive.
Examples
n360 EQU 01011010b + 132q + 5Ah + 90d ; 4 * 90
n60 EQU 00001111b + 17o + 0Fh + 15d ; 4 * 15
6.1.1.2 Setting the Default Radix
The .RADIX directive sets the default radix for integer constants in the
source file.
Syntax
.RADIX expression
The expression must evaluate to a number in the range 2-16. It defines
whether the numbers are binary, octal, decimal, hexadecimal, or numbers of
some other base.
Numbers given in expression are always considered decimal, regardless of
the current default radix. The initial default radix is decimal.
Note that the .RADIX directive does not affect real numbers initialized as
variables with the DD, DQ, or DT directive. Initial values for real-number
variables declared with these directives are always evaluated as decimal
unless a radix specifier is appended.
Also, the .RADIX directive does not affect the optional radix specifiers,
B and D, used with integer numbers. When the letters B or D appear at the
end of any integer, they are always considered to be a radix specifier
even if the current radix is 16.
For example, if the input radix is 16, the number 0ABCD will be
interpreted as 0ABC decimal, an illegal number, instead of as 0ABCD
hexadecimal, as intended. Type 0ABCDh to specify 0ABCD in hexadecimal.
Similarly, the number 11B will be treated as 11 binary, a legal number,
but not as 11B hexadecimal as intended. Type 11Bh to specify 11B in
hexadecimal.
Examples
.RADIX 16 ; Set default radix to hexadecimal
.RADIX 2 ; Set default radix to binary
6.1.2 Packed Binary Coded Decimal Constants
When an integer constant is used with the DT directive, the number is
interpreted by default as a packed binary coded decimal (BCD) number. You
can use the D radix specifier to override the default and initialize
10-byte integers as binary-format integers.
The syntax for specifying binary coded decimals is exactly the same as for
other integers. However, the assembler encodes binary coded decimals in a
completely different way. See Section 6.5.1.2, "Binary Coded Decimal
Variables," for complete information on storage of binary coded decimals.
Examples
positive DT 1234567890 ; Encoded as 00000000001234567890h
negative DT -1234567890 ; Encoded as 80000000001234567890h
6.1.3 Real-Number Constants
A real number is a number consisting of an integer part, a fractional
part, and an exponent. Real numbers are usually represented in decimal
format.
Syntax
[[+ | -]] integer.fraction[[E[[+ | -]]exponent]]
The integer and fraction parts combine to form the value of the number.
This value is stored internally as a unit and is called the mantissa. It
may be signed. The optional exponent follows the exponent indicator (E).
It represents the magnitude of the value and is stored internally as a
unit. If no exponent is given, 1 is assumed. If an exponent is given, it
may be signed.
During assembly, the assembler converts real-number constants given in
decimal format to a binary format. The sign, exponent, and mantissa of the
real number are encoded as bit fields within the number. See Section
6.5.1.4, "Real-Number Variables," for an explanation of how real numbers
are encoded.
You can specify the encoded format directly using hexadecimal digits (0-9
or A-F). The number must begin with a decimal digit (0-9) and cannot be
signed. It must be followed by the real-number designator (R). This
designator is used the same as a radix designator except it specifies that
the given hexadecimal number should be interpreted as a real number.
Real numbers can only be used to initialize variables with the DD, DQ, and
DT directives. They cannot be used in expressions. The maximum number of
digits in the number and the maximum range of exponent values depend on
the directive. The number of digits for encoded numbers used with DD, DQ,
and DT must be 8, 16, and 20 digits, respectively. (If a leading 0 is
supplied, the number must be 9, 17, or 21 digits.) See Section 6.5.1.4,
"Real-Number Variables," for an explanation of how real numbers are
encoded.
──────────────────────────────────────────────────────────────────────────
NOTE Real numbers will be encoded differently depending upon whether you
use the .MSFLOAT directive. By default, real numbers are encoded in the
IEEE format. The .MSFLOAT directive overrides the default and specifies
Microsoft Binary format. See Section 6.5.1.4, "Real-Number Variables,"
for a description of these formats.
──────────────────────────────────────────────────────────────────────────
Example
; Real numbers
shrt DD 25.23
long DQ 2.523E1
ten_byte DT 2523.0E-2
; Assumes .MSFLOAT
mbshort DD 81000000r ; 1.0 as Microsoft Binary short
mblong DQ 8100000000000000r ; 1.0 as Microsoft Binary long
; Assumes default IEEE format
ieeeshort DD 3F800000r ; 1.0 as IEEE short
ieeelong DQ 3FF0000000000000r ; 1.0 as IEEE long
; The same regardless of processor directives
temporary DT 3FFF8000000000000000r ; 1.0 as 10-byte temporary real
6.1.4 String Constants
A string constant consists of one or more ASCII characters enclosed in
single or double quotation marks. Strings are interpreted as lists of
characters having the ASCII values of the characters in the string.
Syntax
'characters'
"characters"
String constants are case sensitive. A string constant consisting of a
single character is sometimes called a character constant.
Single quotation marks must be encoded twice when used literally within
string constants that are also enclosed by single quotation marks.
Similarly, double quotation marks must be encoded twice when used in
string constants that are also enclosed by double quotation marks.
Examples
char DB 'a'
char2 DB "a"
message DB "This is a message."
warn DB 'Can"t find file.' ; Can't find file.
warn2 DB "Can't find file." ; Can't find file.
string DB "This ""value"" not found." ; This "value" not found.
string2 DB 'This "value" not found.' ; This "value" not found.
6.1.5 Determining Floating-Point Format
The .MSFLOAT directive disables all coprocessor instructions and specifies
that initialized real-number variables be encoded in the Microsoft Binary
format. Without this directive, initialized real-number variables are
encoded in the IEEE format. This is a change from Versions 4.0 and earlier
of the Microsoft Macro Assembler, which used Microsoft Binary format by
default and required a coprocessor directive or the /R option to specify
IEEE format. .MSFLOAT must be used for programs that require real-number
data in the Microsoft Binary format. Section 6.5.1.4, "Real-Number
Variables," describes real-number data formats and the factors to consider
in choosing a format.
6.2 Assigning Names to Symbols
A symbol is a name that represents a value. Symbols are one of the most
important elements of assembly-language programs. Elements that must be
represented symbolically in assembly-language source code include
variables, address labels, macros, segments, procedures, records, and
structures. Constants, expressions, and strings can also be represented
symbolically.
Symbol names are combinations of letters (both uppercase and lowercase),
digits, and special characters. The QuickAssembler recognizes the
following character set:
A-Z a-z 0-9
? @ _ $ : . [ ] ( ) < > { } + - / *
& % ! ' ~ | \ = # ^ ; , ` "
Letters, digits, and some characters can be used in symbol names, but some
restrictions on how certain characters can be used or combined are listed
below:
■ A name can have any combination of uppercase and lowercase letters.
Within the QC integrated environment, the default behavior (Preserve
Extrn) is for the assembler to convert all symbol names to uppercase
unless they are public or external. When you use simplified segment
directives, all procedure labels declared with PROC are automatically
public.
When you use QCL, all lowercase letters are converted to uppercase by
the assembler, unless you give the /Cl assembly option, or you declare
the name with a PROC, PUBLIC, or EXTRN directive and you give the /Cx
option. The /Cl and /Cx options correspond to the assembler flags
Preserve Case and Preserve Extrn, respectively, within the QC
environment.
■ Digits may be used within a name, but not as the first character.
■ A name can be given any number of characters, but only the first 31 are
used. All other characters are ignored.
■ The following characters may be used at the beginning of a name or
within a name: underscore (_), question mark (?), dollar sign ($), and
at sign (@).
■ The period (.) is an operator and cannot be used within a name, but it
can be used as the first character of a name.
■ A name may not be the same as any reserved name. Note that two special
characters, the question mark (?) and the dollar sign ($), are reserved
names and therefore can't stand alone as symbol names.
A reserved name is any name with a special, predefined meaning to the
assembler. Reserved names include instruction and directive mnemonics,
register names, and operator names. All uppercase and lowercase letter
combinations of these names are treated as the same name.
The following is a list of names that are always reserved by the
assembler. Using any of these names for a symbol results in an error.
$ DWORD GE %OUT
* ELSE GROUP PAGE
+ ELSEIF GT PROC
- ELSEIF1 HIGH PTR
. ELSEIF2 IF PUBLIC
/ ELSEIFB IF1 PURGE
= ELSEIFDEF IF2 QWORD
? ELSEIFDIF IFB .RADIX
[] ELSEIFDIFI IFDEF RECORD
.186 ELSEIFE IFDIF REPT
.286 ELSEIFIDN IFE .SALL
.286P ELSEIFIDNI IFIDN SEG
.287 ELSEIFNB IFNB SEGMENT
.386 ELSEIFNDEF IFNDEF .SEQ
.386P END INCLUDE .SFCOND
.387 ENDIF INCLUDELIB SHL
.8086 ENDM IRP SHORT
.8087 ENDP IRPC SHR
ALIGN ENDS LABEL SIZE
.ALPHA EQ .LALL SIZESTR
AND EQU LE .STACK
ASSUME .ERR LENGTH .STARTUP
BYTE .ERR1 .LFCOND STRUC
CATSTR .ERR2 .LIST SUBSTR
.CODE .ERRB LOCAL SUBTTL
COMM .ERRDEF LOW TBYTE
COMMENT .ERRDIF LT .TFCOND
.CONST .ERRE MACRO THIS
.CREF .ERRIDN MASK TITLE
.DATA .ERRNB MOD TYPE
.DATA? .ERRNDEF .MODEL .TYPE
DB .ERRNZ NAME WIDTH
DD EVEN NE WORD
DOSSEG EXITM NEAR .XALL
DQ EXTRN NOT .XCREF
DS FAR OFFSET .XLIST
DT .FARDATA OR XOR
In addition to the names listed above, instruction mnemonics and register
names are considered reserved names. Instructions can vary depending on
the processor directives given in the source file. For example, ENTER is
recognized as a reserved word if you have enabled 286 instructions with
the .286 directive. Section 18.3 describes processor directives.
Instruction mnemonics for each processor are listed in the on-line Help
system. Register names are listed in Section 2.6.2, "Register Operands."
6.3 Using Type Specifiers
Some statements require type specifiers to give the size or type of an
operand. There are two kinds of type specifiers: those that specify the
size of a variable or other memory operand, and those that specify the
distance of a label.
The type specifiers that give the size of a memory operand are listed
below with the number of bytes specified by each:
Specifier Number of Bytes
──────────────────────────────────────────────────────────────────────────
BYTE 1
WORD 2
DWORD 4
QWORD 8
TBYTE 10
In some contexts, ABS can also be used as a type specifier that indicates
an operand is a constant rather than a memory operand.
The type specifiers that give the distance of a label are listed below:
Specifier Description
──────────────────────────────────────────────────────────────────────────
FAR The label references both the segment and offset of
the label.
NEAR The label references only the offset of the label.
PROC The label has the default type (NEAR or FAR) of the
current memory model. The default size is always NEAR
if you use full segment definitions. If you use
simplified segment directives (see Section 5.1), the
default type is NEAR for small and compact models or
FAR for medium, large, and huge models.
Directives that use type specifiers include LABEL, PROC, EXTRN, and COMM.
Operators that use type specifiers include PTR and THIS.
6.4 Defining Code Labels
Code labels give symbolic names to the addresses of instructions in the
code segment. These labels can be used as the operands to jump, call, and
loop instructions to transfer program control to a new instruction.
6.4.1 Near-Code Labels
Near-label definitions create instruction labels that have NEAR type.
These instruction labels can be used to access the address of the label
from other statements.
Syntax
name:
The name must be followed by a colon (:). The segment containing the
definition must be the one that the assembler currently associates with
the CS register. The ASSUME directive is used to associate a segment with
a segment register (see Section 5.4, "Associating Segments with
Registers"). A near label can appear on a line by itself or on a line with
an instruction.
Near-code labels have different behavior depending on whether they are
used in a procedure with the extended PROC syntax. When the extended PROC
feature is used (which requires that .MODEL and a language must be
specified), near labels are local to the procedure. This functionality is
explained in Section 15.3.7, "Variable Scope."
If the full segments are used or if the language argument is not supplied
to the .MODEL directive, near labels are known throughout the module in
which they occur. The same label name can be used in different modules as
long as each label is only referenced by instructions in its own module.
If a label must be referenced by instructions in another module, it must
be given a unique name and declared with the PUBLIC and EXTRN directives,
as described in Chapter 8, "Creating Programs from Multiple Modules."
Examples
cmp ax,5 ; Compare with 5
ja bigger
jb smaller
. ; Instructions if AX = 5
.
.
jmp done
bigger: . ; Instructions if AX > 5
.
.
jmp done
smaller: . ; Instructions if AX < 5
.
.
done:
6.4.2 Anonymous Labels
The assembler provides a way to generate automatic labels for jump
instructions. To define a label, use two at signs (@@) followed by a colon
(:). To jump to the nearest preceding anonymous label, use @B (back) in
the jump instruction's operand field; to jump to the nearest following
anonymous label, use @F (forward) in the operand field.
You can use two at signs (@@) to define any number of anonymous labels in
your program. The items @B and @F always refer to the nearest occurrences
of @@, so there is never any conflict between different anonymous labels.
Anonymous labels are best used for conditionally executing a few lines of
code. The advantage is that you do not need to continually think up new
label names. The disadvantage is that they do not provide a meaningful
name. You should mark major divisions of a program with actual named
labels.
The following example shows a typical sequence of code with a
jump-to-label instruction:
; DX is 20, unless CX is less than -20, then make DX 30
mov dx,20
cmp cx,-20
jge greatequ
mov dx,30
greatequ:
Here are the same lines rewritten to use an anonymous label:
; DX is 20, unless CX is less than -20, then make DX 30
mov dx,20
cmp cx,-20
jge @F
mov dx,30
@@:
6.4.3 Procedure Labels
The easiest way to declare a procedure is to use the PROC and ENDP
directives. The former declares the beginning of the procedure, and the
latter declares the end.
The PROC directive has the following syntax:
label PROC [[NEAR|FAR]]
statements
RET [[constant]]
label ENDP
The label assigns a symbol to the procedure. The distance can be NEAR or
FAR. Any RET instructions within the procedure automatically have the same
distance (NEAR or FAR) as the procedure.
The syntax shown here is always available. In addition, there is an
extended PROC syntax available if you use .MODEL and specify a language.
The extended PROC syntax is explained in Section 15.3.4, "Declaring
Parameters with the PROC Directive."
The ENDP directive labels the address where the procedure ends. Every
procedure label must have a matching ENDP label to mark the end of the
procedure. QuickAssembler generates an error message if it does not find
an ENDP directive to match each PROC directive.
When the PROC label definition is encountered, the assembler sets the
label's value to the current value of the location counter and sets its
type to NEAR or FAR. If the label has FAR type, the assembler also sets
its segment value to that of the enclosing segment. If you have specified
full segment definitions, the default distance is NEAR. If you are using
simplified segment directives, the default distance is the distance
associated with the declared memory model──that is, NEAR for small and
compact models or FAR for medium, large, and huge models.
The procedure label can be used in a CALL instruction to direct execution
control to the first instruction of the procedure. Control can be
transferred to a NEAR procedure label from any address in the same segment
as the label. Control can be transferred to a FAR procedure label from an
address in any segment.
Procedure labels must be declared with the PUBLIC and EXTRN directives if
they are located in one module but called from another module, as
described in Chapter 8, "Creating Programs from Multiple Modules."
Example
call task ; Call procedure
.
.
.
task PROC NEAR ; Start of procedure
.
.
.
ret
task ENDP ; End of procedure
6.4.4 Code Labels Defined with the LABEL Directive
The LABEL directive provides an alternative method of defining code
labels.
Syntax
name LABEL distance
The name is the symbol name assigned to the label. The distance can be a
type specifier, such as NEAR, FAR, or PROC. PROC means NEAR or FAR,
depending on the default memory model, as described in Section 5.1.3,
"Defining Basic Attributes of the Module." You can use the LABEL directive
to define a second entry point into a procedure. FAR code labels can also
be the destination of far jumps or of far calls that use the RETF
instruction (see Section 15.3.2, "Defining Procedures").
Example
task PROC FAR ; Main entry point
.
.
.
task1 LABEL FAR ; Secondary entry point
.
.
.
ret
task ENDP ; End of procedure
6.5 Defining and Initializing Data
The data-definition directives enable you to allocate memory for data. At
the same time, you can specify the initial values for the allocated data.
Data can be specified as numbers, strings, or expressions that evaluate to
constants. The assembler translates these constant values into binary
bytes, words, or other units of data. The encoded data is written to the
object file at assembly time.
6.5.1 Variables
Variables consist of one or more named data objects of a specified size.
Syntax
[[name]] directive initializer [[,initializer]]...
The name is the symbol name assigned to the variable. If no name is
assigned, the data is allocated; but the starting address of the variable
has no symbolic name.
The size of the variable is determined by directive. The directives that
can be used to define single-item data objects are listed below:
Directive Meaning
──────────────────────────────────────────────────────────────────────────
DB Defines byte
DW Defines word (2 bytes)
DD Defines doubleword (4 bytes)
DQ Defines quadword (8 bytes)
DT Defines 10-byte variable
The optional initializer can be a constant, an expression that evaluates
to a constant, or a question mark (?). The question mark is the symbol
indicating that the value of the variable is undefined. You can define
multiple values by using multiple initializers separated by commas, or by
using the DUP operator, as explained in Section 6.5.2, "Arrays and
Buffers."
Simple data types can allocate memory for integers, strings, addresses, or
real numbers.
6.5.1.1 Integer Variables
When defining an integer variable, you can specify an initial value as an
integer constant or as a constant expression. QuickAssembler generates an
error if you specify an initial value too large for the specified
variable.
Integer values for all sizes except 10-byte variables are stored in binary
form. They can be interpreted as either signed or unsigned numbers. For
instance, the hexadecimal value 0FFCD can be interpreted either as the
signed number -51 or the unsigned number 65,485.
The processor cannot tell the difference between signed and unsigned
numbers. Some instructions are designed specifically for signed numbers.
It is the programmer's responsibility to decide whether a value is to be
interpreted as signed or unsigned, and then to use the appropriate
instructions to handle the value correctly.
Figure 6.1 shows various integer storage formats.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 6.5.1.1 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The directives for defining integer variables are listed below with the
sizes of integer they can define:
Directive Size of Directive
──────────────────────────────────────────────────────────────────────────
DB (bytes) Allocates unsigned numbers from 0 to 255 or signed
numbers from -128 to 127.
DW (words) Allocates unsigned numbers from 0 to 65,535 or signed
numbers from -32,768 to 32,767. The bytes of a word
integer are stored in the format shown in Figure 6.1.
Note that in assembler listings and in most debuggers
the bytes of a word are shown in the opposite
order──high byte first──since this is the way most
people think of numbers.
Word values can be used directly in 8086-family
instructions. They can also be loaded, used in
calculations, and stored with 8087-family
instructions.
DD (doublewords) Allocates unsigned numbers from 0 to 4,294,967,295 or
signed numbers from -2,147,483,648 to 2,147,483,647.
The words of a doubleword integer are stored in the
format shown in Figure 6.1.
These 32-bit values (called long integers) can be
loaded, used in calculations, and stored with
8087-family instructions. Some calculations can be
done on these numbers directly with 16-bit 8086-family
processors; others involve an indirect method of doing
calculations on each word separately (see Chapter 14,
"Doing Arithmetic and Bit Calculations").
DQ (quadwords) Allocates 64-bit integers. The doublewords of a
quadword integer are stored in the format shown in
Figure 6.1.
These values can be loaded, used in calculations, and
stored with 8087-family instructions. You must write
your own routines to use them with 16-bit 8086-family
processors.
DT Allocates 10-byte (80-bit) integers if the D radix
specifier is used.
By default, DT allocates packed binary coded decimal
(BCD) numbers, as described in Section 6.5.1.2,
"Binary Coded Decimal Variables." If you define binary
10-byte integers, you must write your own routines to
use routines in calculations.
Example
integer DB 16 ; Initialize byte to 16
expression DW 4*3 ; Initialize word to 12
empty DQ ? ; Allocate uninitialized long integer
DB 1,2,3,4,5,6 ; Initialize six unnamed bytes
long DD 4294967295 ; Initialize double word to 4,294,967,295
tb DT 2345d ; Initialize 10-byte binary integer
6.5.1.2 Binary Coded Decimal Variables
Binary coded decimal (BCD) numbers provide a method of doing calculations
on large numbers without rounding errors. They are sometimes used in
financial applications. There are two kinds: packed and unpacked.
Unpacked BCD numbers are stored one digit to a byte, with the value in the
lower four bits. They can be defined with the DB directive. For example,
an unpacked BCD number could be defined and initialized as shown below:
unpackedr DB 1,5,8,2,5,2,9 ; Initialized to 9,252,851
unpackedf DB 9,2,5,2,8,5,1 ; Initialized to 9,252,851
Whether least-significant digits can come either first or last depends on
how you write the calculation routines that handle the numbers.
Calculations with unpacked BCD numbers are discussed in Section 14.5.1.
Packed BCD numbers are stored two digits to a byte, with one digit in the
lower four bits and one in the upper four bits. The leftmost bit holds the
sign (0 for positive or 1 for negative).
Packed BCD variables can be defined with the DT directive as shown below:
packed DT 9252851 ; Allocate 9,252,851
The 8087-family processors can do fast calculations with packed BCD
numbers, as described in Chapter 17, "Calculating with a Math
Coprocessor." The 8086-family processors can also do some calculations
with packed BCD numbers, but the process is slower and more complicated.
See Section 14.5.2 for details.
6.5.1.3 String Variables
Strings are normally initialized with the DB directive. The initializing
value is specified as a string constant. Strings can also be initialized
by specifying each value in the string. For example, the following
definitions are equivalent:
version1 DB 97,98,99 ; As ASCII values
version2 DB 'a','b','c' ; As characters
version3 DB "abc" ; As a string
One- and two-character strings can also be initialized with any of the
other data-definition directives. The last (or only) character in the
string is placed in the byte with the lowest address. Either 0 or the
first character is placed in the next byte. The unused portion of such
variables is filled with zeros.
Examples
function9 DB 'Hello',13,10,'$' ; Use with DOS INT 21h
; function 9
asciiz DB "\ASM\TEST.ASM",0 ; Use as ASCIIZ string
message DB "Enter file name: " ; Use with DOS INT 21h
l_message EQU $-message ; function 40h
a_message EQU OFFSET message
str1 DB "ab" ; Stored as 61 62
str2 DD "ab" ; Stored as 62 61 00 00
str3 DD "a" ; Stored as 61 00 00 00
6.5.1.4 Real-Number Variables
Real numbers must be stored in binary format. However, when initializing
variables, you can specify decimal or hexadecimal constants and let the
assembler automatically encode them into their binary equivalents.
QuickAssembler can use two different binary formats for real numbers: IEEE
or Microsoft Binary. You can specify the format by using directives (IEEE
is the default).
This section tells you how to initialize real-number variables, describes
the two binary formats, and explains real-number encoding.
Initializing and Allocating Real-Number Variables
Real numbers can be defined by initializing them either with real-number
constants or with encoded hexadecimal constants. The real-number
designator (R) must follow numbers specified in encoded format.
The directives for defining real numbers are listed below with the sizes
of the numbers they can allocate:
Directive Size
──────────────────────────────────────────────────────────────────────────
DD Allocates short (32-bit) real numbers in either the
IEEE or Microsoft Binary format.
DQ Allocates long (64-bit) real numbers in either the
IEEE or Microsoft Binary format.
DT Allocates temporary or 10-byte (80-bit) real numbers.
The format of these numbers is similar to the IEEE
format. They are always encoded the same regardless of
the real-number format. Their size is nonstandard and
incompatible with most Microsoft high-level languages.
Temporary-real format is provided for those who want
to initialize real numbers in the format used
internally by 8087-family processors.
The 8086-family microprocessors do not have any instructions for handling
real numbers. You must write your own routines, use a library that
includes real-number calculation routines, or use a coprocessor. The
8087-family coprocessors can load real numbers in the IEEE format; they
can also use the values in calculations and store the results back to
memory, as explained in Chapter 17, "Calculating with a Math
Coprocessor."
Examples
shrt DD 98.6 ; QuickAsm automatically encodes
long DQ 5.391E-4 ; in current format
ten_byte DT -7.31E7
eshrt DD 87453333r ; 98.6 encoded in Microsoft
; Binary format
elong DQ 3F41AA4C6F445B7Ar ; 5.391E-4 encoded in IEEE format
The real-number designator (R) used to specify encoded numbers is
explained in Section 6.1.3, "Real-Number Constants."
Selecting a Real-Number Format
QuickAssembler can encode four-byte and eight-byte real numbers in two
different formats: IEEE and Microsoft Binary. Your choice depends on the
type of program you are writing. The four primary alternatives are listed
below:
1. If your program requires a coprocessor for calculations, you must use
the IEEE format.
2. Most high-level languages use the IEEE format. If you are writing
modules that will be called from such a language, your program should
use the IEEE format. All versions of the C, FORTRAN, and Pascal
compilers sold by Microsoft and IBM use the IEEE format.
3. If you are writing a module that will be called from early versions of
Microsoft or IBM BASIC, your program should use the Microsoft Binary
format. Versions that support only the Microsoft Binary format include:
■ Microsoft QuickBASIC through Version 2.01
■ Microsoft BASIC Compiler through Version 5.3
■ IBM BASIC Compiler through Version 2.0
■ Microsoft GW-BASIC(R) interpreter (all versions)
■ IBM BASICA interpreter (all versions)
Microsoft QuickBASIC Version 3.0 supported both the Microsoft Binary
and IEEE formats as options. Current and future versions of Microsoft
QuickBASIC and the Microsoft and IBM BASIC compilers support only the
IEEE format.
4. If you are creating a stand-alone program that does not use a
coprocessor, you can choose either format. The IEEE format is better
for overall compatibility with high-level languages. The Microsoft
Binary format may be necessary for compatibility with existing source
code.
──────────────────────────────────────────────────────────────────────────
NOTE When you interface assembly-language modules with high-level
languages, the real-number format only matters if you initialize
real-number variables in the assembly module. If your assembly module does
not use real numbers, or if all real numbers are initialized in the
high-level-language module, the real-number format does not make any
difference.
──────────────────────────────────────────────────────────────────────────
By default, QuickAssembler assembles real-number data in the IEEE format.
If you wish to use the Microsoft Binary format, you must put the .MSFLOAT
directive at the start of your source file before initializing any
real-number variables.
Real-Number Encoding
The IEEE format for encoding four- and eight-byte real numbers is
illustrated in Figure 6.2. Although this figure places the
most-significant bit first for illustration, low bytes actually appear
first in memory.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 6.5.1.4 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The parts of the real numbers are described below:
1. Sign bit (0 for positive or 1 for negative) in the upper bit of the
first byte.
2. Exponent in the next bits in sequence (8 bits for short real number or
11 bits for long real number).
3. All except the first set bit of mantissa in the remaining bits of the
variable. Since the first significant bit is known to be set, it need
not be actually stored. The length is 23 bits for short real numbers
and 52 bits for long real numbers.
The Microsoft Binary format for encoding real numbers is illustrated in
Figure 6.3.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 6.5.1.4 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The three parts of real numbers are described below:
1. Biased exponent (8 bits) in the high-address byte. The bias is 81H for
short real numbers and 401H for long real numbers.
2. Sign bit (0 for positive or 1 for negative) in the upper bit of the
second-highest byte.
3. All except the first set bit of mantissa in the remaining 7 bits of the
second-highest byte and in the remaining bytes of the variable. Since
the first significant bit is known to be set, it need not be actually
stored. The length is 23 bits for short real numbers and 55 bits for
long real numbers.
QuickAssembler also supports the 10-byte temporary-real format used
internally by 8087-family coprocessors. This format is similar to IEEE
format. The size is nonstandard and is not used by Microsoft compilers or
interpreters. Since the coprocessors can load and automatically convert
numbers in the more standard 4-byte and 8-byte formats, the 10-byte format
is seldom used in assembly-language programming.
The temporary-real format for encoding real numbers is illustrated in
Figure 6.4.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 6.5.1.4 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The four parts of the real numbers are described below:
1. Sign bit (0 for positive or 1 for negative) in the upper bit of the
first byte.
2. Exponent in the next bits in sequence (15 bits for 10-byte real).
3. The integer part of mantissa in the next bit in sequence (bit 63).
4. Remaining bits of mantissa in the remaining bits of the variable. The
length is 63 bits.
Notice that the 10-byte temporary-real format stores the integer part of
the mantissa. This differs from the 4-byte and 8-byte formats, in which
the integer part is implicit.
6.5.2 Arrays and Buffers
Arrays, buffers, and other data structures consisting of multiple data
objects of the same size can be defined with the DUP operator. This
operator can be used with any of the data-definition directives described
in this chapter.
Syntax
count DUP (initialvalue[[,initialvalue]]...)
The count sets the number of times to define initialvalue. The initial
value can be any expression that evaluates to an integer value, a
character constant, or another DUP operator. It can also be the undefined
symbol (?) if there is no initial value.
Multiple initial values must be separated by commas. If multiple values
are specified within the parentheses, the sequence of values is allocated
count times. For example, the statement
DB 5 DUP ("Text ")
allocates the string "Text " five times for a total of 25 bytes.
DUP operators can be nested up to 17 levels. The initial value (or values)
must always be placed within parentheses.
Examples
array DD 10 DUP (1) ; 10 doublewords
; initialized to 1
buffer DB 256 DUP (?) ; 256 byte buffer
masks DB 20 DUP (040h,020h,04h,02h) ; 80 byte buffer
; with bit masks
DB 32 DUP ("I am here ") ; 320 byte buffer with
; signature for debugging
three_d DD 5 DUP (5 DUP (5 DUP (0))) ; 125 doublewords
; initialized to 0
Note that QuickAssembler sometimes generates different object code when
the DUP operator is used rather than when multiple values are given. For
example, the statement
test1 DB ?,?,?,?,? ; Indeterminate
is "indeterminate." It causes QuickAssembler to write five zero-value
bytes to the object file. The statement
test2 DB 5 DUP (?) ; Undefined
is "undefined." It causes QuickAssembler to increase the offset of the
next record in the object file by five bytes. Therefore, an object file
created with the first statement will be larger than one created with the
second statement.
In most cases, the distinction between indeterminate and undefined
definitions is trivial. The linker adjusts the offsets so that the same
executable file is generated in either case. However, the difference is
significant in segments with the COMMON combine type. If COMMON segments
in two modules contain definitions for the same variable, one with an
indeterminate value and one with an explicit value, the actual value in
the executable file varies depending on link order. If the module with the
indeterminate value is linked last, the 0 initialized for it overrides the
explicit value. You can prevent this by always using undefined rather than
indeterminate values in COMMON segments. For example, use the first of the
following statements:
test3 DB 1 DUP (?) ; Undefined - doesn't initialize
test4 DB ? ; Indeterminate - initializes 0
If you use the undefined definition, the explicit value is always used in
the executable file regardless of link order.
6.5.3 Labeling Variables
The LABEL directive can be used to define a variable of a given size at a
specified location. It is useful if you want to refer to the same data as
variables of different sizes.
Syntax
name LABEL type
The name is the symbol assigned to the variable, and type is the variable
size. The type can be any one of the following type specifiers: BYTE,
WORD, DWORD, QWORD, or TBYTE. It can also be the name of a previously
defined structure.
Examples
warray LABEL WORD ; Access array as 50 words
darray LABEL DWORD ; Access same array as 25 doublewords
barray DB 100 DUP(?) ; Access same array as 100 bytes
6.5.4 Pointer Variables
The assembler lets you explicitly allocate pointers. A pointer (address)
variable is either two or four bytes in size; consequently, any word or
doubleword data definition can create a pointer variable. However,
declaring pointer variables explicitly gives more accurate debugging
information to the environment.
Pointer-variable definitions have the following form:
symbol [[DW | DD]] type PTR initialvalue
The type can consist of the name of a record, structure, or one of the
standard types described in Section 6.3, "Using Type Specifiers."
Example
string DB "from swerve of shore to bend of bay", 0
pstring DW BYTE PTR string ; Declares a near pointer to string.
fpstring DD BYTE PTR string ; Declares a far pointer to string.
In this example, near (two-byte) and far (four-byte) pointers are declared
and initialized to the value of a null terminated string. This is the
format used in C language, and the pointer variables in the example could
be used in C functions that process strings.
Using an explicit pointer declaration generates debugging information,
causing the variable to be viewed as a pointer during debugging.
Consequently, the environment properly interprets the variable when you
enter it as a Watch expression. No special syntax is required.
This use of PTR is distinct from the use of PTR to alter the type of a
variable during an instruction. The assembler uses the context of the
program to determine which way you are using the PTR keyword.
6.6 Setting the Location Counter
As the assembler encounters labels and data declarations, it needs to know
what address to assign. This function is fulfilled by the location
counter, which indicates the offset address corresponding to the current
line of source code. This value is generally equal to the value that IP
will have at run time.
The assembler increments the location counter as it processes each
statement. However, you can set the location counter directly by using the
ORG directive.
Syntax
ORG expression
Subsequent code and data offsets begin at the new offset specified set by
expression. The expression must resolve to a constant number. In other
words, all symbols used in the expression must be known on the first pass
of the assembler.
──────────────────────────────────────────────────────────────────────────
NOTE The value of the location counter, represented by the dollar sign
($), can be used in the expression, as described in Section 9.3, "Using
the Location Counter."
──────────────────────────────────────────────────────────────────────────
Example 1
; Labeling absolute addresses
STUFF SEGMENT AT 0 ; Segment has constant value 0
ORG 410h ; Offset has constant value 410h
equipment LABEL WORD ; Value at 0000:0410 labeled "equipment"
ORG 417h ; Offset has constant value 417h
keyboard LABEL WORD ; Value at 0000:0417 labeled "keyboard"
STUFF ENDS
.CODE
.
.
.
ASSUME ds:STUFF ; Tell the assembler
mov ax,STUFF ; Tell the processor
mov ds,ax
mov dx,equipment
mov keyboard,ax
Example 1 illustrates one way of assigning symbolic names to absolute
addresses.
Example 2
; Format for .COM files
_TEXT SEGMENT
ASSUME cs:_TEXT,ds:_TEXT,ss:_TEXT,es:_TEXT
ORG 100h ; Skip 100h bytes of DOS header
entry: jmp begin ; Jump over data
variable DW ? ; Put more data here
.
begin: . ; First line of code
. ; Put more code here
_TEXT ENDS
END entry
Example 2 illustrates how the ORG directive is used to initialize the
starting execution point in .COM files.
6.7 Aligning Data
Some operations are more efficient when the variable used in the operation
is lined up on a boundary of a particular size. The EVEN and ALIGN
directives can be used to pad the object file so that the next variable is
aligned on a specified boundary.
Syntax 1
EVEN
Syntax 2
ALIGN number
The EVEN directive always aligns on the next even byte. The ALIGN
directive aligns on the next byte that is a multiple of number. The number
must be a power of 2. For example, use ALIGN 2 or EVEN to align on word
boundaries, or use ALIGN 4 to align on doubleword boundaries.
If the value of the location counter is not on the specified boundary when
an ALIGN directive is encountered, the location counter is incremented to
a value on the boundary. If the location counter is already on the
boundary, the directive has no effect.
When the assembler increments the location counter, it also pads the
skipped memory locations by inserting certain values. If the segment is a
data segment, the assembler always pads these locations with zeros. If the
segment is a code segment, the assembler pads skipped memory locations
with a two-byte no-op instruction (instruction that performed no
operation) where possible:
xchg bx,bx
This instruction, which assembles as 87D8 hexadecimal, does nothing, but
it executes faster than two NOP instructions. Where there is no room for
the two-byte no-op, the assembler inserts the one-byte NOP instruction.
The ALIGN and EVEN directives give no efficiency improvements on
processors that have an 8-bit data bus (such as the 8088). These
processors always fetch data one byte at a time, regardless of the
alignment. However, using EVEN can speed certain operation on processors
that have a 16-bit data bus (such as the 8086), since the processor can
fetch a word if the data is word aligned, but must do two memory fetches
if the data is not word aligned.
──────────────────────────────────────────────────────────────────────────
NOTE The ALIGN directive is a new feature of recent versions of Microsoft
assemblers, starting with 5.0. In previous versions, data could be word
aligned by using the EVEN directive, but other alignments could not be
specified.
The EVEN directive should not be used in segments with BYTE align type.
Similarly, the number specified with the ALIGN directive should be no
greater than the size of the align type of the current segment (thus
ensuring that number is a divisor of the align type of the segment).
──────────────────────────────────────────────────────────────────────────
Example
DOSSEG
.MODEL small,c
.STACK 100h
.DATA
.
.
.
ALIGN 2 ; For faster data access
stuff DW 66,124,573,99,75
.
.
.
ALIGN 2 ; For faster data access
evenstuff DW ?,?,?,?,?
.CODE
start: mov ax,@data ; Load segment location
mov ds,ax ; into DS
mov es,ax ; and ES registers
mov cx,5 ; Load count
mov si,OFFSET stuff ; Point to source
mov di,OFFSET evenstuff ; and destination
ALIGN 2 ; Align for faster loop access
mloop: lodsw ; Load a word
inc ax ; Make it even by incrementing
and ax,NOT 1 ; and turning off first bit
stosw ; Store
loop mloop ; Again
.
.
.
In this example, the words at stuff and evenstuff are forced to word
boundaries. This makes access to the data faster with processors that have
a 16-bit data bus. Without this alignment, the initial data might start on
an odd boundary and the processor would have to fetch half of each word at
a time.
Similarly, the alignment in the code segment speeds up repeated access to
the code at the start of the loop. The sample code sacrifices program size
in order to achieve moderate improvements on the 8086 and 80286. There is
no speed advantage on the 8088.
────────────────────────────────────────────────────────────────────────────
Chapter 7: Using Structures and Records
QuickAssembler can define and use two kinds of multifield variables:
structures and records.
"Structures" are templates for data objects made up of smaller data
objects. A structure can be used to define structure variables, which are
made up of smaller variables called fields. Fields within a structure can
be different sizes, and each can be accessed individually.
"Records" are templates for data objects whose bits can be described as
groups of bits called fields. A record can be used to define record
variables. Each bit field in a record variable can be used separately in
constant operands or expressions. The processor cannot access bits
individually at run time, but bit fields can be used with logical bit
instructions to change bits indirectly.
This chapter describes structures and records and tells how to use them.
7.1 Structures
A structure variable is a collection of data objects that can be accessed
symbolically as a single data object. Objects within the structure can
have different sizes and can be accessed symbolically.
There are two steps in using structure variables:
1. Declare a structure type. A structure type is a template for data. It
declares the sizes and, optionally, the initial values for objects in
the structure. By itself the structure type does not define any data.
The structure type is used by QuickAssembler during assembly but is not
saved as part of the object file.
2. Define one or more variables having the structure type. For each
variable defined, memory is allocated to the object file in the format
declared by the structure type.
The structure variable can then be used as an operand in assembler
statements. The structure variable can be accessed as a whole by using the
structure name, or individual fields can be accessed by using structure
and field names.
7.1.1 Declaring Structure Types
The STRUC and ENDS directives mark the beginning and end of a type
declaration for a structure.
Syntax
name STRUC
fielddeclarations
name ENDS
The name declares the name of the structure type. It must be unique. The
fielddeclarations declare the fields of the structure. Any number of field
declarations may be given. They must follow the form of data definitions
described in Section 6.5, "Defining and Initializing Data." Default
initial values may be declared individually or with the DUP operator.
The names given to fields must be unique within the source file where they
are declared. When variables are defined, the field names will represent
the offset from the beginning of the structure to the corresponding field.
When declaring strings in a structure type, make sure the initial values
are long enough to accommodate the largest possible string. Strings
smaller than the field size can be placed in the structure variable, but
larger strings will be truncated.
A structure declaration can contain both field declarations and comments.
Conditional-assembly statements are allowed in structure declarations; no
other kinds of statements are allowed. Since the STRUC directive is not
allowed inside structure declarations, structures cannot be nested.
──────────────────────────────────────────────────────────────────────────
NOTE The ENDS directive that marks the end of a structure has the same
mnemonic as the ENDS directive that marks the end of a segment. The
assembler recognizes the meaning of the directive from context. Make sure
each SEGMENT directive and each STRUC directive has its own ENDS
directive.
──────────────────────────────────────────────────────────────────────────
Example
student STRUC ; Structure for student records
id DW ? ; Field for identification #
sname DB "Last, First Middle "
scores DB 10 DUP (100) ; Field for 10 scores
student ENDS
Within the sample structure student, the fields id, sname, and scores have
the offset values 0, 2, and 24, respectively.
7.1.2 Defining Structure Variables
A structure variable is a variable with one or more fields of different
sizes. The sizes and initial values of the fields are determined by the
structure type with which the variable is defined.
Syntax
[[name]] structurename <[[initialvalue [[,initialvalue]]...]]>
The name is the name assigned to the variable. If no name is given, the
assembler allocates space for the variable, but does not give it a
symbolic name. The structurename is the name of a structure type
previously declared by using the STRUC and ENDS directives.
An initialvalue can be given for each field in the structure. Its type
must not be incompatible with the type of the corresponding field. The
angle brackets (< >) are required even if no initial value is given. If
initial values are given for more than one field, the values must be
separated by commas.
If the DUP operator (see Section 6.5.2, "Arrays and Buffers") is used to
initialize multiple structure variables, only the angle brackets and
initial values, if given, need to be enclosed in parentheses. For example,
you can define an array of structure variables as shown below:
war date 365 DUP (<,,1940>)
You need not initialize all fields in a structure. If an initial value is
left blank, the assembler automatically uses the default initial value of
the field, which was originally determined by the structure type. If there
is no default value, the field is undefined.
Examples
The following examples use the student type declared in the example in
Section 7.1.1, "Declaring Structure Types":
s1 student <> ; Uses default values of type
s2 student <1467,"White, Robert D.",>
; Override default values of first two
; fields--use default value of third
sarray student 100 DUP (<>) ; Declare 100 student variables
; with default initial values
Note that you cannot initialize any structure field that has multiple
values if this field was given a default initial value when the structure
was declared. For example, assume the following structure declaration:
stuff STRUC
buffer DB 100 DUP (?) ; Can't override
crlf DB 13,10 ; Can't override
query DB 'Filename: ' ; String <= can override
endmark DB 36 ; Can override
stuff ENDS
The buffer and crlf fields cannot be overridden by initial values in the
structure definition because they have multiple values. The query field
can be overridden as long as the overriding string is no longer than query
(10 bytes). A longer string would generate an error. The endmark field can
be overridden by any byte value.
7.1.3 Using Structure Operands
Like other variables, structure variables can be accessed by name. Fields
within structure variables can also be accessed by using the syntax shown
below:
Syntax
variable.field
The variable must be the name of a structure (or an operand that resolves
to the address of a structure). The field must be the name of a field
within that structure. The variable is separated from the field by a
period. The period is discussed as a structure-field-name operator in
Section 9.2.1.2.
The address of a structure operand is the sum of the offsets of variable
and field. The address is relative to the segment or group in which the
variable is declared.
Examples
date STRUC ; Declare structure
month DB ?
day DB ?
year DW ?
date ENDS
.DATA
yesterday date <9,30,1987> ; Declare structure
today date <10,1,1987> ; variables
tomorrow date <10,2,1987>
.CODE
.
.
.
mov al,yesterday.day ; Use structure variables
mov ah,today.month ; as operands
mov tomorrow.year,dx
mov bx,OFFSET yesterday ; Load structure address
mov ax,[bx].month ; Use as indirect operand
.
.
.
7.2 Records
A record variable is a byte or word variable in which specific bit fields
can be accessed symbolically. Bit fields within the record can have
different sizes.
There are two steps in declaring record variables:
1. Declare a record type. A record type is a template for data. It
declares the sizes and, optionally, the initial values for bit fields
in the record. By itself, the record type does not define any data. The
record type is used by Quick-Assembler during assembly but is not saved
as part of the object file.
2. Define one or more variables having the record type. For each variable
defined, memory is allocated to the object file in the format declared
by the type.
The record variable can then be used as an operand in assembler
statements. The record variable can be accessed as a whole by using the
record name, or individual fields can be specified by using the record
name and a field name combined with the field-name operator. A record type
can also be used as a constant (immediate data).
7.2.1 Declaring Record Types
The RECORD directive declares a record type for an 8-bit or 16-bit record
that contains one or more bit fields.
Syntax
recordname RECORD field [[,field]]...
The recordname is the name of the record type to be used when creating the
record. The field declares the name, width, and initial value for the
field.
The syntax for each field is shown below:
Syntax
fieldname:width[[=expression]]
The fieldname is the name of a field in the record, width is the number of
bits in the field, and expression is the initial (or default) value for
the field.
Any number of field combinations can be given for a record, as long as
each is separated from its predecessor by a comma. The sum of the widths
for all fields must not exceed 16 bits.
The width must be a constant. If the total width of all declared fields is
larger than eight bits, the assembler uses two bytes. Otherwise, only one
byte is used.
If expression is given, it declares the initial value for the field. An
error message is generated if an initial value is too large for the width
of its field. If the field is at least seven bits wide, you can use an
ASCII character for expression. The expression must not contain a forward
reference to any symbol.
In all cases, the first field you declare goes into the most significant
bits of the record. Successively declared fields are placed in the
succeeding bits to the right. If the fields you declare do not total
exactly 8 bits or exactly 16 bits, the entire record is shifted right so
that the last bit of the last field is the lowest bit of the record.
Unused bits in the high end of the record are initialized to 0.
Example 1
color RECORD blink:1,back:3,intense:1,fore:3
Example 1 creates a byte record type color having four fields: blink,
back, intense, and fore. The contents of the record type are shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 7.2.1 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Since no initial values are given, all bits are set to 0. Note that this
is only a template maintained by the assembler. No data is created.
Example 2
cw RECORD r1:3=0,ic:1=0,rc:2=0,pc:2=3,r2:2=1,masks:6=63
Example 2 creates a record type cw having six fields. Each record declared
by using this type occupies 16 bits of memory. The bit diagram below shows
the contents of the record type:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 7.2.1 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Default values are given for each field. They can be used when data is
declared for the record.
7.2.2 Defining Record Variables
A record variable is an 8-bit or 16-bit variable whose bits are divided
into one or more fields.
Syntax
[[name]] recordname <[[initialvalue [[,initialvalue]]...]]>
The name is the symbolic name of the variable. If no name is given, the
assembler allocates space for the variable, but does not give it a
symbolic name. The recordname is the name of a record type that was
previously declared by using the RECORD directive.
An initialvalue for each field in the record can be given as an integer, a
character constant, or an expression that resolves to a value compatible
with the size of the field. Angle brackets (< >) are required even if no
initial value is given. If initial values for more than one field are
given, the values must be separated by commas.
If the DUP operator (see Section 6.5.2, "Arrays and Buffers") is used to
initialize multiple record variables, only the angle brackets and initial
values, if given, need to be enclosed in parentheses. For example, you can
define an array of record variables as shown below:
xmas color 50 DUP (<1,2,0,4>)
You do not have to initialize all fields in a record. If an initial value
is left blank, the assembler automatically uses the default initial value
of the field. This is declared by the record type. If there is no default
value, each bit in the field is cleared.
Sections 7.2.3, "Using Record Operands and Record Variables," and 7.2.4,
"Record Operators," illustrate ways to use record data after it has been
declared.
Example 1
color RECORD blink:1,back:3,intense:1,fore:3 ; Record declaration
warning color <1,0,1,4> ; Record definition
The definition above creates a variable named warning whose type is given
by the record type color. The initial values of the fields in the variable
are set to the values given in the record definition. The initial values
would override the default record values, had any been given in the
declaration. The contents of the record variable are shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 7.2.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Example 2
color RECORD blink:1,back:3,intense:1,fore:3 ; Record declaration
colors color 16 DUP (<>) ; Record declaration
Example 2 creates an array named colors containing 16 variables of type
color. Since no initial values are given in either the declaration or the
definition, the variables have undefined (0) values.
Example 3
cw RECORD r1:3=0,ic:1=0,rc:2=0,pc:2=3,r2:2=1,masks:6=63
newcw cw <,,2,,,>
Example 3 creates a variable named newcw with type cw. The default values
set in the type declaration are used for all fields except the rc field.
This field is set to 2. The contents of the variable are shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 7.2.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
7.2.3 Using Record Operands and Record Variables
A record operand refers to the value of a record type. It should not be
confused with a record variable. A record operand is a constant; a record
variable is a value stored in memory. A record operand can be used with
the following syntax:
Syntax
recordname <[[value[[,value]]...]]>
The recordname must be the name of a record type declared in the source
file. The optional value is the value of a field in the record. If more
than one value is given, each value must be separated by a comma. Values
can include expressions or symbols that evaluate to constants. The
enclosing angle brackets (<>) are required, even if no value is given. If
no value for a field is given, the default value for that field is used.
Example
.DATA
color RECORD blink:1,back:3,intense:1,fore:3 ; Record declaration
window color <0,6,1,6> ; Record definition
.CODE
.
.
.
mov ah,color <0,3,0,2> ; Load record operand
; (constant value 32h
mov bh,window ; Load record variable
; (memory value 6Eh)
In this example, the record operand color <0,3,0,2> and the record
variable warning are loaded into registers. The contents of the values are
shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 7.2.3 of the manual │
└────────────────────────────────────────────────────────────────────────┘
7.2.4 Record Operators
The WIDTH and MASK operators are used exclusively with records to return
constant values representing different aspects of previously declared
records.
7.2.4.1 The MASK Operator
The MASK operator returns a bit mask for the bit positions in a record
occupied by the given record field. A bit in the mask contains a 1 if that
bit corresponds to a field bit. All other bits contain 0.
Syntax
MASK {recordfieldname | record}
The recordfieldname may be the name of any field in a previously defined
record. The record may be the name of any previously defined record. The
NOT operator is sometimes used with the MASK operator to reverse the bits
of a mask.
Example
.DATA
color RECORD blink:1,back:3,intense:1,fore:3
message color <0,5,1,1>
.CODE
.
.
.
mov ah,message ; Load initial 0101 1001
and ah,NOT MASK back ; Turn off AND 1000 1111
; "back" ---------
; 0000 1001
or ah,MASK blink ; Turn on OR 1000 0000
; "blink" ---------
; 1000 1001
xor ah,MASK intense ; Toggle XOR 0000 1000
; "intense" ---------
; 1000 0001
7.2.4.2 The WIDTH Operator
The WIDTH operator returns the width (in bits) of a record or record
field.
Syntax
WIDTH {recordfieldname | record}
The recordfieldname may be the name of any field defined in any record.
The record may be the name of any defined record.
Note that the width of a field is the number of bits assigned for that
field; the value of the field is the starting position (from the right) of
the field.
Examples
.DATA
color RECORD blink:1,back:3,intense:1,fore:3
wblink EQU WIDTH blink ; "wblink" = 1 "blink" = 7
wback EQU WIDTH back ; "wback" = 3 "back" = 4
wintense EQU WIDTH intense ; "wintense" = 1 "intense" = 3
wfore EQU WIDTH fore ; "wfore" = 3 "fore" = 0
wcolor EQU WIDTH color ; "wcolor" = 8
prompt color <1,5,1,1>
.CODE
.
.
.
IF (WIDTH color) GE 8 ; If color is 16 bit, load
mov ax,prompt ; into 16-bit register
ELSE ; else
mov al,prompt ; load into low 8-bit register
xor ah,ah ; and clear high 8-bit register
ENDIF
7.2.5 Using Record-Field Operands
Record-field operands represent the location of a field in its
corresponding record. The operand evaluates to the bit position of the
low-order bit in the field and can be used as a constant operand. The
field name must be from a previously declared record.
Record-field operands are often used with the WIDTH and MASK operators, as
described in Sections 7.2.4.1 and 7.2.4.2.
Example
.DATA
color RECORD blink:1,back:3,intense:1,fore:3 ; Record declaration
cursor color <1,5,1,1> ; Record definition
.CODE
.
.
.
; Rotate "back" of "cursor" without changing other values
mov al,cursor ; Load value from memory
mov ah,al ; Save a copy for work 1101 1001=
and al,NOT MASK back ; Mask out old bits AND 1000 1111=
; to save old cursor ---------
; 1000 1001=
mov cl,back ; Load bit position
shr ah,cl ; Shift to right 0000 1101=
inc ah ; Increment 0000 1110=
shl ah,cl ; Shift left again 1110 0000=
and ah,MASK back ; Mask off extra bits AND 0111 0000=
; to get new cursor ---------
; 0110 0000
or ah,al ; Combine old and new OR 1000 1001
; ---------
mov cursor,ah ; Write back to memory 1110 1001
This example illustrates several ways in which record fields can be used
as operands and in expressions.
────────────────────────────────────────────────────────────────────────────
Chapter 8: Creating Programs from Multiple Modules
Most medium and large assembly-language programs are created from several
source files or modules. When several modules are used, the scope of
symbols becomes important. This chapter discusses the scope of symbols and
explains how to declare global symbols that can be accessed from any
module. It also tells you how to specify a module that will be accessed
from a library.
Symbols, such as labels and variable names, can be either local or global
in scope. By default, all symbols are local; they are specific to the
source file in which they are defined. Symbols must be declared global if
they must be accessed from modules other than the one in which they are
defined.
To declare symbols global, they must be declared public in the source
module in which they are defined. They must also be declared external in
any module that must access the symbol. If the symbol represents
uninitialized data, it can be declared communal──meaning that the symbol
is both public and external. The PUBLIC, EXTRN, and COMM directives are
used to declare symbols public, external, and communal, respectively.
──────────────────────────────────────────────────────────────────────────
NOTE The term "local" often has a different meaning in assembly language
than in many high-level languages. Local symbols in compiled languages are
symbols that are known only within a procedure (called a function,
routine, subprogram, or subroutine, depending on the language). You can
use QuickAssembler to generate these kinds of variables, as explained in
Section 15.3.6, "Creating Locals Automatically."
By default, the assembler converts all lowercase letters in names declared
with the PUBLIC, EXTRN, and COMM directives to uppercase letters before
copying the name to the object file. To preserve lowercase names in public
symbols, choose Preserve Case or Preserve Extrn from the Assembler Flags
dialog box, or assemble with /Cx or /Cl on the QCL command line. This
should be done when preparing assembler modules to be linked with modules
from C and other case-sensitive languages.
──────────────────────────────────────────────────────────────────────────
8.1 Declaring Symbols Public
The PUBLIC directive is used to declare symbols public so that they can be
accessed from other modules. If a symbol is not declared public, the
symbol name is not written to the object file. The symbol has the value of
its offset address during assembly, but the name and address are not
available to the linker.
If the symbol is declared public, its name is associated with its offset
address in the object file. During linking, symbols in different
modules──but with the same name──are resolved to a single address.
Public symbol names are also used by some symbolic debuggers (such as
SYMDEB) to associate addresses with symbols.
Syntax
PUBLIC declaration [[,declaration]]...
Each declaration has the following syntax:
[[lang]] name
The optional lang field contains a language specifier that overrides the
language specified by the .MODEL directive. With this statement, the
language specifier determines naming conventions for the variable that it
precedes. The specifier can be C, FORTRAN, Pascal, or BASIC. The C naming
convention prefixes each variable with an underscore (_); the other
conventions do not. If you specify lang with the .MODEL directive, all
procedures are automatically public. However, you must use the PUBLIC
directive for any data that you want to access from other modules.
Note that using the C type specifier does not preserve case. You must
choose one of the assembler flags or options that preserve case.
The name must be the name of a variable, label, or numeric equate defined
within the current source file. PUBLIC declarations can be placed anywhere
in the source file. Equate names, if given, can only represent one-byte or
two-byte integer or string values. Text macros (or text equates) cannot be
declared public.
Note that although absolute symbols can be declared public, aliases for
public symbols may cause errors. For example, the following statements are
illegal:
PUBLIC lines ; Declare absolute symbol public
lines EQU rows ; Declare alias for lines
rows EQU 25 ; Illegal - Assign value to alias
Example
.MODEL small,c
PUBLIC true,status,first,clear
true EQU -1 ; Public constant
.DATA
status DB 1 ; Public variable
.CODE
.
.
.
first LABEL FAR ; Public label
clear PROC ; Procedure names are automatically public
. ; with .MODEL model, lang
.
.
clear ENDP
8.2 Declaring Symbols External
If a symbol undeclared in a module must be accessed by instructions in
that module, it must be declared with the EXTRN directive.
This directive tells the assembler not to generate an error, even though
the symbol is not in the current module. The assembler assumes that the
symbol occurs in another module. However, the symbol must actually exist
and must be declared public in some module. Otherwise, the linker
generates an error.
Syntax
EXTRN declaration [[,declaration]]...
Each declaration has the following syntax:
[[lang]]name:type
The optional lang field contains a language specifier that overrides the
language specified by the .MODEL directive. With this statement, the
language specifier determines naming conventions for the variable that it
precedes. The specifier can be C, FORTRAN, Pascal, or BASIC. The C naming
convention prefixes each variable with an underscore (_); the other
conventions do not.
Note that using the C type specifier does not preserve case. You must
choose one of the assembler flags or options that preserve case.
The EXTRN directive defines an external variable, label, or symbol of the
specified name and type. The type must match the type given to the item in
its actual definition in some other module. It can be any one of the
following:
Description Types
──────────────────────────────────────────────────────────────────────────
Distance specifier NEAR, FAR, or PROC
Size specifier BYTE, WORD, DWORD, QWORD, or TBYTE
Absolute ABS
The ABS type is for symbols that represent constant numbers, such as
equates declared with the EQU and = directives (see Section 11.1, "Using
Equates").
The PROC type represents the default type for a procedure. For programs
that use simplified segment directives, the type of an external symbol
declared with PROC will be NEAR for small or compact model, or FAR for
medium, large, or huge model. Section 5.1.3, "Defining Basic Attributes
of the Model," tells you how to declare the memory model using the .MODEL
directive. If full segment definitions are used, the default type
represented by PROC is always NEAR.
Although the actual address of an external symbol is not determined until
link time, the assembler assumes a default segment for the item, based on
where the EXTRN directive is placed in the source code. Placement of EXTRN
directives should follow these rules:
■ NEAR code labels (such as procedures) must be declared in the code
segment from which they are accessed.
■ FAR code labels can be declared anywhere in the source code. It may be
convenient to declare them in the code segment from which they are
accessed if the label may be FAR in one context or NEAR in another.
■ Data must be declared in the segment in which it occurs. This may
require that you define a dummy data segment for the external
declaration.
■ Absolute symbols can be declared anywhere in the source code.
Example 1
EXTRN max:ABS,act:FAR ; Constant or FAR label anywhere
DOSSEG
.MODEL small,c
.STACK 100h
.DATA
EXTRN nvar:BYTE ; NEAR variable in near data
.FARDATA
EXTRN fvar:WORD ; FAR variable in far data
.CODE
.STARTUP
EXTRN task:PROC ; PROC or NEAR in near code
ASSUME es:SEG fvar ; Tell assembler
mov ax,SEG fvar ; Tell processor that ES
mov es,ax ; has far data segment
.
.
.
mov ah,nvar ; Load external NEAR variable
mov bx,fvar ; Load external FAR variable
mov cx,max ; Load external constant
call task ; Call procedure (NEAR or FAR)
jmp act ; Jump to FAR label
END
The example above shows how each type of external symbol could be declared
and used in a small-model program that uses simplified segment directives.
Notice the use of the PROC type specifier to make the external-procedure
memory model independent. The jump and its external declaration are
written so that they will be FAR regardless of the memory model. Using
these techniques, you can change the memory model without breaking code.
Example 2
EXTRN max:ABS,act:FAR ; Constant or FAR label anywhere
STACK SEGMENT PARA STACK 'STACK'
DB 100h DUP (?)
STACK ENDS
_DATA SEGMENT WORD PUBLIC 'DATA'
EXTRN nvar:BYTE ; NEAR variable in near data
_DATA ENDS
FAR_DATA SEGMENT PARA 'FAR_DATA'
EXTRN fvar:WORD ; FAR variable in far data
FAR_DATA ENDS
DGROUP GROUP _DATA,STACK
_TEXT SEGMENT BYTE PUBLIC 'CODE'
EXTRN task:NEAR ; NEAR procedure in near code
ASSUME cs:_TEXT,ds:DGROUP,ss:STACK
start: mov ax,DGROUP ; Load segment
mov ds,ax ; into DS
ASSUME es:SEG fvar ; Tell assembler
mov ax,SEG fvar ; Tell processor that ES
mov es,ax ; has far data segment
.
.
.
mov ah,nvar ; Load external NEAR variable
mov bx,fvar ; Load external FAR variable
mov cx,max ; Load external constant
call task ; Call NEAR procedure
jmp act ; Jump to FAR label
_TEXT ENDS
END start
Example 2 shows a fragment similar to the one in Example 1, but with full
segment definitions. Notice that the types of code labels must be declared
specifically. If you wanted to change the memory model, you would have to
specifically change each external declaration and each call or jump.
8.3 Using Multiple Modules
The following source files illustrate a program that uses public and
external declarations to access instruction labels. The program consists
of two modules called hello and display.
The hello module is the program's initializing module. Execution starts at
the instruction labeled start in the hello module. After initializing the
data segment, the program calls the procedure display in the display
module, where a DOS call is used to display a message on the screen.
Execution then returns to the address after the call in the hello module.
The hello module is shown below:
TITLE hello
DOSSEG
.MODEL small,c
.STACK 256
.DATA
PUBLIC message, lmessage
message DB "Hello, world.",13,10
lmessage EQU $ - message
.CODE
EXTRN display:PROC ; Declare in near code segment
.STARTUP
call display ; Call other module
mov ax,04C00h ; Terminate with exit code 0
int 21h ; Call DOS
END
The display module is shown below:
TITLE display
EXTRN lmessage:ABS ; Declare anywhere
.MODEL small
.DATA
EXTRN message:BYTE ; Declare in near data segment
.CODE
display PROC
mov bx,1 ; File handle for standard output
mov cx,lmessage ; Message length
mov dx,OFFSET message ; Message address
mov ah,40h ; Write function
int 21h ; Call DOS
ret
display ENDP
END
The sample program is a variation of the HELLO.ASM program used in the
examples in Chapter 4, "Writing Stand-Alone Assembly Programs," except
that it uses an external procedure to display to the screen. Notice that
all symbols defined in one module but used in another are declared PUBLIC
in the defining module and declared EXTRN in the using module.
For instance, message and lmessage are declared PUBLIC in the program
HELLO.ASM and declared EXTRN in DISPLAY.ASM. The procedure display is
declared EXTRN in HELLO.ASM. The symbol display is automatically public in
the simplified segment version, but you would have to specifically declare
it PUBLIC if you used full segments.
To create an executable file for these modules, you can add both files to
the environment's Program List dialog box. You can also assemble the
modules with the following command line:
QCL hello.asm display.asm
The output is placed in the executable file HELLO.EXE.
For each source module, QuickAssembler writes a module name to the object
file. The module name is used by some debuggers and by the linker when it
displays error messages. With QuickAssembler, the module name is always
the base name of the source module file.
For compatibility, QuickAssembler recognizes the NAME directive. However,
NAME has no effect. Arguments to the directive are ignored.
8.4 Declaring Symbols Communal
Communal variables are uninitialized variables that are both public and
external. They are often declared in include files.
If a variable must be used by several assembly routines, you can declare
the variable communal in an include file, and then include the file in
each of the assembly routines. Although the variable is declared in each
source module, it exists at only one address. Using a communal variable in
an include file and including it in several source modules is an
alternative to defining the variable and declaring it public in one source
module and then declaring it external in other modules.
If a variable is declared communal in one module and public in another,
the public declaration takes precedence and the communal declaration has
the same effect as an external declaration.
Syntax
COMM definition[[,definition]]...
Each definition has the following syntax:
[[NEAR | FAR]] [[lang]] label:size[[:count]]
A communal variable can be NEAR or FAR. If neither is specified, the type
will be that of the default memory model. If you use simplified segment
directives, the default type is NEAR for small and medium models, or FAR
for compact, large, and huge models. If you use full segment definitions,
the default type is NEAR.
The optional lang field can be C, BASIC, FORTRAN, or Pascal. The use of
the C keyword turns on the C naming convention──the assembler prefixes the
name of the variable with an underscore (_). The use of any of the other
language types turns off the C naming convention, even if you specified C
with the .MODEL directive. Note that the use of C does not preserve case.
You must choose one of the assembler flags or options that preserve case.
The label is the name of the variable. The size can be BYTE, WORD, DWORD,
QWORD, TBYTE, or the name of a structure. The count is the number of
elements. If no count is given, one element is assumed. Multiple variables
can be defined with one COMM statement by separating each definition with
a comma.
──────────────────────────────────────────────────────────────────────────
NOTE C variables declared outside functions (except static variables) are
communal unless explicitly initialized; they are the same as
assembly-language communal variables. If you are writing assembly-language
modules for C, you can declare the same communal variables in C include
files and in QuickAssembler include files.
──────────────────────────────────────────────────────────────────────────
QuickAssembler cannot tell whether a communal variable has been used in
another module. Allocation of communal variables is handled by LINK. As a
result, communal variables have the following limitations that other
variables declared in assembly language do not have:
■ Communal variables cannot be initialized. Under DOS, initial values are
not guaranteed to be 0 or any other value. The variables can be used
for data, such as file buffers, that is not given a value until run
time.
■ Communal variables are not guaranteed to be allocated in the sequence
in which they are declared. Assembly-language techniques that depend on
the sequence and position in which data is defined should not be used
with communal variables. For example, the following statements do not
work:
COMM wbuffer:WORD:128
lbuffer EQU $ - buffer ; "lbuffer" won't have desired val
bbuffer LABEL BYTE ; "bbuffer" won't have desired add
COMM wbuffer:WORD:40
■ If a communal variable references a variable that is allocated and
declared public inside a module, the variable has the segment of the
allocated instance. If all references to the variable are communal, the
variable will be placed in one of the segments described below.
Near communal variables are placed in a segment called c_common, which
is part of DGROUP. This group is created and initialized automatically
if you use simplified segment directives. If you use full segment
definitions, you must create a group called DGROUP and use the ASSUME
directive to associate it with the DS register.
Far communal variables are placed in a segment called FAR_BSS. This
segment has combine type private and class type 'FAR_BSS'. This means
that multiple segments with the same name can be created. Such segments
cannot be accessed by name. They must be initialized indirectly using
the SEG operator. For example, if a far communal variable (with word
size) is called comvar, its segment can be initialized with the
following lines:
ASSUME ds:SEG comvar ; Tell the assembler
mov ax,SEG comvar ; Tell the processor
mov ds,ax
mov bx,comvar ; Use the variable
Example 1
.DATA
COMM temp:BYTE:128
ASCIIZ MACRO address ;; Name of address for string
mov temp,128 ;; Insert maximum length
mov dx,OFFSET temp ;; Address of string buffer
mov ah,0Ah ;; Get string
int 21h
mov dl,temp[1] ;; Get length of string
xor dh,dh
mov bx,dx
mov temp[bx+2],0 ;; Overwrite CR with null
address EQU OFFSET temp+2
ENDM
Example 1 shows an include file that declares a buffer for temporary data.
The buffer is then used in a macro in the same include file. An example of
how the macro could be used in a source file is shown below:
DOSSEG
.MODEL small,c
INCLUDE communal.inc
.STACK
.DATA
message DB "Enter file name: $"
.CODE
.STARTUP
.
.
.
mov dx,OFFSET message ; Load offset of file prompt
mov ah,09h ; Display prompt
int 21h
ASCIIZ place ; Get file name and
; return address as "place"
mov al,00000010b ; Load access code
mov dx,place ; Load address of ASCIIZ string
mov ah,3Dh ; Open the file
int 21h
.
.
.
Note that once the macro is written, the user does not need to know the
name of the temporary buffer or how it is used in the macro.
Example 2
date STRUC
month DB ?
day DB ?
year DB ?
date ENDS
.DATA
COMM today:date
.
.
.
The example above uses the COMM directive to make the structure variable
today a communal variable.
8.5 Specifying Library Files
The INCLUDELIB directive instructs the linker to link with a specified
library file. If you are writing a program that calls library routines,
you can use this directive to specify the library file in the assembly
source file rather than in the LINK command line.
Syntax
INCLUDELIB libraryname
The libraryname is written to the comment record of the object file. The
Intel title for this record is COMENT. At link time, the linker reads this
record and links with the specified library file.
The libraryname must be a file name rather than a complete file
specification. If you do not specify an extension, the default extension
.LIB is assumed. LINK searches directories for the library file in the
following order:
1. The current directory
2. Any directories given in the library field of the LINK command line
3. Any directories listed in the LIB environment variable
Example
INCLUDELIB graphics
This statement passes a message from QuickAssembler telling LINK to use
library routines from the file GRAPHICS.LIB. If this statement is included
in a source file called DRAW.ASM, the program might be linked with the
following command line:
LINK draw;
Without the INCLUDELIB directive, the program would have to be linked with
the following command line:
LINK draw,,,graphics;
────────────────────────────────────────────────────────────────────────────
Chapter 9: Using Operands and Expressions
Operands are the arguments that define values to be acted on by
instructions or directives. Operands can be constants, variables,
expressions, or keywords, depending on the instruction or directive and
the context of the statement.
A common type of operand is an expression. An expression consists of
several operands that are combined to describe a value or memory location.
Operators indicate the operations to be performed when combining the
operands of an expression.
Expressions are evaluated at assembly time. By using expressions, you can
instruct the assembler to calculate values that would be difficult or
inconvenient to calculate when you are writing source code.
This chapter discusses operands, expressions, and operators as they are
evaluated at assembly time. See Section 2.6, "Addressing Modes," for a
discussion of the addressing modes that can be used to calculate operand
values at run time. This chapter also discusses the location-counter
operand, forward references, and strong typing of operands.
9.1 Using Operands with Directives
Each directive requires a specific type of operand. Most directives take
string or numeric constants, or symbols or expressions that evaluate to
such constants.
The type of operand varies for each directive, but the operand must always
evaluate to a value that is known at assembly time. This differs from
instructions, whose operands may not be known at assembly time and may
vary at run time. Operands used with instructions are discussed in Section
2.6, "Addressing Modes."
Some directives, such as those used in data declarations, accept labels or
variables as operands. When a symbol that refers to a memory location is
used as an operand to a directive, the symbol represents the address of
the symbol rather than its contents. This is because the contents may
change at run time and are therefore not known at assembly time.
Example 1
ORG 100h ; Set address to 100h
var DB 10h ; Address of "var" is 100h
; Value of "var" is 10h
pvar DW var ; Address of "pvar" is 101h
; Value of "pvar" is
; address of "var" (100h)
In Example 1, the operand of the DW directive in the third statement
represents the address of var (100h) rather than its contents (10h). The
address is relative to the start of the segment in which var is defined.
Example 2
TITLE doit ; String
_TEXT SEGMENT BYTE PUBLIC 'CODE' ; Key words
INCLUDE \include\bios.inc ; Pathname
.RADIX 16 ; Numeric constant
tst DW a / b ; Numeric expression
PAGE + ; Special character
sum EQU x * y ; Numeric expression
here LABEL WORD ; Type specifier
Example 2 illustrates the different kinds of values that can be used as
directive operands.
9.2 Using Operators
The assembler provides a variety of operators for combining, comparing,
changing, or analyzing operands. Some operators work with integer
constants, some with memory values, and some with both. Operators cannot
be used with floating-point constants since QuickAssembler does not
recognize real numbers in expressions.
It is important to understand the difference between operators and
instructions. Operators handle calculations of constant values that are
known at assembly time. Instructions handle calculations of values that
may not be known until run time. For example, the addition operator (+)
handles assembly-time addition, while the ADD and ADC instructions handle
run-time addition.
This section describes the different kinds of operators used in
assembly-language statements and gives examples of expressions formed with
them. In addition to the operators described in this chapter, you can use
the DUP operator (Section 6.5.2, "Arrays and Buffers"), the record
operators (Section 7.2.4, "Record Operators"), and the macro operators
(Section 11.4, "Using Macro Operators").
9.2.1 Calculation Operators
QuickAssembler provides the common arithmetic operators as well as several
other operators for adding, shifting, or doing bit manipulations. The
sections below describe operators that can be used for doing numeric
calculations.
9.2.1.1 Arithmetic Operators
QuickAssembler recognizes a variety of arithmetic operators for common
mathematical operations. Table 9.1 lists the arithmetic operators.
Table 9.1 Arithmetic Operators
Operator Syntax Meaning
──────────────────────────────────────────────────────────────────────────
+ +expression Positive (unary)
- -expression Negative (unary)
* expression1 * expression2 Multiplication
/ expression1 / expression2 Integer division
MOD expression1 MOD expression2 Remainder (modulus)
+ expression1 + expression2 Addition
- expression1 - expression2 Subtraction
──────────────────────────────────────────────────────────────────────────
For all arithmetic operators except the addition operator (+) and the
subtraction operator (-), the expressions operated on must be integer
constants.
The addition and subtraction operators can be used to add or subtract an
integer constant and a memory operand. The result can be used as a memory
operand.
The subtraction operator can also be used to subtract one memory operand
from another, but only if the operands refer to locations within the same
segment. The result will be a constant, not a memory operand.
──────────────────────────────────────────────────────────────────────────
NOTE The unary plus and minus operators (used to designate positive or
negative numbers) are not the same as the binary plus and minus operators
(used to designate addition or subtraction). The unary plus and minus
operators have a higher level of precedence, as described in Section
9.2.5, "Operator Precedence."
──────────────────────────────────────────────────────────────────────────
Example 1
intgr = 14 * 3 ; = 42
intgr = intgr / 4 ; 42 / 4 = 10
intgr = intgr MOD 4 ; 10 mod 4 = 2
intgr = intgr + 4 ; 2 + 4 = 6
intgr = intgr - 3 ; 6 - 3 = 3
intgr = -intgr - 8 ; -3 - 8 = -11
intgr = -intgr - intgr ; 11 - -11 = 22
Example 1 illustrates arithmetic operators used in integer expressions.
Example 2
ORG 100h
a DB ? ; Address is 100h
b DB ? ; Address is 101h
mem1 EQU a + 5 ; mem1 = 100h + 5 = 105h
mem2 EQU a - 5 ; mem2 = 100h - 5 = 0FBh
const EQU b - a ; const = 101h - 100h = 1
Example 2 illustrates arithmetic operators used in memory expressions.
9.2.1.2 Structure-Field-Name Operator
The structure-field-name operator (.) indicates addition. It is used to
designate a field within a structure.
Syntax
variable.field
The variable is a memory operand (usually a previously declared structure
variable), and field is the name of a field within the structure. See
Section 7.1, "Structures," for more information.
Example
.DATA
date STRUC ; Declare structure
month DB ?
day DB ?
year DW ?
date ENDS
yesterday date <12,31,1987> ; Define structure variables
today date <1,1,1988>
.CODE
.
.
.
mov bh,yesterday.day ; Load structure variable
mov bx,OFFSET today ; Load structure variable address
inc [bx].year ; Use in indirect memory operand
9.2.1.3 Index Operator
The index operator ([ ]) indicates addition. It is similar to the addition
(+) operator. When used with a register, the index operator also indicates
that the operand is an indirect memory operand rather than a
register-direct operand.
Syntax
[[expression1]][expression2]
In most cases expression1 is simply added to expression2. The limitations
of the addition operator for adding memory operands also apply to the
index operator. For example, two direct memory operands cannot be added.
The expression label1[label2] is illegal if both are memory operands.
The index operator has an extended function in specifying indirect memory
operands. Section 2.6.4 explains the use of indirect memory operands. The
index brackets must be outside the register or registers that specify the
indirect displacement. However, any of the three operators that indicate
addition (the addition operator, the index operator, or the
structure-field-name operator) may be used for multiple additions within
the expression.
For example, the following statements are equivalent:
mov ax,table[bx][di]
mov ax,table[bx+di]
mov ax,[table+bx+di]
mov ax,[table][bx][di]
The following statements are illegal because the index operator does not
enclose the registers that specify indirect displacement:
mov ax,table+bx+di ; Illegal - no index operator
mov ax,[table]+bx+di ; Illegal - registers not
; inside index operator
The index operator is typically used to index elements of a data object,
such as variables in an array or characters in a string.
Example 1
mov al,string[3] ; Get 4th element of string
add ax,array[4] ; Add 5th element of array
mov string[7],al ; Load into 8th element of string
Example 1 illustrates the index operator used with direct memory operands.
Example 2
mov ax,[bx] ; Get element BX points to
add ax,array[si] ; Add element SI points to
mov string[di],al ; Load element DI points to
cmp cx,table[bx][di] ; Compare to element BX and DI point
Example 2 illustrates the index operator used with indirect memory
operands.
9.2.1.4 Shift Operators
The SHR and SHL operators can be used to shift bits in constant values.
Both perform logical shifts. Bits on the right for SHL and on the left for
SHR are zero-filled as their contents are shifted out of position.
Syntax
expression SHR count
expression SHL count
The expression is shifted right or left by count number of bits. Bits
shifted off either end of the expression are lost. If count is greater
than or equal to 16, the result is 0.
Do not confuse the SHR and SHL operators with the processor instructions
having the same names. The operators work on integer constants only at
assembly time. The processor instructions work on register or memory
values at run time. The assembler can tell the difference between
instructions and operands from context.
Examples
mov ax,01110111b SHL 3 ; Load 01110111000b
mov ah,01110111b SHR 3 ; Load 01110b
9.2.1.5 Bitwise Logical Operators
The bitwise operators perform logical operations on each bit of an
expression. The expressions must resolve to constant values. Table 9.2
lists the logical operators and their meanings.
Table 9.2 Logical Operators
Operator Syntax Meaning
──────────────────────────────────────────────────────────────────────────
NOT NOT expression Bitwise complement
AND expression1 AND expression2 Bitwise AND
OR expression1 OR expression2 Bitwise inclusive OR
XOR expression1 XOR expression2 Bitwise exclusive XOR
──────────────────────────────────────────────────────────────────────────
Do not confuse the NOT, AND, OR, and XOR operators with the processor
instructions having the same names. The operators work on integer
constants only at assembly time. The processor instructions work on
register or memory values at run time. The assembler can tell the
difference between instructions and operands from context.
──────────────────────────────────────────────────────────────────────────
NOTE Although calculations on expressions using the AND, OR, and XOR
operators are done using 17-bit numbers, the results are truncated to 16
bits.
──────────────────────────────────────────────────────────────────────────
Examples
mov ax,NOT 11110000b ; Load 1111111100001111b
mov ah,NOT 11110000b ; Load 00001111b
mov ah,01010101b AND 11110000b ; Load 01010000b
mov ah,01010101b OR 11110000b ; Load 11110101b
mov ah,01010101b XOR 11110000b ; Load 10100101b
9.2.2 Relational Operators
The relational operators compare two expressions and return true (-1) if
the condition specified by the operator is satisfied, or false (0) if it
is not. The expressions must resolve to constant values. Relational
operators are typically used with conditional directives. Table 9.3 lists
the operators and the values they return if the specified condition is
satisfied.
Table 9.3 Relational Operators
Operator Syntax Returned Value
──────────────────────────────────────────────────────────────────────────
EQ expression1 EQ expression2 True if expressions are equal
NE expression1 NE expression2 True if expressions are not
equal
LT expression1 LT expression2 True if left expression is
less than right
LE expression1 LE expression2 True if left expression is
less than or equal to right
GT expression1 GT expression2 True if left expression is
greater than right
GE expression1 GE expression2 True if left expression is
greater than or equal to right
──────────────────────────────────────────────────────────────────────────
Note that the EQ and NE operators treat their arguments as 16-bit numbers.
Numbers specified with the 16th bit set are considered negative. For
example, the expression -1 EQ OFFFFh is true, but the expression -1 NE
OFFFFh is false.
The LT, LE, GT, and GE operators treat their arguments as 17-bit numbers,
in which the 17th bit specifies the sign. For example, OFFFFh is 65,535,
not -1. The expression 1 GT -1 is true, but the expression 1 GT OFFFFh is
false.
Examples
mov ax,4 EQ 3 ; Load false( 0)
mov ax,4 NE 3 ; Load true (-1)
mov ax,4 LT 3 ; Load false( 0)
mov ax,4 LE 3 ; Load false( 0)
mov ax,4 GT 3 ; Load true (-1)
mov ax,4 GE 3 ; Load true(-1)
9.2.3 Segment-Override Operator
The segment-override operator (:) forces the address of a variable or
label to be computed relative to a specific segment.
Syntax
segment:expression
The segment can be specified in several ways. It can be one of the segment
registers: CS, DS, SS, or ES. It can also be a segment or group name. In
this case, the name must have been previously defined with a SEGMENT or
GROUP directive and assigned to a segment register with an ASSUME
directive. The expression can be a constant, expression, or a SEG
expression. See Section 9.2.4.5 for more information on the SEG operator.
Note that when a segment override is given with an indexed operand, the
segment must be specified outside the index operators. For example,
es:[di] is correct, but [es:di] generates an error.
Examples
mov ax,ss:[bx+4] ; Override default assume (DS)
mov al,es:082h ; Load from ES
ASSUME ds:FAR_DATA ; Tell the assembler and
mov bx,FAR_DATA:count ; load from a far segment
As shown in the last two statements, a segment override with a segment
name is not enough if no segment register is assumed for the segment name.
You must use the ASSUME directive to assign a segment register, as
explained in Section 5.4, "Associating Segments with Registers."
9.2.4 Type Operators
This section describes the assembler operators that specify or analyze the
types of memory operands and other expressions.
9.2.4.1 PTR Operator
The PTR operator specifies the type for a variable or label.
Syntax
type PTR expression
The operator forces expression to be treated as having type. The
expression can be any operand. The type can be BYTE, WORD, DWORD, QWORD,
or TBYTE for memory operands. It can be NEAR, FAR, or PROC for labels.
The PTR operator is typically used with forward references to define
explicitly what size or distance a reference has. If it is not used, the
assembler assumes a default size or distance for the reference. See
Section 9.4 for more information on forward references.
The PTR operator is also used to enable instructions to access variables
in ways that would otherwise generate errors. For example, you could use
the PTR operator to access the high-order byte of a WORD size variable.
The PTR operator is required for FAR calls and jumps to forward-referenced
labels.
Example 1
.DATA
stuff DD ?
buffer DB 20 DUP (?)
.CODE
.
.
.
call FAR PTR task ; Call a far procedure
jmp FAR PTR place ; Jump far
mov bx,WORD PTR stuff[0] ; Load a word from a
; doubleword variable
add ax,WORD PTR buffer[bx] ; Add a word from a byte variab
The PTR operator can be used to specify the size of an indirect register
operand for a CALL or JMP instruction. However, the size cannot be
specified with NEAR or FAR. Use WORD or DWORD instead. Examples are shown
below:
Example 2
jmp WORD PTR [bx] ; Legal near jump
call NEAR PTR [bx] ; Illegal near call
call DWORD PTR [bx] ; Legal far call
jmp FAR PTR [bx] ; Illegal far jump
This limitation only applies to indirect register operands. NEAR or FAR
can be applied to operands associated with labels, as shown in Example 1.
Furthermore, use NEAR or FAR with an indirect operand that combines a
register with a label.
9.2.4.2 SHORT Operator
The SHORT operator sets the type of a specified label to SHORT. Short
labels can be used in JMP instructions whenever the distance from the
label to the instruction is less than 128 bytes.
Syntax
SHORT label
Instructions using short labels are a byte smaller than identical
instructions using the default near labels. See Section 9.4.1, "Forward
References to Labels," for information on using the SHORT operator with
jump instructions.
Example
jmp again ; Jump 128 bytes or more
.
.
.
jmp SHORT again ; Jump less than 128 bytes
.
.
.
again:
9.2.4.3 THIS Operator
The THIS operator creates an operand whose offset and segment values are
equal to the current location-counter value and whose type is specified by
the operator.
Syntax
THIS type
The type can be BYTE, WORD, DWORD, QWORD, or TBYTE for memory operands. It
can be NEAR, FAR, or PROC for labels.
The THIS operator is typically used with the EQU or equal-sign (=)
directive to create labels and variables. The result is similar to using
the LABEL directive.
Example
tag1 EQU THIS BYTE ; Both represent the same variable
tag2 LABEL BYTE
check1 EQU THIS NEAR ; All represent the same address
check2 LABEL NEAR
check3:
check4 PROC NEAR
check4 ENDP
9.2.4.4 HIGH and LOW Operators
The HIGH and LOW operators return the high and low bytes, respectively, of
an expression.
Syntax
HIGH expression
LOW expression
The HIGH operator returns the high-order eight bits of expression; the LOW
operator returns the low-order eight bits. The expression must evaluate to
a constant. You cannot use the HIGH and LOW operators on the contents of a
memory operand since the contents may change at run time.
Examples
stuff EQU 0ABCDh
mov ah,HIGH stuff ; Load 0ABh
mov al,LOW stuff ; Load 0CDh
The HIGH and LOW operators work reliably only with constants and with
offsets to external symbols. HIGH and LOW operations are not supported for
offsets to local symbols.
9.2.4.5 SEG Operator
The SEG operator returns the segment address of an expression.
Syntax
SEG expression
The expression can be any label, variable, segment name, group name, or
other memory operand. The SEG operator cannot be used with constant
expressions. The returned value can be used as a memory operand.
Example
.DATA
var DB ?
.CODE
.
.
.
ASSUME ds:SEG var ; Assume segment of variable
mov ax,SEG var ; Get address of segment
mov ds,ax ; where variable is declared
9.2.4.6 OFFSET Operator
The OFFSET operator returns the offset address of an expression.
Syntax
OFFSET expression
The expression can be any label, variable, or other direct memory operand.
Constant expressions return meaningless values. The value returned by the
OFFSET operand is an immediate (constant) operand.
If the MODEL directive is used, the value returned by the OFFSET operator
is relative to a group, whenever the data item is declared in a segment
that is part of a group. The OFFSET operator returns the number of bytes
between the beginning of the group and the data object. If the object is
declared in a segment not part of a group, OFFSET returns the number of
bytes between the beginning of the segment and the data object.
If the MODEL directive is not used, OFFSET returns a value relative to the
beginning of the segment, regardless of whether the segment is part of a
group.
If full segment definitions are given, the returned value is a memory
operand equal to the number of bytes between the item and the beginning of
the segment in which it is defined.
The segment-override operator (:) can be used to force OFFSET to return
the number of bytes between the item in expression and the beginning of a
named segment or group. This is the method used to generate valid offsets
for items in a group when full segment definitions are used. For example,
the statement
mov bx,OFFSET DGROUP:array
is not the same as
mov bx,OFFSET array
if array is not in the first segment in DGROUP.
Example
.DATA
string DB "This is it."
.CODE
.
.
.
mov dx,OFFSET string ; Load offset of variable
9.2.4.7 .TYPE Operator
The .TYPE operator returns a byte that defines the mode and scope of an
expression.
Syntax
.TYPE expression
If expression is not valid, .TYPE returns 0. Otherwise, .TYPE returns a
byte having the bit setting shown in Table 9.4. The .TYPE operator sets
all bits except bit 6. Future versions of the assembler may reserve a use
for this bit.
Table 9.4 .TYPE Operator and Variable Attributes
Bit Position If Bit = 0 If Bit = 1
──────────────────────────────────────────────────────────────────────────
0 Not program related Program related
1 Not data related Data related
2 Not a constant value Constant value
3 Addressing mode is not direct Addressing mode is direct
4 Not a register Expression is a register
5 Not defined Defined
7 Local or public scope External scope
──────────────────────────────────────────────────────────────────────────
The .TYPE operator is typically used in macros in which different kinds of
arguments may need to be handled differently.
Example
display MACRO string
IF ((.TYPE string) SHL 14) NE 8000h
IF2
%OUT Argument must be a variable
ENDIF
ENDIF
mov dx,OFFSET string
mov ah,09h
int 21h
ENDM
This macro checks to see if the argument passed to it is data related (a
variable). It does this by shifting all bits except the relevant bits (1
and 0) to the left so that they can be checked. If the data bit is not
set, an error message is generated.
9.2.4.8 TYPE Operator
The TYPE operator returns a number that represents the type of an
expression.
Syntax
TYPE expression
If expression evaluates to a variable, the operator returns the number of
bytes in each data object in the variable. Each byte in a string is
considered a separate data object, so the TYPE operator returns 1 for
strings.
If expression evaluates to a structure or structure variable, the operator
returns the number of bytes in the structure. If the expression is a
label, the operator returns 0FFFFH for NEAR labels and 0FFFEH for FAR
labels. If the expression is a constant, the operator returns 0.
9.2.4.9 LENGTH Operator
The LENGTH operator returns the number of data elements in an array or
other variable defined with the DUP operator.
Syntax
LENGTH variable
The returned value is the number of elements of the declared size in
variable. If the variable was declared with nested DUP operators, only the
value given for the outer DUP operator is returned. If the variable was
not declared with the DUP operator, the value returned is always 1.
Example
array DD 100 DUP(0FFFFFFh)
table DW 100 DUP(1,10 DUP(?))
string DB 'This is a string'
var DT ?
larray EQU LENGTH array ; 100 - number of elements
ltable EQU LENGTH table ; 100 - inner DUP not counted
lstring EQU LENGTH string ; 1 - string is one element
lvar EQU LENGTH var ; 1
.
.
.
mov cx,LENGTH array ; Load number of elements
again: . ; Perform some operation on
. ; each element
.
loop again
9.2.4.10 SIZE Operator
The SIZE operator returns the total number of bytes allocated for an array
or other variable defined with the DUP operator.
Syntax
SIZE variable
The returned value is equal to the value of LENGTH variable times the
value of TYPE variable. If the variable was declared with nested DUP
operators, only the value given for the outside DUP operator is
considered. If the variable was not declared with the DUP operator, the
value returned is always TYPE variable.
Example
array DD 100 DUP(1)
table DW 100 DUP(1,10 DUP(?))
string DB 'This is a string'
var DT ?
sarray EQU SIZE array ; 400 - elements times size
stable EQU SIZE table ; 200 - inner DUP ignored
sstring EQU SIZE string ; 1 - string is one element
svar EQU SIZE var ; 10 - bytes in variable
.
.
.
mov cx,SIZE array ; Load number of bytes
again: . ; Perform some operation on
. ; each byte
.
loop again
9.2.5 Operator Precedence
Expressions are evaluated according to the following rules:
■ Operations of highest precedence are performed first.
■ Operations of equal precedence are performed from left to right.
■ The order of evaluation can be overridden by using parentheses.
Operations in parentheses are always performed before any adjacent
operations.
The order of precedence for all operators is listed in Table 9.5.
Operators on the same line have equal precedence.
Table 9.5 Operator Precedence
Precedence Operators
──────────────────────────────────────────────────────────────────────────
(Highest)
1 LENGTH, SIZE, WIDTH, MASK, (), [],<>
2 . (structure-field-name operator)
3 :
4 PTR, OFFSET, SEG, TYPE, THIS
5 HIGH, LOW
6 +,- (unary)
7 *,/, MOD, SHL, SHR
8 +, - (binary)
9 EQ, NE, LT, LE, GT, GE
10 NOT
11 AND
12 OR, XOR
13 SHORT, .TYPE
(Lowest)
──────────────────────────────────────────────────────────────────────────
Examples
a EQU 8 / 4 * 2 ; Equals 4
b EQU 8 / (4 * 2) ; Equals 1
c EQU 8 + 4 * 2 ; Equals 16
d EQU (8 + 4) * 2 ; Equals 24
e EQU 8 OR 4 AND 2 ; Equals 8
f EQU (8 OR 4) AND 3 ; Equals 0
9.3 Using the Location Counter
The location counter is a special operand that, during assembly,
represents the address of the statement currently being assembled. At
assembly time, the location counter keeps changing, but when used in
source code, it resolves to a constant representing an address.
The location counter has the same attributes as a near label. It
represents an offset that is relative to the current segment and is equal
to the number of bytes generated for the segment to that point.
Example 1
string DB "Who wants to count every byte in a string, "
DB "especially if you might change it later."
lstring EQU $-string ; Let the assembler do it
Example 1 shows one way of using the location-counter operand in
expressions relating to data.
Example 2
cmp ax,bx
jl shortjump ; If ax < bx, go to "shortjump"
. ; else if ax >= bx, continue
.
shortjump: .
cmp ax,bx
jge $+5 ; If ax >= bx, continue
jmp longjump ; else if ax < bx, go to "longjump"
. ; This is "$+5"
.
longjump: .
Example 2 illustrates how you can use the location counter to do
conditional jumps of more than 128 bytes. The first part shows the normal
way of coding jumps of less than 128 bytes, and the second part shows how
to code the same jump when the label is more than 128 bytes away.
9.4 Using Forward References
The assembler permits you to refer to labels, variable names, segment
names, and other symbols before they are declared in the source code. Such
references are called forward references.
The assembler handles forward references by making assumptions about them
on the first pass and then attempting to correct the assumptions, if
necessary, on the second pass. Checking and correcting assumptions on the
second pass takes processing time, so source code with forward references
assembles more slowly than source code with no forward references.
In addition, the assembler may make incorrect assumptions that it cannot
correct, or corrects at a cost in program efficiency.
9.4.1 Forward References to Labels
Forward references to labels may result in incorrect or inefficient code.
In the statement below, the label target is a forward reference:
jmp target ; Generates 3 bytes in 16-bit segmen
.
.
.
target:
Since the assembler processes source files sequentially, target is unknown
when it is first encountered. It could be one of three types: short (-128
to 127 bytes from the jump), near (-32,768 to 32,767 bytes from the jump),
or far (in a different segment than the jump). QuickAssembler assumes that
target is a near label, and assembles the number of bytes necessary to
specify a near label: one byte for the instruction and two bytes for the
operand.
If, on the second pass, the assembler learns that target is a short label,
it will need only two bytes: one for the instruction and one for the
operand. However, it will not be able to change its previous assembly and
the three-byte version of the assembly will stand. If the assembler learns
that target is a far label, it will need five bytes. Since it can't make
this adjustment, it will generate a phase error.
You can override the assembler's assumptions by specifying the exact size
of the jump. For example, if you know that a JMP instruction refers to a
label less than 128 bytes from the jump, you can use the SHORT operator,
as shown below:
jmp SHORT target ; Generates 2 bytes
.
.
.
target:
Using the SHORT operator makes the code smaller and slightly faster. If
the assembler has to use the three-byte form when the two-byte form would
be acceptable, it will generate a warning message if the warning level is
2. (The warning level can be set with the /W option, as described in
Appendix B, Section B.16.) You can ignore the warning, or you can go
back to the source code and change the code to eliminate the forward
references.
──────────────────────────────────────────────────────────────────────────
NOTE The SHORT operator in the example above would not be needed if
target were located before the jump. The assembler would have already
processed target and would be able to make adjustments based on its
distance.
──────────────────────────────────────────────────────────────────────────
If you use the SHORT operator when the label being jumped to is more than
128 bytes away, QuickAssembler generates an error message. You can either
remove the SHORT operator, or try to reorganize your program to reduce the
distance.
If a far jump to a forward-referenced label is required, you must override
the assembler's assumptions with the FAR and PTR operators, as shown
below:
jmp FAR PTR target ; Generates 5 bytes
.
.
.
target: ; In different segment
If the type of a label has been established earlier in the source code
with an EXTRN directive, the type does not need to be specified in the
jump statement.
9.4.2 Forward References to Variables
When QuickAssembler encounters code referencing variables that have not
yet been defined in pass 1, it makes assumptions about the segment where
the variable will be defined. If on pass 2 the assumptions turn out to be
wrong, an error will occur.
These problems usually occur with complex segment structures that do not
follow the Microsoft segment conventions. The problems never appear if
simplified segment directives are used.
By default, QuickAssembler assumes that variables are referenced to the DS
register. If a statement must access a variable in a segment not
associated with the DS register, and if the variable has not been defined
earlier in the source code, you must use the segment-override operator to
specify the segment.
The situation is different if neither the variable nor the segment in
which it is defined has been defined earlier in the source code. In this
case, you must assign the segment to a group earlier in the source code.
QuickAssembler will then know about the existence of the segment even
though it has not yet been defined.
9.5 Strong Typing for Memory Operands
The assembler carries out strict syntax checks for all instruction
statements, including strong typing for operands that refer to memory
locations. This means that when an instruction uses two operands with
implied data types, the operand types must match. Warning messages are
generated for nonmatching types.
For example, in the following fragment, the variable string is incorrectly
used in a move instruction:
.DATA
string DB "A message."
.CODE
.
.
.
mov ax,string[1]
The ax register has WORD type, but string has BYTE type. Therefore, the
statement generates the following warning message:
Operand types must match
To avoid all ambiguity and prevent the warning error, use the PTR operator
to override the variable's type, as shown below:
mov ax,WORD PTR string[1]
You can ignore the warnings if you are willing to trust the assembler's
assumptions. When a register and memory operand are mixed, the assembler
assumes that the register operand is always the correct size. For example,
in the statement
mov ax,string[1]
the assembler assumes that the programmer wishes the word size of the
register to override the byte size of the variable. A word starting at
string[1] will be moved into AX. In the statement
mov string[1],ax
the assembler assumes that the programmer wishes to move the word value in
AX into the word starting at string[1]. However, the assembler's
assumptions are not always as clear as in these examples. You should not
ignore warnings about type mismatches unless you are sure you understand
how your code will be assembled.
──────────────────────────────────────────────────────────────────────────
NOTE Some assemblers (including early versions of the IBM Macro
Assembler) do not do strict type checking. For compatibility with these
assemblers, type errors are warnings rather than severe errors. Many
assembly-language program listings in books and magazines are written for
assemblers with weak type checking. Such programs may produce warning
messages, but assemble correctly. You can use the /W option to turn off
type warnings if you are sure the code is correct.
──────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────
Chapter 10: Assembling Conditionally
QuickAssembler provides two types of conditional directives,
conditional-assembly and conditional-error directives.
Conditional-assembly directives test for a specified condition and
assemble a block of statements if the condition is true. Conditional-error
directives test for a specified condition and generate an assembly error
if the condition is true.
Both kinds of conditional directives test assembly-time conditions. They
cannot test run-time conditions. Only expressions that evaluate to
constants during assembly can be compared or tested.
Since macros and conditional-assembly directives are often used together,
you may need to refer to Chapter 11, "Using Equates, Macros, and Repeat
Blocks," to understand some of the examples in this chapter. In
particular, conditional directives are frequently used with the operators
described in Section 11.5, "Using Macro Operators."
10.1 Using Conditional-Assembly Directives
The conditional-assembly directives include the following:
ELSE IFB IFIDN
ENDIF IFDEF IFIDNI
IF IFDIF IFNB
IF1 IFDIFI IFNDEF
IF2 IFE
The IF directives and the ENDIF and ELSE directives can be used to enclose
the statements to be considered for conditional assembly.
Syntax
IFcondition
statements
[[ELSEIFcondition
statements]]
.
.
.
[[ELSE
statements]]
ENDIF
The statements following the IF directive can be any valid statements,
including other conditional blocks. The ELSEIF and ELSE blocks are
optional. The conditional block can contain any number of ELSEIF blocks.
(The ELSEIF directives are listed in Section 10.1.6.) ENDIF ends the
block.
The statements following the IF directive are assembled only if the
corresponding condition is true. If the condition is not true and an
ELSEIF directive is used, the assembler checks to see if the corresponding
condition is true. If so, it assembles the statements following the ELSEIF
directive. If no IF or ELSEIF conditions are satisifed, the statements
following the ELSE directive are assembled.
IF statements can be nested up to 20 levels. A nested ELSE or ELSEIF
directive always belongs to the nearest preceding IF statement that does
not have its own ELSE directive.
10.1.1 Testing Expressions with IF and IFE Directives
The IF and IFE directives test the value of an expression and grant
assembly based on the result.
Syntax
IF expression
IFE expression
The IF directive grants assembly if the value of expression is true
(nonzero). The IFE directive grants assembly if the value of expression is
false (0). The expression must evaluate to a constant value and must not
contain forward references.
Example
IF debug GT 20
push debug
call adebug
ELSEIF debug GT 10
call bdebug
ELSE
call cdebug
ENDIF
In this example, a different debug routine will be called, depending on
the value of debug.
10.1.2 Testing the Pass with IF1 and IF2 Directives
The IF1 and IF2 directives test the current assembly pass and grant
assembly only on the pass specified by the directive. Multiple passes of
the assembler are discussed in Appendix C, Section C.7, "Reading a Pass
1 Listing."
Syntax
IF1
IF2
The IF1 directive grants assembly only on pass 1. The IF2 directive grants
assembly only on pass 2. The directives take no arguments. If you turn on
the One-Pass Assembly option, the IF2 directive produces an error.
Macros usually only need to be processed once. You can enclose blocks of
macros in IF1 blocks to prevent them from being reprocessed on the second
pass.
Example
IF1 ; Define on first pass only
dostuff MACRO argument
.
.
.
ENDM
ENDIF
10.1.3 Testing Symbol Definition with IFDEF and IFNDEF Directives
The IFDEF and IFNDEF directives test whether a symbol has been defined and
grant assembly based on the result.
Syntax
IFDEF name
IFNDEF name
The IFDEF directive grants assembly only if name is a defined label,
variable, or symbol. The IFNDEF directive grants assembly if name has not
yet been defined.
The name can be any valid name. Note that if name is a forward reference,
it is considered undefined on pass 1, but defined on pass 2.
Example
IFDEF buffer
buff DB buffer DUP(?)
ENDIF
In this example, buff is allocated only if buffer has been previously
defined.
One way to use this conditional block is to leave buffer undefined in the
source file and define it if needed by using the /Dsymbol option (see
Appendix B, Section B.4, "Defining Assembler Symbols") when you start
QuickAssembler. For example, if the conditional block is in TEST.ASM, you
could start the assembler with the following command line:
QCL /Dbuffer=1024 test.asm
You could also define the symbol buffer by entering buffer=1024 in the
Defines field of the Assembler Flags dialog box.
The command line would define the symbol buffer. As a result, the
conditional-assembly block would allocate buff. However, if you didn't
need buff, you could use the following command line:
QCL test.asm
10.1.4 Verifying Macro Parameters with IFB and IFNB Directives
The IFB and IFNB directives test to see if a specified argument was passed
to a macro and grant assembly based on the result.
Syntax
IFB <argument >
IFNB <argument>
These directives are always used inside macros, and they always test
whether a real argument was passed for a specified dummy argument. The IFB
directive grants assembly if argument is blank. The IFNB directive grants
assembly if argument is not blank. The arguments can be any name, number,
or expression. Angle brackets (< >) are required.
Example
Write MACRO buffer,bytes,handle
IFNB <handle>
mov bx,handle ; (1=stdout,2=stderr,3=aux,4=printer)
ELSE
mov bx,1 ; Default standard out
ENDIF
mov dx,OFFSET buffer ; Address of buffer to write to
mov cx,bytes ; Number of bytes to write
mov ah,40h
int 21h
ENDM
In this example, a default value is used if no value is specified for the
third macro argument.
10.1.5 Comparing Macro Arguments with IFIDN and IFDIF Directives
The IFIDN and IFDIF directives compare two macro arguments and grant
assembly based on the result.
Syntax
IFIDN[[I]] <argument1>,<argument2>
IFDIF[[I]] <argument1>,<argument2>
These directives are always used inside macros, and they always test
whether real arguments passed for two specified arguments are the same.
The IFIDN directive grants assembly if argument1 and argument2 are
identical. The IFDIF directive grants assembly if argument1 and argument2
are different. The arguments can be names, numbers, or expressions. They
must be enclosed in angle brackets and separated by a comma.
The optional I at the end of the directive name specifies that the
directive is case insensitive. Arguments that are spelled the same will be
evaluated the same, regardless of case. If the I is not given, the
directive is case sensitive.
Example
divide8 MACRO numerator,denominator
IFDIFI <numerator>,<al> ;; If numerator isn't AL
mov al,numerator ;; make it AL
ENDIF
xor ah,ah
div denominator
ENDM
In this example, a macro uses the IFDIFI directive to check one of the
arguments and take a different action, depending on the text of the
string. The sample macro could be enhanced further by checking for other
values that would require adjustment (such as a denominator passed in AL
or passed in AH).
10.1.6 ELSEIF Directives
The assembler includes an ELSEIF conditional-assembly directive
corresponding to each of the IF directives. The ELSEIF directives provide
a more compact and better structured way of writing some sequences of ELSE
and IF directives. QuickAssembler supports the following directives:
ELSEIF ELSEIFDEF ELSEIFIDN
ELSEIF1 ELSEIFDIF ELSEIFIDNI
ELSEIF2 ELSEIFDIFI ELSEIFNB
ELSEIFB ELSEIFE ELSEIFNDEF
The following macro contains nested IF and ELSE blocks:
; Macro to load register for high-level-language return
FuncRet MACRO arg,length
LOCAL tmploc
IF length EQ 1
mov al,arg
ELSE
IF length EQ 2
mov ax,arg
ELSE
IF length EQ 4
.DATA
tmploc DW ?
DW ?
.CODE
mov ax,WORD PTR arg
mov tmploc,ax
mov ax,WORD PTR arg+2
mov tmploc+2,ax
mov dx,SEG tmploc
mov ax,OFFSET tmploc
ELSE
%OUT Error in FuncRet expansion
.ERR
ENDIF
ENDIF
ENDIF
ENDM
The macro can be rewritten as follows, using the ELSEIF directives:
FuncRet MACRO arg,length
LOCAL tmploc
IF length EQ 1
mov al,arg
ELSEIF length EQ 2
mov ax,arg
ELSEIF length EQ 4
.DATA
tmploc DW ?
DW ?
.CODE
mov ax,WORD PTR arg
mov tmploc,ax
mov ax,WORD PTR arg+2
mov tmploc+2,ax
mov dx,SEG tmploc
mov ax,OFFSET tmploc
ELSE
%OUT Error in FuncRet expansion
.ERR
ENDIF
ENDM
10.2 Using Conditional-Error Directives
Conditional-error directives can be used to debug programs and check for
assembly-time errors. By inserting a conditional-error directive at a key
point in your code, you can test assembly-time conditions at that point.
You can also use conditional-error directives to test for boundary
conditions in macros.
The conditional-error directives and the error messages they produce are
listed in Table 10.1.
Table 10.1 Conditional-Error Directives
Directive Number Message
──────────────────────────────────────────────────────────────────────────
.ERR1 2087 Forced error - pass1
.ERR2 2088 Forced error - pass2
.ERR 2089 Forced error
.ERRE 2090 Forced error - expression equals 0
.ERRNZ 2091 Forced error - expression not equal 0
.ERRNDEF 2092 Forced error - symbol not defined
.ERRDEF 2093 Forced error - symbol defined
.ERRB 2094 Forced error - string blank
.ERRNB 2095 Forced error - string not blank
.ERRIDN [[I]] 2096 Forced error - strings identical
.ERRDIF [[I]] 2097 Forced error - strings different
──────────────────────────────────────────────────────────────────────────
Like other severe errors, those generated by conditional-error directives
cause the assembler to return exit code 7. If a severe error is
encountered during assembly, QuickAssembler will delete the object module.
All conditional-error directives except ERR1 generate severe errors.
10.2.1 Generating Unconditional Errors
with .ERR, .ERR1, and .ERR2 Directives
The .ERR, .ERR1, and .ERR2 directives force an error where the directives
occur in the source file. The error is generated unconditionally when the
directive is encountered, but the directives can be placed within
conditional-assembly blocks to limit the errors to certain situations.
Syntax
.ERR
.ERR1
.ERR2
The .ERR directive forces an error regardless of the pass. The .ERR1 and
.ERR2 directives force the error only on their respective passes. The
.ERR1 directive appears only on the screen or in the listing file if you
use the /D option to request a pass 1 listing.
You can place these directives within conditional-assembly blocks or
macros to see which blocks are being expanded.
Example
IFDEF dos
.
.
.
ELSEIFDEF xenix
.
.
.
ELSE
.ERR
%OUT dos or xenix must be defined
ENDIF
ENDIF
This example makes sure that either the symbol dos or the symbol xenix is
defined. If neither is defined, the nested ELSE condition is assembled and
an error message is generated. Since the .ERR directive is used, an error
would be generated on each pass. You could use .ERR1 or .ERR2 to check if
you want the error to be generated only on the corresponding pass.
10.2.2 Testing Expressions with .ERRE or .ERRNZ Directives
The .ERRE and .ERRNZ directives test the value of an expression and
conditionally generate an error based on the result.
Syntax
.ERRE expression
.ERRNZ expression
The .ERRE directive generates an error if expression is false (0). The
.ERRNZ directive generates an error if expression is true (nonzero). The
expression must evaluate to a constant value and must not contain forward
references.
Example
buffer MACRO count,bname
.ERRE count LE 128 ;; Allocate memory, but
bname DB count DUP(0) ;; no more than 128 bytes
ENDM
.
.
.
buffer 128,buf1 ; Data allocated - no error
buffer 129,buf2 ; Error generated
In this example, the .ERRE directive is used to check the boundaries of a
parameter passed to the macro buffer. If count is less than or equal to
128, the expression being tested by the error directive will be true
(nonzero) and no error will be generated. If count is greater than 128,
the expression will be false (0) and the error will be generated.
10.2.3 Verifying Symbol Definition with .ERRDEF and .ERRNDEF Directives
The .ERRDEF and .ERRNDEF directives test whether a symbol is defined and
conditionally generate an error based on the result.
Syntax
.ERRDEF name
.ERRNDEF name
The .ERRDEF directive produces an error if name is defined as a label,
variable, or symbol. The .ERRNDEF directive produces an error if name has
not yet been defined. If name is a forward reference, it is considered
undefined on pass 1, but defined on pass 2.
Example
.ERRNDEF publevel
IF publevel LE 2
PUBLIC var1, var2
ELSE
PUBLIC var1, var2, var3
ENDIF
In this example, the .ERRNDEF directive at the beginning of the
conditional block makes sure that a symbol being tested in the block
actually exists.
10.2.4 Testing for Macro Parameters with .ERRB and .ERRNB Directives
The .ERRB and .ERRNB directives test whether a specified argument was
passed to a macro and conditionally generate an error based on the result.
Syntax
.ERRB <argument>
.ERRNB <argument>
These directives are always used inside macros, and they always test
whether a real argument was passed for a specified dummy argument. The
.ERRB directive generates an error if argument is blank. The .ERRNB
directive generates an error if argument is not blank. The argument can be
any name, number, or expression. Angle brackets (<>) are required.
Example
work MACRO realarg,testarg
.ERRB <realarg> ;; Error if no parameters
.ERRNB <testarg> ;; Error if more than one parameter
.
.
.
ENDM
In this example, error directives are used to make sure that one, and only
one, argument is passed to the macro. The .ERRB directive generates an
error if no argument is passed to the macro. The .ERRNB directive
generates an error if more than one argument is passed to the macro.
10.2.5 Comparing Macro Arguments with .ERRIDN and .ERRDIF Directives
The .ERRIDN and .ERRDIF directives compare two macro arguments and
conditionally generate an error based on the result.
Syntax
.ERRIDN[[I]] <argument1>,<argument2>
.ERRDIF[[I]] <argument1>,<argument2>
These directives are always used inside macros, and they always compare
the real arguments specified for two parameters. The .ERRIDN directive
generates an error if the arguments are identical. The .ERRDIF directive
generates an error if the arguments are different. The arguments can be
names, numbers, or expressions. They must be enclosed in angle brackets
and separated by a comma.
The optional I at the end of the directive name specifies that the
directive is case insensitive. Arguments that are spelled the same will be
evaluated the same regardless of case. If the I is not given, the
directive is case sensitive.
Example
addem MACRO ad1,ad2,sum
.ERRIDNI <ax>,<ad2> ;; Error if ad2 is "ax"
mov ax,ad1 ;; Would overwrite if ad2 were AX
add ax,ad2
mov sum,ax ;; Sum must be register or memory
ENDM
In this example, the .ERRIDNI directive is used to protect against passing
the AX register as the second parameter, since this would cause the macro
to fail.
────────────────────────────────────────────────────────────────────────────
Chapter 11: Using Equates, Macros, and Repeat Blocks
This chapter explains how to use equates, macros, and repeat blocks.
"Equates" are constant values assigned to symbols so that the symbol can
be used in place of the value. "Macros" are a series of statements that
are assigned a symbolic name (and, optionally, parameters) so that the
symbol can be used in place of the statements. "Repeat blocks" are a
special form of macro used to do repeated statements.
Both equates and macros are processed at assembly time. They can simplify
writing source code by allowing the user to substitute mnemonic names for
constants and repetitive code. By changing a macro or equate, a programmer
can change the effect of statements throughout the source code.
In exchange for these conveniences, the programmer loses some
assembly-time efficiency. Assembly may be slightly slower for a program
that uses macros and equates extensively than for the same program written
without them. However, the program without macros and equates usually
takes longer to write and is more difficult to maintain.
11.1 Using Equates
The equate directives enable you to use symbols that represent numeric or
string constants. QuickAssembler recognizes three kinds of equates:
1. Redefinable numeric equates
2. Nonredefinable numeric equates
3. String equates (also called text macros)
11.1.1 Redefinable Numeric Equates
Redefinable numeric equates are used to assign a numeric constant to a
symbol. The value of the symbol can be redefined at any point during
assembly time. Although the value of a redefinable equate may be different
at different points in the source code, a constant value will be assigned
for each use, and that value will not change at run time.
Redefinable equates are often used for assembly-time calculations in
macros and repeat blocks.
Syntax
name=expression
The equal-sign (=) directive creates or redefines a constant symbol by
assigning the numeric value of expression to name. No storage is allocated
for the symbol. The symbol can be used in subsequent statements as an
immediate operand having the assigned value. It can be redefined at any
time.
The expression can be an integer, a constant expression, a one- or
two-character string constant, or an expression that evaluates to an
address. The name must be either a unique name or a name previously
defined by using the equal-sign (=) directive.
──────────────────────────────────────────────────────────────────────────
NOTE Redefinable equates must be assigned numeric values. String
constants longer than two characters cannot be used.
──────────────────────────────────────────────────────────────────────────
Example
counter = 0 ; Initialize counter
array LABEL BYTE ; Label array of increasing numbers
REPT 100 ; Repeat 100 times
DB counter ; Initialize number
counter = counter + 1 ; Increment counter
ENDM
This example redefines equates inside a repeat block to declare an array
initialized to increasing values from 0 to 100. The equal-sign directive
is used to increment the counter symbol for each loop. See Section 11.4
for more information on repeat blocks.
11.1.2 Nonredefinable Numeric Equates
Nonredefinable numeric equates are used to assign a numeric constant to a
symbol. The value of the symbol cannot be redefined.
Nonredefinable numeric equates are often used for assigning mnemonic names
to constant values. This can make the code more readable and easier to
maintain. If a constant value used in numerous places in the source code
needs to be changed, the equate can be changed in one place rather than
throughout the source code.
Syntax
name EQU expression
The EQU directive creates constant symbols by assigning expression to
name. The assembler replaces each subsequent occurrence of name with the
value of expression. Once a numeric equate has been defined with the EQU
directive, it cannot be redefined. Attempting to do so generates an error.
──────────────────────────────────────────────────────────────────────────
NOTE String constants can also be defined with the EQU directive, but the
syntax is different, as described in Section 11.1.3, "String Equates."
──────────────────────────────────────────────────────────────────────────
No storage is allocated for the symbol. Symbols defined with numeric
values can be used in subsequent statements as immediate operands having
the assigned value.
Examples
column EQU 80 ; Numeric constant 80
row EQU 25 ; Numeric constant 25
screenful EQU column * row ; Numeric constant 2000
line EQU row ; Alias for "row"
.DATA
buffer DW screenful
.CODE
.
.
.
mov cx,column
mov bx,line
11.1.3 String Equates
String equates (or text macros) are used to assign a string constant to a
symbol. String equates can be used in a variety of contexts, including
defining aliases and string constants.
Syntax
name EQU{string | <string>}
The EQU directive creates constant symbols by assigning string to name.
The assembler replaces each subsequent occurrence of name with string.
Symbols defined to represent strings with the EQU directive can be
redefined to new strings. Symbols cannot be defined to represent strings
with the equal-sign (=) directive.
An alias is a special kind of string equate. It is a symbol that is
equated to another symbol or keyword.
If you want an equate to be a string equate, you should use angle brackets
to force the assembler to evaluate it as a string. If you do not use angle
brackets, the assembler will try to guess from context whether a numric or
string equate is appropriate. This can lead to unexpected results. For
example, the statement
rt EQU run-time
would be evaluated as run minus time, even though the user might intend to
define the string run-time. If run and time were not already defined as
numeric equates, the statement would generate an error. Using angle
brackets solves this problem. The statement
rt EQU <run-time>
is evaluated as the string run-time.
Examples
;String equate definitions
pi EQU <3.1415> ; String constant "3.1415"
prompt EQU <'Type Name: '> ; String constant "'Type Name: '",
WPT EQU <WORD PTR> ; String constant for "WORD PTR"
argl EQU <[bp+4]> ; String constant for "[bp+4]"
; Use of string equates
.DATA
message DB prompt ; Allocate string "Type Name:"
pie DQ pi ; Allocate real number 3.1415
.CODE
.
.
.
inc WPT parm1 ; Increment word value of
; argument passed on stack
Section 11.3, "Text-Macro String Directives," describes directives that
enable you to manipulate strings. They are particularly powerful when you
use them from within macros and repeat blocks, described later.
11.1.4 Predefined Equates
The assembler includes several predefined equates. The ones related to
segments are described in Section 5.1.5, "Using Predefined Segment
Equates." In addition, the following equates are available: @WordSize,
@Cpu, and @Version.
The @WordSize equate returns the size of a word for the current segment.
With QuickAssembler, this value is always equal to 2. However, other
versions of the assembler can assign a different value to @WordSize when
working with 80386 extended features.
──────────────────────────────────────────────────────────────────────────
NOTE If you set the Preserve Case assembler flag or use the /Cl option,
QuickAssembler considers predefined equates to be case-sensitive. The
case-sensitive names of predefined equates are @WordSize, @Cpu, @Version,
@CurSeg, @FileName, @CodeSize, @DataSize, @Model, @data, @data?, @fardata,
@fardata?, and @code.
──────────────────────────────────────────────────────────────────────────
The @Cpu equate returns a 16-bit value containing information about the
selected processor. You select a processor by using one of the processor
directives, such as the .286 directive. You can use the @Cpu text macro to
control assembly of processor-specific code. Individual bits in the value
returned by @Cpu indicate information about the selected processor.
Bit If Bit = 1
──────────────────────────────────────────────────────────────────────────
0 8086 processor
1 80186 processor
2 80286 processor
8 8087 coprocessor instructions enabled
10 80287 coprocessor instructions enabled
Because the processors are upwardly compatible, selecting a
higher-numbered processor automatically sets the bits indicating
lower-numbered processors. For example, selecting an 80286 processor
automatically sets the 80186 and 8086 bits.
Bits 4 through 6, 9, and 12 through 15 are reserved for future use and
should be masked off when testing. Bits 3, 7, and 11 have special meaning
to Versions 5.1 and later of the Microsoft Macro Assembler: bit 3
indicates an 80386 processor, bit 7 indicates privilege mode enabled, and
bit 11 indicates that 80387 coprocessor instructions are enabled.
──────────────────────────────────────────────────────────────────────────
NOTE The @Cpu equate only provides information about the processor
selected during assembly by one of the processor directives. It does not
provide information about the processor actually used when a program is
run.
──────────────────────────────────────────────────────────────────────────
The following example uses the @Cpu text macro to select more efficient
instructions available only on the 80186 processor and above:
; Use the 186/286/386 pusha instruction if possible
P186 EQU (@Cpu AND 0002h) ; Only test 186 bit--286 and
; 386 set 186 bit as well
.
.
.
IF P186 ; Non-zero if 186 processor
pusha ; or above
ELSE
push ax ; Do what the single
push cx ; pusha instruction does
push dx
push bx
push sp
push bp
push si
push di
ENDIF
The @Version equate returns the version of the assembler in use. With the
@Version equate, you can write macros that take appropriate actions for
different versions of the assembler. Currently, the @Version equate
returns 520 as a string of three characters.
──────────────────────────────────────────────────────────────────────────
NOTE Although the version number of QuickAssembler is 2.01, the @Version
equate returns 520 rather than 201. The number 520 was selected because
QuickAssembler is an enhancement of Version 5.1 of the Microsoft Macro
Assembler. The @Version equate was first assembled for Version 5.1.
──────────────────────────────────────────────────────────────────────────
You can use the IF and IFE conditional assembly directives to test for
different versions of the assembler and to assemble different code
depending on the version.
IFNDEF @Version
%OUT MASM 5.0 or earlier has no extended PROC or .STARTUP
ELSEIF @Version EQ 510
%OUT MASM 5.1 has extended PROC, but not .STARTUP
ELSEIF @Version EQ 520
%OUT QuickAssembler 2.01 has extended PROC and .STARTUP
ELSE
%OUT Future assembler
ENDIF
11.2 Using Macros
Macros enable you to assign a symbolic name to a block of source
statements and then to use that name in your source file to represent the
statements. Parameters can also be defined to represent arguments passed
to the macro.
Macro expansion is a text-processing function that occurs at assembly
time. Each time QuickAssembler encounters the text associated with a macro
name, it replaces that text with the text of the statements in the macro
definition. Similarly, the text of parameter names is replaced with the
text of the corresponding actual arguments.
A macro can be defined any place in the source file as long as the
definition precedes the first source line that calls the macro. Macros and
equates are often kept in a separate file and made available to the
program through an INCLUDE directive (see Section 11.7.1, "Using Include
Files") at the start of the source code.
Often a task can be done by using either a macro or procedure. For
example, the addup procedure shown in Section 15.3.3, "Passing Arguments
on the Stack," does the same thing as the addup macro in Section 11.2.1,
"Defining Macros." Macros are expanded on every occurrence of the macro
name, so they can increase the length of the executable file if called
repeatedly. Procedures are coded only once in the executable file, but the
increased overhead of saving and restoring addresses and parameters can
make them slower.
The section below tells how to define and call macros. Repeat blocks, a
special form of macro for doing repeated operations, are discussed
separately in Section 11.4.
11.2.1 Defining Macros
The MACRO and ENDM directives are used to define macros. MACRO designates
the beginning of the macro block, and ENDM designates the end of the macro
block.
Syntax
name MACRO [[parameter [[,parameter]]...]]
statements
ENDM
The name must be unique and a valid symbol name. It can be used later in
the source file to invoke the macro.
The parameters (sometimes called dummy parameters) are names that act as
placeholders for values to be passed as arguments to the macro when it is
called. Any number of parameters can be specified, but they must all fit
on one line. If you give more than one parameter, you must separate them
with commas, spaces, or tabs. Commas can always be used as separators;
spaces and tabs may cause ambiguity if the arguments are expressions.
──────────────────────────────────────────────────────────────────────────
NOTE This manual uses the term "parameter" to refer to a placeholder for
a value that will be passed to a macro or procedure. Parameters appear in
macro or procedure definitions. The term "argument" is used to refer to an
actual value passed to the macro or procedure when it is called.
──────────────────────────────────────────────────────────────────────────
Any valid assembler statements may be placed within a macro, including
statements that call or define other macros. Any number of statements can
be used. The parameters can be used any number of times in the statements.
Macros can be nested, redefined, or used recursively, as explained in
Section 11.6, "Using Recursive, Nested, and Redefined Macros."
QuickAssembler assembles the statements in a macro only if the macro is
called and only at the point in the source file from which it is called.
The macro definition itself is never assembled.
A macro definition can include the LOCAL directive, which lets you define
labels used only within a macro, or the EXITM directive, which allows you
to exit from a macro before all the statements in the block are expanded.
These directives are discussed in Sections 11.2.3, "Using Local Symbols,"
and 11.2.4, "Exiting from a Macro." Macro operators can also be used in
macro definitions, as described in Section 11.5, "Using Macro Operators."
Example
addup MACRO ad1,ad2,ad3
mov ax,ad1 ;; First parameter in AX
add ax,ad2 ;; Add next two parameters
add ax,ad3 ;; and leave sum in AX
ENDM
This example defines a macro named addup, which uses three parameters to
add three values and leave their sum in the AX register. The three
parameters will be replaced with arguments when the macro is called.
11.2.2 Calling Macros
A macro call directs QuickAssembler to copy the statements of the macro to
the point of the call and to replace any parameters in the macro
statements with the corresponding actual arguments.
Syntax
name [[argument [[,argument]]...]]
The name must be the name of a macro defined earlier in the source file.
The arguments can be any text. For example, symbols, constants, and
registers are often given as arguments. Any number of arguments can be
given, but they must all fit on one logical line. You can use the
continuation character (\) to continue long macro calls on multiple
physical lines. Multiple arguments must be separated by commas, spaces, or
tabs.
QuickAssembler replaces the first parameter with the first argument, the
second parameter with the second argument, and so on. If a macro call has
more arguments than the macro has parameters, the extra arguments are
ignored. If a call has fewer arguments than the macro has parameters, any
remaining parameters are replaced with a null (empty) string.
You can use conditional statements to enable macros to check for null
strings or other types of arguments. The macro can then take appropriate
action to adjust to different kinds of arguments. See Chapter 10,
"Assembling Conditionally," for more information on using
conditional-assembly and conditional-error directives to test macro
arguments.
Example
addup MACRO ad1,ad2,ad3 ; Macro definition
mov ax,ad1 ;; First parameter in AX
add ax,ad2 ;; Add next two parameters
add ax,ad3 ;; and leave sum in AX
ENDM
.
.
.
addup bx,2,count ; Macro call
When the addup macro is called, QuickAssembler replaces the parameters
with the actual parameters given in the macro call. In the example above,
the assembler would expand the macro call to the following code:
mov ax,bx
add ax,2
add ax,count
This code could be shown in an assembler listing, depending on whether the
.LALL, .XALL, or .SALL directive was in effect (see Section 12.3,
"Controlling the Contents of Listings").
11.2.3 Using Local Symbols
The LOCAL directive can be used within a macro to define symbols that are
available only within the defined macro.
──────────────────────────────────────────────────────────────────────────
NOTE In this context, the term "local" is not related to the public
availability of a symbol, as described in Chapter 8, "Creating Programs
from Multiple Modules," or to variables that are defined to be local to a
procedure, as described in Section 15.3.5, "Using Local Variables." Local
simply means that the symbol is not known outside the macro where it is
defined.
──────────────────────────────────────────────────────────────────────────
Syntax
LOCAL localname [[,localname]]...
The localname is a temporary symbol name that is to be replaced by a
unique symbol name when the macro is expanded. At least one local name is
required for each LOCAL directive. If more than one local symbol is given,
the names must be separated with commas. Once declared, local name can be
used in any statement within the macro definition.
QuickAssembler creates a new actual name for localname each time the macro
is expanded. The actual name has the following form:
??number
The number is a hexadecimal number in the range 0000 to 0FFFF. You should
not give other symbols names in this format, since doing so may produce a
symbol with multiple definitions. In listings, the local name is shown in
the macro definition, but the actual name is shown in expansions of macro
calls.
Nonlocal labels may be used in a macro; but if the macro is used more than
once, the same label will appear in both expansions, and QuickAssembler
will display an error message, indicating that the file contains a symbol
with multiple definitions. To avoid this problem, use only local labels
(or redefinable equates) in macros.
──────────────────────────────────────────────────────────────────────────
NOTE The LOCAL directive in macro definitions must precede all other
statements in the definition. If you try another statement (such as a
comment directive) before the LOCAL directive, an error will be generated.
──────────────────────────────────────────────────────────────────────────
Example
power MACRO factor,exponent ;; Use for unsigned only
LOCAL again,gotzero ;; Declare symbols for macro
xor dx,dx ;; Clear DX
mov cx,exponent ;; Exponent is count for loop
mov ax,1 ;; Multiply by 1 first time
jcxz gotzero ;; Get out if exponent is zero
mov bx,factor
again: mul bx ;; Multiply until done
loop again
gotzero:
ENDM
In this example, the LOCAL directive defines the local names again and
gotzero as labels to be used within the power macro. These local names
will be replaced with unique names each time the macro is expanded. For
example, the first time the macro is called, again will be assigned the
name ??0000 and gotzero will be assigned ??0001. The second time through,
again will be assigned ??0002 and gotzero will be assigned ??0003, and so
on.
11.2.4 Exiting from a Macro
Normally, QuickAssembler processes all the statements in a macro
definition and then continues with the next statement after the macro
call. However, you can use the EXITM directive to tell the assembler to
terminate macro expansion before all the statements in the macro have been
assembled.
When the EXITM directive is encountered, the assembler exits the macro or
repeat block immediately. Any remaining statements in the macro or repeat
block are not processed. If EXITM is encountered in a nested macro or
repeat block, QuickAssembler returns to expanding the outer block.
The EXITM directive is typically used with conditional directives to skip
the last statements in a macro under specified conditions. Often macros
using the EXITM directive contain repeat blocks or are called recursively.
Example
allocate MACRO times ; Macro definition
x = 0
REPT times ;; Repeat up to 256 times
IF x GT 0FFh ;; Is x > 255 yet?
EXITM ;; If so, quit
ELSE
DB x ;; Else allocate x
ENDIF
x = x + 1 ;; Increment x
ENDM
ENDM
This example defines a macro that allocates a variable amount of data, but
no more than 255 bytes. The macro contains an IF directive that checks the
expression x - 0FFh. When the value of this expression is true (x-255 =
0), the EXITM directive is processed and expansion of the macro stops.
11.3 Text-Macro String Directives
The assembler includes four text-macro string directives that let you
manipulate literal strings or text-macro values. You use the four
directives in much the same way you use the equal-sign (=) directive. For
example, the following line assigns the first three characters (abc) of
the literal string to the label three by using the SUBSTR directive:
three SUBSTR <abcdefghijklmnopqrstuvwxyz>,1,3
Each of the directives assigns its value──depending on the directive──to a
numeric label or a text macro. The following list summarizes the four
directives and the type of label that the directives should be used with:
Directive Description
──────────────────────────────────────────────────────────────────────────
SUBSTR Returns a substring of its text macro or literal
string argument. SUBSTR requires a text-macro label.
CATSTR Concatenates a variable number of strings (text macros
or literal strings) to form a single string. CATSTR
requires a text-macro label.
SIZESTR Returns the length, in characters, of its argument
string. SIZESTR requires a numeric label.
INSTR Returns an index indicating the starting position of a
substring within another string. INSTR requires a
numeric label.
Strings used as arguments in the directives must be text enclosed in angle
brackets (< >), previously defined text macros, or expressions starting
with a percent sign (%). Numeric arguments can be numeric constants or
expressions that evaluate to constants during assembly.
The next four sections describe the directives in more detail.
11.3.1 The SUBSTR Directive
The SUBSTR directive returns a substring from a given string.
Syntax
textlabel SUBSTR string,start[[, length]]
The SUBSTR directive takes the following arguments:
Argument Description
──────────────────────────────────────────────────────────────────────────
textlabel The text label the result is assigned to.
string The string the substring is extracted from.
start The starting position of the substring. The first
character in the string has a position of one.
length The number of characters to extract. If omitted,
SUBSTR returns all characters to the right of position
start, including the character at position start.
In the following lines, the text macro freg is assigned the first two
characters of the text macro reglist:
reglist EQU <ax,bx,cx,dx>
.
.
.
freg SUBSTR reglist,1,2 ; freg = ax
11.3.2 The CATSTR Directive
The CATSTR directive concatenates a series of strings.
Syntax
textlabel CATSTR string[[, string]]...
The CATSTR directive takes the following arguments:
Argument Description
──────────────────────────────────────────────────────────────────────────
textlabel The text label the result is assigned to
string The string or strings concatenated and assigned to
textlabel
The following lines concatenate the two literal strings and assign the
result to the text macro lstring:
lstring CATSTR <a b c>, <d e f>, ; lstring = a b c d e f
11.3.3 The SIZESTR Directive
The SIZESTR directive assigns the length of its argument string to a
numeric label.
Syntax
numericlabel SIZESTR string
The SIZESTR directive takes the following arguments:
Argument Description
──────────────────────────────────────────────────────────────────────────
numericlabel The numeric label that the assembler assigns the
string length to
string The string whose length is returned
The following lines set slength to 8──the length of the text macro
tstring:
tstring EQU <ax bx cx>
.
.
.
slength SIZESTR tstring ; slength = 8
A null string has a length of zero.
11.3.4 The INSTR Directive
The INSTR directive returns the position of a string within another
string. The directive returns 0 if the string is not found. The first
character in a string has a position of one.
Syntax
numericlabel INSTR [[start,]]string1, string2
The INSTR directive takes the following arguments:
Argument Description
──────────────────────────────────────────────────────────────────────────
numbericlabel The numeric label the substring's position is assigned
to.
start The starting position for the search. When omitted,
the INSTR directive starts searching at the first
character. The first character in the string has a
position of one.
string1 The string being searched.
string2 The string to look for.
The following lines set colpos to the character position of the first
colon in segarg:
segarg EQU <ES:AX>
.
.
.
colpos INSTR segarg,<:> ; colpos = 3
11.3.5 Using String Directives Inside Macros
The following example uses the text-macro string directives CATSTR, INSTR,
SIZESTR, and SUBSTR. It defines two macros, SaveRegs and RestRegs, that
save and restore registers on the stack. The macros are written so that
RestRegs restores only the most recently saved group of registers.
The SaveRegs macro uses a text macro, regpushed, to keep track of the
registers pushed onto the stack. The RestRegs macro uses this string to
restore the proper registers. Each time the SaveRegs macro is invoked, it
adds a pound sign (#) to the string to mark the start of a new group of
registers. The RestRegs macro restores the most recently saved group by
finding the first pound sign in the string, creating a substring
containing the saved register names, and then looping and generating PUSH
instructions.
; Initialize regpushed to the null string
regpushed EQU <>
; SaveRegs
; Loops and generates a push for each argument register.
; Saves each register name in regpushed.
SaveRegs MACRO r1,r2,r3,r4,r5,r6,r7,r8,r9
regpushed CATSTR <#>,regpushed ;; Mark a new group of regs
IRP reg,<r1,r2,r3,r4,r5,r6,r7,r8,r9>
IFNB <reg>
push reg ;; Push and record a register
regpushed CATSTR <reg>,<,>,regpushed
ELSE
EXITM ;; Quit on blank argument
ENDIF
ENDM
ENDM
; RestRegs
; Generates a pop for each register in the most recently saved groups
RestRegs MACRO
numloc INSTR regpushed,<#> ;; Find location of #
reglist SUBSTR regpushed,1,numloc-1 ;; Get list of registers to pop
reglen SIZESTR regpushed ;; Adjust numloc if # is notlast
IF reglen GT numloc ;; item in the string
numloc = numloc + 1
ENDIF
regpushed SUBSTR regpushed,numloc ;; Remove list from regpushed
% IRP reg,<reglist> ;; Generate pop for each register
IFNB <reg>
pop reg
ENDIF
ENDM
ENDM
The following lines from a listing file show the sample code that the
macros would generate (a 2 marks lines generated by the macros):
SaveRegs ax,bx
2 push ax ;
2 push bx ;
SaveRegs cx
2 push cx ;
SaveRegs dx
2 push dx ;
RestRegs
2 pop dx
RestRegs
2 pop cx
RestRegs
2 pop bx
2 pop ax
11.4 Defining Repeat Blocks
Repeat blocks are a special form of macro that allows you to create blocks
of repeated statements. They differ from macros in that they are not
named, and thus cannot be called. However, like macros, they can have
parameters that are replaced by actual arguments during assembly. Macro
operators, symbols declared with the LOCAL directive, and the EXITM
directive can be used in repeat blocks. Like macros, repeat blocks are
always terminated by an ENDM directive.
Repeat blocks are frequently placed in macros in order to repeat some of
the statements in the macro. They can also be used independently, usually
for declaring arrays with repeated data elements.
Repeat blocks are processed at assembly time and should not be confused
with the REP instruction, which causes string instructions to be repeated
at run time, as explained in Chapter 16, "Processing Strings."
Three different kinds of repeat blocks can be defined by using the REPT,
IRP, and IRPC directives. The difference between them is in how the number
of repetitions is specified.
11.4.1 The REPT Directive
The REPT directive is used to create repeat blocks in which the number of
repetitions is specified with a numeric argument.
Syntax
REPT expression
statements
ENDM
The expression must evaluate to a numeric constant (a 16-bit unsigned
number). It specifies the number of repetitions. Any valid assembler
statements may be placed within the repeat block.
Example
alphabet LABEL BYTE
x = 0 ;; Initialize
REPT 26 ;; Specify 26 repetitions
DB 'A' + x ;; Allocate ASCII code for letter
x = x + 1 ;; Increment
ENDM
This example repeats the equal-sign (=) and DB directives to initialize
ASCII values for each uppercase letter of the alphabet.
11.4.2 The IRP Directive
The IRP directive is used to create repeat blocks in which the number of
repetitions, as well as parameters for each repetition, is specified in a
list of arguments.
Syntax
IRP parameter,<argument[[,argument]]...>
statements
ENDM
The assembler statements inside the block are repeated once for each
argument in the list enclosed by angle brackets (< >). The parameter is a
name for a placeholder to be replaced by the current argument. Each
argument can be text, such as a symbol, string, or numeric constant. Any
number of arguments can be given. If multiple arguments are given, they
must be separated by commas. The angle brackets (< >) around the argument
list are required. The parameter can be used any number of times in the
statements.
When QuickAssembler encounters an IRP directive, it makes one copy of the
statements for each argument in the enclosed list. While copying the
statements, it substitutes the current argument for all occurrences of
parameter in these statements. If a null argument (< >) is found in the
list, the dummy name is replaced with a blank value. If the argument list
is empty, the IRP directive is ignored and no statements are copied.
Example
numbers LABEL BYTE
IRP x,<0,1,2,3,4,5,6,7,8,9>
DB 10 DUP(x)
ENDM
This example repeats the DB directive 10 times, allocating 10 bytes for
each number in the list. The resulting statements create 100 bytes of
data, starting with 10 zeros, followed by 10 ones, and so on.
11.4.3 The IRPC Directive
The IRPC directive is used to create repeat blocks in which the number of
repetitions, as well as arguments for each repetition, is specified in a
string.
Syntax
IRPC parameter,string
statements
ENDM
The assembler statements inside the block are repeated as many times as
there are characters in string. The parameter is a name for a placeholder
to be replaced by the current character in the string. The string can be
any combination of letters, digits, and other characters. It should be
enclosed with angle brackets (< >) if it contains spaces, commas, or other
separating characters. The parameter can be used any number of times in
these statements.
When QuickAssembler encounters an IRPC directive, it makes one copy of the
statements for each character in the string. While copying the statements,
it substitutes the current character for all occurrences of parameter in
these statements.
Example 1
ten LABEL BYTE
IRPC x,0123456789
DB x
ENDM
Example 1 repeats the DB directive 10 times, once for each character in
the string 0123456789. The resulting statements create 10 bytes of data
having the values 0-9.
Example 2
IRPC letter,ABCDEFGHIJKLMNOPQRSTUVWXYZ
DB '&letter' ; Allocate uppercase letter
DB '&letter'+20h ; Allocate lowercase letter
DB '&letter'-40h ; Allocate number of letter
ENDM
Example 2 allocates the ASCII codes for uppercase, lowercase, and numeric
versions of each letter in the string. Notice that the substitute operator
(&) is required so that letter will be treated as an argument rather than
a string. See Section 11.5.1, "Substitute Operator," for more
information.
11.5 Using Macro Operators
Macro and conditional directives use the following special set of macro
operators:
Operator Definition
──────────────────────────────────────────────────────────────────────────
& Substitute operator
<> Literal-text operator
! Literal-character operator
% Expression operator
;; Macro comment
When used in a macro definition, a macro call, a repeat block, or as the
argument of a conditional-assembly directive, these operators carry out
special control operations, such as text substitution.
11.5.1 Substitute Operator
The substitute operator (&) enables substitution of macro parameters to
take place, even when the parameter occurs within a larger word or within
a quoted string.
Syntax
You can use the substitute operator in any one of three different ways:
name1&name2
name&
&name
The assembler responds by analyzing name1 and name2 separately, then
joining them together. If either name1 or name2 is a parameter, the
assembler replaces each parameter by an actual argument before joining the
names. You can join any number of names with the substitute operator, so
that items such as a&b&c are valid.
The last two forms are useful when a parameter name appears within a
quoted string. The assembler responds by substituting the actual argument
for the parameter; when not next to an ampersand (&), the assembler
considers the parameter name just part of the string data.
Example
declare MACRO x,y
xy DW 0
x&y DW 0
x&str DB 'x and y params are &x and &y'
ENDM
The example above demonstrates how the presence or absence of the
substitute operator affects macro substitution. Given the macro definition
above, the statement
declare foot,ball
is expanded to
xy DW
football DW 0
footstr DB 'x and y params are foot and ball'
In the first statement of the macro, xy is not identified with either of
the parameters x or y; instead, xy forms a distinct name. No substitution
takes place. In the second statement, the assembler interprets x&y by
analyzing x and y as separate names, performing the appropriate parameter
substitution in each case, and then joining the resulting names together.
When you use the substitute operator with nested macros and repeat blocks,
the assembler applies the following rules to expressions outside of
quotes:
1. Perform parameter substitution as described above.
2. Remove exactly one of the substitute operators (&) from the group. The
assembler strips off an operator whether or not a parameter was
substituted.
The number of ampersands (&) you use should never be greater than the
number of levels of nesting. If you use too few ampersands, proper
substitution will not take place. If you use too many ampersands, text
such as x&y will remain after macro expansion is complete. Such
expressions are invalid.
When an ampersand appears inside quotes, the assembler removes ampersands
on either side of a macro parameter when substitution is possible. When
substitution is not possible (because the parameter name is not defined at
the current level of nesting), the assembler leaves the ampersand as it
is. With this method, parameter substitution automatically takes place at
the appropriate level of nesting.
11.5.2 Literal-Text Operator
The literal-text operator (< >) directs QuickAssembler to treat a list as
a single string rather than as separate arguments.
Syntax
<text >
The text is considered a single literal element even if it contains
commas, spaces, or tabs. The literal-text operator is most often used in
macro calls and with the IRP directive to ensure that values in a
parameter list are treated as a single parameter.
The literal-text operator can also be used to force QuickAssembler to
treat special characters, such as the semicolon or the ampersand,
literally. For example, the semicolon inside angle brackets <;> becomes a
semicolon, not a comment indicator.
QuickAssembler removes one set of angle brackets each time the parameter
is used in a macro. When using nested macros, you will need to supply as
many sets of angle brackets as there are levels of nesting.
Example
work 1,2,3,4,5 ; Passes five parameters to "work"
work <1,2,3,4,5> ; Passes one five-element
; parameter to "work"
When the IRP directive is used inside a macro definition and when the
argument list of the IRP directive is also a parameter of the macro, you
must use the literal-text operator (< >) to enclose the macro parameter.
For example, in the following macro definition, the parameter x is used as
the argument list for the IRP directive:
init MACRO x
IRP y,<x>
DB y
ENDM
ENDM
If this macro is called with
init <0,1,2,3,4,5,6,7,8,9>
the macro removes the angle brackets from the parameter so that it is
expanded as 0,1,2,3,4,5,6,7,8,9. The brackets inside the repeat block are
necessary to put the angle brackets back on. The repeat block is then
expanded as shown below:
IRP y,<0,1,2,3,4,5,6,7,8,9>
DB y
ENDM
11.5.3 Literal-Character Operator
The literal-character operator (!) forces the assembler to treat a
specified character literally rather than as a symbol.
Syntax
!character
The literal-character operator is used with special characters, such as
the semicolon or ampersand, when meaning of the special character must be
suppressed. Using the literal-character operator is the same as enclosing
a single character in brackets. For example, !! is the same as <!>.
Example
errgen MACRO y,x
PUBLIC err&y
err&y DB 'Error &y: &x'
ENDMW
.
.
.
errgen 103,<Expression !> 255>
The example macro call is expanded to allocate the string Error 103:
Expression > 255. Without the literal-character operator, the greater-than
symbol would be interpreted as the end of the argument and an error would
result.
11.5.4 Expression Operator
The expression operator (%) causes the assembler to treat the argument
following the operator as an expression.
Syntax
%text
QuickAssembler computes the expression's value and replaces text with the
result. The expression can be either a numeric expression or a text
equate. Additional arguments after an argument that uses the expression
operator must be preceded by a comma, not a space or tab.
The expression operator is typically used in macro calls when the
programmer needs to pass the result of an expression rather than the
actual expression to a macro.
Example
printe MACRO exp,val
IF1 ;; On pass 1 only
%OUT exp = val ;; Display expression and result
ENDIF ;; to screen
ENDM
sym1 EQU 100
sym2 EQU 200
msg EQU <"Hello, World.">
printe <sym1 + sym2>,%(sym1 + sym2)
printe msg,%msg
In the first macro call, the text literal sym1 + sym2 = is passed to the
parameter exp, and the result of the expression is passed to the parameter
val. In the second macro call, the equate name msg is passed to the
parameter exp, and the text of the equate is passed to the parameter val.
As a result, Quick-Assembler displays the following messages:
sym1 + sym2 = 300
msg = "Hello, World."
The %OUT directive, which sends a message to the screen, is described in
Section 12.1, "Sending Messages to the Standard Output Device"; the IF1
directive is described in Section 10.1.2, "Testing the Pass with IF1 and
IF2 Directives."
You can also use the expression operator (%) to substitute the values of
text macros for the macro names anywhere a text-macro name appears. When
the expression operator is the first item on a line and is followed by one
or more blanks or tabs, the line is scanned for text macros and the values
of the macros are substituted. Using the expression operator, you can
force substitution of text macros wherever they appear in a line. The
assembler re-scans the line until all substitutions have been made.
──────────────────────────────────────────────────────────────────────────
NOTE Text macros are always evaluated when they appear in the name or
operation fields. The expression operator is required to evaluate a text
macro only when the macro appears in the operand field.
──────────────────────────────────────────────────────────────────────────
This use of the expression operator eliminates the need to do a macro call
in order to evaluate a text macro. For example, the following macro uses a
separate macro, popregs, to evaluate the text macro regpushed:
regpushed EQU <ax,bx,cx>
.
.
.
RestRegs MACRO
popregs %regpushed
ENDM
popregs MACRO reglist
IRP reg,<reglist>
pop reg
ENDM
ENDM
The use of the expression operator to evaluate text macros in a line makes
the popregs macro unnecessary:
regpushed EQU <ax,bx,cx>
.
.
.
RestRegs MACRO
% IRP reg,<regpushed> ;; % operator makes
;; separate macro unnecessary
pop reg
ENDM
ENDM
You cannot use the EQU directive to assign a value to a text macro in a
line evaluated with the expression operator. For example, the following
lines generate an error:
strpos EQU <[si]+12>
.
.
.
% wpstrpos EQU <WORD PTR strpos>
On pass 1, wpstrpos is defined as a text macro that is expanded on pass 2.
Thus, on pass 2 the second EQU directive becomes
WORD PTR [si]+12 EQU <WORD PTR [si]+12>
and generates an error.
Instead, use the CATSTR directive to assign values to text macros (see
Section 11.3, "Text-Macro String Directives," for more information about
CATSTR and other text-macro string directives). The previous example
should be rewritten as follows:
strpos EQU <[si]+12>
.
.
.
wpstrpos CATSTR <WORD PTR >, strpos
If the text macro evaluates to a valid name, there is no error when you
use EQU. The following lines do not generate an error, but define two
names, one (numlabel) with the value 5, the other (tmacro) with the value
<numlabel>:
tmacro EQU <numlabel>
% tmacro EQU 5
You can also use the substitution operator (&) with text macros just as
you would inside a macro:
SegName EQU <MySeg>
.
.
.
% SegName&_text SEGMENT PUBLIC 'CODE'
The final line, after expanding the text macro, becomes:
MySeg_text SEGMENT PUBLIC 'CODE'
The substitution operator separates the text-macro name from the text that
immediately follows it. The name appears to the assembler as segName_text
without the substitution operator, and the assembler fails to recognize
the text macro.
11.5.5 Macro Comments
A macro comment is any text in a macro definition that does not need to be
copied in the macro expansion. A double semicolon (;;) is used to start a
macro comment.
Syntax
;;text
All text following the double semicolon (;;) is ignored by the assembler
and will appear only in the macro definition when the source listing is
created.
The regular comment operator (;) can also be used in macros. However,
regular comments may appear in listings when the macro is expanded. Macro
comments will appear in the macro definition, but not in macro expansions.
Whether or not regular comments are listed in macro expansions depends on
the use of the .LALL, .XALL, and .SALL directives, as described in Section
12.2.3, "Controlling Page Breaks."
11.6 Using Recursive, Nested, and Redefined Macros
The concept of replacing macro names with predefined macro text is simple,
but in practice it has many implications and potentially unexpected side
effects. The following sections discuss advanced macro features (such as
nesting, recursion, and redefinition) and point out some side effects of
macros.
11.6.1 Using Recursion
Macro definitions can be recursive: that is, they can call themselves.
Using recursive macros is one way of doing repeated operations. The macro
does a task, and then calls itself to do the task again. The recursion is
repeated until a specified condition is met.
Example
pushall MACRO reg1,reg2,reg3,reg4,reg5,reg6
IFNB <reg1> ;; If parameter not blank
push reg1 ;; push one register and repeat
pushall reg2,reg3,reg4,reg5,reg6
ENDIF
ENDM
.
.
.
pushall ax,bx,si,ds
pushall cs,es
In this example, the pushall macro repeatedly calls itself to push a
register given in a parameter until no parameters are left to push. A
variable number of parameters (up to six) can be given.
11.6.2 Nesting Macro Definitions
One macro can define another. QuickAssembler does not process nested
definitions until the outer macro has been called. Therefore, nested
macros cannot be called until the outer macro has been called at least
once. Macro definitions can be nested to any depth. Nesting is limited
only by the amount of memory available when the source file is assembled.
Using a macro to create similar macros can make maintenance easier. If you
want to change all the macros, change the outer macro and it automatically
changes the others.
Example
shifts MACRO opname ; Define macro that defines macros
opname&s MACRO operand,rotates
IF rotates LE 4
REPT rotates
opname operand,1 ;; One at a time is faster
ENDM ;; for 4 or less on 8088/8086
ELSE
mov cl,rotates ;; Using CL is faster
opname operand,cl ;; for more than 4 on 8088/8086
ENDIF
ENDM
ENDM
shifts ror ; Call macro to new macros
shifts rol
shifts shr
shifts shl
shifts rcl
shifts rcr
shifts sal
shifts sar
.
.
.
shrs ax,5 ; Call defined macros
rols bx,3
This macro, when called as shown, creates macros for multiple shifts with
each of the shift and rotate instructions. All the macro names are
identical except for the instruction. For example, the macro for the SHR
instruction is called shrs; the macro for the ROL instruction is called
rols. If you want to enhance the macros by doing more parameter checking,
you can modify the original macro. Doing so will change the created macros
automatically. This macro uses the substitute operator, as described in
Section 11.5.1.
11.6.3 Nesting Macro Calls
Macro definitions can contain calls to other macros. Nested macro calls
are expanded like any other macro call, but only when the outer macro is
called.
Example
ex MACRO text,val ; Inner macro definition
IF2
%OUT The expression (text) has the value: &val
ENDIF
ENDM
express MACRO expression ; Outer macro definition
ex <expression>,%(expression)
ENDM
.
.
.
express <4 + 2 * 7 - 3 MOD 4>
The two sample macros enable you to print the result of a complex
expression to the screen by using the %OUT directive, even though that
directive expects text rather than an expression (see Section 12.1,
"Sending Messages to the Standard Output Device"). Being able to see the
value of an expression is convenient during debugging.
Both macros are necessary. The express macro calls the ex macro, using
operators to pass the expression both as text and as the value of the
expression. With the call in the example, the assembler sends the
following line to the standard output:
The expression (4 + 2 * 7 - 3 MOD 4) has the value: 15
You could get the same output by using only the ex macro, but you would
have to type the expression twice and supply the macro operators in the
correct places yourself. The express macro does this for you
automatically. Notice that expressions containing spaces must still be
enclosed in angle brackets. Section 11.5.2, "Literal-Text Operator,"
explains why.
11.6.4 Redefining Macros
Macros can be redefined. You do not need to purge the macro before
redefining it. The new definition automatically replaces the old
definition. If you redefine a macro from within the macro itself, make
sure there are no statements or comments between the ENDM directive of the
nested redefinition and the ENDM directive of the original macro.
Example
getasciiz MACRO
.DATA
max DB 80
actual DB ?
tmpstr DB 80 DUP (?)
.CODE
mov ah,0Ah
mov dx,OFFSET max
int 21h
mov bl,actual
xor bh,bh
mov tmpstr[bx],0
getasciiz MACRO
mov ah,0Ah
mov dx,OFFSET max
int 21h
mov bl,actual
xor bh,bh
mov tmpstr[bx],0
ENDM
ENDM
This macro allocates data space the first time it is called, and then
redefines itself so that it doesn't try to reallocate the data on
subsequent calls.
11.6.5 Avoiding Inadvertent Substitutions
QuickAssembler replaces all parameters when they occur with the
corresponding argument, even if the substitution is inappropriate. For
example, if you use a register name, such as AX or BH, as a parameter,
QuickAssembler replaces all occurrences of that name when it expands the
macro. If the macro definition contains statements that use the register,
not the parameter, the macro will be incorrectly expanded. QuickAssembler
will not warn you about using reserved names as macro parameters.
QuickAssembler does give a warning if you use a reserved name as a macro
name. You can ignore the warning, but be aware that the reserved name will
no longer have its original meaning. For example, if you define a macro
called ADD, the ADD instruction will no longer be available. Your ADD
macro takes its place.
11.7 Managing Macros and Equates
Macros and equates are often kept in a separate file and read into the
assembler source file at assembly time. In this way, libraries of related
macros and equates can be used by many different source files.
The INCLUDE directive is used to read an include file into a source file.
Memory can be saved by using the PURGE directive to delete the unneeded
macros from memory.
11.7.1 Using Include Files
The INCLUDE directive inserts source code from a specified file into the
source file from which the directive is given.
Syntax
INCLUDE filespec
The filespec must specify an existing file containing valid assembler
statements. When the assembler encounters an INCLUDE directive, it opens
the specified source file and begins processing its statements. When all
statements have been read, QuickAssembler continues with the statement
immediately following the INCLUDE directive.
The filespec can be given either as a file name, or as a complete or
relative file specification, including drive or directory name.
If a complete or relative file specification is given, QuickAssembler
looks for the include file only in the specified directory. If a file name
is given without a directory or drive name, QuickAssembler looks for the
file in the following order:
1. If paths are specified with the /I option, QuickAssembler looks for the
include file in the specified directory or directories.
2. QuickAssembler looks for the include file in the current directory.
3. If an INCLUDE environment variable is defined, QuickAssembler looks for
the include file in the directory or directories specified in the
environment variable.
Nested INCLUDE directives are allowed. QuickAssembler marks included
statements with the letter "C" in assembly listings.
Directories can be specified in INCLUDE path names with either the
backslash (\) or the forward slash (/). This is for XENIX(R)
compatibility.
──────────────────────────────────────────────────────────────────────────
NOTE Any standard code can be placed in an include file. However, include
files are usually used only for macros, equates, and standard segment
definitions. Standard procedures are usually assembled into separate
object files and linked with the main source modules.
──────────────────────────────────────────────────────────────────────────
Examples
INCLUDE fileio.mac ; File name only; use with
; /I or environment
INCLUDE b:\include\keybd.inc ; Complete file specification
INCLUDE /usr/jons/include/stdio.mac ; Path name in XENIX format
INCLUDE masm_inc\define.inc ; Partial path name in DOS format
; (relative to current directory)
11.7.2 Purging Macros from Memory
The PURGE directive can be used to delete a currently defined macro from
memory.
Syntax
PURGE macroname[[,macroname]]...
Each macroname is deleted from memory when the directive is encountered at
assembly time. Any subsequent call to that macro causes the assembler to
generate an error.
The PURGE directive is intended to clear memory space no longer needed by
a macro. If a macro has been used to redefine a reserved name, the
reserved name is restored to its previous meaning.
The PURGE directive can be used to clear memory if a macro or group of
macros is needed only for part of a source file.
It is not necessary to purge a macro before redefining it. Any
redefinition of a macro automatically purges the previous definition.
Also, a macro can purge itself as long as the PURGE directive is on the
last line of the macro.
The PURGE directive works by redefining the macro to a null string.
Therefore, calling a purged macro does not cause an error. The macro name
is simply ignored.
Examples
GetStuff
PURGE GetStuff
These examples call a macro and then purge it. You might need to purge
macros in this way if your system does not have enough memory to keep all
of the macros needed for a source file in memory at the same time.
────────────────────────────────────────────────────────────────────────────
Chapter 12: Controlling Assembly Output
QuickAssembler has two ways of communicating results. It can write
information to a listing or object file, or it can display messages to the
standard output device (normally the screen).
Both kinds of output can be controlled by menu commands and by source-file
statements. This chapter explains the directives that directly control
output through source-file statements.
12.1 Sending Messages to the Standard Output Device
The %OUT directive instructs the assembler to display text to the program
output window.
Syntax
%OUT text
The text can be any line of ASCII characters. If you want to display
multiple lines, you must use a separate %OUT directive for each line.
The directive is useful for displaying messages at specific points of a
long assembly. It can be used inside conditional-assembly blocks to
display messages when certain conditions are met.
The %OUT directive generates output for both assembly passes. The IF1 and
IF2 directives can be used for control when the directive is processed.
Macros that enable you to output the value of expressions are shown in
Section 11.6.3, "Nesting Macro Calls."
Example
IF1
%OUT First Pass - OK
ENDIF
This sample block could be placed at the end of a source file so that the
message First Pass - OK would be displayed at the end of the first pass,
but ignored on the second pass.
12.2 Controlling Page Format in Listings
QuickAssembler provides several directives for controlling the page format
of listings. These directives include the following:
Directive Action
──────────────────────────────────────────────────────────────────────────
TITLE Sets title for listings
SUBTTL Sets title for sections in listings
PAGE Sets page length and width, and controls page and
section breaks
12.2.1 Setting the Listing Title
The TITLE directive specifies a title to be used on each page of assembly
listings. In editor-based listing files (the default inside the QC
environment), the title is only printed once, at the top of the file.
Syntax
TITLE text
The text can be any combination of characters up to 60 in length. The
title is printed flush left on the second line of each page of the
listing.
If no TITLE directive is given, the title will be blank. No more than one
TITLE directive per module is allowed.
Example
TITLE Graphics Routines
This example sets the listing title. A page heading that reflects this
title is shown below:
Microsoft (R) QuickC with QuickAssembler Version 2.01 9/25/89 12:00:00
Graphics Routines
Page 1-2
12.2.2 Setting the Listing Subtitle
The SUBTTL directive specifies the subtitle used on each page of assembly
listings. In editor-based listing files (the default inside the QC
environment), the subtitle is ignored.
Syntax
SUBTTL text
The text can be any combination of characters up to 60 in length. The
subtitle is printed flush left on the third line of the listing pages.
If no SUBTTL directive is used, or if no text is given for a SUBTTL
directive, the subtitle line is left blank.
Any number of SUBTTL directives can be given in a program. Each new
directive replaces the current subtitle with the new text. SUBTTL
directives are often used just before a PAGE + statement, which creates a
new section (see Section 12.2.3, "Controlling Page Breaks").
Example
SUBTTL Point Plotting Procedure
PAGE +
The example above creates a section title and then creates a page break
and a new section. A page heading that reflects this title is shown below:
Microsoft (R) QuickC with QuickAssembler Version 2.01 9/25/89 12:00:00
Graphics Routines
Page 3-1
Point Plotting Procedure
12.2.3 Controlling Page Breaks
The PAGE directive can be used to designate the line length and width for
the program listing, to increment the section and adjust the section
number accordingly, or to generate a page break in the listing. In
editor-based listing files (the default inside the QC environment),
page-break directives are ignored, except for the page width specifier.
Syntax
PAGE [[[[length]],width]]
PAGE +
If length and width are specified, the PAGE directive sets the maximum
number of lines per page to length and the maximum number of characters
per line to width. The length must be in the range of 10-255 lines. The
default page length is 50 lines. The width must be in the range of 60-132
characters. The default page width is 80 characters. With editor-based
listing files, the default page width is 255. To specify the width without
changing the default length, use a comma before width.
If no argument is given, PAGE starts a new page in the program listing by
copying a form-feed character to the file and generating new title and
subtitle lines.
If a plus sign follows PAGE, a page break occurs, the section number is
incremented, and the page number is reset to 1. Program-listing page
numbers have the following format:
section-page
The section is the section number within the module, and page is the page
number within the section. By default, section and page numbers begin with
1-1. The SUBTTL directive and the PAGE directive can be used together to
start a new section with a new subtitle. See Section 12.2.2, "Setting the
Listing Subtitle," for an example.
Example 1
PAGE
Example 1 creates a page break.
Example 2
PAGE 58,90
Example 2 sets the maximum page length to 58 lines and the maximum width
to 90 characters.
Example 3
PAGE ,132
Example 3 sets the maximum width to 132 characters. The current page
length (either the default of 50 or a previously set value) remains
unchanged.
Example 4
PAGE +
Example 4 creates a page break, increments the current section number, and
sets the page number to 1. For example, if the preceding page was 3-6, the
new page would be 4-1.
12.2.4 Naming the Module
The assembler automatically uses the base file name of the source file as
the name of the module. This name is used to identify error messages when
you run the assembler from the command line.
12.3 Controlling the Contents of Listings
QuickAssembler provides several directives for controlling what text will
be shown in listings. The directives that control the contents of listings
are shown below:
Directive Action
──────────────────────────────────────────────────────────────────────────
.LIST Lists statements in program listing
.XLIST Suppresses listing of statements
.LFCOND Lists false-conditional blocks in program listing
.SFCOND Suppresses false-conditional listing
.TFCOND Toggles false-conditional listing
.LALL Includes macro expansions in program listing
.SALL Suppresses listing of macro expansions
.XALL Excludes comments from macro listing
12.3.1 Suppressing and Restoring Listing Output
The .LIST and .XLIST directives specify which source lines are included in
the program listing.
Syntax
.LIST
.XLIST
The .XLIST directive suppresses copying of subsequent source lines to the
program listing. The .LIST directive restores copying. The directives are
typically used in pairs to prevent a particular section of a source file
from being copied to the program listing.
The .XLIST directive overrides other listing directives, such as .SFCOND
or .LALL.
Example
.XLIST ; Listing suspended here
.
.
.
.LIST ; Listing resumes here
.
.
.
12.3.2 Controlling Listing of Conditional Blocks
The .SFCOND, .LFCOND, and .TFCOND directives control whether
false-conditional blocks should be included in assembly listings.
Syntax
.SFCOND
.LFCOND
.TFCOND
The .SFCOND directive suppresses the listing of any subsequent conditional
blocks whose condition is false. The .LFCOND directive restores the
listing of these blocks. Like .LIST and .XLIST, conditional-listing
directives can be used to suppress listing of conditional blocks in
sections of a program.
The .TFCOND directive toggles the current status of listing of conditional
blocks. This directive can be used in conjunction with the /Sx option of
the assembler. By default, conditional blocks are not listed on start-up.
However, they will be listed on start-up if the /Sx option is given. This
means that using /Sx reverses the meaning of the first .TFCOND directive
in the source file. The /Sx option is discussed in Appendix B, Section
B.14, "Listing False Conditionals."
Example
test1 EQU 0 ; Defined to make all conditionals false
; /Sx not used /Sx used
.TFCOND
IFNDEF test1 ; Listed Not listed
test2 DB 128
ENDIF
.TFCOND
IFNDEF test1 ; Not listed Listed
test3 DB 128
ENDIF
.SFCOND
IFNDEF test1 ; Not listed Not listed
test4 DB 128
ENDIF
.LFCOND
IFNDEF test1 ; Listed Listed
test5 DB 128
ENDIF
In the example above, the listing status for the first two conditional
blocks would be different, depending on whether the /X option was used.
The blocks with .SFCOND and .LFCOND would not be affected by the /X
option.
12.3.3 Controlling Listing of Macros
The .LALL, .XALL, and .SALL directives control the listing of the expanded
macro calls. The assembler always lists the full macro definition. The
directives only affect expansion of macro calls.
Syntax
.LALL
.XALL
.SALL
The .LALL directive causes QuickAssembler to list all the source
statements in a macro expansion, including normal comments (preceded by a
single semicolon) but not macro comments (preceded by a double semicolon).
The .XALL directive causes QuickAssembler to list only those source
statements in a macro expansion that generate code or data. For instance,
comments, equates, and segment definitions are ignored.
The .SALL directive causes QuickAssembler to suppress listing of all macro
expansions. The listing shows the macro call, but not the source lines
generated by the call.
The .XALL directive is in effect when QuickAssembler first begins
execution.
Example
tryout MACRO param
;; Macro comment
; Normal comment
it EQU 3 ; No code or data
ASSUME es:_DATA ; No code or data
DW param ; Generates data
mov ax,it ; Generates code
ENDM
.
.
.
.LALL
tryout 6 ; Call with .LALL
.XALL
tryout 6 ; Call with .XALL
.SALL
tryout 6 ; Call with .SALL
The macro calls in the example generate the following listing lines:
.LALL
tryout 6 ; Call with .LALL
1 ; Normal comment
= 0003 1 it EQU 3 ; No code or data
1 ASSUME es:_TEXT ; No code or data
0015 0006 1 DW 6 ; Generates data
0017 B8 0003 1 mov ax,it ; Generates code
.XALL
tryout 6 ; Call with .XALL
001A 0006 1 DW 6 ; Generates data
001C B8 0003 1 mov ax,it ; Generates code
.SALL
tryout 6 ; Call with .SALL
Notice that the macro comment is never listed in macro expansions. Normal
comments are listed only with the .LALL directive.
────────────────────────────────────────────────────────────────────────────
PART 3: Using Instructions
Part 3 of the Programmer's Guide (comprising Chapters 13-18) explains
how to use instructions in assembly-language source code. Instructions
constitute the actual steps of your program and are translated into
machine-code statements that the processor executes at run time.
Part 3 is organized topically, with related instructions discussed
together. Chapter 13 explains the instructions for moving data from one
location to another. The instructions for performing calculations on
numbers and bits are covered in Chapter 14.
The 8086-family processors provide four major types of instructions for
controlling program flow, as described in Chapter 15. Chapter 16
explains the instructions and techniques for processing strings. The
8087-family coprocessors and their instructions are explained in Chapter
17. Finally, Chapter 18 summarizes the instructions available for
processor control.
────────────────────────────────────────────────────────────────────────────
Chapter 13: Loading, Storing, and Moving Data
The 8086-family processors provide several instructions for loading,
storing, or moving various kinds of data. Among the types of transferable
data are variables, pointers, and flags. Data can be moved to and from
registers, memory, ports, and the stack. This chapter explains the
instructions for moving data from one location to another.
13.1 Transferring Data
Moving data is one of the most common tasks in assembly-language
programming. Data can be moved between registers or between memory and
registers. Immediate data can be loaded into registers or into memory.
Furthermore, all memory-to-memory operations are illegal. To move data
from one memory location to another, you must first move the data to an
intermediate register.
13.1.1 Copying Data
The MOV instruction is the most common method of moving data. This
instruction can be thought of as a copy instruction, since it always
copies the source operand to the destination operand. Immediately after a
MOV instruction, the source and destination operands both contain the same
value. The old value in the destination operand is destroyed.
Syntax
MOV {register | memory},{register | memory | immediate}
Example 1
mov ax,7 ; Immediate to register
mov mem,7 ; Immediate to memory direct
mov mem[bx],7 ; Immediate to memory indirect
mov mem,ds ; Segment register to memory
mov mem,ax ; Register to memory direct
mov mem[bx],ax ; Register to memory indirect
mov ax,mem ; Memory direct to register
mov ax,mem[bx] ; Memory indirect to register
mov ds,mem ; Memory to segment register
mov ax,bx ; Register to register
mov ds,ax ; General register to segment register
mov ax,ds ; Segment register to general register
The statements in Example 1 illustrate each type of memory move that can
be done with a single instruction. Example 2 illustrates several common
types of moves that require two instructions.
Example 2
; Move immediate to segment register
mov ax,DGROUP ; Load immediate to general register
mov ds,ax ; Store general register to segment register
; Move memory to memory
mov ax,mem1 ; Load memory to general register
mov mem2,ax ; Store general register to memory
; Move segment register to segment register
mov ax,ds ; Load segment register to general register
mov es,ax ; Store general register to segment register
13.1.2 Exchanging Data
The XCHG (Exchange) instruction exchanges the data in the source and
destination operands. Data can be exchanged between registers or between
registers and memory.
Syntax
XCHG {register | memory},{register | memory}
Examples
xchg ax,bx ; Put AX in BX and BX in AX
xchg memory,ax ; Put "memory" in AX and AX in "memory"
13.1.3 Looking Up Data
The XLAT (Translate) instruction is used to load data from a table in
memory. The instruction is useful for translating bytes from one coding
system to another.
Syntax
XLAT[[B]] [[[[segment:]]memory]]
The BX register must contain the address of the start of the table. By
default, the DS register contains the segment of the table, but a segment
override can be used to specify a different segment. The operand need not
be given except when specifying a segment override.
Before the XLAT instruction is called, the AL register should contain a
value that points into the table (the start of the table is considered 0).
After the instruction is called, AL will contain the table value pointed
to. For example, if AL contains 7, the 8th byte of the table will be
placed in the AL register.
──────────────────────────────────────────────────────────────────────────
NOTE For compatibility with Intel 80386 mnemonics, QuickAssembler
recognizes XLATB as a synonym for XLAT. In the Intel syntax, XLAT requires
an operand; XLATB does not allow one. Quick-Assembler never requires an
operand, but always allows one.
──────────────────────────────────────────────────────────────────────────
Example
; Table of Hexadecimal digits
hex DB "0123456789ABCDEF"
convert DB "You pressed the key with ASCII code "
key DB ?,?,"h",13,10,"$"
.CODE
.
.
.
mov ah,8 ; Get a key in AL
int 21h ; Call DOS
mov bx,OFFSET hex ; Load table address
mov ah,al ; Save a copy in high byte
and al,00001111b ; Mask out top character
xlat ; Translate
mov key[1],al ; Store the character
mov cl,12 ; Load shift count
shr ax,cl ; Shift high character into position
xlat ; Translate
mov key,al ; Store the character
mov dx,OFFSET convert ; Load message
mov ah,9 ; Display it
int 21h ; Call DOS
This example looks up hexadecimal characters in a table in order to
convert an eight-bit binary number to a string representing a hexadecimal
number.
13.1.4 Transferring Flags
The 8086-family processors provide instructions for loading and storing
flags in the AH register.
Syntax
LAHF
SAHF
The status of the lower byte of the flags register can be saved to the AH
register with LAHF and then later restored with SAHF. If you need to save
and restore the entire flags register, use PUSHF and POPF, as described in
Section 13.4.3, "Saving Flags on the Stack."
SAHF is often used with a coprocessor to transfer coprocessor control
flags to processor control flags. Section 17.7, "Controlling Program
Flow," explains and illustrates this technique.
13.2 Converting between Data Sizes
Since moving data between registers of different sizes is illegal, you
must take special steps if you need to extend a register value to a larger
register or register pair.
The procedure is different for signed and unsigned values. The processor
cannot tell the difference between signed and unsigned numbers; the
programmer has to understand this difference and program accordingly.
13.2.1 Extending Signed Values
The CBW (Convert Byte to Word) and CWD (Convert Word to Doubleword)
instructions are provided to sign-extend values. Sign-extending means
copying the sign bit of the unextended operand to all bits of the extended
operand.
Syntax
CBW
CWD
The CBW instruction converts an 8-bit signed value in AL to a 16-bit
signed value in AX. The CWD instruction is similar except that it
sign-extends a 16-bit value in AX to a 32-bit value in the DX:AX register
pair. Both instructions work only on values in the accumulator register.
Example
.DATA
mem8 DB -5
mem16 DW -5
.CODE
.
.
.
mov al,mem8 ; Load 8-bit -5 (FBh)
cbw ; Convert to 16-bit -5 (FFFBh) in AX
mov ax,mem16 ; Load 16-bit -5 (FFFBh)
cwd ; Convert to 32-bit -5 (FFFF:FFFBh)
; in DX:AX
13.2.2 Extending Unsigned Values
To extend unsigned numbers, set the value of the upper register to 0.
Example
.DATA
mem8 DB 251
mem16 DW 251
.CODE
.
.
.
mov al,mem8 ; Load 251 (FBh) from 8-bit memory
xor ah,ah ; Zero upper half (AH)
mov ax,mem16 ; Load 251 (FBh) from 16-bit memory
xor dx,dx ; Zero upper half (DX)
13.3 Loading Pointers
The 8086-family processors provide several instructions for loading
pointer values into registers or register pairs. They can be used to load
either near or far pointers.
13.3.1 Loading Near Pointers
The LEA instruction loads a near pointer into a specified register.
Syntax
LEA register,memory
The destination register may be any general-purpose register. The source
operand may be any memory operand. The effective address of the source
operand is placed in the destination register.
The LEA instruction can be used to calculate the effective address of a
direct memory operand, but this is usually not efficient, since the
address of a direct memory operand is a constant known at assembly time.
For example, the following statements have the same effect, but the second
version is faster:
lea dx,string ; Load effective address - slow
mov dx,OFFSET string ; Load offset - fast
The LEA instruction is more useful for calculating the address of indirect
memory operands:
lea dx,string[si] ; Load effective address
13.3.2 Loading Far Pointers
The LDS and LES instructions load far pointers.
Syntax
LDS register,memory
LES register,memory
The memory address being pointed to is specified in the source operand,
and the register where the offset will be stored is specified in the
destination operand.
The address must be stored in memory with the segment in the upper word
and the offset in the lower word. The segment register where the segment
will be stored is specified in the instruction name. For example, LDS puts
the segment in DS, and LES puts the segment in ES. The instructions are
often used with string instructions, as explained in Chapter 16,
"Processing Strings."
Example
.DATA
string DB "This is a string."
fpstring DD string ; Far pointer to string
pointers DD 100 DUP (?)
.CODE
.
.
.
les di,fpstring ; Put address in ES:DI pair
lds si,pointers[bx] ; Put address in DS:SI pair
13.4 Transferring Data to and from the Stack
A "stack" is an area of memory for storing temporary data. Unlike other
segments in which data is stored starting from low memory, data on the
stack is stored in reverse order starting from high memory.
Initially, the stack is an uninitialized segment of a finite size. As data
is added to the stack at run time, the stack grows downward from high
memory to low memory. When items are removed from the stack, it shrinks
upward from low memory to high memory.
The stack has several purposes in the 8086-family processors. The CALL,
INT, RET, and IRET instructions automatically use the stack to store the
calling addresses of procedures and interrupts (see Sections 15.3, "Using
Procedures," and 15.4, "Using Interrupts"). You can also use the PUSH and
POP instructions and their variations to store values on the stack.
13.4.1 Pushing and Popping
In 8086-family processors, the SP (Stack Pointer) register always points
to the current location in the stack. The PUSH and POP instructions use
the SP register to keep track of the current position in the stack.
The values pointed to by the BP and SP registers are relative to the SS
(Stack Segment) register. The BP register is often used to point to the
base of a frame of reference (a stack frame) within the stack.
Syntax
PUSH {register | memory}
POP {register | memory}
PUSH immediate (80186-80386 only)
The PUSH instruction is used to store a two-byte operand on the stack. The
POP instruction is used to retrieve a previously pushed value. When a
value is pushed onto the stack, the SP register is decreased by 2. When a
value is popped off the stack, the SP register is increased by 2. Although
the stack always contains word values, the SP register points to bytes.
Thus, SP changes in multiples of 2.
──────────────────────────────────────────────────────────────────────────
NOTE The 8088 and 8086 processors differ from later Intel processors in
how they push and pop the SP register. If you give the statement push sp
with the 8088 or 8086, the word pushed will be the word in SP after the
push operation.
──────────────────────────────────────────────────────────────────────────
Figure 13.1 illustrates how pushes and pops change the SP register.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 13.4.1 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The PUSH and POP instructions are almost always used in pairs. Words are
popped off the stack in reverse order from the order in which they are
pushed onto the stack. You should normally do the same number of pops as
pushes to return the stack to its original status. However, it is possible
to return the stack to its original status by subtracting the correct
number of words from the SP register.
Values on the stack can be accessed by using indirect memory operands with
BP as the base register.
Example
mov bp,sp ; Set stack frame
push ax ; Push first; SP = BP + 2
push bx ; Push second; SP = BP + 4
push cx ; Push third; SP = BP + 6
.
.
.
mov ax,[bp+6] ; Put third in AX
mov bx,[bp+4] ; Put second in BX
mov cx,[bp+2] ; Put first in CX
.
.
.
sub sp,6 ; Restore stack pointer
; two bytes per push
80186/286/386 Only
Starting with the 80186 processor, the PUSH instruction can be given with
an immediate operand. For example, the following statement is legal on the
80186, 80286, and 80386 processors:
push 7 ; 3 clocks on 80286
This statement is faster than the following equivalent statements, which
are required on the 8088 or 8086:
mov ax,7 ; 2 clocks on 80286
push ax ; 3 clocks on 80286
13.4.2 Using the Stack
The stack can be used to store temporary data. For example, in the
Microsoft calling convention, the stack is used to pass arguments to a
procedure. The arguments are pushed onto the stack before the call. The
procedure retrieves and uses them. Then the stack is restored to its
original position at the end of the procedure. The stack can also be used
to store variables that are local to a procedure. Both of these techniques
are discussed in Section 15.3, "Using Procedures."
Another common use of the stack is to store temporary data when there are
no free registers available or when a particular register must hold more
than one value. For example, the CX register usually holds the count for
loops. If two loops are nested, the outer count is loaded into CX at the
start. When the inner loop starts, the outer count is pushed onto the
stack and the inner count loaded into CX. When the inner loop finishes,
the original count is popped back into CX.
Example
mov cx,10 ; Load outer loop counter
outer: .
. ; Start outer loop task
.
push cx ; Save outer loop value
mov cx,20 ; Load inner loop counter
inner: .
. ; Do inner loop task
.
loop inner
pop cx ; Restore outer loop counter
.
. ; Continue outer loop task
.
loop outer
13.4.3 Saving Flags on the Stack
Flags can be pushed and popped onto the stack using the PUSHF and POPF
instructions.
Syntax
PUSHF
POPF
These instructions are sometimes used to save the status of flags before a
procedure call and then to restore the same status after the procedure.
They can also be used within a procedure to save and restore the flag
status of the caller.
Example
pushf
call systask
popf
13.4.4 Saving All Registers on the Stack
80186/286/386 Only
Starting with the 80186 processor, the PUSHA and POPA instructions were
implemented to push or pop all the general-purpose registers with one
instruction.
Syntax
PUSHA
POPA
These instructions can be used to save the status of all registers before
a procedure call and then to restore them after the return. Using PUSHA
and POPA instructions is significantly faster and takes fewer bytes of
code than pushing and popping each register individually.
The registers are pushed in the following order: AX, CX, DX, BX, SP, BP,
SI, and DI. The SP word pushed is the value before the first register is
pushed. The registers are popped in the opposite order.
Example
pusha
call systask
popa
13.5 Transferring Data to and from Ports
"Ports" are the gateways between hardware devices and the processor. Each
port has a unique number through which it can be accessed. Ports can be
used for low-level communication with devices, such as disks, the video
display, or the keyboard. The OUT instruction is used to send data to a
port; the IN instruction receives data from a port.
Syntax
IN accumulator,{portnumber | DX}
OUT {portnumber | DX},accumulator
When using the IN and OUT instructions, the number of the port can either
be an eight-bit immediate value or the DX register. You must use DX for
ports with a number higher than 256. The value to be received from the
port must be in the accumulator register (AX for word values or AL for
byte values).
When using the IN instruction, the number of the port is given as the
source operand and the value to be sent to the port is the destination
operand. When using the OUT instruction, the number of the port is given
as the destination operand and the value to be sent to the port is the
source operand.
In applications programming, most communication with hardware is done with
DOS or ROM-BIOS calls. Ports are more often used in systems programming.
Since systems programming is beyond the scope of this manual and since
ports differ depending on hardware, the IN and OUT instructions are not
explained in detail here.
Example
; Actual values are hardware dependent
sound EQU 61h ; Port to chip that controls speaker
timer EQU 42h ; Port to chip that pulses speaker
on EQU 00000011b ; Bits 0 and 1 turn on speaker
in al,sound ; Get current port setting
or al,on ; Turn on speaker and connect timer
out sound,al ; Put value back in port
mov al,50 ; Start at 50
sounder: out timer,al ; Send byte to timer port...
mov cx,2000 ; Loop 2000 times to delay
hold: loop hold
dec al ; Go down one step
jnz sounder ; Repeat for each step
in al,sound ; Get port value
and al,NOT on ; Turn it back off
out sound,al ; Put it back in port
This example creates a sound of ascending frequency on the IBM PC and
IBM-compatible computers. The technique of making sound or the port values
used may be different on other hardware.
80186/286/386 Only
Starting with the 80186 processor, instructions were implemented to send
strings of data to and from ports. The instructions are INS, INSB, INSW,
OUTS, OUTSB, and OUTSW. The operation of these instructions is much like
the operation of other string instructions. They are discussed in Section
16.7, "Transferring Strings to and from Ports."
────────────────────────────────────────────────────────────────────────────
Chapter 14: Doing Arithmetic and Bit Manipulations
The 8086-family processors provide instructions for doing calculations on
byte, word, and doubleword values. Operations include addition,
subtraction, multiplication, and division. You can also do calculations at
the bit level. This includes the AND, OR, XOR, and NOT logical operations.
Bits can also be shifted or rotated to the right or left.
This chapter tells you how to use the instructions that do calculations on
numbers and bits.
14.1 Adding
The ADD, ADC, and INC instructions are used for adding and incrementing
values.
Syntax
ADD {register | memory},{register | memory | immediate}
ADC {register | memory},{register | memory | immediate}
INC {register | memory}
These instructions can work directly on 8-bit or 16-bit values. They can
also be used in combination to do calculations on values that are too
large to be held in a single register (such as 32-bit values). When used
with AAA and DAA, they can be used to do calculations on binary coded
decimal (BCD) numbers, as described in Section 14.5.
14.1.1 Adding Values Directly
The ADD and INC instructions are used for adding to values in registers or
memory.
The INC instruction takes a single register or memory operand. The value
of the operand is incremented. The value is treated as an unsigned
integer, so the carry flag is not updated for signed carries.
The ADD instruction adds values given in source and destination operands.
The destination can be either a register or a memory operand. Its contents
will be destroyed by the operation. The source operand can be an
immediate, memory, or register operand. Since memory-to-memory operations
are never allowed, the source and destination operands can never both be
memory operands.
The result of the operation is stored in the source operand. The operands
can be either 8-bit or 16-bit, but both must be the same size.
An addition operation can be interpreted as addition of either signed
numbers or unsigned numbers. It is the programmer's responsibility to
decide how the addition should be interpreted and to take appropriate
action if the sum is too large for the destination operand. When an
addition overflows the possible range for signed numbers, the overflow
flag is set. When an addition overflows the range for unsigned numbers,
the carry flag is set.
There are two ways to take action on an overflow: you can use the JO or
JNO instruction to direct program flow to or around instructions that
handle the overflow (see Section 15.1.2.3, "Testing Bits and Jumping").
You can also use the INTO instruction to trigger the overflow interrupt
(interrupt 4) if the overflow flag is set. This requires writing an
interrupt handler for interrupt 4, since the DOS overflow routine simply
returns without taking any action. Section 15.4.2, "Defining and
Redefining Interrupt Routines," gives a sample of an overflow interrupt
handler.
Example
.DATA
mem8 DB 39
.CODE
.
.
. ; unsigned signed
mov al,26 ; Start with register 26 26
inc al ; Increment 1 1
add al,76 ; Add immediate + 76 76
; ---- ----
; 103 103
add al,mem8 ; Add memory + 39 39
; ---- ----
mov ah,al ; Copy to AH 142 -114+overflow
add al,ah ; Add register 142
; ----
; 28+carry
This example shows 8-bit addition. When the sum exceeds 127, the overflow
flag is set. A JO (Jump On Overflow) or INTO (Interrupt On Overflow)
instruction at this point could transfer control to error-recovery
statements. When the sum exceeds 255, the carry flag is set. A JC (Jump On
Carry) instruction at this point could transfer control to error-recovery
statements.
14.1.2 Adding Values in Multiple Registers
The ADC (Add with Carry) instruction makes it possible to add numbers
larger than can be held in a single register.
The ADC instruction adds two numbers in the same fashion as the ADD
instruction, except that the value of the carry flag is included in the
addition. If a previous calculation has set the carry flag, then 1 will be
added to the sum of the numbers. If the carry flag is not set, the ADC
instruction has the same effect as the ADD instruction.
When adding numbers in multiple registers, the carry flag should be
ignored for the least-significant portion, but taken into account for the
most-significant portion. This can be done by using the ADD instruction
for the least-significant portion and the ADC instruction for
most-significant portion.
You can add and carry repeatedly inside a loop for calculations that
require more than two registers. Use the ADC instruction in each
iteration, but turn off the carry flag with the CLC (Clear Carry Flag)
instruction before entering the loop so that it will not be used for the
first iteration. You could also do the first add outside the loop.
Example
.DATA
mem32 DD 316423
.CODE
.
.
.
mov ax,43981 ; Load immediate 43981
sub dx,dx ; into DX:AX
add ax,WORD PTR mem32[0] ; Add to both + 316423
adc dx,WORD PTR mem32[2] ; memory words ------
; Result in DX:AX 360404
14.2 Subtracting
The SUB, SBB, DEC, and NEG instructions are used for subtracting and
decrementing values.
Syntax
SUB {register | memory},{register | memory | immediate}
SBB {register | memory},{register | memory | immediate}
DEC {register | memory}
NEG {register | memory}
These instructions can work directly on 8-bit or 16-bit values. They can
also be used in combination to do calculations on values too large to be
held in a single register. When used with AAA and DAA, they can be used to
do calculations on BCD numbers, as described in Section 14.5,
"Calculating with Binary Coded Decimals."
14.2.1 Subtracting Values Directly
The SUB and DEC instructions are used for subtracting from values in
registers or memory. A related instruction, NEG (Negate), reverses the
sign of a number.
The DEC instruction takes a single register or memory operand. The value
of the operand is decremented. The value is treated as an unsigned
integer, so the carry flag is not updated for signed borrows.
The NEG instruction takes a single register or memory operand. The sign of
the value of the operand is reversed. The NEG instruction should only be
used on signed numbers.
The SUB instruction subtracts the values given in the source operand from
the value of the destination operand. The destination can be either a
register or a memory operand. It will be destroyed by the operation. The
source operand can be an immediate, memory, or register operand. It will
not be destroyed by the operation. Since memory-to-memory operations are
never allowed, the source and destination operands cannot both be memory
operands.
The result of the operation is stored in the source operand. The operands
can be either 8-bit or 16-bit, but both must be the same size.
A subtraction operation can be interpreted as subtraction of either signed
numbers or unsigned numbers. It is the programmer's responsibility to
decide how the subtraction should be interpreted and to take appropriate
action if the result is too small for the destination operand. When a
subtraction overflows the possible range for signed numbers, the carry
flag is set. When a subtraction underflows the range for unsigned numbers
(becomes negative), the sign flag is set.
Example
.DATA
mem8 DB 122
.CODE
.
.
. ; signed unsigned
mov al,95 ; Load register 95 95
dec al ; Decrement - 1 - 1
sub al,23 ; Subtract immediate - 23 - 23
; ---- ----
; 71 71
sub al,mem8 ; Subtract memory - 122 - 122
; ---- ----
; - 51 205+sign
mov ah,119 ; Load register 119
sub al,ah ; and subtract - 51
; ----
; 86+overflow
This example shows 8-bit subtraction. When the result goes below 0, the
sign flag is set. A JS (Jump On Sign) instruction at this point could
transfer control to error-recovery statements. When the result goes below
-128, the carry flag is set. A JC (Jump On Carry) instruction at this
point could transfer control to error-recovery statements.
14.2.2 Subtracting with Values in Multiple Registers
The SBB (Subtract with Borrow) instruction makes it possible to subtract
from numbers larger than can be held in a single register.
The SBB instruction subtracts two numbers in the same fashion as the SUB
instruction except that the value of the carry flag is included in the
subtraction. If a previous calculation has set the carry flag, then 1 will
be subtracted from the result. If the carry flag is not set, the SBB
instruction has the same effect as the SUB instruction.
When subtracting numbers in multiple registers, the carry flag should be
ignored for the least-significant portion, but taken into account for the
most-significant portion. This can be done by using the SUB instruction
for the least-significant portion and the SBB instruction for
most-significant portions.
You can subtract and borrow repeatedly inside a loop for calculations that
require more than two registers. Use the SBB instruction in each
iteration, but turn off the carry flag with the CLC (Clear Carry Flag)
instruction before entering the loop so that it will not be used for the
first iteration. You could also do the first subtraction outside the loop.
Example
.DATA
mem32a DD 316423
mem32b DD 156739
.CODE
.
.
.
mov ax,WORD PTR mem32a[0] ; Load mem32 316423
mov dx,WORD PTR mem32a[2] ; into DX:AX
sub ax,WORD PTR mem32b[0] ; Subtract low 156739
sbb dx,WORD PTR mem32b[2] ; then high ------
; Result in DX:AX 159684
14.3 Multiplying
The MUL and IMUL instructions are used to multiply numbers. The MUL
instruction should be used for unsigned numbers; the IMUL instruction
should be used for signed numbers. This is the only difference between the
two.
Syntax
MUL {register | memory}
IMUL {register | memory}
The multiply instructions require that one of the factors be in the
accumulator register (AL for 8-bit numbers or AX for 16-bit numbers). This
register is implied; it should not be specified in the source code. Its
contents will be destroyed by the operation.
The other factor to be multiplied must be specified in a single register
or memory operand. The operand will not be destroyed by the operation,
unless it is DX, AX, AH, or AL. A number may be squared by loading it into
the accumulator, and then executing a multiplication instruction with the
accumulator as the operand.
Note that multiplying two 8-bit numbers will produce a 16-bit number. If
the product is a 16-bit number, it will be placed in AX and the overflow
and carry flags will be set.
Similarly, multiplying two 16-bit numbers will produce a 32-bit number in
the DX:AX register pair. If the product is a 32-bit number, the
least-significant bits will be in AX, the most-significant bits will be in
DX, and the overflow and carry flags will be set.
──────────────────────────────────────────────────────────────────────────
NOTE Multiplication is one of the slower operations on 8086-family
processors (especially the 8086 and 8088). Multiplying by certain common
constants is often faster when done by shifting bits (see Section 14.7.1,
"Multiplying and Dividing by Constants").
──────────────────────────────────────────────────────────────────────────
Examples
.DATA
mem16 DW -30000
.CODE
.
.
. ; 8-bit unsigned multiply
mov al,23 ; Load AL 23
mov bl,24 ; Load BL * 24
mul bl ; Multiply BL -----
; 16-bit signed multiply
mov ax,50 ; Load AX 50
; -30000
imul mem16 ; Multiply memory -----
; Product in DX:AX -1500000
; overflow and carry set
80186/286/386 Only
Starting with the 80186 processor, the IMUL instruction has two additional
syntaxes that allow for 16-bit multiples that produce a 16-bit product.
Syntax
IMUL register16, immediate
IMUL register16, memory16, immediate
You can specify a 16-bit immediate value as the source instruction and a
word register as the destination operand. The product appears in the
destination operand. The 16-bit result will be placed in the destination
operand. If the product is too large to fit in 16 bits, the carry and
overflow flags will be set. In this context, IMUL can be used for either
signed or unsigned multiplication, since the 16-bit product is the same.
You can also specify three operands for IMUL. The first operand must be a
16-bit register operand, the second a 16-bit memory operand, and the third
a 16-bit immediate operand. The second and third operands are multiplied
and the product stored in the first operand.
With both of these syntaxes, the carry and overflow flags will be set if
the product is too large to fit in 16 bits. The IMUL instruction with
multiple operands can be used for either signed or unsigned
multiplication, since the 16-bit product is the same in either case. If
you need to get a 32-bit result, you must use the single-operand version
of MUL or IMUL.
Examples
imul dx,456 ; Multiply DX times 456
imul ax,[bx],6 ; Multiply the value pointed to by BX
; times 6 and put the result in AX
14.4 Dividing
The DIV and IDIV instructions are used to divide integers. Both a quotient
and a remainder are returned. The DIV instruction should be used for
unsigned integers; the IDIV instruction should be used for signed
integers. This is the only difference between the two.
Syntax
DIV {register | memory}
IDIV {register | memory}
To divide a 16-bit number by an 8-bit number, put the number to be divided
(the dividend) in the AX register. The contents of this register will be
destroyed by the operation. Specify the dividing number (the divisor) in
any 8-bit memory or register operand (except AL or AH). This operand will
not be changed by the operation. After the multiplication, the result
(quotient) will be in AL and the remainder will be in AH.
To divide a 32-bit number by a 16-bit number, put the dividend in the
DX:AX register pair. The least-significant bits go in AX. The contents of
these registers will be destroyed by the operation. Specify the divisor in
any 16-bit memory or register operand (except AX or DX). This operand will
not be changed by the operation. After the division, the quotient will be
in AX and the remainder will be in DX.
To divide a 16-bit number by a 16-bit number, you must first sign-extend
or zero-extend (see Section 13.2, "Converting between Data Sizes") the
dividend to 32 bits; then divide as described above. You cannot divide a
32-bit number by another 32-bit number.
If division by zero is specified, or if the quotient exceeds the capacity
of its register (AL or AX), the processor automatically generates an
interrupt 0. By default, the program terminates and returns to DOS. This
problem can be handled in two ways: check the divisor before division and
go to an error routine if you can determine it to be invalid, or write
your own interrupt routine to replace the processor's interrupt 0 routine.
See Section 15.4 for more information on interrupts.
──────────────────────────────────────────────────────────────────────────
NOTE Division is one of the slower operations on 8086-family processors
(especially the 8086 and 8088). Dividing by common constants that are
powers of two is often faster when done by shifting bits, as described in
Section 14.7.1, "Multiplying and Dividing by Constants."
──────────────────────────────────────────────────────────────────────────
Examples
.DATA
mem16 DW -2000
mem32 DD 500000
.CODE
.
. ; Divide 16-bit unsigned by 8-bit
.
mov ax,700 ; Load dividend 700
mov bl,36 ; Load divisor DIV 36
div bl ; Divide BL -----
; Quotient in AL 19
; Remainder in AH 16
; Divide 32-bit signed by 16-bit
mov ax,WORD PTR mem32[0] ; Load into DX:AX
mov dx,WORD PTR mem32[2] ; 500000
idiv mem16 ; DIV -2000
; Divide memory ------
; Quotient in AX -250
; Remainder in DX 0
; Divide 16-bit signed by 16-bit
mov ax,WORD PTR mem16 ; Load into AX -2000
cwd ; Extend to DX:AX
mov bx,-421 ; DIV -421
idiv bx ; Divide by BX -----
; Quotient in AX 4
; Remainder in DX -316
14.5 Calculating with Binary Coded Decimals
The 8086-family processors provide several instructions for adjusting BCD
numbers. The BCD format is seldom used for applications programming in
assembly language. Programmers who wish to use BCD numbers usually use a
high-level language. However, BCD instructions are used to develop
compilers, function libraries, and other systems tools.
Since systems programming is beyond the scope of this manual, this section
provides only a brief overview of calculations on the two kinds of BCD
numbers, unpacked and packed.
──────────────────────────────────────────────────────────────────────────
NOTE Intel mnemonics use the term "ASCII" to refer to unpacked BCD
numbers and "decimal" to refer to packed BCD numbers. Thus AAA (ASCII
Adjust After Addition) adjusts unpacked numbers, while DAA (Decimal Adjust
After Addition) adjusts packed numbers.
──────────────────────────────────────────────────────────────────────────
14.5.1 Unpacked BCD Numbers
Unpacked BCD numbers are made up of bytes containing a single decimal
digit in the lower four bits of each byte. The 8086-family processors
provide instructions for adjusting unpacked values with the four
arithmetic operations──addition, subtraction, multiplication, and
division.
To do arithmetic on unpacked BCD numbers, you must do the eight-bit
arithmetic calculations on each digit separately. The result should always
be in the AL register. After each operation, use the corresponding BCD
instruction to adjust the result. The ASCII-adjust instructions do not
take an operand. They always work on the value in the AL register.
When a calculation using two one-digit values produces a two-digit result,
the ASCII-adjust instructions put the first digit in AL and the second in
AH. If the digit in AL needs to carry to or borrow from the digit in AH,
the carry and auxiliary carry flags are set.
The four ASCII-adjust instructions are described below:
Instruction Description
──────────────────────────────────────────────────────────────────────────
AAA Adjusts after an addition operation. For example, to
add 9 and 3, use the following lines:
mov ax,9 ; Load 9
mov bx,3 ; and 3 as unpacked BCD
add al,bl ; Add 09h and 03h to get 0Ch
aaa ; Adjust 0Ch in AL to 02h,
; increment AH to 01h, set carry
; Result 12 unpacked BCD in AX
AAS Adjusts after a subtraction operation. For example, to
subtract 4 from 13, use the following lines:
mov ax,103h ; Load 13
mov bx,4 ; and 4 as unpacked BCD
sub al,bl ; Subtract 4 from 3 to get FFh (-1)
aas ; Adjust 0FFh in AL to 9,
; decrement AH to 0, set carry
; Result 9 unpacked BCD in AX
AAM Adjusts after a multiplication operation. Always use
MUL, not IMUL. For example, to multiply 9 times 3, use
the following lines:
mov ax,903h ; Load 9 and 3 as unpacked BCD
mul ah ; Multiply 9 and 3 to get 1Bh
aam ; Adjust 1Bh in AL
; to get 27 unpacked BCD in AX
AAD Adjusts before a division operation. Unlike other BCD
instructions, this one converts a BCD value to a
binary value before the operation. After the
operation, the quotient must still be adjusted by
using AAM. For example, to divide 25 by 2, use the
following lines:
mov ax,205h ; Load 25
mov bl,2 ; and 2 as unpacked BCD
aad ; Adjust 0205h in AX
; to get 19h in AX
div bl ; Divide by 2 to get
; quotient 0Ch in AL
; remainder 1 in AH
aam ; Adjust 0Ch in AL
; to 12 unpacked BCD in AX
; (remainder destroyed)
Notice that the remainder is lost. If you need the remainder, save it in
another register before adjusting the quotient. Then move it back to AL
and adjust if necessary.
Multidigit BCD numbers are usually processed in loops. Each digit is
processed and adjusted in turn. In addition to their use for processing
unpacked BCD numbers, the ASCII-adjust instructions can be used in
routines that convert between different number bases.
Example
mov al,79 ; Load 79 (04Fh)
aam ; Adjust to BCD (0709h)
add ah,'0' ; Adjust to ASCII characters
add al,'0' ; (3739h)
mov dx,ax ; Copy to DX
xchg dl,dh ; Trade for most significant digit
mov ah,2 ; DOS display character function
int 21h ; Call DOS
mov dl,dh ; Load least significant digit
int 21h ; Call DOS
The example converts an eight-bit binary number to hexadecimal and
displays it on the screen. The routine could be enhanced to handle large
numbers.
14.5.2 Packed BCD Numbers
Packed BCD numbers are made up of bytes containing two decimal digits: one
in the upper four bits and one in the lower four bits. The 8086-family
processors provide instructions for adjusting packed BCD numbers after
addition and subtraction. You must write your own routines to adjust for
multiplication and division.
To do arithmetic on packed BCD numbers, you must do the eight-bit
arithmetic calculations on each byte separately. The result should always
be in the AL register. After each operation, use the corresponding BCD
instruction to adjust the result. The decimal-adjust instructions do not
take an operand. They always work on the value in the AL register.
Unlike the ASCII-adjust instructions, the decimal-adjust instructions
never affect AH. The auxiliary carry flag is set if the digit in the lower
four bits carries to or borrows from the digit in the upper four bits. The
carry flag is set if the digit in the upper four bits needs to carry to or
borrow from another byte.
The decimal-adjust instructions are described below:
Instruction Description
──────────────────────────────────────────────────────────────────────────
DAA Adjusts after an addition operation. For example, to
add 88 and 33, use the following lines:
mov ax,8833h ; Load 88 and 33 as packed BCD
add al,ah ; Add 88 and 33 to get 0BBh
daa ; Adjust 0BBh to 121 packed BCD:
; 1 in carry and 21 in AL
DAS Adjusts after a subtraction operation. For example, to
subtract 38 from 83, put 83 in AL and 38 in AH in
packed BCD format. Then use the following lines to
subtract them:
mov ax,3883h ; Load 83 and 38 as packed BCD
sub al,ah ; Subtract 38 from 83 to get 04Bh
das ; Adjust 04Bh to 45 packed BCD:
; 0 in carry and 45 in AL
Multidigit BCD numbers are usually processed in loops. Each byte is
processed and adjusted in turn.
14.6 Doing Logical Bit Manipulations
The logical instructions do Boolean operations on individual bits. The
AND, OR, XOR, and NOT operations are supported by the 8086-family
instructions.
AND compares two bits and sets the result if both bits are set. OR
compares two bits and sets the result if either bit is set. XOR compares
two bits and sets the result if the bits are different. NOT reverses a
single bit. Table 14.1 shows a truth table for the logical operations.
Table 14.1 Values Returned by Logical Operations
X Y NOT X X AND Y X OR Y X XOR Y
──────────────────────────────────────────────────────────────────────────
1 1 0 1 1 0
1 0 0 0 1 1
0 1 1 0 1 1
0 0 1 0 0 0
──────────────────────────────────────────────────────────────────────────
The syntax of the AND, OR, and XOR instructions is the same. The only
difference is the operation performed. For all instructions, the target
value to be changed by the operation is placed in one operand. A mask
showing the positions of bits to be changed is placed in the other
operand. The format of the mask differs for each logical instruction. The
destination operand can be register or memory. The source operand can be
register, memory, or immediate. However, the source and destination
operands cannot both be memory operands.
Either of the values can be in either operand. However, the source operand
will be unchanged by the operation, while the destination operand will be
destroyed by it. Your choice of operands depends on whether you want to
save a copy of the mask or of the target value.
──────────────────────────────────────────────────────────────────────────
NOTE The logical instructions should not be confused with the logical
operators. They specify completely different behavior. The instructions
control run-time bit calculations. The operators control assembly-time bit
calculations. Although the instructions and operators have the same name,
the assembler can distinguish them from context.
──────────────────────────────────────────────────────────────────────────
14.6.1 AND Operations
The AND instruction does an AND operation on the bits of the source and
destination operands. The original destination operand is replaced by the
resulting bits.
Syntax
AND {register | memory},{register | memory | immediate}
The AND instruction can be used to clear the value of specific bits
regardless of their current settings. To do this, put the target value in
one operand and a mask of the bits you want to clear in the other. The
bits of the mask should be 0 for any bit positions you want to clear and 1
for any bit positions you want to remain unchanged.
Example 1
mov ax,035h ; Load value 00110101
and ax,0FBh ; Mask off bit 2 AND 11111011
; --------
; Value is now 31h 00110001
and ax,0F8h ; Mask off bits 2,1,0 AND 11111000
; --------
; Value is now 30h 00110000
Example 2
mov ah,7 ; Get character without echo
int 21h
and al,11011111b ; Convert to uppercase by clearing bit 5
cmp al,'Y' ; Is it Y?
je yes ; If so, do Yes stuff
. ; else do No stuff
.
yes: .
Example 2 illustrates how to use the AND instruction to convert a
character to uppercase. If the character is already uppercase, the AND
instruction has no effect, since bit 5 is always clear in uppercase
letters. If the character is lowercase, clearing bit 5 converts it to
uppercase.
14.6.2 OR Operations
The OR instruction does an OR operation on the bits of the source and
destination operands. The original destination operand is replaced by the
resulting bits.
Syntax
OR {register | memory},{register | memory | immediate}
The OR instruction can be used to set the value of specific bits
regardless of their current settings. To do this, put the target value in
one operand and a mask of the bits you want to clear in the other. The
bits of the mask should be 1 for any bit positions you want to set and 0
for any bit positions you want to remain unchanged.
Example
mov ax,035h ; Move value to register 00110101
or ax,08h ; Mask on bit 3 OR 00001000
; --------
; Value is now 3Dh 00111101
or ax,07h ; Mask on bits 2,1,0 OR 00000111
; --------
; Value is now 3Fh 00111111
Another common use for OR is to compare an operand to 0:
or bx,bx ; Compare to 0
; 2 bytes, 2 clocks on 8088
jg positive ; BX is positive
jl negative ; BX is negative
; BX is zero
The first statement has the same effect as the following statement, but is
faster and smaller:
cmp bx,0 ; 3 bytes, 3 clocks on 8088
14.6.3 XOR Operations
The XOR (Exclusive OR) instruction does an XOR operation on the bits of
the source and destination operands. The original destination operand is
replaced by the resulting bits.
Syntax
XOR {register | memory},{register | memory | immediate}
The XOR instruction can be used to toggle the value of specific bits
(reverse them from their current settings). To do this, put the target
value in one operand and a mask of the bits you want to toggle in the
other. The bits of the mask should be 1 for any bit positions you want to
toggle and 0 for any bit positions you want to remain unchanged.
Example
mov ax,035h ; Move value to register 00110101
xor ax,08h ; Mask on bit 3 XOR 00001000
; --------
; Value is now 3Dh 00111101
xor ax,07h ; Mask on bits 2,1,0 XOR 00000111
; --------
; Value is now 3Ah 00111010
Another common use for the XOR instruction is to set a register to 0:
xor cx,cx ; 2 bytes, 3 clocks on 8088
This sets the CX register to 0. When the XOR instruction takes identical
operands, each bit cancels itself, producing 0. The statement
mov cx,0 ; 3 bytes, 4 clocks on 8088
is the obvious way of doing this, but it is larger and slower. The
statement
sub cx,cx ; 2 bytes, 3 clocks on 8088
is also smaller than the MOV version. The only advantage of using MOV is
that it does not affect any flags.
14.6.4 NOT Operations
The NOT instruction does a NOT operation on the bits of a single operand.
It is used to toggle the value of all bits at once.
Syntax
NOT {register | memory}
The NOT instruction is often used to reverse the sense of a bit mask from
masking certain bits on to masking them off. Use the NOT instruction if
the value of the mask is not known until run time; use the NOT operator
(see Section 9.2.1.5, "Bitwise Logical Operators") if the mask is a
constant.
Example
.DATA
masker DB 00010000b ; Value may change at run time
.CODE
.
.
.
mov ax,0D743h ; Load 0D7h to AH, 43h to AL 01000011
or al,masker ; Turn on bit 4 in AL OR 00010000
; --------
; Result is 53h 01010011
not masker ; Reverse sense of mask 11101111
and ah,masker ; Turn off bit 4 in AH AND 11010111
; --------
; Result is 0C7h 11000111
14.7 Shifting and Rotating Bits
The 8086-family processors provide a complete set of instructions for
shifting and rotating bits. Bits can be moved right (toward the
most-significant bits) or left (toward the 0 bit). Values shifted off the
end of the operand go into the carry flag.
Shift instructions move bits a specified number of places to the right or
left. The last bit in the direction of the shift goes into the carry flag,
and the first bit is filled with 0 or with the previous value of the first
bit.
Rotate instructions move bits a specified number of places to the right or
left. For each bit rotated, the last bit in the direction of the rotate
operation is moved into the first bit position at the other end of the
operand. With some variations, the carry bit is used as an additional bit
of the operand. Figure 14.1 illustrates the eight variations of shift and
rotate instructions for eight-bit operands. Notice that SHL and SAL are
identical.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 14.7 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Syntax
SHL {register | memory},{CL | 1} SHR {register | memory},{CL | 1} SAL
{register | memory},{CL | 1} SAR {register | memory},{CL | 1} ROL
{register | memory},{CL | 1} ROR {register | memory},{CL | 1} RCL
{register | memory},{CL | 1} RCR {register | memory},{CL | 1}
The format of all the shift instructions is the same. The destination
operand should contain the value to be shifted. It will contain the
shifted operand after the instruction. The source operand should contain
the number of bits to shift or rotate. It can be the immediate value 1 or
the CL register. No other value or register is accepted on the 8088 and
8086 processors.
80186/286/386 Only
Starting with the 80186 processor, eight-bit immediate values larger than
1 can be given as the source operand for shift or rotate instructions, as
shown below:
shr bx,4 ; 9 clocks, 3 bytes on 80286
The following statements are equivalent if the program must run the 8088
or 8086:
mov cl,4 ; 2 clocks, 3 bytes on 80286
shr bx,cl ; 9 clocks, 2 bytes on 80286
; 11 clocks, 5 bytes
14.7.1 Multiplying and Dividing by Constants
Shifting right by one has the effect of dividing by two; shifting left by
one has the effect of multiplying by two. You can take advantage of this
to do fast multiplication and division by common constants. The easiest
constants are the powers of two. Shifting left twice multiplies by four,
shifting left three times multiplies by eight, and so on.
SHR is used to divide unsigned numbers. SAR can be used to divide signed
numbers, but SAR rounds negative numbers down──IDIV always rounds up. Code
that divides by using SAR must adjust for this difference. Multiplication
by shifting is the same for signed and unsigned numbers, so either SAL or
SHL can be used. Both instructions do the same operation.
Since the multiply and divide instructions are the slowest on the 8088 and
8086 processors, using shifts instead can often speed operations by a
factor of 10 or more. For example, on the 8088 or 8086 processor, the
following statements take four clocks:
xor ah,ah ; Clear AH
shl ax,1 ; Multiply byte in AL by 2
The following statements have the same effect, but take between 74 and 81
clocks on the 8088 or 8086:
mov bl,2 ; Multiply byte in AL by 2
mul bl
The same statements take 15 clocks on the 80286. See the on-line Help
system for complete information on timing of instructions.
Shift instructions can be combined with add or subtract instructions to do
multiplication by common constants. These operations are best put in
macros so that they can be changed if the constants in a program change.
Example 1
mul_10 MACRO factor ; Factor must be unsigned
mov ax,factor ; Load into AX
shl ax,1 ; AX = factor * 2
mov bx,ax ; Save copy in BX
shl ax,1 ; AX = factor * 4
shl ax,1 ; AX = factor * 8
add ax,bx ; AX = (factor * 8) + (factor * 2)
ENDM ; AX = factor * 10
Example 2
div_u512 MACRO dividend ; Dividend must be unsigned
mov ax,dividend ; Load into AX
shr ax,1 ; AX = dividend / 2 (unsigned)
xchg al,ah ; xchg is like rotate right 8
; AL = (dividend / 2) / 256
cbw ; Clear upper byte
ENDM ; AX = (dividend / 512
14.7.2 Moving Bits to the Least-Significant Position
Sometimes a group of bits within an operand needs to be treated as a
single unit──for example, to do an arithmetic operation on those bits
without affecting other bits. This can be done by masking off the bits and
then shifting them into the least-significant positions. After the
arithmetic operation is done, the bits are shifted back to the original
position and merged with the original bits by using OR. See Section
7.2.5, "Using Record-Field Operands," for an example of this operation.
14.7.3 Adjusting Masks
Masks for logical instructions can be shifted to new bit positions. For
example, an operand that masks off a bit or group of bits can be shifted
to move the mask to a different position.
Example
.DATA
masker DB 00000010b ; Mask that may change at run time
.CODE
.
.
.
mov cl,2 ; Rotate two at a time
mov bl,57h ; Load value to be changed 01010111b
rol masker,cl ; Rotate two to left 00001000b
or bl,masker ; Turn on masked values ---------
; New value is 05Fh 01011111b
rol masker,cl ; Rotate two more 00100000b
or bl,masker ; Turn on masked values ---------
; New value is 07Fh 01111111b
This technique is useful only if the mask value is unknown until run time.
14.7.4 Shifting Multiword Values
Sometimes it is necessary to shift a value that is too large to fit in a
register. In this case, you can shift each part separately, passing the
shifted bits through the carry flag. The RCR or RCL instructions must be
used to move the carry value from the first register to the second.
RCR and RCL can also be used to initialize the high or low bit of an
operand. Since the carry flag is treated as part of the operand (like
using a nine-bit operand), the flag value before the operation is crucial.
The carry flag may be set by a previous instruction, or you can set it
directly using the CLC (Clear Carry Flag), CMC (Complement Carry Flag),
and STC (Set Carry Flag) instructions.
Example
.DATA
mem32 DD 500000
.CODE
.
. ; Divide 32-bit unsigned by 16
.
mov cx,4 ; Shift right 4 500000
again: shr WORD PTR mem32[2],1 ; Shift into carry DIV 16
rcr WORD PTR mem32[0],1 ; Rotate carry in ------
loop again ; 31250
────────────────────────────────────────────────────────────────────────────
Chapter 15: Controlling Program Flow
The 8086-family processors provide a variety of instructions for
controlling the flow of a program. The four major types of program-flow
instructions are jumps, loops, procedure calls, and interrupts.
This chapter tells you how to use these instructions and how to test
conditions for the instructions that change program flow conditionally.
15.1 Jumping
Jumps are the most direct method of changing program control from one
location to another. At the internal level, jumps work by changing the
value of the IP (Instruction Pointer) register from the address of the
current instruction to a target address.
Jumps can be short, near, or far. QuickAssembler automatically handles
near and short jumps, although it may not always generate the most
efficient code if the label being jumped to is a forward reference. The
size and control of jumps are discussed in Section 9.4.1, "Forward
References to Labels."
15.1.1 Jumping Unconditionally
The JMP instruction is used to jump unconditionally to a specified
address.
Syntax
JMP {register | memory}
The operand should contain the address to be jumped to. Unlike conditional
jumps, whose target address must be short (within 128 bytes), the target
address for unconditional jumps can be short, near, or far. See Section
9.4.1 for more information on specifying the distance for conditional
jumps.
If a conditional jump must be greater than 128 bytes, the construction
must be reorganized. This can be done by reversing the sense of the
conditional jump and adding an unconditional jump, as shown in Example 1.
Example 1
cmp ax,7 ; If AX is 7 and jump is short
je close ; then jump close
cmp ax,6 ; If AX is 6 and jump is near
jne close ; then test opposite and skip over
jmp distant ; Now jump
.
.
.
close: ; Less than 128 bytes from jump
.
.
.
distant: ; More than 128 bytes from jump
An unconditional jump can be used as a form of conditional jump by
specifying the address in a register or indirect memory operand. The value
of the operand can be calculated at run time, based on user interaction or
other factors. You can use indirect memory operands to construct jump
tables that work like C switch statements, BASIC ON GOTO statements, or
Pascal case statements.
Example 2
.CODE
.
.
.
jmp process ; Jump over data
ctl_tbl LABEL WORD ; (required in overlay procedures)
DW extended ; Null key (extended code)
DW ctrla ; Address of CONTROL-A key routine
DW ctrlb ; Address of CONTROL-B key routine
process: mov ah,8h ; Get a key
int 21h
cbw ; Convert AL to AX
mov bx,ax ; Copy
shl bx,1 ; Convert to address
jmp ctl_tbl[bx] ; Jump to key routine
extended: mov ah,8h ; Get second key of extended
int 21h
. ; Use another jump table
. ; for extended keys
.
ctrla: . ; CONTROL-A routine here
.
.
jmp next
ctrlb: . ; CONTROL-B routine here
.
.
jmp next
.
.
next: . ; Continue
In Example 2, an indirect memory operand points to addresses of routines
for handling different keystrokes. Notice that the jump table is placed in
the code segment. This technique is optional in stand-alone assembler
programs, but it may be required for procedures called from some
languages.
15.1.2 Jumping Conditionally
The most common way of transferring control in assembly language is with
conditional jumps. This is a two-step process: first test the condition,
and then jump if the condition is true or continue if it is false.
Syntax
Jcondition label
Conditional-jump instructions take a single operand containing the address
to be jumped to. The distance from the jump instruction to the specified
address must be short (less than 128 bytes). If a longer distance is
specified, an error will be generated telling the distance of the jump in
bytes. See Section 15.1.1, "Jumping Unconditionally," for information on
arranging longer conditional jumps.
Conditional-jump instructions (except JCXZ) use the status of one or more
flags as their condition. Thus, any statement that sets a flag under
specified conditions can be the test statement. The most common test
statements use the CMP or TEST instructions. The jump statement can be any
one of 31 conditional-jump instructions.
Because conditional jumps cannot refer to labels more than 128 bytes away,
they are often used in combination with unconditional jumps, which have no
such limitation. For example, the following statement is valid as long as
target is not far away:
jz target ; If previous operation resulted in
; zero, jump to target
Once target becomes too distant, the following sequence must be used to
enable a longer jump. Note that this sequence is logically equivalent to
the example above:
jnz skip ; If previous operation resulted in NOT zero
; jump to "skip"
jmp target ; Otherwise, jump to target
skip:
The instructions above first test for the logical inverse of the desired
condition. If the test condition (in this case, equality to zero) is not
true, the jump to target is avoided. Yet if a zero condition is true, the
program falls through to the instruction jmp target, which can jump any
distance. The effect, of course, is to jump to target if the previous
operation resulted in zero.
The problem with this technique is that if used often, you may have to
think up a label name just to jump around one instruction. Anonymous
labels, described in Section 6.4.2, let you avoid having to invent so
many label names. For example, you could use an anonymous label to rewrite
the example above:
jnz @F ; If previous operation resulted in NOT zero,
; jump forward to next @ label
jmp target ; Otherwise, jump to target
@:
15.1.2.1 Comparing and Jumping
The CMP instruction is specifically designed to test for conditional
jumps. It does not change the destination operand, so it can be used to
compare two values without changing either of them. Instructions that
change operands (such as SUB or AND) can also be used to test conditions.
The CMP instruction compares two operands and sets flags based on the
result. It is used to test the following relationships: equal; not equal;
greater than; less than; greater than or equal; or less than or equal.
Syntax
CMP {register | memory},{register | memory | immediate}
The destination operand can be memory or register. The source operand can
be immediate, memory, or register. However, they cannot both be memory
operands.
The jump instructions that can be used with CMP are made up of mnemonic
letters combined to indicate the type of jump. The letters are shown
below:
Letter Meaning
──────────────────────────────────────────────────────────────────────────
J Jump
G Greater than (for unsigned comparisons)
L Less than (for unsigned comparisons)
A Above (for signed comparisons)
B Below (for signed comparisons)
E Equal
N Not
The mnemonic names always refer to the relationship that the first operand
of the CMP instruction has to the second operand of the CMP instruction.
For instance, JG tests whether the first operand is greater than the
second. Several conditional instructions have two names. You can use
whichever name seems more mnemonic in context.
Comparisons and conditional jumps can be thought of as statements in the
following format:
IF (value1 relationship value2) THEN GOTO truelabel:
Statements of this type can be coded in assembly language by using the
following syntax:
CMP value1,value2
Jrelationship truelabel
.
.
.
truelabel:
Table 15.1 lists conditional-jump instructions for each relationship and
shows the flags that are tested in order to see if relationship is true.
Table 15.1 Conditional-Jump Instructions Used after Compare
Jump Condition Signed Jump if: Unsigned Jump if:
Compare Compare
──────────────────────────────────────────────────────────────────────────
= Equal JE ZF = 1 JE ZF = 1
╪ Not equal JNE ZF = 1 JNE ZF = 1
> Greater than JG or JNLE ZF = 0 and JA or JNBE CF = 0 and ZF = 0
SF = OF
<= Less than or JLE or JNG ZF = 1 and JBE or JNA CF = 1 or ZF = 1
equal SF ╪ OF
< Less than JL or JNGE SF ╪ OF JB or JNAE CF = 1
>= Greater than JGE or JNL SF = OF JAE or JNB CF = 0
or equal
──────────────────────────────────────────────────────────────────────────
Internally, the CMP instruction is exactly the same as the SUB
instruction, except that the destination operand is not changed. The flags
are set according to the result that would have been generated by a
subtraction.
Example 1
; If CX is less than -20, then make DX 30, else make DX 20
cmp cx,-20 ; If signed CX is smaller than -20
jl less ; then do stuff at "less"
mov dx,20 ; Else set DX to 20
jmp skip ; Finished
less: mov dx,30 ; Then set DX to 30
skip:
Example 1 shows the basic form of conditional jumps. Notice that in
assembly language, if-then-else constructions are usually written in the
form if-else-then.
This theme has many variations. For example, you may find it more mnemonic
to code in the if-then-else format. However, you must then use the
opposite jump condition, as shown in Example 2.
Example 2
; If CX is greater than or equal to -20, then make DX 20, else make DX 30
cmp cx,-20 ; If signed CX is smaller than -20
jnl notless ; else do stuff at "notless"
mov dx,30 ; Then set DX to 30
jmp continue ; Finished
notless: mov dx,20 ; Else set DX to 20
continue:
The then-if-else format shown in Example 3 is often more efficient. Do the
work for the most likely case, and then compare for the opposite
condition. If the condition is true, you are finished.
Example 3
; DX is 20, unless CX is less than -20, then make DX 30
mov dx,20 ; DX is 20
cmp cx,-20 ; If signed CX is greater than -20
jge greatequ ; then done
mov dx,30 ; Else set DX to 30
greatequ:
This example avoids the unconditional jump used in Examples 1 and 2 and
thus is faster even if the less likely condition is true.
15.1.2.2 Jumping Based on Flag Status
The CMP instruction is the most mnemonic way to set the flags for
conditional jumps, but any instruction that changes flags can be used as
the test condition. The conditional-jump instructions listed below enable
you to jump based on the condition of flags rather than on relationships
of operands. Some of these instructions have the same effect as
instructions listed in Table 15.1.
Instruction Action
──────────────────────────────────────────────────────────────────────────
JO Jumps if the overflow flag is set
JNO Jumps if the overflow flag is clear
JC Jumps if the carry flag is set (same as JB)
JNC Jumps if the carry flag is clear (same as JAE)
JZ Jumps if the zero flag is set (same as JE)
JNZ Jumps if the zero flag is clear (same as JNE)
JS Jumps if the sign flag is set
JNS Jumps if the sign flag is clear
JP Jumps if the parity flag is set
JNP Jumps if the parity flag is clear
JPE Jumps if parity is even (parity flag set)
JPO Jumps if parity is odd (parity flag clear)
JCXZ Jumps if CX is 0
Notice that JCXZ is the only conditional jump based on the condition of a
register (CX) rather than flags. Since JCXZ is usually used with loop
instructions, it is discussed in more detail in Section 15.2, "Looping."
Example 1
add ax,bx ; Add two values
jo overflow ; If value too large, adjust
.
.
.
overflow: ; Adjustment routine here
Example 2
sub ax,dx ; Subtract
jnz skip ; If the result is not zero, continue
call zhandler ; else do special case
skip:
15.1.2.3 Testing Bits and Jumping
Like the CMP instruction, the TEST instruction is designed to test for
conditional jumps. However, specific bits are compared rather than entire
operands.
Syntax
TEST {register | memory},{register | memory | immediate}
The destination operand can be memory or register. The source operand can
be immediate, memory, or register. However, they cannot both be memory
operands.
Normally, one of the operands is a mask in which the bits to be tested are
the only bits set. The other operand contains the value to be tested. If
all the bits set in the mask are clear in the operand being tested, the
zero flag will be set. If any of the flags set in the mask are also set in
the operand, the zero flag will be cleared.
The TEST instruction is actually the same as the AND instruction, except
that neither operand is changed. If the result of the operation is 0, the
zero flag is set, but the 0 is not actually written to the destination
operand.
You can use the JZ and JNZ instructions to jump after the test. JE and JNE
are the same and can be used if you find them more mnemonic.
Example
.DATA
bits DB ?
.CODE
.
.
.
; If bit 2 or bit 4 is set, then call taska
; Assume "bits" is 0D3h 11010011
test bits,10100b ; If 2 or 4 is set AND 00010100
jz skip1 ; Else continue --------
call taska ; Then call taska 00010000
skip1: ; Jump not taken
.
.
.
; If bits 2 and 4 are clear, then call taskb
; Assume "bits" is 0E9h 11101001
test bits,10100b ; If 2 and 4 are clear AND 00010100
jnz skip2 ; Else continue --------
call taskb ; Then call taskb 00000000
skip2: ; Jump not taken
15.2 Looping
The 8086-family processors have several instructions specifically designed
for creating loops of repeated instructions. In addition, you can create
loops using conditional jumps.
Syntax
LOOP label
LOOPE label
LOOPZ label
LOOPNE label
LOOPNZ label
JCXZ label
The LOOP instruction is used for loops with a set number of iterations.
For example, it can be used in constructions similar to the "for" loops of
BASIC, C, and Pascal, and the "do" loops of FORTRAN.
A single operand specifies the address to jump to each time through the
loop. The CX register is used as a counter for the number of times to
loop. On each iteration, CX is decremented. When CX reaches 0, control
passes to the instruction after the loop.
The LOOPE, LOOPZ, LOOPNE, and LOOPNZ instructions are used in loops that
check for a condition. For example, they can be used in constructions
similar to the "while" loops of BASIC, C, and Pascal; the "repeat" loops
of Pascal; and the "do" loops of C.
The LOOPE (also called LOOPZ) instruction can be thought of as meaning
"loop while equal." Similarly, the LOOPNE (also called LOOPNZ) instruction
can be thought of as meaning "loop while not equal." A single short memory
operand specifies the address to loop to each time through. The CX
register can specify a maximum number of times to go through the loop. The
CX register can be set to a number that is out of range if you do not want
a maximum count.
The JCXZ instruction is often used in loop structures. For example, it may
be used in loops that check a condition at the start of the loop rather
than at the end. Unlike the loop instruction, JCXZ does not decrement CX,
so the programmer must use another statement to decrement the count. You
can also use JCX2 with string instructions, as described in Chapter 16,
"Processing Strings."
Example 1
; For 0 to 200 do task
mov cx,200 ; Set counter
next: . ; Do the task here
.
.
loop next ; Do again
; Continue after loop
This loop has the same effect as the following statements:
; For 0 to 200, do task
mov cx,200 ; Set counter
next: .
. ; Do the task here
.
dec cx
cmp cx,0
jne next ; Do again
; Continue after loop
The first version is more efficient as well as easier to understand.
However, there are situations in which you must use conditional-jump
instructions rather than loop instructions. For example, conditional jumps
are often required for loops that test several conditions.
If the counter in CX is variable because of previous instructions, you
should use the JCXZ instruction to check for 0, as shown in Example 2.
Otherwise, if CX is 0, it will be decremented to -1 in the first iteration
and will continue through 65,535 iterations before it reaches 0 again.
Example 2
; For 0 to CX do task
; CX counter set previously
jcxz done ; Check for 0
next: . ; Do the task here
.
.
loop next ; Do again
done: ; Continue after loop
15.3 Using Procedures
A "procedure" is a program subdivision that typically executes a specific
task. Once you write a procedure, you can execute it from anywhere in the
program. This technique lets you avoid writing the same block of code over
and over, thus saving space.
Even if you execute it only once, writing a procedure can be a useful way
of dividing a large program into manageable units. You can place a
procedure in its own source module and test it separately.
Assembly-language procedures are comparable to functions in C;
subprograms, functions, and subroutines in BASIC; procedures and functions
in Pascal; or routines and functions in FORTRAN.
Two instructions control the use of assembly-language procedures. The CALL
instruction can appear anywhere in a program. It temporarily transfers
program control to a specified procedure. The RET instruction appears at
the end of a procedure. It returns control back to the location that
issued the call.
These instructions use the stack to properly return from each call. The
instruction immediately following the CALL instruction is called the
"return address," and the procedure should return to this location when
done. CALL pushes the return address onto the stack; RET pops this address
off the stack and transfers program control there.
Along with the RET instruction (which terminates a procedure), two
directives help define a procedure. The PROC and ENDP directives normally
mark the beginning and end of a procedure definition, as described in
Section 15.3.2, "Defining Procedures."
In addition, the PROC directive can save you time and effort by automating
the following tasks:
■ Preserving register values that should not change, but that the
procedure might otherwise alter
■ Setting up a framepointer, so that you can access parameters placed on
the stack
■ Creating text macros, so that your source code can refer to each
parameter by a meaningful name
Section 15.3.4, "Declaring Parameters with the PROC Directive," describes
how to use these features. Section 15.3.3, "Passing Arguments on the
Stack," gives background information on the technique for accessing
parameters.
When you write procedures, you can create local variables, which exist
only during execution of the procedure. The advantage of these variables
is that they use memory dynamically, taking up space only in the procedure
that uses them. Section 15.3.5, "Using Local Variables," describes the
basic technique for allocating and accessing local variables. Section
15.3.6, "Creating Locals Automatically," describes how to make the
assembler generate the necessary code for you.
15.3.1 Calling Procedures
The CALL instruction saves the address following the instruction on the
stack and passes control to a specified address.
Syntax
CALL {register | memory}
The address is usually specified as a direct memory operand. However, the
operand can also be a register or indirect memory operand containing a
value calculated at run time. This enables you to write call tables
similar to the jump table illustrated in Section 15.1.2.1, "Comparing and
Jumping."
Calls can be near or far. Near calls push only the offset portion of the
calling address. Far calls push both the segment and offset. You must give
the type of far calls to forward-referenced labels using the FAR type
specifier and the PTR operator. For example, use the following statement
to make a far call to a label that has not been earlier defined or
declared external in the source code:
call FAR PTR task
15.3.2 Defining Procedures
Procedures are defined by labeling the start of the procedure and placing
an ENDP directive at the end. The code should not fall through past the
end of the procedure. Exit the procedure with a RET, RETF, RETN, or IRET
instruction. There are several variations of this syntax.
Syntax 1
label PROC [[NEAR|FAR]] RET [[constant]] label ENDP
Procedures are normally defined by using the PROC directive at the start
of the procedure and the ENDP directive at the end. The RET instruction is
normally placed immediately before the ENDP directive. The size of the RET
instruction automatically matches the size defined by the PROC directive.
The syntax shown is always available. In addition, there is an extended
PROC syntax available if you use .MODEL and specify a language. The
extended PROC syntax is explained in Section 15.3.4, "Declaring
Parameters with the PROC Directive." These language features automate many
of the details of accessing parameters and saving registers.
Syntax 2
label:
statements
RETN [[constant]]
Syntax 3
label LABEL FAR
statements
RETF [[constant]]
The RET instruction can be extended to RETN (Return Near) or RETF (Return
Far) to override the default size. This enables you to define and use
procedures without the PROC and ENDP directives, as shown in Syntax 2 and
Syntax 3, above. However, with this method, the programmer is responsible
for making sure the size of the CALL matches the size of the RET.
The RET instruction (and its RETF and RETN variations) allows a constant
operand that specifies a number of bytes to be added to the value of the
SP register after the return. This operand can be used to adjust for
arguments passed to the procedure before the call, as shown in the example
in Section 15.3.5, "Using Local Variables."
Example 1
call task ; Call is near because procedure is near
. ; Return comes to here
.
.
task PROC NEAR ; Define "task" to be near
.
. ; Instructions of "task" go here
.
ret ; Return to instruction after call
task ENDP ; End "task" definition
Example 1 shows the recommended way of making calls with QuickAssembler.
Example 2 shows another method that programmers who are used to other
assemblers may find more familiar.
Example 2
call NEAR PTR task ; Call is declared near
. ; Return comes to here
.
.
task: ; Procedure begins with near label
.
. ; Instructions go here
.
retn ; Return declared near
This method gives more direct control over procedures, but the programmer
must make sure that calls have the same size as corresponding returns.
For example, if a call is made with the statement
call NEAR PTR task
the assembler does a near call. This means that one word (the offset
following the calling address) is pushed onto the stack. If the return is
made with the statement
retf
two words are popped off the stack. The first will be the offset, but the
second will be whatever happened to be on the stack before the call. Not
only will the popped value be meaningless, but the stack status will be
incorrect, causing the program to fail.
15.3.3 Passing Arguments on the Stack
Procedure arguments can be passed in various ways. For example, values can
be passed to a procedure in registers or in variables. However, the most
common method of passing arguments is to use the stack. Microsoft
languages have a specific convention for doing this.
This section describes how a procedure accesses the parameters passed to
it on the stack. Each parameter is accessed as an offset from BP, and you
must calculate this offset. However, if you use the PROC directive to
declare parameters, the assembler calculates these offsets for you and
lets you refer to parameters by name. The next section explains how to use
PROC this way.
The arguments are pushed onto the stack before the call. After the call,
the procedure retrieves and processes them. At the end of the procedure,
the stack is adjusted to account for the arguments.
Although the same basic method is used for all Microsoft high-level
languages, the details vary. For instance, in some languages, pointers to
the arguments are passed to the procedure; in others, the arguments
themselves are passed. The order in which arguments are passed (whether
the first argument is pushed first or last) also varies according to the
language. Finally, in some languages, the stack is adjusted by the RET
instruction in the called procedure; in others, the code immediately
following the CALL instruction adjusts the stack. See Appendix A,
"Mixed-Language Mechanics," for details on calling conventions.
Example
; C-style procedure call and definition
mov ax,10 ; Load and
push ax ; push constant as third argument
push arg2 ; Push memory as second argument
push cx ; Push register as first argument
call addup ; Call the procedure
add sp,6 ; Destroy the pushed arguments
. ; (equivalent to three pops)
.
.
addup PROC NEAR ; Return address for near call
; takes two bytes
push bp ; Save base pointer - takes two bytes
; so arguments start at 4th byte
mov bp,sp ; Load stack into base pointer
mov ax,[bp+4] ; Get first argument from
; 4th byte above pointer
add ax,[bp+6] ; Add second argument from
; 6th byte above pointer
add ax,[bp+8] ; Add third argument from
; 8th byte above pointer
pop bp ; Restore BP
ret ; Return result in AX
addup ENDP
The example shows one method of passing arguments to a procedure. This
method is similar to the way procedures are called in the C language.
Figure 15.1 shows the stack condition at key points in the process.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 15.3.3 of the manual │
└────────────────────────────────────────────────────────────────────────┘
──────────────────────────────────────────────────────────────────────────
NOTE Arguments passed on the stack in assembler routines cannot be
accessed by name in debugging commands, unless you declare parameters with
the PROC directive, as explained in the next section.
──────────────────────────────────────────────────────────────────────────
15.3.4 Declaring Parameters with the PROC Directive
This section describes how to use the PROC directive in order to automate
the parameter-accessing techniques described in the last section.
The PROC directive lets you specify registers to be saved, define
arguments to the procedure, and set up text macros so that you can refer
to parameters by name (rather than as an offset to BP). For example, the
following PROC directive could be placed at the beginning of a procedure
called from BASIC that takes a single argument passed by value and that
uses (and must save) the DI and SI registers:
myproc PROC FAR BASIC USES DI SI, arg1:WORD
Note that you must use the .MODEL directive and specify a language in
order to use the extended features of PROC, including the lang type,
reglist, and arguments.
Syntax
label PROC [[NEAR|FAR]] [[lang]] [[USES reglist]] [[arguments]]
The NEAR and FAR keywords indicate whether you invoke the procedure with a
near call or a far call, as described in Section 15.3.2, "Defining
Procedures."
The following list describes the other parts of the PROC directive:
Argument Description
──────────────────────────────────────────────────────────────────────────
label The name of the procedure. The assembler automatically
adds an underscore to the beginning of the name if you
specify C as the language in the .MODEL directive or
if you specify C as the lang.
lang An optional language specifier that overrides language
conventions specified by the .MODEL directive. The
language type may be C, Pascal, FORTRAN, or BASIC.
The language type determines the calling convention
used to access parameters and restore the stack. It
also determines whether an underscore is prefixed to
the procedure name, as required by the C naming
convention. Note that use of the C specifier does not
preserve lowercase letters in the procedure name. To
guarantee compatibility with C naming conventions,
choose Preserve Case or Preserve Extrn from the
Assembler Flags dialog box, or assemble with /Cl or
/Cx from the QCL command line.
reglist A list of registers that the procedure uses and that
should be saved on entry. Registers in the list must
be separated by blanks or tabs. The assembler
generates code to push these registers on the stack.
When you exit, the assembler generates code to pop the
saved register values off the stack.
arguments The list of arguments passed to the procedure on the
stack. See the discussion below for the syntax of the
argument.
The arguments indicate each of the procedure's arguments and are separated
from the reglist argument by a comma if there is a list of registers. Each
argument has the following syntax:
argname [[ :[[[[NEAR|FAR]]PTR]]type]]
If you have more than one argument, separate each by a comma.
The argname is the name of the argument. The type is the type of the
argument and may be WORD, DWORD, QWORD, TBYTE, or the name of a structure
defined by a STRUC structure declaration (see Chapter 6, "Defining
Labels, Constants, and Variables" for more information about types). If
you omit type, the default is the WORD type.
The FAR, NEAR, PTR, and type arguments are all optional. If you omit all
of them, the assembler assumes the variable is a WORD type. If you use
only the type argument, the assembler assumes the variable has the
indicated type.
──────────────────────────────────────────────────────────────────────────
Note If you are writing a routine to be called from BASIC, FORTRAN, or
Pascal, and the routine returns a function value, you must declare an
additional parameter if you return anything other than a two- or four-byte
integer. See Appendix A, "Mixed-Language Mechanics," for more
information.
──────────────────────────────────────────────────────────────────────────
The PTR type generates debugging information so that the variable is
treated as a pointer during debugging. The assembler assumes specific
sizes for the variable, depending on the combination of NEAR, FAR, and PTR
arguments you specify. The lines below show some example combinations of
NEAR, FAR, PTR, and type:
myproc PROC var1:PTR WORD, var2:PTR DWORD
.
.
.
myproc ENDP
proc2 PROC var3:FAR PTR WORD, var4:NEAR PTR BYTE
.
.
.
proc2 ENDP
If you omit NEAR or FAR, the default data size established by .MODEL is
used. All PTR declarations are translated into a word-size variable if the
data size is near or a doubleword variable if the data size is far.
For example, the following declarations of procvar produce the same code
for the variable name, although they generate different debugging
information:
aproc PROC procvar:PTR WORD
aproc PROC procvar:PTR DWORD
aproc PROC procvar:PTR BYTE
Specifying a particular type changes only the debugging information, not
the code produced for accessing the argument.
If you specify a NEAR PTR or FAR PTR argument, as in the declarations of
var3 and var4, the assembler ignores the memory model you selected and
assigns a WORD type for a NEAR PTR argument and a DWORD type for a FAR PTR
argument.
The assembler does not generate any code to get the value or values the
pointer references; your program must still explicitly treat the argument
as a pointer. For example, the procedure in Section 5.1 can be rewritten
for use with BASIC so that it gets its argument by near reference (the
BASIC default):
; Call from BASIC as a FUNCTION returning an integer
.MODEL medium, basic
.CODE
myadd PROC arg1:NEAR PTR WORD, arg2:NEAR PTR WORD
mov bx,arg1 ; Load first argument
mov ax,[bx]
mov bx,arg2 ; Add second argument
add ax,[bx]
ret
myadd ENDP
END
In the example above, even though the arguments are declared as near
pointers, you still must code two move instructions in order to get the
values of the arguments──the first move gets the address of the argument;
the second move gets the argument.
You can use conditional-assembly directives to make sure that your pointer
arguments are loaded correctly for the memory model. For example, the
following version of myadd treats the arguments as far arguments if
necessary:
.MODEL medium,c ;Could be any model
.CODE
myadd PROC arg1:PTR WORD, arf2:PTR WORD
IF @DataSize
les bx,arg1 ;Far arguments
mov ax,es:[bx]
les bx,arg2
add ax,es:[bx]
ELSE
mov bx,arg1 ;Near arguments
mov ax,[bx]
mov bx,arg2
add ax,[bx]
ENDIF
ret
myadd ENDP
END
──────────────────────────────────────────────────────────────────────────
Note When you use the high-level-language features and the assembler
encounters a RET instruction, it automatically generates instructions to
pop saved registers, remove local variables from the stack, and, if
necessary, remove arguments. The assembler does not generate this code if
you use a RETF or RETN instruction. It generates this code for each RET
instruction it encounters. You can save code by having only one exit and
jumping to it from various points.
──────────────────────────────────────────────────────────────────────────
15.3.5 Using Local Variables
In high-level languages, local variables are known only within a
procedure. In Microsoft languages, these variables are usually stored on
the stack. Assembly-language programs can use the same technique. These
variables should not be confused with labels or variable names that are
local to a module, as described in Chapter 8, "Creating Programs from
Multiple Modules."
──────────────────────────────────────────────────────────────────────────
NOTE If your procedure has relatively few variables, you can usually
write the most efficient code by placing these values in registers. Local
(stack) data is efficient when you have a large amount of local data for
the procedure.
──────────────────────────────────────────────────────────────────────────
This section outlines the standard methods for creating local variables.
The next section shows how to use the LOCAL directive to make the
assembler generate local variables for you automatically. When you use
this directive, the assembler generates the same instructions as those
used in this section, but hides some of the details from you.
If you want to use LOCAL right away, you may want to skip directly to the
next section. However, this section gives useful background.
Local variables are created by saving stack space for the variable at the
start of the procedure. The variable can then be accessed by its position
in the stack. At the end of the procedure, the stack pointer is restored
to restore the memory used by local variables.
Example
push ax ; Push one argument
call task ; Call
.
.
.
arg EQU <[bp+4]> ; Name for argument
loc EQU <[bp-2]> ; Name for local variable
task PROC NEAR
push bp ; Save base pointer
mov bp,sp ; Load stack into base pointer
sub sp,2 ; Save two bytes for local variable
.
.
.
mov loc,3 ; Initialize local variable
add ax,loc ; Add local variable to AX
sub arg,ax ; Subtract local from argument
. ; Use "loc" and "arg" in other operations
.
.
mov sp,bp ; Adjust for stack variable
pop bp ; Restore base
ret 2 ; Return result in AX and pop
task ENDP ; two bytes to adjust stack
In this example, two bytes are subtracted from the SP register to make
room for a local word variable. This variable can then be accessed as
[bp-2]. In the example, this value is given the name loc with a text
equate. Notice that the instruction mov sp,bp is given at the end to
restore the original value of SP. The statement is only required if the
value of SP is changed inside the procedure (usually by allocating local
variables). The argument passed to the procedure is returned with the
RET instruction. Contrast this to the example in Section 15.3.3,
"Passing Arguments on the Stack," in which the calling code adjusts for
the argument. Figure 15.2 shows the state of the stack at key points in
the process.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 15.3.5 of the manual │
└────────────────────────────────────────────────────────────────────────┘
──────────────────────────────────────────────────────────────────────────
NOTE Local variables created in assembler routines cannot be accessed by
name with debugging commands, unless you declare local variables with the
LOCAL directive, as explained in the next section.
──────────────────────────────────────────────────────────────────────────
15.3.6 Creating Locals Automatically
This section describes how to automate the techniques for local-variable
creation described in the last section.
You can use the LOCAL directive to save time and effort when working with
local variables. When you use this directive, simply list the variables
you want to create, giving a type for each one. The assembler calculates
how much space is required on the stack. It also generates instructions to
properly decrement SP (as described in the previous section) and to later
reset SP when you return from the procedure.
The LOCAL directive can only be used inside procedures created with the
extended PROC directive. This means that you must first use .MODEL and
specify a language.
When you create local variables this way, your source code can then refer
to each local variable by name rather than as an offset. Moreover, the
assembler generates debugging information for each local variable, so that
you can enter the name of the local variable as part of a Watch
expression.
The procedure in Section 15.3.5 can be generated more simply with the
following code:
task PROC NEAR arg:WORD
LOCAL loc:WORD
.
.
.
mov loc,3 ; Initialize local variable
add ax,loc ; Add local variable to AX
sub arg,ax ; Subtract local from argument
. ; Use "Loc" and "arg" in other operat
.
.
ret
task ENDP
The LOCAL directive has the following syntax:
LOCAL vardef [[,vardef]]...
Each vardef has the form:
label[[[count]]][[:[[[[NEAR | FAR]]PTR]]type]]]]...
The LOCAL directive arguments are as follows:
Argument Description
──────────────────────────────────────────────────────────────────────────
label The name given to the local variable. The assembler
automatically defines a text macro you may use to
access the variable.
count The number of elements of this name and type to
allocate on the stack. Using count allows you to
allocate a simple array on the stack. The brackets
around count are required. If this field is omitted,
one data object is assumed.
type The type of variable to allocate. The type argument
may be one of the following: WORD, DWORD, QWORD,
TBYTE, or the name of a structure defined by a STRUC
structure declaration.
The assembler sets aside space on the stack, following the same rules as
for procedure arguments.
The assembler does not initialize local variables. Your program must
include code to perform any necessary initializations. For example, the
following code fragment sets up a local array and initializes it to zero:
arraysz EQU 20
aproc PROC
LOCAL var1[arraysz]:WORD, var2:WORD
.
.
.
; Initialize local array to zero
mov cx,arraysz
xor ax,ax
xor di,di ; Use di as array index
repeat: mov var1[di],ax
inc di
inc di
loop repeat
; Use the array...
.
.
.
ret
aproc
15.3.7 Variable Scope
When you use the extended form of the .MODEL directive, the assembler
makes all identifiers inside a procedure local to the procedure. Labels
ending with a colon (:), procedure arguments, and local variables declared
in a LOCAL directive are undefined outside of the procedure. Variables
defined outside of any procedure are available inside a procedure. For
example, in the following fragment, var1 can be used in proc1 and proc2,
while var2──because it is defined in proc2──is not available to proc1:
.MODEL medium,c
.DATA
var1 DW 256 ; Available to proc1 and proc2
.CODE
proc1 PROC
.
.
.
exit: ret
proc1 ENDP
proc2 PROC
LOCAL var2:WORD ; This var2 only available in proc2
.
.
.
exit: ret
proc2 ENDP
If proc1 contained a LOCAL directive defining var2, that var2 would be a
completely different variable than the var2 in proc2.
Notice that both procedures contain the label exit. Because labels are
local when you use the language option on the .MODEL directive, you may
use the same labels in different procedures. You can make a label in a
procedure global (make it available outside the procedure) by ending it
with two colons:
proc3 PROC
.
.
.
label1::
.
.
.
proc3 ENDP
In the preceding example, label1 is available throughout the file
containing proc3.
15.3.8 Setting Up Stack Frames
80186/286/386 Only
Starting with the 80186 processor, the ENTER and LEAVE instructions are
provided for setting up a stack frame. These instructions do the same
thing as the multiple instructions at the start and end of procedures in
the Microsoft calling conventions (see the examples in Section 15.3.3,
"Passing Arguments on the Stack").
The PROC statement takes advantage of these instructions if you enable the
extended instruction set with the .186 or .286 directive.
Syntax
ENTER framesize, nestinglevel
statements
LEAVE
The ENTER instruction takes two constant operands. The framesize (a 16-bit
constant) specifies the number of bytes to reserve for local variables.
The nestinglevel (an 8-bit constant) specifies the level at which the
procedure is nested. This operand should always be 0 when writing
procedures for BASIC, C, and FORTRAN. The nestinglevel can be greater than
0 with Pascal and other languages that enable procedures to access the
local variables of calling procedures.
The LEAVE instruction reverses the effect of the last ENTER instruction by
restoring BP and SP to their values before the procedure call.
Example 1
task PROC NEAR
enter 6,0 ; Set stack frame and reserve 6
. ; bytes for local variables
. ; Do task here
.
leave ; Restore stack frame
ret ; Return
task ENDP
Example 1 has the same effect as the code in Example 2.
Example 2
task PROC NEAR
push bp ; Save base pointer
mov bp,sp ; Load stack into base pointer
sub sp,6 ; Reserve 6 bytes for local variables
.
. ; Do task here
.
mov sp,bp ; Restore stack pointer
pop bp ; Restore base
ret ; Return
task ENDP
The code in Example 1 takes fewer bytes, but is slightly slower. See
on-line Help on instructions for exact comparisons of size and timing.
15.4 Using Interrupts
"Interrupts" are a special form of routines that are called by number
instead of by address. They can be initiated by hardware devices as well
as by software. Hardware interrupts are called automatically whenever
certain events occur in the hardware.
Interrupts can have any number from 0 to 255. Most of the interrupts with
lower numbers are reserved for use by the processor, DOS, or the ROM BIOS.
The programmer can call existing interrupts with the INT instruction.
Interrupt routines can also be defined or redefined to be called later.
For example, an interrupt routine that is called automatically by a
hardware device can be redefined so that its action is different.
DOS defines several interrupt handlers. Two that are sometimes used by
applications programmers are listed below:
Interrupt Description
──────────────────────────────────────────────────────────────────────────
0 Divide overflow. Called automatically when the
quotient of a divide operation is too large for the
source operand or when a divide by zero is attempted.
4 Overflow. Called by the INTO instruction if the
overflow flag is set.
Interrupt 21H is the normal method of using DOS functions. To call a
function, place the function number in AH, put arguments in registers as
appropriate, then call the interrupt. For complete documentation of DOS
functions, see the Microsoft MS-DOS Programmer's Reference, one of the
many other books on DOS functions, or the on-line Help system.
DOS has several other interrupts, but they should not normally be called.
Some (such as 20H and 27H) have been replaced by DOS functions. Others are
used internally by DOS.
You can also access ROM-BIOS services through interrupt calls. See the
on-line Help system for a description of all these services.
15.4.1 Calling Interrupts
Interrupts are called with the INT instruction.
Syntax
INT interruptnumber
INTO
The INT instruction takes an immediate operand with a value between 0 and
255.
When calling DOS and ROM-BIOS interrupts, a function number is usually
placed in the AH register. Other registers may be used to pass arguments
to functions. Some interrupts and functions return values in certain
registers. Register use varies for each interrupt.
When the instruction is called, the processor takes the following six
steps:
1. Looks up the address of the interrupt routine in the interrupt
descriptor table. In real mode, this table starts at the lowest point
in memory (segment 0, offset 0) and consists of four bytes (two segment
and two offset) for each interrupt. Thus, the address of an interrupt
routine can be found by multiplying the number of the interrupt by 4.
2. Pushes the flags register, the current code segment (CS), and the
current instruction pointer (IP).
3. Clears the trap (TF) and interrupt enable (IF) flags.
4. Jumps to the address of the interrupt routine, as specified in the
interrupt description table.
5. Executes the code of the interrupt routine until it encounters an IRET
instruction.
6. Pops the instruction pointer, code segment, and flags.
Figure 15.3 illustrates how interrupts work.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 15.4.1 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The INTO (Interrupt On Overflow) instruction is a variation of the INT
instruction. It calls interrupt 04H if called when the overflow flag is
set. By default, the routine for interrupt 4 simply consists of an IRET so
that it returns without doing anything. However, you can write your own
overflow interrupt routine. Using INTO is an alternative to using JO (Jump
On Overflow) to jump to an overflow routine. Section 15.4.2, "Defining
and Redefining Interrupt Routines," gives an example of this.
The CLI (Clear Interrupt Flag) and STI (Set Interrupt Flag) instructions
can be used to turn interrupts on or off. You can use CLI to turn
interrupt processing off so that an important routine cannot be stopped by
a hardware interrupt. After the routine has finished, use STI to turn
interrupt processing back on. Interrupts received while interrupt
processing was turned off by CLI are saved and executed when STI turns
interrupts back on.
Example 1
; DOS call (Display String)
mov ah,09h ; Load function number
mov dx,OFFSET string ; Load argument
int 21h ; Call DOS
Example 2
; BIOS call (Read Character from Keyboard)
xor ah,ah ; Load function number 0 in AH
int 16h ; Call BIOS
; Return scan code in AH
; Return ascii code in AL
Example 1 is a call to a DOS function.
Example 2 is a ROM-BIOS call that works on IBM Personal Computers and
IBM-compatible computers. See the on-line Help system for complete
information on DOS and BIOS calls.
15.4.2 Defining and Redefining Interrupt Routines
You can write your own interrupt routines, either to replace an existing
routine or to use an undefined interrupt number.
Syntax
label PROC FAR[[USES reglist]]
statements
IRET
label ENDP
An interrupt routine can be written like a procedure by using the PROC and
ENDP directives. The only differences are that the routine should always
be defined as far and the routine should be terminated by an IRET
instruction instead of a RET instruction.
──────────────────────────────────────────────────────────────────────────
NOTE Since the assembler doesn't know whether you are going to terminate
with a RET or an IRET, it is possible to use the full extended PROC syntax
(described in Section 15.3.4) for interrupt procedures. However, making
interrupt procedures NEAR or specifying arguments for them makes no sense.
The USES keyword does correctly generate code to save and restore a
register list in interrupt procedures.
──────────────────────────────────────────────────────────────────────────
Your program should replace the address in the interrupt descriptor table
with the address of your routine. DOS calls are provided for this task.
Another common technique is to jump to the old interrupt routine and let
it do the IRET instruction.
It is usually a good idea to save the old address and restore it before
your program ends.
Interrupt routines you may want to replace include the processor's
divide-overflow (0H) and overflow (04H) interrupts. You can also replace
DOS interrupts, such as the critical-error (24H) and CONTROL+C (23H)
handlers. Interrupt routines can be part of device drivers. Writing
interrupt routines is usually a systems task. The example below
illustrates a simple routine. For complete information, see the Microsoft
MS-DOS Programmer's Reference or one of the other reference books on DOS.
Example
.DATA
message DB "Overflow - result set to 0",13,10,"$"
vector DD ?
.CODE
.STARTUP
mov ax,3504h ; Load interrupt 4 and call DOS
int 21h ; get interrupt vector function
mov WORD PTR vector[2],es ; Save segment
mov WORD PTR vector[0],bx ; and offset
push ds ; Save DS
mov ax,cs ; Load segment of new routine
mov ds,ax
mov dx,OFFSET overflow ; Load offset of new routine
mov ax,2504h ; Load interrupt 4 and call DOS
int 21h ; set interrupt vector function
pop ds ; Restore
.
.
.
add ax,bx ; Do addition (or multiplication)
into ; Call interrupt 4 if overflow
.
.
.
lds dx,vector ; Load original interrupt address
mov ax,2504h ; Restore interrupt number 4
int 21h ; with DOS set vector function
mov ax,4C00h ; Terminate function
int 21h
overflow PROC FAR
sti ; Enable interrupts
; (turned off by INT)
mov ah,09h ; Display string function
mov dx,OFFSET message ; Load address
int 21h ; Call DOS
xor ax,ax ; Set AX to 0
xor dx,dx ; Set DX to 0
iret ; Return
overflow ENDP
END start
In this example, DOS functions are used to save the address of the initial
interrupt routine in a variable and to put the address of the new
interrupt routine in the interrupt table. Once the new address has been
set, the new routine is called any time the interrupt is called. The
sample interrupt handler sets the result of a calculation that causes an
overflow (either in AX or AX:DX) to 0. It is good practice to restore the
original interrupt address before terminating the program.
15.5 Checking Memory Ranges
80186/286/386 Only
Starting with the 80186 processor, the BOUND instruction can check to see
if a value is within a specified range. This instruction is usually used
to check a signed index value to see if it is within the range of an
array. BOUND is a conditional interrupt instruction like INTO. If the
condition is not met (the index is out of range), an interrupt 5 is
executed.
Syntax
BOUND register16, memory32
To use it for this purpose, the starting and ending values of the array mu
st be stored as 16-bit values in the low and high words of a doubleword me
mory operand. This operand is given as the source operand. The index value
to be checked is given as the destination operand. If the index value is
out of range, the instruction issues interrupt 5. This means that the oper
ating system or the program must provide an interrupt routine for interrup
t 5. DOS does not provide such a routine, so you must write your own. See
Section 15.4, "Using Interrupts," for more information.
Example
.DATA
bottom EQU 0
top EQU 19
dbounds LABEL DWORD ; Allocate boundaries
wbounds DW bottom,top ; initialized to bounds
array DB top+1 DUP (?) ; Allocate array
.CODE
.
.
. ; Assume index in DI
bound di,dbounds ; Check to see if it is in range
; if out of range, interrupt 5
mov dx,array[di] ; If in range, use it
────────────────────────────────────────────────────────────────────────────
Chapter 16: Processing Strings
The 8086-family processors have a full set of instructions for
manipulating strings. In the discussion of these instructions, the term
"string" refers not only to the common definition of a string──a sequence
of bytes containing characters──but to any sequence of bytes or words
The following instructions are provided for 8086-family string functions:
Instruction Description
──────────────────────────────────────────────────────────────────────────
MOVS Moves string from one location to another
SCAS Scans string for specified values
CMPS Compares values in one string with values in another
LODS Loads values from a string to accumulator register
STOS Stores values from accumulator register to a string
INS Transfers values from a port to memory
OUTS Transfers values from memory to a port
All these instructions use registers in the same way and have a similar
syntax. Most are used with the repeat instruction prefixes: REP, REPE,
REPNE, REPZ, and REPNZ.
This chapter first explains the general format for string instructions and
then tells you how to use each instruction.
16.1 Setting Up String Operations
The string instructions all work in a similar way. Once you understand the
gen-eral procedure, it is easy to adapt the format for a particular string
operation. The five steps are listed below:
1. Make sure the direction flag indicates the direction in which you want
the string to be processed. If the direction flag is clear, the string
will be pro-cessed up (from low addresses to high addresses). If the
direction flag is set, the string will be processed down (from high
addresses to low addresses). The CLD instruction clears the flag, while
STD sets it. Under DOS, the direction flag will normally be cleared if
your program has not changed it.
2. Load the number of iterations for the string instruction into the CX
register. For instance, if you want to process a 100-byte string, load
100. If a string instruction will be terminated conditionally, load the
maximum number of iterations that can be done without an error.
3. Load the starting offset address of the source string into DS:SI and
the starting address of the destination string into ES:DI. Some string
instructions take only a destination or source (shown in Table 16.1
below). Normally, the segment address of the source string should be
DS, but you can use a segment override with the string instruction to
specify a different segment. You cannot override the segment address
for the destination string. Therefore, you may need to change the value
of ES.
4. Choose the appropriate repeat-prefix instruction. Table 16.1 shows the
repeat prefixes that can be used with each instruction.
5. Put the appropriate string instruction immediately after the repeat
prefix (on the same line).
String instructions have two basic forms, as shown below:
Syntax 1
[[repeatprefix]] stringinstruction[[ES:[[destination,]]]]
[[[[segmentregister:]]source]]
The string instruction can be given with the source and/or destination as
operands. The size of the operand or operands indicates the size of the
objects to be processed by the string. Note that the operands only specify
the size. The actual values to be worked on are the ones pointed to by
DS:SI and/or ES:DI. No error is generated if the operand is not the same
as the actual source or destination. One important advantage of this
syntax is that the source operand can have a segment override. The
destination operand is always relative to ES and cannot be overridden.
Syntax 2
[[repeatprefix]] stringinstructionB
[[repeatprefix]] stringinstructionW
The letter B or W appended to stringinstruction indicates bytes or words.
With a letter appended to a string instruction, no operand is allowed.
For instance, MOVS can be given with byte operands to move bytes or with
word operands to move words. As an alternative, MOVSB can be given with no
operands to move bytes, or MOVSW can be given with no operands to move
words.
Note that instructions that specify the size in the name never accept
operands. Therefore, the following statement is illegal:
lodsb es:0 ; Illegal - no operand allowed
Instead, the statement must be coded as shown below:
lods BYTE PTR es:0 ; Legal - use type specifier
If a repeat prefix is used, it can be one of the following instructions:
Instruction Description
──────────────────────────────────────────────────────────────────────────
REP Repeats for a specified number of iterations. The
number is given in CX.
REPE or REPZ Repeats while equal. The maximum number of iterations
should be specified in CX.
REPNE or REPNZ Repeats while not equal. The maximum number of
iterations should be specified in CX.
REPE is the same as REPZ, and REPNE is the same as REPNZ. You can use
whichever name you find more mnemonic. The prefixes ending with E are used
in syntax listings and tables in the rest of this chapter.
Table 16.1 lists each string instruction with the type of repeat prefix it
uses and whether the instruction works on a source, a destination, or
both.
Table 16.1 Requirements for String Instructions
Instruction Repeat Prefix Source/Destination Register Pair
──────────────────────────────────────────────────────────────────────────
MOVS REP Both DS:SI, ES:DI
SCAS REPE/REPNE Destination ES:DI
CMPS REPE/REPNE Both ES:DI, DS:SI
LODS None Source DS:SI
STOS REP Destination ES:DI
INS REP Destination ES:DI
OUTS REP Source DS:SI
──────────────────────────────────────────────────────────────────────────
At run time, a string instruction preceded by a repeat sequence causes the
processor to take the following steps:
1. Checks the CX registers and exits from the string instruction if CX is
0.
2. Performs the string operation once.
3. Increases SI and/or DI if the direction flag is cleared. Decreases SI
and/or DI if the direction flag is set. The amount of increase or
decrease is 1 for byte operations, 2 for word operations.
4. Decrements CX (no flags are modified).
5. If the string instruction is SCAS or CMPS, checks the zero flag and
exits if the repeat condition is false──that is, if the flag is set
with REPE or REPZ or if it is clear with REPNE or REPNZ.
6. Goes to the next iteration (step 1).
Although string instructions (except LODS) are most often used with repeat
prefixes, they can also be used by themselves. In this case, the SI and/or
DI registers are adjusted as specified by the direction flag and the size
of operands. However, you must decrement the CX register and set up a loop
for the repeated action.
──────────────────────────────────────────────────────────────────────────
NOTE Although you can use a segment override on the source operand, a
segment override combined with a repeat prefix can cause problems in
certain situations. If an interrupt occurs during the string operation,
the segment override is lost and the rest of the string operation
processes incorrectly. Segment overrides can be used safely when
interrupts are turned off.
──────────────────────────────────────────────────────────────────────────
16.2 Moving Strings
The MOVS instruction is used to move data from one area of memory to
another.
Syntax
[[REP]] MOVS [[ES:]]destination,[[segmentregister:]]source
[[REP]] MOVSB
[[REP]] MOVSW
To move the data, load the count and the source and destination addresses
into the appropriate registers. Then use REP with the MOVS instruction.
Example 1
.MODEL small
.DATA
source DB 10 DUP ('0123456789')
destin DB 100 DUP (?)
.CODE
mov ax,@data ; Load same segment
mov ds,ax ; to both DS
mov es,ax ; and ES
.
.
.
cld ; Work upward
mov cx,100 ; Set iteration count to 100
mov si,OFFSET source ; Load address of source
mov di,OFFSET destin ; Load address of destination
rep movsb ; Move 100 bytes
Example 1 shows how to move a string by using string instructions. For
comparison, Example 2 shows a much less efficient way of doing the same
operation without string instructions.
Example 2
.MODEL small
.DATA
source DB 10 DUP ('0123456789')
destin DB 100 DUP (?)
.CODE
. ; Assume ES = DS
.
.
mov cx,100 ; Set iteration count to 100
mov si,OFFSET source ; Load offset of source
mov di,OFFSET destin ; Load offset of destination
repeat: mov al,[si] ; Get a byte from source
mov [di],al ; Put it in destination
inc si ; Increment source pointer
inc di ; Increment destination pointer
loop repeat ; Do it again
Both examples illustrate how to move byte strings in a small-model program
in which DS already points to the segment containing the variables. In
such programs, ES can be set to the same value as DS.
There are several variations on this. If the source string was not in the
current data segment, you could load the starting address of its segment
into ES. Another option would be to use the MOVS instruction with operands
and give a segment override on the source operand. For example, you could
use the following statement if ES pointed to both the source and the
destination strings:
rep movs destin,es:source
It is sometimes faster to move a string of bytes as words. You must adjust
for any odd bytes, as shown in Example 3. Assume the source and
destination are already loaded.
Example 3
mov cx,count ; Load count
shr cx,1 ; Divide by 2 (carry will be set
; if count is odd)
rep movsw ; Move words
rcl cx,1 ; If odd, make CX 1
rep movsb ; Move odd byte if there is one
16.3 Searching Strings
The SCAS instruction is used to scan a string for a specified value.
Syntax
[[REPE | REPNE]] SCAS [[ES:]]destination
[[REPE | REPNE]] SCASB
[[REPE | REPNE]] SCASW
SCAS and its variations work only on a destination string, which must be
pointed to by ES:DI. The value to scan for must be in the accumulator
register──AL for bytes, AX for words.
The SCAS instruction works by comparing the value pointed to by DI with
the value in the accumulator. If the values are the same, the zero flag is
set. Thus, the instruction only makes sense when used with one of the
repeat prefixes that checks the zero flag.
If you want to search for the first occurrence of a specified value, use
the REPNE or REPNZ instruction. If the value is found, ES:DI will point to
the value immediately after the first occurrence. You can decrement DI to
make it point to the first matching value.
If you want to search for the first value that does not have a specified
value, use REPE or REPZ. If the value is found, ES:DI will point to the
position after the first nonmatching value. You can decrement DI to make
it point to the first non-matching value.
After a REPNE SCAS, the zero flag will be cleared if no match was found.
After a REPE SCAS, the zero flag will be set if no nonmatch was found.
Example
.DATA
string DB "The quick brown fox jumps over the lazy dog"
lstring EQU $-string ; Length of string
pstring DD string ; Far pointer to string
.CODE
.
.
.
cld ; Work upward
mov cx,lstring ; Load length of string
les di,pstring ; Load address of string
mov al,'z' ; Load character to find
repne scasb ; Search
jnz notfound ; CX is 0 if not found
. ; ES:DI points to character
. ; after first 'z'
.
notfound: ; Special case for not found
This example assumes that ES is not the same as DS, but that the address
of the string is stored in a pointer variable. The LES instruction is used
to load the far address of the string into ES:DI.
16.4 Comparing Strings
The CMPS instruction is used to compare two strings and point to the
address where a match or nonmatch occurs.
Syntax
[[REPE | REPNE]] CMPS [[segmentregister:]]source,[[ES:]],destination
[[REPE | REPNE]] CMPSB
[[REPE | REPNE]] CMPSW
The count and the addresses of the strings are loaded into registers, as
described in Section 16.1, "Setting Up String Operations." Either string
can be considered the destination or source string unless a segment
override is used. Notice that unlike other instructions, CMPS requires
that the source be on the left.
The CMPS instruction works by comparing, in turn, each value pointed to by
DI with the value pointed to by SI. If the values are the same, the zero
flag is set. Thus, the instruction makes sense only when used with one of
the repeat prefixes that checks the zero flag.
If you want to search for the first match between the strings, use the
REPNE or REPNZ instruction. If a match is found, ES:DI and DS:SI will
point to the position after the first match in the respective strings. You
can decrement DI or SI to point to the match. (Conversely, you would
increment DI or SI if the direction flag was set.)
If you want to search for a nonmatch, use REPE or REPZ. If a nonmatch is
found, ES:DI and DS:SI will point to the position after the first nonmatch
in the respective strings. You can decrement DI or SI to point to the
nonmatch.
After a REPNE CMPS, the zero flag will be cleared if no match was found.
After a REPE CMPS, the zero flag will be set if no nonmatch was found.
Example
.MODEL large
.DATA
string1 DB "The quick brown fox jumps over the lazy dog"
.FARDATA
string2 DB "The quick brown dog jumps over the lazy fox"
lstring EQU $-string2
.CODE
mov ax,@data ; Load data segment
mov ds,ax ; into DS
mov ax,@fardata ; Load far data segment
mov es,ax ; into ES
.
.
.
cld ; Work upward
mov cx,lstring ; Load length of string
mov si,OFFSET string1 ; Load offset of string1
mov di,OFFSET string2 ; Load offset of string2
repe cmpsb ; Compare
jnz allmatch ; CX is 0 if no nonmatch
dec si ; Adjust to point to nonmatch
dec di ; in each string
.
.
allmatch: . ; Special case for all match
This example assumes that the strings are in different segments. Both
segments must be initialized to the appropriate segment register.
16.5 Filling Strings
The STOS instruction is used to store a specified value in each position
of a string.
Syntax
[[REP]] STOS [[ES:]]destination
[[REP]] STOSB
[[REP]] STOSW
The string is considered the destination, so it must be pointed to by
ES:DI. The length and address of the string must be loaded into registers,
as described in Section 16.1, "Setting Up String Operations." The value
to store must be in the accumulator register──AL for bytes, AX for words.
For each iteration specified by the REP instruction prefix, the value in
the accumulator is loaded into the string.
Example
.MODEL small
.DATA
destin DB 100 DUP ?
.CODE
. ; Assume ES = DS
.
.
cld ; Work upward
mov ax,'aa' ; Load character to fill
mov cx,50 ; Load length of string
mov di,OFFSET destin ; Load address of destination
rep stosw ; Store 'a' into array
This example loads 100 bytes containing the character 'a'. Notice that
this is done by storing 50 words rather than 100 bytes. This makes the
code faster by reducing the number of iterations. You would have to adjust
for the last byte if you wanted to fill an odd number of bytes.
16.6 Loading Values from Strings
The LODS instruction is used to load a value from a string into a
register.
Syntax
LODS [[segmentregister:]]source
LODSB
LODSW
The string is considered the source, so it must be pointed to by DS:SI.
The value is always loaded from the string into the accumulator
register──AL for bytes, AX for words.
Unlike other string instructions, LODS is not normally used with a repeat
prefix since there is no reason to move a value repeatedly to a register.
However, LODS does adjust the SI register as specified by the direction
flag and the size of operands. The programmer must code the instructions
to use the value after it is loaded.
Example 1
.DATA
stuff DB 0,1,2,3,4,5,6,7,8,9
.CODE
.
.
.
cld ; Work upward
mov cx,10 ; Load length
mov si,OFFSET stuff ; Load offset of source
mov ah,2 ; Display character function
get: lodsb ; Get a character
add al,'0' ; Convert to ASCII
mov dl,al ; Move to DL
int 21h ; Call DOS to display character
loop get ; Repeat
Example 1 loads, processes, and displays each byte in a string of bytes.
Example 2
.DATA
buffer DB 80 DUP(?) ; Create buffer for argument strin
.CODE
start: mov ax,@data ; Initialize DS
mov ds,ax
; On start-up ES points to PSP
cld ; Work upward
mov cl,BYTE PTR es:[80h] ; Load length of arguments
xor ch,ch
mov di,OFFSET buffer ; Load offset of buffer
mov si,82h ; Load position of argument string
mov dx,es ; Exchange ES and DS
mov ax,ds
mov es,ax
mov ds,dx
another: lodsb ; Get a character
cmp al,'a' ; Is it high enough to be upper?
jb noway ; No? Check
cmp al,'z' ; Is it low enough to be letter?
ja noway
sub al,32 ; Yes? Convert to uppercase
noway: stosb
loop another ; Repeat
mov dx,es ; Restore ES and DS
mov ax,ds
mov es,ax
mov ds,dx
Example 2 copies the command arguments from position 82H in the DOS
Program Segment Prefix (PSP) while converting them to uppercase. See the
Microsoft MS-DOS Programmer's Reference or one of the many other books on
DOS for information about the PSP. Notice that both LODSB and STOSB are
used without repeat prefixes.
16.7 Transferring Strings to and from Ports
80186/286/386 Only
The INS instruction reads a string from a port to memory, and the OUTS
instruction writes a string from memory to a port.
Syntax
OUTS DX,[[segmentregister:]]source
OUTSB
OUTSW
INS [[ES:]]destination,DX
INSB
INSW
The INS and OUTS instructions require that the number of the port be in
DX. The port cannot be specified as an immediate value, as it can be with
IN and OUT.
To move the data, load the count into CX. The string to be transferred by
INS is considered the destination string, so it must be pointed to by
ES:DI. The string to be transferred by OUTS is considered the source
string, so it must be pointed to by DS:SI.
If you specify the source or destination as an operand, DX must be
specified. Otherwise, DX is assumed and should be omitted.
If you need to process the string as it is transferred (for instance, to
check for the end of a null-terminated string), you must set up the loop
yourself instead of using the REP instruction prefix.
Example
.DATA
count EQU 100
buffer DB count DUP (?)
inport DW ?
.CODE
. ; Assume ES = DS
.
.
cld ; Work upward
mov cx,count ; Load length to transfer
mov di,OFFSET buffer ; Load address of destination
mov dx,inport ; Load port number
rep insb ; Transfer the string
; from port to buffer
────────────────────────────────────────────────────────────────────────────
Chapter 17: Calculating with a Math Coprocessor
The 8087-family coprocessors are used to do fast mathematical
calculations. When used with real numbers, packed binary coded decimal
(BCD) numbers, or long integers, they do calculations many times faster
than the same operations done with 8086-family processors.
This chapter explains how to use the 8087-family processors to transfer
and process data. The approach taken is from an applications standpoint.
Features that would be used by systems programmers (such the flags used
when writing exception handlers) are not explained. This chapter is
intended as a reference, not a tutorial.
──────────────────────────────────────────────────────────────────────────
NOTE This manual does not attempt to explain the mathematical concepts
involved in using certain coprocessor features. It assumes that you will
not need to use a feature unless you understand the mathematics involved.
For example, you need to understand logarithms to use the FYL2X and
FYL2XP1 instructions.
──────────────────────────────────────────────────────────────────────────
17.1 Coprocessor Architecture
The math coprocessor works simultaneously with the main processor.
However, since the coprocessor cannot handle device input or output, most
data originates in the main processor.
The main processor and the coprocessor have their own registers, which are
completely separate and inaccessible to the other. They exchange data
through memory, since memory is available to both.
Ordinarily you follow these three steps when using the coprocessor:
1. Load data from memory to coprocessor registers.
2. Process the data.
3. Store the data from coprocessor registers back to memory.
Step 2, processing the data, can occur while the main processor is
handling other tasks. Steps 1 and 3 must be coordinated with the main
processor so that the processor and coprocessor do not try to access the
same memory at the same time, as explained in Section 17.5, "Transferring
Data."
17.1.1 Coprocessor Data Registers
The 8087-family coprocessors have eight 80-bit data registers. Unlike
8086-family registers, the coprocessor data registers are organized as a
stack. As data is pushed into the top register, previous data items move
into higher-numbered registers. Register 0 is the top of the stack;
register 7 is the bottom. The syntax for specifying registers is shown
below:
ST[[(number)]]
The number must be a digit between 0 and 7, or a constant expression that
evaluates to a number from 0 to 7. If number is omitted, register 0 (top
of stack) is assumed.
All coprocessor data is stored in registers in the temporary-real format.
This is the 10-byte IEEE format described in Section 6.5.1.4,
"Real-Number Variables." The registers and the register format are shown
in Figure 17.1.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 17.1.1 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Internally, all calculations are done on numbers of the same type. Since
temporary-real numbers have the greatest precision, lower-precision
numbers are guaranteed not to lose precision as a result of calculations.
The instructions that transfer values between the main processor and the
coprocessor automatically convert numbers to and from the temporary-real
format.
17.1.2 Coprocessor Control Registers
The 8087-family coprocessors have seven 16-bit control registers. The most
useful control registers are made up of bit fields or flags. Some flags
control coprocessor operations, while others maintain the current status
of the coprocessor. In this sense, they are much like the 8086-family
flags registers.
You do not need to understand these registers to do most coprocessor
operations. Control flags are set by default to the values appropriate for
most programs. Errors and exceptions are reported in the status-word
register. However, the coprocessor already has a default system for
handling exceptions. Applications programmers can usually accept the
defaults. Systems programmers may want to use the status-word and
control-word registers when writing exception handlers, but such problems
are beyond the scope of this manual.
Figure 17.2 shows the overall layout of the control registers, including
the control word, status word, tag word, instruction pointer, and operand
pointer. The format of each of the registers is not shown, since these
registers are generally of use only to systems programmers. The exception
is the condition-code bits of the status-word register. These bits are
explained in Section 17.7, "Controlling Program Flow."
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 17.1.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The control registers are explained in more detail in the on-line Help
system.
17.2 Emulation
You can write assembly-language procedures that use the emulator library
when called from QuickC. First write the procedure by using coprocessor
instructions, then assemble it using the /E option, and finally link it
with your high-level-language modules. When compiling modules, use the
compiler options that specify emulation.
Some coprocessor instructions are not emulated by Microsoft emulation
libraries. Which instructions are emulated varies depending on the
language and version. If you use a coprocessor instruction that is not
emulated, the program will generate a run-time error when it tries to
execute the unemulated instruction. You cannot use a Microsoft emulation
library with stand-alone assembler programs, since the library depends on
the compiler start-up code.
See Appendix B, Section B.6, "Creating Code for a Floating-Point
Emulator," for information on the /E option. See Appendix A,
"Mixed-Language Mechanics," for information on writing assembly-language
procedures for high-level languages.
17.3 Using Coprocessor Instructions
Coprocessor instructions are readily recognizable because, unlike all
8086-family instruction mnemonics, they start with the letter F.
Most coprocessor instructions have two operands, but in many cases, one or
both operands are implied. Often, one operand can be a memory operand; in
this case, the other operand is always implied as the stack-top register.
Coprocessor instructions can never have immediate operands, and with the
exception of the FSTSW instruction (see Section 17.5.2, "Loading
Constants"), they cannot have processor registers as operands. As with
8086-family instructions, memory-to-memory operations are never allowed.
One operand must be a coprocessor register.
Instructions usually have a source and a destination operand. The source
specifies one of the values to be processed. It is never changed by the
operation. The destination specifies the value to be operated on and
replaced with the result of the operation. If two operands are specified,
the first is the destination and the second is the source.
The stack organization of registers gives the programmer flexibility to
think of registers either as elements on a stack or as registers much like
8086-family registers. Table 17.1 lists the variations of coprocessor
instructions along with the syntax for each.
Table 17.1 Coprocessor Operand Forms
Instruction Form Implied Syntax Operands Example
──────────────────────────────────────────────────────────────────────────
Classical-stack Faction ST(1), ST fadd
Memory Faction memory ST fadd memloc
Register Faction ST(num), fadd st(5),st Faction ST, ST(num)
ST fadd st,st(3)
Register pop FactionP ST(num), faddp st(4),st
ST
──────────────────────────────────────────────────────────────────────────
Not all instructions accept all operand variations. For example, load and
store instructions always require the memory form. Load-constant
instructions always take the classical-stack form. Arithmetic instructions
can usually take any form.
Some instructions that accept the memory form can have the letter I
(integer) or B (BCD) following the initial F to specify how a memory
operand is to be interpreted. For example, FILD interprets its operand as
an integer and FBLD interprets its operand as a BCD number. If no type
letter is included in the instruction name, the instruction works on real
numbers.
17.3.1 Using Implied Operands in the Classical-Stack Form
The classical-stack form treats coprocessor registers like items on a
stack. Items are pushed onto or popped off the top elements of the stack.
Since only the top item can be accessed on a traditional stack, there is
no need to specify operands. The first register (and the second if there
are two operands) is always assumed.
In arithmetic operations (see Section 17.6), the top of the stack (ST) is
the source operand, and the second register (ST(1)) is the destination.
The result of the operation goes into the destination operand, and the
source is popped off the stack. The effect is that both of the values used
in the operation are destroyed and the result is left at the top of the
stack.
Instructions that load constants always use the stack form (see Section
17.5.1, "Transferring Data to and from Registers"). In this case, the
constant created by the instruction is the implied source, and the top of
the stack (ST) is the destination. The source is pushed into the
destination.
Note that the classical-stack form with its implied operands is similar to
the register-pop form, not to the register form. For example, fadd, with
the implied operands ST(1),ST, is equivalent to faddp st(1),st, rather
than to fadd st(1),st.
Example
fld1 ; Push 1 into first position
fldpi ; Push pi into first position
fadd ; Add pi and 1 and pop
The status of the register stack after each instruction is shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 17.3.1 of the manual │
└────────────────────────────────────────────────────────────────────────┘
17.3.2 Using Memory Operands
The memory form treats coprocessor registers like items on a stack. Items
are pushed from memory onto the top element of the stack, or popped from
the top element to memory. Since only the top item can be accessed on a
traditional stack, there is no need to specify the stack operand. The top
register (ST) is always assumed. However, the memory operand must be
specified.
Memory operands can be used in load and store instructions (see Section
17.5.1, "Transferring Data to and from Registers"). Load instructions
push source values from memory to an implied destination register (ST).
Store instructions pop source values from an implied source register (ST)
to the destination in memory. Some versions of store instructions pop the
register stack so that the source is destroyed. Others simply copy the
source without changing the stack.
Memory operands can also be used in calculation instructions that operate
on two values (see Section 17.6, "Doing Arithmetic Calculations"). The
memory operand is always the source. The stack top (ST) is always the
implied destination. The result of the operation replaces the destination
without changing its stack position.
Example
.DATA
m1 DD 1.0
m2 DD 2.0
.CODE
.
.
.
fld m1 ; Push m1 into first position
fld m2 ; Push m2 into first position
fadd m1 ; Add m2 to first position
fstp m1 ; Pop first position into m1
fst m2 ; Copy first position to m2
The status of the register stack and the memory locations used in the
instructions is shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 17.3.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
17.3.3 Specifying Operands in the Register Form
The register form treats coprocessor registers as traditional registers.
Registers are specified the same as 8086-family instructions with two
register operands. The only limitation is that one of the two registers
must be the stack top (ST).
In the register form, operands are specified by name. The second operand
is the source; it is not affected by the operation. The first operand is
the destination; its value is replaced with the result of the operation.
The stack position of the operands does not change.
The register form can only be used with the FXCH instruction and with
arithmetic instructions that do calculations on two values. With the FXCH
instruction, the stack top is implied and need not be specified.
Example
fadd st(1),st ; Add second position to first -
; result goes in second position
fadd st,st(2) ; Add first position to second -
; result goes in first position
fxch st(1) ; Exchange first and second positions
The status of the register stack if the registers were previously
initialized to 1.0, 2.0, and 3.0 is shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 17.3.3 of the manual │
└────────────────────────────────────────────────────────────────────────┘
17.3.4 Specifying Operands in the Register-Pop Form
The register-pop form treats coprocessor registers as a modified stack.
This form has some of the aspects of both a stack and registers. The
destination register can be specified by name, but the source register
must always be the stack top.
The result of the operation will be placed in the destination operand, and
the stack top will be popped off the stack. The effect is that both values
being operated on will be destroyed and the result of the operation will
be saved in the specified destination register. The register-pop form is
only used for instructions that do calculations on two values.
Example
faddp st(2),st ; Add first and third positions and pop -
; first position destroyed
; third moves to second and holds result
The status of the register stack if the registers were already initialized
to 1.0, 2.0, and 3.0 is shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 17.3.4 of the manual │
└────────────────────────────────────────────────────────────────────────┘
17.4 Coordinating Memory Access
Problems of coordinating memory access can occur when the coprocessor and
the main processor both try to access a memory location at the same time.
Since the processor and coprocessor work independently, they may not
finish working on memory in the order in which you give instructions.
There are two separate cases, and they are handled in different ways.
In the first case, if a processor instruction is given and then followed
by a coprocessor instruction, the coprocessor must wait until the
processor is finished before it can start the next instruction. This is
handled automatically by Quick-Assembler for the 8088 and 8086 or by the
processor for the 80186 and 80286.
──────────────────────────────────────────────────────────────────────────
Coprocessor Differences To synchronize operations between the 8088 or
8086 processor and the 8087 coprocessor, each 8087 instruction must be
preceded by a WAIT instruction. This is not necessary for the 80287. If
you use the .8087 directive, QuickAssembler inserts WAIT instructions
automatically. However, if you use the .286 directive, QuickAssembler
assumes the instructions are for the 80287 or 80387 and does not insert
the WAIT instructions. If your code will never need to run on an 8086 or
8088 processor, you can make your programs shorter and more efficient by
using the .286 directive.
──────────────────────────────────────────────────────────────────────────
In the second case, if a coprocessor instruction that accesses memory is
followed by a processor instruction attempting to access the same memory
location, memory access is not automatically synchronized. For instance,
if you store a coprocessor register to a variable and then try to load
that variable into a processor register, the coprocessor may not be
finished. Thus, the processor gets the value that was in memory before the
coprocessor finished, rather than the value stored by the coprocessor. Use
the WAIT or FWAIT instruction (they are mnemonics for the same
instruction) to ensure that the coprocessor finishes before the processor
begins.
Example
; Coprocessor instruction first - Wait needed
fist mem32 ; Store to memory
fwait ; Wait until coprocessor is done
mov ax,WORD PTR mem32 ; Move to register
mov dx,WORD PTR mem32[2]
; Processor instruction first - No wait needed
mov WORD PTR mem32,ax ; Load memory
mov WORD PTR mem32[2],dx
fild mem32 ; Load to register
17.5 Transferring Data
The 8087-family coprocessors have separate instructions for each of the
following types of transfers:
1. Transferring data between memory and registers, or between different
registers
2. Loading certain common constants into registers
3. Transferring control data to and from memory
17.5.1 Transferring Data to and from Registers
Data-transfer instructions transfer data between main memory and the
coprocessor registers, or between different coprocessor registers. Two
basic principles govern data transfers:
■ The instruction determines whether a value in memory will be considered
an integer, a BCD number, or a real number. The value is always
considered a temporary-real number once it is transferred to the
coprocessor.
■ The size of the operand determines the size of a value in memory.
Values in the coprocessor always take up 10 bytes.
The adjustments between formats are made automatically. Notice that
floating-point numbers must be stored in the IEEE format, not in the
Microsoft Binary format. Data is automatically stored correctly by
default. It is stored incorrectly and the coprocessor instructions
disabled if you use the .MSFLOAT directive. Data formats for real numbers
are explained in Section 6.5.1.4, "Real-Number Variables."
Data is transferred to stack registers by using load commands. These
commands push data onto the stack from memory or coprocessor registers.
Data is removed by using store commands. Some store commands pop data off
the register stack into memory or coprocessor registers, whereas others
simply copy the data without changing it on the stack.
17.5.1.1 Real Transfers
The following instructions are available for transferring real numbers:
Syntax Description
──────────────────────────────────────────────────────────────────────────
FLD mem Pushes a copy of mem into ST. The source must be a 4-,
8-, or 10-byte memory operand. It is automatically
converted to the temporary-real format.
FLD ST(num) Pushes a copy of the specified register into ST.
FST mem Copies ST to mem without affecting the register stack.
The destination can be a 4- or 8-byte memory operand.
It is automatically converted from temporary-real
format to short real or long real format, depending on
the size of the operand. It cannot be stored in the
10-byte-real format.
FST ST(num) Copies ST to the specified register. The current value
of the specified register is replaced.
FSTP mem Pops a copy of ST into mem. The destination can be a
4-, 8-, or 10-byte memory operand. It is automatically
converted from temporary-real format to the
appropriate real-number format, depending on the size
of the operand.
FSTP ST(num) Pops ST into the specified register. The current value
of the specified register is replaced.
FXCH [[ST(num)]] Exchanges the value in ST with the value in ST(num).
If no operand is specified, ST(0) and ST(1) are
exchanged.
17.5.1.2 Integer Transfers
The following instructions are available for transferring binary integers:
Syntax Description
──────────────────────────────────────────────────────────────────────────
FILD mem The source must be a 2-, 4-, or 8-byte integer memory
operand. It is interpreted as an integer and converted
to temporary-real format.
FIST mem Copies ST to mem. The destination must be a 2- or
4-byte memory operand. It is automatically converted
from temporary-real format to a word or a doubleword,
depending on the size of the operand. It cannot be
converted to a quadword integer.
FISTP mem Pops ST into mem. The destination must be a 2-, 4-, or
8-byte memory operand. It is automatically converted
from temporary-real format to a word, doubleword, or
quadword integer, depending on the size of the
operand.
17.5.1.3 Packed BCD Transfers
The following instructions are available for transferring BCD integers:
Syntax Description
──────────────────────────────────────────────────────────────────────────
FBLD mem Pushes a copy of mem into ST. The source must be a
10-byte memory operand. It should contain a packed BCD
value, although no check is made to see that the data
is valid.
FBSTP mem Pops ST into mem. The destination must be a 10-byte
memory operand. The value is rounded to an integer if
necessary and converted to a packed BCD value.
The following examples illustrate instructions described throughout this
section:
Example 1
fld m1 ; Push m1 into first item
fld st(2) ; Push third item into first
fst m2 ; Copy first item to m2
fxch st(2) ; Exchange first and third items
fstp m1 ; Pop first item into m1
Assuming that registers ST and ST(1) were previously initialized to 3.0
and 4.0, the status of the register stack is shown below:
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 17.5.1.3 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Example 2
.DATA
shortreal DD 100 DUP (?)
longreal DQ 100 DUP (?)
.CODE
. ; Assume array shortreal has been
. ; filled by previous code
.
mov cx,100 ; Initialize loop
xor si,si ; Clear pointer into shortreal
xor di,di ; Clear pointer into longreal
again: fld shortreal[si] ; Push shortreal
fstp longreal[di] ; Pop longreal
add si,4 ; Increment source pointer
add di,8 ; Increment destination pointer
loop again ; Do it again
Example 2 illustrates one way of doing run-time type conversions.
17.5.2 Loading Constants
Constants cannot be given as operands and loaded directly into coprocessor
registers. You must allocate memory and initialize the variable to a
constant value. The variable can then be loaded by using one of the load
instructions described in Section 17.5.1, "Transferring Data to and from
Registers."
However, special instructions are provided for loading certain constants.
You can load 0, 1, pi, and several common logarithmic values directly.
Using these instructions is faster and often more precise than loading the
values from initialized variables.
The instructions that load constants all have the stack top as the implied
destination operand. The constant to be loaded is the implied source
operand. The instructions are listed below:
Syntax Description
──────────────────────────────────────────────────────────────────────────
FLDZ Pushes 0 into ST
FLD1 Pushes 1 into ST
FLDPI Pushes the value of pi into ST
FLDL2E Pushes the value of log2^e into ST
FLDL2T Pushes log2^10 into ST
FLDLG2 Pushes log10^2 into ST
FLDLN2 Pushes loge^2 ST
17.5.3 Transferring Control Data
The coprocessor data area, or parts of it, can be stored to memory and
later loaded back. One reason for doing this is to save a snapshot of the
coprocessor state before going into a procedure, and restore the same
status after the procedure. Another reason is to modify coprocessor
behavior by storing certain data to main memory, operating on the data
with 8086-family instructions, and then loading it back to the coprocessor
data area.
You can choose to transfer the entire coprocessor data area, the control
registers, or just the status or control word. Applications programmers
seldom need to load anything other than the status word.
All the control-transfer instructions take a single memory operand. Load
instructions use the memory operand as the destination; store instructions
use it as the source. The coprocessor data area is the implied source for
load instructions and the implied destination for store instructions.
Each store instruction has two forms. The "wait form" checks for unmasked
numeric-error exceptions and waits until they have been handled. The
"no-wait" form (which always begins with FN) ignores unmasked exceptions.
The instructions are listed below:
Syntax Description
──────────────────────────────────────────────────────────────────────────
FLDCW mem2byte Loads control word
F[[N]]STCW mem2byte Stores control word
F[[N]]STSW mem2byte Stores status word
FLENV mem14byte Loads environment
F[[N]]STENV mem14byte Stores environment
FRSTOR mem94byte Restores state
F[[N]]SAVE mem94byte Saves state
80287/80387 Only
Starting with the 80287 coprocessor, the FSTSW and FNSTSW instructions can
store data directly to the AX register. This is the only case in which
data can be transferred directly between processor and coprocessor
registers, as shown below:
fstsw ax
17.6 Doing Arithmetic Calculations
The math coprocessors offer a rich set of instructions for doing
arithmetic. Most arithmetic instructions accept operands in any of the
formats discussed in Section 17.3, "Using Coprocessor Instructions."
When using memory operands with an arithmetic instruction, make sure you
indicate in the name whether you want the memory operand to be treated as
a real number or an integer. For example, use FADD to add a real number to
the stack top or FIADD to add an integer to the stack top. You do not need
to specify the operand type in the instruction if both operands are stack
registers, since register values are always real numbers. You cannot do
arithmetic on BCD numbers in memory. You must use FBLD to load the numbers
into stack registers.
The arithmetic instructions are listed below.
Addition
The following instructions add the source and destination and put the
result in the destination:
Syntax Description
──────────────────────────────────────────────────────────────────────────
FADD Classical-stack form. Adds ST and ST(1) and pops the
result into ST. Both operands are destroyed.
FADD ST(num),ST Register form with stack top as source. Adds the two
register values and replaces ST(num) with the result.
FADD ST,ST(num) Register form with stack top as destination. Adds the
two register values and replaces ST with the result.
FADD mem Real-memory form. Adds a real number in mem to ST. The
result replaces ST.
FIADD mem Integer-memory form. Adds an integer in mem to ST. The
result replaces ST.
FADDP ST(num),ST Register-pop form. Adds the two register values and
pops the result into ST(num).
Normal Subtraction
The following instructions subtract the source from the destination and
put the difference in the destination. Thus, the number being subtracted
from is replaced by the result.
Syntax Description
──────────────────────────────────────────────────────────────────────────
FSUB Classical-stack form. Subtracts ST from ST(1) and pops
the result into ST. Both operands are destroyed.
FSUB ST(num),ST Register form with stack top as source. Subtracts ST
from ST(num) and replaces ST(num) with the result.
FSUB ST,ST(num) Register form with stack top as destination. Subtracts
ST(num) from ST and replaces ST with the result.
FSUB mem Real-memory form. Subtracts the real number in mem
from ST. The result replaces ST.
FISUB mem Integer-memory form. Subtracts the integer in mem from
ST. The result replaces ST.
FSUBP ST(num),ST Register-pop form. Subtracts ST from ST(num) and pops
the result into ST(num). Both operands are destroyed.
Reversed Subtraction
The following instructions subtract the destination from the source and
put the difference in the destination. Thus, the number subtracted is
replaced by the result.
Syntax Description
──────────────────────────────────────────────────────────────────────────
FSUBR Classical-stack form. Subtracts ST(1) from ST and pops
the result into ST. Both operands are destroyed.
FSUBR ST(num),ST Register form with stack top as source. Subtracts
ST(num) from ST and replaces ST(num) with the result.
FSUBR ST,ST(num) Register form with stack top as destination. Subtracts
ST from ST(num) and replaces ST with the result.
FSUBR mem Real-memory form. Subtracts ST from the real number in
mem. The result replaces ST.
FISUBR mem Integer-memory form. Subtracts ST from the integer in
mem. The result replaces ST.
FSUBRP ST(num),ST Register-pop form. Subtracts ST(num) from ST and pops
the result into ST(num). Both operands are destroyed.
Multiplication
The following instructions multiply the source and destination and put the
product in the destination:
Syntax Description
──────────────────────────────────────────────────────────────────────────
FMUL Classical-stack form. Multiplies ST by ST(1) and pops
the result into ST. Both operands are destroyed.
FMUL ST(num),ST Register form with stack top as source. Multiplies the
two register values and replaces ST(num) with the
result.
FMUL ST,ST(num) Register form with stack top as destination.
Multiplies the two register values and replaces ST
with the result.
FMUL mem Real-memory form. Multiplies a real number in mem by
ST. The result replaces ST.
FIMUL mem Integer-memory form. Multiplies an integer in mem by
ST. The result replaces ST.
FMULP ST(num),ST Register-pop form. Multiplies the two register values
and pops the result into ST(num). Both operands are
destroyed.
Normal Division
The following instructions divide the destination by the source and put
the quotient in the destination. Thus, the dividend is replaced by the
quotient.
Syntax Description
──────────────────────────────────────────────────────────────────────────
FDIV Classical-stack form. Divides ST(1) by ST and pops the
result into ST. Both operands are destroyed.
FDIV ST(num),ST Register form with stack top as source. Divides
ST(num) by ST and replaces ST(num) with the result.
FDIV ST,ST(num) Register form with stack top as destination. Divides
ST by ST(num) and replaces ST with the result.
FDIV mem Real-memory form. Divides ST by the real number in
mem. The result replaces ST.
FIDIV mem Integer-memory form. Divides ST by the integer in mem.
The result replaces ST.
FDIVP ST(num),ST Register-pop form. Divides ST(num) by ST and pops the
result into ST(num). Both operands are destroyed.
Reversed Division
The following instructions divide the source by the destination and put
the quotient in the destination. Thus, the divisor is replaced by the
quotient.
Syntax Description
──────────────────────────────────────────────────────────────────────────
FDIVR Classical-stack form. Divides ST by ST(1) and pops the
result into ST. Both operands are destroyed.
FDIVR ST(num),ST Register form with stack top as source. Divides ST by
ST(num) and replaces ST(num) with the result.
FDIVR ST,ST(num) Register form with stack top as destination. Divides
ST(num) by ST and replaces ST with the result.
FDIVR mem Real-memory form. Divides the real number in mem by
ST. The result replaces ST.
FIDIVR mem Integer-memory form. Divides the integer in mem by ST.
The result replaces ST.
FDIVRP ST(num),ST Register-pop form. Divides ST by ST(num) and pops the
result into ST(num). Both operands are destroyed.
Other Operations
The following instructions all use the stack top (ST) as an implied
destination operand. The result of the operation replaces the value in the
stack top. No operand should be given.
Syntax Description
──────────────────────────────────────────────────────────────────────────
FABS Sets the sign of ST to positive.
FCHS Reverses the sign of ST.
FRNDINT Rounds ST to an integer.
FSQRT Replaces the contents of ST with its square root.
FSCALE Scales by powers of 2 by adding the value of ST(1) to
the exponent of the value in ST. This effectively
multiplies the stack-top value by 2 to the power
contained in ST(1). Since the exponent field is an
integer, the value in ST(1) should normally be an
integer.
FPREM Calculates the partial remainder by performing modulo
division on the top two stack registers. The value in
ST is divided by the value in ST(1). The remainder
replaces the value in ST. The value in ST(1) is
unchanged. Since this instruction works by repeated
subtractions, it can take a lot of execution time if
the operands are very different in magnitude. FRPEM is
sometimes used with trigonometric functions.
FXTRACT Breaks a number down into its exponent and mantissa
and pushes the mantissa onto the register stack.
Following the operation, ST contains the value of the
original mantissa and ST(1) contains the value of the
unbiased exponent.
Example
.DATA
a DD 3.0
b DD 7.0
c DD 2.0
posx DD 0.0
negx DD 0.0
.CODE
.
.
.
; Solve quadratic equation - no error checking
fld1 ; Get constants 2 and 4
fadd st,st ; 2 at bottom
fld st ; Copy it
fmul a ; = 2a
fmul st(1),st ; = 4a
fxch ; Exchange
fmul c ; = 4ac
fld b ; Load b
fmul st,st ; = b^2
fsubr ; = b^2 - 4ac
; Negative value here produces error
fsqrt ; = square root(b^2 - 4ac)
fld b ; Load b
fchs ; Make it negative
fxch ; Exchange
fld st ; Copy square root
fadd st,st(2) ; Plus version = -b + root((b^2 - 4ac)
fxch ; Exchange
fsubp st(2),st ; Minus version = -b - root((b^2 - 4ac)
fdiv st,st(2) ; Divide plus version
fstp posx ; Store it
fdivr ; Divide minus version
fstp negx ; Store it
This example solves quadratic equations. It does no error checking and
fails for some values because it attempts to find the square root of a
negative number. You could enhance the code by using the FTST instruction
(see Section 17.7.1, "Comparing Operands to Control Program Flow") to
check for a negative number or 0 just before the square root is
calculated. If b^2 - 4ac is negative or 0, the code can jump to routines
that handle special cases for no solution or one solution, respectively.
17.7 Controlling Program Flow
The math coprocessors have several instructions that set control flags in
the status word. The 8087-family control flags can be used with
conditional jumps to direct program flow in the same way that 8086-family
flags are used. Since the coprocessor does not have jump instructions, you
must transfer the status word to memory so that the flags can be used by
8086-family instructions.
An easy way to use the status word with conditional jumps is to move its
upper byte into the lower byte of the processor flags. For example, use
the following statements:
fstsw mem16 ; Store status word in memory
fwait ; Make sure coprocessor is done
mov ax,mem16 ; Move to AX
sahf ; Store upper word in flags
As noted in Section 17.5.3, "Transferring Control Data," you can save
several steps by loading the status word directly to AX on the 80287.
Figure 17.3 shows how the coprocessor control flags line up with the
processor flags. C3 overwrites the zero flag, C2 overwrites the parity
flag, and C0 overwrites the carry flag. C1 overwrites an undefined bit, so
it cannot be used directly with conditional jumps, although you can use
the TEST instruction to check C1 in memory or in a register. The sign and
auxiliary-carry flags are also overwritten, so you cannot count on them
being unchanged after the operation.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section 17.7 of the manual │
└────────────────────────────────────────────────────────────────────────┘
See Section 15.1.2 for more information on using conditional-jump
instructions based on flag status.
17.7.1 Comparing Operands to Control Program Flow
The 8087-family coprocessors provide several instructions for comparing
operands. All these instructions compare the stack top (ST) to a source
operand, which may either be specified or implied as ST(1).
The compare instructions affect the C3, C2, and C0 control flags. The C1
flag is not affected. Table 17.2 shows the flags set for each possible
result of a comparison or test.
Variations on the compare instructions allow you to pop the stack once or
twice, and to compare integers and zero. For each instruction, the stack
top is always the implied destination operand. If you do not give an
operand, ST(1) is the implied source. Some compare instructions allow you
to specify the source as a memory or register operand.
Table 17.2 Control-Flag Settings after Compare or Test
After FCOM After FTEST C3 C2 C0
──────────────────────────────────────────────────────────────────────────
ST > source ST is positive 0 0 0
ST < source ST is negative 0 0 1
ST = source ST is 0 1 0 0
Not comparable ST is NAN or 1 1 1
projective
infinity
──────────────────────────────────────────────────────────────────────────
The compare instructions are listed below.
17.7.1.1 Compare
These instructions compare the stack top to the source. The source and
destination are unaffected by the comparison.
Syntax Description
──────────────────────────────────────────────────────────────────────────
FCOM Compares ST to ST(1).
FCOM ST(num) Compares ST to ST(num).
FCOM mem Compares ST to mem. The memory operand can be a four-
or eight-byte real number.
FICOM mem Compares ST to mem. The memory operand can be a two-
or four-byte integer.
FTST Compares ST to 0. The control registers will be
affected as if ST had been compared to 0 in ST(1).
Table 17.2 above shows the possible results.
17.7.1.2 Compare and Pop
These instructions compare the stack top to the source and then pop the
stack. Thus, the destination is destroyed by the comparison.
Syntax Description
──────────────────────────────────────────────────────────────────────────
FCOMP Compares ST to ST(1) and pops ST off the register
stack.
FCOMP ST(num) Compares ST to ST(num) and pops ST off the register
stack.
FCOMP mem Compares ST to mem and pops ST off the register stack.
The operand can be a four- or eight-byte real number.
FICOMP mem Compares ST to mem and pops ST off the register stack.
The operand can be a two- or four-byte integer.
FCOMPP Compares ST to ST(1) and then pops the stack twice.
Both the source and destination are destroyed by the
comparison.
Example
IFDEF c287
.287
ENDIF
.DATA
down DD 10.35 ; Sides of a rectangle
across DD 13.07
diameter DD 12.93 ; Diameter of a circle
status DW ?
.CODE
.
.
.
; Get area of rectangle
fld across ; Load one side
fmul down ; Multiply by the other
; Get area of circle
fld1 ; Load one and
fadd st,st ; double it to get constant 2
fdivr diameter ; Divide diameter to get radius
fmul st,st ; Square radius
fldpi ; Load pi
fmul ; Multiply it
; Compare area of circle and rectangle
fcompp ; Compare and throw both away
IFNDEF c287
fstsw status ; Load from coprocessor to memory
fwait ; Wait for coprocessor
mov ax,status ; Memory to register
ELSE
fstsw ax ; (for 287+, skip memory)
ENDIF
sahf ; to flags
jp nocomp ; If parity set, can't compare
jz same ; If zero set, they're the same
jc rectangle ; If carry set, rectangle is bigger
jmp circle ; else circle is bigger
nocomp: . ; Error handler
.
same: . ; Both equal
.
rectangle: . ; Rectangle bigger
.
circle: . ; Circle bigger
Notice how conditional blocks are used to enhance 80287 code. If you
define the symbol c287 from the command line by using the /D symbol option
(see Section B.4, "Defining Assembler Symbols"), the code is smaller and
faster, but does not run on an 8087.
17.7.2 Testing Control Flags after Other Instructions
In addition to the compare instructions, the FXAM and FPREM instructions
affect coprocessor control flags.
The FXAM instruction sets the value of the control flags based on the type
of the number in the stack top (ST). This instruction is used to identify
and handle special values, such as infinity, zero, unnormal numbers,
denormal numbers, and NANs (not a number). Certain math operations are
capable of producing these special-format numbers. A description of them
is beyond the scope of this manual. The possible settings of the flags are
shown in the on-line Help system.
FPREM also sets control flags. Since this instruction must sometimes be
repeated to get a correct remainder for large operands, it uses the C2
flag to indicate whether the remainder returned is partial (C2 is set) or
complete (C2 is clear). If the bit is set, the operation should be
repeated.
FPREM also returns the least-significant three bits of the quotient in C0,
C3, and C1. These bits are useful for reducing operands of periodic
transcendental functions, such as sine and cosine, to an acceptable range.
The technique is not explained here. The possible settings for each flag
are shown in the on-line Help system.
17.8 Using Transcendental Instructions
The 8087-family coprocessors provide a variety of instructions for doing
transcendental calculations, including exponentiation, logarithmic
calculations, and some trigonometric functions.
Use of these advanced instructions is beyond the scope of this manual.
However, the instructions are listed below for reference. All
transcendental instructions have implied operands──either ST as a
single-destination operand, or ST as the destination and ST(1) as the
source.
Instruction Description
──────────────────────────────────────────────────────────────────────────
F2XM1 Calculates 2^x-1, where x is the value of the stack
top. The value x must be between 0 and .5, inclusive.
Returning 2^x-1 instead of 2^x allows the instruction
to return the value with greater accuracy. The
programmer can adjust the result to get 2^x.
FYL2X Calculates Y times log2 X, where X is in ST and Y is
in ST(1). The stack is popped, so both X and Y are
destroyed, leaving the result in ST. The value of X
must be positive.
FYL2XP1 Calculates Y times log2 (X+1), where X is in ST and Y
is in ST(1). The stack is popped, so both X and Y are
destroyed, leaving the result in ST. The absolute
value of X must be between 0 and the square root of 2
divided by 2. This instruction is more accurate than
FYL2X when computing the log of a number close to 1.
FPTAN Calculates the tangent of the value in ST. The result
is a ratio Y/X, with Y replacing the value in ST and X
pushed onto the stack so that after the instruction,
ST contains Y and ST(1) contains X. The value being
calculated must be a positive number less than pi/4.
The result of the FPTAN instruction can be used to
calculate other trigonometric functions, including
sine and cosine.
FPATAN Calculates the arctangent of the ratio Y/X, where X is
in ST and Y is in ST(1). The stack is popped, so both
X and Y are destroyed, leaving the result in ST. Both
X and Y must be positive numbers less than infinity,
and Y must be less than X. The result of the FPATAN
instruction can be used to calculate other inverse
trigonometric functions, including arcsine and
arccosine.
17.9 Controlling the Coprocessor
Additional instructions are available for controlling various aspects of
the coprocessor. With the exception of FINIT, these instructions are
generally used only by systems programmers. They are summarized below, but
not fully explained or illustrated. Some instructions have a wait version
and a no-wait version. The no-wait versions have N as the second letter.
Syntax Description
──────────────────────────────────────────────────────────────────────────
F[[N]]INIT Resets the coprocessor and restores all the default
conditions in the control and status words. It is a
good idea to use this instruction at the start and end
of your program. Placing it at the start ensures that
no register values from previous programs affect your
program. Placing it at the end ensures that register
values from your program will not affect later
programs.
F[[N]]CLEX Clears all exception flags and the busy flag of the
status word. It also clears the error-status flag on
the 80287, or the interrupt-request flag on the 8087.
FINCSTP Adds 1 to the stack pointer in the status word. Do not
use to pop the register stack. No tags or registers
are altered.
FDECSTP Subtracts 1 from the stack pointer in the status word.
No tags or registers are altered.
FREE ST(num) Marks the specified register as empty.
FNOP Copies the stack top to itself, thus padding the
executable file and taking up processing time without
having any effect on registers or memory.
8087 Only
The 8087 has the instructions FDISI, FNDISI, FENI, and FNENI. These
instructions can be used to enable or disable interrupts. The 80287
coprocessor permits these instructions, but ignores them. Applications
programmers will not normally need these instructions. Systems programmers
should avoid using them so that their programs are portable to all
coprocessors.
────────────────────────────────────────────────────────────────────────────
Chapter 18: Controlling the Processor
The 8086-family processors provide instructions for processor control.
These instructions are available on all 8086-family processors.
System-control instructions have limited use in applications programming.
They are primarily used by systems programmers who write operating systems
and other control software. Since systems programming is beyond the scope
of this manual, the systems-control instructions are summarized, but not
explained in detail, in the sections below.
This chapter ends with a description of all the directives that enable the
instruction sets for the various processors in the 8086 family.
18.1 Controlling Timing and Alignment
The NOP instruction takes up one byte of memory but does not have any
effect when executed. The purpose of this instruction is generally to fill
up space in the code segment; primarily, it is used to pad executable code
for alignment.
Although NOP has no effect, it does take a few clock cycles to execute. In
a sense, NOP does do something──it is exactly equivalent to the following
instruction:
xchg ax,ax ; Exchange AX with itself
Because NOP does use up some clock time, you can use it in timing loops by
executing it many times. However, when writing a program for use on
different machines, avoid using this technique. Timing loops that use NOP
take different lengths of time on different machines. A better way to
control timing is to use the DOS Get Time function, since it is based on
the computer's internal clock rather than on the speed of the processor.
QuickAssembler automatically inserts NOP instructions for padding when you
use the ALIGN or EVEN directive (see Section 6.7, "Aligning Data") to
align data or code on a given boundary.
18.2 Controlling the Processor
The LOCK, WAIT, ESC, and HLT instructions control different aspects of the
processor.
These instructions can be used to control processes handled by external
coprocessors. The 8087-family coprocessors are the coprocessors most
commonly used with 8086-family processors, but 8086-based machines can
work with other coprocessors if they have the proper hardware and control
software.
These instructions are summarized below:
Instruction Description
──────────────────────────────────────────────────────────────────────────
LOCK Locks out other processors until a specified
instruction is finished. This is a prefix that
precedes the instruction. It can be used to make sure
that a coprocessor does not change data being worked
on by the processor.
WAIT Instructs the processor to do nothing until it
receives a signal that a coprocessor has finished with
a task being performed at the same time. See Section
17.4, "Coordinating Memory Access," for information
on using WAIT or its coprocessor equivalent, FWAIT,
with the 8087-family coprocessors.
ESC Provides an instruction and possibly a memory operand
for use by a coprocessor. QuickAssembler automatically
inserts ESC instructions when required for use with
8087-family coprocessors.
HLT Stops the processor until an interrupt is received. It
can be used in place of an endless loop if a program
needs to wait for an interrupt.
18.3 Processor Directives
Processor and coprocessor directives define the instruction set that is
recognized by QuickAssembler. They are listed and explained below:
Directive Description
──────────────────────────────────────────────────────────────────────────
.8086 The .8086 directive enables assembly of instructions
for the 8086 and 8088 processors and the 8087
coprocessor. It disables assembly of the instructions
unique to the 80186, 80286, and 80386 processors.
This is the default mode and is used if no instruction
set directive is specified. Using the default
instruction set ensures that your program can be used
on all 8086-family processors. However, if you choose
this directive, your program will not take advantage
of the more powerful instructions available on more
advanced processors.
.186 The .186 directive enables assembly of the 8086
processor instructions, 8087 coprocessor instructions,
and the additional instructions for the 80186
processor.
.286 The .286 directive enables assembly of the 8086
instructions plus the additional nonprivileged
instructions of the 80286 processor. It also enables
80287 coprocessor instructions. If privileged
instructions were previously enabled, the .286
directive disables them.
This directive should be used for programs that will
be executed only by an 80186, 80286, or 80386
processor. For compatibility with early versions of
the Macro Assembler, the .286C directive is also
available. It is equivalent to the .286 directive.
.8087 The .8087 directive enables assembly of instructions
for the 8087 math coprocessor and disables assem-bly
of instructions unique to the 80287 coprocessor. It
also specifies the IEEE format for encoding
floating-point variables.
This is the default mode and is used if no coprocessor
directive is specified. This directive should be used
for programs that must run with either the 8087,
80287, or 80387 coprocessors.
.287 The .287 directive enables assembly of instructions
for the 8087 floating-point coprocessor and the
additional instructions for the 80287. It also
specifies the IEEE format for encoding floating-point
variables.
Coprocessor instructions are optimized if you use this
directive rather than the .8087 directive. Therefore,
you should use it if you know your program will never
need to run under an 8087 coprocessor. See Section
17.4, "Coordinating Memory Access," for an
explanation.
If you do not specify any processor directives, QuickAssembler uses the
following defaults:
1. 8086/8088 processor instruction set
2. 8087 coprocessor instruction set
3. IEEE format for floating-point variables
Normally, the processor and coprocessor directives can be used at the
start of the source file to define the instruction sets for the entire
assembly. However, it is possible to use different processor directives at
different points in the source file to change assumptions for a section of
code. For instance, you might have processor-specific code in different
parts of the same source file. You can also turn privileged instructions
on and off or allow unusual combinations of the processor and coprocessor.
There are two limitations on changing the processor or coprocessor:
1. The directives must be given outside segments. You must end the current
segment, give the processor directive, and then open another segment.
See Section 5.1.5, "Using Predefined Segment Equates," for an example
of changing the processor directives with simplified segment
directives.
2. You can specify a lower-level coprocessor with a higher-level
coprocessor, but an error message will be generated if you try to
specify a lower-level processor with a higher-level coprocessor.
The coprocessor directives have the opposite effect of the .MSFLOAT
directive. .MSFLOAT turns off coprocessor instruction sets and enables the
Microsoft Binary format for floating-point variables. Any coprocessor
instruction turns on the specified coprocessor instruction set and enables
IEEE format for floating-point variables.
Examples
; .MSFLOAT affects the source file until turned off
.MSFLOAT
.8087 ; Ignored
; Illegal - can't use 8086 with 80287
.8086
.287
────────────────────────────────────────────────────────────────────────────
Appendix A: Mixed-Language Mechanics
The QuickAssembler PROC statement automates most details of interfacing to
QuickC, as well as to other Microsoft high-level languages. When you use
PROC with a parameter list or USES clause as described in Section 15.3.4,
or when you use the LOCAL directive, the assembler generates code that
properly enters and exits the procedure. The assembler also determines the
location of each parameter on the stack for you. You refer to each
parameter by a meaningful name, and the assembler translates each
parameter name into the actual memory reference.
The main purpose of this appendix is to show you what code the assembler
generates when you use the LOCAL directive or expanded features of the
PROC directive. However, you can write this code yourself rather than
letting the assembler generate it. Doing so requires significant extra
work, but it does give you complete control over your procedure.
Using simplified segment directives is the easiest way to interface with a
Microsoft high-level language (including QuickC). The simplified segment
directives generate segment definitions similar to the ones generated by
high-level languages and guarantee compatibility in the use of segment
names and conventions. If you want to use full segment definitions, see
Chapter 5, "Defining Segment Structure," for a description of the
segments used in Microsoft languages.
A.1 Writing the Assembly Procedure
The Microsoft BASIC, C, FORTRAN, and Pascal compilers use roughly the same
interface for procedure calls. This section describes the interface, so
that you can call assembly procedures using essentially the same methods
as Microsoft compiler-generated code. Procedures written with these
methods can be called recursively.
The standard assembly-interface method consists of these steps:
1. Setting up the procedure
2. Entering the procedure
3. Allocating local data (optional)
4. Preserving register values
5. Accessing parameters
6. Returning a value (optional)
7. Exiting the procedure
The PROC statement, when used with a parameter list or USES clause,
automates steps 1 and 2, and simplifies step 5 for you. The LOCAL
directive automates step 3, and the USES clause automates step 4. Finally,
if you use any of these features, the assembler automatically generates
all the proper code to exit (step 7) wherever it encounters a RET
directive. (However, the RETF and RETN statements never generate automatic
code.)
Sections A.1.1-A.1.7 describe these steps.
A.1.1 Setting Up the Procedure
The linker cannot combine the assembly procedure with the calling program
unless compatible segments are used and unless the procedure itself is
declared properly. The following points may be helpful:
1. Use the .MODEL directive at the beginning of the source file; this
directive automatically causes the appropriate kind of returns to be
generated (NEAR for small or compact model, FAR otherwise). Modules
called from Pascal should be declared as .MODEL LARGE; modules called
from BASIC should be .MODEL MEDIUM.
2. Use the simplified segment directives: .CODE to declare the code
segment and .DATA to declare the data segment. (Having a code segment
is sufficient if you do not have data declarations.)
3. Tie procedure label must be public. This makes the procedure available
to be called by other modules. If you specify a language type with the
.MODEL directive, the assembler automatically makes all procedure names
public, but you must use the PUBLIC directive if you don't specify the
language. Also, any data you want to make public to other modules must
be declared as PUBLIC.
4. Global data or procedures accessed by the routine (but defined in other
modules) must be declared EXTRN.
A.1.2 Entering the Procedure
Two instructions begin the procedure:
push bp
mov bp,sp
This sequence establishes BP as the framepointer. The framepointer is used
to access parameters and local data, which are located on the stack. SP
cannot be used for this purpose because it is not an index or base
register. Also, the value of SP may change as more data is pushed onto the
stack. However, the value of the base register (BP) will remain constant
throughout the procedure, so that each parameter can be addressed as a
fixed displacement from the location pointed to by BP.
The instruction sequence above first saves the value of BP, since it will
be needed by the calling procedure as soon as the current procedure
terminates. Then BP is loaded with the value of SP in order to capture the
value of the stack pointer at the time of entry to the procedure.
The PROC statement generates these two lines of code automatically if you
use a parameter list, LOCAL directive, or USES clause.
──────────────────────────────────────────────────────────────────────────
NOTE If you alter the direction flag with the STD instruction, make sure
you reset this flag with the CLD instruction before you exit.
──────────────────────────────────────────────────────────────────────────
A.1.3 Allocating Local Data (Optional)
Local variables are also called dynamic, stack, or automatic variables.
An assembly procedure can use the same technique for implementing local
data used by high-level languages. To set up local data space, decrease
the contents of SP in the third instruction of the procedure. (To ensure
correct execution, you should always increase or decrease SP by an even
amount.) Decreasing SP reserves space on the stack for the local data. The
space must be restored at the end of the procedure.
push bp
mov bp,sp
sub sp,space
In the code above, space is the total size in bytes of the local data.
Local variables are then accessed as fixed, negative displacements from
the location pointed to by BP.
Example
push bp
mov bp,sp
sub sp,4
.
.
.
mov WORD PTR [bp-2],0
mov WORD PTR [bp-4],0
The example above uses two local variables, each of which is two bytes in
size. SP is decreased by 4, since there are four bytes total of local
data. Later, each of the variables is initialized to 0. These variables
are never formally declared with any assembler directive; the programmer
must keep track of them manually.
The LOCAL directive uses this same method for creating local variables.
However, when you use LOCAL, you can refer to a local variable by a
symbolic name rather than by a reference, such as WORD PTR [bp-2].
A.1.4 Preserving Register Values
A procedure called from any of the Microsoft high-level languages should
preserve the values of SI, DI, SS, and DS (in addition to BP, which is
already saved). Therefore, push any of these register values that the
procedure alters. If the procedure does not change the value of any of
these registers, the registers do not need to be pushed.
The recommended method (used by high-level languages) is to save registers
after the framepointer is set and local data (if any) is allocated.
push bp ; Save old framepointer
mov bp,sp ; Establish current framepointer
sub sp,4 ; Allocate local data space
push si ; Save SI and DI
push di
.
.
.
In the example above, DI and SI (in that order) must be popped from the
stack before the end of the procedure.
The USES clause in a PROC statement causes the assembler to generate this
same code.
A.1.5 Accessing Parameters
When you use PROC with a parameter list, the assembler calculates the
location of each parameter on the stack. This section shows how the
assembler determines these locations. If you do not use a parameter list,
you must calculate parameter locations yourself and refer to them
explicitly by their offsets from BP. Otherwise, you can refer to each
parameter by the name you gave it in the parameter list.
To write instructions that can access parameters, consider the general
picture of the stack frame after a procedure call, as illustrated in
Figure A.1.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section A.1.5 of the manual │
└────────────────────────────────────────────────────────────────────────┘
When determining the order of parameters on the stack, note that the C
calling convention (the default for QuickC) specifies that parameters are
passed in the reverse order they appear in source code. The non-C calling
convention (which you can specify in QuickC with the pascal or fortran
keyword) specifies that parameters are passed in the same order they
appear in source code.
The stack frame for the procedure is established by the following
sequence:
1. The calling program pushes each of the parameters on the stack, after
which SP points to the last parameter pushed.
2. The calling program issues a CALL instruction, which causes the return
address (the place in the calling program to which control will
ultimately return) to be placed on the stack. This address may be
either two bytes long (for near calls) or four bytes long (for far
calls). SP now points to this address.
3. The first instruction of the called procedure saves the old value of
BP, with the instruction push bp. SP now points to the saved copy of
BP.
4. BP is used to capture the current value of SP, with the instruction mov
bp,sp. BP therefore now points to the old value of BP.
5. Whereas BP remains constant throughout the procedure, SP may be
decreased to provide room on the stack for local data or saved
registers.
In general, the displacement (from the location pointed to by BP) for a
parameter X is equal to:
2 + size of return address + total size of parameters between X and BP
For example, consider a FAR procedure that has received one parameter, a
two-byte address. The displacement of the parameter would be:
Argument's displacement = 2 + size of return address
= 2 + 4
= 6
The argument can thus be loaded into BX with the following instruction:
mov bx,[bp+6]
Once you determine the displacement of each parameter, you may want to use
string equates or structures so that the parameter can be referenced with
a single identifier name in your assembly source code. For example, the
parameter above at BP+6 can be conveniently accessed if you put the
following statement at the beginning of the assembly source file:
Arg1 EQU <[bp+6]>
You could then refer to this parameter as Arg1 in any instruction. Use of
this feature is optional.
──────────────────────────────────────────────────────────────────────────
NOTE Microsoft high-level languages always push segment addresses before
pushing offset addresses. Furthermore, when pushing arguments larger than
two bytes, high-order words are always pushed before low-order words.
This standard for pushing segment addresses before pushing offset
addresses facilitates the use of the LES and LDS instructions, as
described in Chapter 3, "Writing Assembly Modules for C Programs."
──────────────────────────────────────────────────────────────────────────
A.1.6 Returning a Value (Optional)
The assembler does not generate code to return a value. If you want your
procedure to return a value, you must take care of the details yourself.
Microsoft BASIC, C, FORTRAN, and Pascal share similar conventions for
receiving return values. The conventions are the same when the data type
to be returned is simple (that is, not an array or structured type) and is
no more than four bytes long. This includes all NEAR and FAR address types
(in other words, all pointers and all parameters passed by reference).
Data Size Returned in Register
──────────────────────────────────────────────────────────────────────────
1 byte AL
2 bytes AX
4 bytes High-order portion (or segment address) in DX;
low-order portion (or offset address) in AX
When the return value is larger than four bytes, a procedure called by C
must allocate space for the return value and then place its address in
DX:AX. You can create space for the return value by simply declaring it in
a data segment.
If your assembly procedure uses the non-C calling convention, it must use
a special convention in order to return floating-point values, records,
user-defined types and arrays, and values larger than four bytes. This
convention is presented below.
BASIC/FORTRAN/Pascal Long Return Values
To create an interface for long return values, modules using the non-C
calling convention take the following actions before they call your
procedure:
1. The calling modules create space, somewhere in the stack segment, to
hold the actual return value.
2. When the call to your procedure is made, an extra parameter is passed
containing the offset address of the actual return value. This
parameter is placed immediately above the return address. (In other
words, this parameter is the last one pushed.)
3. The segment address of the return value is contained in both SS and DS.
The extra parameter (containing the offset address of the return value) is
always located at BP+6. Furthermore, its presence automatically increases
the displacement of all other parameters by 2, as shown in Figure A.2.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section A.1.6 of the manual │
└────────────────────────────────────────────────────────────────────────┘
Your assembly procedure will successfully return a long value if you
follow these steps:
1. Put the data for the return value at the location pointed to by the
return value offset.
2. Copy the return-value offset (located at BP+6) to AX, and copy SS to
DX. This is necessary because the calling module expects DX:AX to point
to the return value.
3. Exit the procedure as described in the next section.
A.1.7 Exiting the Procedure
Several steps may be involved in terminating the procedure:
1. If any of the registers SS, DS, SI, or DI have been saved, these must
be popped off the stack in the reverse order that they were saved.
2. If local data space was allocated at the beginning of the procedure, SP
must be restored with the instruction mov sp,bp.
3. Restore BP with pop bp. This step is always necessary.
4. Finally, return to the calling program with ret. If the BASIC, FORTRAN,
or Pascal calling convention is in use, you can use the ret n form of
the instruction to adjust the stack with respect to the parameters that
were pushed by the caller. (If the procedure is called by a C module,
the calling module will perform this adjustment.)
Examples
pop bp
ret
The example above shows the simplest possible exit sequence. No registers
were saved, no local data space was allocated, and the C calling
convention is in use.
pop di ; Pop saved regs
pop si
mov sp,bp ; Remove local data space
pop bp ; Restore old framepointer
ret 6 ; Exit, and restore 6 byte of args
The example above shows an exit sequence for a procedure that has
previously saved SI and DI, allocated local data space, and uses a non-C
calling convention. The procedure must therefore use ret 6 (where n is 6)
to restore the six bytes of parameters on the stack.
Assuming you use one of the automated features described above (such as a
parameter list or LOCAL directive), the assembler generates all the code
to properly exit from a procedure whenever it encounters a RET
instruction. However, the assembler does not generate any exit code when
you use the directives RETN or RETF.
A.2 Calls from Modules Using C Conventions
Most of the details below are automated when you use simplified segment
directives and the expanded features of the PROC directive. Make sure to
declare both a language type and a memory model with the .MODEL directive.
This section reviews all the steps taken when you use the C language type.
In addition to the steps outlined in Section A.1, the assembler observes
the following rules to set up an interface to C.
Follow these rules if you want to manually establish this interface:
1. Declare procedures called from C as FAR if the C module is compiled in
large, huge, or medium model, and NEAR if the C module is compiled in
small or compact model (although the near and far keywords can override
these defaults). The correct declaration for the procedure is made
implicitly when you use the .MODEL directive. Note that tiny memory
model is not supported by QuickC 2.0.
2. Observe the C calling convention.
a. Return with a simple ret instruction. Do not restore the stack with
ret size, since the calling C routine will restore the stack itself
as soon as it resumes control.
b. Parameters are placed on the stack in the reverse order that they
appear in the C source code. The first parameter will be lowest in
memory (because it is placed on the stack last and the stack grows
downward).
c. By default, C parameters are passed by value, except for arrays,
which are passed by reference. As a rule, do not expect an address
to be placed on the stack, unless the C code specifically refers to
a pointer or array in the function call or prototype.
3. Observe the C naming convention.
Include an underscore (_) in front of any name that will be shared
publicly with C. C recognizes only the first eight characters of any
name, so do not make names shared with C longer than eight characters.
Also, if you plan to link with the /NOIGNORECASE option, remember that
C is case sensitive and does not convert names to uppercase. To
preserve lowercase names in public symbols, choose Preserve Case or
Preserve Extrn from the Assembler Flags dialog box, or assemble with
the /Cl or /Cx option on the QCL command line.
In the example program below, C calls an assembly procedure that
calculates "A x 2^B," where A and B are the first and second parameters,
respectively. The calculation is performed by shifting the bits in A to
the left, B times.
extern int power2( int, int ),
main ()
{
printf( "3 times 2 to the power of 5 is %d\n",
power2( 3, 5 ) );
}
The C program uses an extern declaration to create an interface with the
assembly procedure. No special keywords are required because the assembly
procedure will use the C calling convention.
To understand how to write the assembly procedure, consider how the
parameters are placed on the stack, as illustrated in Figure A.3.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section A.2 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The return address is two bytes long, assuming that the C module is
compiled in small or compact model. If the C module is compiled in large,
huge, or medium model, the addresses of Arg 1 and Arg 2 are each increased
by 2, to BP+6 and BP+8, respectively, because the return address will be
four bytes long.
Arg 1 (parameter 1) is lower in memory than Arg 2, because C pushes
arguments in the reverse order that they appear. Each argument is passed
by value.
The assembly procedure can be written as follows:
.MODEL small
.CODE
PUBLIC _power2
_power2 PROC
push bp ; Entry sequence - save old BP
mov bp,sp ; Set stack framepointer
mov ax,[bp+4] ; Load Arg1 into AX
mov cx,[bp+6] ; Load Arg2 into CX
shl ax,cl ; AX = AX * (2 to power of CX)
; Leave return value in AX
pop bp ; Exit sequence - restore old BP
ret ; Return
_power2 ENDP
END
The example above assumes that the C module is compiled in small model.
The parameter offsets and the .MODEL directive will change for different
models.
Note that ret without a size variable is used, since the caller will
adjust the stack upon return from the call.
A.3 Calls from Non-C Modules
In your C programs you can specify the pascal or fortran function type.
These keywords are equivalent: they both specify use of non-C calling and
naming conventions. Furthermore, you may want to interface to languages
other than C (which you can do by linking .OBJ files together outside the
environment). In all these cases, make sure you specify BASIC, FORTRAN, or
Pascal as the language type with the .MODEL directive. Alternately, you
can specify the language as part of the procedure if you are using the
extended PROC directive.
This section reviews all the steps taken when you use a non-C language
type. In addition to the steps outlined in Section A.1, the assembler
observes the following rules to set up an interface to a language using a
non-C calling convention.
Follow these rules if you want to manually establish an interface to a
high-level language:
1. If the procedure is called from Microsoft BASIC, Pascal, or FORTRAN,
make sure to declare the procedure as FAR, or use the .MODEL directive
to specify medium or large memory model. BASIC always uses medium
memory model; Pascal uses large memory model.
2. Observe the non-C calling convention.
a. Upon exit, the procedure must reset SP to the value it had before
the parameters were placed on the stack. This is accomplished with
the instruction ret size, where size is the total size in bytes of
all the parameters.
b. Parameters are placed on the stack in the same order in which they
appear in the high-level language source code. The first parameter
will be highest in memory (because it is placed on the stack first
and the stack grows downward).
c. Each language has different defaults for passing parameters by value
or reference. When a language passes by reference, it places a data
pointer on the stack. When it passes by value, it places a complete
copy of the parameter on the stack. Consult your language
documentation for the details of when the language passes by value
or reference. (In C, the default is by value except for arrays.)
3. Observe the language naming convention.
Microsoft BASIC, FORTRAN, and Pascal output symbolic names in uppercase
characters, which is also the default behavior of the assembler. Each
language recognizes a different number of characters in a name. For
example, BASIC recognizes up to 40 characters of a name, whereas the
assembler recognizes only the first 31.
In the following example program, QuickBASIC 4.0 calls an assembly
procedure that calculates "A x 2B," where A and B are the first and second
parameters, respectively. The calculation is performed by shifting the
bits in A to the left, B times. (Note: with earlier versions of BASIC, you
need to rewrite the example so that it calls a subprogram, not a
function.)
' BASIC program
DEFINT A-Z
PRINT "3 times 2 to the power of 5 is ";
PRINT Power2(3,5)
END
To understand how to write the assembly procedure, consider how the
parameters are placed on the stack, as illustrated in Figure A.4.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section A.3 of the manual │
└────────────────────────────────────────────────────────────────────────┘
The return address is four bytes long because procedures called from BASIC
must be FAR. Arg 1 (parameter 1) is higher in memory than Arg 2 because
BASIC pushes arguments (parameters) in the same order in which they
appear. Also, each argument is passed as a two-byte offset address, the
BASIC default.
The assembly procedure can be written as follows:
.MODEL medium
.CODE
PUBLIC Power2
Power2 PROC
push bp ; Entry sequence - save old BP
mov bpsp ; Set stack framepointer
mov bx,[bp+8] ; Load Arg1 into
mov ax,[bx] ; AX
mov bx,[bp] ; Load Arg2 into
mov cx,[bx] ; CX
shl ax,cl ; AX = AX * (2 to power of CX)
; Leave return value in AX
pop bp ; Exit sequence - restore old BP
ret 4 ; Return, and restore 4 bytes
Power2 ENDP
END
Note that each parameter must be loaded in a two-step process because the
address of each is passed rather than the value. Also, note that the stack
is restored with the instruction ret 4, since the total size of the
parameters is four bytes.
A.4 Calling High-Level Languages from Assembly Language
Many high-level-language routines assume that certain initialization code
has previously been executed; you can ensure that the proper
initialization is performed by starting in a high-level-language module,
and then calling an assembly procedure. The assembly procedure can then
call high-level-language routines as needed, as shown in Figure A.5.
┌────────────────────────────────────────────────────────────────────────┐
│ This figure can be found in Section A.4 of the manual │
└────────────────────────────────────────────────────────────────────────┘
To execute an assembly call to a high-level language, you need to observe
the following guidelines:
1. Push each parameter onto the stack, observing the calling convention of
the high-level language. Constants, such as offset addresses, must
first be loaded into a register before being pushed.
2. With long parameters, always push the segment or high-order portion of
the parameter first, regardless of the calling convention.
3. If you are using the BASIC/FORTRAN/Pascal calling convention with a
function that returns a noninteger value, allocate an additional
two-byte parameter. This additional parameter should contain the offset
of the location where you want the value returned and must be pushed on
the stack last.
4. Execute a call. The call must be far unless the high-level-language
routine is small model.
5. If the routine used the C calling convention, after the call you must
immediately clear the stack of parameters with the instruction add sp,
size, where size is the total size in bytes of all parameters that were
pushed.
A.5 Using Full Segment Definitions
If you use the simplified segment directives by themselves, you do not
need to know the names assigned for each segment. However, if you choose
to use full segment definitions, you should use the SEGMENT, GROUP,
ASSUME, and ENDS directives equivalent to the simplified segment
directives.
The following example shows the C-assembly program from Section A.3,
without the simplified segment directives:
_TEXT SEGMENT WORD PUBLIC 'CODE'
ASSUME cs:_TEXT
PUBLIC _Power2
_Power2 PROC
push bp ; Entry sequence - save BP
mov bp,sp ; Set stack frame
mov ax,[bp+4] ; Load Arg1 into AX
mov cx,[bp+6] ; Load Arg2 into CX
shl ax,cl ; AX = AX * (2 to power of CX)
; Leave return value in AX
pop bp ; Exit sequence - restore BP
ret ; Return
_Power2 ENDP
_TEXT ENDS
END
────────────────────────────────────────────────────────────────────────────
Appendix B: Using Assembler Options with QCL
You can use the QCL driver for both compiling and assembling. The driver
compiles .C files and assembles .ASM files. Unless the /c option is given,
the QCL driver then links together all resulting .OBJ files, as well as
any .OBJ files specified on the command line. The default file extension
is .OBJ.
If you acquired QuickAssembler as an upgrade, make sure you use the
version of QCL that came with the QuickAssembler package. This driver
program is an updated and expanded version, and it supports assembly
options in addition to all the compile options listed in the QuickC Tool
Kit.
The following options may affect work with .ASM files, but are not
described here because they work precisely the same way as described in
the QuickC Tool Kit:
Option Action
──────────────────────────────────────────────────────────────────────────
/help Print help listing for QCL
/link flags Specify linker flags
/Fefile Specify output file
/Fofile Name object file
/Z{d|i} Generate debugging information.
The /c, /D, and /W options are documented in the QuickC Tool Kit, but are
also documented here because their meaning and usage change somewhat for
assembly-language files.
In addition to the linker options documented in the QuickC Tool Kit, QCL
supports one other option, /TINY. This option causes the linker to output
a .COM file, if possible. The linker can only create a .COM file if the
program is entirely written in assembly language, and all the modules
observe the rules for the .COM format. (The easiest way to do this is to
use tiny memory model as described in Chapter 5.) The following example
generates a .COM file:
QCL /AT TINYPROG.ASM /link /TINY
The /AT option causes the assembler to check the assembly code for
adherence to the .COM format. The /TINY linker option causes the linker to
generate a .COM file.
The QuickAssembler version of QCL supports the following options in
addition to the ones supported for use with C-language modules:
Option Action
──────────────────────────────────────────────────────────────────────────
/a Writes segments in alphabetical order
/AT Requires program to use tiny memory model; gives error
messages for code that violates requirements of .COM
format
/C{l|u|x} Determines case sensitivity (l=preserve case,
u=convert to upper, x=preserve case of external and
public symbols)
/D Defines symbols
/Ez Displays error lines on screen
/Flfile Generates an assembly-listing file with given file
name
/FPi Creates code for emulated floating-point instructions
/l Generates an assembly-listing file
/P1 Enables one-pass assembly
/s Writes segments in source-code order (reverses effect
of /a)
/Sa Lists all lines of macro expansions (assumes /Flfile
or /l is given)
/Sd Adds pass 1 information to listing (assumes /Flfile or
/l is given)
/Se Creates editor-oriented listing file; the resulting
listing has no page breaks or page headings (assumes
/Flfile or /l is given)
/Sn Suppresses symbol-table in listing (assumes /Flfile or
/l is given)
/Sq Generates an editor-based listing file with a
source-line index at the end (assumes Flfile or /l is
given)
/Sx Suppresses listing of false conditionals (assumes
Flfile or /l is given)
/t Suppresses messages if assembly is successful
/v Displays extra statistics during assembly
/w Equivalent to /W0
/W{0|1|2} Sets warning-message level
B.1 Specifying the Segment-Order Method
Syntax
/s Default
/a
The /a option directs QuickAssembler to place the assembled segments in
alphabetical order before copying them to the object file. The /s option
directs the assembler to write segments in the order in which they appear
in the source code.
Source-code order is the default. If no option is given, QuickAssembler
copies the segments in the order encountered in the source file. The /s
option is provided for compatibility with the XENIX(R) operating system
and for overriding a default option in the QuickAssembler environment
variable.
──────────────────────────────────────────────────────────────────────────
NOTE Some previous versions of the IBM Macro Assembler ordered segments
alphabetically by default. Listings in some books and magazines have been
written with these early versions in mind. If you have trouble assembling
and linking a listing taken from a book or magazine, try using the /a
option.
──────────────────────────────────────────────────────────────────────────
The order in which segments are written to the object file is only one
factor in determining the order in which they will appear in the
executable file. The significance of segment order and ways to control it
are discussed in Sections 5.2.1, "Setting the Segment-Order Method" and
5.2.2.2, "Defining Segment Combinations with Combine Type."
Example
QCL /a file.asm
The example above creates an object file, FILE.OBJ, whose segments are
arranged in alphabetical order. If the /s option were used instead, or if
no option were specified, the segments would be arranged in sequential
order.
B.2 Checking Code for Tiny Model
Syntax
/AT
The /AT option causes the assembler to enforce the requirements of .COM
format. If the .MODEL directive is used, /AT generates an error unless the
directive specifies tiny memory model. If the .MODEL directive is not
used, the /AT option generates an error if any program-defined segments
are referenced (since these references violate conditions of .COM format).
The use of /AT alone does not generate a .COM file. You must also use the
/TINY linker option, as in the following example:
QCL /AT TINYPROG.ASM /link /TINY
B.3 Selecting Case Sensitivity
Syntax
/Cu Default
/Cl
/Cx
The /Cl option directs the assembler to make all names case sensitive. The
/Cx option directs the assembler to make public and external names case
sensitive. The /Cu option directs the assembler to convert all names to
uppercase.
By default, QuickAssembler converts all names to uppercase (/Cu).
If case sensitivity is turned on, all names that have the same spelling
but use letters of different cases are considered distinct. For example,
with the /Cl option, DATA and data are different. They would also be
different with the /Cx option if they were declared external or public.
Public and external names include any label, variable, or symbol names
defined by using the EXTRN, PUBLIC, or COMM directives (see Chapter 8,
"Creating Programs from Multiple Modules").
If you use the /Zi or /Zd option (these cause QCL to include debugging
information), the /Cx, /Cl, and /Cu options affect the case of the
symbolic data that will be available to a symbolic debugger.
The /Cl and /Cx options are typically used when object modules created
with QuickAssembler are to be linked with object modules created by a
case-sensitive compiler such as the Microsoft C compiler. If case
sensitivity is important, you should also use the linker /NOI option.
Example
QCL /Cx module.asm
This example shows how to use the /Cx option with QuickAssembler to
assemble a file with case-sensitive public symbols.
B.4 Defining Assembler Symbols
Syntax
/Dsymbol[[=value]]
The /D option, when given with a symbol argument, directs QuickAssembler
to define a symbol that can be used during the assembly as if it were
defined as a text equate in the source file. Multiple symbols can be
defined in a single command line.
The value can be any text string that does not include a space, comma, or
semicolon. If value is not given, the symbol is assigned a null string.
Example
QCL /Dwide /Dmode=3 file,,;
This example defines the symbol wide and gives it a null value. The symbol
could then be used in the following conditional-assembly block:
IFDEF wide
PAGE 50,132
ENDIF
When the symbol is defined in the command line, the listing file is
formatted for a 132-column printer. When the symbol is not defined in the
command line, the listing file is given the default width of 80 (see the
description of the PAGE directive in Section 12.2, "Controlling Page
Format in Listings").
The example also defines the symbol mode and gives it the value 3. The
symbol could then be used in a variety of contexts, as shown below:
IF mode LT 15 ; Use in expression
scrmode DB mode ; Initialize to mode
ELSE
scrmode DB 15 ; Initialize to 15
ENDIF
B.5 Displaying Error Lines on the Screen
Syntax
/Ez
The /Ez option directs QuickAssembler to display lines containing errors
on the screen. Normally, when the assembler encounters an error, it
displays only an error message describing the problem. When you use the
/Ez option in the command line, the assembler displays the source line
that produced the error in addition to the error message. QuickAssembler
assembles faster without the /Ez option, but you may find the convenience
of seeing the incorrect source lines worth the slight cost in processing
speed.
Example
QCL /Ez file.asm
B.6 Creating Code for a Floating-Point Emulator
Syntax
/FPi 87 /FPi
The /FPi and /FPi87 options control how instructions for a math
coprocessor (such as the 8087, 80287, or 80387) are assembled. The /FPi
option tells the assembler to generate code for a coprocessor emulator
library. The /FPi87 option tells the assembler to generate code for a
coprocessor. These options are different than most other QuickAssembler
options in that the default for C files is /FPi, but the default for
assembler files is /FPi87. They are also different in that the options
must be specified separately for each file.
An emulator library uses the instructions of a coprocessor if one is
present; otherwise, the library executes interrupts that emulate
coprocessor instructions. Emulator libraries are available for QuickC and
other high-level language compilers, including Microsoft Pascal, BASIC,
and FORTRAN compilers.
With QuickAssembler, you should specify /FPi only for assembly modules
that will be linked with a main C module, since the emulator code requires
the start-up code generated by the C compiler. A stand-alone assembler
program generated with /FPi will execute emulator interrupts, but the
program will not work because the interrupts will not be initialized. If
you are programming in the QC environment and you want the emulator
library to be used with an assembler module, you must specify /FPi in the
Global Custom Flags field of the Assembler Flags dialog box (reached from
the Options menu). This will affect all assembly modules in the program
list.
To the applications programmer, writing code for the emulator is like
writing code for a coprocessor. The instruction sets are the same (except
as noted in Chapter 17, "Calculating with a Math Coprocessor"). However,
at run time the coprocessor instructions are used only if there is a
coprocessor available on the machine. If there is no coprocessor, the
slower code from the emulator library is used instead.
The /FPi87 option specifies that coprocessor instructions should be
generated directly. It does not need to be given directly for assembly
modules, since it is the default, but it must be specified for C modules.
Programs that use this option can be run only on a system that has a
coprocessor. If the program contains a main C module, it will fail with a
warning if the system has no coprocessor. If the program is a stand-alone
assembler program, you should write the code to check for a coprocessor
and terminate with an error message if no coprocessor exists.
Example
QCL calc.c /FPi /Cx math.asm
The example above assembles MATH.ASM with the /FPi option and compiles the
C source file CALC.C. The resulting object files are then linked together
to produce the file CALC.EXE. The C compiler generates emulator code for
floating-point instructions. The FORTRAN, BASIC, and Pascal compilers
generate similar code.
B.7 Creating Listing Files
Syntax
/l
/Flfile
The /l option directs QuickAssembler to create a listing file. Files
specified with this option always have the base name of the source file
plus a .LST extension. You cannot specify any other file name. The /Fl
option has the same purpose as /l, but lets you specify any file name as
the listing file. The default file name is the base file name plus a .LST
extension.
Example
QCL /l prog.asm
This example causes the assembler to generate the file PROG.LST during
assembly.
B.8 Enabling One-Pass Assembly
Syntax
/P1
The /P1 option causes the assembler to attempt translation of source code
in one pass. If successful, the translation is significantly faster than
the default two-pass assembly. Assembly modules cannot be successfully
assembled with this option if they contain conditional-assembly directives
that make references to pass 1 or pass 2.
──────────────────────────────────────────────────────────────────────────
NOTE One-pass assembly is not compatible with the generation of listing
files or the /a option for specifying alphabetical segment order.
──────────────────────────────────────────────────────────────────────────
If the assembler generates a message reporting that one-pass assembly is
not possible, simply assemble the file again without using this option.
Example
QCL /P1 file.asm
B.9 Listing All Lines of Macro Expansions
Syntax
/Sa
The /Sa option causes the listing file to contain all statements generated
by the assembler. It overrides directives that limit listings such as
.XLIST, .XALL, and .SFCOND. It forces display of all statements generated
automatically by simplified segment directives and the extended PROC
syntax. The /Sa option has no effect unless /l or /Fl is also specified.
Example
QCL /l /Sa file.asm
B.10 Creating a Pass 1 Listing
Syntax
/Sd
The /Sd option causes the listing file to contain the results of both
assembler passes. A pass 1 listing is typically used to locate phase
errors. Phase errors occur when the assembler makes assumptions about the
program in pass 1 that are not valid in pass 2. The /Sd option has no
effect unless /l or /Fl is also specified.
Example
QCL /l /Sd file.asm
B.11 Specifying an Editor-Oriented Listing
Syntax
/Se
The /Se option causes the assembler to generate the listing file in a
format suited to text editors. This format does not contain page breaks or
page headings. The default behavior, which is designed for files output to
a printer, assumes a page break and heading at periodic intervals. The /Se
option has no effect unless /l or /Fl is also specified.
Example
QCL /l /Se file.asm
B.12 Suppressing Tables in the Listing File
Syntax
/Sn
The /Sn option tells the assembler to omit all tables from the end of the
listing file. If this option is not chosen, QuickAssembler includes tables
of macros, structures, records, segments and groups, and symbols. The code
portion of the listing file is not changed by the /Sn option. The /Sn
option has no effect unless /l or /Fl is also specified.
Example
QCL /l /Sn file.asm
B.13 Adding a Line-Number Index to the Listing
Syntax
/Sq
The /Sq option generates an editor-based listing file just as the /Se
option does, but it also adds a source-line index to the end of the
listing file. This index contains pairs of corresponding line numbers for
the listing file and appropriate source files. The QuickC/QuickAssembler
environment uses this information to let you move from a source file to
the corresponding position in a listing file.
When you create a listing file from within the QuickC/QuickAssembler
environment, QC.EXE automatically passes this option to the assembler. The
/Sq option has no effect unless /l or /Fl is also specified.
Example
QCL /l /Sq file.asm
B.14 Listing False Conditionals
Syntax
/Sx
The /Sx option directs QuickAssembler to copy to the assembly listing all
statements forming the body of conditional-assembly blocks whose condition
is false. If you do not give the /Sx option in the command line,
QuickAssembler suppresses all such statements. The /Sx option lets you
display conditionals that do not generate code. Conditional-assembly
directives are explained in Chapter 12, "Controlling Assembly Output."
The .LFCOND, .SFCOND, and .TFCOND directives can override the effect of
the /Sx option, as described in Section 12.3.2, "Controlling Listing of
Conditional Blocks." The /Sx option does not affect the assembly listing
unless you direct the assembler to create an assembly-listing file.
Example
QCL /Sx file,,;
Listing of false conditionals is turned on when FILE.ASM is assembled.
Directives in the source file can override the /Sx option to change the
status of false-conditional listing.
B.15 Controlling Display of Assembly Statistics
Syntax
/v
/t
The /v and /t options specify the level of information displayed to the
screen at the end of assembly (/v is a mnemonic for verbose; /t is a
mnemonic for terse).
If neither option is given, QuickAssembler outputs a line telling the
amount of symbol space free and the number of warnings and errors.
If the /v option is given, QuickAssembler also reports the number of lines
and symbols processed.
If the /t option is given, QuickAssembler does not output anything to the
screen unless errors are encountered. This option may be useful in batch
or make files if you do not want the output cluttered with unnecessary
messages.
If errors are encountered, they will be displayed whether these options
are given or not.
B.16 Setting the Warning Level
Syntax
/W{0 | 1 | 2}
/w
The /W option sets the assembler warning level. QuickAssembler gives
warning messages for assembly statements that are ambiguous or
questionable but not necessarily illegal. Some programmers purposely use
practices that generate warnings. By setting the appropriate warning
level, they can turn off warnings if they are aware of the problem and do
not wish to take action to remedy it. The /w option is equivalent to /W0.
QuickAssembler has three levels of errors, as shown in Table B.1.
Table B.1 Warning Levels
Level Type Description
──────────────────────────────────────────────────────────────────────────
0 Severe errors Illegal statements
1 Serious Ambiguous statements or questionable
warnings programming practices
2 Advisory Statements that may produce inefficient
warnings code
──────────────────────────────────────────────────────────────────────────
The default warning level is 1. A higher warning level includes all of the
messages reported by a lower level. Level 2 includes severe errors,
serious warnings, and advisory warnings. If severe errors are encountered,
no object file is produced.
Warning level 0 reports error messages in the range 1000-2999. Warning
level 1 reports warning and error messages in the ranges 1000-2999 and
4000-4999. Warning level 2 reports all warning and error messages,
including those numbered 5000 and above.
────────────────────────────────────────────────────────────────────────────
Appendix C: Reading Assembly Listings
QuickAssembler creates an assembly listing of your source file whenever
you give an assembly-listing option on the QCL command line or select a
listing file option in the Assembler Flags dialog box. The assembly
listing contains both the statements in the source file and the object
code (if any) generated for each statement. The listing also shows the
names and values of all labels, variables, and symbols in your source
file.
The assembler creates tables for macros, structures, records, segments,
groups, and other symbols. These tables are placed at the end of the
assembly listing (unless you suppress them with the QCL /Sn option).
QuickAssembler lists only the types of symbols encountered in the program.
All symbol names will be shown in uppercase letters unless you choose
Preserve Case or Preserve Extrn from the Assembler Flags dialog box or use
a QCL option (/Cx or /Cl) that supports case sensitivity.
C.1 Reading Code in a Listing
The assembler lists the code generated from the statements of a source
file. Each line has the syntax shown below:
offset [[code]] statement
The offset is the offset from the beginning of the current segment to the
code. If the statement generates code or data, code shows the numeric
value in hexadecimal if the value is known at assembly time. If the value
is calculated at run time, the assembler indicates what action is
necessary to compute the value. The statement is the source statement
shown exactly as it appears in the source file, or as expanded by a macro.
If any errors occur during assembly, each error message and error number
will appear directly below the statement where the error occurred. An
example of an error line and message is shown below:
0012 E8 001C R call doit
test.ASM(46): error A2071: Forward needs override or FAR
The assembler uses the symbols and abbreviations in Table C.1 to indicate
addresses that need to be resolved by the linker or values that were
generated in a special way.
Table C.1 Symbols and Abbreviations in Listings
Character Meaning
──────────────────────────────────────────────────────────────────────────
R Relocatable address (linker must resolve)
E External address (linker must resolve)
---- Segment/group address (linker must resolve)
= EQU or equal-sign (=) directive
nn: Segment override in statement
nn/ REP or LOCK prefix instruction
nn[xx] DUP expression: nn copies of the value xx
n Macro-expansion nesting level (+ if more than nine)
C Line from include file
──────────────────────────────────────────────────────────────────────────
Example
The sample listing shown in this section is produced using the /Se option,
which produces an editor-oriented listing. The QuickC/QuickAssembler
environment always produces this kind of listing. The editor-oriented
environment produces no page headings and is thus ideal for viewing within
the environment or another editor. If you are using QCL to generate a
listing file that you intend to print, you may want to generate a
printer-oriented listing file by giving the /Sp option:
QCL /l /Sp listdemo.asm
The code portion of the resulting listing is shown below. The tables
normally seen at the end of the listing are explained later, in Sections
C.2-C.7.
Microsoft(R) QuickC with QuickAssembler Version 2.01 Listing features demo
PAGE 65,132
TITLE Listing features demo
C INCLUDE dos.mac
C StrAlloc MACRO name,text
C name DB &text
C DB 13d,10d
C l&name EQU $-name
C ENDM
= 0080 larg EQU 80h
DOSSEG
.MODEL small
0100 .STACK 256
color RECORD b:1,r:3=1,i:1=1,f:3=7
date STRUC
0000 05 month DB 5
0001 07 day DB 7
0002 07C3 year DW 1987
0004 date ENDS
0000 .DATA
0000 1F text color <>
0001 09 today date <9,22,1987>
0002 16
0003 07C3
0005 0064[ buffer DW 100 DUP(?)
????
StrAlloc ending,"Finished."
00CD 46 69 6E 69 73 68 65 1 ending DB "Finished."
00D6 0D 0A 1 DB 13d,10d
0000 .CODE
0000 B8 ---- R start: mov ax,@DATA
0003 8E D8 mov ds,ax
0005 B8 0063 mov ax,'c'
0008 26: 8B 0E 0080 mov cx,es:larg
000D BF 0052 mov di,82
0010 F2/ AE repne scasb
0012 57 push di
EXTRN work:NEAR
0013 E8 0000 E call work
0016 B8 170C mov ax,4C00
listdemo.ASM(40): error A2107: Non-digit in number
0019 CD 21 int 21h
001B END start
C.2 Reading a Macro Table
A macro table at the end of a listing file gives the names and sizes (in
lines) of all macros called or defined in the source file. The macros
appear in alphabetical order.
Example
Macros:
N a m e Lines
STRALLOC . . . . . . . . . . . . 3
C.3 Reading a Structure and Record Table
All structures and records declared in the source file are given at the
end of the listing file. The names are listed in alphabetical order. Each
name is followed by the fields in the order in which they are declared.
Example
Structures and Records:
N a m e Width # fields
Shift Width Mask Initial
COLOR . . . . . . . . . . . . . 0008 0004
B . . . . . . . . . . . . . . 0007 0001 0080 0000
R . . . . . . . . . . . . . . 0004 0003 0070 0010
I . . . . . . . . . . . . . . 0003 0001 0008 0008
F . . . . . . . . . . . . . . 0000 0003 0007 0007
DATE . . . . . . . . . . . . . . 0004 0003
MONTH . . . . . . . . . . . . 0000
DAY . . . . . . . . . . . . . 0001
YEAR . . . . . . . . . . . . . 0002
The first row of headings only applies to the record or structure itself.
For a record, the "Width" column shows the width in bits while the "#
fields" column tells the total number of fields.
The second row of headings applies only to fields of the record or
structure. For records, the "Shift" column lists the offset (in bits) from
the low-order bit of the record to the low-order bit in the field. The
"Width" column lists the number of bits in the field. The "Mask" column
lists the maximum value of the field, expressed in hexadecimal. The
"Initial" column lists the initial value of the field, if any. For each
field, the table shows the mask and initial values as if they were placed
in the record and all other fields were set to 0.
For a structure, the "Width" column lists the size of the structure in
bytes. The "# fields" column lists the number of fields in the structure.
Both values are in hexadecimal.
For structure fields, the "Shift" column lists the offset in bytes from
the beginning of the structure to the field. This value is in hexadecimal.
The other columns are not used.
C.4 Reading a Segment and Group Table
Segments and groups used in the source file are listed at the end of the
program with their size, align type, combine type, and class. If you used
simplified segment directives in the source file, the actual segment names
generated by QuickAssembler will be listed in the table.
Example
Segments and Groups:
N a m e Size Align Combine Class
DGROUP . . . . . . . . . . . . . GROUP
_DATA . . . . . . . . . . . . 00D8 WORD PUBLIC 'DATA'
STACK . . . . . . . . . . . . 0800 PARA STACK 'STACK'
_TEXT . . . . . . . . . . . . . 0018 BYTE PUBLIC 'CODE'
The "Name" column lists the names of all segments and groups. Segment and
group names are given in alphabetical order, except that the names of
segments belonging to a group are placed under the group name in the order
in which they were added to the group.
The "Size" column lists the byte size (in hexadecimal) of each segment.
The size of groups is not shown.
The "Align" column lists the align type of the segment.
The "Combine" column lists the combine type of the segment. If no explicit
combine type is defined for the segment, the listing shows NONE,
representing the private combine type. If the "Align" column contains AT,
the "Combine" column contains the hexadecimal address of the beginning of
the segment.
The "Class" column lists the class name of the segment. For a complete
explanation of the align, combine, and class types, see Section 5.2.2,
"Defining Full Segments."
C.5 Reading a Symbol Table
All symbols (except names for macros, structures, records, and segments)
are listed in a symbol table at the end of the listing.
Example
Symbols:
N a m e Type Value Attr
BUFFER . . . . . . . . . . . . . L WORD 0005 _DATA Length = 0064
ENDING . . . . . . . . . . . . . L BYTE 00CD _DATA
LARG . . . . . . . . . . . . . . NUMBER 0080
LENDING . . . . . . . . . . . . NUMBER 000B
START . . . . . . . . . . . . . L NEAR 0000 _TEXT
TEXT . . . . . . . . . . . . . . L BYTE 0000 _DATA
TODAY . . . . . . . . . . . . . L DWORD 0001 _DATA
WORK . . . . . . . . . . . . . . L NEAR 0000 _TEXT External
@CODE . . . . . . . . . . . . . TEXT _TEXT
@CODESIZE . . . . . . . . . . . TEXT 0
@DATA . . . . . . . . . . . . . TEXT DGROUP
@DATASIZE . . . . . . . . . . . TEXT 0
@FARDATA . . . . . . . . . . . . TEXT FAR_DATA
@FARDATA? . . . . . . . . . . . TEXT FAR_BSSk
@FILENAME . . . . . . . . . . . TEXT listdemo
@MODEL . . . . . . . . . . . . . TEXT 1
@VERSION . . . . . . . . . . . . TEXT 520
The "Name" column lists the names in alphabetical order. The "Type" column
lists each symbol's type. A type is given as one of the following:
Type Definition
──────────────────────────────────────────────────────────────────────────
L NEAR A near label
L FAR A far label
N PROC A near procedure label
F PROC A far procedure label
NUMBER An absolute label
ALIAS An alias for another symbol
TEXT A text equate
BYTE One byte
WORD One word (two bytes)
DWORD Doubleword (four bytes)
QWORD Quadword (eight bytes)
TBYTE Ten bytes
number Length in bytes of a structure variable
The length of a multiple-element variable, such as an array or string, is
the length of a single element, not the length of the entire variable. For
example, string variables are always shown as L BYTE.
If the symbol represents an absolute value defined with an EQU or
equal-sign (=) directive, the "Value" column shows the symbol's value. The
value may be another symbol, a string, or a constant numeric value (in
hexadecimal), depending on whether the type is ALIAS, TEXT, or NUMBER. If
the symbol represents a variable, label, or procedure, the "Value" column
shows the symbol's hexadecimal offset from the beginning of the segment in
which it is defined.
The "Attr" column shows the attributes of the symbol. The attributes
include the name of the segment (if any) in which the symbol is defined,
the scope of the symbol, and the code length. A symbol's scope is given
only if the symbol is defined using the EXTRN and PUBLIC directives. The
scope can be external, global, or communal. The code length (in
hexadecimal) is given only for procedures. The "Attr" column is blank if
the symbol has no attribute.
The text equates shown at the end of the sample table are the ones defined
automatically when you use simplified segment directives (see Section
5.1.1, "Understanding Memory Models").
C.6 Reading Assembly Statistics
Data on the assembly, including the number of lines and symbols processed
and the errors or warnings encountered, is shown at the end of the
listing.
Example
48 Source Lines
52 Total Lines
53 Symbols
45570 + 310654 Bytes symbol space free
0 Warning Errors
1 Severe Errors
C.7 Reading a Pass 1 Listing
When you specify the /Sd option in the QCL command line or select Pass One
Information from the Assembler Flags dialog box, the assembler puts a pass
1 listing in the assembly-listing file. The listing file shows the results
of both assembler passes. Pass 1 listings are useful in analyzing phase
errors.
The following example illustrates a pass 1 listing for a source file that
assembled without error on the second pass.
0017 7E 00 jle label1
PASS_CMP.ASM(20) : error 9 : Symbol not defined LABEL1
0019 BB 1000 mov bx,4096
001C label1:
During pass 1, the JLE instruction to a forward reference produces an
error message and the value 0 is encoded as the operand. QuickAssembler
displays this error because it has not yet encountered the symbol label1.
Later in pass 1, label1 is defined. Therefore, the assembler knows about
label1 on pass 2 and can fix the pass 1 error. The pass 2 listing is shown
below:
0017 7E 03 jle label1
0019 BB 1000 mov bx,4096
001C label1:
The operand for the JLE instruction is now coded as 3 instead of 0 to
indicate that the distance of the jump to label1 is three bytes.
Since QuickAssembler generated the same number of bytes for both passes,
there was no error. Phase errors occur if the assembler makes an
assumption on pass 1 that it cannot change on pass 2. If you get a phase
error, you can examine the pass 1 listing to see what assumptions the
assembler made.
═══════════════════════════════════════════════════════════════════════════
Index
Symbols
(brackets)
with arrays
index operator
with registers
+ (plus sign), to separate registers
_ (underscore)
Numbers
10-byte temporary-real format
.186 directive
.286 directive
.287 directive
.8086 directive
8086-family processors
assembly language
calculating physical addresses (figure)
flags (figure)
instructions
registers (figure)
.8087 directive
8087-family registers, modifying
A
/a option
AAA instruction
AAD instruction
AAM instruction
AAS instruction
ABS type
Absolute segments
Accumulator
ADC instruction
ADD instruction
Adding
Addressing modes
contrasted with C
defined
direct memory
immediate
indirect memory
listed
register
Advisor, Quick
Advisory warnings
AH register
AL register
Aliases
ALIGN directive
Align type
Alignment, of segments
.ALPHA directive
& (ampersand), operator
Ampersand (&), operator
AND instruction
AND operator
\la (angle brackets), operator
Angle brackets (\la), operator
Animate command
Arguments
macros
passing on stack
repeat blocks
Arithmetic operators (table)
Arrays
accessing elements of
boundary checking
defining
specifying elements
ASCII character set
converting numerals to face value
name for unpacked BCD numbers
Assembler display mode
Assembler Flags dialog box (figure)
Assembler options, summary
Assembly
calling from C
parameters, accessing
passing by
near reference
value
warning levels (table)
Assembly listing
addresses
false conditionals
macros
page breaks
page length
page width
reading
subtitle
suppressing
title
Assembly-language books
ASSUME directive
(at sign)
symbol names, used in
/AT option
AT combine type
Attributes of variables
Auto display mode
Automatic variables
Auxiliary-carry flag
AX register
B
Base register
Based operands
Based-indexed operands
BASIC
calling convention
for loops
nestinglevel
ON GOTO statements
stack
frame (figure)
long return values (figure)
BCD (binary coded decimal) numbers
calculations with
constants
defining of
transfer instructions (list)
variables initialized
BH register
Binary integers, transfer instructions (list)
Binary radix
Binary to decimal conversion
BIOS functions
calling with interrupts
on-line help
Bit fields
Bit mask
Bits, rotating and shifting (figure)
Bitwise operators
BL register
Boolean bit operations
BOUND instruction
Boundary-checking array
BP register
Brackets ()
with arrays
index operator
with registers
Buffers
Bugs, reporting
Building programs
within environment
QCL driver
BY memory operator
BYTE align type
BYTE type specifier
C
C compiler
C display mode
C language
assembly call (figure)
calling convention
if statement
interfacing with
loops
memory models and
nestinglevel value
passing by value
return value
stack frame (figure)
switch statements
C register variables
CALL instruction
Call tables
Calling convention
Calls command
Carry flag
Case sensitivity
compilers
lack of
options
preserving
CATSTR directive
CBW instruction
CH register
Character constant
Character set
/Cl option
/Cl option
CL register
defined
use in shifting bits
Class type
Classical-stack operands, coprocessor
CLC instruction
CLD instruction
CLI instruction
CMP instruction
CMPS instruction
.CODE directive
CODE class name
Code equate
Code Segment register
Code segments
developing programs with
initializing
(colon), operator
definition
(colon), operator
in Debug expressions
.COM file, assembling
.COM format
debugging
example
with full segment definitions
initializing
with linker
restrictions on
tiny memory model
Combine type
COMENT object record
COMM directive
Command line, QC
COMMENT directive
COMMON combine type
Communal symbols
Compact memory model
Compare instructions
Comparing
register to zero
strings
Concatenating strings
Conditional assembly
Conditional directives
assembly directives
assembly passes
error directives
macro arguments
nesting
operators
symbol definition
value of true and false
Conditional-error directives (table)
Conditional-jump instructions
based on flag status (table)
defined
logic
used after Compare (table)
.CONST directive
Constants
as direct memory operands
integer
loading instructions (list)
multiplying and dividing by
packed binary coded decimal
real number
string
use of
Control data, coprocessor
Control registers, coprocessor (figure)
Control-flag settings (table)
Control-flow instructions
Controlling program flow
Converting
binary to decimal
data sizes
Coprocessors
architecture
control data
control flags (figure)
control instructions (list)
control registers (figure)
data registers (figure)
directives (list)
emulator
loading data
loading pi
no-wait instructions
operand forms (table)
storing data
Copying data
Count register
Cpu equate
CS register
/Cu option
Current-line highlighting
Custom flags
Customer support
CWD instruction
/Cx option
/Cx option
CX register
D
D
DAA instruction
DAS instruction
.DATA directive
.DATA? directive
Data conversion
Data equate
Data pointer, using far
Data registers, coprocessor (figure)
Data segments
defining
developing programs with
initializing
registers
Data-definition directives
Data-manipulation instructions
DataSize equate
DB directive
.DBG files
DD directive
Debug expression operators
Debug flags
Debugging
commands
local variables
DEC instruction
Decimal conversion example
Decimal, packed BCD numbers
Decimal radix
Declaring
far pointers
strings
Decrementing
Defaults
file extension
QCL driver
radix
segment names
segment registers
simplified segment
stack size
types
Defining symbols from command line
Dereferencing, pointer
Destination operand
Destination string
DGROUP group name
COMM directive, with
DOSSEG, with
simplified segments, with
DH register
DI register
DIF
Direction flag
Directives
.186
.286
.287
.8086
.8087
ALIGN
.ALPHA
ASSUME
CATSTR
.CODE
COMM
COMMENT
.CONST
.DATA
.DATA?
data definition (list)
data (list)
DB
DD
defined
DOSSEG
DQ
DT
DW
ELSE
ELSEIF
EQU
equal sign (=)
.ERR
.ERR1
.ERR2
.ERRB
.ERRDEF
.ERRDIF
.ERRE
.ERRIDN
.ERRNB
.ERRNDEF
.ERRNZ
EVEN
EXITM
EXTRN
.FARDATA
.FARDATA?
full segment
global
GROUP
IF
IF1
IF2
IFB
IFDEF
IFDIF
IFE
IFIDN
IFNB
IFNDEF
INCLUDE
INCLUDELIB
INSTR
instruction set
IRP
IRPC
LABEL
.LALL
.LFCOND
.LIST
LOCAL
MACRO
.MODEL
.MSFLOAT
NAME
on-line help
ORG
%OUT
PAGE
PROC
PUBLIC
PURGE
.RADIX
RECORD
REPT
.SALL
SEGMENT
.SEQ
.SFCOND
simplified segment
SIZESTR
.STACK
.STARTUP
string-manipulation (list)
STRUC
SUBSTR
SUBTTL
.TFCOND
TITLE
.XALL
.XLIST
Directives
Displacement
Display dialog box (figure)
Display mode
DIV instruction
Divide overflow interrupt
Dividing
by constants
integers
DL register
DM
Document conventions
Documentation feedback card
$ (dollar sign)
location counter symbol
symbol names, used in
Dollar sign ($)
location counter symbol
symbol names, used in
DOS
returning to
version requirements
DOS functions
calling with interrupts
Exit, registers used (list)
on-line help
segment-order convention
Write, registers used (list)
/DOSSEG linker option
DOSSEG directive
DP
DQ directive
DS
DS register
/Dsymbol option
DT directive
Dummy parameters
macros
repeat blocks
Dummy segment definitions
DUP operator
DW directive
DW memory operator
DWORD type specifier
DX register
Dynamic variables
E
Effective address
Elements, array
ELSE directive
ELSEIF directives
Emulator, coprocessor
Encoded real numbers
END directive
ENDIF directive
ENDM directive
ENDP directive
ENDS directive
ENTER instruction
Environment variable, INCLUDE
EQ operator
EQU directive
= (equal sign), directive
Equal sign (=), directive
Equates
defined
nonredefinable
predefined. See predefined equates
redefinable
string
.ERR directive
.ERR1 directive
.ERR2 directive
.ERRB directive
.ERRDEF directive
.ERRDIF directive
.ERRE directive
.ERRIDN directive
.ERRNB directive
.ERRNDEF directive
.ERRNZ directive
Error lines, displaying
ES register
ESC instruction
EVEN directive
! (exclamation point), operator
Exclamation point (!), operator
Execution, tracing
Exit function, DOS
Exiting a program
EXITM directive
Exponent, part of real-number constant
Exponentiation, with 8087-family coprocessors
Expression operator (%)
Expressions
in Debug commands
defined
External names
External symbols
Extra segment
EXTRN directive
/Ez option
F
F2XM1 instruction
FABS instruction
FADD instruction
FADDP instruction
False conditionals, listing
Far data pointers
decimal conversion with
loading
FAR type specifier
.FARDATA? directive
.FARDATA directive
Fardata equate
Fardata? equate
farStack
farStack keyword
Fatal errors
FBLD instruction
FBSTP instruction
FCHS instruction
FCOM instruction
FCOMP instruction
FCOMPP instruction
FDIV instruction
FDIVP instruction
FDIVR instruction
FDIVRP instruction
FIADD instruction
FICOM instruction
FICOMP instruction
FIDIV instruction
FIDIVR instruction
Fields
assembler statements
bit
records
structures
File extensions, default
File menu, defaults
Filename equate
Files
.COM
.DBG
include
listing
specifications
FIMUL instruction
Finishing execution
FINIT instruction
First-in-first-out (FIFO)
FIST instruction
FISTP instruction
FISUB instruction
FISUBR instruction
/Fl option
Flags
8086-family processors (figure)
altering within environment
build
control, settings after compare or test (table)
coprocessor, processor control (figure)
loading and storing
register, summary (table)
FLD instruction
FLD1 instruction
FLDCW instruction
FLDL2E instruction
FLDL2T instruction
FLDLG2 instruction
FLDLN2 instruction
FLDPI instruction
FLDZ instruction
Floating-point numbers
FMUL instruction
FMULP instruction
For loops, emulating high-level-language statement
FORTRAN
compiler
do loops, emulating
nestinglevel
return value (figure)
Forward references
defined
during a pass
labels
variables
FPATAN instruction
/FPi option
FPREM instruction
FPTAN instruction
Fraction
Framepointer
FRNDINT instruction
FSCALE instruction
FSQRT instruction
FST instruction
FSTCW instruction
FSTP instruction
FSTSW instruction
FSUB instruction
FSUBP instruction
FSUBR instruction
FSUBRP instruction
FTST instruction
Full segment definitions
Function return values
FXAM instruction
FXCH instruction
FXTRACT instruction
FYL2X instruction
FYL2XP1 instruction
G
GE operator
General-purpose registers
Global directives
defined
illustrated
Global flags
Global scope
Global symbols
GROUP directive
Group-relative segments
Groups
assembly listing
defined
illustrated
size restriction
GT operator
H
Hardware interrupts
Help menu
Help on DOS and BIOS functions
Help topics
Hexadecimal conversion example
Hexadecimal radix
in Debug expressions
specifier
HIGH operator
High-level languages
interfacing with
memory model
HLT instruction
Huge memory model
I
/I option
IDIV instruction
IEEE format
If blocks, run-time
IF directives
IF1 directive
IF2 directive
IFB directive
IFDEF directive
IFDIF directive
IFE directive
IFIDN directive
IFNB directive
IFNDEF directive
Immediate operands
Implied operands
IMUL instruction
IN instruction
INC instruction
INCLUDE directive
INCLUDE environment variable
Include files
assembly listings
using
View menu command
INCLUDELIB directive
Incrementing
Indeterminate operand
Index checking
Index, Help menu selection
Index operator
Index registers
Indexed operands
Indirect addressing modes (table)
Indirection, pointer
Initializing
segment registers
variables
INS instruction
INSTR directive
Instruction-pointer register (IP)
Instructions
AAA
AAD
AAM
AAS
ADC
ADD
addition (list)
AND
bit test
BOUND
CALL
CBW
CLC
CLD
CLI
CMP
CMPS
compare
conditional-jump
control-flow
CWD
DAA
DAS
data-manipulation
DEC
defined
DIV
ESC
F2XM1
FABS
FADD
FADDP
FBLD
FBSTP
FCHS
FCOM
FCOMP
FCOMPP
FDIV
FDIVP
FDIVR
FDIVRP
FIADD
FICOM
FICOMP
FIDIV
FIDIVR
FILD
FIMUL
FINIT
FIST
FISTP
FISUB
FISUBR
FLD
FLD1
FLDCW
FLDL2E
FLDL2T
FLDLG2
FLDLN2
FLDPI
FLDZ
FMUL
FMULP
FPATAN
FPREM
FPTAN
FRNDINT
FSCALE
FSQRT
FST
FSTCW
FSTP
FSTSW
FSUB
FSUBP
FSUBR
FSUBRP
FTST
FXAM
FXCH
FXTRACT
FYL2X
FYL2XP1
HLT
IDIV
IMUL
IN
INC
INS
INT
INTO
IRET
JC
Jcondition
JCXZ
JMP
LAHF
LDS
LEA
LEAVE
LES
LOCK
LODS
logical
LOOP
LOOPNE
LOOPNZ
MOV
MOVS
MUL
multiplication (list)
NEG
NOP
normal division (list)
normal subtraction (list)
NOT
on-line help
OR
OUT
OUTS
POP
POPA
POPF
program-flow
PUSH
PUSHA
PUSHF
REP
REPE
REPNE
REPNZ
REPZ
RET
RETF
RETN
reversed division (list)
reversed subtraction (list)
SAHF
SBB
SCAS
STD
STI
STOS
SUB
TEST
timing of
WAIT
XCHG
XLAT
XOR
Instructions
instructions
AND
LDS
LES
SHL
Instruction-set directives
INT instruction
Integer formats (figure)
Integers
Interrupt-enable flag
Interrupts
defined
operation of (figure)
using
INTO instruction
IP register
IRET instruction
IRP directive
IRPC directive
J
JC instruction
Jcondition instruction
JCXZ instruction
JMP instruction
JO instruction
Jump tables
Jumping conditionally
K
Keywords, on-line help for
L
/l option
LABEL directive
Labels
macros, in
near-code
procedures
LAHF instruction
.LALL directive
Language type
COMM directive
EXTRN directive
.MODEL directive
PROC statement
PUBLIC directive
Large memory model
LDS instruction
LE operator
LEA instruction
Learning assembly language
LEAVE instruction
LENGTH operator
LES instruction
.LFCOND directive
Line-continuation character
.LIST directive
Listing
controlling contents of
false conditionals
format
addresses
described
EQU directive
errors
groups
include files
LOCK directive
macro expansions
macros
Pass 1, reading
records
REP directive
segment override
segments
structures
symbols
macros
subtitles in
suppressing output
symbols and abbreviations in (table)
Listing files
creating
editor-oriented
example
index to source code
macro expansion
Pass 1
setting title
suppressing tables
View menu
viewing
Literal-character operator (!)
Literal-text operator (\la)
Loading
constants to coprocessor
coprocessor data
far pointers
values from strings
LOCAL directive
declaring stack variables
symbols declared with
using
Local symbols
defined
in macros
Local variables
in procedures
on stack (figure)
Location counter ($)
LOCK directive, assembly listing
LOCK instruction
LODS instruction
Logarithms
Logical bit operations (table of values)
Logical instructions
Logical operators
vs. logical instructions
(table)
LOOP instruction
Looping
overview
without use of CX
LOOPNE instruction
LOOPNZ instruction
LOW operator
LT operator
M
Machine code
Macro comment operator (\sc\sc)
MACRO directive
Macro expansions, assembly listings
Macros
argument testing
arguments
assembly listing
calling
compared to procedures
defined
efficiency penalty
exiting early
expansions in listing
local symbols
nested
operators
parameters
recursive
redefining
removing from memory
string-manipulation directives (list)
text
viewing listing of
Make dialog box (figure)
MASK operator
Masking bits
Masking out a bit
Masks, adjusting
Math coprocessors
Medium memory model
Memory access, coordinating
MEMORY combine type
Memory models
assembly procedure with
default segments, types (table)
described (list)
Memory operands
coprocessor
defined
Memory requirements
Memory-model-independent procedures
Messages
to screen
suppressing
Microsoft Binary format
Microsoft Binary Real format
Microsoft segment model
Mixed-language interface
C
entry sequences
exit sequences
local data
register considerations
return value
Mixed-language programs
building
C and assembler
program list (figure)
.MODEL directive
Model equate
Modular programming
Modulo division
MOV instruction
MOVS instruction
.MSFLOAT directive
MUL instruction
Multiple modules
Multiplying
by 16
by constants
instructions
Multiword values, shifting
N
NAME directive
Names
assigning
external
public
reserved
Naming convention
NE operator
Near pointers
Near reference parameters, assembly
NEAR type specifier
nearStack
nearStack keyword
NEG instruction
Negating
Nesting
conditional
DUP operators
include files
macros
procedures for Pascal
segments
Nonredefinable equates
NOP instruction
NOT instruction
NOT operator
No-wait coprocessor instructions
Null class type
Null string
O
Object records
Octal radix
OFFSET operator
with group-relative segments
with .MODEL directive
overview
ON GOSUB, emulating BASIC statement
One-pass assembly option
Operands
based
based indexed
classical stack
coprocessor
defined
destination
direct memory
immediate
implied
indeterminate
indexed
indirect memory
location counter
memory
record field
records
register
register indirect
relocatable
source
strong typing
structures
types (list)
undefined
Operators
AND
arithmetic
bitwise
calculation
defined
DUP
EQ
expression (%)
GE
GT
HIGH
index
LE
LENGTH
literal character (!)
literal text
logical (table)
LOW
LT
macro comment (\sc\sc)
macro (list)
MASK
NE
NOT
OFFSET
OR
precedence (table)
PTR
relational (table)
SEG
segment override (:). See
(segment-override operator)
shift
SHL
SHORT
SHR
SIZE
structure-field name
substitute (&)
THIS
TYPE
.TYPE
WIDTH
XOR
Options
/a
/AT
/Cl
/Cu
/Cx
/DOSSEG linker
/Dsymbol
/Ez
/Fl
/FPi
/I
/l
/P1
/s
/Sa
/Sd
/Se
setting inside environment
/Sn
/Sq
summary
/Sx
/t
/v
/W
/w
Options menu
OR instruction
OR operator
ORG directive
%OUT directive
OUT instruction
Output messages to screen
OUTS instruction
Overflow flag
Overflow interrupt
P
/P1 option
Packed BCD numbers
Packed decimal integers
Packed decimal numbers
PAGE align type
Page breaks in assembly listings
PAGE directive
Page format, in listings
PARA align type
Parameter list, in PROC statement
Parameters
assembly, accessing from
defining in procedures
macros
repeat blocks
types, common (list)
Parity flag
Partial remainder
Pascal
case statements, emulating
compiler
for loops
nestinglevel
repeat loops, emulating
return value (figure)
Pass 1 listing
Passing by
near reference, assembly
value
assembly
C
% (percent sign), expression operator
Percent sign (%), expression operator
. (period)
Period (.)
Phase errors
Pi, loading to coprocessor
Plus sign (+), to separate registers
Pointer indirection
Pointer registers
Pointers
defining
loading
POP instruction
POPA instruction
POPF instruction
Ports
defined
getting strings from
sending strings to
Precedence of operators
Predefined equates
CodeSize
Cpu
CurSeg
DataSize
FileName
Model
segment
Version
WordSize
Preserving register values
PROC directive
PROC type specifier
Procedure arguments, on stack (figure)
Procedures
compared to macros
defining labels
using
Processor directives
Product assistance report
Program list (figure)
Program-flow instructions
PTR operator
declaring parameters with
declaring pointers with
syntax
used with data types
PUBLIC combine type
PUBLIC directive
Public names
Public symbols
PURGE directive
PUSH instruction
PUSHA instruction
PUSHF instruction
Q
QC environment
building programs
debugging commands
described
on-line help
starting
QC register variables
QCL driver
introduction
options (list)
? (question mark)
Question mark (?)
Quick Advisor
QuickAssembler
assembly interfaces, writing
environment
See QC environment
QuickBASIC compiler
QuickC, interfacing with
QWORD type specifier
R
.RADIX directive
Radixes
binary
default
specifiers (table)
Real numbers
arithmetic calculations
designator (R)
directives for defining (list)
encoding
format
transfer instructions (list)
RECORD directive
Record operands
compared to variables (figure)
using
Record type
contents (figure)
declaring
Record variables
compared to operands (figure)
contents (figure)
defining
Records
assembly listing
declarations
defining
field operands
fields
initializing
MASK operator
object
WIDTH operator
Recursive macros
Redefinable equates
Redefining
interrupts
macros
Register stacks
classical-stack form (figure)
data transfer (figure)
memory form (figure)
register form (figure)
register-pop form (figure)
Register variables, in C
Registers
accumulator
AH
AL
altering within environment
AX
BH
BL
BP
BX
CH
CL
coprocessor
CS
CX
defined
DH
DI
DL
DS
DX
ES
flags
general purpose
index
IP
operands
operands, coprocessor
pointer
preserving value of
register-pop operands, coprocessor
segment
setting to zero
SI
SP
SS
strategy for using
types of
uses of
watching contents of
Registers window
Relational operators (table)
REP directive, assembly listing
REP instruction
REPE instruction
Repeat blocks
arguments
defined
parameters
repeat for each argument
repeat for each character of string
repeat for specified count
Repeating
instructions, execution of
using 8086-family string functions
REPNE instruction
REPNZ instruction
Reporting problems
REPT directive
REPZ instruction
Reserved names
RET instruction
RETF instruction
RETN instruction
Return value, offset (figure)
Rotating bits (figure)
S
/s option
/Sa option
SAHF instruction
.SALL directive
SBB instruction
Scaling by powers of two
Scaling factor
SCAS instruction
Screen swapping
\sc\sc (semicolons), operator
/Sd option
/Se option
Search paths, include files
Searching strings
Sections in assembly listings
SEG operator
SEGMENT directive
Segment register
Segmented addressing
Segment-order method
(Segment-override operator)
definition
OFFSET operator, with
string instructions, with
XLAT instructions, with
(segment-override operator)
used with ES
Segments
absolute
align type
align type (figure)
assembly listing
combine type
(figure)
(list)
defined
extra
group-relative offset
groups
defining
structure (figure)
MEMORY
nesting
ordering
override, assembly listings
override operator (:). See
(segment-override operator)
registers
types
Semicolons (\sc\sc), operator
.SEQ directive
Serious warnings
Severe errors
.SFCOND directive
Shift operators
Shifting
bits
multiword values
SHL instruction
SHL operator
SHORT operator
SHR operator
SI register
Sign flag
Signed numbers
Simplified segment defaults
SIZE operator
SIZESTR directive
Small memory model
defining attributes
described
setting up procedures
Smart help
/Sn option
Source files, include
Source modules
Source operand
Source string
SP register
Specifying calling convention
/Sq option
Square root
SS register
.STACK directive
Stack
allocating
defined
frame
local variables on (figure)
near and far types
operands, coprocessor
procedure arguments on (figure)
registers
segment
status, after pushes and pops (figure)
trace. See Calls command
type
use of
variables
STACK combine type
Stand-alone programs
.STARTUP directive
Statement fields
Statistics
STD instruction
Step Over command
STI instruction
STOS instruction
String directives (list)
Strings
comparing
constants
declaring
defined
destination strings
equates
filling
instructions, requirements for (table)
loading values from
moving
null
ports, transfer from and to
searching
source
structures, in
variables
Strong typing
STRUC directive
Structure type
Structure-field-name operator
Structures
assembly listing
declarations
definitions
fields
initializing
operands
overview
variables
SUB instruction
Substitute operator (&)
SUBSTR directive
Substring directive
Subtitles in listings
Subtracting values
SUBTTL directive
/Sx option
Symbols
assembly listing
communal
defined
defining from command line
external
global
location counter
public
relocatable operands
scope
SYMDEB
System requirements
T
/t option
TBYTE type specifier
Temporary real format (figure)
TER
Terminating execution
TEST instruction
Text macros
.TFCOND directive
THIS operator
/TINY linker option
Tiny memory model
Tiny model option
TITLE directive
Trace Into command
Tracing execution
Transcendental calculations
Transferring
BCD integers
binary integers
real numbers
Trap flag
Trigonometric functions
Tutorial books, assembly language
Type
ABS
align
class
combine
null class
operand matching
operators, described
PROC
record
structure
TYPE operator
Type specifiers (list)
.TYPE operator
U
Undefined operand
Underscore (_)
Unpacked BCD numbers
Unsigned numbers
Updates
USES, in PROC statement
V
/v option
Value parameters, C
Variables
automatic
communal
defined
dynamic
external
floating point
initializing
integer
local
public
real number
record
string
structure
watching value of
Version equate
View menu Include command
W
/W option
/w option
WAIT instruction
Warning levels
Watch Value command
Watch Value dialog box (figure)
Watchpoint command
Weak typing in other assemblers
While, emulating high-level-language statement
WIDTH operator
Width, structures
WO memory operator
WORD align type
WORD PTR, in example
WORD type specifier
WordSize equate
Write function, DOS
X
.XALL directive
XCHG instruction
XENIX compatibility
pathnames, with / (forward slash)
/sI
XLAT instruction
.XLIST directive
XOR instruction
XOR operator
Z
Zero flag