Getting Started with MASM and Visual Studio

The book's example programs in Chapters 1-14 have been successfully tested in Windows
!" #$-bit %ista and the #$-bit version of Windows &' (n the other hand" many programs
in Chapters 1)-1& will not run in any *icrosoft (+ later than Windows ,-" because they
rely on direct access to hardware and system memory' .ou cannot directly run 1/-bit
applications in any /4-bit version of Windows'
Required Setup for 32-bit Applications
0irst" you must install %isual +tudio $111 and select the C22 language option' %+ $111
and %isual C22 $111 3xpress both include the current version of the *icrosoft
4ssembler' .ou can verify that the *icrosoft 4ssembler is installed by looking for the
file ml.exe in the \vc\bin folder of your %isual +tudio installation directory" such as
c:\Program iles\!icrosoft "isual Studio #$.x\vc\bin.
%sing "isual Studio &xpress' (ou must do t)e follo*ing in order to see t)e same
menu options as t)e users of "isual Studio professional: from t)e Tools menu+
select Settings+ and select Expert Settings'
Next: Install the Book's Example Programs
The latest copy of the book's link libraries and example programs have been copied to
the c:\,rvine folder'
Check that the following files are copied into the c:\,rvine directory5
ilename -escription
cmd'exe
+hortcut to the Windows command-line interpreter 6named
cmd'exe7
8raphWin'inc 9nclude file for writing Windows applications
9rvine1/'inc 9nclude file used with the 9rvine1/ link library 61/-bit applications7
9rvine1/'lib 1/-bit link function library used with this book
9rvine#$'inc 9nclude file used with the 9rvine#$ link library 6#$-bit applications7
:ink1/'exe 1/-bit linker
9rvine#$'lib #$-bit link function library used with this book
;ser#$'lib <asic 9=( link library
*acros'inc 9nclude file containing macros 6explained in Chapter 117
+mallWin'inc +mall-si>ed include file" used by 9rvine#$'inc
make1/'bat <atch file for building 1/-bit applications
%irtual?eys'inc ?eyboard code definitions file" used by 9rvine#$'inc
4 subdirectory named &xamples will contain all the example programs shown in the
book" as well as all the source code for the book's 1/- and #$-bit link libraries'
Setting up Visual Studio
.ou will only have to do these steps the first time you use %isual +tudio'
Add the Start Without Debugging ommand to the !e"ug menu
9t's very useful to run programs without having to debug them' To do that" you will want
to add a new command to the -ebug menu5 Start .it)out -ebugging' @ere's how to
do it5
1' 0rom the /ools" menu" select Customize'
$' +elect the Commands tab'
#' +elect !enu bar 6radio button7'
4' Click the Add Command button'
)' +elect Debug from the Categories list'
/' +elect Start Without Debugging in the right-hand list box'
&' Click the 01 button'
-' Click the 2lose button'
9n fact" you can use the same seAuence to customi>e any of the menus and toolbars in
%isual +tudio'
Set the #a" Si$e to %
+tart %isual +tudio" and select 0ptions from the /ools menu' +elect /ext &ditor"
+elect All 3anguages" and select /abs5
+et the Tab +i>e and 9ndent +i>e to )'
Building a Sample Assem"l& 'anguage Program
Bow you're ready to open and build your first proCect'
(pening a Pro)et
%isual +tudio and %isual +tudio 3xpress reAuire assembly language source files to belong
to a project" which is a kind of container' 4 proCect holds configuration information such
as the locations of the assembler" linker" and reAuired libraries' 4 proCect has its own
folder" and it holds the names and locations of all files belonging to it' We have created a
sample proCect folder in the c:\Irvine\cxamples\ch03 directory" and its name is Project'
Do the following steps" in order5
1' +tart %isual +tudio'
$' 0irst you will open an existing %isual +tudio proCect file' 9f you're using %isual
+tudio" select 0pen Pro4ectfrom the 0ile menu' (r" if you're using %isual +tudio
3xpress" select 0pen" and select Pro4ect5Solution.
#' Bavigate to the c:\,rvine\&xamples\c)$3 folder and open the file
named Pro4ect.sln'
4' 9n the Solution Explorer window" you will see the word !roCect' This is the name
of a %isual +tudio proCect'
)' Bext" you need to add a source code file named main.asm to the proCect' To do
that" right-click on Pro4ect" select Add" select &xisting ,tem" select main.asm"
and click the Add button to close the dialog window' 6.ou can use this seAuence
of commands in the future to add any asm file into a proCect'7
/' Bext" you will open the main'asm file for editing' Double-click the file
named main.asm to open it in the editing window' 6%isual +tudio users may see a
popup dialog asking for the encoding method used in the asm file' Cust click the
(? button to continue'7
Tip: 9f the Solution Explorer window is not visible" select Solution Explorer from
the View menu' 4lso" if you do not see main.asm in the +olution 3xplorer window" it
might be hidden behind another window' To bring it to the front" click the Solution
Explorer tab from the tabs shown along the bottom of the window'
.ou should see the following program in the editor window5
TITLE MASM Template (main.asm)
; Description:
;
; Revision date:
INCLDE Irvine!".inc
.data
m#Messa$e %&TE 'MASM pro$ram e(ample')*d+)*a+)*
.code
main ,R-C
call Clrscr
mov ed()-..SET m#Messa$e
call /riteStrin$
e(it
main END,
END main
:ater" we'll show you how to copy this program and use it as a starting point to write your
own programs'
Build the Program
Bext" you will build 6assemble and link7 the sample program' +elect 6uild Pro4ect from
the <uild menu' 9n the (utput window for %isual +tudio at the bottom of the screen" you
should see messages similar to the following" indicating the build progress5
01222222 %3ild started: ,ro4ect: ,ro4ect)
Con5i$3ration: De63$ /in!" 222222
01Assem6lin$...
01Assem6lin$: .7main.asm
01Lin8in$...
01Em6eddin$ mani5est...
01%3ild lo$ 9as saved at
'5ile:::$:7masm7,ro4ect;sample7De63$7%3ildLo$.+tm'
01,ro4ect 2 * error(s)) * 9arnin$(s)
<<<<<<<<<< %3ild: 0 s3cceeded) * 5ailed) * 3p2to2
date) * s8ipped <<<<<<<<<<
9f you do not see these messages" the proCect has probably not been modified since it was
last built' Bo problem--Cust select Rebuild Pro4ect from the <uild menu'
*un the Program
+elect Start *it)out -ebugging from the Debug menu' The following console window
should appear" although your window will be larger than the one shown here5
The E!ress any key to continue'''E message is automatically generated by %isual +tudio'
Congratulations" you have Cust run your first 4ssembly :anguage program'
!ress any key to close the Console window'
When you assembled and linked the proCect" a file named Pro4ect.exe was created
inside the proCect's FDebug folder' This is the file that executes when you run the
proCect' .ou can execute !roCect'exe by double-clicking its name inside Windows
3xplorer" but it will Cust flash on the screen and disappear' That is because Windows
3xplorer does not pause the display before closing the command window'
+reating New Pro)ets o, -our (wn
<efore long" you will want to create your own proCects' The easiest way to do this is to
copy the entirec:\,rvine\&xamples\Pro4ect7Sample folder to a new location' Copy it to
a folder in which you have read=write permissions' 69f you're working in a college
computer lab" a useful location is a portable ;+< drive' Then you can modify the
program" build" and run it again'
Step %: *unning the Sample Program in !e"ug
Mode
9n this step" you will set a breakpoint inside the sample program' Then you will use the
%isual C22 debugger to step through the program's execution one statement at a time'
1' *ake sure the 4+* source code file is open in the editor window'
$' To begin stepping through your program in Debug mode" press the 011 key'
#' 4 yellow arrow will appear next to the first program statement 6call Clrscr7'The
arrow indicates that the statement is next to be executed'
4' !ress the 011 key 6called Step Over7 to execute the current statement' Continue
pressing 011 until the program is about to execute the exit statement'
)' 4 small black window icon should appear on your Windows status bar' (pen it
and look at the contents of the Command window' .ou should see the words
E*4+* program exampleE in the window'
/' !ress 011 one more time to end the program'
*egisters
9f you want to display the C!; registers" do the following5 +tart debugging the program"
then select in!owsfrom the "e#u$ menu' +elect %e$isters from the drop-down list' The
bottom window will display the register contents' Gight click this window and check the
item &la$s to enable the display of conditional flags'
.ou can interrupt a debugging session at any time by selecting Stop "e#u$$in$ from the
Debug menu' .ou can do the same by clicking the blue sAuare button on the toolbar' To
remove a breakpoint from the program" click on the red dot so that it disappears'
Setting a BreakPoint
9f you set a breakpoint in a program" you can use the debugger to execute the program a
full speed 6more or less7 until it reaches the breakpoint' 4t that point" the debugger drops
into single-step mode'
1' Click the mouse along the border to the left of the call Write+tring statement' 4
large red dot should appear in the margin'
$' +elect +tart Debugging from the Debug menu' The program should run" and pause
on the line with the breakpoint" showing the same .ellow arrow as before'
#' !ress 011 until the program finishes'
.ou can remove a breakpoint by clicking its red dot with the mouse' Take a few minutes
to experiment with the Debug menu commands' +et more breakpoints and run the
program again' 0or the time being" you can use the 011 key to step through the program
in the same way the 011 key did'
Building and *unning (ther Programs
+uppose you want to run another example program" or possibly create your own program'
.ou can either edit and modify main'asm" or you can remove main'asm from the proCect
and insert some other 'asm file into the proCect'
To remove a program from a proCect without deleting the file" right-click its name
in the Solution Explorer win!ow' 9n the context menu" select &xclude from
Pro4ect' 9f you change your mind and decide to add it back to the proCect" right-
click in the same window" select Add+ select &xisting item+ and select the file you
want to add'
To remove a program from a proCect and delete the source code file" select the file
with the mouse and press the -el key' (r" you can right-click the file name and
select Remove.
Adding a .ile to a Pro)et
The easiest way to add an assembly language source file to an open proCect is to drag its
filename with the mouse from a Windows 3xplorer window onto the name of your
proCect in the +olution 3xplorer window' 4 reference to the file 6not a copy7 will be
inserted in your proCect's directory' Try this now5
1' Gemove the main'asm file from your proCect'
$' 4dd a reference to the file c5F9rvineF3xamplesFch1#F4dd+ub'asm to the proCect'
#' <uild and run the proCect'
@ere is what you should see in the Console window" except that only your 34 register
will have the same value as ours5
When you press a key" the console window will close'
+op&ing a soure ,ile
9f you want to make a copy of an existing file" use Windows 3xplorer to copy the file into
your proCect directory' Then" right-click the proCect name in +olution 3xplorer" select
4dd" select 3xisting 9tem" and select the filename'
6uilding #8-bit Applications 92)apters #:-#;<
(nly Chapters 14 through 1& reAuire you to build 1/-bit applications' 3xcept for a few
exceptions" which are noted in the book" your 1/-bit applications will run under the #$-bit
versions of Windows 6!" %ista" &7' <ut 1/-bit applications will not run directly in any
/4-bit version of Windows'
9f you plan to build 1/-bit applications" you need to add two new commands to the Tools
menu in %isual C22 3xpress 6or %isual +tudio7' To add a command" select &xternal
/ools from the Tools menu' The following dialog will appear" although many of the items
in your list on the left side will be missing5

Step /: +reate the Build /01"it ASM +ommand
Click the Add button and fill in the Title" Command" 4rguments" and 9nitial directory
fields as shown in the screen snapshot' 9f you click the buttons with arrows on the right
side of the 4rguments and 9nitial directory fields" a convenient list appears' .ou can
select an item without having to worry about spelling5
Click the Appl= button to save the command'

Step 2: +reate the *un /01"it ASM +ommand
Click the 4dd button again" and create a new command named Run #8-bit AS!5
Click the (? button to save the command and close the 3xternal Tools dialog'
#esting -our new /01Bit +ommands
To test your new 1/-bit commands" open the file named #8-bit.asm from the ch1# folder
in the book's example programs' +elect 6uild #8-bit AS! from the Tools menu' The
following command window should appear" showing the successful execution of the
assembler and linker" followed by a listing of all files related to this program5
!ress a key to close the window' Bext" you will run the program' +elect Run #8-bit
AS! from the Tools menu' The following window will appear" although the contents of
all registers except 34 will be different5
!ress a key to close the window'
.ou have completed the setup for building and running 1/-bit assembly language
programs'
Pro4ect Properties Settings
.ou might be interested to know more about how %isual C22 proCects are set up for
assembly language programs'
4ssuming that our sample proCect is still open" select Pro4ect Properties from the !roCect
menu' 3xpand the entry under 2onfiguration Properties' Then expand the entry
named !icrosoft !acro Assembler' This is what you should see5
Click the entry named >eneral under !icrosoft !acro Assembler ' Botice that
the ,nclude Pat)s option has been set to the c5F9rvine directory' This tells the assembler
where to find files having a filename extension of E'incE' @ere is a sample5
Bext" select the 3isting ile entry" also in the *icrosoft *acro 4ssembler group' Botice
that the 4ssembled Code :isting 0ile entry 6shown below7 has been assigned a macro
name 6starting with H7 that identifies the name of the source input file" with a file
extension of 'lst' +o" if your program were named main'asm" the listing file would be
named main'lst5
0ind the :inker entry under 2onfiguration Properties' +elect the ,nput entry" and notice
that two filenames have been added to the Additional -ependencies entry'
The user32.lib file is a standard *+-Windows file' The irvine32.lib file is the link
library file supplied with this book' There must be at least one space separating the file
names5
Bext" select 3in?er under Configuration !roperties" and then select >eneral'
The Additional 3ibrar= -irectories option eAuals c:\,rvine" so the linker can find the
9rvine#$'lib library file5
+elect 3in?er under the 2onfiguration Properties and select -ebugging' Botice that
the >enerate -ebug,nfo option is set to (es:
+elect S=stem under the 3in?er entry' Botice that the +ub+ystem option has been set
to 2onsole5
We use the Console setting because it is easy for assembly language programs to write
output to a text console 6Command7 window' This is the window you see when running
cmd'exe from the +tart I Gun menu in Windows'
Click the (? button to close the !roCect !roperty !ages window'
Generating a Soure 'isting .ile
(pen the proCect' 0rom the menu" select Pro4ect" select Pro4ect Properties' 9n the list
box" select !icrosoft !acro Assembler" then select 3isting ile' +et the Assembled
2ode 3isting file option to@9,nputAame<.lst'
MASM s&ntax highlighting
When a text editor uses syntax highlighting" language keywords" strings" and other
elements appear in different colors' %isual +tudio and %isual C22 3xpress can highlight
*4+* reserved words and strings" as shown in the following example5
This won't happen automatically" but you can create a syntax definition file named
;sertype'dat that contains *4+* keywords' Then when %isual +tudio 6or %isual C22
3xpress7 starts" it reads the syntax file and highlights *4+* keywords'
@ere are the reAuired steps to set up *4+* syntax highlighting in %isual +tudio or
%isual C22 3xpress5
17 Download the ;sertype'dat file to a folder in which you have read=write permissions'
9f you are using Windows %ista" download to *y Documents" or C5Ftemp" or any folder
that doesn't have security restrictions'
$7 Copy ;sertype'dat to the C5F!rogram 0ilesF*icrosoft %isual +tudio
xx'xFCommon&F9D3 folder' 9f you are using Windows %ista" it will display a verification
window before copying the file' 6ExxE may be ,'x or 11'x7
#7 (pen %isual +tudio or %isual C22 3xpress" select 0ptions from the Tools menu"
select /ext &ditor" and select ile &xtension' (n the right side of the dialog 6shown
below7" enter asm as the extension" select!icrosoft "isual 2BB from the 3ditor list" and
click the Add button' Click the 01 button to save your changes'
Close %isual +tudio and restart it' (pen your proCect and display an 4+* file' .ou should
see syntax highlighting in the editor'
Assembling+ 3in?ing+ and -ebugging *it) a
6atc) ile
*any people like to use a in!ows #atch 'ile to assemble and link programs' 4 batch file
is a text file containing a seAuence of commands that execute as if they had been typed at
the command prompt' 9n fact" they are powerful enough to contain variables" loops" 90
statements" and so on'
The easiest way to run a batch file is to first open a Command window and then type the
name of the batch file 6along with arguments7 at the command prompt' To open a
Command window" you must execute a program named cmd.exe' We will make that easy
for you'
Step #: Download a J9! file 6<atch+ample%+$1117 containing the following items5
A s)ortcut to cmd.exe+ which opens a Command window in the current directory
asm32.bat" a batch file for assembling and linking programs
main.asm" a sample assembly language program
Step 2: 3xtract the J9! file into the c5F9rvineF3xamples directory on your computer'
Step 3: Do the following5
Copy asm#$'bat to any directory on your system path' <y doing this" you make it
possible for *+-Windows to recogni>e asm32 as a valid command when typed at
the *+-Windows command prompt'69f you want to find out which directories are
on the current system path" type pat) and press 3nter at the system command
prompt'7
Double-click the shortcut to cmd.exe' 4 Command window should appear'
4t the command prompt in this window" type asm32 and press 3nter' This will
execute the asm#$ batch file and display help information'
T+is 5ile assem6les) lin8s) and de63$s a
sin$le assem6l# lan$3a$e
so3rce 5ile. %e5ore 3sin$ it) install
=is3al St3dio "*0* in t+e 5ollo9in$
director#:
C:7,ro$ram .iles7Microso5t =is3al
St3dio 0*.*
Ne(t) install t+e Irvine >t+ edition lin8
li6raires and incl3de
5iles in t+e 5ollo9in$ director#:
C:7Irvine
.inall#) cop# t+is 6atc+ 5ile to a
location on #o3r s#stem pat+.
/e recommend t+e 5ollo9in$ director#:
C:7,ro$ram .iles7Microso5t =is3al St3dio
0*.*7=C76in
Command2line s#nta(:
asm!" ?:@ A :+ A 2@ A 2+B 22 displa#
t+is +elp in5ormation
asm!" 5ilelist 22 assem6le and lin8 all
5iles
asm!" :D 5ilelist 22 assem6le) lin8) and
de63$
asm!" :C 5ilelist 22 assem6le onl#
C5ilelist1 is a list o5 3p to D 5ilenames
(9it+o3t e(tensions))
separated 6# spaces. T+e 5ilenames are
ass3med to re5er to 5iles
+avin$ .asm e(tensions. Command2line
s9itc+es are case2sensitive.
Type the following command to assemble and link a source file named main.asm5
asm!" main
.ou should see the following messages5
Assem6lin$: main.asm
T+e 5ile main.o64 9as prod3ced.
..................................
Lin8in$ main.o64 to t+e Irvine!") Eernel!") and
ser!" li6raries.
T+e 5ile main.e(e 9as prod3ced.
..................................
9n fact" several files were produced'
main'obC - the obCect file
main'ilk - incremental link status file
main'pdb - debug symbol file
.ou might get a linker error saying that it cannot find ?ernel#$'lib' This file is normally
installed as part of the Windows +D?" but you can get a copy here'6 kernel#$7 Copy this
file into your c5F9rvine folder'
9f there were syntax errors in your program" you would see error messages generated by
the assembler' @ere is an example5
Assem6lin$: main.asm
main.asm(F) : error A"**G: s#nta( error : m#Messa$e
main.asm(0D) : error A"**>: 3nde5ined s#m6ol : m#Messa$e
.ou would then open the main'asm file with a text editor 6such as Botepad7" fix the
errors" and run the asm#$ batch file again'
4lthough we used a file named main'asm in this example" the asm#$'bat batch
file will work for any assembly language file" regardless of the name' The only
reAuirement is that your assembly language source file have a .asm filename
extension'
Assem"ling Programs in (ther !iretories
Bo doubt" you will want to assemble programs in various different disk folders" not Cust
the batchKsample folder used in the foregoing example' 4ll you need to do is copy
the cmd.exe shortcut we gave you to your working directory" where your assembly
language source files are located' When you double-click to run the shortcut" it will open
a Command window in the current folder'
Assem"ling3 'inking3 and !e"ugging
9n addition to assembling and linking" you can use the asm#$'bat file to launch your
program in the %isual +tudio debugger' Try the following command5
asm!" :D main
9f the program assembles and links with no errors" your program should load in %isual
+tudio' The first time you do this with a new program" the source code will not appear'
4ll you have to do is press the #$ ?e= to begin debugging" and your program should
appear with a yellow band across the first executable line5
6Depending on how %isual +tudio is configured" you might have to press 0- to do the
same thing'7
0rom here" you can step through the program' When you get to the call to Write+tring"
you can even trace into its code by pressing the 011 key 6trace to7' When you finish" close
%isual +tudio'
0rom this time on" when you load the same program in the %isual +tudio debugger" your
source code will appear right away'
Assem"ling without 'inking
(ccasionally" you may want to assemble programs but not link them' This happens" for
example" when you are creating a multimodule proCect and you want to assemble each
asm file into an obC file separately before linking them into the final exe program' (r" you
might be assembling a module to be inserted into a link library 6like 9rvine#$'lib7'
To assemble a source file only" inser the =C option before the name of the file being
assembled5
asm!" :C main
.ou should see the following output5
Assem6lin$: main.asm
T+e 5ile main.o64 9as prod3ced.
..................................