Category : Utilities for DOS and Windows Machines
Archive   : JP4REF.ZIP
Filename : REFMAN.DOC

 
Output of file : REFMAN.DOC contained in archive : JP4REF.ZIP










4DOS (r)

4OS2 (tm)

4DOS for Windows NT




Reference Manual





Developed By
Rex Conn and Tom Rawson

Documentation By
Hardin Brothers, Tom Rawson, and Rex Conn





Published By

JP Software Inc.
P.O. Box 1470
East Arlington, MA 02174
U.S.A.

(617) 646-3975
fax (617) 646-0904





ACKNOWLEDGMENTS


We couldn't produce products like 4DOS, 4OS2, and 4DOS/NT
without the dedication and quality work of many people. Our
thanks to:

JP Software Staff: Mike Bessy, Helen Coyne, Ellen Stone,
Marcella Turner, Misty White.

Online Support: Brian Miller and Tess Heder of Channel 1
BBS; Don Watkins of CompuServe's IBMNET.

Beta Test Support: David Moskowitz, Guy Scharf, and
Martin Schiff, of CompuServe's CONSULT forum.

Beta Testers: We can't list all of our beta testers
here! A special thanks to all of you who helped make
4DOS, 4OS2, and 4DOS/NT elegant, reliable, and friendly.


The following tools are used in creating and maintaining 4DOS,
4OS2, and 4DOS/NT:

Compilers: Microsoft C, Microsoft Macro Assembler,
IBM C-Set/2, Borland Turbo Pascal
Libraries: Spontaneous Assembly (Base Two
Development), Turbo Professional (Turbo
Power Software)
Editors: Edix (Emerging Technology), Brief
(Solution Systems)
Debuggers: Periscope (The Periscope Company),
Soft-ICE (Nu-Mega Technologies)
Version Control: PVCS (Sage Software)
Documentation: Microsoft Word for Windows with Adobe
Type Manager


Program and Documentation Copyright c 1988 - 1993, JP Software
Inc., All Rights Reserved. 4DOS is a registered trademark and
4OS2, JP Software, and the JP Software logo and product logos
are trademarks of JP Software Inc. Other product and company
names are trademarks of their respective owners.

11-93B

CONTENTS
-------------------------------------------------------------------


CONTENTS

Introduction...............................................1
How to Use This Manual.................................2
Registration and Upgrade Information...................6
Technical Support......................................7

Chapter 1 / General Concepts..............................10
Operating Systems and Command Processors..............10
Primary and Secondary Shells......................12
Files and Directories.................................13
Drives and Volumes................................14
File Systems......................................14
Directories and Subdirectories....................15
File Names........................................16
File Attributes...................................18
Internal and External Commands........................18
Executable Files and File Searches....................20
The Environment.......................................21
ASCII and Key Codes...................................22
The Keyboard..........................................23
Video.................................................24
ANSI Drivers..........................................24

Chapter 2 / Conventions...................................26
Colors and Color Names................................26
Blinking Text and Bright Background Colors........27
Color-Coded Directories...............................30
Keys and Key Names....................................31

Chapter 3 / Using 4DOS, 4OS2, and 4DOS/NT.................33
At the Command Line...................................33
Command-Line Editing..............................34
Command History and Recall........................35
Local and Global Command History..................38
Command History Window............................39
Filename Completion...............................40
Filename Completion Window........................41
Directory Changes and CDPATH......................42
Directory History Window..........................43
Automatic Directory Changes.......................44
Multiple Commands.................................45
Temporarily Disabling Aliases.....................46
Command Line Help.................................46
Command-Line Length Limits........................47
Page and File Prompts.................................48
Critical Errors.......................................49
Input and Output......................................50

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / i

CONTENTS
-------------------------------------------------------------------

Redirection.......................................50
Piping............................................53
Keystack..........................................55
File Selection........................................56
Extended Parent Directory Names...................57
Wildcards.........................................57
Date, Time, and Size Ranges.......................60
Multiple Filenames................................64
Include Lists.....................................65
Executable Extensions.............................66
Advanced Features.....................................68
Conditional Commands..............................68
Command Grouping..................................69
Escape Character..................................71
4DOS, 4OS2, and 4DOS/NT Compatibility.................72

Chapter 4 / Aliases and Batch Files.......................74
Aliases...............................................74
Batch Files...........................................77
.BAT, .CMD, and .BTM Files........................77
Echoing...........................................78
Batch File Parameters.............................78
Batch File Commands...............................80
Interrupting a Batch File.........................82
Automatic Batch Files.............................82
Detecting 4DOS, 4OS2, or 4DOS/NT..................83
Using Aliases in Batch Files......................84
Debugging Batch Files.............................86
Batch File String Processing......................88
Batch File Compression............................90
REXX Support......................................92
EXTPROC Support...................................93
Using the Environment.................................94
Configuration Variables...........................96
Internal Variables................................97
Variable Functions...............................105
Command Parsing......................................116
Argument Quoting.................................118

Chapter 5 / Configuration................................120
Using the .INI File..................................120
.INI File Directives.................................121
Types of Directives..............................124
Initialization Directives........................125
Configuration Directives.........................130
Color Directives.................................135
Key Mapping Directives...........................136
Advanced Directives..............................141
Examples.........................................144

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / ii

CONTENTS
-------------------------------------------------------------------

Chapter 6 / Command Reference Guide......................146
Command Categories...................................147
How to Use the Command Descriptions..................148
?....................................................153
ACTIVATE.............................................154
ALIAS................................................155
ATTRIB...............................................167
BEEP.................................................169
BREAK................................................171
CALL.................................................173
CANCEL...............................................174
CD / CHDIR...........................................175
CDD..................................................177
CHCP.................................................178
CLS..................................................179
COLOR................................................180
COPY.................................................181
CTTY.................................................187
DATE.................................................188
DEL / ERASE..........................................189
DELAY................................................192
DESCRIBE.............................................193
DETACH...............................................195
DIR..................................................196
DIRS.................................................205
DO...................................................206
DPATH................................................209
DRAWBOX..............................................210
DRAWHLINE............................................212
DRAWVLINE............................................213
ECHO.................................................214
ECHOS................................................216
ENDLOCAL.............................................217
ESET.................................................218
EXCEPT...............................................220
EXIT.................................................222
FOR..................................................223
FREE.................................................228
GLOBAL...............................................229
GOSUB................................................231
GOTO.................................................232
HELP.................................................234
HISTORY..............................................235
IF...................................................238
IFF..................................................244
INKEY................................................247
INPUT................................................249
KEYBD................................................251
KEYS.................................................253

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / iii

CONTENTS
-------------------------------------------------------------------

KEYSTACK.............................................254
LH / LOADHIGH........................................257
LIST.................................................260
LOADBTM..............................................263
LOG..................................................264
MD / MKDIR...........................................266
MEMORY...............................................267
MOVE.................................................269
MSGBOX...............................................273
ON...................................................274
PATH.................................................276
PAUSE................................................279
POPD.................................................280
PROMPT...............................................281
PUSHD................................................285
QUIT.................................................287
RD / RMDIR...........................................288
REBOOT...............................................289
REM..................................................291
REN / RENAME.........................................292
RETURN...............................................295
SCREEN...............................................296
SCRPUT...............................................298
SELECT...............................................299
SET..................................................305
SETDOS...............................................308
SETLOCAL.............................................315
SHIFT................................................316
START................................................317
SWAPPING.............................................325
TEE..................................................326
TEXT.................................................328
TIME.................................................329
TIMER................................................330
TITLE................................................332
TRUENAME.............................................333
TYPE.................................................334
UNALIAS..............................................335
UNSET................................................336
VER..................................................338
VERIFY...............................................339
VOL..................................................340
VSCRPUT..............................................341
WINDOW...............................................343
Y....................................................344

Appendix A / Error Messages..............................345


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / iv

CONTENTS
-------------------------------------------------------------------

Appendix B / ASCII and Key Codes.........................357
Keys and Key Codes...................................361

Glossary.................................................368

Index....................................................380

Quick Reference..........................................394
Internal Variables...................................394
Variable Functions...................................395
.INI File Directives.................................396








































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / v

CONTACTING JP SOFTWARE
-------------------------------------------------------------------



CONTACTING JP SOFTWARE

You can contact JP Software at any of the following addresses. Our
normal business hours are 9:00 AM to 5:00 PM weekdays, eastern US
time. For more information about contacting us for technical
support, see page 7.


By mail:

JP Software Inc.
P.O. Box 1470
East Arlington, MA 02174
USA


By telephone / fax:

Voice: (617) 646-3975
Fax: (617) 646-0904
Order Line: (800) 368-8777 (orders only, USA only)


Electronically:

CompuServe: Customer Service 75020,244
Technical Support, GO JPSOFT or GO PCVENB
(section 10), User ID 75300,1215
Internet: Customer Service [email protected]
Technical Support
[email protected]
BBS Support: Via Channel 1 BBS, Boston, 617-354-5776 at
2,400 - 14,400 baud, no parity, 8 data
bits, 1 stop bit














-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / vi

INTRODUCTION
-------------------------------------------------------------------


INTRODUCTION


Welcome to our Reference Manual. We have designed this manual
to accompany three of our products: 4DOS, 4OS2, and 4DOS for
Windows NT.

Technically, each of these programs is a command interpreter
or "shell." That means that they respond to the commands you
type at the C:\> or [C:\] prompt. Each is designed to replace
the default command interpreter that was supplied with your
operating system:

4DOS replaces COMMAND.COM from DOS
4OS2 replaces CMD.EXE from OS/2
4DOS/NT replaces CMD.EXE from Windows NT

4DOS can also be used as the command interpreter for DOS
sessions running under OS/2, and under Windows 3.0 and above.

Each of our products is highly compatible with the command
interpreter that it replaces. That means that you don't have
to change your computing habits or unlearn anything to use any
of these products. Each also adds many new features and
commands to its operating environment. They make the
operating system friendlier, easier to use, and much more
powerful and versatile, without requiring you to learn a new
program, a new set of commands, or a new style of work.

Each product is shipped with this manual plus a smaller
Introduction and Installation Guide. Please start with the
smaller manual. It will tell you how to get started with the
product you purchased and also contains some other information
that applies specifically to that product.

Once you have installed 4DOS, 4OS2, or 4DOS for Windows NT,
you can learn its features at your own pace. Relax, enjoy the
power of your new program, and browse through both manuals
occasionally. Press the F1 key whenever you need help. The
program will soon become an essential part of your computer,
and you'll wonder how you ever got along without it.

If you are a new user and want to take your new program for a
spin without performing a complete installation, see the
Guided Tour pamphlet included with your copy of 4DOS, 4OS2, or
4DOS/NT.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 1

INTRODUCTION
-------------------------------------------------------------------

We are constantly working to improve these programs. If you
have suggestions for features or commands that you think we
should include in the next version, or any other way we could
improve our product, please let us know. Many of the
improvements in this version were suggested by our users, and
while we can't promise to include every suggested feature, we
really do appreciate and pay attention to your comments.


How to Use This Manual

This manual covers three separate products: 4DOS, 4OS2, and
4DOS for Windows NT. We have combined reference information
for the products in one manual because 4DOS, 4OS2, and 4DOS
for Windows NT offer almost exactly the same features and
commands, so individual manuals would be almost identical.
Many of our customers use more than one of these products;
they find that a single manual helps them understand the
similarities and differences of the three products. In
addition, printing a single manual reduces our costs and lets
us bring you the most powerful command interpreters available
for the lowest possible price.

Most of this manual describes commands and features which are
available in all three products. When we need to discuss the
features or behavior of a single product, we mention it
specifically in the text. When an entire paragraph or section
applies to a specific product, we use marginal text to
identify that product:

4DOS marks sections that apply only to 4DOS.

4OS2 marks sections that apply only to 4OS2.

4NT marks sections that apply only to 4DOS for Windows NT. For
brevity, we often refer to this product as "4DOS/NT", or by
the actual program name, "4NT", in this manual.

Occasionally, a feature will be marked with two of these
marginal notations when it applies to two different products.

We have designed this manual to serve as a gentle introduction
to our products for novice users and as a reference manual for
advanced users.

You will likely find some parts of the manual too simple or
too technical for your tastes. Unless you are convinced that
one of those sections holds just the information you need for
a specific task, feel free to skip to the next part of the

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 2

INTRODUCTION
-------------------------------------------------------------------

manual that is more to your liking. You can use almost every
feature of our products without having to worry about other
features or commands.

As you read the manual, you will occasionally see an
exclamation point [!] next to a paragraph. The exclamation
point means that that paragraph contains a caution or warning
you should observe when using the feature it discusses.

You will also see the symbol ## next to certain paragraphs.
This indicates an in-depth discussion or a more advanced topic
which you can skip if you wish to stick with the basics. Come
back to this topic later for more details, or if you're having
trouble with the particular issue it discusses. If you see
the ## next to a section heading, it means the entire section
contains such information.

You may find the information in such marked sections useful
even if you're relatively new to computers or to our products.
However, you can also skip the marked section and still
understand and use the basic topic of the larger section
you're reading.

This manual is divided into six chapters and two appendices,
plus a glossary and index. Here's a brief overview of what
you'll find in each:


Chapter 1 / General Concepts

This chapter is an introduction to several terms and
concepts that we use throughout the manual. If you're a
novice, you might want to browse through the entire
chapter. If you're a power user and all of the topics in
this chapter seem simple, then go on to the next chapter.
If you think you need to brush up a bit on the basics of
a couple of terms and ideas, you'll probably find them
here.


Chapter 2 / Conventions and Restrictions

This chapter contains information about three conventions
that are used throughout 4DOS, 4OS2, and 4DOS/NT: colors
and color names, color-coded directories, and keys and
key names. You'll find many references in the manual to
the information in this chapter. You may choose to read
through this chapter to see what is available, or refer


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 3

INTRODUCTION
-------------------------------------------------------------------

to the topics here when you come to a cross reference
later in the manual.


Chapter 3 / Using 4DOS, 4OS2, and 4DOS/NT

This chapter is for everyone. It contains a description
of 4DOS, 4OS2, and 4DOS/NT features, and lots of examples
to help you learn to use each one. Even if you are a
novice user and want to ignore some of these features
until later, skim through this chapter to get an idea of
what is available and where to find the information that
you will eventually want. Our products offer both
features which are not related to specific commands, and
a complete set of over 80 internal commands. This
chapter has complete reference information on most of the
non-command features. Reference information on commands
is in Chapter 6.


Chapter 4 / Aliases and Batch Files

This chapter introduces two of the most powerful features
in 4DOS, 4OS2, and 4DOS/NT: Aliases and Batch Files.
You can use both to automate much of your computing work.
Even if you are a novice user, you should skim through
this chapter to see what is available. This chapter also
contains information about using environment variables,
and the internal variables and variable functions that
make aliases and batch files extremely powerful and
flexible.


Chapter 5 / Configuration

This chapter is for advanced users who want to be sure
that 4DOS, 4OS2, or 4DOS/NT is running at top efficiency
on their systems. It includes detailed information on
setting up your command processor and on changing its
configuration.


Chapter 6 / Command Reference

Each of our products offers over 80 internal commands.
This chapter explains the purpose of each command and
tells you how to use it. It has examples that will help
you learn each command and the technical details you will
need to get the command to behave exactly as you wish.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 4

INTRODUCTION
-------------------------------------------------------------------

Appendices

We've included some helpful tables here, as well as
information for those who like to know technical details.
There are two appendices.

Appendix A lists all error messages. Look here if you
need an explanation of an error message, or if you aren't
sure if the message came from 4DOS, 4OS2, or 4DOS/NT.

Appendix B lists codes for the ASCII character set (your
computer's internal method for representing letters,
digits, and other characters) and for the keys on your
keyboard. These codes can be useful with certain
commands.


Glossary

If you need help with any of the terminology in this
manual, look here.


Index

If you can't find the information you need, this should
help you find it.


Quick Reference

This quick index will give you the page number for
detailed information on each internal variable, variable
funtion, and .INI file directive.


Additional Files

Files distributed with 4DOS, 4OS2, and 4DOS/NT cover
important additional information beyond what's included
in this manual. README.DOC contains general notes,
highlights of the latest release, and brief installation
instructions for those upgrading from a downloaded copy
of 4DOS, 4OS2, or 4DOS/NT. MANMOD.DOC covers changes or
corrections in the manual, if any, and UPDATxxx.DOC
contains detailed information for users with older
versions on what has changed in the latest release ("xxx"
is the version number). For 4DOS users we also include
APPNOTES.DOC, which contains application notes for a

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 5

INTRODUCTION
-------------------------------------------------------------------

variety of other software packages to help you use those
packages with 4DOS.


Registration and Upgrade Information

If you purchased 4DOS, 4OS2, or 4DOS/NT from a software
dealer, your copy came with a registration card. Please fill
out this card and return it promptly to JP Software. It
ensures that we have a record of your registration so that we
can give you ongoing technical support and notices of
upgrades. If you purchased 4DOS, 4OS2, or 4DOS/NT directly
from JP Software, you are already registered and no
registration card is necessary.

Once you are a registered user, you will receive:

* A subscription to The Prompt Solution, JP Software's
customer newsletter. The Prompt Solution includes
tips for using 4DOS, 4OS2, and 4DOS/NT; notification
of upgrades; and information about other products from
JP Software.

* Technical support via electronic mail, fax, mail, or
telephone.

* A downloadable upgrade to the next version of 4DOS;
see below for details.

4DOS, 4OS2, and 4DOS/NT are upgraded regularly through
maintenance releases, designed to fix minor problems or
improve compatibility, and major upgrades which contain
enhancements and additional features. Maintenance releases
are identified by a change in the hundredths digit of the
version number, for example from 5.0 to 5.01 or 5.02. Major
upgrades are identified by a change in the tenths digit or
"ones" digit, for example from 5.0 to 5.1 or 6.0.

Major upgrades can be purchased from JP Software or your
dealer for a modest charge. For most users the first major
upgrade released after your initial purchase is available at
no charge if you download it from one of our support areas
(see below). You can also download maintenance releases from
one of the support areas, or order them on disk at a nominal
cost.

As a registered user, you will automatically be notified when
a major upgrade is released. We don't send out notices when
maintenance releases become available, because you don't

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 6

INTRODUCTION
-------------------------------------------------------------------

usually need them unless you're having a problem. If you call
with a problem that's been addressed in a maintenance release,
we'll mail you a copy on disk or assist you in downloading it.

As a registered user, you can download maintenance releases
and your first major upgrade from the JP Software support area
on CompuServe (GO PCVENB, library 10), or Channel 1 (see
below). If you are familiar with the Internet, you can also
obtain JP Software files via anonymous ftp from the 4DOS
directory on simtel20 or any of its mirrors.

The file names used for updates vary from time to time
depending on the extent of the changes made, but typically
will look like 4DOS5*.ZIP, 4OS22*.ZIP, etc. The "*" refers to
one or more characters further identifying the file. .ZIP
files are "archives" which contain many other files within
them. The files stored inside the .ZIP file are compressed
for more efficient downloads. To decompress the .ZIP file and
gain access to the actual 4DOS, 4OS2, or 4DOS/NT files you
will need the PKUNZIP program or an equivalent. Such programs
are available from the same source as the .ZIP files
themselves. Check the directory listings and file
descriptions on the service you are using to identify the
files you need.

Downloads are also available from many other local bulletin
boards and online services. Lists of download locations,
including bulletin boards outside the USA, are published from
time to time in The Prompt Solution and are included in the
SUPPORT.BBS file that comes with each product.

We offer BBS support through Channel 1 in Boston, one of the
largest and best-run bulletin boards in the US. Channel 1 is
an independent bulletin board and is not owned or operated by
JP Software. To access Channel 1 set your modem to any speed
from 2,400 to 14,400 baud, no parity, 8 data bits, and 1 stop
bit, and dial 617-354-5776. Join conference 5 for 4DOS
downloads. You can leave support messages and download files
at no charge, but if you want to use any of Channel 1's other
excellent services you may need to purchase a membership to
have sufficient online time.


Technical Support

Technical support is available via public electronic support
conferences, private electronic mail, telephone, fax, and
mail. When you contact us for support please give us your


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 7

INTRODUCTION
-------------------------------------------------------------------

serial number so that we can verify your status as a customer,
keep track of your inquiry, and contact you if necessary.

Often the best way to contact us for support is in one of the
following public electronic support conferences. The numbers
in parentheses indicate the usual delay, in business days, to
receive a reply to a message.

CompuServe / ZiffNet: Primary support is via the JP Software
section of the CompuServe PCVENB forum (GO JPSOFT or GO
PCVENB, section 10, "JP Software") (1 day).

Bulletin Boards: Primary support is via the Channel 1 BBS,
Boston, MA (1 - 3 days; see above for access details).
Messages may be left in any of the 4DOS conferences; check the
online list for exact conference numbers. Support is also
available from many local BBSes via the 4DOS conferences on
the RIME, ILink, SmartNet, and FidoNet BBS Networks (3-5
days).

To contact JP Software for support by mail, telephone, fax, or
electronic mail, see our addresses and phone numbers on page
vi of this manual.

If you call for support and no technical support
representative is available, we will do our best to return
your call within 24 hours (weekends and holidays excluded).
If your problem is urgent and requires a faster response,
please let us know and we will try to accommodate you. If you
contact us by telephone and don't receive a reply within 24
hours, please try again. We may have tried to return your
call and been unable to reach you.

Before contacting us for support, please check the manuals and
other documentation for answers to your question. If you
can't find what you need, try the Index. If you're having
trouble getting 4DOS, 4OS2, or 4DOS/NT to run properly, either
alone or with your particular hardware or software, see the
Introduction and Installation Guide, and (for 4DOS) the
APPNOTES.DOC file on your disk. Also look through the
README.DOC and UPDATxxx.DOC files, as they may contain updates
to this manual or other important information ("xxx" is the
version number).

If you do need to contact us for support, it helps if you can
give us some basic information:

* What exactly did you do? A concise description of
what steps you must take to make the problem appear is

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 8

INTRODUCTION
-------------------------------------------------------------------

much more useful than a long analysis of what might be
happening.

* What went wrong? At what point did the failure occur?
If you saw an error message or other important or
unusual information on the screen, what exactly did it
say?

* Briefly, what techniques did you use to try to resolve
the problem? What results did you get?

* What computer and operating system are you using?

* Are you running a network, or using a particular
operating environment (such as DESQview or Windows)?

* What are the contents of any startup files you use
(such as CONFIG.SYS, AUTOEXEC.BAT, 4START, 4EXIT, and
the .INI file), any batch files they call, and any
alias or environment variable files they load?

* Can you repeat the problem or does it occur randomly?
If it's random, does it seem related to the programs
you're using when the problem occurs?


























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 9

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------


CHAPTER 1 / GENERAL CONCEPTS


You can start using 4DOS, 4OS2, or 4DOS/NT as soon as you finish
installing it, because each of our products is compatible with the
traditional commands you're used to. But most users find that the
more they know about their computer systems, the more power they
get from our products. And, the more experience they gain, the
more they want to know about their computer system as a whole.

This section of the manual explains some fundamental concepts about
your computer, operating system, and 4DOS, 4OS2, and 4DOS/NT. It
should help you understand the terms and concepts in the pages that
follow. If you find some of the concepts overwhelming, just
remember that they are here when you need them. If you find this
material too simple, skim over the topics and then go on to the
next section. Each topic in this chapter is independent, so if you
read it straight through you won't necessarily find a natural
"flow" from one topic to another.

If you come across terms or concepts in this chapter that you are
unsure about, refer to the Glossary on page 368 or the Index.


Operating Systems and Command Processors

This section explains briefly what an operating system is,
what a command processor is, and how the command processor
works under DOS, OS/2, and Windows NT.

An operating system is nothing more than a collection of
software. However, unlike application software, which
performs a specific, user-oriented task (such as creating and
printing documents, or performing calculations on rows and
columns of numbers), operating system software is designed to
perform some special functions. The operating system
typically:

* Starts the computer system. The operating system is
the first software loaded when you turn on the
computer.

* Provides services to other software. These include
basic file access, assignment of your computer's
memory for use by different programs, and the control
of hardware devices like the keyboard, display,
printer, and serial ports.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 10

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

* Ensures that programs don't interfere with each other
while they are running.

* Provides a way for you to start programs to do your
work.

* Includes utilities to control and manage your system,
for example to organize disks and files, display
status information, or adjust your system for
international conventions.

More complex operating systems may include many more
functions, such as built-in network connections, the ability
to switch rapidly between many tasks, support for high-quality
sound output, and so on.

Our products run under the DOS, OS/2, and Windows NT operating
systems.

Each of these operating systems includes a command processor:
a program that accepts your instructions and carries them out.
The basic operation of a command processor is very simple: It
prompts you for a command, you type in the command, the
command processor executes it, and the cycle repeats. This
sometimes called a "command line" interface, because commands
are typically executed line by line.

Under DOS, the command-line interface is the only way to tell
the operating system what you want it to do. OS/2 and Windows
NT each include a graphical user interface that is intended to
replace the command line as the primary method for providing
instructions to the operating system. However, most OS/2 and
Windows NT users find that the command line is required for
some tasks, and much more efficient for many others. They
therefore use both the graphical interface and the command
line, depending on the task at hand.

The command processor shipped with DOS is called COMMAND.COM.
The command processors shipped with OS/2 and Windows NT are
both called CMD.EXE.

When you install 4DOS, 4DOS.COM replaces COMMAND.COM as your
command processor. 4OS2 replaces the OS/2 version of CMD.EXE
with 4OS2.EXE, and 4DOS/NT replaces the Windows NT version of
CMD.EXE with 4NT.EXE. All of these command processors are
normal programs that know how to translate your commands into
actions. 4DOS, 4OS2, and 4DOS/NT are simply much more
powerful command processors than those supplied with each
operating system.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 11

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

4DOS Under DOS, the command processor is started automatically at
the end of the boot process. If you don't want to use
COMMAND.COM as your command processor, you use the SHELL
statement in CONFIG.SYS to specify a different command
processor.

4OS2 Under OS/2, the command processor is started whenever you
select the appropriate object on your OS/2 desktop. If you
don't want to use CMD.EXE as your command processor, you use
the SET OS2_SHELL statement in CONFIG.SYS to specify a
different command processor. Because OS/2 includes the
ability to run DOS programs, it also includes a copy of
COMMAND.COM as its default DOS command processor. You can
change to a different DOS command processor with the SHELL
statement in the OS/2 CONFIG.SYS file.

4NT Under Windows NT, there is no CONFIG.SYS file, and no special
way to specify a default command processor. Instead, you
simply create a desktop object for any command processor you
want to use.


Primary and Secondary Shells

Technically, the command processor is a shell: a program that
understands your commands and makes the correct calls to the
underlying operating system to perform various tasks,
including running programs.

4DOS Under DOS, the command processor that runs when the computer
boots up, or when an OS/2 DOS session starts, is called the
primary shell.

Any command processor that is started as a "child" to a
primary shell is a secondary shell. Typically, secondary
shells are started by application programs with a "shell to
the command prompt" feature, and by multitasking environments
like Windows or DESQView. A secondary shell has most of the
same features as a primary shell.

There are a few differences between primary and secondary
shells under DOS. Generally, less memory is available when a
secondary shell is running, because at least part of the
program that started it is still in memory waiting to spring
back to life when you exit. And normally only the primary
shell automatically executes the instructions in your
AUTOEXEC.BAT file.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 12

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

Under DOS you can leave a secondary shell with the EXIT
command, but there is normally no way to exit from the primary
shell, because DOS requires a shell present to operate.
However, if you are running 4DOS in a DOS session under OS/2
version 2.0 or later you can use EXIT in the primary DOS shell
to close the session and return to the OS/2 desktop.

4OS2, Under OS/2 and Windows NT, each 4OS2 or 4DOS/NT session that
4NT is started from the desktop is a primary shell. Secondary
shells are started by applications with a "shell to the
command prompt" feature, and are also used for a special kind
of communication between programs called a pipe (see page 53).

Under 4OS2 and 4DOS/NT, you can exit from both primary and
secondary shells. When you exit from a primary shell, the
command processor session is closed and you are returned to
the desktop.

You may also see the term shell used to describe programs
which assist you in managing your files (for example XTree or
Lotus Magellan for DOS, or Norton Commander for OS/2). This
is a different and less precise meaning of "shell" than the
one used above and elsewhere in this manual. Such programs
are also sometimes called "visual shells" because they use a
menu or graphical interface to receive commands. Unlike 4DOS,
4OS2, and 4DOS/NT, these programs are not command processors,
and cannot replace COMMAND.COM or CMD.EXE.

Each time 4DOS, 4OS2, or 4DOS/NT starts as either a primary or
secondary shell, it looks for and executes one or more
"automatic" batch files. These files are explained on page
82.


Files and Directories

You may have dozens, hundreds, or thousands of files stored on
your computer's disks. Your operating system is responsible
for managing all of these files. In order to do so, it uses a
unique name to locate each file in much the same way that the
post office assigns a unique address to every residence.

The unique name of any file is composed of a drive letter, a
directory path, and a filename. Each of these parts of the
file's name is case insensitive; you can mix upper and lower
case letters in any way you wish.




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 13

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

Drives and Volumes

A drive letter designates which drive contains the file. In a
file's full name, the drive letter is followed by a colon.
Drive letters A: and B: are normally reserved for the floppy
disk drives. (Systems with a single drive use both A: and B:
for that drive. The operating system asks you to swap
diskettes as necessary to turn that single physical drive into
two separate logical disk drives.)

Normally, drive C: is the first (or only) hard disk drive.
Later versions of DOS, some DOS-based utility programs, and
both OS/2 and Windows NT can divide a large hard disk into
multiple logical drives or volumes that are usually called C:,
D:, E:, etc. Also, the DOS and Windows NT utility SUBST lets
you use drive letters as a substitute for directory names.
Many network systems (LANs) use a similar feature to give
drive letters to sections of the network file server drives.

Some computers also have "RAM disks" (sometimes called
"virtual disks"), which are areas of memory set aside by
software (a "RAM disk driver") for use as fast but temporary
storage. RAM disks are also assigned drive letters, typically
using letters beyond that used by the last hard disk in the
system, but before any network drives. For example, on a
system with a large hard disk you might have A: and B: as
floppy drives, C:, D:, and E: as parts of the hard disk, F: as
a RAM disk, and G: and H: as network drives.


File Systems

Each disk volume is organized according to a file system. The
file system determines how files are named and how they are
organized on the disk. The DOS file system uses a File
Allocation Table or FAT to keep track of each file, and
therefore it is often called a FAT file system. Both OS/2 and
Windows NT also include support for the traditional FAT file
system.

OS/2 also supports the High Performance File System or HPFS.
Windows NT can work with HPFS disk volumes plus volumes
formatted with its own file system, which is called NTFS.

The file system type (FAT, HPFS, or NTFS) is determined when a
hard disk volume is formatted and applies to the entire
volume. For example, you might have a 200 MB hard disk
divided into four 50 MB volumes, with the first three volumes


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 14

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

(C:, D:, and E:) formatted for the FAT file system, and the
fourth formatted for HPFS or NTFS.

When you are using DOS, only files on FAT volumes are visible
and available. HPFS and NTFS volumes are completely
inaccessible. If you boot your system under OS/2, you can
access FAT and HPFS volumes, both from OS/2 itself and from
DOS sessions running under OS/2 (DOS sessions can only access
files with FAT-compatible names; see page 17 for details). If
you boot under Windows NT, you can access FAT, HPFS, and NTFS
volumes.

4OS2 Finally, OS/2 also supports installable file systems, which
are installed with the IFS= directive in the OS/2 CONFIG.SYS
file. The CD-ROM file system supplied with OS/2 2.x is an
example of an installable file system, and many OS/2 networks
are also implemented as installable file systems.


Directories and Subdirectories

A file system is a method of organizing all of the files on an
entire disk or hard disk volume. Directories are used to
divide the files on a disk into logical groups that are easy
to work with. Their purpose is similar to the use of file
drawers to contain groups of hanging folders, hanging folders
to contain smaller manila folders, and so on.

Every drive has a root or base directory, and many have one or
more subdirectories. Subdirectories can also have
subdirectories, extending in a branching tree structure from
the root directory. The collection of all directories on a
drive is often called the directory tree, and a portion of the
tree is sometimes called a subtree. The terms directory and
subdirectory are typically used interchangeably to mean a
single subdirectory within this tree structure.

Subdirectory names follow the same naming rules as files in
each operating system (see below). However, under DOS it is
best to use a name of 8 characters or less, without an
extension, when naming subdirectories, because some
application programs do not properly handle subdirectory names
that have an extension.

The drive and subdirectory portion of a file's name are
collectively called the file's path. For example, the file
name C:\DIR1\DIR2\MYFILE.DAT says to look for the file
MYFILE.DAT in the subdirectory DIR2 which is part of the
subdirectory DIR1 which is on drive C. The path for

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 15

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

MYFILE.DAT is C:\DIR1\DIR2. The backslashes between
subdirectory names are required. The total length of a file's
path may not exceed 64 characters in DOS, and on FAT volumes
under OS/2 and Windows NT. (This limit excludes the file name
and extension, but includes the drive letter and colon). On
HPFS and NTFS volumes, the path and file name must each be 255
characters or less in length, and in addition the total length
of the path and file name together cannot exceed 260
characters.

The operating system and command processor remember both a
current or default drive for your system as a whole, and a
current or default directory for every drive in your system.
Whenever a program tries to create or access a file without
specifying the file's path, the operating system uses the
current drive (if no other drive is specified) and the current
directory (if no other directory path is specified).

The root directory is named using the drive letter and a
single backslash. For example, D:\ refers to the root
directory of drive D:. Using a drive letter with no directory
name at all refers to the current directory on the specified
drive. For example, E:4DOS.DOC refers to the file 4DOS.DOC in
the current directory on drive E:.

There are also two special subdirectory names that are useful
in many situations: a single period [.] by itself means "the
current default directory." Two periods together [..] means
"the directory which contains the current default directory"
(often referred to as the parent directory). These special
names can be used wherever a full directory name can be used.
4DOS, 4OS2, and 4DOS/NT allow you to use additional periods to
specify directories further "up" the tree (see page 57).


File Names

Finally, each file has a filename. Under the FAT file system,
the filename consists of a base name of 1 to 8 characters plus
an optional extension composed of a period plus 1 to 3 more
characters. You can use alphabetic and numeric characters
plus the punctuation marks ! # $ % & ' ( ) - @ ^ _ ` { } and ~
in both the base name and the extension. Because the
exclamation point [!], percent sign [%], caret [^], at sign
[@], parentheses [()], and back-quote [`] also have other
meanings to 4DOS, 4OS2, and 4DOS/NT, it is best to avoid using
them in filenames.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 16

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

The HPFS file system, which can be used under OS/2 and Windows
NT, allows file names with a maximum of 255 characters,
including spaces and other characters that are not allowed in
a FAT system file name, but excluding some punctuation
characters which are allowed in FAT file names. See your
operating system documentation for details on the characters
allowed. If you use HPFS filenames which contain semicolons
[;], see page 60 for details on avoiding problems with
interpretation of the semicolon under 4OS2 and 4DOS/NT.

The NTFS file system which can be used under Windows NT also
allows file names with a maximum of 255 characters.

HPFS and NTFS file names are always stored and displayed
exactly as you entered them, and are not automatically shifted
to upper or lower case. For example, you could create a file
called MYFILE, myfile, or MyFile, and each name would be
stored in the directory just as you entered it. However, case
is ignored when looking for filenames, so you cannot have two
files whose names differ only in case (i.e., the three names
given above would all refer to the same file). This behavior
is sometimes described as "case-retentive but not case-
sensitive" because the case information is retained, but does
not affect access to the files.

Files stored on HPFS and NTFS volumes often have "FAT-
compatible" names: names which contain only those characters
legal on a FAT volume, and which meet the 8-character name /
3-character extension limits. Programs which cannot handle
the long names supported by HPFS and NTFS (for example, DOS
programs running under OS/2) generally can access files with
FAT-compatible names.

4DOS 4DOS is compatible with FAT volumes. When running in a DOS
session under OS/2, 4DOS can also access files on HPFS volumes
and installable file system volumes (see below), provided the
files have FAT-compatible names. Files on such volumes which
do not have FAT-compatible names will be invisible to 4DOS.

If an HPFS or NTFS-compatible file name includes spaces or
other characters that would not be allowed in a FAT name, you
must place double quotes around the entire name. For example,
suppose you have a file named LET3 on a FAT volume, and you
want to copy it to the LETTERS directory on drive F:, an HPFS
partition, and give it the name Letter To Sara. To do so, use
either of these commands in 4OS2 or 4DOS/NT:

[c:\wp] copy let3 f:\LETTERS\"Letter To Sara"
[c:\wp] copy let3 "f:\LETTERS\Letter To Sara"

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 17

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

HPFS and NTFS do not explicitly define an "extension" for file
names which are not FAT-compatible. However, the convention
used by 4OS2 and 4DOS/NT (and by CMD.EXE) is to treat all
characters after the last period in the file name as the
extension. For example, the file name "Letter to Sara" has no
extension, whereas the name "Letter.to.Sara" has the extension
Sara.


File Attributes

Each file also has attributes which define characteristics of
the file which may be useful to the operating system, to you,
or to an application program. Attributes can be set with the
ATTRIB command (see page 167) and viewed with the ATTRIB and
DIR commands.

Every time a program modifies a file, the operating system
sets the Archive attribute, which signals that the file has
been modified since it was last backed up. This can be used
by 4DOS, 4OS2, or 4DOS/NT to determine which files to COPY,
and by backup programs to determine which files to back up.

When the Read-only attribute is set, the file can't be changed
or erased; this can be used to protect important files from
damage. The Hidden and System attributes prevent the file
from appearing in normal directory listings. The DIR command
(see page 196) has options which allow you to select filenames
to view based on their attributes, to view the attributes
themselves, and to view information about normally "invisible"
hidden and system files.

When a file is created, and every time it is modified, the
operating system records the system time and date in a time
stamp in the file's directory entry. Several 4DOS, 4OS2, and
4DOS/NT commands and variable functions, and many backup and
utility programs, use this time stamp to determine the
relative ages of files.


Internal and External Commands

Whenever you type something at the command line and press the
Enter key, you have given a command to the command processor,
which must figure out how to execute your command. If you
understand the general process that 4DOS, 4OS2, and 4DOS/NT
use, you will be able to make the best use of them and their
commands.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 18

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

The command processor begins by dividing the line you typed
into a command name and a command tail. The command name is
the first word in the command; the tail is everything that
follows the command name. For example, in this command line:

dir *.txt /2/p/v

the command name is "dir", and the command tail is " *.txt
/2/p/v."

If the command name is not an alias (see page 74), the command
processor tries to find the name in its list of internal
commands. An internal command is one that the command
processor can perform itself, without running another program.
DIR and COPY are examples of internal commands.

If the command name is not found in the command processor's
list of internal commands, it assumes that it must find and
execute an external command. This means that the command
processor must load and run a separate program, either an
executable program or a batch file. DOS, OS/2, and Windows NT
are shipped with a number of external utility programs (such
as FORMAT and DISKCOPY), and any program or application you
install on your system becomes a new external command.

The advantage of internal commands is that they run almost
instantly. When you give an internal command, the command
processor interprets the command line and carries out the
necessary activities without having to look for, load, and run
another program.

The advantage of external commands is that they can be large,
varied, and complex without taking space inside the system
command processor. External commands can also be renamed or
replaced easily. If you want to rename the external DOS
command XCOPY to MYCOPY, for example, all you need to do is
find the file called XCOPY.EXE on your DOS disk or directory
and change its name to MYCOPY.EXE. If you want to replace
XCOPY with a more efficient program, you can do so. 4DOS,
4OS2, and 4DOS/NT add this flexibility to internal commands.
You can rename or replace any internal command by using an
alias (see pages 74 and 155), and you can enable or disable
internal commands whenever you wish (see SETDOS /I on page
310).






-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 19

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

Executable Files and File Searches

Once the command processor knows that it is supposed to run an
external command, it tries to find an executable file (one
with a .COM or .EXE extension) whose name matches the command
name. It runs the executable file if it finds one. (See the
previous section for more information on external commands.)

If the command processor cannot find an external program to
run, it next looks for a batch file (a file with one or more
commands in it) whose name matches the command name. 4DOS
recognizes a file as a batch file if its extension is .BAT or
.BTM. 4OS2 recognizes .CMD, .BTM, and .BAT as batch file
extensions. It will run .CMD and .BTM files itself, and will
start a DOS session to run .BAT files. 4DOS/NT can run batch
files with a .BAT, .CMD, or .BTM extension. If the command
processor finds such a file, it then reads each line in the
file as a new command.

If the search for a batch file fails, the command processor
checks to see if the command name matches the name of a file
with an extension that you have defined as executable. If a
match is found, the command processor runs the program you
specified when you defined the executable extension.
(Executable extensions are used to associate file extensions
with the specific program that processes a particular type of
file; see page 66 for details).

4DOS, 4OS2, and 4DOS/NT first search for an executable
program, a batch file, and a file with an executable extension
in the current directory. If the command name doesn't match a
.COM, .EXE, .BTM, .BAT or .CMD file or an executable extension
in the current directory, the command processor repeats its
search in every directory in your search path.

The search path is a list of directories that the command
processor (and some applications) search for executable files.
For example, if you wanted the command processor to search the
root directory of the C: drive, the \DOS subdirectory on the
C: drive, and the \UTIL directory on the D: drive for
executable files, your search path would look like this:

PATH=C:\;C:\DOS;C:\UTIL

Notice that the directory names in the search path are
separated by semicolons.

You can create or view the search path with the PATH command
(see page 276). You can use the ESET command (see page 218)

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 20

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

to edit the path. Many programs also use the search path to
find their own files. The search path is stored in the
environment with the name PATH.

Remember, the command processor always looks for an executable
file or a file with an executable extension first in the
current subdirectory, and then in each directory in the search
path. (You can change the search order so the current
directory is not searched first; see the PATH command for
details.)

If you include an extension as part of the command name, the
command processor only searches for a file with that
extension. For example, if you enter the command WP, 4DOS,
4OS2, or 4DOS/NT will search for any executable file whose
base name is WP. However, if you enter WP.EXE as the command
name, the command processor will search the current directory
and each directory in your search path for WP.EXE, but will
not look for files with other extensions.

If the command processor cannot find an executable file, batch
program, or a file with an executable extension in the current
directory or any directory in the search path, it looks for an
alias called UNKNOWN_CMD (see ALIAS on page 155 for details).
If you have defined an alias with that name, it is executed.
Otherwise, the command processor displays an "Unknown command"
error message and waits for your next instruction.


The Environment

The command processor allows you to keep a list of information
in memory. This list is called the environment. Every
program receives a copy of the environment when it begins, and
many programs use some of its information to configure
themselves or to find files.

The environment is arranged as a series of variables and their
related values. Each variable is a name stored in upper case.
The name is followed by an equal sign [=] and some text. You
can view the environment by typing SET, and add new entries or
edit existing entries with the SET and ESET commands. You can
erase entries in the environment with both the UNSET and SET
commands.

A typical environment entry looks like this:

LIB=c:\lib


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 21

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

In this example, the name of the variable is "LIB" and its
value is "c:\lib". The text string or value can include any
characters except nulls (ASCII 0).

The format and meaning of each entry in the environment is up
to the program that uses the particular variable. Environment
variables can contain just about anything, and can be used for
any purpose the author of a program desires. The "purpose" of
the environment as a whole is simply to hold small amounts of
text which programs can then access according to their own
rules. Most environment variables are used by single programs
for their own information; a few have well-defined meanings
and are used by many different programs.

4DOS, 4OS2, and 4DOS/NT use several environment variables to
control their own behavior. They also provide a wide range of
facilities for manipulating and managing the environment. See
"Using the Environment" beginning on page 94 for details about
these special variables, the size of the environment, and
other environment-related features.


ASCII and Key Codes

Internally, computers use numbers for everything. To
represent the text that you type, a computer must translate
each letter to and from a number. For all PC-compatible
computers, the code used for this translation is called ASCII
(American Standard Code for Information Interchange). ASCII
codes are used both for the characters you type and for the
characters that are displayed on the screen.

The original ASCII code has 128 values for upper and lower
case letters, numerals, punctuation marks, and control codes
(control codes correspond to pressing the Ctrl key plus
another character). Some control codes are represented on the
keyboard with such keys as Tab, Enter, Backspace, and Esc.
IBM, in its original PC, defined an additional 128 extended
ASCII codes for math symbols, international characters, the
line characters used to draw boxes, and some miscellaneous
symbols. You can enter extended ASCII codes on the keyboard
by holding down the Alt key while you type the code number on
the numeric key pad.

The symbol that the computer displays for each ASCII and
extended ASCII code, and the code generated by each key on the
keyboard, depends in part on the country and language support
that your computer is configured to use. Through the use of
code pages in DOS and OS/2, and the Registry in Windows NT,

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 22

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

your computer can be configured for use in most countries.
See your operating system documentation for more information
about country and language support.

Do not confuse extended ASCII with extended key codes. The
latter include special codes that the computer generates when
you press a function key, cursor key, or Alt plus a letter
(see below). Those keys do not have any representation in
either the ASCII or extended ASCII code systems. Another set
of key codes, called scan codes, is discussed in the section
on the keyboard below.

Appendix B on page 357 has a complete list of ASCII, extended
ASCII, and extended key codes.


The Keyboard

When you press a single key or a key combination on the
keyboard, the computer translates your keystroke into two
numbers. For all alphabetic, numeric, and punctuation keys,
the Tab, Enter, Backspace, Esc keys and Ctrl plus an
alphabetic key, these numbers are an ASCII code plus a scan
code. The ASCII code represents the key's meaning; the scan
code identifies which specific key was pressed. For example,
many keyboards have two plus [+] keys, one above the equal
sign and one on the numeric keypad. Both generate the same
ASCII code, but they generate different scan codes.

Keys which are not represented by ASCII codes are translated
to an ASCII 0 plus an extended key code. These keys include
the function keys, the cursor keys, and Alt plus a key. The
extended key code for a key is generally the same as the scan
code for that key.

Some keys, like the Alt, Ctrl, and Shift by themselves or in
combination with each other, plus Print Screen, SysReq, Scroll
Lock, Pause, Break, Num Lock, and Caps Lock, do not have any
code representations at all. The computer performs special
actions automatically when you press these keys (for example,
it switches your keyboard into Caps Lock mode when you press
the Caps Lock key), and does not report the keystrokes to
whatever program is running unless the program has been
written specially to accept them.

Appendix B has a complete list of ASCII and scan codes for the
keys on most keyboards.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 23

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

Video

4DOS, 4OS2, and 4DOS/NT are "character-based" programs, which
means they work in text mode on your computer. In text mode,
the screen or window used by the program displays text in a
single, fixed-pitch font (a font where every character is the
same width), but cannot mix fonts or display graphics. All
three command processors can run graphics programs which
change your screen to graphics mode, but the screen must be
returned to text mode whenever the command processor is
active. In the early days of the IBM PC, text mode was a
single, simple video operating environment. Today, advanced
video boards and video software have created a wide range of
text modes.

The original IBM PC monochrome and CGA color video cards can
display 80 columns and 25 rows of text. Newer, advanced video
systems normally run in this 80 x 25 display mode but can also
display more columns and rows. For example, EGA video cards
can display 43 rows of text and VGA video cards can display 50
rows. With special driver programs, a VGA can display 60 rows
or more and up to 132 columns of text. Each of these
different screen configurations is a different text mode.

In addition to running in a variety of text modes, 4DOS, 4OS2,
and 4DOS/NT can run in "normal" full-screen mode or in a
window inside a graphical environment such as the Windows or
Windows NT desktop, or the OS/2 Workplace Shell. When they
run in such a window, they are still operating in text mode.
The underlying graphical environment translates their text
commands into the appropriate graphics for your video display.

4DOS, 4OS2, and 4DOS/NT support whatever number of rows and
columns of text you decide to use. They don't have commands
to switch from one screen size to another - you will need to
use the software that came with your computer or video board
to do that - but they can read and work with the number of
rows and columns on your screen.


ANSI Drivers

4DOS Every version of DOS includes a program called ANSI.SYS. This
program lets you use text colors other than drab white on
black, redefine keys, and control screen output. Commercial
ANSI drivers are available as replacements for ANSI.SYS. The
commercial programs usually include many new features, boost
screen display speed dramatically, and support text displays
that have more than 80 columns and 25 lines.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 24

CHAPTER 1 / GENERAL CONCEPTS
-------------------------------------------------------------------

In most cases, 4DOS automatically determines whether you have
an ANSI driver installed (if the automatic determination does
not work on your system you can set the ANSI state manually).
If you do have an ANSI driver installed, 4DOS will use the
driver to clear the screen and set screen colors.

4OS2 OS/2 includes ANSI support for character mode sessions. 4OS2
enables this feature when it starts, and assumes that it
remains enabled. You can turn off ANSI support with OS/2's
external ANSI command (ANSI.EXE). If you do, however, 4OS2
will not notice the change and will display unusual characters
or ignore colors in your CLS and COLOR commands.

4NT There is no provision for ANSI support in Windows NT, and
4DOS/NT always assumes that no ANSI driver is present.

Several 4DOS, 4OS2, and 4DOS/NT commands provide replacements
for traditional ANSI commands. For example, there are
commands to set the screen colors and display text in specific
colors. These commands are easier to understand and use than
the traditional ANSI control sequences. Some of these
commands manipulate screen colors directly. Others use an
ANSI driver if one is installed (under 4DOS) or expected
(under 4OS2), but save you the work of figuring out complex
ANSI control sequences. Any special interaction between 4DOS
or 4OS2 and the ANSI driver is described in the documentation
for each command.























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 25

CHAPTER 2 / CONVENTIONS
-------------------------------------------------------------------


CHAPTER 2 / CONVENTIONS


This chapter contains information about three conventions that are
used throughout 4DOS, 4OS2, and 4DOS/NT: colors and color names,
color-coded directories, and keys and key names. These topics are
combined here in a central reference spot so that they will be easy
to find when you need to refer to them. You will find cross
references to this chapter in several other parts of this manual.


Colors and Color Names

You can use color names in several of the directives in the
.INI file and in many commands. The general form of a color
name is:

[BRIght] [BLInk] fg ON [BRIght] bg [BORder bc]

where fg is the foreground or text color, bg is the background
color, and bc is the border color.

The available colors are:

Black Blue Green Red
Magenta Cyan Yellow White

Color names and the words BRIght, BLInk, and BORder may be
shortened to the first 3 letters. BORder is valid only in
4DOS and 4OS2.

There are several subtleties that complicate the use of colors
and color names. In order to understand them, you will need
to read through the restrictions described below. You may
also want to review the Video section in the previous chapter
(see page 24). These restrictions are due to the design of
your PC video hardware, BIOS, and video drivers, and are not
inherent in 4DOS, 4OS2, or 4DOS/NT. Some of the restrictions
are complex, so feel free to skip over those that do not apply
to color combinations you use.

Some restrictions depend on the display "mode." 4DOS, 4OS2,
and 4DOS/NT can run in either normal display mode, when the
command processor is using the full screen and has more direct
control over the video hardware; or in windowed display mode,
when the command processor appears in a window as part of a
graphical display under Windows 3.x, OS/2, or Windows NT.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 26

CHAPTER 2 / CONVENTIONS
-------------------------------------------------------------------

Monochrome Video Adapters

If you have a monochrome video adapter, you cannot display any
colors except white and black in either normal or bright
intensity. If you have a color video adapter, you can use any
of the standard colors listed above (provided you meet the
other restrictions below).


Color Errors

A standard color specification allows sixteen foreground and
eight background colors (sixteen if bright backgrounds are
enabled, see below). However, most video adapters and
monitors do not provide true renditions of certain colors.
For example, most users see normal "yellow" as brown, and
bright yellow as yellow; many also see normal red as red, and
"bright red" as pink. Color errors are often much worse when
running in windowed mode (see above), because the graphical
environment that created the window may not map the text-mode
colors the way you expect. These problems are inherent in the
monitor, video adapter, and driver software. They cannot be
corrected using 4DOS, 4OS2, or 4DOS/NT color specifications.


Border Colors

In order to use border colors, you must have a color video
adapter (monochrome adapters do not support border colors).

4NT 4DOS/NT does not support border colors, and will ignore the
BORder keyword.

4DOS, 4DOS and 4OS2 can only accept border colors in the CLS and
4OS2 COLOR commands, and in the StdColors directive in the .INI
file. Border colors will be ignored, or will cause an error,
if they are used elsewhere.

Border colors do not work in windowed mode, and will be
ignored if used in a windowed session under Windows or OS/2.


Blinking Text and Bright Background Colors

The interactions between blinking characters, bright
backgrounds, and your display mode can be complex. You will
need to understand them if you use either attribute in your
color specifications.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 27

CHAPTER 2 / CONVENTIONS
-------------------------------------------------------------------

Bright background colors are only available if you have an
EGA- or VGA-compatible display adapter. If you have a
monochrome or CGA adapter, you can use blinking displays and
ignore the interactions described below.

The effects of blinking and bright background color
specifications depend partly on whether you are in normal or
windowed display mode.


Normal Display Mode

In normal, full-screen display mode your video hardware can be
configured via software commands to display either blinking
text, or text with a bright background, but not both. This is
due to the design of PC video hardware, and is not a software
restriction.

The memory on your video adapter includes a "flag" for each
character on the screen. The flag controls blinking text and
bright background colors. If the flag is off, the character
is displayed with a normal background and does not blink. If
the flag is "on," the character either blinks or is displayed
with a bright background, depending on which way your video
adapter is currently configured.

4DOS, In normal display mode, the configuration of your video
4OS2 adapter can be controlled by 4DOS and 4OS2 with the BrightBG
directive in the 4DOS.INI file (see page 135) or the SETDOS /B
command (page 309). If you set BrightBG = No or use the
SETDOS /B0 command, 4DOS and 4OS2 will configure the video
adapter for blinking text, and characters with the blink /
bright background flag set will blink. If you set BrightBG =
Yes or use SETDOS /B1, 4DOS and 4OS2 will configure the video
adapter for bright background colors, and the characters will
be displayed with a bright background instead.

4NT BrightBG and SETDOS /B are not available under 4DOS/NT,
because Windows NT always enables bright backgrounds and
disables blinking text.

Because there is only one flag for each character to specify
both blinking text and bright background color, it doesn't
matter which attribute you use when you specify the color.
Whether you specify blinking text or a bright background, you
will see the same thing on your screen. For example, these
two COLOR commands will always produce the same results:

color blink white on blue

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 28

CHAPTER 2 / CONVENTIONS
-------------------------------------------------------------------

color white on bright blue

If bright backgrounds are enabled, both commands will produce
white text on a bright blue background. If blinking text is
enabled, both commands will produce blinking white text on a
blue background.

If you don't use BrightBG or SETDOS /B, 4DOS and 4OS2 will not
attempt to configure your video hardware. Most video adapters
default to blinking text in normal mode, but this can be
changed by application programs. If you use BrightBG or
SETDOS /B, 4DOS and 4OS2 will configure the hardware each time
they display the prompt.

The method used to adjust the video hardware may not be
compatible with all video cards. If you see screen "flashes"
at each prompt when you use BrightBG or SETDOS /B, discontinue
using both commands. This problem is very rare and is not
likely to occur on standard EGA and VGA systems.


Windowed Mode

In windowed mode, the command processor cannot control your
hardware to select blinking or bright backgrounds. Instead,
Windows, OS/2, and Windows NT all display bright background
colors, regardless of the BrightBG or SETDOS /B setting. They
do not provide a way to display blinking characters in
windowed mode. As an example, the two commands given above
would both display white text on a bright blue background when
run in windowed mode.


Switching Modes

Windows and OS/2 allow you to switch any DOS session between
full-screen and windowed mode; Windows NT allows you to switch
modes for any console (non-graphical) session. For example,
when running 4DOS in a DOS session under Windows, you can
switch modes by pressing Alt-Enter. Switching modes will
usually alter color rendition, as you switch between direct
interaction with the video board (in full-screen mode) and the
color mapping provided by your graphical environment (in
windowed mode). In addition, switching modes may alter the
display of blinking text and bright background characters.

4DOS Under 4DOS, if BrightBG is set to Yes, bright background
colors will be preserved when you switch modes. However, if
BrightBG is set to No, the display will shift from blinking

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 29

CHAPTER 2 / CONVENTIONS
-------------------------------------------------------------------

text in the full-screen mode to bright background colors
behind that text in the windowed mode. This effect can be
disturbing; you may need to take it into account if you write
batch files or aliases which may be used in either mode.

4OS2 You cannot switch modes for OS/2 sessions, so 4OS2 is not
directly affected by mode switching. However, if you write
batch files or aliases which run in both modes, you may need
to take into account that OS/2 defaults to displaying blinking
text in full-screen mode and bright backgrounds in windowed
mode.


Color-Coded Directories

The DIR and SELECT commands can display each file name in a
different color, depending on the file's extension.

To choose the DIR and SELECT display colors, you must either
use the SET command to create an environment variable called
COLORDIR, or use the ColorDir directive in your .INI file.

If you do not use the COLORDIR variable or the ColorDir
directive, DIR will use the default screen colors and SELECT
will use the default screen colors or those set with the
SelectColors directive.

If you use both the COLORDIR variable and the ColorDir
directive, the environment variable will override the settings
in your .INI file. You may find it useful to use the COLORDIR
variable for experimenting, then to set permanent directory
colors with the ColorDir directive.

The format for both the COLORDIR environment variable and the
ColorDir directive in the .INI file is:

ext ... :ColorName; ...

where "ext" is a file extension (which may include wildcards)
or one of the following file types:

DIRS Directories
RDONLY Read-only files
HIDDEN Hidden files
SYSTEM System files
ARCHIVE Files modified since the last backup

and "ColorName" is any valid color name (see page 26 for
information on color names).

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 30

CHAPTER 2 / CONVENTIONS
-------------------------------------------------------------------

Unlike most color specifications, the background portion of
the color name may be left out for directory colors. If you
don't specify a background color, DIR and SELECT will use the
current screen background color.

For example, to display the .COM and .EXE files in red on the
current background, the .C and .ASM files in bright cyan on
the current background, and the read-only files in blinking
green on white (this should be entered on one line):

c:\> set colordir=com exe:red; c asm:bright cyan;
rdonly:blink green on white

Extended wildcards (for example "BA[KXC]" for .BAK, .BAX, and
.BAC files) can be used in directory color specifications.
See page 57 for more information on extended wildcards.

4DOS ## 4DOS normally writes text directly to the screen when
displaying color-coded directories. If you have an unusual
display adapter which does not support direct video output,
see the OutputBIOS directive on page 143.


Keys and Key Names

Key names are used to define keystroke aliases, in several of
the .INI file directives, and with the 4DOS KEYSTACK command.
The format of a key name is the same in all three uses:

[Prefix-]Keyname

The key prefix can be left out, or it can be any one of the
following:

Alt followed by A - Z, 0 - 9, F1 - F12, or Bksp
Ctrl followed by A - Z, F1 - F12, Tab, Bksp, Enter,
Left, Right, Home, End, PgUp, PgDn, Ins, or Del
Shift followed by F1 - F12 or Tab.

The possible key names are:

A - Z Enter PgDn
0 - 9 Up Home
F1 - F12 Down End
Esc Left Ins
Bksp Right Del
Tab PgUp



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 31

CHAPTER 2 / CONVENTIONS
-------------------------------------------------------------------

All key names must be spelled as shown. Alphabetic keys can
be specified in upper-case or lower-case. You cannot specify
a punctuation key.

The prefix and key name must be separated by a dash [-]. For
example:

Alt-F10 This is okay
Alt F10 The space will cause an error

If you prefer, you can use a numeric value instead of a key
name. Use the ASCII code for an ASCII, extended ASCII, or
control character. Use the scan code preceded by an at sign
[@] for extended key codes like F1 or the cursor keys. For
example, use 13 for Enter, or @59 for F1. In general, you
will find it easier to use the names described above rather
than key numbers. See Appendix B (page 357) for an
explanation and list of ASCII and key codes.

Some keys are intercepted by your operating system or BIOS and
are not passed on to 4DOS, 4OS2, or 4DOS/NT. For example,
under DOS Ctrl-S pauses screen output temporarily, and on some
systems Ctrl-P toggles Print Echo mode (where text displayed
on the screen is automatically echoed to the printer). Keys
which are intercepted by the operating system or BIOS
generally cannot be assigned to aliases or with key mapping
directives, because the command processor never receives these
keystrokes and therefore cannot act on them.

You also may not be able to use certain keys if your keyboard
is not 100% IBM-compatible, your keyboard driver does not
support them, or, under DOS, if you have an ANSI driver which
does not support them. For example, on some systems the F11
and F12 keys are not recognized; others may not support
unusual combinations like Ctrl-Tab. These problems are rare;
when they do occur, they are usually due to the operating
system and/or your ANSI driver, and not to any problem with
4DOS, 4OS2, or 4DOS/NT.












-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 32

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------


CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT


4DOS, 4OS2, and 4DOS/NT are both a collection of commands and a set
of features which make your computer easier to use. The commands
are explained in the Command Reference section which begins on page
146. This chapter explains each of the features that are not
directly related to individual commands.

Most of the features described in this section are easy to use, but
a few are more technical in nature. Such features are marked with
a ## next to the feature name or the paragraph which describes the
feature's operation.

As you read through this section, we urge you to experiment with
the features that catch your interest and pass over any which seem
too complicated. Come back to this section as you gain expertise,
and you will probably discover that the more complex features will
seem easy and very useful. You don't need to learn any more than
you want, and even if you are a computer novice, you'll find some
features that will interest you immediately.

If you come across terms or concepts in this chapter that you are
unsure about, refer to Chapter 1 / General Concepts, the Glossary
on page 368, or the Index.


At the Command Line

4DOS displays a c:\> prompt when it is waiting for you to
enter a command. 4OS2 and 4DOS/NT display the similar [c:\]
prompt. (In each case, the actual text depends on the current
drive and directory as well as your PROMPT settings.) This is
called the command line and the prompt is asking you to enter
a command, an alias or batch file name, or the instructions
necessary to begin an application program.

This section of the manual explains the features that will
help you while you are typing in commands, and how keystrokes
are interpreted when you enter them at the command line. The
keystrokes discussed here are the ones normally used by 4DOS,
4OS2, and 4DOS/NT. If you prefer using different keystrokes
to perform these functions, you can assign new ones with
keystroke directives in the .INI file (see page 120).





-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 33

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

Command-Line Editing

The command line works like a single-line word processor,
allowing you to edit any part of the command at any time
before you press Enter to execute it, or Esc to erase it.

The command line extends to a maximum of 255 characters under
4DOS and 1023 characters under 4OS2 and 4DOS/NT.

You can use the following editing keys when you are typing a
command (the words Ctrl and Shift mean to press the Ctrl or
Shift key together with the other key named):

Cursor Movement:

Left arrow Move the cursor left one character.
Right arrow Move the cursor right one character.
Ctrl-Left arrow Move the cursor left one word.
Ctrl-Right arrow Move the cursor right one word.
Home Move the cursor to the beginning of
the line.
End Move the cursor to the end of the
line.

Insert and Delete:

Ins Toggle between insert and overtype
mode.
Del Delete the character at the cursor.
Backspace Delete the character to the left of
the cursor.
Ctrl-L Delete the word or partial word to
the left of the cursor.
Ctrl-R or Ctrl-Bksp Delete the word or partial word to
the right of the cursor.
Ctrl-Home Delete from the beginning of the line
to the cursor.
Ctrl-End Delete from the cursor to the end of
the line.
Esc Delete the entire line.
Ctrl-C or Ctrl-Break Cancel the command.
Enter Execute the command line.

4OS2 ## 4OS2 and 4DOS/NT will prompt for additional command-line text
4NT when you include the escape character as the very last
character of a typed command line. The default escape
character in both programs is the caret [^]. For example,

[c:\] echo The quick brown fox jumped over the lazy^

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 34

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

More? sleeping dog. > alphabet

## Sometimes you may want to enter one of the above keystrokes on
the command line instead of performing the key's usual action.
For example, suppose you have a program that requires a Ctrl-R
character on its command line. Normally you couldn't type
this keystroke at the prompt, because it would be interpreted
as a "Delete word right" command.

To get around this problem, use the special keystroke Alt-255.
You enter Alt-255 by holding down the Alt key while you type
255 on the numeric keypad, then releasing the Alt key (you
must use the number keys on the numeric pad; the row of keys
at the top of your keyboard won't work). This forces the
command processor to interpret the next keystroke literally
and places it on the command line, ignoring any special
meaning it would normally have as a command-line editing or
history keystroke. You can use Alt-255 to suppress the normal
meaning of command-line editing keystrokes even if they have
been reassigned with key mapping directives in the .INI file
(see page 120), and Alt-255 itself can be reassigned with the
CommandEscape directive.

If you want your input at the command line to be in a
different color from the command processor's prompts or
output, you can use the InputColors directive in your .INI
file. You must have an ANSI driver installed to use
InputColors under 4DOS. See page 135 for more details on
InputColors.

Most of the command-line editing capabilities are also
available when a 4DOS, 4OS2, or 4DOS/NT command prompts you
for a line of input. For example, you can use the command-
line editing keys when DESCRIBE (page 193) prompts for a file
description, when INPUT (page 249) prompts for input from an
alias or batch file, or when LIST (page 260) prompts you for a
search string.


Command History and Recall

Each time you execute a command, the entire command line is
saved in a command history list. You can display the saved
commands, search the list, modify commands, and rerun
commands.

The simplest use of the command history list is to repeat a
command exactly. For example, you might enter the command


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 35

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

c:\> dir b:*.wks;*.doc

to see some of the files on drive B. You might move some new
files to drive B and then want to repeat the DIR command.
Just press the Up Arrow key repeatedly to scan back through
the history list. When the DIR command appears, press Enter
to execute it again.

After you have found a command, you can edit it before
pressing Enter. You will appreciate this feature when you
have to execute a series of commands that differ only slightly
from each other.

The history list is "circular". If you move to the last
command in the list and then press the down arrow one more
time, you'll see the first command in the list. Similarly, if
you move to the first command in the list and then press the
up arrow one more time, you'll see the last command in the
list.

You can search the command history list to find a previous
command quickly using command completion. Just enter the
first few characters of the command you want to find and press
Up Arrow. You only need to enter enough characters to
identify the command that you want to find. For example, to
find the DIR command, enter DI and then press Up Arrow. If
you press the Up Arrow key a second time, you will see the
previous command that matches. The system will beep if there
are no matching commands. The search process stops as soon as
you type one of the editing keys, whether or not the line is
changed. At that point, the line you're viewing becomes the
new line to match if you press Up Arrow again.

You can specify the size of the command history list with the
History directive in the .INI file (see page 127). When the
list is full, the oldest commands are discarded to make room
for new ones. You can also use the HistMin directive in the
.INI file to enable or disable history saves and to specify
the shortest command line that will be saved (see page 132).

You can prevent any command line from being saved in the
history by beginning it with an at sign [@].

When you execute a command from the history, that command
remains in the history list in its original position. The
command is not copied to the end of the list (unless you
modify it). If you want each command to be copied to the end
of the list when it is re-executed, set HistCopy to Yes in
your .INI file (see page 132).

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 36

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

Command History Keys:

Up Arrow Recall the previous (or most recent)
command, or the most recent command
that matches a partial command line.
Down Arrow Recall the next (or oldest) command,
or the oldest command that matches a
partial command line.
F3 Fill in the rest of the command line
from the previous command, beginning
at the current cursor position.
Ctrl-D Delete the currently displayed
history list entry, erase the command
line, and display the previous
matching history list entry.
Ctrl-E Display the last entry in the history
list.
Ctrl-K Save the current command line in the
history list without executing it,
and then clear the command line
@ As the first character in a line: Do
not save the current line in the
history list when it is executed, or
store it in the CMDLINE environment
variable (see CMDLINE on page 96 for
further details).

Use F3 when your new command is different from your old one by
just a character or two at the beginning. For example,
suppose you want to execute a DIR on several file names then
use DEL to delete those same files. After the DIR is complete
type DEL and press F3; the rest of the command line will be
completed for you. Check that it's correct, and then press
Enter to delete the files. F3 also retrieves the entire
previous command (like up-arrow) if nothing has been typed on
the line.

Use Ctrl-E to "get your bearings" by returning to the end of
the list if you've scrolled around so much that you aren't
sure where you are any more.

Use Ctrl-K to save some work when you've typed a long command
and then realize that you weren't quite ready. For example,
if you forget to change directories and notice it after a
command is typed or mostly typed, but before you press Enter,
just press Ctrl-K to save the command without executing it.
Use the CD or CDD command to change to the right directory,
press up-arrow twice to retrieve the command you saved, make
any final changes to it, and press Enter to execute it.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 37

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

Local and Global Command History

The command history can be stored in either a "local" or
"global" list.

With a local history list, any changes made to the history
will only affect the current copy of the command processor.
They will not be visible in other shells, or other sessions.
A local history list is the default under 4DOS.

With a global history list, all copies of the command
processor will share the same command history, and any changes
made to the history in one copy will affect all other copies.
Global lists are the default for 4OS2 and 4DOS/NT.

You can control the type of history list with the LocalHistory
directive in the .INI file (see page 128), and with the /L and
/LH options of the START command (see page 317).

There is no fixed rule for deciding whether to use a local or
global history list. Depending on your work style, you may
find it most convenient to use one type, or a mixture of types
in different sessions or shells. We recommend that you start
with the default approach for your command processor, then
modify it if you find a situation where the default is not
convenient.

4DOS If you select a global history list for 4DOS running under
DOS, you can share the history among all copies of 4DOS.
However, if you run 4DOS under OS/2, global lists will apply
within each DOS session, but will not allow you to share the
history between different DOS sessions.

4OS2 ## If you select a global history list for 4OS2 or 4DOS/NT, you
4NT can share the history among all copies of the command
processor running in any session. When you close all 4OS2 or
4DOS/NT sessions, the memory for the global history list is
released, and a new, empty history list is created the next
time you start 4OS2 or 4DOS/NT. If you want the history list
to be retained in memory even when no command processor
session is running, you need to load the SHRALIAS program,
which performs this service for the global history and alias
lists. SHRALIAS is described in more detail under the ALIAS
command (see page 164).

Whenever you start a secondary shell (see page 12) which uses
a local history list, it inherits a copy of the command
history from the previous shell. However, any changes to the
history made in the secondary shell will affect only that

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 38

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

shell. If you want changes made in a secondary shell to
affect the previous shell, use a global history list in both
shells.


Command History Window

You can also view the command history in a scrollable command
history window, and select the command to modify or re-execute
from those displayed in the window. To activate the command
history window press PgUp or PgDn at the command line. A
window will appear in the upper right corner of the screen,
with the command you most recently executed marked with a
highlight. (If you just finished re-executing a command from
the history, then the next command in sequence will be
highlighted.)

You can scroll the command history window up and down one line
at a time with Up Arrow and Down Arrow, and one page (screen)
at a time with PgUp and PgDn. The display is not circular as
it is at the prompt; it has a fixed beginning and end. Left
Arrow and Right Arrow will pan the text in the history to the
left or right. Home or Ctrl-PgUp will go to the beginning of
the history, and End or Ctrl-PgDn will go to the end. The
Ctrl-D (delete from history) key works within the history
window as it does at the command line.

Once you have selected a command in the history window, press
Enter to execute it immediately, or Ctrl-Enter to move the
line to the prompt for editing (you cannot edit the line
directly in the history window).

You can bring up a "filtered" history window by typing some
characters on the command line, then pressing PgUp or PgDn.
Only those commands matching the typed characters will be
displayed in the window.

You can control the position and size of the history window
with directives in the .INI file (see page 133). You can also
change the keys used in the window with key mapping directives
in the .INI file (see page 140).

Command History Window:

PgUp or PgDn (from the command line) Open the
command history window.
Up Arrow Scroll the display up one line.
Down Arrow Scroll the display down one line.
Left Arrow Scroll the display left 4 columns.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 39

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

Right Arrow Scroll the display right 4 columns.
PgUp (inside the window) Scroll the
display up one page.
PgDn (inside the window) Scroll the
display down one page.

Ctrl-PgUp or Home Go to the beginning of the history
list.
Ctrl-PgDn or End Go to the end of the history list.
Ctrl-D Delete the selected line from the
history list.
Enter Execute the selected line.
Ctrl-Enter Move the selected line to the command
line for editing.


Filename Completion

Filename completion can help you by filling in a complete file
name on the command line when you only remember part of the
name. For example, suppose you want to copy a file. You know
that its name begins AU but you can't remember the rest of the
name. Type:

c:\> copy au

and then press the Tab key or F9 key. 4DOS, 4OS2, or 4DOS/NT
will search the current directory for filenames that begin AU
and insert the first one onto the command line in place of the
AU that you typed.

If this is the file that you want, simply complete the
command. If the command processor didn't find the file that
you were looking for, press Tab or F9 again to substitute the
next filename that begins with AU. When there are no more
filenames that match your pattern, the system will beep each
time you press Tab or F9.

If you go past the filename that you want, press Shift-Tab or
F8 to back up and return to the previous matching filename.
After you back up to the first filename, the system will beep
each time you press Shift-Tab or F8.

If you want to enter more than one matching filename on the
same command line, press F10 when each desired name appears.
This will keep that name and place the next matching filename
after it on the command line. You can then use Tab (or F9)
and Shift-Tab (or F8) to move through the remaining matching
files.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 40

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

The pattern you use for matching may contain any valid
filename characters, as well as wildcard characters and
extended wildcards (see page 57). For example, you can copy
the first matching .TXT file by typing

c:\> copy *.txt

and then pressing Tab.

If you don't specify part of a filename before pressing Tab,
the matching pattern will be *.*. If you type a filename
without an extension, the command processor will add *.* to
the name. It will also place a "*" after a partial extension.
If you are typing a group of file names in an include list
(see page 65), the part of the include list at the cursor will
be used as the pattern to match.

When filename completion is used at the start of the command
line, it will only match directories, executable files (see
page 20), and files with executable extensions, since these
are the only file names that it makes sense to use at the
start of a command. If a directory is found, a "\" will be
appended to it to enable an automatic directory change (see
page 44).

Filename Completion Keys:

F8 or Shift-Tab Get the previous matching filename.
F9 or Tab Get the next matching filename.
F10 Keep the current matching filename
and display the next matching name
immediately after the current one.


Filename Completion Window

You can also view filenames in a scrollable filename
completion window and select the file you want to work with.
To activate the window, press F7 or Ctrl-Tab at the command
line. You will see a window in the upper-right corner of the
screen, with the names of files that match any partial
filename you have entered on the command line. If you haven't
yet entered a file name, the window will contain the name of
all files in the current directory. (Ctrl-Tab will work only
if your keyboard and BIOS or keyboard driver support it. If
it does not work on your system, use F7 instead.)

You can scroll the filename completion window up and down one
line at a time with Up Arrow and Down Arrow, and one page

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 41

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

(screen) at a time with PgUp and PgDn. Home or Ctrl-PgUp will
go to the beginning of the list of file names; End or Ctrl-
PgDn will go to the end. You can scroll the window left and
right 4 spaces at a time with the Left Arrow or Right Arrow.

Once you have selected the filename you want, press Enter to
insert it into the command line.

Filename Completion Window:

F7 or Ctrl-Tab (from the command line) Open the
filename completion window.
Up Arrow Scroll the display up one line.
Down Arrow Scroll the display down one line.
Left Arrow Scroll the display left 4 columns.
Right Arrow Scroll the display right 4 columns.
PgUp Scroll the display up one page.
PgDn Scroll the display down one page.
Ctrl-PgUp or Home Go to the beginning of the filename
list.
Ctrl-PgDn or End Go to the end of the filename list.
Enter Insert the selected filename into the
command line.


Directory Changes and CDPATH

The operating system and command processor remember both a
current or default drive for your system as a whole, and a
current or default directory for every drive in your system.
The current directory on the current drive is sometimes called
the current working directory.

You can change the current drive by simply typing the new
drive letter plus a colon at the prompt. You can change the
current working directory with the CD command (see page 175),
the CDD command (page 177), the PUSHD and POPD commands (pages
285 and 280), and with automatic directory changes (page 44).
The CD command can change the default directory on any drive,
but it cannot change the current working directory from one
drive to another. The other methods of changing the current
working directory can change both the current drive and the
current directory in a single command.

Whenever you change the current working directory, 4DOS, 4OS2,
or 4DOS/NT saves the original directory in up to three places.
First, the directory is saved as the previous working
directory. You can change to the previous working directory
with the CD - and CDD - commands (see pages 175 and 177). You

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 42

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

can use either of these commands repeatedly to switch back and
forth between two directories.

The original directory is also saved in the directory history
(see the next topic below). You can use this list to change
to a recent directory with the cursor keys instead of typing a
directory name.

Finally, the PUSHD command records the old directory in the
directory stack. You can view the contents of this stack with
the DIRS command and return to the directory on the top of the
stack with the POPD command.

If CD, CDD, PUSHD, or an automatic directory change can't
locate the specified directory to change to, they will look
for the CDPATH environment variable. The command will append
the specified directory name to each directory in CDPATH and
attempt to change to that drive and directory, until the first
match or the end of the CDPATH argument. This allows you to
use CDPATH as a quick way to find commonly used subdirectories
which have unique names. For example, if you are currently in
the directory C:\WP\LETTERS\JANUARY and you'd like to change
to D:\SOFTWARE\UTIL, you could enter the command:

c:\wp\letters\january> cdd d:\software\util

However, if the D:\SOFTWARE directory is listed in your CDPATH
variable, and is the first directory in the list with a UTIL
subdirectory, you can simply enter the command

c:\wp\letters\january> cdd util

to change to D:\SOFTWARE\UTIL.

You can create CDPATH with the SET command. The format of the
CDPATH is similar to that of PATH: a list of directories
separated by semicolons [;]. For example, if you want the
directory change commands to search the C:\DATA directory, the
D:\SOFTWARE directory, and the root directory of drive E:\ for
the subdirectories that you name, you should create CDPATH
with this command:

c:\> set cdpath=c:\data;d:\software;e:\


Directory History Window

Every time you change to a new directory or drive, the current
directory is recorded in an internal directory history. The

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 43

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

length of the directory history is fixed at 256 bytes; as new
entries are added, old entries are deleted from the list.
Directory changes are recorded whether you make them from the
command line with the CD, CDD, PUSHD, or POPD commands, with
an automatic directory change, or by typing a new drive letter
followed by a colon. Directories are recorded whether you
change from one to another at the command line, from within a
batch file, or from within an alias. In order to conserve
space, each directory name is recorded just once in the
directory history, even if you move into and out of that
directory several times.

You can view the directory history from a scrollable directory
history window and change to any drive and directory on the
list. To activate the directory history window, press Ctrl-
PgUp or Ctrl-PgDn at the command line. You can then select a
new directory with the Enter key.

Directory History Window:

Ctrl-PgUp (from the command line) Open the
or Ctrl-PgDn directory history window.
Up Arrow Scroll the display up one line.
Down Arrow Scroll the display down one line.
Left Arrow Scroll the display left 4 columns.
Right Arrow Scroll the display right 4 columns.
PgUp Scroll the display up one page.
PgDn Scroll the display down one page.
Ctrl-PgUp or Home Go to the beginning of the directory
list.
Ctrl-PgDn or End Go to the end of the directory list.
Ctrl-D Delete the selected line from the
directory list.
Enter Change to the selected drive and
directory.
Ctrl-Enter Move the selected line to the command
line for editing.


Automatic Directory Changes

The automatic directory change feature gives you a quick
method for changing directories. You can use an automatic
directory change in place of the CD or CDD command. To do so,
simply type the name of the directory you want to change to at
the prompt, with a backslash [\] at the end. For example:

c:\> 4dos\
c:\4dos>

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 44

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

This feature can make directory changes very simple when it's
combined with the CDPATH environment variable (see page 43).
CDPATH is a list of directories for the CD and CDD commands to
search if the directory you name does not exist below the
current directory. Automatic directory changes use CDPATH as
well. For example, suppose CDPATH is set to C:\;D:\;E:\, and
the directory WIN exists on drive E:. You can change to this
directory with a single word on the command line:

c:\4dos> win\
e:\win>

In executing the command shown above, the command processor
first looks for a WIN subdirectory of the current directory,
i.e., C:\4DOS\WIN. If no such directory exists it looks for a
WIN subdirectory in every directory in the CDPATH list, and
changes to the first one it finds.

Internally, automatic directory changes use the CDD command,
so the text before the backslash can include a drive letter, a
full path, or a partial path. Commands like "....\" can be
used to move up the directory tree quickly (see page 57).
Automatic directory changes save the current directory, so it
can be recalled with a "CDD -" or "CD -" command. For more
information on directory changes see page 43, CD on page 175,
and CDD on page 177.


Multiple Commands

At times, you probably know the next two or three commands
that you want to execute. Instead of waiting for each one to
finish before you type the next, you can type them all on the
same command line, separated by a caret [^] in 4DOS, or an
ampersand [&] in 4OS2 or 4DOS/NT. For example, if you know
you want to copy all of your .TXT files to drive A: and then
run CHKDSK to be sure that drive A's file structure is in good
shape, in 4DOS you could enter the following command:

c:\> copy *.txt a: ^ chkdsk a:

You may put as many commands on the command line as you wish,
as long as the total length of the command line does not
exceed 255 characters in 4DOS or 1023 characters in 4OS2 and
4DOS/NT.

You can use multiple commands in batch files (see page 77) and
alias definitions (see page 74) as well as from the command
line.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 45

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

If you don't like using the default command separator, you can
pick another character using the SETDOS /C command (see page
309) or the CommandSep directive in the .INI file (see page
131). If you plan to share aliases or batch files between
4DOS, 4OS2, and 4DOS/NT, see page 72 for details about
choosing compatible command separators for two or more
products.


Temporarily Disabling Aliases

Aliases can be used to create shorthand names for commonly
used commands, or to define default options for existing
commands (for more information see pages 74 and 155). At
times, you may want to temporarily disable an alias that you
have defined. You may have an alias that changes the defaults
of a particular command, for example, and want to run the
unmodified version of the command. To do so, precede the
command name with an asterisk [*]. For example, if you have
an alias for DIR which displays directories in 2-column paged
mode by default, you can use the following command to display
a directory in the normal single-column, non-paged mode:

c:\> *dir

You can also disable aliases temporarily with the SETDOS /X
command (see page 312).


Command Line Help

All of our products include complete online help. You can
start the help system by typing HELP or HELP plus a command
name at the prompt, or by pressing the F1 key at any time at
the command line.

4DOS In 4DOS,a special program (4HELP.EXE) displays the online
help. If you press F1, the 4DOS help system will display the
list of all help topics just as if you had entered the HELP
command.

4OS2, In 4OS2 and 4DOS/NT, the online help uses the operating
4NT system's built-in help facility. If you press F1, the table
of contents will be displayed and you can select the desired
help topic using the standard help "navigation" keys for your
system.

If you have already typed part or all of a command on the
line, the help system will provide "context-sensitive" help by

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 46

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

using the first word on the line as a help topic. If it's a
valid topic, you will see help for that topic automatically;
if not, you will see the list of all help topics (in 4DOS) or
the table of contents (in 4OS2 and 4DOS/NT), and you can then
pick the topic you want. For example, if you press F1 after
entering each of the command lines shown below you will get
the display indicated:

c:\> Topic list / table of contents
c:\> copy *.* a: Help on COPY
c:\> c:\util\map Topic list / table of contents

If you type the name of any internal command at the prompt,
followed by a slash and a question mark [/?] like this:

copy /?

then you will see help for the command in a "quick-reference"
style. Output from a /? display may be redirected with > or
>> (see page 50). The /? option may not work correctly if you
have redefined how the command operates with an alias. In
this case you may need to add an asterisk to the beginning of
the command to disable alias processing:

alias copy copy /r
*copy /?

/? will only access the help system when you use it with an
internal command. If you use it with an external command
name, the external command will be executed and will interpret
the /? parameter according to its own rules. Some external
commands, including some DOS and OS/2 external utility
programs, do display help when run with a /? parameter, but
this a characteristic of these commands and does not depend on
the command processor. Many other external commands do not
have this feature.

Please see the Introduction and Installation Guide that was
supplied with your version of 4DOS, 4OS2, or 4DOS/NT for a
more thorough explanation of the online Help available with
the program you use.


## Command-Line Length Limits

Under 4DOS, when you first enter a command at the prompt or in
an alias or batch file, it can be up to 255 characters long.
The 4OS2 and 4DOS/NT command lines can hold 1,023 characters.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 47

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

As the command processor scans the command line and
substitutes the contents of aliases and environment variables
for their names, the line usually gets longer. This expanded
line is stored in an internal buffer which allows each
individual command to grow to 255 characters during the
expansion process (1,023 characters in 4OS2 and 4DOS/NT). In
addition, if you have multiple commands on a single line,
during expansion the entire line can grow to as much as 511
characters in 4DOS, or 2,047 characters in 4OS2 and 4DOS/NT.
If your use of aliases or environment variables causes the
command line to exceed either of these limits as it is
expanded, you will see an error message and the remainder of
the line will not be executed.


Page and File Prompts

Several 4DOS, 4OS2, and 4DOS/NT commands can generate prompts,
which wait for you to press a key to view a new page or to
perform a file activity.

When 4DOS, 4OS2, or 4DOS/NT is displaying information in page
mode, for example with a DIR /P or SET /P command, it displays
the message

Press Esc to Quit or any other key to continue...

At this prompt, you can press Esc, Ctrl-C, or Ctrl-Break if
you want to quit the command. You can press almost any other
key to continue with the command and see the next page of
information.

During file processing, if you have activated prompting with a
command like DEL /P, you will see this prompt before
processing every file:

Y/N/R ?

You can answer this prompt by pressing "Y" for "Yes, process
this file;" "N" for "No, do not process this file;" or "R"
for "process the Remainder of the files without further
prompting." You can also press Ctrl-C or Ctrl-Break at this
prompt to cancel the remainder of the command.

If you press Ctrl-C or Ctrl-Break while a batch file is
running, you will see a "Cancel batch job" prompt. For
information on responses to this prompt see page 82.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 48

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

Critical Errors

DOS, OS/2, and Windows NT all watch for physical errors during
input and output operations. Physical errors are those due to
hardware problems, such as trying to read a floppy disk while
the drive door is open.

These errors are called critical errors because the operating
system, command processor, or application program cannot
proceed until the error is resolved.

When a critical error occurs, you will see a message asking
you to choose one of four error handling options. The message
comes from the command processor or the operating system, and
will vary slightly depending on your operating system and
(under OS/2 and Windows NT) whether you are in full-screen or
windowed mode. You can respond with a single character (under
DOS), or a mouse click or menu selection (under OS/2 or
Windows NT). However, the options and their meanings are
similar in all cases:

Retry Retry the operation. Choose this option if you
have corrected the problem.

Ignore Ignore the error and continue. Use caution when
choosing this option. Ignoring critical errors,
especially on the hard disk, can cause errors in
your applications or damage data on the disk.

Fail Tell the program that the operation failed. This
option returns an error code to the command
processor or to the application program that was
running when the error occurred. 4DOS, 4OS2, and
4DOS/NT generally stop the current command when
an operation fails. This option is not available
for all errors; if you don't see it, use Abort
instead. Under DOS, you can force a Fail
response to all critical errors with the CritFail
directive in 4DOS.INI (see page 142).

Abort Abort the program. Choose this option to stop
the program that was running when the error
occurred. Choosing Abort after an error in 4DOS,
4DOS/NT, or the 16-bit version of 4OS2 will abort
the command, but not the command processor
itself. Choosing Abort after an error in the 32-
bit version of 4OS2 will abort both the command
and the command processor. To avoid this, use
Fail rather than Abort if possible.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 49

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

Input and Output

Internal commands and many external programs get their input
from the computer's standard input device and send their
output to the standard output device. Some programs also send
special messages to the standard error device. Normally, the
keyboard is used for standard input and the video screen for
both standard output and standard error, but you can
temporarily change these assignments for special tasks.

For example, suppose you want a printed list of the files in a
directory. If you change the standard output to the printer
and issue a DIR command, the task is easy. DIR prints to
standard output, and you have redirected standard output to
the printer, so the DIR command prints filenames instead of
displaying them on the screen. You can just as easily send
the output of DIR (or any other command) to a file or a serial
port.

We offer three methods of manipulating input and output:
Redirection, Piping, and (under 4DOS) the Keystack. All three
are explained in this section.

Redirection and piping affect the standard input, standard
output, and standard error devices. They do not work with
application programs which read the keyboard hardware
directly, or which write directly to the screen.


Redirection

Redirection assigns standard input, standard output, and
standard error to a device like the printer or serial port, or
to a file. (You must use some discretion when you use
redirection with a device; there is no way to get input from
the printer, for example.)

Redirection always applies to a specific command, and lasts
only for the duration of that command. When the command is
finished, the assignments for standard input, standard output,
and standard error revert to whatever they were before the
command.

In the descriptions below, filename means either the name of a
file or of an appropriate device (PRN, LPT1, LPT2, or LPT3 for
printers; COM1 to COM4 for serial ports; CON for the keyboard
and screen; etc.).



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 50

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

To use redirection, place the redirection symbol and filename
at the end of the command line, after the command name and any
parameters. For example, to redirect the output of the DIR
command to a file called DIRLIST, you could use a command line
like this:

c:\> dir /b *.dat > dirlist

You can use both input and output redirection for the same
command, if both are appropriate:

c:\> sort < dirlist > dirlist.srt

If you redirect the output of a single internal command like
DIR, the redirection ends automatically when that command is
done. If you start a batch file with redirection, all of the
batch file's output is redirected, and redirection ends when
the batch file is done. Similarly, if you use redirection at
the end of a command group (see page 69), all of the output
from the command group is redirected, and redirection ends
when the command group is done.

Here are the redirection options supported by 4DOS, 4OS2, and
4DOS/NT:

To get input from a file or device instead of from the
keyboard:

< filename

To redirect standard output to a file or device:

> filename

To redirect standard output and standard error to a file
or device:

>& filename

To redirect standard error only to a file or device:

>&> filename

If you want to append output to the end of an existing file,
rather than creating a new file, replace the first ">" in the
last three commands above with ">>" (use >>, >>&, and >>&>).

## When output is directed to a file with >, >&, or >&>, if the
file already exists, it will be overwritten. You can protect

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 51

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

existing files by using the SETDOS /N1 command (see page 311)
or the NoClobber directive in the .INI file (see page 134).

## When output is appended to a file with >>, >>&, or >>&>, the
file will be created if it doesn't already exist. Setting
NoClobber will also prevent the creation of a new file.

## You can temporarily override the current setting of NoClobber
by using an exclamation mark [!] after the redirection symbol.
For example, to redirect the output of DIR to the file DIROUT,
and allow overwriting of any existing file despite the
NoClobber setting:

c:\> dir >! dirout

## Redirection is fully nestable. For example, you can invoke a
batch file and redirect all of its output to a file or device.
Output redirection on a command within the batch file will
take effect for that command only; when the command is
completed, output will revert to the redirected output file or
device in use for the batch file as a whole.

## You can use redirection if you need to create a zero-byte
file. To do so, enter >filename as a command, with no actual
command before the > character.

4DOS ## For another method of changing the standard input and output
devices see CTTY on page 187.

4OS2, In addition to the extended 4DOS redirection options, 4OS2 and
4NT 4DOS/NT also support the OS/2 and Windows NT CMD.EXE syntax

n>file

and

n>&m

where [n] and [m] are digits between 0 and 9. You may not put
any spaces between the n and the >, or between the >, &, and m
in the second form. The digits represent file handles; OS/2
and Windows NT interpret "0" as standard input, "1" as
standard output, and "2" as standard error. Handles 3 to 9
will probably not be useful unless you have an application
which uses those handles for a specific, documented purpose,
or have opened a file with the %@FILEOPEN variable function
(see page 110) and the file handle is between 3 and 9.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 52

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

The n>file syntax redirects output from handle n to a file.
You can use this form to redirect two handles to different
places. For example:

[c:\] dir > outfile 2> errfile

sends normal output to a file called OUTFILE and any error
messages to a file called ERRFILE.

The n>&m syntax redirects handle n to the same location as the
previously assigned handle m. For example, to send standard
error to the same file as standard output, you could use this
command:

[c:\] dir > outfile 2>&1

Notice that you can perform the same operations by using 4OS2
or 4DOS/NT's enhanced redirection features. The two examples
above could be written as

[c:\] dir > outfile >&> errfile

and

[c:\] dir >&outfile


Piping

You can also create a "pipe," which means sending the standard
output of one command to the standard input of another
command. To send the standard output of command1 to the
standard input of command2:

command1 | command2

To send the standard output and standard error of command1 to
the standard input of command2:

command1 |& command2

For example, to take the output of the SET command (which
displays a list of your environment variables and their
values) and pipe it to the SORT utility to generate a sorted
list, you would use the command:

c:\> set | sort



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 53

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

To do the same thing and then pipe the sorted list to the
internal LIST command for full-screen viewing (see page 260):

c:\> set | sort | list /s

## The TEE and Y commands (see pages 326 and 344) are "pipe
fittings" which add more flexibility to pipes.

## Like redirection, pipes are fully nestable. For example, you
can invoke a batch file and send all of its output to another
command with a pipe. A pipe on a command within the batch
file will take effect for that command only; when the command
is completed, output will revert to the pipe in use for the
batch file as a whole. You may also have 2 or more pipes
operating simultaneously if, for example, you have the pipes
running in different windows in a multitasking system.

4DOS ## 4DOS creates one or two temporary files to hold the output of
pipes. The files are given unique names. By default, these
files are stored in the root directory of the boot drive, but
you can override this with either the TEMP4DOS or TEMP
environment variable (see page 97).

4OS2 ## 4OS2 and 4DOS/NT implement pipes by starting a new process for
4NT the receiving program instead of using temporary files. The
sending and receiving programs run simultaneously; the sending
program writes to the pipe and the receiving program reads
from the pipe. When the receiving program finishes reading
and processing the piped data, it is ended automatically.

If you are used to using pipes under 4DOS, you normally will
not see any difference with a 4OS2 or 4DOS/NT pipe except
perhaps less disk activity. But you may not get the results
you expect if you use a pipe command like:

[c:\] echo test | input %%var

4DOS In 4DOS, this pipe will create an environment variable called
VAR and set its value as "test." You will be able to see the
new variable by typing SET at the prompt.

4OS2, In 4OS2 and 4DOS/NT, VAR will be set in the environment that
4NT belongs to the receiving program. But that environment will
be discarded when the pipe has been emptied and the process
ends. You will never see VAR in the environment even though
the command processor and the operating system are both
operating correctly.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 54

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

The same cautions apply to the "pipe-fitting" commands, TEE
and Y. When you use pipes with 4OS2 or 4DOS/NT, make sure you
think about any possible consequences that can occur from
using a separate process to run the receiving program.


4DOS Keystack

The 4DOS Keystack overcomes two weaknesses of input
redirection: many programs ignore standard input and read the
keyboard directly, and input redirection doesn't end until the
program or command terminates. You can't, for example, use
redirection to send the opening commands to a program and then
type the rest of the commands yourself. But the Keystack lets
you do exactly that.

The 4DOS Keystack sends keystrokes to an application program.
Once the Keystack is empty, the program will receive the rest
of its input from the keyboard. The Keystack is useful when
you want a program to take certain actions automatically when
it starts. It is most often used in batch files and aliases.

The Keystack is invoked with the KEYSTACK command (see page
254). It depends on a small resident program called
KSTACK.COM, which may be installed from your AUTOEXEC.BAT file
(see page 83). If you don't have KSTACK.COM installed, the
KEYSTACK command will display an error message. If you are
using a multitasking system such as DESQview or Windows, see
your 4DOS Introduction and Installation Guide for information
on loading KSTACK within a window.

To place the letters, digits, and punctuation marks you would
normally type for your program into the keystack, enclose them
in double quotes:

c:\> keystack "myfile"

Many other keys can be entered into the Keystack using their
names. This example puts the F1 key followed by the Enter key
in the keystack:

c:\> keystack F1 Enter

See page 31 for details on how key names are entered. See the
KEYSTACK command on page 254 for information on using numeric
key values along with or instead of key names, and other
details about using the Keystack.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 55

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

The following command creates an alias (see page 155) that
will run a dBASE report called TIMEREP (it should be entered
on one line):

c:\> alias drpt `keystack "use times index times" Enter
"report form timerep to print" Enter "quit" Enter
^ dbase`

This command creates an alias called DRPT which puts the
following characters on the keystack:

the characters "use times index times"
the Enter key's code
the characters "report form timerep to print"
the Enter key's code
the characters "quit"
and one more Enter key

The alias then runs the program dBASE which receives those
characters just as if you had typed them.

When you use the Keystack, remember that you must put the
keystrokes into the Keystack before you run the program that
will receive them. The Keystack will hold the keystrokes
until the program asks for them.


File Selection

Most internal commands (like COPY, DIR, etc.) work on a file
or a group of files. Besides typing the exact name of the
file you want to work with, you can use several shorthand
forms for naming or selecting files: Extended Parent
Directory Names; Wildcards; Date, Time, and Size Ranges;
Multiple Filenames; Include Lists; and Executable Extensions.
These six features are explained in this section.

These features apply to 4DOS, 4OS2, and 4DOS/NT commands only,
and generally can not be used to pass file names to external
programs. For example, the file name ...\FILE.DAT uses an
extended parent directory name ("..."). It can be used in an
internal command like COPY or MOVE. However, your editor
probably was not designed to support this extension to
traditional directory names, and is likely to give an error
message if you try to pass it such a name.

Remember throughout this section that, if you are using DOS,
or the FAT file system under OS/2 or Windows NT, a filename is
a base name of 1 to 8 characters, optionally followed by an

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 56

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

extension which is a period [.] and 1 to 3 more characters.
On an HPFS or NTFS drive, file names can contain up to 255
characters, including spaces. If an HPFS or NTFS filename
includes spaces, you must place it in quotation marks on the
command line. (See page 13 for additional details on
filename formats and restrictions.)


Extended Parent Directory Names

4DOS, 4OS2, and 4DOS/NT allow you to extend the traditional
DOS ".." syntax for naming the parent directory, by adding
additional [.] characters. Each additional [.] represents an
additional directory level above the current directory. For
example, .\FILE.DAT refers to a file in the current directory,
..\FILE.DAT refers to a file one level up (in the parent
directory), and ...\FILE.DAT refers to a file two levels up
(in the parent of the parent directory). If you are in the
C:\DATA\FINANCE\JANUARY directory and want to copy the file
LETTERS.DAT from the directory C:\DATA to drive A:

C:\DATA\FINANCE\JANUARY>copy ...\LETTERS.DAT A:


Wildcards

Wildcards let you specify a file or group of files by typing a
partial filename. The appropriate directory is scanned to
find all of the files that match the partial name you have
specified.

Most internal commands accept filenames with wildcards
anywhere that a full filename can be used. There are two
wildcard characters, the asterisk [*] and the question mark
[?], plus a special method of specifying a range of
permissible characters.

An asterisk [*] in a filename means "any zero or more
characters in this position." For example, this command will
display a list of all files in the current directory:

c:\> dir *.*

If you want to see all of the files with a .TXT extension, you
could type this:

c:\> dir *.txt



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 57

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

If you know that the file you are looking for has a base name
that begins with ST and an extension that begins with .D, you
can find it this way. Filenames such as STATE.DAT,
STEVEN.DOC, and ST.D will all be displayed:

c:\> dir st*.d*

With 4DOS, 4OS2, or 4DOS/NT, you can also use the asterisk to
match filenames with specific letters somewhere inside the
name. The following example will display any file with a .TXT
extension that has the letters AM together anywhere inside its
base name. It will, for example, display AMPLE.TXT,
STAMP.TXT, CLAM.TXT, and AM.TXT:

c:\> dir *am*.txt

A question mark [?] matches any single filename character.
You can put the question mark anywhere in a filename and use
as many question marks as you need. The following example
will display files with names like LETTER.DOC and LATTER.DAT,
and LITTER.DU:

c:\> dir l?tter.d??

The use of an asterisk wildcard before other characters, and
of the character ranges discussed below, are enhancements to
the standard wildcard syntax, and are not likely to work
properly with software other than 4DOS, 4OS2, and 4DOS/NT.

## "Extra" question marks in your wildcard specification are
ignored if the file name is shorter than the wildcard
specification. For example, if you have files called
LETTER.DOC, LETTER1.DOC, and LETTERA.DOC, this command will
display all three names:

c:\> dir letter?.doc

The file LETTER.DOC is included in the display because the
"extra" question mark at the end of "LETTER?" is ignored when
matching the shorter name LETTER.

## In some cases, the question mark wildcard may be too general.
You can also specify what characters you want to accept (or
exclude) in a particular position in the filename by using
square brackets. Inside the brackets, you can put the
individual acceptable characters or ranges of characters. For
example, if you wanted to match LETTER0.DOC through
LETTER9.DOC, you could use this command:


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 58

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

c:\> dir letter[0-9].doc

You could find all files that have a vowel as the second
letter in their name this way. This example also demonstrates
how to mix the wildcard characters:

c:\> dir ?[aeiouy]*.*

You can exclude a group of characters or a range of characters
by using an exclamation mark [!] as the first character inside
the brackets. This example displays all filenames that are at
least 2 characters long except those which have a vowel as the
second letter in their names:

c:\> dir ?[!aeiouy]*.*

The next example, which selects files such as AIP, BIP, and
TIP but not NIP, demonstrates how you can use multiple ranges
inside the brackets. It will accept a file that begins with
an A, B, C, D, T, U, or V:

c:\> dir [a-dt-v]ip

## You may use a question mark character inside the brackets, but
its meaning is slightly different than a normal (unbracketed)
question mark wildcard. A normal question mark wildcard
matches any character, but will be ignored when matching a
name shorter than the wildcard specification, as described
above. A question mark inside brackets will match any
character, but will not be discarded when matching shorter
filenames. For example:

c:\> dir letter[?].doc

will display LETTER1.DOC and LETTERA.DOC, but not LETTER.DOC.

## You can repeat any of the wildcard characters in any
combination you desire within a single file name. For
example, the following command lists all files which have an
A, B, or C as the third character, followed by zero or more
additional characters, followed by a D, E, or F, followed
optionally by some additional characters, and with an
extension beginning with P or Q. You probably won't need to
do anything this complex, but we've included it to show you
the flexibility of extended wildcards:

c:\> dir ??[abc]*[def]*.[pq]*



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 59

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

4OS2 ## You can also use the square bracket wildcard syntax to work
4NT around a conflict between HPFS and NTFS filenames containing
semicolons [;], and the use of a semicolon to indicate an
include list (see page 65). For example, if you have a file
on an HPFS drive named C:\DATA\LETTER1;V2 and you enter this
command:

[c:\] del \data\letter1;v2

you will not get the results you expect. Instead of deleting
the named file, 4OS2 or 4DOS/NT will attempt to delete LETTER1
and then V2, because the semicolon indicates an include list.
However if you use square brackets around the semicolon it
will be interpreted as a filename character, and not as an
include list separator. For example, this command would
delete C:\DATA\LETTER1;V2:

[c:\] del \data\letter1[;]v2


Date, Time, and Size Ranges

Most internal commands which accept wild cards also allow
date, time, and size ranges to further define the files that
you wish to work with. 4DOS, 4OS2, and 4DOS/NT will examine
the files' timestamps (which record when the file was last
modified), and the files' sizes, to determine which files meet
the range criteria that you specify.

A range begins with the switch character (usually a slash
[/]), followed by a left square bracket ("[") and a character
that specifies the range type: "s" for a size range, "d" for
a date range, or "t" for a time range. The "s", "d", or "t"
is followed by a start value, and an optional comma and end
value. The range ends with a right square bracket ("]").

4DOS ! Ranges should not be used with the DEL /Q command under DOS.
See the notes under DEL on page 189 for additional details.


Size Ranges

Size ranges simply select files whose size is between the
limits given. For example, /[s10000,20000] selects files
between 10,000 and 20,000 bytes long.

Either or both values in a size range can end with "k" to
indicate thousands of bytes, "K" to indicate kilobytes (1,024
bytes), "m" to indicate millions of bytes, or "M" to indicate

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 60

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

megabytes (1,048,576 bytes). For example, the range above
could be rewritten as /[s10k,20k].

All ranges are inclusive. Both examples above will match
files that are exactly 10,000 bytes and 20,000 bytes long, as
well as all sizes in between.

The second argument of a size range is optional. If you use a
single argument, like /[s10k], you will select files of that
size or larger. You can also precede the second argument with
a plus sign [+]; when you do, it is added to the first value
to determine the largest file size to include in the search.
For example, /[s10k,+1k] select files from 10,000 through
11,000 bytes in size.

Some further examples of size ranges:

Specification Selects Files

/[s0,0] of length zero (empty)
/[s1M] 1 megabyte or more in length
/[s10k,+200] between 10,000 and 10,200 bytes


Date Ranges

Date ranges select files that were created or last modified at
any time between the two dates. For example,
/[d12-1-93,12-5-93] selects files that were last modified
between December 1, 1993, and December 5, 1993.

The time for the starting date defaults to 00:00:00 and the
time for the ending date defaults to 23:59:59. You can alter
these defaults, if you wish, by including a start and stop
time inside the date range. The time is separated from the
date with an at sign [@]. For example, the range
/[d7-1-94@8:00a,7-3-94@6:00p] selects files that were modified
at any time between 8:00 am on July 1, 1994 and 6:00 pm on
July 3, 1994. If you prefer, you can specify the times in 24-
hour format (e.g., @18:00 for the end time in the previous
example).

If you omit the second argument in a date range, the command
processor substitutes the current date and time. For example,
/[d10-1-93] selects files dated between October 1, 1993 and
today.

You can use an offset value for either the beginning or ending
date, or both. An offset begins with a plus sign [+] or a

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 61

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

minus sign [-] followed by an integer. If you use an offset
for the second value, it is calculated relative to the first.
If you use an offset for the first (or only) value, the
current date is used as the basis for calculation. For
example:

Specification Selects Files

/[d10-27-93,+3] modified between 10-27-93 and
10-30-93

/[d10-27-93,-3] modified between 10-24-93 and
10-27-93

/[d-0] modified today (from today minus zero
days, to today)

/[d-1] modified yesterday or today (from
today minus one day, to today)

/[d-1,+0] modified yesterday (from today minus
one day, to zero days after that)

You cannot use offsets in the time portion of a date range
(the part after an at sign), but you can combine a time with a
date offset. For example, /[d12-8-93@12:00,+2@12:00] selects
files that were last modified between noon on December 8 and
noon on December 10, 1993. Similarly, /[d-2@15:00,+1] selects
files last modified between 3:00 pm the day before yesterday
and the end of the day one day after that, i.e., yesterday.
The second time defaults to the end of the day because no time
is given.


Time Ranges

A time range specifies a file modification time without
reference to the date. For example, to select files modified
between noon and 2:00 pm on any date, use /[t12:00p,2:00p].
The times in a time range can either be in 12-hour format,
with a trailing "a" for AM or "p" for PM, or in 24-hour
format.

If you omit the second argument in a time range, you will
select files that were modified between the first time and the
current time, on any date. You can also use offsets,
beginning with a plus sign [+] or a minus sign [-] for either
or both of the arguments in a time range. The offset values
are interpreted as minutes. Some examples:

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 62

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

Specification Selects Files

/[t12:00p,+120] modified between noon and 2:00 PM on
any date
/[t-120,+120] modified between two hours ago and
the current time on any date
/[t0:00,11:59] modified in the morning on any date


Using Ranges

If you combine two types of ranges, a file must satisfy both
ranges to be included. For example, /[d2-8-94,2-9-94]
/[s1024,2048] means files last modified between February 8 and
February 9, 1994, which are also between 1,024 and 2,048 bytes
long.

When you use a date, time, or size range in a command, it
should immediately follow the command name. Unlike some
command switches which apply to only part of the command line,
the range usually applies to all file names specified for the
command. Any exceptions are noted in the descriptions of
individual commands.

For example, to get a directory of all the *.C files dated
October 1, 1993, you could use this command:

c:\> dir /[d10-1-93,+0] *.c

To delete all of the 0-byte files on your hard disk, you could
use this command:

c:\> del /[s0,0] *.* /s

And to copy all of the non-zero byte files that you changed
yesterday or today to your floppy disk, you can use this
command:

c:\> copy /[d-1] /[s1] *.* a:

Date, time, and size ranges can be used with the ATTRIB, COPY,
DEL, DESCRIBE, DIR, EXCEPT, FOR, LIST, MOVE, RD, REN, SELECT,
and TYPE commands. They cannot be used with filename
completion or in filename arguments for variable functions.

## It can be complex to type all of the elements of a range,
especially when it involves multiple dates and times. In this
case you may find it easier to use aliases for common
operations. For example, if you often wish to select from

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 63

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

.DAT files modified over the last three days and copy the
selected files to the floppy disk, you might define an alias
like this:

alias workback `select /[d-2] copy (*.dat) a:`

For more complex requirements, you may want to use internal
variables (e.g. _DATE or _TIME, see page 97) and variable
functions (e.g. @DATE, @TIME, @MAKEDATE, @MAKETIME, @FILEDATE,
@FILETIME, or @EVAL, see page 105). These variables and
functions allow you to perform arithmetic and date / time
calculations.


Multiple Filenames

Most file processing commands can work with multiple files at
one time. To use multiple file names, you simply list the
files one after another on the command line, separated by
spaces. You can use wildcards in any or all of the filenames.
For example, to copy all .TXT and .DOC files from the current
directory to drive A, you could use this command:

c:\> copy *.txt *.doc a:

If the files you want to work with are not in the default
directory, you must include the full path with each filename:

c:\> copy a:\details\file1.txt a:\details\file1.doc c:

Multiple filenames are handy when you want to match a group of
files which cannot be defined with a single filename and
wildcards. They let you be very specific about which files
you want to work with in a command.

! When you use multiple filenames with a command that expects
both a source and a destination, like COPY or MOVE, be sure
that you always include a specific destination on the command
line. If you don't, the command will assume that the last
filename is the destination and may overwrite important files.

Like extended wildcards and include lists (see below), the
multiple filename feature will work with internal commands but
not with external programs, unless those programs have been
written to handle multiple file names on the command line.

If you have a list of files to process that's too long to put
on the command line or too time-consuming to type, see the


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 64

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

SELECT command on page 299 for another way of passing multiple
file names to a command.


Include Lists

Any internal command that accepts multiple filenames will also
accept one or more include lists. An include list is simply a
group of filenames, with or without wildcards, separated by
semicolons [;]. All files in the include list must be in the
same directory. You may not add a space on either side of the
semicolon.

If you used an include list instead of multiple file names for
the previous examples, they would look like this:

c:\> copy *.txt;*.doc a:
c:\> copy a:\details\file1.txt;file1.doc c:

Include lists are similar to multiple filenames, but have
three important differences. First, you don't have to repeat
the path to your files if you use an include list, because all
of the included files must be in the same directory. Second,
if you use include lists, you aren't as likely to accidentally
overwrite files if you forget a destination path for commands
like COPY, because the last name in the list will be part of
the include list, and won't be seen as the destination file
name. (Include lists can only be used as the source parameter
- the location files are coming from - for COPY and other
similar commands. They cannot be used to specify a
destination for files.)

Third, multiple filenames and include lists are processed
differently by the DIR and SELECT commands. If you use
multiple filenames, all of the files matching the first
filename are processed, then all of the files matching the
second name, and so on. When you use an include list, all
files that match any entry in the include list are processed
together, and will appear together in the directory display or
SELECT list. You can see this difference clearly if you
experiment with both techniques and the DIR command. For
example,

c:\> dir *.txt *.doc

will list all the .TXT files with a directory header, the file
list, and a summary of the total number of files and bytes
used. Then it will do the same for the .DOC files. However,


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 65

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

c:\> dir *.txt;*.doc

will display all the files in one list.

Like extended wildcards and multiple filenames (see above),
the include list feature will work with internal commands, but
not with external programs (unless they have been programmed
especially to support it).


Executable Extensions

Normally, when you type a filename (as opposed to an alias or
internal command name) as the first word on the command line,
the command processor looks for a file with that name to
execute. The file's extension may be .EXE or .COM to indicate
that it contains a program, or it may have a batch file
extension like .BTM (under OS/2, a file's contents may also
indicate that it is executable).

The exact list of default extensions for executable files
varies slightly depending on which operating system you use,
because each has its own rules for batch file extensions(see
page 20 for details).

You can add to this default list of extensions, and have 4DOS,
4OS2, or 4DOS/NT take the action you want with files that are
not executable programs or batch files. The action taken is
always based on the file's extension. For example, you could
start your text editor whenever you type the name of a .DOC
file, or start your database manager whenever you type the
name of a .DAT file.

Environment variables define the internal command, external
program, batch file, or alias to run for each defined file
extension. To create an executable extension, use the SET
command to create a new environment variable. An environment
variable is recognized as an executable extension if its name
begins with a period.

For example, if you want to run a word processor called EDITOR
whenever you type the name of a file that has an extension of
.EDT, you could use this command:

c:\> set .edt=c:\edit\editor.exe

The syntax for creating an executable extension is:

set .ext=command [options]

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 66

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

where .EXT is the executable file extension; command is the
name of the internal command, external program, alias, or
batch file to run; and [options] are any command-line startup
options you want to specify for the program, batch file, or
alias.

If the command is a batch file or external program, the
command processor will search the PATH for it if necessary.
However, you can make sure that the correct program or batch
file is used, and speed up the executable extension, by
specifying the full name including drive, path, filename, and
extension.

Once an executable extension is defined, any time you name a
file with that extension the corresponding program, batch
file, or alias is started, with the name of your file passed
to it as a parameter.

The following example defines QBASIC.EXE as the processor for
.BAS files:

c:\> set .bas=c:\dos\qbasic.exe /run

With this definition, if you have a file named PUSHCART.BAS in
the current directory and enter the command:

c:\> pushcart

the command processor will execute the command:

c:\dos\qbasic.exe /run pushcart.bas

The next example defines B.EXE (the Brief text editor) as the
processor for .C files:

c:\> set .c=c:\brief\b.exe -Mxyz

Now, if you have a file called HELLO.C and enter the command

c:\> hello -i30

This will be expanded to:

c:\brief\b.exe -Mxyz hello.c -i30

Notice that the text from the .C environment variable is
inserted at the beginning of the line, including any options,
followed by the original file name plus its extension, and
then the remainder of the original command line.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 67

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

In order for executable extensions to work, the command,
program, batch file, or alias must be able to interpret the
command line properly. For example, if a program you want to
run doesn't accept a file name on its command line as shown in
these examples, then executable extensions won't work with
that program.

The search for executable files starts in the current
directory, then proceeds to each subdirectory specified by the
PATH environment variable (if a "." is used in the PATH the
current directory is not searched first; see the PATH command
on page 276 for details).

You may need to take this search order into account when using
executable extensions. Using the .BAS example above, if you
had a file named FORMAT.BAS in the current directory and
entered the command FORMAT A:, your command would run the
QBASIC processor specified by the executable extension,
instead of finding the standard DOS FORMAT command as you
intended. You can get around this by remembering that the DOS
FORMAT command is in the file FORMAT.COM. If you entered the
command FORMAT.COM A: then the .BAS executable extension would
not match, and the search would continue until it found the
FORMAT.COM file.

## Executable extensions may include wildcards, so you could, for
example, run your text editor for any file with an extension
beginning with T by defining an executable extension called
.T*. Extended wildcards (e.g., DO[CT] for .DOC and .DOT
files) may also be used.



## Advanced Features

The next three features are designed for advanced users. If
you are a novice user, you might want to skim over this
section and return to it as your computing skills and needs
progress.


Conditional Commands

When an internal command or external program finishes, it
returns a result called the exit code. Conditional commands
allow you to perform tasks based upon the previous command's
exit code. Many programs return a 0 if they are successful
and a non-zero value if they encounter an error.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 68

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

If you separate two commands by && (AND), the second command
will be executed only if the first returns an exit code of 0.
For example, the following command will only erase files if
the BACKUP operation succeeds:

c:\> backup c:\ a: && del c:\*.bak;*.lst

If you separate two commands by || (OR), the second command
will be executed only if the first returns a non-zero exit
code. For example, if the following BACKUP operation fails,
then ECHO will display a message:

c:\> backup c:\ a: || echo Error in the backup!

All internal commands return an exit code, but not all
external programs do. Conditional commands will behave
unpredictably if you use them with external programs which do
not return an explicit exit code.


Command Grouping

Command grouping allows you to logically group a set of
commands together by enclosing them in parentheses. The
parentheses are similar in function to the BEGIN and END block
statements in some programming languages.

There are two primary uses for command grouping. One is to
execute multiple commands in a place where normally only a
single command is allowed. For example, suppose you want to
copy then rename all the .WKQ files on drives A: and B: using
the FOR command. You could do it like this:

c:\> for %drv in (A B) do copy %drv:*.wkq d:\wksave\
c:\> for %drv in (A B) do ren %drv:*.wkq *.old

But with command grouping you can do the same thing in one
command (enter this on one line):

c:\> for %drv in (A B) do (copy %drv:*.wkq d:\wksave\
^ ren %drv:*.wkq *.sav)

The COPY and REN commands enclosed in the parentheses appear
to FOR as if they were a single command, so both commands are
executed for every element of the FOR list. (To try a command
like this under 4OS2 or 4DOS/NT, replace the caret [^] with an
ampersand [&].)



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 69

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

This kind of command grouping is most useful with the EXCEPT,
FOR, GLOBAL, and IF commands. You cannot use command grouping
to make SELECT execute several commands, because SELECT will
assume that the parentheses are marking the list of files from
which to select, and will display an error message or give
incorrect results if you try to use parentheses for command
grouping instead. (You can use a SELECT command inside the
command grouping parentheses, you just can't use command
grouping to specify a group of commands for SELECT to
execute.)

The second common use of command grouping is to redirect input
or output for several commands without repeatedly using the
redirection symbols. For example, consider the following
batch file fragment which places some header lines (including
today's date) and directory displays in an output file using
redirection. The first ECHO command creates the file using >,
and the other commands append to the file using >>:

echo Data files %_date > filelist
dir *.dat >> filelist
echo. >> filelist
echo Text files %_date >> filelist
dir *.txt >> filelist

Using command grouping, these commands can be written much
more simply. Enter this example on one line (use an ampersand
[&] as the command separator if you try this under 4OS2 or
4DOS/NT):

(echo Data files %_date ^ dir *.dat ^ echo. ^ echo Text
files %_date ^ dir *.txt) > filelist

The redirection, which appears outside the parentheses,
applies to all the commands within the parentheses. Because
the redirection is performed only once, the commands will run
slightly faster than if each command was entered separately.
The same approach can be used for input redirection and for
piping.

You can also use command grouping in a batch file or at the
prompt to split commands over several lines. This last
example is like the redirection example above, but is entered
at the prompt. Note the "More?" prompt after each incomplete
line. None of the commands are executed until the command
group is completed with the closing parenthesis. This example
does not have to be entered on one line:

c:\> (echo Data files %_date

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 70

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

More? dir *.dat
More? echo.
More? echo Text files %_date
More? dir *.txt) > filelist
c:\>

A group of commands in parentheses is like a long command
line. The total length of the group may not exceed 511
characters in 4DOS, or 2,047 characters in 4OS2 and 4DOS/NT,
whether the commands are entered from the prompt, an alias, or
a batch file. The limit includes the space required to expand
aliases and environment variables invoked within the group.
In addition, each line you type at the normal prompt or the
More? prompt, and each individual command within the line,
must meet the usual length limits: 255 characters in 4DOS, or
1,023 characters in 4OS2 and 4DOS/NT.


Escape Character

4DOS, 4OS2, and 4DOS/NT recognize a user-definable escape
character. This character gives the following character a
special meaning; it is not the same as the ASCII ESC that is
often used in ANSI and printer control sequences.

The default 4DOS escape character is Ctrl-X (ASCII 24), which
will be displayed here - and on your screen - as an up arrow
[-]. The default 4OS2 and 4DOS/NT escape character is a caret
[^].

If you don't like using the default escape character, you can
pick another character using the SETDOS /E command (see page
310) or the EscapeChar directive in your .INI file (see page
132). If you plan to share aliases or batch files between
4DOS, 4OS2, and 4DOS/NT, see page 72 for details about
choosing compatible escape characters for two or more
products.

Eight special characters are recognized when they are preceded
by the escape character. The combination of the escape
character and one of these characters is translated to a
single character, as shown below. These are useful for
redirecting codes to the printer; -e is also useful to
generate ANSI "escape sequences" in your PROMPT, ECHO, or
other output commands; and -r can be used in keystroke
aliases. The special characters which can follow the escape
character are:

b backspace

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 71

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

c comma
e the ASCII ESC character (ASCII 27)
f form feed
n line feed
r carriage return
s space
t tab character

If you follow the escape character with any other character,
the escape character is removed and the second character is
copied directly to the command line. This allows you to
suppress the normal meaning of special characters (such as ? *
/ \ | " ` > < and &).


For example, to send a form feed followed by the sequence ESC
Y to the printer, you can use this command:

c:\> echos -f-eY > prn


4DOS, 4OS2, and 4DOS/NT Compatibility

4DOS, 4OS2, and 4DOS/NT are highly compatible with each other.
However, there are minor differences between them. These
differences are caused by the different requirements of each
operating system and by our design goal of maintaining
compatibility between each product and the default command
processor which it replaces.

We discuss the differences between our products in this manual
as part of the description of each feature and command. Most
of the differences are minor: different command line lengths,
a few different options in some commands, and some commands
that only make sense in one or two products.

If you use two or more of our products, or if you want to
share aliases and batch files with users of different
products, you need to be aware of the differences in three
important characters: the Command Separator (see page 45),
the Escape Character (page 71), and the Parameter Character
(page 78).

The default values of each of these characters in each product
is shown in the following chart:

Character 4DOS Default 4OS2 and 4NT Default

Command Separator ^ &
Escape Character -(Ctrl-X) ^

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 72

CHAPTER 3 / USING 4DOS, 4OS2, AND 4DOS/NT
-------------------------------------------------------------------

Parameter Character & $

In your batch files and aliases, and even at the command line,
you can smooth over these differences in two ways:

* Select a consistent set of characters with .INI file
directives (see page 120) or the SETDOS command (page
308). For example, to set the 4DOS characters to
match 4OS2 and 4DOS/NT, use:

CommandSep = &
EscapeChar = ^
ParameterChar = $

in 4DOS.INI, or use the command:

SETDOS /C& /P$ /E-^

(Note the use of the old escape character [-] before
the new one [^]. This is because the new escape
character is also the old command separator, and will
be interpreted as the end of the command if it does
not have an escape character before it!)

* Use internal variables that contain the current
special character, rather than using the character
itself (see page 97). For example, this command:

if "%1" == "" (echo Argument missing! ^ quit)

will only work if the command separator is a caret.
However, this version works regardless of the current
command separator:

if "%1" == "" (echo Argument missing! %+ quit)

The following chart shows the correspondence between the
appropriate SETDOS command options, .INI file directives, and
internal variables:

Special SETDOS INI File Internal
Character Switch Directive Variable

Command Separator /C CommandSep %+
Escape Character /E EscapeChar %=
Parameter Character /P ParameterChar (none)




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 73

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------


CHAPTER 4 / ALIASES AND BATCH FILES


This chapter introduces two of the most powerful features of 4DOS,
4OS2, and 4DOS/NT: aliases and batch files. It also discusses the
environment (a list of information available to all programs),
along with the command processor's internal variables and variable
functions. The discussion of the environment, variables, and
variable functions is included in this chapter because they are
most often used in aliases and batch files.


Aliases

Much of the power of 4DOS, 4OS2, and 4DOS/NT comes together in
aliases, which give you the ability to create your own
commands. An alias is a name that you select for a command or
group of commands. Simple aliases substitute a new name for
an existing command. More complex aliases can redefine the
default settings of internal or external commands, operate as
very fast in-memory batch files, and perform commands based on
the results of other commands.

This section of the manual will show you some examples of the
power of aliases. See the ALIAS command (page 155) for
complete details about writing your own aliases.

The simplest type of alias gives a new name to an existing
command. For example, you could create a command called ROOT
to switch to the root directory this way:

c:\> alias root = cd \

After the alias has been defined this way, every time you type
the command ROOT, you will actually execute the command CD \.

Aliases can also create customized versions of commands. For
example, the DIR command can sort a directory in various ways.
You can create an alias called DE that means "sort the
directory by filename extension, and pause after each page
while displaying it" like this:

c:\> alias de = dir /oe /p

Aliases can be used to execute sequences of commands as well.
The following command creates an alias called W which saves
the current drive and directory, changes to the WP directory
on drive C, runs the program E:\WP60\WP.EXE, and, when the

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 74

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

program terminates, returns to the original drive and
directory:

c:\> alias w = `pushd c:\wp ^ e:\wp60\wp.exe ^ popd`

This alias is enclosed in back-quotes because it contains
multiple commands. You must use the back-quotes whenever an
alias contains multiple commands, environment variables,
parameters (see below), redirection, or piping. See the ALIAS
command for full details. Also, please note that throughout
this section we use the 4DOS command separator, a caret [^],
to separate multiple commands. If you are using 4OS2 or
4DOS/NT, substitute an ampersand [&] for the caret in the
examples.

Aliases can be nested, that is, one alias can invoke another.
For example, the alias above could also be written as:

c:\> alias wp = e:\wp60\wp.exe
c:\> alias w = `pushd c:\wp ^ wp ^ popd`

If you enter W as a command, the command processor will
execute the PUSHD command, detect that the next command (WP)
is another alias, and execute the program E:\WP60\WP.EXE, and
- when the program exits - return to the first alias, execute
the POPD command, and return to the prompt.

You can use aliases to change the default options for both
internal commands and external commands. Suppose that you
always want the DEL command to prompt before it erases a file:

c:\> alias del = *del /p

An asterisk [*] is used in front of the second "del" to show
that it is the name of an internal command, not an alias. See
page 157 for more information about this use of the asterisk.

You may have a program on your system that has the same name
as an internal command. Normally, if you type the command
name, you will start the internal command rather than the
program you desire, unless you explicitly add its full path on
the command line. For example, if you have a program named
LIST.COM in the C:\UTIL directory, you could run it with the
command C:\UTIL\LIST.COM. However, if you simply type LIST,
the internal LIST command will be invoked instead. Aliases
give you two ways to get around this problem.

First, you could define an alias that runs the program in
question, but with a different name:

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 75

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

c:\> alias l = c:\util\list.com

Another approach is to rename the internal command and use the
original name for the external program. The following example
renames the LIST command as DISPLAY and then uses a second
alias to run LIST.COM whenever you type LIST:

c:\> alias display = *list
c:\> alias list = c:\util\list.com

You can also assign an alias to a key, so that every time you
press the key, the command will be invoked. You do so by
naming the alias with an at sign [@] followed by a key name.
After you enter this next example, you will see a 2-column
directory with paging whenever you press Shift-F5, then Enter:

c:\> alias @Shift-F5 = *dir /2/p

This alias will put the DIR command on the command line when
you press Shift-F5, then wait for you to enter file names or
additional switches. You must press Enter when you are ready
to execute the command. You can change this alias so that it
executes the command immediately, and does not display it on
the command line or wait for you to type a filename. To do
so, use two at signs at the start of the alias name:

c:\> alias @@Shift-F5 = *dir /2/p

The next example clears the screen whenever you press Alt-F1:

c:\> alias @@Alt-F1 = cls

Aliases have many other capabilities as well. This example
creates a simple command-line calculator. Once you have
entered the example, you can type CALC 4*19, for example, and
you will see the answer:

c:\> alias calc = `echo The answer is: %@eval[%&]`

Our last example in this section creates an alias called IN.
It will temporarily change directories, run an internal or
external command, and then return to the current directory
when the command is finished:

c:\> alias in = `pushd %1 ^ %2& ^ popd`

Now if you type

c:\> in c:\letters wp letter.txt

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 76

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

you will change to the C:\LETTERS subdirectory, execute the
command WP LETTER.TXT and then return to the current
directory.

Your copy of 4DOS, 4OS2, or 4DOS/NT includes a sample alias
file called ALIASES which contains several useful aliases and
demonstrates many alias techniques. Also, see the ALIAS and
UNALIAS commands on pages 155 and 335 for more information and
examples. See page 84 for tips about using aliases inside
your batch files.


Batch Files

A batch file is a file that contains a list of commands to
execute. 4DOS, 4OS2, and 4DOS/NT read and interpret each line
as if it had been typed at the keyboard. Like aliases, batch
files are handy for automating computing tasks. Unlike
aliases, batch files can be as long as you wish. Batch files
take up separate disk space for each file, and can't usually
execute quite as quickly as aliases, since they must be read
from the disk.


.BAT, .CMD, and .BTM Files

A batch file can run in two different modes. In the first,
traditional mode, each line of the batch file is read and
executed individually. In the second mode, the entire batch
file is read into memory at once. The second mode can be 5 to
10 times faster, especially if most of the commands in the
batch file are internal commands. However, only the first
mode can be used for self-modifying batch files (which are
rare), for batch files which install memory-resident utilities
under DOS, and for batch files larger than 64K bytes.

The batch file's extension determines its mode. Files with a
.BAT extension (in 4DOS and 4DOS/NT), or a .CMD extension (in
4OS2 and 4DOS/NT) are run in the slower, traditional mode.
Files with a .BTM extension are run in the faster, more
efficient mode. You can change the execution mode inside a
batch file with the LOADBTM command (see page 263).








-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 77

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Echoing

By default, each line in a batch file is displayed or "echoed"
as it is executed. You can change this behavior, if you want,
in several different ways:

Any batch file line that begins with an [@] symbol will
not be displayed.

The display can be turned off and on within a batch file
with the ECHO OFF and ECHO ON commands.

The default setting can be changed with the SETDOS /V
command (see page 312) or the BatchEcho directive in the
.INI file (see page 131).

For example, the following line turns off echoing inside a
batch file. The [@] symbol keeps the batch file from
displaying the ECHO OFF command:

@echo off

Your command processor also has a command line echo that is
unrelated to the batch file echo setting. See the ECHO
command on page 214 for details about both settings.


Batch File Parameters

Like aliases and application programs, batch files can examine
the command line that is used to invoke them. The command
tail (everything on the command line after the batch file
name) is separated into individual parameters (also called
arguments or batch variables) by scanning for the spaces,
tabs, and commas that separate the parameters. A batch file
can work with the individual parameters or with the command
tail as a whole.

These parameters are numbered from %1 to %127. %1 refers to
the first parameter on the command line, %2 to the second, and
so on. It is up to the batch file to determine the meaning of
each parameter. You can use quotation marks to pass spaces,
tabs, commas, and other special characters in a batch file
parameter; see page 118 for details.

Parameters that are referred to in a batch file, but which are
missing on the command line, appear as empty strings inside
the batch file. For example, if you start a batch file and
put two parameters on the command line, any reference in the

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 78

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

batch file to %3, or any higher-numbered parameter, will be
interpreted as an empty string.

A batch file can also work with three special parameters: %0
contains the name of the batch file as it was entered on the
command line, %# contains the number of command line
arguments, and in 4DOS %n& contains the complete command-line
tail starting with argument number "n" (for example, %3& means
the third parameter and all those after it). The default
value of "n" is 1, so %& contains the entire command tail.
The values of these special parameters will change if you use
the SHIFT command (see page 316).

4OS2, By default, 4OS2 and 4DOS/NT use a dollar sign [$] instead of
4NT an ampersand [&] to indicate the remainder of the command
tail. For example, %$ means all the parameters, and %2$ means
the second parameter and all those after it. If you want to
share batch files or aliases between 4DOS and these command
processors, you can select a new character for any product
with the SETDOS /P command (see page 311) or the ParameterChar
directive in your .INI file (see page 134).

For example, if your batch file interprets the first argument
as a subdirectory name then the following line would move to
the specified directory:

cd %1

A friendlier batch file would check to make sure the directory
exists and take some special action if it doesn't:

iff isdir %1 then ^ cd %1
else ^ echo Subdirectory %1 does not exist! ^ quit
endiff

(see the IF and IFF commands on pages 238 and 244).

## Batch files can also use environment variables, internal
variables, and variable functions. See pages 97 - 115 for a
complete list of the internal variables and variable functions
available. You can use these variables and functions to
determine system status (e.g., the type of CPU in the system),
resource levels (e.g., the amount of free disk space), file
information (e.g., the date and time a file was last
modified), and other information (e.g., the current date and
time). You can also perform arithmetic operations (including
date and time arithmetic), manipulate strings and substrings,
extract parts of a filename, and perform simple file access.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 79

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

## To create temporary variables for use inside a batch file,
just use the SET command to store the information you want in
an environment variable. Pick a variable name that isn't
likely to be in use by some other program (for example, PATH
would be a bad choice), and use the UNSET command (page 336)
to remove these variables from the environment at the end of
your batch file. You can use SETLOCAL (page 315) and ENDLOCAL
(page 217) to create a "local" environment so that the
original environment will be restored when your batch file is
finished.

## Environment variables used in a batch file may contain either
numbers or text. It is up to you to keep track of what's in
each variable and use it appropriately; if you don't (for
example, if you use %@EVAL to add a number to a text string),
you'll get an error message.


Batch File Commands

Several 4DOS, 4OS2, and 4DOS/NT commands are particularly
suited to batch file processing. Each command is explained in
detail in the Command Reference section of this manual,
beginning on page 146. Here is a list of some of the commands
you might find most useful:

BEEP produces a sound of any pitch and duration through
the computer's speaker.

CALL executes one batch file from within another.

CANCEL terminates all batch file processing.

CLS and COLOR set the screen display colors.

DO starts a loop. The loop can be based on a counter, or
on a conditional test like those used in IF and IFF.

DRAWBOX draws a box on the screen.

DRAWHLINE and DRAWVLINE draw horizontal and vertical
lines on the screen.

ECHO and ECHOS print text on the screen (the text can
also be redirected to a file or device).

GOSUB executes a subroutine inside a batch file. The
RETURN command terminates the subroutine.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 80

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

GOTO branches to a different location in the batch file.

FOR executes commands for each file that matches a set of
wildcards, or each entry in a list.

IF and IFF execute commands based on a test of string or
numeric values, program exit codes, or other conditions.

INKEY and INPUT collect keyboard input from the user and
store it in environment variables.

KEYSTACK places keystrokes into the 4DOS Keystack.

LOADBTM changes the batch file operating mode.

ON initializes error handling for Ctrl-C / Ctrl-Break, or
for program and command errors.

PAUSE displays a message and waits for the user to press
a key.

QUIT ends the current batch file and optionally returns
an exit code.

REM places a remark in a batch file.

SCREEN positions the cursor on the screen and optionally
prints a message at the new location.

SCRPUT displays a message in color.

SETLOCAL saves the current disk drive, default directory,
environment, and alias list. ENDLOCAL restores the
settings that were saved.

SHIFT changes the numbering of the parameters.

START starts another session or window in certain
multitasking environments.

TEXT displays a block of text. ENDTEXT ends the block.

TIMER starts or reads a stopwatch.

VSCRPUT displays a vertical message in color.

These commands, along with the internal variables and variable
functions, make the enhanced batch file language extremely
powerful. Your copy of 4DOS, 4OS2, or 4DOS/NT includes a

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 81

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

number of sample batch files, combined in the file
SAMPLES.BTM, that demonstrate some of the many things you can
do with batch files.


Interrupting a Batch File

You can usually interrupt a batch file by pressing Ctrl-C or
Ctrl-Break. Whether and when these keystrokes are recognized
will depend on whether the command processor or an application
program is running, how the application (if any) was written,
whether BREAK is ON or OFF under DOS (see page 171), and
whether the ON BREAK command is in use (see page 274).

If 4DOS, 4OS2, or 4DOS/NT detects a Ctrl-C or Ctrl-Break (and
ON BREAK is not in use), it will display a prompt, for
example:

Cancel batch job C:\CHARGE.BTM ? (Y/N/A) :

Enter N to continue, Y to terminate the current batch file and
continue with any batch file which called it, or A to end all
batch file processing regardless of the batch file nesting
level. Answering Y is similar to the QUIT command (page 287);
answering A is similar to the CANCEL command (page 174).


Automatic Batch Files

4DOS, 4OS2, and 4DOS/NT support three "automatic" batch files,
files that run without your intervention, as long as the
command processor can find them.

Each time 4DOS, 4OS2, or 4DOS/NT starts as either a primary or
a secondary shell, it looks for an automatic batch file called
4START.BTM, 4START.BAT (for 4DOS), or 4START.CMD (for 4OS2 and
4DOS/NT). If the 4START batch file is not in the same
directory as your command processor itself, you should use the
4StartPath directive in your .INI file (see page 125) to
specify its location. 4START is optional, so the command
processor will not display an error message if it cannot find
the file.

4START is a convenient place to change the color or content of
the prompt for each shell, LOG the start of a shell, or put
other special startup or configuration commands. Under 4OS2
and 4DOS/NT, it is one way to set aliases and environment
variables (under 4DOS, these are normally set in
AUTOEXEC.BAT).

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 82

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

## With the exception of some 4DOS initialization switches, the
entire startup command line passed to the command processor is
available to 4START via batch file parameters (%1, %2, etc.).
This can be useful if you want to see the command line passed
to a secondary shell by an application. For example, to pause
if any parameters are passed to a secondary shell you could
include this command in 4START (enter this on one line):

if "%1" != "" .and. "%_shell" gt 0 pause Starting shell
%_shell with parameters [%&]

4DOS Whenever it is started as a primary shell, 4DOS runs
AUTOEXEC.BAT immediately after 4START. On a DOS system,
AUTOEXEC.BAT runs each time the computer boots up. (If
COMMAND.COM cannot find AUTOEXEC.BAT, it asks you for the time
and date. 4DOS skips that step and immediately displays a
prompt.)

Normally, AUTOEXEC.BAT must be in the root directory of the
boot drive. You can store it in a different location (and
even give it a different name) by using the 4DOS.INI directive
AutoExecPath (see page 125). You can also pass parameters to
AUTOEXEC.BAT using the AutoExecParms directive in 4DOS.INI.

4OS2 and 4DOS/NT do not execute AUTOEXEC.BAT.

Whenever a 4DOS, 4OS2, or 4DOS/NT shell ends, it runs a third
automatic batch file called 4EXIT.BTM, 4EXIT.BAT (for 4DOS),
or 4EXIT.CMD (for 4OS2 and 4DOS/NT). This file, if you use
it, should be in the same directory as your 4START batch file.
Like 4START, 4EXIT is optional. It is not necessary in most
circumstances, but it is a convenient place to put commands to
save information such as a history list before a shell ends,
or LOG the end of the shell.

Under 4DOS, 4START and 4EXIT should not load any memory
resident programs (TSRs). Otherwise, these three files can
include any commands that could be part of any batch file or
any commands which you could type from the command line.


## Detecting 4DOS, 4OS2, or 4DOS/NT

From a batch file, you can determine if 4DOS, 4OS2, or 4DOS/NT
is loaded by testing for the variable function @EVAL, with a
test like this:

if "%@eval[2+2]" == "4" echo 4DOS is loaded!


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 83

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

This test can never succeed in COMMAND.COM or CMD.EXE. Other
variable functions could be used for the same purpose.


## Using Aliases in Batch Files

One way to simplify batch file programming is to use aliases
to hide unnecessary detail inside a batch file. For example,
suppose you want to implement a multiple choice list in a
batch file that will let you select among several different
applications. This example shows one way to do so:

alias in `pushd %1 ^ %2& ^ popd`
alias choice `elseiff "%userchoice"=="%1" then`
:dispmenu
screen 8 0
text
Enter your choice:
1. Word Processing
2. Spreadsheet
3. Communications
endtext
inkey %%userchoice
iff "1"=="2" then ^ rem Always fail and go to next line
choice 1 ^ in d:\letters c:\wp60\wp.exe
choice 2 ^ in d:\finance c:\quattro\q.exe
choice 3 ^ in d:\comm c:\comsw\pcplus.exe
else
scrput 23 0 bri whi on red Invalid choice, try again
goto dispmenu
endiff
unalias in choice

The first alias, IN, expects 2 or more command-line arguments.
It uses the first as a new working directory and changes to
that directory with a PUSHD command. The rest of the command
line is interpreted as another command plus possible command
line parameters, which the alias executes. This alias could
be used from the command line.

The second alias, CHOICE, expects one command-line argument.
It tests whether an environment variable called userchoice has
the same value as the command-line argument. This alias is
designed just for this particular batch file. If you try to
use CHOICE from the command line, you will see an error
because the alias uses ELSEIFF and THEN without the necessary
IFF and ENDIFF to define a block. (The last line of the batch
file "cleans up" by removing IN and CHOICE from the alias
list.)

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 84

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

The next 9 lines print a menu on the screen and then get a
keystroke from the user and store the keystroke in an
environment variable called userchoice. Then the batch file
tests the user's keystroke to decide what action to take.

Since the CHOICE alias starts with an ELSEIFF command, there
has to be an IFF. But the first condition must fail in order
to get to the ELSEIFF command in the first CHOICE alias, so
the IFF statement starts with a condition that will always be
false. The three lines after the IFF are easy to follow and
much shorter than they would be without the aliases. If it
had to be typed in full, the first choice line would look like
this:

elseiff "%userchoice"=="1" then pushd d:\letters ^
c:\wp60\wp.exe ^ popd

There's another side to aliases in batch files. If you're
going to distribute your batch files to others, you need to
remember that they may have aliases defined for the commands
you're going to use. For example if the user has aliased CD
to CDD and you aren't expecting this, your file may not work
as you intended. There are two ways to address this problem.
First, you can use SETLOCAL, ENDLOCAL, and UNALIAS to clear
out aliases before your batch file starts and restore them at
the end. For example:

setlocal
unalias *
rem Aliases cleared, set up new aliases
alias ...
rem Other batch file commands go here
endlocal

Remember that SETLOCAL and ENDLOCAL will save and restore not
only the aliases but also the environment and the current
drive and directory.

If this method isn't appropriate or necessary for the batch
file you're working on, you can also use an asterisk [*]
before the name of any command. The asterisk means the
command that follows it should not be interpreted as an alias.
For example the following command redirects a list of file
names to the file FILELIST:

dir /b > filelist




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 85

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

However, if the user has redefined DIR with an alias this
command may not do what you want. To get around this just
use:

*dir /b > filelist

The same can be done for any command in your batch file. If
you use the asterisk, it will disable alias processing, and
the rest of the command will be processed normally as an
internal command, external command, or batch file. Using an
asterisk before a command will work whether or not there is
actually an alias defined with the same name as the command.
If there is no alias with that name, the asterisk will be
ignored and the command will be processed as if the asterisk
wasn't there.


## Debugging Batch Files

There are several tricks you can use in debugging batch files.
Probably the simplest is to turn ECHO on at the beginning of
the file while you're testing it, or use SETDOS /V2 to force
ECHO on even if an ECHO OFF command is used in the batch file.
This will give you a picture of what is happening as the file
is executed. It will make your output look messy of course,
so just turn it off once things are working. You can also
turn ECHO on at the beginning of a group of commands you want
to "watch", and off at the end, just by adding ECHO commands
at the appropriate spots in your file.

You can also use the SETDOS /Y1 command to single step through
all or part of a batch file (see page 313). Insert the
command at the beginning of the portion of the batch file that
you wish to single-step through, and add a SETDOS /Y0 command
at the end of the section. After 4DOS, 4OS2, or 4DOS/NT
executes the SETDOS command, it will display each command
before it is executed, followed by a Y/N/R prompt. Press Y to
execute the command, N to skip the command and go on to the
next, or R to execute the remainder of the batch file up to
the next SETDOS /Y1 command without further prompting. You
can also press Ctrl-C or Ctrl-Break at the Y/N/R prompt to
halt execution of the remainder of the batch file and return
to the command processor prompt.

Another trick is to insert PAUSE commands wherever you need
them in order to be able to watch what's happening. For
complex debugging, you can make an alias that uses INKEY for a
similar purpose, but helps you out a little more. For example


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 86

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

(enter this on one line, and use an ampersand [&] as the
command separator if you are using 4OS2 or 4DOS/NT):

alias step `set skey=^ inkey Step: %%skey ^ iff
"%skey"=="S" then ^ set /P ^ elseiff "%skey"=="X"
then ^ quit ^ endiff`

Now anywhere you insert a STEP command in your file you'll get
the Step: prompt during execution. At that point you can type
S to do a SET /P and display the current contents of your
environment variables, X to exit the batch file, and any other
key to go on. (Of course you may need to modify this alias to
fit your particular needs.)

If you can't figure out how your aliases and variables are
expanded, try turning LOG on at the start of the batch file.
LOG keeps track of all commands after alias and variable
expansion are completed, and gives you a record in a file that
you can examine after the batch file is done. If you simply
want to see a record of what commands are executed, without
the expansion, use LOG /H.

You may also want to consider using redirection to capture
your batch file output. Simply type the batch file name
followed by the redirection symbols, for example:

c:\> mybatch >& testout

This records all batch file output, including error messages,
in the file TESTOUT, so you can go back and examine it. If
you have ECHO ON in the batch file you'll get the batch
commands intermingled with the output, which can provide a
very useful trace of what's happening. Of course, output from
full-screen commands and programs that don't write to the
standard output devices can't be recorded, but you can still
gain a lot of useful information if your batch file does much
output.

If you're using redirection to see the output, remember that
any prompts for input will probably go to the output file and
not to the screen, so you need to know in advance the sequence
of keystrokes required to get through the entire batch file,
and enter them by hand or with KEYSTACK. (As an example, the
raw text for the Guided Tour distributed with new copies of
4DOS, 4OS2, and 4DOS/NT was created by writing a 4DOS batch
file containing the demonstration commands, testing it to get
the proper keystroke sequence, and executing a command which
used KEYSTACK to send the keystrokes and redirected the batch
file's output to a disk file.)

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 87

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

## Batch File String Processing

As you gain experience with batch files, you're likely to find
that you need to manipulate text strings. You may need to
prompt a user for a name or password, process a list of files,
or find a name in a phone list. All of these are examples of
string processing - the manipulation of lines of readable
text.

4DOS, 4OS2, and 4DOS/NT include several features that make
string processing easier. For example, you can use the INKEY
and INPUT commands for user input; the ECHO, SCREEN, SCRPUT,
and VSCRPUT commands for output; and the FOR command or the
@FILEREAD function to scan through the lines of a file. In
addition, variable functions offer a wide range of string
handling capabilities (see page 105 for full details).

For example, suppose you need a batch file that will prompt a
user for a name, break the name into a first name and a last
name, and then run a hypothetical LOGIN program. LOGIN
expects the syntax /F:first /L:last with both the first and
last names in upper case and neither name longer than 8
characters. Here is one way to write such a program:

@echo off
setlocal
unalias *
input Enter your name (no initials): %%name

set first=%@word[%name,0]
set flen=%@len[%first]
set last=%@word[%name,1]
set llen=%@len[%last]

iff %flen gt 8 .or. %llen gt 8
echo First or last name too long
quit
endiff

login /F:%@upper[%first] /L:%@upper[%last]
endlocal

The SETLOCAL command at the beginning of this batch file saves
the environment and aliases. Then the UNALIAS * command
removes any existing aliases so they won't interfere with the
behavior of the commands in the remainder of the batch file
(you can accomplish the same thing by using an asterisk [*] in
front of each command). The first block of lines ends with an


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 88

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

INPUT command which asks the user to enter a name. The user's
input is stored in the environment variable NAME.

The second block of lines extracts the user's first and last
names from the NAME variable and calculates the length of
each. It stores the first and last name, along with the
length of each, in additional environment variables. Note
that the @WORD function numbers the first word as 0, not as 1.

The IFF command in the third block of lines tests the length
of both the first and last names. If either is longer than 8
characters, the batch file displays an error message and ends.
Finally, in the last block, the batch file executes the LOGIN
program with the appropriate parameters, then uses the
ENDLOCAL command to restore the original environment and alias
list. At the same time, ENDLOCAL discards the temporary
variables that the batch file used (NAME, FIRST, FLEN, etc.).

When you're processing strings, you also need to avoid some
common traps. The biggest one is handling special characters.

Suppose you have a batch file with these two commands, which
simply accept a string and display it:

input Enter a string: %%str
echo %str

Those lines look safe, but what happens if the user enters the
string "some > none" (without the quotes). After the string
is placed in the variable STR, the second line becomes

echo some > none

The ">" is a redirection symbol, so the line echoes the string
"some" and redirects it to a file called NONE - probably not
what you expected. You could try using quotation marks (see
page 118) to avoid this kind of problem, but that won't quite
work. If you use back-quotes (ECHO `%STR`), the command will
echo the four-character string %STR. Environment variable
names are not expanded (replaced by their contents, see page
116) when they are inside back-quotes.

If you use double quotes (ECHO "%STR"), the string entered by
the user will be displayed properly, and so will the quotation
marks. With double quotes, the output would look like this:

"some > none"



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 89

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

As you can imagine, this kind of problem becomes much more
difficult if you try to process text from a file. Special
characters in the text can cause all kinds of confusion in
your batch files. Text containing back-quotes, double quotes,
or redirection symbols can be virtually impossible to handle
correctly.

One way to overcome these potential problems is to use the
SETDOS /X command (see page 312) to temporarily disable
redirection symbols and other special characters. The two-
line batch file above would be a lot more likely to produce
the expected results if it were rewritten this way:

setdos /x-15678
input Enter a string: %%str
echo %str
setdos /x0

The first line turns off alias processing and disables several
special symbols, including the command separator and all
redirection symbols. Once the string has been processed, the
last line re-enables the features that were turned off in the
first line.

If you need advanced string processing capabilities beyond
those provided by 4DOS, 4OS2, and 4DOS/NT, you may want to
consider using the REXX language. Our products support
external REXX programs for this purpose; see page 92 for
additional details.


## Batch File Compression

You can compress your .BTM files with a program called
BATCOMP.EXE, which is distributed with 4DOS, 4OS2, and
4DOS/NT. This program condenses batch files by about a third
and makes them unreadable with the LIST command and similar
utilities. Compressed batch files run at approximately the
same speed as regular .BTM files.

You may want to consider compressing batch files if you need
to distribute them to others and keep your original code
secret or prevent your users from altering them. You may also
want to consider compressing batch files to save some disk
space on the systems where the compressed files are used.
(However, you will not save space if you keep your compressed
batch files on a disk compressed with a program like DBLSPACE,
Stacker, or SuperStor.)


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 90

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

The full syntax for the batch compression program is

BATCOMP [/O] input file [output file]

You must specify the full name of the input file, including
its extension, on the BATCOMP command line. If you do not
specify the output file, BATCOMP will use the same base name
as the input file and add a .BTM extension. BATCOMP will also
add a .BTM extension if you specify a base name for the output
file without an extension. For example, to compress
MYBATCH.BAT and save the result as MYBATCH.BTM, you can use
any of these three commands:

c:\> batcomp mybatch.bat
c:\> batcomp mybatch.bat mybatch
c:\> batcomp mybatch.bat mybatch.btm

If the output file (MYBATCH.BTM in the examples above) already
exists, BATCOMP will prompt you before overwriting the file.
You can disable the prompt by including /O on the BATCOMP
command line immediately before the input file name. Even if
you use the /O option, BATCOMP will not compress a file into
itself.

JP Software does not provide a decompression utility to
uncompress batch files. If you use BATCOMP.EXE, make sure
that you also keep a copy of the original batch file for
future inspection or modification.

You can adopt one of two strategies for keeping track of your
original source files and compressed batch files. First, you
may want to create the source files with a traditional .BAT or
.CMD extension and reserve the .BTM extension for compressed
batch files. The advantage of this approach is that you can
modify and test the uncompressed versions at any time,
although they will run in the slower, traditional mode unless
they begin with a LOADBTM command (see page 263).

If you prefer, you can use a .BTM extension for both the
source and compressed files. In this case you will have to
use a different base name for each file. For example, you
might use MYBATCHS.BTM for the source file and MYBATCH.BTM for
the compressed file. This may make it more difficult to keep
track of the correspondence between the source file and the
compressed file, but it allows both files to run automatically
in the high-speed .BTM mode.

Each of our command processors includes its own version of
BATCOMP.EXE, set up to run under the corresponding operating

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 91

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

system. However, the output produced by each program is the
same, so a batch file compressed with any version of BATCOMP
can be used with any JP Software command processor.

If you plan to distribute batch files to users of different
platforms, be sure to read the compatibility discussion on
page 72.


## REXX Support

REXX is a a powerful file and text processing language
developed by IBM, and available on many PC and other
platforms. You can invoke REXX programs from 4DOS, 4OS2, or
4DOS/NT. REXX is an ideal extension to the 4DOS, 4OS2, and
4DOS/NT batch language, especially if you need advanced string
processing capabilities.

The REXX language is not built into 4DOS, 4OS2, or 4DOS/NT.
Under DOS and Windows NT, you must have a copy of Personal
REXX from Quercus Systems in Saratoga, CA in order to use the
REXX language. Under IBM OS/2 1.3 and above you can use the
built-in REXX language provided by IBM, or use Quercus's
Personal REXX for OS/2. (Personal REXX is available from JP
Software or directly from Quercus Systems.)

4DOS Under 4DOS, REXX programs are stored in .REX files. To enable
REXX support you must install Personal REXX, and define an
executable extension (see page 66) that tells 4DOS to load
Personal REXX when you invoke a .REX file. For example:

set .rex=c:\prexx\rexx.exe

4OS2 Under 4OS2, REXX programs are stored in .CMD files. 4OS2
checks to see if the first two characters on the first line of
a .CMD file are [/*], the beginning of a REXX comment. If so,
it passes the file to OS/2's built-in REXX facility for
processing. If Personal REXX for OS/2 is installed, it
automatically replaces OS/2's built-in REXX, and handles all
REXX commands passed by 4OS2.

4NT Under 4DOS/NT, REXX programs may be stored in .CMD or .REX
files. 4DOS/NT checks to see if the first two characters on
the first line of a .CMD or .REX file are [/*]. If so, it
passes the file to Personal REXX for Windows NT for
processing. You must have Personal REXX for Windows NT
installed to enable 4DOS/NT's REXX support.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 92

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Both Personal REXX and OS/2's built-in REXX extend the
interface between REXX and the command processor by allowing
you to invoke 4DOS, 4OS2, or 4DOS/NT commands from within a
REXX program. For details, or for more information on any
aspect of REXX, see your Personal REXX or OS/2 REXX
documentation.


4OS2 ## EXTPROC Support
4NT
4OS2 and 4DOS/NT offer an external processor (EXTPROC) option
for batch files that lets you define an external program to
process a particular .CMD file. To identify a .CMD file to be
used with an external processor, place the string "EXTPROC" as
the first word on the first line of the file, followed by the
name of the external program that should be called. The
command processor will start the program and pass it the name
of the .CMD file and any command-line arguments that were
entered.

For example, suppose GETDATA.CMD contains the following lines:

EXTPROC D:\DATAACQ\DATALOAD.EXE
OPEN PORT1
READ 4000
DISKWRITE D:\DATAACQ\PORT1\RAW

Then if you entered the command:

[d:\dataacq] getdata /p17

The command processor would read the GETDATA.CMD file,
determine that it began with an EXTPROC command, read the name
of the processor program, and then execute the command:

D:\DATAACQ\DATALOAD.EXE D:\DATAACQ\GETDATA.CMD /p17

The hypothetical DATALOAD.EXE program would then be
responsible for reopening the GETDATA.CMD file, ignoring the
EXTPROC line at the start, and interpreting the other
instructions in the file. It would also have to respond
appropriately to the command-line parameter entered (/p17).

Do not try to use 4OS2 or 4DOS/NT as the external processor
named on the EXTPROC line in the .CMD file. They will
interpret the EXTPROC line as a command to re-open themselves.
The result will be an infinite loop that will continue until
the computer runs out of resources and locks up.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 93

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Using the Environment

The environment is a collection of information about your
computer that every program receives. Each entry in the
environment consists of a variable name, followed by an equal
sign and a string of text. You can automatically substitute
the text for the variable name in any command. To create the
substitution, include a percent sign [%] and a variable name
on the command line or in an alias or batch file. For
example, you can create a variable named BACKUP like this:

c:\> set BACKUP=*.bak;*.bk!;*.bk

If you then type

c:\> del %BACKUP

it is equivalent to the following command:

del *.bak;*.bk!;*.bk

## The variable names you use this way may contain any alphabetic
or numeric characters, the underscore character [_], and the
dollar sign [$]. You can force acceptance of other characters
by including the full variable name in square brackets, like
this: %[AB##2]. You can also "nest" environment variables
using square brackets. For example %[%var1] means "the
contents of the variable whose name is stored in VAR1". A
variable referenced with this technique cannot contain more
than 255 characters of information. Nested variable expansion
can be disabled with the SETDOS /X command (see page 312).

In 4DOS, the size of the environment is specified by the
Environment and EnvFree directives in 4DOS.INI (see page 126)
or by the /E: startup switch (see the 4DOS Introduction and
Installation Guide). In 4OS2 and 4DOS/NT the size of the
environment is set automatically.

## Environment variables may contain alias names. The command
processor will substitute the variable value for the name,
then check for any alias name which may have been included
within the variable's value. For example, the following
commands would generate a 2-column directory of the .TXT
files:

c:\> alias d2 dir /2
c:\> set cmd=d2
c:\> %cmd *.txt


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 94

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

## The trailing percent sign that was traditionally required for
environment variable names is not usually required in 4DOS,
4OS2, or 4DOS/NT, which accept any character that cannot be
part of a variable name as the terminator. However, the
trailing percent can be used to maintain compatibility.

The trailing percent sign is needed if you want to join two
variable values. The following examples show the possible
interactions between variables and literal strings. First,
create two environment variables called ONE and TWO this way:

c:\> set ONE=abcd
c:\> set TWO=efgh

Now the following combinations produce the output text shown:

%ONE%TWO abcdTWO ("%ONE%" + "TWO")
%ONE%TWO% abcdTWO ("%ONE%" + "TWO%")
%ONE%%TWO abcdefgh ("%ONE%" + "%TWO")
%ONE%%TWO% abcdefgh ("%ONE%" + "%TWO%")
%ONE%[TWO] abcd[TWO] ("%ONE%" + "[TWO]")
%ONE%[TWO]% abcd[TWO] ("%ONE%" + "[TWO]%")
%[ONE]%TWO abcdefgh ("%[ONE]" + "%TWO")
%[ONE]%TWO% abcdefgh ("%[ONE]" + "%TWO%")

## If you want to pass a percent sign to a command, or a string
which includes a percent sign, you must use two percent signs
in a row. Otherwise, the single percent sign will be seen as
the beginning of a variable name and will not be passed on to
the command. For example, to display the string "We're with
you 100%" you would use the command:

echo We're with you 100%%

You can also use back-quotes around the text, rather than a
double percent sign. See page 118 for details.

4DOS Each copy of the command processor maintains its own copy of
the environment. The copy of the environment maintained by
the primary shell is called the master environment. When
using a secondary shell, 4DOS will allow you to access the
master environment in the primary shell with the commands SET
/M (page 305), UNSET /M (page 336), and ESET /M (page 218),
and with the %@MASTER variable function (page 112). Master
environment access is not available in 4OS2 or 4DOS/NT.





-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 95

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Configuration Variables

The following environment variables have special meanings in
4DOS, 4OS2, and 4DOS/NT.

CDPATH tells the command processor where to search for
directories specified by the CD, CDD, and PUSHD commands
and in automatic directory changes. (_CDPATH can be used
as an alternative to CDPATH if you are using Microsoft
Bookshelf, which uses a CDPATH variable for its own
purposes.) CDPATH is composed of a list of directories,
separated by semicolons [;]. See page 43 for more
information about using CDPATH.

CMDLINE is the fully expanded text of the currently
executing command line. CMDLINE is set just before
invoking any .COM, .EXE, .BTM, .BAT, or .CMD file. If a
command line is prefaced with an "@" to prevent echoing
(see page 37), it will not be put in CMDLINE, and any
previous CMDLINE variable will be removed from the
environment. Under DOS, this allows you to squeeze out
the last few bytes of environment space before loading
TSRs by prefacing each TSR command with an "@".

COLORDIR controls directory display colors used by DIR
and SELECT. See page 30 for a complete description of
the format of this variable.

COMSPEC contains the full path and name of the command
processor. COMSPEC is most commonly used by applications
which have a "shell to the command prompt" feature. For
details on how COMSPEC is set and used, see your
Introduction and Installation Guide.

DIRCMD is used by some versions of COMMAND.COM and
CMD.EXE to hold default options for the DIR command.
4DOS and its cousins do not support this variable, but
you can achieve the same effect with an alias. For
example, if you want the DIR command to default to a 2-
column display with a vertical sort and a pause at the
end of each page, you could use this alias:

c:\> alias dir = `*dir /2/p/v`

If you wish to continue to use DIRCMD for compatibility
with systems that do not use 4DOS, you can define the
alias this way:

c:\> alias dir = `*dir %dircmd`

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 96

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

PATH is a list of directories that 4DOS, 4OS2, or 4DOS/NT
will search for executable files that aren't in the
current directory. PATH may also be used by some
application programs to find their own files. See page
20 and the PATH command on page 276 for a full
description of this variable.

PROMPT defines the command-line prompt. It can be set or
changed with the PROMPT command (see page 281).

4DOS TEMP specifies the directory where 4DOS should store
temporary pipe files if the TEMP4DOS variable doesn't
exist. Some other programs also use TEMP to define where
they should place their temporary files. Temporary pipe
files are not used in 4OS2 and 4DOS/NT.

4DOS TEMP4DOS specifies where 4DOS should store temporary pipe
files. Temporary pipe files are not used in 4OS2 and
4DOS/NT.

4NT In addition, 4DOS/NT uses the environment to keep track of the
default directory on each drive or hard disk volume. DOS and
OS/2 keep track of the default directory for each drive letter
internally; Windows NT does not. 4DOS/NT overcomes this
incompatibility by saving the default directory for each drive
in the environment, using variable names that cannot be
accessed by the user. Each variable begins with an equal sign
followed by the drive letter and a colon (for example, =C:).
You can view these variables with the SET command, but you
cannot change them with any of the commands in 4DOS/NT.


## Internal Variables

Internal variables are special environment variables built
into 4DOS, 4OS2, and 4DOS/NT to provide information about your
system. They are not actually stored in the environment, but
can be used in commands, aliases, and batch files just like
any other environment variable. The values of these variables
are stored internally in the command processor, and cannot be
changed with the SET, UNSET, or ESET command. However, you
can override any of these variables by defining a new variable
with the same name.

These internal variables are often used in batch files and
aliases to examine system resources and adjust to the current
computer settings. You can examine the contents of any
internal variable (except %= or %+) from the command line with
a command like this:

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 97

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

c:\> echo %variablename

The variables are listed below. The first list is by
category, to assist you in locating the information you want
quickly. The second list includes all the variables in
alphabetical order, and defines the meaning of each one.


Internal Variable Categories

Hardware status:

_APMAC _APMBATT _APMLIFE _CPU
_MONITOR _NDP _VIDEO


Operating system and software status:

_ANSI _BOOT _CODEPAGE _COUNTRY
_DOS _DOSVER _DV _MOUSE
_WIN _WINDIR _WINSYSDIR _WINVER

Command processor status:

_4VER _ALIAS _BATCH _ENV
_HLOGFILE _KSTACK _LOGFILE _PID
_PPID _PTYPE _SHELL _SID
_SWAPPING _TRANSIENT _WINTITLE

Screen and color:

_BG _COLUMN _COLUMNS _FG
_ROW _ROWS

Drives and directories:

_CWD _CWDS _CWP _CWPS
_DISK _LASTDISK

Dates and times:

_DATE _DAY _DOW _DOY
_HOUR _MINUTE _MONTH _SECOND
_TIME _YEAR

Error codes:

? ?? _? _SYSERR



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 98

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Compatibility:

= +


Internal Variable Details

(In the list below the possible values for most variables are
shown in double quotes for ease of understanding. The actual
values returned by the variables do not include the double
quotes.)

? contains the exit code of the last external command. Many
programs return a "0" to indicate success and a non-zero value
to signal an error. However, not all programs return an exit
code. If no explicit exit code is returned, the value of %?
is undefined.

4DOS ?? returns a code which explains how the last program
terminated:

0 - program terminated normally.
1 - program terminated by Ctrl-C or Ctrl-Break.
2 - program terminated due to a critical error.
3 - program terminated and stayed resident in memory
(TSR).

_? contains the exit code of the last internal command. It is
set to "0" if the command was successful, "1" if a usage error
occurred, "2" if another command processor error or an
operating system error occurred, or "3" if the command was
interrupted by Ctrl-C or Ctrl-Break. You must use or save
this value immediately, because it is set by every internal
command.

= returns the current escape character. Use this variable,
instead of the actual escape character, if you want your batch
files and aliases to work regardless of how the escape
character is defined. For example, if the escape character is
a caret [^] (the default in 4OS2 and 4DOS/NT), both of the
commands below will send a form feed to the printer. However,
if the escape character has been changed, the first command
will send the string "^f" to the printer, while the second
command will continue to work as intended.

echos ^f > prn
echos %=f > prn



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 99

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

+ returns the current command separator. Use this variable,
instead of the actual command separator, if you want your
batch files and aliases to work regardless of how the command
separator is defined. For example, if the command separator
is an ampersand [&] (the default in 4OS2 and 4DOS/NT), both of
the commands below will display "Hello" on one line and
"world" on the next. However, if the command separator has
been changed the first command will display "Hello & echo
world", while the second command will continue to work as
intended.

echo Hello & echo world
echo Hello %+ echo world

_4VER is the current 4DOS, 4OS2, or 4DOS/NT version (for
example, "5.0").

4DOS _ALIAS contains the free space in the alias list, in bytes.

_ANSI contains "1" if internal flags indicate that ANSI.SYS or
a compatible driver is installed; "0" if not.

4OS2 4OS2 always enables OS/2's ANSI support, and assumes that it
remains enabled. Therefore _ANSI always returns "1" in 4OS2.

4NT Under 4DOS/NT, _ANSI always returns "0", because there is no
ANSI support in Windows NT.

4DOS In 4DOS, the internal flags which determine the value of _ANSI
depend on the SETDOS /A option (see page 309) and the ANSI
directive in 4DOS.INI (see page 131), as shown in the table
below. If SETDOS /A is 0 or ANSI is set to Auto, 4DOS tests
for the presence of an ANSI driver. In this case you may need
to experiment to see if this variable works properly with your
particular driver, because there is no standard and 100%
reliable way to detect an ANSI driver. See page 24 for more
information on ANSI drivers.

SETDOS /A ANSI Directive _ANSI Value

0 (default) Auto (default) Result of test
1 Yes 1
2 No 0

4DOS _APMAC is the Advanced Power Management AC line status ("on",
"off", or "unknown"). An empty string is returned if APM is
not installed on your system. (See the Glossary on page 368
for a short description of APM.)


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 100

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

4DOS _APMBATT is the Advanced Power Management battery status
("high", "low", "critical", "charging", or "unknown"). An
empty string is returned if APM is not installed.

4DOS _APMLIFE is the Advanced Power Management remaining battery
life (0 - 100 or "unknown"). An empty string is returned if
APM is not installed.

_BATCH is the current batch nesting level. It is "0" if no
batch file is currently being processed.

_BG is a string containing the first three characters of the
screen background color at the current cursor location (for
example, "Bla").

_BOOT is the boot drive letter, without a colon.

_CODEPAGE is the current code page number (see CHCP on page
178).

_COLUMN is the current cursor column (for example, "0" for the
left side of the screen).

_COLUMNS is the current number of screen columns (for example,
"80").

_COUNTRY is the current country code.

_CPU is the CPU type:

86 8086 and 8088 386 i386
186 80186 and 80188 486 i486
200 NEC V20 and V30 586 Pentium
286 80286

_CWD is the current working directory in the format
d:\pathname.

_CWDS has the same value as CWD, except it ends the pathname
with a backslash [\].

_CWP is the current working directory in the format \pathname.

_CWPS has the same value as CWP, except it ends the pathname
with a backslash [\].

_DATE contains the current system date, in the format mm-dd-yy
(U.S.), dd-mm-yy (Europe), or yy-mm-dd (Japan).


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 101

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

_DAY is the day of the month (1 to 31).

_DISK is the current disk drive, without a colon (for example,
"C").

_DOS is the operating system type ("DOS", "OS2", or "NT").
4DOS always returns "DOS", 4OS2 always returns "OS2", and
4DOS/NT always returns "NT". This may be useful if you have
batch files running under more than one operating system.

_DOSVER is the current operating system version (for example,
"6.0"). When running 4DOS in an OS/2 DOS session the version
number will be 10.3 for OS/2 1.3, 20.1 for OS/2 2.1, and so
on.

_DOW is the first three characters of the current day of the
week ("Mon", "Tue", "Wed", etc.).

_DOY is the day of the year (1 to 366).

4DOS _DV is "1" if DESQview is loaded or "0" otherwise.

4DOS _ENV is the free space in the environment, in bytes.

_FG is a string containing the first three letters of the
screen foreground color at the current cursor position (for
example, "Whi").

_HLOGFILE returns the name of the current history log file
(or an empty string if LOG /H is OFF).

_HOUR is the current hour (0 - 23).

4DOS _KSTACK returns "1" if KSTACK.COM is loaded or "0" otherwise.

_LASTDISK is the last valid drive letter, without a colon.

_LOGFILE returns the name of the current log file (or an
empty string if LOG is OFF).

_MINUTE is the current minute (0 - 59).

4DOS, _MONITOR is the monitor type ("mono" or "color").
4OS2

_MONTH is the month of the year (1 to 12).

_MOUSE is "1" if a mouse driver is loaded, and "0" otherwise.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 102

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

_NDP is the coprocessor type:

0 no coprocessor is installed
87 8087
287 80287
387 80387, 80486DX, or Pentium

4OS2 _PID is the current process ID number.

4OS2 _PPID is the process ID number of the parent process.

4OS2 _PTYPE is the current OS/2 process type:

AVIO Character mode, windowed
DT Detached (no screen in use)
FS Character mode, full-screen
PM Presentation Manager

_ROW is the current cursor row (for example, "0" for the top
of the screen).

_ROWS is the current number of screen rows (for example,
"25").

_SECOND is the current second (0 - 59).

_SHELL is the current shell nesting level. The primary shell
is level "0", and each subsequent secondary shell increments
the level by 1.

4OS2 _SID is the session ID number.

4DOS _SWAPPING returns the current swapping state. The return
value is "OFF" if swapping has been disabled with the SWAPPING
command, "EMS" if expanded memory is being used, "XMS" if
extended memory is being used, or "Disk" if 4DOS is using disk
swapping. The return value is "None" if swapping has been
disabled with the 4DOS.INI Swapping directive or if 4DOS
failed to initiate memory or disk swapping during
initialization.

_SYSERR is the error code of the last operating system error.
You will need a technical or programmer's manual to understand
these error values.

_TIME contains the current system time in the format hh:mm:ss.
The separator character may vary depending upon your country
information.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 103

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

_TRANSIENT is "1" if the current shell is transient (started
with a /C, see your Introduction and Installation Guide for
details), or "0" otherwise.

4DOS, _VIDEO is the video card type ("mono", "cga", "ega", or
4OS2 "vga").

4DOS _WIN is the current Microsoft Windows mode. This variable
will always be zero except when 4DOS is running under
Microsoft Windows:

0 Windows is not running
1 Windows 2
2 Windows 3 in 386 enhanced mode
3 Windows 3 in real or standard mode

4NT _WINDIR returns the name of the Windows NT directory.

4NT _WINSYSDIR returns the name of the Windows NT system
directory.

_WINTITLE returns the title of the current window. This
variable is valid in 4OS2 and 4DOS/NT, and in 4DOS when it is
running in a DOS session under OS/2. If you are using 4DOS
running under DOS or DOS plus Windows, the return value is an
empty string.

4NT _WINVER returns the current Windows NT version number.

_YEAR is the current year (1980 to 2099).

The _CWD, _CWDS, _CWP, _CWPS, and _DISK variables will return
their result in upper or lower case depending on the value of
the SETDOS /U switch (see page 312) or the UpperCase directive
in the .INI file (see page 135).

You can use these variables in a wide variety of ways
depending on your needs. Here are just a few examples. Some
of these examples rely on the IF command (page 238) or the IFF
command (page 244) to test the value of a variable and perform
different actions based on that value.

In a 4DOS or 4OS2 batch file, set the color based on the video
card type:

iff "%_video"=="mono" then
color bright white on black
else
color bright white on blue

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 104

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

endiff

Call another batch file if 4DOS is running under DESQview:

if "%_dv" == "1" call dvstart

Store the current date and time in a file, then save the
output of a DIR command in the same file:

echo Directory as of %_date %_time > dirsave
dir >> dirsave

Set up a prompt for the primary shell which displays the time
and current directory, and a different one for secondary
shells which includes the shell level rather than the time
(see PROMPT on page 281 for details about setting the prompt).
Also set different background colors for the two shells,
without changing the foreground color. You might use a
sequence like this in your 4START file (see page 82):

iff %_shell==0 then
prompt $t $p$g
color %_fg on blue
else
prompt [$z] $p$g
color %_fg on cyan
endiff


## Variable Functions

Variable functions are like internal variables, but they take
one or more arguments (which can be environment variables or
even other variable functions) and they return a value.

Like all environment variables, these variable functions must
be preceded by a percent sign in normal use (%@EVAL, %@LEN,
etc.). All variable functions must have square brackets
enclosing their argument(s). The argument(s) to a variable
function cannot exceed 255 characters in length for all
arguments taken as a group.

The variable functions are useful in aliases and batch files
to check on available system resources, manipulate strings and
numbers, and work with filenames.

Some variable functions, like @DISKFREE, are shown with
"b|k|m" as one of their arguments. Those functions return a


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 105

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

number of bytes, kilobytes, or megabytes based on the "b|k|m"
argument:

b return the number of bytes
K return the number of kilobytes (bytes / 1,024)
k return the number of thousands of bytes (bytes /
1,000)
M return the number of megabytes (bytes /
1,048,576)
m return the number of millions of bytes (bytes /
1,000,000)

You can include commas in the results from a "b|k|m" function
by appending a "c" to the argument. For example, to add
commas to a "b" or number of bytes result, enter "bc" as the
argument.

! In variable functions which take a drive letter as an
argument, like @DISKFREE or @READY, the drive letter must be
followed by a colon. The function will not work properly if
you use the drive letter without the colon.

! The @FILEREAD, @FILEWRITE, @FILESEEK, and @FILECLOSE functions
allow you to access files based on their file handle. These
functions should only be used with file handles returned by
@FILEOPEN! If you use them with any other file handle you may
damage other files opened by the command processor (or, in a
secondary shell, the program which started the command
processor), or hang your system.

The functions are listed below. The first list is by
category, to assist you in locating the function you want
quickly. The second list includes all the functions in
alphabetical order, and defines the arguments and return value
for each one.


Variable Function Categories

System status:

@DOSMEM @EMS @EXTENDED @MASTER
@READSCR @XMS

Drives and devices:

@CDROM @DEVICE @DISKFREE @DISKTOTAL
@DISKUSED @FSTYPE @LABEL @LPT
@READY @REMOTE @REMOVABLE

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 106

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Files:

@ATTRIB @DESCRIPT @EXETYPE @FILEAGE
@FILECLOSE @FILEDATE @FILEOPEN @FILEREAD
@FILES @FILESEEK @FILESIZE @FILETIME
@FILEWRITE @FINDFIRST @FINDNEXT @LINE
@LINES @SEARCH @TRUENAME @UNIQUE

File names:

@EXT @FILENAME @FULL @NAME
@PATH

Strings and characters:

@ASCII @CHAR @INDEX @INSTR
@LEN @LOWER @REPEAT @SUBSTR
@TRIM @UPPER @WORD

Numbers and arithmetic:

@DEC @EVAL @INC @INT
@NUMERIC @RANDOM

Dates and times:

@DATE @MAKEDATE @MAKETIME @TIME

Utility:

@ALIAS @SELECT @EXEC


Variable Function Details

@ALIAS[name]: Returns the contents of the specified alias as
a string, or a null string if the alias doesn't exist. When
manipulating strings returned by @ALIAS you may need to
disable certain special characters with the SETDOS /X command
(see page 312). Otherwise, command separators, redirection
characters, and other similar "punctuation" in the alias may
be interpreted as part of the current command, rather than
part of a simple text string.

@ASCII[c]: Returns the numeric value of the specified ASCII
character as a string. For example %@ASCII[A] returns 65.
You can put an escape character [-] before the actual
character to process. This allows quotes and other special
characters as the argument (e.g., %@ASCII[-`]).

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 107

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

@ATTRIB[filename,nrhsda]: Returns a "1" if the specified file
has the matching attribute(s); otherwise returns a "0". The
attributes are:

N Normal (no attributes set) S System
R Read-only D Directory
H Hidden A Archive

The attributes (other than N) can be combined (for example
%@ATTRIB[MYFILE,HS]). ATTRIB will only return a 1 if all of
the attributes match.

@CDROM[d:]: Returns "1" if the drive is a CD-ROM or "0"
otherwise.

@CHAR[n]: Returns the character corresponding to an ASCII
numeric value. For example %@CHAR[65] returns A.

@DATE[mm-dd-yy]: Returns the number of days since January 1,
1980 for the specified date. DATE uses the date format and
separators mandated by your country code (for example dd.mm.yy
in Germany, or yy-mm-dd in Japan).

@DEC[%var]: Returns the same value as @EVAL[%var - 1]. That
is, it retrieves and decrements the value of a variable. The
variable itself is not changed; to do so, use a command like
this:

set var=%@dec[%var]

@DESCRIPT[filename]: Returns the file description for the
specified filename (see the DESCRIBE command on page 193).

@DEVICE[name]: Returns "1" if the specified name is a
character device (such as a printer or serial port), or "0" if
not.

@DISKFREE[d:,b|k|m]: Returns the amount of free disk space on
the specified drive.

@DISKTOTAL[d:,b|k|m]: Returns the total disk space on the
specified drive.

@DISKUSED[d:,b|k|m]: Returns the amount of disk space in use
by files and directories on the specified drive.

@DOSMEM[b|k|m]: In 4DOS, returns the amount of free base
memory. In 4OS2, returns the size of the largest free memory


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 108

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

block (either in physical or virtual memory). In 4DOS/NT,
returns the amount of free physical memory.

4DOS @EMS[b|k|m]: Returns the amount of free EMS memory.

@EVAL[expression]: Evaluates an arithmetic expression. @EVAL
supports addition (+), subtraction (-), multiplication (*),
division (/), and modulo (%%). The expression can contain
environment variables and other variable functions. @EVAL
also supports parentheses, commas, and decimals. Parentheses
can be nested. The maximum precision is 16 digits to the left
of the decimal point and 8 digits to the right of the decimal
point. @EVAL will strip leading and trailing zeros from the
result. When evaluating expressions, *, /, and %% take
precedence over + and -. For example, 3 + 4 * 2 will be
interpreted as 3 + 8, not as 7 * 2. To change this order of
evaluation, use parentheses to specify the order you want.
Also see @DEC and @INC.

@EXEC[command]: Execute the command. The command can be an
alias, internal command, external command, .BTM file, or .BAT
file. @EXEC is primarily intended for running a program from
within the PROMPT. It is a "back-door" entry into command
processing and should be used with extreme caution. Incorrect
or recursive use of @EXEC may cause stack overflows or hang
your system.

4OS2 @EXETYPE[filename]: Returns the application type as a string:

DOS DOS .COM, .EXE, or .BAT file (OS/2 2.x only)
AVIO OS/2 Character mode, windowed
FS OS/2 Character mode, full-screen
PM OS/2 Presentation Manager
WIN Windows 3 (OS/2 2.x only)
UNKNOWN Any other file

@EXT[filename]: Returns the extension from a file name,
without a leading period.

4DOS @EXTENDED[b|k|m]: Returns the amount of extended memory.

@FILEAGE[filename]: Returns the date and time of the file as
a single numeric value. The number can be used to compare the
relative ages of two or more files.

@FILECLOSE[n]: Closes the file whose handle is "n." You
cannot close handles 0, 1 or 2. Returns "0" if the file
closed OK or "-1" if an error occurs. Be sure to read the
cautionary note about file functions on page 106.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 109

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

@FILEDATE[filename]: Returns the date a file was last
modified, in the default country format (mm-dd-yy for the US).

@FILENAME[filename]: Returns the name and extension of a
file, without a path.

@FILEOPEN[filename, read | write | append]: Opens the file in
the specified mode and returns the file handle as an integer.
Returns "-1" if the file cannot be opened. Be sure to read
the cautionary note about file functions on page 106.

@FILEREAD[n]: Reads a line from the file whose handle is "n."
Returns "**EOF**" if you attempt to read past the end of the
file. Be sure to read the cautionary note about file
functions on page 106.

@FILES[filename]: Returns the number of files that match the
filename specification, which may contain wildcards and
include lists. The filename must refer to a single directory;
to check several directories, use @FILES once for each
directory, and add the results together with @EVAL.

@FILESEEK[n,offset,start]: Moves the file pointer "offset"
bytes in the file whose handle is "n". Returns the new
position of the pointer, in bytes from the start of the file.
Set "start" to 0 to seek relative to the beginning of the
file, 1 to seek relative to the current file pointer, or 2 to
seek relative to the end of the file. The offset value may be
negative (seek backward), positive (seek forward), or zero
(return current position, but do not change it). Be sure to
read the cautionary note about file functions on page 106.

@FILESIZE[filename,b|k|m]: Returns the size of a file, or
"-1" if the file does not exist. If the filename includes
wildcards or an include list, returns the combined size of all
matching files.

@FILETIME[filename]: Returns the time a file was last
modified, in hh:mm format.

@FILEWRITE[n,text]: Writes a line to the file whose handle is
"n". Returns the number of bytes written, or "-1" if an error
occurred. Be sure to read the cautionary note about file
functions on page 106.

@FINDFIRST[filename [,nrhsda]]: Returns the name of the first

file that matches the filename, which may include wildcards.
The second argument, if included, defines the attributes of


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 110

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

the files that will be included in the search. Returns an
empty string if no files match. The attributes are:

N Normal (no attributes set) S System
R Read-only D Directory
H Hidden A Archive

The attributes (other than N) can be combined (for example
%@FINDFIRST[MYFILE,HS]). @FINDFIRST will only find a file if
all of the attributes match.

@FINDNEXT[filename [,nrhsda]]: Returns the name of the next
file that matches the filename, which may include wildcards.
The second argument, if included, defines the attributes of
the files that will be included in the search (see @FINDFIRST
for details). Returns an empty string when no more files
match. @FINDNEXT should only be used after a successful call
to @FINDFIRST.

4OS2, @FSTYPE[d:]: Returns the file system type for the specified
4NT drive. Under 4OS2, @FSTYPE will return "FAT" for a DOS-
compatible drive with a file allocation table, "HPFS" for a
drive that uses OS/2's high performance file system, or "CDFS"
for a CD-ROM drive. It may return other values if additional
file systems have been installed with the IFS= directive in
CONFIG.SYS. 4DOS/NT will normally return "FAT", "HPFS",
"CDFS", or "NTFS" for a drive that uses the Windows NT file
system.

@FULL[filename]: Returns the fully qualified path name of a
file.

@INC[%var]: Returns the same value as %@EVAL[%var + 1]. That
is, it retrieves and increments the value of a variable. The
variable itself is not changed; to do so, use a command like
this:

set var=%@inc[%var]

@INDEX[string1,string2]: Returns the position of string2
within string1, or "-1" if string2 is not found. The first
position in string1 is numbered 0.

@INSTR[start, length, string]: The same as @SUBSTR (see page
113). However, the string is at the end of the @INSTR
argument list, so that commas in the string will not be
confused with commas separating the arguments.

@INT[n]: Returns the integer part of the number n.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 111

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

@LABEL[d:]: Returns the volume label of the specified disk
drive.

@LEN[string]: Returns the length of a string.

@LINE[filename,n]: Returns line "n" from the specified file.
The first line in the file is numbered 0. "**EOF**" is
returned for all line numbers beyond the end of the file. If
you need to scan through the lines of a file in sequence, the
@FILEREAD function (above) and the "@filename" construct
available in the FOR command (page 223) are much faster than
calling the @LINE function repeatedly. @LINE will retrieve
input from standard input if you specify CON as the filename.
If you are redirecting input to @LINE using this feature, you
must use command grouping (see page 69) or the redirection
will not work properly. For example:

(echo %@line[con,0]) < myfile.dat

@LINES[filename]: Returns the line number of the last line in
the file, or "-1" if the file is empty. The first line in the
file is numbered 0, so (for example) @LINES will return 0 for
a file containing one line.

@LOWER[string]: Returns the string converted to lower case.

4DOS @LPT[n]: Returns a "1" if the specified printer is ready;
otherwise, returns "0". n=1 checks the printer connected to
LPT1, n=2 checks LPT2, and n=3 checks LPT3.

@MAKEDATE[n]: Returns a date (formatted according to the
current country settings). "n" is the number of days since
1/1/80. This is the inverse of @DATE.

@MAKETIME[n]: Returns a time (formatted according to the
current country settings). "n" is the number of seconds since
midnight. This is the inverse of @TIME.

4DOS @MASTER[varname]: Returns the value of a variable from the
master environment.

@NAME[filename]: Returns the base name of a file, without the
path or extension.

@NUMERIC[string]: Returns "1" if the argument is composed
entirely of digits (0 to 9), signs (+ or -), and the thousands
and decimals separators. Otherwise, returns "0".



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 112

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

@PATH[filename]: Returns the path from a file name, including
the drive letter and a trailing backslash but not including
the base name or extension.

@RANDOM[min, max]: Returns a random value between min and
max, inclusive. Min, max, and the returned value are all
integers.

@READSCR[row,col,length]: Returns the text displayed on the
screen at the specified location. The upper left corner of
the screen is location 0,0.

@READY[d:]: Returns "1" if the specified drive is ready;
otherwise returns "0".

@REMOTE[d:]: Returns "1" if the specified drive is a remote
(network) drive; otherwise returns "0".

@REMOVABLE[d:]: Returns "1" if the specified drive is
removable (i.e., a floppy disk or removable hard disk);
otherwise returns "0".

@REPEAT[c,n]: Returns the character "c" repeated "n" times.

@SEARCH[filename]: Searches for the filename using the PATH
environment variable, appending an extension if one isn't
specified. See page 20 for details on the default extensions
used when searching the PATH, and the order in which the
search proceeds. Returns the fully-expanded name of the file
including drive, path, base name, and extension, or an empty
string if a matching file is not found. If wildcards are used
in the filename, @SEARCH will search for the first file that
matches the wildcard specification, and return the drive and
path for that file plus the wildcard filename (e.g.,
E:\UTIL\*.COM).

@SELECT[filename,top,left,bottom,right,title]: Pops up a
selection window with the lines from the specified file.
Returns the text of the line the scrollbar is on if you press
Enter, or an empty string if you press Esc. @SELECT can be
used to display menus or other selection lists from a batch
file. To select from lines passed through input redirection
or a pipe, use CON as the filename. You can move through the
selection window with standard navigation keystrokes. To
change the navigation keys, see page 140.

@SUBSTR[string,start,length]: Returns a substring, starting
at the position "start" and continuing for "length"
characters. If the length is omitted, it will default to the

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 113

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

remainder of the string. If the length is negative, the start
is relative to the right side of the string. The first
character in the string is numbered 0; if the length is
negative, the last character is numbered 0. For example,
%@SUBSTR[%_TIME,0,2] gets the current time and extracts the
hour. If the string includes commas, it must be quoted with
double quotes ["] or back-quotes [`]. The quotes do count in
calculating the position of the substring. @INSTR (page 111)
performs the same function, and allows commas in the string
without quoting.

@TIME[hh:mm:ss]: Returns the number of seconds since midnight
for the specified time. The time must be in 24-hour format;
"am" and "pm" cannot be used.

@TRIM[string]: Returns the string with the leading and
trailing white space (space and tab characters) removed.

4DOS @TRUENAME[filename]: Returns the true, fully-expanded name
for a file. TRUENAME will "see through" a JOIN or SUBST, and
requires DOS 3.0 or above. Wildcards may not be used in the
filename. @TRUENAME can handle simple drive substitutions
such as those created by JOIN, SUBST, or most network drive
mappings. However it may not be able to correctly determine
the true name if you use "nested" JOIN or SUBST commands, or a
network which does not report true names properly.

@UNIQUE[d:\path]: Creates a zero-length file with a unique
name in the specified directory, and returns the full name and
path. If no path is specified, the file will be created in
the current directory. The file name will be FAT-compatible
(8 character name and 3-character extension) regardless of
whether the file is created on a FAT, HPFS, or NTFS drive.
This function allows you to create a temporary file without
overwriting an existing file.

@UPPER[string]: Returns the string converted to upper case.

@WORD[n,string]: Returns the "nth" word in a string. The
first word is numbered 0. If "n" is negative, words are
returned from the end of the string. Only spaces, tabs, and
commas are considered to be word separators. For example:

%@WORD[2,NOW IS THE TIME] returns "THE"
%@WORD[-0,NOW IS THE TIME] returns "TIME"
%@WORD[-2,NOW IS THE TIME] returns "IS"

4DOS @XMS[b|k|m]: Returns the amount of free XMS memory.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 114

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Examples

You can use variable functions in a wide variety of ways
depending on your needs. We've included a few examples below
to give you an idea of what's possible.

To set the prompt to show the amount of free memory (see the
PROMPT command, page 281, for details on including variable
functions in your prompt):

c:\> prompt (%%@dosmem[K]K) $p$g

Set up a simple command-line calculator. The calculator is
used with a command like CALC 3 * (4 + 5):

c:\> alias calc `echo The answer is: %@eval[%&]`

The following batch file uses variable functions to implement
"once a day" execution of a group of commands. It works by
constructing a 6-digit number "yymmdd" from today's date, and
comparing that to a number of the same type stored in the file
C:\ONCEADAY.DAT. If today's date is numerically larger than
the saved date, and the time is after 6:00 AM, then the "once
a day" commands are run, and today's date is saved in the file
as the new date for comparison. Otherwise, no action is
taken. You can make this file simpler using the %@DATE and
%@TIME functions instead of using %@SUBSTR to extract
substrings of the %_DATE and %_TIME variables; we used the
approach shown to demonstrate the use of %@SUBSTR.

rem Temporary variables used to shorten example lines:
rem DD is _date, DY is yymmdd date, TM is _time
set dd=%_date
set
dy=%@substr[%dd,6,2]%@substr[%dd,0,2]%@substr[%dd,3,2]
set lastdate=0
iff exist c:\onceaday.dat then
set lastdate=%@line[onceaday.dat,0]
endiff
iff %dy gt %lastdate then
set tm=%_time
iff "%@substr[%tm,0,2]%@substr[%tm,3,2]" gt "0600" then
rem Commands to be executed once a day go here
echo %dy > c:\onceaday.dat
endiff
endiff




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 115

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Command Parsing

Whenever you type something at the command line and press the
Enter key, or include a command in a batch file, you have
given a command to 4DOS, 4OS2, or 4DOS/NT, which must figure
out how to execute your command. If you understand the
general process that is used, you will be able to make the
best use of the commands. Understanding these steps can be
especially helpful when working with complex aliases or batch
file commands.

To decide what activity to perform, the command processor goes
through several steps. Before it starts, it writes the entire
command line (which may contain multiple commands) to the
history log file if history logging has been enabled with the
LOG /H command (see page 264). Then, if the line contains
multiple commands, the first command is isolated for
processing.

4DOS, 4OS2, and 4DOS/NT begin by dividing the command into a
command name and a command tail. The command name is the
first word in the command; the tail is everything that follows
the command name. For example, in the command line

dir *.txt /2/p/v

the command name is "dir," and the command tail is " *.txt
/2/p/v."

Next the command processor tries to match the command name
against its list of aliases. If it finds a match between the
command name and one of the aliases you've defined, it
replaces the command name with the contents of the alias.
(This substitution is done internally and is not normally
visible to you). If the alias included parameters (%1, %2,
etc.), the parameter values are filled in from the text on the
command line, and any parameters used in this process are
removed from the command line. The process of replacing a
command name that refers to an alias with the contents of the
alias, and filling in the alias parameters, is called alias
expansion.

This expansion of an alias creates a new command name: the
first word of the alias. This new command name is again
tested against the list of aliases, and if a match is found
the contents of the new alias is expanded just like the first
alias. This process, called nested alias expansion, continues
until the command name no longer refers to an alias.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 116

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

Once it has finished with the aliases, 4DOS, 4OS2, or 4DOS/NT
next tries to match the command name with its list of internal
commands. If it is unsuccessful, the command processor knows
that it will have to search for a batch file or external
program to execute your command.

The next step is to locate any batch file or alias parameters,
environment variables, internal variables, or variable
functions in the command, and replace each one with its value.
This process is called variable expansion.

The variable expansion process is modified for certain
internal commands, like EXCEPT, IFF, and GLOBAL. These
commands are always followed by another command, so variable
expansion takes place separately for the original command and
the command that follows it.

Once all of the aliases and environment variables have been
expanded, 4DOS, 4OS2, or 4DOS/NT will echo the complete
command to the screen (if command-line echo has been enabled)
and write it to the log file (if command logging has been
turned on).

Before it can actually execute your command, the command
processor must scan the command tail to see if it includes
redirection or piping. If so, the proper internal switches
are set to send output to an alternate device or to a file,
instead of to the screen. In 4OS2 and 4DOS/NT, a second
process is started at this point, if necessary, to receive any
piped output.

Finally, it is time to execute the command. If the command
name matches an internal command, 4DOS, 4OS2, or 4DOS/NT will
perform the activities you have requested. Otherwise, the
command processor searches for an executable (.COM or .EXE)
file, a batch file, or a file with an executable extension
that matches the command name (see the detailed description of
this search on page 20).

Once the internal command or external program has terminated,
the command processor saves the result or exit code that the
command generated, cleans up any redirection that you
specified, and then returns to the original command line to
retrieve the next command. When all of the commands in a
command line are finished, the next line is read from the
current batch file, or if no batch file is active, the prompt
is displayed.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 117

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

You can disable and re-enable several parts of command parsing
(for example alias expansion, variable expansion, and
redirection) with the SETDOS /X command (see page 312).


Argument Quoting

As it parses the command line, the command processor looks for
command separators (carets [^] in 4DOS, or ampersands [&] in
4OS2 and 4DOS/NT), conditional commands (|| or &&), white
space (spaces, tabs, and commas), percent signs [%] which
indicate variables to be expanded, and redirection and piping
characters (>, <, or |).

Normally, these special characters cannot be passed to a
command as part of an argument. However, you can include any
of the special characters in an argument by enclosing the
entire argument in back-quotes [`] or double quotes ["].
Although both back-quotes and double quotes will let you build
arguments that include special characters, they do not work
the same way.

No alias or variable expansion is performed on an argument
enclosed in back-quotes. Redirection symbols inside the back-
quotes are ignored. The back-quotes are removed from the
command line before the command is executed.

No alias expansion is performed on expressions enclosed in
double quotes. Redirection symbols inside double quotes are
ignored. However, variable expansion is performed on
expressions inside double quotes. The double quotes
themselves will be passed to the command as part of the
argument.

For example, suppose you have a batch file CHKNAME.BTM which
expects a name as its first parameter (%1). Normally the name
is a single word. If you need to pass a two-word name with a
space in it to this batch file you could use the command:

c:\> chkname `MY NAME`

Inside the batch file, %1 will have the value MY NAME,
including the space. The back-quotes caused the command
processor to pass the string to the batch file as a single
argument.

For a more complex example, suppose the batch file QUOTES.BAT
contains the following commands:


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 118

CHAPTER 4 / ALIASES AND BATCH FILES
-------------------------------------------------------------------

@echo off
echo Arg1 = %1
echo Arg2 = %2
echo Arg3 = %3

and that the environment variable FORVAR has been defined with
this command:

c:\> set FORVAR=for

Now, if you enter the command

c:\> quotes `Now is the time %forvar` all good

the output from QUOTES.BAT will look like this:

Arg1 = Now is the time %forvar
Arg2 = all
Arg3 = good

But if you enter the command

c:\> quotes "Now is the time %forvar" all good

the output from QUOTES.BAT will look like this:

Arg1 = "Now is the time for"
Arg2 = all
Arg3 = good

Notice that in both cases, the quotes keep characters together
and reduce the number of arguments in the line.

The following example has 7 command-line arguments, while the
examples above only have 3:

c:\> quotes Now is the time %forvar all good

When an alias is defined in a batch file or from the command
line, its argument can be enclosed in back-quotes to prevent
the expansion of replaceable parameters, variables, and
multiple commands until the alias is invoked. See ALIAS on
page 155 for details.

You can disable and re-enable back-quotes and double quotes
with the SETDOS /X command (see page 312).




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 119

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------


CHAPTER 5 / CONFIGURATION


Part of the power of 4DOS, 4OS2, and 4DOS/NT is their flexibility.
You can alter their configuration to match your style of computing.
This chapter explains how to make the command processor work the
way you want.

The configuration of 4DOS, 4OS2, and 4DOS/NT is controlled through
an optional file of initialization information with the extension
.INI. This file is called 4DOS.INI in 4DOS, 4OS2.INI in 4OS2, and
4NT.INI in 4DOS/NT. (For brevity, we refer to all three files as
.INI files throughout this manual.)

You can create, add to, and edit the .INI file with any ASCII text
editor. Each command processor reads its .INI file when it starts,
and configures itself accordingly. The .INI file is not re-read
when you change it. For changes to take effect, you must reboot
your system (under DOS), or restart the session or window in which
your command processor is running (under OS/2 or Windows NT).

Each item that you can include in the .INI file has a default
value. You only need to include entries in the file for settings
that you want to change from their default values. If you are
happy with all of the default values, you don't need an .INI file
at all.


Using the .INI File

Some settings in the .INI file are initialized when you
install 4DOS, 4OS2, or 4DOS/NT, so you may have an .INI file
even if you didn't create one yourself. You should not delete
this file unless you've checked carefully to be sure that you
don't need any of the settings the installation program put
there.

4DOS, 4OS2, and 4DOS/NT primary shells search for the .INI
file in three places:

* If there is an "@d:\path\inifile" option on the SHELL=
line in CONFIG.SYS (for 4DOS) or on the startup
command line (for 4OS2 and 4DOS/NT), the command
processor will use the path and file name specified
there, and will not look elsewhere.

* If there is no .INI file name on the SHELL= line or
startup command line, the search proceeds to the same

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 120

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

directory where the command processor program file
(4DOS.COM, 4OS2.EXE, or 4NT.EXE) is stored. This is
the "normal" location for the .INI file. 4DOS, 4OS2,
and 4DOS/NT determine this directory automatically.
You can also set it yourself by placing a COMSPEC
directory name on the SHELL= line in CONFIG.SYS (for
4DOS), or on the startup command line (for 4OS2 and
4DOS/NT). See your Introduction and Installation
Guide for further details on setting the COMSPEC
directory.

* If the .INI file is not found in the directory where
the program file is stored, a final check is made in
the root directory of the boot drive.

When 4DOS, 4OS2, or 4DOS/NT is loaded as a secondary shell, it
does not search for the .INI file. Instead, it retrieves the
primary shell's .INI file data, processes the [Secondary]
section of the original .INI file if necessary, and then
processes any "@d:\path\inifile" option on the secondary shell
command line (see your Introduction and Installation Guide for
details). You can override this behavior with the NextINIFile
directive (see page 142).


.INI File Directives

Most lines in the .INI file consist of a one-word directive,
an equal sign [=], and a value. For example, in the following
line, the word "Environment" is the directive and "2048" is
the value:

Environment = 2048

Any spaces before or after the equal sign are ignored.

If you have a long string to enter in the .INI file (for
example, for the ColorDir directive), you must enter it all on
one line. Strings cannot be "continued" to a second line.
Each line may be up to 511 characters long in 4DOS, or 1023
characters long in 4OS2 and 4DOS/NT.

The format of the value part of a directive line depends on
the individual directive. It may be a numeric value, a single
character, a choice (like "Yes" or "No"), a color setting, a
key name, a path, a filename, or a text string. The value
begins with the first non-blank character after the equal sign
and ends at the end of the line or the beginning of a comment.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 121

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

Blank lines are ignored in the .INI file and can be used to
separate groups of directives. You can place comments in the
file by beginning a line with a semicolon [;]. You can also
place comments at the end of any line except one containing a
text string value. To do so, enter at least one space or tab
after the value, a semicolon, and your comment, like this:

Environment = 2048 ;set standard environment size

If you try to place a comment at the end of a string value,
the comment will become part of the string and will probably
cause an error.

When the command processor detects an error while processing
the .INI file, it displays an error message and prompts you to
press a key to continue processing the file. This allows you
to note any errors before the startup process continues. The
directive in error will retain its previous or default value.
Only the most catastrophic errors (like a disk read failure)
will terminate processing of the remainder of the .INI file.
If you don't want a pause after each error, use a
"PauseOnError = No" directive at the beginning of the .INI
file.

If you need to test different values for an .INI directive
without repeatedly editing the .INI file, see the INIQuery
directive on page 127.

The .INI file has three sections: the first or global
section, the [Primary] section, and the [Secondary] section.
The global section consists of directives at the beginning of
the file, with no section name before them. These directives
are effective in all shells. In most cases, this is the only
section you will need, particularly for 4OS2 and 4DOS/NT.

The [Primary] and [Secondary] sections include directives that
are used only in primary and secondary shells respectively
(see page 12 for more information on primary and secondary
shells). Each section is identified by the section name in
square brackets on a line by itself. You don't need to set up
these sections unless you want different directives for
primary and secondary shells.

Directives in the [Primary] section are used for the first or
primary shell. The values are passed automatically to all
secondary shells, unless overridden by a directive with the
same name in the [Secondary] section.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 122

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

Directives in the [Secondary] section are used in secondary
shells only, and override any corresponding primary shell
settings. For example, these lines in the .INI file:

[Primary]
ScreenRows = 25
[Secondary]
ScreenRows = 50

mean to assume that you have 25 rows on the screen in the
primary shell and 50 lines in all secondary shells.

Sections that begin with any name other than [Primary] or
[Secondary] are ignored.

The SETDOS command can override several of the .INI file
directives (see page 308). For example, the cursor shape used
by 4DOS, 4OS2, and 4DOS/NT can be adjusted either with the
CursorIns and CursorOver directives or the SETDOS /S command.
The correspondence between SETDOS options and .INI directives
is noted under each directive below, and under each option of
the SETDOS command.

Secondary shells automatically inherit the configuration
settings currently in effect in the previous shell. If values
have been changed by SETDOS since the primary shell started,
the current values will be passed to the secondary shell. If
the previous shell's .INI file had a [Secondary] section, it
will then be read and processed. If not, the previous shell's
settings will remain in effect.

For example, you might set BatchEcho to Yes in the .INI file,
to enable batch file echo. If you then use SETDOS /V0 to turn
off batch file echoing in the primary shell, then any
secondary shells will inherit the SETDOS setting, rather than
the original value from the .INI file; i.e., batch files in
the secondary shell will default to no echo.

If you want to force secondary shells to start with a specific
value for a particular directive, regardless of any changes
made with SETDOS in a previous shell, repeat the directive in
the [Secondary] section of the .INI file.

4DOS If you start a secondary shell from a task switching program
like Windows, DESQview, or Back & Forth, you can specify an
alternate location and name for 4DOS.INI by passing the
"@d:\path\inifile" option to 4DOS as a command-line parameter
(see your 4DOS Introduction and Installation Guide for
details). In this case, the configuration settings in the

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 123

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

alternate 4DOS.INI file will supersede any settings inherited
from the previous shell. Any values which are not explicitly
set in the alternate file will retain the value they had in
the previous shell.

The first section below lists the different types of
directives. Subsequent sections list all the individual
directives, divided by function and then alphabetically by
directive name. At the end we have included a few examples of
how to use the .INI file directives (see page 144).


Types of Directives

There are 8 types of directives in the .INI file. The
different types of directives are shown in the lists below as
follows:

* Name = nnnn (1234): This directive takes a numeric
value which replaces the "nnnn." The default value is
shown in parentheses.

* Name = c (X): This directive accepts a single
character as its value. The default character is
shown in parentheses. You must type in the actual
character; you cannot use a key name.

* Name = CHOICE1 | Choice2 | ... : This directive takes
a choice value. The possible choices are listed,
separated by vertical bars. The default value is
shown in all upper case letters in the directive
description, but in your file any of the choices can
be entered in upper case or lower case. For example,
if the choices were shown as "YES | No" then "YES" is
the default.

* Name = Color: This directive takes a color
specification. See page 26 for the format of color
names.

* Name = Key (Default): This directive takes a key
specification. See page 31 for the format of key
names.

* Name = Path: This directive takes a path
specification, but not a filename. The value should
include both a drive and path (e.g., C:\4DOS) to avoid
any possible ambiguities. A trailing backslash [\] at


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 124

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

the end of the path name is acceptable but not
required. Any default path is described in the text.

* Name = File: This directive takes a filename. We
recommend that you use a full filename including the
drive letter and path to avoid any possible
ambiguities. Any default filename is described in the
text.

* Name = String: This directive takes a string in the
format shown. The text describes the default value
and any additional requirements for formatting the
string correctly. No comments are allowed.

4DOS, 4OS2, and 4DOS/NT each contain a fixed-length area for
storing strings entered in the .INI file, including file
names, paths, and other strings. This area is large and is
unlikely to overflow; if it does, you will receive an error
message. If this occurs, reduce the complexity of your .INI
file or contact our technical support department for
assistance.

Each directive is listed below with its name, type, and
default value. In some cases, no default is shown because the
default value is different for different products; in these
cases, the default is described in the text.


Initialization Directives

The directives in this section control how your command
processor starts and where it looks for its files.

4StartPath = Path: Sets the drive and directory where
the 4START and 4EXIT batch files (if any) are located.

4DOS Alias = nnnn (1024): Sets the amount of memory in bytes
allocated for the alias list. The allowable range of
values is 256 to 32767 bytes. This directive is not
needed in 4OS2 or 4DOS/NT because both adjust the size of
the alias list dynamically. If you use a global alias
list (see page 163), the Alias value is ignored in all
shells except the shell which first establishes the
global list.

4DOS AutoExecPath = Path | File: Sets the path used to find
AUTOEXEC.BAT if 4DOS is started as a primary shell with
the /P option in CONFIG.SYS (see your Introduction and
Installation Guide). If you include only a path, 4DOS

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 125

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

will look for AUTOEXEC.BAT in the specified directory.
If you include a complete file name, 4DOS will look for
the specified file, and will not look for AUTOEXEC.BAT.
The default is the file AUTOEXEC.BAT in the root
directory of the boot drive.

Using AutoExecPath with a complete file name lets you
store multiple startup files in a single directory. You
may find this useful under DOS if you have multiple boot
software and use different startup files under different
configurations, or under OS/2 if you have several DOS
sessions with different startup files. If you are
running under OS/2, using AutoExecPath is equivalent to
setting DOS_AUTOEXEC on a session's DOS settings notebook
page (see the OS/2 documentation and your Introduction
and Installation Guide for details on DOS settings).

4DOS AutoExecParms = String: Sets the parameter or parameters
to be passed to AUTOEXEC.BAT, or the file specified with
the AutoExecPath directive, above, when 4DOS is started
as a primary shell with the /P option in CONFIG.SYS (see
your Introduction and Installation Guide). The
parameters will be available in your AUTOEXEC.BAT file as
%1, %2, etc.

4DOS Environment = nnnn (512): Sets the amount of memory
allocated to the environment in bytes. The allowable
range of values is 256 to 32767 bytes. This directive is
not needed in 4OS2 or 4DOS/NT because both adjust the
size of the environment dynamically.

4DOS EnvFree = nnnn (128): Sets the minimum amount of memory
in bytes that will be available in the environment for
secondary shells. 4DOS will enlarge the environment for
each secondary shell, if necessary, so that there is at
least this much free environment space when the shell
starts. The allowable range of values is 128 to 32767
bytes.

4OS2 HelpBook = String: Sets the names of the "books" to be
loaded when 4OS2 help is invoked with the HELP command or
the F1 key. The default is 4OS2+CMDREF which loads the
4OS2 help and the OS/2 command reference. See the 4OS2
Introduction and Installation Guide for details about
this directive.

4DOS HelpOptions = String: Sets default options for the 4DOS
help system. For the available options, see your 4DOS
Introduction and Installation Guide.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 126

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

4DOS HelpPath = Path: Sets the path used to find 4HELP.EXE
when F1 is pressed or the HELP command is used. If this
directive is not used, 4DOS will search the current
directory and each of the directories in the PATH.

History = nnnn (1024): Sets the amount of memory
allocated to the command history list in bytes. The
allowable range of values is 512 to 8192 bytes. If you
use a global history list (see page 38), the History
value is ignored in all shells except the shell which
first establishes the global list.

INIQuery = Yes | NO: If set to Yes, a prompt will be
displayed before execution of each subsequent line in the
current .INI file. This allows you to modify certain
directives when you start the command processor in order
to test different configurations. INIQuery can be reset
to No at any point in the file. Normally INIQuery = Yes
is only used during testing of other .INI file
directives.

The prompt generated by INIQuery = Yes is:

[contents of the line] (Y/N/Q/R/E) ?

At this prompt, you may enter:

Y = Yes: Process this line and go on to the next.
N = No: Skip this line and go on to the next.
Q = Quit: Skip this line and all subsequent lines.
R = Rest: Execute this and all subsequent lines.
E = Edit: Prompt for a new value for this entry.

If you choose E for Edit, you can enter a new value for
the directive, but not a new directive name.

For example, if you have found a compatibility problem
you think may be related to 4DOS's swapping or upper
memory block usage, you might change your 4DOS.INI file
so a part of it read as follows:

INIQuery = Yes
Swapping = XMS, EMS, C:\
UMBLoad = Yes
UMBEnvironment = Yes
INIQuery = No

You could then choose to process, ignore, or edit the
Swapping, UMBLoad, or UMBEnvironment directive each time

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 127

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

4DOS started. This would allow you to test several
possible combinations to see if you could resolve the
compatibility problem.

LocalAliases = Yes | No: The default value is Yes in
4DOS and No in 4OS2 and 4DOS/NT. No forces all copies of
the command processor to share the same alias list. Yes
keeps the lists for each shell separate. See page 163
for more details on local and global alias lists.

LocalHistory = Yes | No: The default value is Yes in
4DOS and No in 4OS2 and 4DOS/NT. No forces all copies of
the command processor to share the same history list.
Yes keeps the lists for each shell separate. See page 38
for more details on local and global history lists.

PauseOnError = YES | No: Yes forces a pause with the
message "Error in filename, press any key to continue
processing" after displaying any error message related to
a specific line in the .INI file. No continues
processing with no pause after an error message is
displayed.

4DOS Swapping = swap type [, swap type] ...: Sets the type of
swapping 4DOS should use. 4DOS runs in two parts, a
resident portion that is always in memory and a transient
portion that is "swapped" to EMS memory, XMS memory, a
RAM disk, or your hard disk while application programs
are running. The swap area for the transient portion
normally requires about 128K bytes of memory or disk
space for the primary shell, and 28 - 32K bytes for each
secondary shell.

The swap type can be EMS to swap to EMS expanded memory,
XMS to swap to XMS extended memory, d:\path to swap to
the specified drive and path, or None for no swapping.

If you use d:\path, 4DOS will create the file
4DOSSWAP.nnn in the specified directory. The file name
changes if UniqueSwapName is set to Yes (see page 144).
If you use None, the transient portion of 4DOS will
remain in memory at all times; this will reduce memory
available for application programs by about 128K.

You can specify multiple swap types and 4DOS will try
them in the order listed. Swap type "None" is always
appended to your list of possible swap types as a "last
resort," even if you don't include it explicitly. The
default Swapping specification is EMS, XMS, x:\, None,

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 128

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

where x is the boot drive. In most cases you will find
that the default setting works without modification.

Before changing the Swapping specification, see your 4DOS
Introduction and Installation Guide for more detail on
swapping types and the way 4DOS uses memory.

4DOS UMBAlias = Yes | NO | 1 | 2 ... | 8: Yes attempts to
load global alias list storage into a UMB (Upper Memory
Block). If you use a specific region number (1 through
8), 4DOS will attempt to reserve room for the global
alias list in that UMB region.

Region numbers can be used under MS-DOS / PC-DOS 5.0 and
above, and under OS/2's DOS support. To use them, you
must enable DOS UMB management with the DOS=UMB or
DOS=HIGH,UMB directive in CONFIG.SYS. See your 4DOS
Introduction and Installation Guide for complete details
on UMBs and UMB regions, and the hardware and software
required to support them.

If you use an invalid region number, or if region numbers
have not been enabled on your system, 4DOS will load the
global alias list into the first available region. If no
upper memory is available, space for the global alias
list will be reserved in low memory.

UMBAlias applies to global aliases only, and is only used
in the first shell which establishes the global alias
area (see page 163 for more information on local and
global alias lists). If you specify LocalAliases = Yes,
or if the previous shell already created a global alias
area, any UMBAlias setting is ignored.

4DOS UMBEnvironment = Yes | NO | 1 | 2 ... | 8: Yes attempts
to load the master environment into a UMB (Upper Memory
Block). This reduces 4DOS's base memory requirements but
may cause problems with some programs that try to access
the master environment directly. See UMBAlias (above)
for information on the use of UMBs and region numbers.

4DOS UMBHistory = Yes | NO | 1 | 2 ... | 8: Yes attempts to
load global history list storage into a UMB (Upper Memory
Block). If you use a specific region number (1 through
8), 4DOS will attempt to reserve room for the global
history list in that UMB region. See page 38 for more
information on local and global history lists. See
UMBAlias (above) for information on the use of UMBs and


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 129

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

region numbers. Like UMBAlias, UMBHistory will be
ignored if a global history list is not used.

4DOS UMBLoad = Yes | NO | 1 | 2 ... | 8: Yes attempts to load
the resident portion of 4DOS into a UMB (Upper Memory
Block). This reduces the size of the resident portion in
base memory from about 3K bytes to 256 bytes. See
UMBAlias (above) for information on the use of UMBs and
region numbers.

4OS2, WindowState = STANDARD | Maximize | Minimize: Sets the
4NT initial state of the 4OS2 or 4DOS/NT window. Standard
puts the window in the default position on the OS/2 or
Windows NT desktop, and is the default setting. Maximize
maximizes the window; Minimize minimizes it. If you use
Maximize or Minimize, you may see the 4OS2 or 4DOS/NT
window appear briefly in the Standard position as it is
created by the operating system, then switch to the new
state.

4OS2, WindowX = nnnn, WindowY = nnnn, WindowWidth = nnnn,
4NT WindowHeight = nnnn: These 4 directives set the initial
size and position of the 4OS2 or 4DOS/NT window. The
measurements are in pixels or pels. Under 4OS2, WindowX
and WindowY refer to the position of the bottom left
corner of the window relative to the bottom left corner
of the screen. Under 4DOS/NT, WindowX and WindowY refer
to the position of the top left corner of the window
relative to the top left corner of the screen.


Configuration Directives

These directives control the way that 4DOS, 4OS2, and 4DOS/NT
operate. Some can be changed with the SETDOS command while
the command processor is running. Any corresponding SETDOS
command is listed in the description of each directive;
information on SETDOS begins on page 308.

AmPm = Yes | NO | Auto: Yes displays times in 12-hour
format with a trailing "a" for AM or "p" for PM. The
default of No forces a display in 24-hour time format.
Auto formats the time according to the country code set
for your system. AmPm controls the time displays used by
DIR and SELECT, in LOG files, and the output of the
TIMER, DATE, and TIME commands. It has no effect on
%_TIME, %@MAKETIME, the $t and $T options of PROMPT, or
date and time ranges.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 130

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

4DOS ANSI = AUTO | Yes | No: Tells 4DOS whether an ANSI
driver is installed and should be used for the CLS and
COLOR commands. 4DOS normally determines this itself,
but if you are using a non-standard ANSI driver or your
loading sequence is unusual, you may need to explicitly
inform 4DOS. Also see SETDOS /A. This directive is not
available in 4OS2 (because 4OS2 assumes that ANSI support
is always enabled), or 4DOS/NT (because Windows NT does
not offer ANSI support).

BatchEcho = YES | No: Sets the default batch ECHO mode.
Yes enables echoing of all batch file commands unless
ECHO is explicitly set off in the batch file. No
disables batch file echoing unless ECHO is explicitly set
on. Also see SETDOS /V.

BeepFreq = nnnn (440): Sets the default BEEP command
frequency in Hz. This is also the frequency for "error"
beeps (for example, if you press an illegal key). To
disable all error beeps set this or BeepLength to 0. If
you do, the BEEP command will still be operable, but will
not produce sound unless you explicitly specify the
frequency and duration.

BeepLength = nnnn (2): Sets the default BEEP length in
system clock ticks (approximately 1/18 of a second per
tick). BeepLength is also the default length for "error"
beeps (for example, if you press an illegal key).

CommandSep = c: This is the character used to separate
multiple commands on the same line. The default is the
caret [^] in 4DOS, and the ampersand [&] in 4OS2 and
4DOS/NT. You cannot use any of the redirection
characters (| > < ) or any of the whitespace characters
(space, tab, comma, or equal sign). Also see SETDOS /C,
the %+ internal variable on page 100, and page 72 for
information on using compatible command separators for
two or more products.

CursorIns = nnnn (100): This is the shape of the cursor
for insert mode during command-line editing and all
commands which accept line input (DESCRIBE, ESET, etc.).
The size is a percentage of the total character cell
size, between 0% and 100%. Because of the way video
BIOSes and drivers map the cursor shape, you may not get
a smooth progression in cursor shapes as CursorIns and
CursorOver change. Also see SETDOS /S.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 131

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

CursorOver = nnnn (15): This is the shape of the cursor
for overtype mode during command-line editing and all
commands which accept line input. The size is a
percentage of the total character cell size, between 0%
and 100%. Also see SETDOS /S.

DescriptionMax = nnnn (40): Controls the description
length limit for DESCRIBE (see page 193). The allowable
range is 20 to 200 characters.

Descriptions = YES | No: Turns description handling on
or off during the file processing commands COPY, DEL,
MOVE, and REN. If set to No, the command processor will
not update the description file when files are moved,
copied, deleted or renamed. Also see SETDOS /D.

EditMode = Insert | OVERSTRIKE: This directive lets you
start the command-line editor in either insert or
overstrike mode. Also see SETDOS /M.

EscapeChar = c : Sets the character used to suppress the
normal meaning of the following character. The default
is Ctrl-X [-] in 4DOS, and a caret [^] in 4OS2 and
4DOS/NT. See page 71 for a description of the escape
character and special escape sequences. You cannot use
any of the redirection characters (|, >, or < ) or the
whitespace characters (space, tab, comma, or equal sign)
as the escape character. Also see SETDOS /E, the %=
internal variable on page 99, and page 72 for information
on using compatible escape characters for two or more
products.

HistCopy = Yes | NO: Controls what happens when you re-
execute a line from the command history. If this option
is set to Yes, the line is appended to the end of the
history list. By default, or if this option is set to
No, no copy of the command is made. The original copy of
the command is always retained at its original position
in the list, regardless of the setting of HistCopy.

HistLogName = File: Sets the history log file name
and/or path. If only a path is given, the default log
file name (4DOSHLOG, 4OS2HLOG, etc.) will be used. Using
HistLogName does not turn history logging on; you must
use a LOG /H ON command to do so.

HistMin = nnnn (0): Sets the minimum command-line size
to save in the command history list. Any command line
whose length is less than this value will not be saved.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 132

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

Legal values range from 0, which saves everything, to the
maximum command-line length plus 1 (i.e., 256 in 4DOS, or
1024 in 4OS2 and 4DOS/NT), which disables all command
history saves.

HistWinColors = Color: Sets the default colors for the
command-line and directory history windows. If this
directive is not used the colors will be reversed from
the current colors on the screen.

HistWinHeight = nn (12): Sets the height of the command-
line and directory history windows in lines, including
the border. Legal values range from 5 to the height of
your screen. Any value which would cause the bottom of
the window to be off the screen will be adjusted so that
the entire window remains on the screen.

HistWinLeft = nn (40): Sets the horizontal position of
the left side of the command-line and directory history
windows. Legal values range from 0 (the left edge of the
screen) to the number of columns on your screen minus 10.
Any value which would cause the right side of a minimum-
width window to be off the screen will be adjusted so
that the entire window remains on the screen.

HistWinTop = nn (1): Sets the vertical position of the
top of the command-line and directory history windows.
Legal values range from 0 (the top of the screen) to the
number of rows on your screen minus 5. Any value which
would cause the bottom of a minimum-height window to be
off the screen will be adjusted so that the entire window
remains on the screen.

HistWinWidth = nn (36): Sets the width of the command-
line and directory history windows in characters,
including the border. Legal values range from 10 to the
width of your screen. Any value which would cause the
right side of the window to be off the screen will be
adjusted so that the entire window remains on the screen.

4DOS, LineInput = Yes | NO: This directive controls how 4DOS
4NT and 4OS2 get their input from the command line. Yes
forces 4DOS and 4OS2 to perform line-by-line input, just
as COMMAND.COM and CMD.EXE do, instead of character-by-
character input. This will disable command-line editing,
history recall, the directory history window, and
filename completion, and will reduce the 4OS2 input
length limit from 1023 characters to 255 characters. It
is normally used only for rare memory-resident programs

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 133

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

(TSRs) or applications which do not work properly unless
the command processor uses line input. If you have a
particular program that requires line input, you can use
SETDOS /L to temporarily change modes. See APPNOTES.DOC
(for 4DOS) or README.DOC (for 4OS2) for information on
programs which require this option.

LogName = File: Sets the log file name and/or path. If
only a path is given, the default log file name (4DOSLOG,
4OS2LOG, etc.) will be used. Using LogName does not turn
logging on; you must use a LOG ON command to do so.

NoClobber = Yes | NO: If set to Yes, will prevent
standard output redirection (see page 50) from
overwriting an existing file, and will require that the
output file already exist for append redirection. Also
see SETDOS /N.

ParameterChar = c: Sets the character used after a
percent sign to specify all or all remaining command-line
arguments in a batch file or alias (e.g., %& or %n&; see
pages 79 and 162). The default is the ampersand [&] for
4DOS and the dollar sign [$] for 4OS2 and 4DOS/NT. Also
see SETDOS /P. See page 72 for information on using
compatible parameter characters for two or more
products..

Printer = devicename: Sets the output device that the
LIST command will print to. By default, LPT1 is used.
The device can be PRN, LPT1 to 3, COM1 to 4, NUL (which
will disable printed output) or any other installed
character device.

4DOS ScreenColumns = nnnn: Sets the number of columns used by
the video display. Normally the screen size is
determined automatically, but if you have a non-standard
display you may need to set it explicitly. Systems which
need to set OutputBIOS to Yes (see page 143) may also
need to use this directive.

ScreenRows = nnnn: Sets the number of screen rows used
by the video display. Normally the screen size is
determined automatically, but if you have a non-standard
display you may need to set it explicitly. This value
does not affect screen scrolling, which is controlled by
your operating system, or (under DOS) your video BIOS or
ANSI driver. ScreenRows is used only by the LIST and
SELECT commands, the paged output options of other


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 134

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

commands (e.g., TYPE /P), and error checking in the
screen output commands. Also see SETDOS /R.

UpperCase = Yes | NO: Yes specifies that filenames
should be displayed in the traditional upper-case by
internal commands like COPY and DIR. No allows the
normal 4DOS, 4OS2, and 4DOS/NT lower-case style. This
directive does not affect the display of filenames on
HPFS and NTFS drives; see page 17 for more details. Also
see SETDOS /U.


Color Directives

These directives control the colors that 4DOS, 4OS2, and
4DOS/NT use for their displays. Screen border colors can only
be set in StdColors. "BORder" color specifications included
in other directives will be ignored. For complete details on
color names see page 26.

4DOS, BrightBG = Yes | No. If set to Yes, 4DOS and 4OS2 will
4OS2 enable bright background colors. If set to No, bright
backgrounds will be disabled but blinking foreground
characters will be enabled. If BrightBG is not used,
4DOS and 4OS2 will not adjust the bright background /
blinking foreground switch at all. Most color video
boards default to a blinking foreground with bright
background colors disabled. See also SETDOS /B.

Using BrightBG requires careful attention to interactions
of display type, mode, and color. For a detailed
explanation, see page 27.

ColorDir = ext1 ext2 ...:colora;ext3 ext4 ... :colorb;
...: Sets the directory colors used by DIR and SELECT.
The format is the same as that used for the COLORDIR
environment variable. See page 30 for a detailed
explanation of color-coded directories.

InputColors = Color: Sets the colors used for command-
line input. This setting is useful for making your input
stand out from the normal output. InputColors will not
work properly under 4DOS unless you have an ANSI driver
loaded (see page 24 for more information on ANSI).

ListColors = Color: Sets the colors used by the LIST
command. If this directive is not used, LIST will use
the current default colors set by the CLS or COLOR
command or by the StdColors directive, below.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 135

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

ListStatBarColors = Color: Sets the colors used on the
LIST status bar. If this directive is not used, LIST
will set the status bar to the reverse of the screen
color (the screen color is controlled by ListColors,
above).

SelectColors = Color: Sets the color used by the SELECT
command. If this directive is not used, SELECT will use
the current default colors set by the CLS or COLOR
command or by the StdColors directive, below.

SelectStatBarColors = Color: Sets the color used on the
SELECT status bar. If this directive is not used, SELECT
will set the status bar to the reverse of the screen
color (the screen color is controlled by SelectColors,
above).

StdColors = Color: Sets the standard colors to be used
when CLS is used without a color specification, and for
LIST and SELECT if ListColors and SelectColors are not
used. Using this directive is similar to placing a COLOR
command in AUTOEXEC.BAT. StdColors takes effect the
first time CLS, LIST, or SELECT is used after 4DOS, 4OS2,
or 4DOS/NT starts, but will not affect the color of error
or other messages displayed during the loading and
initialization process. Under 4DOS, if ANSI.SYS or a
compatible driver is not loaded, the colors will not be
"sticky" - you may lose them when you run an application.


## Key Mapping Directives

The directives in this group allow you to change the keys used
for command-line editing and other internal functions. They
take effect only inside 4DOS, 4OS2, or 4DOS/NT, and do not
affect other programs or the help system.

The description of each directive below explains the function
of the corresponding key. Using the directive allows you to
assign a different or additional key to perform the function
described. For example, to use function key F3 to invoke the
HELP facility (normally invoked with F1):

Help = F3

Any directive can be used multiple times to assign multiple
keys to the same function. For example:

ListFind = F ;F does a find in LIST

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 136

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

ListFind = F5 ;F5 also does a find in LIST

Use some care when you reassign keystrokes. If you assign a
default key to a different function, it will no longer be
available for its original use. For example, if you assign F1
to the AddFile directive (a part of filename completion), the
F1 key will no longer invoke the help system, so you will
probably want to assign a different key to Help.

Please read the information on key names beginning on page 31
before using the key mapping directives.

Key assignments are processed before looking for keystroke
aliases. For example, if you assign Shift-F1 to HELP and also
assign Shift-F1 to a key alias, the key alias will be ignored.

Assigning a new keystroke for a function does not deassign the
default keystroke for the same function. If you want to
deassign one of the default keys, use the NormalKey directive
described below or the corresponding directive for keys in the
other key groups (NormalEditKey, NormalHWinKey, or
NormalListKey).


General Input Keys

This first set of Key Mapping Directives applies to all
input. These directives are in effect whenever 4DOS,
4OS2, or 4DOS/NT requests input from the keyboard,
including during command-line editing and the DESCRIBE,
ESET, INPUT, LIST, and SELECT commands. See page 34 for
more information about command-line editing.

Backspace = Key (Bksp): Deletes the character to the
left of the cursor.

BeginLine = Key (Home): Moves the cursor to the
beginning of the line.

Del = Key (Del): Deletes the character at the cursor.

DelToBeginning = Key (Ctrl-Home): Deletes from the
cursor to the start of the line.

DelToEnd = Key (Ctrl-End): Deletes from the cursor to
the end of the line.

DelWordLeft = Key (Ctrl-L): Deletes the word to the
left of the cursor.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 137

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

DelWordRight = Key (Ctrl-R, Ctrl-Bksp): Deletes the
word to the right of the cursor. See ClearKeyMap on page
141 if you need to remove the default mapping of Ctrl-
Bksp to this function.

Down = Key (Down): Scrolls the display down one line in
LIST; moves the cursor down one line in SELECT and in the
command-line history, directory history, or %@SELECT
window. (Scrolling down through the command history at
the prompt is controlled by NextHistory on page 139, not
by this directive.)

EndLine = Key (End): Moves the cursor to the end of the
line.

EraseLine = Key (Esc): Deletes the entire line.

ExecLine = Key (Enter): Executes or accepts a line.

Ins = Key (Ins): Toggles insert / overstrike mode during
line editing.

Left = Key (Left): Moves the cursor left one character;
scrolls the display left 8 columns in LIST; scrolls the
display left 4 columns in the command-line, directory
history, or %@SELECT window.

NormalKey = Key: Deassigns a general input key in order
to disable the usual meaning of the key within 4DOS,
4OS2, or 4DOS/NT and/or make it available for keystroke
aliases. This will make the keystroke operate as a
"normal" key with no special function. For example:

NormalKey = Ctrl-End

will disable Ctrl-End, which is the standard "delete to
end of line" key. Ctrl-End could then be assigned to a
keystroke alias. Another key could be assigned the
"delete to end of line" function with the DelToEnd
directive (above).

Right = Key (Right): Moves the cursor right one
character; scrolls the display right 8 columns in LIST;
scrolls the display right 4 columns in the command-line
history, directory history, or %@SELECT window.

Up = Key (Up): Scrolls the display up one line in LIST;
moves the cursor up one line in SELECT and in the
command-line history, directory history, or %@SELECT

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 138

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

window. (Scrolling up through the command history at the
prompt is controlled by PrevHistory on page 139, not by
this directive.)

WordLeft = Key (Ctrl-Left): Moves the cursor left one
word; scrolls the display left 40 columns in LIST.

WordRight = Key (Ctrl-Right): Moves the cursor right
one word; scrolls the display right 40 columns in LIST.


Command-Line Editing Keys

The following directives apply only to command-line
editing. They are only effective at the 4DOS, 4OS2, or
4DOS/NT prompt.

AddFile = Key (F10): Keeps the current filename
completion entry and inserts the next matching name.

CommandEscape = Key (Alt-255): Allows direct entry of a
keystroke that would normally be interpreted as an editor
command.

DelHistory = Key (Ctrl-D): Deletes the displayed
history list entry and displays the previous entry.

EndHistory = Key (Ctrl-E): Displays the last entry in
the history list.

Help = Key (F1): Invokes the HELP facility.

NextFile = Key (F9, Tab): Gets the next matching
filename. See ClearKeyMap on page 141 if you need to
remove the default mapping of Tab to this function.

NextHistory = Key (Down): Recalls the next command from
the command history.

NormalEditKey = Key: Deassigns a command-line editing
key in order to disable the usual meaning of the key
while editing a command line, and/or make it available
for keystroke aliases. For details see the NormalKey
directive on page 138.

PopFile = Key (F7, Ctrl-Tab): Opens the filename
completion window. You may not be able to use Ctrl-Tab,
because not all systems recognize it as a keystroke. See


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 139

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

ClearKeyMap on page 141 if you need to remove the default
mapping of Ctrl-Tab to this function.

PrevFile = Key (F8, Shift-Tab): Gets the previous
matching filename. See ClearKeyMap on page 141 if you
need to remove the default mapping of Shift-Tab to this
function.

PrevHistory = Key (Up): Recalls the previous command
from the command history.

SaveHistory = Key (Ctrl-K): Saves the command line in
the command history list without executing it.


History and @SELECT Window Keys

The following directives apply only to the command
history window, the directory history window, and
%@SELECT windows.

DirWinOpen = Key (Ctrl-PgUp): Opens the directory
history window while at the command line.

HistWinBegin = Key (Ctrl-PgUp): Moves to the first line
of the history when in the history window.

HistWinDel = Key (Ctrl-D): Deletes a line from within
the history window.

HistWinEdit = Key (Ctrl-Enter): Moves a line from the
history window to the prompt for editing.

HistWinEnd = Key (Ctrl-PgDn): Moves to the last line of
the history when in the history window.

HistWinExec = Key (Enter): Executes the selected line in
the history window.

HistWinOpen = Key (PgUp): Brings up the history window
while at the command line.

NormalHWinKey = Key: Deassigns a history window key in
order to disable the usual meaning of the key within the
history window. For details see the NormalKey directive
on page 138.




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 140

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

LIST Keys

The keys in the last group of Key Mapping Directives are
effective only inside the LIST command.

ListFind = Key (F): Prompts and searches for a string.

ListHex = Key (X): Toggles hexadecimal display mode.

ListHighBit = Key (H): Toggles LIST's "strip high bit"
option, which can aid in displaying files from certain
word processors.

ListInfo = Key (I): Displays information about the
current file.

ListNext = Key (N): Finds the next matching string.

ListPrint = Key (P): Prints the file on LPT1.

ListWrap = Key (W): Toggles LIST's wrap option on and
off. The wrap option wraps text at the right margin.

NormalListKey = Key: Deassigns a LIST key in order to
disable the usual meaning of the key within LIST. For
details see the NormalKey directive on page 138.


## Advanced Directives

These directives are generally used for unusual circumstances,
or for diagnosing problems. Most often they are not needed in
normal use.


Advanced Directives For 4DOS, 4OS2, and 4DOS/NT

The directives in this section work in 4DOS, 4OS2, and
4DOS/NT.

ClearKeyMap: Clears all current key mappings.
ClearKeyMap is a special directive which has no value or
"=" after it. Use ClearKeyMap to make one of the keys in
the default map (Tab, Shift-Tab, Ctrl-Tab, or Ctrl-Bksp)
available for a keystroke alias, or in the [Secondary]
section of the .INI file to clear key mappings inherited
from the primary shell. ClearKeyMap should appear before
any key mapping directives. If you want to clear some
but not all of the default mappings, use ClearKeyMap,

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 141

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

then recreate the mappings you want to retain (e.g., with
"NextFile=Tab", etc.).

NextINIFile = File. The full path and name of the file
must be specified. All subsequent shells will read the
specified .INI file, and ignore any [Secondary] section
in the original .INI file. Under 4DOS, if you have a
diskless or floppy-based workstation, NextINIFile will
allow you to shift 4DOS.INI to a network drive for
secondary shells, and avoid all access to the original
boot drive.


Advanced Directives For 4DOS Only

4DOS The following advanced directives apply to 4DOS only, and
will not work in 4OS2 or 4DOS/NT.

CritFail = Yes | NO: This is the same as /F on the
SHELL= line in CONFIG.SYS. It intercepts all DOS
critical errors and returns a Fail to each. We do not
recommend this on most systems, because you will not have
a chance to react to a critical error and correct the
problem that caused it. It is intended for use on
bulletin boards or other systems where unattended
operation is required without user prompts.

DiskReset = Yes | NO: Enables or disables disk resets
after COPY, DEL/ERASE, DESCRIBE, MOVE, and REN/RENAME,
before DIR, and when starting 4DOS. Set to Yes if you
have problems with disk change detection on non-standard
or cached floppy disk drives, or with network software
which doesn't always properly flush data to the disk.
Such problems are very rare, so normally No is the best
choice. Setting DiskReset to Yes may increase the time
required to start a secondary shell, and may reduce the
performance of DIR, COPY, MOVE, and RENAME, when using a
"staged-write" disk cache such as Microsoft's SmartDrive.
See APPNOTES.DOC for details on how specific cache
software is affected by the DiskReset setting.

DVCleanup = YES | No. Controls the cleanup of 4DOS
resources (the shell number and any disk swap file) when
you close a 4DOS window from the DESQview menu. See
APPNOTES.DOC for more details.

FullINT2E = YES | No: Enables full support for the
COMMAND.COM "back door" (interrupt 2E) which some
programs use to execute commands. Effective only in a

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 142

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

primary shell loaded via the SHELL= command in
CONFIG.SYS. See Appendix B of the 4DOS Introduction and
Installation Guide for details on using INT 2E. Also,
see APPNOTES.DOC for information on programs known to
require this option. If this directive is set to No, INT
2E will return immediately to the calling program without
taking any action. Setting FullINT2E to No reduces the
size of the primary shell by about 100 bytes.

Inherit = YES | No: .INI file data, aliases, and the
history list are normally passed to secondary shells
automatically. No disables this feature.

MessageServer = YES | No: For compatibility with
COMMAND.COM in MS-DOS 4.x and above, 4DOS includes a
"message server" that retrieves error message text for
DOS external commands like DISKCOPY and FORMAT. The
message server increases the size of the resident portion
of 4DOS by about 200 bytes. No disables the message
server and saves this space, but will cause more cryptic
error messages such as "Parse error 3" or "Extended error
7" from some DOS external commands. The message server
is automatically enabled by 4DOS in the primary 4DOS
shell loaded from CONFIG.SYS when running under MS-DOS
4.x or above, and disabled elsewhere.

NetwareNames = Yes | NO. Set to Yes to include strings
in the resident portion of 4DOS which Novell Netware
searches for when it loads. NetwareNames should be Yes
for Netware systems to avoid problems with destroyed
environment variables during LOGIN. Setting NetwareNames
to Yes increases 4DOS's low DOS memory usage by 112
bytes.

OutputBIOS = Yes | NO: Determines whether 4DOS uses the
BIOS for all screen displays. If set to No, 4DOS will
use direct screen writes for color-coded directories and
the DRAWBOX, DRAWHLINE, DRAWVLINE, LIST, SELECT, SCRPUT,
and VSCRPUT commands. If set to Yes, 4DOS will perform
these commands using BIOS calls. This directive is only
needed for compatibility with unusual display adapters,
such as those used on Japanese systems running DOS/V.
Setting OutputBIOS to Yes may substantially reduce the
speed of the affected commands.

StackSize = nnnn (4096): Set the 4DOS internal stack
size. The allowable range of values is 4096 to 8192.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 143

CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

If you use complex combinations of "prefix" commands like
DO, EXCEPT, FOR, GLOBAL, IF, IFF, and SELECT on the same
command line, and especially if you use these commands in
multiple nested batch files or GOSUBs, you may encounter
a "4DOS internal stack overflow" error. If you do, you
should use this directive to increase the amount of stack
space available.

For virtually all users, the default stack size will be
sufficient. If you increase the stack size, you will
increase the size of 4DOS's transient portion in memory,
and the size of the 4DOS swap area, by the amount of the
stack size increase.

You will not normally encounter a stack size problem with
4OS2 or 4DOS/NT, because both can increase the size of
the internal stack dynamically. This is not feasible
under DOS.

SwapReopen = Yes | NO: Set to Yes to enable reopening of
the 4DOS swap file if it is closed by another program.
This is required when swapping 4DOS to Novell Netware
drives or when using other applications which close
4DOS's swap file. In all other circumstances, it is only
useful for diagnostic purposes. Setting SwapReopen to
Yes also disables the reduced swapping size normally used
in 4DOS secondary shells.

UniqueSwapName = Yes | No: Set to Yes to change the disk
swap file name from 4DOSSWAP.nnn to a unique name
generated by 4DOS, with an extension of "4SW" (e.g.,
A1CD6B11.4SW). This prevents conflicts between swap
files in different shells; it is only necessary when you
are using disk swapping with a COMMAND.COM primary shell
or in an OS/2 2.x DOS session. The default is Yes in
OS/2 DOS sessions and No elsewhere. UniqueSwapName only
works in DOS 3.0 and above, and in OS/2 DOS sessions, and
applies only to disk swapping.


Examples

The following examples will give you an idea of the types of
things that can be done with the .INI file. The comments on
each directive explain what it does.

First, a very simple 4DOS example that just sets up swapping
and environment size, leaving everything else at its default
value:

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 144


CHAPTER 5 / CONFIGURATION
-------------------------------------------------------------------

Swapping = ems, c:\ ;try EMS, then C: root
Environment = 1024 ;set environment size

Here's another 4DOS example, for a system which supports Upper
Memory blocks (UMBs). Several settings take advantage of
UMBs, and others modify the 4DOS configuration to match the
user's preferences. Note that the comment for the Swapping
directive is on separate lines before the directive itself, as
no comments are allowed in string directives:

Environment = 3072 ;expand environment to 3K
Alias = 6144 ;expand aliases to 6K
LocalHistory = No ;use a global history
;for swapping try XMS, then RAM disk H:, then
;hard disk C:
Swapping = xms, h:\, c:\
UMBLoad = Yes ;res. part of 4DOS in UMB
UMBEnvironment = Yes ;master environment in UMB
UMBHistory = Yes ;global history in UMB
BatchEcho = No ;default is ECHO OFF
EditMode = Insert ;editor in insert mode
CursorOver = 100 ;overstrike cursor 100%
CursorIns = 10 ;insert cursor 10%

This example for 4OS2 configures certain special characters to
match 4DOS, and changes other default settings to suit the
user's preferences. All of these settings except HelpBook
would also work in 4DOS or 4DOS/NT:

PauseOnError = No ;don't stop on INI errors
CommandSep = ^ ;4DOS command separator
EscapeChar = - ;4DOS escape character
ParameterChar = & ;4DOS parameter character
BatchEcho = No ;default to ECHO OFF
HelpBook = 4OS2
History = 2048 ;expand history to 2K bytes
BeepFreq = 880 ;make beep higher pitch
EditMode = Insert ;insert mode for cmd edit
CursorOver = 100 ;overstrike cursor 100%
CursorIns = 10 ;insert cursor 10%
ListFind = F5 ;F5 does a find in LIST
ListNext = F6 ;and F6 does a find next
StdColors = bri cya on blu ;default colors
ListColors = bri whi on blu ;colors for LIST
SelectColors = bri whi on blu ;same colors for SELECT
colordir = DIRS:bri yel;com exe bat btm cmd:bri whi




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 145

CHAPTER 6 / COMMAND REFERENCE GUIDE
-------------------------------------------------------------------


CHAPTER 6 / COMMAND REFERENCE GUIDE


The following pages are a complete guide and reference to the 4DOS,
4OS2, and 4DOS/NT commands that are available from the command
line, in aliases, and in batch files. All of these commands are
internal commands, which means that the command processor performs
the activity you have requested without running another program.
(See page 18 for more information on internal and external
commands.)

We offer over 80 internal commands, many more than any version of
COMMAND.COM or CMD.EXE. These neither replace nor interfere with
external commands like BACKUP, CHKDSK, DISKCOPY, or XCOPY. You can
continue to use those utilities like you always have. Also, each
of our command processors has been designed to be compatible with
virtually all traditional internal commands, and to enhance most of
those commands with additional options and capabilities. Once you
have installed your new command processor, you can continue using
the commands that you already know and get the same results.

We have made no attempt to document external DOS, OS/2, and Windows
NT commands in this reference, partly because they are explained in
your operating system manual, and partly because external commands,
and the options available with each command, vary widely from one
operating system to another and from one version to another. The
4DOS HELP system does include information about standard DOS
external commands, and the 4OS2 HELP system can be configured to
display information about OS/2 external commands (see the
Introduction and Installation Guide for each product for further
details).

Most 4DOS, 4OS2, and 4DOS/NT commands are either enhanced
traditional commands or are entirely new (a few are the same as
traditional commands). If you are comfortable using traditional
commands, you can switch to your new command processor without
making any changes in your habits. But you will be missing a lot
of the power of these enhancements and new commands unless you take
a few minutes to see what's available here. Make sure you don't
skip a section of this reference just because you already know how
to use a traditional command with the same name.

If you come across terms or concepts in this chapter that you are
unsure about, please refer to Chapter 1 / General Concepts, the
Glossary on page 368, or the Index.




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 146

CHAPTER 6 / COMMAND REFERENCE GUIDE
-------------------------------------------------------------------



Command Categories

The best way to learn the commands is to use them and
experiment with them. We urge you to browse through this
chapter occasionally and look for commands that might help
simplify your computing life. The following lists categorize
the available commands by topic and will help you find the
ones that you need. Commands listed below with an asterisk
[*] are not available in all command processors; see the list
at the end for details.

System configuration:

BREAK * CHCP * CLS COLOR
CTTY * DATE FREE HISTORY
KEYS * KEYBD LH/LOADHIGH* LOG
MEMORY PROMPT REBOOT SETDOS
SWAPPING * TIME VER VERIFY
VOL

File and directory management:

ATTRIB COPY DEL/ERASE DESCRIBE
LIST MOVE REN/RENAME SELECT
TRUENAME * TYPE

Subdirectory management:

CD/CHDIR CDD DIR DIRS
MD/MKDIR POPD PUSHD RD/RMDIR

Input and output:

DRAWBOX DRAWHLINE DRAWVLINE ECHO
ECHOS INKEY INPUT KEYSTACK *
MSGBOX * SCREEN SCRPUT TEXT
VSCRPUT

Commands primarily for use in or with batch files and aliases
(some work only in batch files; see the individual commands
for details):

ALIAS BEEP CALL CANCEL
DELAY DO ENDLOCAL FOR
GLOBAL GOSUB GOTO IF
IFF LOADBTM ON PAUSE
QUIT REM RETURN SETLOCAL

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 147

CHAPTER 6 / COMMAND REFERENCE GUIDE
-------------------------------------------------------------------

SHIFT TEXT UNALIAS

Environment and path commands:

DPATH * ESET PATH SET
UNSET

Window management commands:

ACTIVATE * TITLE * WINDOW *

Other commands:

? DETACH * EXCEPT EXIT
HELP LIST START TEE
TIMER Y

* Some of these commands are not included in one or more of
our command processors. Usually a command is left out of a
product when it is not useful or cannot be implemented in that
environment (for example, the DETACH command is related to
multitasking, and is not available under DOS because DOS does
not offer multitasking). The commands that are specific to
particular products are:

ACTIVATE ....4DOS/NT KEYSTACK .....4DOS
BREAK .......4DOS, 4DOS/NT LH/LOADHIGH ..4DOS
CHCP ........4DOS, 4OS2 MSGBOX ......4DOS/NT
CTTY ........4DOS SWAPPING .....4DOS
DETACH ......4OS2, 4DOS/NT TITLE ........4DOS/NT
DPATH .......4OS2, 4DOS/NT TRUENAME .....4DOS
KEYS ........4OS2, 4DOS/NT WINDOW .......4OS2, 4DOS/NT


How to Use the Command Descriptions

Each of the internal commands is described in detail on the
following pages. The descriptions are arranged
alphabetically, and each includes examples that will help you
learn to use the commands.

Each description begins with the name of the command on the
left side of the page. If the command is only available in
some of our products, those products are listed next to the
command name, and in the page header. Commands marked "New"
on the right side of the page are unique to 4DOS, 4OS2, or
4DOS/NT. Those marked "Enhanced" are similar to traditional
commands but add new features and options. The commands


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 148

CHAPTER 6 / COMMAND REFERENCE GUIDE
-------------------------------------------------------------------

marked "Compatible" follow the syntax and features of the
traditional command with the same name.

The name is followed by a sentence or two that briefly
describes the command's purpose or major function. That
sentence should help you determine quickly whether you have
found the command you are seeking.

The next part of each description shows the command's format
or syntax. The format line uses certain conventions to
describe how the command should be entered and to create
reference points for the text describing the command:

Words in UPPER CASE must be spelled exactly as they are
shown (although you can type them in either upper or
lower case, or a combination). If a word is shown partly
in upper case (for example BLInk), only the upper case
portion is required, the rest is optional.

Words shown in italics (for example source or filename)
are meant to be replaced by other words or values. Each
of these words is explained directly beneath the format
line and discussed in more detail in the text description
of the command. When the word stands for a file name,
you can use a simple name like MYFILE.TXT, or include a
drive letter and/or a full path, like
C:\MYDIR\MYFILE.TXT.

Items followed by an ellipsis (three periods [...]) may
be repeated. For example, filename ... means you may
enter one or more file names at this point in the
command.

Text shown in [square brackets] is optional. Text
outside of square brackets must be entered literally (if
it is capitalized) or replaced by other words or values
(if it is in italics).

Vertical bars [|] represent a choice; you can pick one
option or another but not both. For example, the
following format shows that the command may be followed
by the word ON or the word OFF, but not both:

COMMAND [ ON | OFF ]

A slash followed by a letter, like [/X], is an "option"
or "switch" which controls the effect of a command. Many
commands have several switches, and you are usually free
to use none, one, or several to make a command behave as

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 149

CHAPTER 6 / COMMAND REFERENCE GUIDE
-------------------------------------------------------------------

you wish. If you use a single switch, you must precede
it with a slash. If you use several switches, in most
cases you can put them together with one slash or use
separate slashes. For example, if you wanted to use
switches X, Y, and Z for a command, you could type them
three different ways:

command /x /y /z
command /x/y/z
command /xyz

A few switches, particularly in the DIR, SELECT, and
START commands, use two or more characters. If you need
to follow a multi-letter switch with another switch, the
second switch must have its own slash to avoid ambiguity.

Included in the format section is an explanation of each
replaceable argument and a one or two word explanation of each
switch. Many descriptions also list related commands to help
you find the exact command you want.

For file handling commands, a section called "File Select"
appears immediately after the format section. This section
lists the file-handling features that the command supports.
The list may include mention of extended wildcards (see page
57); multiple file names (page 64); include lists (page 65);
and date, time, and size ranges (see page 60).

Next, you'll find a description of the command's usage. This
description normally starts with the basic functions of a
command and gradually adds more details. We've also included
many examples to help you see the command in action.

The last part of each description is a detailed explanation of
the options or switches available for each command, in
alphabetical order. Occasionally, we've included more
examples in this section to demonstrate how a switch is used
or how multiple switches interact.

Most of the commands and their switches have the same use in
4DOS, 4OS2, and 4DOS/NT. When a command, feature, or switch
applies to a single product, we mention it specifically in the
text. When an entire paragraph applies to a specific product,
we use marginal text to identify that product. When an entire




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 150

CHAPTER 6 / COMMAND REFERENCE GUIDE
-------------------------------------------------------------------

command is only available in one or two products, the products
are listed next to the command name, and in the page headings.

4DOS marks information that applies only to 4DOS.

4OS2 marks information that applies only to 4OS2.

4NT marks information that applies only to 4DOS/NT.

Occasionally, a command or switch will be marked with two of
these marginal notations when it applies to two different
products.

An exclamation point [!] to the left of a paragraph means that
paragraph contains a caution or warning you should observe
when using the feature it discusses.

In the Usage and Options sections you may see the symbol## .
This indicates a more in-depth discussion or an advanced topic
which you can skip if you are new to the command; come back to
this topic later for more details, or if you're having trouble
with the command. In most cases the remainder of the section
after such a symbol is devoted to similar information.

The ## doesn't mean that only advanced users will need the
information - you may find it useful even if you're relatively
new to computers or to our products. But it does mean that
you can skip the marked section and still understand and use
the basic features of the command. If a ## appears before the
"Usage" heading, it indicates that the entire command is
generally used only in unusual situations or by more advanced
users.

When you see a ## in the list of options, remember that the
options are listed alphabetically, so there may be more basic
options discussed later in the list, after a more complex or
advanced option marked with## . Don't stop reading the option
list the first time you see the mark.












-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 151

?
-------------------------------------------------------------------

? (New)

Purpose: Display a list of internal commands.

Format: ?

Usage: ? displays a list of internal commands. For help with
these commands, see the HELP command.

When you use the ? command, you will see a display
like this (the list below is for 4DOS; you will see a
slightly different list for 4OS2 or 4DOS/NT):

c:\> ?
? ALIAS ATTRIB BEEP
BREAK CALL CANCEL CD
CDD CHCP CHDIR CLS
COLOR COPY CTTY DATE
DEL DELAY DESCRIBE DIR
DIRS DO DRAWBOX DRAWHLINE
DRAWVLINE ECHO ECHOS ENDLOCAL
ERASE ESET EXCEPT EXIT
FOR FREE GLOBAL GOSUB
GOTO HELP HISTORY IF
IFF INKEY INPUT KEYBD
KEYSTACK LH LIST LOADBTM
LOADHIGH LOG MD MEMORY
MKDIR MOVE ON PATH
PAUSE POPD PROMPT PUSHD
QUIT RD REBOOT REM
REN RENAME RETURN RMDIR
SCREEN SCRPUT SELECT SET
SETDOS SETLOCAL SHIFT START
SWAPPING TEE TEXT TIME
TIMER TRUENAME TYPE UNALIAS
UNSET VER VERIFY VOL
VSCRPUT Y

If you have disabled a command with SETDOS /I, it will
not appear in the list.










-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 153

[4DOS/NT] ACTIVATE
-------------------------------------------------------------------

ACTIVATE [4DOS/NT] (New)

Purpose: Activate a window, set its state, or change its title.

Format: ACTIVATE "window" [MAX | MIN | RESTORE | CLOSE |
"title" ]

window: Current title of window to work with.
title: New title for window.

See also: START, TITLE, and WINDOW.

Usage: Both the current name of the window and the new name,
if any, must be enclosed in double quotes. The quotes
will not appear as part of the title bar text.

If no options are used, the window named in the
command will become the active window and be able to
receive keystrokes and mouse commands.

The MAX option expands the window to its maximum size,
the MIN option reduces the window to an icon, and the
RESTORE option returns the window to its default size
and location on the desktop. The CLOSE option closes
the window and ends the session running in the window.

This example renames and maximizes the window called
"4DOS/NT":

[c:\] activate "4DOS/NT" max "4DOS/NT is Great!"




















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 154

ALIAS
-------------------------------------------------------------------

ALIAS (New)

Purpose: Create new command names that execute one or more
commands or redefine default options for existing
commands; assign commands to keystrokes; load or
display the list of defined alias names.

Format: ALIAS [/P /R file...] [name[=][value]]

file: One or more files to read for alias
definitions.
name: Name for an alias, or for the key to
execute the alias.
value: Text to be substituted for the alias name.

/P(ause) /R(ead file)

See also: UNALIAS, and Aliases on page 74.

Usage: The ALIAS command lets you create new command names or
redefine internal commands. It also lets you assign
one or more commands to a single keystroke. An alias
is often used to execute a complex series of commands
with a few keystrokes or to create "in memory batch
files" that run much faster than disk-based batch
files.

For example, if you would rather type D instead of DIR
/W, you would use the command:

c:\> alias d = dir /w

Now when you type a single d as a command, it will be
translated into a DIR /W command.

If you define aliases for commonly used application
programs, you can often remove the directories they're
stored in from the PATH. For example, if you use
Quattro Pro and had the C:\QPRO directory in your
path, you could define the following alias:

c:\> alias qpro = c:\qpro\q.exe

With this alias defined, you can probably remove
C:\QPRO from your path. Quattro Pro will now load
much faster than it would if the command processor had
to search the PATH for it. In addition, the PATH can
be shorter, which will speed up searches for other
programs.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 155

ALIAS
-------------------------------------------------------------------

If you apply this technique for each application
program, you can often reduce your PATH to just two or
three directories containing utility programs, and
significantly reduce the time it takes to load most
software on your system. Before removing a directory
from the PATH, you will need to define aliases for all
the executable programs you commonly use which are
stored in that directory.

Aliases are stored in memory, and are not saved
automatically when you turn off your computer or end
your current session. See page 161 for information on
saving and reloading your aliases.


Multiple Commands and Special Characters in Aliases

An alias can represent more than one command. For
example:

c:\> alias letters = `cd \letters ^ text`

creates a new command called LETTERS. The command
first uses CD to change to a subdirectory called
\LETTERS and then runs a program called TEXT. The
caret [^] is the 4DOS command separator and indicates
that the two commands are distinct and should be
executed sequentially. (The 4OS2 and 4DOS/NT command
separator is normally an ampersand [&].)

Aliases make extensive use of the command separator
(see page 45), and the parameter character (see page
134), and may also use the escape character (see page
71). These characters differ between 4DOS and 4OS2 or
4DOS/NT. In the text and examples below, we use the
4DOS characters. The difference is also explained the
first time each character is used. Be sure to insert
the correct characters for the command processor you
are using. If you want to use the same aliases under
different command processors, see page 72.

When you type alias commands at the command line or in
a batch file, you must use back-quotes [`] around the
definition if it contains multiple commands,
parameters (discussed below), environment variables,
redirection, or piping. The back-quotes prevent
premature expansion of these arguments. You may use
back-quotes around other definitions, but they are not
required. (You do not need back-quotes when your

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 156

ALIAS
-------------------------------------------------------------------

aliases are loaded from an ALIAS /R file; see below
for details.) The examples above and below include
back-quotes only when they are required.


Nested Aliases

Aliases may invoke internal commands, external
commands, or other aliases. (However, an alias may
not invoke itself, except in special cases where an IF
or IFF command is used to prevent an infinite loop.)
The two aliases below demonstrate alias nesting (one
alias invoking another). The first line defines an
alias which runs a program called WP.EXE that is in
the E:\WP60\ subdirectory. The second alias changes
directories with the PUSHD command, runs the WP alias,
and then returns to the original directory with the
POPD command:

c:\> alias wp = e:\wp60\wp.exe
c:\> alias w = `pushd c:\wp ^ wp ^ popd`

The second alias above could have included the full
path and name of the WP.EXE program instead of calling
the WP alias. However, writing two aliases makes the
second one easier to read and understand, and makes
the first alias available for independent use. If you
rename the WP.EXE program or move it to a new
directory, only the first alias needs to be changed.


Temporarily Disabling Aliases

If you put an asterisk [*] immediately before a
command in the value of an alias definition (the part
after the equal sign), it tells the command processor
not to attempt to interpret that command as another
(nested) alias. An asterisk used this way must be
preceded by a space or the command separator and
followed immediately by an internal or external
command name. The asterisk is used to signal that the
following word is the name of an internal or external
command instead of an alias which may have the same
name. It also allows two popular uses of aliases.

First, by using an asterisk, you can redefine the
default options for any internal command. For
example, suppose that you always want to use the DIR
command with the /2 (two column) and /P (pause at the

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 157

ALIAS
-------------------------------------------------------------------

end of each page) options. The following line will do
just that:

c:\> alias dir = *dir /2/p

If you didn't include the asterisk, the second DIR on
the line would be the name of the alias itself, and
the command processor would repeatedly re-invoke the
DIR alias, rather than running the DIR command. This
would cause an "Alias loop" or "Command line too long"
error. The asterisk forces interpretation of the
second DIR as a command, not an alias.

Second, an asterisk also helps you keep the names of
internal commands from conflicting with the names of
external programs. For example, suppose you have a
program called LIST.COM. Normally, the internal LIST
command will run anytime you type LIST. But two
simple aliases will give you access to both the
LIST.COM program and the LIST command:

c:\> alias list = c:\util\list.com
c:\> alias display = *list

The first line above defines LIST as an alias for the
LIST.COM program. If you stopped there, the external
program would run every time you typed LIST and you
would not have easy access to the internal LIST
command. The second line renames the internal LIST
command as DISPLAY. The asterisk is needed in the
second command to indicate that the following word
means the internal command LIST, not the LIST alias
which runs your external program.

Another way to understand the asterisk is to remember
that a command is always checked for an alias first,
then for an internal or external command, or a batch
file (see page 116). The asterisk at the beginning of
a command name simply skips over the usual check for
aliases when processing that command, and allows the
command processor to go straight to checking for an
internal command, external command, or batch file.

You can also use an asterisk before a command that you
enter at the command line or in a batch file. If you
do, that command won't be interpreted as an alias.
This can be useful when you want to be sure you are
running the true, original command and not an alias
with the same name, or temporarily defeat the purpose

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 158

ALIAS
-------------------------------------------------------------------

of an alias which changes the meaning or behavior of a
command. For example, above we defined an alias for
DIR which made directories display in 2-column paged
mode by default. If you wanted to see a directory
display in the normal single-column, non-paged mode,
you could enter the command *DIR and the alias would
be ignored during that one command.


Partial Alias Names

You can also use an asterisk in the name of an alias.
When you do, the characters following the asterisk are
optional when you invoke the alias command. (Use of
an asterisk in the alias name is unrelated to the use
of an asterisk in the alias value discussed above.)
For example, with this alias:

c:\> alias wher*eis = dir /sp

the new command, WHEREIS, can be invoked as WHER,
WHERE, WHEREI, or WHEREIS. Now if you type:

c:\> where myfile.txt

The WHEREIS alias will be expanded to the command:

dir /sp myfile.txt


Keystroke Aliases

If you want to assign an alias to a keystroke, use the
keyname on the left side of the equal sign, preceded
by an at sign [@]. For example, to assign the command
DIR /W to the F5 key, type

c:\> alias @F5 = dir /w

See page 31 for a complete listing of key names and a
description of the key name format.

When you define keystroke aliases, the assignments
will only be in effect at the command line, not inside
application programs. Be careful not to assign
aliases to keys that are already used at the command
line (like F1 for Help). The command-line meanings
take precedence and the keystroke alias will never be
invoked. If you want to use one of the command-line

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 159

ALIAS
-------------------------------------------------------------------

keys for an alias instead of its normal meaning, you
must first disable its regular use with the NormalKey
or NormalEditKey directive in your .INI file. See
page 137 for instructions.

If you define a keystroke alias with a single at sign
as shown above, then, when you press the F5 key, the
value of the alias (DIR /W above) will be placed on
the command line for you. You can type additional
parameters if you wish and then press Enter to execute
the command. With this particular alias, you can
define the files that you want to display after
pressing F5 and before pressing Enter to execute the
command.

If you want the keystroke alias to take action
automatically without waiting for you to edit the
command line or press Enter, you can begin the
definition with two at signs [@@]. The command
processor will execute the alias "silently," without
displaying its text on the command line. For example,
this command will assign an alias to the F6 key that
uses the CDD command to take you back to the previous
default directory:

c:\> alias @@f6 = cdd -

## A second method can also be used to make a keystroke
alias execute immediately: you can include a carriage
return character as the last character in the alias
definition. When the command processor finds the
carriage return, it executes the alias just as if you
had pressed the Enter key. Unlike the "@@" method
(above), this method will display the contents of the
alias on the screen. If you use this method, do not
define the alias with a double at sign as well. If
you do, the alias will not work properly.

To include the carriage return character, add an
escape character followed by an "r" to the end of the
alias (see page 71 for more information about the
escape character). For example, you could write the
above alias as:

c:\> alias @f6 = `cdd --r`

(If you define your alias at the command line without
using back-quotes, you must use two escape characters
before the "r". In 4DOS, the default escape character

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 160

ALIAS
-------------------------------------------------------------------

is Ctrl-X, shown above as an up-arrow [-]; in 4OS2 and
4DOS/NT, the default escape character is a caret [^].)

## You can also define a keystroke alias by using "@" or
"@@" plus a scan code for one of the permissible keys
(see Appendix B on page 357 for a list of scan codes).
In most cases it will be easier to use key names.
Scan codes should only be used with unusual keyboards
where a key name is not available for the key you are
using.


Displaying Aliases

If you want to see a list of all current ALIAS
commands, type:

c:\> alias

You can also view the definition of a single alias.
If you want to see the definition of the alias LIST,
you can type:

c:\> alias list


Saving and Reloading Your Aliases

You can save your aliases to a file called ALIAS.LST
this way:

c:\> alias > alias.lst

You can then reload all the alias definitions in the
file the next time you boot up with the command:

c:\> alias /r alias.lst

This is much faster than defining each alias
individually in a batch file. If you keep your alias
definitions in a separate file which you load when
your system starts, you can edit them with a text
editor, reload the edited file with ALIAS /R, and know
that the same alias list will be loaded the next time
you boot your computer.

When you define aliases in a file that will be read
with the ALIAS /R command, you do not need back-quotes
around the value, even if back-quotes would normally

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 161

ALIAS
-------------------------------------------------------------------

be required when defining the same alias at the
command line or in a batch file.

To remove an alias, use the UNALIAS command.


Alias Parameters

## Aliases can use command-line arguments or parameters
like those in batch files. The command-line arguments
are numbered from %0 to %127. %0 contains the alias
name. It is up to the alias to determine the meaning
of the other parameters. You can use quotation marks
to pass spaces, tabs, commas, and other special
characters in an alias parameter; see page 118 for
details.

Parameters that are referred to in an alias, but which
are missing on the command line, appear as empty
strings inside the alias. For example, if you put two
parameters on the command line, any reference in the
alias to %3 or any higher-numbered parameter will be
interpreted as an empty string.

The parameter %n& has a special meaning. 4DOS
interprets it to mean "the entire command line, from
argument n to the end." If n is not specified, it has
a default value of 1, so %& means "the entire command
line after the alias name." 4OS2 and 4DOS/NT normally
use a dollar sign [$] instead of an ampersand [&] to
indicate the remainder of the command tail (for
example, use %$ to refer to all parameters under 4OS2
or 4DOS/NT). The special parameter %# contains the
number of command-line arguments.

For example, the following alias will change
directories, perform a command, and return to the
original directory:

c:\> alias in `pushd %1 ^ %2& ^ popd`

When this alias is invoked as:

c:\> in c:\comm mycomm /xmodem /2400

the first parameter, %1, has the value c:\comm. %2 is
mycomm, %3 is /xmodem, and %4 is /2400. The command
line expands into these three separate commands:


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 162

ALIAS
-------------------------------------------------------------------

pushd c:\comm
mycomm /xmodem /2400
popd

## This next example uses the IFF command to redefine the
defaults for SET. It should be entered on one line:

c:\> alias set = `iff %# == 0 then ^ *set /p
^ else ^ *set %& ^ endiff`

This modifies the SET command so that if SET is
entered with no arguments, it is replaced by SET /P
(pause after displaying each page), but if SET is
followed by an argument, it behaves normally. Note
the use of asterisks (*set) to prevent alias loops.

## If an alias uses parameters, command-line arguments
will be deleted up to and including the highest
referenced argument. For example, if an alias refers
only to %1 and %4, then the first and fourth arguments
will be used, the second and third arguments will be
discarded, and any additional arguments beyond the
fourth will be appended to the expanded command (after
the value portion of the alias). If an alias uses no
parameters, all of the command-line arguments will be
appended to the expanded command.

## Aliases also have full access to all variables in the
environment, internal variables, and variable
functions. For example, you can create a simple
command-line calculator this way (enter this on one
line):

c:\> alias calc = `echo The answer is:
%@eval[%&]`

Now, if you enter:

c:\> calc 5 * 6

the alias will display:

The answer is: 30


## Local and Global Aliases

The aliases can be stored in either a "local" or
"global" list.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 163

ALIAS
-------------------------------------------------------------------

With a local alias list, any changes made to the
aliases will only affect the current copy of the
command processor. They will not be visible in other
shells or other sessions. A local alias list is the
default under 4DOS.

With a global alias list, all copies of the command
processor will share the same alias list, and any
changes made to the aliases in one copy will affect
all other copies. A global alias list is the default
for 4OS2 and 4DOS/NT.

You can control the type of alias list with the
LocalAliases directive in the .INI file (see page
128), and with the /L and /LA options of the START
command (see page 317).

There is no fixed rule for determining whether to use
a local or global alias list. Depending on your work
style, you may find it most convenient to use one
type, or a mixture of types in different sessions or
shells. We recommend that you start with the default
approach for your command processor, then modify it if
you find a situation where the default is not
convenient.

Whenever you start a secondary shell (see page 12)
which uses a local alias list, it inherits a copy of
the aliases from the previous shell. However, any
changes to the alias made in the secondary shell will
affect only that shell. If you want changes made in a
secondary shell to affect the previous shell, use a
global alias list in both shells.

4DOS If you select a global alias list for 4DOS running
under DOS, you can share the aliases among all copies
of 4DOS. However, if you run 4DOS under OS/2, global
lists will apply within each DOS session, but will not
allow you to share aliases between different DOS
sessions.


4OS2 ## Retaining Global Aliases with SHRALIAS
4NT
If you select a global alias list for 4OS2 or 4DOS/NT,
you can share the aliases among all copies of the
command processor running in any session. When you
close all 4OS2 or 4DOS/NT sessions, the memory for the
global alias list is released, and a new, empty alias

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 164

ALIAS
-------------------------------------------------------------------

list is created the next time you start 4OS2 or
4DOS/NT.

If you want the alias list to be retained in memory
even when no command processor session is running, you
need to load the SHRALIAS program, which performs this
service for both the global alias list and the global
history list. SHRALIAS is supplied with your copy of
4OS2 or 4DOS/NT.

To load SHRALIAS, simply run the SHRALIAS.EXE program,
which is normally installed in the same directory as
your command processor. You may find it convenient to
load SHRALIAS from your 4START file (see page 82), or,
under OS/2, from your STARTUP.CMD (see your 4OS2
Introduction and Installation Guide for details on
STARTUP.CMD).

If you try to load SHRALIAS when there is no 4OS2 or
4DOS/NT session running with a global alias or history
list enabled, then SHRALIAS will not be able to find
the lists. In this case it will display an error
message and exit. If you load SHRALIAS more than
once, the second copy will detect the original copy,
display an error message, and exit. The original copy
will remain loaded.

SHRALIAS runs as a "detached" process, which means it
does not have a screen display or accept keyboard
input. It is shut down automatically when the
operating system shuts down. To unload SHRALIAS
manually, run SHRALIAS.EXE with the parameter /U.


## The UNKNOWN_CMD Alias

If you create an alias with the name UNKNOWN_CMD, it
will be executed any time the command processor would
normally issue an "Unknown command" error message.
This allows you to define your own handler for unknown
commands. When the UNKNOWN_CMD alias is executed, the
command line which generated the error is passed to
the alias for possible processing.

! Use caution when you create the UNKNOWN_CMD alias. If
it contains an unknown command, it will be called
repeatedly and the command processor will lock up in
an infinite loop.


-------------------------------------------------------------------

Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 165

ALIAS
-------------------------------------------------------------------

Options: /P(ause): This option is only effective when ALIAS is
used to display existing definitions. It pauses the
display after each page and waits for a keystroke
before continuing (see page 48).

/R(ead file): This option loads an alias list from a
file. The format of the file is the same as that of
the ALIAS display:

name=value

where name is the name of the alias and value is its
value. You can use an equal sign [=] or space to
separate the name and value. Back-quotes are not
required around the value. You can add comments to
the file by starting each comment line with a colon
[:]. You can load multiple files with one ALIAS /R
command by placing the names on the command line,
separated by spaces:

c:\> alias /r alias1.lst alias2.lst

Each definition in an ALIAS /R file can be up to 511
characters long in 4DOS, or 2047 characters in 4OS2
and 4DOS/NT. The definitions can span multiple lines
in the file if each line, except the last, is
terminated with an escape character (see page 71).























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 166

ATTRIB
-------------------------------------------------------------------

ATTRIB (Enhanced)

Purpose: Change or view file and subdirectory attributes.

Format: ATTRIB [/D /P /Q /S] [+|-[AHRS]] files ...

files: A file, directory, or list of files or
directories on which to operate.

/D(irectories) /Q(uiet)
/P(ause) /S(ubdirectories)

Attribute flags:

+A Set the archive attribute
-A Clear the archive attribute
+H Set the hidden attribute
-H Clear the hidden attribute
+R Set the read-only attribute
-R Clear the read-only attribute
+S Set the system attribute
-S Clear the system attribute

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65).

Usage: Every file and subdirectory has 4 attributes that can
be turned on (set) or turned off (cleared): Archive,
Hidden, Read-only, and System. For details on the
meaning of each attribute, see page 18.

The ATTRIB command lets you set or clear attributes
for any file, group of files, or subdirectory. You
can view file attributes by entering ATTRIB without
specifying new attributes (i.e., without the [+|-
[AHRS]] part of the format), or with the DIR /T
command.

For example, you can set the read-only and hidden
attributes for the file MEMO:

c:\> attrib +rh memo

Attribute options apply to the file(s) that follow the
options on the ATTRIB command line. The example below
shows how to set different attributes on different
files with a single command. It sets the archive
attribute for all .TXT files, then sets the system


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 167

ATTRIB
-------------------------------------------------------------------

attribute and clears the archive attribute for
TEST.COM:

c:\> attrib +a *.txt +s -a test.com

## Your operating system also supports "D" (subdirectory)
and "V" (volume label) attributes. These attributes
cannot be altered with ATTRIB; they are designed to be
controlled only by the operating system itself.

Options: /D(irectories): If you use the /D option, ATTRIB will
modify the attributes of subdirectories in addition to
files (yes, you can have a hidden subdirectory):

c:\> attrib /d +h c:\mydir

In addition, the /D option will keep ATTRIB from
appending "\*.*" to the end of a directory name and
modifying the attributes of all the files in the
subdirectory.

If you use a directory name instead of a file name,
and omit /D, ATTRIB will append "\*.*" to the end of
the name and act on all files in that directory,
rather than acting on the directory itself.

/P(ause): Wait for a key to be pressed after each
screen page before continuing the display. Your
options at the prompt are explained in detail on page
48.

/Q(uiet): This option turns off ATTRIB's normal
screen output. It is most useful in batch files.

/S(ubdirectories): If you use the /S option, the
ATTRIB command will be applied to all matching files
in the current or named directory and all of its
subdirectories.












-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 168

BEEP
-------------------------------------------------------------------

BEEP (New)

Purpose: Beep the speaker or play simple music.

Format: BEEP [frequency duration ...]

frequency: The beep frequency in Hertz (cycles per
second).
duration: The beep length in 1/18th second
intervals.

Usage: BEEP generates a sound through your computer's
speaker. It is normally used in batch files to signal
that an operation has been completed, or that the
computer needs attention.

Because BEEP allows you to specify the frequency and
duration of the sound, you can also use it to play
simple music or to create different kinds of signals
for the user.

You can include as many frequency and duration pairs
as you wish. No sound will be generated for
frequencies less than 20 Hz, allowing you to insert
short delays. The default value for frequency is 440
Hz; the default value for duration is 2.

This batch file fragment runs a program called DEMO,
then plays a few notes and waits for you to press a
key:

demo ^ beep 440 4 600 2 1040 6
pause Finished with the demo - hit a key...

The following table gives the frequency values for a
five octave range (middle C is 262 Hz):


C 131 262 523 1046 2093

C#/Db 139 277 554 1108 2217

D 147 294 587 1174 2349

D#/Eb 156 311 622 1244 2489

E 165 330 659 1318 2637



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 169

BEEP
-------------------------------------------------------------------


F 175 349 698 1397 2794

F#/Gb 185 370 740 1480 2960

G 196 392 784 1568 3136

G#/Ab 208 415 831 1662 3322

A 220 440 880 1760 3520

A#/Bb 233 466 932 1864 3729

B 248 494 988 1976 3951




































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 170

[4DOS, 4DOS/NT] BREAK
-------------------------------------------------------------------

BREAK [4DOS, 4DOS/NT] (Compatible)

Purpose: Display, enable, or disable Ctrl-C and Ctrl-Break
checking.

Format: BREAK [ON | OFF]

Usage: The Ctrl-C and Ctrl-Break keys are used by many
programs (including 4DOS) as a signal to interrupt the
current operation. BREAK controls how often DOS
checks to see if you've entered one of these
keystrokes.

4NT Ctrl-C and Ctrl-Break checking cannot actually be
enabled or disabled under Windows NT. 4DOS/NT
supports BREAK as a "do-nothing" command, for
compatibility with CMD.EXE. This avoids errors in
batch files which use the BREAK command. The
additional discussion below applies only to 4DOS, not
to 4DOS/NT.

Normally, BREAK is turned off, and DOS only checks for
Ctrl-C and Ctrl-Break keystrokes during DOS input or
output operations involving the screen, keyboard,
serial port, and printer. However, many programs
don't use DOS for these operations, and it can be
difficult to interrupt them.

When BREAK is turned on, DOS checks for Ctrl-C and
Ctrl-Break every time a program calls DOS. Since most
programs use DOS to access files and perform other
functions, turning BREAK on makes it much more likely
that a Ctrl-C or Ctrl-Break will be noticed. If you
turn BREAK on, programs will run slightly slower than
normal (the difference is not usually noticeable).

Turning BREAK on or off only affects when DOS detects
Ctrl-C and Ctrl-Break and notifies the program you're
running. Any program can choose to ignore these
signals. Also, any external program can change the
BREAK setting on its own.

Type BREAK plus ON or OFF to set the BREAK status, or
BREAK by itself to display the current BREAK status.
For example:

c:\> break on
c:\> break
BREAK is ON

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 171

[4DOS, 4DOS/NT] BREAK
-------------------------------------------------------------------

BREAK is off by default. You can change the default
by adding a BREAK=ON command to your CONFIG.SYS file.
















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 172

CALL
-------------------------------------------------------------------

CALL (Compatible)

Purpose: Execute one batch file from within another.

Format: CALL file

file: The batch file to execute.

See also CANCEL and QUIT.

Usage: CALL allows batch files to call other batch files
(batch file nesting). The calling batch file is
suspended while the called (second) batch file runs.
When the second batch file finishes, the original
batch file resumes execution at the next command. If
you execute a batch file from inside another batch
file without using CALL, the first batch file is
terminated before the second one starts.

The following batch file fragment compares an input
line to "wp" and calls another batch file if it
matches:

input Enter your choice: %%option
if "%option" == "wp" call wp.bat

4DOS, 4OS2, and 4DOS/NT support batch file nesting up
to ten levels deep.

The current ECHO state is inherited by a called batch
file.

## A called batch file will return to the calling file
after processing the last line in the called file, or
when a QUIT command is executed. A called batch file
should always return in this way, or terminate all
batch files with CANCEL. Restarting (or CALLing) the
original batch file from within a called file will
prevent the command processor from detecting that
you've left the second file, and it may cause an
infinite loop or a stack overflow.

## CALL returns an exit code which matches the batch file
return code. You can test this exit code with the %_?
or %? environment variable (see page 99), and use it
with conditional commands (&& and ||; see page 68).




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 173

CANCEL
-------------------------------------------------------------------

CANCEL (New)

Purpose: Terminate batch file processing.

Format: CANCEL [value]

value: The exit code from 0 to 255 to return to the
command processor.

See also: CALL and QUIT.

Usage: The CANCEL command ends all batch file processing,
regardless of the batch file nesting level. Use QUIT
to end a nested batch file and return to the previous
batch file.

You can CANCEL at any point in a batch file. If
CANCEL is used from within an alias it will end
execution of both the alias and any batch file(s)
which are running at the time.

The following batch file fragment compares an input
line to "end" and terminates all batch file processing
if it matches:

input Enter your choice: %%option
if "%option" == "end" cancel

## If you specify a value, CANCEL will set the ERRORLEVEL
or exit code to that value (see the IF command, and
the %? variable on page 99).



















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 174

CD / CHDIR
-------------------------------------------------------------------

CD / CHDIR (Enhanced)

Purpose: Display or change the current directory.

Format: CD [ path | - ]
or
CHDIR [ path | - ]

path: The directory to change to, including an
optional drive name.

See also: CDD, MD, PUSHD, RD, and Directory Changes
on page 43.

Usage: CD and CHDIR are synonyms. You can use either one.

CD lets you navigate through the DOS subdirectory
structure by changing the current working directory.
If you enter CD and a directory name, the named
directory becomes the new current directory. For
example, to change to the subdirectory
C:\FINANCE\MYFILES:

c:\> cd \finance\myfiles
c:\finance\myfiles>

Every disk drive on the system has its own current
directory. Specifying both a drive and a directory in
the CD command will change the current directory on
the specified drive, but will not change the default
drive. For example, to change the default directory
on drive A:

c:\> cd a:\utility
c:\>

Notice that this command does not change to drive A:.
Use the CDD command to change the current drive and
directory at the same time.

You can change to the parent directory with CD ..; you
can also go up one additional directory level with
each additional [.]. For example, CD .... will go up
three levels in the directory tree (see page 57 for
additional details). You can move to a sibling
directory - one that branches from the same parent
directory as the current subdirectory - with a command
like CD ..\newdir.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 175

CD / CHDIR
-------------------------------------------------------------------

If you enter CD with no argument or with only a disk
drive name, it will display the current directory on
the default or named drive.

CD saves the current directory before changing to a
new directory. You can switch back to the previous
directory by entering CD -. (There must be a space
between the CD command and the hyphen.) You can
switch back and forth between two directories by
repeatedly entering CD -. The saved directory is the
same for both the CD and CDD commands. Drive changes
and automatic directory changes (see page 44) also
modify the saved directory, so you can use CD - to
return to a directory that you exited with an
automatic directory change.

Directory changes made with CD are recorded for
display in the directory history window (see page 43).

## CD never changes the default drive. If you change
directories on one drive, switch to another drive, and
then enter CD -, the directory will be restored on the
first drive but the current drive will not be changed.

## If CD can't change to the specified directory, it will
look for the CDPATH environment variable. See page 43
for details about using CDPATH.

The operating system limits the permissible length of
the full subdirectory name. See page 15 for more
information on directory names.



















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 176

CDD
-------------------------------------------------------------------

CDD (New)

Purpose: Change the current disk drive and directory.

Format: CDD path

path: The name of the directory (or drive and
directory) to change to.

See also: CD, MD, PUSHD, RD, and Directory Changes on
page 43.

Usage: CDD is similar to the CD command, except that it also
changes the default disk drive if one is specified.
CDD will change to the directory and drive you name.
To change from the root directory on drive A to the
subdirectory C:\WP:

a:\> cdd c:\wp
c:\wp>

You can change to the parent directory with CDD ..;
you can also go up one additional directory level with
each additional [.]. For example, CDD .... will go up
three levels in the directory tree.

CDD saves the current drive and directory before
changing to a new directory. You can switch back to
the previous drive and directory by entering CDD -.
(There must be a space between the CDD command and the
hyphen.) You can switch back and forth between two
drives and directories by repeatedly entering CDD -.
The saved directory is the same for both the CD and
CDD commands. Drive changes and automatic directory
changes (see page 44) also modify the saved directory,
so you can use CDD - to return to a directory that you
exited with a drive change or an automatic directory
change.

Directory changes made with CDD are recorded for
display in the directory history window (see page 43).

## If CDD can't change to the specified directory, it
will look for the CDPATH environment variable. See
page 43 for details about using CDPATH.

The operating system limits the permissible length of
the full subdirectory name. See page 15 for more
information on directory names.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 177

[4DOS, 4OS2] CHCP
-------------------------------------------------------------------

CHCP [4DOS, 4OS2] (Compatible)

Purpose: Display or change the current system code page.

Format: CHCP [n]

n: A system code page number.

## Usage: Code page switching allows you to select different
character sets for language support. To use code page
switching, you must have an EGA or VGA display and be
running under MS-DOS or PC-DOS 3.3 or above, or OS/2.
CHCP is not available in 4DOS/NT.

If you enter CHCP without a number, the current code
page is displayed.

c:\> chcp
Active code page: 437

If you enter CHCP plus a code page number, the system
code page is changed. For example, to set the code
page to multilingual:

c:\> chcp 850

4DOS Before using CHCP under DOS, you must first load the
device drivers (in CONFIG.SYS), make sure the
information file (COUNTRY.SYS) is available, load
national language support (using the NLSFUNC command),
and prepare the specified code page for the devices
(using the MODE command with the CODEPAGE PREPARE
option).

CHCP accepts one of the prepared system code pages.
An error message is displayed if a code page is
selected that has not been prepared for the system.

See your DOS or OS/2 documentation for more
information on CHCP.










-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 178

CLS
-------------------------------------------------------------------

CLS (Enhanced)

Purpose: Clear the video display and move the cursor to the
upper left corner; optionally change the default
display and border colors.

Format: CLS [[BRIght] [BLInk] fg ON [BRIght] bg] [BORder bc]

fg: The new foreground color
bg: The new background color
bc: The new border color

Usage: CLS can be used to clear the screen without changing
colors, or to clear the screen and change the screen
colors simultaneously. These three examples show how
to clear the screen to the default colors, to bright
white letters on a blue background, and to bright
yellow letters on a magenta background with a blue
border:

c:\> cls
c:\> cls bright white on blue
c:\> cls bri yel on mag bor blu

CLS is often used in batch files to clear the screen
before displaying text.

See page 26 for details about colors and color names,
and notes on the use of bright background colors.

4DOS## Under DOS, if ANSI.SYS or a compatible driver is not
loaded, the colors will not be "sticky" - you may lose
them after you run an application. If 4DOS thinks you
have an ANSI driver loaded, it uses an ANSI clear
screen command. Otherwise, 4DOS will call the BIOS to
clear the screen. You can force 4DOS to recognize the
proper ANSI state with the SETDOS /A option (see page
309) or the ANSI directive in 4DOS.INI (see page 131).

4DOS## If your display accommodates more than 25 rows by 80
columns and CLS doesn't clear the whole screen, your
ANSI driver probably does not support the large
display size properly.







-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 179

COLOR
-------------------------------------------------------------------

COLOR (New)

Purpose: Change the default display colors.

Format: COLOR [BRIght] [BLInk] fg ON [BRIght] bg [BORder bc]

fg: The new foreground color
bg: The new background color
bc: The new border color

See also: CLS, and page 26 for details about using
colors.

Usage: COLOR is normally used in batch files before
displaying text. For example, to set screen colors to
bright white on blue, you can use this command:

c:\> color bright white on blue

4DOS If you have an ANSI driver (such as ANSI.SYS)
installed, COLOR will not change anything on the
screen. It will only set the default colors for
subsequent screen displays. If you are not using an
ANSI driver, COLOR will change the display colors of
every character on the screen. However, the colors
will not be "sticky" - you may lose them after you run
an application.

4DOS## If you see odd characters like "[44;37m" when you try
to set the screen colors, 4DOS probably thinks you
have an ANSI driver loaded when you don't. Use SETDOS
/A2, or ANSI = No in 4DOS.INI, to tell 4DOS you have
no ANSI driver.

















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 180

COPY
-------------------------------------------------------------------

COPY (Enhanced)

Purpose: Copy data between disks, directories, files, or
physical hardware devices (such as your printer or
serial port).

Format: COPY [/C /H /M /N /P /Q /R /S /T /U /V] source[+] ...
[/A /B] destination [/A /B]


source: A file or list of files or a device to
copy from.
destination: A file, directory, or device to copy to.

/A(SCII) /Q(uiet)
/B(inary) /R(eplace)
/C(hanged) /S(ubdirectories)
/H(idden) /T(otals)
/M(odified) /U(pdate)
/N(othing) /V(erify)
/P(rompt)

See also: ATTRIB, MOVE, and REN.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65). Date,
time, or size ranges anywhere on the line apply to all
source files.

Usage: The COPY command accepts all traditional syntax and
options and adds several new features.

The simplest use of COPY is to make a copy of a file,
like this example which makes a copy of a file called
FILE1.ABC:

c:\> copy file1.abc file2.def

You can also copy a file to another drive and/or
directory. The following command copies FILE1 to the
\MYDIR directory on drive E:

c:\> copy file1 e:\mydir

You can copy several files at once by using wildcards:

c:\> copy *.txt e:\mydir



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 181

COPY
-------------------------------------------------------------------

(See page 57 for an explanation of how 4DOS interprets
the wildcard characters [*] and [?].)

You can also list several source files in one command.
The following command copies 3 files from the current
directory to the \MYDIR directory on drive E:

c:\> copy file1 file2 file3 e:\mydir

The way COPY interprets your command line depends on
how many arguments (file, directory, or device names)
are on the line, and whether the arguments are
separated with [+] signs or spaces.

If there is only one argument on the line, COPY
assumes it is the source, and uses the current drive
and directory as the destination. For example, the
following command copies all the .DAT files on drive A
to the current directory on drive C:

c:\> copy a:*.dat

If there are two or more arguments on the line and [+]
signs are not used, then COPY assumes that the last
argument is the destination and copies all source
files to this new location. If the destination is a
drive, directory, or device name then the source files
are copied individually to the new location. If the
destination is a file name, the first source file is
copied to the destination, and any additional source
files are then appended to the new destination file.

For example, the first of these commands copies the
.DAT files from the current directory on drive A
individually to C:\MYDIR (which must already exist as
a directory); the second appends all the .DAT files
together into one large file called C:\DATA (assuming
C:\DATA is not a directory):

c:>\ copy a:*.dat c:\mydir\
c:>\ copy a:*.dat c:\data

When you copy to a directory, if you add a backslash
[\] to the end of the name as shown in the first
example above, COPY will display an error message if
the name does not refer to an existing directory. You
can use this feature to keep COPY from treating a
mistyped destination directory name as a file name and
attempting to append all your source files to a

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 182

COPY
-------------------------------------------------------------------

destination file, when you really meant to copy them
individually to a destination directory.

## A plus [+] tells COPY to append two or more files to a
single destination file. If you list several source
files separated with [+] and don't specify a
destination, COPY will use the name of the first
source file as the destination, and append each
subsequent file to the first file. In this case the
destination file will always be created in the current
directory, even if the first source file is in another
directory or on another drive.

For example, the following command will append the
contents of C:\MEMO2 and C:\MEMO3 to C:\MEMO1 and
leave the combined contents in the file named
C:\MEMO1:

c:\> copy memo1+memo2+memo3

To append the same three files but store the result in
BIGMEMO:

c:\> copy memo1+memo2+memo3 bigmemo

To append C:\MEM\MEMO2 and C:\MEM\MEMO3 to
D:\DATA\MEMO1, and leave the result in C:\MEM\MEMO1:

c:\mem> copy d:\data\memo1+memo2+memo3

## You cannot append files to a device (such as a
printer); if you try to do so, COPY will ignore the
[+] signs and copy the files individually. If you
attempt to append several source files to a
destination directory or disk, COPY will append the
files and place the copy in the new location with the
same name as the first source file.

## If your destination has wildcards in it, COPY will
attempt to match them with the source names. For
example, this command copies the .DAT files from drive
A to C:\MYDIR and gives the new copies the extension
.DX:

c:\> copy a:*.dat c:\mydir\*.dx

This feature can give you unexpected results if you
use it with multiple source file names. For example,


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 183

COPY
-------------------------------------------------------------------

suppose that drive A contains XYZ.DAT and XYZ.TXT.
The command

c:\> copy a:\*.dat a:\*.txt c:\mydir\*.dx

will copy A:XYZ.DAT to C:\MYDIR\XYZ.DX. Then it will
copy A:XYZ.TXT to C:\MYDIR\XYZ.DX, overwriting the
first file it copied.

## COPY also understands include lists (see page 65), so
you can specify several different kinds of files in
the same command. This command copies the .TXT, .DOC,
and .BAT files from the E:\MYDIR directory to the root
directory of drive A:

c:\> copy e:\mydir\*.txt;*.doc;*.bat a:\

## You can use date, time, and size ranges to further
define the files that you want to copy (see page 60
for information on ranges). This example copies every
file in the E:\MYDIR directory, which was created or
modified yesterday, and which is also 10,000 bytes or
smaller in size, to the root directory of drive A:

c:\> copy /[d-1] /[s0,10000] e:\mydir\*.* a:\

## COPY maintains the hidden and system attributes of
files, but not the read-only attribute. The
destination file will always have the archive
attribute set.

4DOS## If you are using 4DOS in an OS/2 DOS session, COPY
will copy OS/2 extended attributes from the source to
the destination, if the file system on the destination
drive supports them.

Options: The /A(SCII) and /B(inary) options apply to the
preceding filename and to all subsequent filenames on
the command line until the file name preceding the
next /A or /B, if any. The other options (/C, /H, /M,
/N, /P, /Q, /R, /S, /T, /U, /V) apply to all filenames
on the command line, no matter where you put them.
For example, either of the following commands could be
used to copy a font file to the printer in binary
mode:

c:\> copy /b myfont.dat prn
c:\> copy myfont.dat /b prn


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 184

COPY
-------------------------------------------------------------------

Some options do not make sense in certain contexts, in
which case COPY will ignore them. For example, you
cannot prompt before replacing an existing file when
the destination is a device such as the printer -
there's no such thing as an "existing file" on the
printer. If you use conflicting output options, like
/Q and /P, COPY will take a "conservative" approach
and give priority to the option which generates more
prompts or more information.

Options used in less common situations have been
marked with ## below. Remember that the options are
in alphabetical order, so more basic options are
interspersed with those marked with## .

## /A(SCII): If you use /A with a source filename, the
file will be copied up to, but not including, the
first Ctrl-Z (Control-Z or ASCII 26) character in the
file. If you use /A with a destination filename, a
Ctrl-Z will be added to the end of the file (some
application programs use the Ctrl-Z to mark the end of
a file). /A is the default when appending files, or
when the destination is a device like NUL or PRN,
rather than a disk file.

## /B(inary): If you use /B with a source filename, the
entire file is copied; Ctrl-Z characters in the file
do not affect the copy operation. Using /B with a
destination filename prevents addition of a Ctrl-Z to
the end of the destination file. /B is the default
for normal file copies.

/C(hanged files): Copy files only if the destination
file exists and is older than the source (see also
/U). This option is useful for updating the files in
one directory from those in another without copying
any newly created files.

## /H(idden): Copy all matching files including those
with the hidden and/or system attribute set (see page
18).

/M(odified): Copy only those files with the archive
attribute set (see page 18), i.e., those which have
been modified since the last backup. The archive
attribute will not be cleared after copying.




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 185

COPY
-------------------------------------------------------------------

/N(othing): Do everything except actually perform the
copy. This option is useful for testing what the
result of a complex COPY command will be.

/P(rompt): Ask the user to confirm each source file.
Your options at the prompt are explained in detail on
page 48.

/Q(uiet): Don't display filenames or the total number
of files copied. This option is most often used in
batch files. See also /T.

/R(eplace): Prompt the user before overwriting an
existing file. Your options at the prompt are
explained in detail on page 48.

/S(ubdirectories): Copy the subdirectory tree
starting with the files in the source directory plus
each subdirectory below that. The destination must be
a directory; if it doesn't exist, COPY will attempt to
create it. COPY will also attempt to create needed
subdirectories on the tree below the destination,
including empty source directories. If you attempt
to use COPY /S to copy a subdirectory tree into part
of itself, COPY will display an error message and
exit.

/T(otals): Turns off the display of filenames, like
/Q, but does display the total number of files copied.

/U(pdate): Copy each source file only if it is newer
than a matching destination file or if a matching
destination file does not exist (see also /C). This
option is useful for keeping one directory matched
with another with a minimum of copying.

## /V(erify): Verify each disk write. This is the same
as executing the VERIFY ON command, but is only active
during the COPY. /V does not read back the file and
compare its contents with what was written; it only
verifies that the data written to disk is physically
readable.








-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 186

[4DOS] CTTY
-------------------------------------------------------------------

CTTY [4DOS] (Compatible)

Purpose: Change the default console device.

Format: CTTY device

device: The new console device.

## Usage: Normally, 4DOS uses the keyboard as the standard input
device and the display as the standard output device.
Together, the keyboard and display are known as the
console or CON. The CTTY command allows you to
substitute another device that can perform standard
character I/O for the console.

For example to change the console to the first serial
port:

c:\> ctty com1

Change the console back to the standard keyboard and
display (this command must be entered from the current
console, e.g., a terminal attached to COM1, or from a
batch file):

c:\> ctty con

CTTY works only for programs and commands that use
standard DOS input and output functions. This
includes all 4DOS internal commands except DRAWBOX,
DRAWHLINE, DRAWVLINE, LIST, SCREEN, SCRPUT, SELECT,
and VSCRPUT. In addition, if you use color-coded
directories you should disable them with DIR /D when
using CTTY. Otherwise directories will not be
displayed correctly.















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 187

DATE
-------------------------------------------------------------------

DATE (Compatible)

Purpose: Display and optionally change the system date.

Format: DATE [mm-dd-yy]

mm: The month (1 - 12).
dd: The day (1 - 31).
yy: The year (80 - 99 = 1980 - 1999, or a 4-
digit year).

See also: TIME.

Usage: If you simply type DATE without any parameters, you
will see the current system date and time, and be
prompted for a new date. Press ENTER if you don't
wish to change the date. If you type a new date, it
will become the current system date, which is included
in the directory entry for each file as it is created
or altered:

c:\> date
Wed Dec 22, 1993 9:30:06
Enter new date (mm-dd-yy):

You can also enter a new system date by typing the
DATE command plus the new date on the command line:

c:\> date 3-16-94

You can use hyphens, slashes, or periods to separate
the month, day, and year entries. A full 4-digit year
can be entered if you wish.

DATE adjusts the format it expects depending on your
country settings. When entering the date, use the
correct format for the country setting currently in
effect on your system.












-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 188

DEL / ERASE
-------------------------------------------------------------------

DEL / ERASE (Enhanced)

Purpose: Erase one file, a group of files, or entire
subdirectories.

Format: DEL [/F /N /P /Q /S /T /X /Y /Z] file...
or
ERASE [/F /N /P /Q /S /T /X /Y /Z] file...

file: The file, subdirectory, or list of files
or subdirectories to erase.

/F(orce delete) /T(otal)
/N(othing) /X (remove empty subdirs)
/P(rompt) /Y(es to all prompts)
/Q(uiet) /Z(ap hidden / read-only)
/S(ubdirectories)

File Select:Supports extended wildcards, ranges (see conditions
below), multiple file names, and include lists (see
pages 57 - 65).

Usage: DEL and ERASE are synonyms, you can use either one.

Use the DEL and ERASE commands with caution; the files
and subdirectories that you erase may be impossible to
recover without specialized utilities and a lot of
work.

To erase a single file, simply enter the file name:

c:\> del letters.txt

You can also erase multiple files in a single command.
For example, to erase all the files in the current
directory with a .BAK or .PRN extension:

c:\> del *.bak *.prn

If you enter a subdirectory name, or a filename
composed only of wildcards (* and/or ?), DEL asks for
confirmation (Y or N) unless you specified the /Y
option. If you respond with a Y, DEL will delete all
the files in that subdirectory (hidden, system, and
read-only files are only deleted if you use the /Z
option).

4DOS ! Under DOS, the DEL /Q option uses a high-speed
deletion method which cannot take date, time, and size

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 189

DEL / ERASE
-------------------------------------------------------------------

ranges into account. Therefore you should NOT use DEL
/Q with date, time, or size ranges. If you do, the
range will be ignored, and all the files you specified
will be deleted regardless of their date, time, or
size. This restriction does not apply in OS/2 DOS
sessions, because the high speed deletion method is
not available in OS/2 DOS.

DEL displays the amount of disk space recovered,
unless the /Q option is used (see below). It does so
by comparing the amount of free disk space before and
after the DEL command is executed. This amount may be
incorrect if you are using a deletion tracking system
which stores deleted files in a hidden directory, or
if, under a multitasking system, another program
performs a file operation while the DEL command is
executing.

Remember that DEL removes file descriptions along with
files. Most deletion tracking systems will not be
able to save or recover a file's description, even if
they can save or recover the data in a file.

## DEL returns a non-zero exit code if no files are
deleted, or if another error occurs. You can test
this exit code with the %_? environment variable (see
page 99), and use it with conditional commands (&& and
||; see page 68).

Options: ## /F(orce delete): This option is only for use in the
32-bit version of 4OS2, and in 4DOS when running in an
OS/2 2.1 or later DOS session. It forces deletion of
the file without saving it to the DELDIR directory (if
DELDIR is not in use, /F has no effect).

/N(othing): Do everything except actually delete the
file(s). This is useful for testing what the result
of a DEL would be.

/P(rompt): Prompt the user to confirm each erasure.
Your options at the prompt are explained in detail on
page 48.

/Q(uiet): Don't display filenames as they are
deleted, or the number of files deleted or bytes
freed. When running 4DOS under DOS, DEL will run
fastest if you specify the /Q option and the filename
doesn't use the extended 4DOS wildcards. When running
4OS2, 4DOS/NT, or 4DOS under OS/2, /Q will have little

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 190

DEL / ERASE
-------------------------------------------------------------------

or no effect on DEL's speed. Do not use /Q with date,
time, or size ranges (see note above). See also /T.

! /S(ubdirectories): Delete the specified files in this
directory and all of its subdirectories. This is like
a GLOBAL DEL, and can be used to delete all the files
in a subdirectory tree or even a whole disk. It
should be used with caution!

/T(otal): Don't display filenames as they are
deleted, but display the total number of files deleted
plus the amount of free disk space recovered. Unlike
/Q, the /T option will not speed up deletions under
DOS.

## /X (remove empty subdirectories): Remove empty
subdirectories after deleting (only useful when used
with /S).

! ## /Y(es): The reverse of /P - it assumes a Y response
to everything, including deleting an entire
subdirectory tree. 4DOS, 4OS2, and 4DOS/NT normally
prompt before deleting files when the name consists
only of wildcards or a subdirectory name (see above);
/Y overrides this protection, and should be used with
extreme caution!

! ## /Z(ap): Delete read-only, hidden, and system files as
well as normal files. Files with the read-only,
hidden, or system attribute set are normally protected
from deletion; /Z overrides this protection, and
should be used with caution. Because EXCEPT works by
hiding files, /Z will override an EXCEPT command.

For example, to delete the entire subdirectory tree
starting with C:\UTIL, including hidden and read-only
files, without prompting (use this command with
CAUTION!):

c:\> del /sxyz c:\util\










-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 191

DELAY
-------------------------------------------------------------------

DELAY (New)

Purpose: Pause for a specified length of time.

Format: DELAY [seconds]

seconds: The number of seconds to delay.

Usage: DELAY is useful in batch file loops while waiting for
something to occur. To wait for 10 seconds:

delay 10

A simple loop could make a tone with the BEEP command
to get the operator's attention and then DELAY for a
few seconds while waiting for the user to respond.

## For delays shorter than one second, use the BEEP
command with an inaudible frequency (below 20 Hz).

You can cancel a delay by pressing Ctrl-C or Ctrl-
Break.




























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 192

DESCRIBE
-------------------------------------------------------------------

DESCRIBE (New)

Purpose: Create, modify, or delete file and subdirectory
descriptions.

Format: DESCRIBE file ["description"] ...

file: The file or files to operate on.
"description": The description to attach to the file.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65).

Usage: DESCRIBE adds descriptions to files and
subdirectories. The descriptions are displayed by DIR
in single-column mode and by SELECT. Descriptions let
you identify your files in much more meaningful ways
than you can in an eight-character filename.

You enter a description on the command line by typing
the DESCRIBE command, the filename, and the
description in quotation marks, like this:

c:\> describe memo.txt "Memo to Bob about party"

If you don't put a description on the command line,
DESCRIBE will prompt you for it:

c:\> describe memo.txt
Describe "memo.txt" : Memo to Bob about party

If you use wildcards or multiple filenames with the
DESCRIBE command and don't include the description
text, you will be prompted to enter a description for
each file. If you do include the description on the
command line, all matching files will be given the
same description.

Each description can be up to 40 characters long. You
can change this limit with the DescriptionMax
directive in 4DOS.INI (see page 132). DESCRIBE can
edit descriptions longer than DescriptionMax (up to a
limit of 200 characters), but will not allow you to
lengthen the existing text.

The descriptions are stored in each directory in a
hidden file called DESCRIPT.ION. Use the ATTRIB
command to remove the hidden attribute from this file
if you need to copy or delete it. (DESCRIPT.ION is

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 193

DESCRIBE
-------------------------------------------------------------------

always created as a hidden file, but will not be re-
hidden by 4DOS, 4OS2, or 4DOS/NT if you remove the
hidden attribute.)

The description file is modified appropriately
whenever you perform an internal command which affects
it (such as COPY, MOVE, DEL, or RENAME), but not if
you use an external program (such as XCOPY or a visual
shell).

4OS2,! On HPFS and NTFS drives, you will not see file
4NT descriptions in a normal DIR display, because DIR must
leave space for the long filenames used on these
drives. To view the descriptions, use DIR /Z to
display the directory in FAT format. See the DIR
command for more details.


































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 194

[4OS2, 4DOS/NT] DETACH
-------------------------------------------------------------------

DETACH [4OS2, 4DOS/NT] (Compatible)

Purpose: Start an OS/2 or Windows NT program in detached mode.

Format: DETACH command

command: The name of a command to execute, including
an optional drive and path specification. The name
must be enclosed in quotation marks if it contains any
spaces.

See also: START.

Usage: When you start a program with DETACH, that program
cannot use the keyboard, mouse, or video display. It
is "detached" from the normal means of user input and
output. However, you can redirect the program's
standard I/O to other devices if necessary, using
redirection symbols (see page 50).

The command can be an internal command, external
command, alias, or batch file. 4OS2 or 4DOS/NT will
detach a copy of itself to execute the command.

For example, the following command will detach a copy
of the command processor to run the batch file
XYZ.BTM:

[c:\] detach xyz.btm

Once the program has started, 4OS2 or 4DOS/NT returns
to the prompt immediately. It does not wait for a
detached program to finish.

















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 195

DIR
-------------------------------------------------------------------

DIR (Enhanced)

Purpose: Display information about files and subdirectories.

Format: DIR [/1 /2 /4 /A[[:][-]rhsda] /B /C[HP] /D /E /F /H
/I"text" /J /K /L /M /N /O[[:][-]acdeginrsu] /P
/R /S /T[:acw] /U /V /W /X /Z] [file...]

file: The file, directory, or list of files or
directories to display.

/1 (one column) /L(ower case)
/2 (two columns) /M (suppress footer)
/4 (four columns) /N(ormal) or (New format)
/A(ttribute select) /O(rder)
/B(are) /P(ause)
/C[HP] (Compression) /R (disable wRap)
/D(isable color coding) /S(ubdirectories)
/E (use upper case) /T (aTtribute) or (Time)
/F(ull path) /U (sUmmary information)
/H(ide dots) /V(ertical sort)
/I (match descriptions) /W(ide)
/J(ustify names) /X (display short names)
/K (suppress header) /Z (use FAT format)


See also: ATTRIB, DESCRIBE, SELECT, and SETDOS.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65).

Usage: DIR can be used to display information about files
from one or more of your disk directories, in a wide
range of formats. Depending on the options chosen,
you can display the file name, attributes, and size;
the time and date of the last change to the file; the
file description; and the file's compression ratio.
You can also display information in 1, 2, 4, or 5
columns, sort the files several different ways, use
color to distinguish file types, and pause after each
full screen.

The various DIR displays are controlled through
options or switches. The best way to learn how to use
the many options available with the DIR command is to
experiment. You will soon know which options you want
to use regularly. You can select those options
permanently by using the ALIAS command.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 196

DIR
-------------------------------------------------------------------

You may want to mix several options. For example, to
display all the files in the current directory, in 2
columns, sorted vertically (down one column then down
the next), and with a pause at the end of each page:

c:\> dir /2/p/v

To set up this format as the default, using an alias:

c:\> alias dir=*dir /2/p/v

This example displays all the files on all directories
of drive C, including hidden and system files, pausing
after each page:

c:\> dir /s/a/p c:\

DIR allows wildcard characters (* and ?) in the
filename. If you don't specify a filename, DIR
defaults to *.* (display all non-hidden files and
subdirectories in the current directory). To display
all of the .WKS files in the current directory:

c:\> dir *.wks

With the /I option, DIR can select files to display
based on their descriptions. DIR will display a file
if its description matches the text after the /I
switch. The search is not case sensitive. You can
use wildcards and extended wildcards as part of the
text. For example, to display any file described as a
"Test File" you can use this command:

c:\> dir /i"test file"

If you want to display files that include the words
"test file" anywhere in their descriptions, use
extended wild cards like this:

c:\> dir /i"*test file*"

If you link two or more filenames together with
spaces, DIR will display all of the files that match
the first name and then all of the files that match
the second name. You may use a different drive and
path for each filename. This example lists all of the
.WKS and then all of the .WK1 files in the current
directory:


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 197

DIR
-------------------------------------------------------------------

c:\> dir *.wks *.wk1

If you use an include list (see page 65) to link
multiple filenames, DIR will display the matching
filenames in a single listing. Only the first
filename in an include list can have a path; the other
files must be in the same path. This example displays
the same files as the previous example, but the .WKS
and .WK1 files are intermixed:

c:\> dir *.wks;*.wk1

You can display the file and subdirectory names in
color by setting the COLORDIR environment variable or
using the ColorDir directive in your .INI file. See
page 30 for details.

## If you are using color-coded directories and attempt
to redirect the output of DIR to a character device,
such as a serial port or the printer, non-color-coded
file names will be displayed on the device but color-
coded names may still be displayed on the screen.
This will not occur if the output of DIR is redirected
to a disk file. To prevent this problem, use the /D
switch to disable color coding when redirecting the
output of DIR to a character device.

When displaying file descriptions, DIR will wrap long
lines to fit on the screen. DIR displays a maximum of
40 characters of text in each line of a description,
unless your screen width allows a wider display. If
you disable description wrapping with the /R switch,
the description is truncated at the right edge of the
screen, and a right arrow [a] is added at the end of
the line to alert you to the existence of additional
description text.

If you attempt to redirect the output of DIR to a
character device, such as a serial port or the
printer, long descriptions will be wrapped at the
screen width in the redirected output. If this is not
what you want, use /R to disable wrapping.

4DOS## If you are using a disk compression program, you can
use the /C switch to view the amount of compression
achieved for each file. When you do, the compression
ratio is displayed instead of the file's description.
You can also sort the display by compression ratios
with the /O:c switch. Details for both switches are

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 198

DIR
-------------------------------------------------------------------

in the Options section, below. See APPNOTES.DOC for a
list of compression systems supported by the 4DOS DIR
command.

## When sorting file names and extensions, 4DOS, 4OS2,
and 4DOS/NT normally assume that sequences of digits
should be sorted numerically (for example, the file
DRAW2 would come before DRAW03 because 2 is
numerically smaller than 03), rather than strictly
alphabetically (where DRAW2 would come second because
"2" is after "0" in alphanumeric order). You can
defeat this behavior and force a strict alphabetic
sort with the /O:a option.

## If you have selected a specific country code for your
system, DIR will display the date in the format for
that country. The default date format is U.S. (mm-dd-
yy). The separator character in the file time will
also be affected by the country code.

4DOS## DIR can handle directories of any size, limited only
by available memory. Under 4DOS, each filename
requires 32 bytes of free base memory plus the size of
the description (if any). For example, a system with
just 128K of free memory can display up to 4,000 files
per directory. Memory requirements for DIR are
generally not a concern under 4OS2 and 4DOS/NT,
because of the virtual memory available under these
operating systems.

## Options on the command line apply only to the
filenames which follow the option, and options at the
end of the line apply to the preceding filename only.
This allows you to specify different options for
different groups of files, yet retains compatibility
with the traditional DIR command when a single
filename is specified.

Options: /1: Single column display - display the filename,
size, date, time, and description. This is the
default. If /T is used the attributes are displayed
instead of the description; if /C or /O:c is used the
compression ratio is displayed instead of the
description.

/2: Two column display - display the filename, size,
date, and time. If you use /2 (or /4) on an HPFS or
NTFS drive under 4OS2 or 4DOS/NT, DIR will only
display the file names. Also, the number of columns

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 199

DIR
-------------------------------------------------------------------

may be reduced to one for names too long to fit on
half the screen. Due to these restrictions, /2 is
normally most useful on HPFS and NTFS drives when used
with /Z to force the display to FAT format.

/4: Four column display - display the filename and
size, in K (kilobytes) or M (megabytes). The note
under /2 above regarding HPFS and NTFS drives applies
to /4 as well.

## /A(ttribute select): Display only those files that
have the specified attribute(s) set. Preceding the
attribute character with a hyphen [-] will display
files that do not have that attribute set. The
attributes are:

R Read-only D Subdirectory
H Hidden A Archive
S System

If no attributes are listed at all (e.g., DIR /A), DIR
will display all files and subdirectories including
hidden and system files. If attributes are combined,
all the specified attributes must match for a file to
be included in the listing. For example, /A:RHS will
display only those files with all three attributes
set. See page 18 for more information on file
attributes.

## /B(are): Suppress the header and summary lines, and
display file or subdirectory names only, in a single
column. This option is most useful when you want to
redirect a list of names to a file or another program.
If you use /B with /S, DIR will show the full path of
each file instead of simply its name and extension.

4DOS /C(ompression): Display per-file and total
compression ratio on compressed drives. The
compression ratio is displayed instead of the file
description or attributes. The ratio is left blank
for directories and files with a length of 0 bytes,
and for files on non-compressed drives. /C only works
in single-column mode; it is ignored if /2, /4, or /W
is used. See APPNOTES.DOC for a list of supported
compression systems.

The numerator of the displayed compression ratio is
the amount of space which would be allocated to the
file if the compression utility were not in use, based

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 200

DIR
-------------------------------------------------------------------

on the compressed drive's cluster size (usually 8K
bytes). The denominator is the space actually
allocated for the compressed file. For example, if a
file is allocated 6,144 bytes when compressed, and
would require 8,192 bytes if uncompressed, the
displayed compression ratio would be 8,192 / 6,144, or
1.3 to 1.

Using /CH displays compression ratios like /C, but
bases the calculation on the host drive's cluster
size. This gives a more accurate picture of the space
saved through compression than is given by /C. This
option will occasionally display compression ratios
slightly less than 1.0 to 1.0 for files which have
actually expanded when stored on the compressed drive.

If /CP is used instead of /C, the compression is
displayed as a percentage (e.g., 33%) instead of a
ratio (e.g., 3 to 1). If /CHP is used instead of /CH,
the host compression is displayed as a percentage.
The /CHP option must be entered as shown; you can not
use /CPH.

## /D(isable color coding): Temporarily disable
directory color coding. May be required when color-
coded directories are used and DIR output is
redirected to a character device like the printer
(e.g., PRN or LPT1) or serial port (e.g., COM1 or
COM2). /D is not required when DIR output is
redirected to a file.

/E: Display filenames in the traditional upper case;
also see SETDOS /U (page 312) and the UpperCase
directive in 4DOS.INI (page 135). /E is ignored under
4OS2 and 4DOS/NT if the display is in HPFS or NTFS
format. HPFS and NTFS file names are always displayed
in the case in which they are stored.

## /F(ull path): Display each filename with its drive
letter and path in a single column, without other
information.

/H(ide dots): Suppress the display of the "." and
".." directories.

/I: Display filenames by matching text in their
descriptions. The text can include wild cards and
extended wildcards. The search text must be enclosed
in quotation marks. /I may be used to select files

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 201

DIR
-------------------------------------------------------------------

even if descriptions are not displayed (for example,
if /2 is used). However, /I will be ignored if /C or
/O:c is used.

/J(ustify names): Justify (align) filename extensions
and display them in the traditional format.

## /K: Suppress the header (disk and directory name)
display.

/L(ower case): Display file and directory names in
lower case; also see SETDOS /U (page 312) and the
UpperCase directive in 4DOS.INI (page 135). /L is
ignored under 4OS2 and 4DOS/NT if the display is in
HPFS or NTFS format. HPFS and NTFS file names are
always displayed in the case in which they are stored.

## /M: Suppress the footer (file and byte count totals)
display.

4DOS /N: Reset the DIR options to the default values.
This is useful when you want to display some files in
one format, and then change back to the defaults for
another set of files.

4OS2, /N: Use the HPFS or NTFS display format, even if the
4NT files are stored on a FAT file system volume.

/O(rder): Set the sorting order. You may use any
combination of the following sorting options; if
multiple options are used, the listing will be sorted
with the first sort option as the primary key, the
next as the secondary key, and so on:

- Reverse the sort order for the next option
a Sort names and extensions in standard ASCII
order, rather than sorting numerically when
digits are included in the name or
extension.
c Sort by compression ratio (the least
compressed file in the list will be
displayed first). For single-column
directory displays, the compression ratios
will be used as the basis of the sort and
will also be displayed. For wider displays
(/2, /4, and /W), the compression ratios
will be used to determine the order but will
not be displayed. If /O:c is used with /CH


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 202

DIR
-------------------------------------------------------------------

or /CHP, the sort will be based on the host-
drive compression ratios.
d Sort by date and time (oldest first); for
HPFS and NTFS drives also see /T.
e Sort by extension.
g Group subdirectories first, then files.
i Sort by the file description (ignored if /C
or /O:c is also used).
n Sort by filename (this is the default).
r Reverse the sort order for all options.
s Sort by size.
u Unsorted.

/P(ause): Wait for a key to be pressed after each
screen page before continuing the display. Your
options at the prompt are explained in detail on page
48.

/R (disable wRap): Forces long descriptions to be
displayed on a single line, rather than wrapped onto
two or more lines. Use /R when output is redirected
to a character device, such as a serial port or the
printer; or when you want descriptions truncated,
rather than wrapped, in the on-screen display.

/S(ubdirectories): Display file information from the
current directory and all of its subdirectories. DIR
will only display headers and summaries for those
directories which contain files that match the
filename(s) and attributes (if /A is used) that you
specify on the command line.

4DOS## /T (aTtribute display): Display the filenames and
attributes only. File descriptions are not displayed
if /T is used (the attributes are displayed in place
of the descriptions). /T is ignored if /C or /O:c is
also used. The attributes are displayed in the format
RHSA, where:

R Read-only S System
H Hidden A Archive

4OS2, /T:acw (Time display): Specify which of the date and
4NT time fields on an NTFS or HPFS drive should be
displayed and used for sorting:

a last access time
c creation time
w last write time (default)

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 203

DIR
-------------------------------------------------------------------

/U (sUmmary information): Only display the number of
files, the total file size, and the total amount of
disk space used.

/V(ertical sort): Display the filenames sorted
vertically rather than horizontally (use with the /2,
/4 or /W options).

/W(ide): Display filenames only, horizontally across
the screen (5 columns on an 80-character wide
display).

4NT /X: Display both the short (8-character name plus 3-
character extension) and the long name of files on an
NTFS drive.

4OS2, /Z: Display an HPFS or NTFS directory in FAT format.
4NT Long names will be truncated to 12 characters. If the
name is longer than 12 characters, it will be followed
by a right arrow [a] to show that one or more
characters have been truncated.





























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 204

DIRS
-------------------------------------------------------------------

DIRS (New)

Purpose: Display the current directory stack.

Format: DIRS

See also: PUSHD and POPD.

Usage: The PUSHD command adds the current default drive and
directory to the directory stack, a list that 4DOS,
4OS2, and 4DOS/NT maintain in memory. The POPD
command removes the top entry of the directory stack
and makes that drive and directory the new default.
The DIRS command displays the contents of the
directory stack, with the most recent entries on top
(i.e., the next POPD will retrieve the first entry
that DIRS displays).

For example, to change directories and then display
the directory stack:

c:\> pushd c:\database
c:\database> pushd d:\wordp\memos
d:\wordp\memos> dirs
c:\database
c:\

The directory stack holds 255 characters, enough for
10 to 20 typical drive and directory entries.





















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 205

DO
-------------------------------------------------------------------

DO (New)

Purpose: Create loops in batch files.

Format: DO [n | FOREVER]
or
DO varname = start TO end [BY n]
or
DO [WHILE | UNTIL] condition
...
[ITERATE]
[LEAVE]
...
ENDDO

n, start, end: An integer between 0 and 2,147,483,647
inclusive, or an internal variable or
variable function that evaluates to such a
value.
varname: The environment variable that will hold
the loop counter.
condition: A test to determine if the loop should be
executed.

Usage: DO can only be used in batch files.

DO can be used to create 3 different kinds of loops.
The first, introduced by DO n, is a counted loop. The
batch file lines between DO and ENDDO are repeated n
times. You can also specify "forever" for n if you
wish to create an endless loop. For example:

do 5
beep
enddo

The second type of loop is similar to a "for loop" in
programming languages like BASIC. DO creates an
environment variable, varname, and sets it equal to
the value start (if varname already exists in the
environment, it will be overwritten). DO then begins
the loop process by comparing the value of varname
with the value of end. If varname is less than or
equal to end, DO executes the batch file lines up to
the ENDDO. Next, DO adds 1 to the value of varname,
or adds the value n if BY n is specified, and repeats
the compare and execute process until varname is
greater than end. This example displays the even
numbers from 2 through 20:

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 206

DO
-------------------------------------------------------------------

do i = 2 to 20 by 2
echo %i
enddo

DO can also count down, rather than up. If n is
negative, varname will decrease by n with each loop,
and the loop will stop when varname is less than end.
For example, to display the even numbers from 2
through 20 in reverse order, replace the first line of
the example above with:

do i = 20 to 2 by -2

The third type of loop is called a "while loop" or
"until loop."

DO WHILE executes the lines between DO and ENDDO as
long as the condition is true. The loop ends when the
condition becomes false. The condition is tested at
the start of the loop, so if the condition is
initially false the lines between DO and ENDDO will
never be executed.

DO UNTIL continues to execute the lines between DO and
ENDDO until the condition becomes true. The condition
is tested at the end of the loop, so if the condition
is initially true the lines between DO and ENDDO will
be executed once, then the loop will stop.

Two special commands, ITERATE and LEAVE, can only be
used inside a DO / ENDDO loop. ITERATE ignores the
remaining lines inside the loop and returns to the
beginning of loop for another iteration (unless DO
determines that the loop is finished). LEAVE exits
from the current DO loop and continues with the line
following ENDDO. Both ITERATE and LEAVE are most
often used in an IF or IFF command (see pages 238 and
244):

do while "%var" != "%val1"
...
if "%var" == "%val2" leave
enddo

You can nest DO loops up to 15 levels deep.

! ## You can exit from all DO / ENDDO loops by using GOTO
to a line past the last ENDDO. However, be sure to
read the cautionary notes about GOTO and DO under the

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 207

DO
-------------------------------------------------------------------

GOTO command (page 232) before using a GOTO inside any
DO loop.
















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 208

[4OS2, 4DOS/NT] DPATH
-------------------------------------------------------------------

DPATH [4OS2, 4DOS/NT] (Compatible)

Purpose: Specify the subdirectories which applications will
search to find files that are not in the current
directory.

Format: DPATH [directory[;directory...]]

directory: The full name of a directory to include in
the DPATH (data path) setting.

See also: PATH, SET, and ESET.

Usage: When most OS/2 and Windows NT applications try to open
a data file, they look for the file in the current
directory first. If they fail to find the file there,
they search each of the directories in the DPATH
setting in the order that they are included. Internal
commands like TYPE do not search the DPATH directories
for files.

For example, the following DPATH command directs
applications to look for files in this order: the
current directory, the INIT directory on C, and the
CONFIG directory on D:

[c:\] dpath c:\init;d:\config

The listing of directories to be searched can be set
or viewed with DPATH. The list is stored as an
environment string with the variable name DPATH, and
can also be set or viewed with the SET command and
edited with the ESET command.

Directory names in the DPATH must be separated with
semicolons [;]. 4OS2 and 4DOS/NT will not shift
directory names in the DPATH to upper case as they do
with those in the PATH setting. If you want the names
in the DPATH to be in upper case you must enter them
that way.

If you enter DPATH with no parameters, 4OS2 and 4DOS
/NT display the current DPATH search list.







-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 209

DRAWBOX
-------------------------------------------------------------------

DRAWBOX (New)

Purpose: Draw a box on the screen.

Format: DRAWBOX ulrow ulcol lrrow lrcol style [BRIght] [BLInk]
fg ON [BRIght] bg [FILl bgfill] [ZOOm] [SHAdow]

ulrow: Row for upper left corner
ulcol: Column for upper left corner
lrrow: Row for lower right corner
lrcol: Column for lower right corner
style: Box drawing style:
0 No lines (box is drawn with blanks)
1 Single line
2 Double line
3 Single line top and bottom, double on
sides
4 Double line top and bottom, single on
sides
fg: Foreground character color
bg: Background character color
bgfill: Background fill color (for the inside of
the box)

See also: DRAWHLINE and DRAWVLINE.

Usage: DRAWBOX is useful for creating attractive screen
displays in batch files.

For example, to draw a box around the entire screen
with bright white lines on a blue background:

drawbox 0 0 24 79 1 bri whi on blu fill blu

See page 26 for details about colors and color names,
and notes on the use of bright background colors.

If you use ZOOM, the box appears to grow in steps to
its final size. The speed of the zoom operation
depends on the speed of your video system.

If you use SHADOW, a drop shadow is created by
changing the characters in the row under the box and
the 2 columns to the right of the box to normal
intensity text with a black background (this will make
characters displayed in black disappear entirely).




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 210

DRAWBOX
-------------------------------------------------------------------

The row and column values are zero-based, so on a
standard 25 line by 80 column display, valid rows are
0 - 24 and valid columns are 0 - 79.

DRAWBOX checks for valid row and column values, and
displays a "Usage" error message if any values are out
of range.

Unlike DRAWHLINE and DRAWVLINE, DRAWBOX does not
automatically connect boxes to existing lines on the
screen with the proper connector characters. If you
want to draw lines inside a box and have the proper
connectors drawn automatically, draw the box first,
then use DRAWHLINE and DRAWVLINE to draw the lines.

DRAWBOX uses the standard line and box drawing
characters in the U.S. English extended ASCII
character set. If your system is configured for a
different country or language, the box may not appear
on your screen as you expect.

4DOS## DRAWBOX normally writes text directly to the screen.
If you have an unusual display adapter which does not
support direct video output, see the OutputBIOS
directive on page 143.

























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 211

DRAWHLINE
-------------------------------------------------------------------

DRAWHLINE (New)

Purpose: Draw a horizontal line on the screen.

Format: DRAWHLINE row column len style [BRIght] [BLInk]
fg ON [BRIght] bg

row: Starting row
column: Starting column
len: Length of line
style: Line drawing style:
1 Single line
2 Double line
fg: Foreground character color
bg: Background character color

See also: DRAWBOX and DRAWVLINE.

Usage: DRAWHLINE is useful for creating attractive screen
displays in batch files. It detects other lines and
boxes on the display, and creates the appropriate
connector characters when possible (not all types of
lines can be connected with the available characters).

For example, the following command draws a double line
along the top row of the display with green characters
on a blue background:

drawhline 0 0 80 2 green on blue

The row and column values are zero-based, so on a
standard 25 line by 80 column display, valid rows are
0 - 24 and valid columns are 0 - 79. DRAWHLINE checks
for a valid row and column, and displays a "Usage"
error message if either value is out of range.

See page 26 for details about colors and color names,
and notes on the use of bright background colors.

DRAWHLINE uses the standard line and box drawing
characters in the U.S. English extended ASCII
character set. If your system is configured for a
different country or language, the line may not appear
on your screen as you expect.

4DOS## DRAWHLINE normally writes text directly to the screen.
If you have an unusual display adapter which does not
support direct video output, see the OutputBIOS
directive on page 143.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 212

DRAWVLINE
-------------------------------------------------------------------

DRAWVLINE (New)

Purpose: Draw a vertical line on the screen.

Format: DRAWVLINE row column len style [BRIght][BLInk]
fg ON [BRIght] bg

row: Starting row
column: Starting column
len: Length of line
style: Line drawing style:
1 Single line
2 Double line
fg: Foreground character color
bg: Background character color

See also: DRAWBOX and DRAWHLINE.

Usage: DRAWVLINE is useful for creating attractive screen
displays in batch files. It detects other lines and
boxes on the display, and creates the appropriate
connector characters when possible (not all types of
lines can be connected with the available characters).

For example, to draw a double width line along the
left margin of the display with bright red characters
on a black background:

drawvline 0 0 25 2 bright red on black

The row and column values are zero-based, so on a
standard 25 line by 80 column display, valid rows are
0 - 24 and valid columns are 0 - 79. DRAWVLINE checks
for a valid row and column, and displays a "Usage"
error message if either value is out of range.

See page 26 for details about colors and color names,
and notes on the use of bright background colors.

DRAWVLINE uses the standard line and box drawing
characters in the U.S. English extended ASCII
character set. If your system is configured for a
different country or language, the line may not appear
on your screen as you expect.

4DOS## DRAWVLINE normally writes text directly to the screen.
If you have an unusual display adapter which does not
support direct video output, see the OutputBIOS
directive on page 143.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 213

ECHO
-------------------------------------------------------------------

ECHO (Enhanced)

Purpose: Display a message, enable or disable batch file or
command-line echoing, or display the echo status.

Format: ECHO [ON | OFF | message]

message: Text to display.

See also: ECHOS, SCREEN, SCRPUT, SETDOS and TEXT.

Usage: 4DOS, 4OS2, and 4DOS/NT have a separate echo
capability for batch files and for the command line.
The command-line ECHO state is independent of the
batch file ECHO state; changing ECHO in a batch file
has no effect on the display at the command prompt,
and vice versa.

To see the current echo state, use the ECHO command
with no arguments. This displays either the batch
file or command-line echo state, depending on where
the ECHO command is performed.

In a batch file, if you turn ECHO on, each line of the
file is displayed before it is executed. If you turn
ECHO off, each line is executed without being
displayed. ECHO can also be used in a batch file to
display a message on the screen. Regardless of the
ECHO state, a batch file line that begins with the [@]
character will not be displayed. To turn off batch
file echoing, without displaying the ECHO command, use
this line:

@echo off

ECHO commands in a batch file will send messages to
the screen while the batch file executes, even if ECHO
is set OFF. For example, this line will display a
message in a batch file:

echo Processing your print files...

If you want to echo a blank line from within a batch
file, enter:

echo.

You cannot use the command separator character ([^] in
4DOS or [&] in 4OS2 and 4DOS/NT) or the redirection

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 214

ECHO
-------------------------------------------------------------------

symbols (| > <) in an ECHO message, unless you enclose
them in quotes (see page 118) or precede them with the
escape character (see page 71).

ECHO defaults to ON in batch files. The current ECHO
state is inherited by called batch files. You can
change the default setting to ECHO OFF with the SETDOS
/V0 command or the BatchEcho directive in the .INI
file (see page 131).

If you turn the command-line ECHO on, each command
will be displayed before it is executed. This will
let you see the command line after expansion of all
aliases and variables. The command-line ECHO is most
useful when you are learning how to use advanced
features. This example will turn command-line echoing
on:

c:\> echo on

ECHO defaults to OFF at the command line.





























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 215

ECHOS
-------------------------------------------------------------------

ECHOS (New)

Purpose: Display a message without a trailing carriage return
and line feed.

Format: ECHOS message

See also: ECHO, SCREEN, SCRPUT, TEXT, and VSCRPUT.

Usage: ECHOS is useful for text output when you don't want to
add a carriage return / linefeed pair at the end of
the line. For example, you can use ECHOS when you
need to redirect control sequences to your printer;
this example sends the sequence Esc P to the printer
on LPT1:

c:\> echos -eP > lpt1:

You cannot use the command separator character ([^] in
4DOS and [&] in 4OS2 and 4DOS/NT) or the redirection
symbols [|><] in an ECHOS message, unless you enclose
them in quotes (see page 118) or precede them with the
escape character (see page 71).

## ECHOS does not translate or modify the message text.
For example, carriage return characters are not
translated to CR/LF pairs. ECHOS sends only the
characters you enter (after escape character and back-
quote processing). The only character you cannot put
into an ECHOS message is the NUL character (ASCII 0).




















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 216

ENDLOCAL
-------------------------------------------------------------------

ENDLOCAL (New)

Purpose: Restore the saved disk drive, directory, environment,
and alias list.

Format: ENDLOCAL

See also: SETLOCAL.

## Usage: The SETLOCAL command in a batch file saves the current
disk drive, default directory, all environment
variables, and the alias list. ENDLOCAL restores
everything that was saved by the previous SETLOCAL
command.

For example, this batch file fragment saves the drive,
current working directory, and environment variables,
removes all aliases so that any user aliases will not
affect batch file commands, changes the drive and
directory, sets some environment variables, runs the
program TEST1, and then restores the original values:

setlocal
unalias *
cdd d:\test
set path=c:\;c:\dos;c:\util
set lib=d:\lib
test1
endlocal

SETLOCAL and ENDLOCAL can only be used in batch files,
not in aliases or from the command line.


















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 217

ESET
-------------------------------------------------------------------

ESET (New)

Purpose: Edit environment variables and aliases.

Format: ESET [/A /M] variable name...

variable name: The name of an environment variable or
alias to edit.

/A(lias) /M(aster environment)

See also: ALIAS, UNALIAS, SET, and UNSET.

Usage: ESET allows you to edit environment variables and
aliases using line editing commands (see page 34).

For example, to edit the executable file search path:

c:\> eset path
path=c:\;c:\dos;c:\util

To create and then edit an alias:

c:\> alias d = dir /d/j/p
c:\> eset d
d=dir /d/j/p

ESET will search for environment variables first and
then aliases. If you have an environment variable and
an alias with the same name, ESET will edit the
environment variable and ignore the alias unless you
use the /A option.

Environment variable and alias names are normally
limited to 80 characters, and their contents to 255
characters in 4DOS, or 1,023 characters in 4OS2 and
4DOS/NT. However, if you use special techniques to
create a longer environment variable, ESET will edit
it provided the variable contains no more than 511
characters of text in 4DOS, or 2,047 characters in
4OS2 and 4DOS/NT.

If you have enabled global aliases (see page 163), any
changes made to an alias with ESET will immediately
affect all other copies of the command processor which
are using the same alias list.

Option: ## /A(lias): Edit the named alias even if an environment
variable of the same name exists. If you have an

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 218

ESET
-------------------------------------------------------------------

alias and an environment variable with the same name,
you must use this switch to be able to edit the alias.

4DOS /M(aster environment): Edit an environment variable
in the master environment rather than the local
environment. This option is only useful from a
secondary command shell (for example, when an
application has "shelled to DOS"). /M only works for
environment variables; it cannot be used to edit the
primary shell's aliases.








































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 219

EXCEPT
-------------------------------------------------------------------

EXCEPT (New)

Purpose: Perform a command on all available files except those
specified.

Format: EXCEPT (file) command

file: The file or files to exclude from the
command.
command: The command to execute, including all
appropriate arguments and switches.

See also: ATTRIB.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65). Date,
time, or size ranges must appear immediately after the
EXCEPT keyword.

Usage: EXCEPT provides a means of executing a command on a
group of files and/or subdirectories, and excluding a
subgroup from the operation. The command can be an
internal command or alias, an external command, or a
batch file.

You may use wildcards to specify the files to exclude
from the command. The first example erases all the
files in the current directory except those beginning
with MEMO, and those whose extension is .WKS. The
second example copies all the files and subdirectories
on drive C to drive D except those in C:\MSC and
C:\DOS, using the COPY command:

c:\> except (memo*.* *.wks) erase *.*
c:\> except (c:\msc c:\dos) copy c:\*.* d:\ /s

## Date, time, and size ranges can be used immediately
after the word EXCEPT to further qualify which files
should be excluded from the command. If the command
is an internal command that supports ranges, an
independent range can also be used in the command
itself.

! ## EXCEPT prevents operations on the specified file(s) by
setting the hidden attribute, performing the command,
and then clearing the hidden attribute. If the
command is aborted in an unusual way, you may need to
use the ATTRIB command to remove the hidden attribute
from the file(s).

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 220

EXCEPT
-------------------------------------------------------------------

! ## EXCEPT will not work with programs or commands that
ignore the hidden attribute or which work explicitly
with hidden files, including DEL /Z, and the /H
(process hidden files) switch available in some 4DOS,
4OS2, and 4DOS/NT file processing commands.

## You can use command grouping (see page 69) to execute
multiple commands with a single EXCEPT. For example,
the following command copies all files in the current
directory whose extensions begin with .DA, except the
.DAT files, to the D:\SAVE directory, then changes the
first two characters of the extension of the copied
files to .SA. This example should be entered on one
line:

c:\data> except (*.dat) (copy *.da* d:\save ^
ren *.da* *.sa*)

## If you use filename completion (see page 40) to enter
the filenames inside the parentheses, type a space
after the open parenthesis before entering a partial
filename or pressing Tab. Otherwise, the command-line
editor will treat the open parenthesis as the first
character of the filename to be completed.

4DOS ! ## If you receive a stack overflow error when using
EXCEPT in complex, nested command sequences, see the
notes under the StackSize directive on page 143.






















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 221

EXIT
-------------------------------------------------------------------

EXIT (Enhanced)

Purpose: Return from the command processor.

Format: EXIT [value]

value: The exit code to return (0 - 255).

Usage: EXIT terminates the current copy of the command
processor. Use it to return to an application when
you have "shelled out" to work at the prompt, or to
end a command-line session under Windows, OS/2, or
Windows NT.

To close the session, or to return to the application
that started the command processor, type:

c:\> exit

## If you specify a value, EXIT will return that value to
the program that started the command processor. For
example:

c:\> exit 255

## The value is a number you can use to inform the
program of some result, such as the success or failure
of a batch file. This feature is most useful for
systems which use batch files to automate their
operation, such as bulletin boards, or custom
application programs like databases that shell to the
command processor to perform certain tasks.

4DOS## You cannot EXIT from the primary 4DOS shell under DOS.
If EXIT does not seem to have any effect, you are
probably in the primary shell.














-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 222

FOR
-------------------------------------------------------------------

FOR (Enhanced)

Purpose: Repeat a command for several values of a variable.

Format: FOR [/A[[:][-]rhsda]] %var IN ([@]set) [DO] command...

%var: The variable to be used in the command
("FOR variable").
set: A set of values for the variable.
command: A command or group of commands to be
executed for each value of the variable.

/A(ttribute select)

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65). Date,
time, or size ranges must appear immediately after the
FOR keyword.

Usage: FOR begins by creating a set. It then executes a
command for every member of the set. The command can
be an internal command, an alias, an external command,
or a batch file.

Normally, the set is a list of files specified with
wildcards. For example, if you use this line in a
batch file:

for %x in (*.txt) do list %x

then LIST will be executed once for each file in the
current directory with the extension .TXT. The FOR
variable %x is set equal to each of the file names in
turn, then the LIST command is executed for each file.
(You could do the same thing more easily with a simple
LIST *.TXT. We used FOR here so you could get a feel
for how it operates, using a simple example.)

The set can include multiple files or an include list,
like this:

for %x in (d:\*.txt;*.doc;*.asc) do type %x

If the set includes filenames, the file list can be
further refined by using date, time, and size ranges
(see page 60). The range must be placed immediately
after the word FOR. The range will be ignored if no
wildcards are used inside the parentheses. For


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 223

FOR
-------------------------------------------------------------------

example, this set is made up of all of the *.TXT files
that were created or updated on October 4, 1993:

for /[d10-4-93,+0] %x in (*.txt) do ...

If the command is an internal command that supports
ranges, an independent range can also be used in the
command itself.

The set can also be made up of text instead of file
names. For example, to display the free space on
drives C:, D:, and E:, you could use:

for %drive in (c d e) do free %drive:

When the set is made up of text or several separate
file names (not an include list), the elements must be
separated by spaces, tabs, commas, or the switch
character (normally a slash [/]).

## You can also set the FOR variable equal to each line
in a file by placing an [@] in front of the file name.
If you have a file called DRIVES.TXT that contains a
list of drives on your computer, one drive name per
line (with a ":" after each drive letter), you can
print the free space on each drive this way:

for %d in (@drives.txt) do free %d > prn

## Because the [@] is also a valid filename character,
FOR first checks to see if the file exists with the
[@] in its name (i.e., a file named @DRIVES.TXT). If
so, the filename is treated as a normal argument. If
it doesn't exist, FOR uses the filename (without the
[@]) as the file from which to retrieve text.

## You can use either % or %% in front of the variable
name. Either form will work, whether the FOR command
is typed from the command line or is part of an alias
or batch file (some of the traditional command
processors require a single % if FOR is used at the
command line, but use %% if it is used in a batch
file). The variable name can be up to 80 characters
long. The word DO is optional.

## If you use a single-character FOR variable name, that
name is given priority over any environment variable
which starts with the same letter, in order to
maintain compatibility with the traditional FOR

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 224

FOR
-------------------------------------------------------------------

command. For example, the following command tries to
add a: and b: to the end of the PATH, but will not
work as intended:

c:\> for %p in (a: b:) do path %path;%p

The "%p" in "%path" will be interpreted as the FOR
variable %p followed by the text "ath", which is not
what was intended. To get around this, use a
different letter or a longer name for the FOR
variable, or use square brackets around the variable
name (see page 94).

## The following example uses FOR with variable functions
to delete the .BAK files for which a corresponding
.TXT file exists in the current directory (this should
be entered on one line):

c:\docs> for %file in (*.txt) do del
%@name[%file].bak

## You can use command grouping (see page 69) to execute
multiple commands for each element in the list. For
example, the following command copies each .WKQ file
in the current directory to the D:\WKSAVE directory,
then changes the extension of each file in the current
directory to .SAV. This should be entered on one
line:

c:\text> for %file in (*.wkq) do (copy %file
d:\wksave\ ^ ren %file *.sav)

(Use an ampersand [&] as the separator character if
you are using 4OS2 or 4DOS/NT.)

## In a batch file you can use GOSUB to execute a
subroutine for every element in the set. Within the
subroutine, the FOR variable can be used just like any
environment variable. This is a convenient way to
execute a complex sequence of commands for every
element in the set without CALLing another batch file.

## One unusual use of FOR is to execute a collection of
batch files or other commands with the same parameter.
For example, you might want to have three batch files
all operate on the same data file. The FOR command
could look like this (enter this on one line):

c:\> for %cmd in (filetest fileform fileprnt)

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 225

FOR
-------------------------------------------------------------------

do %cmd datafile

This line will expand to three separate commands:

filetest datafile
fileform datafile
fileprnt datafile

## The variable that FOR uses (the %CMD in the example
above) is created in the environment and then erased
when the FOR command is done. However, for
compatibility with COMMAND.COM and CMD.EXE, single-
character FOR variables do not overwrite existing
environment variables with the same name. As a
result, when using a multi-character variable name you
must be careful not to use the name of one of your
environment variables as a FOR variable. For example,
a command that begins

c:\> for %path in ...

will write over your current path setting and then
erase the path variable completely.

## FOR statements can be nested. Under 4DOS, the
permissible nesting level depends on the amount of
free space in 4DOS's internal stack.

4DOS ! ## If you receive a stack overflow error when using FOR
in complex, nested command sequences, see the notes
under the StackSize directive on page 143.

Options: ## /A(ttribute select): Process only those files that
have the specified attribute(s). /A will be used only
when processing wildcard file names in the set. It
will be ignored for filenames without wildcards or
other items in the set. Preceding the attribute
character with a hyphen [-] will process files that do
not have that attribute set. The attributes are:

R Read-only D Subdirectory
H Hidden A Archive
S System

If no attributes are listed (e.g., FOR /A ...), FOR
will process all files including hidden and system
files. If attributes are combined, all the specified
attributes must match for a file to be included. For
example, /A:RHS will include only those files with all

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 226

FOR
-------------------------------------------------------------------

three attributes set. See page 18 for more
information on file attributes.

For example, to process only those files with the
archive attribute set:

for /a:a %f in (*.*) echo %f needs a backup!











































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 227

FREE
-------------------------------------------------------------------

FREE (New)

Purpose: Display the total disk space, total bytes used, and
total bytes free on the specified (or default)
drive(s).

Format: FREE [drive: ...]

drive: One or more drives to include in the
report.

See also: MEMORY.

Usage: FREE provides the same disk information as the
external command CHKDSK, but without the wait, since
it does not check the integrity of the file and
directory structure of the disk.

A colon [:] is required after each drive letter. This
example displays the status of drives A and C:

c:\> free a: c:
Volume in drive A: is unlabeled
1,213,952 bytes total disk space
1,115,136 bytes used
98,816 bytes free
Volume in drive C: is DEVELOPMENT
42,496,000 bytes total disk space
36,851,712 bytes used
5,644,288 bytes free

If you are using DOS 4.0 or later, OS/2, or Windows
NT, the volume serial number will appear after the
drive label or name.

4DOS Some DOS networks with large server disk drives (256
MB or more) may report disk space values that are too
small when FREE is used. If this occurs, it is
because the network software does not report the
proper values to 4DOS.










-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 228

GLOBAL
-------------------------------------------------------------------

GLOBAL (New)

Purpose: Execute a command in the current directory and its
subdirectories.

Format: GLOBAL [/H /I /P /Q] command

command: The command to execute, including
arguments and switches.

/H(idden directories) /P(rompt)
/I(gnore exit codes) /Q(uiet)

Usage: GLOBAL performs the command first in the current
directory and then in every subdirectory under the
current directory. The command can be an internal
command, an alias, an external command, or a batch
file.

This example copies the files in every directory on
drive A to the directory C:\TEMP:

a:\> global copy *.* c:\temp

If you use the /P option, GLOBAL will prompt for each
subdirectory before performing the command. You can
use this option if you want to perform the command in
most, but not all subdirectories of the current
directory.

## You can use command grouping (see page 69) to execute
multiple commands in each subdirectory. For example,
the following command copies each .TXT file in the
current directory and all of its subdirectories to
drive A. It then changes the extension of each of the
copied files to .SAV:

c:\> global (copy *.txt a: ^ ren *.txt *.sav)

4DOS ! ## If you use GLOBAL in complex, nested command
sequences, see the cautionary note on page 143.

Options: ## /H(idden directories): Forces GLOBAL to look for
hidden directories. If you don't use this switch,
hidden directories are ignored.

## /I(gnore exit codes): If this option is not
specified, GLOBAL will terminate if the command
returns a non-zero exit code. Use /I if you want

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 229

GLOBAL
-------------------------------------------------------------------

command to continue in additional subdirectories even
if it returns an error in a previous subdirectory.
Even if you use /I, GLOBAL will halt execution in
response to Ctrl-C or Ctrl-Break.

/P(rompt): Forces GLOBAL to prompt with each
directory name before it performs the command. Your
options at the prompt are explained in detail on page
48.

/Q(uiet): Do not display the directory names as each
directory is processed.






































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 230

GOSUB
-------------------------------------------------------------------

GOSUB (New)

Purpose: Execute a subroutine in the current batch file.

Format: GOSUB label

label: The batch file label at the beginning of
the subroutine.

See also: CALL, GOTO and RETURN.

Usage: GOSUB can only be used in batch files.

4DOS, 4OS2, and 4DOS/NT allow subroutines in batch
files. A subroutine must start with a label (a colon
[:] followed by a one-word label name) which appears
on a line by itself. Case differences are ignored
when matching labels. The subroutine must end with a
RETURN statement.

The subroutine is invoked with a GOSUB command from
another part of the batch file. After the RETURN,
processing will continue with the command following
the GOSUB command. For example, the following batch
file fragment calls a subroutine which displays the
directory and returns:

echo Calling a subroutine
gosub subr1
echo Returned from the subroutine
quit
:subr1
dir /a/w
return

If the label doesn't exist, the batch file is
terminated with the error message "Label not found."

GOSUB saves the IFF state, so IFF statements inside a
subroutine won't interfere with IFF statements in the
part of the batch file from which the subroutine was
called.

## Subroutines can be nested. Under 4DOS, the
permissible nesting level depends on the amount of
free space in 4DOS's internal stack; if you receive a
stack overflow error when using GOSUB in complex,
nested command sequences, see the notes under the
StackSize directive on page 143.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 231

GOTO
-------------------------------------------------------------------

GOTO (Compatible)

Purpose: Branch to a specified line inside the current batch
file.

Format: GOTO [/I] label

label: The batch file label to branch to.

/I(FF and DO continue)

See also: GOSUB.

Usage: GOTO can only be used in batch files.

After a GOTO command in a batch file, the next line to
be executed will be the one immediately after the
label. The label must begin with a colon [:] and
appear on a line by itself. The colon is required on
the line where the label is defined, but is not
required in the GOTO command itself. Case differences
are ignored when matching labels.

This batch file fragment checks for the existence of
the file CONFIG.SYS. If the file exists, the batch
file jumps to C_EXISTS and copies all the files from
the current directory to the root directory on A:.
Otherwise, it prints an error message and exits.

if exist config.sys goto C_EXISTS
echo CONFIG.SYS doesn't exist - exiting.
quit
:C_EXISTS
copy *.* a:\

If the label doesn't exist, the batch file is
terminated with the error message "Label not found."

! ## To avoid errors in the processing of nested statements
and loops, GOTO cancels all active IFF statements and
DO /ENDDO loops unless you use /I. This means that a
normal GOTO (without /I) may not branch to any label
that is between an IFF and the corresponding ENDIFF or
between a DO and the corresponding ENDDO.

Options: ## /I(FF and DO continue): Prevents GOTO from canceling
IFF statements and DO loops. Use this option only if
you are absolutely certain that your GOTO command is
branching entirely within any current IFF statement

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 232

GOTO
-------------------------------------------------------------------

and any active DO / ENDDO block. Using /I under any
other conditions will cause an error later in your
batch file.

You cannot branch into another IFF statement, another
DO loop, or a different IFF or DO nesting level,
whether you use the /I option or not. If you do, you
will eventually receive an "unknown command" error (or
execution of the UNKNOWN_CMD alias) on a subsequent
ENDDO, ELSE, ELSEIFF, or ENDIFF statement.








































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 233

HELP
-------------------------------------------------------------------

HELP (Enhanced, External command)

Purpose: Display help for internal commands. Help for external
commands is also available under DOS, and optionally
under OS/2.

Format: HELP [topic]

topic: A help topic, internal command, or
external command.

Usage: Online help is available for 4DOS, 4OS2, and 4DOS/NT.
The 4OS2 and 4DOS/NT help systems use the operating
system's help facility. 4DOS uses its own help
program.

See page 46 for more details on getting help at the
command line. See the Introduction and Installation
Guide that was supplied with your version of 4DOS,
4OS2, or 4DOS/NT for a more thorough explanation of
the online help available with the program you use.

If you type the command HELP by itself (or press F1
when the command line is empty), the table of contents
is displayed. If you type HELP plus a topic name,
that topic is displayed. For example,

help copy

displays information about the COPY command and its
options.



















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 234

HISTORY
-------------------------------------------------------------------

HISTORY (New)

Purpose: Display, add to, clear, or read the history list.

Format: HISTORY [/A command /F /P /R filename]

/A(dd) /P(ause)
/F(ree) /R(ead)

See also: LOG.

Usage: 4DOS, 4OS2, and 4DOS/NT keep a list of the commands
you have entered on the command line. See page 35 for
information on command recall, which allows you to use
the history list to repeat or edit commands you have
typed.

The HISTORY command lets you view and manipulate the
command history list directly. If no parameters are
entered, HISTORY will display the current command
history list:

c:\> history

With the options explained below, you can clear the
list, add new commands to the list without executing
them, save the list in a file, or read a new list from
a file.

The number of commands saved in the history list
depends on the length of each command line. The
history list size can be specified at startup from 512
to 8192 characters (see page 127). The default size
is 1024 characters.

Your history list can be stored either locally (a
separate history list for each copy of the command
processor) or globally (all copies of the command
processor share the same list). For full details see
the discussion of local and global history lists
beginning on page 38.

## You can use the HISTORY command as an aid in writing
batch files by redirecting the HISTORY output to a
file and then editing the file appropriately.
However, it is easier to use the LOG /H command for
this purpose.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 235

HISTORY
-------------------------------------------------------------------

## You can disable the history list or specify a minimum
command-line length to save with the HistMin directive
in the .INI file.

Options: ## /A(dd): Add a command to the history list. This
performs the same function as the Ctrl-K key at the
command line (see page 35).

/F(ree): Erase all entries in the command history
list.

/P(rompt): Wait for a key after displaying each page
of the list. Your options at the prompt are explained
in detail on page 48.

## /R(ead): Read the command history from the specified
file and append it to the history list currently held
in memory. Each line in the file must fit within the
command-line length limit for your command processor
(see page 47).

You can save the history list by redirecting the
output of HISTORY to a file. This example saves the
command history to a file called HISTFILE and reads it
back again immediately. If you leave out the HISTORY
/F command on the second line, the contents of the
file will be appended to the current history list
instead of replacing it:

c:\> history > histfile
c:\> history /f
c:\> history /r histfile

If you need to save your history at the end of each
day's work, you might use commands like this in your
AUTOEXEC.BAT or other startup file:

if exist c:\histfile history /r c:\histfile
alias shut*down `history > c:\histfile`

This restores the previous history list if it exists,
then defines an alias which will save the history
before shutting off the system.

## If you are creating a HISTORY /R file by hand, and
need to create an entry that spans multiple lines in
the file, you can do so by terminating each line,
except the last, with an escape character (see page


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 236

HISTORY
-------------------------------------------------------------------

71). However, you cannot use this method to exceed
the command-line length limit.
















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 237

IF
-------------------------------------------------------------------

IF (Enhanced)

Purpose: Execute a command if a condition or set of conditions
is true.

Format: IF [NOT] condition [.AND. | .OR. | .XOR. [NOT]
condition ...] command

condition: A test to determine if the command should
be executed.
command: The command to execute if the condition is
true.

See also: IFF.

Usage: IF is normally used only in aliases and batch files.
It is always followed by one or more conditions and
then a command. First, the conditions are evaluated.
If they are true, the command is executed. Otherwise,
the command is ignored. If you add a NOT before a
condition, the command is executed only when the
condition is false.

You can link conditions with .AND., .OR., or .XOR.,
and you can nest IF statements. The conditions can
test strings, numbers, the existence of a file or
subdirectory, the exit code returned by the preceding
external command, and the existence of alias names and
internal commands.

The command can be an alias, an internal command, an
external command, or a batch file. The entire IF
statement, including all conditions and the command,
must fit on one line.

## You can use command grouping (see page 69) to execute
multiple commands if the condition is true. For
example, the following command tests if any .TXT files
exist. If they do, they are copied to drive A: and
their extensions are changed to .TXO:

if exist *.txt (copy *.txt a: ^ ren *.txt *.txo)

(Change the command separator to an ampersand [&] to
use a command like this under 4OS2 or 4DOS/NT. Also,
note that the IFF command provides a more structured
method of executing multiple commands if a condition
or set of conditions is true.)


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 238

IF
-------------------------------------------------------------------

4DOS ! ## If you receive a stack overflow error when using IF in
complex, nested command sequences, see the notes under
the StackSize directive on page 143.

Conditions: The following conditional tests are available in both
the IF and IFF commands. They fit into two
categories: string and numeric tests, and status
tests. The tests can use environment variables,
internal variables and variable functions, file names,
literal text, and numeric values as their arguments.

Spaces are required on either side of the test
condition in all cases, except == which will work with
or without spaces around it.


String and Numeric Tests

Six test conditions can be used to test character
strings. The same conditions are available for both
numeric and normal text strings (see below for
details). In each case you enter the test as:

string1 operator string2

The operator defines the type of test (equal, greater
than or equal, and so on). The operators are:

Operator Tests

EQ or == string1 equal to string2
NE or != string1 not equal to string2
LT string1 less than string2
LE string1 less than or equal to string2
GE string1 greater than or equal to
string2
GT string1 greater than string2

When IF compares two character strings, it will use
either a numeric comparison or a string comparison. A
numeric comparison treats the strings as numeric
values and tests them arithmetically. A string
comparison treats the strings as text.

The difference between numeric and string comparisons
is best explained by looking at the way two values are
tested. For example, consider comparing the values 2
and 19. Numerically, 2 is smaller, but as a string it
is "larger" because its first digit is larger than the

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 239

IF
-------------------------------------------------------------------

first digit of 19. So the first of these conditions
will be true, and the second will be false:

if 2 lt 19 ...
if "2" lt "19" ...

IF determines which kind of test to do by examining
the first character of each string. If both strings
begin with a numeric character (a digit, sign, or
decimal point), a numeric comparison is used. If
either value does not begin with a numeric character,
a string comparison is used. To force a string
comparison when both values are or may be numeric, use
double quotes around the values you are testing, as
shown above. Because the double quote is not a
numeric character, it forces IF to do a string

comparison.

Case differences are ignored in string comparisons.
If two strings begin with the same text but one is
shorter, the shorter string is considered to be "less
than" the longer one. For example, "a" is less than
"abc", and "hello_there" is greater than "hello".

When you compare text strings, you should always
enclose the arguments in double quotes in order to
avoid syntax errors which may occur if one of the
argument values is empty.

Numeric comparisons work with both integer and decimal
values. The values to be compared must contain only
numeric digits, decimal points, and an optional sign
(+ or -). The number to the left of the decimal point
may not exceed 2,147,483,648 (the maximum possible 32-
bit positive integer). The number of digits to the
right of the decimal point is limited only by the
length of the command line.

Internal variables (page 97) and variable functions
(page 105) are very powerful when combined with string
and numeric comparisons. They allow you to test the
state of your system, the characteristics of a file,
date and time information, or the result of a
calculation. You may want to review the variables and
variable functions when determining the best way to
set up an IF test.

This first example is a batch file fragment which runs
a program called MONOPROG if a monochrome monitor is

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 240

IF
-------------------------------------------------------------------

attached to the system (this example will work in 4DOS
or 4OS2; 4DOS/NT does not include the _MONITOR
variable):

if "%_monitor" == "mono" monoprog

The second batch file fragment tests for a string
value:

input "Enter your selection : " %%cmd
if "%cmd" == "WP" goto wordproc
if "%cmd" NE "GRAPHICS" goto badentry

This example calls GO.BTM if the first two characters
in the file MYFILE are "GO" (enter this example on one
line):

if "%@instr[0,2,%@line[myfile,0]]"=="GO"
call go.btm


The next two examples test whether there is more than
500 KBytes of free memory or more than 2 MBytes of
free EMS memory (the EMS example only applies to
4DOS):

c:\> if %@dosmem[k] gt 500 echo Over 500K free
c:\> if %@ems[m] gt 2 echo Over 2 MB EMS free


Status Tests

These conditions test the system or command processor
status. You can use internal variables and variable
functions to test many other parts of the system
status.

ERRORLEVEL [operator] n

This test retrieves the exit code of the
preceding external program. By convention,
programs return an exit code of 0 when they are
successful and a number between 1 and 255 to
indicate an error. The condition can be any of
the operators listed above (EQ, !=, GT, etc.).
If no operator is specified, the default is GE.
The comparison is done numerically.




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 241

IF
-------------------------------------------------------------------

Not all programs return an explicit exit code.
For programs which do not, the behavior of
ERRORLEVEL is undefined.

EXIST filename

If the file exists, the condition is true. You
can use wildcards in the filename, in which case
the condition is true if any file matching the
wildcard name exists.

ISALIAS aliasname

If the name is defined as an alias, the condition
is true.

ISDIR | DIREXIST path

If the subdirectory exists, the condition is
true. For compatibility with DR DOS and Novell
DOS, DIREXIST may be used as a synonym for ISDIR.

ISINTERNAL command

If the specified command is an active internal
command, the condition is true. Commands can be
activated and deactivated with the SETDOS /I
command.

ISLABEL labelname

If the name exists as a label in the current
batch file, the condition is true.

4NT ISWINDOW "title"

If a window with the title exists, the condition
is true. Double quotes must be used around the
title.

The first batch file fragment below tests for the
existence of A:\JAN.DOC before copying it to drive C.

if exist a:\jan.doc copy a:\jan.doc c:\

This example tests the exit code of the previous
program and stops all batch file processing if an
error occurred:


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 242

IF
-------------------------------------------------------------------

if errorlevel==0 goto success
echo "External Error -- Batch File Ends!"
cancel


## Combining Tests

You can negate the result of any test with NOT, and
combine tests of any type with .AND., .OR., and .XOR.
Test conditions are always scanned from left to right
- there is no implied order of precedence, as there is
in some programming languages.

When two tests are combined with .AND., the result is
true if both individual tests are true. When two
tests are combined with .OR., the result is true if
either (or both) individual tests are true. When two
tests are combined with .XOR., the result is true only
if one of the tests is true and the other is false.

This example runs a program called HIGHRES if either
an EGA or VGA video adapter is in use (this will work
in 4DOS or 4OS2; 4DOS/NT does not include the _VIDEO
variable):

if "%_video"=="ega" .or. "%_video"=="vga" highres
























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 243

IFF
-------------------------------------------------------------------

IFF (New)

Purpose: Perform IF / THEN / ELSE conditional execution of
commands.

Format: IFF [NOT] condition [.AND. | .OR. | .XOR. [NOT]
condition ...] THEN ^ commands
[ELSEIFF condition THEN ^ commands] ...
[ELSE ^ commands]
^ ENDIFF

condition: A test to determine if the command(s)
should be executed.
commands: One or more commands to execute if the
condition(s) is true. If you use multiple
commands, they must be separated by
command separators or be placed on
separate lines of a batch file.

See also: IF.

Usage: IFF is similar to the IF command, except that it can
perform one set of commands when a condition or set of
conditions is true and different commands when the
conditions are false.

IFF can execute multiple commands when the conditions
are true or false; IF normally executes only one
command. IFF imposes no limit on the number of
commands and is generally a "cleaner" and more
structured command than IF.

IFF is always followed by one or more conditions. If
they are true, the commands that follow the word THEN
are executed. Additional conditions can be tested
with ELSEIFF. If none of these conditions are true,
the commands that follow the word ELSE are executed.
In both cases, after the selected commands are
executed, processing continues after the word ENDIFF.

If you add a NOT before the condition, the THEN
commands are executed only when the condition is false
and the ELSE commands are executed only when the
condition is true.

The commands may be separated by command separators,
or may be on separate lines of a batch file. You
should include a command separator or a line break
after a THEN, before an ELSEIFF, and before and after

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 244

IFF
-------------------------------------------------------------------

an ELSE. Note that the syntax above and the examples
below use the default 4DOS command separator, a caret
[^]. Replace the caret with an ampersand [&] if you
are using 4OS2 or 4DOS/NT.

You can link conditions with .AND., .OR., or .XOR.,
and you can nest IFF statements up to 15 levels deep.
The conditions can test strings or numbers, the
existence of a file or subdirectory, the errorlevel
returned from the preceding external command, and the
existence of alias names and internal commands.

See the IF command for a list of the possible
conditions.

The commands can include any internal command, alias,
external command, or batch file.

The following batch file fragment for 4DOS or 4OS2
tests the monitor type (monochrome or color), and sets
the appropriate colors and prompt (enter the "prompt"
lines on one line of the batch file):

iff "%_monitor" == "color" then
color bright white on blue ^ cls
prompt=$e[s$e[1;1f$e[41;1;37m$e[K Path:
$p$e[u$e[44;37m$n$g
else
prompt=$e[s$e[1;1f$e[0;7m$e[K Path:
$p$e[u$e[0m$n$g
endiff

(The above example uses ANSI color sequences in the
prompt, which work in 4DOS if an ANSI driver is
loaded, and in 4OS2. They will not work in 4DOS/NT,
because Windows NT does not offer ANSI support. See
PROMPT for additional details.)

The alias in this second example checks to see if the
argument is a subdirectory. If so, the alias deletes
the subdirectory's files and removes it (enter this on
one line):

c:\> alias prune `iff isdir %1 then ^
del /sxz %1 ^ else ^
echo Not a directory!^endiff`




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 245

IFF
-------------------------------------------------------------------

! ## Be sure to read the cautionary notes about GOTO and
IFF under the GOTO command (page 232) before using a
GOTO inside an IFF statement.















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 246

INKEY
-------------------------------------------------------------------

INKEY (New)

Purpose: Get a single keystroke from the user and store it in
an environment variable.

Format: INKEY [/C /K"keys" /P /Wn] [prompt] %%varname

prompt: Optional text that is displayed as a
prompt.
varname: The variable that will hold the user's
keystroke.

/C(lear buffer) /P(assword)
/K (valid keystrokes) /W(ait)

See also: INPUT and KEYSTACK.

Usage: INKEY optionally displays a prompt. Then it waits for
a specified time or indefinitely for a keystroke, and
places the keystroke into an environment variable. It
is normally used in batch files and aliases to get a
menu choice or other single-key input. Along with the
INPUT command, INKEY allows great flexibility in
reading input from within a batch file or alias.

If prompt text is included in an INKEY command, it is
displayed while INKEY waits for input.

The following batch file fragment prompts for a
character and stores it in the variable NUM:

inkey Enter a number from 1 to 9: %%num

INKEY reads standard input for the keystroke, so it
will accept keystrokes from a redirected file or from
the Keystack under 4DOS. You can supply a list of
valid keystrokes with the /K option.

Standard keystrokes with ASCII values between 1 and
255 are stored directly in the environment variable.
Extended keystrokes (for example, function keys and
cursor keys) are stored as a string in decimal format,
with a leading @ (for example, the F1 key is @59).
The Enter key is stored as an extended keystroke, with
the code @28. See Appendix B (page 357) for a list of
the ASCII and extended key codes.

If you press Ctrl-C or Ctrl-Break while INKEY is
waiting for a key, execution of an alias will be

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 247

INKEY
-------------------------------------------------------------------

terminated, and execution of a batch file will be
suspended while you are asked whether to cancel the
batch job (see page 82). In a batch file you can
handle Ctrl-C and Ctrl-Break yourself with the ON
BREAK command (see page 274).

Options: /C(lear buffer): Clears the keyboard buffer before
INKEY accepts keystrokes. If you use this option,
INKEY will ignore any keystrokes which you type,
either accidentally or intentionally, before INKEY is
ready to accept input.

/K["keys"]: Specify the permissible keystrokes. The
list of valid keystrokes should be enclosed in double
quotes. For alphabetic keys the validity test is not
case-sensitive. You can specify extended keys by
enclosing their names in square brackets (within the
quotes), for example:

inkey /k"ab[F10]" Enter A, B, or F10 %%var

See page 31 for a complete listing of the key names
you can use within the square brackets, and a
description of the key name format.

If an invalid keystroke is entered, the command
processor will echo the keystroke if possible, beep,
move the cursor back one character, and wait for
another keystroke.

/P(assword): Prevents INKEY from echoing the
character.

/W(ait): Timeout period, in seconds, to wait for a
response. If no keystroke is entered by the end of
the timeout period, INKEY returns with the variable
unchanged. You can specify /W0 to return immediately
if there are no keys waiting in the keyboard buffer.

For example, the following batch file fragment waits
up to 10 seconds for a character, then tests to see if
a "Y" was entered:

set net=N
inkey /K"YN" /w10 Load the network (Y/N)? %%net
iff "%net" == "Y" then
rem Commands to load the network go here
endiff


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 248

INPUT
-------------------------------------------------------------------

INPUT (New)

Purpose: Get a string from the keyboard and save it in an
environment variable.

Format: INPUT [/C /E /Ln /P /Wn] [prompt] %%varname

prompt: Optional text that is displayed as a
prompt.
varname: The variable that will hold the user's
input.

/C(lear buffer) /P(assword)
/E(dit) /W(ait)
/L(ength)

See also: INKEY and KEYSTACK.

Usage: INPUT optionally displays a prompt. Then it waits for
a specified time or indefinitely for your entry. It
places any characters you type into an environment
variable. INPUT is normally used in batch files and
aliases to get multi-key input. Along with the INKEY
command, INPUT allows great flexibility in reading
user input from within a batch file or alias.

If prompt text is included in an INPUT command, it is
displayed while INPUT waits for input. Standard
command-line editing keys may be used to edit the
input string as it is entered. If you use the /P
password option, INPUT will echo asterisks instead of
the keys you type.

All characters entered up to, but not including, the
carriage return are stored in the variable.

The following batch file fragment prompts for a string
and stores it in the variable FNAME:

input Enter the file name: %%fname

INPUT reads standard input, so it will accept text
from a re-directed file or from the KEYSTACK.

If you press Ctrl-C or Ctrl-Break while INPUT is
waiting for input, execution of an alias will be
terminated, and execution of a batch file will be
suspended while you are asked whether to cancel the
batch job (see page 82). In a batch file you can

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 249

INPUT
-------------------------------------------------------------------

handle Ctrl-C and Ctrl-Break yourself with the ON
BREAK command (see page 274).

Option: /C(lear buffer): Clears the keyboard buffer before
INPUT accepts keystrokes. If you use this option,
INPUT will ignore any keystrokes which you type,
either accidentally or intentionally, before INPUT is
ready.

/E(dit): Allows you to edit an existing value. If
there is no existing value for varname, INPUT proceeds
as if /E had not been used, and allows you to enter a
new value.

/Ln (Length): Sets the maximum number of characters
which INPUT will accept to "n". If you attempt to
enter more than this number of characters, INPUT will
beep and prevent further input (you will still be able
to edit the characters typed before the limit was
reached).

/P(assword): Tells INPUT to echo asterisks, instead
of the characters you type.

/W(ait): Timeout period, in seconds, to wait for a
response. If no keystroke is entered by the end of
the timeout period, INPUT returns with the variable
unchanged. If you enter a key before the timeout
period, INPUT will wait indefinitely for the remainder
of the line. You can specify /W0 to return
immediately if there are no keys waiting in the
keyboard buffer.


















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 250

KEYBD
-------------------------------------------------------------------

KEYBD (New)

Purpose: Set the state of the keyboard toggles: Caps Lock, Num
Lock, and Scroll Lock.

Format: KEYBD [/Cn /Nn /Sn]

/C(aps lock) /S(croll lock)
/N(um lock)

n can be either 0 to turn off the toggle or 1 to turn
on the toggle.

Usage: Most keyboards have 3 toggle keys, the Caps Lock, Num
Lock, and Scroll Lock. The toggle key status is
usually displayed by three lights at the top right
corner of the keyboard.

This command lets you turn any toggle key on or off.
It is most useful in batch files and aliases if you
want the keys set a particular way before collecting
input from the user.

For example, to turn off the Num Lock and Caps Lock
keys, you can use this command:

c:\> keybd /c0 /n0

If you use the KEYBD command with no switches, it will
display the present state of the toggle keys.

4DOS## In 4DOS, KEYBD works by performing a BIOS setting.
Some memory resident programs that monitor the
physical keyboard rather than BIOS settings may not
recognize that the state of the toggle keys has
changed after a KEYBD command.

4OS2## In OS/2, the toggle key state is different for each
session. Changes made with KEYBD will affect the
session in which the command is executed, but will not
affect other sessions.

4NT ## In Windows NT, the toggle key state is the same for
all sessions. Changes made in one session will affect
all other sessions.

Options: /C(aps lock): Turn the Caps Lock key on or off.

/N(um lock): Turn the Num Lock key on or off.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 251

KEYBD
-------------------------------------------------------------------

/S(croll lock): Turn the Scroll Lock key on or off.

















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 252

[4OS2, 4DOS/NT] KEYS
-------------------------------------------------------------------

KEYS [4OS2, 4DOS/NT] (Enhanced)

Purpose: Enable, disable, or display the history list.

Format: KEYS [ON | OFF | LIST]

See also: HISTORY.

Usage: This command is provided for compatibility with KEYS
command in CMD.EXE, which controls the history list in
OS/2 and Windows NT. The same functions are available
by setting the HistMin directive in the .INI file, and
by using the HISTORY command.

The history list collects the commands you type for
later recall, editing, and viewing. You can view the
contents of the list through the history list window
or by typing any of the following commands:

[c:\] history
[c:\] history /p
[c:\] keys list

The first command displays the entire history list.
The second displays the entire list and pauses at the
end of each full screen. The third command produces
the same output as the first, except that each line is
numbered.

You can disable the collection and storage of commands
in the history list by typing:

[c:\] keys off

You can turn the history back on with the command:

[c:\] keys on

If you issue the KEYS command without any parameters,
4OS2 or 4DOS/NT will show you the current status of
the history list.

4OS2 KEYS also affects the way 4OS2 reads input from the
keyboard. KEYS OFF will force 4OS2 into line input
mode; KEYS ON will return input to the usual character
by character method. See the LineInput directive on
page 133, or the /L option of the SETDOS command on
page 310, for details on line input mode.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 253

[4DOS] KEYSTACK
-------------------------------------------------------------------

KEYSTACK [4DOS] (New)

Purpose: Feed keystrokes to a program or command automatically.

Format: KEYSTACK [/Wn] ["abc"] [keyname] [!] ...

"abc": Literal characters to be placed in the
Keystack.
keyname: Name or code for a key to be placed in the
Keystack.
!: Signal to clear the Keystack and the
keyboard buffer.

/W(ait)

Usage: KEYSTACK takes a series of keystrokes and feeds them
to a program or command as if they were typed at the
keyboard. When the program has used all of the
keystrokes in the keystack buffer, it will begin to
read the keyboard for input, as it normally would.

The KEYSTACK command must be executed before running
the program which is going to receive the keystrokes.
This places the keystrokes into the buffer first, so
the program can find them when it runs.

KEYSTACK will only work if the memory-resident program
KSTACK.COM has been loaded. KSTACK is usually loaded
from the AUTOEXEC.BAT file (see page 83). If KSTACK
is not loaded, the KEYSTACK command will display an
error message. If you are using a multitasking system
such as DESQview or Windows, see your Introduction and
Installation Guide for information on loading KSTACK
within a window.

Characters entered within double quotes ("abc") will
be stored "as is" in the keyboard buffer. The only
items allowed outside double quotes are key names, key
codes, and the ! and /W options.

See page 31 for a complete listing of key names and a
description of the key name format.

An exclamation mark [!] will clear all pending
keystrokes, both in the KEYSTACK buffer and in the
keyboard buffer.

For example, to start ProComm Plus and skip the
opening screen you could use the command:

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 254

[4DOS] KEYSTACK
-------------------------------------------------------------------

c:\comm> keystack 32 ^ pcplus

This places a space (ASCII code 32) in the buffer,
then runs ProComm Plus. When ProComm looks for a
keystroke to end the display of the opening screen the
keystroke is already in the buffer, and the opening
screen is removed immediately.

You can store a maximum of 255 characters in the
KEYSTACK buffer. Each time the KEYSTACK command is
executed, it will clear any remaining keystrokes
stored by a previous KEYSTACK command.

You may need to experiment with your programs and
insert delays (see the /W option) to find a keystroke
sequence that works for a particular program.

Programs that bypass DOS and the BIOS for keyboard
input cannot read keystrokes entered with KEYSTACK.
If you use KEYSTACK and then run such a program, the
keystrokes will not appear in the program, but may
appear at the prompt when you exit the program and
return to 4DOS.

## KEYSTACK treats the number 0 as a special case; it is
used with programs that flush the keyboard buffer.
When KEYSTACK processes a key value of 0, it tells the
program the buffer is clear, so subsequent keystrokes
will be accepted normally. Some programs will require
several "0"s before they will accept input; you may
need to experiment to determine the correct number.

For example, the following batch file starts Lotus 1-
2-3 and loads the file specified on the command line
when the batch file is invoked (the KEYSTACK command
should be entered on one line):

pushd c:\123
keystack 0 Enter 0 Enter 0 Enter 0 Enter 0 Enter
"/FR" 0 "%1" Enter
123
popd

The sequence of "0 Enter" pairs tells 1-2-3 that the
keyboard buffer is empty, then passes 1-2-3 a carriage
return, repeating this sequence five times. This gets
1-2-3 to a point where an empty spreadsheet is
displayed. The rest of the KEYSTACK line issues a
File Retrieve command (/FR), simulates an empty

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 255

[4DOS] KEYSTACK
-------------------------------------------------------------------

keyboard buffer once more, enters the file name passed
on the batch command line (%1), and finally enters a
carriage return to end the file name.

## Here's the same command defined as an alias (enter
this on one line):

alias 321 `pushd c:\123 ^ keystack 0 Enter 0
Enter 0 Enter 0 Enter 0 Enter "/FR" 0 "%1" 13 ^
123 ^ popd`

## Some programs require both the keyboard "scan code"
and the ASCII value to be stacked. To stack both
codes, calculate the value ((256 * scan code) + ASCII
code) and enter that numeric value as an argument for
KEYSTACK. For example, for the Enter key, the scan
code is 28 and the ASCII code is 13, so to stack both
values use ((256 * 28) + 13) or KEYSTACK 7181. Try
this approach if a "normal" KEYSTACK command does not
work (for example, if you use "KEYSTACK 13" or
"KEYSTACK Enter" for the Enter key and the program
doesn't see the correct character). To stack combined
key codes you must use the numeric value, not the key
name. See Appendix B on page 357 for a complete list
of ASCII codes and scan codes.

Options: ## /W(ait): Delay the next keystroke in the KEYSTACK
buffer by a specified number of clock "ticks". A
clock tick is approximately 1/18 second. The number
of clock ticks to delay should be placed immediately
after the W, and must be between 1 and 65535 (65535
ticks is about 1 hour). You can use the /W option as
many times as desired and at any point in the string
of keystrokes except within double quotes. Some
programs may need the delays provided by /W in order
to receive keystrokes properly from KEYSTACK. The
only way to determine what delay is needed is to
experiment. Sometimes a combination of a delay and an
"empty buffer" signal (a 0) are required. For
example, to start the program CADX and send it an F7,
a delay of one second, an indication that the keyboard
buffer is empty, and a carriage return:

c:\> keystack F7 /W18 0 Enter ^ cadx






-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 256

[4DOS] LH / LOADHIGH
-------------------------------------------------------------------

LH / LOADHIGH [4DOS] (Compatible)

Purpose: Load a memory resident program into an Upper Memory
Block (UMB).

Format: LH [/L:r1,n1;r2,n2;... /S] filename
or
LOADHIGH [/L:r1,n1;r2,n2;... /S] filename

filename: The name of the program to load into high
memory.

/L(oad region) /S(hrink)

Usage: LH and LOADHIGH are synonyms. You can use either one.

LOADHIGH requires version 5.0 or later of MS-DOS, PC-
DOS, DR DOS, or Novell DOS, or an OS/2 2.x DOS
session.

If you load memory-resident programs into UMBs, you
will have more room in base memory for application
programs. If your system has no UMBs, or if the
program is larger than the largest UMB, then LOADHIGH
will load the program into conventional base memory.

For example, to load the program C:\UTIL\CACHE.EXE
into high memory:

c:\> loadhigh c:\util\cache.exe

If you are running MS-DOS / PC-DOS 5.0 or above, or an
OS/2 2.x DOS session, LOADHIGH requires the DOS=UMB
command in your CONFIG.SYS file. It can only be used
to load programs into UMBs managed by version 5.0 or
later of MS-DOS, PC-DOS, DR DOS, or Novell DOS; or by
OS/2 2.x DOS sessions.

! If you use a memory manager like 386MAX or QEMM to
manage your UMBs, rather than the MS-DOS DOS=UMB
directive, then LOADHIGH will not work, and you must
use the equivalent command supplied with your memory
manager in order to load programs high.

See your 4DOS Introduction and Installation Guide for
complete details on UMBs and UMB regions, and the
hardware and software required to support them.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 257

[4DOS] LH / LOADHIGH
-------------------------------------------------------------------

## The /L and /S switches are designed to aid in
optimizing the use of upper memory by selecting one or
more UMB regions for a particular memory-resident
program to use. They are fully compatible with the
MS-DOS 6.0 and above memory optimizer, MEMMAKER, and
may also be used under MS-DOS 5.0 and in OS/2 2.x DOS
sessions. (They are not used by other memory
optimizers, such as QEMM's OPTIMIZE or 386MAX's
MAXIMIZE.)

While a complete discussion of memory optimization
techniques is well beyond the scope of this manual,
the basic technique is to load each memory-resident
program into a specific region to free up the maximum
possible amount of base memory.

Optimizing UMB usage requires a detailed knowledge of
the memory requirements for your memory-resident
programs. This information can be very difficult to
obtain, because some programs require more memory when
starting and less when running, and each program is
unique. However, if you know these memory
requirements, you may be able to use /L and /S to
optimize the use of upper memory, or to improve on the
optimization done by MEMMAKER or another memory
optimizer.

Options: ## /L:r1,n1;r2,n2;... (Load region): Specifies which
region(s) should be used for the program, and
optionally the minimum free space required in a region
before the program is allowed access to that region.

If /L is not used, all upper memory regions are
available to the program. If /L is used, you must
specify one or more regions (r1, r2, etc.); only those
regions will be made available. Upper memory regions
are numbered sequentially beginning with 1 (region 0
refers to low memory, and is normally used only by
MEMMAKER).

If only a region number is given, the entire region is
made available to the program (assuming there is free
space in the region). If a size is given for a
particular region (n1, n2, etc.), then the region is
only made available if the free space in the region is
equal to or greater than that size. All sizes are in
bytes. Any region not available to a particular
program is "locked out" while that program is loading
and made available again once the program is loaded.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 258

[4DOS] LH / LOADHIGH
-------------------------------------------------------------------

If the combination of /L values you use does not
provide sufficient upper memory space for the program
to load, it will be loaded in low memory.

You can combine /L values in several ways. In each of
the following examples, if the requested space is not
available or is insufficient the program is loaded
into low memory:

lh /l:2 filename
The program can use region 2 only.

lh /l:2;3 filename
The program can use regions 2 and 3 only.

lh /l:2,2048 filename
The program can use region 2 only, and only
if it has 2048 or more bytes free.

lh /l:2,2048;3 filename
The program can use region 2 if it has 2048
or more bytes free, and region 3 regardless
of how many bytes it has free

## /S(hrink): Shrinks each region selected by /L to the
minimum size used in /L before loading the program.
This prevents memory-resident programs which take all
available memory from using more than you want them
to. This switch is primarily intended for use by
MEMMAKER.




















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 259

LIST
-------------------------------------------------------------------

LIST (New)

Purpose: Display a file, with forward and backward paging and
scrolling.

Format: LIST [/H /S /W /X] file...

file: A file or list of files to display.

/H(igh bit off) /W(rap)
/S(tandard input) /X (heX display mode)

See also: TYPE.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65).

Usage: LIST provides a much faster and more flexible way to
view a file than TYPE, without the overhead of loading
and using a text editor.

LIST is most often used for displaying ASCII text
files. Most other files contain non-alphabetic
characters and may be unreadable, except in hex mode.

For example, to display a file called MEMO.DOC:

c:\> list memo.doc

LIST uses the cursor pad to scroll through the file.
The following keys have special meanings:

Home Display the first page of the
file.
End Display the last page of the
file.
Esc Exit the current file.
Ctrl-C Quit LIST.
Up Arrow Scroll up one line.
Down Arrow Scroll down one line.
Left Arrow Scroll left 8 columns.
Right Arrow Scroll right 8 columns.
Ctrl-Left Arrow Scroll left 40 columns.
Ctrl-Right Arrow Scroll right 40 columns.
F1 Display online help
F Prompt and search for a string.
G Go to a specific line.
H Toggle the "strip high bit" (/H)
option.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 260

LIST
-------------------------------------------------------------------

I Display information on the
current file (the full name,
size, date, and time).
N Find next matching string.
P Print the entire file.
W Toggle the "line wrap" (/W)
option.
X Toggle the hex-mode display (/X)
option.

Text searches performed with F and N are not case-
sensitive. However, if the display is currently in
hexadecimal mode and you press F, you will be prompted
for whether you want to search in hexadecimal as well.
If you answer Y, you should then enter the search
string as a sequence of 2-digit hexadecimal numbers
separated by spaces, for example 41 63 65 (these are
the ASCII values for the string "Ace"; see Appendix B
on page 357 for a complete list of ASCII codes).
Hexadecimal searches are case-sensitive, and search
for exactly the string you enter.

LIST saves the search string used by F and N, so you
can LIST multiple files and search for the same string
simply by pressing N in each file, or repeat your
search the next time you use LIST.

LIST normally allows long lines in the file to extend
past the right edge of the screen. You can use the
horizontal scrolling keys (see above) to view text
that extends beyond the screen width. If you use the
W command or /W switch to wrap the display, each line
is wrapped when it reaches the right edge of the
screen, and the horizontal scrolling keys are
disabled.

If you print the file which LIST is displaying, the
print format will match the display format. If you
have switched to hexadecimal or wrapped mode, that

mode will be used for the printed output as well. If
you print in wrapped mode, long lines will be wrapped
at the width of the display. If you print in normal
display mode without line wrap, long lines will be
wrapped or truncated by the printer, not by LIST.

Printed output normally goes to device LPT1. If you
wish to send the printed output to another device, use
the Printer directive in the .INI file (see page 134).


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 261

LIST
-------------------------------------------------------------------

## Most of the LIST keystrokes can be reassigned with
.INI file directives (see pages 136 and 141).

## You can set the colors used by LIST with the
ListColors and ListStatBarColors directives in the
.INI file. If ListColors is not used, the LIST
display will use the current default colors. If
ListStatBarColors is not used, the status bar will use
the reverse of the LIST display colors.

4DOS## LIST normally writes text directly to the screen. If
you have an unusual display adapter which does not
support direct video output, see the OutputBIOS
directive on page 143.

Options: ## /H(igh bit off): Strip the high bit from each
character before displaying. This is useful when
displaying files created by some word processors that
turn on the high bit for formatting purposes. You can
toggle this option on and off from within LIST with
the H key.

/S(tandard input): Read from standard input rather
than a file. This allows you to redirect command
output and view it with LIST. For example, to use
LIST to display the output of DIR:

c:\> dir | list /s

/W(rap): Wrap the text at the right edge of the
screen. This option is useful when displaying files
that don't have a carriage return at the end of each
line. The horizontal scrolling keys do not work when
the display is wrapped. You can toggle this option on
and off from within LIST with the W key.

/X (hex mode): Display the file in hexadecimal (hex)
mode. This option is useful when displaying
executable files and other files that contain non-text
characters. Each byte of the file is shown as a pair
of hex characters. The corresponding text is
displayed to the right of each line of hexadecimal
data. You can toggle this mode on and off from within
LIST with the X key.






-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 262

LOADBTM
-------------------------------------------------------------------

LOADBTM (New)

Purpose: Switch a batch file to or from BTM mode.

Format: LOADBTM [ON | OFF]

Usage: 4DOS, 4OS2, and 4DOS/NT recognize two kinds of batch
files: .BAT or .CMD, and .BTM. Batch files executing
in BTM mode run two to five times faster than in BAT
or CMD mode. (However, BTM mode should not be used to
load memory-resident programs in DOS, nor should BTM
mode be used for self-modifying batch files.) Batch
files automatically start in the mode indicated by
their extension. For more information on .BTM, .BAT,
and .CMD files, see page 77.

The LOADBTM command turns BTM mode on and off. It can
be used to switch modes in either a .BAT / .CMD or
.BTM file. If you use LOADBTM with no argument, it
will display the current batch mode: LOADBTM ON or
LOADBTM OFF.

LOADBTM can only be used within a batch file. It is
most often used to switch a .BAT file into BTM mode
after memory-resident programs are loaded, to convert
a .BAT or .CMD file to BTM mode without changing its
extension, or to switch a .BTM file into BAT mode in
order to load memory-resident programs under DOS.

Using LOADBTM to repeatedly switch modes within a
batch file is not efficient. In most cases the speed
gained by running some parts of the file in BTM mode
will be more than offset by the speed lost through
repeated loading of the file each time BTM mode is
invoked.

The following .BAT file fragment loads some memory
resident programs (TSRs), and then switches to BTM
mode:

rem Loading TSRs...
ansi.com
mouse.com
rem Switch to high-speed (BTM) mode now that
rem TSRs are loaded
loadbtm on
path c:\;c:\util;c:\dos
alias /r c:\aliases


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 263

LOG
-------------------------------------------------------------------

LOG (New)

Purpose: Save a log of commands to a disk file.

Format: LOG [/H /W file] [ON | OFF | text]

file: The name of the file to hold the log.
text: An optional message that will be added to
the log.

/H(istory log) /W(rite to).

See also: HISTORY.

Usage: LOG keeps a record of all internal and external
commands you use. Each entry includes the current
system date and time, along with the actual command
after any alias or variable expansion (see page 116
for more information on alias and variable expansion).
You can use the log file as a record of your daily
activities.

LOG with the /H option keeps a similar record, but it
does not record the date and time for each command.
In addition, it records commands before aliases and
variables are expanded.

By default, LOG writes to the file 4DOSLOG, 4OS2LOG,
or 4NTLOG (depending on which command processor you
are using), in the root directory of the boot drive.
The corresponding default file names for LOG /H are
4DOSHLOG, 4OS2HLOG, and 4NTHLOG.

Entering LOG or LOG /H with no parameters displays the
log status (ON or OFF):

c:\> log
LOG is OFF

To enable or disable logging, add the word "ON" or
"OFF" after the LOG command:

c:\> log on

or

c:\> log /h on



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 264

LOG
-------------------------------------------------------------------

Entering LOG or LOG /H with text writes a message to
the log file, even if logging is set OFF. This
allows you to enter headers in the log file:

c:\> log "Started work on the database system"

The LOG file format looks like this:

[mm-dd-yy hh:mm:ss] command

The LOG /H output can be used as the basis for writing
batch files. Start LOG /H, then execute the commands
that you want the batch file to execute. When you are
finished, turn LOG /H off. The resulting file can be
turned into a batch file that performs the same
commands with little or no editing.

You can have both a regular log (with time and date
stamping) and a history log (without the time stamps)
enabled simultaneously.

Options: /H(istory log): This option turns on (or off) the
history log, which saves commands without the time and
date stamp. For example, to turn on history logging
and write to the file C:\LOG\HLOG:

c:\> log /h /w c:\log\hlog

/W(rite): This switch specifies a different filename
for the LOG or LOG /H output. It also automatically
performs a LOG ON command. For example, to turn
logging on and write the log to C:\LOG\LOGFILE:

c:\> log /w c:\log\logfile

Once you select a new file name with the LOG /W or LOG
/H/W command, LOG will use that file until you issue
another LOG /W or LOG /H/W command, or until you
reboot your computer. Turning LOG or LOG /H off or on
does not change the file name. You can set the
default log file names when your command processor
starts with the LogName and HistLogName directives in
the .INI file.







-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 265

MD / MKDIR
-------------------------------------------------------------------

MD / MKDIR (Enhanced)

Purpose: Create a subdirectory.

Format: MD [/S] pathname...
or
MKDIR [/S] pathname...

pathname: The name of one or more directories to
create.

/S(ubdirectories)

See also: RD.

Usage: MD and MKDIR are synonyms. You can use either one.

MD creates a subdirectory anywhere in the directory
tree. To create a subdirectory from the root, start
the pathname with a backslash [\]. For example, this
command creates a subdirectory called MYDIR in the
root directory:

c:\> md \mydir

If no path is given, the new subdirectory is created
in the current directory. This example creates a
subdirectory called DIRTWO in the current directory:

c:\mydir> md dirtwo

To create a directory from the parent of the current
directory (that is, to create a sibling of the current
directory), start the pathname with two periods and a
backslash [..\].

The operating system limits the permissible length of
the full subdirectory name. See page 16 for details.

Option: /S(ubdirectories): MD creates one directory at a time
unless you use the /S option. If you need to create
the directory C:\ONE\TWO\THREE and none of the named
directories exist, you can use /S to have MD create
all of the necessary subdirectories for you in a
single command:

c:\> md /s \one\two\three



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 266

MEMORY
-------------------------------------------------------------------

MEMORY (New)

Purpose: Display the amount and status of system RAM.

Format: MEMORY

Usage: MEMORY displays information about the RAM in your
system.

4DOS In 4DOS, MEMORY lists the amount of total RAM in your
system and the amount available for applications after
DOS, 4DOS, and memory-resident programs have been
loaded; the amount of EMS expanded memory, XMS
extended memory, and non-XMS extended memory; the HMA
status; and the amount of memory 4DOS is using for
environment variable space, alias space, and history
space:

c:\> memory
655,360 bytes total RAM
534,464 bytes free

1,687,552 bytes total EMS memory
1,097,728 bytes free

914,432 bytes total XMS memory (HMA in use)

512 bytes total environment
195 bytes free

1,024 bytes total alias
452 bytes free

1,024 bytes total history

You can use the information from the MEMORY display to
fine tune your system, to aid in setting the proper
alias and environment sizes in 4DOS.INI, and to be
sure that you have sufficient memory for your largest
applications.

If you compare the free RAM displayed by MEMORY with
the free RAM displayed by CHKDSK and some memory map
programs, MEMORY will usually show a slightly higher
value. The difference is the size of the environment
passed to these external programs; most memory mapping
programs do not count the passed environment as free
space, but MEMORY does.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 267

MEMORY
-------------------------------------------------------------------

The MEMORY command displays for 4OS2 and 4DOS/NT are
somewhat different to reflect the way in which OS/2
and Windows NT organize the computer's memory.

4OS2 A typical MEMORY display using 4OS2 is shown below:

16,379,904 bytes total physical RAM
40,546,048 bytes total resident RAM
5,050,368 bytes largest free block

3,145,728 bytes total swap file

4,096 bytes total environment
2,451 bytes free

4,096 bytes total alias
1,910 bytes free

1,024 bytes total history

4NT A typical MEMORY display using 4DOS/NT is shown below:

21 % Memory load

16,449,536 bytes total physical RAM
3,665,920 bytes available physical RAM

37,715,968 bytes total page file
19,038,208 bytes available page file

4,096 bytes total environment
3,192 bytes free

32,768 bytes total alias
32,767 bytes free

1,024 bytes total history













-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 268

MOVE
-------------------------------------------------------------------

MOVE (New)

Purpose: Move files to a new directory and drive.

Format: MOVE [/C /D /F /H /N /P /Q /R /S /T /U] source...
destination

source: A file or list of files to move.
destination: The new location for the files.

/C(hanged) /Q(uiet)
/D(irectory) /R(eplace)
/F(orce delete) /S(ubdirectory tree)
/H(idden and system) /T(otal)
/N(othing) /U(pdate)
/P(rompt)

See also: COPY and RENAME.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65). Date,
time, or size ranges anywhere on the line apply to all
source files.

Usage: The MOVE command moves one or more files from one
directory to another, whether the directories are on
the same drive or not. It has the same effect as
copying the files to a new location and then deleting
the originals. Like COPY and RENAME, MOVE works with
single files, multiple files, and sets of files
specified with an include list.

The simplest MOVE command moves a single source file
to a new location and, optionally, gives it a new
name. These two examples both move one file from
drive C: to the root directory on drive A:

c:\> move myfile.dat a:\
c:\> move myfile.dat a:\savefile.dat

In both cases, MYFILE.DAT is removed from drive C:
after it has been copied to drive A:. If a file
called MYFILE.DAT in the first example, or
SAVEFILE.DAT in the second example, already existed on
drive A:, it would be overwritten. (This demonstrates
the difference between MOVE and RENAME. MOVE will
move files between drives and will overwrite the
destination file if it exists; RENAME will not.)


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 269

MOVE
-------------------------------------------------------------------

If you MOVE multiple files, the destination must be a
directory name. MOVE will move each file into the
destination directory with its original name (if the
target is not a directory, MOVE will display an error
message and exit):

c:\> move *.wks *.txt c:\finance\myfiles

You cannot move a file to a character device like the
printer, or to itself.

When you move files to another directory, if you add a
backslash [\] to the end of the destination name MOVE
will display an error message if the name does not
refer to an existing directory. You can use this
feature to keep MOVE from treating a mistyped
destination directory name as a file name, and
attempting to move all source files to that name. The
/D option performs the same function but will also
prompt to see if you want to create the destination
directory if it doesn't exist.

! Be careful when you use MOVE with the SELECT command.
If you SELECT multiple files and the target is not a
directory (for example, because of a misspelling),
MOVE will assume it is a file name. In this case each
file will be moved in turn to the target file,
overwriting the previous file, and then the original
will be erased before the next file is moved. At the
end of the command, all of the original files will
have been erased and only the last file will exist as
the target file. You can avoid this problem by using
square brackets with SELECT instead of parentheses (be
sure that you don't allow the command line to get too
long - watch the character count in the upper left
corner while you're selecting files). MOVE will then
receive one list of files to move instead of a series
of individual filenames, and it will detect the error
and halt. You can also add a backslash [\] to the end
of the destination name to ensure that it is the name
of a subdirectory (see above).

## MOVE first attempts to rename the file(s), which is
the fastest way to move files between subdirectories
on the same drive. If that fails (the destination is
on a different drive or already exists), MOVE will
copy the file(s) and then delete the originals.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 270

MOVE
-------------------------------------------------------------------

## If you are using 4DOS in an OS/2 DOS session, MOVE
will copy OS/2 extended attributes from the source to
the destination, provided the file system on the
destination drive supports them.

## If MOVE must physically copy the files and delete the
originals, rather than renaming them (see above), then
some disk space may be freed on the source drive. The
free space may be the result of moving the files to
another drive, or of overwriting a larger destination
file with a smaller source file. MOVE displays the
amount of disk space recovered unless the /Q option is
used (see below). It does so by comparing the amount
of free disk space before and after the MOVE command
is executed. However, this amount may be incorrect if
you are using a deletion tracking system which stores
deleted files in a hidden directory, or if, under a
multitasking system, another program performs a file
operation while the MOVE command is executed.

## When physically copying files, MOVE preserves the
hidden, system, and read-only attributes of the source
files, and sets the archive attribute of the
destination files. However, if the files can be
renamed, and no copying is required, then the source
file attributes are not changed.

Options: /C(hanged files): Move files only if the destination
file exists and is older than the source (see also
/U). This option is useful for updating the files in
one directory from those in another without moving any
newly-created files.

/D(irectory): Requires that the destination be a
directory. If the destination does not exist, MOVE

will prompt to see if you want to create it. If the
destination exists as a file, MOVE will fail with an
"Access denied" error. Use this option to avoid
having MOVE accidentally interpret your destination
name as a file name when it's really a mistyped
directory name.

## /F(orce delete): This option is only for use in the
32-bit version of 4OS2, and in 4DOS when running in an
OS/2 2.1 or later DOS session. It forces deletion of
the source file without saving it to the DELDIR
directory (if DELDIR is not in use, /F has no effect).



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 271

MOVE
-------------------------------------------------------------------

## /H(idden): Move all files, including hidden and
system files.

/N(othing): Do everything except actually move the
file(s). This option is most useful for testing what
a complex MOVE command will do.

/P(rompt): Prompt the user to confirm each move.
Your options at the prompt are explained in detail on
page 48.

/Q(uiet): Don't display filenames, the total number
of files moved, or the amount of disk space recovered,
if any. This option is most often used in batch
files. See also /T.

/R(eplace): Prompt for a Y or N response before
overwriting an existing destination file.

/S(ubdirectories): Move an entire subdirectory tree
to another location. MOVE will attempt to create the
destination directories if they don't exist, and will
remove empty subdirectories after the move. When /D
is used with /S, you will be prompted if the first
destination directory does not exist, but
subdirectories below that will be created
automatically by MOVE. If you attempt to use /S to
move a subdirectory tree into part of itself, MOVE
will display an error message and halt.

/T(otal): Don't display filenames as they are moved,
but display the total number of files deleted and the
amount of free disk space recovered, if any.

/U(pdate): Move each source file only if it is newer
than a matching destination file or if a matching
destination file does not exist (also see /C). This
option is useful for moving new or changed files from
one directory to another.











-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 272

[4DOS/NT] MSGBOX
-------------------------------------------------------------------

MSGBOX [4DOS/NT] (New)

Purpose: Display a message box and collect the user's response.

Format: MSGBOX OK | OKCANCEL | YESNO | YESNOCANCEL ["title"]
prompt

title: Text for the title bar of the message box.
prompt: Text that will appear inside the message
box.

Usage: MSGBOX can display one of 4 kinds of message boxes and
wait for the user's response. You can use title and
prompt to display any text you wish. 4DOS/NT
automatically sizes and locates the box on the screen.

The message box may have 1, 2, or 3 response buttons.
The command MSGBOX OK creates a single-button box; the
user must simply acknowledge the prompt text.

The OKCANCEL and YESNO forms have 2 buttons each. The
YESNOCANCEL form has 3 buttons. The button the user
chooses is returned in the 4DOS/NT variable %_?. Be
sure to save the return value in another variable or
test it immediately; the value of %_? changes with
every internal command.

The following list shows the value returned for each
possible selection:

Yes 10 No 11
OK 10 Cancel 12

If you exit the message box without selecting one of
these options (for example, some message boxes allow
you to exit by pressing Esc or double-clicking the
close button), MSGBOX will set %_? to 0. If there is
an error in the MSGBOX command itself, %_? will be set
as described on page 99.











-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 273

ON
-------------------------------------------------------------------

ON (New)

Purpose: Execute a command in a batch file when a specific
condition occurs.

Format: ON BREAK [command]
or
ON ERROR [command]

Usage: ON can only by used in batch files.

ON sets a "watchdog" that remains in effect for the
duration of the current batch file. Whenever a BREAK
or ERROR condition occurs after ON has been executed,
the command is automatically executed.

ON BREAK will execute its command if the user presses
Ctrl-C or Ctrl-Break.

ON ERROR will execute its command after any command
processor or operating system error (including
critical errors; see page 49). That is, ON ERROR will
detect errors such as a disk write error, and 4DOS,
4OS2, or 4DOS/NT errors such as a COPY command that
fails to copy any files, or the use of an unacceptable
command option.

ON BREAK and ON ERROR are independent of each other.
You can use either one, or both, in any batch file.

Each time ON BREAK or ON ERROR is used, it defines a
new command to be executed for a break or error, and
any old command is discarded. If you use ON BREAK or
ON ERROR with no following command, that type of error
handling is disabled. Error handling is also
automatically disabled when the batch file exits.

ON BREAK and ON ERROR only affect the current batch
file. If you CALL another batch file, the first batch
file's error handling is suspended, and the CALLed
file must define its own error handling. When control
returns to the first batch file, its error handling is
reactivated.

The command can be any command that can be used on a
batch file line by itself. Frequently, it is a GOTO
or GOSUB command. For example, the following fragment
traps any user attempt to end the batch file by
pressing Ctrl-C or Ctrl-Break. It scolds the user for

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 274

ON
-------------------------------------------------------------------

trying to end the batch file and then continues
displaying the numbers from 1 to 1000:

on break gosub gotabreak
do i = 1 to 1000
echo %i
enddo
quit
:gotabreak
echo Hey! Stop that!!
return

You can use a command group (see page 69) as the
command if you want to execute multiple commands, for
example:

on break (echo Oops, got a break!^quit)

ON BREAK and ON ERROR always assume that you want to
continue executing the batch file. After the command
is executed, control automatically returns to the next
command in the batch file (the command after the one
that was interrupted by the break or error). The only
way to avoid continuing the batch file after a break
or error is for the command to transfer control to
another point with GOTO, end the batch file with QUIT
or CANCEL, or start another batch file (without
CALLing it).

When handling an error condition with ON ERROR, you
may find it useful to use internal variables (see page
97), particularly %_? and %_SYSERR, to help determine
the cause of the error.

! If a break or error occurs while the command specified
in ON BREAK or ON ERROR is executing, the command will
be restarted. This means you must use caution to
avoid or handle any possible errors in the commands
invoked by ON ERROR, since such errors can cause an
infinite loop and/or a stack overflow condition.










-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 275

PATH
-------------------------------------------------------------------

PATH (Enhanced)

Purpose: Display or alter the list of directories that 4DOS,
4OS2, or 4DOS/NT will search for executable files,
batch files, and files with executable extensions that
are not in the current directory.

Format: PATH [directory[;directory...]]

directory: The full name of a directory to include in
the path setting.

See also: ESET and SET.

Usage: When the command processor is asked to execute an
external command (a .COM, .EXE, .BTM, .BAT, or .CMD
file or executable extension), it first looks for the
file in the current directory. If it fails to find an
executable file there, it then searches each of the
directories specified in the PATH setting. See page
20 for more details on how the path is searched.

For example, after the following PATH command, the
command processor will search for an executable file
in four directories: the current directory, then the
root directory on drive C, then the DOS subdirectory
on C, and then the UTIL subdirectory on C:

c:\> path c:\;c:\dos;c:\util

The list of directories to search can be set or viewed
with the PATH command. The list is stored as an
environment string, and can also be set or viewed with
SET, and edited with ESET.

Directory names in the path must be separated by
semicolons [;]. Each directory name is shifted to
upper case to maintain compatibility with programs
which can only recognize upper case directory names in
the path. If you modify your path with the SET or
ESET command, you may include directory names in lower
case. These may cause trouble with some programs,
which assume that all path entries have been shifted
to upper case.

If you enter PATH with no parameters, the current path
is displayed:

c:\> path

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 276

PATH
-------------------------------------------------------------------

PATH=C:\;C:\DOS;C:\UTIL

Entering PATH and a semicolon clears the search path
so that only the current directory is searched for
executable files (this is the default at system
startup).

Some applications also use the PATH to search for
their data files.

## If you include an explicit file extension on a command
name (for example, WP.EXE), the search will find files
with that name and extension in the current directory
and every directory in the path. It will not locate
other executable files with the same base name.

## If you have an entry in the path which consists of a
single period [.], the current directory will not be
searched first, but instead will be searched when the
command processor reaches the "." in the path. This
allows you to delay the search of the current
directory for executable files and files with
executable extensions. In rare cases, this feature
may not be compatible with applications which use the
path to find their files; if you experience a problem,
you will have to remove the "." from the path while
using any such application.

4DOS## In normal use, 4DOS can create a path as long as 250
characters (the command-line limit is 255 characters,
and "PATH " takes five). However, some DOS
applications expect a path no longer than the
traditional limit of 123 characters. If you extend
your path beyond this limit and experience problems
with application programs, see Appendix A of the 4DOS
Introduction and Installation Guide for tips on
resolving the difficulty.


## To create a path longer than the command-line length
limit, use PATH repeatedly to append additional
directories to the path:

path [first list of directories]
path %path;[second list of directories]
...

You cannot use this method to extend the path beyond
506 characters in 4DOS or 2042 characters in 4OS2 and
4DOS/NT (the internal buffer limits, with room for

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 277

PATH
-------------------------------------------------------------------

"PATH "). It is usually more efficient to use aliases
to load application programs than to create a long
PATH. See ALIAS on page 155 for details.

If you specify an invalid directory in the path, it
will be skipped and the search will continue with the
next directory in the path.











































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 278

PAUSE
-------------------------------------------------------------------

PAUSE (Enhanced)

Purpose: Suspend batch file or alias execution.

Format: PAUSE [text]

text: The message to be displayed as a user prompt.

Usage: A PAUSE command will suspend execution of a batch file
or alias, giving you the opportunity to change disks,
turn on the printer, etc.

PAUSE waits for any key to be pressed and then
continues execution. You can specify the text that
PAUSE displays while it waits for a keystroke, or let
4DOS use the default message:

Press any key when ready...

For example, the following batch file fragment prompts
the user before erasing files (the PAUSE command
should be entered on one line):

pause Press Ctrl-C to abort, any other key to
erase all .LST files
erase *.lst

If you press Ctrl-C or Ctrl-Break while PAUSE is
waiting for a key, execution of an alias will be
terminated, and execution of a batch file will be
suspended while you are asked whether to cancel the
batch job (see page 82). In a batch file you can
handle Ctrl-C and Ctrl-Break yourself with the ON
BREAK command (see page 274).
















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 279

POPD
-------------------------------------------------------------------

POPD (New)

Purpose: Return to the disk drive and directory at the top of
the directory stack.

Format: POPD [*]

See also: DIRS and PUSHD.

Usage: Each time you use the PUSHD command, it saves the
current disk drive and directory on the internal
directory stack. POPD restores the last drive and
directory that was saved with PUSHD and removes that
entry from the stack. You can use these commands
together to change directories, perform some work, and
return to the starting drive and directory.

Directory changes made with POPD are recorded for
display in the directory history window (see page 43).

This example saves and changes the current disk drive
and directory with PUSHD, and then restores it. The
current directory is shown in the prompt:

c:\> pushd d:\database\test
d:\database\test> pushd c:\wordp\memos
c:\wordp\memos> pushd a:\123
a:\123> popd
c:\wordp\memos> popd
d:\database\test> popd
c:\>

You can use the DIRS command to see the complete list
of saved drives and directories (the directory stack).

The POPD command followed by an asterisk [*] clears
the directory stack without changing the current drive
and directory.

## If the directory on the top of the stack is not on the
current drive, POPD will switch to the drive and
directory on the top of the stack without changing the
default directory on the current drive.







-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 280

PROMPT
-------------------------------------------------------------------

PROMPT (Enhanced)

Purpose: Change the command-line prompt.

Format: PROMPT [text]

text: Text to be used as the new command-line prompt.

Usage: You can change and customize the command-line prompt
at any time. The prompt can include normal text, and
system information such as the current drive and
directory, the time and date, and the amount of memory
available. You can create an informal "Hello, Bob!"
prompt or an official-looking prompt full of
impressive information.

The prompt text can contain special commands in the
form $?, where ? is one of the characters listed
below:

b The vertical bar character [|].
c The open parenthesis [(].
d Current date, in the format: Fri Jan 7,
1994.
D Current date, in the format: Fri 1-07-94
(the month, day, and year are formatted
according to your current country settings).
e The ASCII ESC character (decimal 27).
f The close parenthesis [)].
g The > character.
h Backspace over the previous character.
i Display the OS/2 prompt header line, which
reminds you of how to return to the OS/2
desktop, or get help.
l The < character.
n Current drive letter.
p Current drive and directory (lower case).
P Current drive and directory (upper case).
q The = character.
r The numeric exit code of the last external
command.
s The space character.
t Current 24-hour time, in the format
hh:mm:ss.
T Current 12-hour time, in the format
hh:mm:ss[a|p].
v Operating system version number, in the
format 3.10.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 281

PROMPT
-------------------------------------------------------------------

xd: Current directory on drive d:, in lower
case.
Xd: Current directory on drive d:, in upper
case.
z Current shell nesting level; the primary
command processor is shell 0.
$ The $ character.
_ CR/LF (go to beginning of a new line).

For example, to set the prompt to the current date and
time, with a ">" at the end:

c:\> prompt $d $t $g
Fri Dec 3, 1993 10:29:19 >

To set the prompt to the current date and time,
followed by the current drive and directory in upper
case on the next line, with a ">" at the end:

c:\> prompt $d $t$_$P$g
Fri Dec 3, 1993 10:29:19
C:\>

Under DOS, you can include the PROMPT command in your
AUTOEXEC.BAT file to set the prompt whenever your
system is rebooted. The 4OS2 prompt can be set in
CONFIG.SYS (see below), and the prompt for any command
processor can be set in 4START (see page 82), or in
any batch file that runs when the command processor
starts.

4DOS The default prompt is $n$g (drive name plus ">") on
drives A and B, and $p$g (current drive and directory
plus ">") on all other drives. If you use 4DOS under
OS/2, the SET PROMPT statement in the OS/2 CONFIG.SYS
file (see next paragraph) will override the default
4DOS prompt. You must delete this statement if you
want to use the default prompt.

4OS2 The 4OS2 default prompt is [$n] (drive name in square
brackets) on floppy drives, and [$p] (current drive
and directory in square brackets) on all other drives.
When OS/2 is installed, it inserts a SET PROMPT
statement in CONFIG.SYS to set the prompt to $i[$p].
This prompt will override the 4OS2 defaults. The $i
adds a header line to the default prompt to remind you
of certain OS/2 keystrokes. You must delete this
statement if you want to use the default prompt.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 282

PROMPT
-------------------------------------------------------------------

4NT The 4DOS/NT default prompt is [$n] (drive name in
square brackets) on floppy drives, and [$p] (current
drive and directory in square brackets) on all other
drives.

If you enter PROMPT with no arguments, the prompt will
be reset to its default value. The PROMPT command
sets the environment variable PROMPT, so to view the
current prompt setting use the command:

c:\> set prompt

(If the prompt is not set at all, the PROMPT
environment variable will not be used, in which case
the SET command above will give a "Not in environment"
error.)

## Along with literal text, special characters, and ANSI
sequences (under DOS and OS/2), you can include the
text of any environment variable, internal variable,
or variable function (see pages 97 and 105) in a
prompt. For example, if you want to include the
amount of free memory in the command prompt, plus the
current drive and directory, you could use this
command:

c:\> prompt (%%@dosmem[K]K) $p$g
(601K) c:\data>

Notice that the @DOSMEM function is shown with two
leading percent signs [%]. If you used only one
percent sign, the @DOSMEM function would be expanded
once when the PROMPT command was executed, instead of
every time the prompt is displayed. As a result, the
amount of memory would never change from the value it
had when you entered the PROMPT command. You can also
use back-quotes to delay expanding the variable
function until the prompt is displayed:

c:\> prompt `(%@dosmem[K]K) $p$g`

4DOS, ## If you have an ANSI-compatible driver installed
4OS2 under 4DOS, or are running 4OS2, you can include ANSI
escape sequences in the PROMPT text. See your online
help for complete details on ANSI. This example uses
ANSI sequences to set a prompt that displays the shell
level, date, time and path in color on the top line of
the screen (enter the command as one line):


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 283

PROMPT
-------------------------------------------------------------------

c:\> prompt $e[s$e[1;1f$e[41;1;37m$e[K[$z] $d
Time: $t$h$h$h Path: $p$e[u$e[0;32m$n$g

4NT You cannot use ANSI escape sequences in your prompt in
4DOS/NT, because Windows NT does not provide ANSI
support.

## A few older batch files use the PROMPT command to
transmit ANSI.SYS control sequences to the screen (for
example, to redefine function keys). This technique
will not work with 4DOS and 4OS2, because they don't
display a prompt within batch files; hence, the
characters in the PROMPT string are never sent to
ANSI.SYS. To send ANSI sequences in 4DOS and 4OS2,
use the ECHO command, substituting an escape character
followed by an e for $e in the PROMPT string (see page
71 for more information on the escape character).

## You may find it helpful to define a different prompt
in secondary shells, perhaps including $z in the
prompt to display the shell level. To do so, place a
PROMPT command in your 4START file and use IF or IFF
statements to set the appropriate prompt for different
shells (for an example, see page 105).


























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 284

PUSHD
-------------------------------------------------------------------

PUSHD (New)

Purpose: Save the current disk drive and directory, optionally
changing to a new drive and directory.

Format: PUSHD [pathname]

pathname: The name of the new default drive and
directory.

See also: DIRS, POPD and Directory Changes on page
43.

Usage: PUSHD saves the current drive and directory on a "last
in, first out" directory stack. The POPD command
returns to the last drive and directory that was saved
by PUSHD. You can use these commands together to
change directories, perform some work, and return to
the starting drive and directory. The DIRS command
displays the contents of the directory stack.

To save the current drive and directory, without
changing directories, use the PUSHD command by itself,
with no pathname.

If a pathname is specified as part of the PUSHD
command, the current drive and directory are saved and
PUSHD changes to the specified drive and directory.
If the pathname includes a drive letter, PUSHD changes
to the specified directory on the new drive without
changing the current directory on the original drive.

This example saves the current directory and changes
to C:\WORDP\MEMOS, then returns to the original
directory:

c:\> pushd \wordp\memos
c:\wordp\memos> popd
c:\>

Directory changes made with PUSHD are recorded for
display in the directory history window (see page 43).

## The directory stack can hold up to 255 characters, or
about 10 to 20 entries (depending on the length of the
names). If you exceed this limit, the oldest entry is
removed before adding a new entry.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 285

PUSHD
-------------------------------------------------------------------

## If PUSHD can't change directly to the specified
directory, it will look for the CDPATH variable. See
page 43 for details on CDPATH.















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 286

QUIT
-------------------------------------------------------------------

QUIT (New)

Purpose: Terminate the current batch file.

Format: QUIT [value]

value: The exit code from 0 to 255 to return to the
command processor or to the previous batch file.

See also: CANCEL.

Usage: QUIT provides a simple way to exit a batch file before
reaching the end of the file. If you QUIT a batch
file called from another batch file, you will be
returned to the previous file at the line following
the original CALL.

This example batch file fragment checks to see if the
user entered "quit" and exits if true.

input Enter your choice : %%option
if "%option" == "quit" quit

QUIT only ends the current batch file. To end all
batch file processing, use the CANCEL command.

## If you specify a value, QUIT will set the ERRORLEVEL
or exit code (see the IF command, and the %? variable
on page 99) to that value.

## You can also use QUIT to terminate an alias. If you
QUIT an alias while inside a batch file, QUIT will end
both the alias and the batch file and return you to
the command prompt or to the calling batch file.
















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 287

RD / RMDIR
-------------------------------------------------------------------

RD / RMDIR (Enhanced)

Purpose: Remove one or more subdirectories.

Format: RD [/S] pathname...
or
RMDIR [/S] pathname...

pathname: The name of a subdirectory to remove.

4NT /S(ubdirectories)

See also: MD.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65).

Usage: RD and RMDIR are synonyms. You can use either one.

RD removes directories from the directory tree. For
example, to remove the subdirectory MEMOS from the
subdirectory WP, you can use this command:

c:\> rd \wp\memos

Before using RD, you must delete all files and
subdirectories (and their files) in the pathname you
want to remove. Remember to remove hidden and read-
only files as well as normal files (you can use DEL /Z
to delete hidden and read-only files).

You can use wildcards in the pathname.

## You cannot remove the root directory, the current
directory (.), any directory above the current
directory in the directory tree, or any directory in
use by another process in a multitasking system.

Options: ! /S(ubdirectories): This option is included only for
## compatibility with Windows NT's CMD.EXE, and should be
4NT used with EXTREME CAUTION! It deletes all files
(including hidden and system files) in the named
directory and all of its subdirectories, then removes
all empty subdirectories. This option does not prompt
for permission before deleting files and
subdirectories, and can potentially erase all files on
a drive with a single command.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 288

REBOOT
-------------------------------------------------------------------

REBOOT (New)

Purpose: Do a warm or cold system reboot.

Format: REBOOT [/C /S /V]

/C(old reboot) /V(erify)
/S(hutdown)

## Usage: REBOOT will completely restart your computer. It
normally performs a warm reboot, which is comparable
to pressing Ctrl-Alt-Delete under DOS or OS/2, or to a
shutdown and restart under Windows NT. Under DOS,
REBOOT can also perform a cold reboot, which is
comparable to turning the power off and back on or
pressing the reset button. A reboot is necessary to
activate any changes to your CONFIG.SYS file in DOS
and OS/2, and may also be used if you wish to restart
DOS with an altered 4START or AUTOEXEC.BAT file.

The following example prompts you to verify the
reboot, then does a warm boot:

c:\> reboot /v

REBOOT defaults to performing a warm boot, with no
prompting.

REBOOT flushes the disk buffers, resets the drives,
and waits one second before rebooting, to allow disk
caching programs to finish writing any cached data.
4OS2 and 4DOS/NT issue the proper commands to shut
down the operating system before rebooting.

4DOS ! Under DOS, some system BIOSes, memory managers,
multitaskers, or memory-resident programs (TSRs) may
intercept attempts to reboot your system and defeat
them entirely, convert a cold boot request to a warm
boot or vice versa, or in very rare cases, hang the
system - requiring a reboot! As a result you may need
to experiment with which reboot options work best for
your system hardware and software configuration, and
under rare circumstances REBOOT may not be usable on
your system.

4OS2 ! ## Under OS/2, REBOOT must use the DOS.SYS device driver
to reboot your system. DOS.SYS is loaded via a
DEVICE= statement in your CONFIG.SYS file. If DOS.SYS
is not loaded, REBOOT will not work.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 289

REBOOT
-------------------------------------------------------------------

Options: /C(old): Do a "cold" reboot. This is similar to
turning the power off and back on, and may be
necessary to properly initialize the system.
4DOS REBOOT /C may not physically reset all hardware
devices as thoroughly as actually turning off the
power; its effect depends on the internal design of
each hardware device and on your system configuration.

4OS2, /S(hutdown): Shut down the system, but do not reboot.
4NT This option is equivalent to clicking the "Shutdown"
choice on the OS/2 2.x Workplace Shell popup menu, or
using the Shutdown choice on the Program Manager's
File menu in Windows NT.

/V(erify): Prompt for confirmation (Y or N) before
rebooting.


































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 290

REM
-------------------------------------------------------------------

REM (Compatible)

Purpose: Put a comment in a batch file.

Format: REM [comment]

comment: The text to include in the batch file.

Usage: The REM command lets you place a remark or comment in
a batch file. Batch file comments are useful for
documenting the purpose of a batch file and the
procedures you have used. For example:

rem This batch file provides a
rem menu-based system for accessing
rem word processing utilities.
rem
rem Clear the screen and get selection
cls

REM must be followed by a space or tab character and
then your comment. Comments can be up to 255
characters long in 4DOS, or 1023 characters long in
4OS2 and 4DOS/NT. 4DOS, 4OS2, and 4DOS/NT will
normally ignore everything on the line after the REM
command, including quote characters, redirection
symbols, and other commands (see below for the
exception to this rule).

If ECHO is ON, the comment is displayed. Otherwise,
it is ignored. If ECHO is ON and you don't want to
display the line, preface the REM command with an at
sign [@].

## You can use REM to create a zero-byte file if you use
a redirection symbol immediately after the REM
command. For example, to create the zero-byte file
C:\FOO:

c:\> rem>foo

(This capability is included for compatibility with
COMMAND.COM and CMD.EXE. A simpler method for
creating a zero-byte file with 4DOS, 4OS2, or 4DOS/NT
is to enter >filename as a command, with no actual
command before the [>] redirection character.)




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 291

REN / RENAME
-------------------------------------------------------------------

REN / RENAME (Enhanced)

Purpose: Rename files or subdirectories.

Format: REN [/N /P /Q /S /T] old_name... new_name
or
RENAME [/N /P /Q /S /T] old_name... new_name

old_name: Original name of the file(s) or
subdirectory.
new_name: New name to use, or new path on the same
drive.

/N(othing) /S(ubdirectory)
/P(rompt) /T(otal)
/Q(uiet)

See also: COPY and MOVE.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65).

Usage: REN and RENAME are synonyms. You may use either one.

REN lets you change the name of a file or a
subdirectory, or move one or more files to a new
subdirectory on the same drive. (If you want to move
files to a different drive, use MOVE.)

In its simplest form, you simply give REN the old_name
of an existing file or subdirectory and then a
new_name. The new_name must not already exist - you
can't give two files the same name (unless they are in
different directories). The first example renames the
file MEMO.TXT to MEM.TXT. The second example changes
the name of the \WORD directory to \WP:

c:\> rename memo.txt mem.txt
c:\> rename \word \wp

You can also use REN to rename a group of files that
you specify with wildcards, as multiple files, or in
an include list. When you do, the new_name must use
one or more wildcards to show what part of each
filename to change. Both of the next two examples
change the extensions of multiple files to .SAV:

c:\> ren config.sys autoexec.bat 4start.btm *.sav
c:\> ren *.txt *.sav

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 292

REN / RENAME
-------------------------------------------------------------------

REN can move files to a different subdirectory on the
same drive. When it is used for this purpose, REN
requires one or more filenames for the old_name and a
directory name for the new_name:

c:\> ren memo.txt \wp\memos\
c:\> ren oct.dat nov.dat \data\save\

The final backslash in the last two examples is
optional. If you use it, you force REN to recognize
the last argument as the name of a directory, not a
file. The advantage of this approach is that if you
accidentally mistype the directory name, REN will
report an error instead of renaming your files in a
way that you didn't intend.

Finally, REN can move files to a new directory and
change their name at the same time if you specify both
a path and file name for new_name. In this example,
the files are renamed with an extension of .SAV as
they are moved to a new directory:

c:\> ren *.dat \data\save\*.sav

When new_name refers to a file or files (rather than a
directory), the file(s) must not already exist. Also,
you cannot rename a subdirectory to a new location on
the directory tree.

## REN does not change a file's attributes. The new_name
file(s) will have the same attributes as old_name.

Options: /N(othing): Do everything except actually rename the
file(s). This option is useful for testing what a REN
command will actually do.

/P(rompt): Prompt the user to confirm each rename
operation. Your options at the prompt are explained
in detail on page 48.

/Q(uiet): Don't display filenames or the number of
files renamed. This option is most often used in
batch files. See also /T.

/S(ubdirectory): Normally, you can rename a
subdirectory only if you do not use any wildcards in
the new_name. This prevents subdirectories from being
renamed inadvertently when a group of files is being


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 293

REN / RENAME
-------------------------------------------------------------------

renamed with wildcards. /S will let you rename a
subdirectory even when you use wildcards.

/T(otal): Don't display filenames as they are
renamed, but report the number of files renamed. See
also /Q.












































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 294

RETURN
-------------------------------------------------------------------

RETURN (New)

Purpose: Return from a GOSUB (subroutine) in a batch file.

Format: RETURN

See also: GOSUB.

Usage: 4DOS, 4OS2, and 4DOS/NT allow subroutines in batch
files.

A subroutine begins with a label (a colon followed by
a word) and ends with a RETURN command.

The subroutine is invoked with a GOSUB command from
another part of the batch file. When a RETURN command
is encountered the subroutine terminates, and
execution of the batch file continues on the line
following the original GOSUB.

The following batch file fragment calls a subroutine
which displays the files in the current directory:

echo Calling a subroutine
gosub subr1
echo Returned from the subroutine
quit

:subr1
dir /a/w
return



















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 295

SCREEN
-------------------------------------------------------------------

SCREEN (New)

Purpose: Position the cursor on the screen and optionally
display a message.

Format: SCREEN row column [text]

row: The new row location for the cursor.
column: The new column location for the cursor.
text: Optional text to display at the new cursor
location.

See also: ECHO, SCRPUT, TEXT, and VSCRPUT.

Usage: SCREEN allows you to create attractive screen displays
in batch files. You use it to specify where a message
will appear on the screen. You can use SCREEN to
create menu displays, logos, etc. The following batch
file fragment displays a menu:

@echo off
cls
screen 3 10 Select a number from 1 to 4:
screen 6 20 1 - Word Processing
screen 7 20 2 - Spreadsheet
screen 8 20 3 - Telecommunications
screen 9 20 4 - Quit

SCREEN does not change the screen colors. If you have
ANSI.SYS installed and have set colors with CLS or
COLOR, those colors will be used for the display. To
display text in specific colors, use SCRPUT or
VSCRPUT. SCREEN always leaves the cursor at the end
of the displayed text.

The row and column values are zero-based, so on a
standard 25 line by 80 column display, valid rows are
0 - 24 and valid columns are 0 - 79. You can also
specify the row and column as offsets from the current
cursor position. Begin the value with a plus sign [+]
to move the cursor down the specified number of rows
or to the right the specified number of columns, or
with a minus sign [-] to move the cursor up or to the
left. This example prints a string 3 lines above the
current position, in absolute column 10:

screen -3 10 Hello, World!



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 296

SCREEN
-------------------------------------------------------------------

SCREEN checks for a valid row and column, and displays
a "Usage" error message if either value is out of
range.















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 297

SCRPUT
-------------------------------------------------------------------

SCRPUT (New)

Purpose: Position text on the screen and display it in color.

Format: SCRPUT row col [BRIght] [BLInk] fg ON [BRIght] bg text

row: Starting row
col: Starting column
fg: Foreground character color
bg: Background character color
text: The text to display

See also: CLS, ECHO, SCREEN, TEXT, and VSCRPUT.

Usage: SCRPUT allows you to create attractive screen displays
in batch files. You use it to specify where a message
will appear on the screen and what colors will be used
to display the message text. You can use SCRPUT to
create menu displays, logos, etc.

SCRPUT works like SCREEN, but allows you to specify
the display colors. It writes directly to the screen
and does not require ANSI support. It always leaves
the cursor in its current position. See page 26 for
details about colors and color names, and notes on the
use of bright background colors.

The row and column are zero-based, so on a standard 25
line by 80 column display, valid rows are 0 - 24 and
valid columns are 0 - 79. You can also specify the
row and column as offsets from the current cursor
position. Begin the value with a plus sign [+] to
move down the specified number of rows or to the right
the specified number of columns, or with a minus sign
[-] to move up or to the left.

The following batch file fragment displays a menu in
color:

cls white on blue
scrput 3 10 bri whi on blu Select an option:
scrput 6 20 bri red on blu 1 - Word Processing
scrput 7 20 bri yel on blu 2 - Spreadsheet
scrput 8 20 bri gre on blu 3 - Communications
scrput 9 20 bri mag on blu 4 - Quit

4DOS## If you have an unusual display adapter which does not
support the direct video output used by SCRPUT, see
the OutputBIOS directive on page 143.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 298

SELECT
-------------------------------------------------------------------

SELECT (New)

Purpose: Interactively select files for a command.

Format: SELECT [/A[:][-]rhsda /C[HP] /D /E /I"text"
/O[:][-]acdeginrsu /Z] [command] ...
(files...)...

command: The command to execute with the selected
files.
files: The files from which to select. File
names may be enclosed in either
parentheses or square brackets. The
difference is explained below.

/A(ttribute select) /I (match descriptions)
/C[HP] (Compression) /O(rder)
/D(isable color coding) /Z (use FAT format)
/E (use upper case)

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65). Date,
time, or size ranges must appear immediately after the
SELECT keyword.

Usage: SELECT allows you to select files for internal and
external commands by using a full-screen "point and
shoot" display. You can have SELECT execute a command
once for each file you select, or have it create a
list of files for a command to work with. The command
can be an internal command, an alias, an external
command, or a batch file.

If you use parentheses around the files, SELECT
executes the command once for each file you have
selected. During each execution, one of the selected
files is passed to the command as an argument. If you
use square brackets around files, the SELECTed files
are combined into a single list, separated by spaces.
The command is then executed once with the entire list
presented as its command-line arguments.

SELECT uses the cursor up, cursor down, PgUp, and PgDn
keys to scroll through the file list. Use the + key
or the spacebar to select a file (or unselect a marked
file), and the - key to unselect a file. The * key
will reverse all of the current marks (excluding
subdirectories), and the / key will unmark everything.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 299

SELECT
-------------------------------------------------------------------

After marking the files, press Enter to execute the
command.

You can select a single file by moving the scroll bar
to the filename and pressing Enter without marking any
other files.

To skip the files listed in the current display and go
on to the next file specification inside the
parentheses or brackets (if any), press the Esc key.
To cancel the current SELECT command entirely, press
Ctrl-C or Ctrl-Break.

In the simplest form of SELECT, you merely specify the
command and then the list of files from which you will
make your selection(s). For example:

c:\> select copy (*.com *.exe) a:\

will let you select from among the .COM and .EXE files
on the current drive. It will then invoke the COPY
command to copy each file you select to drive A:. You
will be able to select first from a list of all .COM
files in the current directory, and then from a list
of all .EXE files.

If you want to select from a list of all the .COM and
.EXE files mixed together, create an include list
inside the parentheses by inserting a semicolon (see
page 65 for information on include lists):

c:\> select copy (*.com;*.exe) a:\

Finally, if you want the SELECT command to send a
single list of files to COPY, instead of invoking COPY
once for each file you select, put the file names in
square brackets instead of parentheses:

c:\> select copy [*.com;*.exe] a:\

If you use brackets, you have to be sure that the
resulting command (the word COPY, the list of files,
and the destination drive in this example) is no more
than 255 characters long for internal commands and no
more than 127 characters long for external commands
under 4DOS. The line length limit for 4OS2 and
4DOS/NT is 1,023 characters for both internal and
external commands. The current line length is


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 300

SELECT
-------------------------------------------------------------------

displayed by SELECT while you are marking files to
help you to conform to these limits.

The parentheses or brackets enclosing the file name(s)
can appear anywhere within the command; SELECT assumes
that the first set of parentheses or brackets it finds
is the one containing the list of files from which you
wish to make your selection.

The list of files from which you wish to select can be
further refined by using date, time, and size ranges
(see page 60). The range must be placed immediately
after the word SELECT. If the command is an internal
command that supports ranges, an independent range can
also be used in the command itself.

## If you don't specify a command, the selected
filename(s) will become the command. For example,
this command defines an alias called UTILS that
selects from the executable files in the directory
C:\UTIL, and then executes them in the order marked
(enter the alias on one line):

c:\> alias utils select
(c:\util\*.com;*.exe;*.btm;*.bat)

## If you want to use filename completion (see page 40)
to enter the filenames inside the parentheses, type a
space after the opening parenthesis. Otherwise the
command-line editor will treat the open parenthesis as
the first character of the filename.

## You can set the default colors used by SELECT with the
SelectColors and SelectStatBarColors directives in the
.INI file (see page 135). If SelectColors is not
used, the SELECT display will use the current default
colors. If SelectStatBarColors is not used, the
status bar will use the reverse of the SELECT display
colors.

You can display the filenames in color by setting the
COLORDIR environment variable or using the ColorDir
directive in your .INI file. See page 30 for details.
To disable directory color coding within SELECT, use
the /D option.

When displaying descriptions, SELECT adds a right
arrow [a] at the end of the line if the description is


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 301

SELECT
-------------------------------------------------------------------

too long to fit on the screen. This symbol will alert
you to the existence of additional description text.

## With the /I option, you can select files based on
their descriptions. SELECT will display files if
their description matches the text after the /I
switch. The search is not case sensitive. You can
use wildcards and extended wild cards as part of the
text.

## When sorting file names and extensions for the SELECT
display, 4DOS, 4OS2, and 4DOS/NT normally assume that
sequences of digits should be sorted numerically (for
example, the file DRAW2 would come before DRAW03
because 2 is numerically smaller than 03), rather than
strictly alphabetically (where DRAW2 would come second
because "2" comes after "0"). You can defeat this
behavior and force a strict alphabetic sort with the
/O:a option.

4DOS## SELECT normally writes text directly to the screen.
If you have an unusual display adapter which does not
support direct video output, see the OutputBIOS
directive on page 143.

4DOS ! ## If you receive a stack overflow error when using
SELECT in complex, nested command sequences, see the
notes under the StackSize directive on page 143.

Options: ## /A(ttribute select): Display only those files that
have the specified attribute set. Preceding the
attribute character with a minus [-] will display
files that do not have that attribute set. Attributes
can also be combined. The attributes are:

R Read-only D Subdirectory
H Hidden A Archive
S System

If no attributes are listed at all (e.g., SELECT /A
...), SELECT will display all files and subdirectories
including hidden and system files. If attributes are
combined, all the specified attributes must match for
a file to be included in the listing. For example,
/A:RHS will display only those files with all three
attributes set. See page 18 for more information on
file attributes.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 302

SELECT
-------------------------------------------------------------------

4DOS /C(ompression): Display compression ratios on
compressed drives. The compression ratio is displayed
instead of the file description. The ratio is left
blank for directories, for files with a length of 0
bytes, and for files on non-compressed drives. See
APPNOTES.DOC for a list of supported compression
systems.

Using /CH displays compression ratios like /C, but
bases the calculation on the host drive's cluster
size. This gives a more accurate picture of the space
saved through compression than is given by /C.

If /CP is used instead of /C, the compression is
displayed as a percentage instead of a ratio. If /CHP
is used instead of /CH, the host compression is
displayed as a percentage. The /CHP option must be
entered as shown; you can not use /CPH.

See the DIR /C documentation on page 200 for more
details on how compression ratios are calculated.

## /D(isable color coding): Temporarily turn off
directory color coding within SELECT.

/E (use upper case): Display filenames in the
traditional upper case format; also see SETDOS /U and
the UpperCase directive in the .INI file. /E is
ignored under 4OS2 and 4DOS/NT if the display is in
HPFS format. HPFS and NTFS file names are always
displayed in the case in which they are stored.

/I (match descriptions): Display filenames by
matching text in their descriptions. The text can
include wild cards and extended wildcards. The search
text must be enclosed in quotation marks. /I will be
ignored if /C or /O:c is also used.

/O(rder): Set the sort order for the files. The
order can be any combination of the following options:

- Reverse the sort order for the next option
a Sort names and extensions in standard ASCII
order, rather than sorting numerically when
digits are included in the name or extension
c Sort by compression ratio (the least
compressed file in the list will be
displayed first). The compression ratios
will be used as the basis of the sort and

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 303

SELECT
-------------------------------------------------------------------

will also be displayed. If /O:c is used
with /CH or /CHP, the sort will be based on
the host-drive compression ratios.
d Sort by date and time (oldest first)
e Sort by extension
g Group subdirectories together
i Sort by the file description (ignored if /C
or /O:c is also used)
n Sort by filename (this is the default)
r Reverse the sort order for all options
s Sort by size
u Unsorted

4OS2, /Z: Display HPFS and NTFS filenames in FAT format.
4NT Long names will be truncated to 12 characters. If the
name is longer than 12 characters, it will be followed
by a right arrow [a] to show that one or more
characters have been truncated.
































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 304

SET
-------------------------------------------------------------------

SET (Enhanced)

Purpose: Display, create, modify, or delete environment
variables.

Format: SET [/M /P /R filename...] [name[=][value]]

filename: The name of a file containing variable
definitions.
name: The name of the environment variable to
define or modify.
value: The new value for the variable.

/M(aster) /R(ead from file)
/P(ause)

See also: ESET and UNSET.

Usage: Every program and command inherits an environment,
which is a list of variable names, each of which is
followed by an equal sign and some text. Many
programs use entries in the environment to modify
their own actions. 4DOS, 4OS2, and 4DOS/NT use
several environment variables (see page 96). See
pages 21 and 94 for more information on the
environment.

If you simply type the SET command with no options or
arguments, it will display all the names and values
currently stored in the environment. Typically, you
will see an entry called COMSPEC, an entry called
PATH, an entry called CMDLINE, and whatever other
environment variables you and your programs have
established:

c:\> set
COMSPEC=C:\4DOS.COM
PATH=C:\;C:\DOS;C:\UTIL
CMDLINE=E:\UTIL\MAPMEM.EXE

To add a variable to the environment, type SET, a
space, the variable name, an equal sign, and the text:

c:\> set mine=c:\finance\myfiles

The variable name is converted to upper case by 4DOS
and 4OS2 (for compatibility with CMD.EXE, 4DOS/NT does
not shift variable names to upper case). The text
after the equal sign will be left just as you entered

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 305

SET
-------------------------------------------------------------------

it. If the variable already exists, its value will be
replaced with the new text that you entered.

! Normally you should not put a space on either side of
the equal sign. A space before the equal sign will
become part of the name; a space after the equal sign
will become part of the value.

! If you use SET to create a variable with the same name
as one of the 4DOS, 4OS2, or 4DOS/NT internal
variables (see page 97), you will disable the internal
variable. If you later execute a batch file or alias
that depends on that internal variable, it may not
operate correctly.

To display the contents of a single variable, type SET
plus the variable name:

c:\> set mine

You can edit environment variables with the ESET
command. To remove variables from the environment,
use UNSET, or type SET plus a variable name and an
equal sign:

c:\> set mine=

The variable name is limited to a maximum of 80
characters. Under 4DOS, the name and value together
cannot be longer than 255 characters. In 4OS2 and
4DOS/NT, the maximum length for the name and value
together is 1,023 characters.

4DOS## Unless you use /M, SET only affects the environment of
the current command processor and the programs it
executes. If you EXIT to a parent command processor,
the original environment will be unchanged.

In 4DOS, the size of the environment is specified by
the Environment and EnvFree directives in 4DOS.INI
(see page 126) or by the /E: startup switch (see the
4DOS Introduction and Installation Guide). In 4OS2
and 4DOS/NT the size of the environment is set
automatically.

Options: ## /M(aster): Display or modify the master environment
4DOS rather than the local environment. This option only
makes sense in a secondary shell.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 306

SET
-------------------------------------------------------------------

/P(ause): Wait for a key to be pressed after each
screen page before continuing the display. Your
options at the prompt are explained in detail on page
48.

## /R(ead): Read environment variables from a file.
This is much faster than loading variables from a
batch file with multiple SET commands. Each entry in
the file must fit within the command-line length limit
for your command processor: 255 bytes for 4DOS and
1,023 bytes for 4OS2 and 4DOS/NT. The file is in the
same format as the SET display, so SET /R can accept
as input a file generated by redirecting SET output.
For example, the following commands will save the
environment variables to a file, and then reload them
from that file:

set > varlist
set /r varlist

You can load variables from multiple files by listing
the filenames individually after the /R. You can add
comments to a variable file by starting the comment
line with a colon [:].

If you are creating a SET /R file by hand, and need to
create an entry that spans multiple lines in the file,
you can do so by terminating each line, except the
last, with an escape character (see page 71).
However, you cannot use this method to exceed the
command-line length limit.



















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 307

SETDOS
-------------------------------------------------------------------

SETDOS (New)

Purpose: Display or set the 4DOS, 4OS2, or 4DOS/NT
configuration.

Format: SETDOS [/A? /B? /C? /D /E? /I+|- command /L? /M? /N?
/P? /R? /S?:? /U? /V? /X[+|-]n /Y]

/A(NSI) /N(o clobber)
/B(right background) /P(arameter character)
/C(ompound) /R(ows)
/D(escriptions) /S(hape of cursor)
/E(scape character) /U(pper case)
/I(nternal commands) /V(erbose)
/L(ine) /X (expansion)
/M(ode for editing) /Y (single step)

Usage: SETDOS allows you to customize certain aspects of
4DOS, 4OS2, or 4DOS/NT to suit your personal tastes or
the configuration of your system. Each of these
options is described below.

You can display the value of all SETDOS options by
entering the SETDOS command with no parameters.

Most of the SETDOS options can be initialized when the
command processor executes the directives in the .INI
file (see page 130). The name of the corresponding
directive is listed in square brackets [ ] with each
option below; if none is listed, that option cannot be
set from the .INI file. You can also define the
SETDOS options in your AUTOEXEC.BAT, 4START, or other
startup file (see page 82), in aliases, or at the
command line.

Secondary shells automatically inherit most
configuration settings currently in effect in the
previous shell. If values have been changed by SETDOS
since 4DOS, 4OS2, or 4DOS/NT started, the new values
will be passed to the secondary shell. For details on
inheritance of SETDOS values by secondary shells and
their relationship to the .INI file, see page 123.

SETDOS /I settings are not inherited by secondary
shells. If you want to use SETDOS /I- to disable
commands in all shells, place the SETDOS command(s) in
your 4START file (see page 82), which is executed when
any shell starts.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 308

SETDOS
-------------------------------------------------------------------

Many of the options below are marked with## . If you
are a new user, skip these and read the /M, /S, and /U
options, which are more common.

Options: ## /A(NSI) [ANSI]: The ANSI option determines whether
4DOS will attempt to use ANSI escape sequences for the
CLS and COLOR
4DOS commands. 4DOS normally determines this itself, but
if you are using a non-standard ANSI driver or your
loading sequence is unusual, you may need to
explicitly inform 4DOS. /A0 allows 4DOS to determine
automatically whether an ANSI driver is installed (the
default). /A1 forces 4DOS to assume an ANSI driver
is installed. /A2 forces 4DOS to assume an ANSI
driver is not installed. See page 24 for more
information on ANSI drivers.

4OS2 The /A(NSI) option and the corresponding ANSI
directive are not available in 4OS2. ANSI support is
automatically turned on by 4OS2, which assumes that it
remains enabled.

4NT The /A(NSI) option and the corresponding ANSI
directive are not available in 4DOS/NT because Windows
NT does not provide ANSI support.

4DOS, /B(right background) [BrightBG]: The BRIGHTBG option
4OS2 determines whether 4DOS and 4OS2 configure your video
adapter for blinking text (/B0, the default) or bright
background colors (/B1). See page 26 for a detailed
discussion of this option.

## /C(ompound character) [CommandSep]: The COMPOUND
option sets the character used for separating multiple
commands on the same line. The default is the caret
[^] in 4DOS and the ampersand [&] in 4OS2 and 4DOS/NT.
You cannot use any of the redirection characters (| >
<), or the blank, tab, comma, or equal sign as the
command separator. This example changes the COMPOUND
character to a tilde [~]:

c:\> setdos /c~

If you want to share batch files or aliases between
4DOS and 4OS2 or 4DOS/NT, see page 100 for information
on the %+ variable, which retrieves the current
command separator, and page 72 for details on using
compatible command separators for all the products you
use.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 309

SETDOS
-------------------------------------------------------------------

## /D(escriptions) [Descriptions]: The DESCRIPTIONS
option controls whether file processing commands like
COPY, DEL, MOVE, and REN process file descriptions
along with the files they belong to. /D1 turns
description processing on, which is the default. /D0
turns description processing off.

## /E(scape character) [EscapeChar]: The ESCAPE option
sets the character used to suppress the normal meaning
of the following character. Any character following
the escape character will be passed unmodified to the
command. The default escape character is Ctrl-X
(ASCII 24, which appears on screen as an up-arrow [-])
in 4DOS and the caret [^] in 4OS2 and 4DOS/NT. You
cannot use any of the redirection characters (| > <)
or the blank, tab, comma, or equal sign as the escape
character. Certain characters (b, c, e, f, n, r, s,
and t) have special meanings when immediately preceded
by the escape character. See page 71 for additional
details on the escape character.

If you want to share batch files or aliases between
4DOS and 4OS2 or 4DOS/NT, see page 99 for information
on the %= variable, which retrieves the current escape
character, and page 72 for details on using compatible
escape characters for all the products you use.

## /I(nternal): The INTERNAL option allows you to
disable or enable internal commands. To disable a
command, precede the command name with a minus [-].
To re-enable a command, precede it with a plus [+].
For example, to disable the internal LIST command to
force 4DOS to use an external command:

c:\> setdos /i-list

4DOS, ## /L(ine) [LineInput]: The LINE option controls how
4OS2 4DOS or 4OS2 gets its input from the command line.
/L0 tells the command processor to use character input
(the default). /L1 tells it to use line input (like
COMMAND.COM and CMD.EXE). /L1 will disable command-
line editing, history recall, filename completion, and
the directory history window, and will reduce the 4OS2
input length limit from 1023 characters to 255
characters. It should only be used if it is needed
for compatibility with a specific program. If you
have a program that requires line input, you can use
the following line in an alias or batch file to change
the line input option just for that single program

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 310

SETDOS
-------------------------------------------------------------------

(change the command separator to an ampersand [&] for
4OS2):

setdos /L1 ^ program %& ^ setdos /L0

See APPNOTES.DOC (for 4DOS) or README.DOC (for 4OS2)
for information on programs which require this option.

/M(ode) [EditMode]: The MODE option controls the
initial line editing mode. To start in overstrike
mode at the beginning of each command line, use /M0
(the default). To start in insert mode, use /M1.

## /N(o clobber) [NoClobber]: The NOCLOBBER option
controls output redirection (see page 50). /N0 means
existing files will be overwritten by output
redirection (with >) and that appending (with >>) does
not require the file to exist already. This is the
default. /N1 means existing files may not be
overwritten by output redirection, and that when
appending the output file must exist. A /N1 setting
can be overridden with the [!] character. If you use
/N1, you may have problems with a few unusual programs
that shell out to run a command with redirection, and
expect to be able to overwrite an existing file.

## /P(arameter character) [ParameterChar]: This option
sets the character used after a percent sign to
specify all or all remaining command-line arguments in
a batch file or alias (e.g., %& or %n&; see pages 79
and 162). The default is the ampersand [&] for 4DOS
and the dollar sign [$] for 4OS2 and 4DOS/NT.

If you want to share batch files or aliases between
4DOS and 4OS2 or 4DOS/NT, see page 72 for details on
selecting compatible parameter characters for all the
products you use.

## /R(ows) [ScreenRows]: The ROWS option sets the
number of screen rows used by the video display.
Normally 4DOS, 4OS2, and 4DOS/NT detect the screen
size, but if you have a non-standard display you may
need to set it explicitly. This option does not
affect screen scrolling (that is controlled by your
video driver or, under 4DOS, the BIOS or ANSI.SYS); it
is used only for LIST, SELECT, the paged output
options (i.e., TYPE /P), and error checking in the
screen output commands.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 311

SETDOS
-------------------------------------------------------------------

/S(hape) [CursorOver, CursorIns]: The SHAPE option
sets the cursor shape. The format is /So:i where o is
the cursor size for overstrike mode, i the cursor size
for insert mode. The size is entered as a percentage
of the total character height. The default values are
10:100 (an underscore cursor for overstrike mode, and
a block cursor for insert mode). Because of the way
video BIOSes and drivers remap the cursor shape, you
may not get a smooth progression in the cursor size
from 0% - 100%. To disable the cursor, enter /S0:0.

/U(pper) [UpperCase]: The UPPER option controls the
default case (upper or lower) for filenames displayed
by internal commands like COPY and DIR. /U0 displays
file names in lower case (the default). /U1 displays
file names in the traditional upper case. The /U
setting is ignored for HPFS and NTFS filenames under
4OS2 and 4DOS/NT. HPFS and NTFS names are always
displayed in the case in which they are stored.

## /V(erbose) [BatchEcho]: The VERBOSE option controls
the default for command echoing in batch files. /V0
disables echoing of batch file commands unless ECHO is
explicitly set ON. /V1, the default setting, enables
echoing of batch file commands unless ECHO is
explicitly set OFF.

/V2 forces echoing of all batch file commands, even if
ECHO is set OFF or the line begins with an "@". This
allows you to turn echoing on for a batch file without
editing the batch file and removing the ECHO OFF
command(s) within it. /V2 is intended for debugging,
and can be set with SETDOS, but not with the BatchEcho
directive in 4DOS.INI. For more information on batch
file debugging see page 86, and /Y (below).

## /X[+|-]n (expansion and special characters): This
option enables and disables alias and environment
variable expansion, and controls whether special
characters have their usual meaning or are treated as
text. It is most often used in batch files to process
text strings which may contain special characters.
See page 88 for further details on string processing
in batch files, and page 116 for details on alias
expansion, variable expansion, and special characters.

The features enabled or disabled by /X are numbered.
All features are enabled when the command processor
starts, and you can re-enable all features at any time

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 312

SETDOS
-------------------------------------------------------------------

by using /X0. To disable a particular feature, use
/X-n, where n is the feature number from the list
below. To re-enable the feature, use /X+n. To enable
or disable multiple individual features, list their
numbers in sequence after the + or - (e.g. /X-345 to
disable features 3, 4, and 5).

The features are:

1 All alias expansion.
2 Nested alias expansion only.
3 All variable expansion (includes environment
variables, batch file parameters, and alias
parameters).
4 Nested variable expansion only.
5 Multiple commands, conditional commands, and
piping (affects the command separator, ||,
&&, |, and |&).
6 Redirection (affects < , >, >&, >&>, etc.).
7 Quoting (affects back-quotes [`] and double
quotes ["]).
8 Escape character.

If nested alias expansion is disabled, the first alias
of a command is expanded but any aliases it invokes
are not expanded. If nested variable expansion is
disabled, each variable is expanded once, but
variables containing the names of other variables are
not expanded further.

For example, to disable all features except alias
expansion while you are processing a text file
containing special characters:

setdos /x-35678
... [perform text processing here]
setdos /x0

## /Y (single step): /Y1 enables single-stepping through
a batch file. Each command is displayed on the screen
along with a Y/N/R (yes / no / remainder) prompt.
Press Y to execute the command, N to omit the command
and go on to the next, or R to execute the remainder
of the batch file (up to the next SETDOS /Y1 command).
You may also press Ctrl-C or Ctrl-Break to terminate
the batch file.

SETDOS /Y is reset to 0 each time the command
processor returns to the prompt, to avoid leaving

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 313

SETDOS
-------------------------------------------------------------------

single stepping enabled after a batch file completes.
This means that you cannot type SETDOS /Y1 at the
prompt, press Enter, then start a batch file from the
following prompt. To enable SETDOS /Y1 and run a
batch file from the prompt, place both commands on the
same line, for example:

c:\> setdos /y1 ^ mybatch

For more information on batch file debugging, see page
86, and /V (above).







































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 314

SETLOCAL
-------------------------------------------------------------------

SETLOCAL (New)

Purpose: Save a copy of the current disk drive, directory,
environment, and alias list.

Format: SETLOCAL

See also: ENDLOCAL.

Usage: SETLOCAL is used in batch files to save the default
disk drive and directory, the environment, and the
alias list to a reserved block of memory. You can
then change their values and later restore the
original values with the ENDLOCAL command.

For example, this batch file fragment saves
everything, removes all aliases so that user aliases
will not affect batch file commands, changes the disk
and directory, modifies a variable, runs a program,
and then restores the original values:

setlocal
unalias *
cdd d:\test
set path=c:\;c:\dos;c:\util
rem run some program here
endlocal

SETLOCAL and ENDLOCAL are not nestable within a batch
file. However, you can have multiple SETLOCAL /
ENDLOCAL pairs within a batch file, and nested batch
files can each have their own SETLOCAL / ENDLOCAL.
You cannot use SETLOCAL in an alias or at the command
line.

An ENDLOCAL is performed automatically at the end of a
batch file if you forget to do so. If you invoke one
batch file from another without using CALL, the first
batch file is terminated, and an automatic ENDLOCAL is
performed. The second batch file inherits the drive,
directory, aliases, and environment variables as they
were prior to any unterminated SETLOCAL.

4DOS ! Do not load memory-resident programs (TSRs) from a
batch file while SETLOCAL is in effect. If you do,
when ENDLOCAL is executed and the memory used by
SETLOCAL is released, a "hole" will be left in memory
below the TSR. This is not usually harmful, but
wastes memory.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 315

SHIFT
-------------------------------------------------------------------

SHIFT (Enhanced)

Purpose: Allows the use of more than 127 batch file parameters
in a batch file.

Format: SHIFT [n]

n: Number of positions to shift.

Usage: SHIFT is provided for compatibility with older batch
files, where it was used to access more than 10
parameters. 4DOS, 4OS2, and 4DOS/NT support 128
parameters (%0 to %127), so you may not need to use
SHIFT for batch files running exclusively under JP
Software command processors.

SHIFT moves each of the batch file parameters n
positions to the left. The default value for n is 1.
SHIFT 1 moves the parameter in %1 to position %0, the
parameter in %2 becomes %1, etc. You can reverse a
SHIFT by giving a negative value for n (i.e., after
SHIFT -1, the former %0 is restored, %0 becomes %1, %1
becomes %2, etc.).

SHIFT also affects the parameters %n& (command-line
tail; %n$ in 4OS2 and 4DOS/NT) and %# (number of
command arguments).

For example, create a batch file called TEST.BAT:

echo %1 %2 %3 %4
shift
echo %1 %2 %3 %4
shift 2
echo %1 %2 %3 %4
shift -1
echo %1 %2 %3 %4

Executing TEST.BAT produces the following results:

c:\> test one two three four five six seven

one two three four
two three four five
four five six seven
three four five six




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 316

START
-------------------------------------------------------------------

START (New)

Purpose: Start a program in another session or window.

Format: The format for START depends on which command
processor you are using (see the Options section below
for additional minor differences in valid options
under 4DOS and 4OS2):

4DOS START ["program title"] [/B[G] /C /DOS[=optfile] /F[G]
4OS2 /FS /ICON=iconfile /I /INV /K /L /LA /LH /MAX /MIN /N
/PGM progname /PM /POS=row,col,width,height /WAIT /WIN
/WIN3[=optfile] /WIN3S[=optfile]] [command]

4NT START ["program title"] [/B /C /Dpath /HIGH /I
/INV /K /L /LA /LH /LOW /MAX /MIN /NORMAL
/PGM progname /POS=row,col,width,height /REALTIME
/SIZE=rows,cols /WAIT] [command]

program title: Title to appear on title bar.
optfile: Option settings file.
iconfile: Name of icon (.ICO) file.
progname: Program name (not the session name).
path: Startup directory.
command: Command to be executed.

/B (no new console) /LOW (priority)
/B[G] (background) /MAX(imized)
/C(lose when done) /MIN(imized)
/D(irectory) /N(o CMD.EXE)
/DOS (DOS session) /NORMAL (priority)
/F[G] (foreground) /PGM (program name)
/FS (full screen) /PM (PM application)
/HIGH (priority) /POS(ition of window)
/I(nherit environment) /REALTIME (priority)
/ICON (name .ICO file) /SIZE (of screen buffer)
/INV(isible) /WAIT (for session to finish)
/K(eep when done) /WIN(dowed session)
/L(ocal lists) /WIN3 (Windows enhanced)
/LA (local aliases) /WIN3S (Windows standard)
/LH (local history list)

See also: DETACH.

Usage: START is used to begin a new OS/2 session or Windows
NT window and, optionally, to run a program in that
session or window. If you use START with no
parameters, it will begin a new session or window. If


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 317

START
-------------------------------------------------------------------

you add a command, START will begin a new session or
window and execute that command.

The program title, if it is included, will appear on
the title bar, on the Presentation Manager task list
(OS/2 version 1.x) or window list (OS/2 version 2.x),
or on the task list and Alt-Tab displays (Windows NT).
The program title must be enclosed in quotation marks
and cannot exceed 60 characters in 4OS2 and 4DOS, or
127 characters in 4DOS/NT. If the program title is
omitted, the program name will be used as the title.

You can use START if you are running 4OS2, 4DOS/NT, or
4DOS in an OS/2 2.1 or later DOS session. START will
not work when running 4DOS under DOS, or DOS plus
Windows.

Although the START command has the same purpose in
4DOS, 4OS2, and 4DOS/NT, there are several subtle
differences between platforms. The 4DOS and 4OS2
versions of START are similar because both rely on the
services of the OS/2 operating system. The 4DOS/NT
version of START has different options available,
partly to maintain compatibility with the START
command in the Windows NT version of CMD.EXE, and
partly because of the features of and limitations
imposed by Windows NT.

START offers a large number of switches to control the
session you start. In most cases you need only a few
switches to accomplish what you want. The list below
summarizes the most commonly used START options, and
how you can use them to control the way a session is
started:

/MAX, /MIN, and /POS allow you to start a
character-mode windowed session in a maximized
window, a minimized window, or a window with a
specified position and size. The default is to
let the operating environment choose the position
and size of the window.

/C allows you to close the session when the
command is finished (the default for DOS, OS/2
Presentation Manager, and Windows NT graphical
sessions); /K allows you to keep the session open
and go to a prompt (the default for OS/2 and
Windows NT character mode sessions).


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 318

START
-------------------------------------------------------------------

4OS2, /BG and /FG allow you to start the session in the
4DOS background (does not respond to keystrokes until
selected) or foreground (responds to keystrokes
until deselected). /FG is the default if /DOS,
/FS, /WIN, or /PM is used; otherwise, /BG is the
default.

4OS2, /FS and /WIN control whether a character-mode
4DOS session is started in full-screen or windowed
mode. The default is to start a session of the
same type as the current session, if the
application can be run in such a session.

4OS2, Under 4OS2 and 4DOS/NT, START determines the
4NT application type automatically and starts the session
in the appropriate mode: OS/2, Windows, DOS, full-
screen, windowed, or Presentation Manager for OS/2;
DOS, 16-bit Windows, 32-bit Windows, 32-bit Windows NT
(both graphical and character mode), 16-bit OS/2 1.x
character mode, or POSIX for Windows NT.

START gives you some flexibility in determining the
session mode. For example, if the command is the name
of a batch file (either a .BTM or .CMD file), you can
use the /FS or /WIN options to run the batch file as
part of a new 4OS2 session in either full-screen or
windowed mode.

However, you cannot start a session in a mode that is
inappropriate for the application type. A DOS
application cannot be run as part of a Presentation
Manager session, for example, even if you use the /PM
switch. Invalid or conflicting options will be
ignored. 4OS2 and 4DOS/NT will always attempt to run
the command in the appropriate type of session.

4DOS The 4DOS START command is unable to determine the
application type. If you don't specify the type on
the command line, 4DOS will start a new OS/2 session
to run it.

4OS2## If the program is a DOS application or .BAT file, 4OS2
will return an error message in OS/2 version 1.x. In
OS/2 version 2.x, 4OS2 will start a new DOS session to
run the program or batch file. The DOS session will
close itself automatically as soon as the program or
batch file ends, unless /K is used. If you want the
session to wait for a keystroke before it closes
itself, you can use the syntax:

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 319

START
-------------------------------------------------------------------

[c:\] start /DOS command ^^ pause

(Because the caret [^] is the default 4OS2 escape
character, two carets must be used in order to pass
one on to 4DOS as a command separator.)

4OS2, If you want to start a DOS command-line session in
4DOS OS/2 version 2.x, you can use the command:

[c:\] start /DOS

4OS2 ! ## Under OS/2, you can specify settings for DOS and
4DOS Windows sessions by using a settings options file, and
loading it with the /DOS=, /WIN3=, or /WIN3S= option.
This allows you to start DOS and Windows sessions with
specific settings without creating a desktop object
and modifying the settings manually. Before using
this capability you should read the description of it
under /DOS= (below) very carefully, since errors in
the settings file can occasionally hang your system.

Options: Unlike most commands, the options below are not in
strictly alphabetical order. Instead, they are
divided first by product, then alphabetically.

The following options are available in 4OS2, 4DOS/NT,
and 4DOS:

/C(lose): The session or window is closed when
the application ends.

/INV(isible): Start the session or window as
invisible. No icon will appear and the session
will only be accessible through the Task Manager
or Window List.

/K(eep session or window at end): The session or
window continues after the application program
ends. Use the EXIT command to end the session.

/L(ocal lists): Start the command processor with
local alias and history lists. Under 4OS2 or
4DOS/NT, this option combines the effects of /LA
and /LH (below).

/LA (Local Alias list): Start the command
processor with a local alias list. See page 163
for information on local and global aliases.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 320

START
-------------------------------------------------------------------

/LH (Local History list): Start the command
processor with a local history list. See page 38
for information on local and global history
lists.

/MAX(imized): Start the session or window
maximized.

/MIN(imized): Start the session or window
minimized.

/PGM (program name): The string following this
option is the program name. The first quoted
string on the line will be used as the session
and task list title, and not as the program name.

/POS(ition): Start the window at the specified
screen position. The syntax is /POS=row, col,
width, height where the values are specified in
pixels or pels. Under 4DOS and 4OS2, row and col
refer to the position of the bottom left corner
of the window relative to the bottom left corner
of the screen. Under 4DOS/NT, row and col refer
to the position of the top left corner of the
window relative to the top left corner of the
screen.

4OS2, The following options are available in 4OS2 and 4DOS,
4DOS but not in 4DOS/NT:

/BG (BackGround session): The session is started
as a background session. /BG may be abbreviated
to /B.

/DOS[=filename] (DOS session): Start a DOS
session under OS/2 version 2.x. This option is
not available in OS/2 version 1.x, which doesn't
allow multiple DOS sessions.

If you include the =filename, OS/2 will load DOS
settings from the specified file. This option is
available only in the 32-bit version of 4OS2, and
in 4DOS.

! Starting a session with specific DOS settings is
an undocumented feature which was implemented
within OS/2 with little error checking. It is

included in START because it substantially eases
a complex task, but you must experiment carefully

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 321

START
-------------------------------------------------------------------

to ensure that the settings you select will work
properly on the systems on which you plan to use
them. Incorrect settings may be ignored, but
they may also hang your session or stop the
entire system. Be sure your experiments are not
conducted while critical tasks are in process.

Each line in the file must have a name, an equal
sign [=], and a value. The names are those shown
in OS/2's DOS Settings dialog box. Do not use
spaces on either side of the equal sign.

The names in the DOS Settings dialog box will
vary depending on the device drivers and other
settings in your CONFIG.SYS file, though many are
available on all systems. You must ensure that
the names you use are valid for the systems on
which you use them. For example, if you replace
IBM's COM.SYS and VCOM.SYS with different
communications drivers, the COM_ settings will
probably not be valid for the new drivers. If
you have a settings file which contains settings
defined by a particular driver, and use it on a
system where the corresponding driver is not
loaded, the results are undefined.

The values in your settings file must be numeric
for settings which show a numeric value under DOS
Settings (e.g., DOS_FILES=30), and must be text
strings for settings shown with a string (e.g.,
DOS_SHELL=C:\4DOS.COM C:\4DOS /P). Strings
should be entered without trailing blanks. For
values shown as multiple choice on the DOS
Settings page you must specify a numeric value,
typically "0" for Off and 1 for On (e.g.,
DOS_HIGH=1). Items with choices other than Off
and On may use different values, or may not work
at all; experimentation is usually required to
find out what works. Attempting to use strings
for choice items (e.g., DOS_HIGH=ON) will not
work, and can hang your system. This is due to
the internal operation of OS/2, and is not a
problem in 4OS2 or 4DOS.

A typical DOS settings file might look like this:

DOS_FILES=30
DOS_HIGH=1
DOS_SHELL=C:\4DOS\4DOS.COM C:\4DOS /P

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 322

START
-------------------------------------------------------------------

MOUSE_EXCLUSIVE_ACCESS=0
VIDEO_FASTPASTE=1

You can include comments in a settings file by
beginning any line with a colon [:].

/FG (ForeGround session): Start the session as
the foreground session. /FG may be abbreviated
to /F.

/FS (Full Screen): Start the session as a full-
screen session.

/ICON=filename: Use the specified icon file. If
you don't use /ICON, 4OS2 or 4DOS will look for
an .ICO file with the same file name and in the
same directory as the program file. Some
versions of OS/2 may ignore this option and use
the default icon for the session. If you
encounter this problem, check whether an update
to OS/2 has been released which addresses it.

/N: Under 4OS2, start an OS/2 program directly,
without a command processor. The command cannot
be an internal command or batch file. This is
the default for PM applications. Under 4DOS,
start a DOS program directly.

/PM (Presentation Manager): Start a program in
the PM session.

/WIN(dowed): Start the session in a window.

/WIN3[=filename] (Windows enhanced mode): Run
the program in an enhanced-mode Windows 3.x
session. The session will run seamless (on the
OS/2 desktop) if started from 4OS2, or full-
screen if started from 4DOS. (To start a Windows
application in full-screen mode from 4OS2, use
/FS rather than /WIN3). You can include an equal
sign and the name of an options file to set
options for the specific session and application
(see /DOS= above for details). The setting names
in the file should be taken from those shown in
OS/2's WIN-OS/2 Settings dialog box. Available
only in the 32-bit version of 4OS2, and in 4DOS.

/WIN3S[=filename] (Windows standard mode):
Equivalent to /WIN3, but runs the program in

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 323

START
-------------------------------------------------------------------

standard mode rather than enhanced mode.
Available only in 4OS2/32 and 4DOS.

4OS2, The following options are available in 4OS2 and
4NT 4DOS/NT, but cannot be used under 4DOS:

/I(nherit environment): Inherit the default
environment specified in CONFIG.SYS, if any,
rather than the current environment.

/WAIT: Wait for the new session or window to
finish before continuing. Cannot be used with
/WIN3 or /WIN3S.

4NT The final group of options is only available under
4DOS/NT:

/B (no new console): The program is started
without creating a new window or console.

/D(irectory): Specifies the startup directory.
Include the directory immediately after the /D,
with no intervening spaces or punctuation.

/HIGH: Start the window at high priority.


/LOW: Start the window at low priority.

/NORMAL: Start the window at normal priority.

/REALTIME: Start the window at realtime
priority.

/SIZE: Specify the screen buffer size. The full
syntax is /SIZE=rows, columns.















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 324

[4DOS] SWAPPING
-------------------------------------------------------------------

SWAPPING [4DOS] (New)

Purpose: Enable or disable 4DOS swapping, or display the
swapping state.

Format: SWAPPING [ON | OFF]

## Usage: SWAPPING temporarily disables or enables the swapping
of the transient portion of 4DOS to expanded memory,
to XMS extended memory, or to disk (see page 128).

Setting SWAPPING OFF is particularly useful for
speeding up batch files (including AUTOEXEC.BAT) when
4DOS is using disk swapping. When you are running
several small programs from a batch file, disk
swapping can sometimes cause a noticeable delay.
However, if you disable swapping, there will be about
128K less memory available for large application
programs.

The following batch file fragment disables swapping,
runs several programs, and then re-enables swapping:

swapping off
c:\util\mouse
c:\video\ansi.com
cls bright white on blue
c:\bin\cache.com
swapping on

If you enter SWAPPING with no arguments, 4DOS displays
the current swapping type (XMS, EMS, Disk, or None)
and state:

c:\> swapping
SWAPPING (XMS) is ON

Setting SWAPPING OFF does not close the disk swap file
or release any reserved EMS or XMS memory.

You may have trouble if you load memory-resident
programs (TSRs) with SWAPPING OFF and unload them with
SWAPPING ON, or vice versa. Many TSRs expect the
system to be in the same state when they unload that
it was in when they loaded, and variation from this
norm may cause the TSR to unload improperly or hang
your system.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 325

TEE
-------------------------------------------------------------------

TEE (New)

Purpose: Copy standard input to both standard output and a
file.

Format: TEE [/A] file...

file: One or more files that will receive the
"tee-d" output.

/A(ppend)

See also: Y, and the redirection options (page 50).

## Usage: TEE is normally used to "split" the output of a
program so that you can see it on the display and also
save it in a file. It can also be used to capture
intermediate output before the data is altered by
another program or command.

TEE gets its input from standard input (usually the
piped output of another command or program), and sends
out two copies: one goes to standard output, the
other to the file or files that you specify. TEE is
not likely to be useful with programs which do not use
standard output, because these programs cannot send
output through a pipe. See page 53 for more
information on pipes.

For example, to search the file DOC for any lines
containing the string "4DOS", make a copy of the
matching lines in 4.DAT, sort the lines, and write
them to the output file 4D.DAT:

c:\> find "4DOS" doc | tee 4.dat | sort > 4d.dat

If you are typing at the keyboard to produce the input
for TEE, you must enter a Ctrl-Z to terminate the
input.

4DOS When using TEE with a pipe under 4DOS, the previous
command writes its output to a temporary file. When
that command finishes, TEE begins operation and can
read the temporary file, display the output, and write
it to the file(s) named in the TEE command.





-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 326

TEE
-------------------------------------------------------------------

4OS2, When using TEE with a pipe under 4OS2 or 4DOS/NT, the
4NT programs on the two ends of the pipe run
simultaneously, not sequentially as in 4DOS. See page
54 for more information.

Option: /A(ppend): Append the output to the file(s) rather
than overwriting them.











































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 327

TEXT
-------------------------------------------------------------------

TEXT (New)

Purpose: Display a block of text in a batch file.

Format: TEXT
.
.
.
ENDTEXT

See also: ECHO, SCREEN, SCRPUT, and VSCRPUT.

Usage: TEXT can only be used in batch files.

The TEXT command is useful for displaying menus or
multi-line messages. TEXT will display all subsequent
lines in the batch file until terminated by ENDTEXT.
Both TEXT and ENDTEXT must be entered as the only
command on the line.

To redirect the entire block of text, use redirection
on the TEXT command itself, but not on the actual text
lines or the ENDTEXT line. No environment variable
expansion or other processing is performed on the
lines between TEXT and ENDTEXT; they are displayed
exactly as they are stored in the batch file.

4DOS, If you are running 4OS2, or 4DOS with an ANSI driver
4OS2 loaded, you can change screen colors by inserting ANSI
escape sequences anywhere in the text block. This
will not work in 4DOS/NT, because Windows NT does not
provide ANSI support. You can also use a CLS or COLOR
command in 4DOS, 4OS2, or 4DOS/NT to set the screen
color before executing the TEXT command.

The following batch file fragment displays a simple
menu:

@echo off
cls
screen 2 0
text
Enter one of the following:
1 - Spreadsheet
2 - Word Processing
3 - DOS Utilities
Enter your selection :
endtext


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 328

TIME
-------------------------------------------------------------------

TIME (Compatible)

Purpose: Display or set the current system time.

Format: TIME [hh[:mm[:ss]]] [AM | PM]

hh: The hour (0 - 23).
mm: The minute (0 - 59).
ss: The second (0 - 59).

See also: CHCP and DATE

Usage: If you don't enter any parameters, TIME will display
the current system time and prompt you for a new time.
Press Enter if you don't wish to change the time;
otherwise, enter the new time:

c:\> time
Wed Dec 22, 1993 9:30:10
New time (hh:mm:ss):

TIME defaults to 24-hour format, but you can
optionally enter the time in 12-hour format by
appending "a", "am", "p", or "pm" to the time you
enter.

For example, to enter the time as 9:30 am:

c:\> time 9:30 am

The operating system adds the system time and date to
the directory entry for every file you create or
modify. If you keep both the time and date accurate,
you will have a record of when you last updated each
file.















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 329

TIMER
-------------------------------------------------------------------

TIMER (New)

Purpose: TIMER is a system stopwatch.

Format: TIMER [ON] [/1 /2 /3 /S]

ON: Force the stopwatch to restart

/1 (stopwatch #1) /3 (stopwatch #3)
/2 (stopwatch #2) /S(plit)

Usage: The TIMER command turns a system stopwatch on and off.
When you first run TIMER, the stopwatch starts:

c:\> timer
Timer 1 on: 12:21:46

When you run TIMER again, the stopwatch stops and the
elapsed time is displayed:

c:\> timer
Timer 1 off: 12:21:58 Elapsed time: 0:00:12.06

There are three stopwatches available (1, 2, and 3) so
you can time multiple overlapping events. By default,
TIMER uses stopwatch #1.

TIMER is particularly useful for timing events in
batch files. For example, to time both an entire
batch file, and an intermediate section of the same
file, you could use commands like this:

rem Turn on timer 1
timer
rem Do some work here
rem Turn timer 2 on to time the next section
timer /2
rem Do some more work
echo Intermediate section completed
rem Display time taken in intermediate section
timer /2
rem Do some more work
rem Now display the total time
timer

The smallest interval TIMER can measure depends on the
operating system you are using, your hardware, and the
interaction between the two. However, it should never


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 330

TIMER
-------------------------------------------------------------------

be greater than .06 second. The largest interval is
23 hours, 59 minutes, 59.99 seconds.

Options: /1: Use timer #1 (the default).

/2: Use timer #2.

/3: Use timer #3.

/S(plit): Display a split time without stopping the
timer. To display the current elapsed time but leave
the timer running:

c:\> timer /s
Timer 1 elapsed: 0:06:40.63

ON: Start the timer regardless of its previous state
(on or off). Otherwise the TIMER command toggles the
timer state (unless /S is used).































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 331

[4DOS/NT] TITLE
-------------------------------------------------------------------

TITLE [4DOS/NT] (Compatible)

Purpose: Change the window title.

Format: TITLE "title"

title: The new window title

See also: ACTIVATE and WINDOW.

Usage: TITLE changes the text that appears in the caption bar
at the top of the 4DOS/NT window. It is included only
for compatibility with CMD.EXE. You can also change
the window title with the WINDOW command or the
ACTIVATE command.

The title text must be enclosed in double quotes. The
quotes will not appear as part of the actual title.


To change the title of the current window to "4DOS for
Windows NT":

[c:\] title "4DOS for Windows NT"



























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 332

[4DOS] TRUENAME
-------------------------------------------------------------------

TRUENAME [4DOS] (New)

Purpose: Find the full, true path and file name for a file.

Format: TRUENAME file

file: The file whose name TRUENAME will report.

See also: @TRUENAME variable function on page 114.

Usage: Default directories, as well as the JOIN and SUBST
external commands, can obscure the true name of a
file. TRUENAME "sees through" these obstacles and
reports the fully qualified name of a file.

The following example uses TRUENAME to get the true
pathname for a file:

c:\> subst d: c:\util\test
c:\> truename d:\test.exe
c:\util\test\test.exe

TRUENAME requires MS-DOS or PC-DOS 3.0 or above,
DR DOS or Novell DOS 6.0 or above, or OS/2 version 2.0
or above.

TRUENAME can handle simple drive substitutions such as
those created by JOIN, SUBST, or most network drive
mappings. However it may not be able to correctly
determine the true name if you use "nested" JOIN or
SUBST commands, or a network which does not report
true names properly.


















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 333

TYPE
-------------------------------------------------------------------

TYPE (Enhanced)

Purpose: Display the contents of the specified file(s).

Format: TYPE [/L /P] file...

file: The file or list of files that you want to
display.

/L(ine numbers) /P(ause)

See also: LIST.

File Select:Supports extended wildcards, ranges, multiple file
names, and include lists (see pages 57 - 65).

Usage: The TYPE command displays a file. It is normally only
useful for displaying ASCII text files. Executable
files (.COM and .EXE) and many data files may be
unreadable when displayed with TYPE because they
include non-alphanumeric characters.

To display the files MEMO1 and MEMO2:

c:\> type /p memo1 memo2

You can press Ctrl-S to pause TYPE's display and then
any key to continue.

You will probably find LIST to be more useful for
displaying files. However, the TYPE /L command used
with redirection (see page 50) is useful if you want
to add line numbers to a file.

Options: /L(ine numbers): Display a line number preceding each
line of text.

/P(ause): Prompt after displaying each page. Your
options at the prompt are explained in detail on page
48.










-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 334

UNALIAS
-------------------------------------------------------------------

UNALIAS (New)

Purpose: Remove aliases from the alias list.

Format: UNALIAS [/Q] alias...
or
UNALIAS *

alias: One or more aliases to remove from memory.

/Q(uiet)

See also: ALIAS and ESET.

Usage: 4DOS, 4OS2, and 4DOS/NT maintain a list of the aliases
that you have defined. The UNALIAS command will
remove aliases from that list. You can remove one or
more aliases by name, or you can delete the entire
alias list by using the command UNALIAS *.

For example, to remove the alias DDIR:

c:\> unalias ddir

To remove all the aliases:

c:\> unalias *

Options: /Q(uiet): Prevents UNALIAS from displaying an error
message if one or more of the aliases does not exist.
This option is most useful in batch files, for
removing a group of aliases when some of the aliases
may not have been defined.

















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 335

UNSET
-------------------------------------------------------------------

UNSET (New)

Purpose: Remove variables from the environment.

Format: UNSET [/M /Q] name...
or
UNSET *

name: One or more variables to remove from the
environment.

/M(aster environment) /Q(uiet)

See also: ESET and SET.

Usage: UNSET removes one or more variables from the
environment. For example, to remove the variable
CMDLINE:

c:\> unset cmdline

If you use the command UNSET *, all of the environment
variables will be deleted:

c:\> unset *

UNSET is often used in conjunction with the SETLOCAL
and ENDLOCAL commands in order to clear the
environment of variables that may cause problems for
some applications.

For more information on environment variables, see the
SET command and the general discussions on pages 21
and 94.

! Use caution when removing environment variables, and
especially when using UNSET *. Many programs will not
work properly without certain environment variables;
for example, 4DOS depends on PATH and COMSPEC, and
4OS2 uses PATH and DPATH.

Options: ## /M(aster): Remove the variable from the master
4DOS environment rather than the local environment. This
option only makes sense if used in a secondary shell.

/Q(uiet): Prevents UNSET from displaying an error
message if one or more of the variables does not
exist. This option is most useful in batch files, for


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 336

UNSET
-------------------------------------------------------------------

removing a group of variables when some of the
variables may not have been defined.
















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 337

VER
-------------------------------------------------------------------

VER (Enhanced)

Purpose: Display the current command processor and operating
system versions.

Format: VER [/R]

/R(evision level)

Usage: Version numbers consist of a one-digit major version
number, a period, and a one- or two-digit minor
version number. The VER command displays both version
numbers:

c:\> ver

4DOS 5.0 DOS 6.0

4DOS 4DOS's VER command will automatically detect OS/2 and
DR DOS or Novell DOS and display the corresponding
operating system name and version number. For
example:

c:\> ver

4DOS 5.0 OS/2 2.1

Option: /R(evision level): Display the command processor and
operating system internal revision level (if any),
plus your 4DOS, 4OS2, or 4DOS/NT serial number and
registered name.

Under 4DOS, /R also displays whether DOS is loaded
into the high memory area (HMA), is resident in ROM,
or is in normal base memory. This output is only
meaningful in MS-DOS or PC-DOS version 5.0 or above or
in an OS/2 2.x DOS session.













-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 338

VERIFY
-------------------------------------------------------------------

VERIFY (Compatible)

Purpose: Enable or disable disk write verification or display
the verification state.

Format: VERIFY [ON | OFF]

Usage: DOS and OS/2 maintain an internal verify flag. When
the flag is on, the operating system attempts to
verify each disk write by making sure that the data
written to the disk can be read back successfully into
the computer. It does not compare the data written
with the data actually placed on disk.

4NT Disk write verification cannot actually be enabled or
disabled under Windows NT. 4DOS/NT supports VERIFY as
a "do-nothing" command, for compatibility with
CMD.EXE. This avoids "unknown command" errors in
batch files which use the VERIFY command. The
additional discussion below applies only to 4DOS and
4OS2, and not to 4DOS/NT.

If used without any parameters, VERIFY will display
the state of the verify flag:

c:\> verify
VERIFY is OFF

VERIFY is off when the system boots up. Once it is
turned on with the VERIFY ON command, it stays on
until you use the VERIFY OFF command or until you
reboot.

Verification will slow your disk write operations
slightly (the effect is not usually noticeable).















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 339

VOL
-------------------------------------------------------------------

VOL (Enhanced)

Purpose: Display disk volume label(s).

Format: VOL [d:] ...

d: The drive or drives to search for labels.

Usage: Each disk may have a volume label, created when the
disk is formatted or with the external LABEL command.
Also, every floppy disk formatted with DOS version 4.0
or above, OS/2, or Windows NT has a volume serial
number.

The VOL command will display the volume label and, if
available, the volume serial number of a disk volume.
If the disk doesn't have a volume label, VOL will
report that it is "unlabeled." If you don't specify a
drive, VOL displays information about the current
drive:

c:\> vol
Volume in drive C: is MYHARDDISK

If available, the volume serial number will appear
after the drive label or name.

To display the disk labels for drives A and B:

c:\> vol a: b:
Volume in drive A: is unlabeled
Volume in drive B: is BACKUP_2


















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 340

VSCRPUT
-------------------------------------------------------------------

VSCRPUT (New)

Purpose: Display text vertically in the specified color.

Format: VSCRPUT row col [BRIght] [BLInk] fg ON [BRIght] bg
text

row: Starting row number.
col: Starting column number.
fg: Foreground text color.
bg: Background text color.
text: The text to display.

See also: SCRPUT.

Usage: VSCRPUT writes text vertically on the screen rather
than horizontally. Like the SCRPUT command, it uses
the colors you specify to write the text. VSCRPUT can
be used for simple graphs and charts generated by
batch files. It always leaves the cursor in its
current position. See page 26 for details about
colors and color names, and notes on the use of bright
background colors.

The row and column are zero-based, so on a standard 25
line by 80 column display, valid rows are 0 - 24 and
valid columns are 0 - 79. You can also specify the
row and column as offsets from the current cursor
position. Begin the value with a plus sign [+] to
move down the specified number of rows or to the right
the specified number of columns before displaying
text, or with a minus sign [-] to move up or to the
left.

The following batch file fragment displays an X and Y
axis and labels them:

cls bright white on blue
drawhline 20 10 40 1 bright white on blue
drawvline 2 10 19 1 bright white on blue
scrput 21 20 bright red on blue X axis
vscrput 8 9 bright red on blue Y axis

VSCRPUT checks for a valid row and column, and
displays a "Usage" error message if either value is
out of range.

4DOS## VSCRPUT normally writes text directly to the screen.
If you have an unusual display adapter which does not

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 341

VSCRPUT
-------------------------------------------------------------------

support direct video output, see the OutputBIOS
directive on page 143.
















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 342

[4OS2, 4DOS/NT] WINDOW
-------------------------------------------------------------------

WINDOW [4OS2, 4DOS/NT] (New)

Purpose: Minimize or maximize the current window, restore the
default window size, or change the window title.

Format: WINDOW [MIN | MAX | RESTORE]
[/POS=row,col,width, height] ["title"]

title: A new title for the window.

/POS(ition)

See also: ACTIVATE and TITLE.

Usage: WINDOW is used to control the appearance and title of
the current window. WINDOW MIN reduces the window to
an icon, WINDOW MAX enlarges it to its maximum size,
and WINDOW RESTORE returns the window to its default
size and location on the desktop.

You can use the /POS option to set the location and
size of the window on the desktop. The row and column
values of the /POS option select the window's origin
while the width and height values determine its size.

If you specify a new title, the title text must be
enclosed in double quotes. The quotes will not appear
as part of the actual title.

Options: /POS(ition): Set the window screen position and size.
The syntax is /POS=row, col, width, height where the
values are specified in pixels or pels. Under 4OS2,
row and col refer to the position of the bottom left
corner of the window relative to the bottom left
corner of the screen. Under 4DOS/NT, row and col
refer to the position of the top left corner of the
window relative to the top left corner of the screen.













-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 343

Y
-------------------------------------------------------------------

Y (New)

Purpose: Copy standard input to standard output, and then copy
the specified file(s) to standard output.

Format: Y file ...

file: The file or list of files to send to
standard output.

See also: TEE.

## Usage: The Y command copies input from standard input
(usually the keyboard) to standard output (usually the
screen). Once the input ends, the named files are
appended to standard output.

For example, to get text from standard input, append
the files MEMO1 and MEMO2 to it, and send the output
to MEMOS:

c:\> y memo1 memo2 > memos

The Y command is most useful if you want to add
redirected data to the beginning of a file instead of
appending it to the end. For example, this command
copies the output of DIR, followed by the contents of
the file DIREND, to the file DIRALL:

c:\> dir | y dirend > dirall

If you are typing at the keyboard to produce input
text for Y, you must enter a Ctrl-Z to terminate the
input.

! When using Y with a pipe under 4OS2 or 4DOS/NT, you
must take into account that the programs on the two
ends of the pipe run simultaneously, not sequentially.
See page 54 for more information.











-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 344

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------


APPENDIX A / ERROR MESSAGES


This appendix lists error messages generated by 4DOS, 4OS2, and
4DOS/NT, and includes a recommended course of action for most
errors. If you are unable to resolve the problem, look through
your Introduction and Installation Guide for any additional
troubleshooting recommendations, then contact JP Software for
technical support (see page 7).

Error messages relating to files are generally reports of errors
returned by the operating system. You may find some of these
messages (for example, "Access denied") vague enough that they are
not always helpful. 4DOS, 4OS2, and 4DOS/NT include the file name
in file error messages, but are often unable to determine a more
accurate explanation of these errors. The message shown is the
best information available based on the error codes returned by the
operating system.

For some errors you are instructed to "restart the session or
reboot the system." This means that you should attempt to correct
the error by closing and restarting the current session under OS/2,
Windows NT, or a DOS task switcher or multitasker (including
Windows). Under DOS without a multitasker or task switcher, you
will probably have to reboot the system to correct the problem.

The following list includes all error messages, in alphabetical
order:

4DOS 4DOS internal stack overflow: You attempted to nest batch
files or commands like DO, EXCEPT, FOR, IF, IFF, GLOBAL, or
SELECT too deep, and 4DOS ran out of stack space. Restructure
your command, alias, or batch file, or use the StackSize
directive in 4DOS.INI to increase 4DOS's internal stack size.

4DOS 4DOS initialization error --: An error occurred during the
4DOS startup process. Look up the rest of the message in this
list for a more specific explanation.

4DOS 4DOS server error --: An error occurred in communication
between 4DOS's resident and transient portions. A more
specific error message follows.

4DOS 4DOS swapping failed, loading in non-swapping mode: None of
the swapping options worked, so 4DOS loaded in non-swapping
mode, which requires about 128K more memory than swapping
mode. Check your Swapping specification in 4DOS.INI, and/or
free some XMS or EMS memory or disk space.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 345

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

4DOS 4DOS unrecoverable error XX: An error occurred in the
resident portion of 4DOS. These errors will terminate
secondary shells and, and may require you to reboot the system
or restart the session if they occur during a primary shell or
if 4DOS cannot continue. The error codes are:

BI Bad function code. Contact JP Software.
DI Same as Disk swap file corrupted.
DR Same as Swap file read error.
DS Same as Swap file seek error.
EI Same as EMS mapping error.
NS No number for new shell. You have started too
many 4DOS secondary shells without properly
exiting some of them, perhaps by closing DESQview
windows rather than EXITing. Clean up any work
in process and reboot the system or restart the
session.
PT Illegal process termination. Contact JP
Software.
TS Terminated inactive shell. Contact JP Software.
XI Same as XMS move failed.

Access denied: You tried to write to or erase a read-only
file, rename a file or directory to an existing name, create a
directory that already exists, remove a read-only directory or
a directory with files or subdirectories still in it, or
access a file in use by another program in a multitasking
system.

4DOS Address table missing: Your 4DOS.COM file is invalid. If you
used an executable file compression program on 4DOS.COM, the
compression may not be compatible with 4DOS. Re-install
4DOS.COM from diskette, or download a new copy.

Alias loop: An alias refers back to itself either directly or
indirectly (i.e., a = b = a), or aliases are nested more than
16 deep. Correct your alias list.

4DOS Attempt to exit from root shell: Another program has probably
destroyed a portion of 4DOS's memory. Reboot the system or
restart the session; if the error persists, contact JP
Software.

Bad disk unit: Generally caused by a disk drive hardware
failure.

4DOS Bad environment: The DOS environment has a bad structure,
probably because a program destroyed 4DOS's master environment
space. Reboot the system or restart the session.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 346

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

Batch file missing: 4DOS, 4OS2, or 4DOS/NT can't find the
batch (.BAT or .CMD) file it was running. It was either
deleted, renamed, moved, or the disk was changed. Correct the
problem and rerun the file.

Can't copy file to itself: You cannot COPY or MOVE a file to
itself. 4DOS, 4OS2, and 4DOS/NT perform full path and
filename expansion before copying to ensure that files aren't
inadvertently destroyed.

Can't create: The command processor can't create the
specified file. The disk may be full or write protected, or
the file already exists and is read-only, or the root
directory is full.

Can't delete: The command processor can't delete the
specified file or directory. The disk is probably write
protected.

Can't get directory: The command processor can't read the
directory. The disk drive is probably not ready.

Can't make directory entry: The command processor can't
create the filename in the directory. This is usually caused
by a full root directory. Create a subdirectory and move some
of the files to it.

Can't open: The command processor can't open the specified
file. Either the file doesn't exist or the disk directory or
File Allocation Table is damaged.

Can't remove current directory: You attempted to remove the
current directory, which the operating system does not allow.
Change to the parent directory and try again.

4DOS Can't set up disk swap file: The disk swap file you specified
cannot be opened. The path or drive is invalid, the disk is
full, DOS is out of file handles, or there is a hardware
problem. Check 4DOS.INI to be sure your Swapping directive is
correct.

Command line too long: A single command exceeded 255
characters in 4DOS or 1023 characters in 4OS2 or 4DOS/NT, or
the entire command line exceeded 511 characters in 4DOS, or
2047 characters in 4OS2 or 4DOS/NT, during alias and variable
expansion. Reduce the complexity of the command or use a
batch file. Also check for an alias which refers back to
itself either directly or indirectly.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 347

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

Command only valid in batch file: You have tried to use a
batch file command, like DO or GOSUB, from the command line or
in an alias. A few commands can only be used in batch files
(see the individual commands for details).

4DOS Command tail too long, truncated: A program attempted to pass
a command in an improper format or a command longer than 126
characters to a 4DOS secondary shell. This is probably a bug
in the program from which 4DOS was loaded. Contact the author
of the program or JP Software for technical assistance.

Contents lost before copy: COPY was appending files, and
found one of the source files is the same as the target. That
source file is skipped, and appending continues with the next
file.

Data error: The operating system can't read or write properly
to the device. On a floppy drive, this error is usually
caused by a defective floppy disk, dirty disk drive heads, or
a misalignment between the heads on your drive and the drive
on which the disk was created. On a hard drive, this error
may indicate a drive that is too hot or too cold, or a
hardware problem. Retry the operation; if it fails again,
correct the hardware or diskette problem.

Directory stack empty: POPD or DIRS can't find any entries in
the directory stack.

Disk is write protected: The disk cannot be written to.
Check the disk and remove the write-protect tab or close the
write-protect window if necessary.

4DOS Disk swap file corrupted: The 4DOS disk swapping file
(4DOSSWAP.nnn or xxxxxxxx.4SW) has been moved, deleted, or
damaged by another program. Reboot the system or restart the
session.

Drive not ready -- close door: The floppy disk drive door is
open. Close the door and try again.

4DOS EMS deallocation failed: 4DOS can't deallocate EMS memory
when exiting from a secondary shell. The EMS map has been
corrupted or the memory area used by 4DOS or the EMS driver
has been destroyed by a program. Clean up any work in process
and reboot the system or restart the session.

4DOS EMS map save or restore failed: 4DOS cannot save or restore
the EMS page map. The EMS map has been corrupted, memory has
been destroyed by a program, or you have an incompatible EMS

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 348

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

driver. If this error recurs, try another swapping method,
update your EMS driver, or contact JP Software.

4DOS EMS mapping failed: 4DOS can't map EMS pages when swapping to
or from EMS. The EMS map has been corrupted or the memory
area used by the loader or the EMS driver has been destroyed
by a program. Reboot the system or restart the session.

Environment already saved: You have already saved the
environment with a previous SETLOCAL command. You cannot nest
SETLOCAL / ENDLOCAL pairs.

Error in command-line directive: You used the //iniline
option to place an .INI directive on the startup command line,
or, under 4DOS, on the SHELL= line in CONFIG.SYS, but the
directive is in error. A more specific error message follows.

Error on line [nnnn] of [filename]: There is an error in your
.INI file. The following message explains the error in more
detail. Correct the line in error and restart the command
processor for your change to take effect.

Error reading: The operating system experienced an I/O error
when reading from a device. This is usually caused by a bad
disk, a device not ready, or a hardware error.

Error writing: The operating system experienced an I/O error
when writing to a device. This is usually caused by a full
disk, a bad disk, a device not ready, or a hardware error.

Exceeded batch nesting limit: You have attempted to nest
batch files more than 10 levels deep.

4DOS Fatal error -- please reboot: 4DOS cannot continue due to the
previous error. Reboot the system or restart the session.

File Allocation Table bad: The operating system can't access
the FAT on the specified disk. This can be caused by a bad
disk, a hardware error, or an unusual software interaction.

File exists: The requested output file already exists, and
the command processor won't overwrite it.

File is empty: You attempted to LIST a file with no data (a
zero-byte file).

File not found: 4DOS, 4OS2, or 4DOS/NT couldn't find the
specified file. Check the spelling and path name.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 349

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

General failure: This is usually a hardware problem,
particularly a disk drive failure or a device not properly
connected to a serial or parallel port. Try to correct the
problem, or reboot and try again. Also see Data error above;
the problems described there can sometimes cause a general
failure rather than a data error.

4DOS I/O error in [filename], some directives may not have been
processed: An I/O error occurred while reading your 4DOS.INI
file. There may be a physical problem with data on the disk
or a sharing error on a multitasking system. Check your
4DOS.INI file and try again.

Infinite COPY or MOVE loop: You tried to COPY or MOVE a
directory to one of its own subdirectories and used the /S
switch, so the command would run forever. Correct the command
and try again.

Insufficient disk space: COPY or MOVE ran out of room on the
destination drive. Remove some files and retry the operation.

4DOS Insufficient load space: There is not enough room in 4DOS's
internal memory areas to include all of the options you
requested in 4DOS.INI. Contact JP Software for assistance.

4DOS Internal DOS error: DOS encountered an internal bug and
failed. Reboot the system.

4DOS Invalid AUTOEXEC filename: You specified an invalid path or
filename for the AUTOEXEC file with the /P: startup switch, or
with the DOS_AUTOEXEC setting in an OS/2 DOS session. The
default name will be used instead. Correct the filename, then
reboot the system or restart the session.

Invalid character value: You gave an invalid value for a
character directive in the .INI file.

Invalid choice value: You gave an invalid value for a
"choice" directive (one that accepts a choice from a list,
like "Yes" or "No") in the .INI file.

Invalid color: You gave an invalid value for a color
directive in the .INI file.

Invalid date: An invalid date was entered. Check the syntax
and reenter.

Invalid directive name: 4DOS, 4OS2, or 4DOS/NT can't
recognize the name of a directive in your .INI file.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 350

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

4DOS Invalid DOS version: You need a newer version of DOS to
execute the specified command.

Invalid drive: A bad or non-existent disk drive was
specified.

4DOS Invalid INI file path or name, file not processed: The path
or name for the initialization file on the SHELL= line in
CONFIG.SYS, or on the startup command line, is invalid.
Correct the @d:\path\inifile option to name the correct file.

Invalid key name: You tried to make an invalid key
substitution in the .INI file, or you used an invalid key name
in a keystroke alias or command. Correct the error and retry
the operation.

Invalid numeric [or character] value: You gave an invalid
value for a numeric directive in the .INI file, or for a
character directive in 4DOS.INI.

Invalid parameter: The command processor didn't recognize a
parameter. Check the syntax and spelling of the command you
entered.

Invalid path: The specified path does not exist. Check the
disk specification and/or spelling.

Invalid path or file name: You used an invalid path or
filename in a directive in the .INI file.

4DOS Invalid startup switch, ignored: You passed 4DOS an invalid
option on the SHELL= line in CONFIG.SYS or on the startup
command line for a secondary shell. Correct the switch.

4DOS Invalid Swapping option or path: The swap type or disk swap
path in the 4DOS.INI Swapping directive is invalid. 4DOS
ignores the bad swap type or path and attempts to scan the
rest of the Swapping specification for a valid option.
Multiple errors in the Swapping directive will cause this
message to repeat. Correct 4DOS.INI and reboot the system or
restart the session.

Invalid time: An invalid time was entered. Check the syntax
and reenter.

Keystroke substitution table full: 4DOS, 4OS2, or 4DOS/NT ran
out of room to store keystroke substitutions entered in the
.INI file. Reduce the number of key substitutions or contact
JP Software for assistance.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 351

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

4DOS KSTACK.COM not loaded: You attempted to execute a KEYSTACK
command without loading KSTACK.COM. See the KEYSTACK command
for more information.

Label not found: A GOTO or GOSUB referred to a non-existent
label. Check your batch file.

4DOS Memory [allocation | deallocation] error: 4DOS can't allocate
or deallocate memory while loading, or while reserving or
releasing memory for internal use. DOS memory allocation has
been corrupted, or another application has reserved memory
incorrectly. Reboot the system or restart the session.

4DOS Memory destroyed: The DOS memory control blocks have been
corrupted. Reboot the system or restart the session.

Missing ENDTEXT: A TEXT command is missing a matching
ENDTEXT. Check the batch file.

Missing GOSUB: The command processor cannot perform the
RETURN command in a batch file. You tried to do a RETURN
without a GOSUB, or your batch file has been corrupted.

Missing SETLOCAL: An ENDLOCAL was used without a matching
SETLOCAL.

No aliases defined: You tried to display aliases but no
aliases have been defined.

No closing quote: 4DOS, 4OS2, or 4DOS/NT couldn't find a
second matching back-quote [`] or double-quote ["] on the
command line.

No expression: The expression passed to the %@EVAL variable
function is empty. Correct the expression and retry the
operation.

4DOS No file handle available: This is an internal 4DOS disk
swapping error. Change to another swapping method if
possible, and contact JP Software.

No room for INI file name: 4DOS, 4OS2, or 4DOS/NT does not
have enough space to pass the name of your .INI file to
secondary shells; see String area overflow for more details.
Any [Secondary] section in 4DOS.INI will be ignored in
secondary shells until the problem is corrected and the system
or session is restarted.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 352

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

4DOS No UMBs; loading low: The LOADHIGH (or LH) command can't find
any UMBs for your program. The program is loaded into base
memory. LH and LOADHIGH only work with MS-DOS 5.0 and above,
when the DOS=UMB directive is included in CONFIG.SYS and
sufficient upper memory space is available for the program.

4DOS No upper memory available, low memory will be used for
[resident portion | master environment | global aliases |
global history]: You asked 4DOS to load the block of memory
named in the message into a UMB via the corresponding
directive in 4DOS.INI (UMBLoad, UMBEnvironment, etc.), but no
UMB was available. Check that your XMS driver is properly
installed and/or free up some UMB space in use by another
program.

4DOS Non-DOS disk: DOS can't read the disk. Either the disk is
bad, or it has been formatted by a different operating system.
Reformat it as a DOS disk. Also see Data error above; the
problems described there can sometimes cause a non-DOS disk
error rather than a data error.

Not an alias: The specified alias is not in the alias list.

Not in environment: The specified variable is not in the
environment.

4DOS Not in swapping mode: You attempted to turn swapping on or
off with the SWAPPING command, but 4DOS is loaded in non-
swapping mode.

Not ready: The specified device can't be accessed.

Not same device: This error usually appears in RENAME. You
cannot rename a file to a different disk drive.

4DOS Out of environment/alias space: 4DOS has run out of space for
environment variables or aliases. Edit the SHELL line in
CONFIG.SYS or the Environment directive in 4DOS.INI to
increase the environment size, or the Alias directive in
4DOS.INI to increase the alias list size.

Out of memory: The command processor or the operating system
had insufficient memory to execute the last command, or under
DOS, the memory control blocks have been destroyed. If this
error occurs in a 4DOS secondary shell, return to the primary
shell before running the command. Otherwise, try to free some
memory by removing memory-resident programs (under DOS), or
closing other sessions (under OS/2 and Windows NT). If the
error persists, contact JP Software for assistance.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 353

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

4DOS Under 4DOS, if the base memory (DOS RAM) figures reported by
MEMORY are unreasonable, the memory control blocks have
probably been destroyed and you must reboot the system or
restart the session. If you receive this error from DIR when
MEMORY shows sufficient memory for the directory you are
displaying, memory has probably been "fragmented," and
contains a free area larger than 8K but not large enough for
the entire directory. Use a memory mapping program like PMAP,
MAPMEM, or the DOS MEM utility to locate the fragmentation,
and experiment with your TSRs and applications to determine
and remove its cause.

Out of paper: The operating system detected an out-of-paper
condition on one of the printers (LPT1, LPT2, or LPT3). Check
your printer and add paper if necessary.

Overflow: An arithmetic overflow occurred in the %@EVAL
variable function. Check the values being passed to %@EVAL.
%@EVAL can handle 16 digits to the left of the decimal point
and 8 to the right.

Read error: The operating system encountered a disk read
error; usually caused by a bad or unformatted disk.

4DOS Region unavailable, using first available region for [resident
portion | master environment | global aliases | global
history]: You used a 4DOS.INI directive to load the block of
memory named in the message into a specific UMB region, but
that region was unavailable. Check the use of upper memory
for device drivers and other programs loaded before 4DOS,
and/or change the requested region number.

Sector not found: BIOS disk error, usually caused by a bad or
unformatted disk.

Seek error: The operating system can't seek to the proper
location on the disk. This is generally caused by a bad disk
or drive.

Sharing violation: You tried to access a file in use by
another program in a multitasking system or on a network.
Wait for the file to become available, or change your method
of operation so that another program does not have the file
open while you are trying to use it.

String area overflow: The command processor ran out of room
to store the text from string directives in the .INI file.
Reduce the complexity of the .INI file or contact JP Software
for assistance.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 354

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

4DOS Swap file [seek | read | write] failed: 4DOS encountered an
I/O error while accessing the disk swap file (4DOSSWAP.nnn or
xxxxxxx.4SW). The disk was changed, the file has been
destroyed by a program, or 4DOS's memory area has been
overwritten by another program. Reboot the system or restart
the session.

Syntax error: A command or variable function was entered in
an improper format. Check the syntax and correct the error.

4DOS Syntax error in region number or size: You specified an
invalid region number or size in the LH or LOADHIGH command.
Correct the command.

4DOS Too many DR DOS SETs in CONFIG.SYS: The SET commands in your
DR DOS or Novell DOS CONFIG.SYS file exceeded the size of
4DOS's buffer area. Reduce the length of the commands or
contact JP Software for assistance.

4DOS, Too many open files: DOS or OS/2 has run out of file handles.
4OS2 Try increasing the FILES setting in CONFIG.SYS.

4DOS Transient memory [allocation | deallocation] error: 4DOS
could not reserve or release memory for its transient portion
(probably in a SWAPPING OFF or SWAPPING ON command). The
memory control blocks have been destroyed, or a program has
fragmented memory. Reboot the system or restart the session.

Unbalanced parentheses: The number of left and right
parentheses did not match in an expression passed to the
%@EVAL variable function. Correct the expression and retry
the operation.

Unknown command: A command was entered that 4DOS, 4OS2, or
4DOS/NT didn't recognize and couldn't find in the current
search path. Check the spelling or PATH specification. You
can handle unknown commands with the UNKNOWN_CMD alias (see
page 165).

Variable loop: A nested environment variable refers to
itself, or variables are nested more than 16 deep. Correct
the error and retry the command.

4OS2, Window title not found: The ACTIVATE or WINDOW command cannot
4NT find a window with the title you specified. Correct the
command and try again.

Write error: The operating system encountered a disk write
error; usually caused by a bad or unformatted disk.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 355

APPENDIX A / ERROR MESSAGES
-------------------------------------------------------------------

4DOS XMS deallocation failed: 4DOS could not deallocate XMS memory
when exiting a secondary shell. XMS memory has been
destroyed; reboot the system or restart the session.

4DOS XMS move failed: 4DOS could not move data between base memory
and XMS memory while swapping itself. XMS memory has been
destroyed; reboot the system or restart the session.











































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 356

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------


APPENDIX B / ASCII AND KEY CODES


The tables in this section are based on U.S. English conventions.
Your system may differ if it is configured for a different country
or language. See your operating system documentation for more
information about country and language support.


ASCII

To represent the text you type, computers must translate each
letter to and from a number. The code used by all PC-
compatible computers for this translation is called ASCII
(American Standard Code for Information Interchange).
Function keys, cursor keys, and Alt keys do not generate ASCII
codes. For details on these keys and a reference table, see
Keys and Key Codes later in this Appendix.

The ASCII table on the following pages is in three parts.
Each part is described below. The first two parts cover the
128 standard ASCII characters; the third covers the 128
extended ASCII characters used on the IBM PC and compatible
computers. All the tables include a Char column showing the
visual representation of the character, a Dec column showing
the decimal numeric value of the character in the ASCII set,
and a Hex column showing the hexadecimal (base-16) value.

ASCII Control Characters have numeric values between 0 and 31,
and include non-printing characters like carriage return and
line feed. The ASCII standard does not define a visual
representation for these characters, but the IBM PC character
set does define one for most control characters as shown in
the Char column of the table. You can enter these characters
using the key combination shown in the Ctrl column, with a
caret [^] representing the Ctrl key. For example, to enter
character 4, the diamond symbol (^D), press the Ctrl and D
keys together. You can also enter control characters with the
Alt key and the numeric keypad, like extended ASCII codes (see
below). The Name column shows a two or three character "name"
given to each control character as part of the ASCII standard.

ASCII Printing Characters have numeric values between 32 and
127, and include the entire English-language character set as
well as punctuation and other special marks. You enter these
characters by pressing the corresponding keyboard key.
Character 127 has no keyboard key, but can be entered on many
systems by typing Ctrl-Backspace.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 357

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------

Extended ASCII Characters have values between 128 and 255 and
include international language characters, line-drawing
characters, and other symbols. You can enter extended ASCII
codes (or other character codes) on the keyboard by holding
down the Alt key, entering the decimal numeric value of the
key on the numeric keypad, and then releasing the Alt key.












































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 358

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------



















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 359

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------



















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 360

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------


Keys and Key Codes

When you press a single key or a key combination, software
built into your computer (the BIOS or Basic Input / Output
System) translates your keystroke into two numbers: a scan
code, representing the actual key that was pressed, and an
ASCII code, representing the ASCII value for that key. The
BIOS returns these numbers the next time a program requests
keyboard input. This section explains how key codes work; for
information on using them with 4DOS, 4OS2, and 4DOS/NT see the
.INI file (page 136), keystroke aliases (page 159), INKEY
(page 247), and KEYSTACK (page 254).

Most 4DOS, 4OS2, and 4DOS/NT commands that use the numeric key
codes listed here also use key names, which are usually more
convenient to use than the numeric codes. See page 31 for
more information on key names.

As PCs have evolved, the structure of keyboard codes has
evolved somewhat haphazardly with them, resulting in a
bewildering array of possible key codes. We'll give you a
basic explanation of how key codes work. For a more in-depth
discussion, refer to a BIOS or PC hardware reference manual.

The nuances of how your keyboard behaves depends on the
keyboard manufacturer, the computer manufacturer who provides
the built-in BIOS, and your operating system. As a result, we
can't guarantee the accuracy of the information below for
every system, but the discussion and reference table should be
accurate for most systems. Our discussion is based on the
101-key "enhanced" keyboard commonly used on 286, 386, 486,
and Pentium computers, but virtually all of it is applicable
to the 84-key keyboards on older systems. The primary
difference is that older keyboards lack a separate cursor pad
and only have 10 function keys.

All keys have a scan code, but not all have an ASCII code.
For example, function keys and cursor keys are not part of the
ASCII character set (see page 357) and have no ASCII value,
but they do have a scan code. Some keys have more than one
ASCII code. The A, for example, has ASCII code 97 (lower case
"a") if you press it by itself. If you press it along with
Shift, the ASCII code changes to 65 (upper case "A"). If you
press Ctrl and A the ASCII code changes to 1. In all these
cases, the scan code (30) is unchanged because you are
pressing the same physical key.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 361

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------

Things are different if you press Alt-A. Alt keystrokes have
no ASCII code, so the BIOS returns an ASCII code of 0, along
with the A key's scan code of 30. This allows a program to
detect all the possible variations of A, based on the
combination of ASCII code and scan code.

Some keys generate more than one scan code depending on
whether Shift, Ctrl, or Alt is pressed. This allows a program
to differentiate between two different keystrokes on the same
key, neither of which has a corresponding ASCII value. For
example, F1 has no ASCII value so it returns an ASCII code of
0, and the F1 scan code of 59. Shift-F1 also returns an ASCII
code 0; if it also returned a scan code of 59, a program
couldn't distinguish it from F1. The BIOS or operating system
translates scan codes for keys like Shift-F1 (and Ctrl-F1 and
Alt-F1) so that each variation returns a different scan code
along with an ASCII code of 0.

On the 101-key keyboard there's one more variation: non-ASCII
keys on the cursor keypad (such as up-arrow) return the same
scan code as the corresponding key on the numeric keypad, for
compatibility reasons. If they also returned an ASCII code of
0, a program couldn't tell which key was pressed. Therefore,
these keys return an ASCII code of 224 rather than 0. This
means that older programs, which only look for an ASCII 0 to
indicate a non-ASCII keystroke like up-arrow, may not detect
these cursor pad keys properly.

The number of different codes returned by any given key varies
from one (for the spacebar) to four, depending on the key, the
design of your keyboard, and the BIOS or operating system.
Some keys, like Alt, Ctrl, and Shift by themselves or in
combination with each other, plus Print Screen, SysReq, Scroll
Lock, Pause, Break, Num Lock, and Caps Lock keys, do not have
any code representations at all. The same is true of
keystrokes with more than one modifying key, like Ctrl-Shift-
A. The BIOS or operating system may perform special actions
automatically when you press these keys (for example, it
switches into Caps Lock mode when you press Caps Lock), but it
does not report the keystrokes to whatever program is running.
Programs which detect such keystrokes access the keyboard
hardware directly, a subject which is beyond the scope of this
manual.

The following table lists all of the keys on the 101-key
"enhanced" keyboard. The keys are arranged roughly in scan
code order, which is generally left to right, moving from the
top of the keyboard to the bottom.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 362

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------

Column 1 shows the key's keycap symbol or name. Columns 2 and
3 show the scan code, and the ASCII code if the key is
unshifted. Columns 4 and 5 contain the codes for the shifted
key. Columns 6 and 7 show the codes for Ctrl plus the key.
The last column contains the scan code for Alt plus the key
(Alt keystrokes have no ASCII code and always generate an
ASCII code of 0, which is not shown).

Key names prefaced by np are on the numeric keypad. Those
prefaced by cp are on the cursor keypad between the main
typing keys and the number keypad. The numeric keypad values
are valid if Num Lock is turned off. If you need to specify a
number key from the numeric keypad, use the scan code shown
for the keypad and the ASCII code shown for the corresponding
typewriter key. For example, the keypad "7" has a scan code
of 71 (the np Home scan code) and an ASCII code of 54 (the
ASCII code for "7").

The chart is blank for key combinations that are not reported
at all by the BIOS, like Ctrl-1 and Alt-PgUp.






























-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 363

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------


Scan Codes and Key Codes for Top Two Keyboard Rows



Shift Shift Ctrl Ctrl Alt
Key Cap Scan Scan ASCII ASCII ASCII Scan Scan
Symbol Code Code Code Code Code Code Code


Esc 1 1 27 27 27 1 1
1 ! 2 2 49 33 120
2 @ 3 3 50 64 0 3 121
3 # 4 4 51 35 122
4 $ 5 5 52 36 123
5 % 6 6 53 37 124
6 ^ 7 7 54 94 30 7 125
7 & 8 8 55 38 126
8 * 9 9 56 42 127
9 ( 10 10 57 40 128
0 ) 11 11 48 41 129
- _ 12 12 45 95 31 12 130
= + 13 13 61 43 131
Backspace 14 14 8 8 127 14 14

Tab 15 15 9 0 0 148 165
Q 16 16 113 81 17 16 16
W 17 17 119 87 23 17 17
E 18 18 101 69 5 18 18
R 19 19 114 82 18 19 19
T 20 20 116 84 20 20 20
Y 21 121 21 89 21 25 21
U 22 22 117 85 22 21 22
I 23 105 23 73 23 9 23
O 24 111 24 79 15 24 24
P 25 25 112 80 25 16 25
[ { 26 26 91 123 27 26 26
] } 27 93 27 125 29 27 27
Enter 28 13 28 13 10 28 28











-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 364

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------


Scan Codes and Key Codes for Bottom Two Keyboard Rows



Shift Shift Ctrl Ctrl Alt
Key Cap Scan Scan ASCII ASCII ASCII Scan Scan
Symbol Code Code Code Code Code Code Code


A 30 30 97 65 1 30 30
S 31 31 115 83 19 31 31
D 32 32 100 68 4 32 32
F 33 33 102 70 6 33 33
G 34 34 103 71 7 34 34
H 35 35 104 72 8 35 35
J 36 36 106 74 10 36 36
K 37 37 107 75 11 37 37
L 38 38 108 76 12 38 38
; : 39 39 59 58 39
' " 40 40 39 34 40

` ~ 41 41 96 126 41
\ | 43 43 92 124 28 43 43
Z 44 44 122 90 26 44 44
X 45 45 120 88 24 45 45
C 46 46 99 67 3 46 46
V 47 118 47 86 47 22 47
B 48 98 48 66 2 48 48
N 49 49 110 78 49 14 49
M 50 50 109 77 13 50 50
, < 51 44 51 60 51
. > 52 46 52 62 52
/ ? 53 47 53 63 53
Space 57 57 32 32 32 57 57















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 365

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------

Scan Codes and Key Codes for Key Pads and Function Keys



Shift Shift Ctrl Ctrl Alt
Key Cap Scan Scan ASCII ASCII ASCII Scan Scan
Symbol Code Code Code Code Code Code Code


F1 59 84 0 0 0 94 104
F2 60 85 0 0 0 95 105
F3 61 86 0 0 0 96 106
F4 62 87 0 0 0 97 107
F5 63 88 0 0 0 98 108
F6 64 89 0 0 0 99 109
F7 65 90 0 0 0 100 110
F8 66 91 0 0 0 101 111
F9 67 92 0 0 0 102 112
F10 68 93 0 0 0 103 113
F11 133 135 0 0 0 137 139
F12 134 136 0 0 0 138 140

np * 55 55 42 42 0 150 55
np Home 71 71 0 55 0 119
cp Home 71 71 224 224 224 119 151
np Up 72 72 0 56 0 141
cp Up 72 72 224 224 224 141 152
np PgUp 73 73 0 57 0 132
cp PgUp 73 73 224 224 224 132 153
np Minus 74 74 45 45 0 142 74
np Left 75 75 0 52 0 115
cp Left 75 224 75 224 224 115 155
np 5 76 0 76 53 143 0
np Right 77 0 77 54 0 116
cp Right 77 224 77 224 116 224 157
np Plus 78 78 43 43 0 144 78
np End 79 79 0 49 0 117
cp End 79 224 79 224 224 117 159
np Down 80 80 0 50 0 145
cp Down 80 80 224 224 224 145 160
np PgDn 81 81 0 51 118 0
cp PgDn 81 224 81 224 118 224 161
np Ins 82 82 0 48 146 0
cp Ins 82 82 224 224 224 146 162
np Del 83 0 83 46 0 147
cp Del 83 83 224 224 147 224 163
np / 224 47 224 47 0 149 164



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 366

APPENDIX B / ASCII AND KEY CODES
-------------------------------------------------------------------

np Enter 224 13 224 13 224 10 166

















































-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 367

GLOSSARY
-------------------------------------------------------------------


GLOSSARY


Some items in this glossary refer to features or to terms which are
discussed in more detail elsewhere in this manual. Be sure to
check the index to see if more information is available on a
particular feature or term.

4EXIT: A batch file which is executed whenever a secondary
4DOS, 4OS2, or 4DOS/NT shell ends.

4START: A batch file which is executed whenever 4DOS, 4OS2,
or 4DOS/NT is started, either as a primary shell or a
secondary shell.

Alias: A shorthand name for a command or series of commands.

Alias Parameter: A numbered variable (e.g. %2) included in an
alias definition, allowing a different value to be used in the
alias each time it is executed.

AND: A logical combination of two true or false conditions.
If both conditions are true, the result is true; if either
condition is false, the result is false.

ANSI.SYS: A device driver supplied with DOS which provides
enhanced screen display and keyboard macros, or one of the
many similar programs.

APM: A standardized system used by manufacturers of battery-
powered computers to report battery status and control power
management features.

Append: Concatenation of one file or string onto the end of
another (this use is not related to the DOS and OS/2 external
command named APPEND).

Application: A program run from the command prompt or a batch
file. Used broadly to mean any program other than the command
processor; and more narrowly to mean a program with a specific
purpose such as a spreadsheet or word processing program, as
opposed to a utility.

Archive: A file attribute indicating that the file has been
modified since the last backup (most backup programs clear
this attribute). Also sometimes refers to a single file (such
as a .ZIP file) which contains a number of other files in
compressed form.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 368

GLOSSARY
-------------------------------------------------------------------

Argument: See Parameter.

ASCII: The American Standard Code for Information
Interchange, which defines numeric values for 128 different
characters comprising the English alphabet, numbers,
punctuation, and some control characters.

ASCII File: A file containing ASCII text, as opposed to a
binary file which may contain numbers, or other information
that cannot be sensibly interpreted as text.

Attribute: A characteristic of a file which can be set or
cleared. The standard attributes are Read-Only, Hidden,
System, and Archive.

Automatic Directory Change: A 4DOS, 4OS2, and 4DOS/NT feature
which allows you to change directories by typing the directory
name and a backslash [\] at the prompt.

Base Memory: Under DOS, the portion of your computer's memory
available for use by DOS, the command processor, and
application programs. On most PCs this area consists of the
first 640K or 655,360 bytes of the computer's memory.

Base Name: The file name without a drive, path, or extension.
For example, in the file name C:\DIR1\LETTER.DAT the base name
is LETTER.

BAT File: Same as a Batch File.

Batch File: A text file containing a sequence of commands for
the command processor to execute. Batch files are used to
save command sequences so that they can be re-executed at any
time, transferred to another system, etc.

Batch File Parameter: A numbered variable (e.g. %2) used
within a batch file, allowing a different value to be used at
that spot in the file each time it is executed.

Binary File: A file containing information which does not
represent or cannot sensibly be interpreted as text. See also
ASCII File.

Block Device: A physical device for input or output which can
transmit or receive large blocks of data while the computer is
engaged in other activities. Examples include disk, tape, and
CD-ROM drives. See also Character Device.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 369

GLOSSARY
-------------------------------------------------------------------

Boot: The process of starting the computer and loading the
operating system into memory.

Boot Directory: The current directory at the time the system
is booted, usually the root directory of the boot drive.

Boot Drive: The disk drive that the system is booted from,
usually A: (the floppy disk) or C: (the hard disk).

Break: A signal sent to a program to tell it to halt what it
is doing. The Ctrl-C key or Ctrl-Break key is used to send
this signal. Some external commands abort when they receive a
break signal; others return to a previous screen or menu, or
abort the current operation.

BTM File: A special type of batch file which is loaded into
memory to speed up execution.

Buffer: An area of memory set aside for storage. For
example, disk buffers are used to save information as it is
transferred between your program and the disk, and the
keyboard buffer holds keystrokes until a program can use them.

Character Device: A physical device for input or output which
must communicate with your computer one character at a time.
Examples include the console, communications ports, and
printers. See also Block Device.

Code Page: A set of definitions which tells DOS or OS/2 how
to get and display date, time, and other information in the
format appropriate to a particular country.

Command Completion: A 4DOS, 4OS2, and 4DOS/NT feature which
allows you to recall a previous command by typing the first
few letters of the command, then an up-arrow or down-arrow.

Command Echoing: A feature which displays commands as they
are executed. Echoing can be turned on and off.

Command History: A 4DOS, 4OS2, and 4DOS/NT feature which
retains commands you have executed, so that they can be
modified and re-executed later.

Command History Window: A pop-up window used by 4DOS, 4OS2,
and 4DOS/NT to display the command history, allowing you to
choose a previous command to modify and/or execute.




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 370

GLOSSARY
-------------------------------------------------------------------

Command Processor: A program which interprets commands and
executes other programs. Sometimes also called a Command
Interpreter.


Command Recall: See Command History.

Command Tail: The portion of a command consisting of all the
arguments, i.e., everything but the command name itself.

Compound Command: See Multiple Commands.

COMSPEC: An environment variable which defines where to find
the command processor to start a secondary shell.

Conditional Commands: A 4DOS, 4OS2, and 4DOS/NT feature
allowing commands to be executed or skipped depending on the
results of a previous command. See also Exit Code.

Console: The PC keyboard and display.

Control Character: A character which is part of the ASCII
code, but does not have a normal text representation, and
which can be generated by pressing the Ctrl key along with
another key.

Country Code: See Code Page.

CPU: The Central Processing Unit which performs all logic and
calculations in a computer. In PC-compatible systems, the CPU
is on a single microprocessor chip.

CR: The ASCII character "carriage return", generated by
pressing the Enter key on the keyboard, and stored in most
ASCII files at the end of each line.

Critical Error: An error, usually related to a physical or
hardware problem with input, output, or network access, which
prevents a program from continuing.

Current Directory: The directory in which all file operations
will take place unless otherwise specified.

Date Range: A 4DOS, 4OS2, and 4DOS/NT feature which allows
you to select files based on the date and time they were last
modified.

Description: A string of characters assigned to describe a
file with the 4DOS, 4OS2, or 4DOS/NT DESCRIBE command.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 371

GLOSSARY
-------------------------------------------------------------------

Destination: In file processing commands (e.g. COPY or MOVE),
the name or directory files should have after any copying or
modification has taken place, generally the last specification
on the command line. See also Source.

Device: A physical device for input or output such as the
console, a communications port, or a printer. Sometimes
"device" is used to refer to character devices, and excludes
block devices.

Device Driver: A program which allows the operating system to
communicate with a device, and which is loaded into memory
when the system boots. Device drivers are also used to manage
memory or for other similar internal functions.

Directory: A portion of any disk, identified by a name and a
relationship to other directories in a "tree" structure, with
the tree starting at the root directory. A directory
separates files on the disk into logical groups, but does not
represent a physical division of the data on the disk.

Directory History: A 4DOS, 4OS2, and 4DOS/NT feature which
allows you to recall recently-used directory names in a window
and choose one to switch to.

Disk Swapping: A type of swapping in which the transient
portion of 4DOS is stored on disk while an application is
running.

DOS Memory: See Base Memory.

DOS Session: See Session.

Echo: See Command Echoing.

EMS Memory: Under DOS, memory which conforms to the Lotus /
Intel / Microsoft Expanded Memory Specification (LIM EMS),
which allows programs to access large amounts of memory
outside of base memory or extended memory.

EMS Swapping: A type of swapping in which the transient
portion of 4DOS is stored in EMS memory while an application
is running.

Environment: An area of memory which contains multiple
entries in the form "NAME=value". See also Master Environment
and Passed Environment.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 372

GLOSSARY
-------------------------------------------------------------------

Environment Variable: The name of a single entry in the
environment.

Errorlevel: A numeric value between 0 and 255 returned from
an external command to indicate its result (e.g., success,
failure, response to a question). See also Exit Code.

Escape Character: In some contexts, the 4DOS, 4OS2, or
4DOS/NT escape character, which is used to suppress the normal
meaning of or give special meaning to the following character.
In other cases, the specific ASCII character ESC. The meaning
must be determined from the context.

Executable Extensions: A 4DOS, 4OS2, and 4DOS/NT feature
which allows you to specify the application to be executed
when a file with a particular extension is named at the
command prompt.

Executable File: A file, usually with the extension .COM or
.EXE, which can be loaded into memory and run as a program.

Exit Code: The result code returned by an external command or
an internal command. 4DOS, 4OS2, and 4DOS/NT internal
commands return an exit code of 0 if successful, or non-zero
if unsuccessful. See also Errorlevel.

Expansion: The process 4DOS, 4OS2, and 4DOS/NT go through
when they scan a command line and substitute the appropriate
actual values for aliases, alias parameters, batch file
parameters, and environment variables. See also Parsing.

Extended ASCII Character: A character which is not part of
the standard set of 128 ASCII characters, but is used on the
PC as part of an extended set of 256 characters. These
characters include international language symbols, and box and
line drawing characters.

Extended Memory: Any memory on a 286-based (PC-AT
compatible), 386, 486, or Pentium-based computer system which
is above the 1 MB (one megabyte, or 1024*1024 bytes) of memory
that DOS can address directly. See also XMS.

Extended Parent Directory Names: A 4DOS, 4OS2, and 4DOS/NT
feature which allows you to use additional periods in a
directory name to represent directories which are successively
higher in the directory tree.




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 373

GLOSSARY
-------------------------------------------------------------------

Extended Wildcard: A 4DOS, 4OS2, and 4DOS/NT feature which
allows you to use multiple wildcard characters, extending the
traditional wildcard syntax. See also Wildcard.

Extension: The final portion of a file name, preceded by a
period. For example, in the file name C:\DIR1\LETTER.DAT the
extension is .DAT.

External Command: A program which resides in an executable
file, as opposed to an internal command which is part of the
command processor.

FAT File System: The traditional file system used by DOS to
store files on diskettes and hard disks; also supported by
OS/2 and Windows NT. Uses a File Allocation Table to keep
track of allocated and unallocated space on the disk.

File Attribute: See Attribute.

File Description: See Description.

Filename Completion: A 4DOS, 4OS2, and 4DOS/NT feature which
allows you to type part of a filename on the command line, and
have the command processor fill in the rest for you.

Free Memory: Usually, the amount of base memory (under DOS)
or total memory (under OS/2 and Windows NT) which is
unoccupied and available for applications.

Hidden: A file attribute indicating that the file should not
be displayed with a normal DIR command, and should not be made
available to programs unless they specifically request access
to hidden files.

History: See Command History.

History Window: See Command History Window and Directory
History.

HPFS or High Performance File System: A file system
distributed with OS/2 and Windows NT which allows longer file
names and provides better performance than the traditional FAT
file system.

Include List: A concise method of specifying several files or
groups of files in the same directory, for use with all 4DOS,
4OS2, and 4DOS/NT commands which take file names as arguments.



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 374

GLOSSARY
-------------------------------------------------------------------

.INI File: The 4DOS, 4OS2, or 4DOS/NT initialization file
containing directives which set the initial configuration of
the command processor.

Insert Mode: When editing text, a mode in which newly typed
characters are inserted into the line at the cursor position,
rather than overwriting existing characters on the line. See
also Overstrike Mode.

Internal Command: A command which is part of the command
processor, as opposed to an external command.

Keyboard Buffer: A buffer which holds keystrokes you have
typed that have not yet been used by the currently executing
program.

Keystroke Alias: An alias assigned to a key, so that it can
be invoked or recalled with a single keystroke.

Label: A marker in a batch file, with the format :name,
allowing GOTO and GOSUB commands to "jump" to that point in
the file. See also Volume Label.

LF: The ASCII character "line feed", not usually generated
from the keyboard, but stored in most ASCII files at the end
of each line, after the CR character.

Master Environment: The master copy of the environment
maintained by the command processor.

Memory Resident Mode: A method of installing 4DOS in which
swapping is disabled, and all of 4DOS remains permanently
resident in memory.

Modulo: The remainder after an integer division. For example
11 modulo 3 is 2, because when 11 is divided by 3 the
remainder is 2.

Multiple Commands: A 4DOS, 4OS2, and 4DOS/NT feature which
allows multiple commands to be placed on a line, separated by
a caret [^] in 4DOS, an ampersand [&] in 4OS2 and 4DOS/NT, or
another, user-defined character.

Multitasking: A capability of some software (and the related
hardware) which allows two or more programs to run apparently
simultaneously on the same computer. Multitasking software
for PC compatible systems includes programs like OS/2,
Windows, Windows NT, and DESQview.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 375

GLOSSARY
-------------------------------------------------------------------

NTFS or New Technology File System: A file system distributed
with Windows NT with characteristics similar to HPFS. See
also HPFS.

Non-Swapping Mode: See Memory Resident Mode.

Operating System: A collection of software which loads when
the computer is started, provides services to other software,
and ensures that programs don't interfere with each other
while they are running.

Option: See Switch.

OR: A logical combination of two true or false conditions.
If both conditions are false the result is false; if either
condition is true the result is true.

Overstrike Mode: When editing text, a mode in which newly
typed characters overwrite existing characters on the line,
rather than being inserted into the line at the cursor
position. See also Insert Mode.

Parameter: A piece of additional information placed after a
command or function name. For example, in the command DIR
XYZ, XYZ is a parameter. Also used to refer to an alias
parameter or batch file parameter.

Parsing: The process 4DOS, 4OS2, and 4DOS/NT perform when
they analyze the command line, perform alias and environment
variable expansion, and find the appropriate internal command
or external command to execute.

Passed Environment: A copy of the master environment created
before running an application, so that any changes made by the
application will not affect the master environment.

Path: A specification of all the directories a file resides
in. For example, the path for C:\WPFILES\MYDIR\MEMO.TXT is
C:\WPFILES\MYDIR\. Also used to refer to the environment
variable PATH, which contains a series of path specifications
used when searching for external commands and batch files.

Pipe: A method for collecting the standard output of one
program and passing it on as the standard input of the next
program to be executed, signified by a vertical bar "|" on the
command line. See also Redirection.




-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 376

GLOSSARY
-------------------------------------------------------------------

Primary Shell: The copy of the command processor which is
loaded by the operating system when the system boots or a
session opens.

RAM Disk: A pseudo "disk drive", created by software, which
appears like a normal physical disk drive to programs.
Sometimes also called a "virtual disk."

Range: See Date Range, Size Range, and Time Range.

Read-Only: A file attribute indicating that the file can be
read, but not written or deleted by the operating system or
the command processor unless special commands are used.

Reboot: The process of restarting the computer, usually by
pressing the Ctrl, Alt, and Del keys simultaneously.

Redirection: A method for collecting output from a program in
a file, and/or of providing the input for a program from a
file. See also Pipe.

Resident Portion: The small portion of 4DOS stored
permanently in memory when swapping mode is in use, as opposed
to the larger transient portion.

Root Directory: The first directory on any disk, from which
all other directories are "descended." The root directory is
referenced with a single backslash [\].

Secondary Shell: Any copy of the command processor which is
started by another program, rather than by the operating
system.

Session: A general term for the individual windows or tasks
started by a multitasking system. For example, under OS/2 you
might run an OS/2 program in one session, and a DOS program in
another.

Shell: See Command Processor. Also used to refer to a
program which gives access to DOS functions and commands
through a menu- or mouse-driven system.

Size Range: A 4DOS, 4OS2, and 4DOS/NT feature which allows
you to select files based on their size.

Source: In file processing commands (e.g. COPY or MOVE), the
original files before any copying or modification has taken
place, i.e., those specified earlier on the command line. See
also Destination.

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 377

GLOSSARY
-------------------------------------------------------------------

Stack: An area of memory used by any program to store
temporary data while the program is running; more generally,
any such storage area where the last item stored is normally
the first one removed.

Standard Error, Standard Input, and Standard Output: The
file(s) or character device(s) where a program respectively
displays error messages, obtains its normal input, and
displays its normal output. Standard error, standard input,
and standard output always refer to the console, unless
redirection is used.

Subdirectory: Any directory other than the root directory.

Swap File: A disk file created by 4DOS to store its transient
portion when disk swapping is in use.

Swapping: A 4DOS feature which removes the larger transient
portion of 4DOS from base memory while an application is
running, leaving the maximum possible amount of memory for the
application.

Switch: A parameter for an internal command or application
which specifies a particular behavior or setting. For
example, the command "DIR /P" might be referred to as "having
the /P switch set".

System: A file attribute indicating that the file belongs to
the operating system or command processor, and should not be
accessed by other programs.

Target: See Destination.

Time Range: A 4DOS, 4OS2, and 4DOS/NT feature which allows
you to select files based on the time they were last modified.

Transient Portion: The larger portion of 4DOS stored in
memory temporarily when swapping is in use, as opposed to the
smaller resident portion.

TSR: A DOS Terminate and Stay Resident program, i.e., a
program which "terminates" but remains resident in memory, to
provide features such as network support, a pop-up notepad or
telephone dialer, a disk cache, or mouse support.

UMB: An XMS Upper Memory Block, whose address is above the
end of base memory, but within the 1 megabyte of memory that
DOS can address directly.


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 378

GLOSSARY
-------------------------------------------------------------------

Variable: See Alias Parameter, Batch File Parameter, and
Environment Variable.

Virtual Disk: See RAM Disk.

Volume Label: A special, hidden file placed on any disk,
whose name constitutes a "label" for the entire disk.

White Space Character: A character used to separate arguments
on the command line. The white space characters recognized by
4DOS, 4OS2, and 4DOS/NT are the space, tab, and comma.

Wildcard: A character ("*" or "?") used in a filename to
specify the possibility that any single character ("?") or
sequence of characters ("*") can occur at that point in the
actual name. See also Extended Wildcard.

XMS Memory: A software method for accessing extended memory
under DOS. XMS memory is not additional memory, but is a
software specification only.

XMS Swapping: A type of swapping where the transient portion
of 4DOS is stored in XMS memory while an application is
running.

XOR (exclusive OR): A logical combination of two true or
false conditions. If both conditions are false or both
conditions are true the result is false; if either condition
is true and the other is false the result is true.





















-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 379

Index
-------------------------------------------------------------------

Index * (asterisk)
as file name "wildcard", 57
in alias name, 159
Conventions: Most fully in alias value, 157
capitalized terms (e.g., ECHO, to temporarily disable an
SELECT) are command names alias, 46, 85, 157
unless otherwise noted.
., see Current directory
.., see Parent directory
Special Characters
/, in command switches, 149

## advanced topic mark, 3, 33, ; (semicolon)
151 in HPFS and NTFS file
names, 17, 60
! warning mark, 3, 151 in include lists, 65

$ (dollar sign), as parameter ? as file name "wildcard", 57
character, 134, 311 ? command, 153
in batch files, 79
@ sign, see also Variable
% sign functions
and alias parameters, 162 for key codes, 32
and batch file parameters, in a keystroke alias,
78 161
and environment variables, in file names, 16
94, 95 in INKEY results, 247
in file names, 16 to define a keystroke
use with variable alias, 159
functions, 105 to override batch file
%# and %n& echo, 78, 214, 291
changing parameter to override command history
character, 134, 311 save, 36
in aliases, 162 to read a file in FOR, 224
in batch files, 79, 316
%0 to %127 ^ (caret)
in aliases, 162 as command separator, 131,
in batch files, 78, 316 309
as escape character, 132,
& (ampersand) 310
as command separator, 131,
309 || (or) in conditional
as parameter character, commands, 69
134, 311
in batch files, 79
&& (and) in conditional
commands, 69



-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 380

Index
-------------------------------------------------------------------

4
Aliases (continued)
4DOS back-quotes in, 119, 156,
and DESQview, 142 161, 166
and disk caching software, defining default command
142 options with, 157, 163
and DR DOS, 242, 257, 338 disabling, 46, 85, 157, 312
and HPFS files, 17 editing, 218
and MS-DOS 5.0 and above, examples, 74, 84, 86
257 expansion, 48, 116
and Novell DOS, see 4DOS and batch file
and DR DOS debugging, 87
and Windows, see Microsoft disabling, 312
Windows nested, 116
configuration, 120 global, 128, 163
memory usage, 130 storing in upper
resident portion, loading memory, 129
in upper memory, 130 in batch files, 84
REXX support in, 92 inheritance, in secondary
stack size, 143 shells, 143
4DOS/NT internal variables in, 163
configuration, 120 keystroke, 76, 159
EXTPROC support in, 93 and key assignments,
REXX support in, 92 137
4EXIT, 83 automatic execution of,
location of, 125 71, 76, 160
4OS2 local, 128, 163
configuration, 120 memory space for, 100, 125,
EXTPROC support in, 93 267
REXX support in, 92 multiple commands in, 156
4START, 82, 105 nested, 75, 116, 157
location of, 125 order of execution, 116
parameters, 162, 163
A expansion, 117
reading from a file, 166
Abort, Retry, Fail message, see removing, 335
Critical errors saving in a file, 161
ACTIVATE command, 154 saving temporarily, 315
Advanced Power Management sharing between 4DOS, 4OS2,
status, 100 and 4DOS/NT, 72
Advanced topic mark, see v storing in upper memory,
ALIAS command, 19, 155 129
Aliases, 74, 155 suspending execution of,
and executable extensions, 279
66 variable functions in, 115,
and QUIT, 287 163
asterisk in name, 159 And (&&) in conditional
asterisk in value, 157 commands, 69


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 381

Index
-------------------------------------------------------------------

.AND., in IF and IFF, 238, 243, Batch files (continued)
244 branching in, 232
ANSI driver, 24 calling, 173
and CLS, 179, 309 capturing output of, 87
and COLOR, 180, 309 chaining, 173
and PROMPT, 283 commands for, 80, 147
and screen colors, 136 comments in, 291
and scrolling, 311 compression, 90
and TEXT, 328 debugging, 86
detecting, 100 detecting 4DOS, 4OS2, or
escape sequences, 71, 283, 4DOS/NT from, 83
328 displaying messages in,
use by 4DOS, 131 214, 216, 296, 298, 328,
APM, see Advanced Power 341
Management echoing of commands, 78,
Appending files, 181 131, 214, 312
Archive attribute, see File environment variables in,
attributes 79
Argument quoting, 118 handling Ctrl-Break, 274
Arguments, see Parameters handling errors, 274
Arithmetic, 109 handling strings in, 88,
ASCII, 22 312
Asterisk, see * internal variables in, 79,
At sign, see @ sign 104
ATTRIB, 167 interrupting, 82
Attributes, see File attributes keyboard input in, 247, 249
AUTOEXEC.BAT, 83 labels in, 231, 232
location of, 125 modes, 77, 263
parameters for, 126 nesting, 101, 173
speeding up, 325 parameters, 78, 316
starting KSTACK.COM, 55, expansion, 117
254 samples, 82
Automatic batch files, 82 saving environment in, 315
Automatic directory changes, 44 screen display, 210, 212,
213
B sharing between 4DOS, 4OS2,
and 4DOS/NT, 72
Backspace character, 71 string processing in, 88,
Base memory, see Memory 312
Base name, see File names subroutines, 231, 295
.BAT files, 20, 77, 263 suspending execution of,
Batch files, 77 279
aliases in, 84, 85 temporary variables in, 80
and executable extensions, terminating, 174, 287
66 timing events in, 330
and redirection, 51 variable functions in, 79,
automatic, 82 115
based on command history, BATCOMP.EXE, 90
235 BEEP, 80, 131, 169

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 382

Index
-------------------------------------------------------------------

Beeps Colors
frequency of, 131 and ANSI driver, 24, 136,
length of, 131 309
BIOS output blinking text, 27
and color-coded directory bright background, 27, 135,
displays, 31 309
and DRAWBOX, 211 errors in, 27
and DRAWHLINE, 212 in directories, 30
and DRAWVLINE, 213 in history window, 133
and LIST, 262 in LIST, 135, 262
and SCRPUT, 298 in PROMPT, 283
and SELECT, 302 in SELECT, 136, 301
and VSCRPUT, 341 of border, 27
BIOS output, in 4DOS, 143 of boxes, 210
Border colors, see Colors of lines, 212, 213
Boxes, drawing, on screen, 210 of text, 298, 328, 341
BREAK, 171 of typed input, 35, 135
.BTM files, 20, 77, 263 setting defaults, 135, 179,
180
C setting, in 4START, 105
standard, 136
CALL, 80, 173 testing, 101, 102
CANCEL, 80, 173, 174, 287 Command grouping, 69, see also
Caps Lock key, 251 EXCEPT, FOR, GLOBAL, and IF
Carriage return character, 72 and redirection, 51, 70
in keystroke aliases, 160 Command history, see History
Case (upper / lower), 135, 312 list
CD, 175 Command line, 33
CDD, 177 arguments, see Parameters
CDFS file system, 111 automatic directory
CDPATH environment variable, changes, 44
42, 45, 96, 176, 177, 286 echoing of, 214, 215
Changing directories, 42, 44, editing, 34, 137, 139
175, 177, 280, 285 editing mode, 34, 132, 311
CHCP, 178 expanded, viewing, 215
CHDIR, 175 filename completion, 40
CLS, 80, 179 help, 46
.CMD files, 20, 77, 263 history, 35, see also
CMDLINE environment variable, History list
96 history window, 39
Code pages, see Country code input method, 133, 310
Cold reboot, 289 multiple commands, 45
COLOR, 80, 180 processing of, 19, 116
Color-coded directory displays, prompt, 281
30, 135, 198, 301 Command parsing, 116
and redirection, 198 Command processor, 10
COLORDIR environment variable, Command Reference Guide, 146
30, 96, 198, 301


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 383

Index
-------------------------------------------------------------------

Command separator, 45, 72, 100, COPY, 181
131, 309 and ctrl-Z end of file
disabling, 312 mark, 185
in IFF, 244 and extended attributes,
Command tail, 19, 116 184
COMMAND.COM message server, 143 Country code, 22, 101, 178, 188
Commands Critical errors, 49, 99
conditional execution of, automatic Fail response,
244 142
external, 18, 146, 276 detecting, 274
and /? help, 47 Ctrl-Break
exit codes for, 99 at file processing prompt,
format of, 148 48
help for, 46, 234 at page prompt, 48
internal, 18, 146 checking, 171, 274

disabling, 153, 310 during DELAY, 192
length of, 34, 45, 47 during INKEY, 247, 249, 279
list of, 153 during SELECT, 300
new, 148 in batch files, 82, 274
order of execution, 116 in external programs, 99
types of, 148 Ctrl-C, see Ctrl-Break
unknown, handling, 165 Ctrl-X, see Escape character
Comments Ctrl-Z end of file mark, and
in .INI file, 122 COPY, 185
in alias files, 166 CTTY, 52, 187
in batch files, 291 Current drive and directory, 16
in environment variable changing, see Changing
files, 307 directories
Compatibility between 4DOS, retrieving, 101
4OS2, and 4DOS/NT, 72 saving temporarily, 285,
Compound character, see Command 315
separator Cursor
Compressed drives, 200, 303 positioning, 296, 298, 341
COMSPEC environment variable, shape, 131, 312
96, 121, 336
Conditional commands, 68 D
disabling, 312
CONFIG.SYS, 12 Daily execution of batch file,
Configuration, of 4DOS, 4OS2, 115
and 4DOS/NT, 96, 120 DATE, 188
CONsole device, 187, see also time format, 130
Standard input, Standard Date ranges, 60
output, and Standard error Dates, formatting, 112
Coprocessor, see Numeric Day of week, 102
coprocessor Default directory, see Current
drive and directory
Default drive, see Current
drive and directory
DEL, 189

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 384

Index
-------------------------------------------------------------------

DELAY, 192 DO, 80, 206
DELDIR environment variable, and GOTO, 207
190, 271 DOS
Delete tracking, 190 commands, help for, 46, 146
Deleting files, 189 compatibility box, see OS/2
DESCRIBE, 137, 193 DOS sessions
DESCRIPT.ION, see File default command processor,
descriptions 11
Descriptions, see File memory, see Memory
descriptions DOS/V (Japan), 143
DESQview DPATH, 209
and 4DOS, 142 DRAWBOX, 80, 210
and secondary shells, 123 DRAWHLINE, 80, 212
detecting, 102, 105 DRAWVLINE, 80, 213
DETACH, 195 Drive, see Disk drives
Detecting 4DOS, 4OS2, or
4DOS/NT from a batch file, 83 E
DIR, 196
and include lists, 65 ECHO, 214
color-coded displays, 30, ANSI sequences in, 71
135, 198 at command line, 215
and CTTY, 187 in batch files, 78, 80, 86,
and redirection, 198, 291
201 default state, 131, 312
directory size limits, 199 inheritance, 173
displaying file ECHOS, 80, 216
descriptions, and Editing aliases and environment
redirection, 198, 203 variables, 218
time format, 130 ELSE and ELSEIFF, in IFF, 244
DIRCMD environment variable, 96 EMS, see Memory
Directories, see Subdirectories ENDDO, in DO, 206
Directory history window, 43 ENDIFF, in IFF, 244
Directory stack, 285 ENDLOCAL, 80, 85, 217, 315, 336
clearing, 280 ENDTEXT, 81, 328
displaying, 205 Environment, 21, 94, 305
Directory tree, 15 master, 95, 112, 219, 306,
DIREXIST test, in IF and IFF, 336
242 saving temporarily, 315
DIRS, 205, 280, 285 size of, 94, 126, 306
Disk drives, 14 displaying, 267
compressed, 200, 303 testing, 102
drive letter, 14 storing in upper memory,
space on, 108, 228 129
swapping to, 128, 325 Environment variables, 21, 94,
testing status of, 113 305
volume label, 112, 340 and INKEY, 247
write verification on, 339 and INPUT, 249
Display colors, see Colors characters in name, 94
creating, 305

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 385

Index
-------------------------------------------------------------------

Environment variables Extended ASCII, see ASCII
(continued) Extended attributes
displaying, 305 and COPY, 184
editing, 218 and MOVE, 271
expansion, 48, 117 Extended key codes, see Keys
and batch file Extended memory, see Memory
debugging, 87 Extended parent directory
disabling, 312 names, 57
nested, 94 Extension, see File names
for current directory, in External commands, see Commands
Windows NT, 97 EXTPROC support, in 4OS2 and
nesting, 94 4DOS/NT, 93
reading from a file, 307
referencing, 94 F
removing, 336
spaces in, 306 FAT file system, 14
ERASE, 189 detecting, 111
Error level, see Exit codes file names, 16
Error messages, 345 path length, 16
ERRORLEVEL test, in IF and IFF, File attributes, 18, 167
241 and COPY, 184, 185
Errors, handling, in batch and DEL, 191
files, 274 and DIR, 196, 200, 203
Escape character, 71, 72, 99, and EXCEPT, 220
132, 310 and FOR, 226
ESET, 95, 137, 218, 306 and GLOBAL, 229
and PATH, 276 and MOVE, 272
EXCEPT, 70, 220 and REN, 293
and DEL /Z, 191 and SELECT, 302
Executable extensions, 20, 66, of subdirectories, 168
117, 276 setting, 167
and filename completion, 41 subdirectory, 168
and Personal REXX, 92 testing, 108
wildcards in, 68 viewing, 167
EXIST test, in IF and IFF, 242 volume label, 168
EXIT, 222 File descriptions, 193
Exit codes, 117 controlling processing of,
and CALL, 173 132, 310
and CANCEL, 174 displaying, and
and conditional commands, redirection, 198, 203
68 length of, 132, 193, 198,
and DEL, 190 301
and EXIT, 222 retrieving, 108
and GLOBAL, 229 selecting files by, 197,
and IF tests, 241 201, 302, 303
and PROMPT, 281 sorting by, 203, 304
and QUIT, 287
retrieving, 99
Expanded memory, see Memory

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 386

Index
-------------------------------------------------------------------

File names, 13, 16, 56 Form feed character, 72
FAT-compatible, 17 FREE, 228
HPFS and NTFS, 17 Free memory, see Memory
extensions, 18
quoting, 17 G
semicolons in, 17, 60
length of, 16, 56 General Concepts, 10
parts of, 13 GLOBAL, 70, 229
separating, 109, 110, Glossary, 368
111, 112, 113 GOSUB, 80, 231, 295
shorthand for, 56 and FOR, 225
unique, 114 GOTO, 81, 232
File processing prompts, 48 and DO, 207
File system, see FAT file and IFF, 246
system, HPFS file system, and
NTFS file system H
Filename completion, 40
window, 41 HELP, 46, 234
Files, 13 and external commands, 146
adding line numbers to, 334 books to load, in 4OS2, 126
copying, 181 location of files, in 4DOS,
date stamp, 18, 110, 188, 127
196 options, in 4DOS, 126
deleting, 189 Hidden attribute, see File
displaying, 260, 334 attributes
finding, 110 HISTORY, 235
forcing deletion of, 190, History list, 35, 235
271 and secondary shells, 38,
moving, 269, 292 164
processing data from, 110, controlling, 132, 236
112 global, 38, 128
reading, in FOR, 224 storing in upper
renaming, 292 memory, 129
searching for, 113 inheritance, in secondary
selecting, 56, 299 shells, 143
with date, time, and local, 38, 128
size ranges, 60 memory space for, 127, 267
with extended parent reading from a file, 236
directory names, 57 History windows
with include lists, 65 colors of, 133
with multiple command line, 39
filenames, 64 directory, 43
with wildcards, 57 position of, 133
size of, 110, 196 size of, 133
time stamp, 18, 110, 196, HMA, see Memory
329 HPFS file system, 14
true path of, 114, 333 and 4DOS, 17
FOR, 70, 81, 223 and DIR, 199, 201, 202, 204
and GOSUB, 225 and file descriptions, 194

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 387

Index
-------------------------------------------------------------------

HPFS file system (continued) INT 2E support (4DOS), 142
and SELECT, 303, 304 Internal commands, see Commands
detecting, 111 Internal variables, 97, see
file names, 17, 56, 312 also Quick Reference on page
path length, 16 394
semicolons in file names, in aliases, 163
17, 60 in batch files, 79, 104
time stamps in, 203 International character sets,
22, 178, 211, 212, 213, 357
I ISALIAS test, in IF and IFF,
242
IF, 70, 81, 238 ISDIR test, in IF and IFF, 242
conditions, 239 ISINTERNAL test, in IF and IFF,
IFF, 81, 244 242
and GOSUB, 231 ISLABEL test, in IF and IFF,
and GOTO, 246 242
conditions, 239 ISWINDOW test, in IF and IFF,
Include lists, 65 242
.INI file, 120 ITERATE, in DO, 206
advanced directives, 141
and installation, 120 J
and SETDOS, 123, 130, 308
changing, for secondary JOIN (DOS command), 333
shells, 142
color directives, 135 K
comments in, 122
configuration directives, KEYBD, 251
130 Keyboard
directive types, 124 Caps Lock, Num Lock, and
directives, 121, see also Scroll Lock, 251
Quick Reference on page checking buffer, 248, 250
394 clearing buffer, 248, 250,
errors in, 122, 127, 128 254
global section, 122 KEYS, 253
initialization directives, Keys
125 codes, 22, 361
key mapping directives, 136 ASCII, 22, 357
location of, and extended, 23
multitaskers, 123 extended ASCII, 22
primary section, 122 F11 and F12, using, 32
prompts during execution, mapping, 136
127 clearing default key
secondary section, 123 map, 141
INKEY, 81, 86, 247 for all input, 137
INPUT, 81, 137, 249 for command line
Input and output, commands for, editing, 139
147 for history windows,
Installable file systems 140
(OS/2), 15, 111 for LIST, 141

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 388

Index
-------------------------------------------------------------------

Keys (continued) Memory (continued)
names, 31, 159 upper memory blocks (UMBs)
KEYSTACK, 55, 81, 87, 254 and LOADHIGH, 257
Keystroke aliases, see Aliases loading 4DOS in, 130
KSTACK.COM, 55, 254 storing aliases in, 129
storing environment in,
L 129
storing history in, 129
Labels, in batch files, 231, Memory resident programs, see
232 TSRs
LEAVE, in DO, 206 Messages, displaying, 214, 216
LH, 257 Microsoft Windows
LIM EMS, see Memory and screen colors, 29
Line feed character, 72 and secondary shells, 123
Lines, drawing, on screen, 212, detecting, 104
213 MKDIR, 266
LIST, 260 Monitor, detecting type of, 102

default colors, 135 Monochrome monitor, and colors,
keys used with, 137, 141 27
print device for, 134 MOVE, 269
screen size, 134, 311 and extended attributes,
LOADBTM, 77, 81, 263 271
LOADHIGH, 257 and SELECT, 270
LOG, 87, 264 MSGBOX, 273
Log files, time format, 130 Multiple commands, 45
Lower case, 135, 312 disabling, 312
in aliases, 156
M separator character, see
Command separator
Master environment, see Multiple filenames, 64
Environment
MD, 266 N
MEMORY, 267
Memory Netware, see Novell Netware
base Networks
amount of, 108 disk swapping on, 144
DOS in, 338 drive names on, 14
expanded (EMS) NOT, in IF and IFF, 238, 243,
amount of, 109, 267 244
swapping to, 128, 325 Novell Netware, and 4DOS, 143,
extended (XMS) 144
amount of, 114, 267 NTFS file system, 14
swapping to, 128, 325 and DIR, 199, 201, 202, 204
extended, amount of, 109, and file descriptions, 194
267 and SELECT, 303, 304
free, 267 detecting, 111
high memory area (HMA) displaying short file
DOS in, 338 names, 204
status of, 267 file names, 17, 56, 312

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 389

Index
-------------------------------------------------------------------

NTFS file system (continued) PATH environment variable
path length, 16 (continued)
semicolons in file names, format of, 276
17, 60 invalid directory in, 278
time stamps on, 203 length of, 277
Num Lock key, 251 viewing, 276
Numbers, comparing, 239 Path, of a file, 13, 15
Numeric coprocessor, 103 and aliases, 75
Numeric strings, testing for, extracting from full file
112 name, 113
finding full path name, 111
O finding true path, 114, 333
if omitted, 16
ON, 274 in executable extensions,
Operating system, 10 67
detecting, 102 in include lists, 65
Options, in commands, 149 length of, 16
Or (||) in conditional PAUSE, 81, 86, 279
commands, 69 Percent sign, see % sign
.OR., in IF and IFF, 238, 243, Personal REXX, 92
244 Pipes, 53, 326
OS/2 disabling, 312
and screen colors, 29 in 4OS2 and 4DOS/NT, 54
commands, help for, 146 nested, 54
default command processor, POPD, 205, 280, 285
11 Previous working directory,
detecting, 102 saving and restoring, 42,
DOS sessions, 102, 144 176, 177
extended attributes Primary shell, see Shell
and, 184, 271 [Primary], see .INI file
in OS/2 version 2.0, Printer
13, 104 checking status of, 112
sending control codes to,
P 72
sending files to, 181
Paged output, 48, 134 use in LIST, 261
Parameter character, 72 PROMPT command, 281
Parameters ANSI sequences in, 71, 283
expansion, 117 changing for secondary
in aliases, 162, 163 shell, 105
in batch files, 78, 316 PROMPT environment variable, 97
Parent directory, 16, 57, 175, Prompt Solution, The, 6
177, 266 PUSHD, 205, 280, 285
PATH command, 276
PATH environment variable, 97
"." in, 277
and @SEARCH variable
function, 113
changing, 218, 276

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 390

Index
-------------------------------------------------------------------

Q S

Quick reference Scan codes, see Keys
.INI file directives, 396 SCREEN, 81, 296
internal variables, 394 Screen, see also Colors
variable functions, 395 clearing, 179
QUIT, 81, 173, 174, 287 reading text from, 113
Quoting size, 24, 134, 311
of arguments, 118 detecting, 101, 103
of file names, 17 Scroll Lock key, 251
SCRPUT, 81, 298
R Search path, see PATH
environment variable
RAM, see Memory Secondary shell, see Shell
RAM disk, 14 [Secondary], see .INI file
swapping to, 128 SELECT, 299
Ranges (date, time, and size), and command grouping, 70
60 and include lists, 65
RD, 288 and MOVE, 270
Read-only attribute, see File color-coded displays, 30,
attributes 135, 301, 303
REBOOT, 289 default colors, 136, 301
Redirection, 50 keys used with, 137
alternative methods, 326, screen size, 134, 311
344 time format, 130
and batch files, 51 Semicolon, see ;
and color-coded directory SET, 95, 305
displays, 198 SETDOS, 308
and command grouping, 51, /A(NSI), 131, 179, 180, 309
70 /B(rightBG), 28, 135, 309
and NoClobber, 51, 311 /C(ompound character), 73,
capturing batch file 131, 309
output, 87 /D(escriptions), 132, 310
disabling, 312 /E(scape character), 73,
nested, 52 132, 310
preventing file overwrites, /I(nternal), 153, 242, 310
134 /L(ine), 134, 310
with numeric file handles, /M(ode), 132, 311
52 /N(o clobber), 134, 311
Registration, 6 /P(arameter character), 73,
REM, 81, 291 79, 134, 311
REN, 269, 292 /R(ows), 135, 311
RENAME, 269, 292 /S(hape), 131, 312
RETURN, 80, 231, 295 /U(pper), 104, 135, 201,
REXX support, 92 312
RMDIR, 288 /V(erbose), 78, 131, 312
Root directory, 15 /X (expansion), 46, 90, 94,
107, 118, 119, 312


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 391

Index
-------------------------------------------------------------------

SETDOS (continued) Swapping, 128
/Y (single step), 86, 313 enabling and disabling, 325
and .INI file, 123, 308 file names used by, 128,
SETLOCAL, 80, 81, 85, 315, 336 144
Shell, 1 types of, 128
level, 103, 282 SWAPPING command, 325
primary, 12 Switches, in commands, 149
secondary, 12 System
inheritance, 123, 143, attribute, see File
308 attributes
SHIFT, 79, 81, 316 rebooting, 289
SHRALIAS program, 38, 164
Size ranges, 60 T
Sound, see BEEP
Stack size, in 4DOS, 143 Tab character, 72
Standard error, 50 Technical support, 7
Standard input, 50, 262, 326, TEE, 54, 326
344 TEMP environment variable, 97
Standard output, 50, 326, 344 TEMP4DOS environment variable,
START, 81, 317 97
Startup command line, viewing, TEXT, 81, 328
in 4START, 83 THEN, in IFF, 244
Status tests, in IF and IFF, TIME, 329
241 Time ranges, 60
Stopwatch, see TIMER Time, format of, 130
Strings TIMER, 81, 330
comparing, 239 time format, 130
testing for numeric digits, Times, formatting, 112
112 TITLE, 332
Subdirectories, 15 TRUENAME, 333
attributes of, 168 TSRs
changing, see Changing and .BTM files, 263
directories and SETLOCAL, 315
copying, 186 and swapping state, 325
creating, 266 TYPE, 334
deleting files from, 191
descriptions for, 193 U
executing commands in, 229
hidden, 229 UMBs, see Memory
moving, 269, 272 UNALIAS, 85, 335
name, maximum length of, 16 Unknown commands, handling, 165
removing, 191, 272, 288 UNKNOWN_CMD alias, 21, 165
renaming, 292 and IFF, 233
testing for, 242 UNSET, 80, 95, 336
Subdirectory attribute, see UNTIL, in DO, 206
File attributes Upgrades, 6
SUBST (DOS command), 333 Upper case, 135, 312
Support, 7 Upper memory, see Memory


-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 392

Index
-------------------------------------------------------------------

V
Windows NT
Variable expansion, see and screen colors, 29
Environment variables, default command processor,
expansion 11
Variable functions, 105, see detecting, 102
also Quick Reference on page
394 X
in aliases, 115, 163
in batch files, 79, 115 XMS, see Memory
VER, 338 .XOR., in IF and IFF, 238, 243,
VERIFY, 186, 339 244
Version numbers, 100, 102, 338
Vertical text display, 341 Y
Video hardware, 24, see also
Screen Y, 54, 344
detecting, 102, 104
Virtual disk, see RAM disk Z
VOL, 340
Volume, see Disk drives Zero length files, creating,
Volume label, see Disk drives 52, 291
Volume label attribute, see
File attributes
VSCRPUT, 81, 341

W

Warm reboot, 289
Warning mark, see !
WHILE, 206
Wildcards, 57
and @SEARCH variable
function, 113
and filename completion, 41
and renaming
subdirectories, 293
extended, 58
and DEL, 190
in executable extensions,
68
in include lists, 65
in multiple filenames, 64
WINDOW, 343
Windows, see also Microsoft
Windows
controlling state of, 130,
154, 343
size of, 130
title of, 154

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 393

Quick Reference
-------------------------------------------------------------------

Quick Reference



Internal Variables

This table lists the 4DOS, 4OS2, and 4DOS/NT internal variables by
type, with a page reference for each.






Hardware status _HLOGFILE......102 Dates and times
_KSTACK........102
_APMAC.........100 _LOGFILE ......102 _DATE..........101
_APMBATT.......101 _PID...........103 _DAY...........102
_APMLIFE.......101 _PPID..........103 _DOW...........102
_CPU...........101 _PTYPE.........103 _DOY...........102
_MONITOR.......102 _SHELL.........103 _HOUR..........102
_NDP...........103 _SID...........103 _MINUTE........102
_VIDEO.........104 _SWAPPING......103 _MONTH.........102
_TRANSIENT.....104 _SECOND........103
_WINTITLE......104 _TIME..........103
Operating system _YEAR..........104
and software status
Screen and colors
_ANSI..........100 Error codes
_BOOT..........101 _BG...........101
_CODEPAGE......101 _COLUMN........101 ?...............99
_COUNTRY.......101 _COLUMNS.......101 ??..............99
_DOS...........102 _FG............102 _?..............99
_DOSVER........102 _ROW...........103 _SYSERR........103
_DV............102 _ROWS..........103
_MOUSE.........102
_WIN...........104 Compatibility
_WINDIR........104 Drives and
_WINSYSDIR.....104 directories =..............99
_WINVER........104 +.............100
_CWD...........101
_CWDS..........101
Command processor _CWP...........101
status _CWPS..........101
_DISK..........102
_4VER..........100 _LASTDISK......102
_ALIAS.........100
_BATCH.........101
_ENV...........102

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 394

Quick Reference
-------------------------------------------------------------------



Variable Functions

This table lists the 4DOS, 4OS2, and 4DOS/NT variable functions by
type, with a page reference for each.





System status @FILETIME......110 Numbers and
@FILEWRITE.....110 arithmetic
@DOSMEM........108 @FINDFIRST.....110
@EMS...........109 @FINDNEXT......111 @DEC...........108
@EXTENDED......109 @LINE..........112 @EVAL..........109
@MASTER........112 @LINES.........112 @INC...........111
@READSCR.......113 @SEARCH........113 @INT...........111
@XMS...........114 @TRUENAME......114 @NUMERIC.......112
@UNIQUE........114 @RANDOM........113

Drives and devices
File names Dates and times
@CDROM.........108
@DEVICE........108 @EXT...........109 @DATE..........108
@DISKFREE......108 @FILENAME......110 @MAKEDATE......112
@DISKTOTAL.....108 @FULL..........111 @MAKETIME......112
@DISKUSED......108 @NAME..........112 @TIME..........114
@FSTYPE........111 @PATH..........113
@LABEL.........112
@LPT...........112 Utility
@READY.........113 Strings and
@REMOTE........113 characters @ALIAS.........107
@REMOVABLE.....113 @SELECT........113
@ASCII.........107 @EXEC..........109
@CHAR..........108
Files @INDEX.........111
@INSTR.........111
@ATTRIB........108 @LEN...........112
@DESCRIPT......108 @LOWER.........112
@EXETYPE.......109 @REPEAT........113
@FILEAGE.......109 @SUBSTR........113
@FILECLOSE.....109 @TRIM..........114
@FILEDATE......110 @UPPER.........114
@FILEOPEN......110 @WORD..........114
@FILEREAD......110
@FILES.........110
@FILESEEK......110
@FILESIZE......110

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 395

Quick Reference
-------------------------------------------------------------------



.INI File Directives

This table lists the 4DOS, 4OS2, and 4DOS/NT .INI file directives
by type, with a page reference for each.





Initialization DescriptionMax.132 Advanced
Descriptions...132
4StartPath.....125 EditMode.......132 All Products
Alias..........125 EscapeChar.....132
AutoExecPath 125 HistCopy.......132 ClearKeyMap....141
AutoExecParms 126 HistLogName....132 NextINIFile....142
Environment....126 HistMin........132
EnvFree........126 HistWinColors..133 4DOS Only
HelpBook.......126 HistWinHeight..133
HelpOptions....126 HistWinLeft....133 CritFail.......142
HelpPath.......127 HistWinTop.....133 DiskReset......142
History........127 HistWinWidth...133 DVCleanup......142
INIQuery.......127 LineInput......133 FullINT2E......142
LocalAliases...128 LogName........134 Inherit........143
LocalHistory...128 NoClobber......134 MessageServer..143
PauseOnError...128 ParameterChar..134 NetwareNames...143
Swapping.......128 Printer........134 OutputBIOS.....143
UMBAlias.......129 ScreenColumns..134 StackSize......143
UMBEnvironment.129 ScreenRows.....134 SwapReopen.....144
UMBHistory.....129 UpperCase......135 UniqueSwapName.144
UMBLoad........130
WindowHeight...130
WindowState....130 Color Key Mapping
WindowWidth....130
WindowX........130 BrightBG.......135 General Input
WindowY........130 ColorDir.......135
InputColors....135 Backspace......137
ListColors.....135 BeginLine......137
Configuration ListStatBarColors Del............137
...............136 DelToBeginning.137
AmPm...........130 SelectColors...136 DelToEnd.......137
ANSI...........131 SelectStatBarColors DelWordLeft....137
BatchEcho......131 ...............136 DelWordRight...138
BeepFreq.......131 StdColors......136 Down...........138
BeepLength.....131 EndLine........138
CommandSep.....131 EraseLine......138
CursorIns......131 ExecLine.......138
CursorOver.....132 Ins............138

-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 396

Quick Reference
-------------------------------------------------------------------

Left...........138
NormalKey......138
Right..........138
Up.............138
WordLeft.......139
WordRight......139

Command Line
Editing

AddFile........139
CommandEscape..139
DelHistory.....139
EndHistory.....139
Help...........139
NextFile.......139
NextHistory....139
NormalEditKey..139
PopFile........139
PrevFile.......140
PrevHistory....140
SaveHistory....140

History Window

DirWinOpen.....140
HistWinBegin...140
HistWinDel.....140
HistWinEdit....140
HistWinEnd.....140
HistWinExec....140
HistWinOpen....140
NormalHWinKey..140

LIST

ListFind.......141
ListHex........141
ListHighBit....141
ListInfo.......141
ListNext.......141
ListPrint......141
ListWrap.......141
NormalListKey..141






-------------------------------------------------------------------
Copr. 1993, JP Software Inc. 4DOS, 4OS2, 4DOS/NT Reference / 397


  3 Responses to “Category : Utilities for DOS and Windows Machines
Archive   : JP4REF.ZIP
Filename : REFMAN.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/