D
The Windows Command Line Interpreter

Microsoft’s MASM is (mostly) a tool that you use from the Windows command line. Therefore, to use MASM properly (at least with respect to all the examples in this book), you will need to be comfortable using the Windows command line interpreter (CLI).

Appendix C shows how to set up the Windows CLI so you can use it. This appendix briefly describes some common commands you will use in the CLI.

D.1 Command Line Syntax

A basic Windows CLI command takes the form

command options 

where command is either a built-in CLI command, an executable program on disk (typically having an .exe filename suffix), or a batch filename (with a .bat suffix), and options is a list of zero or more options for the command. The options are command-specific.

Probably the most common example in this book of an executable program you would run from the command line is the ml64.exe program (the MASM assembler). The Microsoft linker (link.exe), librarian (lib.exe), nmake (nmake.exe), and the MSVC compiler (cl.exe) are also examples of executable programs you might run from the command line.

All of the sample programs appearing in this book are also examples of commands you could run from the command line. For example, the following command executes the build.bat batch file to build the listing2-1.exe executable file (from Chapter 2):

build listing2-1

Immediately after building the listing2-1.exe executable file, you can run it from the command line. Here’s the command and the output it produces:

C:\>listing2-1
Calling Listing 2-1:
i=1, converted to hex=1
j=123, converted to hex=7b
k=456789, converted to hex=6f855
Listing 2-1 terminated

The listing2-1.exe executable file doesn’t support any command line options. If you type anything after the listing2-1 command on the command line, the listing2-1.exe program will ignore that text.

Although most options are command-specific, you can apply certain command line options to most programs you run from the command line: specifically, I/O redirection. Many console applications write data to the standard output device (the console window). All of the print and printf function calls appearing throughout this book, for example, write their data to the standard output device. Normally, all output sent to the standard output device appears as text written to the command line (console) window.

However, you can tell Windows to send this data to a file (or even another device) by using an output redirection option. The output redirection option takes the form

command options >filename more_options

where command is the command name, options and more_options are zero or more command line options (not containing an output redirection option), and filename is the name of the file where you would like to have the output from command sent. Consider the following command line:

listing2-1 >listing2-1.txt

Executing this command produces no output to the display. However, you will discover that this command creates a new text file on the disk. That text file will contain the output from the listing2-1.exe program (given earlier).

The Windows CLI also supports standard input redirection using the syntax

command options <filename more_options

where command is the command name, options and more_options are zero or more command line options (not containing an input redirection option), and filename is the name of the file from which command will read its input.

Input redirection causes a program that would normally read data from the user (at the keyboard, which is the standard input device) to instead read the data from a text file. For example, suppose you executed the listing2-1 command given earlier and redirected the output to the listing2-1.txt output file. Consider the following command (from Chapter 1) that reads a line of text from the user (in this particular example, I typed hello in response to the program’s request for input):

C:\>build listing1-8
C:\>echo off
 Assembling: listing1-8.asm
c.cpp
C:\>listing1-8
Calling Listing 1-8:
Enter a string: hello
User entered: 'hello'
Listing 1-8 terminated

Now consider the following command:

C:\>listing1-8 <listing2-1.txt
Calling Listing 1-8:
Enter a string: User entered: 'Calling Listing 2-1:'
Listing 1-8 terminated

In this example, the input is redirected from the listing2-1.txt file produced by the earlier execution of listing2-1.exe. The listing1-8.exe program reads the first line of that file as input (rather than reading a line of text from the keyboard). The program doesn’t echo the text read from the file (including the newline character); this is why the User entered: 'Calling Listing 2-1:' text appears on the same line as the Enter a string: prompt. When actually reading data from the keyboard, the system echoes the data to the display (including the newline character). This doesn’t happen when redirecting the input from a file.

The file contains several lines of text. However, listing1-8.exe reads only one line of text, so it ignores the remaining lines in the listing2-1.txt file.

You can redirect both the standard input and the standard output on the same command. Consider the following:

C:\>listing1-8 <listing2-1.txt >listing1-8.txt

This reads the data from the listing2-1.txt file and sends all the output to the listing1-8.txt file.

When redirecting the output from a program to a text file, if the output file already exists, Windows will delete that file prior to writing the standard output text to that file. You can also instruct Windows to append the output from the command to the existing file by using the following output redirection syntax (using two greater-than symbols):

command options >>filename more_options

Command line options other than the redirection options are usually filenames (for example, ml64 mySource.asm) or options that control the command’s behavior (such as ml64’s /c or /Fl command line options you’ll find used throughout this book). By convention, most Windows CLI commands use a slash character (/) as a prefix before actual options (as opposed to filenames). This is a convention, not a hard requirement.

Some commands, for example, use the Unix convention of a dash or hyphen character (-) instead of (or in addition to) the slash character. It’s really an application-specific choice. See the documentation for the particular program you are using for the details. All the built-in CLI commands, and most Microsoft CLI programs, use the slash character to designate options.

D.2 Directory Names and Drive Letters

Many commands accept or require a file or directory pathname as a command line option. Pathnames consist of two major components: a drive letter and the directory or file pathname. A drive letter is a single alphabetic character (A to Z) followed by a colon; for example:

A: B: C: etc.

Drive letters are not case-sensitive. A: is equivalent to a: on the command line. Windows reserves drive letters A: and B: for floppy drives. As you don’t often see floppy disk drives on modern machines, you won’t likely use these drive letters. However, if you have a really old machine . . .

C: is the default drive letter for the boot drive. If you have only one hard drive (or SSD) in your machine, Windows will probably associate C: with that drive. The examples appearing throughout this book assume you’re operating on drive C: (though this is by no means a requirement).

If you have multiple drives (either multiple physical drive units, or you’ve partitioned your hard drive into multiple logical drives), Windows usually associates consecutive drive letters (D:, E:, and so forth) with these additional drives. You can reassign drive letters, if you like, so there is no guarantee that all drive letters will be contiguous in the alphabet.

You can switch the default drive letter by typing the letter and a colon, by themselves, on the command line. For example,

D:

switches the default drive to D:, assuming such a drive exists. If the drive does not exist, Windows will complain that the system cannot find the specified drive and will not change the default drive.

Normally (you can change this), Windows displays the current drive letter as part of the command line prompt (by default, it displays the default pathname as well). For example, a typical Windows command line prompt looks like this:

C:\>

The \ character appearing in the command prompt is the current (default) directory. In this case, \ by itself indicates the root (or main) directory on the C: drive. Had the current directory been something else, Windows would have listed that after the drive letter. For example, had the current directory been \WINDOWS, the CLI would have displayed the following as the command line prompt:

C:\WINDOWS>

Windows, as you’re probably aware, has a hierarchical filesystem, allowing subdirectories inside (sub)directories. The backslash character separates directory names in a full pathname. You’ll commonly see two pathname forms in Windows: full pathnames and partial pathnames.

Full pathnames begin with a backslash (\) character and start from the root directory. Partial pathnames do not begin with a backslash, and the path begins with the current (default) directory (the first subdirectory in the partial pathname must appear in the current default subdirectory).

Spaces normally separate options on a command line. If a space appears in a pathname, you must surround the entire pathname with quotes; for example:

"\This\Path name\has\a\space"

The CLI supports a pair of wildcard characters in pathnames. The asterisk character (*) will match zero or more characters. The question mark character (?) will match zero or one character.

A command must explicitly support wildcard characters; the Windows CLI commands support wildcard options, as do most Microsoft tools (for example, ml64.exe). Not all executable files support wildcards in filenames, however. Wildcard characters are usable in directory names as well as filenames. They will not, however, replace the backslash character (\) in a pathname.

D.3 Some Useful Built-in Commands

The Windows CLI contains many built-in commands (commands that are part of the cmd.exe program and don’t require a separate .exe or .bat file). There are far too many built-in commands to consider here (and you wouldn’t use most of them); therefore, this section presents just a handful of the most commonly used commands.

D.3.1 The cd and chdir Commands

The cd (change directory) command switches the default directory to the directory you specify as the command line option. Note that chdir is a synonym for cd. Its syntax is

cd directory_name

where directory_name is a full or partial pathname to the new directory. For example:

cd \masm32\examples

The cd command does not normally change the default drive letter, even if you specify it as part of the pathname. For example, if the current drive letter is D:, the following command will not directly change the default drive letter and pathname:

D:\>cd C:\masm32\examples
D:\>

Notice that the command prompt remains D:\> after the cd command. However, if you switch to the C: drive (using the C: command), Windows will set the default directory as per the previous command:

D:>C:
C:\masm32\examples>

As you can see, the default directory is associated with a drive letter (and each drive letter maintains its own default directory).

If you want to switch both the drive letter and the pathname with the cd command, just supply the /d option before the pathname:

D:\>cd /d C:\masm32\examples
C:\masm32\examples

Don’t forget that if a pathname contains spaces, you must enclose the pathname in quotes when using the cd command:

cd /d "C:\program files"

The following displays help information about the cd command:

cd /?

If you issue the cd command by itself (no command line arguments), this command displays the current (default) pathname.

D.3.2 The cls Command

The cls command clears the screen (at least, the command window). This is useful when you want to clear the screen prior to a compilation and want to see only the messages associated with that particular compilation when scrolling back through the command window.

D.3.3 The copy Command

The copy command copies one or more files to a different location. Typically, you use this command to make backup copies of a file in the current directory or to make a copy of a file into a different subdirectory. The syntax for this command is as follows:

copy source_filename destination_filename

This command duplicates the file specified by source_filename and names that duplicate destination_filename. Both names can be full or partial pathnames.

The copy command supports several command line options (in addition to the source and destination filenames). You probably won’t use those options very often. For more details, issue the following help command:

copy /?

D.3.4 The date Command

The date command, by itself, displays the current system date and prompts you to enter a new date (which will permanently set the system date—so be careful using this!). With a /t command line option, this command will only display the date and not ask you to change it. Here’s an example:

C:\>date /t
Sat 02/23/2019

As usual, date /? displays the help information for this command.

D.3.5 The del (erase) Command

The del command (erase is a synonym for del) will delete the file(s) you specify as the command line options. The syntax is

del options files_to_delete

where options is command line options beginning with a slash, and files_to_delete is a list of filenames (pathnames), separated by spaces or commas, to be deleted. This command accepts wildcard characters; for example, the following command deletes all the .obj files appearing in the current directory:

del *.obj

It goes without saying that you should be very careful when using this command, especially when using wildcard characters. For example, consider the following command (which is probably a typo):

del * .obj

This deletes all the files in the current directory and then attempts to delete a file named .obj (which won’t exist after this command has deleted all the files in the subdirectory).

Some useful command line options are associated with this command. Use the /? option to learn about them:

C:\>del /?

D.3.6 The dir Command

The dir (directory) command is one of the more useful CLI commands. It displays a directory listing (a list of files in a directory).

Without any command line options, this command displays all the files in the current directory. With a single drive letter (and colon) as the argument, this command displays all the files in the default directory on the specified drive. With a pathname that leads to a subdirectory, this command displays all the files in the specified directory. With a pathname that leads to a single filename, this command displays the directory information about that particular file.

As usual, this command supports several command line options beginning with the slash character. Use dir /? to get the help information for this command.

D.3.7 The more Command

The more command displays the text in a text file one screenful at a time. After displaying a screenful of text, it waits for the user to press enter or spacebar on the keyboard. Pressing spacebar advances the output another screenful of text; pressing enter advances the output by one line. Pressing Q terminates the program.

The more command expects one or more filenames on the command line as arguments. If you specify two or more files, more will display the output in order. The more command also allows several command line options. You can use the following command to learn about them:

more /?

D.3.8 The move Command

The move command moves a file from one location to another (possibly renaming the file while moving it). It is similar to copy, though move deletes the file from its original location after moving it. The basic syntax for this command is the following:

move original_file new_file

As usual, the /? command line option provides help for this command.

D.3.9 The ren and rename Commands

The ren command (rename is a synonym) changes the name of a file. The syntax is

ren original_filename new_filename

where (obviously) original_filename is the old filename you want to change and new_filename is the new name of the file you want to use. The new and old files must be in the same directory. Use the move command if you want to move the file to a new directory while renaming it.

D.3.10 The rd and rmdir Commands

The rd command (rmdir is a synonym) removes (deletes) a directory. The directory must be empty before using this command (though the /s option can override this). The basic syntax for this command is

rd directory_path

where directory_path is the path to the directory you wish to remove. Use the rd /? command to get help.

D.3.11 The time Command

With no arguments, the time command displays the current system time and prompts you to change it. With a /t command line argument, time simply displays the current time. Use /? to display help information for this command.

D.4 For More Information

This appendix has provided only the tiniest introduction to the Windows command line interpreter—just enough information to be able to effectively compile and run assembly language programs using MASM. The CLI supports many dozens of built-in commands (if not over a hundred). One place to learn about these commands is https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmd/.