.nameit symbol=date     text='2 Sep'
.nameit symbol=4verprev text='3.03'
.nameit symbol=4ver     text='3.04'
.nameit symbol=4verrev  text='3.04B'
.nameit symbol=4OS2     text='CMD.EXE'
.nameit symbol=4OS2INI  text='CMD.INI'

:userdoc.
:docprof toc=12345.
:title.Command reference

.* --------------------------------------------------------------------------

:h1 name=AboutHelp.About Command reference
:p.
:lines align=center.
&4OS2.
:p.
Version &4ver. Help System
:p.
Text by osFree team, Hardin Brothers, Tom Rawson, and Rex Conn
:elines.
:p.
:p.
Help Text Copyright 2003, osFree team.
.br
Help Text Copyright 1993 - 2002, JP Software Inc., All Rights Reserved.
:p.
Software Copyright 1988 - 2002, Rex Conn and JP Software Inc., All Rights
Reserved.
:p.
4DOS, 4OS2, and 4NT are JP Software Inc.'s trademarks for its family of
character-mode command processors.  4DOS and Take Command are registered
trademarks of JP Software Inc.  JP Software, jpsoft.com, and all JP
Software designs and logos are also trademarks of JP Software Inc.  Other
product and company names are trademarks of their respective owners.
:p.
:p.
[&date. - &4verrev.]

.* --------------------------------------------------------------------------

:h1 name=CommandLine.The Command Line
:p.
&4OS2. displays a [c&colon.\] prompt when it is waiting for you to enter a
command.  (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.
:p.
This section 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 &4OS2..  If you prefer using different
keystrokes to perform these functions, you can assign new ones with
:link reftype=hd refid=INIKeyMap.key mapping directives:elink. in
:hp1.&4OS2INI.:ehp1..
:p.
The command line features documented in this section are&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=Editing.Command-Line Editing:elink.
:pt.:pd.:link reftype=hd refid=CmdHist.Command History and Recall:elink.
:pt.:pd.:link reftype=hd refid=HistWin.Command History Window:elink.
:pt.:pd.:link reftype=hd refid=CmdNames.Command Names and Parameters:elink.
:pt.:pd.:link reftype=hd refid=FileComp.Filename Completion:elink.
:pt.:pd.:link reftype=hd refid=AutoDir.Automatic Directory Changes:elink.
:pt.:pd.:link reftype=hd refid=DirHist.Directory History Window:elink.
:pt.:pd.:link reftype=hd refid=MultCmds.Multiple Commands:elink.
:pt.:pd.:link reftype=hd refid=ExpandAlias.Expanding and Disabling Aliases:elink.
:pt.:pd.:link reftype=hd refid=CmdLength.Command-Line Length Limits:elink.
:eparml.:lm margin=1.
.br
:p.
Additional command-line features are documented under
:link reftype=hd refid=FileSel.File Selection:elink. and :link reftype=hd
refid=TOC_Other.Other Features:elink..

.* --------------------------------------------------------------------------

:h2 name=Editing.Command-Line Editing
:p.
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 :hp2.Enter:ehp2.
to execute it, or :hp2.Esc:ehp2. to erase it.  The command line you enter
can be up to 1023 characters long.
:p.
You can use the following editing keys when you are typing a command (the
words :hp2.Ctrl:ehp2. and :hp2.Shift:ehp2. mean to press the Ctrl or Shift
key together with the other key named)&colon.
:p.
:hp2.Cursor Movement Keys&colon.:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:hp2.:ehp2.:pd.Move the cursor left one character.
:pt.:hp2.:ehp2.:pd.Move the cursor right one character.
:pt.:hp2.Ctrl :ehp2.:pd.Move the cursor left one word.
:pt.:hp2.Ctrl :ehp2.:pd.Move the cursor right one word.
:pt.:hp2.Home:ehp2.:pd.Move the cursor to the beginning of the line.
:pt.:hp2.End:ehp2.:pd.Move the cursor to the end of the line.
:eparml.:lm margin=1.
.br
:hp2.Insert and Delete&colon.:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:hp2.Ins:ehp2.:pd.Toggle between insert and overtype mode.
:pt.:hp2.Del:ehp2.:pd.Delete the character at the cursor.
:pt.:hp2.Backspace:ehp2.:pd.Delete the character to the left of the cursor.
:pt.:hp2.Ctrl-L:ehp2.:pd.Delete the word or partial word to the left of the cursor.
:pt.:hp2.Ctrl-R:ehp2.:pd.or :hp2.Ctrl-Bksp:ehp2.   Delete the word or partial word to the right of the cursor.
:pt.:hp2.Ctrl-Home:ehp2.:pd.Delete from the beginning of the line to the cursor.
:pt.:hp2.Ctrl-End:ehp2.:pd.Delete from the cursor to the end of the line.
:pt.:hp2.Esc:ehp2.:pd.Delete the entire line.
:eparml.:lm margin=1.
.br
:hp2.Execution&colon.:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:hp2.Ctrl-C:ehp2.:pd.or :hp2.Ctrl-Break:ehp2.  Cancel the command line.
:pt.:hp2.Enter:ehp2.:pd.Execute the command line.
:eparml.:lm margin=1.
.br
Most of the command-line editing capabilities are also available
when a &4OS2. command prompts you for a line of input.  For example,
you can use the command-line editing keys when
:link reftype=hd refid=DESCRIBE.DESCRIBE:elink. prompts for a file
description, when :link reftype=hd refid=INPUT.INPUT:elink. prompts for
input from an alias or batch file, or when :link reftype=hd
refid=LIST.LIST:elink. prompts you for a search string.
:p.
If you want your input at the command line to be in a different
color from &4OS2.'s prompts or output, you can use the Display page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, or the
:link reftype=hd refid=INI_InputColors.InputColors:elink. directive in
:hp1.&4OS2INI.:ehp1..
:p.
&4OS2. will prompt for additional command-line text when you include
the :link reftype=hd refid=Escape.escape character:elink. as the very
last character of a typed command line.  The default escape character
is the caret [:hp2.^:ehp2.].  For example&colon.
:xmp.
        [c&colon.\] echo The quick brown fox jumped over the lazy^
        More? sleeping dog. > alphabet
:exmp.:p.
Sometimes you may want to enter one of the command line editing 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.
:p.
To get around this problem, use the special keystroke :hp2.Alt-255:ehp2..
You enter Alt-255 by holding down the :hp2.Alt:ehp2. key while you type
:hp2.255:ehp2. on the numeric keypad, then releasing the :hp2.Alt:ehp2. 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 &4OS2. 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 :link reftype=hd refid=INIKeyMap.key mapping directives:elink. in
the :hp1..INI:ehp1. file, and Alt-255 itself can be reassigned with the
:link reftype=hd refid=INI_CommandEscape.CommandEscape:elink. directive.

.* --------------------------------------------------------------------------

:h2 name=CmdHist.Command History and Recall
:p.
:hp2.Command History Keys&colon.:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:hp2.&uarrow.:ehp2.:pd.Recall the previous (or most recent) command, or the
most recent command that matches a partial command line.
:pt.:hp2.&darrow.:ehp2.:pd.Recall the next (or oldest) command, or the oldest
command that matches a partial command line.
:pt.:hp2.F3:ehp2.:pd.Fill in the rest of the command line from the previous command,
beginning at the current cursor position.
:pt.:hp2.Ctrl-D:ehp2.:pd.Delete the currently displayed history list entry, erase
the command line, and display the previous (matching) history list entry.
:pt.:hp2.Ctrl-E:ehp2.:pd.Display the last entry in the history list.
:pt.:hp2.Ctrl-K:ehp2.:pd.Save the current command line in the history list without
executing it, and then clear the command line.
:pt.:hp2.Ctrl-Enter:ehp2.:pd.Copy the current command line to the end of
the history list even it has not been altered, then execute it.
:pt.:hp2.@:ehp2.:pd.As the first character in a line&colon.  Do not save the current line
in the history list when it is executed, and do not store it in the :link reftype=hd refid=CMDLINE.CMDLINE:elink.
environment variable.
:eparml.:lm margin=1.
.br
Use the :hp2.&uarrow.:ehp2. key repeatedly to scan back through the
history list.  When the desired command appears, press :hp2.Enter:ehp2. to
execute it again.  After you have found a command, you can edit it
before pressing :hp2.Enter:ehp2..
:p.
The history list is normally "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 disable this feature and
make command history recall stop at the beginning or end of the list by
turning off the History Wrap selection on the Command Line 1 page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, or setting :link
reftype=hd refid=INI_HistWrap.Histwrap:elink. to No in the :hp1..INI:ehp1.
file.
:p.
You can search the command history list to find a previous command
quickly using :hp2.command completion:ehp2..  Just enter the first few
characters of the command you want to find and press :hp2.&uarrow.:ehp2..
You only need to enter enough characters to identify the command
that you want to find.  If you press the :hp2.&uarrow.:ehp2. 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 :hp2.&uarrow.:ehp2. again.
:p.
You can specify the size of the command history list with the
:link reftype=hd refid=OPTION.OPTION:elink. command, or with the
:link reftype=hd refid=INI_History.History:elink. directive in the :hp1..INI:ehp1. file.  When the
list is full, the oldest commands are discarded to make room for
new ones.  You can also use the :link reftype=hd refid=INI_HistMin.HistMin:elink. directive
in the :hp1..INI:ehp1. file to enable or disable history saves and to
specify the shortest command line that will be saved.
:p.
You can prevent any command line from being saved in the history by
beginning it with an at sign [:hp2.@:ehp2.].
:p.
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 or moved to the end of the list when it is re-
executed, set :link reftype=hd refid=INI_HistCopy.HistCopy:elink. or
:link reftype=hd refid=INI_HistMove.HistMove:elink. to Yes in
:hp1.&4OS2INI.:ehp1..
If you select either of these options, the list entry identified as "current"
(the entry from which commands are retrieved when you press
:hp2.&uarrow.:ehp2.) is also adjusted to refer to the end of the history
list after each recalled command is executed.
:p.
:p.
:hp2.Local and Global Command History:ehp2.
:p.
The command history can be stored in either a "local" or "global"
list.
:p.
With a local command history list, any changes made to the history will
only affect the current copy of &4OS2..  They will not be visible in
other shells, or other sessions.
:p.
With a global command history list, all copies of &4OS2. 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..
:p.
You can control the type of command history on the Startup page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, with the
:link reftype=hd refid=INI_LocalHistory.LocalHistory:elink. directive in the
:hp1..INI:ehp1. file, or with the :hp2./L:ehp2. and :hp2./LH:ehp2. options
of the :link reftype=hd refid=START.START:elink. command.
:p.
There is no fixed rule for deciding whether to use a local or global
command 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 setting, then modify it if you find a situation where the default is
not convenient.
:p.
If you select a global history list for &4OS2. you can share the
history among all copies of &4OS2. running in any session.  When you
close all &4OS2. sessions, the memory for the global history list is
released, and a new, empty history list is created the next time
you start &4OS2..
:p.
If you want the history list to be retained in
memory even when no command processor session is running, execute the :link
reftype=hd refid=SHRALIAS.SHRALIAS:elink. command, which loads a program to
perform this service for the global command history, directory history, and
alias lists.
:p.
Whenever you start a secondary shell 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
shell.  If you want changes made in a secondary shell to affect the previous
shell, use a global history list in both shells.

.* --------------------------------------------------------------------------

:h2 name=HistWin.Command History Window
:p.
:hp2.Command History Window Keys&colon.:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:hp2.PgUp:ehp2.:pd.(from the command line) Open the command history window.
:pt.  or :hp2.PgDn:ehp2.:pd.
:pt.:hp2.&uarrow.:ehp2.:pd.Scroll the display up one line.
:pt.:hp2.&darrow.:ehp2.:pd.Scroll the display down one line.
:pt.:hp2.:ehp2.:pd.Scroll the display left 4 columns.
:pt.:hp2.:ehp2.:pd.Scroll the display right 4 columns.
:pt.:hp2.PgUp:ehp2.:pd.(inside the window) Scroll the display up one page.
:pt.:hp2.PgDn:ehp2.:pd.(inside the window) Scroll the display down one page.
:pt.:hp2.Ctrl-PgUp:ehp2.:pd.Go to the beginning of the history list.
:pt.  or :hp2.Home:ehp2.:pd.
:pt.:hp2.Ctrl-PgDn:ehp2.:pd.Go to the end of the history list.
:pt.  or :hp2.End:ehp2.:pd.
:pt.:hp2.Ctrl-D:ehp2.:pd.Delete the selected line from the history list.
:pt.:hp2.Enter:ehp2.:pd.Execute the selected line.
:pt.:hp2.Ctrl-Enter:ehp2.:pd.Move the selected line to the command line for editing.
:eparml.:lm margin=1.
.br
You can view the command history in a scrollable :hp2.command
history window:ehp2., and select the command to modify or re-execute
from those displayed in the window.  To activate the command
history window press :hp2.PgUp:ehp2. or :hp2.PgDn:ehp2. 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.)
:p.
The display is not circular as it is at the prompt; it has a fixed beginning
and end.  The :hp2.Ctrl-D:ehp2. (delete from history) key works within the
history window as it does at the command line.
:p.
Once you have selected a command in the history window, press
:hp2.Enter:ehp2. to execute it immediately, or :hp2.Ctrl-Enter:ehp2. to move
the line to the prompt for editing (you cannot edit the line directly
in the history window).
:p.
You can bring up a "filtered" history window by typing some
characters on the command line, then pressing :hp2.PgUp:ehp2. or
:hp2.PgDn:ehp2.. Only those commands matching the typed characters will be
displayed in the window.
:p.
See :link reftype=hd refid=Popup.Popup Windows:elink. for information on
customizing window position, size, and color.

.* --------------------------------------------------------------------------

:h2 name=CmdNames.Command Names and Parameters
:p.
When you enter a command you type its name at the prompt, followed by a
space and any parameters for the command.  For example, all of these
could be valid commands&colon.
:xmp.
      [c&colon.\] dir
      [c&colon.\] copy file1 file2 d&colon.\
      [c&colon.\] f&colon.\util\mapmem /v
      [c&colon.\] "c&colon.\my programs\jp software\take command\tcmdos2.exe" /l
:exmp.:p.
The last three commands above include both a command name, and one or
more parameters.  There are no spaces within the command name (except in
quoted file names), but there is a space between the command name and
any parameeters, and there are spaces between the parameters.
:p.
Some commands may work when parameters are entered directly after the
command (without an intervening space, :hp1.e.g.:ehp1. :hp2.dir/p:ehp2.), or when several
parameters are entered without spaces between them (:hp1.e.g.:ehp1. :hp2.dir /2/p:ehp2.).
A very few older programs may even require this approach.  However
leaving out spaces in this way is usually technically incorrect, and is
not recommended as a general practice, as it may not work for all
commands.
:p.
If the command name includes a path, the elements must be separated with
backslashes (:hp1.e.g.:ehp1. f&colon.\util\mapmem).  If you are accustomed to Unix syntax
where forward slashes are used in command paths, and want &4OS2. to
recognize this approach, you can set :link reftype=hd
refid=INI_UnixPaths.UnixPaths:elink. to Yes in :hp1.&4OS2INI.:ehp1..
:p.
For more information on command entry see
:link reftype=hd refid=MultCmds.Multiple Commands:elink. and
:link reftype=hd refid=CmdLength.Command-Line Length Limits:elink..
For details on how &4OS2. handles the various elements it finds on
the command line see :link reftype=hd refid=Parsing.Command Parsing:elink..

.* --------------------------------------------------------------------------

:h2 name=FileComp.Filename Completion
:p.
:hp2.Filename Completion Keys&colon.:ehp2.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:hp2.F8:ehp2.:pd.Get the previous matching filename.
:pt.  or :hp2.Shift-Tab:ehp2.:pd.
:pt.:hp2.F9:ehp2.:pd.Get the next matching filename.
:pt.  or :hp2.Tab:ehp2.:pd.
:pt.:hp2.F10:ehp2.:pd.Keep the current matching filename and display the next
matching name immediately after the current one.
:eparml.:lm margin=1.
.br
Filename completion can help you by filling in a complete file name
on the command line when you only remember or want to type part of the name.
For example, if you know the name of a file begins :hp1.AU:ehp1. but you
can't remember the rest of the name, type&colon.
:xmp.
        [c&colon.\] copy au
:exmp.:p.
and then press the :hp2.Tab:ehp2. key or :hp2.F9:ehp2. key.  &4OS2. will
search the current directory for filenames that begin :hp1.AU:ehp1. and
insert the first one onto the command line in place of the :hp1.AU:ehp1.
that you typed.
:p.
If this is the file that you want, simply complete the command.  If
&4OS2. didn't find the file that you were looking for, press :hp2.Tab:ehp2.
or :hp2.F9:ehp2. again to substitute the next filename that begins with
:hp1.AU:ehp1..  When there are no more filenames that match your pattern,
the system will beep each time you press :hp2.Tab:ehp2. or :hp2.F9:ehp2..
:p.
If you go past the filename that you want, press :hp2.Shift-Tab:ehp2. or
:hp2.F8:ehp2. 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 :hp2.Shift-Tab:ehp2. or :hp2.F8:ehp2..
:p.
If you want to enter more than one matching filename on the same
command line, press :hp2.F10:ehp2. 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 :hp2.Tab:ehp2. (or :hp2.F9:ehp2.),
:hp2.Shift-Tab:ehp2. (or :hp2.F8:ehp2.), and :hp2.F10:ehp2. to move through
the remaining matching files.
:p.
The pattern you use for matching may contain any valid filename
characters, as well as wildcard characters and extended
:link reftype=hd refid=Wildcards.wildcards:elink..  For example, you can copy the first
matching :hp1..TXT:ehp1. file by typing
:xmp.
        [c&colon.\] copy *.txt
:exmp.:p.
and then pressing :hp2.Tab:ehp2..
:p.
If you don't specify part of a filename before pressing :hp2.Tab:ehp2.,
the command processor will match all files.  For example, if you enter the
above command as "COPY", without the "*.TXT", and then press :hp2.Tab:ehp2.,
the first filename in the current directory is displayed.  Each time you
press :hp2.Tab:ehp2. or :hp2.F9:ehp2. after that, another name from the
current directory is displayed, until all filenames have been displayed.
:p.
If you type a filename without an extension, &4OS2. will add :hp1.*.*:ehp1. to
the name (* on HPFS drives).  It will also place a "*" after a partial
extension. If you are typing a group of file names in an :link reftype=hd
refid=InclList.include list:elink., the part of the include list at the
cursor will be used as the pattern to match.
:p.
When filename completion is used at the start of the command line,
it will only match directories, executable files, 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
:link reftype=hd refid=AutoDir.automatic directory change:elink..
:p.
:p.
:hp2.Appending Backslashes to Directory Names:ehp2.
:p.
If you set the :link reftype=hd refid=INI_AppendToDir.AppendToDir:elink.
:hp1..INI:ehp1. directive, or the "Add \ ..." option on the Command Line 1
page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, &4OS2. will add a
trailing backslash [:hp2.\:ehp2.] to all directory names.  This feature can
be especially handy if you use filename completion to specify files that are
not in the current directory -- a succession of :hp2.Tab :ehp2.(or
:hp2.F9:ehp2.) and :hp2.F10 :ehp2.keystrokes can build a complete path to the
file you want to work with.
:p.
The following example shows the use of this technique to edit the file :hp1.
C&colon.\DATA\FINANCE\MAPS.DAT:ehp1..  The lines which include :hp1.<F9>:ehp1.
show where :hp2.F9:ehp2. (or :hp2.Tab:ehp2.) is pressed; the other lines
show how the command line appears after the previous :hp2.F9:ehp2. or
:hp2.Tab:ehp2. (the example is displayed on several lines here, but all
appears at a single command prompt when you actually perform the steps)&colon.
:xmp.
        1    [c&colon.\> edit \da :hp1.<F9>:ehp1.
        2    [c&colon.\> edit \data\
        3    [c&colon.\> edit \data\f :hp1.<F9>:ehp1.
        4    [c&colon.\> edit \data\frank.doc :hp1.<F9>:ehp1.
        5    [c&colon.\> edit \data\finance\
        6    [c&colon.\> edit \data\finance\map :hp1.<F9>:ehp1.
        7    [c&colon.\> edit \data\finance\maps.dat
:exmp.:p.
Note that :hp2.F9:ehp2. was pressed twice in succession on lines 3 and 4,
because the file name displayed on line 3 was not what was needed we were
looking for the FINANCE directory, which came up the second time :hp2.F9:ehp2.
was pressed.  In this example, filename completion saves about half the
keystrokes that would be required to type the name in full.  If you are using
long file or directory names, the savings can be much greater.
:p.
:p.
:hp2.Customizing Filename Completion:ehp2.
:p.
You can customize filename completion for any internal or external
command or alias.  This allows the command processor to display filenames
intelligently based on the command you are entering.  For example, you might
want to see only :hp1..TXT:ehp1. files when you use filename completion in
the EDIT command.
:p.
To customize filename completion you can use the Command Line 1 page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, or set the
:link reftype=hd refid=INI_FileCompletion.FileCompletion:elink.
directive manually in your .:hp1.INI:ehp1. file.  You can also use the
:link reftype=hd refid=FILECOMPLETION.FILECOMPLETION:elink. environment
variable.  If you use both, the environment variable will override the
settings in your :hp1..INI:ehp1. file.  You may find it useful to use the
environment variable for experimenting, then create permanent settings with
the OPTION command or the FileCompletion directive.
:p.
The format for both the environment variable and the :hp1..INI:ehp1. file
is&colon.
:xmp.
        cmd1&colon.ext1 ext2 ...; cmd2&colon. ...
:exmp.:p.
where "cmd" is a command name and "ext" is a file extension (which may
include wildcards) or one of the following file types&colon.
:xmp.
        DIRS       Directories
        RDONLY     Read-only files
        HIDDEN     Hidden files
        SYSTEM     System files
        ARCHIVE    Files modified since the last backup
:exmp.:p.
The command name is the internal command, alias command, or executable
file name (without a path).  For example, to have file completion return only
directories for the CD command and only :hp1..C:ehp1. and :hp1..ASM:ehp1.
files for B (the Boxer editor), you would use this setting for filename
completion in the OPTION dialogs&colon.
:xmp.
        FileCompletion=cd&colon.dirs; b&colon.c asm
:exmp.:p.
To set the same values using the environment variable, you would use this
line&colon.
:xmp.
        [c&colon.\] set filecompletion=cd&colon.dirs; b&colon.c asm
:exmp.:p.
With this setting in effect, if you type "CD " and then pressed :hp2.Tab:ehp2.,
the command processor will return only directories, not files.  If you type
"B " and press :hp2.Tab:ehp2., you will see only names of :hp1..C:ehp1. and
:hp1..ASM:ehp1. files.
:p.
&4OS2. does :hp2.not:ehp2. check your command line for aliases before matching
the commands for customized file completion.  Instead, they ignore any path
or file extension information in the first word of the command, and then
search the :link reftype=hd refid=FILECOMPLETION.FILECOMPLETION:elink.
environment variable and the :link reftype=hd refid=INI_FileCompletion.FileCompletion:elink.
:hp1.INI:ehp1. directive to find a match that will limit the files selected
for filename completion.
:p.
:p.
:hp2.Filename Completion Window:ehp2.
:p.
You can also view filenames in a :hp2.filename completion window:ehp2. and
select the file you want to work with.  To activate the window, press
:hp2.F7:ehp2. or :hp2.Ctrl-Tab:ehp2. at the command line.  You will see a
window in the upper-right corner of the screen, with a sorted list 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.  You can search for a name by typing the
first few characters. (:hp2.Ctrl-Tab:ehp2. will work only if your keyboard
and keyboard driver support it.  If it does not work on your system, use
:hp2.F7:ehp2. instead.)
:p.
See :link reftype=hd refid=Popup.Popup Windows:elink. for information on
customizing window position, size, and color.
:p.
:p.
:hp2.Filename Completion Window Keys&colon.:ehp2.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:hp2.F7:ehp2.:pd.(from the command line)  Open the filename completion window.
:pt.  or :hp2.Ctrl-Tab:ehp2.:pd.
:pt.:hp2.&uarrow.:ehp2.:pd.Scroll the display up one line.
:pt.:hp2.&darrow.:ehp2.:pd.Scroll the display down one line.
:pt.:hp2.:ehp2.:pd.Scroll the display left 4 columns.
:pt.:hp2.:ehp2.:pd.Scroll the display right 4 columns.
:pt.:hp2.PgUp:ehp2.:pd.Scroll the display up one page.
:pt.:hp2.PgDn:ehp2.:pd.Scroll the display down one page.
:pt.:hp2.Ctrl-PgUp:ehp2.:pd.Go to the beginning of the filename list.
:pt.  or :hp2.Home:ehp2.:pd.
:pt.:hp2.Ctrl-PgDn:ehp2.:pd.Go to the end of the filename list.
:pt.  or :hp2.End:ehp2.:pd.
:pt.:hp2.Enter:ehp2.:pd.Insert the selected filename into the command line.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=AutoDir.Automatic Directory Changes
:p.
The automatic directory change feature lets you change directories
quickly from the command prompt, without entering an explicit
:link reftype=hd refid=CD.CD:elink. or :link reftype=hd refid=CDD.CDD:elink.
command.  To do so, simply type the name of the directory you want to change
to at the prompt, with a backslash [:hp2.\:ehp2.] at the end.  For
example&colon.
:xmp.
        [c&colon.\] &4OS2.\
        [c&colon.\&4OS2.]
:exmp.:p.
This can make directory changes very simple when it is combined with
:link reftype=hd refid=ExtDirSearch.Extended Directory Searches:elink.
or :link reftype=hd refid=CDPATH.CDPATH:elink..  If you have enabled either
of those features, the command processor will use them in searching for any
directory you change to with an automatic directory change.
:p.
For example, suppose Extended Directory Searches are enabled, and the
directory WIN exists on drive E&colon..  You can change to this directory
with a single word on the command line&colon.
:xmp.
        [c&colon.\&4OS2.] win\
        [e&colon.\win]
:exmp.:p.
(Depending on the way Extended Directory Searches are configured, and the
number of subdirectories on your disk whose names contain the string
:hp1.WIN:ehp1., when you execute such a command you may see an immediate
change as shown above, or a popup window which contains a list of
subdirectories named :hp1.WIN:ehp1. to choose from.)
:p.
The text before the backslash can include a drive letter, a full path, a
partial path, or a UNC name.  Commands like "....\" can be used to
move up the directory tree quickly (see
:link reftype=hd refid=ParDir.Extended Parent Directory
Names:elink.).  Automatic directory changes save the current directory, so
it can be recalled with a "CDD -" or "CD -" command.  For example, any of
the following are valid automatic directory change entries&colon.
:xmp.
        [c&colon.\] d&colon.\data\finance\
        [c&colon.\] archives\
        [c&colon.\] ...\util\os2\
        [c&colon.\] \\server\vol1\george\
:exmp.:p.
The first and last examples change to the named directory.  The second
changes to the :hp1.ARCHIVES:ehp1. subdirectory of the current directory, and
the third changes to the :hp1.UTIL\OS2:ehp1. subdirectory of the directory
which is two levels "up" from the current directory in the tree.

.* --------------------------------------------------------------------------

:h2 name=DirHist.˙Directory History Window
:p.
:hp2.Directory History Window Keys&colon.:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:hp2.Ctrl-PgUp:ehp2.:pd.(from the command line) Open the directory history window.
:pt.  or :hp2.Ctrl-PgDn:ehp2.:pd.
:pt.:hp2.&uarrow.:ehp2.:pd.Scroll the display up one line.
:pt.:hp2.&darrow.:ehp2.:pd.Scroll the display down one line.
:pt.:hp2.:ehp2.:pd.Scroll the display left 4 columns.
:pt.:hp2.:ehp2.:pd.Scroll the display right 4 columns.
:pt.:hp2.PgUp:ehp2.:pd.Scroll the display up one page.
:pt.:hp2.PgDn:ehp2.:pd.Scroll the display down one page.
:pt.:hp2.Ctrl-PgUp:ehp2.:pd.Go to the beginning of the directory list.
:pt.  or :hp2.Home:ehp2.:pd.
:pt.:hp2.Ctrl-PgDn:ehp2.:pd.Go to the end of the directory list.
:pt.  or :hp2.End:ehp2.:pd.
:pt.:hp2.Ctrl-D:ehp2.:pd.Delete the selected line from the directory list.
:pt.:hp2.Enter:ehp2.:pd.Change to the selected drive and directory.
:pt.:hp2.Ctrl-Enter:ehp2.:pd.Move the selected line to the command line
for editing.
:eparml.:lm margin=1.
.br
:p.
The current directory is recorded automatically in the :hp2.directory history
list:ehp2. just before each change to a new directory or drive.
:p.
You can view the directory history from a :hp2.directory history window:ehp2.
and change to any drive and directory on the list.  To activate the directory
history window, press :hp2.Ctrl-PgUp:ehp2. or :hp2.Ctrl-PgDn:ehp2. at the
command line.  You can then select a new directory with the :hp2.Enter:ehp2.
key.
:p.
If the directory history list becomes full, old entries are deleted to
make room for new ones.  You can set the size of the list with the
:link reftype=hd refid=INI_DirHistory.DirHistory:elink. directive in the
:hp1..INI:ehp1. file.  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.  The directory history can be stored in
either a "local" or "global" list. (See :link reftype=hd
refid=GlobalDirHistory.Local and Global Directory History:elink..)
:p.
When you switch directories the original directory is saved in the
directory history list, regardless of whether you change directories at the
command line, from within a batch file, or from within an alias.  However,
directory changes made by external directory navigation utilities or other
external programs are not recorded by &4OS2..
:p.
See :link reftype=hd refid=Popup.Popup Windows:elink. for information on
customizing window position, size, and color.

.* --------------------------------------------------------------------------

:h3 name=GlobalDirHistory.Local and Global Directory History
:p.
The directory history can be stored in either a "local" or "global"
list.
:p.
With a local directory history list, any changes made to the list will
only affect the current copy of the command processor.  They will not
be visible in other shells, or other sessions.
:p.
With a global list, all copies of the command processor will share the
same directory history, and any changes made to the list in one copy
will affect all other copies.
:p.
You can control the type of directory history list on the Startup page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, with the
:link reftype=hd refid=INI_LocalDirHistory.LocalDirHistory:elink. directive
in :hp1.&4OS2INI.:ehp1., with the :hp2./L:ehp2. and :hp2./LD:ehp2.
:link reftype=hd refid=Startup.startup options:elink., and with the
:hp2./L:ehp2. and :hp2./LD:ehp2. options of the
:link reftype=hd refid=START.START:elink. command.
:p.
There is no fixed rule for deciding whether to use a local or global
directory 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 setting, then modify it if you find a situation where the default is
not convenient.
:p.
If you select a global directory list, you can share the list among
all copies of the command processor running in any session.  When you
close all &4OS2. sessions, the memory for the global directory history
list is released, and a new, empty list is created the next time you
start &4OS2..
:p.
If you want the list to be retained in memory even when no command processor
session is running, you need to execute the :link reftype=hd
refid=SHRALIAS.SHRALIAS:elink. command, which loads a program to perform this
service for the global command history, directory history, and alias
lists.
:p.
Whenever you start a secondary shell which uses a local directory history
list, it inherits a copy of the directory history from the previous shell.
However, any changes to the list 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 directory history list in both shells.

.* --------------------------------------------------------------------------

:h2 name=MultCmds.Multiple Commands
:p.
You can type several commands on the same command line, separated by an
ampersand [:hp2.&amp.:ehp2.].  For example, if you know you want to copy
all of your :hp1..TXT:ehp1. files to drive A&colon. and then run CHKDSK to
be sure that drive A's file structure is in good shape, you could enter
the following command&colon.
:xmp.
        [c&colon.\] copy *.txt a&colon. &amp. chkdsk a&colon.
:exmp.:p.
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 1023 characters.
:p.
You can use multiple commands in :link reftype=hd refid=alias.alias:elink.
definitions and :link reftype=hd refid=batch.batch files:elink. as well as
from the command line.
:p.
If you don't like using the default command separator, you can pick
another character using the :link reftype=hd refid=SETDOS.SETDOS:elink. /C command or the
:link reftype=hd refid=INI_CommandSep.CommandSep:elink. directive in the :hp1..INI:ehp1. file.  If
you plan to share aliases or batch files between &4OS2. and 4DOS,
4NT, or Take Command, see :link reftype=hd
refid=Compat.Special Character Compatibility:elink. for
details about choosing compatible command separators for two or
more products.

.* --------------------------------------------------------------------------

:h2 name=ExpandAlias.Expanding and Disabling Aliases
:p.
A few command line options are specifically related to :link reftype=hd
refid=ALIAS.aliases:elink., and are documented briefly here for completeness.
:p.
You can expand an alias on the command line and view or edit the results by
pressing :hp2.Ctrl-F:ehp2. before the command is executed.  Doing so is
especially useful when you are developing and debugging a complex alias or
if you want to make sure that an alias that you may have forgotten won't
change the intent of your command.
:p.
At times, you may want to temporarily disable an alias that you have defined.
To do so, precede the command with an asterisk [:hp2.*:ehp2.].  For example,
if you have an alias for DIR which changes the display format, you can use
the following command to bypass the alias and display the directory in the
standard format&colon.
:xmp.
        [c&colon.\] *dir
:exmp.:p.

.* --------------------------------------------------------------------------

:h2 name=CmdLineHelp.Command Line Help
:p.
You can start the online help system at the command line by entering
:hp2.HELP:ehp2. or :hp2.HELP:ehp2. plus a topic, or by pressing the
:hp2.F1:ehp2. key at any time.
:p.
If you have already typed part or all of a command on the line, the help
system will provide "context-sensitive" help by 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 a table of contents and you can
then pick the topic you want.  For example, if you press :hp2.F1:ehp2. after
entering each of the command lines shown below you will get the display
indicated&colon.
:xmp.
        [c&colon.\]                  Topic list / table of contents
        [c&colon.\] copy *.* a&colon.      Help on COPY
        [c&colon.\] c&colon.\util\map      Topic list / table of contents
:exmp.:p.
For quick help you can type the name of any internal command at the prompt,
followed by a slash and a question mark [:hp2./?:ehp2.] like this&colon.
:xmp.
        copy /?
:exmp.:p.
This will show you help for the command in a "quick-reference" style (the
output can be :link reftype=hd refid=RedirPipe.redirected:elink.).  The
:hp2./?:ehp2. 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
:link reftype=hd refid=ExpandAlias.disable alias processing:elink.&colon.
:xmp.
        alias copy copy /r
        *copy /?
:exmp.:p.
:hp2./?:ehp2. 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 :hp2./?:ehp2. parameter
according to its own rules.  Some external commands, including some external
utility programs, do display help when run with a :hp2./?:ehp2. 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.

.* --------------------------------------------------------------------------

:h2 name=CmdLength.Command-Line Length Limits
:p.
When you first enter a command at the prompt or in an
alias or batch file, it can be up to 1,023 characters long.
:p.
As &4OS2. 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 1,023 characters
during the expansion process.  In addition, if you have multiple commands on
a single line, during expansion the entire line can grow to as much as 2,047
characters.  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 a "Command line too long" error and the remainder of the line will not be
executed.

.* --------------------------------------------------------------------------

:h1 name=FileSel.File Selection
:p.
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 and the applications associated with them.
:p.
Most of the features explained in this section apply to &4OS2. commands only,
and can not be used to pass file names to external programs unless
those programs were specifically written to support these features.
:p.
The file selection features are&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=ParDir.Extended Parent Directory Names:elink.
:pt.:pd.:link reftype=hd refid=Wildcards.Wildcards:elink.
:pt.:pd.:link reftype=hd refid=Ranges.Date, Time, and Size Ranges:elink.
:pt.:pd.:link reftype=hd refid=ExclRanges.File Exclusion Ranges:elink.
:pt.:pd.:link reftype=hd refid=MultFiles.Multiple Filenames:elink.
:pt.:pd.:link reftype=hd refid=InclList.Include Lists:elink.
:pt.:pd.:link reftype=hd refid=ExeExt.Executable Extensions:elink.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=ParDir.Extended Parent Directory Names
:p.
&4OS2. allows you to extend the traditional syntax for
naming the parent directory, by adding additional [:hp2..:ehp2.]
characters.  Each additional [:hp2..:ehp2.] represents an additional
directory level above the current directory.  For example,
:hp1..\FILE.DAT:ehp1. refers to a file in the current directory,
:hp1...\FILE.DAT:ehp1. refers to a file one level up (in the parent
directory), and :hp1....\FILE.DAT:ehp1. refers to a file two levels up (in
the parent of the parent directory).  If you are in the
C&colon.\DATA\FINANCE\JANUARY directory and want to copy the file
LETTERS.DAT from the directory C&colon.\DATA to drive A&colon.
:xmp.
        [C&colon.\DATA\FINANCE\JANUARY] copy ...\LETTERS.DAT A&colon.
:exmp.

.* --------------------------------------------------------------------------

:h2 name=Wildcards.Wildcards
:p.
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.
:p.
Wildcards are usually used to specify which files :hp2.should:ehp2. be
processed by a command.  If you need to specify which files should
:hp2.not:ehp2. be processed see
:link reftype=hd refid=ExclRanges.File Exclusion Ranges:elink. (for internal
commands), or :link reftype=hd refid=EXCEPT.EXCEPT:elink. (for external
commands).
:p.
Most internal commands accept filenames with wildcards anywhere that a full
filename can be used.  There are two wildcard characters, the asterisk
[:hp2.*:ehp2.] and the question mark [:hp2.?:ehp2.], plus a special method
of specifying a range of permissible characters.
:p.
An asterisk [:hp2.*:ehp2.] 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&colon.
:xmp.
        [c&colon.\] dir *.*
:exmp.:p.
If you want to see all of the files with a :hp1..TXT:ehp1. extension, you
could type this&colon.
:xmp.
        [c&colon.\] dir *.txt
:exmp.:p.
If you know that the file you are looking for has a base name that
begins with :hp1.ST:ehp1. and an extension that begins with :hp1..D:ehp1., you
can find it this way.  Filenames such as :hp1.STATE.DAT:ehp1.,
:hp1.STEVEN.DOC:ehp1., and :hp1.ST.D:ehp1. will all be displayed&colon.
:xmp.
        [c&colon.\] dir st*.d*
:exmp.:p.
With &4OS2., 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 :hp1..TXT:ehp1. extension that has the
letters :hp1.AM:ehp1. together anywhere inside its base name.  It will,
for example, display :hp1.AMPLE.TXT:ehp1., :hp1.STAMP:ehp1..:hp1.TXT:ehp1.,
:hp1.CLAM:ehp1..:hp1.TXT:ehp1., and :hp1.AM.TXT:ehp1. &colon.
:xmp.
        [c&colon.\] dir *am*.txt
:exmp.:p.
A question mark [:hp2.?:ehp2.] 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 :hp1.LETTER.DOC:ehp1. and :hp1.LATTER.DAT:ehp1., and
:hp1.LITTER.DU:ehp1. &colon.
:xmp.
        [c&colon.\] dir l?tter.d??
:exmp.:p.
The use of an asterisk wildcard before other characters, and of the
character ranges discussed below, are enhancements to the standard
wildcard syntax, and may not work properly with software
other than &4OS2. and Take Command.
:p.
"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 :hp1.LETTER.DOC:ehp1.,:hp1. LETTER1.DOC:ehp1.,
and :hp1.LETTERA.DOC:ehp1., this command will display all three names&colon.
:xmp.
        [c&colon.\] dir letter?.doc
:exmp.:p.
The file :hp1.LETTER.DOC:ehp1. is included in the display because the
"extra" question mark at the end of ":hp1.LETTER?:ehp1. " is ignored when
matching the shorter name :hp1.LETTER:ehp1..
:p.
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 :hp1.LETTER0.DOC:ehp1. through :hp1.LETTER9.DOC:ehp1., you could use this
command&colon.
:xmp.
        [c&colon.\] dir letter[0-9].doc
:exmp.:p.
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&colon.
:xmp.
        [c&colon.\] dir ?[aeiouy]*.*
:exmp.:p.
You can exclude a group of characters or a range of characters by
using an exclamation mark [:hp2.!:ehp2.] as the first character inside the
brackets.  This example displays all filenames that are at least 2
characters long :hp2.except:ehp2. those which have a vowel as the second
letter in their names&colon.
:xmp.
        [c&colon.\] dir ?[!aeiouy]*.*
:exmp.:p.
The next example, which selects files such as :hp1.AIP:ehp1.,:hp1. BIP:ehp1., and
:hp1.TIP:ehp1. but not :hp1.NIP:ehp1., demonstrates how you can use multiple
ranges inside the brackets.  It will accept a file that begins with
an :hp2.A:ehp2., :hp2.B:ehp2., :hp2.C:ehp2., :hp2.D:ehp2., :hp2.T:ehp2., :hp2.U:ehp2., or :hp2.V:ehp2.&colon.
:xmp.
        [c&colon.\] dir [a-dt-v]ip
:exmp.:p.
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 :hp2.not:ehp2. be
discarded when matching shorter filenames.  For example&colon.
:xmp.
        [c&colon.\] dir letter[?].doc
:exmp.:p.
will display :hp1.LETTER1.DOC:ehp1. and :hp1.LETTERA.DOC:ehp1., but not
:hp1.LETTER.DOC.:ehp1.
:p.
A pair of brackets with no characters between them [], or an
exclamation point and question mark together [:hp2.!?:ehp2.], will match only if
there is no character in that position.  For example,
:xmp.
        [c&colon.\] dir letter[].doc
:exmp.:p.
will not display LETTER1.DOC or LETTERA.DOC, but will display
LETTER.DOC.  This is most useful for commands like
:xmp.
        [c&colon.\] dir /I"[]" *.btm
:exmp.:p.
which will display a list of all .BTM files which don't have a
description, because the empty brackets match only an empty description
string (DIR /I selects files to display based on their descriptions).
:p.
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 :hp2.A:ehp2., :hp2.B:ehp2., or :hp2.C:ehp2. as the
third character, followed by zero or more additional characters,
followed by a :hp2.D:ehp2., :hp2.E:ehp2., or :hp2.F:ehp2., followed optionally by some
additional characters, and with an extension beginning with :hp2.P:ehp2.
or :hp2.Q:ehp2..  You probably won't need to do anything this complex, but
we've included it to show you the flexibility of extended
wildcards&colon.
:xmp.
        [c&colon.\] dir ??[abc]*[def]*.[pq]*
:exmp.:p.
You can also use the square bracket wildcard syntax to work around
a conflict between long filenames containing semicolons [:hp2.;:ehp2.],
and the use of a semicolon to indicate an
:link reftype=hd refid=InclList.include list:elink..
For example, if you have a file on an HPFS drive
named :hp1.C&colon.\DATA\LETTER1;V2:ehp1. and you enter this command&colon.
:xmp.
        [c&colon.\] del \data\letter1;v2
:exmp.:p.
you will not get the results you expect.  Instead of deleting the
named file, &4OS2. will attempt to delete :hp1.LETTER1:ehp1. and then
:hp1.V2:ehp1., because the semicolon indicates an
:link reftype=hd refid=InclList.include list:elink..  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
the file named above&colon.
:xmp.
        [c&colon.\] del \data\letter1[;]v2
:exmp.

.* --------------------------------------------------------------------------

:h2 nosearch name=TOC_Ranges.Ranges
:p.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=Ranges.Date, Time, and Size Ranges:elink.
:pt.:pd.:link reftype=hd refid=ExclRanges.File Exclusion Ranges:elink.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h3 name=Ranges.Date, Time, and Size Ranges
:p.
Most internal commands which accept wildcards also allow date,
time, and size ranges to further define the files that you wish to
work with.  &4OS2. will examine each file's size and timestamp (a
record of when the file was created, last modified, or last accessed)
to determine if the file meets the range criteria you have specified.
:p.
(&4OS2. also supports :link reftype=hd refid=ExclRanges.File Exclusion
Ranges:elink. to exclude files from a command.  These are similar to date,
time, and size ranges, but have a slightly different purpose and therefore
are documented separately.)
:p.
A range begins with the switch character (:hp2./:ehp2.),
followed by a left square bracket (":hp2.[:ehp2.") and a character that
specifies the range type&colon.  "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 (":hp2.]:ehp2.").  For example, to select
files between 100 and 200 bytes long you could use the range
:hp2./[s100,200]:ehp2..
:p.
All ranges are inclusive.  For example, a size range which selects files from
10,000 to 20,000 bytes long will match files that are exactly 10,000 bytes and
20,000 bytes long, as well as all sizes in between; a date range that selects
files last modified between 10-27-97 and 10-30-97 will include files modified
on each of those dates, and on the two days in between.
:p.
If you reverse range start and end values the command processor will recognize
the reversal, and will use the second (lower) value as the start point of the
range and the first (higher) value as its end point.    For example, the range
above for files between 100 and 200 bytes long could also be entered as
:hp2./[s200,100]:ehp2..
:p.
See the individual range types for details on specifying ranges&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=DateRanges.Date Ranges:elink.
:pt.:pd.:link reftype=hd refid=TimeRanges.Time Ranges:elink.
:pt.:pd.:link reftype=hd refid=SizeRanges.Size Ranges:elink.
:eparml.:lm margin=1.
.br
:p.
:hp2.Using Ranges:ehp2.
:p.
If you combine two types of ranges, a file must satisfy both ranges
to be included.  For example, :hp2./[d2-8-97,2-9-97] /[s1024,2048]:ehp2.
means files last modified between February 8 and February 9, 1997,
which are also between 1,024 and 2,048 bytes long.
:p.
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.
:p.
For example, to get a directory of all the :hp1.*.C:ehp1. files dated
October 1, 1997, you could use this command&colon.
:xmp.
        [c&colon.\] dir /[d10-1-97,+0] *.c
:exmp.:p.
To delete all of the 0-byte files on your hard disk, you could use
this command&colon.
:xmp.
        [c&colon.\] del /[s0,0] *.* /s
:exmp.:p.
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&colon.
:xmp.
        [c&colon.\] copy /[d-1] /[s1] *.* a&colon.
:exmp.:p.
The HPFS file system maintains 3 sets of dates and times for each
file&colon.  creation, last access, and last write.  By default, date
and time ranges work with the last write time stamp. You can use the
"last access" (a) or "created" (c) time stamp in a date or time range with
the syntax&colon.
:xmp.
        /[da...]  or  /[dc...]  or  /[ta...]  or  /[tc...]
:exmp.:p.
For example, to select files that were last accessed yesterday or today:
:xmp.
        /[da-1]
:exmp.:p.
Date, time, and size ranges can be used with the
:link reftype=hd refid=ATTRIB.ATTRIB:elink., :link reftype=hd refid=COPY.COPY:elink., :link reftype=hd refid=DEL.DEL:elink.,
:link reftype=hd refid=DESCRIBE.DESCRIBE:elink., :link reftype=hd refid=DIR.DIR:elink., :link reftype=hd refid=EXCEPT.EXCEPT:elink.,
:link reftype=hd refid=FFIND.FFIND:elink., :link reftype=hd refid=FOR.FOR:elink., :link reftype=hd refid=LIST.LIST:elink.,
:link reftype=hd refid=MOVE.MOVE:elink., :link reftype=hd refid=RD.RD:elink.,
:link reftype=hd refid=REN.REN:elink., :link reftype=hd refid=SELECT.SELECT:elink., and
:link reftype=hd refid=TYPE.TYPE:elink. commands.  They cannot be used with
filename completion or in filename arguments for variable functions.

.* --------------------------------------------------------------------------

:h4 name=DateRanges.Date Ranges
:p.
Date ranges select files that were created or last modified at any
time between the two dates.  For example, :hp2./[d12-1-97,12-5-97]:ehp2.
selects files that were last modified between December 1, 1997, and
December 5, 1997.
:p.
The time for the starting date defaults to 00&colon.00&colon.00 and the time
for the ending date defaults to 23&colon.59&colon.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 [:hp2.@:ehp2.].  For example, the range
:hp2./[d7-1-97@8&colon.00a,7-3-97@6&colon.00p]:ehp2. selects files that were modified
at any time between 8&colon.00 am on July 1, 1997 and 6&colon.00 pm on July 3,
1997.  If you prefer, you can specify the times in 24-hour format
(:hp1.e.g.:ehp1., @18&colon.00 for the end time in the previous example).
:p.
If you omit the second argument in a date range, &4OS2. substitutes
the current date and time.  For example, :hp2./[d10-1-97]:ehp2. selects
files dated between October 1, 1997 and today.
:p.
You can use an offset value for either the beginning or ending
date, or both.  An offset begins with a plus sign [:hp2.+:ehp2.] or a
minus sign [:hp2.-:ehp2.] 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&colon.
:xmp.
        Specification       Selects Files

        /[d10-27-97,+3]     modified between 10-27-97 and 10-30-97
        /[d10-27-97,-3]     modified between 10-24-97 and 10-27-97
        /[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)
:exmp.:p.
As a shorthand way of specifying files modified today, you can also use
:hp2./[d]:ehp2.; this has the same effect as the :hp2./[d-0]:ehp2.
example shown above.
:p.
To select files last modified :hp2.n:ehp2. days ago or earlier, use
:hp2./[dn,1/1/80]:ehp2..  For example, to get a directory of all files last
modified 3 days or more before today (:hp1.i.e.:ehp1., those files
:hp2.not:ehp2. modified within the last 3 days), you could use this
command&colon.
:xmp.
        [c&colon.\] dir /[d-3,1/1/80]
:exmp.:p.
This reversed date range (with the later date given first) will be handled
correctly by &4OS2..  It takes advantage of the facts that an offset in the
:hp2.start :ehp2.date is relative to today, and that the base or "zero"
point for PC file dates is January 1, 1980.
:p.
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, :hp2./[d12-8-97@12&colon.00,+2@12&colon.00]:ehp2.
selects files that were last modified between noon on December 8 and noon on
December 10, 1997.  Similarly, :hp2./[d-2@15&colon.00,+1]:ehp2. selects files
last modified between 3&colon.00 pm the day before yesterday and the end
of the day one day after that, :hp1.i.e.:ehp1., yesterday.  The second
time defaults to the end of the day because no time is given.
:p.
The HPFS file system maintains 3 sets of dates and times for each file&colon.  creation,
last access, and last write.  By default, date ranges work with
the last write date/time stamp.  You can use the "last access" (a) or
"created" (c) date/time stamp in a date range with the syntax&colon.
:xmp.
        /[da...]  or  /[dc...]
:exmp.:p.
For example, to select files that were last accessed yesterday or
today&colon.
:xmp.
        /[da-1]
:exmp.:p.

.* --------------------------------------------------------------------------

:h4 name=TimeRanges.Time Ranges
:p.
A time range specifies a file modification time without reference
to the date.  For example, to select files modified between noon
and 2&colon.00 pm on any date, use
:hp2./[t12&colon.00p,2&colon.00p]:ehp2..  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.
:p.
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 [:hp2.+:ehp2.] or a minus sign [:hp2.-:ehp2.] for either or both of the
arguments in a time range.  The offset values are interpreted as
minutes.  Some examples&colon.
:xmp.
        Specification       Selects Files

        /[t12&colon.00p,+120]     modified between noon and 2&colon.00 PM on any date
        /[t-120,+120]       modified between two hours ago and the
                            current time on any date
        /[t0&colon.00,11&colon.59]      modified in the morning on any date
:exmp.
The HPFS file system maintains 3 sets of date and time for each file&colon.
creation, last access, and last write.  By default, time ranges work
with the last write time stamp.  You can use the "last access" (a)
or "created" (c) time stamp in a time range with the syntax&colon.
:xmp.
        /[ta...]  or  /[tc...]
:exmp.:p.

.* --------------------------------------------------------------------------

:h4 name=SizeRanges.Size Ranges
:p.
Size ranges simply select files whose size is between the limits
given.  For example, :hp2./[s10000,20000]:ehp2. selects files between
10,000 and 20,000 bytes long.
:p.
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 megabytes (1,048,576
bytes).  For example, the range above could be rewritten as
:hp2./[s10k,20k]:ehp2..
:p.
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.
:p.
The second argument of a size range is optional.  If you use a
single argument, like :hp2./[s10k]:ehp2., you will select files of that
size or larger.  You can also precede the second argument with a
plus sign [:hp2.+:ehp2.]; when you do, it is added to the first value to
determine the largest file size to include in the search.  For
example,  :hp2./[s10k,+1k]:ehp2. select files from 10,000 through 11,000
bytes in size.
:p.
Some further examples of size ranges&colon.
:xmp.
        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
:exmp.

.* --------------------------------------------------------------------------

:h3 name=ExclRanges.File Exclusion Ranges
:p.
Most internal commands which accept wildcards also accept file exclusion
ranges to further define the files that you wish to work with.  &4OS2.
examines each file name and excludes files that match the names you have
specified in a file exclusion range.
:p.
A file exclusion range begins with the switch character (usually a slash),
followed by a left square bracket and an exclamation mark
(":hp2.[!:ehp2.")  The range ends with a right square bracket
(":hp2.]:ehp2.").
:p.
Inside the brackets, you can list one or more filenames to be excluded from
the command.  The filenames can include wildcards and extended wildcards,
but cannot include path names or drive letters.
:p.
The following example will display all files in the current directory except
backup files (files with the extension .BAK or .BKP)&colon.
:xmp.
        [c&colon.\] dir /[!*.bak *.bkp] *.*
:exmp.:p.
You can combine file exclusion ranges with :link reftype=hd
refid=Ranges.date, time, and size ranges:elink.  This example displays all
files that are 10K bytes or larger in size and that were created in the last
7 days, except :hp1..C:ehp1. and :hp1..H:ehp1. files&colon.
:xmp.
        [c&colon.\] dir /[s10k] /[d-7] /[!*.c *.h] *.*
:exmp.:p.
File exclusion ranges will only work for &4OS2. internal commands.  The
:link reftype=hd refid=EXCEPT.EXCEPT:elink. command can be used to exclude
files from processing by many external commands.

.* --------------------------------------------------------------------------

:h2 name=MultFiles.Multiple Filenames
:p.
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 :hp1..TXT:ehp1. and :hp1..DOC:ehp1. files from the current directory to
drive A, you could use this command&colon.
:xmp.
        [c&colon.\] copy *.txt *.doc a&colon.
:exmp.:p.
If the files you want to work with are not in the default
directory, you must include the full path with each filename&colon.
:xmp.
        [c&colon.\] copy a&colon.\details\file1.txt a&colon.\details\file1.doc c&colon.
:exmp.:p.
Multiple filenames are handy when you want to work with 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.
:p.
When you use multiple filenames with a command that expects both
a source and a destination, like COPY or MOVE, :hp8.be sure that you
always include a specific destination on the command line:ehp8..  If you
don't, the command will assume that the last filename is the
destination and may overwrite important files.
:p.
Like :link reftype=hd refid=Wildcards.extended wildcards:elink. and
:link reftype=hd refid=InclList.include lists:elink., multiple filenames
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.
:p.
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
:link reftype=hd refid=FOR.FOR:elink. or
:link reftype=hd refid=SELECT.SELECT:elink. for another way of
passing multiple file names to a command.

.* --------------------------------------------------------------------------

:h2 name=InclList.Include Lists
:p.
Any internal command that accepts :link reftype=hd refid=MultFiles.multiple filenames:elink.
will also accept one or more include lists.  An include list is
simply a group of filenames, with or without wildcards, separated
by semicolons [:hp2.;:ehp2.].  All files in the include list must be in
the same directory.  You may not add a space on either side of the
semicolon.
:p.
For example, you can shorten this command which uses multiple file names&colon.
:xmp.
        [c&colon.\] copy a&colon.\details\file1.txt a&colon.\details\file1.doc c&colon.
:exmp.:p.
to this using an include list&colon.
:xmp.
        [c&colon.\] copy a&colon.\details\file1.txt;file1.doc c&colon.
:exmp.:p.
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 :link reftype=hd refid=COPY.COPY:elink., 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 :hp1.source:ehp1.
parameter - the location files are coming from - for COPY and other similar
commands.  They cannot be used to specify a destination for files.)
:p.
Third, multiple filenames and include lists are processed
differently by the :link reftype=hd refid=DIR.DIR:elink. and :link reftype=hd refid=SELECT.SELECT:elink. 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&colon.
:xmp.
        [c&colon.\] dir *.txt *.doc
:exmp.:p.
will list all the :hp1..TXT:ehp1. 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 :hp1..DOC:ehp1. files.  However,
:xmp.
        [c&colon.\] dir *.txt;*.doc
:exmp.:p.
will display all the files in one list.
:p.

Like :link reftype=hd refid=Wildcards.extended wildcards:elink. and
:link reftype=hd refid=MultFiles.multiple filenames:elink., the
include list feature will work with internal commands, but not with
external programs (unless they have been programmed especially to
support them).  The maximum length of an include list is 260 characters.

.* --------------------------------------------------------------------------

:h2 name=ExeExt.Executable Extensions
:p.
The syntax for creating an executable extension is&colon.
:xmp.
        set .ext=command [options]
:exmp.:p.
This tells &4OS2. to run the specified command whenever you name
a file with the extension :hp2..ext:ehp2. at the prompt.
:p.
:hp1..EXT:ehp1. is the executable file extension; :hp1.command:ehp1. is the
name of the internal command, external program, alias, or batch
file to run; and :hp1.[options]:ehp1. are any command-line startup options
you want to specify for the program, batch file, or alias.
:p.
Normally, when you type a filename (as opposed to an alias or
internal command name) as the first word on the command line, &4OS2.
looks for a file with that name to execute.  The file's extension
may be :hp1..EXE:ehp1. or :hp1..COM:ehp1. to indicate that it contains a
program, it may have a batch file extension like :hp1..BTM:ehp1., or the
file's contents may indicate that it is executable.  (To change the
default list of extensions see the :link reftype=hd
refid=PATHEXT.PATHEXT:elink. environment variable and the :link reftype=hd
refid=INI_PathExt.PathExt:elink. setting in :hp1.&4OS2INI.:ehp1..)
:p.
You can add to the default list of extensions, and have &4OS2. 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 :hp1..DOC:ehp1. file, or start your database
manager whenever you type the name of a :hp1..DAT:ehp1. file.
:p.
You can use environment variables to define the internal command, external
program, batch file, or alias to run for each defined file
extension.  To create an executable extension, use the :link reftype=hd refid=SET.SET:elink.
command to create a new environment variable.  An environment
variable is recognized as an executable extension if its name
begins with a period.
:p.
For example, if you want to run a word processor called :hp1.EDITOR:ehp1.
whenever you type the name of a file that has an extension of
:hp1..EDT:ehp1., you could use this command&colon.
:xmp.
        [c&colon.\] set .edt=c&colon.\edit\editor.exe
:exmp.:p.
If the command specified in an executable extension is a batch file or
external program, &4OS2. 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.
:p.
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.
:p.
The following example defines :hp1.B.EXE:ehp1. (the Boxer text editor)
as the processor for :hp1..MAK:ehp1. files&colon.
:xmp.
        [c&colon.\] set .mak=c&colon.\boxer\b.exe -s
:exmp.:p.
With this definition, if you have a file named :hp1.INIT.MAK:ehp1. in
the current directory and enter the command&colon.
:xmp.
        [c&colon.\source] init
:exmp.:p.
&4OS2. will execute the command&colon.
:xmp.
        c&colon.\boxer\b.exe -s c&colon.\source\init.mak
:exmp.:p.
Notice that the full pathname of :hp1.INIT.MAK:ehp1. is automatically
included.  If you enter parameters on the command line, they are appended
to the end of the command.  For example, if you changed the above entry
to&colon.
:xmp.
        [c&colon.\source] init -w
:exmp.:p.
the command processor would execute the command&colon.
:xmp.
        c&colon.\boxer\b.exe -s c&colon.\source\init.mak -w
:exmp.:p.
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.
:p.
Executable extensions may include
:link reftype=hd refid=Wildcards.wildcards:elink., so you could, for
example, run your text editor for any file with an extension
beginning with :hp2.T:ehp2. by defining an executable extension called
:hp1..T*:ehp1..  Extended wildcards (:hp1.e.g.:ehp1., :hp2.DO[CT]:ehp2.
for .DOC and .DOT files) may also be used.
:p.
The search for executable files starts in the current directory, then
proceeds to each subdirectory specified by the
:link reftype=hd refid=PATH_Var.PATH:elink. environment variable
(if a "." is used in the PATH the current directory is :hp2.not:ehp2.
searched first; see the :link reftype=hd refid=PATH.PATH:elink.
command for details).
:p.
You may need to take this search order into account when using executable
extensions.  Using the :hp1..MAK:ehp1. example above, if you had a file named
:hp1.FORMAT.MAK:ehp1. in the current directory and entered the command
FORMAT A&colon., your command would run the Boxer editor specified by the
executable extension, instead of finding the standard OS/2 FORMAT command as
you perhaps intended.  You can get around this by remembering that the OS/2
FORMAT command is in the file :hp1.FORMAT.COM:ehp1..  If you entered the
command FORMAT.COM A&colon. then the :hp1..MAK:ehp1. executable extension
would not be checked, and the search would continue until it found the
:hp1.FORMAT.COM:ehp1. file.
:p.
To remove an executable extension, use the :link reftype=hd
refid=UNSET.UNSET:elink. command to remove the corresponding variable.

.* --------------------------------------------------------------------------

:h1 name=DirNav.Directory Navigation
:p.
The operating system and command processor remember both a :hp2.current:ehp2.
or :hp2.default drive:ehp2. for your system as a whole, and a
:hp2.current:ehp2. or :hp2.default directory:ehp2. for every drive in your
system.  The current directory on the current drive is sometimes called the
:hp2.current working directory:ehp2..
:p.
With traditional command processors, you change the current drive by typing
the new drive letter plus a colon at the prompt, and you change the current
working directory with the CD command.  &4OS2. supports those standard
features, and offer a number of enhancements to make directory navigation
much simpler and faster.
:p.
The &4OS2. directory navigation features are in three groups&colon.  features
which help the command processor find the directory you want, methods for
initiating a directory change with a minimal amount of typing, and methods
for returning easily to directories you've recently used.  Each group is
summarized below.
:p.
:p.
:hp2.Finding Directories:ehp2.
:p.
Traditional command processors require you to explicitly type the name of the
directory you want to change to.  &4OS2. support this method, and also offer
two significant enhancements&colon.
:p.
:lm margin=4.:parml tsize=4 break=fit.
:pt.*:pd.:hp2.:link reftype=hd refid=ExtDirSearch.Extended Directory
Searches:elink.:ehp2. allow the command processor to search a "database" of
all the directories on your system to find the one you want.
:pt.*:pd.The :hp2.:link reftype=hd refid=CDPATH.CDPATH:elink.:ehp2. allows
you to enter a specific list of directories to be searched, rather than
searching a database.  Use CDPATH instead of Extended Directory Searches if
you find the extended searches too broad, or your hard drive has too many
directories for an efficient search.
:eparml.:lm margin=1.
.br
:p.
:hp2.Initiating a Directory Change:ehp2.
:p.
&4OS2. supports the traditional methods of changing directories, and also
offers several more flexible approaches&colon.
:p.
:lm margin=4.:parml tsize=4 break=fit.
:pt.*:pd.:hp2.:link reftype=hd refid=AutoDir. Automatic directory changes:elink.:ehp2.
allow you to type a directory name at the prompt and switch to it
automatically, without typing an explicit CD or similar command.
:pt.*:pd.The :hp2.:link reftype=hd refid=CD.CD:elink. command:ehp2. can
change directories on a single drive, and can return to the most recently
used directory.
:pt.*:pd.The :hp2.:link reftype=hd refid=CDD.CDD:elink. command:ehp2. changes
drive and directory at the same time, and can return to the most recently
used drive and directory.
:pt.*:pd.The :hp2.:link reftype=hd refid=PUSHD.PUSHD:elink. command:ehp2.
changes changes the drive and directory like CDD, and records the previous
directory in a directory "stack."  You can view the stack with
:link reftype=hd refid=DIRS.DIRS:elink. and return to the directory on the
top of the stack with :link reftype=hd refid=POPD.POPD:elink..
:eparml.:lm margin=1.
.br
:p.
CDD, PUSHD, and automatic directory changes can also change to a network
drive and directory mapped to a drive letter or specified with a UNC name
(see :link reftype=hd refid=FileSys.File Systems:elink. for more information
about network directories).
:p.
:p.
:hp2. Returning to a Previous Directory:ehp2.
:p.
Traditional command processors do not remember previously-used directories,
and can only "return" to a directory by changing back to it with a standard
drive change or CD command.  &4OS2. supports three additional methods for
returning to a previous directory&colon.
:p.
:lm margin=4.:parml tsize=4 break=fit.
:pt.*:pd.The :hp2.:link reftype=hd refid=CD.CD -:elink.:ehp2. and
:hp2.:link reftype=hd refid=CDD.CDD -:elink.:ehp2. commands can be used
to return to the previous working directory (the one you used immediately
before the current directory).  Use these commands if you are working in two
directories and alternating between them.
:pt.*:pd.The :hp2.:link reftype=hd refid=DirHist.directory history window:elink.:ehp2.
allows you to select one of several recently-used directories from a popup
list and return to it immediately.  The window displays the contents of the
directory history list.
:pt.*:pd.The :hp2.:link reftype=hd refid=POPD.POPD:elink. command:ehp2. will
return to the last directory saved by :link reftype=hd refid=PUSHD.PUSHD:elink..
The directory stack holds 511 characters, enough for 20 to 40 typical drive
and directory entries.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=ExtDirSearch.Extended Directory Searches
:p.
When you change directories with an
:link reftype=hd refid=AutoDir.automatic directory change:elink.,
:link reftype=hd refid=CD.CD:elink., :link reftype=hd refid=CDD.CDD:elink., or
:link reftype=hd refid=PUSHD.PUSHD:elink. command, &4OS2. must find the
directory you want to change to.  To do so, the command processor first uses
the traditional method to find a new directory&colon.  it checks to see
whether you have specified either the name of an existing subdirectory below
the current directory, or the name of an existing directory with a full path
or a drive letter.  If you have, the command processor changes to that
directory, and does no further searching.
:p.
This traditional search method requires that you navigate manually through
the directory tree, and type the entire name of each directory you want to
change to.  Extended Directory Searches speed up the navigation process
dramatically by allowing the command processor to find the directory you
want, even if you only enter a small part of its name.
:p.
When the traditional search method fails, &4OS2. try to find the directory you
requested via the :link reftype=hd refid=CDPATH.CDPATH:elink., then via an
Extended Directory Search.  This section covers only Extended Directory
Searches, which are more flexible and more commonly used than CDPATH.
:p.
Extended Directory Searches use a database of directory names to facilitate
changing to the correct directory.  The database is used only if Extended
Directory Searches are enabled, and if the explicit directory search and
CDPATH search fail to find the directory you requested.
:p.
An extended directory search automatically finds the correct path to the
requested directory and changes to it if that directory exists in your
directory database.  If more than one directory in the database matches the
name you have typed, a popup window appears and you can choose the directory
you want.
:p.
You can control the color, position and size of the popup directory search
window from the Command line 2 page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, or with directives in
the :hp1..INI:ehp1. file, including
:link reftype=hd refid=INI_CDDWinLeft.CDDWinLeft, CDDWinTop, CDDWinWidth,
and CDDWinHeight:elink., and
:link reftype=hd refid=INI_CDDWinColors.CDDWinColors:elink..  You can also
change the keys used in the popup window with :link reftype=hd
refid=INIKeyMap.key mapping directives:elink. in :hp1.&4OS2INI.:ehp1..
:p.
To use extended directory searches, you must explicitly enable them and also
create the directory database.
:p.
:p.
:hp2.The Extended Search Database:ehp2.
:p.
To create or update the database of directory names, use the
:link reftype=hd refid=CDD.CDD:elink. /S command.  When you create the
database with CDD /S, you can specify which drives should be included.  If
you enable Extended Directory Searches and do not create the database, it
will be created automatically the first time it is required, and will include
all local hard drives.
:p.
The database is stored in the file :hp1.JPSTREE.IDX:ehp1., which is placed in
the root directory of drive C&colon. by default.  The same tree file is used
by all JP Software command processors.  You can specify a different location
for this file on the Command Line 2 page of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs, or with the :link reftype=hd
refid=INI_TreePath.TreePath:elink. :hp1..INI:ehp1.
directive.  If you are using 2 or more of our products on your computer and
want to have different drives stored in the database for each, use the dialogs
or the TreePath directive to place their database directories in different
locations.
:p.
If you use an internal &4OS2. command to create or delete a directory, the
directory database is automatically updated to reflect the change to your
directory structure.  The updates occur if the command processor can find the
:hp1.JPSTREE.IDX:ehp1. file in the root directory of drive C&colon. or in the
location specified by the TreePath :hp1..INI:ehp1. directive.
:p.
The internal commands which can modify the directory structure and cause
automatic updates of the file are :link reftype=hd refid=MD.MD:elink.,
:link reftype=hd refid=RD.RD:elink.,
:link reftype=hd refid=COPY.COPY /S:elink.,
:link reftype=hd refid=DEL.DEL /X:elink.,
:link reftype=hd refid=MOVE.MOVE /S:elink., and
:link reftype=hd refid=REN.REN:elink..
The :hp2.MD /N:ehp2. command can be used to create a directory without
updating the directory database.  This is useful when creating a temporary
directory which you do not want to appear in the database.
:p.
:p.
:hp2.Enabling Extended Searches:ehp2.
:p.
To enable extended directory searches and control their operation, you must
set the :link reftype=hd refid=INI_FuzzyCD.FuzzyCD:elink. directive
in the :hp1..INI:ehp1. file.  You can set FuzzyCD with the Search Level
option on the Command Line 2 page of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs, or by editing the :hp1..INI:ehp1. file
manually.
:p.
:lm margin=8.
If :hp2.FuzzyCD = 0:ehp2., extended searches are disabled, the
:hp1.JPSTREE:ehp1. database is ignored, and :hp2.CD:ehp2., :hp2.CDD:ehp2.,
:hp2.PUSHD:ehp2., and automatic directory changes search for directories
using only explicit names and CDPATH.  This is the default.
:p.
If :hp2.FuzzyCD = 1:ehp2. and an extended search is required, then the
command processor will search the :hp1.JPSTREE:ehp1. database for directory
names which :hp2.exactly match:ehp2. the name you specified.
:p.
If :hp2.FuzzyCD = 2:ehp2. and an extended search is required, the command
processor will search the database for exact matches first, just as when
FuzzyCD = 1.  If the requested directory is not found, it will search the
database a second time looking for directory names that :hp2.begin with:ehp2.
the name you specified.
:p.
If :hp2.FuzzyCD = 3:ehp2. and an extended search is required, the command
processor will search the database for exact matches first, just as when
FuzzyCD = 1.  If the requested directory is not found, it will search the
database a second time looking for directory names that :hp2.contain:ehp2.
the name you specified anywhere within them.
:lm margin=1.
:p.
For example, suppose that you have a directory called
:hp1.C&colon.\DATA\MYDIR:ehp1., CDPATH is not set, and
:hp1.C&colon.\DATA:ehp1. is :hp2.not:ehp2. the current directory on drive
C&colon..  The following chart shows what CDD command you might use to change
to this directory.
:p.
:lm margin=8.:parml tsize=12 compact break=fit.
:pt.FuzzyCD:pd.
:pt.Setting:pd.CDD Command
.br
:pt.  0:pd.[c&colon.\] cdd c&colon.\data\mydir
:pt.  1:pd.[c&colon.\] cdd mydir
:pt.  2:pd.[c&colon.\] cdd myd
:pt.  3:pd.[c&colon.\] cdd yd
:eparml.:lm margin=1.
.br
An extended directory search is not used if you specify a full directory path
(one beginning with a backslash [:hp2.\:ehp2.], or a drive letter and a
backslash).  If you use a name which begins with a drive letter
(:hp1.e.g. C&colon.MYDIR:ehp1. ), the extended search will examine only
directories on that drive.
:p.
:p.
:hp2.Forcing an Extended Search with Wildcards:ehp2.
:p.
Normally you type a specific directory name for the command processor to
locate, and the search proceeds as described in the preceding sections.
However, you can also force the command processor to perform an extended
directory search by using
:link reftype=hd refid=Wildcards.wildcard characters:elink. in the directory
name.  If you use a wildcard, an extended search will occur whether or not
extended searches have been enabled.
:p.
When &4OS2. is changing directories and it finds wildcards in the directory
name, it skips the explicit search and
:link reftype=hd refid=CDPATH.CDPATH:elink. steps and goes directly to the
extended search.
:p.
If a single match is found, the change is made immediately.  If more than one
match is found, a popup window is displayed with all matching directories.
:p.
Wildcards can only be used in the final directory name in the path (after the
last backslash in the path name).  For example you can find
:hp1.COMM\*A*.*:ehp1. (all directories whose parent directory is COMM and
which have an A somewhere in their names), but you cannot find
:hp1.CO?M\*A*.*:ehp1. because it uses a wildcard before the last backslash.
:p.
If you use wildcards in the directory name as described here, and the
extended directory search database does not exist, it will be built
automatically the first time a wildcard is used.  You can update the
database at any time with :link reftype=hd refid=CDD.CDD:elink. /S.
:p.
Internally, extended directory searches use wildcards to scan the directory
database.  If FuzzyCD is set to 2, an extended search looks for the name you
typed followed by an asterisk (:hp1.i.e.:ehp1. :hp1.DIRNAME*:ehp1.).  If
FuzzyCD is set to 3, it looks for the name preceded and followed by an
asterisk (:hp1.i.e. *DIRNAME*:ehp1.).
:p.
These internal wildcards will be used in addition to any wildcards you use in
the name.  For example if you search for :hp1.ABC?DEF:ehp1. (ABC followed by
any character followed by DEF) and FuzzyCD is set to 3, the command processor
will actually search the directory database for :hp1.*ABC?DEF*:ehp1..
:p.
:p.
:hp2.Disabling Extended Searches in Batch Files:ehp2.
:p.
When writing batch files you may want to use the :link reftype=hd
refid=CD.CD:elink. or :link reftype=hd refid=CDD.CDD:elink. command to
switch directories without triggering an extended search.  For example,
you may need the search to fail (rather than search the extended search
database) if a directory does not exist, or you may want to ensure that
the extended search popup window does not appear in a batch file
designed to run in unattended mode.
:p.
To disable extended searches, use the :hp2./N:ehp2. option of CD or CDD.  When
this option is used and a directory does not exist below the current
directory or on the CDPATH, the command will fail with an error message,
and will not search the extended search database.  For example this
command might trigger an extended search&colon.
:xmp.
     cdd testdir
:exmp.:p.
but this one will not&colon.
:xmp.
     cdd /n testdir
:exmp.:p.
Note that this option is not available for :link reftype=hd
refid=PUSHD.PUSHD:elink..  To perform the same function when using PUSHD,
save the current directory with PUSHD (without parameters) and then use
CDD /N to change directories, for example&colon.
:xmp.
     pushd
     cdd /n testdir
:exmp.

.* --------------------------------------------------------------------------

:h2 name=CDPATH.CDPATH
:p.
When you change directories with an
:link reftype=hd refid=AutoDir.automatic directory change:elink.,
:link reftype=hd refid=CD.CD:elink., :link reftype=hd refid=CDD.CDD:elink., or
:link reftype=hd refid=PUSHD.PUSHD:elink. command, &4OS2. must find the
directory you want to change to.  To do so, the command processor first uses
the traditional method to find a new directory.
:p.
When the traditional search method fails, &4OS2. tries to find
the directory you requested via the CDPATH, then via an
:link reftype=hd refid=ExtDirSearch.Extended Directory
Search:elink..  This section covers only the CDPATH.
:p.
Enabling both CDPATH and Extended Directory Searches can yield confusing
results, so we recommend that you do not use both features at the same time.
If you prefer to explicitly list where the command processor should look for
directories, use CDPATH.  If you prefer to have the command processor look at
all of the directory names on your disk, use Extended Directory Searches.
:p.
CDPATH is an environment variable, and is similar to the
:link reftype=hd refid=PATH_Var.PATH:elink. variable used to search for
executable files&colon.  it contains an explicit list of directories to
search when attempting to find a new directory.  The command processor
appends the specified directory name to each directory in CDPATH and
attempts to change to that drive and directory.  It stops when it finds a
match or when it reaches the end of the CDPATH list.
:p.
CDPATH is ignored if a complete directory name (one beginning with a
backslash [:hp2. \:ehp2.]) is specified, or if a drive letter is included
in the name.  It is only used when a name is given with no drive letter or
leading backslash.
:p.
CDPATH provides a quick way to find commonly used subdirectories in an
explicit list of locations.  You can create CDPATH with the
:link reftype=hd refid=SET.SET:elink. command.  The format of CDPATH is
similar to that of PATH&colon.  a list of directories separated by semicolons
[:hp2.;:ehp2.].  For example, if you want the directory change commands to
search the :hp1.C&colon.\DATA:ehp1. directory, the
:hp1.D&colon.\SOFTWARE:ehp1. directory, and the root directory of drive
E&colon.\ for the subdirectories that you name, you
should create CDPATH with this command&colon.
:xmp.
        [c&colon.\] set cdpath=c&colon.\data;d&colon.\software;e&colon.\
:exmp.:p.
Suppose you are currently in the directory
:hp1.C&colon.\WP\LETTERS\JANUARY:ehp1., and you'd like to change to
:hp1.D&colon.\SOFTWARE\UTIL:ehp1..  You could change directories
explicitly with the command&colon.
:xmp.
        [c&colon.\wp\letters\january] cdd d&colon.\software\util
:exmp.:p.
However, because the :hp1.D&colon.\SOFTWARE:ehp1. directory is listed in your
CDPATH variable as shown in the previous example (we'll assume it is the first
directory in the list with a UTIL subdirectory), you can simply enter the
command
:xmp.
        [c&colon.\wp\letters\january] cdd util
:exmp.:p.
or, using an automatic directory change&colon.
:p.
:xmp.
        [c&colon.\wp\letters\january] util\
:exmp.:p.
to change to :hp1.D&colon.\SOFTWARE\UTIL:ehp1..
:p.
As it handles this request, the command processor looks first in the current
directory, and attempts to find the :hp1.C&colon.\WP\LETTERS\JANUARY\UTIL:ehp1.
subdirectory.  Then it looks at CDPATH, and appends the name you entered,
:hp1.UTIL:ehp1., to each entry in the CDPATH variable -- in other words, it
tries to change to :hp1.C&colon.\DATA\UTIL:ehp1., then to
:hp1.D&colon.\SOFTWARE\UTIL:ehp1..  Because this change succeeds, the search
stops and the directory change is complete.

.* --------------------------------------------------------------------------

:h1 nosearch name=TOC_Other.Other Features
:p.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=Prompts.Page and File Prompts:elink.
:pt.:pd.:link reftype=hd refid=RedirPipe.Redirection and Piping:elink.
:pt.:pd.:link reftype=hd refid=KeystackUse.Using the Keystack:elink.
:pt.:pd.:link reftype=hd refid=WaitForApps.Waiting for Applications to Finish:elink.
:pt.:pd.:link reftype=hd refid=CritErr.Critical Errors:elink.
:pt.:pd.:link reftype=hd refid=Conditional.Conditional Commands:elink.
:pt.:pd.:link reftype=hd refid=Grouping.Command Grouping:elink.
:pt.:pd.:link reftype=hd refid=Escape.Escape Character:elink.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=Prompts.Page and File Prompts
:p.
Several &4OS2. commands can generate prompts, which wait for you to
press a key to view a new page or to perform a file activity.
:p.
When &4OS2. is displaying information in page mode, for example with
a DIR /P or SET /P command, it displays the message
:xmp.
        Press Esc to Quit or any other key to continue...
:exmp.:p.
At this prompt, you can press :hp2.Esc:ehp2., :hp2.Ctrl-C:ehp2., or :hp2.Ctrl-
Break:ehp2. 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.
:p.
During file processing, if you have activated prompting with a
command like DEL /P, you will see this prompt before processing
every file&colon.
:xmp.
        Y/N/R ?
:exmp.:p.
You can answer this prompt by pressing :hp2.Y:ehp2. for ":hp2.Y:ehp2.es,
process this file;"  :hp2.N:ehp2. for ":hp2.N:ehp2.o, do not process this
file;" :hp2.R:ehp2. for "process the :hp2.R:ehp2.emainder of the files
without further prompting."  You can also press :hp2.Ctrl-C:ehp2.,
:hp2.Ctrl-Break:ehp2., or :hp2.Esc:ehp2. at this prompt to cancel the
remainder of the command.

.* --------------------------------------------------------------------------

:h2 name=RedirPipe.Redirection and Piping
:p.
This section covers :hp2.redirection:ehp2. and :hp2.piping:ehp2..  You
can use these features to change how &4OS2. and some application programs
handle input and output.
:p.
Internal commands and many external programs get their input from the
computer's :hp2.standard input:ehp2. device and send their output to the
:hp2.standard output:ehp2. device.  Some programs also send special messages
to the :hp2.standard error:ehp2. device.  Normally, the keyboard is used for
standard input and the video screen for both standard output and standard
error.
:p.
Redirection and piping allow you to change these assignments temporarily.
:p.
:link reftype=hd refid=Redirection.Redirection:elink. changes the standard
input, standard output, or standard error device for a program or command
from the default device (the keyboard or screen), to another device or to a
file.
:p.
:link reftype=hd refid=Piping.Piping:elink. changes the standard output and
/ or standard error device so that the output of one command becomes the
standard input for another program or command.

.* --------------------------------------------------------------------------

:h3 name=Redirection.Redirection
:p.
Redirection can be used to reassign the :hp2.standard input:ehp2.,
:hp2.standard output:ehp2., and :hp2.standard error:ehp2. devices from
their default settings (the keyboard and screen) to another device like the
printer or serial port, to a file, or to the clipboard.  You must use some
discretion when you use redirection with a device; there is no way to get
input from the printer, for example.
:p.
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.
:p.
In the descriptions below, :hp2.filename:ehp2. 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; CLIP&colon.
for the clipboard; NUL for the "null" device, etc.).
:p.
Here are the standard redirection options supported by &4OS2. (see below
for additional redirection options using numeric file handles)&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:hp2.< filename:ehp2.:pd.To get input from a file or device instead
of from the keyboard
:pt.:hp2.> filename:ehp2.:pd.Redirect standard output to a file or device
:pt.:hp2.>&amp. filename:ehp2.:pd.Redirect standard output and standard
error to a file or device
:pt.:hp2.>&amp.> filename:ehp2.:pd.Redirect standard error only to a
file or device
:eparml.:lm margin=1.
.br
If you want to append output to the end of an existing file, rather than
creating a new file, replace the first ":hp2.>:ehp2." in the last three
commands above with ":hp2.>>:ehp2." (:hp1.i.e.:ehp1., use :hp2.>>:ehp2.,
:hp2.>>&amp.:ehp2., and :hp2.>>&amp.>:ehp2.).
:p.
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 :hp1.DIRLIST:ehp1., you could use a command line like
this&colon.
:xmp.
        [c&colon.\] dir /b *.dat > dirlist
:exmp.:p.
You can use both input and output redirection for the same command,
if both are appropriate&colon.  For example, this command sends input to
SORT from the file :hp1.DIRLIST:ehp1., and sends output from SORT to the file
:hp1.DIRLIST.SRT:ehp1.&colon.
:xmp.
        [c&colon.\] sort < dirlist > dirlist.srt
:exmp.:p.
You can redirect text to or from the OS/2 clipboard by using the
pseudo-device name :hp2.CLIP&colon.:ehp2. (the colon is required).
:p.
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
:link reftype=hd refid=Grouping.command group:elink., all of the output from
the command group is redirected, and redirection ends when the command group
is done.
:p.
When output is directed to a file with :hp2.>:ehp2., :hp2.>&amp.:ehp2., or
:hp2.>&amp.>:ehp2., if the file already exists, it will be overwritten.  You
can protect existing files by using the
:link reftype=hd refid=SETDOS.SETDOS:elink. /N1 command, the "Protect
redirected output files" setting available on the Options 1 page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, or the
:link reftype=hd refid=INI_NoClobber.NoClobber:elink. directive in the
:hp1..INI:ehp1. file.
:p.
When output is appended to a file with :hp2.>>:ehp2., :hp2.>>&amp.:ehp2., or
:hp2.>>&amp.>:ehp2., the file will be created if it doesn't already
exist.  However, if NoClobber is set as described in the above,
append redirection will not create a new file; instead, if the output file
does not exist a "File not found" or similar error will be displayed.
:p.
You can temporarily override the current setting of NoClobber by
using an exclamation mark [:hp2.!:ehp2.] after the redirection symbol.
For example, to redirect the output of DIR to the file :hp1.DIROUT:ehp1.,
and allow overwriting of any existing file despite the NoClobber
setting&colon.
:xmp.
        [c&colon.\] dir >! dirout
:exmp.:p.
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.
:p.
You can use redirection if you need to create a zero-byte file.  To
do so, enter :hp2.>filename:ehp2. as a command, with no actual command
before the :hp2.>:ehp2. character.
:p.
In addition to the standard redirection options above, &4OS2. also supports the
OS/2 :hp1.CMD.EXE:ehp1. syntax&colon.
:lm margin=8.:parml compact tsize=12 break=fit.
:pt.:hp2.n>file:ehp2.:pd.Redirect handle :hp2.n:ehp2. to the named file
:pt.:hp2.n>&amp.m:ehp2.:pd.Redirect handle :hp2.n:ehp2. to the same place as
handle :hp2.m:ehp2.
:eparml.:lm margin=1.
.br
[:hp2.n:ehp2.] and [:hp2.m:ehp2.] are one-digit file handles between 0 and
9.  You may not put any spaces between the :hp2.n:ehp2. and the :hp2.>:ehp2.,
or between the :hp2.>:ehp2., :hp2.&amp.:ehp2., and :hp2.m:ehp2. in the
second form. OS/2 interprets "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 you have opened a file with the
%:link reftype=hd refid=_@FILEOPEN.@FILEOPEN:elink. variable function and
the file handle is between 3 and 9.
:p.
The :hp2.n>file:ehp2. syntax redirects output from handle :hp2.n:ehp2. to a
file.  You can use this form to redirect two handles to different places.  For
example&colon.
:xmp.
        [c&colon.\] dir > outfile 2> errfil
:exmp.:p.
sends normal output to a file called :hp1.OUTFILE:ehp1. and any error messages
to a file called :hp1.ERRFILE:ehp1..
:p.
The :hp2.n>&amp.m:ehp2. syntax redirects handle :hp2.n:ehp2. to the same
location as the previously assigned handle :hp2.m:ehp2..  For example, to
send standard error to the same file as standard output, you could use this
command&colon.
:xmp.
        [c&colon.\] .dir > outfile 2>&amp.1
:exmp.:p.
Notice that you can perform the same operations by using standard &4OS2.
redirection features.  The two examples above could be written as
:xmp.
        [c&colon.\] dir > outfile >&amp.> errfile
:exmp.:p.
and
:xmp.
        [c&colon.\] dir >&amp.outfile
:exmp.:p.

.* --------------------------------------------------------------------------

:h3 name=Piping.Piping
:p.
You can create a "pipe" to send the standard output of one command
to the standard input of another command&colon.
:lm margin=8.:parml compact tsize=32 break=fit.
:pt.:hp2.command1 &splitvbar. command2:ehp2.:pd.Send the standard
output of :hp1.command1:ehp1. to the standard input of :hp1.command2:ehp1.
:pt.:hp2.command1 &splitvbar.&amp. command2:ehp2.:pd.Send the standard output
and standard error of :hp1.command1:ehp1. to the standard input of :hp1.command2:ehp1.
:eparml.:lm margin=1.
.br
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&colon.
:xmp.
        [c&colon.\] set &splitvbar. sort
:exmp.:p.
To do the same thing and then pipe the sorted list to the internal
:link reftype=hd refid=LIST.LIST:elink. command for full-screen viewing&colon.
:xmp.
        [c&colon.\] set &splitvbar. sort &splitvbar. list
:exmp.:p.
The :link reftype=hd refid=TEE.TEE:elink. and :link reftype=hd refid=Y.Y:elink. commands are "pipe fittings" which
add more flexibility to pipes.
:p.
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.
:p.
&4OS2. implements pipes by starting a new process for 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 ends automatically.
:p.
When you use pipes with &4OS2. make sure you think about any possible
consequences that can occur from using a separate process to run
the receiving program.

.* --------------------------------------------------------------------------

:h2 name=KeystackUse.Using the Keystack
:p.
The Keystack overcomes two weaknesses of input redirection&colon.  some
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.
:p.
The 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 :link reftype=hd
refid=KEYSTACK.KEYSTACK:elink. command.
:p.
KEYSTACK depends on a program called :hp1.KEYSTACK.EXE:ehp1..  This file
must be in the same directory as :hp1.&4OS2..EXE:ehp1., or in a directory
listed in your :link reftype=hd refid=PATH_Var.PATH:elink..  You don't have to
take any special action to activate :hp1.KEYSTACK.EXE:ehp1.; &4OS2. will run
it automatically when you use the KEYSTACK command.  If &4OS2. cannot
find :hp1.KEYSTACK.EXE:ehp1., the KEYSTACK command will display an error
message.
:p.
To place the letters, digits, and punctuation marks you would normally type
for your program into the keystack, enclose them in double quotes&colon.
:xmp.
        [c&colon.\] keystack "myfile"
:exmp.:p.
Many other keys can be entered into the Keystack using their names.  This
example puts the :hp2.F1:ehp2. key followed by the :hp2.Enter:ehp2. key in the
keystack&colon.
:xmp.
        [c&colon.\] keystack F1 Enter
:exmp.:p.
See :link reftype=hd refid=KeyNames.Keys and Key Names:elink. for details on
how key names are entered.  See the
:link reftype=hd refid=KEYSTACK.KEYSTACK:elink. command for
information on using numeric key values along with or instead of key names,
and other details about using the Keystack.
:p.
The following command creates an :link reftype=hd refid=ALIAS.alias:elink.
that will run a FoxPro report called :hp1.TIMEREP:ehp1. (it should be entered
on one line)&colon.
:xmp.
        [c&colon.\] alias timerep `keystack "use times index times" Enter
              "report form timerep to print" Enter "quit" Enter &amp. foxpro`
:exmp.:p.
This command creates an alias called :hp2.timerep:ehp2. which puts the
following characters on the keystack&colon.
:p.
:lm margin=8.
the characters ":hp2.use times index times:ehp2."
the Enter key's code
the characters ":hp2.report form timerep to print:ehp2."
the Enter key's code
the characters ":hp2.quit:ehp2."
and one more Enter key
:lm margin=1.
:p.
The alias then runs the program :hp1.FOXPRO:ehp1. which receives those
characters just as if you had typed them.
:p.
When you use the Keystack, remember that you must put the keystrokes into the
Keystack :hp2.before:ehp2. you run the program that will receive them.  The
Keystack will hold the keystrokes until the program asks for them.

.* --------------------------------------------------------------------------

:h2 name=WaitForApps.Waiting for Applications to Finish
:p.
When you start an OS/2 Presentation Manager application from the prompt, the
command processor does not normally wait for the application to finish
before returning to the prompt. This default behavior allows you to continue
your work at the prompt while the application is running.  You can force
&4OS2. to wait for applications to finish before continuing by selecting the
"Wait for Completion" option on the Options 2 page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, with the :link
reftype=hd refid=INI_ExecWait.ExecWait:elink.
directive in the :hp1..INI:ehp1. file, or with the :link reftype=hd
refid=START.START:elink. command's :hp2./WAIT:ehp2. switch (you can also use
START to control many other aspects of how your applications are started).
:p.
Regardless of the ExecWait setting, &4OS2. always waits for applications which
are run from batch files before continuing with subsequent commands in the
batch file.  To start an application from a batch file and continue with the
batch file immediately, without waiting for the application to finish, use
the :link reftype=hd refid=START.START:elink. command (without the
:hp2./WAIT:ehp2. switch).

.* --------------------------------------------------------------------------

:h2 name=CritErr.Critical Errors
:p.
OS/2 watches 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.
:p.
These errors are called :hp2.critical errors:ehp2. because OS/2, &4OS2., or
your application program cannot proceed until the error is resolved.
:p.
When a critical error occurs, you will see a popup window asking you to
choose one of four error handling options.  The message comes from
OS/2 or &4OS2., and will vary slightly depending on whether you are in
full-screen or windowed mode.  You can respond with a mouse click or menu
selection.  The options and their meanings are similar in all cases&colon.
:lm margin=8.:parml tsize=12 break=fit.
:pt.:hp2.Return error code to program:ehp2..  Tell the program that
the operation failed.  This option returns an error code to &4OS2. or to
the application program that was running when the error occurred.  &4OS2.
generally stops the current command when an operation fails.
:pt.:hp2.End program/command/operation:ehp2..  Choose this option to
stop the program that was running when the error occurred and abort &4OS2..
:pt.:hp2.Retry command or operation:ehp2..  Choose this option if you have
corrected the problem.
:pt.:hp2.Display help:ehp2..  Display further information on the error.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=Conditional.Conditional Commands
:p.
When an internal command or external program finished, 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.
:p.
If you separate two commands by :hp2.&amp.&amp.:ehp2. (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&colon.
:xmp.
        [c&colon.\] backup c&colon.\ a&colon. &amp.&amp. del c&colon.\*.bak;*.lst
:exmp.:p.
If you separate two commands by :hp2.&splitvbar.&splitvbar.:ehp2. (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&colon.
:xmp.
        [c&colon.\] backup c&colon.\ a&colon. &splitvbar.&splitvbar. echo Error in the backup!
:exmp.:p.
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.  To determine whether a particular external program returns a
meaningful exit code use an :hp2.ECHO %?:ehp2. command immediately after the
program is finished.  If the program's documentation does not discuss exit
codes you may need to experiment with a variety of conditions to see how the
exit code changes.

.* --------------------------------------------------------------------------

:h2 name=Grouping.Command Grouping
:p.
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.
:p.
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 execute two different
:link reftype=hd refid=REN.REN:elink. commands in all subdirectories of your
hard disk.  You could do it like this&colon.
:xmp.
        [c&colon.\] global ren *.wx1 *.wxo
        [c&colon.\] global ren *.tx1 *.txo
:exmp.:p.
But with command grouping you can do the same thing in one command
(enter this on one line)&colon.
:xmp.
        [c&colon.\]global (ren *.wx1 *.wxo &amp. ren *.tx1 *.txo)
:exmp.:p.
The two REN commands enclosed in the parentheses appear to
:link reftype=hd refid=GLOBAL.GLOBAL:elink. as if they were a single command,
so both commands are executed for every directory, but the directories are
only scanned once, not twice.
:p.
This kind of command grouping is most useful with the
:link reftype=hd refid=EXCEPT.EXCEPT:elink.,
:link reftype=hd refid=FOR.FOR:elink.,
:link reftype=hd refid=GLOBAL.GLOBAL:elink., and
:link reftype=hd refid=IF.IF:elink. commands.  When you use this approach in
a batch file you must either place all of the commands in the group on one
line, or place the opening parenthesis at the end of a line and place the
commands on subsequent lines.  For example, the first two of these
sequences will work properly, but the third will not:
:xmp.
        for %f in (1 2 3) (echo hello %f &amp. echo goodbye %f)
        for %f in (1 2 3) (
                echo hello %f
                echo goodbye %f
        )
        for %f in (1 2 3) (echo hello %f
        echo goodbye %f)
:exmp.:p.
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 uses the ECHO command to create a file (with
:hp2.>:ehp2.), and to append to the file (with :hp2.>>:ehp2.)&colon.
:xmp.
        echo Data files %_date > filelist
        dir *.dat >> filelist
        echo. >> filelist
        echo Text files %_date >> filelist
        dir *.txt >> filelist
:exmp.:p.
Using command grouping, these commands can be written much more
simply.  Enter this example on one line&colon.
:xmp.
        (echo Data files %_date &amp. dir *.dat &amp. echo. &amp. echo Text files
        %_date &amp. dir *.txt) > filelist
:exmp.:p.
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.
:p.
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 :hp2.not:ehp2. have to be entered on one line:
:xmp.
        [c&colon.\] (echo Data files %_date
        More? dir *.dat
        More? echo.
        More? echo Text files %_date
        More? dir *.txt) > filelist
        [c&colon.\]
:exmp.:p.
A group of commands in parentheses is like a long command line.  The total
length of the group may not exceed 2,047 characters, whether the commands are
entered from the prompt, an alias, or a batch file.  The limit
:hp2.includes:ehp2. the space required to expand aliases and environment
variables used within the group.  In addition, each line you type at the
normal prompt or the :hp2.More?:ehp2. prompt, and each individual
command within the line, must meet the usual length limit of 1,023 characters.

.* --------------------------------------------------------------------------

:h2 name=Escape.Escape Character
:p.
&4OS2. recognizes a user-definable escape character.  This character
gives the following character a special meaning; it is :hp2.not:ehp2. the
same as the ASCII ESC that is often used in ANSI and printer
control sequences.
:p.
The default escape character is a caret [:hp2.^:ehp2.].
:p.
If you don't like using the default escape character, you can pick
another character using the :link reftype=hd refid=SETDOS.SETDOS:elink. /E
command, the Options 1 page of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs, or the
:link reftype=hd refid=INI_EscapeChar.EscapeChar:elink. directive in your
:hp1..INI:ehp1. file.  If you plan to share aliases or batch files between
&4OS2. and 4DOS, 4NT, or Take Command, see :link reftype=hd
refid=Compat.Special Character Compatibility:elink. for
details about choosing compatible escape characters for two or more products.
:p.
Ten 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 primarily useful for redirecting codes to the
printer; :hp2.^e:ehp2. is also useful to generate ANSI "escape
sequences" in your PROMPT, ECHO, or other output commands.  The special
characters which can follow the escape character are&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:hp2.b:ehp2.:pd.backspace
:pt.:hp2.c:ehp2.:pd.comma
:pt.:hp2.e:ehp2.:pd.the ASCII ESC character (ASCII 27)
:pt.:hp2.f:ehp2.:pd.form feed
:pt.:hp2.k:ehp2.:pd.back quote
:pt.:hp2.n:ehp2.:pd.line feed
:pt.:hp2.q:ehp2.:pd.double quote
:pt.:hp2.r:ehp2.:pd.carriage return
:pt.:hp2.s:ehp2.:pd.space
:pt.:hp2.t:ehp2.:pd.tab character
:eparml.:lm margin=1.
.br
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 :hp2.? * / \ &splitvbar. "
` > <:ehp2. and :hp2.&amp.:ehp2.). For example, to display a message
containing a :hp2.>:ehp2. symbol, which normally indicates redirection&colon.
:xmp.
        [c&colon.\] echo 2 is ^> 4
:exmp.:p.
To send a form feed followed by the sequence ESC Y to
the printer, you can use this command&colon.
:xmp.
        [c&colon.\] echos ^f^eY > prn
:exmp.
The escape character has an additional use when it is the last character on
any line of a :hp1..BAT:ehp1. or :hp1.BTM:ehp1. batch file.  &4OS2. recognizes
this use of the escape character to signal line continuation&colon.  the
command processor removes the escape character and appends the next line to
the current line before executing it.

.* --------------------------------------------------------------------------

:h1 name=Commands.Internal Commands
:p.
The best way to learn the &4OS2. commands is to
experiment with them.  The lists below categorize the available
commands by topic and will help you find the ones that you need.
:p.
System configuration&colon.
:lm margin=4.:table rules=none frame=box cols='12 12 12 12 12'.
:row.
:c.:link reftype=hd refid=CHCP.CHCP:elink.
:c.:link reftype=hd refid=CLS.CLS:elink.
:c.:link reftype=hd refid=COLOR.COLOR:elink.
:c.:link reftype=hd refid=DATE.DATE:elink.
:c.:link reftype=hd refid=DIRHISTORY.DIRHISTORY:elink.
:row.
:c.:link reftype=hd refid=FREE.FREE:elink.
:c.:link reftype=hd refid=HISTORY.HISTORY:elink.
:c.:link reftype=hd refid=KEYS.KEYS:elink.
:c.:link reftype=hd refid=KEYBD.KEYBD:elink.
:c.:link reftype=hd refid=LOG.LOG:elink.
:row.
:c.:link reftype=hd refid=MEMORY.MEMORY:elink.
:c.:link reftype=hd refid=OPTION.OPTION:elink.
:c.:link reftype=hd refid=PROMPT.PROMPT:elink.
:c.:link reftype=hd refid=REBOOT.REBOOT:elink.
:c.:link reftype=hd refid=SETDOS.SETDOS:elink.
:row.
:c.:link reftype=hd refid=TIME.TIME:elink.
:c.:link reftype=hd refid=VER.VER:elink.
:c.:link reftype=hd refid=VERIFY.VERIFY:elink.
:c.:link reftype=hd refid=VOL.VOL:elink.
:etable.
:lm margin=1.
:p.
File and directory management&colon.
:lm margin=4.:table rules=none frame=box cols='12 12 12 12 12'.
:row.
:c.:link reftype=hd refid=ATTRIB.ATTRIB:elink.
:c.:link reftype=hd refid=COPY.COPY:elink.
:c.:link reftype=hd refid=DEL.DEL:elink.
:c.:link reftype=hd refid=DESCRIBE.DESCRIBE:elink.
:c.:link reftype=hd refid=LIST.LIST:elink.
:row.
:c.:link reftype=hd refid=MOVE.MOVE:elink.
:c.:link reftype=hd refid=REN.REN:elink.
:c.:link reftype=hd refid=SELECT.SELECT:elink.
:c.:link reftype=hd refid=TOUCH.TOUCH:elink.
:c.:link reftype=hd refid=TREE.TREE:elink.
:row.
:c.:link reftype=hd refid=TYPE.TYPE:elink.
:etable.
:lm margin=1.
:p.
Subdirectory management&colon.
:lm margin=4.:table rules=none frame=box cols='12 12 12 12 12'.
:row.
:c.:link reftype=hd refid=CD.CD:elink.
:c.:link reftype=hd refid=CDD.CDD:elink.
:c.:link reftype=hd refid=DIR.DIR:elink.
:c.:link reftype=hd refid=DIRS.DIRS:elink.
:c.:link reftype=hd refid=MD.MD:elink.
:row.
:c.:link reftype=hd refid=POPD.POPD:elink.
:c.:link reftype=hd refid=PUSHD.PUSHD:elink.
:c.:link reftype=hd refid=RD.RD:elink.
:etable.
:lm margin=1.
:p.
Input and output&colon.
:lm margin=4.:table rules=none frame=box cols='12 12 12 12 12'.
:row.
:c.:link reftype=hd refid=DRAWBOX.DRAWBOX:elink.
:c.:link reftype=hd refid=DRAWHLINE.DRAWHLINE:elink.
:c.:link reftype=hd refid=DRAWVLINE.DRAWVLINE:elink.
:c.:link reftype=hd refid=ECHO.ECHO:elink.
:c.:link reftype=hd refid=ECHOS.ECHOSERR:elink.
:row.
:c.:link reftype=hd refid=ECHOS.ECHOS:elink.
:c.:link reftype=hd refid=ECHO.ECHOERR:elink.
:c.:link reftype=hd refid=INKEY.INKEY:elink.
:c.:link reftype=hd refid=INPUT.INPUT:elink.
:c.:link reftype=hd refid=KEYSTACK.KEYSTACK:elink.
:row.
:c.:link reftype=hd refid=SCREEN.SCREEN:elink.
:c.:link reftype=hd refid=SCRPUT.SCRPUT:elink.
:c.:link reftype=hd refid=TEXT.TEXT:elink.
:c.:link reftype=hd refid=VSCRPUT.VSCRPUT:elink.
:etable.
:lm margin=1.
:p.
Commands primarily for use in or with batch files and aliases&colon.
.br
(some work only in batch files; see the individual commands for details)
:lm margin=4.:table rules=none frame=box cols='12 12 12 12 12'.
:row.
:c.:link reftype=hd refid=ALIAS.ALIAS:elink.
:c.:link reftype=hd refid=BEEP.BEEP:elink.
:c.:link reftype=hd refid=CALL.CALL:elink.
:c.:link reftype=hd refid=CANCEL.CANCEL:elink.
:c.:link reftype=hd refid=DELAY.DELAY:elink.
:row.
:c.:link reftype=hd refid=DO.DO:elink.
:c.:link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink.
:c.:link reftype=hd refid=FOR.FOR:elink.
:c.:link reftype=hd refid=GLOBAL.GLOBAL:elink.
:c.:link reftype=hd refid=GOSUB.GOSUB:elink.
:row.
:c.:link reftype=hd refid=GOTO.GOTO:elink.
:c.:link reftype=hd refid=IF.IF:elink.
:c.:link reftype=hd refid=IFF.IFF:elink.
:c.:link reftype=hd refid=LOADBTM.LOADBTM:elink.
:c.:link reftype=hd refid=ON.ON:elink.
:row.
:c.:link reftype=hd refid=PAUSE.PAUSE:elink.
:c.:link reftype=hd refid=QUIT.QUIT:elink.
:c.:link reftype=hd refid=REM.REM:elink.
:c.:link reftype=hd refid=RETURN.RETURN:elink.
:c.:link reftype=hd refid=SETLOCAL.SETLOCAL:elink.
:row.
:c.:link reftype=hd refid=SHIFT.SHIFT:elink.
:c.:link reftype=hd refid=SWITCH.SWITCH:elink.
:c.:link reftype=hd refid=UNALIAS.UNALIAS:elink.
:etable.
:lm margin=1.
:p.
Environment and path commands&colon.
:lm margin=4.:table rules=none frame=box cols='12 12 12 12 12'.
:row.
:c.:link reftype=hd refid=DPATH.DPATH:elink.
:c.:link reftype=hd refid=ESET.ESET:elink.
:c.:link reftype=hd refid=PATH.PATH:elink.
:c.:link reftype=hd refid=SET.SET:elink.
:c.:link reftype=hd refid=UNSET.UNSET:elink.
:etable.
:lm margin=1.
:p.
Other commands&colon.
:lm margin=4.:table rules=none frame=box cols='12 12 12 12 12'.
:row.
:c.:link reftype=hd refid=QMARK.?:elink.
:c.:link reftype=hd refid=ACTIVATE.ACTIVATE:elink.
:c.:link reftype=hd refid=DETACH.DETACH:elink.
:c.:link reftype=hd refid=EXCEPT.EXCEPT:elink.
:c.:link reftype=hd refid=EXIT.EXIT:elink.
:row.
:c.:link reftype=hd refid=FFIND.FFIND:elink.
:c.:link reftype=hd refid=HELP.HELP:elink.
:c.:link reftype=hd refid=SHRALIAS.SHRALIAS:elink.
:c.:link reftype=hd refid=START.START:elink.
:c.:link reftype=hd refid=TEE.TEE:elink.
:row.
:c.:link reftype=hd refid=TIMER.TIMER:elink.
:c.:link reftype=hd refid=TITLE.TITLE:elink.
:c.:link reftype=hd refid=WINDOW.WINDOW:elink.
:c.:link reftype=hd refid=Y.Y:elink.
:etable.
:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=QMARK.? - List the internal commands
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display a list of internal commands or,
prompt for a command.
.br
:pt.:hp2.Format&colon.:ehp2.:pd.:hp2.? [":ehp2.:hp3.prompt:ehp3.
:hp2.":ehp2. :hp3.command:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.prompt :ehp3.&colon.  Prompt text about whether to execute the command.
:pt.:pd.:hp3.command :ehp3.&colon.  Command to be executed if user answers :hp2.Y:ehp2.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
:hp2.?:ehp2. has two functions.  When you use the :hp2.?:ehp2. command by
itself, it displays a list of internal commands.  If you have disabled a
command with :link reftype=hd refid=SETDOS.SETDOS:elink. /I, it will not
appear in the list.
:p.
The second function of :hp2.?:ehp2. is to prompt the user before executing a
specific line in a batch file.  If you add a prompt and a command,
:hp2.?:ehp2. will display the prompt followed by "(Y/N)?" and wait for the
user's response.  If the user presses "Y" or "y", the command line will be
executed.  If the user presses "N" or "n", the command line will be ignored.
:p.
For example, the following command might be used in a batch file&colon.
:xmp.
        ? Load the network call netstart.btm
:exmp.:p.
When this command is executed, you will see the following prompt; if you
answer "Y", the CALL command will be executed&colon.
:xmp.
        Load the network (Y/N)?
:exmp.:p.

.* --------------------------------------------------------------------------

:h2 name=ACTIVATE.ACTIVATE - Activate a window
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Activate a window, set its state, or change
its title.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.ACTIVATE ":ehp2.:hp3.window:ehp3. :hp2."
[MAX &splitvbar. MIN &splitvbar. RESTORE &splitvbar. CLOSE]:ehp2.
.br
:pt.:pd.:hp3.window :ehp3.&colon.  Current title of window to work with.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=START.START:elink., :link reftype=hd
refid=TITLE.TITLE:elink., and :link reftype=hd refid=WINDOW.WINDOW:elink..
:p.
:hp2.Usage:ehp2.
:p.
The name of the window must be enclosed in double quotes.
:p.
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.
:p.
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.
:p.
This example maximizes and then renames the window called "&4OS2."&colon.
:xmp.
        [c&colon.\] activate "&4OS2." max
        [c&colon.\] activate "&4OS2." "Command Prompt"
:exmp.:p.
You can use :link reftype=hd refid=WILDCARDS.wildcards:elink. in the
:hp1.window:ehp1. name if you only know the first part of the title.  This
is useful with applications that change their window title to reflect the
file currently in use.
:p.
ACTIVATE is often used before :link reftype=hd
refid=KEYSTACK.KEYSTACK:elink. to make sure the proper window receives the
keystrokes.  ACTIVATE works by sending the appropriate messages to the named
:hp1.window:ehp1..  If the window ignores or misinterprets the messages,
ACTIVATE may not have the effect you want.

.* --------------------------------------------------------------------------

:h2 name=ALIAS.ALIAS - Create or display aliases
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.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.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.ALIAS [/P /R :ehp2.:hp3.file:ehp3.
:hp2....] [:ehp2.:hp3.name:ehp3. :hp2.[=][:ehp2.:hp3.value:ehp3. :hp2.]]:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  One or more files to read for alias definitions.
:pt.:pd.:hp3.name :ehp3.&colon.  Name for an alias, or for the key to execute the alias.
:pt.:pd.:hp3.value :ehp3.&colon.  Text to be substituted for the alias name.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./P:ehp2.(ause):pd.:hp2./R:ehp2.(ead file)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=UNALIAS.UNALIAS:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
For example, to create a single-letter command D to display a wide directory,
instead of useing the longer DIR /W, you could use the command&colon.
:xmp.
        [c&colon.\] alias d = dir /w
:exmp.:p.
Now when you type a single :hp2.d:ehp2. as a command, it will be
translated into a DIR /W command.
:p.
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 :hp1.C&colon.\QPRO:ehp1.
directory in your path, you could define the following alias&colon.
:xmp.
        [c&colon.\] alias qpro = c&colon.\qpro\q.exe
:exmp.:p.
With this alias defined, you can probably remove :hp1.C&colon.\QPRO:ehp1. from
your PATH.  Quattro Pro will now load more quickly than it would if
&4OS2. had to search the PATH for it.  In addition, the PATH can be
shorter, which will speed up searches for other programs.
:p.
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.
:p.
Aliases are stored in memory, and are not saved automatically when
you turn off your computer or end your current session.  See below
for information on saving and reloading your aliases.
:p.
:hp2.Multiple Commands and Special Characters in Aliases:ehp2.
:p.
An alias can represent more than one command.  For example&colon.
:xmp.
        [c&colon.\] alias letters = `cd \letters &amp. text`
:exmp.:p.
creates a new command called LETTERS.  The command first uses CD to
change to a subdirectory called :hp1.\LETTERS:ehp1. and then runs a
program called :hp1.TEXT:ehp1..  The ampersand [:hp2.&amp.:ehp2.] is the command
separator and indicates that the two commands are distinct and
should be executed sequentially.
:p.
Aliases make extensive use of the
:link reftype=hd refid=MultCmds.command separator:elink.,
and the :link reftype=hd refid=INI_ParameterChar.parameter character:elink.,
and may also use the :link reftype=hd refid=Escape.escape character:elink..
These characters differ between &4OS2., 4DOS, 4NT, and Take Command.  In
the text and examples below, we use the &4OS2. characters.  If you want to
use the same aliases under different command processors, see :link reftype=hd
refid=Compat.Special Character Compatibility:elink..
:p.
When you type alias commands at the command line or in a batch
file, you :hp2.must:ehp2. use back quotes [:hp2.`:ehp2.] 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 :hp2.may:ehp2. use
back quotes around other definitions, but they are not required.
(You do not need back quotes when your 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.
:p.
:hp2.Nested Aliases:ehp2.
:p.
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 :hp1.WP.EXE:ehp1. that is in the :hp1.E&colon.\WP60\:ehp1.
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&colon.
:xmp.
        [c&colon.\] alias wp = e&colon.\wp60\wp.exe
        [c&colon.\] alias w = `pushd c&colon.\wp &amp. wp &amp. popd`
:exmp.:p.
The second alias above could have included the full path and name
of the :hp1.WP.EXE:ehp1. 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 :hp1.WP.EXE:ehp1. program or move it to a new
directory, only the first alias needs to be changed.
:p.
:hp2.Temporarily Disabling Aliases:ehp2.
:p.
If you put an asterisk [:hp2.*:ehp2.] immediately before a command in the
:hp1.value:ehp1. of an alias definition (the part after the equal sign),
it tells &4OS2. 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.
:p.
By using an asterisk, you can redefine the default options for any
internal or external command.  For example, suppose that you always want to
use the DIR command with the :hp2./2:ehp2. (two column) and :hp2./P:ehp2.
(pause at the end of each page) options.  The following line will do just
that&colon.
:xmp.
        [c&colon.\] alias dir = *dir /2/p
:exmp.:p.
If you didn't include the asterisk, the second DIR on the line
would be the name of the alias itself, and &4OS2. 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.
:p.
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 :hp1.LIST.COM:ehp1..  Normally, the
internal LIST command will run anytime you type LIST.  But two
simple aliases will give you access to both the :hp1.LIST.COM:ehp1.
program and the LIST command&colon.
:xmp.
        [c&colon.\] alias list = c&colon.\util\list.com
        [c&colon.\] alias display = *list
:exmp.:p.
The first line above defines LIST as an alias for the :hp1.LIST.COM:ehp1.
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.
:p.
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.  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.
:p.
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 of an alias
which changes the meaning or behavior of a command.
:p.
You can also disable aliases temporarily with the :link reftype=hd
refid=SETDOS.SETDOS:elink. /X command.
:p.
:hp2.Partial Alias Names:ehp2.
:p.
You can also use an asterisk in the :hp1.name:ehp1. 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
:hp1.name:ehp1. is unrelated to the use of an asterisk in the alias
:hp1.value:ehp1. discussed above.)  For example, with this alias&colon.
:xmp.
        [c&colon.\] alias wher*eis = dir /sp
:exmp.:p.
the new command, WHEREIS, can be invoked as WHER, WHERE, WHEREI, or
WHEREIS.  Now if you type&colon.
:xmp.
        [c&colon.\] where myfile.txt
:exmp.:p.
The WHEREIS alias will be expanded to the command&colon.
:xmp.
        dir /sp myfile.txt
:exmp.:p.
:hp2.Keystroke Aliases:ehp2.
:p.
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 [:hp2.@:ehp2.].
For example, to assign the command DIR /W to the :hp2.F5:ehp2. key, type
:xmp.
        [c&colon.\] alias @F5 = dir /w
:exmp.:p.
See :link reftype=hd refid=KeyNames.Keys and Key Names:elink. for a complete listing of key
names and a description of the key name format.
:p.
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 :hp2.F1:ehp2. 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 keys for an alias instead
of its normal meaning, you must first disable its regular use with
the :link reftype=hd refid=INI_NormalKey.NormalKey:elink. or
:link reftype=hd refid=INI_NormalEditKey.NormalEditKey:elink. directives in
your :hp1..INI:ehp1. file.
:p.
If you define a keystroke alias with a single at sign as shown
above, then, when you press the :hp2.F5:ehp2. 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 :hp2.Enter:ehp2. to
execute the command.  With this particular alias, you can define
the files that you want to display after pressing :hp2.F5:ehp2. and before
pressing Enter to execute the command.
:p.
If you want the keystroke alias to take action automatically
without waiting for you to edit the command line or press
:hp2.Enter:ehp2., you can begin the definition with two at signs [:hp2.@@:ehp2.].
&4OS2. will execute the alias "silently," without displaying its text
on the command line.  For example, this command will assign an
alias to the :hp2.F6:ehp2. key that uses the CDD command to take you back
to the previous default directory&colon.
:xmp.
        [c&colon.\] alias @@f6 = cdd -
:exmp.:p.
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
:hp2.F1:ehp2. 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 keys for an alias instead of its normal meaning, you must first
disable its regular use with the :link reftype=hd
refid=INI_NormalKey.NormalKey:elink. or :link reftype=hd
refid=INI_NormalEditKey.NormalEditKey:elink. directives in your
:hp1..INI:ehp1. file.
:p.
You can also define a keystroke alias by using "@" or "@@" plus a
scan code for one of the permissible keys (see the
:link reftype=hd refid=RefTab.Reference Tables:elink. 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.
:p.
:hp2.Displaying Aliases:ehp2.
:p.
If you want to see a list of all current ALIAS commands, type&colon.
:xmp.
        [c&colon.\] alias
:exmp.:p.
You can also view the definition of a single alias.  For example, if you
want to see the definition of the alias LIST, you can type&colon.
:xmp.
        [c&colon.\] alias list
:exmp.:p.
:hp2.Saving and Reloading Your Aliases:ehp2.
:p.
You can save your aliases to a file called :hp1.ALIAS.LST:ehp1. this way&colon.
:xmp.
        [c&colon.\] alias > alias.lst
:exmp.:p.
You can then reload all the alias definitions in the file the next
time you boot up with the command&colon.
:xmp.
        [c&colon.\] alias /r alias.lst
:exmp.:p.
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.
:p.
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 be required when defining the same alias
at the command line or in a batch file.
:p.
To remove an alias, use the :link reftype=hd refid=UNALIAS.UNALIAS:elink.
command.
:p.
:hp2.Alias Parameters:ehp2.
:p.
Aliases can use command-line arguments or parameters like those in
batch files.  The command-line arguments are numbered from :hp2.%0:ehp2.
to :hp2.%127:ehp2..  :hp2.%0:ehp2. 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 :link reftype=hd
refid=Quoting.Argument Quoting:elink. for details.
:p.
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 :hp2.%3:ehp2. or any higher-numbered parameter
will be interpreted as an empty string.
:p.
The parameter :hp2.%n$:ehp2. has a special meaning.  &4OS2. interprets it to
mean "the entire command line, from argument :hp2.n:ehp2. to the end."  If
:hp2.n:ehp2. is not specified, it has a default value of 1, so :hp2.%$:ehp2.
means "the entire command line after the alias name."  The special parameter
:hp2.%#:ehp2. contains the number of command-line arguments.
:p.
For example, the following alias will change directories, perform a
command, and return to the original directory&colon.
:xmp.
        [c&colon.\] alias in `pushd %1 &amp. %2$ &amp. popd`
:exmp.:p.
When this alias is invoked as&colon.
:xmp.
        [c&colon.\] in c&colon.\comm mycomm /zmodem /56K
:exmp.:p.
the first parameter, :hp2.%1:ehp2., has the value :hp1.c&colon.\comm:ehp1..
:hp2.%2:ehp2. is :hp1.mycomm:ehp1., :hp2.%3:ehp2. is :hp1.
/zmodem:ehp1., and :hp2.%4:ehp2. is :hp1./56K:ehp1..  The command line
expands into these three separate commands&colon.
:xmp.
        pushd c&colon.\comm
        mycomm /zmodem /56K
        popd
:exmp.:p.
This next example uses the IFF command to redefine the defaults for
SET.  It should be entered on one line&colon.
:xmp.
        [c&colon.\] alias set = `iff %# == 0 then &amp. *set /p
             &amp. else &amp. *set %&amp. &amp. endiff`
:exmp.:p.
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 (:hp2.*set:ehp2.) to prevent alias loops.
:p.
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 :hp2.%1:ehp2. and :hp2.%4:ehp2., 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 :hp1.value:ehp1. portion of
the alias).  If an alias uses no parameters, all of the command-line
arguments will be appended to the expanded command.
:p.
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&colon.
:xmp.
        [c&colon.\] alias calc = `echo The answer is&colon. %@eval[%&amp.]`
:exmp.:p.
Now, if you enter&colon.
:xmp.
        [c&colon.\] calc 5 * 6
:exmp.:p.
the alias will display&colon.
:xmp.
        The answer is&colon. 30
:exmp.:p.
:hp2.Expanding Aliases at the Prompt:ehp2.
:p.
You can expand an alias on the command line and view or edit the results by
pressing :hp2.Ctrl-F:ehp2. after typing the alias name, but before the
command is executed.  This replaces the alias with its contents, and
substitutes values for each alias paramter, just as if you had pressed the
:hp2.Enter:ehp2. key.  However, the command is not executed; it is simply
redisplayed on the command line for additional editing.
:p.
:hp2.Ctrl-F:ehp2. is especially useful when you are developing and debugging
a complex alias, or if you want to make sure that an alias that you may have
forgotten won't change the effect of your command.
:p.
:hp2.Local and Global Aliases:ehp2.
:p.
The aliases can be stored in either a "local" or "global" list.
:p.
With a local alias list, any changes made to the aliases will only
affect the current copy of &4OS2..  They will not be visible in other
shells or other sessions.
:p.
With a global alias list, all copies of &4OS2. will share the same
alias list, and any changes made to the aliases in one copy will
affect all other copies.  This is the default.
:p.
You can control the type of alias list with the
:link reftype=hd refid=INI_LocalAliases.LocalAliases:elink. directive in the :hp1..INI:ehp1. file,
and with the :hp2./L:ehp2. and :hp2./LA:ehp2. options of the :link reftype=hd refid=START.START:elink.
command.
:p.
Whenever you start a secondary shell which uses a local alias list,
it inherits a copy of the aliases from the previous shell.
However, any changes to the aliases 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.
:p.
:hp2.Retaining Global Aliases with SHRALIAS:ehp2.
:p.
If you select a global alias list for &4OS2. you can share the
aliases among all copies of &4OS2. running in any session.  When you
close all &4OS2. sessions, the memory for the global alias list is
released, and a new, empty alias list is created the next time you
start &4OS2..
:p.
If you want the alias list to be retained in memory even when no
command processor session is running, execute the :link reftype=hd
refid=SHRALIAS.SHRALIAS:elink. command, which loads a program to
perform this service for the global alias list, the global :link reftype=hd
refid=CMDHIST.command history:elink. list, and the global :link reftype=hd
refid=DIRHIST.directory history:elink..
:p.
You may find it convenient to execute SHRALIAS from your :link reftype=hd
refid=AutoBatch.4START:elink. file, or from :hp1.STARTUP.CMD:ehp1..
:p.
SHRALIAS retains the alias list in memory, but cannot preserve it when
OS/2 itself is shut down.  To save your aliases when restarting
OS/2, you must store them in a file and reload them after the system
restarts.  For details on how to do so, see :hp2.Saving and Reloading Your
Aliases:ehp2. (above).
:p.
:hp2.The UNKNOWN_CMD Alias:ehp2.
:p.
If you create an alias with the name :hp2.UNKNOWN_CMD:ehp2., it will be
executed any time &4OS2. would normally issue an "Unknown command"
error message.  This allows you to define your own handler for
unknown commands.  When the :hp2.UNKNOWN_CMD:ehp2. alias is executed, the
command line which generated the error is passed to the alias for
possible processing.  For example, to display the command that caused the
error:
:xmp.
        alias unknown_cmd `echo Error in command "%&amp."`
:exmp.:p.
If the :hp2.UNKNOWN_CMD:ehp2. alias contains an unknown command, it will call
itself repeatedly.  If this occurs, the command processor will loop up to 10
times, then display an "UKNOWN_CMD loop" error.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./P:ehp2.&colon.:pd.(Pause) 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 :link reftype=hd refid=Prompts.Page and File Prompts:elink.).
:pt.:hp2./R:ehp2.&colon.:pd.(Read file) This option loads an alias list from a file.
The format of the file is the same as that of the ALIAS display&colon.
:xmp.
        name=value
:exmp.:p.
where :hp2.name:ehp2. is the :hp1.name:ehp1. of the alias and :hp2.value:ehp2. is
its :hp1.value:ehp1..  You can use an equal sign [:hp2.=:ehp2.] 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
[:hp2.&colon.:ehp2.].  You can load multiple files with one ALIAS /R command
by placing the names on the command line, separated by spaces&colon.
:xmp.
        [c&colon.\] alias /r alias1.lst alias2.lst
:exmp.:p.
Each definition in an ALIAS /R file can be up to 2047 characters long.
The definitions can span multiple lines in the file if each line,
except the last, is terminated with an
:link reftype=hd refid=Escape.escape character:elink..
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=ATTRIB.ATTRIB - Change or view file attributes
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Change or view file and subdirectory attributes.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.ATTRIB [/A&colon.[[-]rhsda] /D /E /P /Q
/S] [+&splitvbar.-[AHRS]] :ehp2.:hp3.file:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  A file, directory, or list of files or directories on which to operate.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2. (Attribute select):pd.:hp2./P:ehp2.(ause)
:pt.:hp2./D:ehp2.(irectories):pd.:hp2./Q:ehp2.(uiet)
:pt.:hp2./E:ehp2. (No error messages):pd.:hp2./S:ehp2.(ubdirectories)
:eparml.:p.
Attribute flags&colon.
:parml compact tsize=8 break=fit.
:pt.:hp2.+A:ehp2.:pd.Set the archive attribute
:pt.:hp2.-A:ehp2.:pd.Clear the archive attribute
:pt.:hp2.+H:ehp2.:pd.Set the hidden attribute
:pt.:hp2.-H:ehp2.:pd.Clear the hidden attribute
:pt.:hp2.+R:ehp2.:pd.Set the read-only attribute
:pt.:hp2.-R:ehp2.:pd.Clear the read-only attribute
:pt.:hp2.+S:ehp2.:pd.Set the system attribute
:pt.:hp2.-S:ehp2.:pd.Clear the system attribute
:eparml.:lm margin=1.
.br
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and
:link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
Every file and subdirectory has 4 attributes that can be turned on
(set) or turned off (cleared)&colon.  :hp2.Archive:ehp2., :hp2.Hidden:ehp2., :hp2.Read-
only:ehp2., and :hp2.System:ehp2..
:p.
The ATTRIB command lets you view, set, or clear attributes for any file,
group of files, or subdirectory.  You can view file attributes by
entering ATTRIB without specifying new attributes (:hp1.i.e.:ehp1.,
without the :hp2.[+&splitvbar.-[AHRS]]:ehp2. part of the format), or with the :hp2.DIR
/T:ehp2. command.
:p.
You can view file attributes by entering ATTRIB without specifying new
attributes (:hp1.i.e.:ehp1., without the :hp2.[+|-[AHRS]]:ehp2. part of the
format).  (You can also view file attributes with the :link reftype=hd
refid=DIR.DIR:elink. /T command.)
:p.
The primary use of ATTRIB is to set attributes.  For example, you can set
the read-only and hidden attributes for the file :hp1.MEMO:ehp1.&colon.
:xmp.
        [c&colon.\] attrib +rh memo
:exmp.:p.
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 :hp1..TXT:ehp1. files, then sets the
system attribute and clears the archive attribute for :hp1.TEST.COM:ehp1. &colon.
:xmp.
        [c&colon.\] attrib +a *.txt +s -a test.com
:exmp.:p.
When you use ATTRIB on an HPFS drive, you must quote any file
names which contain whitespace or special characters.  See :link reftype=hd
refid=FileNames.File Names:elink. for additional details.
:p.
To change directory attributes, use the :hp2./D:ehp2. switch.  If you give
ATTRIB a directory name instead of a file name, and omit :hp2./D:ehp2., it
will append "\*.*" to the end of the name and act on all files in that
directory, rather than acting on the directory itself.
:p.
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.
:p.
ATTRIB will ignore underlines in the new attribute (the
:hp2.[+|-[AHRS]]:ehp2. part of the command).  For example, ATTRIB sees these
two commands as identical&colon.
:xmp.
        [c&colon.\] attrib +a filename
        [c&colon.\] attrib +__A_ filename
:exmp.:p.
This allows you to use a string of attributes from either the @ATTRIB
variable function or from ATTRIB itself (both of which use underscores to
represent attributes that are not set) and send that string back to ATTRIB
to set attributes for other files.  For example, to clear the attributes of
:hp1.FILE2:ehp1. and then set its attributes to match those of
:hp1.FILE1:ehp1. (enter this on one line)&colon.
:xmp.
        [c&colon.\] attrib -arhs file2 &amp. attrib +%@attrib[file1] file2
:exmp.:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A&colon.:ehp2.&colon.:pd.(Attribute select) Select only those files that
have the specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute
set.  The colon [:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is required.  The
attributes are&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.ATTRIB
/A&colon. ...:ehp2.), ATTRIB will select all
files and subdirectories including hidden and system files.  If
attributes are combined, all the specified attributes must match for a
file to be selected. For example, /A&colon.RHS will select only those files
with all three attributes set.
:p.
The :hp2./A&colon.:ehp2. switch specifies which files to select,
:hp2.not:ehp2. which attributes to set.  For example, to remove the archive
attribute from all hidden files, you could use this command&colon.
:xmp.
        [c&colon.\] attrib /a&colon.h -a *.*
:exmp.:p.
:pt.:hp2./D:ehp2.&colon.:pd.(Directories) If you use the :hp2./D:ehp2.
option, ATTRIB will modify the attributes of subdirectories in addition to
files (yes, you can have a hidden subdirectory)&colon.
:xmp.
        [c&colon.\] attrib /d +h c&colon.\mydir
:exmp.:p.
If you use a directory name instead of a file name, and omit :hp2./D:ehp2.,
ATTRIB will append "\*.*" to the end of the name and act on all files in
that directory, rather than acting on the directory itself.
:pt.:hp2./E:ehp2.&colon.:pd.(No error messages) Suppress all non-fatal error
messages, such as "File Not Found."  Fatal error messages, such as "Drive
not ready," will still be displayed.  This option is most useful in batch
files and aliases.
:pt.:hp2./P:ehp2.&colon.:pd.(Pause) Wait for a key to be pressed after each screen page
before continuing the display.  Your options at the prompt are explained in
detail under :link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) This option turns off ATTRIB's normal screen output.
It is most useful in batch files.
:pt.:hp2./S:ehp2.&colon.:pd.(Subdirectories) If you use the :hp2./S:ehp2.
option, the ATTRIB command will be applied to all matching files in the
current or named directory and all of its subdirectories.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=BEEP.BEEP - Beep the speaker
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Beep the speaker or play simple music.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.BEEP [:ehp2.:hp3.frequency
duration:ehp3. :hp2....]:ehp2.
.br
:pt.:pd.:hp3.frequency :ehp3.&colon.  The beep frequency in Hertz (cycles per second).
:pt.:pd.:hp3.duration :ehp3.&colon.  The beep length in 1/18th second intervals.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
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.
:p.
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 use BEEP as a way to create short delays.  The default value
for :hp1.frequency:ehp1. is 440 Hz; the default value for
:hp1.duration:ehp1. is 2.
:p.
This batch file fragment runs a program called:hp1. DEMO:ehp1., then plays
a few notes and waits for you to press a key&colon.
:xmp.
        demo &amp. beep 440 4  600 2  1040 6
        pause Finished with the demo - hit a key...
:exmp.:p.
The following table gives the :hp1.frequency:ehp1. values for a five
octave range (middle C is 262 Hz)&colon.
:xmp.
        ÉÍÍÍÍÍÍÍÍŃÍÍÍÍÍÍÍŃÍÍÍÍÍÍÍŃÍÍÍÍÍÍÍŃÍÍÍÍÍÍÍÍŃÍÍÍÍÍÍÍ»
        ş C      ł  131  ł  262  ł  523  ł  1046  ł  2093 ş
        ş C#/Db  ł  139  ł  277  ł  554  ł  1108  ł  2217 ş
        ş D      ł  147  ł  294  ł  587  ł  1175  ł  2349 ş
        ş D#/Eb  ł  156  ł  311  ł  622  ł  1244  ł  2489 ş
        ş E      ł  165  ł  330  ł  659  ł  1318  ł  2637 ş
        ş 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  ł  1866  ł  3729 ş
        ş B      ł  248  ł  494  ł  988  ł  1973  ł  3951 ş
        ČÍÍÍÍÍÍÍÍĎÍÍÍÍÍÍÍĎÍÍÍÍÍÍÍĎÍÍÍÍÍÍÍĎÍÍÍÍÍÍÍÍĎÍÍÍÍÍÍÍĽ
:exmp.

.* --------------------------------------------------------------------------

:h2 name=CALL.CALL - Execute one batch file from another
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Execute one batch file from within another.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.CALL [/Q]:ehp2. :hp3.file:ehp3.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  The batch file to execute.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./Q:ehp2.(uiet):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=CANCEL.CANCEL:elink. and :link
reftype=hd refid=QUIT.QUIT:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
The following batch file fragment compares an input line to "wp" and calls
another batch file if it matches&colon.
:xmp.
        input  Enter your choice&colon.  %%option
        if "%option" == "wp" call wp.bat
:exmp.:p.
&4OS2. supports batch file nesting up to ten levels deep.
:p.
The current ECHO state is inherited by a called batch file, except when the
:hp2./Q:ehp2..
:p.
The called batch file should always either return (by executing its last
line, or using the :link reftype=hd refid=QUIT.QUIT:elink. command), or
terminate batch file processing with :link reftype=hd
refid=CANCEL.CANCEL:elink..  Do not restart or CALL the original batch file
from within the called file as this may cause an infinite loop or a stack
overflow.
:p.
CALL returns an exit code which matches the batch file return code.
You can test this exit code with the :link reftype=hd
refid=__QMARK.%_?:elink. or :link reftype=hd refid=_QMARK.%?:elink.
environment variable, and use it with :link reftype=hd
refid=Conditional.conditional commands:elink..
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) Starts the new batch file with echo off,
regardless of the current batch file's echo state.  This switch is provided
for compatibility with OS/2's :hp1.CMD.EXE:ehp1..
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=CANCEL.CANCEL - Terminate batch file processing
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Terminate batch file processing.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.CANCEL [:ehp2.:hp3.value:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.value :ehp3.&colon.  The  numeric exit code to return to &4OS2..
:eparml.:p.
See also&colon.  :link reftype=hd refid=CALL.CALL:elink. and :link reftype=hd refid=QUIT.QUIT:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
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 files which are running at the time.
:p.
The following batch file fragment compares an input line to "end"
and terminates all batch file processing if it matches&colon.
:xmp.
        input Enter your choice&colon.  %%option
        if "%option" == "end" cancel
:exmp.:p.
If you specify a :hp1.value:ehp1., CANCEL will set the ERRORLEVEL or exit
code to that value (see the :link reftype=hd refid=IF.IF:elink. command, and
the :link reftype=hd refid=_QMARK.%?:elink. variable).

.* --------------------------------------------------------------------------

:h2 name=CD.CD - Change the current directory
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display or change the current directory.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.CD [/N] [ :ehp2.:hp3.path:ehp3. :hp2.&splitvbar. - ]:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.CHDIR [/N] [ :ehp2.:hp3.path:ehp3. :hp2.&splitvbar. - ]:ehp2.
.br
:pt.:pd.:hp3.path :ehp3.&colon.  The directory to change to, including an optional drive name.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./N:ehp2.(o extended search)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=CDD.CDD:elink., :link reftype=hd
refid=MD.MD:elink., :link reftype=hd refid=PUSHD.PUSHD:elink., :link
reftype=hd refid=RD.RD:elink., :link reftype=hd refid=CDPATH.CDPATH:elink.,
and :link reftype=hd refid=DirNav.Directory Navigation:elink..
:p.
:hp2.Usage:ehp2.
:p.
CD and CHDIR are synonyms.  You can use either one.
:p.
CD lets you navigate through a drive's 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 :hp1.C&colon.\FINANCE\MYFILES:ehp1. &colon.
:xmp.
        [c&colon.\] cd \finance\myfiles
        [c&colon.\finance\myfiles]
:exmp.:p.
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&colon.
:xmp.
        [c&colon.\] cd a&colon.\utility
        [c&colon.\]
:exmp.:p.
Notice that this command does not change to drive A&colon..  Use the CDD
command to change the current drive and directory at the same time.
:p.
When you use CD to change to a directory on an HPFS drive, you must quote
the :hp1.path:ehp1. name if it contains whitespace or special
characters.  See :link reftype=hd refid=Filenames.File Names and File
Systems:elink. for additional details.
:p.
You can change to the parent directory with :hp2.CD ..:ehp2.; you can also
go up one additional directory level with each additional [:hp2..:ehp2.].
For example, :hp2.CD ....:ehp2. will go up three levels in the directory
tree (see :link reftype=hd refid=ParDir.Extended Parent Directory
Names:elink.).  You can move to a sibling directory -- one that branches
from the same parent directory as the current subdirectory -- with a command
like :hp2.CD ..\newdir:ehp2..
:p.
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.
:p.
If CD cannot change to the directory you have specified it will attempt to
search the :link reftype=hd refid=CDPATH.CDPATH:elink. and the :link
reftype=hd refid=ExtDirSearch.extended directory search:elink. database in order
to find a matching directory and switch to it.  You can use :link
reftype=hd refid=Wildcards.wildcards:elink. in the :hp1.path:ehp1. to force
an extended directory search.  See the section on :link reftype=hd
refid=DirNav.Directory Navigation:elink. for complete details on these and
other directory navigation features.  To disable extended directory searches
for the current command (e.g. in a batch file) see the :hp2./N:ehp2. option
below.
:p.
CD saves the current directory before changing to a new directory.
You can switch back to the previous directory by entering :hp2.CD -:ehp2.
(there must be a space between the CD command and the hyphen).  You
can switch back and forth between two directories by repeatedly
entering :hp2.CD -:ehp2..  The saved directory is the same for both the CD
and CDD commands.  Drive changes and
:link reftype=hd refid=AutoDir.automatic directory changes:elink. also
modify the saved directory, so you can use :hp2.CD -:ehp2. to return to a
directory that you exited with an automatic directory change.
:p.
Directory changes made with CD are also recorded in the directory history
list and can be displayed in the :link reftype=hd refid=DirHist.directory
history window:elink., which allows you to return quickly to a recently-used
directory.
:p.
CD never changes the default drive.  If you change directories on
one drive, switch to another drive, and then enter :hp2.CD -:ehp2., the
directory will be restored on the first drive but the current drive
will not be changed.
:p.
:hp2.Option:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./N:ehp2.&colon.:pd.(No extended search) This option prevents CD
from searching the :link reftype=hd refid=ExtDirSearch.extended directory
search:elink. database or displaying the related popup window.  If
:hp2./N:ehp2. is used and the specified directory is not found via other
methods (i.e. without an extended search), CD will display an error.
This option is primarily intended for use in batch files where you do
not want CD to use "fuzzy" directory searching or display an extended
search popup window.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=CDD.CDD - Change the current drive and directory
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Change the current disk drive and directory.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.CDD [/A /N /S[drive ...]] [:ehp2.:hp3.path:ehp3. :hp2.&splitvbar. - ]:ehp2.
.br
:pt.:pd.:hp3.path :ehp3.&colon.  The name of the directory (or drive and directory) to change to.
:pt.:pd.:hp3.drive :ehp3.&colon.  A drive or list of drives to include in the
extended directory search database.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A:ehp2.(ll drives):pd.:hp2./N:ehp2.(o extended search)
:pt.:hp2./S:ehp2.(earch tree):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=CD.CD:elink., :link reftype=hd
refid=MD.MD:elink., :link reftype=hd refid=PUSHD.PUSHD:elink., :link
reftype=hd refid=RD.RD:elink., :link reftype=hd refid=CDPATH.CDPATH:elink.,
and :link reftype=hd refid=DirNav.Directory Navigation:elink..
:p.
:hp2.Usage:ehp2.
:p.
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 :hp1.C&colon.\WP&colon.:ehp1.
:xmp.
        [a&colon.\] cdd c&colon.\wp
        [c&colon.\wp]
:exmp.:p.
You can change to the parent directory with :hp2.CDD ..:ehp2.; you can
also go up one additional directory level with each additional
[:hp2..:ehp2.].  For example, :hp2.CDD ....:ehp2. will go up three levels in
the directory tree (see :link reftype=hd refid=ParDir.Extended Parent
Directory Names:elink.).
:p.
CDD can also change to a network drive and directory specified with a UNC
name (see :link reftype=hd refid=FileSys.File Systems:elink. for more
information about network directories).
:p.
When you use CDD to change to a directory on an HPFS drive, you must quote
the :hp1.path:ehp1. name if it contains whitespace or special
characters.  See :link reftype=hd refid=Filenames.File Names and File
Systems:elink. for additional details.
:p.
If CDD cannot change to the directory you have specified it will attempt to
search the :link reftype=hd refid=CDPATH.CDPATH:elink. and the :link
reftype=hd refid=ExtDirSearch.extended directory search:elink. database in order
to find a matching directory and switch to it.  You can also use :link
reftype=hd refid=Wildcards.wildcards:elink. in the :hp1.path:ehp1. to force
an extended directory search.  See the section on :link reftype=hd
refid=DirNav.Directory Navigation:elink. for complete details on these and
other directory navigation features.  To disable extended directory searches
for the current command (e.g. in a batch file) see the :hp2./N:ehp2. option
below.
:p.
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 :hp2.CDD -:ehp2. (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 :hp2.CDD -:ehp2..  The saved
directory is the same for both the CD and CDD commands.  Drive
changes and :link reftype=hd refid=AutoDir.automatic directory changes:elink. also modify
the saved directory, so you can use :hp2.CDD -:ehp2. to return to a
directory that you exited with a drive change or an automatic
directory change.
:p.
Directory changes made with CDD are also recorded in the directory history
list and can be displayed in the :link reftype=hd refid=DirHist.directory
history window:elink., which allows you to return quickly to a recently-used
directory.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(All drives) When CDD is used with this option, it
displays the current directory on all drives from C&colon. to the last drive
in the system.  You cannot move to a new drive and directory and use
:hp2./A:ehp2. in the same command.
:pt.:hp2./N:ehp2.&colon.:pd.(No extended search) This option prevents CD
from searching the :link reftype=hd refid=ExtDirSearch.extended directory
search:elink. database or displaying the related popup window.  If
:hp2./N:ehp2. is used and the specified directory is not found via other
methods (i.e. without an extended search), CD will display an error.
This option is primarily intended for use in batch files where you do
not want CD to use "fuzzy" directory searching or display an extended
search popup window.
:pt.:hp2./S:ehp2.&colon.:pd.(Search tree) Builds or rebuilds the :link
reftype=hd refid=ExtDirSearch.Extended Directory Search:elink. database,
:hp1.JPSTREE.IDX:ehp1..  You cannot move to a new drive and directory and
use :hp2./S:ehp2. in the same command.
:p.
To include all local hard drives in the database use the command&colon.
:xmp.
        cdd /s
:exmp.:p.
To limit or add to the list of drives included in the database, list the
drives and network volume names after the :hp2./S:ehp2. switch.  For
example, to include drives C, D, E, and the network volume \\server\dir1 in
the database, use this command&colon.
:xmp.
        cdd /s cde \\server\dir1
:exmp.:p.
All non-hidden directories on the listed drives will be indexed; you cannot
restrict the database to certain directories within a drive.  Each time you
use :hp2./S:ehp2., everything in the previous directory database is replaced
by the new database that is created.
:eparml.:lm margin=1.


.* --------------------------------------------------------------------------

:h2 name=CHCP.CHCP - Change the current code page
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display or change the current system code page.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.CHCP [:ehp2.:hp3.n:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.n :ehp3.&colon.  A system code page number.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
Code page switching allows you to select different character sets
for language support.
:p.
If you enter CHCP without a number, the current code page is
displayed.
:xmp.
        [c&colon.\] chcp
        Active code page&colon. 437
:exmp.:p.
If you enter CHCP plus a code page number, the system code page is
changed.  For example, to set the code page to multilingual&colon.
:xmp.
        [c&colon.\] chcp 850
:exmp.:p.
CHCP only affects the current &4OS2. session, and any new programs started
from within that session; the active code page in other sessions remains
unchanged.
:p.
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.
:p.
See your OS/2 documentation for more information on CHCP.

.* --------------------------------------------------------------------------

:h2 name=CLS.CLS - Clear the screen
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Clear the video display and move the cursor to the
upper left corner; optionally change the default display and border colors.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.CLS [[BRIght] [BLInk] :ehp2.:hp3.fg:ehp3. :hp2.ON [BRIght] :ehp2.:hp3.bg:ehp3. :hp2.]
[BORder :ehp2.:hp3.bc:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.fg :ehp3.&colon.  The new foreground color
:pt.:pd.:hp3.bg :ehp3.&colon.  The new background color
:pt.:pd.:hp3.bc :ehp3.&colon.  The new border color
:eparml.:p.
:hp2.Usage:ehp2.
:p.
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&colon.
:xmp.
        [c&colon.\] cls
        [c&colon.\] cls bright white on blue
        [c&colon.\] cls bri yel on mag bor blu
:exmp.:p.
CLS is often used in batch files to clear the screen before
displaying text.
:p.
See :link reftype=hd refid=Colors.Colors and Color Names:elink. for details about colors and
notes on the use of bright background colors.

.* --------------------------------------------------------------------------

:h2 name=COLOR.COLOR - Change the display colors
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Change the default display colors.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.COLOR [BRIght] [BLInk]:ehp2.
:hp3.fg:ehp3. :hp2.ON [BRIght]:ehp2. :hp3.bg:ehp3.
:hp2.[BORder :ehp2.:hp3.bc:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.fg :ehp3.&colon.  The new foreground color
:pt.:pd.:hp3.bg :ehp3.&colon.  The new background color
:pt.:pd.:hp3.bc :ehp3.&colon.  The new border color
:eparml.:p.
See also&colon.  :link reftype=hd refid=CLS.CLS:elink., and :link reftype=hd
refid=Colors.Colors and Color Names:elink. for details about using colors.
:p.
:hp2.Usage:ehp2.
:p.
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&colon.
:xmp.
        [c&colon.\] color bright white on blue
:exmp.

.* --------------------------------------------------------------------------

:h2 name=COPY.COPY - Copy files
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Copy data between disks, directories, files, or
physical hardware devices (such as your printer or serial port).
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.COPY [/A&colon.[[-]rhsda] /C /E /F /H /K
/M /N /P /Q /R /S /T /U /V /X /Z]:ehp2. :hp3.source:ehp3. :hp2.[+] ... [/A
/B]:ehp2. :hp3.destination:ehp3. :hp2.[/A /B]:ehp2.
.br
:pt.:pd.:hp3.source :ehp3.&colon.  A file or list of files or a device to copy :hp3.from:ehp3. .
:pt.:pd.:hp3.destination :ehp3.&colon.  A file, directory, or device to copy :hp3.to:ehp3. .
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A:ehp2.(SCII):pd.:hp2./P:ehp2.(rompt)
:pt.:hp2./A&colon.:ehp2. (Attribute select):pd.:hp2./Q:ehp2.(uiet)
:pt.:hp2./B:ehp2.(inary):pd.:hp2./R:ehp2.(eplace)
:pt.:hp2./C:ehp2.(hanged):pd.:hp2./S:ehp2.(ubdirectories)
:pt.:hp2./E:ehp2. (no Error messages):pd.:hp2./T:ehp2.(otals)
:pt.:hp2./F:ehp2.(ail on EA error):pd.:hp2./U:ehp2.(update)
:pt.:hp2./H:ehp2.(idden):pd.:hp2./V:ehp2.(erify)
:pt.:hp2./K:ehp2.(eep attributes):pd.:hp2./X:ehp2. (clear archive)
:pt.:hp2./M:ehp2.(odified):pd.:hp2./Z:ehp2. (overwrite)
:pt.:hp2./N:ehp2.(othing):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=ATTRIB.ATTRIB:elink., :link reftype=hd refid=MOVE.MOVE:elink., and :link reftype=hd refid=REN.REN:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link
reftype=hd refid=ranges.ranges:elink., :link reftype=hd
refid=MultFiles.multiple file names:elink., and :link reftype=hd
refid=InclList.include lists:elink..  :link reftype=hd refid=Ranges.Date,
time, size:elink., or :link reftype=hd refid=ExclRanges.exclude:elink.
ranges anywhere on the line apply to all :hp1.source:ehp1. files.
:p.
:hp2.Usage:ehp2.
:p.
The COPY command accepts all traditional syntax and options and
adds many new features.
:p.
The simplest use of COPY is to make a copy of a file, like this
example which makes a copy of a file called :hp1.FILE1.ABC:ehp1. &colon.
:xmp.
        [c&colon.\] copy file1.abc file2.def
:exmp.:p.
You can also copy a file to another drive and/or directory.  The
following command copies :hp1.FILE1:ehp1. to the :hp1.\MYDIR:ehp1. directory on
drive E&colon.
:xmp.
        [c&colon.\] copy file1 e&colon.\mydir
:exmp.:p.
You can copy several files at once by using
:link reftype=hd refid=wildcards.wildcards:elink.&colon.
:xmp.
        [c&colon.\] copy *.txt e&colon.\mydir
:exmp.:p.
When you COPY files to or from an HPFS drive, you must quote
the :hp1.path:ehp1. name if it contains whitespace or special
characters.  See :link reftype=hd refid=Filenames.File Names and File
Systems:elink. for additional details.
:p.
:hp2.Copying Files:ehp2.
:p.
You can copy several files at once by using :link reftype=hd
refid=Wildcards.wildcards:elink.&colon.
:xmp.
        [c&colon.\] copy *.txt e&colon.\mydir
:exmp.:p.
You can also list several :hp1.source:ehp1. files in one command.  The
following command copies 3 files from the current directory to the
:hp1.\MYDIR:ehp1. directory on drive E&colon.
:xmp.
        [c&colon.\] copy file1 file2 file3 e&colon.\mydir
:exmp.:p.
:p.
COPY also understands :link reftype=hd refid=InclList.include lists:elink.,
so you can specify several different kinds of files in the same
command.  This command copies the :hp1..TXT:ehp1., :hp1. .DOC:ehp1., and
:hp1..BAT :ehp1.files from the :hp1.E&colon.\MYDIR:ehp1. directory to the
root directory of drive A&colon.
:xmp.
        [c&colon.\] copy e&colon.\mydir\*.txt;*.doc;*.bat a&colon.\
:exmp.:p.
If there is only one argument on the line, COPY assumes it is the
:hp1.source:ehp1., and uses the current drive and directory as the
:hp1.destination:ehp1..  For example, the following command copies all the
:hp1..DAT:ehp1. files on drive A to the current directory on drive C&colon.
:xmp.
        [c&colon.\data] copy a&colon.*.dat
:exmp.:p.
If there are two or more arguments on the line, separated by spaces,
then COPY assumes that the last argument is the :hp1.destination:ehp1. and
copies all :hp1.source:ehp1. files to this new location.  If the
:hp1.destination:ehp1. is a drive, directory, or device name then the
:hp1.source:ehp1. files are copied individually to the new
location.  If the :hp1.destination:ehp1. is a file name, the first
:hp1.source:ehp1. file is copied to the :hp1.destination:ehp1., and any
additional :hp1.source:ehp1. files are then appended to the new
:hp1.destination:ehp1. file.
:p.
For example, the first of these commands copies the :hp1..DAT:ehp1. files
from the current directory on drive A individually to :hp1.C&colon.\MYDIR:ehp1.
(which must already exist as a directory); the second appends all
the :hp1..DAT:ehp1. files together into one large file called :hp1.C&colon.\DATA:ehp1.
(assuming :hp1.C&colon.\DATA:ehp1. is not a directory)&colon.
:xmp.
        [c&colon.\] copy a&colon.*.dat c&colon.\mydir\
        [c&colon.\] copy a&colon.*.dat c&colon.\data
:exmp.:p.
When you copy to a directory, if you add a backslash [:hp2.\:ehp2.] 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 :hp1.destination:ehp1. directory name as a file name and
attempting to append all your :hp1.source:ehp1. files to a
:hp1.destination:ehp1. :hp2.file:ehp2., when you really meant to copy them
individually to a :hp1.destination:ehp1. :hp2.directory:ehp2..
:p.
To copy a file to a device such as the printer, use the device name as the
:hp1.destination:ehp1., for example&colon.
:xmp.
        [c&colon.\] copy schedule.txt prn
:exmp.:p.
To copy text to or from the clipboard use :hp2.CLIP&colon.:ehp2. as the
device name.  Using CLIP&colon. with non-text data will produce unpredictable
results.  See :link reftype=hd refid=Redirection.Redirection:elink. for
additional information on CLIP&colon..
:p.
:hp2.Appending Files:ehp2.
:p.
A plus [:hp2.+:ehp2.] tells COPY to append two or more files to a single
:hp1.destination:ehp1. file.  If you list several :hp1.source:ehp1. files
separated with [:hp2.+:ehp2.] and don't specify a :hp1.destination:ehp1., COPY
will use the name of the first :hp1.source:ehp1. file as the destination,
and append each subsequent file to the first file.
:p.
For example, the following command will append the contents of
:hp1.C&colon.\MEMO2:ehp1. and :hp1.C&colon.\MEMO3:ehp1. to :hp1.C&colon.\MEMO1:ehp1. and leave the
combined contents in the file named :hp1.C&colon.\MEMO1:ehp1. &colon.
:xmp.
        [c&colon.\] copy memo1+memo2+memo3
:exmp.:p.
To append the same three files but store the result in
:hp1.BIGMEMO&colon.:ehp1.
:xmp.
        [c&colon.\] copy memo1+memo2+memo3 bigmemo
:exmp.:p.
To append :hp1.C&colon.\MEM\MEMO2:ehp1. and :hp1.C&colon.\MEM\MEMO3:ehp1. to
:hp1.D&colon.\DATA\MEMO1:ehp1., and leave the result in
:hp1.C&colon.\MEM\MEMO1:ehp1. &colon.

If no :hp1.destination:ehp1. is specified, the destination file will always
be created in the current directory even if the first :hp1.source:ehp1. file
is in another directory or on another drive.  For example, this command will
append :hp1.C&colon.\MEM\MEMO2:ehp1. and :hp1.C&colon.\MEM\MEMO3:ehp1. to
:hp1.D&colon.\DATA\MEMO1:ehp1., and leave the result in
:hp1.C&colon.\MEM\MEMO1:ehp1. &colon.
:xmp.
        [c&colon.\mem] copy d&colon.\data\memo1+memo2+memo3
:exmp.:p.
You cannot append files to a device (such as a printer); if you try
to do so, COPY will ignore the [:hp2.+:ehp2.] signs and copy the files
individually.  If you attempt to append several :hp1.source:ehp1. files to
a :hp1.destination:ehp1. directory or disk, COPY will append the files and
place the copy in the new location with the same name as the first
:hp1.source:ehp1. file.
:p.
:hp2.Advanced Features:ehp2.
:p.
If your :hp1.destination:ehp1. has wildcards in it, COPY will attempt to
match them with the :hp1.source:ehp1. names.  For example, this command
copies the :hp1..DAT:ehp1. files from drive A to :hp1.C&colon.\MYDIR:ehp1. and gives
the new copies the extension :hp1..DX:ehp1. &colon.
:xmp.
        [c&colon.\] copy a&colon.*.dat c&colon.\mydir\*.dx
:exmp.:p.
This feature can give you unexpected results if you use it with
multiple :hp1.source:ehp1. file names.  For example, suppose that drive A
contains :hp1.XYZ.DAT:ehp1. and :hp1.XYZ.TXT:ehp1..  The command
:xmp.
        [c&colon.\] copy a&colon.\*.dat a&colon.\*.txt c&colon.\mydir\*.dx
:exmp.:p.
will copy :hp1.A&colon.XYZ.DAT:ehp1. to :hp1.C&colon.\MYDIR\XYZ.DX:ehp1..  Then it will copy
:hp1.A&colon.XYZ.TXT:ehp1. to :hp1.C&colon.\MYDIR\XYZ.DX:ehp1., overwriting the first file it
copied.
:p.
COPY also understands :link reftype=hd refid=InclList.include lists:elink., so you can
specify several different kinds of files in the same command.  This
command copies the :hp1..TXT:ehp1., :hp1..DOC:ehp1., and :hp1..BAT:ehp1. files from the
:hp1.E&colon.\MYDIR:ehp1. directory to the root directory of drive A&colon.
:xmp.
        [c&colon.\] copy e&colon.\mydir\*.txt;*.doc;*.bat a&colon.\
:exmp.:p.
You can use :link reftype=hd refid=Ranges.date, time, and size ranges:elink. to further
define the files that you want to copy.  This example copies every
file in the :hp1.E&colon.\MYDIR:ehp1. 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&colon.
:xmp.
        [c&colon.\] copy /[d-1] /[s0,10000] e&colon.\mydir\*.* a&colon.\
:exmp.:p.
You can also use file exclusion ranges to restrict the list of files that
would normally be selected with wildcards.  This example copies every file
in the :hp1.E&colon.\MYDIR:ehp1. directory except backup (:hp1..BAK:ehp1. or
:hp1..BK!:ehp1.) files&colon.
:xmp.
        [c&colon.\] copy /[!*.bak;*.bk!] e&colon.\mydir\*.* a&colon.\
:exmp.:p.
COPY will normally process :hp1.source:ehp1. files which do not have the
hidden or system attribute, and will ignore the read-only and archive
attributes.  It will always set the archive attribute and clear the
read-only attribute of :hp1.destination:ehp1. files.  In addition, if the
:hp1.destination:ehp1. is an existing file with the read-only attribute,
COPY will generate an "Access Denied" error and refuse to overwrite the
file.  You can alter some of these behaviors with switches&colon.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A&colon.:ehp2.:pd.Forces COPY to process :hp1.source:ehp1. files
with the attributes you specify after the ":hp2.&colon.:ehp2.", or to process
all :hp1.source:ehp1. files regardless of attributes (if :hp2./A&colon.:ehp2.
is used by itself).
:pt.:hp2./H:ehp2.:pd.Forces COPY to process hidden and system
:hp1.source:ehp1. files, as well as normal files.  The hidden and system
attributes from each source file will be preserved when creating the
:hp1.destination:ehp1. files.
:pt.:hp2./K:ehp2.:pd.Retains the read-only attribute from each
:hp1.source:ehp1. file when creating the :hp1.destination:ehp1.file.  See
:hp2./K:ehp2. below for a special note if you are running under Novell
Netware.
:pt.:hp2./Z:ehp2.:pd.Forces COPY to overwrite an existing read-only
:hp1.destination:ehp1. file.
:eparml.:lm margin=1.
:p.
Use caution with :hp2./A&colon.:ehp2., :hp2./H:ehp2., or :hp2./K:ehp2. when
both the source and destination directories contain file descriptions.  If
the source file specification matches the description file name (normally
:hp1.DESCRIPT.ION:ehp1.), and you use a switch which tells COPY to process
hidden files, the :hp1.DESCRIPT.ION:ehp1. file itself will be copied,
overwriting any existing file descriptions in the destination directory.  For
example, if the :hp1.\DATA:ehp1. directory contains file descriptions this
command would overwrite any existing descriptions in the :hp1.\SAVE:ehp1.
directory&colon.
:xmp.
        [c&colon.\data] copy /h d*.* \save\
:exmp.:p.
(If you remove the hidden attribute from the :hp1.DESCRIPT.ION:ehp1. file
the same caution applies even if you do not use :hp2./A&colon.:ehp2.,
:hp2./H:ehp2., or :hp2./K:ehp2., as :hp1.DESCRIPT.ION:ehp1. is then treated
like any other file.)
:p.
If you copy a file from a FAT volume to an HPFS volume, and you do not give
an explicit :hp1.destination:ehp1. name (:hp1.i.e.:ehp1. you are moving the
file to the current directory, or your :hp1.destination:ehp1. name is made
up entirely of wildcards), COPY will look for a .LONGNAME extended attribute
for the :hp1.source:ehp1. file.  If it finds that attribute, it will use the
long filename for the destination file.  If it does not, it will use the
short name.
:p.
Similarly, if you COPY files with long filenames from an HPFS volume to a FAT
volume, &4OS2. will create the :hp1.destination:ehp1. files with short,
FAT-compatible names and save the long filenames in the .LONGNAME extended
attribute.  The short name is created by replacing special characters with
underscores, adding numeric digits to the filename (if necessary) to make
the new name unique, and truncating the name to fit with in the "8.3" FAT
name structure.
:p.
:hp2.Options:ehp2.
:p.
The :hp2./A:ehp2.(SCII) and :hp2./B:ehp2.(inary) options apply to the preceding
filename and to all subsequent filenames on the command line until
the file name preceding the next :hp2./A:ehp2. or :hp2./B:ehp2., if any.  The
other options (:hp2./A&colon.:ehp2., :hp2./C:ehp2., :hp2./E:ehp2.,
:hp2./H:ehp2., :hp2./K:ehp2., :hp2./M:ehp2., :hp2./N:ehp2., :hp2./P:ehp2.,
:hp2./Q:ehp2., :hp2./R:ehp2., :hp2./S:ehp2., :hp2./T:ehp2., :hp2./U:ehp2.,
:hp2./V:ehp2., :hp2./X:ehp2., :hp2./Z:ehp2.) 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&colon.
:xmp.
        [c&colon.\] copy /b myfont.dat prn
        [c&colon.\] copy myfont.dat /b prn
:exmp.:p.
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 :hp1.destination:ehp1. 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 :hp2./Q:ehp2.
and :hp2./P:ehp2., COPY will generally take a "conservative" approach and give
priority to the option which generates more prompts or more information.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(ASCII) If you use :hp2./A:ehp2. with a
:hp1.source:ehp1. filename, the file will be copied up to, but not
including, the first Ctrl-Z (Control-Z or ASCII 26) character in
the file (some application programs use the Ctrl-Z to mark the end of a
file).  If you use :hp2./A:ehp2. with a :hp1.destination:ehp1. filename,
a Ctrl-Z will be added to the end of the file.  :hp2./A:ehp2. is the default
when appending files, or when the :hp1.destination:ehp1. is a device like
NUL or PRN, rather than a disk file.  Also see :hp2./B:ehp2..
:pt.:hp2./A&colon.:ehp2.&colon.:pd.(Attribute select) Select only those
files that have the specified attribute(s) set.  Preceding the attribute
character with a hyphen [:hp2.-:ehp2.] will select files that do not have
that attribute set.  The colon [:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is
required.  The attributes are&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.COPY
/A&colon. ...:ehp2.), COPY will select all files and subdirectories including hidden
and system files.  If attributes are combined, all the specified attributes
must match for a file to be selected. For example, /A&colon.RHS will select
only those files with all three attributes set.
:p.
See the cautionary note under :hp2.Advanced Features:ehp2. above before
using :hp2./A&colon.:ehp2. when both :hp1.source:ehp1. and
:hp1.destination:ehp1. directories contain file descriptions.
:p.
You must include the colon with this option to distinguish it from the
:hp2./A:ehp2.(SCII) switch, above.
:pt.:hp2./B:ehp2.&colon.:pd.(Binary) If you use :hp2./B:ehp2. with a :hp1.source:ehp1. filename, the
entire file is copied; Ctrl-Z characters in the file do not affect the copy
operation.  Using :hp2./B:ehp2. with a :hp1.destination:ehp1. filename
prevents addition of a Ctrl-Z to the end of the :hp1.destination:ehp1.
file.  :hp2./B:ehp2. is the default for normal file copies.  Also see
:hp2./A:ehp2..
:pt.:hp2./C:ehp2.&colon.:pd.(Changed files) Copy files only if the :hp1.destination:ehp1.
file exists and is older than the :hp1.source:ehp1. (see
also :hp2./U:ehp2.).  This option is useful for updating
the files in one directory from those in another
without copying any newly created files.
:pt.:hp2./E:ehp2.&colon.:pd.(no Error messages) Suppress all non-fatal error
messages, such as "File not found."  Fatal error messages, such as "Drive
not ready," will still be displayed.  This option is most useful in batch
files and aliases.
:pt.:hp2./F:ehp2.&colon.:pd.(Fail on EA error) Fail if the source file has
extended attributes and the destination file system doesn't support extended
attributes.
:pt.:hp2./H:ehp2.&colon.:pd.(Hidden) Copy all matching files including those with the
hidden and/or system attribute set.
:p.
See the cautionary note under :hp2.Advanced Features:ehp2. above before
using :hp2./H:ehp2. when both :hp1.source:ehp1. and :hp1.destination:ehp1.
directories contain file descriptions.
:pt.:hp2./K:ehp2.&colon.:pd.(Keep attributes) To maintain compatibility with
:hp1.CMD.EXE:ehp1., COPY normally maintains the hidden and system
attributes, sets the archive attribute, and removes the read-only attribute
on the destination file.  :hp2./K:ehp2. tells COPY to also maintain the read-only
attribute on the :hp1.destination:ehp1. file.  However, if the
:hp1.destination:ehp1. is on a Novell Netware volume, this option will fail
to maintain the read-only attribute.  This is due to the way Netware handles
file attributes, and is not a problem in COPY.
:pt.:hp2./M:ehp2.&colon.:pd.(Modified) Copy only those files with the archive
attribute set, :hp1.i.e.:ehp1., those which have been modified since the last
backup.  The archive attribute of the :hp1.source:ehp1. will :hp2.not:ehp2.
be cleared after copying; to clear it use the :hp2./X:ehp2. switch, or use
:link reftype=hd refid=ATTRIB.ATTRIB:elink..
:pt.:hp2./N:ehp2.&colon.:pd.(Nothing) Do everything except actually perform
the copy.  This option is useful for testing what the result of a complex
COPY command will be.  :hp2./N:ehp2. does :hp2.not:ehp2. prevent creation of
:hp1.destination:ehp1. subdirectories when it is used with :hp2./s:ehp2..
:pt.:hp2./P:ehp2.&colon.:pd.(Prompt) Ask the user to confirm each
:hp1.source:ehp1. file.  Your options at the prompt are explained in detail
under :link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) Don't display filenames or the total number of files
copied.  This option is most often used in batch
files.  See also :hp2./T:ehp2..
:pt.:hp2./R:ehp2.&colon.:pd.(Replace) Prompt the user before overwriting an existing
file.   Your options at the prompt are explained in
detail under :link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./S:ehp2.&colon.:pd.(Subdirectories) Copy the subdirectory tree
starting with the files in the :hp1.source:ehp1. directory plus each
subdirectory below that.  The :hp1.destination:ehp1. 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 :hp1.destination:ehp1.,
including empty :hp3.source:ehp3. directories.  If COPY /S creates one or
more destination directories, they will be added automatically to the
:link reftype=hd refid=ExtDirSearch.extended directory search:elink. database.
:p.
If you attempt to use COPY /S to copy a subdirectory tree into part of
itself, COPY will detect the resulting infinite loop, display an error
message, and exit.
:pt.:hp2./T:ehp2.&colon.:pd.(Totals) Turns off  the display of filenames, like :hp2./Q:ehp2.,
but does display the total number of files copied.
:pt.:hp2./U:ehp2.&colon.:pd.(Update) Copy each :hp1.source:ehp1. file only
if it is newer than a matching :hp1.destination:ehp1. file or if a matching
:hp1.destination:ehp1. file does not exist (see also :hp2./C:ehp2.).  This
option is useful for keeping one directory matched with another with a
minimum of copying.
:pt.:hp2./V:ehp2.&colon.:pd.(Verify) Verify each disk write.  This is the
same as executing the VERIFY ON command, but is only active during the
COPY.  :hp2./V:ehp2. does :hp2.not:ehp2. read back the file and compare its
contents with what was written; it only verifies that the data written to
disk is physically readable.
:pt.:hp2./X:ehp2.&colon.:pd.Clears the archive attribute
from the source file after a successful copy.  This option is most useful if
you are using COPY to maintain a set of backup files.
:pt.:hp2./Z:ehp2.&colon.:pd.Overwrites read-only
:hp1.destination:ehp1. files.  Without this option, COPY will fail with an
"Access denied" error if the :hp1.destination:ehp1. file has its read-only
attribute set.  This option allows COPY to overwrite read-only files without
generating any errors.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=DATE.DATE - Change the system date
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display and optionally change the system date.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DATE [:ehp2.:hp3.mm:ehp3.
:hp2.-:ehp2.:hp3.dd:ehp3. :hp2.-:ehp2.:hp3.yy:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.mm :ehp3.&colon.  The month (1 - 12).
:pt.:pd.:hp3.dd :ehp3.&colon.  The day (1 - 31).
:pt.:pd.:hp3.yy :ehp3.&colon.  The year (00 - 99, or a 4- digit year).
:eparml.:p.
See also&colon.  :link reftype=hd refid=TIME.TIME:elink..
:p.
:hp2.Usage:ehp2.
:p.
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&colon.
:xmp.
        [c&colon.\] date
        Mon  Dec 22, 1997  9&colon.30&colon.06
        Enter new date (mm-dd-yy)&colon.
:exmp.:p.
You can also enter a new system date by typing the DATE command
plus the new date on the command line&colon.
:xmp.
        [c&colon.\] date 10-16-97
:exmp.:p.
You can use hyphens, slashes, or periods to separate the month,
day, and year entries.  The year can be entered as a 4-digit or 2-digit
value.  Two-digit years between 80 and 99 are interpreted as 1980 - 1999;
values between 00 and 79 are interpreted as 2000 - 2079.
:p.
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.

.* --------------------------------------------------------------------------

:h2 name=DEL.DEL - Delete one or more files
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Erase one file, a group of files, or entire
subdirectories.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DEL [/A&colon.[[-]rhsda] /E /F /N /P /Q
/S /T /W /X /Y /Z] :ehp2.:hp3.file:ehp3. :hp2....:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.ERASE [/A&colon.[[-]rhsda] /E /F /N /P /Q /S /T /W /X /Y /Z]
:ehp2.:hp3.file:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  The file, subdirectory, or list of files or subdirectories to erase.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2. (ttribute select):pd.:hp2./S:ehp2.(ubdirectories)
:pt.:hp2./E:ehp2. (no Error messages):pd.:hp2./T:ehp2.(otal)
:pt.:hp2./F:ehp2.(orce delete):pd.:hp2./W:ehp2.(ipe)
:pt.:hp2./N:ehp2.(othing):pd.:hp2./X:ehp2. (remove empty subdirectories)
:pt.:hp2./P:ehp2.(rompt):pd.:hp2./Y:ehp2.(es to all prompts)
:pt.:hp2./Q:ehp2.(uiet):pd.:hp2./Z:ehp2.(ap hidden and read-only files)
:eparml.:lm margin=1.
.br
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and :link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
DEL and ERASE are synonyms, you can use either one.
:p.
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.
:p.
To erase a single file, simply enter the file name&colon.
:xmp.
        [c&colon.\] del letters.txt
:exmp.:p.
You can also erase multiple files in a single command.  For
example, to erase all the files in the current directory with a
:hp1..BAK:ehp1. or :hp1..PRN:ehp1. extension&colon.
:xmp.
        [c&colon.\] del *.bak *.prn
:exmp.:p.
When you use DEL on an HPFS drive, you must quote any file names
which contain whitespace or special characters.  See :link reftype=hd
refid=FileNames.File Names:elink. for additional details.
:p.
To exclude files from a DEL command, use a :link reftype=hd
refid=ExclRanges.file exclusion range:elink..  For example, to delete all
files in the current directory except those whose extension is
:hp1..TXT:ehp1., use a command like this&colon.
:xmp.
        [c&colon.\] del /[!*.TXT] *.*
:exmp.:p.
When using exclusion ranges or other more complex options you may want to use
the :hp2./N:ehp2. switch first, to preview the effects of the DEL without
actually deleting any files.
:p.
If you enter a subdirectory name, or a filename composed only of
wildcards (* and/or ?), DEL asks for confirmation (:hp2.Y:ehp2. or
:hp2.N:ehp2.) unless you specified the :hp2./Y:ehp2. option.  If you respond
with a :hp2.Y:ehp2., DEL will delete all the files in that subdirectory
(hidden, system, and read-only files are only deleted if you use the
:hp2./Z:ehp2. option).
:p.
DEL displays the amount of disk space recovered, unless the :hp2./Q:ehp2.
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.
:p.
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.
:p.
When a file is deleted, its disk space is returned to the operating system
for use by other files.  However, the contents of the file remain on the
disk until they are overwritten by another file.  If you wish to obliterate
a file or wipe its contents clean, use DEL /W, which overwrites the file
with zeros before deleting it.  Use this option with caution -- once a file
is obliterated, it is impossible to recover.
:p.
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
:link reftype=hd refid=_QMARK.%_?:elink. environment variable, and use it with
the :link reftype=hd refid=Conditional.conditional commands:elink.
:hp2.&amp.&amp.:ehp2. and :hp2.&splitvbar.&splitvbar.:ehp2.).
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A&colon.:ehp2.&colon.:pd.(Attribute select) Select only those files that have the
specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute set.  The colon
[:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is required.  The attributes are&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.DEL /A&colon. ...:ehp2.), DEL will select all
files and subdirectories including hidden and system files.  If attributes are combined,
all the specified attributes must match for a file to be selected. For example,
/A&colon.RHS will select only those files with all three attributes set.
:pt.:hp2./E:ehp2.&colon.:pd.(No error messages) Suppress all non-fatal
error messages, such as "File Not Found."  Fatal error messages, such as
"Drive not ready," will still be displayed.  This option is most useful in
batch files and aliases.
:pt.:hp2./F:ehp2.&colon.:pd.(Force delete) This option forces deletion of the
file without saving it to the DELDIR directory (if DELDIR is not in use,
:hp2./F:ehp2. has no effect).
:pt.:hp2./N:ehp2.&colon.:pd.(Nothing) Do everything except actually delete the
file(s).  This is useful for testing what the result
of a DEL would be.
:pt.:hp2./P:ehp2.&colon.:pd.(Prompt) Prompt the user to confirm each erasure.  Your
options at the prompt are explained in detail under
:link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) Don't display filenames as they are deleted, or the
number of files deleted or bytes freed.  See also :hp2./T:ehp2..
:pt.:hp2./S:ehp2.&colon.:pd.(Subdirectories) Delete the specified files in
this directory and all of its subdirectories.  This can be used to delete
all the files in a subdirectory tree or even a whole disk.  :hp8.It should
be used with caution!:ehp8.
:pt.:hp2./T:ehp2.&colon.:pd.(Total) 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 :hp2./Q:ehp2., the :hp2./T:ehp2. option
will not speed up deletions under DOS.
:pt.:hp2./W:ehp2.&colon.:pd.(Wipe) Clear the file to zeros before deleting
it.  Use this option to completely obliterate a file's contents from your
disk.  Once you have used this option it is impossible to recover the file
even if you are using an undelete utility, because the contents of the file
are destroyed before it is deleted.  :hp2./W:ehp2. overwrites the file only
once; it does :hp2.not:ehp2. adhere to security standards which require
multiple overwrites with varying data when destroying sensitive information.
:pt.:hp2./X:ehp2.&colon.:pd.(Remove empty subdirectories) Remove empty subdirectories
after deleting (only useful when used with :hp2./S:ehp2.).  If DEL deletes
one or more directories, they will be removed automatically from the :link
reftype=hd refid=ExtDirSearch.extended directory search:elink. database.
:pt.:hp2./Y:ehp2.&colon.:pd.(Yes) The reverse of :hp2./P:ehp2. -- it assumes
a :hp2.Y:ehp2. response to everything, including deleting an entire
subdirectory tree.  &4OS2. normally prompts before deleting files when the
name consists only of wildcards or a subdirectory name (see above);
:hp2./Y:ehp2. overrides this protection, and should be used with extreme
caution!
:pt.:hp2./Z:ehp2.&colon.:pd.(Zap) 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; :hp2./Z:ehp2. overrides this protection, and
should be used with caution.  Because
:link reftype=hd refid=EXCEPT.EXCEPT:elink. works by hiding files, :hp2./Z:ehp2.
will override an EXCEPT command.  However, files specified in a :link
reftype=hd refid=ExclRanges.file exclusion range:elink. will not be deleted
by DEL /Z.
:p.
For example, to delete the entire subdirectory tree starting with
C&colon.\UTIL, including hidden and read-only files, without prompting (use
this command with CAUTION!)&colon.
:xmp.
        [c&colon.\] del /sxyz c&colon.\util\
:exmp.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=DELAY.DELAY - Pause for a specified length of time
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Pause for a specified length of time.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DELAY [:ehp2.:hp3.seconds:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.seconds :ehp3.&colon.  The number of seconds to delay.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
DELAY is useful in batch file loops while waiting for something to
occur.  To wait for 10 seconds&colon.
:xmp.
        delay 10
:exmp.:p.
DELAY is most useful when you need to wait a specific amount of time for an
external event, or check a system condition periodically.  For example, this
batch file checks the battery status (as reported by your Advanced Power
Management drivers) every 15 seconds, and gives a warning when battery life
falls below 30%&colon.
:xmp.
        do forever
           iff %_apmlife lt 30 then
              beep 440 4 880 4 440 4 880 4
              echo Low Battery!!
           endiff
           delay 15
        enddo
:exmp.:p.
The seconds value can be as large as 4 million seconds (49 days).
:p.
For delays shorter than one second, use the :link reftype=hd
refid=BEEP.BEEP:elink. command with an inaudible frequency (below 20 Hz).
:p.
&4OS2. uses the minimum possible processor time during a DELAY, in order to
allow other applications full use of system resources.
:p.
You can cancel a delay by pressing :hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2..

.* --------------------------------------------------------------------------

:h2 name=DESCRIBE.DESCRIBE - Create or modify file descriptions
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Create, modify, or delete file and subdirectory
descriptions.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DESCRIBE [/A&colon.[[-]rhsda]]:ehp2.
:hp3.file:ehp3. :hp2.[[/D]:ehp2.":hp3.description:ehp3. ":hp2.] ...:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  The file, directory, or list of files and
directories to operate on.
:pt.:pd.:hp3.description :ehp3.&colon.  The description to attach to the file.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2. (Attribute select):pd.:hp2./D:ehp2.(escription follows)
:eparml.:lm margin=1.
.br
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and :link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
DESCRIBE adds descriptions to files and subdirectories.  The
descriptions can be displayed by :link reftype=hd refid=DIR.DIR:elink. in
single-column mode and by :link reftype=hd
refid=SELECT.SELECT:elink..  Descriptions let you identify your files in
much more meaningful ways than you can in an eight-character filename.
:p.
You enter a description on the command line by typing the DESCRIBE
command, the filename, and the description in quotation marks, like
this&colon.
:xmp.
        [c&colon.\] describe memo.txt "Memo to Bob about party"
:exmp.:p.
If you don't put a description on the command line, DESCRIBE will
prompt you for it&colon.
:xmp.
        [c&colon.\] describe memo.txt
        Describe "memo.txt" &colon. Memo to Bob about party
:exmp.:p.
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.
:p.
If you use DESCRIBE on an HPFS drive, you must quote the :hp1.file:ehp1.
name if it contains whitespace or special characters.  See :link
reftype=hd refid=FileNames.File Names:elink. for additional details.
:p.
If you enter a quoted description on the command line, and the text
matches the name of a file in the current directory, the command
processor will treat the string as a quoted file name, not as
description text as you intended.  To resolve this problem use the
:hp2./D:ehp2. switch immediately prior to the quoted description (with
no intervening spaces).  For example, if the current directory contains
the files :hp1.DATA.TST:ehp1. and :hp1."Test File":ehp1., the first of
these commands will work as intended, but the second will not (in the
second example the string "test file" will be treated as a second file
name, when it is intended to be description text):
:xmp.
        [c&colon.\] describe data.tst /D"test file"
        [c&colon.\] describe data.tst "test file"
:exmp.:p.
On HPFS drives you will not see file descriptions in a normal :link
reftype=hd refid=DIR.DIR:elink. display, because DIR must leave space
for the long filenames.  To view the descriptions, use :hp2.DIR /Z:ehp2.
to display the directory in FAT format.
:p.
Each description can be up to 511 characters long.  You can change this
limit with the :link reftype=hd refid=INI_DescriptionMax.DescriptionMax:elink.
directive in :hp1.&4OS2INI.:ehp1..  In order to fit your descriptions on a
single line in a standard DIR display, keep them to 4o characters or less
(longer descriptions are wrapped in the DIR output).  DESCRIBE can edit
descriptions longer than DescriptionMax (up to a limit of 511 characters),
but will not allow you to lengthen the existing text.
:p.
The descriptions are stored in each directory in a hidden file
called :hp1.DESCRIPT.ION:ehp1..  Use the :link reftype=hd refid=ATTRIB.ATTRIB:elink. command to
remove the hidden attribute from this file if you need to copy or
delete it.  :hp1.DESCRIPT.ION:ehp1. is always created as a hidden file,
but will not be re-hidden by &4OS2. if you remove the hidden
attribute.
:p.
You can change the description file name with the :link reftype=hd
refid=SETDOS.SETDOS:elink. /D command, or the :link reftype=hd
refid=INI_DescriptionName.DescriptionName:elink. directive in &4OS2INI., and
retrieve it with the :link reftype=hd refid=_DName._DName:elink. internal
variable.  Use caution when changing the description file name, as changing
the name from the default will make it difficult to transfer file
descriptions to another system.
:p.
The description file is modified appropriately whenever you perform
an internal command which affects it (such as :link reftype=hd refid=COPY.COPY:elink.,
:link reftype=hd refid=MOVE.MOVE:elink., :link reftype=hd refid=DEL.DEL:elink., or :link reftype=hd refid=REN.RENAME:elink.), but not if
you use an external program (such as XCOPY or a visual shell).  You can
disable description processing on the Options 1 page of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs, with the :link reftype=hd
refid=INI_Descriptions.Descriptions:elink. directive in the :hp1..INI:ehp1.
file, or with :link reftype=hd refid=SETDOS.SETDOS:elink. /D.
:p.
When you :link reftype=hd refid=COPY.COPY:elink. or :link reftype=hd
refid=MOVE.MOVE:elink. files between two directories, both of which have
descriptions, and you use switches which enable processing of hidden files
(or you have removed the hidden attribute from :hp1.DESCRIPT.ION:ehp1.), you
must use caution to avoid overwriting existing file descriptions in the
:hp1.destination:ehp1. directory with the :hp1.DESCRIPT.ION:ehp1. file from
the :hp1.source:ehp1. directory.  See the notes under the :hp2.Advanced
Features:ehp2. sections of COPY and MOVE for additional details.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A&colon.:ehp2.&colon.:pd.(Attribute select) Select only those files that have the
specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute set.  The colon
[:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is required.  The attributes
are&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1.,
:hp2.DESCRIBE /A&colon. ...:ehp2.), DESCRIBE will
select all files and subdirectories including hidden and system files.  If
attributes are combined, all the specified attributes must match for a
file to be selected. For example, /A&colon.RHS will select only those files
with all three attributes set.
:pt.:hp2./D:ehp2.&colon.:pd.(Description follows) The quoted string
immediately following this switch is a description, not a file name.
Use :hp2./D:ehp2. to avoid any ambiguity in the meaning of quoted
strings.  See the :hp2.Usage:ehp2. section above for details.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=DETACH.DETACH - Start a program in detached mode
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Start an OS/2 program in detached mode.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DETACH :ehp2.:hp3.command:ehp3.
.br
:pt.:pd.:hp3.command :ehp3.&colon.  The name of a command to execute,
including an optional drive and path specification.
:eparml.:p.
See also&colon.  :link reftype=hd refid=START.START:elink..
:p.
:hp2.Usage:ehp2.
:p.
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
:link reftype=hd refid=RedirPipe.redirection:elink. symbols.
:p.
The :hp2.command:ehp2. can be an internal command, external command,
alias, or batch file.  If it is not an external command, &4OS2. will
detach a copy of itself to execute the command.
:p.
For example, the following command will detach a copy of &4OS2. to
run the batch file :hp1.XYZ.BTM:ehp1. &colon.
:xmp.
        [c&colon.\] detach xyz.btm
:exmp.:p.
Once the program has started, &4OS2. returns to the prompt
immediately.  It does not wait for a detached program to finish.
:p.
There is no standard way to stop a detached program.  If the program does not
terminate on its own you must reboot the system or use an appropriate task
manager or external utility to stop it.

.* --------------------------------------------------------------------------

:h2 name=DIR.DIR - Display directories
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display information about files and subdirectories.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DIR [/1 /2 /4 /A[[&colon.][-]rhsda] /B
/D /E /F /G /H /I"text" /J /K /L /M /N /O[[&colon.][-]adeginrsu] /P /R /S
/T[&colon.acw] /U /V /W /Z] [:ehp2.:hp3.file:ehp3. :hp2....]:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  The file, directory, or list of files or
directories to display.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./1:ehp2. (one column):pd.:hp2./L:ehp2.(ower case)
:pt.:hp2./2:ehp2. (two columns):pd.:hp2./M:ehp2. (suppress footer)
:pt.:hp2./4:ehp2. (four columns):pd.:hp2./N:ehp2.(ew format)
:pt.:hp2./A:ehp2.(ttribute select):pd.:hp2./O:ehp2.(rder)
:pt.:hp2./B:ehp2.(are):pd.:hp2./P:ehp2.(ause)
:pt.:hp2./D:ehp2.(isable color coding):pd.:hp2./R:ehp2. (disable wRap)
:pt.:hp2./E:ehp2. (use upper case):pd.:hp2./S:ehp2.(ubdirectories)
:pt.:hp2./F:ehp2.(ull path):pd.:hp2./T:ehp2. (aTtribute) or (Time)
:pt.:hp2./G:ehp2. (allocated size):pd.:hp2./U:ehp2. (sUmmary information)
:pt.:hp2./H:ehp2.(ide dots):pd.:hp2./V:ehp2.(ertical sort)
:pt.:hp2./I:ehp2. (match descriptions):pd.:hp2./W:ehp2.(ide)
:pt.:hp2./J:ehp2.(ustify names):pd.:hp2./Z:ehp2. (use FAT format)
:pt.:hp2./K:ehp2. (suppress header):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=ATTRIB.ATTRIB:elink., :link
reftype=hd refid=DESCRIBE.DESCRIBE:elink., :link reftype=hd
refid=SELECT.SELECT:elink., and :link reftype=hd refid=SETDOS.SETDOS:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and :link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
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, 5, or more columns, sort the files
several different ways, use color to distinguish file types, and
pause after each full screen.
:p.
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 :link reftype=hd refid=ALIAS.ALIAS:elink.
command.
:p.
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&colon.
:xmp.
        [c&colon.\] dir /2/p/v
:exmp.:p.
To set up this format as the default, using an alias&colon.
:xmp.
        [c&colon.\] alias dir=*dir /2/p/v
:exmp.:p.
When you use DIR on an HPFS drive, you must quote any file
names which contain whitespace or special characters.  See :link reftype=hd
refid=Filenames.File Names:elink. for additional details.
:p.
The following sections group DIR's features together in several
categories.  Many of the sections move from a general discussion to more
technical material.  If you find some of the information in a category too
detailed for your needs, feel free to skip to the beginning of the next
section.  The sections are&colon.
:p.
:lm margin=8.:parml compact tsize=4 break=fit.
:hp2.
:pt.:pd.Selecting Files
:pt.:pd.Default DIR Output Format
:pt.:pd.Switching Formats
:pt.:pd.Multiple Column Displays
:pt.:pd.Color-Coded Directories
:pt.:pd.Redirected Output
:pt.:pd.Other Notes
:pt.:pd.Options
:ehp2.
:eparml.:lm margin=1.
:p.
:hp2.Selecting Files:ehp2.
:p.
DIR can display information about a single file or about several, dozens,
hundreds, or thousands of files at once.  To display information about a
single file, just add the name of the file to the DIR command line&colon.
:xmp.
        [c&colon.\] dir january.wks
:exmp.:p.
The simplest way to view information about several files at once is to use
wildcards.  DIR can work with traditional wildcard characters (:hp2.*:ehp2.
and :hp2.?:ehp2.) and
the extended :link reftype=hd refid=Wildcards.wildcards:elink..  For example
to display all of the :hp1..WKS:ehp1. files in the current directory&colon.
:xmp.
        [c&colon.\] dir *.wks
:exmp.:p.
To display all :hp1..TXT:ehp1. files whose names begin with A, B, or C&colon.
:xmp.
        [c&colon.\] dir [abc]*.txt
:exmp.:p.
If you don't specify a filename, DIR defaults to :hp2.*.*:ehp2. on
traditional FAT drives, and :hp2.*:ehp2. on HPFS drives.  This default
displays all non-hidden files and subdirectories in the current directory.
:p.
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
:hp1..WKS:ehp1. and then all of the :hp1..WK1:ehp1. files in the current
directory&colon.
:xmp.
        [c&colon.\] dir *.wks *.wk1
:exmp.:p.
If you use an :link reftype=hd refid=InclList.include list:elink. 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 :hp1..WKS:ehp1.
and :hp1..WK1:ehp1. files are intermixed&colon.
:xmp.
        [c&colon.\] dir *.wks;*.wk1
:exmp.:p.
:p.
You can include files in the current or named directory plus all of its
subdirectories by using the :hp2./S:ehp2. option.  This example displays all
of the :hp1..WKS:ehp1. and :hp1..WK1:ehp1. files in the D&colon.\DATA
directory and each of its subdirectories&colon.
:xmp.
        [c&colon.\] dir /s d&colon.\data\*.wks;*.wk1
:exmp.:p.
You can also select files by their attributes by using the :hp2./A:ehp2.
option.  For example, this command displays the names of all of the
subdirectories of the current directory&colon.
:xmp.
        [c&colon.\] dir /a&colon.d
:exmp.:p.
Finally, with the :hp2./I:ehp2. option, DIR can select files to display
based on their descriptions (see the :link reftype=hd
refid=DESCRIBE.DESCRIBE:elink. command for more information on file
descriptions).  DIR will display a file if its description matches the text
after the :hp2./I:ehp2. switch.  The search is not case sensitive.  You can
use :link reftype=hd refid=Wildcards.wildcards:elink. and extended wildcards
as part of the text.  For example, to display any file described as a "Test
File" you can use this command&colon.
:xmp.
        [c&colon.\] dir /i"test file"
:exmp.:p.
If you want to display files that include the words "test file" anywhere in
their descriptions, use extended wildcards like this&colon.
:xmp.
        [c&colon.\] dir /i"*test file*"
:exmp.:p.
To display only those files which do :hp2.not:ehp2. have descriptions,
use&colon.
:xmp.
        [c&colon.\] dir /I"[]"
:exmp.:p.
In addition, you can use :link reftype=hd refid=TOC_Ranges.ranges:elink. to
select or exclude specific sets of files.  For example, to display all files
modified in the last week, all files except those with a :hp1..BAK:ehp1.
extension, and all files over 500 KB in size&colon.
:xmp.
        [c&colon.\] dir /[d-7]
        [c&colon.\] dir /[!*.bak]
        [c&colon.\] dir /[s500K]
:exmp.:p.
You can, of course, mix any of these file selection techniques in whatever
ways suit your needs.
:p.
:hp2.Default DIR Output Format:ehp2.
:p.
DIR's output varies based on the type of volume or drive on which the files
are stored.  On an HPFS volume, the default DIR format contains 4
columns&colon. the date of the last file modification or write, the
time of last write, the file size in bytes, and the file name.  The name is
displayed as it is stored on the disk, in upper, lower, or mixed case.  DIR
will wrap filenames from one line to the next if they are too long to fit the
width of the display.  The standard output format is&colon.
:xmp.
         Volume in drive C is C - BOOTUP    Serial ...
         Directory of  C&colon.\&4OS2.301\*.*
:p.
        10-24-96  12&colon.17         <DIR>    .
        10-24-96  12&colon.17         <DIR>    ..
        10-28-96   7&colon.57             967  &4OS2. 3.txt
        10-21-96  18&colon.08         212,854  &4OS2..EXE
        11-02-96  10&colon.08              45  &4OS2INI.
:exmp.:p.
(See :hp2.Switching Formats:ehp2. below for information on changing the
standard long filename format to allow room for file descriptions.)
:p.
On FAT volumes which do not support long file names, the default DIR format
contains 5 columns&colon. the file name, the file size in bytes, the date of
the last write, the time of the last write, and the file's description.  File
names are listed in lower-case; directory names in upper case&colon.
:xmp.
         Volume in drive C is C - BOOTUP    Serial ...
         Directory of  C&colon.\&4OS2.30\*.*
:p.
        .            <DIR>     10-24-96  12&colon.17
        ..           <DIR>     10-24-96  12&colon.17
        TEST         <DIR>     11-01-96  16&colon.21
        &4OS2.3.txt         967  10-28-96   7&colon.57
        &4OS2..exe       212854  10-21-96  18&colon.08 &4OS2. exe ...
        &4OS2INI.           45  11-02-96  10&colon.08 &4OS2. conf ...
:exmp.:p.
DIR's output is normally sorted by name, with directories listed first.  You
can change the sort order with the :hp2./O:ehp2. option.  For example, these
two commands sort the output by date -- the first command lists the oldest
file first; the second command lists the oldest file last&colon.
:xmp.
        [c&colon.\] dir /o&colon.d
        [c&colon.\] dir /o&colon.-d
:exmp.:p.
When displaying file descriptions, DIR wraps 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 :hp2./R:ehp2.
option, the description is truncated at the right edge of the
screen, and a right arrow [:hp2.:ehp2.] is added at the end of the line to
alert you to the existence of additional description text.
:p.
Regardless of the volume type, DIR's default output is sorted.  It displays
directory names first, with "<DIR>" inserted instead of a file size, and then
filenames.  DIR assumes that sequences of digits should be sorted numerically
(for example, the file :hp1.DRAW2:ehp1. is listed before :hp1.DRAW03:ehp1.
because 2 is numerically smaller than 03), rather than strictly
alphabetically (where :hp1.DRAW2 :ehp1.would come second because "2" is
after "0" in alphanumeric order).  You can change the sort order with the
:hp2./O:ehp2. option.  When DIR displays file names in a multi-column
format, it sorts file names horizontally unless you use the :hp2./V:ehp2.
option to display vertically sorted output.
:p.
DIR's display can be modified in many ways to meet different needs.  Most of
the following sections describes the various ways you can change DIR's output
format.
:p.
:hp2.Switching Formats:ehp2.
:p.
On HPFS volumes, you can force DIR to use a FAT-like format (file name
first, followed by file information) with the :hp2./Z:ehp2. option.  If
necessary, DIR /Z truncates long file names on HPFS drives, and adds a
right arrow [:hp2.:ehp2.] to show that the name contains additional
characters.
:p.
The standard HPFS output format does not provide enough space to show
descriptions along with file names.  Therefore, if you wish to view file
descriptions as part of the DIR listing on an HPFS volume, you
:hp2.must:ehp2. use the :hp2./Z:ehp2. option.
:p.
If you use the :hp2./B:ehp2. option, DIR displays just file names and omits
the file size, time stamp, and description for each file, for example&colon.
:xmp.
        [c&colon.\] dir i* /b
:p.
        IBMCOM
        IBMI18N
        IBMINST
        IBMVESA
        IBMLVL.INI
        .....
:exmp.:p.
There are several ways to modify the display produced by :hp2./B:ehp2..  The
:hp2./F:ehp2. option is similar to :hp2./B:ehp2., but displays the full path
and name of each file, instead of just its name.  To view the same
information for a directory and its subdirectories use :hp2./B:ehp2.
:hp2./S:ehp2. or :hp2./F:ehp2. :hp2./S:ehp2..
:p.
:hp2.Multiple Column Displays:ehp2.
:p.
DIR has three options, :hp2./2:ehp2., :hp2./4:ehp2., and :hp2./W:ehp2., that
create multi-column displays.  On HPFS drives, all 3 of these options force
the use of truncated names.
:p.
The :hp2./2:ehp2. option creates a 2-column display.  On HPFS drives,
only the name of each file is displayed, with directory names placed in
square brackets to distinguish them from file names.  On FAT drives,
support long filenames, or when :hp2./Z:ehp2. or :hp2./X:ehp2. is used (see
below), the display includes the name, file size, and time stamp for each
file.
:p.
The :hp2./4:ehp2. option is similar to :hp2./2:ehp2., but displays directory
information in 4 columns.        On drives which do not support long filenames, or
when :hp2./Z:ehp2. or :hp2./X:ehp2. is used (see below), the display shows
the file name and the file size in kilobytes (KB) or megabytes (MB), with
"<D>" in the size column for directories.
:p.
The :hp2./W:ehp2. option displays directory information in 5 or more
columns, depending on your screen width.  Each entry in a :hp2.DIR /W:ehp2.
display contains either the name of a file or the name of a
directory.  Directory names are placed in square brackets to distinguish
them from file names.
:p.
If you use one of these options on an HPFS drive
and do not select an alternate display format with :hp2./Z:ehp2. or
:hp2./X:ehp2., the actual number of columns will be based on the longest
name to be displayed and your screen width, and may be less than the number
you requested (for example, you might see only three columns even though you
used :hp2./4:ehp2.).  If the longest name is too long to fit in on a single
line the display will be reduced to one column, and each name will be
wrapped, with "extra" blank lines added so that each name takes the same
number of lines.
:p.
:hp2.Color-Coded Directories:ehp2.
:p.
The DIR command can display each file name and the associated file
information in a different color, depending on the file's extension.
:p.
To choose the display colors, you must either use the :link reftype=hd
refid=SET.SET:elink. command to create an environment variable called
:link reftype=hd refid=COLORDIR_Var.COLORDIR:elink., or use the Commands
page of the :link reftype=hd refid=OPTION.OPTION:elink. dialogs or a text
editor to set the :link reftype=hd refid=INI_ColorDir.ColorDir:elink.
directive in your :hp1..INI:ehp1. file.  If you do not use the COLORDIR
variable or the ColorDir directive, DIR will use the default screen colors
for all files.
:p.
If you use both the COLORDIR variable and the ColorDir directive, the
environment variable will override the settings in your :hp1..INI:ehp1.
file.  You may find it useful to use the COLORDIR variable for
experimenting, then to set permanent directory colors with the ColorDir
directive.
:p.
The format for both the COLORDIR environment variable and the ColorDir
directive in the :hp1..INI:ehp1. file is&colon.
:xmp.
        ext ... &colon.ColorName; ...
:exmp.:p.
where "ext" is a file extension (which may include wildcards) or one of the
following file types&colon.
:xmp.
        DIRS        Directories
        RDONLY      Read-only files
        HIDDEN      Hidden files
        SYSTEM      System files
        ARCHIVE     Files modified since the last backup
:exmp.:p.
and "ColorName" is any valid color name (see :link reftype=hd
refid=Colors.Colors and Color Names:elink.).
:p.
Unlike most color specifications, the background portion of the color name
may be omitted for directory colors.  If you don't specify a background
color, DIR will use the current screen background color.
:p.
For example, to display the :hp1..COM:ehp1. and :hp1..EXE:ehp1. files in red
on the current background, the :hp1..C:ehp1. and :hp1..ASM:ehp1. 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)&colon.
:xmp.
        [c&colon.\] set colordir=com exe&colon.red; c asm&colon.bright cyan;
              rdonly&colon.blink green on white
:exmp.:p.
Extended :link reftype=hd refid=Wildcards.wildcards:elink. can be used in
directory color specifications.  For example, to display :hp1..BAK:ehp1.,
:hp1..BAX:ehp1., and :hp1..BAC:ehp1. files in red&colon.
:xmp.
        [c&colon.\] set colordir=BA[KXC]&colon.red
:exmp.:p.
:hp2. Redirected Output:ehp2.
:p.
The output of the DIR command, like that of most other internal commands, can
be redirected to a file, printer, serial port, or other device.  However, you
may need to take certain DIR command options into account when you redirect
DIR's output.
:p.
DIR wraps both long file names and file descriptions at the width of your
display.  Its redirected output will also wrap at the screen width.  Use the
:hp2./R:ehp2. option if you wish to disable wrapping of long descriptions.
:p.
If you redirect a color-coded directory to a file, DIR will remove the color
data as it sends the directory information to a file.  It will usually do the
same if you redirect output to a character device such as a printer or serial
port.  However, it is not always possible for DIR to tell whether or not a
device is a character device.  If you notice that non-colored lines are being
sent to the output device and colored lines are appearing on your screen, you
can use the :hp2./D:ehp2. option to temporarily disable color-coding when
you redirect DIR's output.
:p.
To redirect DIR output to the clipboard, use CLIP&colon. as the output
device name, for example&colon.
:xmp.
        [c&colon.\] dir *.exe > clip&colon.
:exmp.:p.
:hp2.Other Notes:ehp2.
:p.
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.  Thousands and decimal separators in numeric
displays are affected by the country code, and by the :link reftype=hd
refid=INI_ThousandsChar.ThousandsChar:elink. and
:link reftype=hd refid=INI_DecimalChar.DecimalChar:elink. settings selected
on the Options 1 page of the :link reftype=hd refid=OPTION.OPTION:elink.
dialogs or in the :hp1..INI:ehp1. file.
:p.
:hp2.Options:ehp2.
:p.
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.
:lm margin=4.:parml compact tsize=8 break=none.
:pt.:hp2./1:ehp2.&colon.:pd.Single column display -- display the filename,
size, date, and time; also displays the description on drives which do not
support long filenames.  This is the default.  If :hp2./T:ehp2. is used the
attributes are displayed instead of the description.  This option is most
useful if you wish to override a default :hp2./2:ehp2., :hp2./4:ehp2., or
:hp2./W:ehp2. setting stored in an alias.
.br
:pt.:hp2./2:ehp2.&colon.:pd.Two column display -- display just the name (on
HPFS drives), or display the filename, size, date, and time on other
drives.  See :hp2.Multiple Column Displays:ehp2. above for more details.
.br
:pt.:hp2./4:ehp2.&colon.:pd.Four column display -- display just the name (on
HPFS drives); or display the filename and size, in K (kilobytes) or M
(megabytes), with files between 1 and 9.9 megabytes in size displayed in
tenths (:hp1.i.e.:ehp1. "2.4M").  See :hp2.Multiple Column Displays:ehp2.
above for more details.
.br
:pt.:hp2./A:ehp2.&colon.:pd.(Attribute select) Select only those files that have the
specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute set.  The colon
[:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is optional.  The attributes
are&colon.
.br
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.DIR /A ...:ehp2.), 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, :hp2./A&colon.RHS:ehp2. will display only those files
with all three attributes set.
.br
:pt.:hp2./B:ehp2.&colon.:pd.(Bare)  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 :hp2./B:ehp2. with :hp2./S:ehp2., DIR will show
the full path of each file (the same display as :hp2./F:ehp2.) instead of
simply its name and extension.
.br
:pt.:hp2./D:ehp2.&colon.:pd.(Disable 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 (:hp1.e.g.:ehp1., PRN
or LPT1) or serial port (:hp1.e.g.:ehp1., COM1 or COM2).  :hp2./D:ehp2. is not required
when DIR output is redirected to a file.
.br
:pt.:hp2./E:ehp2.&colon.:pd.Display filenames in the traditional upper case;
also see :link reftype=hd refid=SETDOS.SETDOS:elink. /U and the
:link reftype=hd refid=INI_UpperCase.UpperCase:elink. directive in
:hp1.&4OS2INI.:ehp1..
.br
:pt.:hp2./F:ehp2.&colon.:pd.(Full path)  Display each filename with its
drive letter and path in a single column, without other information.  If you
use :hp2./F:ehp2. with :hp2./X:ehp2. on a volume which supports long
filenames, the "short" version of the entire path is displayed.
.br
:pt.:hp2./G:ehp2.&colon.:pd.Display the allocated disk space instead of the
actual size of each file.
.br
:pt.:hp2./H:ehp2.&colon.:pd.(Hide dots)  Suppress the display of the "." and
".." directories.
.br
:pt.:hp2./I:ehp2.&colon.:pd.Display filenames by matching text in their
descriptions.  The text can include wildcards and extended wildcards.  The
search text must be enclosed in quotation marks.  You can select all
filenames that have a description with :hp2./I"[?]*":ehp2., or all
filenames that do not have a description with :hp2./I"[]":ehp2..
:p.
The :hp2./I:ehp2. option may be used to select files even if descriptions are
not displayed (for example, if :hp2./2:ehp2. is used).  However,
:hp2./I:ehp2. will be ignored if :hp2./O&colon.c:ehp2. is used.
.br
:pt.:hp2./J:ehp2.&colon.:pd.(Justify names)  Justify (align) filename
extensions and display them in the traditional format.
.br
:pt.:hp2./K:ehp2.&colon.:pd.Suppress the header (disk and directory name)
display.
.br
:pt.:hp2./L:ehp2.&colon.:pd.(Lower case)  Display file and directory names in lower case;
also see :link reftype=hd refid=SETDOS.SETDOS:elink. /U and the
:link reftype=hd refid=INI_UpperCase.UpperCase:elink. directive in
:hp1.&4OS2INI.:ehp1..
.br
:pt.:hp2./M:ehp2.&colon.:pd.Suppress the footer (file and byte count totals)
display.
.br
:pt.:hp2./N:ehp2.&colon.:pd.Use the HPFS display format, even if the files are
stored on a volume which does not support long names.  See also :hp2./Z:ehp2..
.br
:pt.:hp2./O:ehp2.&colon.:pd.(Order) 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&colon.
.br
:pt.:pd.:hp2.    -:ehp2.  Reverse the sort order for the next option.
:pt.:pd.:hp2.    a:ehp2.  Sort in ASCII order, not numerically, when there are digits in the name.
:pt.:pd.:hp2.    d:ehp2.  Sort by date and time (oldest first); for HPFS drives, also see :hp2./T:ehp2..
:pt.:pd.:hp2.    e:ehp2.  Sort by extension.
:pt.:pd.:hp2.    g:ehp2.  Group subdirectories first, then files.
:pt.:pd.:hp2.    i:ehp2.  Sort by file description (ignored if :hp2./O&colon.c:ehp2. is used).
:pt.:pd.:hp2.    n:ehp2.  Sort by filename (this is the default).
:pt.:pd.:hp2.    r:ehp2.  Reverse the sort order for all options.
:pt.:pd.:hp2.    s:ehp2.  Sort by size.
:pt.:pd.:hp2.    u:ehp2.  Unsorted.
:p.
:pt.:hp2./P:ehp2.&colon.:pd.(Pause)  Wait for a key to be pressed after each screen page
before continuing the display.  Your options at the prompt are explained in detail under
:link reftype=hd refid=Prompts.Page and File Prompts:elink..
.br
:pt.:hp2./R:ehp2.:pd.(disable wRap)  Forces long descriptions to be displayed
on a single line, rather than wrapped onto two or more lines.  Use :hp2./R:ehp2. 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.
.br
:pt.:hp2./S:ehp2.&colon.:pd.(Subdirectories)  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), ranges, and attributes that you specify on the command line.
.br
:pt.:hp2./T:ehp2.:pd.(aTtribute display)  Display the filenames, attributes, and
descriptions.  The descriptions will be wrapped onto the next line, if
necessary, unless you also use the :hp2./R:ehp2. (truncate) option.  If you use
both :hp2./T:ehp2. and :hp2./R:ehp2., descriptions are truncated after 34 characters
on an 80-column display.  The attributes are displayed in the format RHSA, with
the following meanings&colon.
.br
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    D:ehp2.  Directory
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    A:ehp2.  Archive
:p.
On HPFS drives, if you wish to add another option after :hp2./T:ehp2., you
must start the next option with a forward slash.  If you don't, &4OS2. will
interpret the :hp2./T:ehp2. as the time display switch and the
following character as a valid or invalid time selector.  For example&colon.
:xmp.
        [c&colon.\] dir /tz     incorrect, will display error
        [c&colon.\] dir /t/z    correct
:exmp.
:pt.:hp2./T&colon.acw:ehp2.:pd. (Time display)  Specify which of the date and time
fields on an HPFS drive should be displayed and used for sorting&colon.
.br
:pt.:pd.    :hp2.a:ehp2.  Last access date and time.
:pt.:pd.    :hp2.c:ehp2.  Creation date and time.
:pt.:pd.    :hp2.w:ehp2.  Last write date and time (default).
.br
:pt.:hp2./U:ehp2.:pd.(sUmmary information)  Only display the number of
files, the total file size, and the total amount of disk space
used.  Information on individual files is not displayed.
.br
:pt.:hp2./V:ehp2.&colon.:pd.(Vertical sort)  Display the filenames sorted vertically
rather than horizontally (use with the :hp2./2:ehp2., :hp2./4:ehp2. or :hp2./W:ehp2.
options).
.br
:pt.:hp2./W:ehp2.&colon.:pd.(Wide)  Display filenames only, horizontally
across the screen.  On FAT drives, :hp2./W:ehp2. displays as many columns as
it can fit into the command processor window, using 16 characters in each
column.  Otherwise (i.e., when long filenames are displayed) the number of
columns depends on the width of the longest name in the listing.  See
:hp2.Multiple Column Displays:ehp2. above for more details.
.br
:pt.:hp2./Z:ehp2.&colon.:pd.Display an HPFS directory in the traditional FAT
format, with the filename at the left and the description at the
right.   Long names will be truncated to 12 characters unless :hp2./X:ehp2. is
also used; if the name is longer than 12 characters, it will be followed by
a right arrow [:hp2.:ehp2.] to show that one or more characters have been
truncated.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=DIRHISTORY.DIRHISTORY - Display, read, or modify the directory history list
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display, add to, clear, or read the
directory history list.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DIRHISTORY [/A:ehp2. :hp3.directory:ehp3.
:hp2./F /P /R:ehp2. :hp3.filename:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.directory :ehp3.&colon.  The name of a directory to be added to
the directory history.
:pt.:pd.:hp3.filename :ehp3.&colon.  The name of a file containing entries to
be added to the directory history.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A:ehp2.(dd):pd.:hp2./P:ehp2.(ause)
:pt.:hp2./F:ehp2.(ree):pd.:hp2./R:ehp2.(ead)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=HISTORY.HISTORY:elink..
:p.
:hp2.Usage:ehp2.
:p.
Every time you change to a new directory or drive, &4OS2. records the current
directory in an internal directory history list.  See :link reftype=hd
refid=DirHist.Directory History:elink. for information on directory history
window, which allows you to use the list to return to a previous
directory.  Also see :link reftype=hd refid=DirNav.Directory
Navigation:elink..
:p.
The DIRHISTORY command lets you view and manipulate the directory history
list directly.  If no parameters are entered, DIRHISTORY will display the
current directory history list&colon.
:xmp.
        [c&colon.\] dirhistory
:exmp.:p.
With the options explained below, you can clear the list, add new directories
to the list without changing to them, save the list in a file, or read a new
list from a file.
:p.
The number of directories saved in the directory history list depends on the
length of each directory name.  The list size can be specified at startup
from 256 to 32767 characters by using the :link reftype=hd
refid=INI_DirHistory.DirHistory:elink. directive in :hp1.&4OS2INI.:ehp1..
:p.
Your directory 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).  See :link reftype=hd
refid=DirHist.Directory History:elink. for the discussion of local and
global directory history lists.
:p.
You can save the directory history list by redirecting the output of
DIRHISTORY to a file.  This example saves the history to a file called
:hp1.DIRHIST:ehp1. and reads it back again&colon.
:xmp.
        [c&colon.\] dirhistory > dirhist
            .....
        [c&colon.\] dirhistory /r dirhist
:exmp.:p.
Because the directory history stores each name only once, you don't have to
delete its contents before reading back the file unless you want to delete
the directories that were visited by the intervening commands.
:p.
If you need to save your directory history at the end of each day's work, you
might use commands like this in your :hp1.4START.BTM:ehp1. file&colon.
:xmp.
        if exist c&colon.\dirhist dirhistory /r c&colon.\dirhist

        alias shut*down `dirhistory > c&colon.\dirhist`
:exmp.:p.
This restores the previous history list if it exists, then defines an alias
which will allow you to save the history before shutting off the system.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=none.
:pt.:hp2./A:ehp2.&colon.:pd.(Add) Add a directory to the directory history
list.
:pt.:hp2./F:ehp2.&colon.:pd.(Free) Erase all entries in the directory
history list.
:pt.:hp2./P:ehp2.&colon.:pd.(Prompt) Wait for a key after displaying each
page of the list.  Your options at the prompt are explained in :link
reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./R:ehp2.&colon.:pd.(Read) Read the directory history from the
specified file and append it to the list currently held in memory.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=DIRS.DIRS - Display the directory stack
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display the current directory stack.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DIRS:ehp2.
:eparml.:p.
See also&colon.  :link reftype=hd refid=PUSHD.PUSHD:elink., :link
reftype=hd refid=POPD.POPD:elink., and :link reftype=hd
refid=DirNav.Directory Navigation:elink..
:p.
:hp2.Usage:ehp2.
:p.
The PUSHD command adds the current default drive and directory to
the directory stack, a list that &4OS2. maintains 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 (:hp1.i.e.:ehp1., the next POPD will retrieve the first
entry that DIRS displays).
:p.
The directory stack holds 511 characters, enough for 20 to 40
typical drive and directory entries.

.* --------------------------------------------------------------------------

:h2 name=DO.DO - Create loops in batch files
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Create loops in batch files.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DO [:ehp2.:hp3.n:ehp3. :hp2.&splitvbar.
FOREVER]:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.DO :ehp2.:hp3.varname:ehp3.:hp2. = :ehp2.:hp3.start:ehp3.
:hp2.TO :ehp2.:hp3.end:ehp3. :hp2.[BY :ehp2.:hp3.n:ehp3. :hp2.]:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.DO [WHILE &splitvbar. UNTIL] :ehp2.:hp3.condition:ehp3.
:pt.:pd.:hp2.DO:ehp2. :hp3.varname:ehp3. :hp2.IN [@]:ehp2.:hp3.set:ehp3.
:pt.:pd.:hp3.     commands:ehp3.
:pt.:pd.:hp2.[ITERATE]:ehp2.
:pt.:pd.:hp2.[LEAVE]:ehp2.
:pt.:pd.:hp3.     commands:ehp3.
:pt.:pd.:hp2.ENDDO:ehp2.
.br
:pt.:pd.:hp3.varname :ehp3.&colon.  The environment variable that will hold
the loop counter, filename, or line from a file.
:pt.:pd.:hp3.n, start, end :ehp3.&colon.  Integers between 0 and
2,147,483,647 inclusive, or an internal variables or variable functions that
evaluate to such a value.
:pt.:pd.:hp3.condition :ehp3.&colon.  A test to determine if the loop should
be executed.
:pt.:pd.:hp3.set :ehp3.&colon.  A set of values for the variable.
:pt.:pd.:hp3.commands :ehp3.&colon.  One or more commands to execute each
time through the loop.  If you use multiple commands, they must be separated
by command separators or be placed on separate lines.
:eparml.:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link
reftype=hd refid=ranges.ranges:elink.,
and :link reftype=hd refid=InclList.include lists:elink. for the
:hp1.set:ehp1..
:p.
:hp2.Usage:ehp2.
:p.
DO can only be used in batch files.  It cannot be used in aliases.
:p.
DO can be used to create 4 different kinds of loops.  The first,
introduced by :hp2.DO n:ehp2., is a counted loop.  The batch file lines
between DO and ENDDO are repeated :hp1.n:ehp1. times.  For example&colon.
:xmp.
        do 5
           beep
        enddo
:exmp.:p.
You can also specify "forever" for :hp1.n:ehp1. if you wish to create an
endless loop (you can use LEAVE or :link reftype=hd refid=GOTO.GOTO:elink.
to exit such a loop; see below for details).
:p.
The second type of loop is similar to a "for loop" in programming
languages like BASIC.  DO creates an environment variable,
:hp1.varname:ehp1., and sets it equal to the value :hp1.start:ehp1. (if
:hp1.varname:ehp1. already exists in the environment, it will be
overwritten).  DO then begins the loop process by comparing the
value of :hp1.varname:ehp1. with the value of :hp1.end. :ehp1. If :hp1.varname:ehp1. is
less than or equal to :hp1.end:ehp1., DO executes the batch file lines up
to the ENDDO.  Next, DO adds 1 to the value of :hp1.varname:ehp1., or adds
the value :hp1.n:ehp1. if BY :hp1.n:ehp1. is specified, and repeats the compare
and execute process until :hp1.varname:ehp1. is greater than
:hp1.end:ehp1..  This example displays the even numbers from 2 through
20&colon.
:xmp.
        do i = 2 to 20 by 2
           echo %i
        enddo
:exmp.:p.
DO can also count down, rather than up.  If :hp1.n:ehp1. is negative,
:hp1.varname:ehp1. will decrease by :hp1.n:ehp1. with each loop, and the loop
will stop when :hp1.varname:ehp1. is :hp2.less:ehp2. than :hp1.end:ehp1..  For
example, to display the even numbers from 2 through 20 in reverse order,
replace the first line of the example above with&colon.
:xmp.
        do i = 20 to 2 by -2
:exmp.:p.
The third type of loop is called a "while loop" or "until loop."
DO evaluates the :hp1.condition:ehp1., which can be any of the tests
supported by the :link reftype=hd refid=IF.IF:elink. command, and executes the lines between
DO and ENDDO as long as the condition is true.  The loop ends when
the condition becomes false.
:p.
WHILE tests the condition at the start of the loop.  Therefore, if the
condition is false when the loop starts, the statements within the loop will
never be executed, and the batch file will continue with the statement after
the ENDDO.
:p.
UNTIL tests the condition at the end of the loop.  Therefore, if the
condition is false when the loop starts, the statements within the loop will
still be executed at least once.
:p.
The fourth type of loop executes the lines between DO and ENDDO once for
every member of a :hp1.set:ehp1. (this is similar to the set used in the
:link reftype=hd refid=FOR.FOR:elink. command).  Normally, the
:hp1.set:ehp1. is a list of files specified with wildcards.  For
example&colon.
:xmp.
        do x in *.txt
:exmp.:p.
will execute the loop once for every :hp1..TXT:ehp1. file in the current
directory; each time through the loop the variable :hp2.x:ehp2. will be set
to the name of the next file that matches the file specification.
:p.
If, between DO and ENDDO, you create a new file that :hp1.could:ehp1. be
included in the list of files, it may or may not appear in an iteration of
the DO loop.  Whether the new file appears depends on its physical location
in the directory structure, a condition over which &4OS2. has no control.
:p.
You can also execute the loop once for each line of text in a file by placing
an [:hp2.@:ehp2.] in front of the file name.  If you have a file called
:hp1.DRIVES.TXT:ehp1. that contains a list of drives on your computer, one
drive name per line, you can execute the loop once for each drive this
way&colon.
:xmp.
        do x in @drives.txt
:exmp.:p.
To execute the loop once for each line of text in the clipboard, use
:hp2.CLIP&colon.:ehp2. as the file name (:hp1.e.g.:ehp1. DO X IN
@CLIP&colon.).  CLIP&colon. will not return any data unless the clipboard
contains text.  See :link reftype=hd refid=Redirection.Redirection:elink. for
additional information on CLIP&colon..
:p.
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 :link reftype=hd refid=IF.IF:elink. or
:link reftype=hd refid=IFF.IFF:elink. command&colon.
:xmp.
        do while "%var" != "%var1"
           ...
           if "%var" == "%val2" leave
        enddo
:exmp.:p.
You can nest DO loops up to 15 levels deep.
:p.
The DO and ENDDO commands must be on separate lines, and cannot be placed
within a :link reftype=hd refid=Grouping.command group:elink., or on the
same line as other commands (this is the reason DO cannot be used in
aliases).  However, commands within the DO loop can use command groups or
the :link reftype=hd refid=MultCmds.command separator:elink. in the normal
way.
:p.
You can exit from all DO / ENDDO loops by using GOTO to a line
past the last ENDDO.  However, :hp8.be sure to read the cautionary notes:ehp8.
about GOTO and DO under the :link reftype=hd refid=GOTO.GOTO:elink. command
before using a GOTO in any other way inside any DO loop.

.* --------------------------------------------------------------------------

:h2 name=DPATH.DPATH - Set the data search path
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Specify the subdirectories which applications will
search to find files that are not in the current directory.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DPATH [:ehp2.:hp3.directory:ehp3.
:hp2.[;:ehp2.:hp3.directory...:ehp3. :hp2.]]:ehp2.
.br
:pt.:pd.:hp3.directory :ehp3.&colon.  The full name of a directory to
include in the DPATH (data path) setting.
:eparml.:p.
See also&colon.  :link reftype=hd refid=PATH.PATH:elink., :link reftype=hd refid=SET.SET:elink., and :link reftype=hd refid=ESET.ESET:elink..
:p.
:hp2.Usage:ehp2.
:p.
When most OS/2 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 may 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.
:p.
For example, the following DPATH command directs applications to
look for files in this order&colon.  the current directory, the :hp1.INIT:ehp1.
directory on C, and the :hp1.CONFIG:ehp1. directory on D&colon.
:xmp.
        [c&colon.\] dpath c&colon.\init;d&colon.\config
:exmp.:p.
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
:link reftype=hd refid=SET.SET:elink. command and edited with the :link reftype=hd refid=ESET.ESET:elink. command.
:p.
Directory names in the DPATH must be separated with semicolons
[:hp2.;:ehp2.].  &4OS2. will :hp2.not:ehp2. shift directory names in
the DPATH to upper case as it does 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.
:p.
If you enter DPATH with no parameters, &4OS2. displays the current DPATH
search list.

.* --------------------------------------------------------------------------

:h2 name=DRAWBOX.DRAWBOX - Draw a box
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Draw a box on the screen.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DRAWBOX :ehp2.:hp3.ulrow ulcol lrrow
lrcol style:ehp3. :hp2.[BRIght] [BLInk] fg ON [BRIght] bg [FILl [BRIght]
:ehp2.:hp3.bgfill:ehp3. :hp2.] [ZOOm] [SHAdow]:ehp2.
.br
:pt.:pd.:hp3.ulrow :ehp3.&colon.  Row for upper left corner
:pt.:pd.:hp3.ulcol :ehp3.&colon.  Column for upper left corner
:pt.:pd.:hp3.lrrow :ehp3.&colon.  Row for lower right corner
:pt.:pd.:hp3.lrcol :ehp3.&colon.  Column for lower right corner
:pt.:pd.:hp3.style :ehp3.&colon.  Box drawing style&colon.
.* FIX FIX FIX sub-indentation
:pt.:pd.        :hp2.0:ehp2.     No lines (box is drawn with blanks)
:pt.:pd.        :hp2.1:ehp2.     Single line
:pt.:pd.        :hp2.2:ehp2.     Double line
:pt.:pd.        :hp2.3:ehp2.     Single line on top and bottom, double on sides
:pt.:pd.        :hp2.4:ehp2.     Double line on top and bottom, single on sides
:pt.:pd.:hp3.fg :ehp3.&colon.  Foreground character color
:pt.:pd.:hp3.bg :ehp3.&colon.  Background character color
:pt.:pd.:hp3.bgfill :ehp3.&colon.  Background fill color (for the inside of the box)
:eparml.:p.
See also&colon.  :link reftype=hd refid=DRAWHLINE.DRAWHLINE:elink. and :link reftype=hd refid=DRAWVLINE.DRAWVLINE:elink..
:p.
:hp2.Usage:ehp2.
:p.
DRAWBOX is useful for creating attractive screen displays in batch
files.
:p.
For example, to draw a box around the edge of an 80x25 screen with bright
white lines on a blue background&colon.
:xmp.
        drawbox 0 0 24 79 1 bri whi on blu fill blu
:exmp.:p.
See :link reftype=hd refid=Colors.Colors and Color Names:elink. for details about colors and
notes on the use of bright background colors.
:p.
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
computer and video system.
:p.
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).
:p.
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.
:p.
DRAWBOX checks for valid row and column values, and displays a
"Usage" error message if any values are out of range.
:p.
Unlike DRAWHLINE and DRAWVLINE, DRAWBOX does :hp2.not:ehp2. 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.
:p.
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, or a font which does not
include these characters, the box may not appear on your screen as you expect.

.* --------------------------------------------------------------------------

:h2 name=DRAWHLINE.DRAWHLINE - Draw a horizontal line
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Draw a horizontal line on the screen.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DRAWHLINE:ehp2. :hp3.row column len
style:ehp3. :hp2.[BRIght] [BLInk] fg ON [BRIght] bg:ehp2.
.br
:pt.:pd.:hp3.row :ehp3.&colon.  Starting row
:pt.:pd.:hp3.column :ehp3.&colon.  Starting column
:pt.:pd.:hp3.len :ehp3.&colon.  Length of line
:pt.:pd.:hp3.style :ehp3.&colon.  Line drawing style&colon.
.* FIX FIX FIX sub-indentation
:pt.:pd.        :hp2.1:ehp2.     Single line
:pt.:pd.        :hp2.2:ehp2.     Double line
:pt.:pd.:hp3.fg :ehp3.&colon.  Foreground character color
:pt.:pd.:hp3.bg :ehp3.&colon.  Background character color
:eparml.:p.
See also&colon.  :link reftype=hd refid=DRAWBOX.DRAWBOX:elink. and :link reftype=hd refid=DRAWVLINE.DRAWVLINE:elink..
:p.
:hp2.Usage:ehp2.
:p.
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).
:p.
For example, the following command draws a double line along the
top row of the display with green characters on a blue background&colon.
:xmp.
        drawhline 0 0 80 2 green on blue
:exmp.:p.
The :hp1.row:ehp1. and :hp1.column:ehp1. 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 :hp1.row:ehp1. and
:hp1.column:ehp1., and displays a "Usage" error message if either value is
out of range.
:p.
See :link reftype=hd refid=Colors.Colors and Color Names:elink. for details about colors and
notes on the use of bright background colors.
:p.
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, or a font which does not
include these characters, the box may not appear on your screen as you expect.

.* --------------------------------------------------------------------------

:h2 name=DRAWVLINE.DRAWVLINE - Draw a vertical line
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Draw a vertical line on the screen.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.DRAWVLINE :ehp2.:hp3.row column len style:ehp3.
:hp2.[BRIght][BLInk] fg ON [BRIght] bg:ehp2.
.br
:pt.:pd.:hp3.row :ehp3.&colon.  Starting row
:pt.:pd.:hp3.column :ehp3.&colon.  Starting column
:pt.:pd.:hp3.len :ehp3.&colon.  Length of line
:pt.:pd.:hp3.style :ehp3.&colon.  Line drawing style&colon.
.* FIX FIX FIX sub-indentation
:pt.:pd.        :hp2.1:ehp2.     Single line
:pt.:pd.        :hp2.2:ehp2.     Double line
:pt.:pd.:hp3.fg :ehp3.&colon.  Foreground character color
:pt.:pd.:hp3.bg :ehp3.&colon.  Background character color
:eparml.:p.
See also&colon.  :link reftype=hd refid=DRAWBOX.DRAWBOX:elink. and :link reftype=hd refid=DRAWHLINE.DRAWHLINE:elink..
:p.
:hp2.Usage:ehp2.
:p.
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).
:p.
For example, to draw a double width line along the left margin of
the display with bright red characters on a black background&colon.
:xmp.
        drawvline 0 0 25 2 bright red on black
:exmp.:p.
The :hp1.row:ehp1. and :hp1.column:ehp1. 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 :hp1.row:ehp1. and
:hp1.column:ehp1., and displays a "Usage" error message if either value is
out of range.
:p.
See :link reftype=hd refid=Colors.Colors and Color Names:elink. for details about colors and
notes on the use of bright background colors.
:p.
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, or a font which does not
include these characters, the box may not appear on your screen as you expect.

.* --------------------------------------------------------------------------

:h2 name=ECHO.ECHO and ECHOERR - Display a message / set echo state
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display a message, enable or disable batch file or
command-line echoing, or display the echo status.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.ECHO [ON &splitvbar. OFF &splitvbar.
:ehp2.:hp3.message:ehp3. :hp2.]:ehp2.
:pt.:pd.:hp2.ECHOERR:ehp2. :hp3.message:ehp3.
.br
:pt.:pd.:hp3.message :ehp3.&colon.  Text to display.
:eparml.:p.
See also&colon.  :link reftype=hd refid=ECHOS.ECHOS:elink., :link reftype=hd refid=SCREEN.SCREEN:elink., :link reftype=hd refid=SCRPUT.SCRPUT:elink.,
:link reftype=hd refid=SETDOS.SETDOS:elink. and :link reftype=hd refid=TEXT.TEXT:elink..
:p.
:hp2.Usage:ehp2.
:p.
&4OS2. has 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.
:p.
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.
:p.
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 [:hp2.@:ehp2.]
character will not be displayed.  To turn off batch file echoing,
without displaying the ECHO command, use this line&colon.
:xmp.
        @echo off
:exmp.:p.
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&colon.
:xmp.
        echo Processing your print files...
:exmp.:p.
If you want to echo a blank line from within a batch file, enter&colon.
:xmp.
        echo.
:exmp.:p.
You cannot use the command separator character [:hp2.&amp.:ehp2.],
or the redirection symbols [:hp2.&splitvbar. > <:ehp2.]
in an ECHO message, unless you enclose them in quotes (see
:link reftype=hd refid=Quoting.Argument Quoting:elink.) or precede them with
the :link reftype=hd refid=Escape.escape character:elink..
:p.
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 :link reftype=hd refid=SETDOS.SETDOS:elink. /V0
command, the Options 1 page of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs, or the :link reftype=hd
refid=INI_BatchEcho.BatchEcho:elink. directive in the :hp1..INI:ehp1. file.
:p.
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&colon.
:xmp.
        [c&colon.\] echo on
:exmp.:p.
ECHO defaults to OFF at the command line.
:p.
ECHOERR acts like ECHO but sends its output to the standard error device
(usually the screen) instead of the standard output device.  If the standard
output of a batch file is redirected to a file or another device with
:hp2.>:ehp2., ECHOERR will still generate a screen message.  See :link
reftype=hd refid=RedirPipe.Redirection and Piping:elink. for more information
about the standard output and standard error devices and redirection.

.* --------------------------------------------------------------------------

:h2 name=ECHOS.ECHOS and ECHOSERR - Display a message without CR/LF
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display a message without a trailing
carriage return and line feed.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.ECHOS:ehp2. :hp3.message:ehp3.
:pt.:pd.:hp2.ECHOSERR:ehp2. :hp3.message:ehp3.
:eparml.:p.
See also&colon.  :link reftype=hd refid=ECHO.ECHO:elink., :link reftype=hd
refid=SCREEN.SCREEN:elink., :link reftype=hd refid=SCRPUT.SCRPUT:elink.,
:link reftype=hd refid=TEXT.TEXT:elink., and :link reftype=hd
refid=VSCRPUT.VSCRPUT:elink..
:p.
:hp2.Usage:ehp2.
:p.
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 :hp2.Esc
P:ehp2. to the printer on LPT1&colon.
:xmp.
        [c&colon.\] echos :hp2.^:ehp2.eP > lpt1&colon.
:exmp.:p.
You cannot use the command separator character [:hp2.&amp.:ehp2.]
or the redirection symbols [:hp2.&splitvbar. > <:ehp2.]
in an ECHOS message, unless you enclose them in quotes (see
:link reftype=hd refid=Quoting.Argument Quoting:elink.) or precede them with the :link reftype=hd refid=Escape.escape character:elink..
:p.
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).
:p.
ECHOSERR acts like ECHOS but sends its output to the standard error device
(usually the screen) instead of the standard output device.  If the standard
output of a batch file is redirected to a file or another device with
:hp2.>:ehp2., ECHOSERR will still generate a screen message.  See :link
reftype=hd refid=RedirPipe.Redirection and Piping:elink. for more
information about the standard output and standard error devices and
redirection.

.* --------------------------------------------------------------------------

:h2 name=ENDLOCAL.ENDLOCAL - Restore the saved environment
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Restore the saved disk drive, directory,
environment, alias list, and special characters.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.ENDLOCAL:ehp2.
:eparml.:p.
See also&colon.  :link reftype=hd refid=SETLOCAL.SETLOCAL:elink..
:p.
:hp2.Usage:ehp2.
:p.
The SETLOCAL command in a batch file saves the current disk drive,
default directory, all environment variables, the alias
list, and the command separator, escape character, parameter character,
decimal separator, and thousands separator.  ENDLOCAL restores everything
that was saved by the previous SETLOCAL command.
:p.
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, changes the command separator, runs a program, and then
restores the original values&colon.
:xmp.
        setlocal
        unalias *
        cdd d&colon.\test
        setdos /c~
        program ~ echo Done!
        endlocal
:exmp.:p.
SETLOCAL and ENDLOCAL can only be used in batch files, not in
aliases or from the command line.

.* --------------------------------------------------------------------------

:h2 name=ESET.ESET - Edit environment variables and aliases
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Edit environment variables and aliases.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.ESET [/A] :ehp2.:hp3.variable name:ehp3.
:hp2....:ehp2.
.br
:pt.:pd.:hp3.variable name :ehp3.&colon.  The name of an environment variable or alias to edit.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A:ehp2.(lias)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=ALIAS.ALIAS:elink., :link reftype=hd refid=UNALIAS.UNALIAS:elink., :link reftype=hd refid=SET.SET:elink., and
:link reftype=hd refid=UNSET.UNSET:elink..
:p.
:hp2.Usage:ehp2.
:p.
ESET allows you to edit environment variables and aliases using
line editing commands (see :link reftype=hd refid=Editing.Command-Line
Editing:elink.).
:p.
For example, to edit the executable file search path&colon.
:xmp.
        [c&colon.\] eset path
        path=:hp5.c:ehp5.&colon.\;c&colon.\dos;c&colon.\util
:exmp.:p.
To create and then edit an alias&colon.
:xmp.
        [c&colon.\] alias d = dir /d/j/p
        [c&colon.\] eset d
        d=:hp5.d:ehp5.ir /d/j/p
:exmp.: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 :hp2./A:ehp2. option.
:p.
Environment variable and alias names are normally limited to 80
characters.  Their values are normally limited to 1,023 characters.  However,
if you use special techniques to create a longer environment variable, ESET
will edit it provided the variable contains no more than 2,047 characters of
text.
:p.
If you have enabled global aliases (see :link reftype=hd
refid=ALIAS.ALIAS:elink.), any changes made to an alias with ESET will
immediately affect all other copies of &4OS2. which are using the same alias
list.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(Alias) Edit the named alias even if an
environment variable of the same name exists.  If you have an alias and
an environment variable with the same name, you must use this switch to be
able to edit the alias.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=EXCEPT.EXCEPT - Exclude files from a command
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Perform a command on all available files except those
specified.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.EXCEPT (:ehp2.:hp3.file:ehp3. :hp2.)
:ehp2.:hp3.command:ehp3.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  The file or files to exclude from the
command.
:pt.:pd.:hp3.command :ehp3.&colon.  The command to execute, including all
appropriate arguments and switches.
:eparml.:p.
See also&colon.  :link reftype=hd refid=ATTRIB.ATTRIB:elink. and :link
reftype=hd refid=ExclRanges.File Exclusion Ranges:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link
reftype=hd refid=ranges.ranges:elink., :link reftype=hd
refid=MultFiles.multiple file names:elink., and :link reftype=hd
refid=InclList.include lists:elink..  Ranges :hp2.must:ehp2. appear
immediately after the EXCEPT keyword.
:p.
:hp2.Usage:ehp2.
:p.
EXCEPT provides a means of executing a command on a group of files
and/or subdirectories, and excluding a subgroup from the operation.
The :hp1.command:ehp1. can be an internal command or alias, an external
command, or a batch file.
:p.
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 :hp1.MEMO:ehp1., and those whose
extension is :hp1..WKS:ehp1..  The second example copies all the files and
subdirectories on drive C to drive D except those in :hp1.C&colon.\MSC:ehp1. and
:hp1.C&colon.\DOS:ehp1., using the COPY command&colon.
:xmp.
        [c&colon.\] except (memo*.* *.wks) erase *.*
        [c&colon.\] except (c&colon.\msc c&colon.\dos) copy c&colon.\*.* d&colon.\ /s
:exmp.:p.
Date, time, and size ranges can be used immediately after the word
EXCEPT to further qualify which files should be excluded from the
:hp1.command:ehp1..  If the :hp1.command:ehp1. is an internal command that
supports ranges, an independent range can also be used in the
:hp1.command:ehp1. itself.
:p.
When you use EXCEPT on an HPFS drive, you must quote any file
names inside the parentheses which contain whitespace or special characters.
For example, to copy all files except those in the :hp1."Program
Files":ehp1. directory to drive E&colon.\&colon.
:xmp.
        [c&colon.\] except ("Program Files") copy /s *.* e&colon.\
:exmp.:p.
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).
:p.
:hp8.Caution&colon.:ehp8.  EXCEPT will not work with programs or commands that ignore the
hidden attribute or which work explicitly with hidden files,
including :link reftype=hd refid=DEL.DEL:elink. /Z, and the :hp2./H:ehp2. (process hidden files)
switch available in some &4OS2. file processing commands.
:p.
:link reftype=hd refid=ExclRanges.File exclusion ranges:elink. provide a
faster and more flexible method of excluding files from internal commands,
and do not manipulate file attributes, as EXCEPT does.  However, exclusion
ranges can only be used with &4OS2. internal commands; you must use EXCEPT for
external commands.
:p.
:link reftype=hd refid=Ranges.Date, time, and size ranges:elink. can be used
immediately after the word EXCEPT to further qualify which files should be
excluded from the :hp1.command:ehp1..  If the :hp1.command:ehp1. is an
internal command that supports ranges, an independent range can also be used
in the :hp1.command:ehp1. itself.  You can also use a :link reftype=hd
refid=ExclRanges.file exclusion range:elink.
within the EXCEPT command; however, this will select files to be
:hp2.excluded:ehp2. from EXCEPT, and therefore :hp2.included:ehp2. in
execution of the :hp1.command:ehp1..
:p.
You can use :link reftype=hd refid=Grouping.command grouping:elink. to
execute multiple :hp1.commands:ehp1. with a single EXCEPT.  For example, the
following command copies all files in the current directory whose extensions
begin with :hp1..DA:ehp1., except the :hp1..DAT:ehp1. files, to the
:hp1.D&colon.\SAVE:ehp1. directory, then changes the first two characters of
the extension of the copied files to :hp1..SA:ehp1. &colon.
:xmp.
        [c&colon.\data] except (*.dat) (copy *.da* d&colon.\save &amp. ren *.da* *.sa*)
:exmp.:p.
If you use filename completion (see :link reftype=hd refid=FileComp.Filename Completion:elink.)
to enter the filenames inside the
parentheses, type a space after the open parenthesis before
entering a partial filename or pressing :hp2.Tab:ehp2..  Otherwise, the
command-line editor will treat the open parenthesis as the first
character of the filename to be completed.

.* --------------------------------------------------------------------------

:h2 name=EXIT.EXIT - Exit &4OS2.
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Return from &4OS2..
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.EXIT [:ehp2.:hp3.value:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.value :ehp3.&colon.  The numeric exit code to return.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
EXIT terminates the current copy of &4OS2..  Use it to return to an
application when you have "shelled out" to work at the prompt, or
to end an OS/2 command-line session.
:p.
To close the session, or to return to the application that started
&4OS2., type&colon.
:xmp.
        [c&colon.\] exit
:exmp.:p.
If you specify a value, EXIT will return that value to the program
that started &4OS2..  For example&colon.
:xmp.
        [c&colon.\] exit 255
:exmp.:p.
The :hp1.value:ehp1. is a number you can use to inform the program of some
result, such as the success or failure of a batch file.  It can range from
0 - 4,294,967,295.  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 &4OS2. to perform
certain tasks.

.* --------------------------------------------------------------------------

:h2 name=FFIND.FFIND - Search for files
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Search for files by name or contents.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.FFIND [/A[&colon.][[-]rhsda] /B /C
/D[:ehp2.:hp3.list:ehp3. :hp2.] /E /I /K /L /M /O[[&colon.][-]acdeginrsu] /P
/R /S /T"xx" /V /X["xx xx ..."]:ehp2. :hp3.file...:ehp3.
.br
:pt.:pd.:hp3.list :ehp3.&colon.  A list of disk drive letters (without colons).
:pt.:pd.:hp3.file :ehp3.&colon.  The file, directory, or list of files or directories to display.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A:ehp2.(ttribute select):pd.:hp2./M:ehp2. (no footers)
:pt.:hp2./B:ehp2.(are):pd.:hp2./O:ehp2.(rder)
:pt.:hp2./C:ehp2.(ase sensitive):pd.:hp2./P:ehp2.(ause)
:pt.:hp2./D:ehp2.(rive):pd.:hp2./R:ehp2.(everse)
:pt.:hp2./E:ehp2. (upper case display):pd.:hp2./S:ehp2.(ubdirectories)
:pt.:hp2./I:ehp2.(gnore wildcards):pd.:hp2./T"xx":ehp2. (text search string)
:pt.:hp2./K:ehp2. (no headers):pd.:hp2./V:ehp2.(erbose)
:pt.:hp2./L:ehp2.(ine numbers):pd.:hp2./X["xx"]:ehp2. (hex display/search string)
:eparml.:lm margin=1.
.br
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and :link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
FFIND is a flexible search command that looks for files based on their names
and their contents. Depending on the options you choose, FFIND can display
filenames, matching text, or a combination of both in a variety of formats.
:p.
If you want to search for files by name, FFIND works much like the DIR
command.  For example, to generate a list of all the :hp1..BTM:ehp1. files
in the current directory, you could use the command&colon.
:xmp.
        [c&colon.\] ffind *.btm
:exmp.:p.
The output from this command is a list of full pathnames, followed by the
number of files found.
:p.
If you want to limit the output to a list of :hp1.*.BTM:ehp1. files which
contain the string :hp1.color:ehp1., you could use this command instead&colon.
:xmp.
        [c&colon.\] ffind /t"color" *.btm
:exmp.:p.
The output from this command is a list of files that contain the
string :hp1.color:ehp1. along with the first line in each file that contains
that string.  By default, FFIND uses a case-insensitve search, so the command
above will include files that contain :hp1.COLOR:ehp1., :hp1.Color:ehp1.,
:hp1.color:ehp1., or any other combination of upper-case and lower-case
letters.
:p.
If you would rather see the :hp2.last:ehp2. line of each file that contains
the search string, use the :hp2./R:ehp2. option, which forces FFIND to
search from the end of each file to the beginning.  This option will also
speed up searches somewhat if you are looking for text that will normally be
at the end of a file, such as a signature line&colon.
:xmp.
        [c&colon.\] ffind /r /t"Sincerely," *.txt
:exmp.:p.
You can use extended wildcards in the search string to increase the
flexibility of FFIND's search.  For example, the following command will find .TXT
files which contain either the string :hp1.June:ehp1. or :hp1.July:ehp1..  It will also find
:hp1.Juny:ehp1. and :hp1.Jule:ehp1..  The :hp2./C:ehp2. option makes the search case-sensitive&colon.
:xmp.
        [c&colon.\] ffind /c /t"Ju[nl][ey]" *.txt
:exmp.:p.
If you want to search for text that contains wildcard characters
(:hp2.*:ehp2., :hp2.?:ehp2., :hp2.[:ehp2., or :hp2.]:ehp2.), you can use the
:hp2./I:ehp2. option to force FFIND to interpret these as normal
characters instead of wildcards.  The following command, for example, finds
all :hp1..TXT:ehp1. files that contain a question mark&colon.
:xmp.
        [c&colon.\] ffind /i /t"?" *.txt
:exmp.:p.
At times, you may need to search for data that cannot be represented by
ASCII characters.  You can use FFIND's :hp2./X:ehp2. option to represent the
search string in hexadecimal format (this option also changes the output to
show hexadecimal offsets rather than text lines).  With :hp2./X:ehp2., the
search must be represented by pairs of hexadecimal digits separated by
spaces; a search of this type is always case-sensitive (in the example below,
41 63 65 is the hex code for "Ace")&colon.
:xmp.
        [c&colon.\] ffind /x"41 63 65" *.txt
:exmp.:p.
You can use FFIND's other options to further specify the files for which you
are searching and to modify the way in which the output is displayed.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(Attribute select) Select only those files that
have the specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute
set.  The colon [:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is optional.  The
attributes are&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.FFIND /A ...:ehp2.), FFIND will select all
files and subdirectories including hidden and system files.  If
attributes are combined, all the specified attributes must match for a
file to be selected.  For example, /A&colon.RHS will select only those files
with all three attributes set.
:pt.:hp2./B:ehp2.&colon.:pd.(Bare) Display file names only and omit the text that matches
the search.  This option is only useful in combination with :hp2./T:ehp2. or :hp2./X:ehp2.,
which normally force FFIND to display file names and matching text.
:pt.:hp2./C:ehp2.&colon.:pd.(Case sensitive) Perform a case-sensitive search.  This option
is only valid with :hp2./T:ehp2., which defaults to a case-insensitive search.  It
is not needed with a :hp2./X:ehp2. hexadecimal search, which is always case-sensitive.
:pt.:hp2./D:ehp2.&colon.:pd.(Drive)  Search all files on one or more drives.  If you use :hp2./D:ehp2.
without a list of drives, FFIND will search the drives specified in the
list of files.  If no drive letters are listed, FFIND will search all of the
current drive.  You can include a list of drives or a range of drives
to search as part of the :hp2./D:ehp2. option.  For example, to search drives C&colon.,
D&colon., E&colon., and G&colon., you can use either of these commands&colon.
:xmp.
        [c&colon.\] ffind /dcdeg ...
        [c&colon.\] ffind /dc-eg ...
:exmp.:p.
Drive letters listed after :hp2./D:ehp2. will be ignored when processing
:hp1.file:ehp1. names which also include a drive letter.  For example, this
command displays all the :hp1..BTM:ehp1. files on C&colon. and E&colon., but
only the :hp1..BAT:ehp1. files on D&colon.
:xmp.
        [c&colon.\] ffind /s /dce *.btm d&colon.\*.bat
:exmp.:p.
:pt.:hp2./E:ehp2.&colon.:pd.Display filenames in the traditional upper case;
also see :link reftype=hd refid=SETDOS.SETDOS:elink. /U and the
:link reftype=hd refid=INI_UpperCase.UpperCase:elink. directive in
:hp1.&4OS2INI.:ehp1..
:pt.:hp2./I:ehp2.&colon.:pd.(Ignore wildcards) Only meaningful when used in
conjunction with the :hp2./T"text":ehp2. option.  Suppresses the recognition
of wildcard characters in the search text.  This option is useful if you
need to search for characters that would normally be interpreted as
wildcards&colon. :hp2.*:ehp2., :hp2.?:ehp2., :hp2.[:ehp2., and :hp2.]:ehp2..
:pt.:hp2./K:ehp2.&colon.:pd.(No headers) Suppress the display of the header or filename for
each matching text line.
:pt.:hp2./L:ehp2.&colon.:pd.(Line numbers) Include the line number for each text line
displayed.  FFIND numbers lines beginning with 1, unless :link reftype=hd
refid=INI_ListRowStart.ListRowStart:elink. is set to 0 in :hp1.&4OS2INI.:ehp1..  A new line is
counted for every CR or LF character (FFIND determines automatically
which character is used for line breaks in each file), or when line
length reaches 511 characters, whichever comes first.
:pt.:hp2./M:ehp2.&colon.:pd.(No footers) Suppress the footer (the number of files and number
of matches) at the end of FFIND's display.
:pt.:hp2./O:ehp2.&colon.:pd.(Order) 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&colon.
.br
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    -:ehp2.  Reverse the sort order for the next option.
:pt.:pd.:hp2.    a:ehp2.  Sort in ASCII order, not numerically, when there are digits in the name.
:pt.:pd.:hp2.    d:ehp2.  Sort by date and time (oldest first); for HPFS drives, also see :hp2./T:ehp2..
:pt.:pd.:hp2.    e:ehp2.  Sort by extension.
:pt.:pd.:hp2.    g:ehp2.  Group subdirectories first, then files.
:pt.:pd.:hp2.    i:ehp2.  Sort by file description (ignored if :hp2./C:ehp2. or :hp2./O&colon.c:ehp2. is used).
:pt.:pd.:hp2.    n:ehp2.  Sort by filename (this is the default).
:pt.:pd.:hp2.    r:ehp2.  Reverse the sort order for all options.
:pt.:pd.:hp2.    s:ehp2.  Sort by size.
:pt.:pd.:hp2.    u:ehp2.  Unsorted.
:eparml.:p.
:pt.:hp2./P:ehp2.&colon.:pd.(Pause) Wait for a key to be pressed after each screen page
before continuing the display.  Your options at the prompt are explained in
detail under :link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./R:ehp2.&colon.:pd.(Reverse) Only meaningful when used in
conjuction with the :hp2./T"text":ehp2. or :hp2./X :ehp2. options.  Searches
each file from the end backwards to the beginning.  This option is useful if
you want to display the last occurrence of the search string in each file
instead of the first (the default).  It can also speed up searches for
information that is normally at the end of a file, such as a signature.
:pt.:hp2./S:ehp2.&colon.:pd.(Subdirectories) Display matches from the
current directory and all of its subdirectories.
:pt.:hp2./T"xx":ehp2.&colon.:pd.(Text search) Specify the text search string.  :hp2./T:ehp2. must be
followed by a text string in double quotes (:hp1.e.g.:ehp1., :hp2./t"color":ehp2.).  FFIND
will perform a case-insensitive search unless you also use the :hp2./C:ehp2.
option.  For a hexadecimal search and/or hexadecimal display of the
location where the search string is found, see :hp2./X:ehp2..    You can specify a search
string with either /T or /X, but not both.
:pt.:hp2./V:ehp2.&colon.:pd.(Verbose) Show every matching line.  FFIND's default
behavior is to show only the first matching line then and then go on to
the next file.  This option is only valid with :hp2./T:ehp2. or :hp2./X:ehp2..
:pt.:hp2./X:ehp2.&colon.:pd.(Hexadecimal display / search) Specify hexadecimal display
and an optional hexadecimal search string.
:p.
If :hp2./X:ehp2. is followed by one or more pairs of hexadecimal digits in quotes
(:hp1.e.g.:ehp1., :hp1./x"44 63 65":ehp1.), FFIND will search for that exact sequence of
characters or data bytes without regard to the meaning of those bytes
as text.  If those bytes are found, the offset is displayed (in both decimal
and hexadecimal).  A search of this type will always be case-sensitive.
:p.
If :hp2./X:ehp2. is not followed by a hexadecimal search string it must be
used in conjunction with :hp2./T:ehp2., and will change the output format to
display offsets (in both decimal and hexadecimal) rather than actual text
lines when the search string is found.  For example, this command uses
:hp2./T:ehp2. to display the first line in each :hp1..BTM:ehp1. file
containing the word :hp1.hello:ehp1.&colon.
:xmp.
        [c&colon.\] ffind /t"hello" *.btm
        ---- c&colon.\test.btm&colon.
        echo hello

            1 line in 1 file
:exmp.:p.
If you use the same command with :hp2./X:ehp2., the offset is displayed
instead of the text&colon.
:xmp.
        [c&colon.\] ffind /t"hello" /x *.btm
        ---- c&colon.\test.btm&colon.
        Offset&colon. 26 (1Ah)

            1 line in 1 file
:exmp.:p.
You can specify a search string with either :hp2./T:ehp2. or :hp2./X:ehp2.,
but not both.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=FOR.FOR - Repeat a command
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Repeat a command for several values of a variable.
.br
:pt.:hp3.Format&colon.:ehp3.:pd. :hp2.FOR [/A&colon.[[-]rhsda] /D /F
[":ehp2.:hp3.options:ehp3. :hp2."] /H /L /R
[:ehp2.:hp3.path:ehp3. :hp2.]]:ehp2. :hp3.%var:ehp3. :hp2.IN
([@]:ehp2.:hp3.set:ehp3. :hp2.|:ehp2. :hp3.start, step, end:ehp3. :hp2.)
[DO]:ehp2. :hp3.command:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.options :ehp3.&colon.  Parsing options for a "file parsing" :hp2.FOR:ehp2..
:pt.:pd.:hp3.path :ehp3.&colon.  The starting directory for a "recursive" :hp2.FOR:ehp2..
:pt.:pd.:hp3.%var :ehp3.&colon.  The variable to be used in the command ("FOR variable").
:pt.:pd.:hp3.set :ehp3.&colon.  A set of values for the variable.
:pt.:pd.:hp3.start :ehp3.&colon.  The starting increment for a "counted" :hp2.FOR:ehp2..
:pt.:pd.:hp3.step :ehp3.&colon.  The increment value for a "counted" :hp2.FOR:ehp2..
:pt.:pd.:hp3.end :ehp3.&colon.  The limit value for a "counted" :hp2.FOR:ehp2..
:pt.:pd.:hp3.command :ehp3.&colon.  A command or group of commands to be executed for each value of the variable.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2. (Attribute select):pd.:hp2./L:ehp2. (counted loop)
:pt.:hp2./F:ehp2.(ile parsing):pd.:hp2./R:ehp2.(ecursive)
:pt.:hp2./H:ehp2.(ide dots):pd.
:eparml.:lm margin=1.
.br
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link
reftype=hd refid=ranges.ranges:elink., :link reftype=hd
refid=MultFiles.multiple file names:elink., and :link reftype=hd
refid=InclList.include lists:elink..  Ranges :hp2.must:ehp2. appear
immediately after the FOR keyword.
:p.
:hp2.Usage:ehp2.
:p.
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.  The members of the set can be
a list of file names, text strings, a group of numeric values, or text read
from a list of files.
:p.
When the :hp1.set:ehp1. 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 [:hp2./:ehp2.]).
:p.
FOR includes a large number of options, some of which duplicate functions
available in other &4OS2. commands, and/or do not follow conventions you may
find in our other commands.  Most of these extra options are included for
compatibility with Windows NT 4.0's :hp1.CMD.EXE:ehp1..  However, we make
them available in &4OS2., 4DOS, and 4NT so that aliases and batch files which
use them can work under all three products.
:p.
The first three sections below (:hp2.Working with Files:ehp2., :hp2.Working
with Text:ehp2., and :hp2.Retrieving Text from Files:ehp2.) describe the
traditional FOR command and the enhancements to it which are part of
&4OS2..  The sections on :hp2.Parsing Text from Files:ehp2. and :hp2.Counted
FOR Loops:ehp2. describe features added for compatibility of our line of
text mode products with Windows NT 4.0.  The section entitled :hp2.Other
Notes:ehp2. contains information you may need if you use any aspect of the
FOR command extensively.
:p.
:hp2.Working with Files:ehp2.
:p.
Normally, the :hp1.set:ehp1. is a list of files specified with wildcards.  For
example, if you use this line in a batch file&colon.
:xmp.
        for %x in (*.txt) do list %x
:exmp.:p.
then LIST will be executed once for each file in the current
directory with the extension :hp1..TXT:ehp1..  The FOR variable
:hp1.%x:ehp1. 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.  Many of the examples in this
section are constructed in the same way.)
:p.
The :hp1.set:ehp1. can include multiple files or an include list, like
this&colon.
:xmp.
        for %x in (d&colon.\*.txt;*.doc;*.asc) do type %x
:exmp.:p.
FOR supports :link reftype=hd refid=Wildcards.wildcards and extended
wildcards:elink., as well as extended parent directory names
(:hp1.e.g.:ehp1., :hp2....\*.txt:ehp2. to process all of the :hp1..TXT:ehp1.
files that are contained in the directory 2 levels above the current
directory).
:p.
When you use FOR on an HPFS drive, you must quote any file names within the
:hp1.set:ehp1. which contain whitespace or special characters.  The same
restriction applies to names returned in the FOR variable, if you pass them
to &4OS2. internal commands, or other commands which require quoting filenames
with whitespace.  FOR does not quote returned names automatically, even if
you included quotes in the :hp1.set:ehp1..  See :link reftype=hd
refid=FileNames.File Names:elink. for additional details on
file name quoting.
:p.
If the :hp1.set:ehp1. includes filenames, the file list can be further refined
by using :link reftype=hd refid=Ranges.date, time, size:elink. and :link
reftype=hd refid=ExclRanges.file exclusion:elink. ranges.  The range or
ranges must be placed immediately after the word FOR.  Ranges will be
ignored if no wildcards are used inside the parentheses.  For
example, this set is made up of all of the :hp1..TXT:ehp1. files that were
created or updated on October 4, 1997&colon.
:xmp.
        for /[d10-4-97,+0] %x in (*.txt) do ...
:exmp.:p.
If the :hp1.command:ehp1. is an internal command that supports ranges, an
independent range can also be used in the :hp1.command:ehp1. itself.
:p.
You can also refine the list by limiting it with the :hp2./A&colon.:ehp2.
option to select only files that have specific attributes.
:p.
By default, FOR works only with files in the current directory or a specified
directory.  With the :hp2./R:ehp2. option, FOR will also search for files in
subdirectories.  For example, to work with all of the :hp1..TXT:ehp1. files
in the current directory and its subdirectories&colon.
:xmp.
        for /r %x in (*.txt) do ...
:exmp.:p.
If you specify a directory name immediately after :hp2./R:ehp2., FOR will
start in that directory and then search each of its subdirectories.  This
example works with all of the :hp1..BAK:ehp1. files on drive D&colon.
:xmp.
        for /r d&colon.\ %x in (*.bak) do ...
:exmp.:p.
When you use wildcards to specify the :hp1.set:ehp1., FOR scans the
directory and finds each file which matches the wildcard name(s) you
specified.  If, during the processing of the FOR command, you create a file
that could be included in the :hp1.set:ehp1., it may or may not appear in a
future iteration of the same FOR command.  Whether the new file appears
depends on its physical location in the directory structure.  For example,
if you use FOR to execute a command for all :hp1..TXT:ehp1. files, and the
command also creates one or more new :hp1..TXT:ehp1. files, those new files
may or may not be processed during the current FOR command, depending on
where they are placed in the physical structure of the directory.  This is
an operating system constraint over which &4OS2. have no control.  Therefore,
in order to achieve consistent results you should construct FOR commands
which do not create files that could become part of the :hp1.set:ehp1. for
the current command.
:p.
:hp2.Working with Text:ehp2.
:p.
The :hp1.set:ehp1. can also be made up of text instead of file names.  For
example, to create three files named file1, file2, and file3, each
containing a blank line&colon.
:xmp.
        for %suffix in (1 2 3) do echo. > file%suffix
:exmp.:p.
You could also use the names of environment variables as the text.  This
example displays the name and content of several variables from the
environment (see :link reftype=hd refid=Environment.Environment Variables
and Functions:elink. for details on the use of square brackets when
expanding environment variables).  Enter this on one line&colon.
:xmp.
        for %var in (path prompt comspec) do echo %var=%[%var]
:exmp.:p.
:hp2.Retrieving Text from Files:ehp2.
:p.
FOR can extract text from files in two different ways.  The first method
extracts each line from each file in the :hp1.set:ehp1. and places it in the
variable.  To use this method, place an [:hp2.@:ehp2.] at the beginning of
the :hp1.set:ehp1., in front of the file name or names.
:p.
For example, if you have a file called :hp1.DRIVES.TXT:ehp1. that contains a
list of drives on your computer, one drive name per line (with a "&colon."
after each drive letter), you can print the free space on each drive this
way&colon.
:xmp.
        for %d in (@drives.txt) do free %d > prn
:exmp.:p.
Because the [:hp2.@:ehp2.] is also a valid filename character, FOR first
checks to see if the file exists with the [:hp2.@:ehp2.] in its name
(:hp1.i.e.:ehp1., a file named :hp1.@DRIVES.TXT:ehp1. ).  If so, the filename is
treated as a normal argument.  If it doesn't exist, FOR uses the
filename (without the [:hp2.@:ehp2.]:hp2.):ehp2. as the file from which to
retrieve text.
:p.
If you use @CON as the filename, FOR will read from standard input (a
redirected input file) or a pipe; see :link reftype=hd
refid=RedirPipe.Redirection and Piping:elink. for more information).  If you
use @CLIP&colon. as the filename, FOR will read any text available from the
OS/2 clipboard (see :link reftype=hd refid=Redirection.Redirection:elink.
for details).
:p.
:hp2.Parsing Text from Files:ehp2.
:p.
The second method of working with text from files is to have FOR parse each
line of each file for you.  To begin a "file-parsing" FOR, you must use the
:hp2./F:ehp2. option and then include one or more file names in the
:hp1.set:ehp1..  When you use this form of FOR, the variable must be a
single letter, for example, :hp1.%a:ehp1..
:p.
This method of parsing, included for compatibility with Windows NT 4.0's
:hp1.CMD.EXE:ehp1., can be cumbersome and inflexible.  For a more powerful
method, use FOR with :hp2.@filename:ehp2. as the :hp1.set:ehp1. to retrieve
each line from the file, as described in the previous section.  Then use
variable functions like :link reftype=hd refid=_@INSTR.@INSTR:elink., :link
reftype=hd refid=_@LEFT.@LEFT:elink., :link reftype=hd
refid=_@RIGHT.@RIGHT:elink., and :link reftype=hd refid=_@WORD.@WORD:elink.
to parse the line.
:p.
By default, FOR will extract the first word or :hp1.token:ehp1. from each
line and return it in the variable.  For example, to display the first word
on each line in the file :hp1.FLIST.TXT:ehp1.&colon.
:xmp.
        for /f %a in (flist.txt) do echo %a
:exmp.:p.
You can control the way FOR /F parses each line by specifying one or more
parsing options in a quoted string immediately after the :hp2./F:ehp2..  The
available options are&colon.
:lm margin=4.:parml compact tsize=10 break=fit.
:pt.:hp2.skip=n:ehp2.&colon.:pd.FOR /F will skip "n" lines at the beginning of each
file before parsing the remainder of the file.
:pt.:hp2.tokens=n, m, ...:ehp2. &colon.:pd.By default, FOR /F returns just
the first word or "token" from each parsed line in the variable you
named.  You can have it return more than one token in the variable, or
return tokens in several variables, with this option.
:p.
This option is followed by a list of numbers separated by
commas.  The first number tells FOR /F which token to return in the first
variable, the second number tells it which to return in the second variable,
etc.  The variables follow each other alphabetically starting with the
variable you name on the FOR command line.  This example returns the first
word of each line in each text file in :hp1.%d:ehp1., the second in
:hp1.%e:ehp1., and the third in :hp1.%f:ehp1.&colon.
:xmp.
        for /f "tokens=1,2,3" %d in (*.txt) do ...
:exmp.:p.
You can also indicate a range of tokens by separating the numbers with a
hyphen [:hp2.-:ehp2.].  This example returns the first word of each line in
:hp1.%p:ehp1., the second through fifth words in :hp1.%q:ehp1., and the
eighth word in :hp1.%r:ehp1.&colon.
:xmp.
        for /f "tokens=1,2-5,8" %p in (*.txt) do ...
:exmp.:p.
To return the rest of the line in a variable, use a range that ends with a
number higher than the last token in any line, such as 999.  This final
example returns the first word of each line in :hp1.%a:ehp1. and the
remainder of each line (assuming that no line has more than 999 words!) in
:hp1.%b:ehp1.&colon.
:xmp.
        for /f "tokens=1,2-999" %a in (*.txt) do ...
:exmp.:p.
:pt.:hp2.eol=c:ehp2. &colon.:pd.If FOR /F finds the character "c" in the
line, it will assume that the character and any text following it are part
of a comment and ignore the rest of the line.
:pt.:hp2.delims=xxx...:ehp2. &colon.:pd.By default, FOR /F sees spaces and
tabs as word or token delimiters.  This option replaces those delimiters
with all of the characters following the equal sign to the end of the
string.  This option must therefore be the last one used in the quoted
options string.
:eparml.:lm margin=1.
.br
You can also use FOR /F to parse a single string instead of each line of a
file by using the string, in quotes, as the :hp1.set:ehp1..  For example,
this command will assign variable A to the string "this", B to "is", etc.,
then display "this" (enter the command on one line)&colon.
:xmp.
        for /f "tokens=1,2,3,4" %a in ("this is a test") do echo %a
:exmp.:p.
:hp2."Counted" FOR Loop:ehp2.
:p.
The "counted FOR" loop is included only for compatibility with Windows NT
4.0's :hp1.CMD.EXE:ehp1..  In most cases, you will find the :link reftype=hd
refid=DO.DO:elink. command more useful for performing counted loops.
:p.
In a counted FOR command, the :hp1.set:ehp1. is made up of numeric values
instead of text or file names.  To begin a counted FOR command, you must use
the :hp2./L:ehp2. option and then include three values, separated by commas,
in the :hp1.set:ehp1..  These are the :hp1.start:ehp1., :hp1.step:ehp1., and
:hp1.end:ehp1. values.  During the first iteration of the FOR loop, the
variable is set equal to the :hp1.start:ehp1. value.  Before each iteration,
the variable is increased by the :hp1.step:ehp1. value.  The loop ends when
the variable exceeds the :hp1.end:ehp1. value.  This example will print the
numbers from 1 to 10&colon.
:xmp.
        for /l %val in (1,1,10) do echo %val
:exmp.:p.
This example will print the odd numbers from 1 to 10 (1, 3, 5, 7, and
9)&colon.
:xmp.
        for /l %val in (1,2,10) do echo %val
:exmp.:p.
The step value can be negative.  If it is, the loop will end when the
variable is less than the end value.
:p.
:hp2.Other Notes:ehp2.
:p.
You can use either :hp1.%:ehp1. or :hp1.%%:ehp1. 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 :hp1.%:ehp1. if FOR is
used at the command line, but require :hp1.%%:ehp1. if FOR is used in a batch
file).  The variable name can be up to 80 characters long.  The word DO is
optional.
:p.
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
command.  For example, the following command tries to add a&colon. and
b&colon. to the end of the PATH, but will not work as intended&colon.
:xmp.
        [c&colon.\] for %p in (a&colon. b&colon.) do path %path;%p
:exmp.:p.
The "%p" in "%path" will be interpreted as the FOR variable :hp1.%p:ehp1.
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
:link reftype=hd refid=Environment.Environment:elink.).
:p.
The following example uses FOR with variable functions to delete
the :hp1..BAK:ehp1. files for which a corresponding :hp1..TXT:ehp1. file
exists in the current directory&colon.
:xmp.
        [c&colon.\docs] for %file in (*.txt) do del %@name[%file].bak
:exmp.:p.
The above command would not work properly on an HPFS drive, because the
returned FILE variable might contain whitespace.  To correct this problem,
you would need two sets of quotes, one for DEL and one for %@NAME&colon.
:xmp.
        [c&colon.\docs] for %file in (*.txt) do del "%@name["%file"].bak"
:exmp.:p.
You can use :link reftype=hd refid=Grouping.command grouping:elink. to
execute multiple commands for each element in the :hp1.set:ehp1..  For
example, the following command copies each :hp1..WKQ:ehp1. file in the
current directory to the :hp1.D&colon.\WKSAVE:ehp1. directory, then changes
the extension of each file in the current directory to :hp1..SAV:ehp1..  This
should be entered on one line&colon.
:xmp.
        [c&colon.\text] for %file in (*.wkq) do (copy "%file" d&colon.\wksave\ &amp.
                  ren "%file" *.sav)
:exmp.:p.
In a batch file you can use GOSUB to execute a subroutine for every
element in the :hp1.set:ehp1..  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
:hp1.set:ehp1. without CALLing another batch file.
:p.
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&colon.
:xmp.
        [c&colon.\] for %cmd in (filetest fileform fileprnt) do %cmd datafile
:exmp.:p.
This line will expand to three separate commands&colon.
:xmp.
        filetest datafile
        fileform datafile
        fileprnt datafile
:exmp.:p.
The variable that FOR uses (the :hp2.%CMD:ehp2. in the example above) is
created in the environment and then erased when the FOR command is
done.  (For compatibility with :hp1.CMD.EXE:ehp1., a single-character FOR
variable is created in a special way that does not overwrite an existing
environment variable with the same name.)  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
:xmp.
        [c&colon.\] for %path in ...
:exmp.:p.
will write over your current path setting, then erase the path
variable completely when FOR is done.
:p.
FOR statements can be nested.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2./A&colon.:ehp2.&colon.:pd.(Attribute select) Select only those
files that have the specified attribute(s) set.  :hp2./A&colon.:ehp2. 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 select files that do not have
that attribute set.  The colon [&colon.] after :hp2./A:ehp2. is required.  The
attributes are&colon.
.br
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
.br
:pt.:pd.If no attributes are listed (:hp1.e.g.:ehp1., :hp2.FOR /A&colon. ...:ehp2.),
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, :hp2./A&colon.RHS:ehp2. will include only
those files with all three attributes set.
:p.
For example, to process only those files with the
archive attribute set&colon.
:xmp.
        for /a&colon.a %f in (*.*) echo %f needs a backup!
:exmp.
:pt.:hp2./F:ehp2.&colon.:pd.(File parsing) Return one or more words or
tokens from each line of each file in the set.  The :hp2./F:ehp2. option can
be followed by one or more options in a quoted string which control how the
parsing is performed.  See the details under :hp2.Parsing Text From
Files:ehp2., above.
:pt.:hp2./H:ehp2.&colon.:pd.(Hide dots) Suppress the assignment of the "."
and ".." directories to the FOR variable.
:pt.:hp2./L:ehp2.&colon.:pd.(counted loop) Interpret the three values in the
:hp1.set:ehp1. as the :hp1.start:ehp1., :hp1.step:ehp1., and :hp1.end:ehp1.
values of a counted loop.  See the details under :hp2."Counted" FOR
Loop:ehp2., above.
:pt.:hp2./R:ehp2.&colon.:pd.(Recursive) Look in the current directory and
all of its subdirectories for files in the :hp1.set:ehp1..  If the
:hp2./R:ehp2. is followed by a directory name, look for files in that
directory and all of its subdirectories.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=FREE.FREE - Display total and free disk space
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display the total disk space, total bytes used, and
total bytes free on the specified (or default) drive(s).
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.FREE [:ehp2.:hp3.drive&colon.:ehp3.
:hp2....]:ehp2.
.br
:pt.:pd.:hp3.drive :ehp3.&colon.  One or more drives to include in the report.
:eparml.:p.
See also&colon.  :link reftype=hd refid=MEMORY.MEMORY:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
A colon [:hp2.&colon.:ehp2.] is required after each drive letter.  This
example displays the status of drives A and C&colon.
:xmp.
        [c&colon.\] free a&colon. c&colon.

         Volume in drive A&colon. is unlabeled    Serial number is 213A&colon.15D5
            1,213,952 bytes total disk space
            1,115,136 bytes used
               98,816 bytes free

         Volume in drive C&colon. is DEVELOPMENT  Serial number is 2944&colon.15D9
          242,496,000 bytes total disk space
          236,851,712 bytes used
            5,644,288 bytes free
:exmp.:p.

.* --------------------------------------------------------------------------

:h2 name=GLOBAL.GLOBAL - Execute a command all subdirectories
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Execute a command in the current directory and its
subdirectories.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.GLOBAL [/H /I /P /Q] :ehp2.:hp3.command:ehp3.
.br
:pt.:pd.:hp3.command :ehp3.&colon.  The command to execute, including arguments and switches.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./H:ehp2.(idden directories):pd.:hp2./P:ehp2.(rompt)
:pt.:hp2./I:ehp2.(gnore exit codes):pd.:hp2./Q:ehp2.(uiet)
:eparml.:lm margin=1.
.br
:hp2.Usage:ehp2.
:p.
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.
:p.
This example copies the files in every directory on drive A to the
directory :hp1.C&colon.\TEMP:ehp1. &colon.
:xmp.
        [a&colon.\] global copy *.* c&colon.\temp
:exmp.:p.
If you use the :hp2./P:ehp2. 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.
:p.
You can use :link reftype=hd refid=Grouping.command grouping:elink. to execute multiple
:hp1.commands:ehp1. in each subdirectory.  For example, the following
command copies each :hp1..TXT:ehp1. 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 :hp1..SAV:ehp1. &colon.
:xmp.
        [c&colon.\] global (copy *.txt a&colon. &amp. ren *.txt *.sav)
:exmp.:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./H:ehp2.&colon.:pd.(Hidden directories) Forces GLOBAL to look for hidden
directories.  If you don't use this switch, hidden
directories are ignored.
:pt.:hp2./I:ehp2.&colon.:pd.(Ignore exit codes) If this option is not
specified, GLOBAL will terminate if the command returns a non-zero exit
code.  Use :hp2./I:ehp2. if you want the command to continue in additional
subdirectories even if it returns an error in one subdirectory.  Even
if you use :hp2./I:ehp2., GLOBAL will hnormally alt execution if the command
processor receives a :hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2..
:pt.:hp2./P:ehp2.&colon.:pd.(Prompt) Forces GLOBAL to prompt with each directory name
before it performs the command.  Your options at the
prompt are explained in detail under :link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) Do not display the directory names as each directory
is processed.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=GOSUB.GOSUB - Execute a subroutine in a batch file
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Execute a subroutine in the current batch file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.GOSUB :ehp2.:hp3.label:ehp3.
.br
:pt.:pd.:hp3.label :ehp3.&colon.  The batch file label at the beginning of the subroutine.
:eparml.:p.
See also&colon.  :link reftype=hd refid=CALL.CALL:elink., :link reftype=hd refid=GOTO.GOTO:elink. and :link reftype=hd refid=RETURN.RETURN:elink..
:p.
:hp2.Usage:ehp2.
:p.
GOSUB can only be used in batch files.
:p.
&4OS2. allows subroutines in batch files.  A subroutine must start
with a :hp1.label:ehp1. (a colon [:hp2.&colon.:ehp2.] followed by a one-word label
name) which appears on a line by itself.  Case differences are
ignored when matching labels.  Labels may be one or more words long.  The
subroutine must end with a RETURN statement.
:p.
The subroutine is invoked with a GOSUB command from another part of
the batch file.  After the :link reftype=hd refid=RETURN.RETURN:elink.,
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&colon.
:xmp.
        echo Calling a subroutine
        gosub subr1
        echo Returned from the subroutine
        quit
        &colon.subr1
        dir /a/w
        return
:exmp.:p.
&4OS2. begins its search for the :hp1.label:ehp1. on the next line of the
batch file (after the GOSUB command).  If the label is not found between the
current position and the end of the file, GOSUB will restart the search at
the beginning of the file.  If the label does not exist, the
batch file is terminated with the error message "Label not found."
:p.
GOSUB saves the :link reftype=hd refid=IFF.IFF:elink. and :link reftype=hd
refid=DO.DO:elink. states, so IFF and DO statements inside a subroutine
won't interfere with statements in the part of the batch file from which the
subroutine was called.
:p.
Subroutines can be nested.

.* --------------------------------------------------------------------------

:h2 name=GOTO.GOTO - Branch within a batch file
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Branch to a specified line inside the current batch
file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.GOTO [/I] :ehp2.:hp3.label:ehp3.
.br
:pt.:pd.:hp3.label :ehp3.&colon.  The batch file label to branch to.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./I:ehp2.(FF and DO continue):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=GOSUB.GOSUB:elink..
:p.
:hp2.Usage:ehp2.
:p.
GOTO can only be used in batch files.
:p.
After a GOTO command in a batch file, the next line to be executed
will be the one immediately after the :hp1.label:ehp1..  The :hp1.label:ehp1.
must begin with a colon [:hp2.&colon.:ehp2.] 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.  Labels may be one or more words long.
:p.
This batch file fragment checks for the existence of the file
:hp1.CONFIG.SYS:ehp1..  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&colon..  Otherwise, it prints an error message and
exits.
:xmp.
        if exist config.sys goto C_EXISTS
        echo CONFIG.SYS doesn't exist - exiting.
        quit
        &colon.C_EXISTS
        copy *.* a&colon.\
:exmp.:p.
:p.
GOTO begins its search for the :hp1.label:ehp1. on the next line of the
batch file (after the GOTO command).  If the label is not found between the
current position and the end of the file, GOTO will restart the search at
the beginning of the file.  If the label does not exist, the batch file
is terminated with the error message "Label not found."
:p.
To avoid errors in the processing of nested statements and
loops, GOTO cancels all active :link reftype=hd refid=IFF.IFF:elink. statements and
:link reftype=hd refid=DO.DO:elink. / ENDDO loops unless you use :hp2./I:ehp2..  This means that a
normal GOTO (without :hp2./I:ehp2.) may not branch to any label that is
between an IFF and the corresponding ENDIFF or between a DO and the
corresponding ENDDO.
:p.
For compatibility with Windows NT's :hp1.CMD.EXE:ehp1., the command
:xmp.
        GOTO &colon.EOF
:exmp.:p.
will end processing of the current batch file if the label &colon.EOF does
not exist.  However, this is less efficient than using the :link reftype=hd
refid=QUIT.QUIT:elink. or :link reftype=hd refid=CANCEL.CANCEL:elink.
command to end a batch file.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./I:ehp2.&colon.:pd.(IFF 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 :hp2.and:ehp2. any active DO / ENDDO block.  Using :hp2./I:ehp2.
under any other conditions will cause an error later in your batch file.
:p.
You cannot branch into another IFF statement, another DO loop, or a
different IFF or DO nesting level, whether you use the :hp2./I:ehp2. 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.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=HELP.HELP - Display help
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display help for internal commands.  Help for
external commands is also available in some cases.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.HELP [:ehp2.:hp3.topic:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.topic :ehp3.&colon.  A help topic, internal command, or
external command.
:eparml.
.br
See also&colon.  :link reftype=hd refid=HelpSys.The &4OS2. Help System:elink..
:p.
:hp2.Usage:ehp2.
:p.
Online help is available for &4OS2..  The &4OS2. help system uses the OS/2 help
facility.
:p.
See the :hp1.Introduction and Installation Guide:ehp1. for a more thorough
explanation of the online help available.
:p.
If you type the command HELP by itself (or press :hp2.F1:ehp2. 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&colon.
:xmp.
        help copy
:exmp.:p.
displays information about the COPY command and its options.
:p.
You can configure the HELP command to display OS/2's command-line help
along with the &4OS2.'s (the default), display only the &4OS2. help, or display
some other combination of help "books".  For details, see the :link
reftype=hd refid=INI_HelpBook.HelpBook:elink. directive and your
:hp1.Introduction and Installation Guide:ehp1..
:p.
For help on system errors enter the message number in the HELP
command, for example:
:xmp.
        help 3
        help sys0003
:exmp.:p.
&4OS2. will invoke OS/2's HELPMSG program to process these requests, and
HELPMSG will display any available information on the message number
given.

.* --------------------------------------------------------------------------

:h2 name=HISTORY.HISTORY - Manage the history list
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display, add to, clear, or read the history
list.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.HISTORY [/A :ehp2.:hp3.command:ehp3.
:hp2./F /P /R :ehp2.:hp3.filename:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.command :ehp3.&colon.  A command to be added to the history list.
:pt.:pd.:hp3.filename :ehp3.&colon.  The name of a file containing entries to
be added to the history list.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A:ehp2.(dd):pd.:hp2./P(:ehp2.ause)
:pt.:hp2./F:ehp2.(ree):pd.:hp2./R:ehp2.(ead)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=DIRHISTORY.DIRHISTORY:elink. and
:link reftype=hd refid=LOG.LOG:elink..
:p.
:hp2.Usage:ehp2.
:p.
&4OS2. keeps a list of the commands you have entered on the command
line.  See :link reftype=hd refid=CmdHist.Command History and Recall:elink.
for information on command recall, which allows you to use the history list
to repeat or edit commands you have previously executed.
:p.
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&colon.
:xmp.
        [c&colon.\] history
:exmp.:p.
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.
:p.
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 256 to 32767 characters (see the
:link reftype=hd refid=INI_History.History:elink. directive).  The default size is 1024
characters.
:p.
Your history list can be stored either locally (a separate history
list for each copy of &4OS2.) or globally (all copies of &4OS2. share
the same list).  For full details see the discussion of local and
global history lists under :link reftype=hd refid=CmdHist.Command History and Recall:elink..
:p.
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 may be easier to use the LOG /H command for
this purpose.
:p.
You can disable the history list or specify a minimum command-line
length to save with on the Command Line 1 page of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs, or with the :link reftype=hd
refid=INI_HistMin.HistMin:elink. directive in the :hp1..INI:ehp1. file.
:p.
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
:hp1.HISTFILE:ehp1. 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&colon.
:xmp.
        [c&colon.\] history > histfile
        [c&colon.\] history /f
        [c&colon.\] history /r histfile
:exmp.:p.
If you need to save your history at the end of each day's work, you might use
commands like this in your :hp1.AUTOEXEC.BAT:ehp1. or other startup
file&colon.
:xmp.
        if exist c&colon.\histfile history /r c&colon.\histfile
        alias shut*down `history > c&colon.\histfile`
:exmp.:p.
This restores the previous history list if it exists, then defines an alias
which will allow you to save the history before shutting off the system.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(Add) Add a command to the history list.  This
performs the same function as the :hp2.Ctrl-K:ehp2. key at the
command line (see :link reftype=hd refid=CmdHist.Command History and
Recall:elink.).
:pt.:hp2./F:ehp2.&colon.:pd.(Free) Erase all entries in the command history
list.
:pt.:hp2./P:ehp2.&colon.:pd.(Prompt) Wait for a key after displaying each
page of the list.  Your options at the prompt are explained in
detail under :link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./R:ehp2.&colon.:pd.(Read) 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
:link reftype=hd refid=CmdLength.command-line length limit:elink.).
:p.
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 :link reftype=hd refid=Escape.escape
character:elink..  However, you cannot use this method to exceed the
command-line length limit.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=IF.IF - Execute a command if a condition is true
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Execute a command if a condition or set of
conditions is true.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.IF [NOT]
:ehp2.:hp3.condition:ehp3. :hp2.[.AND. &splitvbar. .OR. &splitvbar. .XOR.
[NOT] :ehp2.:hp3.condition:ehp3. :hp2....]:ehp2. :hp3.command:ehp3.
.br
:pt.:pd.:hp3.condition :ehp3.&colon.  A test or set of tests to determine if
the command should be executed.
:pt.:pd.:hp3.command :ehp3.&colon.  The command to execute if the condition
is true.
:eparml.:p.
See also&colon.  :link reftype=hd refid=IFF.IFF:elink., :link reftype=hd
refid=_@IF.@IF:elink..
:p.
:hp2.Usage:ehp2.
:p.
IF is normally used only in aliases and batch files.  It is always
followed by one or more :hp1.conditions:ehp1. and then a
:hp1.command:ehp1..  First, the :hp1.conditions:ehp1. are evaluated.  If
they are true, the :hp1.command:ehp1. is executed.  Otherwise, the
:hp1.command:ehp1. is ignored.  If you add a NOT before a
:hp1.condition:ehp1., the :hp1.command:ehp1. is executed only when the
:hp1.condition:ehp1. is false.
:p.
You can link :hp1.conditions:ehp1. with :hp2..AND.:ehp2., :hp2..OR.:ehp2.,
or :hp2..XOR.:ehp2., and you can group conditions with parentheses (see
:hp2.Combining Tests:ehp2. below).  You can also nest IF statements.
:p.
The :hp1.conditions:ehp1. can test strings, numbers, the existence of a file
or subdirectory, the exit code returned by the preceding external command, and
the existence of aliases and internal commands.
:p.
The :hp1.command:ehp1. can be an alias, an internal command, an external
command, or a batch file.  The entire IF statement, including all
:hp1.conditions:ehp1. and the :hp1.command:ehp1., must fit on one line.
:p.
Some examples of IF conditions and commands are included below; additional
examples can be found in the :hp1.EXAMPLES.BTM:ehp1. file which came with
&4OS2..
:p.
You can use :link reftype=hd refid=Grouping.command grouping:elink. to
execute multiple :hp1.commands:ehp1. if the :hp1.condition:ehp1. is
true.  For example, the following command tests if any :hp1..TXT:ehp1. files
exist.  If they do, they are copied to drive A&colon. and their extensions
are changed to :hp1..TXO:ehp1. &colon.
:xmp.
        if exist *.txt (copy *.txt a&colon. &amp. ren *.txt *.txo)
:exmp.:p.
(Note that the IFF command provides a more structured method of executing
multiple commands if a condition or set of conditions is true.)
:p.
When an IF test fails, the remainder of the command is
discarded, and the command processor normally continues with the next
command on the line, or the next line.  This behavior is not compatible with
:hp1.CMD.EXE:ehp1., which discards all remaining commands on the line when
an IF test fails, including those after a command separator or pipe
character.  To change the behavior so that IF affects all commands on the
line, as in :hp1.CMD.EXE:ehp1., set :link reftype=hd
refid=INI_DuplicateBugs.DuplicateBugs:elink. to Yes in
:link reftype=hd refid=INIModify.&4OS2INI.:elink..
:p.
For example, if DuplicateBugs is set to Yes (the default), the following
command will display nothing, because the second :link reftype=hd
refid=ECHO.ECHO:elink. command is discarded along with the first when the
:hp3.condition:ehp3. fails.  If DuplicateBugs is set to No, it will display
"hello"&colon.
:xmp.
        [c&colon.\] if 1 == 2 echo Wrong! &amp. echo hello
:exmp.:p.
:hp2.Conditions:ehp2.
:p.
The conditional tests listed in the following sections are available in both
the IF and IFF commands.  They fit into two categories&colon.  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.
:p.
:hp2.String and Numeric Tests:ehp2.
:p.
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&colon.
:xmp.
        :hp1.string1:ehp1. operator :hp1.string2:ehp1.
:exmp.:p.
The :hp2.operator:ehp2. defines the type of test (equal, greater than or
equal, and so on).  You should always use spaces on both sides of the
:hp2.operator:ehp2.  The operators are&colon.
:lm margin=8.:parml compact tsize=12 break=fit.
:pt.:hp2.EQ:ehp2. or :hp2.==:ehp2.:pd.:hp1.string1:ehp1. equal to :hp1.string2:ehp1.
:pt.:hp2.NE:ehp2. or !:hp2.=:ehp2.:pd.:hp1.string1:ehp1. not equal to :hp1.string2:ehp1.
:pt.:hp2.LT:ehp2.:pd.:hp1.string1:ehp1. less than :hp1.string2:ehp1.
:pt.:hp2.LE:ehp2.:pd.:hp1.string1:ehp1. less than or equal to :hp1.string2:ehp1.
:pt.:hp2.GE:ehp2.:pd.:hp1.string1:ehp1. greater than or equal to :hp1.string2:ehp1.
:pt.:hp2.GT:ehp2.:pd.:hp1.string1:ehp1. greater than :hp1.string2:ehp1.
:eparml.:lm margin=1.
.br
When IF compares two character strings, it will use either a
:hp2.numeric:ehp2. comparison or a :hp2.string:ehp2. comparison.  A numeric
comparison treats the strings as numeric values and tests them
arithmetically.  A string comparison treats the strings as text.
:p.
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 first digit of 19.  So the first of these
:hp1.conditions:ehp1. will be true, and the second will be false&colon.
:xmp.
        if 2 lt 19 ...
        if "2" lt "19" ...
:exmp.:p.
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 separator), a numeric comparison
is used.  (If a string begins with a decimal separator it is not considered
numeric unless the next character is a digit, and there are no more decimal
separators within the string.  For example, ".07" is numeric, but ".a"
and ".07.01" are not.)  If either value is non-numeric, 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, IF performs a
string comparison.
:p.
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".
:p.
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.
:p.
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 (:hp2.+:ehp2. or :hp2.-:ehp2.).
The number may contain up to 16 digits to the left of the decimal point, and
8 digits to the right.
:p.
:link reftype=hd refid=IntVars.Internal variables:elink. and :link
reftype=hd refid=VarFuncs.variable functions:elink. 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.
:p.
This batch file fragment runs a program called :hp1.MONOPROG:ehp1. if a
monochrome monitor is attached to the system&colon.
:xmp.
        if "%_monitor" == "mono" monoprog
:exmp.:p.
This batch file fragment tests for a string value&colon.
:xmp.
        input "Enter your selection &colon. " %%cmd
        if "%cmd" == "WP" goto wordproc
        if "%cmd" NE "GRAPHICS" goto badentry
:exmp.:p.
This example calls :hp1.GO.BTM:ehp1. if the first two characters in the
file :hp1.MYFILE:ehp1. are "GO"&colon.
:xmp.
        if "%@left[2,%@line[myfile,0]]" == "GO" call go.btm
:exmp.:p.
:hp2.Status Tests:ehp2.
:p.
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.
:lm margin=4.:parml tsize=4 break=all.
:pt.:hp2.DEFINED variable:ehp2.:pd.If the variable exists in the
environment, the condition is true.  This is equivalent to testing whether
the variable is not empty, for example the following two commands are
equivalent&colon.
:xmp.
        if defined abc echo Hello
        if "%abc" != "" echo Hello
:exmp.
:pt.:hp2.ERRORLEVEL [operator] n:ehp2.:pd.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 (depending on the program you are running, the
maximum return value may be larger).  The condition can be any
of the operators listed above (:hp2.EQ:ehp2., :hp2.!=:ehp2., :hp2.GT:ehp2.,
etc.).  If no operator is specified, the default is :hp2.GE:ehp2..  The
comparison is done numerically.
:p.
Not all programs return an explicit exit code.  For programs which do not,
the behavior of ERRORLEVEL is undefined.
:pt.:hp2.EXIST filename:ehp2.:pd.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.
:p.
Do not use IF EXIST to test for existence of a directory
(use IF ISDIR instead).  Due to variations in operating system internals, IF
EXIST will not return consistent results when used to test for the existence
of a directory.
:pt.:hp2.ISALIAS aliasname:ehp2.:pd.If the name is defined as an alias, the
condition is true.
:pt.:hp2.ISDIR &splitvbar. DIREXIST path:ehp2.:pd.If the subdirectory exists,
the condition is true.
:pt.:hp2.ISINTERNAL command:ehp2.:pd.If the specified command is an active
internal command, the condition is true.  Commands can be activated and
deactivated with the :link reftype=hd refid=SETDOS.SETDOS:elink. /I command.
:pt.:hp2.ISLABEL label:ehp2.:pd.If the specified label exists in the current
batch file, the condition is true.  Labels may be one or more words long.
:eparml.:lm margin=1.
.br
This batch file fragment tests for the existence of
:hp1.A&colon.\JAN.DOC:ehp1. before copying it to drive C (this avoids an
error message if the file does not exist)&colon.
:xmp.
        if exist a&colon.\jan.doc copy a&colon.\jan.doc c&colon.\
:exmp.:p.
This example tests the exit code of the previous program and stops
all batch file processing if an error occurred&colon.
:xmp.
        if errorlevel == 0 goto success
        echo "External Error -- Batch File Ends!"
        cancel
:exmp.:p.
:hp2.Combining Tests:ehp2.
:p.
You can negate the result of any test with :hp2.NOT:ehp2., and combine
tests of any type with :hp2..AND.:ehp2., :hp2..OR.:ehp2., and
:hp2..XOR.:ehp2.
:p.
When two tests are combined with :hp2..AND.:ehp2., the result is true if
both individual tests are true.  When two tests are combined with
:hp2..OR.:ehp2., the result is true if either (or both) individual tests
are true.  When two tests are combined with :hp2..XOR.:ehp2., the result
is true only if one of the tests is true and the other is false.
:p.
This example runs a program called :hp1.HIGHRES:ehp1. if either an EGA or
VGA video adapter is in use.  Enter this on one line&colon.
:xmp.
        if "%_video" == "EGA" .or. "%_video" == "vga" highres
:exmp.:p.
Test conditions are always scanned from left to right  there is no implied
order of precedence, as there is in some programming languages.  You can,
however, force a specific order of testing by grouping conditions with
parentheses, for example (enter this on one line)&colon.
:xmp.
        if (%a == 1 .or. (%b == 2 .and. %c == 3)) echo something
:exmp.:p.
Parentheses can only be used when the portion of the condition inside the
parentheses contains at least one ".and.", ".or.", or ".xor.".  Parentheses
on a simple condition which does not combine two or more tests will be taken
as part of the string to be tested, and will probably make the test
fail.  For example, the first of these IF tests would fail; the second would
succeed:
:xmp.
        if (a == a) ...
        if (a == a .and. b == b) ...
:exmp.:p.

.* --------------------------------------------------------------------------

:h2 name=IFF.IFF - IF / THEN / ELSE conditional command execution
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Perform IF / THEN / ELSE conditional
execution of commands.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.IFF [NOT] :ehp2.:hp3.condition:ehp3.
:hp2.[.AND. &splitvbar. .OR. &splitvbar. .XOR. [NOT]:ehp2.
:hp3.condition:ehp3. :hp2. ...] THEN &amp. :ehp2.:hp3.commands:ehp3.
:pt.:pd.:hp2.[ELSEIFF :ehp2.:hp3.condition:ehp3. :hp2. THEN &amp.:ehp2.
:hp3.commands:ehp3. :hp2.] ...:ehp2.
:pt.:pd.:hp2.[ELSE &amp. :ehp2.:hp3.commands:ehp3. :hp2.]:ehp2.
:pt.:pd.:hp2.&amp. ENDIFF:ehp2.
.br
:pt.:pd.:hp3.condition :ehp3.&colon.  A test to determine if the command(s) should be executed.
:pt.:pd.:hp3.commands :ehp3.&colon.  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.
:eparml.:p.
See also&colon.  :link reftype=hd refid=IF.IF:elink. and
:link reftype=hd refid=_@IF.@IF:elink..
:p.
:hp2.Usage:ehp2.
:p.
IFF is similar to the IF command, except that it can perform one
set of :hp1.commands:ehp1. when a condition or set of :hp1.conditions:ehp1. is
true and different :hp1.commands:ehp1. when the :hp1.conditions:ehp1. are
false.
:p.
IFF can also execute multiple commands when the :hp1.conditions:ehp1. 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.
:p.
IFF is always followed by one or more :hp1.conditions:ehp1..  If they are
true, the :hp1.commands:ehp1. that follow the word THEN are
executed.  Additional :hp1.conditions:ehp1. can be tested with ELSEIFF.  If
none of these :hp1.conditions:ehp1. are true, the :hp1.commands:ehp1. that
follow the word ELSE are executed.  After the selected :hp1.commands:ehp1.
(if any) are executed, processing continues after the word ENDIFF.
:p.
If you add a NOT before the condition, the THEN :hp1.commands:ehp1. are
executed only when the :hp1.condition:ehp1. is false and the ELSE
:hp1.commands:ehp1. are executed only when the :hp1.condition:ehp1. is true.
:p.
The :hp1.commands:ehp1. 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 an ELSE.
:p.
You can link :hp1.conditions:ehp1. with :hp2..AND.:ehp2., :hp2..OR.:ehp2.,
or :hp2..XOR.:ehp2., and you can group conditions with parentheses.  You can
nest IFF statements up to 15 levels deep.  The
:hp1.conditions:ehp1. 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.
:p.
See the :link reftype=hd refid=IF.IF:elink. command for a list of the possible
:hp1.conditions:ehp1., and details on useing :hp2..AND.:ehp2., :hp2..OR.:ehp2.,
:hp2..XOR.:ehp2., and parentheses.
:p.
The :hp1.commands:ehp1. can include any internal command, alias, external
command, or batch file.
:p.
The following batch file fragment 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)&colon.
:xmp.
        iff "%_monitor" == "color" then
           color bright white on blue &amp. cls
           prompt=$e[s$e[1;1f$e[41;1;37m$e[K  Path&colon. $p$e[u$e[44;37m$n$g
        else
           prompt=$e[s$e[1;1f$e[0;7m$e[K  Path&colon. $p$e[u$e[0m$n$g
        endiff
:exmp.:p.
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)&colon.
:xmp.
        [c&colon.\] alias prune `iff isdir %1 then &amp. del /sxz %1
              &amp. else &amp. echo Not a directory! &amp. endiff`
:exmp.:p.
:hp8.Be sure to read the cautionary notes:ehp8. about GOTO and IFF under
the :link reftype=hd refid=GOTO.GOTO:elink. command before using a GOTO inside an IFF
statement.
:p.
If you :link reftype=hd refid=Piping.pipe:elink. data to an IFF, the data
will be passed to the command(s) following the IFF, not to IFF itself.

.* --------------------------------------------------------------------------

:h2 name=INKEY.INKEY - Get a character from the keyboard
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Get a single keystroke from the user and
store it in an environment variable.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.INKEY [/C /D /K"keys" /P /Wn /X]
[:ehp2.:hp3.prompt:ehp3. :hp2.]:ehp2. :hp3.%%varname:ehp3.
.br
:pt.:pd.:hp3.prompt :ehp3.&colon.  Optional text that is displayed as a prompt.
:pt.:pd.:hp3.varname :ehp3.&colon.  The variable that will hold the user's keystroke.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./C:ehp2.(lear buffer):pd.:hp2./P:ehp2.(assword)
:pt.:hp2./D:ehp2.(igits only):pd.:hp2./W:ehp2.(ait)
:pt.:hp2./K:ehp2.(valid keystrokes):pd.:hp2./X:ehp2. (no carriage return)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=INPUT.INPUT:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
If :hp1.prompt:ehp1. text is included in an INKEY command, it is displayed
while INKEY waits for input.
:p.
The following batch file fragment prompts for a character and
stores it in the variable :hp1.NUM:ehp1.&colon.
:xmp.
        inkey Enter a number from 1 to 9&colon.  %%num
:exmp.:p.
INKEY reads standard input for the keystroke, so it will accept
keystrokes from a redirected file or from the :link reftype=hd
refid=KEYSTACK.KEYSTACK:elink..  You can supply a list of valid
keystrokes with the :hp2./K:ehp2. option.
:p.
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 :hp2.F1:ehp2. key is
@59).  The :hp2.Enter:ehp2. key is stored as an extended keystroke, with
the code @28.  See the :link reftype=hd refid=RefTab.Reference Tables:elink.
for a list of the ASCII and extended key codes.
:p.
To test for a non-printing ASCII keystroke returned by INKEY use the
:link reftype=hd refid=_@ASCII.@ASCII:elink. function to get the numeric
value of the key.  For example, to test for :hp2.Esc:ehp2., which has an
ASCII value of 27&colon.
:xmp.
        inkey Enter a key&colon.  %%key
        if "%@ascii[%key]" == "27" echo Esc pressed
:exmp.:p.
If you press :hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2. while INKEY 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.  A batch file can handle :hp2.Ctrl-C:ehp2. and
:hp2.Ctrl-Break:ehp2. itself with the :link reftype=hd refid=ON.ON:elink.
BREAK command.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./C:ehp2.&colon.:pd.(Clear 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 it
is ready to accept input.
:pt.:hp2./D:ehp2.&colon.:pd.(Digits only) Prevents INKEY from accepting any keystroke
except a digit from 0 to 9.
:pt.:hp2./K"keys":ehp2.&colon.:pd.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&colon.
:xmp.
        inkey /k"ab[Alt-F10]" Enter A, B, Alt-F10 %%var
:exmp.:p.
See :link reftype=hd refid=KeyNames.Keys and Key Names:elink. for a complete
listing of the key names you can use within the square brackets, and a
description of the key name format.
:p.
If an invalid keystroke is entered, &4OS2. will echo
the keystroke if possible, beep, move the cursor
back one character, and wait for another keystroke.
:pt.:hp2./P:ehp2.&colon.:pd.(Password) Prevents INKEY from echoing the character.
:pt.:hp2./W:ehp2.&colon.:pd.(Wait) 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.  This allows you to
continue the batch file if the user does not respond in a given period of
time.  You can specify :hp2./W0:ehp2. to return immediately if
there are no keys waiting in the keyboard buffer.
:p.
For example, the following batch file fragment waits up to 10 seconds for a
character, then tests to see if a "Y" was entered&colon.
:xmp.
        set net=N
        inkey /K"YN" /w10 Load network (Y/N)?  %%net
        iff "%net" == "Y" then
        rem Commands to load the network go here
        endiff
:exmp.
:pt.:hp2./X:ehp2.&colon.:pd.(No carriage return) Prevents INKEY from
displaying a carriage return and line feed after the user's entry.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=INPUT.INPUT - Get a string from the keyboard
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Get a string from the keyboard and save it in an
environment variable.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.INPUT [/C /D /E /Ln /N /P /Wn /X]
[:ehp2.:hp3.prompt:ehp3. :hp2.]:ehp2. :hp3.%%varname:ehp3.
.br
:pt.:pd.:hp3.prompt :ehp3.&colon.  Optional text that is displayed as a prompt.
:pt.:pd.:hp3.varname :ehp3.&colon.  The variable that will hold the user's input.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./C:ehp2.(lear buffer):pd.:hp2./N:ehp2.(o colors)
:pt.:hp2./D:ehp2.(igits only):pd.:hp2./P:ehp2.(assword)
:pt.:hp2./E:ehp2.(dit):pd.:hp2./W:ehp2.(ait)
:pt.:hp2./L:ehp2.(ength):pd.:hp2./X:ehp2. (no carriage return)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=INKEY.INKEY:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
If :hp1.prompt:ehp1. 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 :hp2./P:ehp2. password option, INPUT will echo asterisks instead of
the keys you type.
:p.
All characters entered up to, but not including, the carriage
return are stored in the variable.
:p.
The following batch file fragment prompts for a string and stores
it in the variable FNAME&colon.
:xmp.
        input Enter the file name&colon.  %%fname
:exmp.:p.
INPUT reads standard input, so it will accept text from a redirected file.
:p.
If you press :hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2. 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.  A batch file can handle :hp2.Ctrl-C:ehp2.
and :hp2.Ctrl-Break:ehp2. itself with the :link reftype=hd
refid=ON.ON:elink. BREAK command.
:p.
You should not :link reftype=hd refid=Piping.pipe:elink. text to INPUT.  If
you do, INPUT will set the variable to the first line it receives, but it
will set the variable in the "child" process used to handle the right hand
side fo the pipe.  This variable will not be available in the original copy
of &4OS2. used to start the pipe.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./C:ehp2.&colon.:pd.(Clear 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.
:pt.:hp2./D:ehp2.&colon.:pd.(Digits only) Prevents INKEY from accepting any
keystroke except a digit from 0 to 9.
:pt.:hp2./E:ehp2.&colon.:pd.(Edit) Allows you to edit an existing value.  If
there is no existing value for :hp1.varname:ehp1., INPUT proceeds as
if :hp2./E:ehp2. had not been used, and allows you to enter a new value.
:pt.:hp2./Ln:ehp2.&colon.:pd.(Length) Sets the maximum number of characters
which INPUT will accept to :hp1.n:ehp1..  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).
:pt.:hp2./N:ehp2.&colon.:pd.(No colors) Disables the use of input colors defined in the
:link reftype=hd refid=INI_InputColors.InputColors:elink. directive in :hp1.&4OS2INI.:ehp1.,
and forces INPUT to use the default display colors.
:pt.:hp2./P:ehp2.&colon.:pd.(Password) Tells INPUT to echo asterisks, instead of the
characters you type.
:pt.:hp2./Wn:ehp2.&colon.:pd.(Wait) 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.  This allows you to
continue the batch file if the user does not respond in a given period of
time.  If you enter a key before the timeout period, INPUT will wait
indefinitely for the remainder of the line.  You can specify :hp2./W0:ehp2.
to return immediately if there are no keys waiting in the keyboard buffer.
:pt.:hp2./X:ehp2.&colon.:pd.(No carriage return) Prevents INPUT from displaying
a carriage return and line feed after the user's entry.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=KEYBD.KEYBD - Set the keyboard toggles
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Set the state of the keyboard
toggles&colon.  Caps Lock, Num Lock, and Scroll Lock.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.KEYBD [/C:ehp2.:hp3.n:ehp3.
:hp2./N:ehp2.:hp3.n:ehp3. :hp2./S:ehp2.:hp3.n:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.n :ehp3.&colon.  0 to turn off the toggle, or 1 to turn on the
toggle.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./C:ehp2.(aps lock):pd.:hp2./S:ehp2.(croll lock)
:pt.:hp2./N:ehp2.(um lock):pd.
:eparml.:lm margin=1.
.br
:hp2.Usage:ehp2.
:p.
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.
:p.
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.
:p.
For example, to turn off the Num Lock and Caps Lock keys, you can
use this command&colon.
:xmp.
        [c&colon.\] keybd /c0 /n0
:exmp.:p.
If you use the KEYBD command with no switches, it will display the
present state of the toggle keys.
:p.
The toggle key state is typically the same for all sessions, and changes
made with KEYBD in one session will therefore affect all other sessions.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./C:ehp2.&colon.:pd.(Caps lock) Turn the Caps Lock key on or off.
:pt.:hp2./N:ehp2.&colon.:pd.(Num lock) Turn the Num Lock key on or off.
:pt.:hp2./S:ehp2.&colon.:pd.(Scroll lock) Turn the Scroll Lock key on or off.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=KEYS.KEYS - Enable or disable the history list
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Enable, disable, or display the history list.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.KEYS [ON &splitvbar. OFF &splitvbar. LIST]:ehp2.
:eparml.:p.
See also&colon.  :link reftype=hd refid=HISTORY.HISTORY:elink..
:p.
:hp2.Usage:ehp2.
:p.
This command is provided for compatibility with the KEYS command in
:hp1.CMD.EXE:ehp1., which controls the history list in OS/2.  The same
functions are available by setting the :link reftype=hd
refid=INI_HistMin.HistMin:elink. directive in the :hp1..INI:ehp1. file, and
by using the :link reftype=hd refid=HISTORY.HISTORY:elink. command.
:p.
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&colon.
:xmp.
        [c&colon.\] history
        [c&colon.\] history /p
        [c&colon.\] keys list
:exmp.:p.
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.
:p.
You can disable the collection and storage of commands in the
history list by typing&colon.
:xmp.
        [c&colon.\] keys off
:exmp.:p.
You can turn the history back on with the command&colon.
:xmp.
        [c&colon.\] keys on
:exmp.:p.
If you issue the KEYS command without any parameters, &4OS2.
will show you the current status of the history list.
:p.
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
:link reftype=hd refid=INI_LineInput.LineInput:elink. directive, or the
:hp2./L:ehp2. option of the
:link reftype=hd refid=SETDOS.SETDOS:elink. command, for details on line
input mode.

.* --------------------------------------------------------------------------

:h2 name=KEYSTACK.KEYSTACK - Feed keystrokes to a program or command
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Feed keystrokes to a program or command
automatically.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.KEYSTACK [!] [/Wn]
[:ehp2.":hp3.abc:ehp3. ":hp2.] [:ehp2.:hp3.keyname:ehp3. :hp2.[n]] ...:ehp2.
.br
:pt.:pd.:hp2.! :ehp2.&colon.  Signal to clear the Keystack and the keyboard
buffer.
:pt.:pd.:hp3.abc :ehp3.&colon.  Literal characters to be placed in the
Keystack.
:pt.:pd.:hp3.keyname :ehp3.&colon.  Name or code for a key to be placed in the
Keystack.
:pt.:pd.:hp2.n :ehp2.&colon.  Number of times to repeat the named key.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./W:ehp2.(ait):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=KeystackUse.Using the Keystack:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
KEYSTACK sends the keystrokes to the current active window.  If you want to
send keystrokes to another program (rather than have them function with &4OS2.
itself), you must start the program or :link reftype=hd
refid=ACTIVATE.ACTIVATE:elink. its window so it can receive the
keystrokes.  The KEYSTACK command must be executed :hp2.after:ehp2. you
start or ACTIVATE the program which is to receive the keystrokes.
:p.
KEYSTACK is most often used for programs started from batch files.  In order
for &4OS2.'s KEYSTACK to work in a batch file, you must start the program with
the :link reftype=hd refid=START.START:elink. command, then use the KEYSTACK
command.  If you start the program directly - without using START - the
batch file will wait for the application to complete before continuing and
running the KEYSTACK command, and the keystrokes will be placed in the
buffer too late.
:p.
If you use KEYSTACK in an alias executed from the prompt, the considerations
are essentially the same, but depend on whether :link reftype=hd
refid=INI_ExecWait.ExecWait:elink. is set.  If ExecWait is :hp2.not:ehp2.
set, you can use KEYSTACK immediately after an application is
started.  However, :hp2.if:ehp2. ExecWait is set, the KEYSTACK command will
not be executed until the program has finished, and the keystrokes will be
placed in the buffer too late.
:p.
You may not be able to use KEYSTACK effectively if you have programs running
in the background which change the active window (for example, by popping up
a dialog box).  If a window pops up in the midst of your KEYSTACK sequence,
keystrokes stored in the KEYSTACK buffer may go to that window, and not to
the application you intended.
:p.
KEYSTACK will only work if the program :hp1.KEYSTACK.EXE:ehp1. is
in the same directory :hp1.&4OS2..EXE:ehp1., or a directory listed in your
:link reftype=hd refid=PATH_Var.PATH:elink..  If
:hp1.KEYSTACK.EXE:ehp1. cannot be found, the KEYSTACK command will display
an error message.  KEYSTACK can send keystrokes to Presentation Manager
applications and to OS/2 character-mode applications running in a window.  It
cannot send keystrokes to DOS applications, or to character-mode
applications running in a full-screen session.
:p.
Characters entered within double quotes (:hp1."abc":ehp1.) will be sent "as
is" to the application.  The only items allowed outside double quotes are
key names, the :hp2.!:ehp2. and :hp2./W:ehp2. options, and a repeat count.
:p.
See :link reftype=hd refid=KeyNames.Keys and Key Names:elink. for
a complete listing of key names and a description of the key name and
numeric key code format.  If you want to send the same key name or numeric
code several times, you can follow it with a repeat count in square
brackets.  For example, to send the Enter key 4 times, you can use this
command:
:xmp.
        keystack enter [4]
:exmp.:p.
The repeat count works only with individual keystrokes, or numeric keystroke
or character values.  It cannot be used with quoted strings.
:p.
An exclamation mark [:hp2.!:ehp2.] will clear all pending keystrokes
in the KEYSTACK buffer.
:p.
For example, to start a program that needs a single space to skip its opening
screen you could use the command&colon.
:xmp.
        [c&colon.\comm] keystack 32 &amp. progname
:exmp.:p.
This places a space (ASCII code 32) in the buffer, then runs the
program.  When the program 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.
:p.
You can store a maximum of 1023 characters in the &4OS2. KEYSTACK
buffer.  The count is determined by the number of characters on the KEYSTACK
command line, not by the actual number of characters sent to the application.
:p.
Each time the KEYSTACK command is executed, it will clear any remaining
keystrokes stored by a previous KEYSTACK command.
:p.
You may need to experiment with your programs and insert delays (see the
:hp2./W:ehp2. option) to find a keystroke sequence that works for a
particular program.
:p.
:hp2.Advanced Options:ehp2.
:p.
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.
:p.
For example, the following batch file starts a spreadsheet programand loads
the file specified on the command line when the batch file is invoked (the
KEYSTACK command should be entered on one line)&colon.
:xmp.
        pushd c&colon.\finance
        keystack 0 Enter 0 Enter 0 Enter 0 Enter 0
          Enter "/FR" 0 "%1" Enter
        spread
        popd
:exmp.:p.
The sequence of "0 Enter" pairs tells the program that the keyboard buffer is
empty, then passes a carriage return, repeating this sequence five
times.  (You must determine the actual sequence required by your software
through experimentation.  Few programs require as long a startup sequence as
is shown here.)  This gets the program to a point where an empty spreadsheet
is displayed.  The rest of the KEYSTACK line issues a File Retrieve command
(/FR), simulates an empty 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.
:p.
Here's the same command defined as an alias (enter this on one line)&colon.
:xmp.
        alias sload `pushd c&colon.\finance &amp. keystack 0 Enter 0 Enter 0
          Enter 0 Enter 0 Enter "/FR" 0 "%1" Enter &amp. spread &amp. popd`
:exmp.:p.
KEYSTACK mimics the BIOS by stacking both an ASCII code and a scan code for
each key.  It does so by calculating the code for each character, whether it
is entered as part of a quoted string, as a key name, or as an ASCII value
less than 128.  However, if you are stacking keys for a program which
distinguishes between keys with the same symbol, like the plus on the
keyboard and the gray plus, you will have to calculate the codes for the
keys on the numeric keypad yourself.  Calculate the value ((256 * scan code)
+ ASCII code) and enter that numeric value as an argument for KEYSTACK.
:p.
For example, for the Enter key on the numeric keypad, the scan code is 224
and the ASCII code is 13, so to stack both values use ((256 * 224) + 13) or
KEYSTACK 57357.  Try this approach if a "normal" KEYSTACK command does not
work (for example, if you use "KEYSTACK Enter" for the Enter key and the
program doesn't see the correct character).  To stack such combined key
codes you must use the numeric value, not the key name.  See
:link reftype=hd refid=RefTab.Reference Tables:elink. for ASCII and scan
codes.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2./W:ehp2.&colon.:pd.(Wait) 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 :hp2.W:ehp2., and must be between 1 and 65535
(65535 ticks is about 1 hour).  You can use the :hp2./W:ehp2. 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 :hp2./W:ehp2.
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 :hp2.F7:ehp2., a delay of
one second, an indication that the keyboard buffer is empty, and a carriage
return&colon.
:xmp.
        [c&colon.\] keystack F7 /W18 0 Enter &amp. cadx
:exmp.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=LIST.LIST - Display a file
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display a file, with forward and backward
paging and scrolling.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.LIST [/A&colon.[[-]rhsda] /H /I /R /S
/T /W /X] :ehp2.:hp3.file:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  A file or list of files to display.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2. (Attribute select):pd.:hp2./S:ehp2.(tandard input)
:pt.:hp2./H:ehp2.(igh bit off):pd.:hp2./T:ehp2. (search for Text)
:pt.:hp2./I:ehp2.(gnore wildcards):pd.:hp2./W:ehp2.(rap)
:pt.:hp2./R:ehp2.(everse):pd.:hp2./X:ehp2. (heX display mode)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=TYPE.TYPE:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink.,
:link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and
:link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
LIST provides a fast and flexible way to view a file, without the overhead
of loading and using a text editor.
:p.
For example, to display a file called :hp1.MEMO.DOC:ehp1.&colon.
:xmp.
        [c&colon.\] list memo.doc
:exmp.:p.
LIST is most often used for displaying ASCII text files.  It can be used for
other files which contain non-alphabetic characters, but you may need to use
hex mode (see below) to read these files.
:p.
LIST uses the cursor pad to scroll through the file.  The following
keys have special meanings&colon.
:lm margin=8.:parml compact tsize=15 break=fit.
:pt.:hp2.Home:ehp2.:pd.Display the first page of the file.
:pt.:hp2.End:ehp2.:pd.Display the last page of the file.
:pt.:hp2.Esc:ehp2.:pd.Exit the current file.
:pt.:hp2.Ctrl-PgUp:ehp2.:pd.Display previous file.
:pt.:hp2.Ctrl-PgDn:ehp2.:pd.Display next file.
:pt.:hp2.Ctrl-C:ehp2.:pd.Quit LIST.
:pt.:hp2.PgUp:ehp2.:pd.Scroll up one page.
:pt.:hp2.PgDn or Space:ehp2.:pd.Scroll down one page.
:pt.:hp2.&uarrow.:ehp2.:pd.Scroll up one line.
:pt.:hp2.&darrow.:ehp2.:pd.Scroll down one line.
:pt.:hp2.:ehp2.:pd.Scroll left 8 columns.
:pt.:hp2.:ehp2.:pd.Scroll right 8 columns.
:pt.:hp2.Ctrl :ehp2.:pd.Scroll left 40 columns.
:pt.:hp2.Ctrl :ehp2.:pd.Scroll right 40 columns.
:pt.:hp2.F1:ehp2.:pd.Display online help
:pt.:hp2.B:ehp2.:pd.Go back one file to the previous file in the current
group of files.
:pt.:hp2.Ctrl-F:ehp2.:pd.Prompt and search for a string, searching backward
from the end of the file.
:pt.:hp2.F:ehp2.:pd.Prompt and search for a string.
:pt.:hp2.G:ehp2.:pd.Go to a specific line, or, in hex mode, to a specific
hexadecimal offset.
:pt.:hp2.H:ehp2.:pd.Toggle the "strip high bit" (:hp2./H:ehp2.) option.
:pt.:hp2.I:ehp2.:pd.Display information on the current file (the full name,
size, date, and time).
:pt.:hp2.N:ehp2.:pd.Find next matching string.
:pt.:hp2.Ctrl-N:ehp2.:pd.Find previous match in the file.
:pt.:hp2.P:ehp2.:pd.Print the current page or the entire file.
:pt.:hp2.W:ehp2.:pd.Toggle the "line wrap" (:hp2./W:ehp2.) option.
:pt.:hp2.X:ehp2.:pd.Toggle the hex-mode display (:hp2./X:ehp2.) option.
:eparml.:lm margin=1.
.br
Text searches performed with :hp2.F:ehp2., :hp2.N:ehp2., :hp2.Ctrl-F:ehp2.,
and :hp2.Ctrl-N:ehp2. are not case-sensitive.  However, if the display is
currently in hexadecimal mode and you press :hp2.F:ehp2. or
:hp2.Ctrl-F:ehp2., you will be prompted for whether you want
to search in hexadecimal mode.  If you answer :hp2.Y:ehp2., you should
then enter the search string as a sequence of 2-digit hexadecimal
numbers separated by spaces, for example :hp2.41 63 65:ehp2. (these are
the ASCII values for the string "Ace"; see :link reftype=hd
refid=ASCII.ASCII:elink. for a complete list of ASCII codes).  Hexadecimal
searches :hp2.are:ehp2. case-sensitive, and search for exactly the string
you enter.
:p.
When the search string is found LIST displays the line containing the string
at the top of the screen, and highlights the string it found.  Any
additional occurrences of the string on the same display page are also
highlighted.  Highlighting is intended for use with text files; in binary
files the search string will be found, but may not be highlighted properly.
:p.
You can use :link reftype=hd refid=Wildcards.wildcards:elink. in the search
string.  For example, you can search for the string "to*day" to find the
next line which contains the word "to" followed by the word "day"
later on the same line, or search for the numbers "101" or "401" with the
search string "[14]01".  If you begin the search string with a back-quote
[:hp2.`:ehp2.], or enclose it in back-quotes, wildcard characters in the
string will be treated as normal text with no special wildcard meaning.
:p.
LIST saves the search string used by :hp2.F:ehp2., :hp2.N:ehp2.,
:hp2.Ctrl-F:ehp2., and :hp2.Ctrl-N:ehp2. so you can
LIST multiple files and search for the same string simply by
pressing :hp2.N:ehp2. in each file, or repeat your search the next time
you use LIST.
:p.
You can use the :hp2./T:ehp2. switch to specify search text for the first
:hp1.file:ehp1..  When you do so, LIST begins a search as soon as the file
is loaded.  Use :hp2./I:ehp2. to ignore wildcards in the initial search
string, and :hp2./R:ehp2. to make the initial search go backwards from the
end of the file.  When you LIST multiple files with a single LIST command,
these switches affect only the first file; they are ignored for the second
and subsequent files.
:p.
You can use the :hp2.G:ehp2. key to go to a specific line number in the
file (or to a specified hexadecimal offset in hex mode).  LIST numbers
lines beginning with 1, unless :link reftype=hd
refid=INI_ListRowStart.ListRowStart:elink. is set to 0.  A new line is counted for
every CR or LF character (LIST determines automatically which character
is used for line breaks in each file), or when line length reaches 511
characters, whichever comes first.
:p.
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 :hp2.W:ehp2. command or :hp2./W:ehp2. 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.
:p.
To view text from the clipboard, use :hp2.CLIP&colon.:ehp2. as the file to
be listed.  CLIP&colon. will not return any data unless the clipboard
contains text.  See :link reftype=hd refid=Redirection.Redirection:elink. for
additional information on CLIP&colon..
:p.
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.
:p.
Printed output normally goes to device LPT1.  If you wish to send
the printed output to another device, use the Commands page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, or the
:link reftype=hd refid=INI_Printer.Printer:elink. directive in
:hp1.&4OS2INI.:ehp1..
:p.
If you specify a directory name instead of a filename as an argument, LIST
will display each of the files in that directory.
:p.
Most of the LIST keystrokes can be reassigned with :hp1..INI:ehp1. file
:link reftype=hd refid=INIKeyMap.key mapping:elink. directives.
:p.
You can set the colors used by LIST on the Commands page of the :link
reftype=hd refid=OPTION.OPTION:elink. dialogs, or the
:link reftype=hd refid=INI_ListColors.ListColors:elink. and
:link reftype=hd refid=INI_ListStatBarColors.ListStatBarColors:elink.
directives in the :hp1..INI:ehp1. 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.
:p.
By default, LIST sets tab stops every 8 columns.  You can change this
behavior on the Display page of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs, or with the :link reftype=hd
refid=INI_TabStops.TabStops:elink. :hp1..INI:ehp1. file directive.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(Attribute select) Select only those files that have the
specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute set.  The colon
[:hp2.&colon.:ehp2.] after /A is required.  The attributes are&colon.
.br
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.LIST /A&colon. ...:ehp2.), LIST will select all
files and subdirectories including hidden and system files.  If
attributes are combined, all the specified attributes must match for a
file to be selected. For example, /A&colon.RHS will select only those files
with all three attributes set.
.br
:pt.:hp2./H:ehp2.&colon.:pd.(High 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 :hp2.H:ehp2. key.
.br
:pt.:hp2./I:ehp2.&colon.:pd.(Ignore wildcards) Only meaningful when used in
conjunction with the :hp2./T "text":ehp2. option.  Directs LIST to interpret
characters such as :hp2.*:ehp2., :hp2.?:ehp2., :hp2.[:ehp2., and
:hp2.]:ehp2. as literal characters instead of wildcard
characters.  :hp2./I:ehp2. affects only the initial search started by
:hp2./T:ehp2., not subsequent searches started from within LIST.
.br
:pt.:hp2./R:ehp2.&colon.:pd.(Reverse) Only meaningful when used in
conjuction with the :hp2./T "text" :ehp2.option.  Directs LIST to search for
text from the end of the file instead of from the beginning of the
file.  Using this switch can speed up searches for text that is normally
near the end of the file, such as a signature.  :hp2./R:ehp2. affects only
the initial search started by :hp2./T:ehp2., not subsequent searches started
from within LIST.
.br
:pt.:hp2./S:ehp2.&colon.:pd.(Standard input) Read from standard input rather than a
file.  This allows you to redirect command output
and view it with LIST.  Normally, LIST will detect input from a redirected
command and adjust automatically.  However, you may find circumstances when
:hp2./S:ehp2. is required.  For example, to use LIST to
display the output of DIR you could use either of these commands&colon.
:xmp.
        [c&colon.\] dir &splitvbar. list
        [c&colon.\] dir &splitvbar. list /s
:exmp.
.br
:pt.:hp2./T:ehp2.&colon.:pd.(Text) Search for text in the first
:hp1.file:ehp1..  This option is the same as pressing :hp2.F:ehp2., but it
allows you to specify the search text on the command line.  The text must be
contained in quotation marks if it contains spaces, punctuation, or wildcard
characters.  For example, to search for the string &4OS2. in the file
:hp1.README.DOC:ehp1., you can use this command&colon.
:xmp.
        [c&colon.\] list /t&4OS2. readme.doc
:exmp.:p.
The search text may include :link reftype=hd refid=Wildcards.wildcards
and extended wildcards:elink..  For example, to search for the words Hello
and John on the same line in the file :hp1.LETTER.DAT:ehp1.&colon.
:xmp.
        [c&colon.\] list /t"Hello*John" letter.dat
:exmp.:p.
When you LIST multiple files with a single LIST command, :hp2./T:ehp2. only
initiates a search in the first file.  It is ignored for the second and
subsequent files.  Also see :hp2./I:ehp2. and :hp2./R:ehp2..
.br
:pt.:hp2./W:ehp2.&colon.:pd.(Wrap) 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 :hp2.W:ehp2. key.
.br
:pt.:hp2./X:ehp2.:pd.(heX mode)&colon.  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 :hp2.X:ehp2. key.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=LOADBTM.LOADBTM - Switch a batch file's mode
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Switch a batch file to or from BTM mode.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.LOADBTM [ON &splitvbar. OFF]:ehp2.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
&4OS2. recognizes two kinds of :link reftype=hd refid=Batch.batch
files:elink.&colon. :hp1..BAT:ehp1. or :hp1..CMD:ehp1., and
:hp1..BTM:ehp1..  Batch files executing in BTM mode run two to ten times
faster than in BAT or CMD mode.  Batch files automatically start in the mode
indicated by their extension.
:p.
The LOADBTM command turns BTM mode on and off.  It can be used to
switch modes in either a :hp1..BAT:ehp1. / :hp1..CMD:ehp1., or
:hp1..BTM:ehp1. file.  If you use LOADBTM with no argument, it will display
the current batch mode&colon.  LOADBTM ON or LOADBTM OFF.
:p.
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.
:p.
LOADBTM can only be used within a batch file.  It is most often
used to convert a :hp1..BAT:ehp1. or :hp1..CMD:ehp1. file to BTM mode
without changing its extension.

.* --------------------------------------------------------------------------

:h2 name=LOG.LOG - Save a log of commands
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Save a log of commands to a disk file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.LOG [/H /W :ehp2.:hp3.file:ehp3. :hp2.]
[ON &splitvbar. OFF &splitvbar. :ehp2.:hp3.text:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  The name of the file to hold the log.
:pt.:pd.:hp3.text :ehp3.&colon.  An optional message that will be added to the log.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./H(:ehp2.istory log):pd.:hp2./W:ehp2.(rite to).
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=HISTORY.HISTORY:elink..
:p.
:hp2.Usage:ehp2.
:p.
LOG keeps a record of all internal and external commands you use, whether
they are executed from the prompt or from a batch file.  Each entry includes
the current system date and time, along with the actual command after any
alias or variable expansion.  You can use the log file as a record of your
daily activities.
:p.
LOG with the :hp2./H:ehp2. option keeps a similar record called a "history
log".  The history log records only commands entered at the prompt; it does
not record batch file commands.  In addition, the history log does not
record the date and time for each command, and it records commands before
aliases and variables are expanded.
:p.
The two logging options are independent.  You can have both a regular log
and a history log enabled simultaneously.
:p.
By default, LOG writes to the file :hp1.&4OS2.LOG:ehp1. in the root directory
of the boot drive.  The default file name for the history log is
:hp1.&4OS2.HLOG:ehp1..  You can set the default log file names on the Options
2 page of the :link reftype=hd refid=OPTION.OPTION:elink. dialogs, or with the
:link reftype=hd refid=INI_LogName.LogName:elink. and
:link reftype=hd refid=INI_HistLogName.HistLogName:elink. directives in
:hp1.&4OS2INI.:ehp1..
:p.
Entering LOG or LOG /H with no parameters displays the name of the log file
and the log status (ON or OFF)&colon.
:xmp.
        [c&colon.\] log
        LOG (C&colon.\&4OS2.LOG) is OFF
:exmp.:p.
To enable or disable logging, add the word "ON" or "OFF" after the
LOG command&colon.
:xmp.
        [c&colon.\] log on
:exmp.:p.
or
:xmp.
        [c&colon.\] log /h on
:exmp.:p.
Entering LOG or LOG /H with :hp1.text:ehp1. writes a message to the log
file, even if logging is set OFF.  This allows you to enter
headers in the log file&colon.
:xmp.
        [c&colon.\] log "Started work on the database system"
:exmp.:p.
The LOG file format looks like this&colon.
:xmp.
        [date  time]  command
:exmp.:p.
where the date and time are formatted according to the country code set
for your system.
:p.
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.
:p.
You can have both a regular log (with time and date stamping) and a
history log (without the time stamps) enabled simultaneously.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2./H:ehp2.&colon.:pd.(History log) This option makes the other options
on the command line (after the :hp2./H:ehp2.) apply to the history log.  For
example, to turn on history logging and write to the file
:hp1.C&colon.\LOG\HLOG:ehp1. &colon.
:xmp.
        [c&colon.\]  log /h /w c&colon.\log\hlog
:exmp.
:pt.:hp2./W:ehp2.&colon.:pd.(Write) 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 :hp1.C&colon.\LOG\LOGFILE:ehp1. &colon.
:xmp.
        [c&colon.\] log /w c&colon.\log\logfile
:exmp.
.br
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.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=MD.MD - Create a subdirectory
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Create a subdirectory.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.MD [/N /S]:ehp2.
:hp3.path:ehp3. :hp2....:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.MKDIR [/N /S]:ehp2. :hp3.path:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.path :ehp3.&colon.  The name of one or more directories to create.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./N:ehp2.(o update):pd.:hp2./S:ehp2.(ubdirectories)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=RD.RD:elink..
:p.
:hp2.Usage:ehp2.
:p.
MD and MKDIR are synonyms.  You can use either one.
:p.
MD creates a subdirectory anywhere in the directory tree.  To
create a subdirectory from the root, start the :hp1.path:ehp1. with a
backslash [:hp2.\:ehp2.].  For example, this command creates a
subdirectory called :hp1.MYDIR:ehp1. in the root directory&colon.
:xmp.
        [c&colon.\] md \mydir
:exmp.:p.
If no path is given, the new subdirectory is created in the current
directory.  This example creates a subdirectory called :hp1.DIRTWO:ehp1.
in the current directory&colon.
:xmp.
        [c&colon.\mydir] md dirtwo
:exmp.:p.
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 [:hp2...\:ehp2.].
:p.
When creating a directory on an HPFS drive, you must quote any
:hp1.path:ehp1. which contains whitespace or special characters.  See
:link reftype=hd refid=FileNames.File Names:elink. for
additional details on file name quoting.
:p.
If MD creates one or more directories, they will be added automatically to
the :link reftype=hd refid=ExtDirSearch.extended directory search:elink. database
unless the :hp2./N:ehp2. option is specified.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./N:ehp2.&colon.:pd.(No Update) Do not update the
:link reftype=hd refid=ExtDirSearch.extended directory search:elink. database,
:hp1.JPSTREE.IDX:ehp1.  This is useful when creating a temporary directory
which you do not want to appear in the extended search database.
:pt.:hp2./S:ehp2.&colon.:pd.(Subdirectories) MD creates one directory at a
time unless you use the :hp2./S:ehp2. option.  If you need to create
the directory :hp1.C&colon.\ONE\TWO\THREE:ehp1. and none of the
named directories exist, you can use :hp2./S:ehp2. to have MD create all of
the necessary subdirectories for you in a single command&colon.
:xmp.
        [c&colon.\] md /s \one\two\three
:exmp.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=MEMORY.MEMORY - Display memory statistics
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display the amount and status of system RAM.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.MEMORY:ehp2.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
MEMORY lists the total physical and resident RAM in your system,
the largest free block of RAM, the swap file size,
the total and free environment and alias space, and the total
history space.  If you use a non-standard swap file location, the swap
file size will be displayed as 0 unless you set the
:link reftype=hd refid=INI_SwapFilePath.SwapFilePath:elink. directive.

.* --------------------------------------------------------------------------

:h2 name=MOVE.MOVE - Move files
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Move files to a new directory and drive.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.MOVE  [/A&colon.[[-]rhsda] /C /D /E /F
/H /M /N /P /Q /R /S /T /U /V]:ehp2. :hp3.source:ehp3. :hp2....:ehp2.
:hp3.destination:ehp3.
.br
:pt.:pd.:hp3.source :ehp3.&colon.  A file or list of files to move.
:pt.:pd.:hp3.destination :ehp3.&colon.  The new location for the files.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2. (Attribute select):pd.:hp2./P:ehp2.(rompt)
:pt.:hp2./C:ehp2.(hanged):pd.:hp2./Q:ehp2.(uiet)
:pt.:hp2./D:ehp2.(irectory):pd.:hp2./R:ehp2.(eplace)
:pt.:hp2./E:ehp2. (No error messages):pd.:hp2./S:ehp2.(ubdirectory tree)
:pt.:hp2./F:ehp2.(orce delete):pd.:hp2./T:ehp2.(otal)
:pt.:hp2./H:ehp2.(idden and system):pd.:hp2./U:ehp2.(pdate)
:pt.:hp2./M:ehp2.(odified files):pd.:hp2./V:ehp2.(erify)
:pt.:hp2./N:ehp2.(othing)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=COPY.COPY:elink. and
:link reftype=hd refid=REN.RENAME:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink.,
:link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and
:link reftype=hd refid=InclList.include lists:elink..  Date, time, or size
ranges anywhere on the line apply to all :hp1.source:ehp1. files.
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
The simplest MOVE command moves a single :hp1.source:ehp1. file to a new
location and, optionally, gives it a new name.  These two examples
both move one file from drive :hp1.C&colon.:ehp1. to the root directory on drive
:hp1.A&colon.:ehp1.
:xmp.
        [c&colon.\] move myfile.dat a&colon.\
        [c&colon.\] move myfile.dat a&colon.\savefile.dat
:exmp.:p.
In both cases, :hp1.MYFILE.DAT:ehp1. is removed from drive :hp1.C&colon.:ehp1. after it
has been copied to drive :hp1.A&colon.:ehp1..  If a file called :hp1.MYFILE.DAT:ehp1.
in the first example, or :hp1.SAVEFILE.DAT:ehp1. in the second example,
already existed on drive :hp1.A&colon.:ehp1., 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.)
:p.
When you move a single file, the :hp1.destination:ehp1. can be a directory
name or a file name.  If it is a directory name, and you add a backslash
[:hp2.\:ehp2.] to the end of the 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 :hp1.destination:ehp1. directory name
as a file name, and attempting to move the :hp1.source:ehp1. file to that
name.
:p.
If you move multiple files, the :hp1.destination:ehp1. :hp2.must:ehp2. be a
directory name.  MOVE will move each file into the :hp1.destination:ehp1.
directory with its original name.  If the :hp1.destination:ehp1. is not a
directory, MOVE will display an error message and exit.  For example, if
:hp1.C&colon.\FINANCE\MYFILES:ehp1. is not a directory, this command will
display an error; otherwise, the files will be moved to that directory&colon.
:xmp.
        [c&colon.\] move *.wks *.txt c&colon.\finance\myfiles
:exmp.:p.
The :hp2./D:ehp2. option can be used for single or multiple file moves; it
checks to see whether the :hp1.destination:ehp1. is a directory, and will
prompt to see if you want to create the :hp1.destination:ehp1. directory if
it doesn't exist.
:p.
If MOVE creates one or more destination directories, they will be added
automatically to the
:link reftype=hd refid=ExtDirSearch.extended directory search:elink. database.
:p.
You cannot move a file to a character device like the printer, or
to itself.
:p.
:hp8.Be careful when you use MOVE with the :link reftype=hd refid=SELECT.SELECT:elink.
command.:ehp8.  If you SELECT multiple files and the destination 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 destination 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 destination file.
:p.
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
[:hp2.\:ehp2.] to the end of the :hp1.destination:ehp1. name to ensure that
it is the name of a subdirectory (see above).
:p.
:hp2.Advanced Features and Options:ehp2.
:p.
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 (:hp1.e.g.:ehp1., because the :hp1.destination:ehp1. is on a different
drive or already exists), MOVE will copy the file(s) and then delete the
originals.
:p.
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 :hp1.source:ehp1. drive.  The free space may be the result of
moving the files to another drive, or of overwriting a larger
:hp1.destination:ehp1. file with a smaller :hp1.source:ehp1. file.  MOVE
displays the amount of disk space recovered unless the :hp2./Q:ehp2. 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 retains deleted files for later recovery, or if another program
performs a file operation while the MOVE command is executed.
:p.
When physically copying files, MOVE preserves the hidden, system,
and read-only attributes of the :hp1.source:ehp1. files, and sets the
archive attribute of the :hp1.destination:ehp1. files.  However, if the
files can be renamed, and no copying is required, then the file attributes
are not changed.
:p.
Use caution with the :hp2./A&colon.:ehp2. and :hp2./H:ehp2. switches (both
of which can allow MOVE to process hidden files) when you are physically
moving files, and both the :hp1.source:ehp1. and :hp1.destination:ehp1.
directories contain file descriptions.  If the :hp1.source:ehp1. file
specification matches the description file name (normally
:hp1.DESCRIPT.ION:ehp1.), and you tell MOVE to process hidden files, the
:hp1.DESCRIPT.ION:ehp1. file itself will be moved, overwriting any existing
file descriptions in the :hp1.destination:ehp1. directory.  For example, if
the :hp1.C&colon.\DATA:ehp1. directory contains file descriptions, this
command would overwrite any existing descriptions in the
:hp1.D&colon.\SAVE:ehp1. directory:
:xmp.
        [c&colon.\data] move /h d*.* d&colon.\save\
:exmp.:p.
(If you remove the hidden attribute from the :hp1.DESCRIPT.ION:ehp1. file
the same caution applies even if you do not use :hp2./A&colon.:ehp2. or
:hp2./H:ehp2., as :hp1.DESCRIPT.ION:ehp1. is then treated like any other
file.)
:p.
If you move a file from a FAT volume to an HPFS volume, and you do not give
an explicit :hp1.destination:ehp1. name (:hp1.i.e.:ehp1. you are moving the
file to the current directory, or your :hp1.destination:ehp1. name is made
up entirely of wildcards), MOVE will look for a .LONGNAME extended attribute
for the :hp1.source:ehp1. file.  If it finds that attribute, it will use the
long filename for the destination file.  If it does not, it will use the
short name.
:p.
Similarly, if you MOVE files with long filenames from an HPFS volume to a FAT
volume, &4OS2. will create the :hp1.destination:ehp1. files with short,
FAT-compatible names and save the long filenames in the .LONGNAME extended
attribute.  The short name is created by replacing special characters with
underscores, adding numeric digits to the filename (if necessary) to make
the new name unique, and truncating the name to fit with in the "8.3" FAT
name structure.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A&colon.:ehp2.&colon.:pd.(Attribute select) Select only those files that have the
specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute set.  The colon
[:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is required.  The attributes are&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.MOVE /A&colon. ...:ehp2.), MOVE will select all
files and subdirectories including hidden and system files.  If
attributes are combined, all the specified attributes must match for a
file to be selected.  For example, /A&colon.RHS will select only those files
with all three attributes set.
:p.
See the cautionary note under :hp2.Advanced Features and Options:ehp2. above
before using :hp2./A&colon.:ehp2. when both :hp1.source:ehp1. and
:hp1.destination:ehp1. directories contain file descriptions.
:pt.:hp2./C:ehp2.&colon.:pd.(Changed files) Move files only if the :hp1.destination:ehp1.
file exists and is older than the :hp1.source:ehp1. (see also
:hp2./U:ehp2.).  This option is useful for updating the files in one
directory from those in another without moving any newly-created files.
:pt.:hp2./D:ehp2.&colon.:pd.(Directory) Requires that the :hp1.destination:ehp1. be a
directory.  If the :hp1.destination:ehp1. does not exist, MOVE will prompt
to see if you want to create it.  If the :hp1.destination:ehp1. exists as a
file, MOVE will fail with an "Access denied" error.  Use this option to
avoid having MOVE accidentally interpret your :hp1.destination:ehp1. name as
a file name when it's really a mistyped directory name.
:pt.:hp2./E:ehp2.&colon.:pd.(No error messages) Suppress all non-fatal error
messages, such as "File Not Found."  Fatal error messages, such as "Drive
not ready," will still be displayed.  This option is most useful in batch
files and aliases.
:pt.:hp2./F:ehp2.&colon.:pd.(Force delete) This option forces deletion of the
:hp1.source:ehp1. file without saving it to the DELDIR directory (if DELDIR
is not in use, :hp2./F:ehp2. has no effect).  :hp2./F:ehp2. is only
effective when MOVE must copy the :hp1.source:ehp1. file(s) and delete the
originals (:hp1.i.e.:ehp1., if the :hp1.destination:ehp1. is on a different
drive or the destination file already exists).  If the files are simply
renamed, :hp2./F:ehp2. has no effect.
:pt.:hp2./H:ehp2.&colon.:pd.(Hidden) Move all files, including hidden and
system files.  See the cautionary note under :hp2.Advanced Features and
Options:ehp2. above before using :hp2./H:ehp2. when both :hp1.source:ehp1. and
:hp1.destination:ehp1. directories contain file descriptions.
:pt.:hp2./M:ehp2.&colon.:pd.(Modified files) Move only files that have the
archive bit set. The archive bit will remain set after the MOVE; to clear it
use :link reftype=hd refid=ATTRIB.ATTRIB:elink..
:pt.:hp2./N:ehp2.&colon.:pd.(Nothing) Do everything except actually move the file(s).
This option is most useful for testing what a
complex MOVE command will do.
:pt.:hp2./P:ehp2.&colon.:pd.(Prompt) Prompt the user to confirm each move.  Your options
at the prompt are explained in detail under :link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) 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 :hp2./T:ehp2..
:pt.:hp2./R:ehp2.&colon.:pd.(Replace) Prompt for a :hp2.Y:ehp2. or :hp2.N:ehp2. response before
overwriting an existing :hp1.destination:ehp1. file.
:pt.:hp2./S:ehp2.&colon.:pd.(Subdirectories) Move an entire subdirectory tree to
another location.  MOVE will attempt to create the
:hp1.destination:ehp1. directories if they don't exist, and
will remove empty subdirectories after the move.  When :hp2./D:ehp2. is used
with :hp2./S:ehp2., you will be prompted if the first :hp1.destination:ehp1.
directory does not exist, but subdirectories below that will be
created automatically by MOVE.  If MOVE /S creates one or more destination
directories, they will be added automatically to the
:link reftype=hd refid=ExtDirSearch.extended directory search:elink. database.
:p.
If you attempt to use :hp2./S:ehp2. to move a subdirectory tree into part of
itself, MOVE will detect the resulting infinite loop, display an error
message, and exit.
:pt.:hp2./T:ehp2.&colon.:pd.(Total) Don't display filenames as they are moved, but
display the total number of files moved and the
amount of free disk space recovered, if any.
:pt.:hp2./U:ehp2.&colon.:pd.(Update) Move each :hp1.source:ehp1. file only
if it is newer than a matching :hp1.destination:ehp1. file or if a matching
:hp1.destination:ehp1. file does not exist (also see :hp2./C:ehp2.).  This
option is useful for moving new or changed files from one directory to
another.
:pt.:hp2./V:ehp2.&colon.:pd.(Verify) Verify each disk write.  This is the
same as executing the VERIFY ON command, but is only active during the
MOVE.  :hp2./V:ehp2. does :hp2.not:ehp2. read back the file and compare its
contents with what was written; it only verifies that the data written to
disk is physically readable.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=ON.ON - Handle Ctrl-Break and errors in batch files
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Execute a command in a batch file when a
specific condition occurs.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.ON BREAK [:ehp2.:hp3.command:ehp3.
:hp2.]:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.ON ERROR [:ehp2.:hp3.command:ehp3. :hp2.]:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.ON ERRORMSG [:ehp2.:hp3.command:ehp3. :hp2.]:ehp2.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
ON can only by used in batch files.
:p.
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 corresponding :hp1.command:ehp1. is
automatically executed.
:p.
ON BREAK will execute the :hp1.command:ehp1. if the user presses
:hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2..
:p.
ON ERROR and ON ERRORMSG will execute the :hp1.command:ehp1. after any
command processor or operating system error (including :link reftype=hd
refid=CritErr.critical errors:elink.).  That is, they will detect errors
such as a disk write error, and &4OS2. errors such as a COPY command that
fails to copy any files, or the use of an unacceptable command option.
:p.
ON ERROR executes the :hp1.command:ehp1. immediately after the error occurs,
without displaying any command processor error message (operating system
errors may still be displayed in some cases).  ON ERRORMSG displays the
appropriate error message, then executes the :hp1.command:ehp1..  If both
are specified, ON ERROR will take precedence, and the ON ERRORMSG setting
will be ignored.  The remainder of this section discusses both settings
together, using the term "ON ERROR[MSG]".
:p.
ON BREAK and ON ERROR[MSG] are independent of each other.  You can use
either one, or both, in any batch file.
:p.
Each time ON BREAK or ON ERROR[MSG] is used, it defines a new
:hp1.command:ehp1. to be executed for a break or error, and any old
:hp1.command:ehp1. is discarded.  If you use ON BREAK or ON ERROR[MSG]
with no following :hp1.command:ehp1., that type of error handling is
disabled.  Error handling is also automatically disabled when the batch file
exits.
:p.
ON BREAK and ON ERROR[MSG] 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.
:p.
The :hp1.command:ehp1. can be any command that can be used on a batch file
line by itself.  Frequently, it is a :link reftype=hd refid=GOTO.GOTO:elink.
or :link reftype=hd refid=GOSUB.GOSUB:elink. command.  For example, the
following fragment traps any user attempt to end the batch file by pressing
:hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2..  It scolds the user for trying
to end the batch file and then continues displaying the numbers from 1 to
1000&colon.
:xmp.
        on break gosub gotabreak
        do i = 1 to 1000
           echo %i
        enddo
        quit
        &colon.gotabreak
        echo Hey!  Stop that!!
        return
:exmp.:p.
You can use a :link reftype=hd refid=Grouping.command group:elink. as the :hp1.command:ehp1. if you
want to execute multiple commands, for example&colon.
:xmp.
        on break (echo Oops, got a break! &amp. quit)
:exmp.:p.
ON BREAK and ON ERROR[MSG] always assume that you want to continue
executing the batch file.  After the :hp1.command:ehp1. 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 :hp1.command:ehp1. to transfer control to
another point with :link reftype=hd refid=GOTO.GOTO:elink., end the batch
file with :link reftype=hd refid=QUIT.QUIT:elink. or :link reftype=hd
refid=CANCEL.CANCEL:elink., or start another batch file (without CALLing it).
:p.
When handling an error condition with ON ERROR[MSG], you may find it
useful to use :link reftype=hd refid=IntVars.internal variables:elink.,
particularly :link reftype=hd refid=__QMARK.%_?:elink. and :link reftype=hd
refid=_SYSERR.%_SYSERR:elink., to help determine the cause of the error.
:p.
The ON ERROR[MSG] command will :hp2.not:ehp2. be invoked if an error occurs
while reading or writing a redirected input file, output file, or pipe.
:p.
:hp8.Caution&colon.:ehp8.  If a break or error occurs while the
:hp1.command:ehp1. specified in ON BREAK or ON ERROR[MSG] is executing, the
:hp1.command:ehp1. will be restarted.  This means you must use caution to
avoid or handle any possible errors in the commands invoked by ON ERROR[MSG],
since such errors can cause an infinite loop.

.* --------------------------------------------------------------------------

:h2 name=OPTION.OPTION - Modify the command processor configuration
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Modify the command processor configuration
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.OPTION [//:ehp2.:hp3.optname:ehp3.
:hp2.=:ehp2.:hp3.value:ehp3. :hp2....]:ehp2.
.br
:pt.:pd.:hp3.optname :ehp3.&colon.  An INI file directive to set or modify.
:pt.:pd.:hp3.value :ehp3.&colon.  A new value for that directive.
:eparml.:p.
See also&colon.  :link reftype=hd refid=INIFile.&4OS2INI.:elink..
:p.
:hp2.Usage:ehp2.
:p.
OPTION displays a settings notebook which allows you to modify many of the
configuration options stored in the file :hp1.&4OS2INI.:ehp1..
:p.
When you exit from the notebook, you can select the :hp2.Save:ehp2. button
to save your changes in :hp1.&4OS2INI.:ehp1. for use in the current session
and all future sessions, select the :hp2.OK:ehp2. button to use your
changes in the current session only, or select the :hp2.Cancel:ehp2. button
to discard the changes.
:p.
:hp2.Save:ehp2. saves all changes since the last :hp2.Save:ehp2., or since
the last time you started the command processor.  If you run OPTION and exit
with :hp2.OK:ehp2., any changes will not be saved in :hp1.&4OS2INI.:ehp1. at
that time.  However, if you run OPTION again and exit with :hp2.Save:ehp2.,
any earlier changes will automatically be saved in the :hp1..INI:ehp1. file
along with any new changes.
:p.
In most cases, changes you make in the :hp2.Startup:ehp2. section of the
OPTION dialogs or notebook will only take effect when you restart your
command processor.
:p.
Other changes take effect as soon as you exit the dialogs or notebook with
:hp2.Save :ehp2. or :hp2.OK:ehp2..  However, not all option changes will
appear immediately, even if they have taken effect.  For example, some color
changes will only appear after a :link reftype=hd refid=CLS.CLS:elink.
command.
:p.
OPTION handles most standard :hp1.&4OS2INI.:ehp1. file settings.  More
advanced settings, including all those listed under
:link reftype=hd refid=INIKeyMap.Key Mapping Directives:elink.
and :link reftype=hd refid=INIAdv.Advanced Directives:elink. cannot be
modified with the OPTION dialogs or notebook.  These settings must be
inserted or modified in :hp1.&4OS2INI.:ehp1. manually.
:p.
OPTION does not preserve comments when saving modified settings in the
:hp1.&4OS2INI.:ehp1. file.  To be sure :hp1..INI:ehp1. file comments are preserved, put them on
separate lines in the file.  See :link reftype=hd
refid=INIModify.Modifying the .INI File:elink. additional details.
:p.
OPTION runs the external program :hp1.OPTION.EXE:ehp1. to display the
notebook.  If the command processor cannot find :hp1.OPTION.EXE :ehp1.it will
display an error message.  :hp1.OPTION.EXE :ehp1.must be run with the OPTION
command, and will not work if you invoke it directly.
:p.
:hp2.Setting Individual Options:ehp2.
:p.
If you follow the OPTION command with one or more sequences of a double slash
mark [:hp2.//:ehp2.] followed by an :hp2.option=value:ehp2. setting, the
OPTION notebook will not appear.  Instead, the new settings will take effect
immediately, and will be in effect for the current session only.  This
example turns off batch file echo and changes the input colors to bright
cyan on black (enter this all on one line)&colon.
:xmp.
        [c&colon.\] option //BatchEcho = No //InputColors = bri cya on bla
:exmp.:p.
Option values may contain whitespace.  However, you cannot enter an option
value which contains the "//" string.
:p.
This feature is most useful for testing settings quickly, and in aliases or
batch files which depend on certain options being in effect.
:p.
Changes made with :hp2.//:ehp2. are temporary.  They will not be saved in
:hp1.&4OS2INI.:ehp1., even if you subsequently load the option dialogs
and select :hp2.Save:ehp2..

.* --------------------------------------------------------------------------

:h2 name=PATH.PATH - Set the executable file search path
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display or alter the list of directories
that &4OS2. will search for executable files, batch files, and files with
executable extensions that are not in the current directory.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.PATH [:ehp2.:hp3.directory:ehp3.
:hp2.[;:ehp2.:hp3.directory:ehp3. :hp2....]]:ehp2.
.br
:pt.:pd.:hp3.directory :ehp3.&colon.  The full name of a directory to include in the path setting.
:eparml.:p.
See also&colon.  :link reftype=hd refid=ESET.ESET:elink. and :link reftype=hd refid=SET.SET:elink..
:p.
:hp2.Usage:ehp2.
:p.
When &4OS2. is asked to execute an external command (a :hp1..COM:ehp1.,
:hp1..EXE:ehp1., :hp1..BTM:ehp1., :hp1..BAT:ehp1., or :hp1..CMD:ehp1. 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 :hp1.directories:ehp1. specified in the PATH setting.
:p.
For example, after the following PATH command, &4OS2. will search for
an executable file in four directories&colon.  the current directory,
then the root directory on drive C, then the :hp1.DOS:ehp1. subdirectory
on C, and then the :hp1.UTIL:ehp1. subdirectory on C&colon.
:xmp.
        [c&colon.\] path c&colon.\;c&colon.\dos;c&colon.\util
:exmp.:p.
The list of :hp1.directories:ehp1. 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.
:p.
Directory names in the path must be separated by semicolons
[:hp2.;:ehp2.].  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
:link reftype=hd refid=SET.SET:elink. or :link reftype=hd refid=ESET.ESET:elink. 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.
:p.
If you enter PATH with no parameters, the current path is
displayed&colon.
:xmp.
        [c&colon.\] path
        PATH=C&colon.\;C&colon.\DOS;C&colon.\UTIL
:exmp.:p.
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).
:p.
Some applications also use the PATH to search for their data files.
:p.
&4OS2. normally searches the path for files with the extensions
:hp1..COM:ehp1., :hp1..EXE:ehp1., :hp1..BTM:ehp1., :hp1..CMD:ehp1., and :hp1..BAT:ehp1.
(in that order).  However, if you include an explicit file extension on
a command name (for example, :hp1.WP.EXE:ehp1.), 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 (:hp1.e.g., WP.COM).:ehp1.
:p.
The standard list of extensions for which to search can be modified by
setting :link reftype=hd refid=INI_PathExt.PathExt:elink. to Yes in
:hp1.&4OS2INI.:ehp1., then setting the :link reftype=hd
refid=PATHEXT.PATHEXT:elink. variable.
:p.
If you have an entry in the path which consists of a single period
[:hp2..:ehp2.], the current directory will :hp2.not:ehp2. be searched first,
but instead will be searched when &4OS2. reaches the ":hp2..:ehp2." 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.
:p.
To create a path longer than the command-line length limit, use
PATH repeatedly to append additional directories to the path&colon.
:xmp.
        path [first list of directories]
        path %path;[second list of directories]
        ...
:exmp.:p.
You cannot use this method to extend the path beyond 2042 characters
(the internal buffer limit, with room for "PATH ").  It is usually more efficient to
use aliases to load application programs than to create a long
PATH.  See :link reftype=hd refid=ALIAS.ALIAS:elink. for details.
:p.
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.

.* --------------------------------------------------------------------------

:h2 name=PAUSE.PAUSE - Suspend batch file or alias execution
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Suspend batch file or alias execution.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.PAUSE [:ehp2.:hp3.text:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.text :ehp3.&colon.  The message to be displayed as a user prompt.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
A PAUSE command will suspend execution of a batch file or alias,
giving you the opportunity to change disks, turn on the printer,
etc.
:p.
PAUSE waits for any key to be pressed and then continues execution.
You can specify the :hp1.text:ehp1. that PAUSE displays while it waits for
a keystroke, or let it use the default message&colon.
:xmp.
        Press any key when ready...
:exmp.:p.
For example, the following batch file fragment prompts the user
before erasing files&colon.
:xmp.
        pause Press Ctrl-C to abort, any other key to erase all .LST files
        erase *.lst
:exmp.:p.
If you press :hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2. 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.  In a batch file you can handle :hp2.Ctrl-C:ehp2.
and :hp2.Ctrl-Break:ehp2. yourself with the :link reftype=hd refid=ON.ON:elink. BREAK command.

.* --------------------------------------------------------------------------

:h2 name=POPD.POPD - Restore the disk drive and directory
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Return to the disk drive and directory at
the top of the directory stack..
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.POPD [*]:ehp2.
:eparml.:p.
See also&colon.  :link reftype=hd refid=DIRS.DIRS:elink.,
:link reftype=hd refid=PUSHD.PUSHD:elink., and
:link reftype=hd refid=DirNav.Directory Navigation:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
Directory changes made with POPD are recorded in the directory history
list and can be displayed in the :link reftype=hd refid=DirHist.directory
history window:elink..  See
:link reftype=hd refid=DirNav.Directory Navigation:elink. for complete details
on this and other directory navigation features.
:p.
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&colon.
:xmp.
        [c&colon.\] pushd d&colon.\database\test
        [d&colon.\database\test] pushd c&colon.\wordp\memos
        [c&colon.\wordp\memos] pushd a&colon.\123
        [a&colon.\123] popd
        [c&colon.\wordp\memos] popd
        [d&colon.\database\test] popd
        [c&colon.\]
:exmp.:p.
You can use the DIRS command to see the complete list of saved
drives and directories (the directory stack).
:p.
The POPD command followed by an asterisk [:hp2.*:ehp2.] clears the
directory stack without changing the current drive and directory.
:p.
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.

.* --------------------------------------------------------------------------

:h2 name=PROMPT.PROMPT - Change the command-line prompt
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Change the command-line prompt.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.PROMPT [:ehp2.:hp3.text:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.text :ehp3.&colon.  Text to be used as the new command-line prompt.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
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 :hp1.text:ehp1. can contain special commands in the form
:hp2.$?:ehp2., where :hp2.?:ehp2. is one of the characters listed below&colon.
:lm margin=8.:parml compact tsize=6 break=fit.
:pt.:hp2.b:ehp2.:pd.The vertical bar character [:hp2.&splitvbar.:ehp2.].
:pt.:hp2.c:ehp2.:pd.The open parenthesis [:hp2.(:ehp2.].
:pt.:hp2.d:ehp2.:pd.Current date, in the format&colon.  :hp1.Fri
2-12-97:ehp1. (the month, day, and year are formatted according to your
current country settings).
:pt.:hp2.D:ehp2.:pd.Current date, in the format&colon.  :hp1.Fri  Dec 12,
1997:ehp1..
:pt.:hp2.e:ehp2.:pd.The ASCII ESC character (decimal 27).
:pt.:hp2.f:ehp2.:pd.The close parenthesis [:hp2.):ehp2.].
:pt.:hp2.g:ehp2.:pd.The :hp2.>:ehp2. character.
:pt.:hp2.h:ehp2.:pd.Backspace over the previous character.
:pt.:hp2.i:ehp2.:pd.Display the OS/2 prompt header line, which reminds you
of how to return to the OS/2 desktop, or get help.
:pt.:hp2.l:ehp2.:pd.The :hp2.<:ehp2. character.
:pt.:hp2.m:ehp2.:pd.Time in hours and minutes using 24-hour format&colon.  :hp1.16&colon.07:ehp1.
:pt.:hp2.M:ehp2.:pd.Time in hours and minutes using the default country format and
retaining "a" or "p", :hp1.e.g. 4&colon.07p:ehp1..
:pt.:hp2.n:ehp2.:pd.Current drive letter.
:pt.:hp2.p:ehp2.:pd.Current directory (lower case).
:pt.:hp2.P:ehp2.:pd.Current directory (upper case on FAT drives; directory
names shown in mixed case as stored on the disk on HPFS drives).
:pt.:hp2.q:ehp2.:pd.The :hp2.=:ehp2. character.
:pt.:hp2.r:ehp2.:pd.The numeric exit code of the last external command.
:pt.:hp2.s:ehp2.:pd.The space character.
:pt.:hp2.t:ehp2.:pd.Current 24-hour time, in the format :hp1.hh&colon.mm&colon.ss:ehp1..
:pt.:hp2.T:ehp2.:pd.Current 12-hour time, in the format :hp1.hh&colon.mm&colon.ss[a&splitvbar.p]:ehp1..
:pt.:hp2.v:ehp2.:pd.Operating system version number, in the format :hp1.3.10:ehp1..
:pt.:hp2.xd&colon.:ehp2.:pd.Current directory on drive :hp1.d&colon.:ehp1.,
in lower case, including the drive letter (uses the actual case of the
directory name as stored on the disk for HPFS drives).
:pt.:hp2.Xd&colon.:ehp2.:pd.Current directory on drive :hp1.d&colon.:ehp1.,
in upper case, including the drive letter.
:pt.:hp2.z:ehp2.:pd.Current shell nesting level; the primary command
processor is shell 0.
:pt.:hp2.+:ehp2.:pd.Display one :hp2.+:ehp2. character for each directory
on the PUSHD directory stack.
:pt.:hp2.$:ehp2.:pd.The $ character.
:pt.:hp2._:ehp2.:pd.CR/LF (go to beginning of a new line).
:eparml.:lm margin=1.
.br
For example, to set the prompt to the current date and time, with a
">" at the end&colon.
:xmp.
        [c&colon.\] prompt $D $t $g
        Fri  Jun 6, 1997 10&colon.29&colon.19 >
:exmp.:p.
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&colon.
:xmp.
        [c&colon.\] prompt $d $t$_$P$g
        Fri  Dec 2, 1994 10&colon.29&colon.19
        [c&colon.\]
:exmp.:p.
The &4OS2. prompt can be set in :hp1.CONFIG.SYS:ehp1. (see
below), and the prompt for any command processor can be set in
:link reftype=hd refid=AutoBatch.4START:elink., or in any batch file that
runs when &4OS2. starts.
:p.
The &4OS2. default prompt is :hp2.[$n]:ehp2. (drive name in square brackets)
on floppy drives, and :hp2.[$p]:ehp2. (current drive and directory in
square brackets) on all other drives.  When OS/2 is installed, it
inserts a SET PROMPT statement in :hp1.CONFIG.SYS:ehp1. to set the prompt
to :hp2.$i[$p]:ehp2..  This prompt will override the &4OS2. defaults.  The
:hp2.$i:ehp2. 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 &4OS2. prompt.
:p.
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&colon.
:xmp.
        [c&colon.\] set prompt
:exmp.:p.
(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.)
:p.
Along with literal text, special characters, and ANSI sequences
you can include the text of any :link reftype=hd refid=environment.environment:elink.
variable, :link reftype=hd refid=IntVars.internal variable:elink.,
or :link reftype=hd refid=VarFuncs.variable function:elink. in a
prompt.  For example, if you want to include the size of the largest free
memory block in the command prompt, plus the current drive and directory,
you could use this command&colon.
:xmp.
        [c&colon.\] prompt (%%@dosmem[K]K) $p$g
        (601K) [c&colon.\data]
:exmp.:p.
Notice that the @DOSMEM function is shown with two leading percent
signs [:hp2.%:ehp2.].  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&colon.
:xmp.
        [c&colon.\] prompt `(%@dosmem[K]K) $p$g`
:exmp.:p.
You can use this feature along with the :link reftype=hd
refid=_@EXEC.@EXEC:elink. variable function to create a complex prompt which
not only displays information but executes commands.  For example, to
execute an alias which checks battery status each time the prompt is
displayed (enter the alias on one line)&colon.
:xmp.
        [c&colon.\] alias cbatt `if %_apmlife lt 30 beep 440 4 880 4 440
         4 880 4`
        [c&colon.\] prompt `%@exec[@cbatt]$p$g`
:exmp.:p.
You can include ANSI escape sequences in the PROMPT
:hp1.text:ehp1..  See :link reftype=hd refid=ANSICODES.ANSI Codes:elink. for complete
details on ANSI commands.  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)&colon.
:xmp.
        [c&colon.\] prompt $e[s$e[1;1f$e[41;1;37m$e[K[$z] $d
              Time&colon. $t$h$h$h  Path&colon. $p$e[u$e[0;32m$n$g
:exmp.:p.
A few older batch files use the PROMPT command to transmit
:hp1.ANSI.SYS:ehp1. control sequences to the screen (for example, to redefine
function keys).  This technique will not work with &4OS2., because it
doesn't display a prompt within batch files; hence, the characters in the
PROMPT string are never sent to :hp1.ANSI.SYS:ehp1..  To send ANSI sequences
in &4OS2., use the :link reftype=hd refid=ECHO.ECHO:elink. command,
substituting an :link reftype=hd refid=Escape.escape character:elink.
followed by an :hp2.e:ehp2. for :hp2.$e:ehp2. in the PROMPT string.
:p.
You may find it helpful to define a different prompt in secondary
shells, perhaps including :hp2.$z:ehp2. in the prompt to display the shell
level.  To do so, place a PROMPT command in your :hp1.4START:ehp1. file
and use :link reftype=hd refid=IF.IF:elink. or :link reftype=hd
refid=IFF.IFF:elink. statements to set the appropriate prompt for different
shells.

.* --------------------------------------------------------------------------

:h2 name=PUSHD.PUSHD - Save the disk drive and directory
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Save the current disk drive and directory,
optionally changing to a new drive and directory.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.PUSHD [:ehp2.:hp3.path:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.path :ehp3.&colon.  The name of the new default drive and directory.
:eparml.:p.
See also&colon.  :link reftype=hd refid=CD.CD:elink.,
:link reftype=hd refid=CDD.CDD:elink., :link reftype=hd refid=DIRS.DIRS:elink.,
:link reftype=hd refid=POPD.POPD:elink., and :link reftype=hd refid=DirNav.Directory
Navigation:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
To save the current drive and directory, without changing
directories, use the PUSHD command by itself, with no :hp1.path:ehp1..
:p.
If a :hp1.path:ehp1. 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 :hp1.path:ehp1. includes a
drive letter, PUSHD changes to the specified directory on the new
drive without changing the current directory on the original drive.
:p.
This example saves the current directory and changes to
:hp1.C&colon.\WORDP\MEMOS:ehp1., then returns to the original directory&colon.
:xmp.
        [c&colon.\] pushd \wordp\memos
        [c&colon.\wordp\memos] popd
        [c&colon.\]
:exmp.:p.
When you use PUSHD to change to a directory on an HPFS drive, you
must quote the :hp1.path:ehp1. name if it contains whitespace or special
characters.  See :link reftype=hd refid=FileNames.File Names:elink. for
additional details.
:p.
PUSHD can also change to a network drive and directory specified with a UNC
name (see :link reftype=hd refid=FileSys.File Systems:elink. for a
description of UNC names).
:p.
If PUSHD cannot change to the directory you have specified it will attempt to
search the :link reftype=hd refid=CDPATH.CDPATH:elink. and the
:link reftype=hd refid=ExtDirSearch.extended directory search:elink.
database.  You can also use wildcards in the :hp1.path:ehp1. to force an
extended directory search.  See the :link reftype=hd refid=DirNav.Directory
Navigation:elink. section for complete details on these and other directory
navigation features.
:p.
Directory changes made with PUSHD are also recorded in the
:link reftype=hd refid=DirHist.directory history list:elink. and can be
displayed in the directory history window.
:p.
The directory stack can hold up to 511 characters, or about 20 to
40 entries (depending on the length of the names).  If you exceed
this limit, the oldest entry is removed before adding a new entry.
:p.
The :hp2./N:ehp2. option available in :link reftype=hd
refid=CD.CD:elink. and :link reftype=hd refid=CDD.CDD:elink. to disable
extended directory searches is not available in PUSHD.  To disable
extended searches when using PUSHD, save the current directory with
PUSHD (without parameters) and then use CDD /N to change directories,
for example&colon.
:xmp.
     pushd
     cdd /n testdir
:exmp.

.* --------------------------------------------------------------------------

:h2 name=QUIT.QUIT - Terminate a batch file
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Terminate the current batch file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.QUIT [:ehp2.:hp3.value:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.value :ehp3.&colon.  The numeric exit code to return to &4OS2. or
to the previous batch file.
:eparml.:p.
See also&colon.  :link reftype=hd refid=CANCEL.CANCEL:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
QUIT only ends the current batch file.  To end all batch file
processing, use the CANCEL command.
:p.
If you specify a :hp1.value:ehp1., QUIT will set the ERRORLEVEL or exit
code to that value.  For information on exit codes see the :link reftype=hd
refid=IF.IF:elink. command, and the :link reftype=hd refid=_QMARK.%?:elink.
variable.
:p.
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.

.* --------------------------------------------------------------------------

:h2 name=RD.RD - Remove subdirectories
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Remove one or more subdirectories.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.RD :ehp2.:hp3.path:ehp3. :hp2....:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.RMDIR :ehp2.:hp3.path:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.path :ehp3.&colon.  The name of one or more subdirectories to remove.
:eparml.:p.
See also&colon.  :link reftype=hd refid=MD.MD:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and :link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
RD and RMDIR are synonyms.  You can use either one.
:p.
RD removes directories from the directory tree.  For example, to
remove the subdirectory :hp1.MEMOS:ehp1. from the subdirectory :hp1.WP:ehp1., you
can use this command&colon.
:xmp.
        [c&colon.\] rd \wp\memos
:exmp.:p.
Before using RD, you must delete all files and subdirectories (and
their files) in the :hp1.path:ehp1. 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).
:p.
You can use wildcards in the :hp1.path:ehp1..
:p.
When removing a directory on an HPFS drive, you must quote any :hp1.path:ehp1.
which contains whitespace or special characters.  See :link reftype=hd
refid=FileNames.File Names:elink. for additional details.
:p.
If RD removes one or more directories, they will be deleted automatically
from the :link reftype=hd refid=ExtDirSearch.extended directory search:elink.
database.
:p.
You cannot remove the root directory, the current directory
(:hp2..:ehp2.), any directory above the current directory in the directory
tree, or any directory in use by another process in a multitasking
system.

.* --------------------------------------------------------------------------

:h2 name=REBOOT.REBOOT - Reboot the system
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Do a system reboot.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.REBOOT [/S /V]:ehp2.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./S:ehp2.(hutdown):pd.:hp2./V:ehp2.(erify)
:eparml.:lm margin=1.
.br
:hp2.Usage:ehp2.
:p.
REBOOT will log off or shut down the operating system, or completely restart
your computer.  It normally performs a warm reboot, which is comparable to
pressing Ctrl-Alt-Delete.  A reboot is necessary to activate any changes to
your :hp1.CONFIG.SYS:ehp1. file.
:p.
The following example prompts you to verify the reboot, then does a
warm boot&colon.
:xmp.
        [c&colon.\] reboot /v
:exmp.:p.
REBOOT defaults to performing a warm boot, with no prompting.
:p.
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. issues commands to shut down OS/2
before rebooting.
:p.
REBOOT uses the DOS.SYS device driver to reboot your
system.  DOS.SYS is loaded via a DEVICE= statement in your
:hp1.CONFIG.SYS:ehp1. file.  If DOS.SYS is not loaded, REBOOT will not
work.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./S:ehp2.&colon.:pd.(Shutdown) Shut down the system, but do not
reboot.  This option is equivalent to clicking the "Shutdown" choice on the
Workplace Shell popup menu.
:pt.:hp2./V:ehp2.&colon.:pd.(Verify) Prompt for confirmation (:hp2.Y:ehp2.
or :hp2.N:ehp2.) before rebooting or taking the action specified by other
REBOOT options.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=REM.REM - Put a comment in a batch file
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Put a comment in a batch file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.REM [:ehp2.:hp3.comment:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.comment :ehp3.&colon.  The text to include in the batch file.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
REM must be followed by a space or tab character and then your
comment.  Comments can be up to 1023 characters long.  &4OS2. 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).
:p.
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 [:hp2.@:ehp2.].
:p.
You can also place a comment in a batch file by starting the comment line
with two colons [:hp2.&colon.&colon.:ehp2.].  In essence this creates a
batch file "label" without a valid label name.  Such comments are processed
slightly faster than those entered with REM, because they do not require the
command processor to handle a command.
:p.
You can use REM to create a zero-byte file if you use a redirection
symbol after the REM command.  No text is permitted between
the REM command and the redirection symbol.  For example, to
create the zero-byte file :hp1.C&colon.\FOO:ehp1. &colon.
:xmp.
        [c&colon.\] rem > foo
:exmp.:p.
(This capability is included for compatibility with
:hp1.CMD.EXE:ehp1..  A simpler method for creating a zero-byte file
with &4OS2. is to use :hp2.>filename:ehp2. as a command, with no actual
command before the [:hp2.>:ehp2.] redirection character.)

.* --------------------------------------------------------------------------

:h2 name=REN.REN - Rename files or subdirectories
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Rename files or subdirectories.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.REN [/A&colon.[[-]rhsda] /E /N /P /Q /S
/T]:ehp2. :hp3.old_name:ehp3. :hp2.... :ehp2.:hp3.new_name:ehp3.
:pt.:pd.     or
:pt.:pd.:hp2.RENAME [/A&colon.[[-]rhsda] /E /N /P /Q /S /T]:ehp2.
:hp3.old_name:ehp3. :hp2....:ehp2. :hp3.new_name:ehp3.
.br
:pt.:pd.:hp3.old_name :ehp3.&colon.  Original name of the file(s) or subdirectory.
:pt.:pd.:hp3.new_name :ehp3.&colon.  New name to use, or new path on the same drive.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2. (Attribute select):pd.:hp2./Q:ehp2.(uiet)
:pt.:hp2./E:ehp2. (No error messages):pd.:hp2./S:ehp2.(ubdirectory)
:pt.:hp2./N:ehp2.(othing):pd.:hp2./T:ehp2.(otal)
:pt.:hp2./P:ehp2.(rompt)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=COPY.COPY:elink. and :link reftype=hd refid=MOVE.MOVE:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and :link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
REN and RENAME are synonyms.  You may use either one.
:p.
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.)
:p.
In its simplest form, you give REN the :hp1.old_name:ehp1. of an
existing file or subdirectory and then a :hp1.new_name:ehp1..  The
:hp1.new_name:ehp1. 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 :hp1.MEMO.TXT:ehp1. to :hp1.MEM.TXT:ehp1..  The
second example changes the name of the :hp1.\WORD:ehp1. directory to
:hp1.\WP:ehp1. &colon.
:xmp.
        [c&colon.\] rename memo.txt mem.txt
        [c&colon.\] rename \word \wp
:exmp.:p.
If you use REN to rename a directory, the :link reftype=hd
refid=ExtDirSearch.extended directory search:elink. database will be
automatically updated to reflect the change.
:p.
When you rename files on an HPFS drive, you must quote any file
names which contain whitespace or special characters.  See :link reftype=hd
refid=FileNames.File Names:elink. for additional details.
:p.
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 :hp1.new_name:ehp1. 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 :hp1..SAV:ehp1. &colon.
:xmp.
        [c&colon.\] ren config.sys autoexec.bat 4start.btm *.sav
        [c&colon.\] ren *.txt *.sav
:exmp.:p.
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
:hp1.old_name:ehp1. and a directory name for the :hp1.new_name:ehp1. &colon.
:xmp.
        [c&colon.\] ren memo.txt \wp\memos\
        [c&colon.\] ren oct.dat nov.dat \data\save\
:exmp.:p.
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.
:p.
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
:hp1.new_name:ehp1..  In this example, the files are renamed with an
extension of :hp1..SAV:ehp1. as they are moved to a new directory&colon.
:xmp.
        [c&colon.\] ren *.dat \data\save\*.sav
:exmp.:p.
You cannot rename a subdirectory to a new location on the directory tree.
:p.
REN does not change a file's attributes.  The :hp1.new_name:ehp1. file(s)
will have the same attributes as :hp1.old_name:ehp1..
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A&colon.:ehp2.&colon.:pd.(Attribute select) Select only those
files that have the specified attribute(s) set.  Preceding the attribute
character with a hyphen [:hp2.-:ehp2.] will select files that do not have
that attribute set.  The colon [:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is
required.  The attributes are&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.REN /A&colon. ...:ehp2.), REN will select all
files and subdirectories including hidden and system files.  If
attributes are combined, all the specified attributes must match for a
file to be selected.  For example, /A&colon.RHS will select only those files
with all three attributes set.
:pt.:hp2./E:ehp2.&colon.:pd.(No error messages) Suppress all non-fatal error
messages, such as "File Not Found."  Fatal error messages, such as "Drive
not ready," will still be displayed.  This option is most useful in batch
files.
:pt.:hp2./N:ehp2.&colon.:pd.(Nothing) Do everything except actually rename
the file(s).  This option is useful for testing what a REN command will
actually do.
:pt.:hp2./P:ehp2.&colon.:pd.(Prompt) Prompt the user to confirm each rename
operation.  Your options at the prompt are explained in detail
under :link reftype=hd refid=Prompts.Page and File Prompts:elink..
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) Don't display filenames or the number of
files renamed.  This option is most often used in batch files.  See also
:hp2./T:ehp2..
:pt.:hp2./S:ehp2.&colon.:pd.(Subdirectory) Normally, you can rename a subdirectory
only if you do not use any wildcards in the :hp1.new_name:ehp1..  This
prevents subdirectories from being renamed inadvertently when a group of
files is being renamed with wildcards.  :hp2./S:ehp2. will let you
rename a subdirectory even when you use wildcards.  :hp2./S :ehp2.does
:hp2.not:ehp2. cause REN to process files in the current directory and all
subdirectories as it does in some other file processing commands.  To rename
files throughout a directory tree, use a :link reftype=hd
refid=GLOBAL.GLOBAL:elink. REN.
:pt.:hp2./T:ehp2.&colon.:pd.(Total) Don't display filenames as they are renamed, but
report the number of files renamed.  See also
:hp2./Q:ehp2..
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=RETURN.RETURN - Return from a subroutine in a batch file
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Return from a GOSUB (subroutine) in a batch
file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.RETURN [:ehp2.:hp3.value:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.value :ehp3.&colon.  The exit code from 0 to 255 to return to the
command processor or to the previous batch file.
:eparml.:p.
See also&colon.  :link reftype=hd refid=GOSUB.GOSUB:elink..
:p.
:hp2.Usage:ehp2.
:p.
&4OS2. allows subroutines in batch files.
:p.
A subroutine begins with a label (a colon followed by a word) and
ends with a RETURN command.
:p.
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.  If RETURN is encountered without a
GOSUB, the command processor will display a "Missing GOSUB" error.
:p.
The following batch file fragment calls a subroutine which displays
the files in the current directory&colon.
:xmp.
        echo Calling a subroutine
        gosub subr1
        echo Returned from the subroutine
        quit

        &colon.subr1
        dir /a/w
        return
:exmp.:p.
If you specify a :hp1.value:ehp1., RETURN will set the ERRORLEVEL or exit
code to that value.  For information on exit codes see the :link reftype=hd
refid=IF.IF:elink. command, and the %:link reftype=hd refid=QMARK.?:elink.
variable.

.* --------------------------------------------------------------------------

:h2 name=SCREEN.SCREEN - Position the cursor and display text
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Position the cursor on the screen and optionally
display a message.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SCREEN :ehp2.:hp3.row column:ehp3.
:hp2.[:ehp2.:hp3.text:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.row :ehp3.&colon.  The new row location for the cursor.
:pt.:pd.:hp3.column :ehp3.&colon.  The new column location for the cursor.
:pt.:pd.:hp3.text :ehp3.&colon.  Optional text to display at the new cursor location.
:eparml.:p.
See also&colon.  :link reftype=hd refid=ECHO.ECHO:elink., :link reftype=hd refid=SCRPUT.SCRPUT:elink., :link reftype=hd refid=TEXT.TEXT:elink., and
:link reftype=hd refid=VSCRPUT.VSCRPUT:elink..
:p.
:hp2.Usage:ehp2.
:p.
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 menus and other similar displays.  The
following batch file fragment displays a menu&colon.
:xmp.
        @echo off
        cls
        screen 3 10  Select a number from 1 to 4&colon.
        screen 6 20  1 - Word Processing
        screen 7 20  2 - Spreadsheet
        screen 8 20  3 - Telecommunications
        screen 9 20  4 - Quit
:exmp.:p.
SCREEN does not change the screen colors.  To display text in specific
colors, use SCRPUT or VSCRPUT.  SCREEN always leaves the cursor at the
end of the displayed text.
:p.
The :hp1.row:ehp1. and :hp1.column:ehp1. values are zero-based, so on a standard
25 line by 80 column display, valid :hp1.rows:ehp1. are 0 - 24 and valid
:hp1.columns:ehp1. are 0 - 79.  You can also specify the :hp1.row:ehp1. and
:hp1.column:ehp1. as offsets from the current cursor position.  Begin the
value with a plus sign [:hp2.+:ehp2.] to move the cursor down the
specified number of rows or to the right the specified number of
columns, or with a minus sign [:hp2.-:ehp2.] to move the cursor up or to
the left.  This example prints a string 3 lines above the current
position, in absolute column 10&colon.
:xmp.
        screen -3 10 Hello, World!
:exmp.:p.
If you specify 999 for the :hp1.row:ehp1., SCREEN will center the text
vertically on the display.  If you specify 999 for the :hp1.column:ehp1.,
SCREEN will center the text horizontally.  This example prints a message at
the center of the display&colon.
:xmp.
        screen 999 999 Hello, World
:exmp.:p.
SCREEN checks for a valid :hp1.row:ehp1. and :hp1.column:ehp1., and displays a
"Usage" error message if either value is out of range.

.* --------------------------------------------------------------------------

:h2 name=SCRPUT.SCRPUT - Display text in color
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Position text on the screen and display it in color.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SCRPUT :ehp2.:hp3.row col:ehp3.
:hp2.[BRIght] [BLInk]:ehp2. :hp3.fg:ehp3. :hp2.ON
[BRIght] :ehp2.:hp3.bg text:ehp3.
.br
:pt.:pd.:hp3.row :ehp3.&colon.  Starting row
:pt.:pd.:hp3.col :ehp3.&colon.  Starting column
:pt.:pd.:hp3.fg :ehp3.&colon.  Foreground character color
:pt.:pd.:hp3.bg :ehp3.&colon.  Background character color
:pt.:pd.:hp3.text :ehp3.&colon.  The text to display
:eparml.:p.
See also&colon.  :link reftype=hd refid=ECHO.ECHO:elink., :link reftype=hd
refid=SCREEN.SCREEN:elink., :link reftype=hd refid=TEXT.TEXT:elink., and
:link reftype=hd refid=VSCRPUT.VSCRPUT:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
SCRPUT works like SCREEN, but requires you to specify the display
colors.  See :link reftype=hd refid=Colors.Colors and Color Names:elink. for
details about colors and notes on the use of bright background colors.
:p.
The :hp1.row:ehp1. and :hp1.column:ehp1. are zero-based, so on a standard 25
line by 80 column display, valid rows are 0 - 24 and valid columns are 0
- 79.  SCRPUT checks for a valid :hp1.row:ehp1. and :hp1.column:ehp1., and
displays a "Usage" error message if either value is out of range.
:p.
You can also specify the :hp1.row:ehp1. and :hp1.column:ehp1. as
offsets from the current cursor position.  Begin the value with a plus sign
[:hp2.+:ehp2.] to move down the specified number of rows or to the right
the specified number of columns, or with a minus sign [:hp2.-:ehp2.] to
move up or to the left.
:p.
If you specify 999 for the :hp1.row:ehp1., SCRPUT will center the text
vertically on the display.  If you specify 999 for the :hp1.column:ehp1.,
SCRPUT will center the text horizontally.
:p.
SCRPUT does not move the cursor when it displays the text.
:p.
The following batch file fragment displays part of a menu, in color&colon.
:xmp.
        cls white on blue
        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
:exmp.

.* --------------------------------------------------------------------------

:h2 name=SELECT.SELECT - Select files for a command
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Interactively select files for a command.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SELECT [/A[[&colon.][-][rhsda]] /D /E /H
/I"text" /J /L /O[&colon.][-]adeginrsu /T&colon.acw /Z]
[:ehp2.:hp3.command:ehp3.:hp2. ] ... (:ehp2.:hp3.files:ehp3.
:hp2....)...:ehp2.
.br
:pt.:pd.:hp3.command :ehp3.&colon.  The command to execute with the selected
files.
:pt.:pd.:hp3.files :ehp3.&colon.  The files from which to select.  File
names may be enclosed in either parentheses or square brackets.  The
difference is explained below.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A:ehp2.(ttribute select):pd.:hp2./J:ehp2.(ustify names)
:pt.:hp2./D:ehp2.(isable color coding):pd.:hp2./L:ehp2.(ower case)
:pt.:hp2./E:ehp2. (use upper case):pd.:hp2./O:ehp2.(rder)
:pt.:hp2./H:ehp2.(ide dots):pd.:hp2./T:ehp2.(ime)
:pt.:hp2./I:ehp2. (match descriptions):pd.:hp2./Z:ehp2. (use FAT format)
:eparml.:lm margin=1.
.br
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link
reftype=hd refid=ranges.ranges:elink., :link reftype=hd
refid=MultFiles.multiple file names:elink., and :link reftype=hd
refid=InclList.include lists:elink..  Ranges :hp2.must:ehp2. appear
immediately after the SELECT keyword.
:p.
:hp2.Usage:ehp2.
:p.
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
:hp1.command:ehp1. can be an internal command, an alias, an external
command, or a batch file.
:p.
If you use parentheses around the :hp1.files:ehp1., SELECT executes the
:hp1.command:ehp1. once for each file you have selected.  During each
execution, one of the selected files is passed to the :hp1.command:ehp1.
as an argument.  If you use square brackets around :hp1.files:ehp1., the
SELECTed files are combined into a single list, separated by
spaces.  The command is then executed once with the entire list
presented as part of its command-line arguments.
:p.
:hp2.Using the SELECT File List:ehp2.
:p.
When you execute the SELECT command, the file list is displayed in a
full-screen format which includes a top-line status bar and shows the command
to be executed, the number of files marked, and the number of Kbytes in those
files.
:p.
SELECT uses the cursor up, cursor down, PgUp, and PgDn keys to scroll through
the file list.  You can also use character matching to find specific files,
just as you can in any :link reftype=hd
refid=PopUp.popup window:elink..  While the file list is displayed you can
enter any of the following keys to select or unselect files, display files,
execute the command, or exit&colon.
:parml compact tsize=25 break=none.
:pt.:hp2.+:ehp2. or :hp2.space:ehp2.:pd.Select a file, or unselect a marked file.
:pt.:hp2.-:ehp2.:pd.Unselect a marked file.
:pt.:hp2.*:ehp2.:pd.Reverse all of the current marks (except those on
subdirectories).  If no files have been marked you can use :hp2.* :ehp2. to
mark all of the files.
:pt.:hp2./:ehp2.:pd.Unselect all files.
:pt.:hp2.Ctrl-L:ehp2.:pd.View the current highlighted file with
:link reftype=hd refid=LIST.LIST:elink.  When you exit from LIST, the SELECT
screen will be restored.
:pt.:hp2.Enter:ehp2.:pd.Execute the command with the marked files, or with
the currently highlighted file if no files have been marked.
:pt.:hp2.Esc:ehp2.:pd.Skip the files in the current display and go on to the
next file specification inside the parentheses or brackets (if any).
:pt.:hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2.:pd.Cancel the current SELECT
command entirely.
:eparml.
.br
On FAT drives the file list is shown in standard FAT directory format, with
names at the left an descriptions at the right.  On HPFS drives
the format is similar but more space is allowed for the name, and the
description is not shown.  In this format long names are truncated if they do
not fit in the allowable space.  For a short-name format (including
descriptions) on long filename drives, use the :hp2./Z:ehp2. switch.
:p.
When displaying descriptions in the short filename format, SELECT adds a
right arrow [:hp2.:ehp2.] at the end of the line if the description is too
long to fit on the screen.  This symbol will alert you to the existence of
additional description text.  You can use the left and right arrow keys to
scroll the description area of the screen horizontally and view the
additional text.
:p.
You can display the filenames in color by using the SET command to create an
environment variable called :link reftype=hd refid=COLORDIR_Var.COLORDIR:elink.,
or using the Commands page of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs or a text
editor to set the :link reftype=hd refid=INI_ColorDir.ColorDir:elink.
directive in your :hp1.&4OS2INI.:ehp1. file.  If you do not use the COLORDIR
variable or the ColorDir directive, SELECT will use the default screen
colors for all files.  See the discussion of color-coded directories under
:link reftype=hd refid=DIR.DIR:elink. for more details.  To disable
directory color coding within SELECT, use the :hp2./D:ehp2. option.
:p.
You can set the default colors used by SELECT on the Commands page of the
OPTION dialogs or with the
:link reftype=hd refid=INI_SelectColors.SelectColors:elink. and
:link reftype=hd refid=INI_SelectStatBarColors.SelectStatBarColors:elink.
directives in the :hp1..INI:ehp1. file.  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 colors.
:p.
:hp2.Creating SELECT Commands:ehp2.
:p.
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&colon.
:xmp.
        [c&colon.\] select copy (*.com *.exe) a&colon.\
:exmp.:p.
will let you select from among the :hp1..COM:ehp1. files on the current
drive and will then invoke the COPY command to copy each file you select to
drive A&colon..  After the :hp1..COM:ehp1. files are done, the operations
will be repeated for the :hp1..EXE:ehp1. files.
:p.
If you want to select from a list of all the :hp1..COM:ehp1. and
:hp1..EXE:ehp1. files mixed together, create an :link reftype=hd
refid=InclList.include list:elink. inside the parentheses by inserting a
semicolon&colon.
:xmp.
        [c&colon.\] select copy (*.com;*.exe) a&colon.\
:exmp.:p.
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&colon.
:xmp.
        [c&colon.\] select copy [*.com;*.exe] a&colon.\
:exmp.:p.
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) does not exceed the command line length limit of 1,023
characters.  The current line length is displayed by SELECT while you are
marking files to help you to conform to this limit.
:p.
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.
:p.
When you use SELECT on an HPFS drive, you must quote any file names inside
the parentheses which contain whitespace or special characters.  See :link
reftype=hd refid=FileNames.File Names:elink. for additional details.  For
example, to copy selected files from the :hp1."Program Files":ehp1.
directory to the :hp1.E&colon.\SAVE:ehp1. directory&colon.
:xmp.
        [c&colon.\] select copy ("Program Files\*.*") e&colon.\save\
:exmp.:p.
File names passed to the :hp1.command:ehp1. will be quoted automatically if
they contain whitespace or special characters.
:p.
The list of files from which you wish to select can be further refined by
using :link reftype=hd refid=Ranges.date, time, size:elink., and :link
reftype=hd refid=ExclRanges.file exclusion:elink. ranges.  The range(s) must
be placed immediately after the word SELECT.  If the :hp1.command:ehp1. is
an internal command that supports ranges, an independent range can also be
used in the :hp1.command:ehp1. itself.
:p.
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 :hp2.can:ehp2. use a SELECT command :hp2.inside:ehp2. command
grouping parentheses, you just can't use command grouping to specify a group
of commands for SELECT to execute.)
:p.
:hp2.Advanced Topics:ehp2.
:p.
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 :hp1.C&colon.\UTIL:ehp1., and then executes them in the order
marked&colon.
:xmp.
        [c&colon.\] alias utils select (c&colon.\util\*.com;*.exe;*.btm;*.bat)
:exmp.:p.
If you want to use :link reftype=hd refid=FileComp.filename completion:elink. 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.
:p.
With the :hp2./I:ehp2. option, you can select files based on their
descriptions.  SELECT will display files if their description
matches the text after the :hp2./I:ehp2. switch.  The search is not case
sensitive.  You can use wildcards and extended wildcards as part
of the text.
:p.
When sorting file names and extensions for the SELECT display, &4OS2.
normally assumes 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 :hp2./O&colon.a:ehp2. option.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(Attribute select) Select only those files that have the
specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute set.  The colon
[:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is optional.  The attributes
are&colon.
.br
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
.br
:pt.:pd.If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.SELECT /A ...:ehp2.), 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, :hp2./A&colon.RHS:ehp2. will display
only those files with all three attributes set.
.br
:pt.:hp2./D:ehp2.&colon.:pd.(Disable color coding) Temporarily turn off directory color
coding within SELECT.
.br
:pt.:hp2./E:ehp2.:pd.(use upper case) Display filenames upper case; also
see :link reftype=hd refid=SETDOS.SETDOS:elink. /U
and the :link reftype=hd refid=INI_UpperCase.UpperCase :elink. directive in
:hp1.&4OS2INI.:ehp1..
.br
:pt.:hp2./H:ehp2.:pd.(Hide dots) Suppress the display of the "." and ".."
directories.
.br
:pt.:hp2./I:ehp2.:pd.(match descriptions) Display filenames by matching text in
their descriptions.  The text can include wildcards and extended
wildcards.  The search text must be enclosed in quotation marks.  You can
select all filenames that have a description with :hp2./I"[?]*",:ehp2. or
all filenames that do not have a description with :hp2./I"[]":ehp2..
.br
:pt.:hp2./J:ehp2.:pd.(Justify names) Justify (align) filename extensions and
display them in the traditional format.
.br
:pt.:hp2./L:ehp2.:pd.(Lower case) Display file and directory names in lower
case; also see :link reftype=hd refid=SETDOS.SETDOS:elink. /U and the
:link reftype=hd refid=INI_UpperCase.UpperCase:elink. directive in
:hp1.&4OS2INI.:ehp1..
.br
:pt.:hp2./O:ehp2.&colon.:pd.(Order) Set the sort order for the files.  The
order can be any combination of the following options&colon.
.br
:pt.:pd.:hp2.    -:ehp2.  Reverse the sort order for the next option.
:pt.:pd.:hp2.    a:ehp2.  Sort in ASCII order, not numerically, when there are digits in the name.
:pt.:pd.:hp2.    d:ehp2.  Sort by date and time (oldest first); for HPFS drives also see :hp2./T:ehp2..
:pt.:pd.:hp2.    e:ehp2.  Sort by extension.
:pt.:pd.:hp2.    g:ehp2.  Group subdirectories first, then files.
:pt.:pd.:hp2.    i:ehp2.  Sort by file description.
:pt.:pd.:hp2.    n:ehp2.  Sort by filename (this is the default).
:pt.:pd.:hp2.    r:ehp2.  Reverse the sort order for all options.
:pt.:pd.:hp2.    s:ehp2.  Sort by size.
:pt.:pd.:hp2.    u:ehp2.  Unsorted.
.br
:pt.:hp2./T:ehp2.&colon.:pd.(Time display) Specify which of the date and
time fields on an HPFS drive should be displayed and used for sorting&colon.
.br
:pt.:pd.:hp2.    a:ehp2.  last access date and time
:pt.:pd.:hp2.    c:ehp2.  creation date and time
:pt.:pd.:hp2.    w:ehp2.  last write date and time (default)
.br
:pt.:hp2./Z:ehp2.&colon.:pd.Display HPFS filenames in the traditional FAT
format, with the filename at the left and the description at the right.
Long names will be truncated to 12 characters; if the name is longer than 12
characters, it will be followed by a right arrow [:hp2.:ehp2.] to show that one or more
characters have been truncated.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=SET.SET - Create or modify environment variables
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display, create, modify, or delete
environment variables.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SET [/P /R:ehp2. :hp3.file:ehp3.
:hp2....] [:ehp2.:hp3.name:ehp3. :hp2.[=][:ehp2.:hp3.value:ehp3. :hp2.]]:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  One or more files containing variable
definitions.
:pt.:pd.:hp3.name :ehp3.&colon.  The name of the environment variable to
define or modify.
:pt.:pd.:hp3.value :ehp3.&colon.  The new value for the variable.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./P:ehp2.(ause):pd.:hp2./R:ehp2.(ead from file)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=ESET.ESET:elink. and
:link reftype=hd refid=UNSET.UNSET:elink..
:p.
:hp2.Usage:ehp2.
:p.
Every program and command inherits an :link reftype=hd refid=Environment.environment:elink.,
which is a list of variable :hp1.names:ehp1., each of which is followed by
an equal sign and some text.  Many programs use entries in the
environment to modify their own actions.
:p.
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&colon.
:xmp.
        [c&colon.\] set
        COMSPEC=C&colon.\&4OS2.\$OS2.EXE
        PATH=C&colon.\;C&colon.\OS2;C&colon.\OS2\SYSTEM;C&colon.\UTIL
        CMDLINE=C&colon.\&4OS2.\4START.CMD
:exmp.:p.
To add a variable to the environment, type SET, a space, the
variable name, an equal sign, and the text&colon.
:xmp.
        [c&colon.\] set mine=c&colon.\finance\myfiles
:exmp.:p.
The variable name is converted to upper case by &4OS2..  The text after the
equal sign will be left just as you entered it.  If the variable already
exists, its value will be replaced with the new text that you entered.
:p.
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
:hp1.name:ehp1. ; a space after the equal sign will become part of the
:hp1.value:ehp1..
:p.
If you use SET to create a variable with the same name as one of
the &4OS2. :link reftype=hd refid=IntVars.internal variables:elink., 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.
:p.
To display the contents of a single variable, type SET plus the
variable name&colon.
:xmp.
        [c&colon.\] set mine
:exmp.:p.
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&colon.
:xmp.
        [c&colon.\] set mine=
:exmp.:p.
The variable :hp1.name:ehp1. is limited to a maximum of 80 characters.
The name and :hp1.value:ehp1. together cannot be longer than 1,023 characters.
:p.
In &4OS2. the size of the environment is set automatically, and
increased as necessary as you add variables.
:p.
&4OS2. supports the "pseudo-variables" :hp2.BeginLIBPath:ehp2. and
:hp2.EndLIBPath:ehp2. introduced in OS/2 Warp.  If you use either of these
as a variable name, &4OS2. will pass the library path information from the SET
command to the operating system, but the variables will not appear in the
environment.  See your OS/2 documentation for more information about these
"variables".
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./P:ehp2.&colon.:pd.(Pause) Wait for a key to be pressed after each
screen page before continuing the display.  Your options at the prompt are
explained in detail under :link reftype=hd refid=Prompts.Page and File
Prompts:elink..
:pt.:hp2./R:ehp2.&colon.:pd.(Read) 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
1,023-byte command-line length limit for &4OS2..  The file is in the same
format as the SET display (:hp1.i.e.:ehp1., :hp3.name:ehp3.
=:hp3.value:ehp3. ), 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&colon.
:xmp.
        set > varlist
        set /r varlist
:exmp.:p.
You can load variables from multiple files by listing the filenames
individually after the :hp2./R:ehp2..  You can add comments to a variable
file by starting the comment line with a colon [:hp2.&colon.:ehp2.].
:p.
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 :link reftype=hd refid=Escape.escape
character:elink..  However, you cannot use this method to exceed the
command-line length limit.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=SETDOS.SETDOS - Set the &4OS2. configuration
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display or set the &4OS2. configuration.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SETDOS [/A? /B? /C? /D? /E? /Fn.n /G??
/I+&splitvbar.-:ehp2. :hp3.command:ehp3. :hp2./L? /M? /N? /P? /R? /S?&colon.?
/U? /V? /X[+&splitvbar.-]n /Y?]:ehp2.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./B:ehp2.(right background):pd.:hp2./N:ehp2.(o clobber)
:pt.:hp2./C:ehp2.(ompound):pd.:hp2./P:ehp2.(arameter character)
:pt.:hp2./D:ehp2.(escriptions):pd.:hp2./R:ehp2.(ows)
:pt.:hp2./E:ehp2.(scape character):pd.:hp2./S:ehp2.(hape of cursor)
:pt.:hp2./F:ehp2.(ormat for @EVAL):pd.:hp2./U:ehp2.(pper case)
:pt.:hp2./G:ehp2. (numeric separators):pd.:hp2./V:ehp2.(erbose)
:pt.:hp2./I:ehp2.(nternal commands):pd.:hp2./X:ehp2. (expansion, special characters)
:pt.:hp2./L:ehp2.(ine):pd.:hp2./Y:ehp2. (debug batch file)
:pt.:hp2./M:ehp2.(ode for editing):pd.
:eparml.:lm margin=1.
.br
:hp2.Usage:ehp2.
:p.
SETDOS allows you to customize certain aspects of &4OS2. to suit your
personal tastes or the configuration of your system.  Each of these
options is described below.
:p.
You can display the value of all SETDOS options by entering the
SETDOS command with no parameters.
:p.
Most of the SETDOS options can be initialized when &4OS2. executes
the :link reftype=hd refid=INIConfig.configuration directives:elink. in
:hp1.&4OS2INI.:ehp1., and can also be set on the Command Line 1, Command
Line 2, Options 1, or Options 2 pages of the :link reftype=hd
refid=OPTION.OPTION:elink. dialogs.  The name of the corresponding directive
is listed with each option below; if none is listed, that option cannot be
set with OPTION or from the :hp1..INI:ehp1. file.  You can also define the
SETDOS options in your :hp1.AUTOEXEC.BAT:ehp1., :hp1.4START:ehp1., or other
startup file (see :link reftype=hd refid=AutoBatch.Automatic Batch
Files:elink.), in aliases, or at the command line.
:p.
Secondary shells automatically inherit most configuration settings
currently in effect in the previous shell.  If values have been
changed by SETDOS since &4OS2. started, the new values will be passed
to the secondary shell.
:p.
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 :hp1.4START:ehp1. file, which is executed when
any shell starts.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2./B:ehp2.&colon.:pd.(Bright background) This option determines
whether &4OS2. configures your video adapter for blinking text
(:hp2./B0:ehp2., the default) or bright background colors (:hp2./B1:ehp2.),
or leave the video bright / blink configuration unchanged
(:hp2./B2:ehp2.).  See :link reftype=hd refid=Colors.Colors and Color
Names:elink. for a detailed discussion of this option.  Also see the
:link reftype=hd refid=INI_BrightBG.BrightBG:elink. directive.
.br
:pt.:hp2./C:ehp2.&colon.:pd.(Compound character) This option sets the
character used for separating multiple commands on
the same line.  The default is the ampersand [:hp2.&amp.:ehp2.].  You cannot
use any of the redirection characters (:hp2.&splitvbar.
> <:ehp2.), or the blank, tab, comma, or equal sign as the command
separator.  The command separator is saved by :link reftype=hd
refid=SETLOCAL.SETLOCAL:elink. and restored by :link reftype=hd
refid=ENDLOCAL.ENDLOCAL:elink..  This example changes the separator
to a tilde [:hp2.~:ehp2.]&colon.
:xmp.
        [c&colon.\] setdos /c~
:exmp.:p.
If you want to share batch files or aliases among 4DOS, &4OS2., 4NT, and
Take Command, see the :link reftype=hd refid=PLUS.%+:elink. variable, which
retrieves the current command separator, and :link reftype=hd
refid=Compat.Special Character Compatibility:elink. for
details on using compatible command separators for all the products
you use.  Also see the :link reftype=hd
refid=INI_CommandSep.CommandSep:elink. directive.
.br
:pt.:hp2./D:ehp2.&colon.:pd.(Descriptions) This option controls whether
file processing commands like :link reftype=hd refid=COPY.COPY:elink.,
:link reftype=hd refid=DEL.DEL:elink., :link reftype=hd
refid=MOVE.MOVE:elink., and :link reftype=hd refid=REN.REN:elink.
process file descriptions along with the files they
belong to.  :hp2./D1:ehp2. turns description processing on,
which is the default.  :hp2./D0:ehp2. turns description
processing off.  Also see the :link reftype=hd
refid=INI_Descriptions.Descriptions:elink. directive.
:p.
You can also use :hp2./D:ehp2. to set the name of the hidden file in each
directory that contains file descriptions.  To do so, follow :hp2./D:ehp2.
with the filename in quotes&colon.
:xmp.
        [c&colon.\] setdos /d"files.bbs"
:exmp.:p.
:hp8.Use this option with caution:ehp8. because changing the name
of the description file will make it difficult to transfer file descriptions
to another system.  This option is provided for bulletin board system
operators and others who have special needs.
:p.
Also see the :link reftype=hd
refid=INI_DescriptionName.DescriptionName:elink. directive.
.br
:pt.:hp2./E:ehp2.&colon.:pd.(Escape character) This option sets the
character used to suppress the normal meaning of the following
character.  Any character following the :link reftype=hd refid=Escape.escape
character:elink. will be passed unmodified to the command.  The default
escape character is a caret [:hp2.^:ehp2.].  You cannot use any of the
redirection characters (:hp2.&splitvbar. > <:ehp2.) or the blank, tab,
comma, or equal sign as the escape character.  The escape character is saved
by :link reftype=hd refid=SETLOCAL.SETLOCAL:elink. and restored by
:link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink..  Certain characters
(:hp2.b:ehp2., :hp2.c:ehp2., :hp2.e:ehp2., :hp2.f:ehp2., :hp2.k:ehp2.,
:hp2.n:ehp2., :hp2.q:ehp2., :hp2.r:ehp2., :hp2.s:ehp2., and :hp2.t:ehp2.)
have special meanings when immediately preceded by the escape character.
:p.
If you want to share batch files or aliases among 4DOS, &4OS2., 4NT, and
Take Command, see the :link reftype=hd refid=EQUALS.%=:elink. variable, which
retrieves the current escape character, and :link reftype=hd
refid=Compat.Special Character Compatibility:elink. for details on using
compatible escape characters for all the products you use.  Also see the
:link reftype=hd refid=INI_EscapeChar.EscapeChar:elink. directive.
.br
:pt.:hp2./F:ehp2.&colon.:pd.(Format for @EVAL) This option lets
you set default decimal precision for the :link reftype=hd refid=_@EVAL.@EVAL:elink. variable
function. The maximum precision is 16 digits to the left of the decimal
point and 8 digits to the right of the decimal point.

The general form of this option is :hp2./Fx.y:ehp2., where :hp2.x:ehp2. sets
the minimum number of digits to the right of the decimal place and
:hp2.y:ehp2. sets the maximum number of digits.  You can use :hp2.=x,y:ehp2.
instead of :hp2.=x.y:ehp2. if the comma is your decimal separator.  Both
values can range from 0 to 8; if :hp2.x:ehp2. is greater than :hp2.y:ehp2.,
it is ignored.  You can specify either or both values:  /F2.5, /F2, and /F.5
are all valid entries.
:p.
See :link reftype=hd refid=_@EVAL.@EVAL:elink. if you want to set the
precision for a single computation.
:p.
Also see the :link reftype=hd refid=INI_EvalMax.EvalMax:elink. and
:link reftype=hd refid=INI_EvalMin.EvalMin:elink. directives.
.br
:pt.:hp2./G:ehp2.&colon.:pd.(Numeric separators) This option sets the
decimal and thousands separator characters.  The format is :hp2./Gxy
:ehp2.where :hp2.x:ehp2. is the new decimal separator and :hp2.y:ehp2. is
the new thousands separator.  Both characters must be included.  The only
valid settings are :hp2./G.,:ehp2. (period is the decimal separator, comma
is the thousands separator); :hp2./G,.:ehp2. (the reverse); or
:hp2./G0:ehp2. to remove any custom setting and use the default separators
associated with your current country code (this is the default).
:p.
The decimal separator is used for :link reftype=hd
refid=_@EVAL.@EVAL:elink., numeric :link reftype=hd refid=IF.IF:elink. and
:link reftype=hd refid=IFF.IFF:elink. tests, version numbers, and other
similar uses.  The thousands separator is used for numeric output, and is
skipped when performing calculations in @EVAL.
.br
:pt.:hp2./I:ehp2.&colon.:pd.(Internal) This option allows you to disable or
enable internal commands.  To disable a command, precede the command name
with a minus [:hp2.-:ehp2.].  To re-enable a command, precede it with a plus
[:hp2.+:ehp2.].  For example, to disable the internal LIST command to force
&4OS2. to use an external command&colon.
:xmp.
        [c&colon.\] setdos /i-list
:exmp.
.br
:pt.:hp2./L:ehp2.&colon.:pd.(Line) This option controls how &4OS2. gets its
input from the command line.  :hp2./L0:ehp2. tells &4OS2. to
use character input (the default).  :hp2./L1:ehp2. tells it
to use line input (like :hp1.CMD.EXE:ehp1. ).  :hp2./L1:ehp2. 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&colon.
:xmp.
        setdos /L1 &amp. program %&amp. &amp. setdos /L0
:exmp.:p.
See :hp1.README.DOC:ehp1. for information on programs which require
this option.  Also see the
:link reftype=hd refid=INI_LineInput.LineInput:elink. directive.
.br
:pt.:hp2./M:ehp2.&colon.:pd.(Mode) This option controls the initial line
editing mode.  To start in overstrike mode at the beginning of each command
line, use :hp2./M0:ehp2. (the default).  To start in insert mode, use
:hp2./M1:ehp2..  Also see the :link reftype=hd
refid=INI_EditMode.EditMode:elink. directive.
.br
:pt.:hp2./N:ehp2.&colon.:pd.(No clobber) This option controls output
:link reftype=hd refid=Redirection.redirection:elink.).  :hp2./N0:ehp2. means
existing files will be overwritten by output redirection
(with :hp2.>:ehp2.) and that appending (with :hp2.>>:ehp2.) does not require
the file to exist already.  This is the default.  :hp2./N1:ehp2. means
existing files may not be overwritten by output redirection, and that when
appending the output file must exist.  A :hp2./N1:ehp2. setting can be
overridden with the [:hp2.!:ehp2.] character.  If you use :hp2./N1:ehp2.,
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.  Also see the :link reftype=hd
refid=INI_NoClobber.NoClobber:elink. directive.
.br
:pt.:hp2./P:ehp2.&colon.:pd.(Parameter character) This option sets the
character used after a percent sign to specify all or all remaining
command-line arguments in a :link reftype=hd refid=Batch.batch file:elink. or
:link reftype=hd refid=ALIAS.alias:elink. (:hp1.e.g.:ehp1.,
:hp2.%&amp.:ehp2. or :hp2.%n&amp.:ehp2..  The default is the dollar sign
[:hp2.$:ehp2.].  The parameter character is saved by :link reftype=hd
refid=SETLOCAL.SETLOCAL:elink. and restored by :link reftype=hd
refid=ENDLOCAL.ENDLOCAL:elink..
:p.
If you want to share batch files or aliases among 4DOS, &4OS2., 4NT, and
Take Command, see :link reftype=hd refid=Compat.Special Character
Compatibility:elink. for details on selecting compatible parameter
characters for all the products you use.  Also see the
:link reftype=hd refid=INI_ParameterChar.ParameterChar:elink. directive.
.br
:pt.:hp2./R:ehp2.&colon.:pd.(Rows) This option sets the number of screen
rows used by the video display.  Normally &4OS2. detects 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 (which is controlled by your video
driver).  It also does not :hp2.set:ehp2. the screen size; it is used only
to specify the screen height for :link reftype=hd refid=LIST.LIST:elink.,
:link reftype=hd refid=SELECT.SELECT:elink., paged output options
(:hp1.i.e.:ehp1., :link reftype=hd refid=TYPE.TYPE:elink. /P), and error
checking in the screen output commands.  Also see
the :link reftype=hd refid=INI_ScreenRows.ScreenRows:elink. directive.
.br
:pt.:hp2./S:ehp2.&colon.:pd.(Shape) This option sets the cursor shape.  The
format is :hp2./So&colon.i:ehp2. where :hp2.o:ehp2. is the cursor size
for overstrike mode and :hp2.i:ehp2. is the cursor size for insert mode.  The
size is entered as a percentage of the total character height.  The default
values are 10&colon.100 (a 10% underscore cursor for overstrike mode,
and a 100% block cursor for insert mode).  Because of the way video drivers
remap the cursor shape, you may not get a smooth progression in the cursor
size from 0% - 100%.  To disable the cursor, enter
:hp2./S0&colon.0:ehp2..
:p.
If either value is -1, &4OS2. will not attempt to modify the cursor shape at
all.  You can use this feature to give another program full control of the
cursor shape.  You can retrieve the current cursor shape values with the
:link reftype=hd refid=_CI.%_CI:elink. and :link reftype=hd
refid=_CO.%_CO:elink. internal variables.
:p.
Also see the :link reftype=hd refid=INI_CursorOver.CursorOver:elink. and
:link reftype=hd refid=INI_CursorIns.CursorIns:elink. directives.
.br
:pt.:hp2./U:ehp2.&colon.:pd.(Upper) This option controls the default case
(upper or lower) for file and directory names displayed by internal commands
like COPY and DIR.  :hp2./U0:ehp2. displays file names in lower case (the
default).  :hp2./U1:ehp2. displays file names in the traditional upper
case.  The :hp2./U:ehp2. setting is ignored for HPFS filenames.  HPFS names
are always displayed in the case in which they are stored.
:p.
Also see the :link reftype=hd refid=INI_UpperCase.UpperCase:elink. directive.
.br
:pt.:hp2./V:ehp2.&colon.:pd.(Verbose) This option controls the default for
command echoing in batch files.  :hp2./V0:ehp2. disables echoing of batch
file commands unless :link reftype=hd refid=ECHO.ECHO:elink. is explicitly
set ON.  :hp2./V1:ehp2., the default setting, enables echoing of batch file
commands unless ECHO is explicitly set OFF.  Also see the :link reftype=hd
refid=BatchEcho.BatchEcho:elink. directive.
:p.
:hp2./V2:ehp2. 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.  :hp2./V2:ehp2. is intended for debugging, and can be
set with SETDOS, but not with the :link reftype=hd
refid=OPTION.OPTION:elink. command or the BatchEcho directive in :hp1.&4OS2INI.:ehp1..
:p.
For more information on batch file debugging see :link reftype=hd
refid=BatchDebug.Debugging Batch Files:elink. and :hp2./Y:ehp2. below.
.br
:pt.:hp2./X[+&splitvbar.-]n:ehp2.&colon.:pd.(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.
:p.
The features enabled or disabled by :hp2./X:ehp2. are numbered.  All
features are enabled when &4OS2. starts, and you can re-enable all features at
any time by using :hp2./X0:ehp2..  To disable a particular feature, use
:hp2./X-n:ehp2., where :hp2.n:ehp2. is the feature number from the list
below.  To re-enable the feature, use :hp2./X+n:ehp2..  To enable or disable
multiple individual features, list their numbers in sequence after the
:hp2.+:ehp2. or :hp2.-:ehp2. (:hp1.e.g.:ehp1. :hp2./X-345:ehp2. to disable
features 3, 4, and 5).
:p.
The features are&colon.
.br
:lm margin=8.:parml compact tsize=8 break=fit.
:pt.    1:pd.All alias expansion.
:pt.    2:pd.Nested alias expansion only.
:pt.    3:pd.All variable expansion (environment variables and batch and alias parameters).
:pt.    4:pd.Nested variable expansion only.
:pt.    5:pd.Multiple commands, conditional commands, and piping.
:pt.    6:pd.Redirection.
:pt.    7:pd.Quoting (double quotes and back quotes) and square brackets.
:pt.    8:pd.Escape character.
:eparml.
:p.
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.
:p.
For example, to disable all features except alias expansion while you are
processing a text file containing special characters&colon.
:xmp.
        setdos /x-35678
        ... [perform text processing here]
        setdos /x0
:exmp.
.br
:pt.:hp2./Y&colon.:ehp2.:pd.(debug batch file) :hp2./Y1:ehp2. enables the
built-in batch file debugger.  The debuggger allows you to "single-step"
through a batch file line by line, with the file displayed in a popup window
as it executes.  For complete details on using the debugger see
:link reftype=hd refid=BatchDebug.Debugging Batch Files:elink. (this topic
also covers additional debugging techniques which do not require stepping
through each line individually).
:p.
To start the debugger, insert a SETDOS /Y1 command at the beginning of the
portion of the batch file you want to debug, and a SETDOS /Y0 command at the
end.
:p.
You cannot use the batch debugger with :link reftype=hd
refid=REXX.REXX:elink. files or :link reftype=hd
refid=EXTPROC.EXTPROC:elink. files.  It can only be used with normal &4OS2.
batch files.
:p.
You can also invoke SETDOS /Y1 from the prompt, but because the debugger is
automatically turned off whenever the command processor returns to the
prompt, you must enter the SETDOS command and the batch file name on the
same line.  For example&colon.
:xmp.
        [c&colon.\] setdos /y1 &amp. mybatch.btm
:exmp.:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=SETLOCAL.SETLOCAL - Save the environment
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Save a copy of the current disk drive,
directory, environment, alias list, and special characters.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SETLOCAL:ehp2.
:eparml.:p.
See also&colon.  :link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink..
:p.
:hp2.Usage:ehp2.
:p.
SETLOCAL is used in batch files to save the default disk drive and
directory, the environment, the alias list, and the command separator,
escape character, parameter character, decimal separator, and thousands
separator.  You can then change their values and later restore the original
values with ENDLOCAL.
:p.
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, changes the command separator, runs a
program, and then restores the original values&colon.
:xmp.
        setlocal
        unalias *
        cdd d&colon.\test
        setdos /c~
        program ~ echo Done!
        endlocal
:exmp.:p.
SETLOCAL and ENDLOCAL are not nestable within a batch file.  However, you
can have multiple, separate 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.
:p.
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 settings as they were prior to any SETLOCAL.

.* --------------------------------------------------------------------------

:h2 name=SHIFT.SHIFT - Shift batch file parameters
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Allows the use of more than 127 parameters
in a batch file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SHIFT [:ehp2.:hp3.n:ehp3.
:hp2.&splitvbar. /:ehp2.:hp3.n:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.n :ehp3.&colon.  Number of positions to shift.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
SHIFT is provided for compatibility with older batch files, where
it was used to access more than 10 parameters.  &4OS2. supports 128
parameters (%0 to %127), so you may not need to use SHIFT for batch
files running exclusively under JP Software command processors.
:p.
SHIFT moves each of the batch file parameters :hp1.n:ehp1. positions to
the left.  The default value for :hp1.n:ehp1. 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 :hp1.n:ehp1.
(:hp1.i.e.:ehp1., after SHIFT -1, the former %0 is restored, %0 becomes
%1, %1 becomes %2, etc.).
:p.
SHIFT also affects the parameters :hp2.%n$.:ehp2. (command-line tail)
and :hp2.%#:ehp2. (number of command arguments).
:p.
For example, create a batch file called :hp1.TEST.BAT:ehp1.&colon.
:xmp.
        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
:exmp.:p.
Executing :hp1.TEST.BAT:ehp1. produces the following results&colon.
:xmp.
        [c&colon.\] test one two three four five six seven
        one two three four
        two three four five
        four five six seven
        three four five six
:exmp.:p.
If you add a slash before the value :hp1.n:ehp1., the value determines the
postion at which to begin the shift.  For example&colon.
:xmp.
        shift /2
:exmp.:p.
leaves parameters %0 and %1 unchanged, and moves the value of %3 to postion
%2, %4 to %3, etc.  The value after the slash cannot be negative, and shifts
performed with the slash cannot be undone later in the batch file.

.* --------------------------------------------------------------------------

:h2 name=SHRALIAS.SHRALIAS - Load or unload SHRALIAS.EXE
:i1 id=SHALIAS global.SHRALIAS
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Retains global command history, directory
history, and alias lists in memory when the command processor is not running.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SHRALIAS [/U]:ehp2.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./U:ehp2.(nload):pd.
:eparml.:lm margin=1.
.br
:hp2.Usage:ehp2.
:p.
When you close all &4OS2. sessions, the memory for the global command history,
global directory history, and global alias list is released.  If you want
the lists to be retained in memory even when no command processor session is
running, you need to execute SHRALIAS.
:p.
The SHRALIAS command starts and initializes :hp1.SHRALIAS.EXE:ehp1., a small
program which remains active and retains global lists when &4OS2. is not
running.  In order to start the program, SHRALIAS must be able to find
:hp1.SHRALIAS.EXE:ehp1. either in the same directory as &4OS2., or in a
directory in your PATH.  You cannot run :hp1.SHRALIAS.EXE:ehp1. directly, it
must be run by the SHRALIAS command.
:p.
Once SHRALIAS has been executed, the global lists will be retained in memory
until you use :hp2.SHRALIAS /U:ehp2. to unload the lists, or until you shut
down your operating system.
:p.
SHRALIAS will not work unless you have at least one copy of &4OS2. running
with global alias, command history, and directory history lists enabled.  If
the required global lists are not found, SHRALIAS will display an error.
:p.
If you start SHRALIAS from a temporary &4OS2. session which exits after
starting SHRALIAS (for example, by executing SHRALIAS in your OS/2
:hp1.STARTUP.CMD:ehp1. file), the command processor session may terminate
and discard the shared lists before SHRALIAS can attach to them.  In this
case :hp1.SHRALIAS.EXE:ehp1. will not be loaded.  If you experience this
problem, add a short delay with the DELAY command after SHRALIAS is loaded
and before your session exits.
:p.
For more information about global history and alias lists, see :hp2.Local and
Global Command History:ehp2. under
:link reftype=hd refid=CmdHist.Command History and Recall:elink.,
:link reftype=hd refid=GlobalDirHistory.Local and Global Directory
History:elink., and :hp2.Local and Global Aliases:ehp2. under the
:link reftype=hd refid=ALIAS.ALIAS:elink. command.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2./U:ehp2.&colon.:pd.(Unload) Shuts down :hp1.SHRALIAS.EXE.:ehp1.  If
SHRALIAS is not loaded again, the memory used by global command history,
directory history, and alias lists will be released when the last copy of
&4OS2. exits.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=START.START - Start a program in another session
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Start a program in another session or window.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.START [":ehp2.:hp3.program
title:ehp3. :hp2."] [/B[G] /C /DOS[=:ehp2.:hp3.optfile:ehp3. :hp2.] /F[G] /FS
/I /ICON=:ehp2.:hp3.iconfile:ehp3. :hp2./INV /K /L /LA /LD /LH /MAX /MIN /N
/PGM:ehp2. :hp3.progname:ehp3. :hp2./PM /POS=x,y,width,height /WAIT /WIN
/WIN3[=:ehp2.:hp3.optfile:ehp3. :hp2.]
/WIN3S[=:ehp2.:hp3.optfile:ehp3. :hp2.]] [:ehp2.:hp3.command:ehp3. :hp2.]:ehp2.
.br
:pt.:pd.:hp3.program title :ehp3.&colon.  Title to appear on title bar.
:pt.:pd.:hp3.optfile :ehp3.&colon.  Option settings file.
:pt.:pd.:hp3.iconfile :ehp3.&colon.  Name of icon (:hp1..ICO:ehp1. ) file.
:pt.:pd.:hp3.progname :ehp3.&colon.  Program name (not the session name).
:pt.:pd.:hp3.path :ehp3.&colon.  Startup directory.
:pt.:pd.:hp3.command :ehp3.&colon.  Command to be executed.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./B[G]:ehp2. (background session):pd.:hp2./LH:ehp2. (local history list)
:pt.:hp2./C:ehp2.(lose when done):pd.:hp2./MAX:ehp2.(imized)
:pt.:hp2./DOS:ehp2. (DOS session):pd.:hp2./MIN:ehp2.(imized)
:pt.:hp2./F[G]:ehp2. (foreground session):pd.:hp2./N:ehp2.(o command processor)
:pt.:hp2./FS:ehp2. (full screen):pd.:hp2./PGM:ehp2. (program name)
:pt.:hp2./I:ehp2.(nherit environment):pd.:hp2./PM:ehp2. (PM application)
:pt.:hp2./ICON:ehp2. (:hp1..ICO:ehp1. file):pd.:hp2./POS:ehp2.(ition of window)
:pt.:hp2./INV:ehp2.(isible):pd.:hp2./WAIT:ehp2. (for session to finish)
:pt.:hp2./K:ehp2.(eep when done):pd.:hp2./WIN:ehp2.(dowed session)
:pt.:hp2./L:ehp2.(ocal lists):pd.:hp2./WIN3:ehp2. (Windows enhanced mode)
:pt.:hp2./LA:ehp2. (local aliases):pd.:hp2./WIN3S:ehp2. (Windows standard mode)
:pt.:hp2./LD:ehp2. (local dir history):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=DETACH.DETACH:elink..
:p.
:hp2.Usage:ehp2.
:p.
START is used to begin a new OS/2 session, and optionally run a program in
that session.  If you use START with no parameters, it will begin a new
command-line session.  If you add a :hp1.command:ehp1., START will begin a new
session or window and execute that command.
:p.
The :hp1.program title:ehp1., if it is included, will appear on the title
bar, and on the Presentation Manager window list.  The :hp1.program
title:ehp1. must be enclosed in quotation marks and cannot exceed 60
characters.  If the :hp1.program title:ehp1. is omitted, the program name
will be used as the title.
:p.
START always assumes that the first quoted string on the command line is the
:hp1.program title:ehp1.; if there is a second quoted string it is assumed
to be the :hp1.command:ehp1..  As a result, if the name of the program you
are starting is a long filename containing whitespace (and must therefore be
quoted), you cannot simply place it on the command line.  If you do, as the
first quoted string it will be interpreted as the :hp1.program title:ehp1.,
not the :hp1.command:ehp1..  To address this, use the /PGM switch to
indicate explicitly that the quoted string is the program name, or include a
title before the program name.  For example, to start the program
":hp1.C&colon.\Program Files\Proc.Exe:ehp1." you could use either of the
first two commands below, but the third command would not work&colon.
:xmp.
        [c&colon.\] start /PGM "C&colon.\Program Files\Proc.Exe"
        [c&colon.\] start "test" "C&colon.\Program Files\Proc.Exe"
        [c&colon.\] start "C&colon.\Program Files\Proc.Exe"
:exmp.:p.
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&colon.
:lm margin=8.:p.
:hp2./MAX:ehp2., :hp2./MIN:ehp2., and :hp2./POS:ehp2. 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.
:p.
:hp2./C:ehp2. allows you to close the session when the command is
finished (the default for DOS and OS/2 Presentation Manager sessions);
:hp2./K:ehp2. allows you to keep the session open and go to a prompt
(the default for OS/2 character mode sessions).
:p.
:hp2./BG:ehp2. and :hp2./FG:ehp2. allow you to start the session in the
background(does not respond to keystrokes until selected) or
foreground (responds to keystrokes until deselected).  :hp2./FG:ehp2.
is the default if :hp2./DOS:ehp2., :hp2./FS:ehp2., :hp2./WIN:ehp2., or :hp2./PM:ehp2. is
used; otherwise, :hp2./BG:ehp2. is the default.
:p.
:hp2./FS:ehp2. and :hp2./WIN:ehp2. control whether a character-mode 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.
:lm margin=1.:p.
START determines the application type automatically and starts the
session in the appropriate mode.
:p.
START gives you some flexibility in determining the session mode.
For example, if the :hp1.command:ehp1. is the name of a batch file (either
a :hp1..BTM:ehp1. or :hp1..CMD:ehp1. file), you can use the :hp2./FS:ehp2.
or :hp2./WIN:ehp2. options to run the batch file as part of a new session in
either full-screen or windowed mode.
:p.
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
:hp2./PM:ehp2. switch.  Invalid or conflicting options will be ignored.
&4OS2. will always attempt to run the command in the appropriate type of
session.
:p.
If the program is a DOS application or :hp1..BAT:ehp1. file, &4OS2. will
start a new DOS session to run it.  The DOS session will close itself
automatically as soon as the program or batch file ends, unless
:hp2./K:ehp2. is used.  If you want the session to wait for a keystroke
before it closes itself, you can use this syntax (assuming 4DOS is your
command processor for OS/2 DOS sessions&colon.
:xmp.
        [c&colon.\] start /DOS command ^^ pause
:exmp.:p.
(Because the caret [:hp2.^:ehp2.] is the default &4OS2. escape character,
two carets must be used in order to pass one on to 4DOS as a
command separator.)
:p.
If you want to start a DOS command-line session in OS/2, you can use the
command&colon.
:xmp.
        [c&colon.\] start /DOS
:exmp.:p.
You can specify settings for DOS and Windows sessions by using a
settings options file, and loading it with the :hp2./DOS=:ehp2.,:hp2.
/WIN3=:ehp2., or :hp2./WIN3S=:ehp2. 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 :hp2./DOS=:ehp2.
(below) very carefully, since :hp8.errors in the settings file can
occasionally hang your system:ehp8..
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=12 break=fit.
:pt.:hp2./BG:ehp2.&colon.:pd.(BackGround session) The session is started as a
background session.  :hp2./BG:ehp2. may be abbreviated to
:hp2./B:ehp2..
:pt.:hp2./C:ehp2.&colon.:pd.(Close) The session or window is closed when the application
ends.
:pt.:hp2./DOS[=filename]:ehp2.&colon.:pd.(DOS session) Start a DOS session.
:p.
If you include the :hp2.=filename:ehp2., OS/2 will load DOS
settings from the specified file.  When you use :hp2./DOS:ehp2. you can also
alter the DOS settings for a session with environment variables of the form
:hp2.DosSetting.name=value:ehp2., without using a settings file.
:p.
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 :hp8.you must experiment carefully to ensure that the settings you
select will work properly on the systems on which you plan to use
them:ehp8..  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.
:p.
Each line in the file must have a name, an equal sign [:hp2.=:ehp2.], 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.
:p.
The names in the DOS Settings dialog box will vary depending on the device
drivers and other settings in your :hp1.CONFIG.SYS:ehp1. 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
:hp1.COM.SYS:ehp1. and :hp1.VCOM.SYS:ehp1. 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.
:p.
The values in your settings file must be numeric for settings which show a
numeric value under DOS Settings (:hp1.e.g.:ehp1., DOS_FILES=30), and must
be text strings for settings shown with a string (:hp1.e.g.:ehp1.,
DOS_SHELL=C&colon.\4DOS.COM C&colon.\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 :hp2.0:ehp2. for
Off and :hp2.1:ehp2. for On (:hp1.e.g.:ehp1., 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 (:hp1.e.g.:ehp1., 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..
:p.
A typical DOS settings file might look like this&colon.
:xmp.
        DOS_FILES=30
        DOS_HIGH=1
        DOS_SHELL=C&colon.\4DOS\4DOS.COM C&colon.\4DOS /P
        MOUSE_EXCLUSIVE_ACCESS=0
        VIDEO_FASTPASTE=1
:exmp.:p.
You can include comments in a settings file by beginning any line with a
colon [:hp2.&colon.:ehp2.].
:p.
When you use :hp2./DOS:ehp2. you can also alter the DOS settings for a
session with environment variables, without using a DOS settings file.  When
the :hp2.=filename:ehp2. portion of the switch is not used, OS/2 will scan the
environment looking for variables of the form
:hp2.DosSetting.name=value:ehp2..  Each such variable entry will be used to
set the DOS setting with the specified name to the specified value.  All of
the cautions and restrictions given above for settings stored in a file
apply equally to settings stored in environment variables.
:p.
Settings stored in environment variables are "global" and apply to all
sessions started with :hp2.START /DOS:ehp2., except when an explicit
settings file is specified with :hp2.=filename:ehp2..
:pt.:hp2./FG:ehp2.&colon.:pd.(ForeGround session) Start the session as the foreground
session.  :hp2./FG:ehp2. may be abbreviated to :hp2./F:ehp2..
:pt.:hp2./FS:ehp2.&colon.:pd.(Full Screen) Start the session as a full-screen
session.
:pt.:hp2./I:ehp2.&colon.:pd.(Inherit environment) Inherit the default environment
specified in :hp1.CONFIG.SYS:ehp1., if any, rather than the
current environment.
:pt.:hp2./ICON=:ehp2.:hp1.filename:ehp1. &colon.:pd.Use the specified icon
file.  If you don't use :hp2./ICON:ehp2., the displayed icon will be the one
found or assigned by OS/2.
:pt.:hp2./INV:ehp2.&colon.:pd.(Invisible) 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.
:pt.:hp2./K:ehp2.&colon.:pd.(Keep session or window at end) The session or window
continues after the application program ends.  Use
the :link reftype=hd refid=EXIT.EXIT:elink. command to end the session.
:pt.:hp2./L:ehp2.&colon.:pd.(Local lists) Start &4OS2. with local alias,
history, and directory history lists.  This option combines the effects of
:hp2./LA:ehp2., :hp2./LD:ehp2., and :hp2./LH:ehp2. (below).
:pt.:hp2./LA:ehp2.&colon.:pd.(Local Alias list) Start &4OS2. with a local alias
list.See :link reftype=hd refid=ALIAS.ALIAS:elink. for information on local
and global aliases.
:pt.:hp2./LD:ehp2.&colon.:pd.(Local Directory history) Start &4OS2. with a local
directory history list.  See :link reftype=hd refid=GlobalDirHistory.Local and Global Directory History:elink.
for more information.
:pt.:hp2./LH:ehp2.&colon.:pd.(Local History list) Start &4OS2. with a local history list.
See :link reftype=hd refid=CmdHist.Command History and Recall:elink. for
information on local and global history lists.
:pt.:hp2./MAX:ehp2.&colon.:pd.(Maximized) Start the session or window maximized.
:pt.:hp2./MIN:ehp2.&colon.:pd.(Minimized) Start the session or window minimized.
:pt.:hp2./N:ehp2.&colon.:pd.(No command processor) Start an OS/2 program
directly, without a command processor.  The :hp1.command:ehp1. cannot be an
internal command or batch file.  This is the default for PM applications.
:pt.:hp2./PGM:ehp2.&colon.:pd.(Program name) The string following this option is the
program name.  If you do not use :hp2./PGM:ehp2., the first quoted string on
the line will be used as the session and task list title, and not as the
program name.
:pt.:hp2./PM:ehp2.&colon.:pd.(Presentation Manager) Start a program in the
Presentation Manager session.
:pt.:hp2./POS:ehp2.&colon.:pd.(Position) Start the window at the specified
screen position.  The syntax is :hp2./POS=x, y, width, height:ehp2. where the
values are specified in pixels or pels.  :hp2.x:ehp2. and :hp2.y:ehp2. refer
to the position of the :hp2.top:ehp2. left corner of the window relative to
the :hp2.bottom:ehp2. left corner of the screen.
:pt.:hp2./WAIT:ehp2.&colon.:pd.Wait for the new session or window to finish
before continuing.  Cannot be used with :hp2./WIN3:ehp2. or :hp2./WIN3S:ehp2..
:pt.:hp2./WIN:ehp2.&colon.:pd.(Windowed) Start the session in a window.
:pt.:hp2./WIN3[=filename]:ehp2.&colon.:pd.(Windows enhanced mode) Run the program
in an enhanced-mode Windows 3.x session.  The session will run seamless (on the OS/2
desktop).  To start a Windows application in full-screen mode, use :hp2./FS:ehp2. rather
than :hp2./WIN3:ehp2..  You can include an equal sign and the name of an options file to
set options for the specific session and application (see :hp2./DOS=:ehp2. above for
details).
:pt.:hp2./WIN3S[=filename]:ehp2.&colon.:pd.(Windows standard mode)
Equivalent to :hp2./WIN3:ehp2., but runs the program in standard mode rather
than enhanced mode.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=SWITCH.SWITCH - Select commands based on a value
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Select commands to execute based on a value.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.SWITCH:ehp2. :hp3.expression:ehp3.
:pt.:pd.:hp2.CASE:ehp2. :hp3.value1:ehp3. :hp2.[.OR.:ehp2.
:hp3.value2:ehp3. :hp2.] ...:ehp2.
:pt.:pd.:hp3.     commands:ehp3.
:pt.:pd.:hp2.CASE:ehp2. :hp3.value3:ehp3.
:pt.:pd.:hp3.     commands:ehp3.
:pt.:pd.:hp2.DEFAULT:ehp2.
:pt.:pd.:hp3.     commands:ehp3. :hp2.]:ehp2.
:pt.:pd.:hp2.ENDSWITCH:ehp2.
.br
:pt.:pd.:hp3.expression :ehp3.&colon.  An environment variable, internal
variable, variable function, text string, or a combination of these
elements, that is used to select a group of commands.
:pt.:pd.:hp3.value1, value2,:ehp3. :hp1.etc. :ehp1.&colon.  A value to test,
or multiple values connected with :hp2..OR.:ehp2.
:pt.:pd.:hp3.commands :ehp3.&colon.  One or more commands to execute if the
expression matches the :hp1.value:ehp1..  If you use multiple commands, they
must be separated by command separators or placed on separate lines.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=IF.IF:elink. and
:link reftype=hd refid=IFF.IFF:elink..
:p.
:hp2.Usage:ehp2.
:p.
SWITCH can only be used in batch files.  It allows you to select a command
or group of commands to execute based on the possible values of a variable
or a combination of variables and text.
:p.
The SWITCH command is always followed by an :hp1.expression:ehp1. created
from environment variables, internal variables, variable functions, and text
strings, and then by a sequence of CASE statements matching the possible
:hp1.values:ehp1. of the :hp1.expression:ehp1..  If one of the
:hp1.values:ehp1. in a CASE statement matches the :hp1.expression:ehp1., the
commands following that CASE statement are executed, and all subsequent CASE
statements and the commands which follow them are ignored.  If no matches are
found, the commands following the optional DEFAULT statement are executed.  If
there are no matches and there is no DEFAULT statement, no commands are
executed by SWITCH.
:p.
After all of the commands following the CASE or DEFAULT statement are
executed, the batch file continues with the commands that follow ENDSWITCH.
:p.
You must include a command separator or new line after the
:hp1.expression:ehp1., before each CASE or DEFAULT statement, before each
command, and before ENDSWITCH.  You can link :hp1.values:ehp1. in a CASE
statement with :hp2..OR.:ehp2. (but not with :hp2..AND.:ehp2. or
:hp2..XOR.:ehp2.).
:p.
For example, the following batch file fragment displays one message if the
user presses :hp2.A:ehp2., another if user presses :hp2.B:ehp2. or
:hp2.C:ehp2., and a third if the user presses any other key&colon.
:xmp.
        inkey Enter a keystroke&colon. %%key
        switch %key
        case A
           echo It's an A
        case B .or. C
           echo It's either B or C
        default
           echo It's not A, B, or C
        endswitch
:exmp.:p.
In the example above, the value of a single environment variable was used for
the :hp1.expression:ehp1..  You will probably find that this is the best
method to use in most situations.  However, you can use other kinds of
expressions if necessary.  The first example below selects a command to
execute based on the length of a variable, and the second bases the action
on a quoted text string stored in an environment variable&colon.
:xmp.
        switch %@len[%var1]
        case 0
           echo Missing var1
        case 1
           echo Single character
        ...
        endswitch

        switch "%string1"
        case "This is a test"
           echo Test string
        case "The quick brown fox"
           echo It's the fox
        ...
        endswitch
:exmp.:p.
The SWITCH and ENDSWITCH commands must be on separate lines, and cannot be
placed within a :link reftype=hd refid=Grouping.command group:elink., or on
the same line as other commands (this is the reason SWITCH cannot be used in
aliases).  However, commands within the SWITCH block can use command groups
or the :link reftype=hd refid=MultCmds.command separator:elink. in the
normal way.
:p.
SWITCH commands can be nested.  You can exit from all SWITCH / ENDSWITCH
processing by using :link reftype=hd refid=GOTO.GOTO:elink. to a line past
the last ENDSWITCH.

.* --------------------------------------------------------------------------

:h2 name=TEE.TEE - "Tee" pipe fitting
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Copy standard input to both standard output
and a file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.TEE [/A] :ehp2.:hp3.file:ehp3.
:hp2....:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  One or more files that will receive the
"tee-d" output.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A:ehp2.(ppend):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=Y.Y:elink. and the :link reftype=hd
refid=RedirPipe.redirection:elink. options.
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
TEE gets its input from standard input (usually the piped output of
another command or program), and sends out two copies&colon.  one goes to
standard output, the other to the :hp1.file:ehp1. or :hp1.files:ehp1. 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.
:p.
For example, to search the file :hp1.DOC:ehp1. for any lines containing
the string "&4OS2.", make a copy of the matching lines in :hp1.4.DAT:ehp1.,
sort the lines, and write them to the output file :hp1.4O.DAT:ehp1. &colon.
:xmp.
        [c&colon.\] find "&4OS2." doc &splitvbar. tee 4.dat &splitvbar. sort > 4o.dat
:exmp.:p.
If you are typing at the keyboard to produce the input for TEE, you
must enter a :hp2.Ctrl-Z:ehp2. to terminate the input.
:p.
When using TEE with a pipe under &4OS2., the programs on the two ends
of the pipe run simultaneously, not sequentially as in 4DOS.
:p.
See :link reftype=hd refid=Piping.Piping:elink. for more information on
pipes.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(Append) Append the output to the file(s) rather
than overwriting them.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=TEXT.TEXT - Display text in a batch file
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display a block of text in a batch file.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.TEXT:ehp2.
:pt.:pd.     .
:pt.:pd.     .
:pt.:pd.     .
:pt.:pd.:hp2.ENDTEXT:ehp2.
:eparml.:p.
See also&colon.  :link reftype=hd refid=ECHO.ECHO:elink., :link reftype=hd refid=SCREEN.SCREEN:elink., :link reftype=hd refid=SCRPUT.SCRPUT:elink.,
and :link reftype=hd refid=VSCRPUT.VSCRPUT:elink..
:p.
:hp2.Usage:ehp2.
:p.
TEXT can only be used in batch files.
:p.
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.
:p.
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.
:p.
You can change screen colors by inserting ANSI escape sequences
anywhere in the text block.  You can also use a
:link reftype=hd refid=CLS.CLS:elink. or :link reftype=hd
refid=COLOR.COLOR:elink. command to set the screen color before executing
the TEXT command.
:p.
The following batch file fragment displays a simple menu&colon.
:xmp.
        @echo off &amp. cls
        screen 2 0
        text
        Enter one of the following&colon.
           1 - Spreadsheet
           2 - Word Processing
           3 - Utilities
           4 - Exit
        endtext
        inkey /k"1243" Enter your selection:  %%key
:exmp.

.* --------------------------------------------------------------------------

:h2 name=TIME.TIME - Set the system time
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display or set the current system time.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.TIME [:ehp2.:hp3.hh:ehp3.
:hp2.[&colon.:ehp2.:hp3.mm:ehp3. :hp2.[&colon.:ehp2.:hp3.ss:ehp3. :hp2.]]]
[AM &splitvbar. PM]:ehp2.
.br
:pt.:pd.:hp3.hh :ehp3.&colon.  The hour (0 - 23).
:pt.:pd.:hp3.mm :ehp3.&colon.  The minute (0 - 59).
:pt.:pd.:hp3.ss :ehp3.&colon.  The second (0 - 59).
:eparml.:p.
See also&colon.  :link reftype=hd refid=DATE.DATE:elink..
:p.
:hp2.Usage:ehp2.
:p.
If you don't enter any parameters, TIME will display the current
system time and prompt you for a new time.  Press :hp2.Enter:ehp2. if you
don't wish to change the time; otherwise, enter the new time&colon.
:xmp.
        [c&colon.\] time
        Mon  Dec 22, 1997  9&colon.30&colon.06
        New time (hh&colon.mm&colon.ss)&colon.
:exmp.:p.
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.
:p.
For example, to enter the time as 9&colon.30 am&colon.
:xmp.
        [c&colon.\] time 9&colon.30 am
:exmp.:p.
OS/2 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.

.* --------------------------------------------------------------------------

:h2 name=TIMER.TIMER - Start or stop a stopwatch
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.TIMER is a system stopwatch.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.TIMER [ON] [/1 /2 /3 /S]:ehp2.
.br
:pt.:pd.:hp3.ON :ehp3.&colon.  Force the stopwatch to restart.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./1:ehp2. (stopwatch #1):pd.:hp2./3:ehp2. (stopwatch #3)
:pt.:hp2./2:ehp2. (stopwatch #2):pd.:hp2./S:ehp2.(plit)
:eparml.:lm margin=1.
.br
:hp2.Usage:ehp2.
:p.
The TIMER command turns a system stopwatch on and off.  When you
first run TIMER, the stopwatch starts&colon.
:xmp.
        [c&colon.\] timer
        Timer 1 on&colon.  12&colon.21&colon.46
:exmp.:p.
When you run TIMER again, the stopwatch stops and the elapsed time
is displayed&colon.
:xmp.
        [c&colon.\] timer
        Timer 1 off&colon.  12&colon.21&colon.58   Elapsed time&colon. 0&colon.00&colon.12.06
:exmp.:p.
There are three stopwatches available (1, 2, and 3) so you can time
multiple overlapping events.  By default, TIMER uses stopwatch #1.
:p.
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 be greater than .06 second.  The
largest interval is 23 hours, 59 minutes, 59.99 seconds.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2./1:ehp2.&colon.:pd.Use timer #1 (the default).
.br
:pt.:hp2./2:ehp2.&colon.:pd.Use timer #2.
.br
:pt.:hp2./3:ehp2.&colon.:pd.Use timer #3.
.br
:pt.:hp2./S:ehp2.&colon.:pd.(Split) Display a split time without stopping
the timer.  To display the current elapsed time but leave the timer
running&colon.
:xmp.
        [c&colon.\] timer /s
        Timer 1 elapsed&colon. 0&colon.06&colon.40.63
:exmp.
:pt.:hp2.ON:ehp2.&colon.:pd.Start the timer regardless of its previous state (on
or off).  Otherwise the TIMER command toggles the timer state (unless :hp2./S:ehp2.
is used).
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=TITLE.TITLE - Window title
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Change the window title.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.TITLE:ehp2. :hp3.title:ehp3.
.br
:pt.:pd.:hp3.title :ehp3.&colon.  The new window title.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=ACTIVATE.ACTIVATE:elink. and
:link reftype=hd refid=WINDOW.WINDOW:elink..
:p.
:hp2.Usage:ehp2.
:p.
TITLE changes the text that appears in the caption bar at the top of the
&4OS2. window.
:p.
The title text should not be enclosed in quotes unless you want the quotes to
appear as part of the actual title.
:p.
To change the title of the current window to "JP Software / &4OS2."&colon.
:xmp.
        [c&colon.\] title JP Software / &4OS2.
:exmp.:p.

.* --------------------------------------------------------------------------

:h2 name=TOUCH.TOUCH - Change date and time stamps
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Change a file's date and time stamps.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.TOUCH [/C /D[acw][mm-dd-yy] /E /F /Q
/T[acw][hh&colon.mm]]:ehp2. :hp3.file:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  One or more files whose date and/or time
stamps are to be changed.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./C:ehp2.(reate file):pd.:hp2./F:ehp2.(orce read-only files)
:pt.:hp2./D:ehp2.(ate):pd.:hp2./Q:ehp2.(uiet)
:pt.:hp2./E:ehp2. (no Error messages):pd.:hp2./T:ehp2.(ime)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=LIST.LIST:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink.,
:link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and
:link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
TOUCH is used to change the date and/or time of a file.  You can use it to
be sure that particular files are included or excluded from an internal
command, backup program, compiler MAKE utility, or other program that
selects files based on their time and date stamps, or to set a group of
files to the same date and time for consistency.
:p.
:hp8.TOUCH should be used with caution:ehp8., and in most cases should only
be used on files you create.  Many programs depend on file dates
and times to perform their work properly.  In addition, many software
manufacturers use file dates and times to signify version
numbers.  Indiscriminate changes to date and time stamps can lead to
confusion or incorrect behavior of other software.
:p.
TOUCH normally works with existing files, and will display an error if the
:hp1.file:ehp1. you specify does not exist, or has the read-only attribute
set.  To create the :hp1.file:ehp1. if it does not already exist, use the
:hp2./C:ehp2. switch.  To force a date and time change for read-only files,
use the :hp2./F:ehp2. switch.
:p.
TOUCH displays the date, time, and full name of each file whose timestamp is
modified.  To disable this output, use :hp2./Q:ehp2..
:p.
If you don't specify a date or a time, TOUCH will default to the current date
and time from your system clock.  For example, to set the time stamp of all
:hp1..C:ehp1. files in the current directory to the current date and
time&colon.
:xmp.
        [d&colon.\source] touch *.c
         6-12-97 11&colon.13&colon.58  D&colon.\SOURCE\MAIN.C
         6-12-97 11&colon.13&colon.58  D&colon.\SOURCE\INIT.C
         ...
:exmp.:p.
If you specify a date but not a time, the time will default to the current
time from your system clock.  Similarly, if you specify a time but not a
date, the date will be obtained from the system clock.
:p.
On HPFS files, TOUCH sets the "modified" or "last write" date and time by
default.  By adding the appropriate character to the /D or /T switch, you
can set the other date and time stamps that are maintained for each
file&colon.
:lm margin=4.:parml compact tsize=8 break=fit.
:pt.:hp2.a:ehp2.:pd.last access date and time.
:pt.:hp2.c:ehp2.:pd.creation date and time
:pt.:hp2.w:ehp2.:pd.last write date and time (default)
:eparml.:lm margin=1.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./C:ehp2.&colon.:pd.(Create file) Create the :hp1.file:ehp1. (as a
zero-byte file) if it does not already exist.  You cannot use wildcards with
:hp2./C:ehp2., but you can create multiple :hp1.files:ehp1. by listing them
individually on the command line.
:pt.:hp2./D:ehp2.&colon.:pd.(Date) Specify the date that will be set for the
selected files.  If the date is not specified, TOUCH will use the current
date.  For HPFS files you can use :hp2./Da:ehp2., :hp2./Dc:ehp2., or
:hp2./Dw:ehp2., followed by the date, to explicitly specify the last access,
creation, or last write date stamp.  The date must be entered using the
proper format for your current country settings.
:pt.:hp2./E:ehp2.&colon.:pd.(No error messages) Suppress all non-fatal error
messages, such as "File not found."  Fatal error messages, such as "Drive not
ready," will still be displayed.  This option is most useful in batch files.
:pt.:hp2./F:ehp2.&colon.:pd.(Force read-only files) Remove the read-only
attribute from each file before changing the date and time, and restore it
afterwards.  Without :hp2./F:ehp2., attempting to change the date and time
on a read-only file will usually cause an error.
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) Do not dislpy the new date and time and
the full name for each file.
:pt.:hp2./T:ehp2.&colon.:pd.(Time) Specify the time that will be set for the
selected files, in hh&colon.mm format.  If the time is not specified, TOUCH
will use the current time.  For HPFS files you can use :hp2./Ta:ehp2.,
:hp2./Tc:ehp2., or :hp2./Tw:ehp2., followed by the time, to explicitly
specify the last access, creation, or last write time stamp.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=TREE.TREE - Directory tree
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display a graphical directory tree.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.TREE [/A /B /F /H /P /S
/T[&colon.acw]]:ehp2. :hp3.dir:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.dir :ehp3.&colon.  The directory to use as the start of the
tree.  If more than one directory is specified, TREE will display a directory
tree for each.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2.(SCII):pd.:hp2./P:ehp2.(ause)
:pt.:hp2./B&colon.:ehp2.(are):pd.:hp2./S:ehp2. (file Size)
:pt.:hp2./F&colon.:ehp2.(iles):pd.:hp2./T:ehp2.(ime and date)
:pt.:hp2./H&colon.:ehp2.(idden directories):pd.
:eparml.:lm margin=1.
.br
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink.,
:link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and
:link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
The TREE command displays a graphical representation of the directory tree
using standard or extended ASCII characters.  For example, to display the
directory structure on drive C&colon.
:xmp.
        [c&colon.\] tree c&colon.\
:exmp.:p.
You can print the display, save it in a file, or view it with
:link reftype=hd refid=LIST.LIST:elink. by using standard
:link reftype=hd refid=RedirPipe.redirection:elink. symbols.  Be sure to
review the :hp2./A :ehp2.option before attempting to print the TREE
output.  The options, discussed below, specify the amount of information
included in the display.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A:ehp2.&colon.:pd.(ASCII) Display the tree using standard ASCII
characters.  You can use this option if you want to save the directory tree
in a file for further processing or print the tree on a printer which does
not support the graphical symbols that TREE normally uses.
:pt.:hp2./B:ehp2.&colon.:pd.(Bare) Display the full pathname of each
directory, without any of the line-drawing characters.
:pt.:hp2./F:ehp2.&colon.:pd.(Files) Display files as well as directories.  If
you use this option, the name of each file is displayed beneath the name of
the directory in which it resides.
:pt.:hp2./H:ehp2.&colon.:pd.(Hidden) Display hidden as well as normal
directories.  If you combine :hp2./H:ehp2. and :hp2./F:ehp2., hidden files
are also displayed.
:pt.:hp2./P:ehp2.&colon.:pd.(Pause) Wait for a key to be pressed after each
screen page before continuing the display.  Your options at the prompt are
explained in detail under :link reftype=hd refid=Prompts.Page and File
Prompts:elink..
:pt.:hp2./S:ehp2.&colon.:pd.(Size) Display the size of each file.  This
option is only useful when combined with :hp2./F:ehp2..
:pt.:hp2./T:ehp2.&colon.:pd.(Time and date) Display the time and date for
each directory.  If you combine :hp2./T:ehp2. and :hp2./F:ehp2., the time
and date for each file will also be displayed.  For HPFS files, the time and
date of the last write will be shown by default.  You can select a specific
time and date stamp by using the following variations of :hp2./T:ehp2.&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2./T&colon.a:ehp2.  last access date and time.
:pt.:pd.:hp2./T&colon.c:ehp2.  creation date and time.
:pt.:pd.:hp2./T&colon.w:ehp2.  last write date and time (default).
:eparml.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=TYPE.TYPE - Display file(s)
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display the contents of the specified file(s).
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.TYPE [/A&colon.[[-]rhsda] /L /P]:ehp2.
:hp3.file:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  The file or list of files that you want to display.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./A&colon.:ehp2. (Attribute select):pd.:hp2./P:ehp2.(ause)
:pt.:hp2./L:ehp2.(ine numbers):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=LIST.LIST:elink..
:p.
:hp2.File Selection:ehp2.
:p.
Supports extended :link reftype=hd refid=wildcards.wildcards:elink., :link reftype=hd refid=ranges.ranges:elink.,
:link reftype=hd refid=MultFiles.multiple file names:elink., and :link reftype=hd refid=InclList.include lists:elink..
:p.
:hp2.Usage:ehp2.
:p.
The TYPE command displays a file.  It is normally only useful for
displaying ASCII text files.  Executable files (:hp1..COM:ehp1. and
:hp1..EXE:ehp1. ) and many data files may be unreadable when displayed with
TYPE because they include non-alphanumeric characters.
:p.
To display the files :hp1.MEMO1:ehp1. and :hp1.MEMO2:ehp1. &colon.
:xmp.
        [c&colon.\] type /p memo1 memo2
:exmp.:p.
You can press :hp2.Ctrl-S:ehp2. to pause TYPE's display and then any key
to continue.
:p.
To display text from the clipboard, use :hp2.CLIP&colon.:ehp2. as the file
name.  CLIP&colon. will not return any data unless the clipboard
contains text.  See :link reftype=hd refid=Redirection.Redirection:elink. for
additional information on CLIP&colon..
:p.
You will probably find LIST to be more useful for displaying files.  However,
the TYPE /L command used with :link reftype=hd
refid=Redirection.redirection:elink. is useful if you want to add line
numbers to a file, for example&colon.
:xmp.
        [c&colon.\] type /l myfile > myfile.num
:exmp.:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./A&colon.:ehp2.&colon.:pd.(Attribute select) Select only those files that have the
specified attribute(s) set.  Preceding the attribute character with a
hyphen [:hp2.-:ehp2.] will select files that do not have that attribute set.  The colon
[:hp2.&colon.:ehp2.] after :hp2./A:ehp2. is required.  The attributes are&colon.
:parml tsize=8 compact break=fit.
:pt.:pd.:hp2.    R:ehp2.  Read-only
:pt.:pd.:hp2.    H:ehp2.  Hidden
:pt.:pd.:hp2.    S:ehp2.  System
:pt.:pd.:hp2.    D:ehp2.  Subdirectory
:pt.:pd.:hp2.    A:ehp2.  Archive
:eparml.:p.
If no attributes are listed at all (:hp1.e.g.:ehp1., :hp2.TYPE /A&colon. ...:ehp2.), TYPE will select all
files and subdirectories including hidden and system files.  If
attributes are combined, all the specified attributes must match for a
file to be selected. For example, /A&colon.RHS will select only those files
with all three attributes set.
:pt.:hp2./L:ehp2.&colon.:pd.(Line numbers) Display a line number preceding
each line of text.
:pt.:hp2./P:ehp2.&colon.:pd.(Pause) Prompt after displaying each page.  Your
options at the prompt are explained in detail under :link reftype=hd
refid=Prompts.Page and File Prompts:elink..
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=UNALIAS.UNALIAS - Remove aliases
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Remove aliases from the alias list.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.UNALIAS [/Q /R:ehp2.
:hp3.file:ehp3. :hp2.] [:ehp2.:hp3.alias:ehp3. :hp2....]:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.UNALIAS *:ehp2.
.br
:pt.:pd.:hp3.alias :ehp3.&colon.  One or more aliases to remove from memory.
:pt.:pd.:hp3.file :ehp3.&colon.  One or more files to read for alias
definitions.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./Q:ehp2.(uiet):pd.:hp2./R:ehp2.(ead file)
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=ALIAS.ALIAS:elink. and
:link reftype=hd refid=ESET.ESET:elink..
:p.
:hp2.Usage:ehp2.
:p.
&4OS2. maintains 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 :hp2.UNALIAS *:ehp2..
:p.
For example, to remove the alias DDIR&colon.
:xmp.
        [c&colon.\] unalias ddir
:exmp.:p.
To remove all the aliases&colon.
:xmp.
        [c&colon.\] unalias *
:exmp.:p.
If you keep aliases in a file that can be loaded with the
:link reftype=hd refid=ALIAS.ALIAS:elink. /R command, you can remove the
aliases by using the UNALIAS /R command with the same file name&colon.
:xmp.
        [c&colon.\] unalias /r alias.lst
:exmp.:p.
This is much faster than removing each alias individually in a batch file,
and can be more selective than using UNALIAS *.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) 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.
:pt.:hp2./R:ehp2.&colon.:pd.(Read) Read the list of aliases to remove from a
file.  The file format should be the same format as that used by the
:link reftype=hd refid=ALIAS.ALIAS:elink. /R command.  You can use multiple
files with one UNALIAS /R command by placing the names on the command line,
separated by spaces&colon.
:xmp.
        [c&colon.\] unalias /r alias1.lst alias2.lst
:exmp.:p.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=UNSET.UNSET - Remove environment variables
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Remove variables from the environment.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.UNSET  [/Q /R:ehp2.
:hp3.file:ehp3. :hp2.]:ehp2. :hp3.name:ehp3. :hp2....:ehp2.
:pt.:pd.     or
:pt.:pd.:hp2.UNSET *:ehp2.
.br
:pt.:pd.:hp3.name :ehp3.&colon.  One or more variables to remove.
:pt.:pd.:hp3.file :ehp3.&colon.  One or more files containing variables
definitions.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./M:ehp2.(uiet):pd.:hp2./R:ehp2.(ead from file)
:pt.:hp2./Q:ehp2.(uiet):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=ESET.ESET:elink. and
:link reftype=hd refid=SET.SET:elink..
:p.
:hp2.Usage:ehp2.
:p.
UNSET removes one or more variables from the environment.  For example, to
remove the variable CMDLINE&colon.
:xmp.
        [c&colon.\] unset cmdline
:exmp.:p.
If you use the command :hp2.UNSET *:ehp2., all of the environment variables
will be deleted&colon.
:xmp.
        [c&colon.\] unset *
:exmp.:p.
UNSET can be used in a batch file, in conjunction with the SETLOCAL and
ENDLOCAL commands, to clear the environment of variables that may cause
problems for applications run from that batch file.
:p.
For more information on environment variables, see the :link reftype=hd
refid=SET.SET:elink. command and the general discussion of the
:link reftype=hd refid=Environment.environment:elink..
:p.
:hp8.Use caution:ehp8. when removing environment variables, and especially
when using UNSET *.  Many programs will not work properly without
certain environment variables; for example, &4OS2. uses PATH and DPATH.
:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./Q:ehp2.&colon.:pd.(Quiet) 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 removing a group of variables when some of the
variables may not have been defined.
:pt.:hp2./R:ehp2.&colon.:pd.(Read) Read environment variables to UNSET from
a file.  This much faster than using multiple UNSET commands in a batch
file, and can be more selective than UNSET *.  The file format should be the
same format as that used by the :link reftype=hd refid=SET.SET:elink. /R
command.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=VER.VER - Display the &4OS2. and OS/2 version
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display the current command processor and operating
system versions.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.VER [/R]:ehp2.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./R:ehp2.(evision level):pd.
:eparml.:lm margin=1.
.br
:hp2.Usage:ehp2.
:p.
Version numbers consist of a one-digit major version number, a
period, and a one- or two-digit minor version number.  Ver uses the default
decimal separator defined by the current country information.  The VER
command displays both version numbers&colon.
:xmp.
        [c&colon.\] ver

        &4OS2. &4verrev.   OS/2 Version is 4.50
:exmp.:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./R:ehp2.&colon.:pd.(Revision level) Display the &4OS2. and OS/2
internal revision levels (if any), plus your &4OS2. serial number and
registered name.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=VERIFY.VERIFY - Enable or disable disk write verification
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Enable or disable disk write verification
or display the verification state.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.VERIFY [ON &splitvbar. OFF]:ehp2.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
OS/2 maintains an internal verify flag.  When the flag is on, OS/2 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 :hp2.not:ehp2.
compare the data in memory with the data actually placed on disk to fully
verify the disk write process.
:p.
If used without any parameters, VERIFY will display the state of the verify
flag&colon.
:xmp.
        [c&colon.\] verify
        VERIFY is OFF
:exmp.:p.
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.
:p.
Verification will slow your disk write operations slightly (the effect is
not usually noticeable).

.* --------------------------------------------------------------------------

:h2 name=VOL.VOL - Display disk volume labels
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display disk volume label(s).
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.VOL [:ehp2.:hp3.drive&colon.:ehp3.
:hp2.] ...:ehp2.
.br
:pt.:pd.:hp3.drive :ehp3.&colon.  The drive or drives to search for labels.
:eparml.:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
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&colon.
:xmp.
        [c&colon.\] vol
        Volume in drive C&colon. is MYHARDDISK
:exmp.:p.
If available, the volume serial number will appear after the drive
label or name.
:p.
To display the disk labels for drives A and B&colon.
:xmp.
        [c&colon.\] vol a&colon. b&colon.
        Volume in drive A&colon. is unlabeled
        Volume in drive B&colon. is BACKUP_2
:exmp.

.* --------------------------------------------------------------------------

:h2 name=VSCRPUT.VSCRPUT - Display text vertically and in color
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Display text vertically in the specified color.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.VSCRPUT:ehp2. :hp3.row col:ehp3.
:hp2.[BRIght] [BLInk]:ehp2. :hp3.fg:ehp3. :hp2.ON [BRIght]:ehp2.
:hp3.bg text:ehp3.
.br
:pt.:pd.:hp3.row :ehp3.&colon.  Starting row number.
:pt.:pd.:hp3.col :ehp3.&colon.  Starting column number.
:pt.:pd.:hp3.fg :ehp3.&colon.  Foreground text color.
:pt.:pd.:hp3.bg :ehp3.&colon.  Background text color.
:pt.:pd.:hp3.text :ehp3.&colon.  The text to display.
:eparml.:p.
See also&colon.  :link reftype=hd refid=SCRPUT.SCRPUT:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.  VSCRPUT always leaves the cursor
at the end of the displayed text.  See :link reftype=hd refid=Colors.Colors
and Color Names:elink. for details about colors and notes on the use of
bright background colors.
:p.
The :hp1.row:ehp1. and :hp1.column:ehp1. are zero-based, so on a standard 25
line by 80 column display, valid rows are 0 - 24 and valid columns are 0
- 79.  VSCRPUT checks for a valid :hp1.row:ehp1. and :hp1.column:ehp1., and
displays a "Usage" error message if either value is out of range.
:p.
You can also specify the :hp1.row:ehp1. and :hp1.column:ehp1. as offsets
from the current cursor position.  Begin the value with a plus sign
[:hp2.+:ehp2.] 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 [:hp2.-:ehp2.] to move up or to the left.
:p.
If you specify 999 for the :hp1.row:ehp1., VSCRPUT will center the text
vertically on the display.  If you specify 999 for the :hp1.column:ehp1.,
VSCRPUT will center the text horizontally.
:p.
VSCRPUT does not move the cursor when it displays the text.
:p.
The following batch file fragment displays an X and Y axis and labels
them&colon.
:xmp.
        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
:exmp.:p.
VSCRPUT checks for a valid :hp1.row:ehp1. and :hp1.column:ehp1., and
displays a "Usage" error message if either value is out of range.

.* --------------------------------------------------------------------------

:h2 name=WINDOW.WINDOW - Change the window state or title
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Minimize or maximize the current window,
restore the default window size, or change the window title.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.WINDOW [MIN &splitvbar. MAX &splitvbar.
RESTORE &splitvbar. /POS=x,y,width,height &splitvbar.
":ehp2.:hp3.title:ehp3. :hp2."]:ehp2.
.br
:pt.:pd.:hp3.title :ehp3.&colon.  A new title for the window.
:eparml.:lm margin=13.:parml compact tsize=32 break=none.
:pt.:hp2./POS:ehp2.(ition):pd.
:eparml.:lm margin=1.
.br
See also&colon.  :link reftype=hd refid=TITLE.TITLE:elink..
:p.
:hp2.Usage:ehp2.
:p.
The WINDOW command is used to control the appearance and title of the current
window.  WINDOW can only be used to specify one change to the current window
at a time; to perform more than one operation, you must use multiple WINDOW
commands (see examples below).
:p.
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.
:p.
You can use the :hp2./POS:ehp2. option to set the location and size of the
window on the desktop.  The x and y values of the :hp2./POS:ehp2.
option select the window's origin while the width and height values
determine its size.
:p.
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.
:p.
For example, to maximize the current window and change it's title, you must
perform two WINDOW commands:
:xmp.
        [c&colon.\] window max
        [c&colon.\] window "JP Software / &4OS2."
:exmp.:p.
:hp2.Options:ehp2.
:lm margin=4.:parml tsize=8 break=fit.
:pt.:hp2./POS:ehp2.&colon.:pd.(Position) Set the window position and size on the
screen.  The syntax is :hp2./POS=x, y, width, height:ehp2. where the
values are specified in pixels or pels.  :hp2.x:ehp2. and :hp2.y:ehp2. refer
to the position of the :hp2.top:ehp2. left corner of the window relative to
the :hp2.bottom:ehp2. left corner of the screen.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=Y.Y - "Y" pipe fitting
:parml compact tsize=12 break=fit.
:pt.:hp3.Purpose&colon.:ehp3.:pd.Copy standard input to standard output, and
then copy the specified file(s) to standard output.
.br
:pt.:hp3.Format&colon.:ehp3.:pd.:hp2.Y:ehp2. :hp3.file:ehp3. :hp2....:ehp2.
.br
:pt.:pd.:hp3.file :ehp3.&colon.  The file or list of files to send to
standard output.
:eparml.:p.
See also&colon.  :link reftype=hd refid=TEE.TEE:elink..
:p.
:hp2.Usage:ehp2.
:p.
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.
:p.
For example, to get text from standard input, append the files
:hp1.MEMO1:ehp1. and :hp1.MEMO2:ehp1. to it, and send the output to :hp1.MEMOS:ehp1. &colon.
:xmp.
        [c&colon.\] y memo1 memo2 > memos
:exmp.:p.
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&colon.
:xmp.
        [c&colon.\] dir &splitvbar. y dirend > dirall
:exmp.:p.
If you are typing at the keyboard to produce input text for Y, you
must enter a :hp2.Ctrl-Z:ehp2. to terminate the input.
:p.
When using Y with a pipe you must take into account that the programs on the
two ends of the pipe run simultaneously, not sequentially.
:p.
See :link reftype=hd refid=Piping.Piping:elink. for more information.

.* --------------------------------------------------------------------------

.im external.ipf

.* --------------------------------------------------------------------------

:h1 name=Aliases.Aliases
:p.
Much of the power of &4OS2. comes together in :hp2.aliases:ehp2., 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.
:p.
This section will show you some examples of the power of aliases.  See the
:link reftype=hd refid=ALIAS.ALIAS:elink. command for complete details about
writing your own aliases.
:p.
The simplest type of alias gives a new name to an existing command.  For
example, you could create a command called ROOT which uses
:link reftype=hd refid=CD.CD:elink. to switch to the root directory this
way&colon.
:xmp.
        [c&colon.\] alias root = cd \
:exmp.:p.
After the alias has been defined this way, every time you type the command
ROOT, you will actually execute the command CD \.
:p.
Aliases can also create customized versions of commands.  For example, the
:link reftype=hd refid=DIR.DIR:elink. 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&colon.
:xmp.
        [c&colon.\] alias de = dir /oe /p
:exmp.: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
:hp1.E&colon.\WP60\WP.EXE:ehp1., and, when the program terminates, returns
to the original drive and directory&colon.
:xmp.
        [c&colon.\] alias w = `pushd c&colon.\wp &amp. e&colon.\wp60\wp.exe &amp. popd`
:exmp.:p.
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 :link reftype=hd refid=ALIAS.ALIAS:elink command for full details.
:p.
Aliases can be nested, that is, one alias can invoke another.  For example,
the alias above could also be written as&colon.
:xmp.
        [c&colon.\] alias wp = e&colon.\wp60\wp.exe
        [c&colon.\] alias w = `pushd c&colon.\wp &amp. wp &amp. popd`
:exmp.:p.
If you enter W as a command, the command processor will execute the
:link reftype=hd refid=PUSHD.PUSHD:elink. command, detect that the next
command (WP) is another alias, and execute the program
:hp1.E&colon.\WP60\WP.EXE:ehp1., and - when the program exits - return to the
first alias, execute the :link reftype=hd refid=POPD.POPD:elink. command, and
return to the prompt.
:p.
You can use aliases to change the default options for both internal commands
and external commands.  Suppose that you always want the
:link reftype=hd refid=DEL.DEL:elink. command to prompt before it erases a
file&colon.
:xmp.
        [c&colon.\] alias del = *del /p
:exmp.:p.
An asterisk [:hp2.*:ehp2.] is used in front of the second "del" to show that
it is the name of an internal command, not an alias.  See
:link reftype=hd refid=ALIAS.ALIAS:elink. for more information about this
use of the asterisk.
:p.
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
:hp1.LIST.COM:ehp1. in the :hp1.C&colon.\UTIL:ehp1. directory, you could run
it with the command :hp1.C&colon.\UTIL\LIST.COM:ehp1..  However, if you
simply type LIST, the internal :link reftype=hd refid=LIST.LIST:elink. command
will be invoked instead.  Aliases give you two ways to get around this
problem.
:p.
First, you could define an alias that runs the program in question, but with a
different name&colon.
:xmp.
        [c&colon.\] alias l = c&colon.\util\list.com
:exmp.:p.
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 :hp1.LIST.COM:ehp1. whenever you
type LIST&colon.
:xmp.
        [c&colon.\] alias display = *list
        [c&colon.\] alias list = c&colon.\util\list.com
:exmp.:p.
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
[:hp2.@:ehp2.] followed by a key name.  After you enter this next example,
you will see a 2-column directory with paging whenever you press
:hp2.Shift-F5:ehp2., then :hp2.Enter:ehp2.&colon.
:xmp.
        [c&colon.\] alias @Shift-F5 = *dir /2/p
:exmp.:p.
This alias will put the :link reftype=hd refid=DIR.DIR:elink. command on the
command line when you press :hp2.Shift-F5:ehp2., then wait for you to enter
file names or additional switches.  You must press :hp2.Enter:ehp2. when you
are ready to execute the command.  To execute the command immediately,
without displaying it on the command line or waiting for you to press
:hp2.Enter:ehp2., use two at signs at the start of the alias name&colon.
:xmp.
        [c&colon.\] alias @@Shift-F5 = *dir /2/p
:exmp.:p.
The next example clears the screen whenever you press :hp2.Alt-F1:ehp2.&colon.
:xmp.
        [c&colon.\] alias @@Alt-F1 = cls
:exmp.:p.
Aliases have many other capabilities as well.  This example creates a simple
command-line calculator using the :link reftype=hd refid=_@EVAL.@EVAL:elink.
function.  Once you have entered the example, you can type CALC 4*19, for
example, and you will see the answer&colon.
:xmp.
        [c&colon.\] alias calc = `echo The answer is&colon.  %@eval[%&amp.]`
:exmp.:p.
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&colon.
:xmp.
        [c&colon.\] alias in = `pushd %1 &amp. %2&amp. &amp. popd`
:exmp.:p.
Now if you type
:xmp.
        [c&colon.\] in c&colon.\letters wp letter.txt
:exmp.:p.
you will change to the :hp1.C&colon.\LETTERS:ehp1. subdirectory, execute the
command WP :hp1.LETTER.TXT:ehp1. and then return to the current directory.
:p.
The above example uses two parameters&colon.  %1 means the first argument on
the command line, and %2&amp. means the second and all subsequent arguments.
Parameters are explained in detail under the
:link reftype=hd refid=ALIAS.ALIAS:elink. command.
:p.
Your copy of &4OS2. includes a sample alias file called :hp1.ALIASES:ehp1.
which contains several useful aliases and demonstrates many alias techniques.
See the :link reftype=hd refid=ALIAS.ALIAS:elink. and :link reftype=hd
refid=UNALIAS.UNALIAS:elink. commands for more information and examples.  Also
see :link reftype=hd refid=BATCHALIAS.Using Aliases in Batch Files:elink..

.* --------------------------------------------------------------------------

:h1 name=Batch.Batch Files
:p.
A batch file is a file that contains a list of commands to
execute.  &4OS2. reads and interprets each line as if it had been
typed at the keyboard.  Like :link reftype=hd refid=ALIAS.aliases:elink.,
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.
:p.
The topics included in this section are&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=BatchType..BAT, .CMD, and .BTM Files:elink.
:pt.:pd.:link reftype=hd refid=BatchEcho.Echoing in Batch Files:elink.
:pt.:pd.:link reftype=hd refid=BatchParms.Batch File Parameters:elink.
:pt.:pd.:link reftype=hd refid=BatchEnv.Using Environment Variables:elink.
:pt.:pd.:link reftype=hd refid=BatchCommands.Batch File Commands:elink.
:pt.:pd.:link reftype=hd refid=BatchInt.Interrupting a Batch File:elink.
:pt.:pd.:link reftype=hd refid=AutoBatch.Automatic Batch Files (4START &amp. 4EXIT):elink.
:pt.:pd.:link reftype=hd refid=BatchDetect.Detecting &4OS2.:elink.
:pt.:pd.:link reftype=hd refid=BatchAlias.Using Aliases in Batch Files:elink.
:pt.:pd.:link reftype=hd refid=BatchDebug.Debugging Batch Files:elink.
:pt.:pd.:link reftype=hd refid=BatchString.Batch File String Processing:elink.
:pt.:pd.:link reftype=hd refid=BatchLineCont.Batch File Line Continuation:elink.
:pt.:pd.:link reftype=hd refid=BatchComp.Batch File Compression:elink.
:pt.:pd.:link reftype=hd refid=Compat.Special Character Compatibility:elink.
:pt.:pd.:link reftype=hd refid=Parsing.Command Parsing:elink.
:pt.:pd.:link reftype=hd refid=Quoting.Argument Quoting:elink.
:pt.:pd.:link reftype=hd refid=REXX.REXX Support:elink.
:pt.:pd.:link reftype=hd refid=EXTPROC.EXTPROC Support:elink.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=BatchType..BAT, .CMD, and .BTM Files
:p.
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), or for batch files which install memory-resident
utilities under DOS.
:p.
The batch file's extension determines its mode.  Files with a
:hp1..CMD:ehp1. extension are run in the slower, traditional mode.  Files
with a :hp1..BTM:ehp1. extension are run in the faster, more
efficient mode.  You can change the execution mode inside a batch
file with the :link reftype=hd refid=LOADBTM.LOADBTM:elink. command.

.* --------------------------------------------------------------------------

:h2 name=BatchEcho.Echoing in Batch Files
:p.
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&colon.
:lm margin=8.
:p.
Any batch file line that begins with an [:hp2.@:ehp2.] symbol will
not be displayed.
:p.
The display can be turned off and on within a batch file with
the :link reftype=hd refid=ECHO.ECHO:elink. OFF and ECHO ON commands.
:p.
The default setting can be changed with the :link reftype=hd
refid=SETDOS.SETDOS:elink. /V command, on the Options 1 page of the :link
reftype=hd refid=OPTION.OPTION:elink. dialogs, or the
:link reftype=hd refid=INI_BatchEcho.BatchEcho:elink. directive in
the :hp1..INI:ehp1. file.
:lm margin=1.
:p.
For example, the following line turns off echoing inside a batch
file.  The [:hp2.@:ehp2.] symbol keeps the batch file from displaying the
ECHO OFF command&colon.
:xmp.
        @echo off
:exmp.:p.
&4OS2. also has a command line echo that is unrelated to the batch
file echo setting.  See :link reftype=hd refid=ECHO.ECHO:elink. for details
about both settings.

.* --------------------------------------------------------------------------

:h2 name=BatchParms.Batch File Parameters
:p.
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 :hp2.parameters:ehp2. (also called :hp2.arguments:ehp2.
or :hp2.batch variables:ehp2.) 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.
:p.
These parameters are numbered from :hp2.%1:ehp2. to :hp2.%127:ehp2..  :hp2.%1:ehp2.
refers to the first parameter on the command line, :hp2.%2:ehp2. 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 :link reftype=hd refid=Quoting.Argument Quoting:elink. for details.
:p.
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 batch file to
:hp2.%3:ehp2., or any higher-numbered parameter, will be interpreted as an
empty string.
:p.
A batch file can also work with three special parameters&colon.  :hp2.%0:ehp2.
contains the name of the batch file as it was entered on the
command line, :hp2.%#:ehp2. contains the number of command line arguments,
and :hp2.%n$:ehp2. contains the complete command-line tail starting with
argument number ":hp2.n:ehp2." (for example, :hp2.%3$:ehp2. means the third
parameter and all those after it).  The default value of ":hp2.n:ehp2." is
1, so :hp2.%$:ehp2. contains the entire command tail.  The values of these
special parameters will change if you use the :link reftype=hd refid=SHIFT.SHIFT:elink.
command.
:p.
By default, 4DOS uses an ampersand [:hp2.&amp.:ehp2.] instead of a dollar sign
[:hp2.$:ehp2.] to indicate the remainder of the command tail.  For
example, :hp2.%&amp.:ehp2. means all the parameters, and :hp2.%2&amp.:ehp2.
means the second parameter and all those after it.  If you want to share
batch files or aliases between 4DOS and &4OS2., see :link reftype=hd
refid=Compat.Special Character Compatibility:elink. for
information on selecting compatible parameter characters for all products.
:p.
For example, if your batch file interprets the first argument as a
subdirectory name then the following line would move to the
specified directory&colon.
:xmp.
        cd %1
:exmp.:p.
A friendlier batch file would check to make sure the directory exists and
take some special action if it doesn't&colon.
:xmp.
        iff isdir %1 then &amp. cd %1
        else &amp. echo Subdirectory %1 does not exist! &amp. quit
        endiff
:exmp.:p.
(see the :link reftype=hd refid=IF.IF:elink. and
:link reftype=hd refid=IFF.IFF:elink. commands).
:p.
Batch files can also use :link reftype=hd refid=Environment.environment
variables:elink., :link reftype=hd refid=IntVars.internal variables:elink.,
and :link reftype=hd refid=VarFuncs.variable functions:elink..

.* --------------------------------------------------------------------------

:h2 name=BatchEnv.Using Environment Variables
:p.
Batch files can also use :link reftype=hd refid=Environment.environment
variables:elink., :link reftype=hd refid=IntVars.internal variables:elink.,
and :link reftype=hd refid=VarFuncs.variable functions:elink..
You can use these variables and functions to determine system status
(:hp1.e.g.:ehp1., the type of CPU in the system), resource levels
(:hp1.e.g.:ehp1., the amount of free disk space), file information
(:hp1.e.g.:ehp1., the date and time a file was last modified), and other
information (:hp1.e.g.:ehp1., 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 read and
write files.
:p.
To create temporary variables for use inside a batch file, just use the
:link reftype=hd refid=SET.SET:elink. 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,
:link reftype=hd refid=PATH_Var.PATH:elink. would be a bad choice), and use
the :link reftype=hd refid=UNSET.UNSET:elink. command to remove these
variables from the environment at the end of your batch file.  You
can use :link reftype=hd refid=SETLOCAL.SETLOCAL:elink. and
:link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink. to create a "local"
environment so that the original environment will be restored when your
batch file is finished.
:p.
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
%:link reftype=hd refid=_@EVAL.@EVAL:elink. to add a number to a text string),
you'll get an error message.

.* --------------------------------------------------------------------------

:h2 name=BatchCommands.Batch File Commands
:p.
Several &4OS2. commands are particularly suited to batch file processing.
Here is a list of some of the commands you might find most useful&colon.
:lm margin=8.:parml compact tsize=12 break=fit.
:pt.:link reftype=hd refid=ACTIVATE.ACTIVATE:elink.:pd.activates another
window.
:pt.:link reftype=hd refid=BEEP.BEEP:elink.:pd.produces a sound of any pitch
and duration through the computer's speaker.
:pt.:link reftype=hd refid=CALL.CALL:elink.:pd.executes one batch file from
within another.
:pt.:link reftype=hd refid=CANCEL.CANCEL:elink.:pd.terminates all batch file
processing.
:pt.:link reftype=hd refid=CLS.CLS:elink. and
:link reftype=hd refid=COLOR.COLOR:elink.:pd.set the screen display colors.
:pt.:link reftype=hd refid=DO.DO:elink.:pd.starts a loop.  The loop can be
based on a counter, or on a conditional test like those used in IF and IFF.
:pt.:link reftype=hd refid=DRAWBOX.DRAWBOX:elink.:pd.draws a box on the
screen.
:pt.:link reftype=hd refid=DRAWHLINE.DRAWHLINE:elink.
:link reftype=hd refid=DRAWVLINE.DRAWVLINE:elink.:pd.draw horizontal and
vertical lines on the screen.
:pt.:link reftype=hd refid=ECHO.ECHO:elink. and
:link reftype=hd refid=ECHOS.ECHOS:elink.:pd.print text on the screen
(the text can also be redirected to a file or
device).  :link reftype=hd refid=ECHO.ECHOERR:elink. and
:link reftype=hd refid=ECHOS.ECHOSERR:elink. print text to the standard
error device.
:pt.:link reftype=hd refid=GOSUB.GOSUB:elink.:pd.executes a subroutine
inside a batch file.  The :link reftype=hd refid=RETURN.RETURN:elink. command
terminates the subroutine.
:pt.:link reftype=hd refid=GOTO.GOTO:elink.:pd.branches to a different
location in the batch file.
:pt.:link reftype=hd refid=FOR.FOR:elink.:pd.executes commands for each file
that matches a set of wildcards, or each entry in a list.
:pt.:link reftype=hd refid=IF.IF:elink. and
:link reftype=hd refid=IFF.IFF:elink.:pd.execute commands based on a test of
string or numeric values, program exit codes, or other conditions.
:pt.:link reftype=hd refid=INKEY.INKEY:elink. and
:link reftype=hd refid=INPUT.INPUT:elink.:pd.collect keyboard input from the
user and store it in environment variables.
:pt.:link reftype=hd refid=KEYSTACK.KEYSTACK:elink.:pd.sends keystrokes to
applications.
:pt.:link reftype=hd refid=LOADBTM.LOADBTM:elink.:pd.changes the batch file
operating mode.
:pt.:link reftype=hd refid=ON.ON:elink.:pd.initializes error handling for
Ctrl-C / Ctrl-Break, or for program and command errors.
:pt.:link reftype=hd refid=PAUSE.PAUSE:elink.:pd.displays a message and waits
for the user to press a key.
:pt.:link reftype=hd refid=QUIT.QUIT:elink.:pd.ends the current batch file
and optionally returns an exit code.
:pt.:link reftype=hd refid=REM.REM:elink.:pd.places a remark in a batch file.
:pt.:link reftype=hd refid=SCREEN.SCREEN:elink.:pd.positions the cursor on
the screen and optionally prints a message at the new location.
:pt.:link reftype=hd refid=SCRPUT.SCRPUT:elink.:pd.displays a message in
color.
:pt.:link reftype=hd refid=SETLOCAL.SETLOCAL:elink.:pd.saves the current disk
drive, default directory, environment, alias list, and special character
settings.  :link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink. restores the
settings that were saved.
:pt.:link reftype=hd refid=SHIFT.SHIFT:elink.:pd.changes the numbering of the
batch file parameters.
:pt.:link reftype=hd refid=START.START:elink.:pd.starts another session or
window in certain multitasking environments.
:pt.:link reftype=hd refid=SWITCH.SWITCH:elink.:pd.selects a group of
statements to execute based on the value of a variable.
:pt.:link reftype=hd refid=TEXT.TEXT:elink.:pd.displays a block of
text.  :link reftype=hd refid=TEXT.ENDTEXT:elink. ends the block.
:pt.:link reftype=hd refid=TIMER.TIMER:elink.:pd.starts or reads a stopwatch.
:pt.:link reftype=hd refid=TITLE.TITLE:elink.:pd.changes the window title.
:pt.:link reftype=hd refid=VSCRPUT.VSCRPUT:elink.:pd.displays a vertical
message in color.
:eparml.:lm margin=1.
.br
These commands, along with the internal variables and variable functions,
make the enhanced batch file language extremely powerful.  Your copy of
&4OS2. includes a sample batch file, in the file :hp1.EXAMPLES.BTM,:ehp1. that
demonstrates some of the things you can do with batch files.
.* --------------------------------------------------------------------------

:h2 name=BatchInt.Interrupting a Batch File
:p.
You can usually interrupt a batch file by pressing :hp2.Ctrl-C:ehp2. or
:hp2.Ctrl-Break:ehp2..  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, and whether the
:link reftype=hd refid=ON.ON:elink. BREAK command is in use.
:p.
If &4OS2. detects a Ctrl-C or Ctrl-Break (and ON BREAK is not in use), it will
display a prompt, for example&colon.
:xmp.
        Cancel batch job C&colon.\CHARGE.BTM ? (Y/N/A) &colon.
:exmp.:p.
Enter :hp2.N:ehp2. to continue, :hp2.Y:ehp2. to terminate the current batch
file and continue with any batch file which called it, or :hp2.A:ehp2. to end
all batch file processing regardless of the batch file nesting
level.  Answering :hp2.Y:ehp2. is similar to the
:link reftype=hd refid=QUIT.QUIT:elink. command; answering :hp2.A:ehp2. is
similar to the :link reftype=hd refid=CANCEL.CANCEL:elink. command.

.* --------------------------------------------------------------------------

:h2 name=AutoBatch.Automatic Batch Files
:p.
&4OS2. supports "automatic" batch files, files that run without your
intervention, as long as the command processor can find them.
:p.
Each time &4OS2. starts as either a primary or a secondary shell, it
looks for an automatic batch file called :hp1.4START.BTM:ehp1.
or :hp1.4START.CMD:ehp1..  If the :hp1.4START:ehp1. batch file is not in the
same directory as &4OS2. itself, you should use the Startup page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs or the
:link reftype=hd refid=INI_4StartPath.4StartPath:elink. directive in your
:hp1..INI:ehp1. file to specify its location.  :hp1.4START:ehp1. is
optional, so &4OS2. will not display an error message if it cannot find the
file.
:p.
:hp1.4START:ehp1. is a convenient place to change the color or content of
the prompt for each shell, :link reftype=hd refid=LOG.LOG:elink. the start
of a shell, or put other special startup or configuration
commands.  :hp1.4START:ehp1. is also a good place to set
:link reftype=hd refid=ALIASES.aliases:elink. and
:link reftype=hd refid=ENVIRONMENT.environment variables:elink..
:p.
The entire startup command line passed to the command processor is available to :hp1.
4START:ehp1. via
:link reftype=hd refid=BatchParms.batch file parameters:elink.
(%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
:hp1.4START:ehp1. (enter this on one line)&colon.
:xmp.
        if "%1" != "" .and. "%_shell" gt 0 pause Starting shell
        %_shell with parameters [%$]
:exmp.:p.
Whenever a &4OS2. shell ends, it runs an automatic batch file called
:hp1.4EXIT.BTM:ehp1., :hp1.4EXIT.CMD:ehp1..  This file, if you use it,
should be in the same directory as your :hp1.4START:ehp1. batch file.  Like
:hp1.4START:ehp1., :hp1.4EXIT:ehp1. 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
:link reftype=hd refid=LOG.LOG:elink. the end of the shell.
:p.
:p.
:hp2.Pipes, Transient Sessions, and 4START:ehp2.
:p.
When you set up the 4START file, remember that it is executed
:hp2.every:ehp2. time &4OS2. starts, including when running a :link reftype=hd
refid=Piping.pipe:elink., or a transient copy of the command processor
started with the :hp2./C:ehp2. :link reftype=hd refid=Startup.startup:elink.
option.
:p.
For example, suppose you enter a command line like this, which uses a pipe:
:xmp.
        [c&colon.\data] myprog | sort > out.txt
:exmp.:p.
Normally this command would create the output file
:hp1.C&colon.\DATA\OUT.TXT:ehp1..  However, if you have a 4START file which
changes to a different directory, the output file will be written there -- not
in :hp1.C&colon.\DATA:ehp1..
:p.
This is because the command processor starts a second copy of itself to run
the commands on the right hand side of the pipe, and that new copy runs
4START before processing the commands from the pipe.  If 4START changes
directories, the command from the pipe will be executed in the new directory.
:p.
The same problem can occur if you use a transient session started with /C to
run an individual command, then exit -- the session will execute in the
directory set by 4START, not the directory in which it was originally
started.  For example, suppose you set up an OS/2 desktop object with a
command line like this, which starts a transient session:
:xmp.
        Command:            d&colon.\&4OS2.\&4OS2..exe /c list myfile.txt
        Working Directory:  c&colon.\data
:exmp.:p.
Normally this command would :link reftype=hd refid=LIST.LIST:elink. the file
:hp1.C&colon.\DATA\MYFILE.TXT:ehp1..  However, if 4START changes to a different
directory, the command processor will look for :hp1.MYFILE.TXT:ehp1. there
-- not in :hp1.C&colon.\DATA:ehp1..
:p.
Similarly, any changes to environment variables or other settings in 4START
will affect all copies of the command processor, including those used for
pipes and transient sessions.
:p.
You can work around these potential problems with the :link reftype=hd
refid=IF.IF:elink. or :link reftype=hd refid=IFF.IFF:elink. command and
the internal variables :link reftype=hd refid=_PIPE._PIPE:elink. and
:link reftype=hd refid=_TRANSIENT._TRANSIENT:elink..  For example, to skip
all 4START processing when running in a pipe or transient session, you could
use a command like this at the beginning of 4START:
:xmp.
        if %_pipe != 0 .or. %_transient != 0 quit
:exmp.

.* --------------------------------------------------------------------------

:h2 name=BatchDetect.Detecting &4OS2.
:p.
From a batch file, you can determine if &4OS2. or Take Command is loaded by
testing for the variable function :link reftype=hd refid=_@EVAL.@EVAL:elink.,
with a test like this&colon.
:xmp.
        if "%@eval[2 + 2]%" == "4" echo &4OS2. is loaded!
:exmp.:p.
This test can never succeed in :hp1.CMD.EXE.:ehp1.  Other variable functions
could be used for the same purpose.

.* --------------------------------------------------------------------------

:h2 name=BatchAlias.Using Aliases in Batch Files
:p.
One way to simplify batch file programming is to use aliases to hide
unnecessary detail inside a batch file.  For example, suppose you want a
batch file to check for certain errors, and display a message and exit if
one is encountered.  This example shows one way to do so&colon.
:xmp.
        setlocal
        unalias *
        alias error `echo. &amp. echo ERROR&colon. %$ &amp. goto dispmenu`
        alias fatalerror `echo. &amp. echo FATAL ERROR&colon. %$ &amp. quit`
        alias in `pushd %1 &amp. %2$ &amp. popd`
        if not exist setup.btm fatalerror Missing setup file!
        call setup.btm
        cls
        &colon.dispmenu
        text
                  1. Word Processing
                  2. Spreadsheet
                  3. Communications
                  4. Exit
        endtext
        echo.
        inkey Enter your choice&colon.  %%userchoice
        switch %userchoice
        case 1
           input Enter the file name&colon.  %%fname
           if not exist fname error File does not exist
           in d&colon.\letters c&colon.\wp60\wp.exe
        case 2
           in d&colon.\finance c&colon.\quattro\q.exe
        case 3
           in d&colon.\comm c&colon.\comsw\pcplus.exe
        case 4
           goto done
        default
          error Invalid choice, try again
        endswitch
        goto dispmenu
        &colon.done
        endlocal
:exmp.:p.
The first alias, ERROR, simply displays an error message and jumps to the label
DISPMENU to redisplay the menu.  The "%$" in the second
:link reftype=hd refid=ECHO.ECHO:elink. command displays all the text passed
to ERROR as the content of the message.  The similar FATALERROR alias
displays the message, then exits the batch file.
:p.
The last 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
:link reftype=hd refid=PUSHD.PUSHD:elink. command.  The rest of the command
line is interpreted as another command plus possible command line parameters,
which the alias executes.  This alias is used here to switch to a directory,
run an application, and switch back.  It could also be used from the
command line.
:p.
The following lines print a menu on the screen and then get a keystroke from
the user and store the keystroke in an environment variable called
:hp1.userchoice:ehp1..  Then the :link reftype=hd refid=SWITCH.SWITCH:elink.
command is used to test the user's keystroke and decide what action to take.
:p.
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 :link reftype=hd refid=CD.CD:elink. to
:link reftype=hd refid=CDD.CDD:elink. and you aren't expecting this, your
file may not work as you intended.  There are two ways to address this
problem.
:p.
First, you can use :link reftype=hd refid=SETLOCAL.SETLOCAL:elink.,
:link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink., and
:link reftype=hd refid=UNALIAS.UNALIAS:elink. to clear out aliases before
your batch file starts and restore them at the end, as we did in the previous
example.  Remember that SETLOCAL and ENDLOCAL will save and restore not only
the aliases but also the environment, the current drive and directory, and
various special characters.
:p.
If this method isn't appropriate or necessary for the batch file you're
working on, you can also use an asterisk [:hp2.*:ehp2.] 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 :hp1.FILELIST:ehp1.&colon.
:xmp.
        dir /b > filelist
:exmp.:p.
However, if the user has redefined :link reftype=hd refid=DIR.DIR:elink.
with an alias this command may not do what you want.  To get around this
just use&colon.
:xmp.
        *dir /b > filelist
:exmp.:p.
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.

.* --------------------------------------------------------------------------

:h2 name=BatchDebug.Debugging Batch Files
:p.
&4OS2. includes a built-in batch file debugger, invoked with
the :link reftype=hd refid=SETDOS.SETDOS:elink. /Y1 command.  The debugger
allows you to "single-step" through a batch file line by line, with the file
displayed in a popup window as it executes.  You can execute or skip the
current line, continue execution with the debugger turned off, view the
fully-expanded version of the command line, or exit the batch file.  The
batch debugger can also pop up a separate window to view current environment
variables or aliases so you can check their values during execution, and can
pop up the :link reftype=hd refid=LIST.LIST:elink. command to display the
contents of any file.
:p.
To start the debugger, insert a :link reftype=hd refid=SETDOS.SETDOS:elink.
/Y1 command at the beginning of the portion of the batch file you want to
debug, and a SETDOS /Y0 command at the end.  You can also invoke SETDOS /Y1
from the prompt, but because the debugger is automatically turned off
whenever the command processor returns to the prompt, you must enter the
SETDOS command and the batch file name on the same line, for example&colon.
:xmp.
        [c&colon.\] setdos /y1 &amp. mybatch.btm
:exmp.:p.
If you use the debugger regularly you may want to define a simple alias to
invoke it, for example&colon.
:xmp.
        [c&colon.\] alias trace `setdos /y1 &amp. %$`
:exmp.:p.
This alias simply enables the debugger, then runs whatever command is
passed to it.  You can use the alias to debug a batch file with a command
like this&colon.
:xmp.
        [c&colon.\] trace mybatch.btm
:exmp.:p.
When the debugger is running you can control its behavior with keystrokes.
Debugging continues after each keystroke unless otherwise noted&colon.
:lm margin=8.:parml compact tsize=15 break=fit.
:pt.:hp2.T:ehp2.(race), :hp2.Enter:ehp2., or :hp2.F8:ehp2.:pd.Execute the
current command.  If it calls a subroutine with
:link reftype=hd refid=GOSUB.GOSUB:elink., or another batch file with
:link reftype=hd refid=CALL.CALL:elink., single-step into the called
subroutine or batch file.
:pt.:hp2.S:ehp2.(tep) or :hp2.F10:ehp2.:pd.Execute the current command, but
execute any subroutine or :link reftype=hd refid=CALL.CALL:elink.ed batch
file without single-stepping.
:pt.:hp2.J:ehp2.(ump):pd.Skip the current command and proceed to the next
command.
:pt.:hp2.X :ehp2.(Expand):pd.Display the next command to be executed, after
expansion of aliases and environment variables.
:pt.:hp2.L:ehp2.(ist):pd.Prompt for a file name and then view the file with
the :link reftype=hd refid=LIST.LIST:elink. command.
:pt.:hp2.V:ehp2.(ariables):pd.Open a popup window to display the current
environment, in alphabetical order.
:pt.:hp2.A:ehp2.(liases):pd.Open a popup window to display the current
aliases, in alphabetical order.
:pt.:hp2.O:ehp2.(ff) or :hp2.Esc:ehp2.:pd.Turn off the debugger and continue
with the remainder of the batch file.
:pt.:hp2.Q:ehp2.(uit):pd.Quit the debugger and the current batch file,
without executing the remainder of the file.
:eparml.:lm margin=1.
.br
The debugger highlights each line of the batch file as it is executed.  It
executes the commands on the line one at a time, so when a line contains more
than one command, the highlight will not move as each command is
executed.  To see the individual commands, use the :hp2.X:ehp2. key to
expand each command before it is executed.
:p.
If you use a "prefix" command like
:link reftype=hd refid=EXCEPT.EXCEPT:elink.,
:link reftype=hd refid=FOR.FOR:elink.,
:link reftype=hd refid=GLOBAL.GLOBAL:elink.,
or :link reftype=hd refid=SELECT.SELECT:elink., the prefix command is
considered one command, and each command it invokes is another.  For example,
this command line executes four commands -- the
:link reftype=hd refid=FOR.FOR:elink. and three
:link reftype=hd refid=ECHO.ECHO:elink. commands&colon.
:xmp.
        for %x in (a b c) do echo %x
:exmp.:p.
You cannot use the batch debugger with :link reftype=hd
refid=REXX.REXX:elink. files or :link reftype=hd
refid=EXTPROC.EXTPROC:elink. files.  It can only be used with normal &4OS2.
batch files.
:p.
The debugger gives you a detailed, step-by-step view of batch file execution,
and will help solve particularly difficult batch file problems.  However, in
some cases you will find it easier to diagnose these problems with techniques
that allow you to review what is happening at specific points in the batch
file without stepping through each line individually.
:p.
There are several tricks you can use for this purpose.  Probably the simplest
is to turn :link reftype=hd refid=ECHO.ECHO:elink. on at the beginning of the
file while you're testing it, or use
:link reftype=hd refid=SETDOS.SETDOS:elink. /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, without stopping at each line.  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.
:p.
If an error occurs in a batch file, the error message will display the name
of the file, the number of the line that contained the error, and the error
itself.  For example&colon.
:xmp.
        e&colon.\test.bat [3] Invalid parameter "/d"
:exmp.:p.
tells you that the file :hp1.E&colon.\TEST.BAT:ehp1. contains an error on
line 3.  The first line of the batch file is numbered 1.
:p.
Another trick, especially useful in a fast-moving batch file or one where the
screen is cleared before you can read messages, is to insert
:link reftype=hd refid=PAUSE.PAUSE:elink. commands wherever you need them in
order to be able to watch what's happening.  You can also use an
:link reftype=hd refid=ON.ON:elink. ERRORMSG command to pause if an error
occurs, then continue with the rest of the file (the first command below),
or to quit if an error occurs (the second command)&colon.
:xmp.
        on errormsg pause
        on errormsg quit
:exmp.:p.
If you can't figure out how your aliases and variables are expanded, try
turning :link reftype=hd refid=LOG.LOG:elink. 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.  You must use a standard LOG command; LOG /H
(the history log) does not work in batch files.
:p.
You may also want to consider using
:link reftype=hd refid=Redirection.redirection:elink. to capture your batch
file output.  Simply type the batch file name followed by the redirection
symbols, for example&colon.
:xmp.
        [c&colon.\] mybatch >&amp. testout
:exmp.:p.
This records all batch file output, including error messages, in the file
:hp1.TESTOUT:ehp1., so you can go back and examine it.  If you have
:link reftype=hd refid=ECHO.ECHO:elink. 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
produces any output.
:p.
If you're using :link reftype=hd refid=Redirection.redirection:elink. 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.  You can also use the
:link reftype=hd refid=TEE.TEE:elink. command to both view the output while
the batch file is running and save it in a file for later examination.

.* --------------------------------------------------------------------------

:h2 name=BatchString.Batch File String Processing
:p.
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.
:p.
&4OS2. include several features that make string processing easier.  For
example, you can use the :link reftype=hd refid=INKEY.INKEY:elink. and
:link reftype=hd refid=INPUT.INPUT:elink. commands for user input;
the :link reftype=hd refid=ECHO.ECHO:elink.,
:link reftype=hd refid=SCREEN.SCREEN:elink.,
:link reftype=hd refid=SCRPUT.SCRPUT:elink., and
:link reftype=hd refid=VSCRPUT.VSCRPUT:elink. commands for output; and the
:link reftype=hd refid=FOR.FOR:elink. command or the
:link reftype=hd refid=_@FILEREAD.@FILEREAD:elink. function to scan through
the lines of a file.  In addition,
:link reftype=hd refid=VarFuncs.variable functions:elink. offer a wide range
of string handling capabilities.
:p.
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
:hp2./F&colon.first /L&colon.last:ehp2. 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&colon.
:xmp.
        @echo off
        setlocal
        unalias *
        input Enter your name (no initials)&colon.  %%name

        set first=%@word[0,%name]
        set flen=%@len[%first]
        set last=%@word[1,%name]
        set llen=%@len[%last]

        iff %flen gt 8 .or. %llen gt 8 then
           echo First or last name too long
           quit
        endiff

        login /F&colon.%@upper[%first] /L&colon.%@upper[%last]
        endlocal
:exmp.:p.
The :link reftype=hd refid=SETLOCAL.SETLOCAL:elink. command at the beginning
of this batch file saves the environment and aliases.  Then the
:link reftype=hd refid=UNALIAS.UNALIAS:elink. * command removes any existing
aliases so they won't interfere with the behavior of the commands in the remainder of the batch
file.  The first block of lines ends with an
:link reftype=hd refid=INPUT.INPUT:elink. command which asks the user
to enter a name.  The user's input is stored in the environment variable NAME.
:p.
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 :link reftype=hd refid=_@WORD.@WORD:elink.
function numbers the first word as 0, not as 1.
:p.
The :link reftype=hd refid=IFF.IFF:elink. 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
:link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink. 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.).
:p.
When you're processing strings, you also need to avoid some common
traps.  The biggest one is handling special characters.
:p.
Suppose you have a batch file with these two commands, which simply accept a
string and display it&colon.
:xmp.
        input Enter a string&colon.  %%str
        echo %str
:exmp.:p.
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:
:xmp.
        echo some > none
:exmp.:p.
The ">" is a :link reftype=hd refid=Redirection.redirection:elink. 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
to avoid this kind of problem
(see :link reftype=hd refid=Quoting.Argument Quoting:elink.), 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 when they are inside back-quotes.
:p.
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&colon.
:xmp.
        "some > none"
:exmp.:p.
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 :link reftype=hd refid=Redirection.redirection:elink.
symbols can be virtually impossible to handle correctly.
:p.
One way to overcome these potential problems is to use the
:link reftype=hd refid=SETDOS.SETDOS:elink. /X command 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&colon.
:xmp.
        setdos /x-15678
        input Enter a string&colon.  %%str
        echo %str
        setdos /x0
:exmp.:p.
The first line turns off :link reftype=hd refid=Aliases.alias:elink.
processing and disables several special symbols, including the command
separator (see :link reftype=hd refid=MultCmds.Multiple Commands:elink.)
and all :link reftype=hd refid=RedirPipe.redirection:elink.
symbols.  Once the string has been processed, the last line re-enables the
features that were turned off in the first line.
:p.
If you need advanced string processing capabilities beyond those provided by
&4OS2. you may want to consider using the
:link reftype=hd refid=REXX.REXX:elink. language.  Our products support
external REXX programs for this purpose.

.* --------------------------------------------------------------------------

:h2 name=BatchLineCont.Batch File Line Continuation
:p.
&4OS2. will combine multiple lines in the batch file into a single line for
processing when you include the
:link reftype=hd refid=Escape.escape character:elink.
as the very last character of each line to be combined (except the last).
The default escape character is the caret [:hp2.^:ehp2.].  For example&colon.
:xmp.
        echo The quick brown fox jumped over the lazy^
        sleeping^
        dog. > alphabet
:exmp.:p.
You cannot use this technique to extend a batch file line beyond the normal
line length limit of 1,023 characters.

.* --------------------------------------------------------------------------

:h2 name=BatchComp.Batch File Compression
:p.
You can compress your batch files with a program called
:hp1.BATCOMP.EXE:ehp1., which is distributed with &4OS2..  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.
:p.
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.
:p.
The full syntax for the batch compression program is
:xmp.
        BATCOMP [/O] :hp1.input file:ehp1. [:hp1.output file:ehp1. ]
:exmp.:p.
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 :hp1..BTM:ehp1. extension.  BATCOMP will also add a :hp1..BTM:ehp1.
extension if you specify a base name for the output file without an
extension.  For example, to compress :hp1.MYBATCH.CMD:ehp1. and save the
result as :hp1.MYBATCH.BTM:ehp1., you can use any of these three commands&colon.
:xmp.
        [c&colon.\] batcomp mybatch.cmd
        [c&colon.\] batcomp mybatch.cmd mybatch
        [c&colon.\] batcomp mybatch.cmd mybatch.btm
:exmp.:p.
If the output file (:hp1.MYBATCH.BTM:ehp1. in the examples above) already
exists, BATCOMP will prompt you before overwriting the file.  You
can disable the prompt by including :hp2./O:ehp2. 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.
:p.
JP Software does not provide a decompression utility to decompress
batch files.  If you use :hp1.BATCOMP.EXE:ehp1., make sure that you also
keep a copy of the original batch file for future inspection or
modification.
:p.
BATCOMP is a DOS and OS/2 character-mode application designed to run in any
environment where our command processors run.  Each of our command
processors includes the same version of :hp1.BATCOMP.EXE:ehp1., and a batch
file compressed with any copy of BATCOMP can be used with any current JP
Software command processor.
:p.
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 :hp1..BAT:ehp1. or :hp1..CMD:ehp1. extension and
reserve the :hp1..BTM:ehp1. 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 :link reftype=hd refid=LOADBTM.LOADBTM:elink.
command.
:p.
If you prefer, you can use a :hp1..BTM:ehp1. extension for both the source
and compressed files.  In this case you will have to use a different
directory or a different base name for each file.  For example, you might
use :hp1.SOURCE\MYBATCH.BTM:ehp1. for the source file and
:hp1.COMP\MYBATCH.BTM:ehp1. for the compressed version, or use
:hp1.MYBATCHS.BTM:ehp1. for the source file and :hp1.MYBATCH.BTM:ehp1. for
the compressed file (however, the latter approach may make it more difficult
to keep track of the correspondence between the source file and the
compressed file).
:p.
Each of our command processors includes its own version of
:hp1.BATCOMP.EXE:ehp1., set up to run under the corresponding operating
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.
:p.
If you plan to distribute batch files to users of different
platforms, see :link reftype=hd
refid=Compat.Special Character Compatibility:elink..

.* --------------------------------------------------------------------------

:h2 name=Compat.Special Character Compatibility
:p.
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&colon.  the
Command Separator (see :link reftype=hd refid=MultCmds.Multiple Commands:elink.), the Escape
Character (see :link reftype=hd refid=Escape.Escape Character:elink.), and the Parameter
Character (see :link reftype=hd refid=BatchParms.Batch File Parameters:elink.).
:p.
The default values of each of these characters in each product is
shown in the following chart&colon.
:xmp.
        Product                  Separator     Escape     Parameter

        4DOS, Take Command/16        ^           &uarrow.            &amp.

        4NT, &4OS2.,                   &amp.           ^            $
        Take Command/32,
        Take Command for OS/2
:exmp.:p.
The up-arrow [:hp2.&uarrow.:ehp2.] represents the ASCII Ctrl-X character,
numeric value 24.)
:p.
In your batch files and aliases, and even at the command line, you
can smooth over these differences in three ways&colon.
:lm margin=8.:parml tsize=4 break=fit.
:pt.*:pd.Select a consistent set of characters from the Options 1 page of the
:link reftype=hd refid=OPTION.OPTION:elink. dialogs, or with :hp1..INI:ehp1.
file :link reftype=hd refid=INIConfig.configuration directives:elink.
command.  For example, to set the &4OS2. characters to match 4DOS, use these
lines in :hp1.&4OS2INI.:ehp1.&colon.
:xmp.
        CommandSep = ^
        EscapeChar = &uarrow.
        ParameterChar = &amp.
:exmp.:p.
:pt.*:pd.Use internal variables that contain the current special
character, rather than using the character itself (see
:link reftype=hd refid=PLUS.+:elink. and :link reftype=hd refid=EQUALS.=:elink.).  For example, this command&colon.
:xmp.
        if "%1" == "" (echo Argument missing! ^ quit)
:exmp.:p.
will only work if the command separator is a caret. However, this version works regardless
of the current command separator&colon.
:xmp.
        if "%1" == "" (echo Argument missing! %+ quit)
:exmp.
:pt.*:pd.In a batch file, use the :link reftype=hd
refid=SETLOCAL.SETLOCAL:elink. command to save the command separator, escape
character, and parameter character when the batch file starts.  Then use
:link reftype=hd refid=SETDOS.SETDOS:elink. as described above to select the
characters you want to use within the batch file.  Use an
:link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink. command at the end of the
batch file to restore the previous settings.
:eparml.:lm margin=1.
.br
You can also use the SETDOS command to change special characters on the
command line.  However, when setting new special character values on the
command line you must take into account the possibility that one of your new
values will have a current meaning that causes problems with the setting.  For
example, this command&colon.
:xmp.
        [c&colon.\] setdos /p&amp.
:exmp.:p.
would :hp2.not:ehp2. set the parameter character to an ampersand
[:hp2.&amp.:ehp2.] in &4OS2. if the standard &4OS2. special characters were
currently in effect.  The :hp2.&amp.:ehp2. would be seen as a command
separator, and would terminate the SETDOS command before the parameter
character was set.  To work around this, use the escape character variable
:hp2.%=:ehp2. before each setting to ensure that the following character is
not treated with any special meaning.
:p.
For example, the following sequence of commands in a batch file will always
set the special characters correctly to their standard 4DOS values, no
matter what their current setting, and will restore them when the batch file
is done&colon.
:xmp.
        setlocal
        setdos /c%=^ /e%=&uarrow. /p%=&amp.
        .....
        endlocal
:exmp.:p.
A similar sequence can be used to select the standard &4OS2. and 4NT
characters, regardless of the current settings&colon.
:xmp.
        setlocal
        setdos /c%=&amp. /e%=^ /p%=$
        .....
        endlocal
:exmp.

.* --------------------------------------------------------------------------

:h2 name=Parsing.Command Parsing
:p.
Whenever you type something at the command line and press the
:hp2.Enter:ehp2. key, or include a command in a batch file, you have given a
command to &4OS2., 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.
:p.
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 :link reftype=hd refid=LOG.LOG:elink. /H
command, and the command did not come from a batch file.  Then, if the line
contains multiple commands, the first command is isolated for processing.
:p.
&4OS2. begins by dividing the command into a :hp2.command name:ehp2. and a
:hp2.command tail:ehp2..  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
:xmp.
        dir *.txt /2/p/v
:exmp.:p.
the command name is "dir", and the command tail is " *.txt /2/p/v".
:p.
Next 4DOS 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).  However,
you can view a command line with aliases expanded by pressing
:hp2.Ctrl-F:ehp2. after entering the command at the prompt.
:p.
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 :hp2.alias expansion:ehp2..
:p.
This expansion of an alias creates a new command name&colon.  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 :hp2.nested alias
expansion:ehp2., continues until the command name no longer refers to an
alias.
:p.
Once it has finished with the aliases, &4OS2. 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.
:p.
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 :hp2.variable
expansion:ehp2..
:p.
The variable expansion process is modified for certain internal commands,
like :link reftype=hd refid=EXCEPT.EXCEPT:elink., :link reftype=hd
refid=IF.IF:elink., and :link reftype=hd refid=GLOBAL.GLOBAL:elink..  These
commands are always followed by another command, so variable expansion takes
place separately for the original command and the command that follows it.
:p.
Once all of the aliases and environment variables have been expanded, &4OS2.
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).
:p.
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.  A second process is started at this
point, if necessary, to receive any piped output.
:p.
Finally, it is time to execute the command.  If the command name matches an
internal command, &4OS2. will perform the activities you have
requested.  Otherwise, the command processor searches for an executable
(:hp1..COM:ehp1. or :hp1..EXE:ehp1.) file, a batch file, or a file with an
executable extension that matches the command name.
:p.
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.
:p.
You can disable and re-enable several parts of command parsing (for example
alias expansion, variable expansion, and redirection) with the :link
reftype=hd refid=SETDOS.SETDOS:elink. /X command.

.* --------------------------------------------------------------------------

:h2 name=Quoting.Argument Quoting
:p.
As it parses the command line, &4OS2. looks for the ampersand [:hp2.&amp.:ehp2.] command
separator, conditional commands (:hp2.&splitvbar.&splitvbar.:ehp2. or
:hp2.&amp.&amp.:ehp2.), white space (spaces, tabs, and commas), percent
signs [:hp2.%:ehp2.] which indicate variables to be expanded, and
redirection and piping characters (:hp2.>:ehp2., :hp2.<:ehp2., or
:hp2.&splitvbar.:ehp2.).
:p.
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 single back
quotes [:hp2.`:ehp2.] or double quotes [:hp2.":ehp2.].  Although both
back quotes and double quotes will let you build arguments that include
special characters, they do not work the same way.
:p.
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.
:p.
No alias expansion is performed on expressions enclosed in double
quotes.  Redirection symbols inside double quotes are ignored.
However, variable expansion :hp2.is:ehp2. performed on expressions inside
double quotes.  The double quotes themselves will be passed to the
command as part of the argument.
:p.
For example, suppose you have a batch file :hp1.CHKNAME.BTM:ehp1. 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&colon.
:xmp.
        [c&colon.\] chkname `MY NAME`
:exmp.:p.
Inside the batch file, %1 will have the value MY NAME, including
the space.  The back quotes caused &4OS2. to pass the string to the
batch file as a single argument.  The quotes keep characters together and
reduce the number of arguments in the line.
:p.
For a more complex example, suppose the batch file :hp1.QUOTES.BAT:ehp1.
contains the following commands&colon.
:xmp.
        @echo off
        echo Arg1 = %1
        echo Arg2 = %2
        echo Arg3 = %3
:exmp.:p.
and that the environment variable FORVAR has been defined with this
command&colon.
:xmp.
        [c&colon.\] set FORVAR=for
:exmp.:p.
Now, if you enter the command
:xmp.
        [c&colon.\] quotes `Now is the time %%forvar` all good
:exmp.:p.
the output from :hp1.QUOTES.BAT:ehp1. will look like this&colon.
:xmp.
        Arg1 = Now is the time %forvar
        Arg2 = all
        Arg3 = good
:exmp.:p.
But if you enter the command
:xmp.
        [c&colon.\] quotes "Now is the time %%forvar" all good
:exmp.:p.
the output from :hp1.QUOTES.BAT:ehp1. will look like this&colon.
:xmp.
        Arg1 = "Now is the time for"
        Arg2 = all
        Arg3 = good
:exmp.:p.
Notice that in both cases, the quotes keep characters together and reduce the
number of arguments in the line.
:p.
The following example has 7 command-line arguments, while the examples above
only have 3&colon.
:xmp.
        [c&colon.\] quotes Now is the time %%forvar all good
:exmp.:p.
(The double percent signs are needed in each case because the argument is
parsed twice, once when passed to the batch file and again in the ECHO
command.)
:p.
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 :link reftype=hd
refid=ALIAS.ALIAS:elink. for details.
:p.
You can disable and re-enable back quotes and double quotes with
the :link reftype=hd refid=SETDOS.SETDOS:elink. /X command.

.* --------------------------------------------------------------------------

:h2 name=REXX.REXX Support
:p.
REXX is a a powerful file and text processing language developed by
IBM, and available on many PC and other platforms.  REXX is an ideal
extension to the &4OS2. batch language, especially if you need advanced
string processing capabilities.
:p.
The REXX language is not built into &4OS2..  REXX language support is provided
in OS/2 2.0 and above, and you can also purchase add-on REXX software such
as Enterprise Alternatives' Enterprise REXX, available for Windows 3.x,
Windows 95, and Windows NT; or Quercus's Personal REXX, available for DOS,
OS/2, Windows 3.x, Windows 95, and Windows NT.  (If you want to learn about
or purchase one of these REXX packages, contact JP Software's sales
department for more information.)
:p.
REXX programs are stored in :hp1..CMD:ehp1. files.  &4OS2. checks to see if
the first two characters on the first line of a :hp1..CMD:ehp1. file are
[:hp2./*:ehp2.], 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..
:p.
Both Personal REXX and OS/2's built-in REXX extend the interface
between REXX and &4OS2. by allowing you to invoke &4OS2. commands from within a
REXX program.
:p.
When you send a command from a REXX program back to the command processor to
be executed (for example, if you execute a :link reftype=hd
refid=DIR.DIR:elink. command within a REXX script), the REXX software must
use the correctaddre for the command processor.  In most cases it is best to
use the default address of :hp2.CMD:ehp2., which is set up automatically by
&4OS2..  If you choose to use an explicit address via the REXX ADDRESS
command, you can use either :hp2.CMD:ehp2. or :hp2.&4OS2.:ehp2..
:p.
For details on communication between REXX and the command processor, or for
more information on any aspect of REXX, see your REXX documentation.

.* --------------------------------------------------------------------------

:h2 name=EXTPROC.EXTPROC Support
:p.
For compatiblility with :hp1.CMD.EXE:ehp1., &4OS2. offers an external
processor (EXTPROC) option for batch files that lets you define an external
program to process a particular :hp1..CMD:ehp1. file.  To identify a
:hp1..CMD:ehp1. 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.  &4OS2. will start
the program and pass it the name of the :hp1..CMD:ehp1. file and any
command-line arguments that were entered.
:p.
For example, suppose :hp1.GETDATA.CMD:ehp1. contains the following lines&colon.
:xmp.
        EXTPROC D&colon.\DATAACQ\DATALOAD.EXE
        OPEN PORT1
        READ 4000
        DISKWRITE D&colon.\DATAACQ\PORT1\RAW
:exmp.:p.
Then if you entered the command&colon.
:xmp.
        [d&colon.\dataacq] getdata /p17
:exmp.:p.
&4OS2. would read the :hp1.GETDATA.CMD:ehp1. file, determine that it began
with an EXTPROC command, read the name of the processor program,
and then execute the command&colon.
:xmp.
        D&colon.\DATAACQ\DATALOAD.EXE D&colon.\DATAACQ\GETDATA.CMD /p17
:exmp.:p.
The hypothetical :hp1.DATALOAD.EXE:ehp1. program would then be responsible
for reopening the :hp1.GETDATA.CMD:ehp1. 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).
:p.
Do not try to use &4OS2. or Take Command as the external processor named on the
EXTPROC line in the :hp1..CMD:ehp1. file.  It 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.

.* --------------------------------------------------------------------------

:h1 name=Environment.Environment Variables and Functions
:p.
The :hp2.environment:ehp2. 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 [:hp2.%:ehp2.] and a variable name on the command
line or in an alias or batch file.
:p.
The following environment variables have special meanings in &4OS2.&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=CDPATH.CDPATH:elink.
:pt.:pd.:link reftype=hd refid=CMDLINE.CMDLINE:elink.
:pt.:pd.:link reftype=hd refid=COLORDIR_Var.COLORDIR:elink.
:pt.:pd.:link reftype=hd refid=COMSPEC.COMSPEC:elink.
:pt.:pd.:link reftype=hd refid=FILECOMPLETION.FILECOMPLETION:elink.
:pt.:pd.:link reftype=hd refid=PATH_Var.PATH:elink.
:pt.:pd.:link reftype=hd refid=PATHEXT.PATHEXT:elink.
:pt.:pd.:link reftype=hd refid=PROMPT_Var.PROMPT:elink.
:eparml.:lm margin=1.
.br
&4OS2. also supports two special types of
variables.  :link reftype=hd refid=IntVars.Internal variables:elink.
are similar to environment variables, but are
stored internally within &4OS2., and are not visible in the
environment.  They provide information about your system for use in
batch files and aliases.  :link reftype=hd refid=VarFuncs.Variable
functions:elink. are referenced like environment variables, but perform
additional functions like file handling, string manipulation and arithmetic
calculations.
:p.
In &4OS2. the size of the environment is set automatically, and increased as
needed when you add variables.
:p.
The :link reftype=hd refid=SET.SET:elink. command is used to create environment variables.
For example, you can create a variable named BACKUP like this&colon.
:xmp.
        [c&colon.\] set BACKUP=*.bak;*.bk!;*.bk
:exmp.:p.
If you then type
:xmp.
        [c&colon.\] del %BACKUP
:exmp.:p.
it is equivalent to the following command&colon.
:xmp.
        del *.bak;*.bk!;*.bk
:exmp.:p.
Environment variable names may contain any alphabetic or numeric characters,
the underscore character [:hp2._:ehp2.], and the
dollar sign [:hp2.$:ehp2.].  You can force acceptance of other characters
by including the full variable name in square brackets, like this&colon.
:hp2.%[AB##2]:ehp2..  You can also "nest" environment variables using
square brackets.  For example :hp2.%[%var1]:ehp2. 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
:link reftype=hd refid=SETDOS.SETDOS:elink. /X command.
:p.
Environment variables may contain
:link reftype=hd refid=ALIASES.alias:elink. 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 :hp1..TXT:ehp1. files&colon.
:xmp.
        [c&colon.\] alias d2 dir /2
        [c&colon.\] set cmd=d2
        [c&colon.\] %cmd *.txt
:exmp.:p.
The trailing percent sign that was traditionally required for
environment variable names is not usually required in &4OS2., which
accept any character that cannot be part of a variable name (including a
space) as the terminator.  However, the trailing percent can be used to
maintain compatibility.
:p.
The trailing percent sign :hp2.is:ehp2. 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&colon.
:xmp.
        [c&colon.\] set ONE=abcd
        [c&colon.\] set TWO=efgh
:exmp.:p.
Now the following combinations produce the output text shown&colon.
:xmp.
        %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%")
:exmp.:p.
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&colon.
:xmp.
        echo We're with you 100%%
:exmp.:p.
You can also use back quotes around the text, rather than a double
percent sign.  See :link reftype=hd refid=Quoting.Argument Quoting:elink.
for details.

.* --------------------------------------------------------------------------

:h2 nosearch name=CDPATH_Var.CDPATH
:p.
:link reftype=hd auto dependent refid=CDPATH.CDPATH
.* Link automatically to CDPATH topic above
.* This puts an entry into the TOC at this location

.* --------------------------------------------------------------------------

:h2 name=CMDLINE.CMDLINE
:p.
:hp2.CMDLINE:ehp2. is the fully expanded text of the currently executing
command line.  CMDLINE is set just before invoking any :hp1..COM:ehp1.,
:hp1..EXE:ehp1., :hp1..BTM:ehp1., :hp1..BAT:ehp1., or :hp1..CMD:ehp1.
file.  If a command line is prefaced with an "@" to prevent echoing, it will
not be put in CMDLINE, and any previous CMDLINE variable will be removed
from the environment.

.* --------------------------------------------------------------------------

:h2 name=COLORDIR_Var.COLORDIR
:p.
:hp2.COLORDIR:ehp2. controls directory display colors used by
:link reftype=hd refid=DIR.DIR:elink. and
:link reftype=hd refid=SELECT.SELECT:elink..  See the Color-Coded Directories
topic under the :link reftype=hd refid=DIR.DIR:elink. command for a complete
description of the format of this variable.

.* --------------------------------------------------------------------------

:h2 name=COMSPEC.COMSPEC
:p.
:hp2.COMSPEC:ehp2. contains the full path and name of &4OS2..  For example,
if &4OS2. is stored in the directory :hp1.C&colon.\&4OS2.:ehp1., the COMSPEC
variable should be set to :hp1.C&colon.\&4OS2.\&4OS2..EXE:ehp1..  COMSPEC is used by applications
which need to find &4OS2. to implement a "shell to the command prompt" feature.
:p.
You can set the COMSPEC variable by specifying the COMSPEC path
with a SET COMSPEC command in :hp1.CONFIG.SYS:ehp1., or including
the COMSPEC path on the &4OS2. :link reftype=hd refid=Startup.startup:elink.
command line.

.* --------------------------------------------------------------------------

:h2 name=FILECOMPLETION.FILECOMPLETION
:p.
:hp2.FILECOMPLETION:ehp2. sets the files made available during filename
completion for selected commands.  See :hp2.Customizing Filename
Completion:ehp2. in the :link reftype=hd refid=FileComp.Filename
Completion:elink. topic for a complete description of the format of this
variable.

.* --------------------------------------------------------------------------

:h2 name=PATH_Var.PATH
:p.
:hp2.PATH:ehp2. is a list of directories that &4OS2. 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 the
:link reftype=hd refid=PATH.PATH:elink. command for a full description of
this variable.

.* --------------------------------------------------------------------------

:h2 name=PATHEXT.PATHEXT
:p.
:hp2.PATHEXT:ehp2. can be used to select the extensions to look for when
searching the :link reftype=hd refid=PATH.PATH:elink. for an executable
file.  It consists of a list of extensions, separated by semicolons.
For example, to replicate the default extension list used by &4OS2.&colon.
:xmp.
     set pathext=.com;.exe;.btm;.cmd;.bat
:exmp.:p.
PATHEXT is ignored unless the :link reftype=hd
refid=INI_PathExt.PathExt:elink. setting is set to Yes in :hp1.&4OS2INI.:ehp1..
Once PATHEXT is enabled the standard path search for :hp1..COM,:ehp1.
:hp1..EXE:ehp1., :hp1..BTM:ehp1., :hp1..CMD:ehp1., and :hp1..BAT:ehp1.
files is replaced by a search for files with the extensions listed in
PATHEXT, in the order listed there.
:p.
Enabling PATHEXT affects :hp2.only:ehp2. the standard path search, it
does not affect the subsequent searches for files with :link reftype=hd
refid=ExeExt.executable extensions:elink..  PATHEXT is supported for
compatibility reasons but should not generally be used as a substitute
for executable extensions, which are much more flexible.  For more
details on path searches, see the :link reftype=hd refid=PATH.PATH:elink.
command.
:p.
:hp8.CAUTION&colon.  If you set PathExt = Yes in :hp1.&4OS2INI.:ehp1. and then fail
to set the PATHEXT variable, path searches will fail as there will be no
extensions for which to search!:ehp8.

.* --------------------------------------------------------------------------

:h2 name=PROMPT_Var.PROMPT
:p.
:hp2.PROMPT:ehp2. defines the command-line prompt.  It can be set or
changed with the :link reftype=hd refid=PROMPT.PROMPT:elink. command.

.* --------------------------------------------------------------------------

:h2 name=IntVars.Internal Variables
:p.
:hp2.Internal variables:ehp2. are special environment variables built into
&4OS2. 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.
:P.
The values of these variables are stored internally in &4OS2., and
cannot be changed with the :link reftype=hd refid=SET.SET:elink.,
:link reftype=hd refid=UNSET.UNSET:elink., or
:link reftype=hd refid=ESET.ESET:elink. command.  However, you can override
any of these variables by defining a new variable with the same name.
:p.
The list below gives a one-line description of each variable, and a
cross-reference which selects a full screen help topic on that variable.
Most of the variables are simple enough that the one-line description is
sufficient.  However, for those variables marked with an asterisk [:hp2.*:ehp2.],
the cross-reference topic contains some additional information you may wish
to review.  You can also obtain help on any variable with a :hp2.HELP
variable name:ehp2. command at the prompt (this is why each variable has its
own topic, in addition to its appearance in the list below).
:p.
See the discussion after the variable list for some additional information,
and examples of how these variables can be used.  For additional examples, see
the :hp1.EXAMPLES.BTM:ehp1. file which came with &4OS2..
:p.
:p.
The variables are&colon.
:p.
:hp2.Hardware status:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:link reftype=hd refid=_CPU._CPU:elink.:pd.CPU type (86, 186, 200, 386, 486, 586)
:pt.:link reftype=hd refid=_MONITOR._MONITOR:elink.:pd.Monitor type (mono or color)
:pt.:link reftype=hd refid=_NDP._NDP:elink.:pd.Coprocessor type (0, 87, 287, 387)
:pt.:link reftype=hd refid=_VIDEO._VIDEO:elink.:pd.Video board type (mono, cga, ega, vga, xga, 8514, or IA/A)
:eparml.:lm margin=1.
.br
:hp2.Operating system and software status:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:link reftype=hd refid=_ANSI._ANSI:elink.:pd.ANSI status (always 1 in &4OS2.)
:pt.:link reftype=hd refid=_APMAC._APMAC:elink.:pd.* APM AC line status
:pt.:link reftype=hd refid=_APMBATT._APMBATT:elink.:pd.* APM battery status
:pt.:link reftype=hd refid=_APMLIFE._APMLIFE:elink.:pd.* APM battery life
:pt.:link reftype=hd refid=_BOOT._BOOT:elink.:pd.Boot drive letter, without a colon
:pt.:link reftype=hd refid=_CI._CI:elink.:pd.Current cursor shape in insert mode
:pt.:link reftype=hd refid=_CO._CO:elink.:pd.Current cursor shape in overstrike mode
:pt.:link reftype=hd refid=_CODEPAGE._CODEPAGE:elink.:pd.Current code page number
:pt.:link reftype=hd refid=_COUNTRY._COUNTRY:elink.:pd.Current country code
:pt.:link reftype=hd refid=_DOS._DOS:elink.:pd.* Operating system (DOS, OS2, etc.)
:pt.:link reftype=hd refid=_DOSVER._DOSVER:elink.:pd.* Operating system version (2.1, 3.0, etc.)
:pt.:link reftype=hd refid=_KBHIT._KBHIT:elink.:pd.Keystroke waiting in buffer (0 or 1)
:pt.:link reftype=hd refid=_MOUSE._MOUSE:elink.:pd.Mouse driver flag (always 1 in &4OS2.)
:eparml.:lm margin=1.
.br
:hp2.Command processor status:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:link reftype=hd refid=_4VER._4VER:elink.:pd.&4OS2. version (&4verprev., &4ver., etc.)
:pt.:link reftype=hd refid=_BATCH._BATCH:elink.:pd.Batch nesting level
:pt.:link reftype=hd refid=_BATCHLINE._BATCHLINE:elink.:pd.Current line number in current batch file
:pt.:link reftype=hd refid=_BATCHNAME._BATCHNAME:elink.:pd.Name of current batch file
:pt.:link reftype=hd refid=_CMDPROC._CMDPROC:elink.:pd.Command processor name
:pt.:link reftype=hd refid=_DNAME._DNAME:elink.:pd.Name of file used to store file descriptions
:pt.:link reftype=hd refid=_HLOGFILE._HLOGFILE:elink.:pd.Current history log file name
:pt.:link reftype=hd refid=_LOGFILE._LOGFILE:elink.:pd.Current log file name
:pt.:link reftype=hd refid=_PID._PID:elink.:pd.&4OS2. process ID (numeric)
:pt.:link reftype=hd refid=_PIPE._PIPE:elink.:pd.Whether running in a pipe
:pt.:link reftype=hd refid=_PPID._PPID:elink.:pd.Parent process ID (numeric)
:pt.:link reftype=hd refid=_PTYPE._PTYPE:elink.:pd.OS/2 session type (AVIO, DT, FS, PM)
:pt.:link reftype=hd refid=_SHELL._SHELL:elink.:pd.Shell level (0, 1, 2, ...)
:pt.:link reftype=hd refid=_SID._SID:elink.:pd.Current OS/2 session ID
:pt.:link reftype=hd refid=_TRANSIENT._TRANSIENT:elink.:pd.* Transient shell flag (0 or 1)
:pt.:link reftype=hd refid=_WINTITLE._WINTITLE:elink.:pd.Current window title
:eparml.:lm margin=1.
.br
:hp2.Screen and color:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:link reftype=hd refid=_BG._BG:elink.:pd.Background color at cursor position
:pt.:link reftype=hd refid=_COLUMN._COLUMN:elink.:pd.Current cursor column
:pt.:link reftype=hd refid=_COLUMNS._COLUMNS:elink.:pd.Screen width
:pt.:link reftype=hd refid=_FG._FG:elink.:pd.Foreground color at cursor position
:pt.:link reftype=hd refid=_ROW._ROW:elink.:pd.Current cursor row
:pt.:link reftype=hd refid=_ROWS._ROWS:elink.:pd.Screen height
:pt.:link reftype=hd refid=_XPIXELS._XPIXELS:elink.:pd.Physical screen horizontal size
:pt.:link reftype=hd refid=_YPIXELS._YPIXELS:elink.:pd.Physical screen vertical size
:eparml.:lm margin=1.
.br
:hp2.Drives and directories:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:link reftype=hd refid=_CWD._CWD:elink.:pd.Current drive and directory (d&colon.\path)
:pt.:link reftype=hd refid=_CWDS._CWDS:elink.:pd.Current drive and directory with trailing :hp2.\:ehp2. (d&colon.\path\)
:pt.:link reftype=hd refid=_CWP._CWP:elink.:pd.Current directory (\path)
:pt.:link reftype=hd refid=_CWPS._CWPS:elink.:pd.Current directory with trailing :hp2.\:ehp2. (\path\)
:pt.:link reftype=hd refid=_DISK._DISK:elink.:pd.Current drive (C, D, etc.)
:pt.:link reftype=hd refid=_LASTDISK._LASTDISK:elink.:pd.Last possible drive (E, F, etc.)
:eparml.:lm margin=1.
.br
:hp2.Dates and times:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:link reftype=hd refid=_DATE._DATE:elink.:pd.* Current date (mm-dd-yy)
:pt.:link reftype=hd refid=_DAY._DAY:elink.:pd.Day of the month (1 - 31)
:pt.:link reftype=hd refid=_DOW._DOW:elink.:pd.Day of the week (Mon, Tue, Wed, etc.)
:pt.:link reftype=hd refid=_DOWI._DOWI:elink.:pd.Integer day of the week (1 = Sunday, 2= Monday, etc.)
:pt.:link reftype=hd refid=_DOY._DOY:elink.:pd.Day of the year (1 - 366)
:pt.:link reftype=hd refid=_HOUR._HOUR:elink.:pd.Hour (0 - 23)
:pt.:link reftype=hd refid=_MINUTE._MINUTE:elink.:pd.Minute (0 - 59)
:pt.:link reftype=hd refid=_MONTH._MONTH:elink.:pd.Month of the year (1 - 12)
:pt.:link reftype=hd refid=_SECOND._SECOND:elink.:pd.Second (0 - 59)
:pt.:link reftype=hd refid=_TIME._TIME:elink.:pd.* Current time (hh&colon.mm&colon.ss)
:pt.:link reftype=hd refid=_YEAR._YEAR:elink.:pd.Year (1980 - 2099)
:eparml.:lm margin=1.
.br
:hp2.Error codes:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:link reftype=hd refid=_QMARK.?:elink.:pd.* Exit code, last external program
:pt.:link reftype=hd refid=__QMARK._?:elink.:pd.* Exit code, last internal command
:pt.:link reftype=hd refid=_SYSERR._SYSERR:elink.:pd.* Last OS/2 error code
:eparml.:lm margin=1.
.br
:hp2.Compatibility:ehp2.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:link reftype=hd refid=EQUALS.=:elink.:pd.* Substitutes escape character
:pt.:link reftype=hd refid=PLUS.+:elink.:pd.* Substitutes command separator
:eparml.:lm margin=1.
.br
:p.
:hp2.Additional Notes:ehp2.
:p.
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
%:link reftype=hd refid=EQUALS.=:elink. and
%:link reftype=hd refid=PLUS.+:elink.) from the command line
with a command like this&colon.
:xmp.
        [c&colon.\] echo %variablename
:exmp.:p.
On disk volumes which do not support long filenames, variables which return a
path or file name will return their result in upper or lower case depending
on the value of the :link reftype=hd refid=SETDOS.SETDOS:elink. /U switch
or the :link reftype=hd refid=INI_UpperCase.UpperCase:elink. directive in
the :hp1..INI:ehp1. file.  On volumes which do support long filenames,
these variables will return names as they are stored on the disk and no case
shifting will be performed.  Returned filename values which include long
filenames are :hp2.not:ehp2. quoted automatically; you must add
quotes yourself if they are required for your use of the variable value (see
:link reftype=hd refid=Quoting.Argument Quoting:elink.).
:p.
Some variables return values based on information provided by your operating
system.  These variables will only return correct information if the operating
system provides it.  For example, _APMBATT will not return accurate results if
your operating system and Advanced Power Management drivers do not provide
correct information on battery status to the command processor.
:p.
:p.
:hp2.Examples:ehp2.
:p.
You can use these variables in a wide variety of ways depending on your
needs.  Here are just a few examples.  For additional examples, see the
:hp1.EXAMPLES.BTM:ehp1. file which came with &4OS2..
:p.
Some of these examples rely on the :link reftype=hd refid=IF.IF:elink.
and :link reftype=hd refid=IFF.IFF:elink. commands to test the value of
a variable and perform different actions based on that value.
:p.
In a batch file, set the color based on the video card type&colon.
:xmp.
        iff "%_video"=="mono" then
          color bright white on black
        else
          color bright white on blue
        endiff
:exmp.:p.
Store the current date and time in a file, then save the output of
a DIR command in the same file&colon.
:xmp.
        echo Directory as of %_date %_time > dirsave
        dir >> dirsave
:exmp.:p.
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
:link reftype=hd refid=PROMPT.PROMPT:elink. 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
:hp1.4START:ehp1. file (see :link reftype=hd refid=AutoBatch.Automatic Batch Files:elink.)&colon.
:xmp.
        iff %_shell==0 then
          prompt $t $p$g
          color %_fg on blue
        else
          prompt [$z] $p$g
          color %_fg on cyan
        endiff
:exmp.
.* --------------------------------------------------------------------------

:h3 name=_QMARK.?
:p.
:hp2.?:ehp2. 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 :hp2.%?:ehp2. is undefined.

.* --------------------------------------------------------------------------

:h3 name=__QMARK._?
:p.
:hp2._?:ehp2. 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
:hp2.Ctrl-C:ehp2. or :hp2.Ctrl-Break:ehp2..  You must use or save this value
immediately, because it is set by every internal command.

.* --------------------------------------------------------------------------

:h3 name=EQUALS.=
:p.
:hp2.=:ehp2. 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 [:hp2.^:ehp2.]
(the default in &4OS2.) 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.
:xmp.
        echos ^f > prn
        echos %=f > prn
:exmp.
.* --------------------------------------------------------------------------

:h3 name=PLUS.+
:p.
:hp2.+:ehp2. 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
[:hp2.&amp.:ehp2.] (the default in &4OS2.) 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 &amp. echo world", while the second command
will continue to work as intended.
:xmp.
        echo Hello &amp. echo world
        echo Hello %+ echo world
:exmp.
.* --------------------------------------------------------------------------

:h3 name=_4VER._4VER
:p.
:hp2._4VER:ehp2. is the current &4OS2. version (for example, "&4ver.").
The current decimal character is used to separate the major and minor version
numbers (see :link reftype=hd refid=INI_DecimalChar.DecimalChar:elink.) for details.

.* --------------------------------------------------------------------------

:h3 name=_ANSI._ANSI
:p.
:hp2._ANSI:ehp2. is always "1" in &4OS2..  (&4OS2. enables OS/2's ANSI support,
and assumes that it remains enabled.)

.* --------------------------------------------------------------------------

:h3 name=_APMAC._APMAC
:p.
:hp2._APMAC:ehp2. is the Advanced Power Management AC line status ("on-line",
"off-line", or "unknown").  An empty string is returned if APM is not
installed on your system.

.* --------------------------------------------------------------------------

:h3 name=_APMBATT._APMBATT
:p.
:hp2._APMBATT:ehp2. is the Advanced Power Management battery status ("high",
"low", "critical", "charging", or "unknown").  An empty string is
returned if APM is not installed.

.* --------------------------------------------------------------------------
:h3 name=_APMLIFE._APMLIFE
:p.
:hp2._APMLIFE:ehp2. is the Advanced Power Management remaining battery life
(0 - 100 or "unknown").  An empty string is returned if APM is not installed.

.* --------------------------------------------------------------------------

:h3 name=_BATCH._BATCH
:p.
:hp2._BATCH:ehp2. is the current batch nesting level.  It is "0" if no
batch file is currently being processed.

.* --------------------------------------------------------------------------

:h3 name=_BATCHLINE._BATCHLINE
:p.
:hp2._BATCHLINE:ehp2. is the current line number in the current batch file.  It is "-1"
if no batch file is currently being processed.

.* --------------------------------------------------------------------------

:h3 name=_BATCHNAME._BATCHNAME
:p.
:hp2._BATCHNAME:ehp2. is the full path and file name of the current batch
file.  It is an empty string if no batch file is currently being processed.

.* --------------------------------------------------------------------------

:h3 name=_BG._BG
:p.
:hp2._BG:ehp2. is a string containing the first three characters of the
screen background color at the current cursor location (for
example, "Bla").

.* --------------------------------------------------------------------------

:h3 name=_BOOT._BOOT
:p.
:hp2._BOOT:ehp2. is the boot drive letter, without a colon.

.* --------------------------------------------------------------------------

:h3 name=_CI._CI
:p.
:hp2._CI:ehp2. is the insert-mode cursor shape, as a percentage (see
:link reftype=hd refid=SETDOS.SETDOS:elink. /S and the
:link reftype=hd refid=INI_CursorIns.CursorIns:elink. directive).

.* --------------------------------------------------------------------------

:h3 name=_CMDPROC._CMDPROC
:p.
:hp2._CMDPROC:ehp2. is the name of the current command processor.  Each JP
Software command processor returns a different value, as follows:
:lm margin=8.:parml tsize=32 compact break=fit.
:pt.:hp2.Product:ehp2.:pd.:hp2.Returns:ehp2.
.br
:pt.4DOS:pd."4DOS"
:pt.&4OS2.:pd."&4OS2."
:pt.4NT:pd."4NT"
:pt.Take Command/16:pd."TCMD"
:pt.Take Command/32:pd."TCMD32"
:pt.Take Command for OS/2:pd."TCMDOS2"
:eparml.
:lm margin=1.
:p.
This variable is useful if you have batch files running in more than one
environment, and need to take different actions depending on the underlying
command processor.  If you also need to determine the operating system, see
:link reftype=hd refid=_DOS._DOS:elink..
.* --------------------------------------------------------------------------

:h3 name=_CO._CO
:p.
:hp2._CO:ehp2. is the overstrike-mode cursor shape, as a percentage (see
:link reftype=hd refid=SETDOS.SETDOS:elink. /S and the
:link reftype=hd refid=INI_CursorOver.CursorOver:elink. directive).

.* --------------------------------------------------------------------------

:h3 name=_CODEPAGE._CODEPAGE
:p.
:hp2._CODEPAGE:ehp2. is the current code page number (see
:link reftype=hd refid=CHCP.CHCP:elink.).

.* --------------------------------------------------------------------------

:h3 name=_COLUMN._COLUMN
:p.
:hp2._COLUMN:ehp2. is the current cursor column (for example, "0" for the
left side of the screen).

.* --------------------------------------------------------------------------

:h3 name=_COLUMNS._COLUMNS
:p.
:hp2._COLUMNS:ehp2. is the current number of screen columns (for example,
"80").

.* --------------------------------------------------------------------------

:h3 name=_COUNTRY._COUNTRY
:p.
:hp2._COUNTRY:ehp2. is the current country code.

.* --------------------------------------------------------------------------

:h3 name=_CPU._CPU
:p.
:hp2._CPU:ehp2. is the CPU type&colon.
:lm margin=8.:parml compact tsize=8 break=fit.
:pt.86:pd.8086 and 8088
:pt.186:pd.80186 and 80188
:pt.200:pd.NEC V20 and V30
:pt.286:pd.80286
:pt.386:pd.i386
:pt.486:pd.i486
:pt.586:pd.Pentium
:pt.686:pd.Pentium Pro
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h3 name=_CWD._CWD
:p.
:hp2._CWD:ehp2. is the current working directory in the format
:hp1.d&colon.\pathname:ehp1..

.* --------------------------------------------------------------------------

:h3 name=_CWDS._CWDS
:p.
:hp2._CWDS:ehp2. has the same value as CWD, except it ends the pathname
with a backslash [:hp2.\:ehp2.].

.* --------------------------------------------------------------------------

:h3 name=_CWP._CWP
:p.
:hp2._CWP:ehp2. is the current working directory in the format
:hp1.\pathname:ehp1..

.* --------------------------------------------------------------------------

:h3 name=_CWPS._CWPS
:p.
:hp2._CWPS:ehp2. has the same value as CWP, except it ends the pathname
with a backslash [:hp2.\:ehp2.].

.* --------------------------------------------------------------------------

:h3 name=_DATE._DATE
:p.
:hp2._DATE:ehp2. contains the current system date, in the format mm-dd-yy
(U.S.), dd-mm-yy (Europe), or yy-mm-dd (Japan).

.* --------------------------------------------------------------------------

:h3 name=_DAY._DAY
:p.
:hp2._DAY:ehp2. is the current day of the month (1 to 31).

.* --------------------------------------------------------------------------

:h3 name=_DISK._DISK
:p.
:hp2._DISK:ehp2. is the current disk drive, without a colon (for example,
"C").

.* --------------------------------------------------------------------------

:h3 name=_DNAME._DNAME
:p.
:hp2._DNAME:ehp2. is the name of the file used to store file descriptions.  It
can be changed with the :link reftype=hd refid=INI_DescriptionName.DescriptionName:elink. directive
in :hp1.&4OS2INI.:ehp1. or the :link reftype=hd refid=SETDOS.SETDOS:elink. /D
command.

.* --------------------------------------------------------------------------

:h3 name=_DOS._DOS
:p.
:hp2._DOS:ehp2. is the operating system and command processor type.  Each JP
Software command processor returns a different value depending on the
operating system, as follows:
:lm margin=4.:table rules=both frame=box cols='21 3 4 7 7 7 7'.
:row.
:c. :c.DOS :c.OS/2 :c.Windows 3.x :c.Windows 95 :c.Windows 98 :c.Windows NT
:row.
:c.4DOS :c.DOS :c.DOS :c.DOS :c.DOS :c.DOS
:row.
:c.&4OS2. :c. :c.OS2
:row.
:c.4NT :c. :c. :c. :c.WIN95C :c.WIN98C :c.NT
:row.
:c.Take Command/16 :c. :c.WIN :c.WIN
:row.
:c.Take Command/32 :c. :c. :c. :c.WIN95 :c.WIN98 :c.WIN32
:row.
:c.Take Command for OS/2 :c. :c.PM
:etable.
:lm margin=1.
.br
This variable is useful if you have batch files running in more than one
environment, and need to take different actions depending on the underlying
operating environment or command processor.  If you want the current command
processor name, use :link reftype=hd refid=_CMDPROC._CMDPROC:elink..

.* --------------------------------------------------------------------------

:h3 name=_DOSVER._DOSVER
:p.
:hp2._DOSVER:ehp2. is the current operating system version (for example,
"4.00"). The current decimal character is used to separate the major and
minor version numbers (see :link reftype=hd
refid=INI_DecimalChar.DecimalChar:elink.) for details.

.* --------------------------------------------------------------------------

:h3 name=_DOW._DOW
:p.
:hp2._DOW:ehp2. is the first three characters of the current day of the
week ("Mon", "Tue", "Wed", etc.).

.* --------------------------------------------------------------------------

:h3 name=_DOWI._DOWI
:p.
:hp2._DOWI:ehp2. is the current day of the week as an integer (1 = Sunday,
2 = Monday, etc.).

.* --------------------------------------------------------------------------

:h3 name=_DOY._DOY
:p.
:hp2._DOY:ehp2. is the day of the year (1 to 366).

.* --------------------------------------------------------------------------

:h3 name=_FG._FG
:p.
:hp2._FG:ehp2. is a string containing the first three letters of the
screen foreground color at the current cursor position (for
example, "Whi").

.* --------------------------------------------------------------------------

:h3 name=_HLOGFILE._HLOGFILE
:p.
:hp2._HLOGFILE:ehp2.  returns the name of the current history log file (or
an empty string if LOG /H is OFF).  See :link reftype=hd refid=LOG.LOG:elink.
for information on logging.

.* --------------------------------------------------------------------------

:h3 name=_HOUR._HOUR
:p.
:hp2._HOUR:ehp2. is the current hour (0 - 23).

.* --------------------------------------------------------------------------

:h3 name=_KBHIT._KBHIT
:p.
:hp2._KBHIT:ehp2. returns 1 if one or more keystrokes are waiting in the keyboard
buffer, or 0 if the keyboard buffer is empty.

.* --------------------------------------------------------------------------

:h3 name=_LASTDISK._LASTDISK
:p.
:hp2._LASTDISK:ehp2. is the last valid drive letter, without a colon.

.* --------------------------------------------------------------------------

:h3 name=_LOGFILE._LOGFILE
:p.
:hp2._LOGFILE:ehp2.  returns the name of the current log file (or an empty
string if LOG is OFF).  See :link reftype=hd refid=LOG.LOG:elink.
for information on logging.

.* --------------------------------------------------------------------------

:h3 name=_MINUTE._MINUTE
:p.
:hp2._MINUTE:ehp2. is the current minute (0 - 59).

.* --------------------------------------------------------------------------

:h3 name=_MONITOR._MONITOR
:p.
:hp2._MONITOR:ehp2. is the monitor type ("mono" or "color").

.* --------------------------------------------------------------------------

:h3 name=_MONTH._MONTH
:p.
:hp2._MONTH:ehp2. is the current month of the year (1 to 12).

.* --------------------------------------------------------------------------

:h3 name=_MOUSE._MOUSE
:p.
:hp2._MOUSE:ehp2. always returns "1" in &4OS2..

.* --------------------------------------------------------------------------

:h3 name=_NDP._NDP
:p.
:hp2._NDP:ehp2. is the coprocessor type&colon.
:lm margin=8.:parml compact tsize=8 break=fit.
:pt.0:pd.no coprocessor is installed
:pt.87:pd.8087
:pt.287:pd.80287
:pt.387:pd.80387, 80486DX, 80487, Pentium, or Pentium Pro
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h3 name=_PID._PID
:p.
:hp2._PID:ehp2. is the current process ID number.

.* --------------------------------------------------------------------------

:h3 name=_PIPE._PIPE
:p.
:hp2._PIPE:ehp2. returns "1" if the current process is running inside a pipe
or "0" otherwise.

.* --------------------------------------------------------------------------

:h3 name=_PPID._PPID
:p.
:hp2._PPID:ehp2. is the process ID number of the parent process.

.* --------------------------------------------------------------------------

:h3 name=_PTYPE._PTYPE
:p.
:hp2._PTYPE:ehp2. is the current OS/2 process type&colon.
:lm margin=8.:parml compact tsize=8 break=fit.
:pt.AVIO:pd.Character mode, windowed
:pt.DT:pd.Detached (no screen in use)
:pt.FS:pd.Character mode, full-screen
:pt.PM:pd.Presentation Manager
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h3 name=_ROW._ROW
:p.
:hp2._ROW:ehp2. is the current cursor row (for example, "0" for the top of
the screen).

.* --------------------------------------------------------------------------

:h3 name=_ROWS._ROWS
:p.
:hp2._ROWS:ehp2. is the current number of screen rows (for example, "25").

.* --------------------------------------------------------------------------

:h3 name=_SECOND._SECOND
:p.
:hp2._SECOND:ehp2. is the current second (0 - 59).

.* --------------------------------------------------------------------------

:h3 name=_SHELL._SHELL
:p.
:hp2._SHELL:ehp2. is the current shell nesting level.  The primary shell
is level "0", and each subsequent secondary shell increments the
level by 1.

.* --------------------------------------------------------------------------

:h3 name=_SID._SID
:p.
:hp2._SID:ehp2. is the session ID number.

.* --------------------------------------------------------------------------

:h3 name=_SYSERR._SYSERR
:p.
:hp2._SYSERR:ehp2. is the error code of the last operating system error.
You will need a technical or programmer's manual to understand
these error values.

.* --------------------------------------------------------------------------

:h3 name=_TIME._TIME
:p.
:hp2._TIME:ehp2. contains the current system time in the format
hh&colon.mm&colon.ss.  The separator character may vary depending upon your
country information.

.* --------------------------------------------------------------------------

:h3 name=_TRANSIENT._TRANSIENT
:p.
:hp2._TRANSIENT:ehp2. is "1" if the current shell is transient (started
with a :hp2./C:ehp2., see :link reftype=hd refid=Startup.Starting
&4OS2.:elink. for details), or "0" otherwise.

.* --------------------------------------------------------------------------

:h3 name=_VIDEO._VIDEO
:p.
:hp2._VIDEO:ehp2. is the video card type ("mono", "cga", "ega", "vga", "xga",
"8514", or "IA/A" (for the PS/2 Image Adapter/A).

.* --------------------------------------------------------------------------

:h3 name=_WINTITLE._WINTITLE
:p.
:hp2._WINTITLE:ehp2. returns the title of the current window.

.* --------------------------------------------------------------------------

:h3 name=_XPIXELS._XPIXELS
:p.
:hp2._XPIXELS:ehp2. returns the physical screen horizontal size in pixels.

.* --------------------------------------------------------------------------

:h3 name=_YEAR._YEAR
:p.
:hp2._YEAR:ehp2. is the current year (1980 to 2099).

.* --------------------------------------------------------------------------

:h3 name=_YPIXELS._YPIXELS
:p.
:hp2._YPIXELS:ehp2. returns the physical screen vertical size in pixels.

.* --------------------------------------------------------------------------

:h2 name=VarFuncs.Variable Functions
:p.
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.
:p.
The list below gives a one-line description of each function, and a
cross-reference which selects a full screen help topic on that function.  A
few of the variables are simple enough that the one-line description is
sufficient, but in most cases you should check for any additional
information in the cross-reference topic if you are not already familiar
with a function.  You can also obtain help on any function with a :hp2.HELP
@functionname:ehp2. command at the prompt.
:p.
See the discussion after the function list for some additional information,
and examples of how the functions can be used.  For additional examples, see
the :hp1.EXAMPLES.BTM:ehp1. file which came with &4OS2..
:p.
:p.
The variable functions are&colon.
:p.
:hp2.System status:ehp2.
:lm margin=8.:parml compact tsize=36 break=fit.
:pt.:link reftype=hd refid=_@DOSMEM.@DOSMEM[b|k|m]:elink.:pd.Size of largest free memory block
:pt.:link reftype=hd refid=_@READSCR.@READSCR[row,col,len]:elink.:pd.Read characters from the screen
:eparml.:lm margin=1.
.br
:hp2.Drives and devices:ehp2.
:lm margin=8.:parml compact tsize=36 break=fit.
:pt.:link reftype=hd refid=_@CDROM.@CDROM[d&colon.]:elink.:pd.CD-ROM drive detection (0 or 1)
:pt.:link reftype=hd refid=_@DEVICE.@DEVICE[name]:elink.:pd.Character device detection
:pt.:link reftype=hd refid=_@DISKFREE.@DISKFREE[d&colon.,b|k|m]:elink.:pd.Free disk space
:pt.:link reftype=hd refid=_@DISKTOTAL.@DISKTOTAL[d&colon.,b|k|m]:elink.:pd.Total disk space
:pt.:link reftype=hd refid=_@DISKUSED.@DISKUSED[d&colon.,b|k|m]:elink.:pd.Used disk space
:pt.:link reftype=hd refid=_@FSTYPE.@FSTYPE[d&colon.]:elink.:pd.File system type (FAT, HPFS, CDFS, etc.)
:pt.:link reftype=hd refid=_@LABEL.@LABEL[d&colon.]:elink.:pd.Volume label
:pt.:link reftype=hd refid=_@READY.@READY[d&colon.]:elink.:pd.Drive ready status (0 or 1)
:pt.:link reftype=hd refid=_@REMOTE.@REMOTE[d&colon.]:elink.:pd.Remote (network) drive detection (0 or 1)
:pt.:link reftype=hd refid=_@REMOVABLE.@REMOVABLE[d&colon.]:elink.:pd.Removable drive detection (0 or 1)
:eparml.:lm margin=1.
.br
:hp2.Files:ehp2.
:lm margin=8.:parml compact tsize=36 break=fit.
:pt.:link reftype=hd refid=_@ATTRIB.@ATTRIB[filename [,-nrhsda]]:elink.:pd.File attribute test (0 or 1)
:pt.:link reftype=hd refid=_@DESCRIPT.@DESCRIPT[filename]:elink.:pd.File description
:pt.:link reftype=hd refid=_@EAREAD.@EAREAD[filename,EAname]:elink.:pd.Read extended attribute
:pt.:link reftype=hd refid=_@EAWRITE.@EAWRITE[filename,EAname,[value]]:elink.:pd.Write extended attribute
:pt.:link reftype=hd refid=_@EXETYPE.@EXETYPE[filename]:elink.:pd.Executable file type (DOS, PM, WIN, etc.)
:pt.:link reftype=hd refid=_@FILEAGE.@FILEAGE[filename[,acw]]:elink.:pd.File age (date and time)
:pt.:link reftype=hd refid=_@FILECLOSE.@FILECLOSE[n]:elink.:pd.Close a file
:pt.:link reftype=hd refid=_@FILEDATE.@FILEDATE[filename[,acw]]:elink.:pd.File date
:pt.:link reftype=hd refid=_@FILEOPEN.@FILEOPEN[filename,mode]:elink.:pd.Open a file
:pt.:link reftype=hd refid=_@FILEREAD.@FILEREAD[n [,length]]:elink.:pd.Read next line from a file
:pt.:link reftype=hd refid=_@FILES.@FILES[filename [,-nrhsda]]:elink.:pd.Count files matching a wildcard
:pt.:link reftype=hd refid=_@FILESEEK.@FILESEEK[n,offset,start]:elink.:pd.Move a file pointer to an offset
:pt.:link reftype=hd refid=_@FILESEEKL.@FILESEEKL[n,offset,start]:elink.:pd.Move a file pointer to a line number
:pt.:link reftype=hd refid=_@FILESIZE.@FILESIZE[filename,b|k|m]:elink.:pd.Size of files matching a wildcard
:pt.:link reftype=hd refid=_@FILETIME.@FILETIME[filename[,acw]]:elink.:pd.File time
:pt.:link reftype=hd refid=_@FILEWRITE.@FILEWRITE[n,text]:elink.:pd.Write next line to a file
:pt.:link reftype=hd refid=_@FILEWRITEB.@FILEWRITEB[n,length,string]:elink.:pd.Write bytes from a string to a file
:pt.:link reftype=hd refid=_@FINDCLOSE.@FINDCLOSE[filename]:elink.:pd.Close the search handle opened by @FINDFIRST
:pt.:link reftype=hd refid=_@FINDFIRST.@FINDFIRST[filename [,-nrhsda]]:elink.:pd.Find first matching file
:pt.:link reftype=hd refid=_@FINDNEXT.@FINDNEXT[filename [,-nrhsda]]:elink.:pd.Find next matching file
:pt.:link reftype=hd refid=_@LINE.@LINE[filename,n]:elink.:pd.Read a random line from a file
:pt.:link reftype=hd refid=_@LINES.@LINES[filename]:elink.:pd.Count lines in a file
:pt.:link reftype=hd refid=_@SEARCH.@SEARCH[filename]:elink.:pd.Path search
:pt.:link reftype=hd refid=_@UNIQUE.@UNIQUE[d&colon.\path]:elink.:pd.Create file with unique name
:eparml.:lm margin=1.
.br
:hp2.File names:ehp2.
:lm margin=8.:parml compact tsize=36 break=fit.
:pt.:link reftype=hd refid=_@EXPAND.@EXPAND[filename [,-nrhsda]]:elink.:pd.Names of all matching files and directories
:pt.:link reftype=hd refid=_@EXT.@EXT[filename]:elink.:pd.File extension
:pt.:link reftype=hd refid=_@FILENAME.@FILENAME[filename]:elink.:pd.File name and extension
:pt.:link reftype=hd refid=_@FULL.@FULL[filename]:elink.:pd.Full file name with path
:pt.:link reftype=hd refid=_@NAME.@NAME[filename]:elink.:pd.File name without path or extension
:pt.:link reftype=hd refid=_@PATH.@PATH[filename]:elink.:pd.File path without name
:eparml.:lm margin=1.
.br
:hp2.Strings and characters:ehp2.
:lm margin=8.:parml compact tsize=36 break=fit.
:pt.:link reftype=hd refid=_@ASCII.@ASCII[c]:elink.:pd.Numeric ASCII value for a character
:pt.:link reftype=hd refid=_@CHAR.@CHAR[n]:elink.:pd.Character value for numeric ASCII
:pt.:link reftype=hd refid=_@FORMAT.@FORMAT[[-][x][.y],string]:elink.:pd.Formats (justifies) a string
:pt.:link reftype=hd refid=_@INDEX.@INDEX[string1,string2]:elink.:pd.Position of one string in another
:pt.:link reftype=hd refid=_@INSERT.@INSERT[n,string1,string2]:elink.:pd.Insert one string into another
:pt.:link reftype=hd refid=_@INSTR.@INSTR[start,length,string]:elink.:pd.Extract a substring
:pt.:link reftype=hd refid=_@LEFT.@LEFT[n,string]:elink.:pd.Leftmost characters of a string
:pt.:link reftype=hd refid=_@LEN.@LEN[string]:elink.:pd.Length of a string
:pt.:link reftype=hd refid=_@LOWER.@LOWER[string]:elink.:pd.Convert string to lower case
:pt.:link reftype=hd refid=_@REPEAT.@REPEAT[c,n]:elink.:pd.Repeat a character
:pt.:link reftype=hd refid=_@REPLACE.@REPLACE[string1,string2,text]:elink.:pd.Replace all occurrences of one string with another
:pt.:link reftype=hd refid=_@RIGHT.@RIGHT[n,string]:elink.:pd.Rightmost characters of a string
:pt.:link reftype=hd refid=_@STRIP.@STRIP[chars,string]:elink.:pd.Remove characters from string
:pt.:link reftype=hd refid=_@SUBSTR.@SUBSTR[string,start,length]:elink.:pd.Extract a substring
:pt.:link reftype=hd refid=_@TRIM.@TRIM[string]:elink.:pd.Remove blanks from a string
:pt.:link reftype=hd refid=_@UPPER.@UPPER[string]:elink.:pd.Convert string to upper case
:pt.:link reftype=hd refid=_@WILD.@WILD[string1,string2]:elink.:pd.Wildcard comparison
:pt.:link reftype=hd refid=_@WORD.@WORD[["sep",] n,string]:elink.:pd.Extract a word from a string
:pt.:link reftype=hd refid=_@WORDS.@WORDS[["sep",] string]:elink.:pd.Counts number of words in a string
:eparml.:lm margin=1.
.br
:hp2.Numbers and arithmetic:ehp2.
:lm margin=8.:parml compact tsize=36 break=fit.
:pt.:link reftype=hd refid=_@COMMA.@COMMA[n]:elink.:pd.Inserts commas in a number
:pt.:link reftype=hd refid=_@CONVERT.@CONVERT[input,output,value]:elink.:pd.Base conversion
:pt.:link reftype=hd refid=_@DEC.@DEC[%var]:elink.:pd.Decremented value of a variable
:pt.:link reftype=hd refid=_@EVAL.@EVAL[expression]:elink.:pd.Arithmetic calculations
:pt.:link reftype=hd refid=_@INC.@INC[%var]:elink.:pd.Incremented value of a variable
:pt.:link reftype=hd refid=_@INT.@INT[n]:elink.:pd.Integer part of a number
:pt.:link reftype=hd refid=_@NUMERIC.@NUMERIC[string]:elink.:pd.Test if a string is numeric
:pt.:link reftype=hd refid=_@RANDOM.@RANDOM[min,max]:elink.:pd.Generate a random integer
:eparml.:lm margin=1.
.br
:hp2.Dates and times:ehp2.
:lm margin=8.:parml compact tsize=36 break=fit.
:pt.:link reftype=hd refid=_@DATE.@DATE[mm-dd-yy]:elink.:pd.Convert date to number of days
:pt.:link reftype=hd refid=_@DAY.@DAY[mm-dd-yy]:elink.:pd.Day of the month
:pt.:link reftype=hd refid=_@DOW.@DOW[mm-dd-yy]:elink.:pd.Day of the week
:pt.:link reftype=hd refid=_@DOWI.@DOWI[mm-dd-yy]:elink.:pd.Numeric day of the week
:pt.:link reftype=hd refid=_@DOY.@DOY[mm-dd-yy]:elink.:pd.Numeric day of the year
:pt.:link reftype=hd refid=_@MAKEAGE.@MAKEAGE[n]:elink.:pd.Convert date/time to file date/time
:pt.:link reftype=hd refid=_@MAKEDATE.@MAKEDATE[n]:elink.:pd.Convert number of days to date
:pt.:link reftype=hd refid=_@MAKETIME.@MAKETIME[n]:elink.:pd.Convert number of seconds to time
:pt.:link reftype=hd refid=_@MONTH.@MONTH[mm-dd-yy]:elink.:pd.Month of the year
:pt.:link reftype=hd refid=_@TIME.@TIME[hh&colon.mm&colon.ss]:elink.:pd.Convert time to number of seconds
:pt.:link reftype=hd refid=_@TIMER.@TIMER[n]:elink.:pd.Elapsed time of specified timer
:pt.:link reftype=hd refid=_@YEAR.@YEAR[mm-dd-yy]:elink.:pd.Year number (2 digits)
:eparml.:lm margin=1.
.br
:hp2.Utility:ehp2.
:lm margin=8.:parml compact tsize=36 break=fit.
:pt.:link reftype=hd refid=_@ALIAS.@ALIAS[name]:elink.:pd.Value of an alias
:pt.:link reftype=hd refid=_@CLIP.@CLIP[n]:elink.:pd.Line from the clipboard
:pt.:link reftype=hd refid=_@IF.@IF[condition,true,false]:elink.:pd.Evaluates a test condition
:pt.:link reftype=hd refid=_@EXEC.@EXEC[command]:elink.:pd.Execute a command
:pt.:link reftype=hd refid=_@EXECSTR.@EXECSTR[command]:elink.:pd.Execute, return string
:pt.:link reftype=hd refid=_@REXX.@REXX[expr]:elink.:pd.Execute a REXX expression
:pt.:link reftype=hd refid=_@SELECT.@SELECT[file,t,l,b,r,title]:elink.:pd.Menu selection
:eparml.:lm margin=1.
.br
:p.
:hp2.Additional Notes:ehp2.
:p.
Like all environment variables, these variable functions must be
preceded by a percent sign (%@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.
:p.
:p.
:hp2.Specific Functions and Arguments:ehp2.
:p.
Some variable functions, like @DISKFREE, are shown with ":hp2.b&splitvbar.k&splitvbar.m:ehp2."
as one of their arguments.  Those functions return a number of
bytes, kilobytes, or megabytes based on the ":hp2.b&splitvbar.k&splitvbar.m:ehp2." argument&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:hp2.b:ehp2.:pd.return the number of bytes
:pt.:hp2.K:ehp2.:pd.return the number of kilobytes (bytes / 1,024)
:pt.:hp2.k:ehp2.:pd.return the number of thousands of bytes (bytes / 1,000)
:pt.:hp2.M:ehp2.:pd.return the number of megabytes (bytes / 1,048,576)
:pt.:hp2.m:ehp2.:pd.return the number of millions of bytes (bytes / 1,000,000)
:eparml.:lm margin=1.
.br
You can include commas (or the "thousands separator" character for your
system) in the results from a ":hp2.b&splitvbar.k&splitvbar.m:ehp2." function
by appending a ":hp2.c:ehp2." to the argument.  For example, to add commas
to a ":hp2.b:ehp2." or number of bytes result, enter ":hp2.bc:ehp2." as the
argument.  To set the thousands separator see the
:link reftype=hd refid=INI_ThousandsChar.ThousandsChar:elink. directive.
:p.
Functions which accept a date as an argument use the date format and
separators mandated by your country code (for example dd.mm.yy in Germany, or
yy-mm-dd in Japan).  The year can be entered as a 4-digit or 2-digit
value.  Two-digit years between 80 and 99 are interpreted as 1980 - 1999;
values between 00 and 79 are interpreted as 2000 - 2079.
:p.
Several functions return filenames or parts of filenames.  On an HPFS
drive the strings returned by these functions may contain whitespace
or other special characters.  To avoid problems which could be caused by
these characters, quote the returned name before you pass it to other
commands, for example (either of these methods would work)&colon.
:xmp.
        set fname="%@findfirst[pro*.*]"
        echo First PRO file contains&colon.
        type %fname
        .....

        set fname=%@findfirst[pro*.*]
        echo First PRO file contains&colon.
        type "%fname"
        .....
:exmp.:p.
If you don't use the quotes in the :link reftype=hd refid=SET.SET:elink. or
:link reftype=hd refid=TYPE.TYPE:elink. command in this example, TYPE
will not interpret any whitespace or special characters in the name properly.
:p.
In variable functions which take a drive letter as an argument,
like :link reftype=hd refid=_@DISKFREE.@DISKFREE:elink. or
:link reftype=hd refid=_@READY.@READY:elink., the drive letter
:hp2.must:ehp2. be followed by a colon.  The function will
not work properly if you use the drive letter without the colon.
:p.
The :link reftype=hd refid=_@FILEREAD.@FILEREAD:elink.,
:link reftype=hd refid=_@FILEWRITE.@FILEWRITE:elink.,
:link reftype=hd refid=_@FILEWRITEB.@FILEWRITEB:elink.,
:link reftype=hd refid=_@FILESEEK.@FILESEEK:elink.,
:link reftype=hd refid=_@FILESEEKL.@FILESEEKL:elink., and
:link reftype=hd refid=_@FILECLOSE.@FILECLOSE:elink. functions
allow you to access files based on their file handle.  :hp8.These
functions should only be used with file handles returned by:ehp8.
:link reftype=hd refid=_@FILEOPEN.@FILEOPEN:elink.:hp8.!:ehp8.  If you use
them with any other file handle :hp8.you may damage other files:ehp8. opened
by &4OS2. (or, in a secondary shell, the program which started &4OS2.), :hp8.or
hang your system.:ehp8.
:p.
Many functions return values based on information provided by your operating
system.  Such functions will only return correct information if the operating
system provides it.  For example, :link reftype=hd refid=_@READY.@READY:elink.
will not return accurate results if your operating system does not provide
correct disk drive status information to the command processor.
:p.
:p.
:hp2.Examples:ehp2.
:p.
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.  For additional examples, see the
:hp1.EXAMPLES.BTM:ehp1. file which came with &4OS2..
:p.
To set the prompt to show the amount of free memory (see
:link reftype=hd refid=PROMPT.PROMPT:elink. for details on including variable functions in
your prompt)&colon.
:xmp.
        [c&colon.\] prompt (%%@dosmem[K]K) $p$g
:exmp.:p.
Set up a simple command-line calculator.  The calculator is used
with a command like CALC 3 * (4 + 5)&colon.
:xmp.
        [c&colon.\] alias calc `echo The answer is&colon.  %@eval[%&amp.]`
:exmp.:p.
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 :hp1.C&colon.\ONCEADAY.DAT:ehp1..
If today's date is numerically larger than the saved date, and the
time is after 6&colon.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 %:link reftype=hd refid=_@DATE.@DATE:elink. and
%:link reftype=hd refid=_@TIME.@TIME:elink. functions instead of using
%:link reftype=hd refid=_@INSTR.@INSTR:elink. to
extract substrings of the %:link reftype=hd refid=_DATE._DATE:elink.
and %:link reftype=hd refid=_TIME._TIME:elink. variables; we used the
approach shown to demonstrate the use of %@INSTR.
:xmp.
        rem  Temporary variables used to shorten example lines&colon.
        rem    DD is _date, DY is yymmdd date, TM is _time
        set dd=%_date
        set dy=%@instr[6,2,%dd]%@instr[0,2,%dd]%@instr[3,2,%dd]
        set lastdate=0
        iff exist c&colon.\onceaday.dat then
           set lastdate=%@line[onceaday.dat,0]
        endiff
        iff %dy gt %lastdate then
           set tm=%_time
           iff "%@instr[0,2,%tm]%@instr[3,2,%tm]" gt "0600" then
              rem Commands to be executed once a day go here
              echo %dy > c&colon.\onceaday.dat
           endiff
        endiff
:exmp.

.* --------------------------------------------------------------------------

:h3 name=_@ALIAS.@ALIAS
:p.
:hp2.@ALIAS[name]:ehp2.&colon.  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
:link reftype=hd refid=SETDOS.SETDOS:elink. /X command.
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.

.* --------------------------------------------------------------------------

:h3 name=_@ASCII.@ASCII
:p.
:hp2.@ASCII[c]:ehp2.&colon.  Returns the numeric value of the specified ASCII
character as a string.  For example :hp2.%@ASCII[A]:ehp2. returns 65.  You
can put an escape character [:hp2.^:ehp2.] before the actual
character to process.  This allows quotes and other special
characters as the argument (:hp1.e.g.:ehp1., :hp2.%@ASCII[^`]:ehp2.).

.* --------------------------------------------------------------------------

:h3 name=_@ATTRIB.@ATTRIB
:p.
:hp2.@ATTRIB[filename, [-nrhsda[,p]]]:ehp2.&colon.  Returns a "1" if the
specified file has the matching attribute(s); otherwise returns a "0".  The
attributes are&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.N:pd.Normal (no attributes set)
:pt.R:pd.Read-only
:pt.H:pd.Hidden
:pt.S:pd.System
:pt.D:pd.Directory
:pt.A:pd.Archive
:eparml.:lm margin=1.
.br
The attributes (other than :hp2.N:ehp2.) can be combined (for example
:hp2.%@ATTRIB[:hp1.MYFILE:ehp1.,HS]:ehp2.).  You can prefix an attribute with
"-" to mean "everything except files with this attribute."
:p.
Without the optional :hp2.p:ehp2. as a third argument, :hp2.ATTRIB:ehp2. will
only return a 1 if all of the attributes match.  With the :hp2.p:ehp2.,
:hp2.ATTRIB:ehp2. will return a 1 if there is a partial match.  For example,
if :hp1.MYFILE.DAT:ehp1. has R, H, and A attributes set:
:xmp.
        %@attrib[myfile.dat,r]   returns 0 because there is not an exact match
:p.
        %@attrib[myfile.dat,r,p] returns 1 because there is a partial match
:exmp.:p.
If you do not specify any attributes, :hp2.ATTRIB:ehp2. will return the
attributes of the specified file in the format :hp2.RHSAD:ehp2., rather than
a "0" or "1".  Attributes which are not set will be replaced with an
underscore.  For example, if :hp1.SECURE.DAT:ehp1. has the read-only, hidden,
and archive attributes set, %:hp2.@ATTRIB[:hp3.SECURE.DAT:ehp3. ]:ehp2.
would return :hp2.RH_A_:ehp2..

.* --------------------------------------------------------------------------

:h3 name=_@CDROM.@CDROM
:p.
:hp2.@CDROM[d&colon.]:ehp2.&colon.  Returns "1" if the drive is a CD-ROM or
"0" otherwise.

.* --------------------------------------------------------------------------

:h3 name=_@CHAR.@CHAR
:p.
:hp2.@CHAR[n]:ehp2.&colon.  Returns the character corresponding to an ASCII
numeric value.  For example :hp2.%@CHAR[65]:ehp2. returns A.

.* --------------------------------------------------------------------------

:h3 name=_@CLIP.@CLIP
:p.
:hp2.@CLIP[n]:ehp2.&colon.  Returns line :hp2.n:ehp2. from the
clipboard.  The first line is numbered 0.  "**EOC**" is returned for all
line numbers beyond the end of the clipboard.

.* --------------------------------------------------------------------------

:h3 name=_@COMMA.@COMMA
:p.
:hp2.@COMMA[n]:ehp2.&colon.  Inserts commas, or the "thousands separator"
character for your system, into a numeric string.  To set the thousands
separator see the :link reftype=hd refid=INI_ThousandsChar.ThousandsChar:elink. directive.

.* --------------------------------------------------------------------------

:h3 name=_@CONVERT.@CONVERT
:p.
:hp2.@CONVERT[input, output, value]:ehp2.&colon.  Converts a numeric string
(:hp2.value:ehp2.) from one number base (:hp2.input:ehp2.) to another
(:hp2.output:ehp2.).  Valid bases range from 2 to 36.  The :hp2.value:ehp2.
must be a positive number between 0 and 2**32-1 (2,147,483,647).  No error
is returned if :hp2.value:ehp2. is outside that range.  For example, to
convert "1010101" from binary to decimal, use this syntax&colon.
:xmp.
        %@convert[2,10,1010101]
:exmp.:p.

.* --------------------------------------------------------------------------

:h3 name=_@DATE.@DATE
:p.
:hp2.@DATE[mm-dd-yy]:ehp2.&colon.  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).  The year can be entered as a 4-digit or
2-digit value.  Two-digit years between 80 and 99 are interpreted as 1980 -
1999; values between 00 and 79 are interpreted as 2000 - 2079.

.* --------------------------------------------------------------------------

:h3 name=_@DAY.@DAY
:p.
:hp2.@DAY[mm-dd-yy]:ehp2.&colon.  Returns the numeric day of the month 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).  The
year can be entered as a 4-digit or 2-digit value.  Two-digit years between
80 and 99 are interpreted as 1980 - 1999; values between 00 and 79 are
interpreted as 2000 - 2079.

.* --------------------------------------------------------------------------

:h3 name=_@DEC.@DEC
:p.
:hp2.@DEC[%var]:ehp2.&colon.  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&colon.
:xmp.
        set var=%@dec[%var]
:exmp.

.* --------------------------------------------------------------------------

:h3 name=_@DESCRIPT.@DESCRIPT
:p.
:hp2.@DESCRIPT[filename]:ehp2.&colon.  Returns the file description for the
specified filename (see :link reftype=hd refid=DESCRIBE.DESCRIBE:elink.).

.* --------------------------------------------------------------------------

:h3 name=_@DEVICE.@DEVICE
:p.
:hp2.@DEVICE[name]:ehp2.&colon.  Returns "1" if the specified name is a
character device (such as a printer or serial port), or "0" if not.

.* --------------------------------------------------------------------------

:h3 name=_@DISKFREE.@DISKFREE
:p.
:hp2.@DISKFREE[d&colon.,b&splitvbar.k&splitvbar.m]:ehp2.&colon. Returns the
amount of free disk space on the specified drive.

.* --------------------------------------------------------------------------

:h3 name=_@DISKTOTAL.@DISKTOTAL
:p.
:hp2.@DISKTOTAL[d&colon.,b&splitvbar.k&splitvbar.m]:ehp2.&colon.  Returns
the total disk space on the specified drive.

.* --------------------------------------------------------------------------

:h3 name=_@DISKUSED.@DISKUSED
:p.
:hp2.@DISKUSED[d&colon.,b&splitvbar.k&splitvbar.m]:ehp2.&colon.  Returns the amount of disk space in use
by files and directories on the specified drive.

.* --------------------------------------------------------------------------

:h3 name=_@DOSMEM.@DOSMEM
:p.
:hp2.@DOSMEM[b&splitvbar.k&splitvbar.m]:ehp2.&colon.  Returns
the size of the largest free memory block (either in physical or virtual
memory).

.* --------------------------------------------------------------------------

:h3 name=_@DOW.@DOW
:p.
:hp2.@DOW[mm-dd-yy]:ehp2.&colon.  Returns the first three characters of the
day of the week for the specified date ("Mon", "Tue", "Wed", etc.).
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).  The
year can be entered as a 4-digit or 2-digit value.  Two-digit years between
80 and 99 are interpreted as 1980 - 1999; values between 00 and 79 are
interpreted as 2000 - 2079.

.* --------------------------------------------------------------------------

:h3 name=_@DOWI.@DOWI
:p.
:hp2.@DOWI[mm-dd-yy]:ehp2.&colon.  Returns the day of the week for the
specified date as an integer (1 = Sunday, 2 = Monday, etc.).  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).  The year can be entered as a
4-digit or 2-digit value.  Two-digit years between 80 and 99 are interpreted
as 1980 - 1999; values between 00 and 79 are interpreted as 2000 - 2079.

.* --------------------------------------------------------------------------

:h3 name=_@DOY.@DOY
:p.
:hp2.@DOY[mm-dd-yy]:ehp2.&colon.  Returns the day of year for the specified
date (1-366).  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).  The
year can be entered as a 4-digit or 2-digit value.  Two-digit years between
80 and 99 are interpreted as 1980 - 1999; values between 00 and 79 are
interpreted as 2000 - 2079.

.* --------------------------------------------------------------------------

:h3 name=_@EAREAD.@EAREAD
:p.
:hp2.@EAREAD[filename, EAname]:ehp2.&colon.  Returns the specified extended
attribute (:hp2. EAname:ehp2.) for a file or an empty string if the extended
attribute does not exist.  This function can only read EAs stored as text;
it cannot read binary EAs.  Wildcards cannot be used in the file name.  For
example, to read the .SUBJECT extended attribute for
:hp1.README.TXT:ehp1.&colon.
:xmp.
        set subject=%@earead[readme.txt,.subject]
:exmp.

.* --------------------------------------------------------------------------

:h3 name=_@EAWRITE.@EAWRITE
:p.
:hp2.@EAWRITE[filename, EAname, [value]]:ehp2.&colon.  Creates or updates the
extended attribute named :hp2.EAname:ehp2. for the specified file.  If the
:hp2.value:ehp2. is not included, the extended attribute is deleted.  Returns
"0" for success or "-1" for failure.  This function can only write EAs stored
as text; it cannot write binary EAs.
:p.
Wildcards cannot be used in the file name and the :hp2.filename:ehp2. must
be in quotes if it contains whitespace or special characters.
:p.
For example, to set the .SUBJECT extended attribute for
:hp1.README.TXT:ehp1. (enter this on one line)&colon.
:xmp.
        if %@eawrite[readme.txt,.subject,Installation notes for
        latest version] != 0 echo EAWRITE failed!
:exmp.

.* --------------------------------------------------------------------------

:h3 name=_@EVAL.@EVAL
:p.
:hp2.@EVAL[expression]:ehp2.&colon.  Evaluates an arithmetic
expression.  @EVAL supports addition (:hp2.+:ehp2.), subtraction
(:hp2.-:ehp2.), multiplication (:hp2.*:ehp2.), division
(:hp2./:ehp2.), integer division (:hp2.\:ehp2., returns the integer
part of the quotient), modulo (:hp2.%%:ehp2.), and integer
exponentiation (:hp2.**:ehp2.).  The expression can contain
environment variables and other variable functions.  @EVAL also
supports parentheses, commas, and decimals.  Parentheses can be
nested.  @EVAL will strip leading and trailing zeros from the result.
When evaluating expressions, :hp2.**:ehp2., :hp2.*:ehp2.,
:hp2./:ehp2., and :hp2.%%:ehp2. take precedence over :hp2.+:ehp2. and
:hp2.-:ehp2..  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
:link reftype=hd refid=_@DEC.@DEC:elink. and
:link reftype=hd refid=_@INC.@INC:elink.
:p.
To ensure that your @EVAL expressions are interpreted correctly, spaces
should be placed on both sides of each operator, for example&colon.
:xmp.
        %@eval[(20 %% 3) + 4]
:exmp.:p.
The maximum precision is 16 digits to the left of the decimal point
and 8 digits to the right of the decimal point.  You can alter
the default precision to the right of the decimal point on the Options 2 page
of the :link reftype=hd refid=OPTION.OPTION:elink. dialogs or with the
:link reftype=hd refid=INI_EvalMax.EvalMax:elink. and
:link reftype=hd refid=INI_EvalMin.EvalMin:elink. directives
in :hp1.&4OS2INI.:ehp1., and with the :link reftype=hd
refid=SETDOS.SETDOS:elink. /F
command.  You can alter the decimal character from the Options 1 page of the
OPTION dialogs, with the
:link reftype=hd refid=INI_DecimalChar.DecimalChar:elink. directive, or the
SETDOS /G command.
:p.
You can alter the precision for a single evaluation with the construct
@EVAL[expression=x.y].  The :hp2.x:ehp2. value specifies the minimum decimal
precision (:hp1.i.e.:ehp1., the minimum number of decimal places displayed);
the :hp2.y:ehp2. value sets the maximum decimal precision.  You can use
:hp2.=x,y:ehp2. instead of :hp2.=x.y:ehp2. if the comma is your decimal
separator.  If :hp2.x:ehp2. is greater than :hp2.y:ehp2., it is
ignored.  You can specify either or both arguments, for example&colon.
:xmp.
        @eval[3 / 7=2]          returns 0.42857143
        @eval[3 / 7=.4]         returns 0.4286
        @eval[3 / 6=2.4]        returns 0.50
:exmp.

.* --------------------------------------------------------------------------

:h3 name=_@EXEC.@EXEC
:p.
:hp2.@EXEC[[@]command]:ehp2.&colon.  Execute the command and return the
numeric exit code.  The command can be an alias, internal command, external
command, or :hp1..BTM:ehp1. file, :hp1..BAT:ehp1., or :hp1..CMD:ehp1. file.
:p.
@EXEC is primarily intended for running a program from within the PROMPT.  It
is a "back door" entry into command processing and :hp8.should be used with
extreme caution:ehp8..  Incorrect or recursive use of @EXEC may hang your
system.
:p.
By default, @EXEC returns the result code from the command; if you
preface the command name with an '@' then @EXEC will return an empty
string.

.* --------------------------------------------------------------------------

:h3 name=_@EXECSTR.@EXECSTR
:p.
:hp2.@EXECSTR[command]:ehp2.&colon.  Runs the specified :hp2.command:ehp2.
and returns the first line written to STDOUT by that :hp2.command:ehp2..
:p.
@EXEC is primarily intended for running a program from within the PROMPT.  It
is a "back door" entry into command processing and :hp8.should be used with
extreme caution:ehp8..  Incorrect or recursive use of @EXEC may hang your
system.
:p.
@EXECSTR is useful for retrieving a result from an external utility -- for
example, if you have an external utility called :hp1.NETTIME.EXE:ehp1. which
retrieves the time of day from your network server and writes it to standard
output, you could save it in an environment variable using a command like
this&colon.
:xmp.
        [c&colon.\] set server_time=%@execstr[d&colon.\path\nettime.exe]
:exmp.:p.
If the same utility returned a result properly formatted for the :link
reftype=hd refid=TIME.TIME:elink. command
you could also use it to set the time on your system&colon.
:xmp.
        [c&colon.\] time %@execstr[d&colon.\path\nettime.exe]
:exmp.:p.

.* --------------------------------------------------------------------------

:h3 name=_@EXETYPE.@EXETYPE
:p.
:hp2.@EXETYPE[filename]:ehp2.&colon.  Returns the application type as a string&colon.
:lm margin=8.:parml compact tsize=14 break=fit.
:pt.DOS:pd.DOS :hp1..COM:ehp1., :hp1..EXE:ehp1., or :hp1..BAT:ehp1.
:pt.AVIO:pd.OS/2 Character mode, windowed
:pt.FS:pd.OS/2 Character mode, full-screen
:pt.PM:pd.OS/2 Presentation Manager
:pt.WIN:pd.Windows 3
:pt.UNKNOWN:pd.Any other file
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h3 name=_@EXPAND.@EXPAND
:p.
:hp2.@EXPAND[filename [,-nrhsda]]&colon.:ehp2.  Returns, on a single line,
the names of all files and directories that match the :hp2.filename:ehp2.
specification, which may contain wildcards and include lists.  Returns an
empty string if no files match.  If the file list is longer than the allowed
command line length, it will be truncated without an error message.
:p.
The second argument, if included, defines the attributes of the files that
will be included in the search.  The attributes are&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.N:pd.Normal (no attributes set)
:pt.R:pd.Read-only
:pt.H:pd.Hidden
:pt.S:pd.System
:pt.D:pd.Directory
:pt.A:pd.Archive
:eparml.:lm margin=1.
.br
The attributes (other than :hp2.N:ehp2.) can be combined (for example
:hp2.%@EXPAND[MYFILE,HS]:ehp2.).  You can prefix an
attribute with "-" to mean "everything except files with this attribute."

If the attribute argument is not used, hidden files, system files, and
directories will be excluded from the returned list; all other files
which match the :hp2.filename:ehp2. will be included.

.* --------------------------------------------------------------------------

:h3 name=_@EXT.@EXT
:p.
:hp2.@EXT[filename]:ehp2.&colon.  Returns the extension from a
:hp2.filename:ehp2., without a leading period.  On HPFS drives the extension
can be up to 64 characters long.  On traditional FAT drives it can be up to
3 characters long.

.* --------------------------------------------------------------------------

:h3 name=_@FILEAGE.@FILEAGE
:p.
:hp2.@FILEAGE[filename[,acw]]:ehp2.&colon.  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, but can not be used for date and time
calculations as it is not returned in identifiable units.

The optional second argument selects which date field is returned for files
on an HPFS drive: :hp2.a:ehp2. means the last access date, :hp2.c:ehp2.
means the creation date, and :hp2.w:ehp2. means the last modification
(write) date, which is the default.

Also see :link reftype=hd refid=_@MAKEAGE.@MAKEAGE:elink..
.* --------------------------------------------------------------------------

:h3 name=_@FILECLOSE.@FILECLOSE
:p.
:hp2.@FILECLOSE[n]:ehp2.&colon.  Closes the file whose handle is
:hp2.n:ehp2..  You cannot close handles 0, 1 or 2.  Returns "0" if the file
closed OK or "-1" if an error occurred.  :hp8.Be sure to read the cautionary
note:ehp8. about file functions under
:link reftype=hd refid=VarFuncs.Variable Functions:elink..

.* --------------------------------------------------------------------------

:h3 name=_@FILEDATE.@FILEDATE
:p.
:hp2.@FILEDATE[filename[,acw]]:ehp2.&colon.  Returns the date a file was last
modified, in the default country format (mm-dd-yy for the US).  The optional
second argument selects which date field is returned for files on an HPFS
drive: :hp2.a:ehp2. means the last access date, :hp2.c:ehp2. means the
creation date, and :hp2.w:ehp2. means the last modification (write) date,
which is the default.

.* --------------------------------------------------------------------------

:h3 name=_@FILENAME.@FILENAME
:p.
:hp2.@FILENAME[filename]:ehp2.&colon.  Returns the name and extension of a
file, without a path.

.* --------------------------------------------------------------------------

:h3 name=_@FILEOPEN.@FILEOPEN
:p.
:hp2.@FILEOPEN[filename, read &splitvbar. write &splitvbar. append, [b &splitvbar. t]]:ehp2.&colon.  Opens the file in
the specified mode and returns the file handle as an integer.  Returns "-1" if the
file cannot be opened.
:p.
The optional third parameter controls whether the file is opened in binary mode
("b") or text mode ("t").  Text mode (the default) should be used to read text
using :link reftype=hd refid=_@FILEREAD.@FILEREAD:elink. :hp2.without:ehp2. a
"length" parameter, and to write text using :link reftype=hd refid=_@FILEWRITE.@FILEWRITE:elink..  Binary
mode should be used to read binary data with @FILEREAD :hp2.with:ehp2. a "length"
parameter, and to write binary data with :link reftype=hd refid=_@FILEWRITEB.@FILEWRITEB:elink..
:p.
:hp8.Be sure to read the cautionary note:ehp8. about file functions under
:link reftype=hd refid=VarFuncs.Variable Functions:elink..
:p.
@FILEOPEN can also open named pipes.  The pipe name must begin with
:hp2.\pipe\:ehp2..  @FILEOPEN first tries to open an existing pipe; if that
fails it tries to create a new pipe.  Pipes are opened in blocking mode,
duplex access, byte-read mode, and inheritable.  For more information
on named pipes see your OS/2 documentation.

.* --------------------------------------------------------------------------

:h3 name=_@FILEREAD.@FILEREAD
:p.
:hp2.@FILEREAD[n [,length]]:ehp2.&colon.
Reads data from the file whose handle is :hp2.n:ehp2..  Returns "**EOF**" if
you attempt to read past the end of the file.  If :hp2.length:ehp2. is not
specified @FILEREAD will read until the next CR or LF (end of line)
character.  If :hp2.length:ehp2. is specified, @FILEREAD will read
:hp2.length:ehp2. bytes regardless of any end of line characters.
:p.
If you plan to read text a line at a time, without using :hp2.length:ehp2.,
you should open the file in text mode.  If you plan to read binary data using
:hp2.length:ehp2., you should open the file in binary mode.  See :link
reftype=hd refid=_@FILEOPEN.@FILEOPEN:elink.
for details on opening the file in the proper mode.
:p.
Be sure to read the cautionary note about file functions under :link
reftype=hd refid=VarFuncs.Variable Functions:elink..

.* --------------------------------------------------------------------------

:h3 name=_@FILES.@FILES
:p.
:hp2.@FILES[filename [,-nrhsda]]:ehp2.&colon.  Returns the number of files
that match the filename, which may contain wildcards and include
lists.  Returns "0" if no files match.  The filename must refer to
a single directory; to check several directories, use @FILES once for each
directory, and add the results together with
:link reftype=hd refid=_@EVAL.@EVAL:elink..
:p.
The second argument is a list of file attributes.  If it is included, only
those files matching all the specified attributes are counted.  The
attributes are&colon.

:lm margin=8.:parml compact tsize=4 break=fit.
:pt.N:pd.Normal (no attributes set)
:pt.R:pd.Read-only
:pt.H:pd.Hidden
:pt.S:pd.System
:pt.D:pd.Directory
:pt.A:pd.Archive
:eparml.:lm margin=1.
.br

The attributes (other than :hp2.N:ehp2.) can be combined (for example
:hp2.%@FILES[MYFILE,HS]:ehp2.).  You can prefix an attribute with
:hp2.-:ehp2. to mean "everything except files with this attribute."

.* --------------------------------------------------------------------------

:h3 name=_@FILESEEK.@FILESEEK
:p.
:hp2.@FILESEEK[n,offset,start]:ehp2.&colon.  Moves the file pointer :hp2.offset:ehp2.
bytes in the file whose handle is :hp2.n:ehp2..  Returns the new position of
the pointer, in bytes from the start of the file.  Set :hp2.start:ehp2. 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).  :hp8.Be sure to read the cautionary note:ehp8. about file
functions under :link reftype=hd refid=VarFuncs.Variable Functions:elink..

.* --------------------------------------------------------------------------

:h3 name=_@FILESEEKL.@FILESEEKL
:p.
:hp2.@FILESEEKL[n,line]:ehp2.&colon.  Moves the file pointer to the
specified :hp2.line:ehp2. in the
file whose handle is :hp2.n:ehp2..  The first line in the file is numbered
0.  Returns the new position of the pointer, in bytes
from the start of the file.:hp8.  Be sure to read the cautionary note:ehp8. about file
functions under :link reftype=hd refid=VarFuncs.Variable Functions:elink..
:p.
@FILESEEKL must read each line of the file up to the target line in order to
position the pointer, and will therefore cause significant delays if used in
a long loop or on a large file.

.* --------------------------------------------------------------------------

:h3 name=_@FILESIZE.@FILESIZE
:p.
:hp2.@FILESIZE[filename,b&splitvbar.k&splitvbar.m[,a]]:ehp2.&colon.  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.
:p.
The optional third argument :hp2.a:ehp2. (allocated), if used, instructs
@FILESIZE to return the amount of space allocated for the file(s) on the
disk, rather than the amount of data in the file.  Network drives and
compressed drives may not always report allocated sizes accurately,
depending on the way the network or disk compression software
is implemented.

.* --------------------------------------------------------------------------

:h3 name=_@FILETIME.@FILETIME
:p.
:hp2.@FILETIME[filename[,acw]]:ehp2.&colon.  Returns the time a file was last
modified, in hh&colon.mm format.  The optional second argument selects which
time field is returned for files on an HPFS drive&colon.  :hp2.a:ehp2. means
the last access time, :hp2.c:ehp2. means the creation time, and :hp2.w:ehp2.
means the last modification (write) time, which is the default.

.* --------------------------------------------------------------------------

:h3 name=_@FILEWRITE.@FILEWRITE
:p.
:hp2.@FILEWRITE[n,text]:ehp2.&colon.  Writes a line to the file whose handle is
:hp2.n:ehp2..  Returns the number of bytes written, or "-1" if an error
occurred.  :hp2.n:ehp2. must be a handle returned by :link reftype=hd
refid=_@FILEOPEN.@FILEOPEN:elink.; or 1 (for standard output) or 2 (for
standard error).
:p.
:hp8.Be sure to read the cautionary note:ehp8. about file functions
under :link reftype=hd refid=VarFuncs.Variable Functions:elink..

.* --------------------------------------------------------------------------

:h3 name=_@FILEWRITEB.@FILEWRITEB
:p.
:hp2.@FILEWRITEB[n,length,string]:ehp2.&colon.  Writes the specified number
of bytes from :hp2.string:ehp2. to the file whose handle is :hp2.n:ehp2..  Returns the number of
bytes written, or "-1" if an error occurred.
:p.
If you plan to write binary data with @FILEWRITEB, you should open the file in binary
mode (see :link reftype=hd refid=_@FILEOPEN.@FILEOPEN:elink.).  If you want to write
text a line at a time you should use :link reftype=hd refid=_@FILEWRITE.@FILEWRITE:elink. instead,
and open the file in text mode.
:p.
:hp8.Be sure to read the cautionary note:ehp8. about file functions under
:link reftype=hd refid=VarFuncs.Variable Functions:elink..

.* --------------------------------------------------------------------------

:h3 name=_@FINDCLOSE.@FINDCLOSE
:p.
:hp2.@FINDCLOSE[filename]:ehp2.&colon.  Signals the end of a :link
reftype=hd refid=_@FINDFIRST.@FINDFIRST:elink. /
:link reftype=hd refid=_@FINDNEXT.@FINDNEXT:elink. sequence.  You
:hp2.must:ehp2. use this function to release the directory search handle
used for @FINDFIRST / @FINDNEXT.

.* --------------------------------------------------------------------------

:h3 name=_@FINDFIRST.@FINDFIRST
:p.
:hp2.@FINDFIRST[filename [,-nrhsda]]:ehp2.&colon.  Returns the name of the first
file that matches the filename, which may contain wildcards and "include lists."  The
second argument, if included, defines the attributes of the files
that will be included in the search.  Returns an empty string if no
files match.  The attributes are&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.N:pd.Normal (no attributes set)
:pt.R:pd.Read-only
:pt.H:pd.Hidden
:pt.S:pd.System
:pt.D:pd.Directory
:pt.A:pd.Archive
:eparml.:lm margin=1.
.br
The attributes (other than :hp2.N:ehp2.) can be combined (for example
:hp2.%@FINDFIRST[MYFILE,HS]:ehp2.).  You can prefix an attribute
with :hp2.-:ehp2. to mean "everything except files with this attribute."
:p.
@FINDFIRST always skips the "." and ".." entries when processing directory names.
:p.
After @FINDFIRST or the last
:link reftype=hd refid=_@FINDNEXT.@FINDNEXT:elink., you :hp2.must:ehp2. use
:link reftype=hd refid=_@FINDCLOSE.@FINDCLOSE:elink. to avoid running out of
directory search handles.
:p.
See the notes under :link reftype=hd refid=VarFuncs.Variable Functions:elink.
about quoting returned long filenames.

.* --------------------------------------------------------------------------

:h3 name=_@FINDNEXT.@FINDNEXT
:p.
:hp2.@FINDNEXT[filename [,-nrhsda]]:ehp2.&colon.  Returns the name of the
next file that matches the filename passed to :link reftype=hd refid=_@FINDFIRST.@FINDFIRST:elink..
@FINDNEXT should only be used after a successful call to
:link reftype=hd refid=_@FINDFIRST.@FINDFIRST:elink..  The first argument is included for compatibility with
previous versions, but is ignored; it can be omitted if the second
argument is not used (:hp1.e.g.:ehp1. %@FINDNEXT[]).  The second argument,
if included, defines the attributes of the files that will be included in
the search.  Returns an empty string when no more files match.  The
attributes are&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.N:pd.Normal (no attributes set)
:pt.R:pd.Read-only
:pt.H:pd.Hidden
:pt.S:pd.System
:pt.D:pd.Directory
:pt.A:pd.Archive
:eparml.:lm margin=1.
.br
The attributes (other than :hp2.N:ehp2.) can be combined (for example
:hp2.%@FINDNEXT[MYFILE,HS]:ehp2.).  You can prefix an attribute
with :hp2.-:ehp2. to mean "everything except files with this attribute."
:p.
@FINDNEXT always skips the "." and ".." entries when processing directory
names.
:p.
After :link reftype=hd refid=_@FINDFIRST.@FINDFIRST:elink. or the last
@FINDNEXT, you :hp2.must:ehp2. use
:link reftype=hd refid=_@FINDCLOSE.@FINDCLOSE:elink. to avoid running out of
directory search handles.
:p.
See the notes under :link reftype=hd refid=VarFuncs.Variable Functions:elink.
about quoting returned long filenames.

.* --------------------------------------------------------------------------

:h3 name=_@FORMAT.@FORMAT
:p.
:hp2.@FORMAT[[-][x][.y],string]:ehp2.&colon.  Reformats a string, truncating
it or padding it with spaces as necessary.  If you use the minus [-], the
string is left-justified; otherwise, it is right-justified.  The
:hp2.x:ehp2. value is the minimum number of characters in the result.  The
:hp2.y:ehp2. value is the maximum number of characters in the result.  You
can combine the options as necessary.  For example&colon.
:xmp.
        %@format[12,JPSoftware]         returns "  JPSoftware"
        %@format[.3,JPSoftware]         returns "JPS"
:exmp.

.* --------------------------------------------------------------------------

:h3 name=_@FSTYPE.@FSTYPE
:p.
:hp2.@FSTYPE[d&colon.]:ehp2.&colon.  Returns the file system type for the specified
drive.  @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 :hp1.CONFIG.SYS:ehp1..

.* --------------------------------------------------------------------------

:h3 name=_@FULL.@FULL
:p.
:hp2.@FULL[filename]:ehp2.&colon.  Returns the fully qualified path and file
name of a file.
:p.
See the notes under :link reftype=hd refid=VarFuncs.Variable Functions:elink.
about quoting returned long filenames.

.* --------------------------------------------------------------------------

:h3 name=_@IF.@IF
:p.
:hp2.@IF[condition,true,false]:ehp2.&colon.  Evaluates the condition and returns a string
based on the result.  The condition can include any of the tests allowed in
the :link reftype=hd refid=IF.IF:elink. command.  If the condition is true, @IF returns the first result
string; if it is false, @IF returns the second string.  For example,
"echo %@IF[2 == 2,Correct!,Oops!]" displays "Correct!"

.* --------------------------------------------------------------------------

:h3 name=_@INC.@INC
:p.
:hp2.@INC[%var]:ehp2.&colon.  Returns the same value as
%:link reftype=hd refid=_@EVAL.@EVAL:elink.[%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&colon.
:xmp.
        set var=%@inc[%var]
:exmp.
.* --------------------------------------------------------------------------

:h3 name=_@INDEX.@INDEX
:p.
:hp2.@INDEX[string1,string2]:ehp2.&colon.  Returns the position of string2
within :hp2.string1:ehp2., or "-1" if :hp2.string2:ehp2. is not found.  The
first position in :hp2.string1:ehp2. is numbered 0.

.* --------------------------------------------------------------------------

:h3 name=_@INSERT.@INSERT
:p.
:hp2.@INSERT[n, string1, string2]:ehp2.&colon.  Inserts :hp2.string1:ehp2.
into :hp2.string2:ehp2. starting at position :hp2.n:ehp2..  The first
position in the string is postion 0.  For example,
:hp2.%@insert[1,arm,wing]:ehp2. returns the string "warming".

.* --------------------------------------------------------------------------

:h3 name=_@INSTR.@INSTR
:p.
:hp2.@INSTR[start, length, string]:ehp2.&colon.  Returns a substring,
starting at the position :hp2.start:ehp2. and continuing for
:hp2.length:ehp2. characters.  If the :hp2.length:ehp2. is omitted, it will
default to the remainder of the :hp2.string:ehp2..  If the :hp2.length:ehp2.
is negative, the start is relative to the right side of the
:hp2.string:ehp2..  The first character in the :hp2.string:ehp2. is numbered
0; if the :hp2.length:ehp2. is negative, the last character is numbered 0.
:p.
For example, %@INSTR[0,2,%_TIME] gets the current time and extracts the hour;
%@INSTR[1,-2,%_TIME] extracts the seconds.  If the :hp2.string:ehp2. includes
commas, it must be quoted with double quotes [:hp2.":ehp2.] or back-quotes
[:hp2.`:ehp2.].  The quotes :hp2.do:ehp2. count in calculating the position
of the substring.  :link reftype=hd refid=_@SUBSTR.@SUBSTR:elink. is an older
version of the same function.

.* --------------------------------------------------------------------------

:h3 name=_@INT.@INT
:p.
:hp2.@INT[n]:ehp2.&colon.  Returns the integer part of the number
:hp2.n:ehp2..

.* --------------------------------------------------------------------------

:h3 name=_@LABEL.@LABEL
:p.
:hp2.@LABEL[d&colon.]:ehp2.&colon.  Returns the volume label of the
specified disk drive.

.* --------------------------------------------------------------------------

:h3 name=_@LEFT.@LEFT
:p.
:hp2.@LEFT[n, string]:ehp2.&colon.  Returns the leftmost :hp2.n:ehp2.
characters from the :hp2.string:ehp2..  If :hp2.n:ehp2. is greater than the
length of the :hp2.string:ehp2., returns the entire :hp2.string:ehp2..  For
example, :hp2.%@left[2,jpsoft]:ehp2. returns the string "jp".

.* --------------------------------------------------------------------------

:h3 name=_@LEN.@LEN
:p.
:hp2.@LEN[string]:ehp2.&colon.  Returns the length of a :hp2.string:ehp2..

.* --------------------------------------------------------------------------
:h3 name=_@LINE.@LINE
:p.
:hp2.@LINE[filename,n]:ehp2.&colon.  Returns line :hp2.n:ehp2. 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.
:p.
@LINE works with files having lines of no more than 1023 characters; longer
lines will not be counted accurately.
:p.
The @LINE function must read each line of the file to find the line you
request, and will therefore cause significant delays if used in a long loop
or on a large file.  For a more effective method of processing each line of
a file in sequence use the :link reftype=hd refid=FOR.FOR:elink. command, or
:link reftype=hd refid=_@FILEOPEN.@FILEOPEN:elink. and a sequence of
:link reftype=hd refid=_@FILEREAD.@FILEREAD:elink.s.
:p.
You can retrieve input from standard input if you specify CON as the
filename.  If you are :link reftype=hd refid=Redirection.redirecting:elink.
input to @LINE using this feature, you must use
:link reftype=hd refid=Grouping.command grouping:elink. or the redirection
will not work properly (you can :link reftype=hd refid=Piping.pipe:elink. to
@LINE without a command group; this restriction applies only to input
redirection).  For example&colon.
:xmp.
        (echo %@line[con,0]) < myfile.dat
:exmp.

.* --------------------------------------------------------------------------

:h3 name=_@LINES.@LINES
:p.
:hp2.@LINES[filename]:ehp2.&colon.  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.  To get the actual number of lines, use
%@INC[%@LINES[filename]].
:p.
@LINES works with files having lines of no more than 1023 characters; longer
lines will not be counted accurately.
:p.
@LINES must read each line of the file in order to count it, and will
therefore cause significant delays if used in a long loop or on a large file.

.* --------------------------------------------------------------------------

:h3 name=_@LOWER.@LOWER
:p.
:hp2.@LOWER[string]:ehp2.&colon.  Returns the :hp2.string:ehp2. converted to
lower case.

.* --------------------------------------------------------------------------

:h3 name=_@MAKEAGE.@MAKEAGE
:p.
:hp2.@MAKEAGE[date[,time]]:ehp2.&colon.  Returns the date and time (if
included) as a single value in the same format as :link reftype=hd
refid=_@FILEAGE.@FILEAGE:elink..  @MAKEAGE can be used to compare the time
stamp of a file with a specific date and time, for example&colon.
:xmp.
        if %@fileage[myfile] lt %@makeage[1/1/85] echo OLD!
:exmp.:p.
The value returned by @MAKEAGE can be used for comparisons, but can not be
used for date and time calculations because it is not in identifiable units.

.* --------------------------------------------------------------------------

:h3 name=_@MAKEDATE.@MAKEDATE
:p.
:hp2.@MAKEDATE[n]:ehp2.&colon.  Returns a date (formatted according to the
current country settings).  :hp2.n:ehp2. is the number of days since 1/1/80.
This is the inverse of :link reftype=hd refid=_@DATE.@DATE:elink..

.* --------------------------------------------------------------------------

:h3 name=_@MAKETIME.@MAKETIME
:p.
:hp2.@MAKETIME[n]:ehp2.&colon.  Returns a time (formatted according to the
current country settings).  :hp2.n:ehp2. is the number of seconds since
midnight.  This is the inverse of :link reftype=hd refid=_@TIME.@TIME:elink..

.* --------------------------------------------------------------------------

:h3 name=_@MONTH.@MONTH
:p.
:hp2.@MONTH[mm-dd-yy]:ehp2.&colon.  Returns the month number for the
specified date (1-12).  MONTH uses the date format and separators mandated
by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan).
The year can be entered as a 4-digit or 2-digit value.  Two-digit years
between 80 and 99 are interpreted as 1980 - 1999; values between 00 and 79
are interpreted as 2000 - 2079.

.* --------------------------------------------------------------------------

:h3 name=_@NAME.@NAME
:p.
:hp2.@NAME[filename]:ehp2.&colon.  Returns the base name of a file, without
the path or extension.
:p.
See the notes under :link reftype=hd refid=VarFuncs.Variable Functions:elink.
about quoting returned long filenames.

.* --------------------------------------------------------------------------

:h3 name=_@NUMERIC.@NUMERIC
:p.
:hp2.@NUMERIC[string]:ehp2.&colon.  Returns "1" if the argument is composed
entirely of digits (0 to 9), signs (:hp2.+:ehp2. or :hp2.-:ehp2.), and the
thousands and decimal separators.  Otherwise, returns "0".  If the
:hp2.string:ehp2. begins with a decimal separator it is not considered
numeric unless the next character is a digit, and there are no more decimal
separators within the string.  For example, ".07" is numeric, but ".a" and
".07.01" are not.

.* --------------------------------------------------------------------------

:h3 name=_@PATH.@PATH
:p.
:hp2.@PATH[filename]:ehp2.&colon.  Returns the path from a file name, including
the drive letter and a trailing backslash but not including the
base name or extension.
:p.
See the notes under :link reftype=hd refid=VarFuncs.Variable Functions:elink.
about quoting returned long filenames.

.* --------------------------------------------------------------------------

:h3 name=_@RANDOM.@RANDOM
:p.
:hp2.@RANDOM[min, max]:ehp2.&colon.  Returns a "pseudo-random" value between
:hp2.min:ehp2. and :hp2.max:ehp2., inclusive.  :hp2.Min:ehp2.,
:hp2.max:ehp2., and the returned value are all integers.
:p.
The random number generator is initialized from the system clock the first
time it is used after the command processor starts, so it will produce a
different sequence of random numbers each time you use it.

.* --------------------------------------------------------------------------

:h3 name=_@READSCR.@READSCR
:p.
:hp2.@READSCR[row,col,length]:ehp2.&colon.  Returns the text displayed on the
screen at the specified location.  The upper left corner of the
screen is location 0,0.
:p.
The :hp2.row:ehp2. and :hp2.column:ehp2. can be specified as an offset from
the current cursor location by preceding either value with a [:hp2.+:ehp2.] or
[:hp2.-:ehp2.].  For example,
:xmp.
        %@readscr[-2,+2,10]
:exmp.:p.
returns 10 characters from the screen, starting 2 rows above and 2 columns to
the right of the current cursor position.
:p.
You can also specify the row and column as offsets from the current cursor
position.  Begin the value with a plus sign [:hp2.+:ehp2.] to read the
screen the specified number of rows below (or columns to the right of) the
current position, or with a minus sign [:hp2.-:ehp2.] to read the screen
above (or to the left of) the current position.

.* --------------------------------------------------------------------------

:h3 name=_@READY.@READY
:p.
:hp2.@READY[d&colon.]:ehp2.&colon.  Returns "1" if the specified drive is
ready; otherwise returns "0".

.* --------------------------------------------------------------------------

:h3 name=_@REMOTE.@REMOTE
:p.
:hp2.@REMOTE[d&colon.]:ehp2.&colon.  Returns "1" if the specified drive is a remote
(network) drive; otherwise returns "0".

.* --------------------------------------------------------------------------

:h3 name=_@REMOVABLE.@REMOVABLE
:p.
:hp2.@REMOVABLE[d&colon.]:ehp2.&colon.  Returns "1" if the specified drive is
removable (:hp1.e.g.:ehp1., a floppy disk or removable hard disk);
otherwise returns "0".

.* --------------------------------------------------------------------------

:h3 name=_@REPEAT.@REPEAT
:p.
:hp2.@REPEAT[c,n]:ehp2.&colon.  Returns the character :hp2.c:ehp2. repeated
:hp2.n:ehp2. times.

.* --------------------------------------------------------------------------

:h3 name=_@REPLACE.@REPLACE
:p.
:hp2.@REPLACE[string1, string2, text]:ehp2.&colon.  Replaces all occurrences
of :hp2.string1:ehp2. in the :hp2.text:ehp2. string with
:hp2.string2:ehp2..  For example, :hp2.%@replace[w,ch,warming]:ehp2. returns
the string "charming".  The search :hp2.is:ehp2. case-sensitive.

.* --------------------------------------------------------------------------

:h3 name=_@REXX.@REXX
:p.
:hp2.@REXX[expr]:ehp2.&colon.  Calls the REXX interpreter to execute the
:hp2.expr:ehp2.ession.  Returns the result string from REXX; if the REXX
expression does not return a string, @REXX returns the REXX numeric result
code.  See :link reftype=hd refid=REXX.REXX Support:elink. for more
information.

.* --------------------------------------------------------------------------

:h3 name=_@RIGHT.@RIGHT
:p.
:hp2.@RIGHT[n,string]:ehp2.&colon.  Returns the rightmost :hp2.n:ehp2.
characters from the :hp2.string:ehp2..  If :hp2.n:ehp2. is greater than the
length of the :hp2.string:ehp2., returns the entire string.  For example,
:hp2.%@right[4,jpsoft]:ehp2. returns the string "soft."

.* --------------------------------------------------------------------------

:h3 name=_@SEARCH.@SEARCH
:p.
:hp2.@SEARCH[filename[,path]]:ehp2.&colon.  Searches for the
:hp2.filename:ehp2. using the :link reftype=hd refid=PATH_Var.PATH:elink.
environment variable or the specified :hp2.path:ehp2., appending an extension
if one isn't specified.
:p.
@SEARCH 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,
:hp2.@SEARCH:ehp2. will search for the first file that matches the
wildcard specification, and return the drive and path for that file
plus the wildcard filename (:hp1.e.g.:ehp1., :hp1.E&colon.\UTIL\*.COM:ehp1.).

.* --------------------------------------------------------------------------

:h3 name=_@SELECT.@SELECT
:p.
:hp2.@SELECT[filename,top,left,bottom,right,title[,1]]:ehp2.&colon.  Pops up
a selection window with the lines from the specified file, allowing you to
display menus or other selection lists from within a batch file.  You can
move through the selection window with standard :link reftype=hd
refid=Popup.popup window:elink. navigation keystrokes, including character
matching.  @SELECT returns the text of the line the scrollbar is on if you
press :hp2.Enter:ehp2., or an empty string if you press :hp2.Esc:ehp2..  The
filename must be in quotes if it contains whitespace or special
characters.  The file size is limited only by available memory.  To select
from lines passed through input redirection or a pipe, use :hp2.CON:ehp2. as
the filename.  If you use the optional :hp2.1:ehp2. argument after the
window title, the list will be sorted alphabetically.

.* --------------------------------------------------------------------------

:h3 name=_@STRIP.@STRIP
:p.
:hp2.@STRIP[chars,string]:ehp2.&colon.  Removes the characters in
:hp2.chars:ehp2. from the :hp2.string:ehp2. and returns the result.  For
example, %@STRIP[AaEe,All Good Men] returns "ll Good Mn".  The test is case
sensitive.  To include a comma in the :hp2.chars:ehp2. string,
enclose the entire first argument in double quotes.  @STRIP will remove the
quotes before processing the :hp2.string:ehp2..

.* --------------------------------------------------------------------------

:h3 name=_@SUBSTR.@SUBSTR
:p.
:hp2.@SUBSTR[string,start,length]:ehp2.&colon.  This is an older version of
:link reftype=hd refid=_@INSTR.@INSTR:elink. The :hp2.string:ehp2. parameter
is at the start of the @SUBSTR argument list, and therefore cannot contain
commas (because any commas in the string would be taken as argument
separators).  @INSTR, which has the :hp2.string:ehp2. argument last, does not
have this restriction.

.* --------------------------------------------------------------------------

:h3 name=_@TIME.@TIME
:p.
:hp2.@TIME[hh&colon.mm&colon.ss]:ehp2.&colon.  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.

.* --------------------------------------------------------------------------

:h3 name=_@TIMER.@TIMER
:p.
:hp2.@TIMER[n]:ehp2.&colon.  Returns the current split time for a stopwatch started with
the :link reftype=hd refid=TIMER.TIMER:elink. command.  The value of
:hp2.n:ehp2. specifies the timer to read and can be 1, 2, or 3.

.* --------------------------------------------------------------------------

:h3 name=_@TRIM.@TRIM
:p.
:hp2.@TRIM[string]:ehp2.&colon.  Returns the :hp2.string:ehp2. with the
leading and trailing white space (space and tab characters) removed.

.* --------------------------------------------------------------------------

:h3 name=_@UNIQUE.@UNIQUE
:p.
:hp2.@UNIQUE[d&colon.\path]:ehp2.&colon.  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 or HPFS drive.  This function
allows you to create a temporary file without overwriting an existing file.

.* --------------------------------------------------------------------------

:h3 name=_@UPPER.@UPPER
:p.
:hp2.@UPPER[string]:ehp2.&colon.  Returns the :hp2.string:ehp2. converted to
upper case.

.* --------------------------------------------------------------------------

:h3 name=_@WILD.@WILD
:p.
:hp2.@WILD[string1,string2]:ehp2.&colon.  Performs a comparison of the two
strings, and returns "1" if they match or "0" if they don't match.  The
second argument, :hp2.string2:ehp2., may contain wildcards or extended
wildcards; the first argument, :hp2.string1:ehp2., may not.  The test is not
case sensitive.  The following example tests whether the \UTIL directory
(or any directory that begins with the characters UTIL) is included in the
:link reftype=hd refid=PATH_Var.PATH:elink.&colon.
:xmp.
        if %@wild[%path,*\UTIL*] == 1 :hp1.command:ehp1.
:exmp.:p.

.* --------------------------------------------------------------------------

:h3 name=_@WORD.@WORD
:p.
:hp2.@WORD[["xxx",]n,string]:ehp2.&colon.  Returns the :hp2.n:ehp2.th word
in a string.  The first word is numbered 0.  If :hp2.n:ehp2. is negative,
words are returned from the end of the string.  The first argument is a list
of word separators you want to use; if you don't specify it, only spaces,
tabs, and commas are considered to be word separators.  For example&colon.
:xmp.
        %@WORD[2,NOW IS THE TIME]     returns "THE"
        %@WORD[-0,NOW IS THE TIME]    returns "TIME"
        %@WORD[-2,NOW IS THE TIME]    returns "IS"
        %@WORD["=",1,2 + 2=4]         returns "4"
:exmp.

.* --------------------------------------------------------------------------

:h3 name=_@WORDS.@WORDS
:p.
:hp2.@WORDS[["xxx",]string]:ehp2.&colon.  Returns the number of words in the
:hp2.string:ehp2..  The optional list of separators follows the same format as
:link reftype=hd refid=_@WORD.@WORD:elink..  If the :hp2.string:ehp2.
argument is enclosed in quotation marks, you must enter a list of separators
as well.

.* --------------------------------------------------------------------------

:h3 name=_@YEAR.@YEAR
:p.
:hp2.@YEAR[mm-dd-yy]:ehp2.&colon.  Returns the year for the specified
date.  YEAR uses the date format and separators mandated by your country code
(for example dd.mm.yy in Germany, or yy-mm-dd in Japan).  The year can be
specified as two digits or four digits; @YEAR returns the same number of
digits included in its argument.  Two-digit years between 80 and 99
are interpreted as 1980 - 1999; values between 00 and 79 are interpreted as
2000 - 2079.

.* --------------------------------------------------------------------------

:h1 name=INIFile.&4OS2INI.
:p.
Most of the configuration of &4OS2. is controlled through a file of
initialization information called :hp1.&4OS2INI.:ehp1., which is discussed in
the following sections:
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=INIModify.Modifying the .INI File:elink.
:pt.:pd.:link reftype=hd refid=INIUsing.Using the .INI File:elink.
:pt.:pd.:link reftype=hd refid=INISections..INI File Sections:elink.
:pt.:pd.:link reftype=hd refid=INIDirectives..INI File Directives:elink.
:pt.:pd.:link reftype=hd refid=INIExamples..INI File Examples:elink.
:eparml.:lm margin=1.
.br
We also discuss many ways of configuring &4OS2. in other sections of the help,
for example&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.*:pd.With :link reftype=hd refid=Aliases.aliases:elink. you can set
default options for internal commands and create new commands.
:pt.*:pd.With :link reftype=hd refid=ExeExt.executable extensions:elink.
you can associate data files with the applications you use to open them.
:pt.*:pd.With the :link reftype=hd
refid=FILECOMPLETION.FILECOMPLETION:elink. environment variable and the
:link reftype=hd refid=INI_FileCompletion.FileCompletion:elink. .INI
directive you can customize filename completion to match the command you
are working with.
:pt.*:pd.With the :link reftype=hd refid=COLORDIR_Var.COLORDIR:elink.
environment variable and the :link reftype=hd
refid=INI_ColorDir.ColorDir:elink. :hp1..INI:ehp1. directive you can set the
colors used by the :link reftype=hd refid=DIR.DIR:elink. and :link reftype=hd
refid=SELECT.SELECT:elink. commands.
:pt.*:pd.With the :link reftype=hd refid=SETDOS.SETDOS:elink. command, you
can change some aspects of the command processor's operation "on the fly."
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=INIModify.Modifying the .INI File
:p.
You can create, add to, and modify the :hp1..INI:ehp1. file in 2
ways&colon. with the OPTION command and by editing the file with any ASCII
editor.  OPTION displays a set of dialogs which allow you to modify the
settings that are used most often.  When you exit from the dialogs, you can
select the :hp2.Save:ehp2. button to save your changes in the
:hp1..INI:ehp1. file for use in the current session and all future
sessions, select the :hp2.Use:ehp2. or :hp2.OK:ehp2. button to use your
changes in the current session only, or discard the changes you have made
by selecting the :hp2.Cancel :ehp2. button.  See the :link reftype=hd
refid=OPTION.OPTION:elink. command for additional details.
:p.
Changes you make in the :hp2.Startup:ehp2. section of the OPTION dialogs
will only take effect when you restart the session or window in which &4OS2.
is running.
:p.
OPTION handles most standard :hp1..INI :ehp1.file settings.  A few more
advanced settings, as well as all settings that affect the interpretation
of keystrokes, cannot be modified with OPTION and must be inserted or
modified manually.  For more details see the :link reftype=hd
refid=OPTION.OPTION:elink. command.
:p.
You can also create, add to, and edit the :hp1.&4OS2INI.:ehp1. file
"manually" with any ASCII text editor.  Each command processor reads its
:hp1..INI:ehp1. file when it starts, and configures itself accordingly.
The :hp1..INI:ehp1. file is not re-read when you change it manually.  For
manual changes to take effect, you must restart the session or window in
which &4OS2. is running.  If you edit the :hp1..INI:ehp1. file manually, make
sure you save the file in ASCII format.
:p.
Each item that you can include in the :hp1..INI:ehp1. 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.
:p.
:p.
:hp2.Format&colon.:ehp2.
:p.
Most lines in the :hp1..INI :ehp1.file consist of a one-word
:hp2.directive:ehp2., an equal sign [:hp2.=:ehp2.], and a
:hp2.value:ehp2..  For example, in the following line, the word
"Environment" is the directive and "2048" is the value&colon.
:xmp.
        Environment = 2048
:exmp.:p.
Any spaces before or after the equal sign are ignored.
:p.
If you have a long string to enter in the :hp1..INI:ehp1. file (for
example, for the :link reftype=hd refid=INI_ColorDir.ColorDir:elink.
directive), you must enter it all on one line.  Strings cannot be
"continued" to a second line.  Each line may be up to 1023 characters long.
:p.
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.
:p.
Blank lines are ignored in the :hp1..INI:ehp1. file and can be used to
separate groups of directives.  You can place comments in the file by
beginning a line with a semicolon [:hp2.;:ehp2.].  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&colon.
:xmp.
        Environment = 2048     ;set standard environment size
:exmp.:p.
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.
:p.
If you use the :link reftype=hd refid=OPTION.OPTION:elink. dialogs to
modify the :hp1..INI:ehp1. file, comments on lines modified from within
the dialogs will not be preserved when the new lines are saved.  To be
sure :hp1..INI:ehp1. file comments are preserved, put them on separate lines in the
file
:p.
If you want to include the text of one :hp1..INI:ehp1. file within another
(for example, if you have a set of common directives used by several JP
Software products), see the :link reftype=hd refid=INI_Include.Include:elink.
directive.

.* --------------------------------------------------------------------------

:h2 name=INIUsing.Using the .INI File
:p.
Some settings in the :hp1..INI:ehp1. file are initialized when you install
&4OS2., so you will probably have a :hp1.&4OS2INI.:ehp1. file even if you didn't
create one yourself.
:p.
&4OS2. primary shells search for the :hp1..INI:ehp1. file in three places&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.*:pd.If there is an "@d&colon.\path\inifile" option on the startup
command line, the command processor will use the path and file name
specified there, and will not look elsewhere.  See :link reftype=hd
refid=Startup.Starting &4OS2.:elink. for details.
:pt.*:pd.If there is no :hp1..INI :ehp1.file name on the startup command
line, the search proceeds to the same directory where the command processor
program file (:hp1.&4OS2..EXE:ehp1.) is stored.  This is the "normal" location
for the :hp1..INI:ehp1. file.  &4OS2. determines this directory automatically.
:pt.*:pd.If the :hp1..INI:ehp1. 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.
:eparml.:lm margin=1.
.br
When &4OS2. is loaded as a secondary shell, it does not search for the
:hp1..INI:ehp1. file.  Instead, it retrieves the primary shell's
:hp1..INI:ehp1. file data, processes the :hp2.[Secondary]:ehp2. section of
the original :hp1..INI:ehp1. file if necessary (see :link reftype=hd
refid=INISections..INI File Sections:elink.), and then processes any
"@d&colon.\path\inifile" option on the secondary shell command line (see
:link reftype=hd refid=Startup.Starting &4OS2.:elink.).  You can override this
behavior with the :link reftype=hd refid=INI_NextINIFile.NextINIFile:elink.
directive.
:p.
Secondary shells automatically inherit the configuration settings currently
in effect in the previous shell.  If values have been changed by :link
reftype=hd refid=SETDOS.SETDOS:elink. since the primary shell started, the
current values will be passed to the secondary shell.  If the previous
shell's :hp1..INI:ehp1. file had a :hp2.[Secondary]:ehp2. section, it will
then be read and processed (see :link reftype=hd refid=INISections..INI
File Sections:elink..  If not, the previous shell's settings will remain in
effect.
:p.
For example, you might set :link reftype=hd
refid=INI_BatchEcho.BatchEcho:elink. to Yes in the :hp1..INI:ehp1. 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 :hp1..INI:ehp1. file;
:hp1.i.e.:ehp1., batch files in the secondary shell will default to no echo.
:p.
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 :hp2.[Secondary]:ehp2. section
of the :hp1..INI:ehp1. file.
:p.
The :link reftype=hd refid=SETDOS.SETDOS:elink. command can override
several of the :hp1..INI:ehp1. file directives.  For example, the cursor
shape used by &4OS2. can be adjusted either with the :link reftype=hd
refid=INI_CursorIns.CursorIns:elink. and :link reftype=hd
refid=INI_CursorOver.CursorOver:elink. directives or the SETDOS /S
command.  The correspondence between SETDOS options and .:hp1.INI:ehp1.
directives is noted with each directive, and under each option of the
SETDOS command.
:p.
When the command processor detects an error while processing the
:hp1..INI:ehp1. 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
:hp1..INI:ehp1. file.  If you don't want a pause after each error, use a
":link reftype=hd refid=INI_PauseOnError.PauseOnError:elink. = No"
directive at the beginning of the :hp1..INI:ehp1. file.
:p.
If you need to test different values for an :hp1..INI:ehp1. directive
without repeatedly editing the :hp1..INI:ehp1. file, use the :link
reftype=hd refid=OPTION.OPTION:elink. command or see the :link reftype=hd
refid=INI_INIQuery.INIQuery:elink. directive.

.* --------------------------------------------------------------------------

:h2 name=INISections..INI File Sections
:p.
The :hp1..INI:ehp1. file has three possible sections&colon.  the first or
:hp2.global:ehp2. section, named :hp2.[&4OS2.]:ehp2.; the
:hp2.[Primary]:ehp2. section; and the :hp2.[Secondary]:ehp2. section.  Each
section is identified by the section name in square brackets on a line by
itself.
:p.
Directives in the global section are effective in all shells.  In most cases,
this is the only section you will need.  Any changes you make to the
:hp1..INI:ehp1. file with the :link reftype=hd refid=OPTION.OPTION:elink.
command are stored in the global section.
:p.
The :hp2.[Primary]:ehp2. and :hp2.[Secondary]:ehp2. sections include
directives that are used only in primary and secondary shells,
respectively.  You don't need to set up these sections unless you want
different directives for primary and secondary shells.
:p.
Directives in the :hp2.[Primary]:ehp2. 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
:hp2.[Secondary]:ehp2. section.
:p.
Directives in the :hp2.[Secondary]:ehp2. section are used in secondary
shells only, and override any corresponding primary shell settings.  For
example, these lines in the :hp1..INI:ehp1. file&colon.
:xmp.
        [Primary]
        ScreenRows = 25
:p.
        [Secondary]
        ScreenRows = 50
:exmp.:p.
mean to assume that you have 25 rows on the screen in the primary shell and
50 lines in all secondary shells.
:p.
Sections that begin with any name other than :hp2.[&4OS2.]:ehp2.,
:hp2.[Primary]:ehp2., or :hp2.[Secondary]:ehp2. are ignored.

.* --------------------------------------------------------------------------

:h2 name=INIDirectives..INI File Directives
:p.
For information on specific directives see the separate topic for each type
of directive&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=INIInit.Initialization Directives:elink.
:pt.:pd.:link reftype=hd refid=INIConfig.Configuration Directives:elink.
:pt.:pd.:link reftype=hd refid=INIColor.Color Directives:elink.
:pt.:pd.:link reftype=hd refid=INIKeyMap.Key Mapping Directives:elink.
:pt.:pd.:link reftype=hd refid=INIAdv.Advanced Directives:elink.
:eparml.:lm margin=1.
.br
These topics list the directives, with a one-line description of each, and
a cross-reference which selects a full screen help topic on that directive.
A few of the directives are simple enough that the one-line description is
sufficient, but in most cases you should check for any additional
information in the cross-reference topic if you are not already familiar
with the directive.
:p.
You can also obtain help on most directives with a :hp2.HELP directive:ehp2.
command at the prompt.
:p.
There are 8 types of directives in the :hp1..INI:ehp1. file.  The different
types of directives are shown in the descriptions as follows&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.*:pd.:hp2.Name = nnnn (1234):ehp2.&colon.  This directive takes a
numeric value which replaces the "nnnn."  The default value is shown in
parentheses.
:pt.*:pd.:hp2.Name = c (X):ehp2.&colon.  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.
:pt.*:pd.:hp2.Name = CHOICE1 | Choice2 | ...:ehp2. &colon.  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.
:pt.*:pd.:hp2.Name = Color:ehp2.&colon.  This directive takes a color
specification.  See :link reftype=hd refid=Colors.Colors and Color
Names:elink..
:pt.*:pd.:hp2.Name = Key (Default):ehp2.&colon.  This directive takes a key
specification.  See :link reftype=hd refid=KeyNames.Key Names:elink..
:pt.*:pd.:hp2.Name = Path:ehp2.&colon.  This directive takes a path
specification, but not a filename.  The value should include both a drive
and path (:hp1.e.g.:ehp1., :hp1.C&colon.\&4OS2.:ehp1.) to avoid any possible
ambiguities.  A trailing backslash [:hp2.\:ehp2.] at the end of the path
name is acceptable but not required.  Any default path is described in the
text.
:pt.*:pd.:hp2.Name = File:ehp2.&colon.  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.
:pt.*:pd.:hp2.Name = String:ehp2.&colon.  This directive takes a string in
the format shown.  The text describes the default value and any additional
requirements for formatting the string correctly.  :hp2.No comments are
allowed:ehp2..
:eparml.:lm margin=1.
.br
&4OS2. contains a fixed-length area for storing strings entered in the
:hp1..INI:ehp1. 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
:hp1..INI:ehp1. file or contact our technical support department for
assistance.

.* --------------------------------------------------------------------------

:h3 name=INIInit.Initialization Directives
:p.
The directives in this section control how &4OS2. starts and where it
looks for its files.  The initialization directives are&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:link reftype=hd refid=INI_4StartPath.4StartPath:elink.:pd.Path for 4START and 4EXIT
:pt.:link reftype=hd refid=INI_DirHistory.DirHistory:elink.:pd.Size of directory history list
:pt.:link reftype=hd refid=INI_DuplicateBugs.DuplicateBugs:elink.:pd.Duplicate bugs in CMD.EXE
:pt.:link reftype=hd refid=INI_HelpBook.HelpBook:elink.:pd.Books to load in help system
:pt.:link reftype=hd refid=INI_History.History:elink.:pd.Size of history list
:pt.:link reftype=hd refid=INI_INIQuery.INIQuery:elink.:pd.Query for each line in &4OS2INI.
:pt.:link reftype=hd refid=INI_LocalAliases.LocalAliases:elink.:pd.Local vs. global aliases
:pt.:link reftype=hd refid=INI_LocalDirHistory.LocalHistory:elink.:pd.Local vs. global directory history
:pt.:link reftype=hd refid=INI_LocalHistory.LocalHistory:elink.:pd.Local vs. global history
:pt.:link reftype=hd refid=INI_PauseOnError.PauseOnError:elink.:pd.Pause on errors in &4OS2INI.
:pt.:link reftype=hd refid=INI_SwapFilePath.SwapFilePath:elink.:pd.Path to OS/2 swap file
:pt.:link reftype=hd refid=INI_TreePath.TreePath:elink.:pd.Path for directory database
:pt.:link reftype=hd refid=INI_WindowState.WindowState:elink.:pd.Initial state for the &4OS2. window
:pt.:link reftype=hd refid=INI_WindowX.WindowX, WindowY, WindowWidth, WindowHeight:elink.:pd.Initial size and position of the &4OS2. window
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h4 name=INI_4StartPath.4StartPath
:p.
:hp2.4StartPath:ehp2. = Path&colon.  Sets the drive and directory where the
:hp1.4START:ehp1. and :hp1.4EXIT:ehp1. batch files (if any) are located.

.* --------------------------------------------------------------------------

:h4 name=INI_DirHistory.˙DirHistory (directive)
:p.
:hp2.DirHistory:ehp2. = nnnn (256)&colon.  Sets the amount of memory
allocated to the directory history in bytes.  The allowable range of values
is 256 to 32767 bytes.  If you use a :link reftype=hd
refid=GlobalDirHistory.global directory history list:elink. the DirHistory
value will be ignored in all shells except the shell which first establishes
the global list.

.* --------------------------------------------------------------------------

:h4 name=INI_DuplicateBugs.DuplicateBugs
:p.
:hp2.DuplicateBugs:ehp2. = YES | No&colon.  Tells the &4OS2. parser to
duplicate certain well-known bugs in :hp1.CMD.EXE:ehp1..  The only bug
currently replicated is in the :link reftype=hd refid=IF.IF:elink. command.

.* --------------------------------------------------------------------------

:h4 name=INI_HelpBook.HelpBook
:p.
:hp2.HelpBook:ehp2. = String&colon.  Sets the names of the "books" to be loaded
when &4OS2. help is invoked with the :link reftype=hd refid=HELP.HELP:elink. command or the
:hp2.F1:ehp2. key.  The default is :hp2.&4OS2.+CMDREF:ehp2. which loads the &4OS2.
help and the OS/2 command reference.

.* --------------------------------------------------------------------------

:h4 name=INI_History.History (directive)
:p.
:hp2.History:ehp2. = nnnn (1024)&colon.  Sets the amount of memory allocated to
the command history list in bytes.  The allowable range of values
is 256 to 32767 bytes.  If you use a global history list (see
:link reftype=hd refid=CmdHist.Command History and Recall:elink.), the History value is
ignored in all shells except the shell which first establishes the
global list.

.* --------------------------------------------------------------------------

:h4 name=INI_INIQuery.INIQuery
:p.
:hp2.INIQuery:ehp2. = Yes &splitvbar. NO&colon.  If set to :hp2.Yes:ehp2., a prompt will be
displayed before execution of each subsequent line in the current
:hp1..INI:ehp1. file.  This allows you to modify certain directives when
you start &4OS2. in order to test different configurations.  INIQuery
can be reset to :hp2.No:ehp2. at any point in the file.  Normally INIQuery
= Yes is only used during testing of other :hp1..INI:ehp1. file
directives.
:p.
The prompt generated by INIQuery = Yes is&colon.
:xmp.
        [contents of the line]  (Y/N/Q/R/E)  ?
:exmp.:p.
At this prompt, you may enter&colon.
:lm margin=8.:parml compact tsize=12 break=fit.
:pt.Y = Yes&colon.:pd.Process this line and go on to the next.
:pt.N = No&colon.:pd.Skip this line and go on to the next.
:pt.Q = Quit&colon.:pd.Skip this line and all subsequent lines.
:pt.R = Rest&colon.:pd.Execute this and all subsequent lines.
:pt.E = Edit&colon.:pd.Edit the value for this entry.
:eparml.:lm margin=1.
.br
If you choose E for Edit, you can enter a new value for the
directive, but not a new directive name.
:p.
For example, if you have found a compatibility problem you think
may be related to &4OS2.'s character (as opposed to line) input mode,
you might change your :hp1.&4OS2INI.:ehp1. file so a part of it read as
follows&colon.
:xmp.
        INIQuery = Yes
        LineInput = Yes
        INIQuery = No
:exmp.:p.
You could then choose to process, ignore, or edit the LineInput
directive each time &4OS2. started.  This would allow you to check whether
changing the line input mode would resolve the compatibility problem.

.* --------------------------------------------------------------------------

:h4 name=INI_LocalAliases.LocalAliases
:p.
:hp2.LocalAliases:ehp2. = Yes &splitvbar. NO&colon.  :hp2.No:ehp2. forces all copies
of &4OS2. to share the same alias list.  :hp2.Yes:ehp2. keeps the lists for each
shell separate.  See :link reftype=hd refid=ALIAS.ALIAS:elink. for more details on local and
global alias lists.

.* --------------------------------------------------------------------------

:h4 name=INI_LocalDirHistory.LocalDirHistory
:p.
:hp2.LocalDirHistory:ehp2. = Yes &splitvbar. NO&colon.  :hp2.No:ehp2. forces
all copies of command processor to share the same directory history.  :hp2.Yes:ehp2.
keeps the directory histories for each shell separate.  See
:link reftype=hd refid=GlobalDirHistory.Local and Global Directory History:elink. for
more details.

.* --------------------------------------------------------------------------

:h4 name=INI_LocalHistory.LocalHistory
:p.
:hp2.LocalHistory:ehp2. = Yes &splitvbar. NO&colon.  :hp2.No:ehp2. forces all copies of &4OS2.
to share the same history list.  :hp2.Yes:ehp2. keeps the lists for each
shell separate.  See :link reftype=hd refid=CmdHist.Command History and Recall:elink. for
more details on local and global history lists.

.* --------------------------------------------------------------------------

:h4 name=INI_PauseOnError.PauseOnError
:p.
:hp2.PauseOnError:ehp2. = YES &splitvbar. No&colon.  :hp2.Yes:ehp2. forces a
pause with the message "Error in :hp1.filename:ehp1., press any key to
continue processing" after displaying any error message related to a
specific line in the :hp1..INI:ehp1. file.  :hp2.No:ehp2. continues processing
with no pause after an error message is displayed.

.* --------------------------------------------------------------------------

:h4 name=INI_SwapFilePath.SwapFilePath
:p.
:hp2.SwapFilePath:ehp2. = Path | File&colon.  Specifies the path to the OS/2
swap file so that the :link reftype=hd refid=MEMORY.MEMORY:elink. command
can find it.  You can either specify a full path and filename for the swap
file or just the path.  If you specify a path only, &4OS2. assumes that the
file is called :hp1.SWAPPER.DAT:ehp1..  If SwapFilePath is not used, &4OS2.
assumes that the file is named :hp1.SWAPPER.DAT:ehp1. and stored in the
:hp1.\OS2\SYSTEM:ehp1. directory of the boot drive.

.* --------------------------------------------------------------------------

:h4 name=INI_TreePath.TreePath
:p.
:hp2.TreePath:ehp2. = Path&colon.  Sets the location of
:hp1.JPSTREE.IDX:ehp1., the file used for :link reftype=hd
refid=ExtDirSearch.extended directory searches:elink. By default, the file is
placed in the root directory of drive C&colon.\.

.* --------------------------------------------------------------------------

:h4 name=INI_WindowState.WindowState
:p.
:hp2.WindowState:ehp2. = STANDARD &splitvbar. Maximize &splitvbar. Minimize&colon.  Sets the initial
state of the &4OS2. window.  :hp2.Standard:ehp2. puts the window in the
default position on the OS/2 desktop, and is the default setting.
:hp2.Maximize:ehp2. maximizes the window; :hp2.Minimize:ehp2. minimizes it.  If
you use Maximize or Minimize, you may see the &4OS2. window appear
briefly in the Standard position as it is created by OS/2, then
switch to the new state.

.* --------------------------------------------------------------------------

:h4 name=INI_WindowX.WindowX, WindowY, WindowWidth, WindowHeight
:p.
:hp2.WindowX:ehp2. = nnnn, :hp2.WindowY:ehp2. = nnnn, :hp2.WindowWidth:ehp2.
= nnnn, :hp2.WindowHeight:ehp2. = nnnn&colon.  These 4 directives set the
initial size and position of the &4OS2. window.  The measurements are in
pixels or pels.  :hp2.WindowX:ehp2. and :hp2.WindowY:ehp2. refer to the
position of the bottom left corner of the window relative to the bottom left
corner of the screen.

.* --------------------------------------------------------------------------

:h3 name=INIConfig.Configuration Directives
:p.
These directives control the way that &4OS2. operate.  Some can be
changed with the :link reftype=hd refid=SETDOS.SETDOS:elink. command while &4OS2. is running.
Any corresponding SETDOS command is listed in the description of
each directive.  The configuration directives are&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:link reftype=hd refid=INI_AmPm.AmPm:elink.:pd.Time display format
:pt.:link reftype=hd refid=INI_AppendToDir.AppendToDir:elink.:pd."\" on directory names in filename completion
:pt.:link reftype=hd refid=INI_BatchEcho.BatchEcho:elink.:pd.Default batch file echo state
:pt.:link reftype=hd refid=INI_BeepFreq.BeepFreq:elink.:pd.Default beep frequency
:pt.:link reftype=hd refid=INI_BeepLength.BeepLength:elink.:pd.Default beep length
:pt.:link reftype=hd refid=INI_CDDWinLeft.CDDWinLeft, CDDWinTop, CDDWinWidth, CDDWinHeight:elink.:pd.Initial position and size of the directory change window
:pt.:link reftype=hd refid=INI_CommandSep.CommandSep:elink.:pd.Multiple command separator character
:pt.:link reftype=hd refid=INI_CursorIns.CursorIns:elink.:pd.Cursor shape in insert mode
:pt.:link reftype=hd refid=INI_CursorOver.CursorOver:elink.:pd.Cursor shape in overstrike mode
:pt.:link reftype=hd refid=INI_DecimalChar.DecimalChar:elink.:pd.DecimalChar
:pt.:link reftype=hd refid=INI_DescriptionMax.DescriptionMax:elink.:pd.Maximum length of file descriptions
:pt.:link reftype=hd refid=INI_DescriptionName.DescriptionName:elink.:pd.Name of file to hold file descriptions
:pt.:link reftype=hd refid=INI_Descriptions.Descriptions:elink.:pd.Enable / disable description processing
:pt.:link reftype=hd refid=INI_EditMode.EditMode:elink.:pd.Editing mode (insert / overstrike)
:pt.:link reftype=hd refid=INI_EscapeChar.EscapeChar:elink.:pd.&4OS2. escape character
:pt.:link reftype=hd refid=INI_EvalMax.EvalMax:elink.:pd.Max digits after decimal point in @EVAL
:pt.:link reftype=hd refid=INI_EvalMin.EvalMin:elink.:pd.Min digits after decimal point in @EVAL
:pt.:link reftype=hd refid=INI_ExecWait.ExecWait:elink.:pd.Wait for external programs at command line
:pt.:link reftype=hd refid=INI_FileCompletion.FileCompletion:elink.:pd.Filename completion by extension
:pt.:link reftype=hd refid=INI_FuzzyCD.FuzzyCD:elink.:pd.Selects Extended Directory Search mode
:pt.:link reftype=hd refid=INI_HistCopy.HistCopy:elink.:pd.History copy mode
:pt.:link reftype=hd refid=INI_HistLogName.HistLogName:elink.:pd.History log file name
:pt.:link reftype=hd refid=INI_HistMin.HistMin:elink.:pd.Minimum command length to save
:pt.:link reftype=hd refid=INI_HistMove.HistMove:elink.:pd.History move mode
:pt.:link reftype=hd refid=INI_HistWrap.HistWrap:elink.:pd.History wrap mode
:pt.:link reftype=hd refid=INI_LineInput.LineInput:elink.:pd.Enable / disable line input mode
:pt.:link reftype=hd refid=INI_ListRowStart.ListRowStart:elink.:pd.Starting row number for LIST and FFIND
:pt.:link reftype=hd refid=INI_LogName.LogName:elink.:pd.Log file name
:pt.:link reftype=hd refid=INI_NoClobber.NoClobber:elink.:pd.Overwrite protection for output redirection
:pt.:link reftype=hd refid=INI_ParameterChar.ParameterChar:elink.:pd.Alias / batch file parameter character
:pt.:link reftype=hd refid=INI_PathExt.PathExt:elink.:pd.Enable or disable the PATHEXT variable
:pt.:link reftype=hd refid=INI_PopupWinLeft.PopupWinLeft, PopupWinTop, PopupWinWidth, PopupWinHeight:elink.:pd.Initial position and size of popup windows
:pt.:link reftype=hd refid=INI_Printer.Printer:elink.:pd.LIST print device
:pt.:link reftype=hd refid=INI_ScreenRows.ScreenRows:elink.:pd.Screen height
:pt.:link reftype=hd refid=INI_TabStops.TabStops:elink.:pd.Tab width in LIST
:pt.:link reftype=hd refid=INI_ThousandsChar.ThousandsChar:elink.:pd.Thousands separator
:pt.:link reftype=hd refid=INI_UnixPaths.UnixPaths:elink.:pd.Enable or disable slash in command paths
:pt.:link reftype=hd refid=INI_UpperCase.UpperCase:elink.:pd.Force file names to upper case
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h4 name=INI_AmPm.AmPm
:p.
:hp2.AmPm:ehp2. = Yes &splitvbar. NO &splitvbar. Auto&colon.  :hp2.Yes:ehp2. displays times in 12-hour
format with a trailing "a" for AM or "p" for PM.  The default of
:hp2.No:ehp2. forces a display in 24-hour time format.  :hp2.Auto:ehp2. formats
the time according to the country code set for your system.  AmPm
controls the time displays used by :link reftype=hd refid=DIR.DIR:elink. and
:link reftype=hd refid=SELECT.SELECT:elink., in :link reftype=hd refid=LOG.LOG:elink. files, and the output of the
:link reftype=hd refid=TIMER.TIMER:elink., :link reftype=hd refid=DATE.DATE:elink., and :link reftype=hd refid=TIME .TIME :elink.commands.  It
has no effect on :link reftype=hd refid=_TIME.%_TIME:elink., :link reftype=hd refid=_@MAKETIME.%@MAKETIME:elink., the
$t and $T options of :link reftype=hd refid=PROMPT.PROMPT:elink., or date and time
:link reftype=hd refid=ranges.ranges:elink..

.* --------------------------------------------------------------------------

:h4 name=INI_AppendToDir.AppendToDir
:p.
:hp2.AppendToDir:ehp2. = Yes &splitvbar. NO&colon.  :hp2.Yes:ehp2. appends a
trailing "\" to directory names when doing filename completion.  The default
is :hp2.No:ehp2..  (Regardless of the setting of this directive, a trailing
backslash is always appended to a directory name at the beginning of the
command line to enable automatic directory changes.)

.* --------------------------------------------------------------------------

:h4 name=INI_BatchEcho.BatchEcho
:p.
:hp2.BatchEcho:ehp2. = YES &splitvbar. No&colon.  Sets the default batch echo mode.
:hp2.Yes:ehp2. enables echoing of all batch file commands unless
:link reftype=hd refid=ECHO.ECHO:elink. is explicitly set off in the batch file.  :hp2.No:ehp2.
disables batch file echoing unless ECHO is explicitly set on.  Also
see :link reftype=hd refid=SETDOS.SETDOS:elink. /V.

.* --------------------------------------------------------------------------

:h4 name=INI_BeepFreq.BeepFreq
:p.
:hp2.BeepFreq:ehp2. = nnnn (440)&colon.  Sets the default :link reftype=hd refid=BEEP.BEEP:elink.
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.

.* --------------------------------------------------------------------------

:h4 name=INI_BeepLength.BeepLength
:p.
:hp2.BeepLength:ehp2. = nnnn (2)&colon.  Sets the default :link reftype=hd refid=BEEP.BEEP:elink. 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).

.* --------------------------------------------------------------------------

:h4 name=INI_CDDWinLeft.CDDWinLeft, CDDWinTop, CDDWinWidth, CDDWinHeight
:p.
:hp2.CDDWinLeft:ehp2. = nnnn, :hp2.CDDWinTop:ehp2. = nnnn,
:hp2.CDDWinWidth:ehp2. = nnnn, :hp2.CDDWinHeight:ehp2. = nnnn&colon.  These
values set the position and size of the popup window used by :link
reftype=hd refid=ExtDirSearch.extended directory searches:elink., in
characters, including the border.  The defaults are 3, 3, 72, and 16,
respectively (:hp1.i.e.:ehp1., a window beginning in column 3, row 3, 72
columns wide and 16 rows high).  The position is relative to the top left
corner of the screen.  The width and height values include the space
required for the window border.
:p.
The window cannot be smaller than than 10 columns wide by 5 rows high
(including the border).  The values you enter will be adjusted if necessary
to keep a minimum-size window visible on the screen.
:p.
The window is normally displayed with a shadow, but if you specify a window
starting at column 0 and extending to the right margin, the shadow is
eliminated; this may be useful to prevent speech software from reading text
in the shadow area while viewing the window.

.* --------------------------------------------------------------------------

:h4 name=INI_CommandSep.CommandSep
:p.
:hp2.CommandSep:ehp2. = c&colon.  This is the character used to separate
multiple commands on the same line.  The default is the ampersand [:hp2.&amp.:ehp2.].
You cannot use any of the redirection characters (:hp2.&splitvbar.:ehp2. :hp2.>:ehp2. :hp2.<:ehp2.
) or any of the whitespace characters (space, tab, comma, or equal
sign).  The command separator is saved by :link reftype=hd
refid=SETLOCAL.SETLOCAL:elink. and restored by :link reftype=hd
refid=ENDLOCAL.ENDLOCAL:elink..
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /C, the :link
reftype=hd refid=PLUS.%+:elink. internal variable, and :link reftype=hd
refid=Compat.Special Character Compatibility:elink. for
information on using compatible command separators for two or more products.

.* --------------------------------------------------------------------------

:h4 name=INI_CursorIns.CursorIns
:p.
:hp2.CursorIns:ehp2. = nnnn (100)&colon.  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 drivers map the cursor shape, you may not
get a smooth progression in cursor shapes as :hp2.CursorIns:ehp2. and
:hp2.CursorOver:ehp2. change.  If :hp2.CursorIns:ehp2. or :hp2.CursorOver:ehp2. is set to
-1, &4OS2. will not attempt to modify the cursor shape at all; you can use this
feature to give another program full control of the cursor shape.
:p.
Also see :link reftype=hd refid=INI_CursorOver.CursorOver:elink.
and :link reftype=hd refid=SETDOS.SETDOS:elink. /S.

.* --------------------------------------------------------------------------

:h4 name=INI_CursorOver.CursorOver
:p.
:hp2.CursorOver:ehp2. = nnnn (15)&colon.  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%.  For details see :link reftype=hd refid=INI_CursorIns.CursorIns:elink.;
also see :link reftype=hd refid=SETDOS.SETDOS:elink. /S.

.* --------------------------------------------------------------------------

:h4 name=INI_DecimalChar.DecimalChar
:p.
:hp2. DecimalChar:ehp2. = . &splitvbar. , &splitvbar. AUTO&colon.  Sets the
character used as the decimal separator for :link reftype=hd
refid=_@EVAL.@EVAL:elink., numeric :link reftype=hd refid=IF.IF:elink. and
:link reftype=hd refid=IFF.IFF:elink. tests, version numbers, and other
similar uses.  The only valid settings are period [:hp2..:ehp2.], comma
[:hp2.,:ehp2.], and :hp2.Auto:ehp2. (the default).  A setting of Auto tells
the command processor to use the decimal separator associated with your
current country code.  If you change the decimal character you must also
adjust the thousands character (with :link reftype=hd
refid=INI_ThousandsChar.ThousandsChar:elink.) so that the two characters are
different.
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /G.

.* --------------------------------------------------------------------------

:h4 name=INI_DescriptionMax.DescriptionMax
:p.
:hp2.DescriptionMax:ehp2. = nnnn (40)&colon.  Controls the description length
limit for :link reftype=hd refid=DESCRIBE.DESCRIBE:elink..  The allowable range is 20 to 511
characters.

.* --------------------------------------------------------------------------

:h4 name=INI_DescriptionName.DescriptionName
:p.
:hp2.DescriptionName:ehp2. = [File &splitvbar. EA]&colon.  Sets the file
name in which to store file descriptions.  The default file name is
:hp1.DESCRIPT.ION:ehp1..  :hp8.Use this directive with caution:ehp8. because
changing the name from the default will make it difficult to transfer file
descriptions to another system.
:p.
If you set :hp2.DescriptionName = EA:ehp2., &4OS2. will use the ".SUBJECT"
extended attribute (EA) for file descriptions instead of a separate
file.  Note that using EAs will slow the :link reftype=hd
refid=DIR.DIR:elink. and :link reftype=hd refid=SELECT.SELECT:elink.
commands noticeably.  On a FAT volume, performance may be substantially
slower, depending on whether the system has cached the extended attributes.
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /D.

.* --------------------------------------------------------------------------

:h4 name=INI_Descriptions.Descriptions
:p.
:hp2.Descriptions:ehp2. = YES &splitvbar. No&colon.  Turns description
handling on or off during the file processing commands :link reftype=hd
refid=COPY.COPY:elink., :link reftype=hd refid=DEL.DEL:elink., :link
reftype=hd refid=MOVE.MOVE:elink., and :link reftype=hd
refid=REN.REN:elink..  If set to :hp2.No:ehp2., &4OS2. will not update the
description file when files are moved, copied, deleted or renamed.
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /D.

.* --------------------------------------------------------------------------

:h4 name=INI_EditMode.EditMode
:p.
:hp2.EditMode:ehp2. = Insert &splitvbar. OVERSTRIKE&colon.  This directive
lets you start the command-line editor in either insert or overstrike
mode.  Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /M.

.* --------------------------------------------------------------------------

:h4 name=INI_EscapeChar.EscapeChar
:p.
:hp2.EscapeChar:ehp2. = c &colon.  Sets the character used to suppress the
normal meaning of the following character.  The default is a caret [:hp2.^:ehp2.].
See :link reftype=hd refid=Escape.Escape Character:elink. for a description of special
escape sequences.  You cannot use any of the
:link reftype=hd refid=RedirPipe.redirection:elink. characters
(:hp2.&splitvbar.:ehp2., :hp2.>:ehp2., or :hp2.<:ehp2. ) or
the whitespace characters (space, tab, comma, or equal sign) as the
escape character.  The escape character is saved by :link reftype=hd
refid=SETLOCAL.SETLOCAL:elink. and restored by :link reftype=hd
refid=ENDLOCAL.ENDLOCAL:elink..
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /E, the
:link reftype=hd refid=EQUALS.%=:elink. internal variable, and :link
reftype=hd refid=Compat.Special Character Compatibility:elink. for
information on using compatible escape characters for two or more products.

.* --------------------------------------------------------------------------

:h4 name=INI_EvalMax.EvalMax
:p.
:hp2.EvalMax:ehp2. = nnnn (8)&colon.  Controls the maximum number of digits
after the decimal point in values returned by :link reftype=hd
refid=_@EVAL.@EVAL:elink.. This setting can be overridden with the construct
:hp2.@EVAL[expression=n.n]:ehp2..  The allowable range is 0 to 8.  Also see
:link reftype=hd refid=INI_EvalMin.EvalMin:elink. and :link reftype=hd
refid=SETDOS.SETDOS:elink. /F.

.* --------------------------------------------------------------------------

:h4 name=INI_EvalMin.EvalMin
:p.
:hp2.EvalMin:ehp2. = nnnn (8)&colon.  Controls the minimum number of digits after the
decimal point in values returned by :link reftype=hd refid=_@EVAL.@EVAL:elink..  This
setting can be overridden with the construct :hp2.@EVAL[expression=n.n]:ehp2..  The
allowable range is 0 to 8.  The :hp2.EvalMin:ehp2. value will be ignored if it is
larger than :link reftype=hd refid=INI_EvalMax.EvalMax:elink..  Also
see :link reftype=hd refid=SETDOS.SETDOS:elink. /F.

.* --------------------------------------------------------------------------

:h4 name=INI_ExecWait.ExecWait
:p.
:hp2.ExecWait:ehp2. = Yes &splitvbar. NO&colon.  Controls whether &4OS2.
waits for an external program to complete before redisplaying the prompt.  See
:link reftype=hd refid=WaitForApps.Waiting for Applications to Finish:elink.
for details on the effects of this directive.

.* --------------------------------------------------------------------------

:h4 name=INI_FileCompletion.FileCompletion
:p.
:hp2.FileCompletion:ehp2. = cmd1&colon. ext1 ext2 ...; cmd2&colon. ext3
ext4 ...  Sets the files made available during filename completion for selected
commands.  The format is the same as that used for the :link reftype=hd
refid=FILECOMPLETION.FILECOMPLETION:elink. environment variable.  See :link
reftype=hd refid=FileComp.Filename Completion:elink. for a detailed
explanation of selective filename completion.

.* --------------------------------------------------------------------------

:h4 name=INI_FuzzyCD.FuzzyCD
:p.
:hp2.FuzzyCD:ehp2. = 0 | 1 | 2 | 3;  Enables or disables extended directory
searches, and controls their behavior.  A setting of 0 (the default)
disables extended searches.  For complete details on the meaning of the
other settings see :link reftype=hd refid=ExtDirSearch.Extended Directory
Searches:elink..

.* --------------------------------------------------------------------------

:h4 name=INI_HistCopy.HistCopy
:p.
:hp2.HistCopy:ehp2. = Yes &splitvbar. NO&colon.  Controls what happens when you re-execute
a line from the command history.  If this option is set to :hp2.Yes:ehp2.,
the line is appended to the end of the history list.  By default, or if
this option is set to :hp2.No:ehp2., the command is not copied.  The
original copy of the command is retained at its original position in the
list, regardless of the setting of HistCopy.
:p.
Set this option to No if you want to use :link reftype=hd
refid=INI_HistMove.HistMove:elink. = Yes; otherwise, the HistCopy setting
will override HistMove.

.* --------------------------------------------------------------------------

:h4 name=INI_HistLogName.HistLogName
:p.
:hp2.HistLogName:ehp2. = File&colon.  Sets the history log file name and
path.  Using HistLogName does not turn history logging on; you must use
a :link reftype=hd refid=LOG.LOG:elink. /H ON command to do so.

.* --------------------------------------------------------------------------

:h4 name=INI_HistMin.HistMin
:p.
:hp2.HistMin:ehp2. = nnnn (0)&colon.  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.  Legal values range from 0,
which saves everything, to 1024, which disables all command history saves.

.* --------------------------------------------------------------------------

:h4 name=INI_HistMove.HistMove
:p.
:hp2.HistMove:ehp2. = Yes &splitvbar. NO&colon.  If set to Yes, a recalled
line is moved to the end of the command history.  The difference between
this directive and :link reftype=hd refid=INI_HistCopy.HistCopy:elink., is
that HistCopy = Yes copies each recalled line to the end of the history but
leaves the original in place.  HistMove = Yes places the line at the end of
history and removes the original line.
:p.
This directive has no effect if HistCopy = Yes.

.* --------------------------------------------------------------------------

:h4 name=INI_HistWrap.HistWrap
:p.
:hp2.HistWrap = :ehp2.YES &splitvbar. No&colon.  Controls whether the
command history recall "wraps" when you reach the top or bottom of the list.  The default
setting enables wrapping, so the list appears "circular".  If HistWrap is set
to No, history recall will stop at the beginning and end of the list rather
than wrapping.  This setting affects history recall at the prompt only; the
command history window never wraps.

.* --------------------------------------------------------------------------

:h4 name=INI_LineInput.LineInput
:p.
:hp2.LineInput:ehp2. = Yes &splitvbar. NO&colon.  This directive controls
how &4OS2. gets its input from the command line.  :hp2.Yes:ehp2. forces &4OS2.
to perform line-by-line input, just as :hp1.CMD.EXE:ehp1. does, 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 299
characters.  It is normally used only for applications which do not work
properly unless &4OS2. uses line input.
:p.
If you have a particular program that requires line input, you can use :link
reftype=hd refid=SETDOS.SETDOS:elink. /L to temporarily change modes.

.* --------------------------------------------------------------------------

:h4 name=INI_ListRowStart.ListRowStart
:p.
:hp2.ListRowStart:ehp2.  = 1 &splitvbar.  0&colon.  Specifies whether
:link reftype=hd refid=LIST.LIST:elink. and :link reftype=hd
refid=FFIND.FFIND:elink. consider the first line in the file to be line
"1" or line "0".  The default is "1".

.* --------------------------------------------------------------------------


:h4 name=INI_LogName.LogName
:p.
:hp2.LogName:ehp2. = File&colon.  Sets the log file name and path.  Using
LogName does not turn logging on; you must use a
:link reftype=hd refid=LOG.LOG:elink. ON command to do so.

.* --------------------------------------------------------------------------

:h4 name=INI_NoClobber.NoClobber
:p.
:hp2.NoClobber:ehp2. = Yes &splitvbar. NO&colon.  If set to :hp2.Yes:ehp2.,
will prevent standard output :link reftype=hd
refid=Redirection.redirection:elink. from overwriting an existing file, and
will require that the output file already exist for append
redirection.  Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /N.

.* --------------------------------------------------------------------------

:h4 name=INI_ParameterChar.ParameterChar
:p.
:hp2.ParameterChar:ehp2. = c&colon.  Sets the character used after a percent
sign to specify all or all remaining command-line arguments in a
batch file or alias (:hp1.e.g.:ehp1., :hp2.%$:ehp2. or
:hp2.%n$:ehp2.; see :link reftype=hd refid=Batch.Batch Files:elink. and
:link reftype=hd refid=ALIAS.ALIAS:elink.).  The default is the dollar sign
[:hp2.$:ehp2.].  The parameter character is saved by :link reftype=hd
refid=SETLOCAL.SETLOCAL:elink. and restored by :link reftype=hd
refid=ENDLOCAL.ENDLOCAL:elink..
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /P.  See :link
reftype=hd refid=Compat.Special Character Compatibility:elink. for
information on using compatible parameter characters for two or more
products.

.* --------------------------------------------------------------------------

:h4 name=INI_PathExt.PathExt
:p.
:hp2.PathExt:ehp2. = Yes &splitvbar. NO&colon.  Determines whether
&4OS2. will use the PATHEXT environment variable.  If set to No (the
default), the PATHEXT variable is ignored.  If set to Yes, the PATHEXT
variable will be used to determine extensions to look for when searching
the PATH for an executable file.  For details, see the :link reftype=hd
refid=PATHEXT.PATHEXT:elink. variable and the :link reftype=hd
refid=PATH.PATH:elink. command.
:p.
:hp8.CAUTION&colon.  If you set PathExt = Yes in :hp1.&4OS2INI.:ehp1. and then fail
to set the PATHEXT variable, path searches will fail as there will be no
extensions for which to search!:ehp8.
:p.
PATHEXT is supported for compatibility reasons but should not generally
be used as a substitute for the more flexible :link reftype=hd
refid=ExeExt.executable extensions:elink. feature.

.* --------------------------------------------------------------------------

:h4 name=INI_PopupWinLeft.PopupWinLeft, PopupWinTop, PopupWinWidth, PopupWinHeight
:p.
:hp2.PopupWinLeft:ehp2. = nnnn, :hp2.PopupWinTop:ehp2. = nnnn,
:hp2.PopupWinWidth:ehp2. = nnnn, :hp2.PopupWinHeight:ehp2. = nnnn&colon.  These
values set the position and size of the command-line,
directory history, and filename completion windows, and most other popup
windows (see :link reftype=hd refid=INI_CDDWinLeft.CDDWinLeft:elink. etc.
for the extended directory search window).  The values are in characters,
and include the border.  The defaults are 40, 1, 36, and 12, respectively
(i.e., a window beginning in column 40, row 1, 36 columns wide and 12 rows
high).  The position is relative to the top left corner of the screen.  The
width and height values include the space required for the window border.
:p.
The window cannot be smaller than than 10 columns wide by 5 rows high
(including the border).  The values you enter will be adjusted if necessary
to keep a minimum-size window visible on the screen.
:p.
The window is normally displayed with a shadow, but if you specify a window
starting at column 0 and extending to the right margin, the shadow is
eliminated; this may be useful to prevent speech software from reading text
in the shadow area while viewing the window.

.* --------------------------------------------------------------------------

:h4 name=INI_Printer.Printer
:p.
:hp2.Printer:ehp2. = devicename&colon.  Sets the output device that the
:link reftype=hd refid=LIST.LIST:elink. 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.

.* --------------------------------------------------------------------------

:h4 name=INI_ScreenRows.ScreenRows
:p.
:hp2.ScreenRows:ehp2. = nnnn&colon.  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 OS/2 and your video driver.
:p.
ScreenRows is used only by the :link reftype=hd refid=LIST.LIST:elink. and
:link reftype=hd refid=SELECT.SELECT:elink. commands, the paged output
options of other commands (:hp1.e.g.:ehp1., TYPE /P), and error checking
in the screen output commands.
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /R.

.* --------------------------------------------------------------------------

:h4 name=INI_TabStops.TabStops
:p.
:hp2.TabStops:ehp2. = nnnn (8)&colon.  Sets the tab stops for files
displayed with the :link reftype=hd refid=LIST.LIST:elink. command.  Setting
TabStops=3, for example, will place a tab stop in every third column.  The
allowable range is 1 to 32.
.* --------------------------------------------------------------------------

:h4 name=INI_ThousandsChar.ThousandsChar
:p.
:hp2.ThousandsChar:ehp2. = . &splitvbar. , &splitvbar. AUTO&colon.  Sets the
character used as the thousands separator for numeric output.  The only
valid settings are period [:hp2..:ehp2.], comma [:hp2.,:ehp2.], and
:hp2.Auto:ehp2. (the default).  A setting of Auto tells the command
processor to use the thousands separator associated with your current country
code.  If you change the thousands character you must also adjust the decimal
character (with :link reftype=hd refid=INI_DecimalChar.DecimalChar:elink.)
so that the two characters are different.
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /G.

.* --------------------------------------------------------------------------

:h4 name=INI_UnixPaths.UnixPaths
:p.
:hp2.UnixPaths:ehp2. = Yes &splitvbar. NO&colon.  Enables the forward
slash as a path separator in the command name (the first item on the
command line).  This allows you to enter a command like&colon.
:xmp.
     [c&colon.\] /bin/programs/foo.exe
:exmp.:p.
without having the forward slashes interpreted as switch characters.
Note that setting UnixPaths to Yes does :hp2.not:ehp2. change the command
processor or operating system switch character, it's still ':hp2./:ehp2.'.  It
simply allows you to put forward slashes in the command name without
problems.
:p.
When UnixPaths is set to Yes command switches beginning with a forward
slash must be preceded by a space to avoid confusion (this is a good
general practice regardless of the setting of UnixPaths).  For example&colon.
:xmp.
     [c&colon.\] \bin\foo.exe /c        OK
     [c&colon.\] /bin/foo.exe /c        OK
     [c&colon.\] \bin\foo.exe/c         Error
     [c&colon.\] /bin/foo.exe/c         Error
:exmp.:p.

.* --------------------------------------------------------------------------

:h4 name=INI_UpperCase.UpperCase
:p.
:hp2.UpperCase:ehp2. = Yes &splitvbar. NO&colon.  :hp2.Yes:ehp2. specifies
that file and directory names should be displayed in the traditional
upper-case by internal commands like COPY and DIR.  :hp2.No:ehp2. allows the
normal &4OS2. lower-case style. This directive does not affect the display of
filenames on HPFS drives.
:p.
Also see :link reftype=hd refid=SETDOS.SETDOS:elink. /U.

.* --------------------------------------------------------------------------

:h3 name=INIColor.Color Directives
:p.
These directives control the colors that &4OS2. use for its 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
:link reftype=hd refid=Colors.Colors and Color Names:elink..  The color directives are&colon.
:lm margin=8.:parml compact tsize=24 break=fit.
:pt.:link reftype=hd refid=INI_BrightBG.BrightBG:elink.:pd.Bright background colors
:pt.:link reftype=hd refid=INI_CDDWinColors.CDDWinColors:elink.:pd.Directory change window colors
:pt.:link reftype=hd refid=INI_ColorDir.ColorDir:elink.:pd.Directory colors
:pt.:link reftype=hd refid=INI_InputColors.InputColors:elink.:pd.Input colors
:pt.:link reftype=hd refid=INI_ListboxBarColors.ListboxBarColors:elink.:pd.Light bar color in list boxes
:pt.:link reftype=hd refid=INI_ListColors.ListColors:elink.:pd.LIST display colors
:pt.:link reftype=hd refid=INI_ListStatBarColors.ListStatBarColors:elink.:pd.LIST status bar colors
:pt.:link reftype=hd refid=INI_PopupWinColors.PopupWinColors:elink.:pd.Popup window colors
:pt.:link reftype=hd refid=INI_SelectColors.SelectColors:elink.:pd.SELECT display colors
:pt.:link reftype=hd refid=INI_SelectStatBarColors.SelectStatBarColors:elink.:pd.SELECT status bar colors
:pt.:link reftype=hd refid=INI_StdColors.StdColors:elink.:pd.Standard display colors
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h4 name=INI_BrightBG.BrightBG
:p.
:hp2.BrightBG:ehp2. = Yes &splitvbar. No.  If set to :hp2.Yes:ehp2., &4OS2. will
enable bright background colors in full-screen sessions.  If set to :hp2.No:ehp2., bright
backgrounds will be disabled, but blinking foreground characters
will be enabled.  If BrightBG is not used, &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.
:p.
See also :link reftype=hd refid=SETDOS.SETDOS:elink. /B.
:p.
Using BrightBG requires careful attention to interactions of
display type, mode, and color.  For a detailed explanation, see
:link reftype=hd refid=Colors.Colors and Color Names:elink..

.* --------------------------------------------------------------------------

:h4 name=INI_CDDWinColors.CDDWinColors
:p.
:hp2.CDDWinColors:ehp2. = Color&colon.  Sets the default colors for the
popup window used by :link reftype=hd refid=ExtDirSearch.extended directory
searches:elink..  If this directive is not used, the colors will be reversed
from the current colors on the screen.

.* --------------------------------------------------------------------------

:h4 name=INI_ColorDir.ColorDir
:p.
:hp2.ColorDir:ehp2. = ext1 ext2 ...&colon.colora;ext3 ext4 ...
&colon.colorb; ...&colon.  Sets the directory colors used by DIR and
SELECT.  The format is the same as that used for the COLORDIR environment
variable.  See the Color-Coded Directories topic under the :link reftype=hd
refid=DIR.DIR:elink. command for a complete description of the format of
this variable.

.* --------------------------------------------------------------------------

:h4 name=INI_InputColors.InputColors
:p.
:hp2.InputColors:ehp2. = Color&colon.  Sets the colors used for command-line
input.  This setting is useful for making your input stand out from
the normal output.

.* --------------------------------------------------------------------------

:h4 name=INI_ListboxBarColors.ListboxBarColors
:p.
:hp2.ListboxBarColors:ehp2. = Color&colon.  Sets the color for the highlight
bar in the popup list boxes (:hp1.i.e.:ehp1., :link reftype=hd
refid=HistWin.command history window:elink., :link reftype=hd
refid=FileComp.filename completion:elink. window, :link reftype=hd
refid=_@SELECT.@SELECT:elink. window, etc.).

.* --------------------------------------------------------------------------

:h4 name=INI_ListColors.ListColors
:p.
:hp2.ListColors:ehp2. = Color&colon.  Sets the colors used by the :link reftype=hd refid=LIST.LIST:elink.
command.  If this directive is not used, LIST will use the current
default colors set by the :link reftype=hd refid=CLS.CLS:elink. or :link reftype=hd refid=COLOR.COLOR:elink. command
or by the :link reftype=hd refid=INI_StdColors.StdColors:elink. directive.

.* --------------------------------------------------------------------------

:h4 name=INI_ListStatBarColors.ListStatBarColors
:p.
:hp2.ListStatBarColors:ehp2. = Color&colon.  Sets the colors used on the
:link reftype=hd refid=LIST.LIST:elink. 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 :link reftype=hd
refid=INI_ListColors.ListColors:elink.).

.* --------------------------------------------------------------------------

:h4 name=INI_PopupWinColors.PopupWinColors
:p.
:hp2.PopupWinColors:ehp2. = Color&colon.  Sets the default colors for the
command-line, directory history, and filename completion windows, and most
other popup windows (see :link reftype=hd
refid=INI_CDDWinColors.CDDWinColors:elink. for the extended directory search
window).  If this directive is not used, the colors will be reversed from
the current colors on the screen.

.* --------------------------------------------------------------------------

:h4 name=INI_SelectColors.SelectColors
:p.
:hp2.SelectColors:ehp2. = Color&colon.  Sets the color used by the
:link reftype=hd refid=SELECT.SELECT:elink. command.  If this directive is
not used, SELECT will use the current default colors set by the :link
reftype=hd refid=CLS.CLS:elink. or :link reftype=hd refid=COLOR.COLOR:elink.
command or by the :link reftype=hd refid=INI_StdColors.StdColors:elink.
directive.

.* --------------------------------------------------------------------------

:h4 name=INI_SelectStatBarColors.SelectStatBarColors
:p.
:hp2.SelectStatBarColors:ehp2. = Color&colon.  Sets the color used on the
:link reftype=hd refid=SELECT.SELECT:elink. 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
:link reftype=hd refid=INI_SelectColors.SelectColors:elink.).

.* --------------------------------------------------------------------------

:h4 name=INI_StdColors.StdColors
:p.
:hp2.StdColors:ehp2. = Color&colon.  Sets the standard colors to be used when
:link reftype=hd refid=CLS.CLS:elink. is used without a color specification, and for
:link reftype=hd refid=LIST.LIST:elink. and :link reftype=hd refid=SELECT.SELECT:elink. if
:link reftype=hd refid=INI_ListColors.ListColors:elink. and
:link reftype=hd refid=INI_SelectColors.SelectColors:elink. are not
used.  Using this directive is similar to placing a :link reftype=hd
refid=COLOR.COLOR:elink. command in 4START.
:p.
StdColors takes effect the first time :link reftype=hd refid=CLS.CLS:elink.,
:link reftype=hd refid=LIST.LIST:elink., or :link reftype=hd
refid=SELECT.SELECT:elink. is used after &4OS2. starts, but will not affect
the color of error or other messages displayed during the loading and
initialization process.

.* --------------------------------------------------------------------------

:h3 name=INIKeyMap.Key Mapping Directives
:p.
These directives allow you to change the keys used for command-line
editing and other internal functions.  They are divided into four types,
depending on the context in which the keys are used.  For a discussion
and list of directives for each type see&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=INIGenKeys.General Input Keys:elink.
:pt.:pd.:link reftype=hd refid=INIEditKeys.Command-Line Editing Keys:elink.
:pt.:pd.:link reftype=hd refid=INIHWinKeys.Popup Window Keys:elink.
:pt.:pd.:link reftype=hd refid=INIListKeys.LIST Keys:elink.
:eparml.:lm margin=1.
.br
Using a key mapping directive allows you to assign a different or
additional key to perform the function described.  For example, to
use function key :hp2.F3:ehp2. to invoke the HELP facility (normally
invoked with :hp2.F1:ehp2.)&colon.
:xmp.
        Help = F3
:exmp.:p.
Any directive can be used multiple times to assign multiple keys to
the same function.  For example&colon.
:xmp.
        ListFind = F            ;F does a find in LIST
        ListFind = F5           ;F5 also does a find in LIST
:exmp.:p.
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 :hp2.F1:ehp2. to the
AddFile directive (a part of filename completion), the :hp2.F1:ehp2. key
will no longer invoke the help system, so you will probably want to
assign a different key to Help.
:p.
See :link reftype=hd refid=KeyNames.Keys and Key Names:elink. before using the key mapping
directives.
:p.
Key assignments are processed before looking for keystroke aliases.  For
example, if you assign :hp2.Shift-F1:ehp2. to HELP and also assign
:hp2.Shift-F1:ehp2. to a key alias, the key alias will be ignored.
:p.
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 :link reftype=hd refid=INI_NormalKey.NormalKey:elink.
directive described below or the corresponding directive for keys
in the other key groups (:link reftype=hd refid=INI_NormalEditKey.NormalEditKey:elink.,
:link reftype=hd refid=INI_NormalPopupKey.NormalPopupKey:elink., or
:link reftype=hd refid=INI_NormalListKey.NormalListKey:elink.).

.* --------------------------------------------------------------------------

:h4 name=INIGenKeys.General Input Keys
:p.
These directives apply to all input.  They are in effect whenever
&4OS2. requests input from the keyboard, including during
:link reftype=hd refid=Editing.command-line editing:elink. and the :link reftype=hd refid=DESCRIBE.DESCRIBE:elink.,
:link reftype=hd refid=ESET.ESET:elink., :link reftype=hd refid=INPUT.INPUT:elink., :link reftype=hd refid=LIST.LIST:elink., and
:link reftype=hd refid=SELECT.SELECT:elink. commands.  The general input keys are&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:link reftype=hd refid=INI_Backspace.Backspace:elink.:pd.Deletes the character to the left of the cursor
:pt.:link reftype=hd refid=INI_BeginLine.BeginLine:elink.:pd.Moves the cursor to the start of the line
:pt.:link reftype=hd refid=INI_Del.Del:elink.:pd.Deletes the character at the cursor
:pt.:link reftype=hd refid=INI_DelToBeginning.DelToBeginning:elink.:pd.Deletes from the cursor to the start of the line
:pt.:link reftype=hd refid=INI_DelToEnd.DelToEnd:elink.:pd.Deletes from the cursor to the end of the line
:pt.:link reftype=hd refid=INI_DelWordLeft.DelWordLeft:elink.:pd.Deletes the word to the left of the cursor
:pt.:link reftype=hd refid=INI_DelWordRight.DelWordRight:elink.:pd.Deletes the word to the right of the cursor
:pt.:link reftype=hd refid=INI_Down.Down:elink.:pd.* Moves the cursor or scrolls the display down
:pt.:link reftype=hd refid=INI_EndLine.EndLine:elink.:pd.Moves the cursor to the end of the line
:pt.:link reftype=hd refid=INI_EraseLine.EraseLine:elink.:pd.Deletes the entire line
:pt.:link reftype=hd refid=INI_ExecLine.ExecLine:elink.:pd.Executes or accepts a line
:pt.:link reftype=hd refid=INI_Ins.Ins:elink.:pd.Toggles insert / overstrike mode
:pt.:link reftype=hd refid=INI_Left.Left:elink.:pd.* Moves the cursor or scrolls the display left
:pt.:link reftype=hd refid=INI_NormalKey.NormalKey:elink.:pd.* Deassigns a key
:pt.:link reftype=hd refid=INI_Right.Right:elink.:pd.* Moves the cursor or scrolls the display right
:pt.:link reftype=hd refid=INI_Up.Up:elink.:pd.* Moves the cursor or scrolls the display up
:pt.:link reftype=hd refid=INI_WordLeft.WordLeft:elink.:pd.Moves the cursor left one word
:pt.:link reftype=hd refid=INI_WordRight.WordRight:elink.:pd.Moves the cursor right one word
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h5 name=INI_Backspace.Backspace
:p.
:hp2.Backspace:ehp2. = Key (Bksp)&colon.  Deletes the character to the left of
the cursor.

.* --------------------------------------------------------------------------

:h5 name=INI_BeginLine.BeginLine
:p.
:hp2.BeginLine:ehp2. = Key (Home)&colon.  Moves the cursor to the beginning of
the line.

.* --------------------------------------------------------------------------

:h5 name=INI_Del.Del
:p.
:hp2.Del:ehp2. = Key (Del)&colon.  Deletes the character at the cursor.

.* --------------------------------------------------------------------------

:h5 name=INI_DelToBeginning.DelToBeginning
:p.
:hp2.DelToBeginning:ehp2. = Key (Ctrl-Home)&colon.  Deletes from the cursor to
the start of the line.

.* --------------------------------------------------------------------------

:h5 name=INI_DelToEnd.DelToEnd
:p.
:hp2.DelToEnd:ehp2. = Key (Ctrl-End)&colon.  Deletes from the cursor to the end
of the line.

.* --------------------------------------------------------------------------

:h5 name=INI_DelWordLeft.DelWordLeft
:p.
:hp2.DelWordLeft:ehp2. = Key (Ctrl-L)&colon.  Deletes the word to the left of
the cursor.

.* --------------------------------------------------------------------------

:h5 name=INI_DelWordRight.DelWordRight
:p.
:hp2.DelWordRight:ehp2. = Key (Ctrl-R, Ctrl-Bksp)&colon.  Deletes the word to
the right of the cursor.  See :link reftype=hd refid=INI_ClearKeyMap.ClearKeyMap:elink. if
you need to remove the default mapping of :hp2.Ctrl-Bksp:ehp2. to this
function.

.* --------------------------------------------------------------------------

:h5 name=INI_Down.Down
:p.
:hp2.Down:ehp2. = Key (Down)&colon.  Scrolls the display down one line in LIST;
moves the cursor down one line in :link reftype=hd refid=SELECT.SELECT:elink. and in the
command-line history, directory history, or :link reftype=hd refid=_@SELECT.%@SELECT:elink.
window.  (Scrolling down through the command history at the prompt
is controlled by :link reftype=hd refid=INI_NextHistory.NextHistory:elink., not by this
directive.)

.* --------------------------------------------------------------------------

:h5 name=INI_EndLine.EndLine
:p.
:hp2.EndLine:ehp2. = Key (End)&colon.  Moves the cursor to the end of the line.

.* --------------------------------------------------------------------------

:h5 name=INI_EraseLine.EraseLine
:p.
:hp2.EraseLine:ehp2. = Key (Esc)&colon.  Deletes the entire line.

.* --------------------------------------------------------------------------

:h5 name=INI_ExecLine.ExecLine
:p.
:hp2.ExecLine:ehp2. = Key (Enter)&colon.  Executes or accepts a line.

.* --------------------------------------------------------------------------

:h5 name=INI_Ins.Ins
:p.
:hp2.Ins:ehp2. = Key (Ins)&colon.  Toggles insert / overstrike mode during line
editing.

.* --------------------------------------------------------------------------

:h5 name=INI_Left.Left
:p.
:hp2.Left:ehp2. = Key (Left)&colon.  Moves the cursor left one character on
the input line; scrolls the display left 8 columns in LIST; scrolls the
display left 4 columns in the command-line, directory history, or
:link reftype=hd refid=_@SELECT.%@SELECT:elink. window.

.* --------------------------------------------------------------------------

:h5 name=INI_NormalKey.NormalKey
:p.
:hp2.NormalKey:ehp2. = Key&colon.  Deassigns a general input key in order to
disable the usual meaning of the key within &4OS2. and/or make it
available for keystroke aliases.  This will make the keystroke
operate as a "normal" key with no special function.  For example&colon.
:xmp.
        NormalKey = Ctrl-End
:exmp.:p.
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 :link reftype=hd refid=INI_DelToEnd.DelToEnd:elink. directive.

.* --------------------------------------------------------------------------

:h5 name=INI_Right.Right
:p.
:hp2.Right:ehp2. = Key (Right)&colon.  Moves the cursor right one character
on the input line; scrolls the display right 8 columns in :link reftype=hd
refid=LIST.LIST:elink.; scrolls the display right 4 columns in the
command-line history, directory history, or :link reftype=hd
refid=_@SELECT.%@SELECT:elink. window.

.* --------------------------------------------------------------------------

:h5 name=INI_Up.Up
:p.
:hp2.Up:ehp2. = Key (Up)&colon.  Scrolls the display up one line in
:link reftype=hd refid=LIST.LIST:elink.; moves the cursor up one line in :link reftype=hd refid=SELECT.SELECT:elink.
and in the command-line history, directory history, or
:link reftype=hd refid=_@SELECT.%@SELECT:elink. window.  (Scrolling up through the command
history at the prompt is controlled by
:link reftype=hd refid=INI_PrevHistory.PrevHistory:elink., not by this directive.)

.* --------------------------------------------------------------------------

:h5 name=INI_WordLeft.WordLeft
:p.
:hp2.WordLeft:ehp2. = Key (Ctrl-Left)&colon.  Moves the cursor left one word;
scrolls the display left 40 columns in :link reftype=hd refid=LIST.LIST:elink..

.* --------------------------------------------------------------------------

:h5 name=INI_WordRight.WordRight
:p.
:hp2.WordRight:ehp2. = Key (Ctrl-Right)&colon.  Moves the cursor right one
word; scrolls the display right 40 columns in :link reftype=hd refid=LIST.LIST:elink..

.* --------------------------------------------------------------------------

:h4 name=INIEditKeys.Command-Line Editing Keys
:p.
These directives apply only to command-line editing.  They are only
effective at the &4OS2. prompt.  The command-line editing keys are&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:link reftype=hd refid=INI_AddFile.AddFile:elink.:pd.Keeps filename completion entry and adds another
:pt.:link reftype=hd refid=INI_AliasExpand.AliasExpand:elink.:pd.Expands aliases without executing them
:pt.:link reftype=hd refid=INI_CommandEscape.CommandEscape:elink.:pd.Allows direct entry of a keystroke
:pt.:link reftype=hd refid=INI_DelHistory.DelHistory:elink.:pd.Deletes a history list entry
:pt.:link reftype=hd refid=INI_EndHistory.EndHistory:elink.:pd.Displays the last entry in the history list
:pt.:link reftype=hd refid=INI_Help.Help:elink.:pd.Invokes this help system
:pt.:link reftype=hd refid=INI_LineToEnd.LineToEnd:elink.:pd.Copies the current line to the end of the history
:pt.:link reftype=hd refid=INI_NextFile.NextFile:elink.:pd.Gets the next matching filename
:pt.:link reftype=hd refid=INI_NextHistory.NextHistory:elink.:pd.Recalls the next command from the history
:pt.:link reftype=hd refid=INI_NormalEditKey.NormalEditKey:elink.:pd.Deassigns a command-line editing key
:pt.:link reftype=hd refid=INI_PopFile.PopFile:elink.:pd.Opens the filename completion window
:pt.:link reftype=hd refid=INI_PrevFile.PrevFile:elink.:pd.Gets the previous matching filename
:pt.:link reftype=hd refid=INI_PrevHistory.PrevHistory:elink.:pd.Recalls the previous command from the history
:pt.:link reftype=hd refid=INI_SaveHistory.SaveHistory:elink.:pd.Saves the command line without executing it
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h5 name=INI_AddFile.AddFile
:p.
:hp2.AddFile:ehp2. = Key (F10)&colon.  Keeps the current filename completion
entry and inserts the next matching name.

.* --------------------------------------------------------------------------

:h5 name=INI_AliasExpand.AliasExpand
:p.
:hp2.AliasExpand:ehp2. = Key (Ctrl-F)&colon.  Expands all aliases in the
current command line without executing them.

.* --------------------------------------------------------------------------

:h5 name=INI_CommandEscape.CommandEscape
:p.
:hp2.CommandEscape:ehp2. = Key (Alt-255)&colon.  Allows direct entry of a
keystroke that would normally be handled by the command line editor
(:hp1.e.g.:ehp1. :hp2.Tab:ehp2. or :hp2.Ctrl-D):ehp2..

.* --------------------------------------------------------------------------

:h5 name=INI_DelHistory.DelHistory
:p.
:hp2.DelHistory:ehp2. = Key (Ctrl-D)&colon.  Deletes the displayed history list
entry and displays the previous entry.

.* --------------------------------------------------------------------------

:h5 name=INI_EndHistory.EndHistory
:p.
:hp2.EndHistory:ehp2. = Key (Ctrl-E)&colon.  Displays the last entry in the
history list.

.* --------------------------------------------------------------------------

:h5 name=INI_Help.Help
:p.
:hp2.Help:ehp2. = Key (F1)&colon.  Invokes the HELP facility.

.* --------------------------------------------------------------------------

:h5 name=INI_LineToEnd.LineToEnd
:p.
:hp2.LineToEnd:ehp2. = Key (Ctrl-Enter)&colon.  Copies the current command
line to the end of the history list, then executes it.

.* --------------------------------------------------------------------------

:h5 name=INI_NextFile.NextFile
:p.
:hp2.NextFile:ehp2. = Key (F9, Tab)&colon.  Gets the next matching filename.
See :link reftype=hd refid=INI_ClearKeyMap.ClearKeyMap:elink. if you need to
remove the default mapping of :hp2.Tab:ehp2. to this function.

.* --------------------------------------------------------------------------

:h5 name=INI_NextHistory.NextHistory
:p.
:hp2.NextHistory:ehp2. = Key (Down)&colon.  Recalls the next command from the
command history.

.* --------------------------------------------------------------------------

:h5 name=INI_NormalEditKey.NormalEditKey
:p.
:hp2.NormalEditKey:ehp2. = Key&colon.  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
additional details see :link reftype=hd refid=INI_NormalKey.NormalKey:elink..

.* --------------------------------------------------------------------------

:h5 name=INI_PopFile.PopFile
:p.
:hp2.PopFile:ehp2. = Key (F7, Ctrl-Tab)&colon.  Opens the filename completion
window.  You may not be able to use :hp2.Ctrl-Tab:ehp2., because not all
systems recognize it as a keystroke.  See
:link reftype=hd refid=INI_ClearKeyMap.ClearKeyMap:elink. if you need to
remove the default mapping of :hp2.Ctrl-Tab:ehp2. to this function.

.* --------------------------------------------------------------------------

:h5 name=INI_PrevFile.PrevFile
:p.
:hp2.PrevFile:ehp2. = Key (F8, Shift-Tab)&colon.  Gets the previous matching
filename.  See :link reftype=hd refid=INI_ClearKeyMap.ClearKeyMap:elink. if
you need to remove the default mapping of :hp2.Shift-Tab:ehp2. to this
function.

.* --------------------------------------------------------------------------

:h5 name=INI_PrevHistory.PrevHistory
:p.
:hp2.PrevHistory:ehp2. = Key (Up)&colon.  Recalls the previous command from
the command history.

.* --------------------------------------------------------------------------

:h5 name=INI_SaveHistory.SaveHistory
:p.
:hp2.SaveHistory:ehp2. = Key (Ctrl-K)&colon.  Saves the command line in the
command history list without executing it.

.* --------------------------------------------------------------------------

:h4 name=INIHWinKeys.Popup Window Keys
:p.
These directives apply to popup windows, including the command history
window, the directory history window, the filename completion window, the
extended directory search window, and the :link reftype=hd
refid=_@SELECT.%@SELECT:elink. window.  The popup window keys are&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:link reftype=hd refid=INI_DirWinOpen.DirWinOpen:elink.:pd.Opens the directory history window
:pt.:link reftype=hd refid=INI_HistWinOpen.HistWinOpen:elink.:pd.Opens the command history window
:pt.:link reftype=hd refid=INI_NormalPopupKey.NormalPopupKey:elink.:pd.Deassigns a popup window key
:pt.:link reftype=hd refid=INI_PopupWinBegin.PopupWinBegin:elink.:pd.Moves to the first line of the popup window
:pt.:link reftype=hd refid=INI_PopupWinDel.PopupWinDel:elink.:pd.Deletes a line from within the popup window
:pt.:link reftype=hd refid=INI_PopupWinEdit.PopupWinEdit:elink.:pd.Moves a line from the popup window to the prompt
:pt.:link reftype=hd refid=INI_PopupWinEnd.PopupWinEnd:elink.:pd.Moves to the last line of the popup window
:pt.:link reftype=hd refid=INI_PopupWinExec.PopupWinExec:elink.:pd.Executes the selected line in the popup window
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h5 name=INI_DirWinOpen.˙DirWinOpen
:p.
:hp2.DirWinOpen:ehp2. = Key (Ctrl-PgUp)&colon.  Opens the directory history
window while at the command line.

.* --------------------------------------------------------------------------

:h5 name=INI_HistWinOpen.HistWinOpen
:p.
:hp2.HistWinOpen:ehp2. = Key (PgUp)&colon.  Brings up the history window while
at the command line.

.* --------------------------------------------------------------------------

:h5 name=INI_NormalPopupKey.NormalPopupKey
:p.
:hp2.NormalPopupKey:ehp2. = Key&colon.  Deassigns a popup window key in
order to disable the usual meaning of the key within the popup window.
:p.
For additional details see :link reftype=hd
refid=INI_NormalKey.NormalKey:elink..

.* --------------------------------------------------------------------------

:h5 name=INI_PopupWinBegin.PopupWinBegin
:p.
:hp2.PopupWinBegin:ehp2. = Key (Ctrl-PgUp)&colon.  Moves to the first item in
the list when in the popup window

.* --------------------------------------------------------------------------

:h5 name=INI_PopupWinDel.PopupWinDel
:p.
:hp2.PopupWinDel:ehp2. = Key (Ctrl-D)&colon.  Deletes a line from within the
command history or directory history window.

.* --------------------------------------------------------------------------

:h5 name=INI_PopupWinEdit.PopupWinEdit
:p.
:hp2.PopupWinEdit:ehp2. = Key (Ctrl-Enter)&colon.  Moves a line from the
command history or directory history window to the prompt for editing.

.* --------------------------------------------------------------------------

:h5 name=INI_PopupWinEnd.PopupWinEnd
:p.
:hp2.PopupWinEnd:ehp2. = Key (Ctrl-PgDn)&colon.  Moves to the last item
when in the popup window.

.* --------------------------------------------------------------------------

:h5 name=INI_PopupWinExec.PopupWinExec
:p.
:hp2.PopupWinExec:ehp2. = Key (Enter)&colon.  Selects the current item and
closes the window.

.* --------------------------------------------------------------------------

:h4 name=INIListKeys.LIST Keys
:p.
These directives are effective only inside the :link reftype=hd refid=LIST.LIST:elink.
command.  The LIST keys are&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:link reftype=hd refid=INI_ListExit.ListExit:elink.:pd.Exits the current file.
:pt.:link reftype=hd refid=INI_ListFind.ListFind:elink.:pd.Prompts and searches for a string
:pt.:link reftype=hd refid=INI_ListFindReverse.ListFindReverse:elink.:pd.Prompts and searches backward for a string
:pt.:link reftype=hd refid=INI_ListHex.ListHex:elink.:pd.Toggles hexadecimal display mode
:pt.:link reftype=hd refid=INI_ListHighBit.ListHighBit:elink.:pd.Toggles LIST's "strip high bit" option
:pt.:link reftype=hd refid=INI_ListInfo.ListInfo:elink.:pd.Displays information about the current file
:pt.:link reftype=hd refid=INI_ListNext.ListNext:elink.:pd.Finds the next matching string
:pt.:link reftype=hd refid=INI_ListPrevious.ListPrevious:elink.:pd.Finds the previous matching string
:pt.:link reftype=hd refid=INI_ListPrint.ListPrint:elink.:pd.Prints the file on LPT1
:pt.:link reftype=hd refid=INI_ListWrap.ListWrap:elink.:pd.Toggles LIST's wrap option
:pt.:link reftype=hd refid=INI_NormalListKey.NormalListKey:elink.:pd.Deassigns a LIST key
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h5 name=INI_ListExit.ListExit
:p.
:hp2.ListExit:ehp2. = Key (Esc)&colon.  Exits from the LIST command.

.* --------------------------------------------------------------------------

:h5 name=INI_ListFind.ListFind
:p.
:hp2.ListFind:ehp2. = Key (F)&colon.  Prompts and searches for a string.

.* --------------------------------------------------------------------------

:h5 name=INI_ListFindReverse.ListFindReverse
:p.
:hp2.ListFindReverse:ehp2. = Key (Ctrl-F)&colon.  Prompts and searches
backward for a string.

.* --------------------------------------------------------------------------

:h5 name=INI_ListHex.ListHex
:p.
:hp2.ListHex:ehp2. = Key (X)&colon.  Toggles hexadecimal display mode.

.* --------------------------------------------------------------------------

:h5 name=INI_ListHighBit.ListHighBit
:p.
:hp2.ListHighBit:ehp2. = Key (H)&colon.  Toggles LIST's "strip high bit"
option, which can aid in displaying files from certain word processors.

.* --------------------------------------------------------------------------

:h5 name=INI_ListInfo.ListInfo
:p.
:hp2.ListInfo:ehp2. = Key (I)&colon.  Displays information about the current
file.

.* --------------------------------------------------------------------------

:h5 name=INI_ListNext.ListNext
:p.
:hp2.ListNext:ehp2. = Key (N)&colon.  Finds the next matching string.

.* --------------------------------------------------------------------------

:h5 name=INI_ListPrevious.ListPrevious
:p.
:hp2.ListPrevious:ehp2. = Key (Ctrl-N)&colon.  Finds the previous matching
string.

.* --------------------------------------------------------------------------

:h5 name=INI_ListPrint.ListPrint
:p.
:hp2.ListPrint:ehp2. = Key (P)&colon.  Prints the file on LPT1.

.* --------------------------------------------------------------------------

:h5 name=INI_ListWrap.ListWrap
:p.
:hp2.ListWrap:ehp2. = Key (W)&colon.  Toggles LIST's wrap option on and off.
The wrap option wraps text at the right margin.

.* --------------------------------------------------------------------------

:h5 name=INI_NormalListKey.NormalListKey
:p.
:hp2.NormalListKey:ehp2. = Key&colon.  Deassigns a LIST key in order to disable
the usual meaning of the key within LIST.  For additional details
see :link reftype=hd refid=INI_NormalKey.NormalKey:elink..

.* --------------------------------------------------------------------------

:h3 name=INIAdv.Advanced Directives
:p.
These directives are generally used for unusual circumstances, or
for diagnosing problems.  Most often they are not needed in normal
use.  The advanced directives are&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:link reftype=hd refid=INI_ClearKeyMap.ClearKeyMap:elink.:pd.Clear default key mappings
:pt.:link reftype=hd refid=INI_Debug.Debug:elink.:pd.Set debugging options
:pt.:link reftype=hd refid=INI_Include.Include:elink.:pd.Include a file containing :hp1..INI:ehp1. directives
:pt.:link reftype=hd refid=INI_NextINIFile.NextINIFile:elink.:pd.Set secondary shell :hp1..INI:ehp1. file name
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h4 name=INI_ClearKeyMap.ClearKeyMap
:p.
:hp2.ClearKeyMap:ehp2.&colon.  Clears all current :link reftype=hd refid=INIKeyMap.key mappings:elink..
ClearKeyMap is a special directive which has no value or "=" after
it.  Use ClearKeyMap to make one of the keys in the default map
(:hp2.Tab:ehp2., :hp2.Shift-Tab:ehp2., :hp2.Ctrl-Tab:ehp2., or :hp2.Ctrl-Bksp:ehp2.) available
for a keystroke alias, or in the :hp2.[Secondary]:ehp2. section of the
:hp1..INI:ehp1. 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, then recreate the mappings you want to
retain (:hp1.e.g.:ehp1., with "NextFile=Tab", etc.).
:p.
If you set :hp2.DescriptionName = EA, :ehp2.&4OS2. will use the ".SUBJECT"
extended attribute (EA) for file descriptions instead of a separate
file.  Note that using EAs will slow the :link reftype=hd
refid=DIR.DIR:elink. and :link reftype=hd refid=SELECT.SELECT:elink.
commands noticeably.  On a FAT volume, performance may be 10% to 200%
slower, depending on whether the system has cached the extended attributes.

.* --------------------------------------------------------------------------

:h4 name=INI_Debug.Debug
:p.
:hp2.Debug:ehp2. = nnnn (0)&colon.  Controls certain debugging options which
can assist you in tracking down unusual problems.  Use the following values
for Debug; to select more than one option, add the values together:
:lm margin=4.:parml tsize=4 break=fit.
:pt.:hp2.1:ehp2.:pd.During the startup process, display the complete command
tail passed to &4OS2., then wait for a keystroke.
:pt.:hp2.2:ehp2.:pd.Include the product name with each error message
displayed by &4OS2..  This may be useful if you are unsure of the origin of a
particular error message.
:eparml.:lm margin=1.
:p.
Also see the :link reftype=hd refid=BatchDebug.batch file debugger:elink., a
separate and unrelated facility for stepping through batch files.

.* --------------------------------------------------------------------------

:h4 name=INI_Include.Include
:p.
:hp2.Include:ehp2. = File&colon.  Include the text from the named file at
this point in the processing of the current :hp1..INI:ehp1. file.  Use this
option to share a file of directives between several products.  The text in
the named file is processed just as if it were part of the original
:hp1..INI:ehp1. file.  When the include file is finished, processing resumes
at the point where it left off in the original file.  The included file may contain any valid directive for the
current section, but may not contain a section name.  Includes may be nested up
to three levels deep (counting the original file as level 1).
:p.
You must maintain include files manually -- the :link reftype=hd
refid=OPTION.OPTION:elink. command modifies the original :hp1..INI:ehp1.
file only, and does not update included files.

.* --------------------------------------------------------------------------

:h4 name=INI_NextINIFile.NextINIFile
:p.
:hp2.NextINIFile:ehp2. = File.  The full path and name of the file must be
specified.  All subsequent shells will read the specified :hp1..INI:ehp1.
file, and ignore any :hp2.[Secondary]:ehp2. section in the original
:hp1..INI:ehp1. file.

.* --------------------------------------------------------------------------

:h2 name=INIExamples..INI File Examples
:p.
This example configures certain special characters to match 4DOS, and
changes other default settings to suit the user's preferences.  Note that
the comments for the :link reftype=hd refid=INI_HelpBook.HelpBook:elink. and
:link reftype=hd refid=INI_ColorDir.ColorDir:elink. directives are on
separate lines before the directives themselves, as no comments are allowed
in string directives&colon.
:xmp.
        [&4OS2.]
        InstallPath = c&colon.\&4OS2.300      ;installation directory
        PauseOnError = No             ;don't stop on INI errors
        CommandSep = ^                ;4DOS command separator
        ParameterChar = &amp.             ;4DOS parameter character
        BatchEcho = No                ;default to ECHO OFF
                                      ;show only &4OS2. help for F1 / HELP
        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
                                      ;set directory display colors
        colordir = DIRS&colon.bri yel;com exe bat btm cmd&colon.bri whi
:exmp.
:p.

.* --------------------------------------------------------------------------

:h1 nosearch name=TOC_Setup.Setup and Troubleshooting
:p.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=Startup.Starting &4OS2.:elink.
:pt.:pd.:link reftype=hd refid=HelpSys.The &4OS2. Help System:elink.
:pt.:pd.:link reftype=hd refid=Errors.Error Messages:elink.
:pt.:pd.:link reftype=hd refid=Support.Troubleshooting, Service, and
Support:elink.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=Startup.Starting &4OS2.
:p.
Each &4OS2. object on your OS/2 desktop represents a different
&4OS2. session.  You can configure any of these sessions to run
in windowed or full-screen mode, and you can set any necessary
command line parameters for &4OS2., by adjusting the properties of the
desktop objects.
:p.
To adjust the properties of an object you need to be familiar with
how object properties are set in your version of OS/2.  For details
see your OS/2 documentation, or the &4OS2. Introduction and Installation
Guide.
:p.
When you configure a &4OS2. object, place an asterisk [:hp2.*:ehp2.] in the
Program Name field, and put any startup options that you want
passed to &4OS2. (:hp1.e.g.:ehp1., @inifile) in the Parameters field.  For
example&colon.
:xmp.
     Path and file name&colon.  *
     Parameters&colon.          @D&colon.\START\&4OS2INI.
     Working directory&colon.   C&colon.\
:exmp.:p.
(If &4OS2. is not set up as your default OS/2 shell in
:hp1.CONFIG.SYS:ehp1., use the full path and name for :hp1.&4OS2..EXE:ehp1. as
the program name, rather than the asterisk.)
:p.
To run a startup batch file for a particular &4OS2. session, include its name
(with a path, if the batch file is not in the session's startup directory)
as the last item in the Parameters field when you configure the desktop
object.  That batch file will be executed after any :link reftype=hd
refid=AutoBatch.4START:elink. file, but before the first prompt is
displayed.  You can use the batch file to set environment variables and
execute any other &4OS2. commands.
:p.
You can also execute any internal &4OS2. command, external command,
or alias by placing its name in the Parameters field.  For example&colon.
:xmp.
     Path and file name&colon.  *
     Parameters&colon.          D&colon.\STARTOS2.CMD
     Working directory&colon.   C&colon.\
:exmp.:p.
To execute an internal or external command, an alias, or a batch file and
then exit (return to the desktop) when it is done, place /C command (rather
than just command) as the last item in the Parameters field.  For
example&colon.
:xmp.
     Path and file name&colon.  *
     Parameters&colon.          /C COMFILES.BTM
     Working directory&colon.   C&colon.\
:exmp.
:p.
The &4OS2. command line does not need to contain any information.  When
invoked with an empty command line, &4OS2. will configure itself from the
:hp1.&4OS2INI.:ehp1. file, run 4START, and then display a prompt and wait for
you to type a command.  However, you may add options on the &4OS2.
command line to change the way &4OS2. operates.
:p.
&4OS2. recognizes several optional fields on the command line.
All of the options go on one line.  If you use more than one
of these fields, their order is important.  The syntax for the
command line is&colon.
:p.:lm margin=8.
:hp2.[d&colon.\path] [@d&colon.\path\inifile] [//iniline]...
[/L] [/LA] [/LD] [/LH] [/S] [/C | /K] [command]:ehp2.
:lm margin=1.
:p.
The options are&colon.
:lm margin=8.
:p.
:hp2.d&colon.\path&colon.:ehp2.  &4OS2. will use this directory and path to set
the :link reftype=hd refid=COMSPEC.COMSPEC:elink. environment variable
for this session.  If this option is not used, COMSPEC is set from the location
of :hp1.&4OS2..EXE:ehp1..  &4OS2. always knows what drive and directory it was
started from and can set COMSPEC accordingly.  It is included only
for compatibility with :hp1.CMD.EXE:ehp1..  This option cannot be used for
secondary shells.
:p.
:hp2.@d&colon.\path\inifile&colon.:ehp2.  This option sets the path and name of
the :link reftype=hd refid=INIFile.&4OS2INI.:elink. file.  You do not
need this option if you aren't using a :hp1.&4OS2INI.:ehp1. file, or if the
file is named :hp1.&4OS2INI.:ehp1. and is stored in the same subdirectory as
:hp1.&4OS2..EXE:ehp1. or in the root directory of the boot drive.  This option
is most useful if you want to start a &4OS2. session with a specific and
unique :hp1..INI:ehp1. file.
:p.
:hp2.//iniline&colon.:ehp2.  This option tells &4OS2. to treat the text
appearing between the :hp2.//:ehp2. and the next space or tab as a
:link reftype=hd refid=INIFile.&4OS2INI.:elink. directive.  The
directive should be in the same format as a line in :hp1.&4OS2INI.:ehp1., but
it may not contain spaces, tabs, or comments.  This option overrides any
corresponding directive in your :hp1.&4OS2INI.:ehp1. file.  It is a convenient
way to send &4OS2. one or two simple directives without modifying or creating
a new :hp1.&4OS2INI.:ehp1. file.
:p.
:hp2./L:ehp2., :hp2./LA:ehp2., :hp2./LD:ehp2., and :hp2./LH:ehp2.&colon.  These options force &4OS2. to to use a local
alias, directory history, and / or command history list.  They can be
used to override any
:link reftype=hd refid=INI_LocalAliases.LocalAliases:elink.=No,
:link reftype=hd refid=INI_LocalDirHistory.LocalDirHistory:elink.=No, or
:link reftype=hd refid=INI_LocalHistory.LocalHistory:elink.=No
settings in :hp1.&4OS2INI.:ehp1..  This allows you to use global lists as the
default, but start a specific &4OS2. session with local lists.  :hp2./LA:ehp2.
forces local aliases, :hp2./LD:ehp2. forces local directory history,
:hp2./LH:ehp2. forces local history, and :hp2./L:ehp2. forces all three.
:p.
See :link reftype=hd refid=CmdHist.Command History:elink. for details on local
and global history, :link reftype=hd refid=DirHist.Directory History
Window:elink. for details on local and global directory history, and :link
reftype=hd refid=ALIAS.ALIAS:elink. for details on local and global aliases.
:p.
:hp2./S&colon.:ehp2.  This option tells &4OS2. that you do not want it to
set up a Ctrl-C / Ctrl-Break handler.  It is included for
compatibility with :hp1.CMD.EXE:ehp1., but it may cause the system
to operate incorrectly if you use this option without
other software to handle Ctrl-C and Ctrl-Break.
:p.
:hp2.[/C | /K] command&colon.:ehp2.  This option tells &4OS2. to run a
command when it starts.  The command will be run after :link reftype=hd
refid=AutoBatch.4START:elink. has been executed and before any command
prompt is displayed.  It can be any valid internal or external command,
batch file, or alias; you may include multiple commands by using the command
separator.  All other startup options must be placed before the command,
because &4OS2. will treat characters after the command as part of the command
and not as additional startup options.
:p.
When the command is preceded by a :hp2./C:ehp2., &4OS2. will execute the
command and then exit and return to the parent program or the OS/2 desktop
without displaying a prompt.
:p.
The :hp2./K:ehp2. switch has no effect; using it is the same as placing the
command (without a :hp2./C:ehp2. or :hp2./K:ehp2.) at the end of the startup
command line.  It is included only for compatibility with :hp1.CMD.EXE:ehp1..
:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=HelpSys.The &4OS2. Help System
:p.
This online help system for &4OS2. covers all &4OS2. features and internal
commands.  It includes reference information to assist you in using &4OS2.
and developing batch files; however it does not include all of the details
which are included in the printed &4OS2. manuals.
:p.
If you type part or all of a command on the line and then press
:hp2.F1:ehp2., the help system will provide "context-sensitive" help by
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 and you can pick the one you
want.
:p.
You can use this feature to obtain help on any topic -- not just on
commands.  For example, if you enter the command :hp2.HELP _DISK:ehp2. you
will see help for the :link reftype=hd refid=_DISK._DISK:elink. internal
variable.  See the :link reftype=hd refid=HELP.HELP:elink. command for more
information.
:p.
If you type the name of any internal command at the prompt,
followed by a slash and a question mark [:hp2./?:ehp2.] like this&colon.
:xmp.
        copy /?
:exmp.:p.
then you will see help for the command in a "quick-reference"
style.  Output from a :hp2./?:ehp2. display may be :link reftype=hd
refid=Redirection.redirected:elink. with :hp2.>:ehp2. or :hp2.>>:ehp2..
:p.
The :hp2./?:ehp2. option may not work correctly if you have used an :link
reftype=hd refid=Aliases.alias:elink.
to redefine how an internal command operates.  To view the :hp2./?:ehp2.
help for such a command you must add an asterisk to the beginning
of the command to disable alias processing.  For example, if you
have defined this alias&colon.
:xmp.
        alias copy *copy /r
:exmp.:p.
then the command :link reftype=hd refid=COPY.COPY:elink. /? will be
translated to COPY /R /?, which will not work properly.  However, if you use
*COPY /?, the alias will be ignored and the :hp2./?:ehp2. will work as you
intended.
:p.
The &4OS2. help system uses OS/2's :hp1.VIEW.EXE:ehp1. to display this help
text.  Once you've started the help system with HELP or :hp2.F1:ehp2., you
can use VIEW's standard keystrokes to navigate.  For more information,
click on the Help menu at the top of the VIEW window.
:p.
:p.
:hp2.Configuring the Help System :ehp2.
:p.
You can select which help "books" are displayed when you press the F1 key
or enter the HELP command.  A help book is a single :hp1..INF:ehp1.
file.  This help text is in the file :hp1.&4OS2..INF:ehp1..
:p.
By default, &4OS2. opens this book and the OS/2 command reference file,
:hp1.CMDREF.INF:ehp1..  You can change the default books opened for the &4OS2.
help system with the :link reftype=hd refid=INI_HelpBook.HelpBook:elink.
directive in :hp1.&4OS2INI.:ehp1..  The default setting is &4OS2.+CMDREF.  For
example, to load only the &4OS2. help when you press :hp2.F1:ehp2. or enter
the HELP command&colon.
:xmp.
        HelpBook = &4OS2.
:exmp.

.* --------------------------------------------------------------------------

:h2 name=Errors.Error Messages
:p.
This section lists error messages generated by &4OS2., and includes a
recommended course of action where appropriate.  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 :link reftype=hd
refid=TechSup.technical support:elink..
:p.
Error messages relating to files are generally reports of errors
returned by OS/2.  You may find some of these messages (for
example, "Access denied") vague enough that they are not always
helpful.  &4OS2. includes the file name in file error messages, but
is 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 OS/2.
:p.
The following list includes all error messages, in alphabetical
order&colon.
:p.
:hp2.Access denied:ehp2.&colon.  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.
:p.
:hp2.Alias loop:ehp2.&colon.  An alias refers back to itself either directly or
indirectly (:hp1.i.e.:ehp1., a = b = a), or aliases are nested more than
16 levels deep.  Correct your alias list.
:p.
:hp2.Already excluded files:ehp2.&colon.  You used more than one exclude
range in a command.  Combine the exclusions into a single range.
:p.
:hp2.Bad disk unit:ehp2.&colon.  Generally caused by a disk drive hardware
failure.
:p.
:hp2.Batch file missing:ehp2.&colon.  &4OS2. can't find the batch
(:hp1..BTM:ehp1. or :hp1..CMD:ehp1. ) file it was running.  It was either
deleted, renamed, moved, or the disk was changed.  Correct the problem and
rerun the file.
:p.
:hp2.Can't copy file to itself:ehp2.&colon.  You cannot :link reftype=hd
refid=COPY.COPY:elink. or :link reftype=hd refid=MOVE.MOVE:elink. a file to
itself.  &4OS2. attempts to perform full path and filename expansion before
copying to help ensure that files aren't inadvertently destroyed.
:p.
:hp2.Can't create:ehp2.&colon.  &4OS2. 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.
:p.
:hp2.Can't delete:ehp2.&colon.  &4OS2. can't delete the specified file or
directory.  The disk is probably write protected.
:p.
:hp2.Can't get directory:ehp2.&colon.  &4OS2. can't read the directory.  The
disk drive is probably not ready.
:p.
:hp2.Can't install hook:ehp2.&colon.  &4OS2. cannot install the operating
system hooks required to support the :link reftype=hd
refid=KEYSTACK.KEYSTACK:elink. command.  The operating system may have
been damaged or improperly installed, or there may be too few resources
to support KEYSTACK.
:p.
:hp2.Can't make directory entry:ehp2.&colon.  &4OS2. 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.
:p.
:hp2.Can't open:ehp2.&colon.  &4OS2. can't open the specified file.  Either the
file doesn't exist or the disk directory or File Allocation Table
is damaged.
:p.
:hp2.Can't remove current directory:ehp2.&colon.  You attempted to remove the
current directory, which OS/2 does not allow.  Change to the parent
directory and try again.
:p.
:hp2.CD-ROM door open:ehp2. or :hp2.CD-ROM not ready:ehp2.&colon.  The
CD-ROM drive door is open, the power is off, or the drive is
disconnected.  Correct the problem and try again.
:p.
:hp2.CD-ROM not High Sierra or ISO-9660:ehp2.&colon.  The CD-ROM is not
recognized as a data CD (it may be a music CD).  Put the correct CD in the
drive and try again.
:p.
:hp2.Clipboard is empty or not text format:ehp2.&colon.  You tried to
retrieve some text from the OS/2 clipboard, but there is no text
available.  Correct the contents of the clipboard and try again.
:p.
:hp2.Clipboard is in use by another program:ehp2.&colon.  &4OS2. could not
access the OS/2 clipboard because another program was using it.  Wait until
the clipboard is available, or complete any pending action in the other
program, then try again.
:p.
:hp2.Command line too long:ehp2.&colon.  A single command exceeded
1023 characters, or the entire command line exceeded 2047 characters, 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.
:p.
:hp2.Command only valid in batch file:ehp2.&colon.  You have tried to use a
batch file command, like :link reftype=hd refid=DO.DO:elink. or :link
reftype=hd refid=GOSUB.GOSUB:elink., from the command line or in
an alias.  A few commands can only be used in batch files (see the
individual commands for details).
:p.
:hp2.Contents lost before copy:ehp2.&colon.  :link reftype=hd
refid=COPY.COPY:elink. was appending files, and found one of the source
files is the same as the destination.  That source file is skipped, and
appending continues with the next file.
:p.
:hp2.Data error:ehp2.&colon.  OS/2 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.
:p.
:hp2.Directory stack empty:ehp2.&colon.  :link reftype=hd
refid=POPD.POPD:elink. or :link reftype=hd refid=DIRS.DIRS:elink. can't find
any entries in the directory stack.
:p.
:hp2.Disk is write protected:ehp2.&colon.  The disk cannot be written to.  Check
the disk and remove the write-protect tab or close the write-
protect window if necessary.
:p.
:hp2.Drive not ready -- close door:ehp2.&colon.  The removable disk drive
door is open.  Close the door and try again.
:p.
:hp2.Duplicate redirection:ehp2.&colon.  You tried to redirect standard
input, standard output, or stand error more than once in the same
command.
:p.
:hp2.Environment already saved:ehp2.&colon.  You have already saved the
environment with a previous :link reftype=hd refid=SETLOCAL.SETLOCAL:elink. command.  You
cannot nest SETLOCAL / :link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink. pairs.
:p.
:hp2.Error in command-line directive:ehp2.&colon.  You used the
:hp2.//iniline:ehp2. option to place an :hp1.&4OS2INI.:ehp1. directive on the
:link reftype=hd refid=Startup.startup:elink. command line, but the
directive is in error.  Usually a more specific error message follows, and
can be looked up in this list.
:p.
:hp2.Error on line [nnnn] of [filename]:ehp2.&colon.  There is an error in your
:link reftype=hd refid=INIFile.&4OS2INI.:elink. file.  The following message explains the error
in more detail.  Correct the line in error and restart &4OS2. for
your change to take effect.
:p.
:hp2.Error reading:ehp2.&colon.  OS/2 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.
:p.
:hp2.Error writing:ehp2.&colon.  OS/2 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.
:p.
:hp2.Exceeded batch nesting limit:ehp2.&colon.  You have attempted to nest batch
files more than 10 levels deep.
:p.
:hp2.File Allocation Table bad:ehp2.&colon.  OS/2  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.
:p.
:hp2.File exists:ehp2.&colon.  The requested output file already exists, and
&4OS2. won't overwrite it.
:p.
:hp2.File is empty:ehp2.&colon.  You attempted to use an empty file in
:link reftype=hd refid=_@SELECT.@SELECT:elink..  Correct the file name
or contents and try again.
:p.
:hp2.File not found:ehp2.&colon.  &4OS2. couldn't find the specified file.  Check
the spelling and path name.
:p.
:hp2.General failure:ehp2.&colon.  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 :hp2.Data error:ehp2. above.
:p.
:hp2.Include file not found:ehp2.&colon.  You used the :link reftype=hd
refid=INI_Include.Include:elink. directive in the :hp1.&4OS2INI.:ehp1. file, but the
file you specified was not found or could not be opened.
:p.
:hp2.Include files nested too deep:ehp2.&colon.  You used the :link
reftype=hd refid=INI_Include.Include:elink. directive in the &4OS2INI.
file, and attempted to nest include files more than three levels deep.
:p.
:hp2.Infinite COPY or MOVE loop:ehp2.&colon.  You tried to :link reftype=hd
refid=COPY.COPY:elink. or :link reftype=hd refid=MOVE.MOVE:elink. 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.
:p.
:hp2.Insufficient disk space:ehp2.&colon.  :link reftype=hd
refid=COPY.COPY:elink. or MOVE ran out of room on the destination
drive.  Remove some files and retry the operation.
:p.
:hp2.Invalid character value:ehp2.&colon.  You gave an invalid value for a
character directive in the :link reftype=hd refid=INIFile.&4OS2INI.:elink. file.
:p.
:hp2.Invalid choice value:ehp2.&colon.  You gave an invalid value for a "choice"
directive (one that accepts a choice from a list, like "Yes" or
"No") in the :link reftype=hd refid=INIFile.&4OS2INI.:elink. file.
:p.
:hp2.Invalid color:ehp2.&colon.  You gave an invalid value for a color directive
in the :link reftype=hd refid=INIFile.&4OS2INI.:elink. file.
:p.
:hp2.Invalid count:ehp2.&colon.  The character repeat count for :link
reftype=hd refid=KEYSTACK.KEYSTACK:elink. is incorrect.
:p.
:hp2.Invalid date:ehp2.&colon.  An invalid date was entered.  Check the syntax
and reenter.
:p.
:hp2.Invalid directive name:ehp2.&colon.  &4OS2. can't recognize the name of a
directive in your :link reftype=hd refid=INIFile.&4OS2INI.:elink. file.
:p.
:hp2.Invalid drive:ehp2.&colon.  A bad or non-existent disk drive was specified.
:p.
:hp2.Invalid key name:ehp2.&colon.  You tried to make an invalid key
substitution in the :link reftype=hd refid=INIFile.&4OS2INI.:elink. file, or you used an invalid
key name in a keystroke :link reftype=hd refid=alias.alias:elink. or command.  Correct the
error and retry the operation.
:p.
:hp2.Invalid numeric value:ehp2.&colon.  You gave an invalid value for a
numeric directive in the :link reftype=hd refid=INIFile.&4OS2INI.:elink. file.
:p.
:hp2.Invalid parameter:ehp2.&colon.  &4OS2. didn't recognize a parameter.  Check
the syntax and spelling of the command you entered.
:p.
:hp2.Invalid path:ehp2.&colon.  The specified path does not exist.  Check the
disk specification and/or spelling.
:p.
:hp2.Invalid path or file name:ehp2.&colon.  You used an invalid path or
filename in a directive in the :link reftype=hd refid=INIFile.&4OS2INI.:elink. file.
:p.
:hp2.Invalid time:ehp2.&colon.  An invalid time was entered.  Check the syntax
and reenter.
:p.
:hp2.Keystroke substitution table full:ehp2.&colon.  &4OS2. ran out of room to
store :link reftype=hd refid=INIKeyMap.keystroke substitutions:elink.
entered in the :hp1.&4OS2INI.:ehp1. file.  Reduce the number of key
substitutions or contact JP Software or your dealer for assistance.
:p.
:hp2.Label not found:ehp2.&colon.  A :link reftype=hd refid=GOTO.GOTO:elink.
or :link reftype=hd refid=GOSUB.GOSUB:elink. referred to a non-existent
label. Check your batch file.
:p.
:hp2.Missing ENDTEXT:ehp2.&colon.  A :link reftype=hd refid=TEXT.TEXT:elink.
command is missing a matching :link reftype=hd
refid=TEXT.ENDTEXT:elink..  Check the batch file.
:p.
:hp2.Missing GOSUB:ehp2.&colon.  &4OS2. cannot perform the :link reftype=hd
refid=RETURN.RETURN:elink. command in a batch file.  You tried to do a
RETURN without a :link reftype=hd refid=GOSUB.GOSUB:elink., or your batch
file has been corrupted.
:p.
:hp2.Missing SETLOCAL:ehp2.&colon.  An :link reftype=hd
refid=ENDLOCAL.ENDLOCAL:elink. was used without a matching :link reftype=hd
refid=SETLOCAL.SETLOCAL:elink..
:p.
:hp2.No aliases defined:ehp2.&colon.  You tried to display aliases but no
aliases have been defined.
:p.
:hp2.No closing quote:ehp2.&colon.  &4OS2. couldn't find a second matching back
quote [:hp2.`:ehp2.] or double-quote [:hp2.":ehp2.] on the command line.
:p.
:hp2.No expression:ehp2.&colon.  The expression passed to the :link
reftype=hd refid=_@EVAL.@EVAL:elink. variable function is empty.  Correct
the expression and retry the operation.
:p.
:hp2.No room for INI file name:ehp2.&colon.  &4OS2. does not have enough space to
pass the name of your :link reftype=hd refid=INIFile.&4OS2INI.:elink. file to secondary shells;
see :hp2.String area overflow:ehp2. for more details.  Any [Secondary]
section in :hp1.&4OS2INI.:ehp1. will be ignored in secondary shells until
the problem is corrected and the system or session is restarted.
:p.
:hp2.No shared memory found:ehp2.&colon.  The :link reftype=hd
refid=SHRALIAS.SHRALIAS:elink. command could not find any global alias list,
history list, or directory history list to retain, because you executed the
command from a session with local lists.  Start &4OS2. with at least one
global list, then invoke SHRALIAS.
:p.
:hp2.Not a windowed session:ehp2.&colon.  You tried to use the
:link reftype=hd refid=WINDOW.WINDOW:elink. command in a full-screen session.  WINDOW
is valid only in windowed sessions.
:p.
:hp2.Not an alias:ehp2.&colon.  The specified alias is not in the alias list.
:p.
:hp2.Not in environment:ehp2.&colon.  The specified variable is not in the
environment.
:p.
:hp2.Not ready:ehp2.&colon.  The specified device can't be accessed.
:p.
:hp2.Not same device:ehp2.&colon.  This error usually appears in :link
reftype=hd refid=REN.RENAME:elink..  You cannot rename a file to a
different disk drive.
:p.
:hp2.Out of memory:ehp2.&colon.  &4OS2. or OS/2 had insufficient memory to execute
the last command.  Try to free some memory by closing other sessions.  If the
error persists, contact JP Software for assistance.
:p.
:hp2.Out of paper:ehp2.&colon.  OS/2 detected an out-of-paper condition on one
of the printers.  Check your printer and add paper if necessary.
:p.
:hp2.Overflow:ehp2.&colon.  An arithmetic overflow occurred in the :link
reftype=hd refid=_@EVAL.@EVAL:elink. 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.
:p.
:hp2.Read error:ehp2.&colon.  OS/2 encountered a disk read error; usually caused
by a bad or unformatted disk.  Also see :hp2.Data error:ehp2. above.
:p.
:hp2.Sector not found:ehp2.&colon.  Disk error, usually caused by a bad or
unformatted disk.  Also see :hp2.Data error:ehp2. above.
:p.
:hp2.Seek error:ehp2.&colon.  OS/2 can't seek to the proper location on the
disk.  This is generally caused by a bad disk or drive.  Also see :hp2.Data
error:ehp2. above.
:p.
:hp2.Sharing violation:ehp2.&colon.  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.
:p.
:hp2.SHRALIAS already loaded:ehp2.&colon.  You used the :link reftype=hd
refid=SHRALIAS.SHRALIAS:elink. command to load :hp1.SHRALIAS.EXE:ehp1., but
it was already loaded.  This message is informational and generally does not
indicate an error condition.
:p.
:hp2.SHRALIAS not loaded:ehp2.&colon.  You used the :link reftype=hd
refid=SHRALIAS.SHRALIAS:elink. /U command to unload :hp1.SHRALIAS.EXE:ehp1.,
but it was never loaded.  This message is informational and may not indicate
an error condition.
:p.
:hp2.String area overflow:ehp2.&colon.  &4OS2. ran out of room to store the text
from string directives in the :link reftype=hd refid=INIFile.&4OS2INI.:elink.
file.  Reduce the complexity of the :hp1.&4OS2INI.:ehp1. file or contact JP
Software for assistance.
:p.
:hp2.Syntax error:ehp2.&colon.  A command or :link reftype=hd refid=VarFuncs.variable function:elink. was
entered in an improper format.  Check the syntax and correct the
error.
:p.
:hp2.Too many open files:ehp2.&colon.  OS/2 has run out of file handles.
Try increasing the FILES setting in :hp1.CONFIG.SYS:ehp1..
:p.
:hp2.Unbalanced parentheses:ehp2.&colon.  The number of left and right
parentheses did not match in an expression passed to the :link reftype=hd
refid=_@EVAL.@EVAL:elink. variable function.  Correct the expression and
retry the operation.
:p.
:hp2.Unknown command:ehp2.&colon.  A command was entered that &4OS2. 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 :link reftype=hd refid=ALIAS.ALIAS:elink.).
:p.
:hp2.UNKNOWN_CMD loop:ehp2.&colon.  The UNKNOWN_CMD alias (see
:link reftype=hd refid=ALIAS.ALIAS:elink.) called itself more than
ten times.  The alias probably contains an unknown command itself, and is
stuck in an infinite loop.  Correct the alias.
:p.
:hp2.Variable loop:ehp2.&colon.  A nested environment variable refers to itself,
or variables are nested more than 16 deep.  Correct the error and
retry the command.
:p.
:hp2.Warning&colon.  Can't load &4OS2.DLL:ehp2.&colon.  &4OS2. cannot find
:hp1.&4OS2.DLL.DLL:ehp1., a library used to support the BEGINLIBPATH and
ENDLIBPATH "environment variables" under OS/2 Warp.  :hp1.&4OS2.DLL.DLL:ehp1.
must be in the &4OS2. directory, or on a directory listed in the LIBPATH
setting in :hp1.CONFIG.SYS:ehp1..  If it is not, BEGINLIBPATH and ENDLIBPATH
will not be available, but all other &4OS2. functions will operate normally.
:p.
:hp2.Write error:ehp2.&colon.  OS/2 encountered a disk write error; usually
caused by a bad or unformatted disk.  Also see :hp2.Data error:ehp2. above.

.* --------------------------------------------------------------------------

:h2 name=Support.Troubleshooting, Service, and Support
:p.
If you need help with &4OS2., we encourage you to review our documentation and
then contact us for assistance if required.
:p.
If you need help with :hp2.sales:ehp2., :hp2.ordering:ehp2., or
:hp2.shipments:ehp2. (including defective disks or other materials which
were shipped to you), or with :hp2.brand codes:ehp2., please contact our
:hp2.Sales and Customer Service:ehp2. department.  See :link
reftype=hd refid=ContactJPS.Contacting JP Software:elink. for our email
address, mail address, and telephone numbers.
:p.
If you need :hp2.technical support:ehp2. for &4OS2., review the :link
reftype=hd refid=TechSup.Technical Support:elink. information
section, which tells you what we need to know to provide you with accurate
and timely support.  Then contact us via one of the methods described
there.  (The technical support staff cannot assist you with sales, ordering,
replacement brand cards, or other administrative matters.)

.* --------------------------------------------------------------------------

:h3 name=TechSup.Technical Support
:p.
:hp2.Before You Contact Us:ehp2.
:p.
Before contacting us for support, please check this help file, the Reference
Manual and other documentation for answers to your question.  If you can't
find what you need, try searching this help file.  If you're having trouble
getting &4OS2. to run properly, review the information on :link reftype=hd
refid=Errors.Error Messages:elink., and look through the
:hp1.README.TXT:ehp1. file for any last-minute information.
:p.
(If you need help with :hp2.sales:ehp2., :hp2.ordering:ehp2.,
:hp2.shipments:ehp2., :hp2.brand codes:ehp2., or other similar
non-technical issues please contact our :hp2.Sales and Customer
Service:ehp2. department.  See :link reftype=hd
refid=ContactJPS.Contacting JP Software:elink. for our addresses.)
:p.
If you do need to contact us for support, we can do a much better job of
assisting you if you can give us some basic information, separate from your
interpretations of or conclusions about the problem.  The first four items
listed below are essential for us to be able to understand and assist you
with your problem&colon.
:lm margin=4.:parml tsize=4 break=fit.
:pt.Ż:pd.:hp2.What environment are you working in?:ehp2.  This includes the
operating system version are you using, the version of the JP Software
product involved, and related information such as network connections and
the name and version number of any other software which appears to be
involved in the problem.  Use the :link reftype=hd refid=VER.VER:elink. /R
command to determine the &4OS2. version and operating system version.
:pt.Ż:pd.:hp2.What exactly did you do?:ehp2.  A concise description of what
steps you must take to make the problem appear is much more useful than a
long analysis of what might be happening.
:pt.Ż:pd.:hp2.What did you expect to happen?:ehp2.  Tell us the result you
expected from the command or operation in question, so that we understand
what you are trying to do.
:pt.Ż:pd.:hp2.What actually happened?:ehp2.  At what point did the failure
occur?  If you saw an error message or other important or unusual
information on the screen, what :hp2.exactly:ehp2. did it say?
:pt.Ż:pd.:hp2.Briefly, what techniques did you use to try to resolve the
problem?:ehp2. What results did you get?
:pt.Ż:pd.:hp2.If the problem seems related to startup and configuration
issues:ehp2., what are the contents of any startup files you use (such as
:link reftype=hd refid=AutoBatch.4START and 4EXIT:elink., and
:link reftype=hd refid=INIFile.&4OS2INI.:elink.), any batch files they call,
and any alias or environment variable files they load?
:pt.Ż:pd.:hp2.Can you repeat the problem or does it occur
randomly?:ehp2.  If it's random, does it seem related to the programs you're
using when the problem occurs?
:eparml.:lm margin=1.
:p.
:p.
:hp2.Online Support:ehp2.
:p.
Support for &4OS2. is offered via our online support forum, where our
support personnel can read and respond to your messages, and other users
can respond as well.  The forum is accessible via several methods; for
complete details and access links see the support area of our web site
at :hp2.http&colon.//www.jpsoft.com/:ehp2..
:p.
A number of other support resources are available from our web site,
including error message listings, documentation files, product
histories, technical tips and discussions, other technical
information, and links to other companies' sites.  We update this
information regularly, and we encourage you to check the Technical
Support area of the web site to see if the information there will
address any questions you have.
:p.
If you are unable to gain access to the forum, or you need to
include confidential information in your support request, contact us
via email at :hp2.support@jpsoft.com:ehp2. and we will assist you in
resolving the problem with forum access, or assist you with your request
privately if appropriate.  Please do not use this address for standard
support questions which can be posted on the forum.
:p.
Technical support messages should be sent as standard ASCII text.
Please do not transmit attached files, binary files, screen images,
or any file over 10K bytes in size to any of our electronic
technical support addresses unless asked to do so by our support
staff.

.* --------------------------------------------------------------------------

:h3 name=ContactJPS.Contacting JP Software
:p.
You can contact JP Software at the following addresses and numbers.  Our
normal business hours are 8&colon.30 AM to 5&colon.00 PM weekdays, eastern
US time (except holidays).
:p.
:lm margin=4.:parml tsize=18 compact break=fit.
:pt.Address&colon.:pd.JP Software Inc.
:pt.:pd.P.O. Box 1470
:pt.:pd.East Arlington, MA 02474
:pt.:pd.USA
.br
:pt.Main number&colon.:pd.(781) 646-3975
.br
:pt.Fax&colon.:pd.(781) 646-0904
.br
:pt.Order Line&colon.:pd.(800) 368-8777  (US / Canada, orders only)
.br
:pt.Email&colon.:pd.Sales / Customer Service&colon.  :hp2.sales@jpsoft.com:ehp2.
.br
:pt.:pd.Technical Support&colon.  Visit our support forum, accessible via
the support area of our web site at :hp2.http&colon.//www.jpsoft.com/:ehp2.
.br
:pt.:pd.World Wide Web&colon.  :hp2.http&colon.//www.jpsoft.com/:ehp2.
.br
:pt.:pd.Downloads via FTP&colon.  :hp2.ftp&colon.//ftp.jpsoft.com/:ehp2.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h1 name=WhatsNew.What's New?
:p.
This section provides a comprehensive list of what's changed since our
previous major release, version 2.52.  Maintenance changes made between
versions 3.00 and &4ver. are indicated notes in the left margin (such as
:hp2.&4ver.:ehp2.).
:p.
This topic does not explain how to use each new feature.  Instead, where
appropriate we have provided links below to the detailed help topics
containing additional usage information or other documentation.
:p.
Some of the descriptions here may be more detailed than you need; if you
aren't using a feature, feel free to skip to the next item.  If you are new
to &4OS2. with version &4ver., you can skip this topic entirely.
:p.
This topic is divided into the following subtopics&colon.
:lm margin=8.:parml tsize=4 compact break=fit.
:pt.:pd.:link reftype=hd refid=NewGen.General Features and Enhancements:elink.
:pt.:pd.:link reftype=hd refid=NewCmdLine.Line Editing and History:elink.
:pt.:pd.:link reftype=hd refid=NewCommands.Command Changes:elink.
:pt.:pd.:link reftype=hd refid=NewVars.Variables and Variable Functions:elink.
:pt.:pd.:link reftype=hd refid=NewStartup.Startup and Configuration:elink.
:pt.:pd.:link reftype=hd refid=NewCompat.Technical and Compatibility
Enhancements:elink.
:pt.:pd.:link reftype=hd refid=NewBugs.Bugs Fixed:elink.
:eparml.:lm margin=1.
:p.
The major new features in this release include&colon.
:lm margin=4.:parml tsize=4 break=fit.
:pt.Ż:pd.:link reftype=hd refid=ExtDirSearch.Extended Directory
Searches:elink.&colon.  allow you to change to a directory anywhere on your
system by entering only part of its name.  They must be explicitly enabled
before you can use them.  See :link reftype=hd refid=DirNav.Directory
Navigation:elink. for complete details.
:pt.Ż:pd.New :link reftype=hd refid=ExclRanges.File Exclusion
Ranges:elink.&colon. provide a convenient way to exclude files from any
internal command -- faster and more flexible than using EXCEPT.
:pt.Ż:pd.The new :link reftype=hd refid=BatchDebug.Batch File
Debugger:elink. can execute each line step by step, process or trace into
additional batch files, and display variables, aliases, and expanded commands
at each step.
:pt.Ż:pd.:hp2.New commands:ehp2. include&colon.
:parml tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=OPTION.OPTION:elink.&colon.  Offers
complete configuration adjustment, either through interactive dialogs or on
the command line.
:pt.:pd.:link reftype=hd refid=SWITCH.SWITCH:elink.&colon.  Provides
for "case" statements in batch files.
:pt.:pd.:link reftype=hd refid=TOUCH.TOUCH:elink.&colon.  Adjusts file
dates and times.
:pt.:pd.:link reftype=hd refid=TREE.TREE:elink.&colon.  Displays the
directory tree, with or without file names, in a variety of formats.
:eparml.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=NewGen.General Features and Enhancements
:p.
:hp2.What's New - General Features and Enhancements:ehp2.
:lm margin=8.:parml tsize=3 break=fit.
:pt.Ż:pd.Added a complete batch file debugger.  The debugger displays the
batch file in a window and allows you to execute each line step by step,
process or trace into additional batch files and subroutines, and display
variables and aliases at each step.  See :link reftype=hd
refid=BatchDebug.Batch File Debugging:elink. for complete details.
:pt.Ż:pd.:link reftype=hd refid=Popup.Popup windows:elink. (for filename
completion, command history recall, etc.) now allow you to search for
a line within the window contents by typing the first few characters of the
line.  The search string is displayed in the lower right corner of the window.
:pt.Ż:pd.You can now :link reftype=hd refid=Redirection.redirect:elink. to
and from the clipboard by using the pseudo-device name CLIP&colon..  For
example, to redirect DIR to the clipboard&colon.
:xmp.
        dir *.doc > clip&colon.
:exmp.
:pt.Ż:pd.The :link reftype=hd refid=HelpSys.online help:elink. has
been reorganized to make it easier to navigate through the main topics, and
includes additional reference information, reference tables, and a
glossary.
:pt.Ż:pd.The default maximum :link reftype=hd refid=DESCRIBE.file
description:elink. length is now 511 bytes in all products.
:pt.Ż:pd.Two new characters can now follow the :link reftype=hd
refid=Escape.escape character:elink.&colon.  An escape followed by
a 'q' will substitute a double quote; an escape followed by a 'k' will
substitute a back quote.
:pt.Ż:pd.The decimal and thousands characters used in :link reftype=hd
refid=_@EVAL.@EVAL:elink. and in displayed version numbers and other similar
locations are now controllable with the :link reftype=hd
refid=INI_DecimalChar.DecimalChar:elink. and :link reftype=hd
refid=INI_ThousandsChar.ThousandsChar:elink. directives in the
:hp1..INI:ehp1. file, the corresponding options in the configuration or
OPTION dialogs, and the SETDOS /G command.  These characters are saved by
SETLOCAL and restored by ENDLOCAL.  This is intended as an aid to those
writing batch files which perform arithmetic operations and which may be
used in countries with differing separator characters.
:pt.Ż:pd.The directory stack size used by :link reftype=hd
refid=PUSHD.PUSHD:elink. and :link reftype=hd refid=POPD.POPD:elink. has
been increased from 255 to 511 bytes to leave adequate room for long
directory names.
:pt.Ż:pd.:hp1..BTM:ehp1. files can now be longer than 64K bytes, though
compressed :hp1..BTMs:ehp1. still have to be less than 64K.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=NewCmdLine.Command Line Editing
:p.
:hp2.What's New - Command Line Editing:ehp2.
:lm margin=8.:parml tsize=3 break=fit.
:pt.Ż:pd.:link reftype=hd refid=ExtDirSearch.Extended directory
searches:elink. can be used directly from the command line for quick
directory navigation; see :link reftype=hd refid=AutoDir.Automatic Directory
Changes:elink. or :link reftype=hd refid=DirNav.Directory Navigation:elink.
for details.
:pt.Ż:pd.Made several ehancements to :link reftype=hd
refid=FileComp.filename completion:elink., including&colon.
:parml tsize=4 break=fit.
:pt.*:pd.The Ctrl-A key, which toggles between long and short
filenames for filename completion, can now be hit at any point during command
line entry -- not just during filename completion.  For example, if you hit
Ctrl-A at the beginning of the command line, all filenames subsequently
returned for that line will be short names (until you hit Ctrl-A again).
:pt.*:pd.Filename completion can now be customized for individual commands
via the new :link reftype=hd refid=INI_FileCompletion.FileCompletion:elink.
:hp1..INI:ehp1. directive (or environment variable).  For example, you can
configure &4OS2. to complete only the names of :hp1..TXT:ehp1. files when the
command line starts with the name of your text editor, or to display only
directory names when you are entering a CD command.
:pt.*:pd.The F7 filename completion popup window now sorts the filename list
alphabetically.
:eparml.
:pt.Ż:pd.You can now expand aliases immediately while still on the command
line with the Ctrl-F key.
:pt.Ż:pd.Command line :link reftype=hd refid=CmdHist.history recall:elink.
will now stop at the beginning and end of the history list rather than
wrapping around, if you set HistWrap to No in the :hp1..INI:ehp1. file or
through the configuration dialogs.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=NewCommands.Command Changes
:p.
:hp2.What's New - Command Changes:ehp2.
:lm margin=8.:parml tsize=3 break=fit.
:pt.Ż:pd.:link reftype=hd refid=ACTIVATE.ACTIVATE:elink.&colon.  This
new command switches to another window.
:pt.Ż:pd.:link reftype=hd refid=ATTRIB.ATTRIB:elink.&colon.  Added the /E
switch to disable display of non-fatal errors.  Also, ATTRIB now allows
underscores in the attribute string, so that you can get a result from the
%:link reftype=hd refid=_@ATTRIB.@ATTRIB:elink. variable function and feed
it directly to the ATTRIB command.
:pt.Ż:pd.:link reftype=hd refid=CD.CD:elink. and :link reftype=hd
refid=CDD.CDD:elink.&colon.  Now support extended directory searches, which
allow you to change to a directory anywhere on your system by entering only
part of its name.  The CDD /S switch builds the extended directory search
database.  Extended directory searches mmust be explicitly enabled before
you can use them.  See :link reftype=hd refid=DirNav.Directory
Navigation:elink. for complete details.
:pt.Ż:pd.:link reftype=hd refid=CDD.CDD:elink.&colon.  Added the /A switch to
display the current directory for all existing and ready drives from
C&colon. to Z&colon..
:pt.Ż:pd.:link reftype=hd refid=CHCP.CHCP:elink.&colon.  Changed to only affect
the current process and its children, as in :hp1.CMD.EXE:ehp1..
:pt.Ż:pd.:link reftype=hd refid=COPY.COPY:elink.&colon.  Added several
switches&colon.
:parml tsize=8 compact break=fit.
:pt.    /E:pd.Disable display of non-fatal errors.
:pt.    /K:pd.Preserve read-only attributes during a COPY.
:pt.    /X:pd.Clear the archive bit from the source file after a successful
copy.
:pt.    /Z:pd.Overwrite read-only target files.
:eparml.
:pt.Ż:pd.:link reftype=hd refid=COPY.COPY:elink.&colon.  When copying from a
FAT drive to an HPFS drive, COPY will now use the .LONGNAME extended
attribute of the source file (if available) to determine the long name.  When
copying from HPFS to FAT, COPY sets the .LONGNAME attribute if possible, to
preserve the long name.
:pt.Ż:pd.:link reftype=hd refid=DEL.DEL:elink.&colon.  Added two
switches&colon.
:parml tsize=8 compact break=fit.
:pt.    /E:pd.Disable display of non-fatal errors.
:pt.    /W:pd.Clear the file to 0's before deleting it.
:eparml.
:pt.Ż:pd.:link reftype=hd refid=DIR.DIR:elink.&colon.  Added or modified
several of the DIR switches&colon.
:parml tsize=8 compact break=fit.
:pt.    /2:pd.Now forces the use of truncated names on HPFS drives.
:pt.    /4:pd.Now forces the use of truncated names on HPFS drives, and displays
files between 1 and 9.9 Mb in tenths (i.e., "2.4M").
:pt.    /G:pd.(New) Displays the allocated size instead of the file size.
:pt.    /W:pd.Now forces the use of truncated names on HPFS drives.
:eparml.
:pt.Ż:pd.:link reftype=hd refid=DIRHISTORY.DIRHISTORY:elink.&colon.  This new
command has the same syntax as HISTORY, but it modifies the directory
history.
:pt.Ż:pd.:link reftype=hd refid=DO.DO:elink.&colon.  Added two new DO loop
types&colon.
:parml tsize=4 compact break=fit.
:pt.*:pd."DO x IN filename" retrieves each matching filename from a
wildcard spec and inserts the value into the variable.
:pt.*:pd."DO x IN @filename" retrieves each line in the file and inserts it
into the variable.
:eparml.
:pt.Ż:pd.:link reftype=hd refid=ECHO.ECHOERR:elink. and :link reftype=hd
refid=ECHOS.ECHOSERR:elink.&colon.  These new commands are like ECHO
and ECHOS, but output goes to the standard error device instead of standard
output.
:pt.Ż:pd.:link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink.&colon.  To aid in
making batch files portable, SETLOCAL and ENDLOCAL now save and restore the
command separator, escape character, parameter character, and decimal and
thousands separators.
:pt.Ż:pd.:link reftype=hd refid=FFIND.FFIND:elink.&colon.  Added two new
switches&colon.
:parml tsize=8 compact break=fit.
:pt.    /I:pd.Do a literal match even if the text search string contains
wildcard characters.
:pt.    /R:pd.Start searching for text from the end backwards.
:eparml.
:p.
Also, the /X switch will now display the offset in both hex and decimal.
:pt.Ż:pd.:link reftype=hd refid=FOR.FOR:elink.&colon.  Added several new
switches for compatibility with Windows NT 4.0's CMD.EXE; see the command
reference information for complete details.
:pt.Ż:pd.:link reftype=hd refid=GOTO.GOTO:elink.&colon.  Added support for
Windows NT 4.0's "GOTO &colon.EOF" -- If there is no "&colon.EOF" label,
GOTO ends the current batch file (equivalent to a QUIT).
:pt.Ż:pd.:link reftype=hd refid=IF.IF:elink. / :link reftype=hd
refid=IFF.IFF:elink.&colon.  These commands now support nested conditional
tests, with parentheses, e.g.&colon.
:xmp.
        if  (%a == 1 .or. %b == 2) .and. %c == 3 echo something
:exmp.:p.
See the command reference information for complete syntax rules.
:pt.Ż:pd.Added a new "IF DEFINED varname" test, which succeeds if the
specified variable exists in the environment.  This is included for
compatibility with Windows NT 4.0's CMD.EXE, and is the same as a test
like&colon.
:xmp.
        if  "%varname" ne "" ...
:exmp.
:pt.Ż:pd.Changed the comparison tests to accept a leading decimal separator
as a numeric character, provided the remainder of the string is numeric and
does not contain additional decimal characters.
:pt.Ż:pd.:link reftype=hd refid=KEYSTACK.KEYSTACK:elink.&colon.  This new
command allows you to pass keystrokes to PM and VIO windowed applications
(but not to DOS apps or VIO full-screen sessions).
:pt.Ż:pd.:link reftype=hd refid=LIST.LIST:elink.&colon.  Added a range of
enhancements, including&colon.
:parml tsize=4 break=fit.
:pt.*:pd.Ctrl-PgUp and Ctrl-PgDn will go to the previous and next
file in the current group, respectively.
:pt.*:pd.Ctrl-F searches backwards for a text string; Ctrl-N repeats the
last search, searching backwards.
:pt.*:pd.Matching strings on the first page are now highlighted after a search.
:pt.*:pd.When piping output to LIST in most cases you no longer need the /S
switch; for example, to view DIR's output in LIST you can now use&colon.
:xmp.
        dir  | list
:exmp.:p.
Also, added three new switches&colon.
:parml tsize=8 compact break=fit.
:pt.    /I:pd.Ignore case in a /T search.
:pt.    /R:pd.The search initiated by /T goes backwards from the end of the file.
:pt.    /T:pd.Search for text when LIST starts.
:eparml.:eparml.
:pt.Ż:pd.:link reftype=hd refid=MD.MD:elink.&colon.  Added the /N switch to
create a directory without updating the extended directory search database
(useful for temporary directories).
:pt.Ż:pd.:link reftype=hd refid=MOVE.MOVE:elink.&colon.  Added the /E switch
to disable display of non-fatal errors.
:pt.Ż:pd.:link reftype=hd refid=MOVE.MOVE:elink.&colon.  When moving files
from a FAT drive to an HPFS drive, MOVE will now use the .LONGNAME extended
attribute of the source file (if available) to determine the long name.  When
moving files from HPFS to FAT, MOVE sets the .LONGNAME attribute if possible,
to preserve the long name.
:pt.Ż:pd.:link reftype=hd refid=OPTION.OPTION:elink.&colon.  This new command
can be used for two purposes.  When invoked without parameters, it loads
configuration dialogs which adjust most commonly-used settings in the
:hp1..INI:ehp1. file.  The dialogs provide a convenient method of adjusting
configuration without manually editing the :hp1..INI:ehp1. file.  OPTION can
also be used to change specific settings on an individual basis with the
OPTION Name=value ... syntax; see the command for complete details.
:pt.Ż:pd.:link reftype=hd refid=PROMPT.PROMPT:elink.&colon.  Added the
:hp2.$+:ehp2. metacharacter, which displays one :hp2.+:ehp2. for each PUSHD
level.
:pt.Ż:pd.:link reftype=hd refid=REN.REN / RENAME:elink.&colon.  Added the /E
switch to disable display of non-fatal errors.
:pt.Ż:pd.:link reftype=hd refid=RETURN.RETURN:elink.&colon.  Now accepts an
optional argument for the errorlevel to return.  The errorlevel can be tested
with %:link reftype=hd refid=_QMARK.?:elink. or :link reftype=hd
refid=IF.IF:elink. ERRORLEVEL.
:pt.Ż:pd.:link reftype=hd refid=SCREEN.SCREEN:elink., :link reftype=hd
refid=SCRPUT.SCRPUT:elink., and :link reftype=hd
refid=VSCRPUT.VSCRPUT:elink.&colon.  If you specify 999 for the row, the
text will be centered vertically; if you specify 999 for the column, the
text will be centered horizontally.
:pt.Ż:pd.:link reftype=hd refid=SELECT.SELECT:elink.&colon.  You can now type
characters from the start of a filename and the selection bar will jump to
the first matching name.  Due to this change, the key to popup :link
reftype=hd refid=LIST.LIST:elink. on the currently selected file has been
changed from L to ^L.  Also, added the /T&colon.acw switch to select the
date and time to use for display and sorting on HPFS drives.
:pt.Ż:pd.:link reftype=hd refid=SETLOCAL.SETLOCAL:elink.&colon.  To aid in
making batch files portable, SETLOCAL now saves the command separator, escape
character, parameter character, and decimal and thousands separators;
:link reftype=hd refid=ENDLOCAL.ENDLOCAL:elink. restores them.
:pt.Ż:pd.:link reftype=hd refid=SHIFT.SHIFT:elink.&colon.  The new "/n"
argument will start the shift at the specified argument -- i.e., "shift /2"
moves %3 to %2, %4 to %3, etc.
:pt.Ż:pd.:link reftype=hd refid=START.START:elink.&colon.  Added /LD for a
local directory history list.
:pt.Ż:pd.:link reftype=hd refid=START.START:elink.&colon.  Added support for
the (undocumented) Warp 4 CMD.EXE "DosSetting.xxx=yyy" environment variables
to specify settings for DOS sessions.
:pt.Ż:pd.:link reftype=hd refid=SWITCH.SWITCH:elink.&colon.  This new command
provides a C-like switch construct for batch files.  SWITCH scans each CASE
statement looking for a matching value; if it finds one it executes the block
of code inside that CASE statement, and then jumps to the end of the switch
block (ENDSWITCH).  If no CASE statement matches, SWITCH will execute the
code in the (optional) DEFAULT block.
:pt.Ż:pd.:link reftype=hd refid=TITLE.TITLE:elink.&colon.  This new command
changes the &4OS2. window title for windowed sessions (it is not effective in
full-screen sessions).
:pt.Ż:pd.:link reftype=hd refid=TOUCH.TOUCH:elink.&colon.  This new command
changes the date and/or time for a file or files.  You can set a specified
date and time or use the current system clock, and you can optionally change
the last access / creation date and time fields on HPFS drives.
:pt.Ż:pd.:link reftype=hd refid=TREE.TREE:elink.&colon.  This new command
displays a graphical directory tree using either line-drawing or ASCII
characters.  It can also optionally display file names, dates, times, and
sizes.
:pt.Ż:pd.:link reftype=hd refid=UNALIAS.UNALIAS:elink.&colon.  Added the /R
switch to read a file of aliases to remove.
:pt.Ż:pd.:link reftype=hd refid=UNSET.UNSET:elink.&colon.  Added the /R
switch to read a file of variables to remove.
:eparml.
:lm margin=1.:parml tsize=10 break=fit.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=FFIND.FFIND:elink.&colon.  Added support for
piping into FFIND.  You can either specify CON for the filename, or if no
filename is specified FFIND will detect whether STDIN is a pipe and use that.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=TOUCH.TOUCH:elink.&colon.  /T[acw] and
/D[acw] now default to the current date and time.  Previously when the "a",
"c", or "w" was specified the date or time had to be specified also.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=CD.CD:elink. and
:link reftype=hd refid=CDD.CDD:elink.&colon.  Added the :hp2./N:ehp2.
switch to disable extended directory searches and the change directory
popup window (intended primarily for use in batch files).
:eparml.

.* --------------------------------------------------------------------------

:h2 name=NewVars.Variables and Functions
:p.
:hp2.What's New - Variables and Functions:ehp2.
Added or updated the following internal variables (all variables listed are
new unless otherwise noted)&colon.
:lm margin=8.:parml tsize=3 break=fit.
:pt.Ż:pd.:link reftype=hd refid=_APMAC._APMAC:elink.&colon.  Advanced Power
Management AC line status.
:pt.Ż:pd.:link reftype=hd refid=_APMBATT._APMBATT:elink.&colon.  Advanced
Power Management battery status.
:pt.Ż:pd.:link reftype=hd refid=_APMLIFE._APMLIFE:elink.&colon.  Advanced
Power Management remaining battery life.
:pt.Ż:pd.:link reftype=hd refid=_CPU._CPU:elink.&colon.  Now returns "686"
for Pentium Pro.
:pt.Ż:pd.:link reftype=hd refid=_DOWI._DOWI:elink.&colon.  Returns the
current day of week as an integer (Sun = 1, Mon = 2, etc.).
:pt.Ż:pd.:link reftype=hd refid=_XPIXELS._XPIXELS:elink.&colon.  Returns the
physical screen horizontal size in pixels.
:pt.Ż:pd.:link reftype=hd refid=_YPIXELS._YPIXELS:elink.&colon.  Returns the
physical screen vertical size in pixels.
:eparml.:lm margin=1.
:lm margin=1.:parml tsize=10 break=fit.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=_CMDPROC._CMDPROC:elink.&colon.  Returns
the name of the current command processor.
:eparml.
:p.
:p.
Added or updated the following variable functions (all functions listed are
new unless otherwise noted)&colon.
:lm margin=8.:parml tsize=3 break=fit.
:pt.Ż:pd.:link reftype=hd refid=_@CLIP.@CLIP:elink.[n]&colon.  Returns line
:hp2.n:ehp2. from the clipboard (base 0).
:pt.Ż:pd.:link reftype=hd
refid=_@CONVERT.@CONVERT:elink.[input,output,value]&colon.  Converts a
number from one base to another.
:pt.Ż:pd.:link reftype=hd refid=_@DAY.@DAY:elink.[date]&colon.  Returns the
day for the specified :hp2.date:ehp2..
:pt.Ż:pd.:link reftype=hd refid=_@DOW.@DOW:elink.[date]&colon.  Returns the
day of week for the specified :hp2.date:ehp2., as a string (Sun, Mon, etc.)
:pt.Ż:pd.:link reftype=hd refid=_@DOWI.@DOWI:elink.[date]&colon.  Returns the
day of week for the specified :hp2.date:ehp2., as an integer (Sun = 1, Mon = 2, etc.).
:pt.Ż:pd.:link reftype=hd refid=_@DOY.@DOY:elink.[date]&colon.  Returns the
day of year for the specified :hp2.date:ehp2. (136).
:pt.Ż:pd.:link reftype=hd
refid=_@EAREAD.@EAREAD:elink.[filename,EAname]&colon.  Returns the specified
text extended attribute for the file.
:pt.Ż:pd.:link reftype=hd
refid=_@EAWRITE.@EAWRITE:elink.[filename,EAname,[value]]&colon.  Writes the
specified text extended attribute for the file.
:pt.Ż:pd.:link reftype=hd refid=_@EVAL.@EVAL:elink.[expression]&colon.  Now
supports user-definable decimal and thousands characters; see :link reftype=hd
refid=INI_DecimalChar.DecimalChar:elink. and :link reftype=hd
refid=INI_ThousandsChar.ThousandsChar:elink., or :link reftype=hd
refid=SETDOS.SETDOS:elink. /G for details.
:pt.Ż:pd.:link reftype=hd refid=_@EXEC.@EXEC:elink.[command]&colon.  This
function has been modified; if you preface the :hp2.command:ehp2. with an '@', @EXEC
will return an empty string rather than the result code of the command.
:pt.Ż:pd.:link reftype=hd refid=_@EXECSTR.@EXECSTR:elink.[command]&colon.  Returns
the first line written to STDOUT by the specified command.  (This is
intended to provide functionality similar to UNIX back-quoting.)
:pt.Ż:pd.:link reftype=hd
refid=_@EXPAND.@EXPAND:elink.[filename[,attributes]]&colon.  Expands a
wildcard filename and returns all of the matching filenames / directories on
a single line.
:pt.Ż:pd.:link reftype=hd refid=_@FILEDATE.@FILEDATE:elink.[filename[,acw]]
/ :link reftype=hd
refid=_@FILETIME.@FILETIME:elink.[filename[,acw]]&colon.  Added
the optional second argument determines which date / time field to return on
HPFS drives.
:pt.Ż:pd.:link reftype=hd
refid=_@FILESIZE.@FILESIZE:elink.[filename[,bkm[,a]]&colon.  Added the
optional third argument :hp2.a:ehp2.(llocated); if specified, the function
returns the size actually used on disk, not the amount of data in the file.
:pt.Ż:pd.:link reftype=hd
refid=_@INSERT.@INSERT:elink.[n,string1,string2]&colon.  Inserts
:hp2.string1:ehp2. into :hp2.string2:ehp2. starting at offset :hp2.n:ehp2..
:pt.Ż:pd.:link reftype=hd refid=_@LEFT.@LEFT:elink.[n,string]&colon.  Returns
the leftmost :hp2.n:ehp2. characters of :hp2.string:ehp2..
:pt.Ż:pd.:link reftype=hd refid=_@MONTH.@MONTH:elink.[date]&colon.  Return
the month for the specified :hp2.date:ehp2..
:pt.Ż:pd.:link reftype=hd refid=_@NUMERIC.@NUMERIC:elink.[string]&colon.  Now
considers a leading decimal separator as a numeric character, provided the
remainder of the :hp2.string:ehp2. is numeric and does not contain
additional decimal characters.
:pt.Ż:pd.:link reftype=hd
refid=_@REPLACE.@REPLACE:elink.[string1,string2,text]&colon.  Replaces all
occurrences of :hp2.string1:ehp2. in text with :hp2.string2:ehp2..
:pt.Ż:pd.:link reftype=hd refid=_@RIGHT.@RIGHT:elink.[n,string]&colon.  Returns
the rightmost :hp2.n:ehp2. characters of :hp2.string:ehp2..
:pt.Ż:pd.:link reftype=hd
refid=_@SEARCH.@SEARCH:elink.[filename[,path]]&colon.  Now accepts an
optional second argument for the :hp2.path:ehp2. to search.
:pt.Ż:pd.:link reftype=hd
refid=_@SELECT.@SELECT:elink.[filename,top,left,bottom,right,title[,1]]&colon.  Has
a new optional argument following the :hp2.title:ehp2..  If it's set to 1, @SELECT will
sort the list alphabetically.
:pt.Ż:pd.:link reftype=hd refid=_@STRIP.@STRIP:elink.[chars,string]&colon.  Return
:hp2.string:ehp2. with the characters in :hp2.chars:ehp2. removed.
:pt.Ż:pd.:link reftype=hd refid=_@WILD.@WILD:elink.[string1,string2]&colon.  Does
a wildcard comparison on the two strings and returns 1 if they match; 0 if
they don't.
:pt.Ż:pd.:link reftype=hd refid=_@YEAR.@YEAR:elink.[date]&colon.  Return the
year for the specified :hp2.date:ehp2..
:eparml.
:lm margin=1.:parml tsize=10 break=fit.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=_@EAWRITE.@EAWRITE:elink.[filename,EAname,[value]]&colon.
You can now delete an EA by specifying an empty third argument (i.e.,
"%@earead[filename,.subject,]).
:eparml.

.* --------------------------------------------------------------------------

:h2 name=NewStartup.Startup and Configuration
:p.
:hp2.What's New - Startup and Configuration:ehp2.
:lm margin=8.:parml tsize=3 break=fit.
:pt.Ż:pd.In previous versions the "global" portion of the :link reftype=hd
refid=INIFile..INI file:elink. (the part prior to any [Primary] or
[Secondary] section) did not have a section name.  This has been changed; a
section name matching the product name is now required, for example&colon.
:xmp.
        [&4OS2.]
        EditMode  = Insert
        .....
:exmp.:p.
[Primary] and [Secondary] section names are still supported as well.
:p.
:pt.Added or modified the following :hp1..INI:ehp1. directives (all are new
unless otherwise noted)&colon.
:pt.Ż:pd.:link reftype=hd refid=INI_CDDWinLeft.CDDWinLeft, CDDWinTop,
CDDWinWidth, CDDWinHeight:elink., and :link reftype=hd
refid=INI_CDDWinColors.CDDWinColors:elink.&colon.  These directives set the
position, size, and color of the popup window used for
:link reftype=hd refid=ExtDirSearch.extended directory searches:elink..
:pt.Ż:pd.:link reftype=hd
refid=INI_DescriptionName.DescriptionName:elink.&colon.  This directive has
a new capability&colon.  If set to "EA", &4OS2. will use extended attributes
(specifically, the ".SUBJECT" EA) for file descriptions, rather than
:hp1.DESCRIPT.ION:ehp1. or another file.  Depending on operating system
configuration and cache behavior, this setting can cause a significant
reduction in performance, but may be useful when working with other programs
that manipulate Extended Attributes.
:pt.Ż:pd.:link reftype=hd refid=INI_DuplicateBugs.DuplicateBugs:elink. = Yes
| NO&colon.  Tells the parser to duplicate certain :hp1.CMD.EXE:ehp1. errors
which may be important in solving rare compatibility problems.  The only bug
currently replicated by this command is the :link reftype=hd
refid=IF.IF:elink. command.
:pt.Ż:pd.:link reftype=hd refid=INI_FileCompletion.FileCompletion:elink. =
cmd1&colon.ext1 ext2;cmd2 ...&colon.  Sets up command-specific :link
reftype=hd refid=FileComp.filename completion:elink..
:pt.Ż:pd.:link reftype=hd refid=INI_FuzzyCD.FuzzyCD:elink. =  0 | 1 | 2 |
3:  Enables or disables :link reftype=hd refid=ExtDirSearch.extended
directory searches:elink., and controls their behavior.
:pt.Ż:pd.:link reftype=hd refid=INI_HistMove.HistMove:elink. = Yes |
NO&colon.  If set to Yes, a recalled line from the command history is moved
to the end of the history list, and removed from its original location.
:pt.Ż:pd.:link reftype=hd refid=INI_Include.Include:elink. =
filename&colon.  Includes the contents of the named file as if they had
appeared at the location of the Include= directive in the current
:hp1..INI:ehp1. file.
:pt.Ż:pd.:link reftype=hd refid=INI_ListboxBarColors.ListboxBarColors:elink. =
Color&colon.  Sets the color for the highlight bar in the popup
listboxes (command history, filename completion, @SELECT, etc.).
:pt.Ż:pd.:link reftype=hd refid=INI_TabStops.TabStops:elink. = nnnn
(8)&colon.  This new :hp1..INI:ehp1. directive specifies the tab expansion
size when displaying a file in LIST.
:pt.Ż:pd.:link reftype=hd refid=INI_TreePath.TreePath:elink. =
Path&colon.  Specifies the location of :hp1.JPSTREE.IDX:ehp1. (the :link
reftype=hd refid=ExtDirSearch.extended directory search:elink. database;
defaults to C&colon.\).
:eparml.
:lm margin=1.:parml tsize=10 break=fit.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd
refid=INI_ListRowStart.ListRowStart:elink.  = 1 &splitvbar.  0&colon.  Specifies
whether :link reftype=hd refid=LIST.LIST:elink. and :link reftype=hd
refid=FFIND.FFIND:elink. consider the first line in a file to be line
"1" or line "0".  The new default is "1".
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=INI_PathExt.PathExt:elink.  =
NO &splitvbar.  Yes&colon.  Determines whether &4OS2. uses standard
extensions when searching the path, or uses the alternate extensions
specified in the :link reftype=hd refid=PATHEXT.PATHEXT:elink. environment
variable.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=INI_UnixPaths.UnixPaths:elink.=
Yes &splitvbar.  NO&colon.  Enables or disables the forward slash as a
path separator in the command name (the first item on the command line).
:eparml.

.* --------------------------------------------------------------------------

:h2 name=NewCompat.Technical and Compatibility Enhancements
:p.
:hp2.What's New - Technical and Compatibility Enhancements:ehp2.
:lm margin=8.:parml tsize=3 break=fit.
:pt.Ż:pd.Removed the 16-bit version of &4OS2..
:pt.Ż:pd.Replaced the old &4OS2.DLL.DLL / TCOS2DLL.DLL with a single file for
both &4OS2. and TCOS2, named JPOS2DLL.DLL.  Also, JPOS2DLL is now loaded
dynamically, so you can start the product without it if necessary (e.g. from
a floppy boot).
:pt.Ż:pd.Worked around an OS/2 problem that prevented %:link reftype=hd
refid=_CPU._CPU:elink. from detecting anything higher than a 486.
:pt.Ż:pd.Updated &4OS2. to remove explicit references to the Presentation
Manager DLLs (this should make it easier to use &4OS2. from a floppy disk boot).
:pt.Ż:pd.:link reftype=hd refid=TYPE.TYPE:elink. NUL now "works" (i.e. it
generates no output), for compatibility with batch files which use TYPE NUL >
file to generate a 0-byte file.
:pt.Ż:pd.Added debugging options which allow you to view the command "tail"
passed to &4OS2., and to "tag" error messages with the product name.  See the
:link reftype=hd refid=INI_Debug.Debug:elink. directive in
:link reftype=hd refid=INIFile.&4OS2INI.:elink. for additional details.
:eparml.
:lm margin=1.:parml tsize=10 break=fit.
:pt.:hp2.3.01:ehp2.  Ż:pd.Worked around an OS/2 API problem that was causing
some batch files (particularly those with loops and lots of internal
commands) to run very slowly.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=_@UNIQUE.@UNIQUE:elink.&colon.  Worked
around an OS/2 bug that caused trouble if @UNIQUE was called repeatedly on a
fast machine.
:eparml.

.* --------------------------------------------------------------------------

:h2 name=NewBugs.Bugs Fixed
:p.
:hp2.What's New - Bugs Fixed:ehp2.

:lm margin=8.:parml tsize=3 break=fit.
:pt.Ż:pd.:link reftype=hd refid=Piping.Piping:elink. the output of a batch
file which also contains a pipe will no longer cause problems.
:pt.Ż:pd.:link reftype=hd refid=ACTIVATE.ACTIVATE:elink.&colon.  The CLOSE
option now works properly.
:pt.Ż:pd.:link reftype=hd refid=DESCRIBE.DESCRIBE:elink.&colon.  Fixed a
problem with quoted long filenames with paths.
:pt.Ż:pd.:link reftype=hd refid=REN.RENAME:elink.&colon.  Now works
properly when renaming quoted long filenames with embedded wildcards.
:pt.Ż:pd.Fixed a problem with invalid drive change requests -- commands
like "1&colon." would crash &4OS2..
:pt.Ż:pd.Quoted long filenames can now be used in the :link reftype=hd
refid=INIFile..INI file:elink..
:pt.Ż:pd.:link reftype=hd refid=_@FILESEEKL.@FILESEEKL:elink.[] now always
returns to the start of the file before seeking.
:eparml.
:lm margin=1.:parml tsize=10 break=fit.
:pt.:hp2.3.01:ehp2.  Ż:pd.Enabled the :link reftype=hd
refid=INI_NormalPopupKey.NormalPopupKey:elink. directive in the .INI
file.  Previously this directive was documented but was only available under
its old name (NormalHWinKey).
:pt.:hp2.3.01:ehp2.  Ż:pd.Fixed a problem which caused spurious "nesting level" errors when
the :link reftype=hd refid=INI_Include.Include:elink. directive was used
more than three times in the :hp1..INI:ehp1. file.
:pt.:hp2.3.01:ehp2.  Ż:pd.Modified popup windows to avoid the situation where the bottom half
of the window is empty when the initially selected line is at the end of the
list.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=CHCP.CHCP:elink.&colon.  Fixed
a problem with not redisplaying existing special characters on the screen.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=DETACH.DETACH:elink.&colon.  Fixed a problem
with not expanding variables before running an external program.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=DEL.DEL:elink.&colon.  Fixed
a problem with /W and 0-byte files.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=DIR.DIR:elink.&colon.  Fixed several
problems, including:
:parml tsize=4 break=fit.
:pt.*:pd./4/Z did not display file sizes ending in ".9M" (1.9M, 2.9M, etc.)
correctly.
:pt.*:pd./J did not display the descriptions.
:pt.*:pd./OGU was ignoring the 'U'; it will now display the files unsorted
after the directory names.
:pt.*:pd."*.*" was incorrectly being appended to file specifications that
ended in a question mark.
:eparml.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=DIR.DIR:elink.&colon.  No longer appends a
".*" to filenames entered on the command line without an extension (to match
CMD.EXE's behavior).
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=DO.DO:elink.&colon.  Fixed a problem with
"LEAVE" not closing the file handle on a "do var in @filename", and a
similar problem with exiting the batch file with :link reftype=hd
refid=QUIT.QUIT:elink. or :link reftype=hd refid=CANCEL.CANCEL:elink. from
inside a DO loop which had a file open.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=DRAWVLINE.DRAWVLINE:elink.&colon.  Fixed a
problem with connecting to a horizontal line on the right side.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=ECHOS.ECHOS:elink.&colon.  Fixed a problem
with aborting an ECHOS with a Ctrl-C while in a :link reftype=hd
refid=DO.DO:elink. or :link reftype=hd refid=FOR.FOR:elink. loop.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=FOR.FOR:elink.&colon.  Fixed a problem with
combining /A&colon.xx and /R, and another problem with combining /H and /R.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=SELECT.SELECT:elink.&colon.  Fixed a problem
with incorrectly adding quotes to short filenames on long filename drives if
they contained a drive spec.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=SWITCH.SWITCH:elink.&colon.  Fixed
occasional problems with nested SWITCHes.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=_PIPE._PIPE:elink.&colon.  Fixed a problem
with this variable not always returning 1 when inside a pipe.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=_@EAREAD.@EAREAD:elink. and
:link reftype=hd refid=_@EAWRITE.@EAWRITE:elink.&colon.  Fixed a problem
with long filenames.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=_@EVAL.@EVAL:elink.&colon.  Fixed a bug with
maximum-length argument strings.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=_@EXPAND.@EXPAND:elink.[filename[,attributes]]&colon.  Fixed a
problem with not adding quotes to long filenames with embedded whitespace.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=_@FILEWRITEB.@FILEWRITEB:elink.[n,length,string]&colon.  No
longer truncates on a write if the file was opened in binary mode.
:pt.:hp2.3.01:ehp2.  Ż:pd.:link reftype=hd refid=_@WORDS.@WORDS:elink.[["xxx",]string]&colon.  Fixed a
problem if the line began with a -.
:pt.:pd.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=Wildcards.Extended wildcards:elink. are now supported inside
:link reftype=hd refid=ExclRanges.file exclusion ranges:elink..  (In previous versions the
documentation indicated that this support was available, but it was
not.)
:pt.:hp2.3.02:ehp2.  Ż:pd.Fixed a problem which prevented :link
reftype=hd refid=FileComp.filename completion:elink. from returning hidden
and system files when these files were enabled in the FILECOMPLETION
variable.  Note that the default filename completion search does not
display hidden and system files, but now if you use FILECOMPLETION to
enable those files for a specific command, they will be shown as you
cycle through files with <Tab>.
:pt.:hp2.3.02:ehp2.  Ż:pd.Improved handling of commands using both *
(disable alias) and @ (don't add to command history) at the start.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=_@FILES.@FILES:elink.&colon.  Fixed a problem
which caused this function to leave a file handle open, which could
cause subsequent "access denied" errors.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=_@REPLACE.@REPLACE:elink.&colon.  Fixed a problem
with replacing commas.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=_@SELECT.@SELECT:elink.&colon.  Fixed a problem
with files over 64K.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=CDD.CDD:elink.&colon.
Fixed a problem if TREE was disabled (CDD /S uses TREE to build the
directory index).
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=FFIND.FFIND:elink.&colon.
Fixed a problem with /C and bracketed wildcards.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=INPUT.INPUT:elink.&colon.
Fixed a problem with line input (SETDOS /L1) and the /Ln switch.  (It
was allowing a maximum of "n-1" rather than "n" characters.)
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=LIST.LIST:elink.&colon.
Fixed a problem with highlighting the offsets as well as the actual
found text when in hex mode.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=SWITCH.SWITCH:elink.&colon.
Fixed minor problems with nested SWITCH statements.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=TEE.TEE:elink.&colon.
Fixed a problem with TEE'ing to CLIP&colon..
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=TOUCH.TOUCH:elink.&colon.
Fixed a problem with failing to display a usage message when there were
no parameters after a /C, and another problem with properly detecting
invalid times.
:pt.:hp2.3.02:ehp2.  Ż:pd.:link reftype=hd refid=UNALIAS.UNALIAS:elink.&colon.
Fixed a problem with /R.
:pt.:pd.
:pt.:hp2.3.02b:ehp2.  Ż:pd.Fixed a problem with
:link reftype=hd refid=Piping.piping:elink. to external applications.
:pt.:hp2.3.02b:ehp2.  Ż:pd.Fixed a problem which occasionally caused
spurious "internal error" crashes.
:pt.:hp2.3.02b:ehp2.  Ż:pd.:link reftype=hd refid=_@EXEC.@EXEC:elink.&colon.  Fixed
a problem which prevented the command from being executed at all if it
was preceded with an :hp2.@:ehp2..
:pt.:hp2.3.02b:ehp2.  Ż:pd.:link reftype=hd refid=_@MAKEAGE.@MAKEAGE:elink.&colon.  Fixed
a problem which caused 2-digit dates to be interpreted based on 1980
rather than 2000 (e.g.  01-01-02 was taken to mean 1-Jan-1982 rather
than the correct value, 1-Jan-2000).
:pt.:pd.
:pt.:hp2.3.03:ehp2.  Ż:pd.Fixed a problem which caused a crash with
extremely large :link reftype=hd refid=ExtDirSearch.extended directory search:elink.
databases.
:pt.:hp2.3.03:ehp2.  Ż:pd.:link reftype=hd refid=CHCP.CHCP:elink.&colon.
Fixed a problem which caused a crash when changing the code page under
Warp FixPak 13 and above.
:pt.:hp2.3.03:ehp2.  Ż:pd.:link reftype=hd refid=FFIND.FFIND:elink.&colon.
Fixed a problem with wildcards.
:pt.:hp2.3.04:ehp2.  Ż:pd.:link reftype=hd refid=CHCP.CHCP:elink.&colon.
Fixed a problem still causing a crash when changing the code page.
:pt.:hp2.3.04b:ehp2.  Ż:pd.Fixed a problem with setting the command window
icon on Warp 4 and above.
:pt.:hp2.3.04b:ehp2.  Ż:pd.Changed the way &4OS2. loads JPOS2DLL.DLL. Previously
only the LIBPATH would be searched. Now the LIBPATH is searched first and if
the search fails, the directory where &4OS2..EXE was invoked from is searched.
A side effect of this new behaviour is that if two different versions of &4OS2.
are run from two different directories and there is no JPOS2DLL.DLL on LIBPATH,
each &4OS2. version will load its own JPOS2DLL.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h1 name=TOC_Reference.Reference Information
:p.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=FileSysRef.File Systems and File Name
Conventions:elink.
:pt.:pd.:link reftype=hd refid=Colors.Colors and Color Names:elink.
:pt.:pd.:link reftype=hd refid=KeyNames.Keys and Key Names:elink.
:pt.:pd.:link reftype=hd refid=PopUp.Popup Windows:elink.
:pt.:pd.:link reftype=hd refid=ExeSearch.Executable Files and File Searches:elink.
:pt.:pd.:link reftype=hd refid=RefTab.Reference Tables:elink.
:pt.:pd.:link reftype=hd refid=Glossary.Glossary:elink.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h2 name=FileSysRef.File Systems and File Name Conventions
:p.
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.
:p.
The unique name of any file is composed of a :hp2.drive letter:ehp2., a
directory :hp2.path:ehp2., and a :hp2.filename:ehp2..  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.
:p.
The topics below are roughly divided according to the different parts of a
file name, and cover the file system structure and naming
conventions&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=DriveVol.Drives and Volumes:elink.
:pt.:pd.:link reftype=hd refid=FileSys.File Systems:elink.
:pt.:pd.:link reftype=hd refid=Directories.Directories and Subdirectories:elink.
:pt.:pd.:link reftype=hd refid=FileNames.File Names:elink.
:pt.:pd.:link reftype=hd refid=FileAttr.File Attributes and Time Stamps:elink.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h3 name=DriveVol.Drives and Volumes
:p.
A :hp2.drive letter:ehp2. designates which drive contains the file.  In a
file's full name, the drive letter is followed by a colon.  Drive letters
:hp2.A&colon.:ehp2. and :hp2.B&colon.:ehp2. are normally reserved for the
floppy disk drives.
:p.
Normally, drive :hp2.C&colon.:ehp2. is the first (or only) hard disk
drive.  Most current operating systems can divide a large hard disk into
multiple logical drives or :hp2.volumes:ehp2. that are usually called
:hp2.C&colon.:ehp2., :hp2.D&colon.:ehp2., :hp2.E&colon.:ehp2., etc.  Network
systems (LANs) give additional drive letters to sections of the network file
server drives.
:p.
Most recent systems also include a CD-ROM drive.  The CD-ROM is also
assigned a drive letter (or several letters, for CD-ROM changers), typically
using letters beyond that used by the last hard disk in the system, but
before any network drives.  Some systems may 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.  Like CD-ROM
drives, RAM disks are usually assigned drive letters beyond the last hard
disk in the system, but before network drives.
:p.
For example, on a system with a large hard disk you might have
:hp2.A&colon.:ehp2. and :hp2.B&colon.:ehp2. as floppy drives,
:hp2.C&colon.:ehp2., :hp2.D&colon.:ehp2., and :hp2.E&colon.:ehp2. as parts
of the hard disk, :hp2.F&colon.:ehp2. as a CD-ROM drive, :hp2.G&colon.:ehp2.
as a RAM disk, and :hp2.H&colon.:ehp2. and :hp2.I&colon.:ehp2. as network
drives.
:p.
Each volume is formatted under a particular file system; see
:link reftype=hd refid=FileSys.File Systems:elink. for details.  Additional
information about disk files and directories is available under
:link reftype=hd refid=Directories.Directories and Subdirectories:elink.,
:link reftype=hd refid=FileNames.File Names:elink., and
:link reftype=hd refid=FileAttr.File Attributes and Time Stamps:elink..

.* --------------------------------------------------------------------------

:h3 name=FileSys.File Systems
:p.
Each disk volume is organized according to a :hp2.file system:ehp2..  The
file system determines how files are named and how they are organized on the
disk.
:p.
As hard disk technology and operating systems have evolved, new file systems
have been invented to support longer file names, larger drives, and higher
disk performance.  Several different and incompatible schemes have
evolved.  Which file systems you can use depends on which operating system
you are using, and how the operating system and your hard disk are configured.
:p.
The operating systems under which &4OS2. runs can support two standard file
systems&colon.  FAT and HPFS.  See
:link reftype=hd refid=FileNames.File Names:elink. for details on the rules
for naming files under each file system.
:p.
:lm margin=4.:parml tsize=4 break=fit.
:pt.*:pd.The :hp2.FAT File System:ehp2. is the traditional file system used
by all versions of DOS.  Its name comes from the :hp2.F:ehp2.ile
:hp2.A:ehp2.llocation :hp2.T:ehp2.able DOS uses to keep track of the space
allocated to each file.  Windows 95, Windows NT, and OS/2 also support the
FAT file system.
:pt.*:pd.The :hp2.High Performance File System:ehp2. or :hp2.HPFS:ehp2. is a
file system provided with all versions of OS/2, and is also supported in
Windows NT version 3.51 and below.  It supports long file names, and offers
higher performance and better support for large drives than the FAT
system.  It also supports "extended attributes" to retain additional
information about your files.
:p.
DOS sessions running under OS/2 can access files on HPFS drives if the
files have short, FAT-compatible names.  Other operating systems (DOS,
Windows 95, and Windows NT 4.0 and above) can not access files on HPFS
drives.
:eparml.:lm margin=1.
:p.
Additional file systems may be installed under some operating systems to
support CD-ROM or network drives.  The file system type (FAT or HPFS)
is determined when a hard disk volume is formatted and applies to the
entire volume.  For example, under OS/2 you might have a 2 GB hard disk
divided into four 500 MB volumes, with the first three volumes (C&colon.,
D&colon., and E&colon.) formatted for the FAT file system, and the fourth
formatted for HPFS.
:p.
&4OS2. supports any standard file system installed under your operating
system.  If your operating system can access files on a particular drive,
then &4OS2. will be able to access those files as well.
:p.
Additional information about disk files and directories is available under
:link reftype=hd refid=DriveVol.Drives and Volumes:elink.,
:link reftype=hd refid=Directories.Directories and Subdirectories:elink.,
:link reftype=hd refid=FileNames.File Names:elink., and
:link reftype=hd refid=FileAttr.File Attributes and Time Stamps:elink..
:p.
:p.
:hp2.Network File Systems:ehp2.
:p.
A network file system allows you to access files stored on another computer
on a network, rather than on your own system.  &4OS2. supports all network file
systems which are compatible with the underlying operating system.
:p.
File and directory names for network file systems depend on both the "server"
software running on the system that has the files on it, and the "client"
software running on your computer to connect it to the network.  However,
they usually follow the rules described under
:link reftype=hd refid=FileNames.File Names:elink..
:p.
Most network software "maps" unused drive letters on your system to specific
locations on the network, and you can then treat the drive as if it were
physically part of your local computer.
:p.
Some networks also support the :hp2.Universal Naming Convention:ehp2., which
provides a common method for accessing files on a network drive without
using a "mapped" drive letter.  Names specified this way are called UNC
names.  They typically appear as :hp2.\\server\volume\path\filename:ehp2.,
where :hp2.server:ehp2. is the name of the network server where the files
reside, :hp2.volume :ehp2.is the name of a disk volume on that server, and
the :hp2.path\filename:ehp2. portion is a directory name and file name
which follow the conventions described in :link reftype=hd
refid=Directories.Directories and Subdirectories:elink..  &4OS2. supports UNC
filenames, and also allows you to use UNC directory names when changing
directories (see :link reftype=hd refid=DirNav.Directory Navigation:elink.
for more details).
:p.
When you use a network file system, remember that the naming conventions for
files on the network may not match those on your local system.  For example,
your local system may support long filenames while the network server or
client software does not, or vice versa.  &4OS2. will usually handle whatever
naming conventions are supported by your network software, as long as the
network software accurately reports the types of names it can handle.
:p.
In rare cases, &4OS2. may not be able to report correct statistics on network
drives (such as the number of bytes free on a drive).  This is usually
because the network file system does not provide complete or accurate
information.

.* --------------------------------------------------------------------------

:h3 name=Directories.˙Directories and Subdirectories
:p.
A file system is a method of organizing all of the files on an entire disk or
hard disk volume.  :hp2.Directories:ehp2. 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.  :hp2.Directories :ehp2.are also sometimes referred to as
:hp2.folders:ehp2..
:p.
Every drive has a :hp2.root:ehp2. or base directory, and many have one or
more :hp2. subdirectories:ehp2..  Subdirectories can also have
subdirectories, extending in a branching :hp2.tree:ehp2. structure from the
root directory.  The collection of all directories on a drive is often
called the :hp2.directory tree:ehp2., and a portion of the tree is sometimes
called a :hp2.subtree:ehp2..  The terms :hp2.directory:ehp2. and
:hp2.subdirectory:ehp2. are typically used interchangeably to mean a single
subdirectory within this tree structure.
:p.
Subdirectory names follow the same rules as file names (see :link reftype=hd
refid=FileNames.File Names:elink.).
:p.
The drive and subdirectory portion of a file's name are collectively called
the file's :hp2.path:ehp2..  For example, the file name
:hp1.C&colon.\DIR1\DIR2\MYFILE.DAT:ehp1. says to look for the file
:hp1.MYFILE.DAT:ehp1. in the subdirectory :hp1.DIR2:ehp1. which is part of
the subdirectory :hp1.DIR1:ehp1. which is on drive C.  The path for
:hp1.MYFILE.DAT:ehp1. is :hp1.C&colon.\DIR1\DIR2:ehp1..  The backslashes
between subdirectory names are required.  On HPFS 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.
:p.
The operating system and command processor remember both a
:hp2.current:ehp2. or :hp2.default drive:ehp2. for your system as a whole,
and a :hp2.current:ehp2. or :hp2.default directory:ehp2. 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).
:p.
The root directory is named using the drive letter and a single
backslash.  For example, D&colon.\ refers to the root directory
of drive D&colon..  Using a drive letter with no directory name
at all refers to the current directory on the specified drive.  For example,
:hp1.E&colon.README.DOC:ehp1. refers to the file :hp1.README.DOC:ehp1. in
the current directory on drive E&colon., whereas
:hp1.E&colon.\README.DOC:ehp1. refers to the file :hp1.README.DOC:ehp1. in
the root directory on drive E&colon..
:p.
There are also two special subdirectory names that are useful in many
situations&colon.  a single period by itself [:hp2..:ehp2.] means "the
current default directory."  Two periods together [:hp2...:ehp2.] means "the
directory which contains the current default directory" (often referred to
as the :hp2.parent directory:ehp2.).  These special names can be used
wherever a full directory name can be used.  &4OS2. allows you to use
additional periods to specify directories further "up" the tree (see :link
reftype=hd refid=ParDir.Extended Parent Directory Names:elink.).
:p.
Additional information about disk files and file systems is available under
:link reftype=hd refid=DriveVol.Drives and Volumes:elink.,
:link reftype=hd refid=FileSys.File Systems:elink.,
:link reftype=hd refid=FileNames.File Names:elink., and
:link reftype=hd refid=FileAttr.File Attributes and Time Stamps:elink..

.* --------------------------------------------------------------------------

:h3 name=FileNames.File Names
:p.
Under the FAT file system, the filename consists of a :hp2.base name:ehp2.
of 1 to 8 characters plus an optional :hp2.extension:ehp2. composed of a
period plus 1 to 3 more characters.
:p.
You can use alphabetic and numeric characters plus the punctuation marks
:hp2.! # $ % &amp. ' ( ) - @ ^ _ ` { }:ehp2. and :hp2.~:ehp2. in both the
base name and the extension of a FAT filename.  Because the exclamation
point [:hp2.!:ehp2.], percent sign [:hp2.%:ehp2.], caret [:hp2.^:ehp2.], at
sign [:hp2.@:ehp2.], parentheses [:hp2.():ehp2.], and back-quote
[:hp2.`:ehp2.] also have other meanings to &4OS2., it is best to avoid using
them in filenames.
:p.
The HPFS file system 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 file names which contain semicolons
[:hp2.;:ehp2.], see :link reftype=hd refid=Wildcards.Wildcards:elink. for
details on avoiding problems with interpretation of those file names under
&4OS2..
:p.
HPFS file names are 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 :hp1.MYFILE:ehp1., :hp1.myfile:ehp1., or
:hp1.MyFile:ehp1., 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 (:hp1.i.e.:ehp1., 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.
:p.
Files stored on HPFS volumes often have "FAT-compatible" names&colon.  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 long names generally can access files by using FAT-compatible names.
:p.
If an HPFS-compatible file name includes spaces or other characters that
would not be allowed in a FAT name, you :hp2.must:ehp2. place double
quotes around the name.  For example, suppose you have a file named
:hp1.LET3:ehp1. on a FAT volume, and you want to copy it to the
:hp1.LETTERS:ehp1. directory on drive F&colon., an HPFS partition, and give
it the name :hp1.Letter To Sara:ehp1..  To do so, use either of these
commands&colon.
:xmp.
        [c&colon.\wp] copy let3 f&colon.\LETTERS\"Letter To Sara"
:p.
        [c&colon.\wp] copy let3 "f&colon.\LETTERS\Letter To Sara"
:exmp.:p.
The HPFS file systems do not explicitly define an "extension" for file names
which are not FAT-compatible.  However, by convention, all characters after
the last period in the file name are treated as the extension.  For example,
the file name :hp1."Letter to Sara":ehp1. has no extension, whereas the name
:hp1."Letter.to.Sara":ehp1. has the extension :hp1.Sara:ehp1..
:p.
Additional information about disk files and file systems is available under
:link reftype=hd refid=DriveVol.Drives and Volumes:elink.,
:link reftype=hd refid=FileSys.File Systems:elink.,
:link reftype=hd refid=Directories.Directories and Subdirectories:elink., and
:link reftype=hd refid=FileAttr.File Attributes and Time Stamps:elink..

.* --------------------------------------------------------------------------

:h3 name=FileAttr.File Attributes and Time Stamps
:p.
Each file also has :hp2.attributes:ehp2., and one or more :hp2.time
stamps:ehp2..  Attributes define characteristics of the file which may be
useful to the operating system, to you, or to an application program.  Time
stamps can record when the file was created, last modified, or last
accessed.  Most &4OS2. file processing commands allow you to select files for
processing based on their attributes and/or time stamp(s).
:p.
Each file on your system has four standard attributes.  Every time a program
modifies a file, the operating system sets the :hp2.Archive:ehp2. attribute,
which signals that the file has been modified since it was last backed
up.  This attribute can be used by &4OS2. to determine which files to :link
reftype=hd refid=COPY.COPY:elink., and by backup programs to determine which
files to back up.  When the :hp2.Read-only:ehp2. attribute is set, the
file can't be changed or erased accidentally; this can be used to help
protect important files from damage.  The :hp2.Hidden:ehp2. and
:hp2.System:ehp2. attributes prevent the file from appearing in normal
directory listings.  (Two additional attributes, :hp2.Directory:ehp2. and
:hp2.Volume label:ehp2., are also available.  These attributes are
controlled by the operating system, and are not modified directly by &4OS2..)
:p.
Attributes can be set and viewed with the :link reftype=hd
refid=ATTRIB.ATTRIB:elink. command.  The :link reftype=hd
refid=DIR.DIR:elink. command also has options 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.
:p.
When a file is created, and every time it is modified, the operating system
records the system time and date in a :hp2.time stamp:ehp2. in the file's
directory entry.  Several &4OS2. commands and variable functions, and many
backup and utility programs, use this time stamp to determine the relative
ages of files.
:p.
On FAT volumes, only the single time stamp described above is
available.  Files on HPFS volumes have three sets of time and date
stamps.  The operating system records when each file was created, when it
was last written or modified, and when it was last accessed.  The "last
write" time stamp matches the single time stamp used on traditional FAT
volumes.
:p.
Several &4OS2. commands and variable functions let you specify which set of
time and date stamps you want to view or work with on HPFS volumes.  These
commands and functions use the letter :hp2.c:ehp2. to refer to the creation
time stamp, :hp2.w:ehp2. for the last write time stamp, and :hp2.a:ehp2. for
the last access time stamp.
:p.
Additional information about disk files and file systems is available under
:link reftype=hd refid=DriveVol.Drives and Volumes:elink.,
:link reftype=hd refid=FileSys.File Systems:elink.,
:link reftype=hd refid=Directories.Directories and Subdirectories:elink., and
:link reftype=hd refid=FileNames.File Names:elink..

.* --------------------------------------------------------------------------
:h2 name=TOC_MiscRef.Miscellaneous Reference Information
:p.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=Colors.Colors and Color Names:elink.
:pt.:pd.:link reftype=hd refid=KeyNames.Keys and Key Names:elink.
:pt.:pd.:link reftype=hd refid=Popup.Popup Windows:elink.
:pt.:pd.:link reftype=hd refid=ExeSearch.Executable Files and File Searches:elink.
:eparml.:lm margin=1.
.* --------------------------------------------------------------------------

:h3 name=Colors.Colors and Color Names
:p.
You can use color names in several of the directives in the :link reftype=hd refid=INIFile..INI file:elink.
and in many commands.  The general form of a color
name is&colon.
:p.
        [BRIght] [BLInk] :hp1.fg:ehp1. ON [BRIght] :hp1.bg:ehp1. [BORder :hp1.bc:ehp1. ]
:p.
where :hp2.fg:ehp2. is the foreground or text color, :hp2.bg:ehp2. is the
background color, and :hp2.bc:ehp2. is the border color.
:p.
The available colors are&colon.
:xmp.
        Black           Blue            Green           Red
        Magenta         Cyan            Yellow          White
:exmp.:p.
Color names and the words BRIght, BLInk, and BORder may be
shortened to the first 3 letters.
:p.
You can also specify colors by number instead of by name.  The numbers are
most useful in potentially long :hp1..INI:ehp1. file directives like
:link reftype=hd refid=INI_ColorDir.ColorDir:elink., where using color names
may take too much space.  The following numbers are recognized&colon.
:xmp.
        0 - Black       8 - Gray (bright black)
        1 - Blue        9 - Bright blue
        2 - Green      10 - Bright green
        3 - Cyan       11 - Bright cyan
        4 - Red        12 - Bright red
        5 - Magenta    13 - Bright magenta
        6 - Yellow     14 - Bright yellow
        7 - White      15 - Bright white
:exmp.:p.
Use one number to substitute for the :hp2.[BRIght] fg:ehp2. portion of the
color name, and a second to substitute for the :hp2.[BRIght] bg:ehp2.
portion.  For example, instead of bright cyan on blue you could use :hp2.11
on 1:ehp2. to save space in a :hp2.ColorDir:ehp2. specification.
:p.
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.  These restrictions are
due to the design of your PC video hardware and video
drivers, and are not inherent in &4OS2..  Some of the restrictions
are complex, so feel free to skip over those that do not apply to
color combinations you use.
:p.
Some restrictions depend on the display "mode."  &4OS2. can run in
either :hp2.full-screen:ehp2. display mode, where it uses the entire screen
and has more direct control over the video hardware; or in :hp2.windowed:ehp2.
display mode, where it appears in a window on the OS/2 desktop.
:p.
:p.
:hp2.Color Errors:ehp2.
:p.
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 &4OS2. color specifications.
:p.
:p.
:hp2.Border Colors:ehp2.
:p.
In order to use border colors, you must have a color video adapter
(monochrome adapters do not support border colors).
:p.
&4OS2. can only accept border colors in the :link reftype=hd
refid=CLS.CLS:elink. and :link reftype=hd refid=COLOR.COLOR:elink. commands,
and in the :link reftype=hd refid=INI_StdColors.StdColors:elink.
directive in the :hp1..INI:ehp1. file.  Border colors will be ignored, or
will cause an error, if they are used elsewhere.
:p.
Border colors do not work in windowed mode, and will be ignored if
used in a windowed session under OS/2.
:p.
:p.
:hp2.Blinking Text and Bright Background Colors:ehp2.
:p.
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.
:p.
The effects of blinking and bright background color specifications
depend partly on whether you are in full-screen or windowed display
mode.
:p.
:p.
:hp2.Full-Screen Display Mode:ehp2.
:p.
Full-screen display mode uses the entire screen for your command
processor or application.  This mode is available as an option for
text-mode sessions in OS/2.
:p.
In 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.
:p.
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.
:p.
In full-screen display mode, the configuration of your video adapter can
be controlled by &4OS2. with the :link reftype=hd refid=INI_BrightBG.BrightBG:elink. directive
in the :hp1.&4OS2INI.:ehp1. file or the :link reftype=hd refid=SETDOS.SETDOS:elink. /B command.  If
you set BrightBG = No or use the SETDOS /B0 command, &4OS2. will
configure the video adapter for blinking text, and all characters
on the screen with the blink / bright background flag set will
blink.  If you set BrightBG = Yes or use SETDOS /B1, &4OS2. will
configure the video adapter for bright background colors, and
the characters will be displayed with a bright background instead
of blinking.
:p.
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 :link reftype=hd refid=COLOR.COLOR:elink. commands
will always produce the same results&colon.
:xmp.
        color blink white on blue
        color white on bright blue
:exmp.:p.
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.
:p.
If you don't use BrightBG or SETDOS /B, or if you use SETDOS /B2, &4OS2. will
not attempt to configure your video hardware.  Most video adapters default
to blinking text in full-screen mode, but this can be changed by application
programs.  If you use BrightBG or SETDOS /B, &4OS2. will configure the hardware
each time it displays the prompt.
:p.
:p.
:hp2.Windowed Display Mode:ehp2.
:p.
Windowed display mode uses a window on the screen for your command
processor or text-mode application.  It is available for command
processor sessions and most applications running under OS/2.
:p.
In windowed mode, &4OS2. cannot control your hardware to select
blinking or bright backgrounds.  Instead, OS/2 displays bright background
colors, regardless of the BrightBG or SETDOS /B setting.  It does 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.
:p.
:p.
:hp2.Switching Modes:ehp2.
:p.
OS/2 allows you to switch any DOS or other text-mode session between
full-screen and windowed mode.  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.

.* --------------------------------------------------------------------------

:h3 name=KeyNames.Keys and Key Names
:p.
Key names are used to define keystroke :link reftype=hd refid=ALIAS.aliases:elink., and in
several :link reftype=hd refid=INIFile.&4OS2INI.:elink. directives, and with the
:link reftype=hd refid=KEYSTACK.KEYSTACK:elink. command.  The format of a key
name is the same in all three uses&colon.
:xmp.
        [Prefix-]Keyname
:exmp.:p.
The key prefix can be left out, or it can be any one of the
following&colon.
:xmp.
        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.
:exmp.:p.
The possible key names are&colon.
:xmp.
        A - Z           Enter           PgDn
        0 - 9           Up              Home
        F1 - F          Down            End
        Esc             Left            Ins
        Bksp            Right           Del
        Tab             PgUp
:exmp.:p.
All key names must be spelled as shown.  Alphabetic keys can be
specified in upper or lower case.  You cannot specify a punctuation key.
:p.
The prefix and key name must be separated by a dash [:hp2.-:ehp2.].  For
example&colon.
:xmp.
        Alt-F10        This is okay
        Alt F10        The space will cause an error
:exmp.:p.
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 [:hp2.@:ehp2.] for
extended key codes like :hp2.F1:ehp2. or the cursor keys.  For example,
use 13 for :hp2.Enter:ehp2., or @59 for :hp2.F1:ehp2..  In general, you will find
it easier to use the names described above rather than key numbers.
See the :link reftype=hd refid=RefTab.Reference Tables:elink. for an explanation and
list of ASCII and key codes.
:p.
Some keys are intercepted by OS/2 and are not passed on to &4OS2..  For
example, :hp2.Ctrl-S:ehp2. pauses screen output temporarily, and Ctrl-Esc
pops up the OS/2 window list.  Keys which are intercepted
by OS/2 generally cannot be assigned to
:link reftype=hd refid=ALIAS.aliases:elink. or with :link reftype=hd refid=INIKeyMap.key mapping directives:elink.,
because &4OS2. never receives these keystrokes and therefore cannot
act on them.
:p.
You also may not be able to use certain keys if your keyboard is
not 100% IBM-compatible or your keyboard driver does not support
them.  For example, on some systems the :hp2.F11:ehp2. and :hp2.F12:ehp2.
keys are not recognized; others may not support unusual combinations
like :hp2.Ctrl-Tab:ehp2..  These problems are rare; when they do occur,
they are usually due to OS/2.

.* --------------------------------------------------------------------------

:h3 name=Popup.Popup Windows
:p.
Several features of &4OS2. display popup windows.  A popup window may be used
to display filenames, recently-executed commands, recently-used directories,
the results of an extended directory search, or a list created by the :link
reftype=hd refid=SELECT.SELECT:elink. command or the :link reftype=hd
refid=_@SELECT.@SELECT:elink. internal function.
:p.
Popup windows always display a list of choices and a cursor bar.  You can
move the cursor bar inside the window until you find the choice that you
wish to make, then press the Enter key to select that item.
:p.
Navigation inside any popup window follows the conventions described below.
Additional information on each specific type of popup window is provided when
that window is introduced in the online help.
:p.
You can control the color, position and size of most popup windows from the
Command Line 2 page of the OPTION dialogs.  You can also control these
features with directives in the :hp1..INI:ehp1. file, including
:link reftype=hd refid=INI_PopupWinLeft.PopupWinLeft, PopupWinTop,
PopupWinWidth, and PopupWinHeight:elink., and :link reftype=hd
refid=INI_PopupWinColors.PopupWinColors:elink..  A few popup windows (e.g.,
the :link reftype=hd refid=ExtDirSearch.extended directory search
window:elink.) have their own specific :hp1..INI:ehp1. directives, and
corresponding separate choices in the OPTION command.  You can also change
the keys used in most popup windows with key mapping directives in
:hp1.&4OS2INI.:ehp1..
:p.
Once a window is open, you can use these navigation keys to find the
selection you wish to make&colon.
:p.
:lm margin=8.:parml compact tsize=16 break=fit.
:pt.:hp2.&uarrow.:ehp2.:pd.Move the selection bar up one line.
:pt.:hp2.&darrow.:ehp2.:pd.Move the selection bar down one line.
:pt.:hp2.:ehp2.:pd.Scroll the display left 4 columns.
:pt.:hp2.:ehp2.:pd.Scroll the display right 4 columns.
:pt.:hp2.PgUp:ehp2.:pd.Scroll the display up one page.
:pt.:hp2.PgDn:ehp2.:pd.Scroll the display down one page.
:pt.:hp2.Ctrl-PgUp:ehp2.:pd.Go to the beginning of the list.
:pt.  or :hp2.Home:ehp2.:pd.
:pt.:hp2.Ctrl-PgDn:ehp2.:pd.Go to the end of the list.
:pt.  or :hp2.End:ehp2.:pd.
:pt.:hp2.Esc:ehp2.:pd.Close the window without making a selection.
:pt.:hp2.Enter:ehp2.:pd.Select the current item and close the window.
:eparml.:lm margin=1.
.br
In addition to scrolling through a popup window, you can search the list
using character matching.  If you press a character, the cursor bar will move
to the next entry that begins with that character.  If you type multiple
characters, the cursor will move to the entry that begins with the search
string entered to that point (you can enter a search string up to 32
characters long).  If no entry matches the character or string that you have
typed, the command processor beeps and does not move the cursor bar.  To
reset the search string, press Backspace.
:p.
You can change the keys used in popup windows with :link reftype=hd
refid=INIKeyMap.key mapping directives:elink. in
:link reftype=hd refid=INIFile.&4OS2INI.:elink. file.

.* --------------------------------------------------------------------------

:h3 name=ExeSearch.Executable Files and File Searches
:p.
Once &4OS2. knows that it is supposed to run an external command, it tries to
find an executable file (one with a :hp1..COM:ehp1. or :hp1..EXE:ehp1.
extension) whose name matches the command name.  It runs the executable file
if it finds one.
:p.
If &4OS2. cannot find an executable 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.  &4OS2. looks first for a :hp1..BTM:ehp1. file, then for a
:hp1..CMD:ehp1. file, then for a :hp1..BAT:ehp1. file, and finally for a
:hp1..REX:ehp1. file.  See :link reftype=hd refid=BatchType..BAT, .CMD,
and .BTM Files:elink. for more information on these different types of batch
files.  If &4OS2. finds such a file, it then reads each line in the file as a
new command.
:p.
If the search for a batch file fails, &4OS2. checks to see if the command name
matches the name of a file with an extension that is associated with a
specific application (for example, if you have associated :hp1..DOC:ehp1.
with your editor or word processor, and you type the name of a
:hp1..DOC:ehp1. file).  If a match is found, &4OS2. runs the program you
specified when the association was defined.
:p.
In searching for the application associated with a file, &4OS2. will first
examine any :link reftype=hd refid=ExeExt.executable extensions:elink. you
have defined to associate a file extension with a specific program to
process that type of file.
:p.
&4OS2. first searches 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 :hp1..COM:ehp1., :hp1..EXE:ehp1., :hp1..BTM:ehp1.,
:hp1..BAT:ehp1. or :hp1..CMD:ehp1. file or an executable extension in the
current directory, &4OS2. repeats its search in every directory in your
:hp2.search path:ehp2..
:p.
The search path is a list of directories that &4OS2. (and some applications)
search for executable files.  For example, if you wanted &4OS2. to search the
root directory of the C&colon. drive, the \OS2 subdirectory on the C&colon.
drive, and the \UTIL directory on the D&colon. drive for executable files,
your search path would look like this&colon.
:xmp.
        PATH=C&colon.\;C&colon.\OS2;D&colon.\UTIL
:exmp.:p.
Notice that the directory names in the search path are separated by
semicolons.
:p.
You can create or view the search path with the :link reftype=hd
refid=PATH.PATH:elink. command.  You can use the :link reftype=hd
refid=ESET.ESET:elink. command 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.
:p.
Remember, &4OS2. always looks for an executable file or a file with an
executable extension in the current subdirectory, then in each directory in
the search path.  (You can change the search order so the current
directory is not searched first; see the :link reftype=hd
refid=PATH.PATH:elink. command for details.)
:p.
If you include an extension as part of the command name, &4OS2. only searches
for a file with that extension.  Similarly, if you include a path as part of
the command name, the command processor will look only in the directory you
specified, and ignore the usual search of the current directory and the PATH.
:p.
The following table sums up the possible search options (the term "standard
search" refers to the search of the current directory and each directory in
the search path)&colon.
:lm margin=8.:parml tsize=24 break=fit.
:pt.Command:pd.&4OS2. Search Sequence
:pt.:hp2.WP:ehp2.:pd.Standard search for any executable file whose base name
is :hp1.WP:ehp1..
:pt.:hp2.WP.EXE:ehp2.:pd.Standard search for :hp1.WP.EXE:ehp1.; will not
find files with other extensions.
:pt.:hp2.C&colon.\WP7\WP:ehp2.:pd.Looks in the :hp1.C&colon.\WP7:ehp1.
directory for any executable file whose base name is :hp1.WP:ehp1..  Does
not check the standard search directories.
:pt.:hp2.C&colon.\WP7\WP.EXE:ehp2.:pd.Looks only for the file
:hp1.C&colon.\WP7\WP.EXE:ehp1..
:pt.:hp2.LAB.DOC:ehp2.:pd.Standard search for :hp1.LAB.DOC:ehp1., if
:hp1..DOC:ehp1. is defined as an executable extension.  Runs the associated
application if the file is found.
:pt.:hp2.C&colon.\LI\LAB.DOC:ehp2.:pd.Looks only for the file
:hp1.C&colon.\LI\LAB.DOC:ehp1., and only if :hp1..DOC:ehp1. is defined as an
executable extension.  Runs the associated application if the file is found.
:eparml.:lm margin=1.
.br
If &4OS2. 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 the :link
reftype=hd refid=ALIAS.ALIAS:elink. command for details).  If you have
defined an alias with that name, it is executed (this allows you to control
error handling for unknown commands).  Otherwise, &4OS2. displays an "Unknown
command" error message and waits for your next instruction.

.* --------------------------------------------------------------------------

:h2 name=RefTab.Reference Tables
:p.
The reference 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, or a character set or display font which does not
include the characters shown here.  See your operating system documentation
for more information about country and language support.
:p.
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 :hp2.ASCII:ehp2. (:hp2.A:ehp2.merican
:hp2.S:ehp2.tandard :hp2.C:ehp2.ode for :hp2.I:ehp2.nformation
:hp2.I:ehp2.nterchange).  Function keys, cursor keys, and Alt keys generate
:hp2.scan codes:ehp2. indicating which key was pressed, but not ASCII
codes.  The tables in this section cover both kinds of codes.
:p.
For more information, see&colon.
:lm margin=8.:parml compact tsize=4 break=fit.
:pt.:pd.:link reftype=hd refid=ASCII.ASCII Table:elink.
:pt.:pd.:link reftype=hd refid=KeyScan.Key Codes and Scan Codes Table:elink.
:pt.:pd.:link reftype=hd refid=KeyScanExpl.Key Codes and Scan Codes Explanation:elink.
:pt.:pd.:link reftype=hd refid=ANSICODES.ANSI Codes:elink.
:eparml.:lm margin=1.

.* --------------------------------------------------------------------------

:h3 name=ASCII.ASCII Table
:p.
The ASCII tables below include a :hp2.Char:ehp2. column showing the visual
representation of the character, a :hp2.Dec:ehp2. column showing the decimal
numeric value of the character in the ASCII set, and a :hp2.Hex:ehp2. column
showing the hexadecimal (base-16) value.
:p.
:xmp.
:hp2.                  Control Characters:ehp2.
:p.
    Dec  Hex  Chr  Nam  Ctl   ł   Dec  Hex  Chr  Nam  Ctl
    ---  ---  ---  ---  ---   ł   ---  ---  ---  ---  ---
    000   00       NUL   ^@   ł   016   10      DLE   ^P
    001   01      SOH   ^A   ł   017   11      DC1   ^Q
    002   02      STX   ^B   ł   018   12      DC2   ^R
    003   03      ETX   ^C   ł   019   13      DC3   ^S
    004   04      EOT   ^D   ł   020   14      DC4   ^T
    005   05      ENQ   ^E   ł   021   15      NAK   ^U
    006   06      ACK   ^F   ł   022   16      SYN   ^V
    007   07       BEL   ^G   ł   023   17      ETB   ^W
    008   08      BS    ^H   ł   024   18      CAN   ^X
    009   09       HT    ^I   ł   025   19      EM    ^Y
    010   0A       LF    ^J   ł   026   1A      SUB   ^Z
    011   0B      VT    ^K   ł   027   1B      ESC   ^[
    012   0C      FF    ^L   ł   028   1C      FS    ^\
    013   0D       CR    ^M   ł   029   1D      GS    ^]
    014   0E      SO    ^N   ł   030   1E      RS    ^^
    015   0F      SI    ^O   ł   031   1F      US    ^_
:p.
:p.
:hp2.              Punctuation, Digits, Upper Case:ehp2.
:p.
  Dec  Hex  Chr ł  Dec  Hex  Chr ł  Dec  Hex  Chr ł  Dec  Hex  Chr
  ---  ---  --- ł  ---  ---  --- ł  ---  ---  --- ł  ---  ---  ---
  032   20      ł  048   30   0  ł  064   40   @  ł  080   50   P
  033   21   !  ł  049   31   1  ł  065   41   A  ł  081   51   Q
  034   22   "  ł  050   32   2  ł  066   42   B  ł  082   52   R
  035   23   #  ł  051   33   3  ł  067   43   C  ł  083   53   S
  036   24   $  ł  052   34   4  ł  068   44   D  ł  084   54   T
  037   25   %  ł  053   35   5  ł  069   45   E  ł  085   55   U
  038   26   &amp.  ł  054   36   6  ł  070   46   F  ł  086   56   V
  039   27   '  ł  055   37   7  ł  071   47   G  ł  087   57   W
  040   28   (  ł  056   38   8  ł  072   48   H  ł  088   58   X
  041   29   )  ł  057   39   9  ł  073   49   I  ł  089   59   Y
  042   2A   *  ł  058   3A   &colon.  ł  074   4A   J  ł  090   5A   Z
  043   2B   +  ł  059   3B   ;  ł  075   4B   K  ł  091   5B   [
  044   2C   ,  ł  060   3C   <  ł  076   4C   L  ł  092   5C   \
  045   2D   -  ł  061   3D   =  ł  077   4D   M  ł  093   5D   ]
  046   2E   .  ł  062   3E   >  ł  078   4E   N  ł  094   5E   ^
  047   2F   /  ł  063   3F   ?  ł  079   4F   O  ł  095   5F   _
:p.
:p.
:hp2.                Lower Case, Miscellaneous:ehp2.
:p.
                 Dec  Hex  Chr ł  Dec  Hex  Chr
                 ---  ---  --- ł  ---  ---  ---
                 096   60   `  ł  112   70   p
                 097   61   a  ł  113   71   q
                 098   62   b  ł  114   72   r
                 099   63   c  ł  115   73   s
                 100   64   d  ł  116   74   t
                 101   65   e  ł  117   75   u
                 102   66   f  ł  118   76   v
                 103   67   g  ł  119   77   w
                 104   68   h  ł  120   78   x
                 105   69   i  ł  121   79   y
                 106   6A   j  ł  122   7A   z
                 107   6B   k  ł  123   7B   {
                 108   6C   l  ł  124   7C   &splitvbar.
                 109   6D   m  ł  125   7D   }
                 110   6E   n  ł  126   7E   ~
                 111   6F   o  ł  127   7F   
:p.
:p.
:hp2.            International; Graphics Characters 1:ehp2.
:p.
  Dec  Hex  Chr ł  Dec  Hex  Chr ł  Dec  Hex  Chr ł  Dec  Hex  Chr
  ---  ---  --- ł  ---  ---  --- ł  ---  ---  --- ł  ---  ---  ---
  128   80   €  ł  144   90   �  ł  160   A0      ł  176   B0   °
  129   81   �  ł  145   91   ‘  ł  161   A1   ˇ  ł  177   B1   ±
  130   82   ‚  ł  146   92   ’  ł  162   A2   ˘  ł  178   B2   ˛
  131   83   �  ł  147   93   “  ł  163   A3   Ł  ł  179   B3   ł
  132   84   „  ł  148   94   ”  ł  164   A4   ¤  ł  180   B4   ´
  133   85   …  ł  149   95   •  ł  165   A5   Ą  ł  181   B5   µ
  134   86   †  ł  150   96   –  ł  166   A6   ¦  ł  182   B6   ¶
  135   87   ‡  ł  151   97   —  ł  167   A7   §  ł  183   B7   ·
  136   88   �  ł  152   98   �  ł  168   A8   ¨  ł  184   B8   ¸
  137   89   ‰  ł  153   99   ™  ł  169   A9   ©  ł  185   B9   ą
  138   8A   Š  ł  154   9A   š  ł  170   AA   Ş  ł  186   BA   ş
  139   8B   ‹  ł  155   9B   ›  ł  171   AB   «  ł  187   BB   »
  140   8C   Ś  ł  156   9C   ś  ł  172   AC   ¬  ł  188   BC   Ľ
  141   8D   Ť  ł  157   9D   ť  ł  173   AD   ­  ł  189   BD   ˝
  142   8E   Ž  ł  158   9E   ž  ł  174   AE   ®  ł  190   BE   ľ
  143   8F   Ź  ł  159   9F   ź  ł  175   AF   Ż  ł  191   BF   ż
:p.
:p.
:hp2.               Graphics Characters 2; Symbols:ehp2.
:p.
  Dec  Hex  Chr ł  Dec  Hex  Chr ł  Dec  Hex  Chr ł  Dec  Hex  Chr
  ---  ---  --- ł  ---  ---  --- ł  ---  ---  --- ł  ---  ---  ---
  192   C0   Ŕ  ł  208   D0   Đ  ł  224   E0   ŕ  ł  240   F0   đ
  193   C1   Á  ł  209   D1   Ń  ł  225   E1   á  ł  241   F1   ń
  194   C2   Â  ł  210   D2   Ň  ł  226   E2   â  ł  242   F2   ň
  195   C3   Ă  ł  211   D3   Ó  ł  227   E3   ă  ł  243   F3   ó
  196   C4   Ä  ł  212   D4   Ô  ł  228   E4   ä  ł  244   F4   ô
  197   C5   Ĺ  ł  213   D5   Ő  ł  229   E5   ĺ  ł  245   F5   ő
  198   C6   Ć  ł  214   D6   Ö  ł  230   E6   ć  ł  246   F6   ö
  199   C7   Ç  ł  215   D7   ×  ł  231   E7   ç  ł  247   F7   ÷
  200   C8   Č  ł  216   D8   Ř  ł  232   E8   č  ł  248   F8   ř
  201   C9   É  ł  217   D9   Ů  ł  233   E9   é  ł  249   F9   ů
  202   CA   Ę  ł  218   DA   Ú  ł  234   EA   ę  ł  250   FA   ú
  203   CB   Ë  ł  219   DB   Ű  ł  235   EB   ë  ł  251   FB   ű
  204   CC   Ě  ł  220   DC   Ü  ł  236   EC   ě  ł  252   FC   ü
  205   CD   Í  ł  221   DD   Ý  ł  237   ED   í  ł  253   FD   ý
  206   CE   Î  ł  222   DE   Ţ  ł  238   EE   î  ł  254   FE   ţ
  207   CF   Ď  ł  223   DF   ß  ł  239   EF   ď  ł  255   FF
:exmp.

.* --------------------------------------------------------------------------

:h3 name=KeyScan.Key Codes and Scan Codes Table
:p.
(For more details on key codes and scan codes, see the
:link reftype=hd refid=KeyScanExpl.Key Codes and Scan Codes Explanation:elink..)
:p.
The following table lists all of the keys on the 101-key "enhanced" U.S.
keyboard.  Many non-U.S. keyboards are similar, but will not be exactly the
same.  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.
:p.
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).
:p.
Key names prefaced by :hp2.np:ehp2. are on the numeric keypad.  Those
prefaced by :hp2.cp:ehp2. 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 when Num Lock is on, 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").
:p.
The chart is blank for key combinations that do not have scan codes
or ASCII codes, like :hp2.Ctrl-1:ehp2. or :hp2.Alt-PgUp:ehp2..
:xmp.

:hp2.                   Top Two Keyboard Rows:ehp2.

                             Shift  Shift  Ctrl   Ctrl   Alt
               Scan   ASCII  Scan   ASCII  Scan   ASCII  Scan
     Key       Code   Code   Code   Code   Code   Code   Code

     Esc       1      27     1      27     1      27     1
     1  !      2      49     2      33                   120
     2  @      3      50     3      64     3      0      121
     3  #      4      51     4      35                   122
     4  $      5      52     5      36                   123
     5  %      6      53     6      37                   124
     6  ^      7      54     7      94     7      30     125
     7  &amp.      8      55     8      38                   126
     8  *      9      56     9      42                   127
     9  (      10     57     10     40                   128
     0  )      11     48     11     41                   129
     -  _      12     45     12     95     12     31     130
     =  +      13     61     13     43                   131
     Backspace 14     8      14     8      14     127    14
     Tab       15     9      15     0      148    0      165
     Q         16     113    16     81     16     17     16
     W         17     119    17     87     17     23     17
     E         18     101    18     69     18     5      18
     R         19     114    19     82     19     18     19
     T         20     116    20     84     20     20     20
     Y         21     121    21     89     21     25     21
     U         22     117    22     85     22     21     22
     I         23     105    23     73     23     9      23
     O         24     111    24     79     24     15     24
     P         25     112    25     80     25     16     25
     [  {      26     91     26     123    26     27     26
     ]  }      27     93     27     125    27     29     27
     Enter     28     13     28     13     28     10     28


:hp2.                  Bottom Two Keyboard Rows:ehp2.

                             Shift  Shift  Ctrl   Ctrl   Alt
               Scan   ASCII  Scan   ASCII  Scan   ASCII  Scan
     Key       Code   Code   Code   Code   Code   Code   Code

    A          30     97     30     65     30     1      30
    S          31     115    31     83     31     19     31
    D          32     100    32     68     32     4      32
    F          33     102    33     70     33     6      33
    G          34     103    34     71     34     7      34
    H          35     104    35     72     35     8      35
    J          36     106    36     74     36     10     36
    K          37     107    37     75     37     11     37
    L          38     108    38     76     38     12     38
    ; &colon.        39     59     39     58                   39
    '  "       40     39     40     34                   40
    `  ~       41     96     41     126                  41
    \  &splitvbar.       43     92     43     124    43     28     43
    Z          44     122    44     90     44     26     44
    X          45     120    45     88     45     24     45
    C          46     99     46     67     46     3      46
    V          47     118    47     86     47     22     47
    B          48     98     48     66     48     2      48
    N          49     110    49     78     49     14     49
    M          50     109    50     77     50     13     50
    ,  <       51     44     51     60                   51
    .  >       52     46     52     62                   52
    /  ?       53     47     53     63                   53
    Space      57     32     57     32     57     32     57


:hp2.                 Key Pads and Function Keys:ehp2.

                             Shift  Shift  Ctrl   Ctrl   Alt
               Scan   ASCII  Scan   ASCII  Scan   ASCII  Scan
     Key       Code   Code   Code   Code   Code   Code   Code


     F1        59     0      84     0      94     0      104
     F2        60     0      85     0      95     0      105
     F3        61     0      86     0      96     0      106
     F4        62     0      87     0      97     0      107
     F5        63     0      88     0      98     0      108
     F6        64     0      89     0      99     0      109
     F7        65     0      90     0      100    0      110
     F8        66     0      91     0      101    0      111
     F9        67     0      92     0      102    0      112
     F10       68     0      93     0      103    0      113
     F11       133    0      135    0      137    0      139
     F12       134    0      136    0      138    0      140
     np *      55     42     55     42     150    0      55
     np Home   71     0      71     55     119    0
     cp Home   71     224    71     224    119    224    151
     np Up     72     0      72     56     141    0
     cp Up     72     224    72     224    141    224    152
     np PgUp   73     0      73     57     132    0
     cp PgUp   73     224    73     224    132    224    153
     np Minus  74     45     74     45     142    0      74
     np Left   75     0      75     52     115    0
     cp Left   75     224    75     224    115    224    155
     np 5      76     0      76     53     143    0
     np Right  77     0      77     54     116    0
     cp Right  77     224    77     224    116    224    157
     np Plus   78     43     78     43     144    0      78
     np End    79     0      79     49     117    0
     cp End    79     224    79     224    117    224    159
     np Down   80     0      80     50     145    0
     cp Down   80     224    80     224    145    224    160
     np PgDn   81     0      81     51     118    0
     cp PgDn   81     224    81     224    118    224    161
     np Ins    82     0      82     48     146    0
     cp Ins    82     224    82     224    146    224    162
     np Del    83     0      83     46     147    0
     cp Del    83     224    83     224    147    224    163
     np /      224    47     224    47     149    0      164
     np Enter  224    13     224    13     224    10     166
:exmp.

.* --------------------------------------------------------------------------

:h3 name=KeyScanExpl.Key Codes and Scan Codes Explanation
:p.
(This section explains how key codes and scan codes work.  For a reference
chart, see the :link reftype=hd refid=KeyScan.Key Codes and Scan Codes Table:elink..)
:p.
When you press a single key or a key combination, OS/2 translates your
keystroke into two numbers&colon.  a scan code, representing the actual key
that was pressed, and an ASCII code, representing the ASCII value for that
key.  OS/2 returns these numbers the next time a program requests keyboard
input.  This section explains how key codes work; for information on using
them with &4OS2. see the :hp1.&4OS2INI.:ehp1. file
:link reftype=hd refid=INIKeyMap.key mapping directives:elink.,
:link reftype=hd refid=ALIAS.keystroke aliases:elink.,
and :link reftype=hd refid=INKEY.INKEY:elink..
:p.
Most &4OS2. 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 :link reftype=hd refid=KeyNames.Keys and Key Names:elink.
for more information.
:p.
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.
:p.
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 in the tables 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.
:p.
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 and have no ASCII value, but they do have a scan
code.  Some keys have more than one ASCII code.  The :hp2.A:ehp2., for
example, has ASCII code 97 (lower case "a") if you press it by
itself.  If you press it along with :hp2.Shift:ehp2., the ASCII code
changes to 65 (upper case "A").  If you press :hp2.Ctrl:ehp2. and :hp2.A:ehp2.
the ASCII code changes to 1.  In all these cases, the scan code
(30) is unchanged because you are pressing the same physical key.
:p.
Things are different if you press :hp2.Alt-A:ehp2..  :hp2.Alt:ehp2. keystrokes
have no ASCII code, so OS/2 returns an ASCII code of 0, along
with the :hp2.A:ehp2. key's scan code of 30.  This allows a program to
detect all the possible variations of :hp2.A:ehp2., based on the
combination of ASCII code and scan code.
:p.
Some keys generate more than one scan code depending on whether
:hp2.Shift:ehp2., :hp2.Ctrl:ehp2., or :hp2.Alt:ehp2. 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,
:hp2.F1:ehp2. has no ASCII value so it returns an ASCII code of 0, and the
:hp2.F1:ehp2. scan code of 59.  :hp2.Shift-F1:ehp2. also returns an ASCII code 0;
if it also returned a scan code of 59, a program couldn't
distinguish it from :hp2.F1:ehp2..  The operating system
translates scan codes for keys like :hp2.Shift-F1:ehp2. (and :hp2.Ctrl-F1:ehp2.
and :hp2.Alt-F1:ehp2.) so that each variation returns a different scan
code along with an ASCII code of 0.
:p.
On the 101-key keyboard there's one more variation&colon.  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 cursor pad 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.
:p.
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 operating system.  Some keys, like :hp2.Alt:ehp2.,
:hp2.Ctrl:ehp2., and :hp2.Shift:ehp2. by themselves or in combination
with each other, plus :hp2.Print Screen:ehp2., :hp2.SysReq:ehp2., :hp2.Scroll
Lock:ehp2., :hp2.Pause:ehp2., :hp2.Break:ehp2., :hp2.Num Lock:ehp2., and
:hp2.Caps Lock:ehp2. keys, do not have any code representations at all.  The
same is true of keystrokes with more than one modifying key, like
:hp2.Ctrl-Shift-A:ehp2..  The operating system may perform special actions
automatically when you press these keys (for example, it switches
into Caps Lock mode when you press :hp2.Caps Lock:ehp2.), 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.

.* --------------------------------------------------------------------------

:h3 name=ANSICODES.ANSI Codes
:p.
This section is a quick-reference to commonly-used ANSI commands.
:p.
An ANSI command string consists of three parts&colon.
:lm margin=8.:parml compact tsize=20 break=fit.
:pt.:hp2.ESC[:ehp2.:pd.The ASCII character ESC, followed by a left
bracket.  These two characters must be present
in all ANSI strings.
:pt.:hp2.parameters:ehp2.:pd.Optional parameters for the command.  If there
are multiple parameters they are separated by semicolons.
:pt.:hp2.cmd:ehp2.:pd.A single-letter command.  The case of the
letter IS meaningful.
:eparml.:lm margin=1.
.br
For example, to position the cursor to row 7, column 12 the ANSI
command is&colon.
:xmp.
        ESC[7;12H
:exmp.:p.
To transmit ANSI commands to the screen with &4OS2., you should use
the :link reftype=hd refid=ECHO.ECHO:elink. command.  The ESC character can be generated by
inserting it into the string directly (if you are putting the string in a
batch file and your editor will insert such a character), or by using
&4OS2.'s internal "escape" character (caret, [:hp2.^:ehp2.])
followed by a lower-case "e".  For example, the sequence shown
above could be transmitted from a batch file with either of these
commands (the first uses an ESC character directly; the second uses
^e)&colon.
:xmp.
        echo [7;12H
        echo ^e[7;12H
:exmp.:p.
You can also include ANSI commands in your prompt, using $e to
transmit the ESC character.  You can NOT use PROMPT to transmit
ANSI commands to the screen from a batch file (see
:link reftype=hd refid=PROMPT.PROMPT:elink.).
:p.
:p.
:hp2.Commands:ehp2.
:lm margin=8.:parml compact tsize=24 break=fit.
:pt.:hp2.ESC[rowsA:ehp2.:pd.Cursor up
:pt.:hp2.ESC[rowsB:ehp2.:pd.Cursor down
:pt.:hp2.ESC[colsC:ehp2.:pd.Cursor right
:pt.:hp2.ESC[colsD:ehp2.:pd.Cursor left
:pt.:hp2.ESC[row;colH:ehp2.:pd.Set cursor position (top left is row 1, column 1)
:pt.:hp2.ESC[2J:ehp2.:pd.Clear screen
:pt.:hp2.ESC[K:ehp2.:pd.Clear from cursor to end of line
:pt.:hp2.ESC[row;colf:ehp2.:pd.Set cursor position, same as "H" command
:pt.:hp2.ESC[attr;attr;...m:ehp2.:pd.Set display attributes; see table of attribute values below
:pt.:hp2.ESC[s:ehp2.:pd.Save cursor position (may not be nested)
:pt.:hp2.ESC[u:ehp2.:pd.Restore cursor position after a save
:eparml.:lm margin=1.
.br
:hp2.Display Attributes:ehp2.
:lm margin=8.:parml compact tsize=12 break=fit.
:pt.:hp2.0:ehp2.:pd.All attributes off (normal white on black)
:pt.:hp2.1:ehp2.:pd.High intensity (bold)
:pt.:hp2.2:ehp2.:pd.Normal intensity
:pt.:hp2.4:ehp2.:pd.Underline (usually effective only on monochrome displays)
:pt.:hp2.5:ehp2.:pd.Blinking
:pt.:hp2.7:ehp2.:pd.Reverse Video
:pt.:hp2.8:ehp2.:pd.Invisible
:pt.:hp2.30-37:ehp2.:pd.Set the foreground color&colon.
:pt.:pd.    30=Black   31=Red       32=Green   33=Yellow
:pt.:pd.    34=Blue    35=Magenta   36=Cyan    37=White
:pt.:hp2.40-47:ehp2.:pd.Set the background color, same values as above but substitute 40 for 30 etc.
:eparml.:lm margin=1.
.br
Settings are cumulative, so (for example) to set bright red
foreground set all attributes off, then set red, then bold, use&colon.
:xmp.
        echo ^e[0;31;1m
:exmp.:p.
:p.
:hp2.Examples:ehp2.
:p.
Clear the display attributes, then set the display to bright cyan
on blue, and clear the screen&colon.
:xmp.
        echo ^e[0;44;36;1m^e[2J
:exmp.:p.
Set up a prompt which saves the cursor position, displays the &4OS2.
shell level, date, and time on the top line in bright white on
magenta, and then restores the cursor position and sets the color
to bright cyan on blue, and displays the standard prompt&colon.
:xmp.
        prompt $e[s$e[1;1f$e[0;45;37;1m$e[K($z) $d $t$e[u$e[0;44;36;1m$p$g
:exmp.

.* --------------------------------------------------------------------------

:h2 name=Glossary.Glossary
:p.
The glossary contains over 200 terms, and is divided into sections by the
first letter of each term.  Select the section you want to review&colon.
:p.
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.

.* --------------------------------------------------------------------------

:h3 name=Glossary_4.Glossary - 4
:p.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.4EXIT:ehp2.&colon.  A batch file which is executed whenever &4OS2. exits.
:p.
:hp2.4START:ehp2.&colon.  A batch file which is executed whenever &4OS2. starts.

.* --------------------------------------------------------------------------

:h3 name=Glossary_A.Glossary - A
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Alias Parameter:ehp2.&colon.  A numbered variable (:hp1.e.g.:ehp1. %2)
included in an alias definition, allowing a different value to be used in
the alias each time it is executed.
:p.
:hp2.Alias:ehp2.&colon.  A shorthand name for a command or series of commands.
:p.
:hp2.AND:ehp2.&colon.  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.
:p.
:hp2.ANSI:ehp2.&colon.  Usually a reference to ANSI control sequences,
standardized sequences of text characters which control colors on the
screen, manipulate the cursor, and redefine keys.  OS2 includes support for
ANSI screen and cursor control sequences.  The abbreviation ANSI is for
American National Standards Institute, an organization whch sets standards
for computer-related systems, including "ANSI" screen control sequences.
:p.
:hp2.Append:ehp2.&colon.  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).
:p.
:hp2.Application:ehp2.&colon.  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.
:p.
:hp2.Archive:ehp2.&colon.  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
:hp1..ZIP:ehp1. file) which contains a number of other files in compressed
form.
:p.
:hp2.Argument:ehp2.&colon.  See :hp2.Parameter:ehp2..
:p.
:hp2.ASCII File:ehp2.&colon.  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.
:p.
:hp2.ASCII:ehp2.&colon.  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.
:p.
:hp2.Attribute:ehp2.&colon.  A characteristic of a file which can be set or
cleared.  The standard attributes are Read-Only, Hidden, System, and
Archive; other attributes include Directory and Volume Label.
:p.
:hp2.Automatic Batch Files:ehp2.&colon.  See :hp2.4START:ehp2. and
:hp2.4EXIT:ehp2..
:p.
:hp2.Automatic Directory Change:ehp2.&colon.  A &4OS2. feature which allows
you to change directories by typing the directory name and a backslash
[:hp2.\:ehp2.] at the prompt.

.* --------------------------------------------------------------------------

:h3 name=Glossary_B.Glossary - B
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Base Name:ehp2.&colon.  The file name without a drive, path, or
extension.  For example, in the file name
:hp1.C&colon.\DIR1\LETTER.DAT:ehp1. the base name is :hp1.LETTER:ehp1..
:p.
:hp2.BAT File:ehp2.&colon.  See :hp2.Batch File:ehp2..
:p.
:hp2.Batch File:ehp2.&colon.  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.  The extension of a batch file may be :hp1..BAT:ehp1.,
:hp1..CMD:ehp1., or :hp1..BTM:ehp1., depending on the operating system and
command processor you are using.
:p.
:hp2.Batch File Parameter:ehp2.&colon.  A numbered variable (:hp1.e.g.:ehp1.
%2) used within a batch file, allowing a different value to be used at that
spot in the file each time it is executed.
:p.
:hp2.Binary File:ehp2.&colon.  A file containing information which does not
represent or cannot sensibly be interpreted as text.  See also :hp2.ASCII
File:ehp2..
:p.
:hp2.BIOS:ehp2. or :hp2.Basic Input Output System:ehp2.&colon.  The software
(or "firmware") stored on chips inside PC systems.  The BIOS provides basic
low-level control of devices required to operate the system, such as the
keyboard, floppy disk, and screen; it also handles system self-tests at
startup, and intiates loading of the operating system.
:p.
:hp2.Block Device:ehp2.&colon.  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 :hp2.Character Device:ehp2..
:p.
:hp2.Boot Directory:ehp2.&colon.  The current directory at the time the
system is booted, usually the root directory of the boot drive.
:p.
:hp2.Boot Drive:ehp2.&colon.  The disk drive that the system is booted from,
usually A&colon. (the floppy disk) or C&colon. (the hard disk).
:p.
:hp2.Boot:ehp2.&colon.  The process of starting the computer and loading the
operating system into memory.  See also :hp2.Reboot:ehp2., :hp2.Cold
Reboot:ehp2., and :hp2.Warm Reboot:ehp2..
:p.
:hp2.Break:ehp2.&colon.  A signal sent to a program to tell it to halt what
it is doing.  The :hp2. Ctrl-C:ehp2. key  or :hp2.Ctrl-Break:ehp2. 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.
:p.
:hp2.BTM File:ehp2.&colon.  A special type of &4OS2. batch file which is loaded
into memory to speed up execution.
:p.
:hp2.Buffer:ehp2.&colon.  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.

.* --------------------------------------------------------------------------

:h3 name=Glossary_C.Glossary - C
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.CDFS or CD-ROM File System:ehp2.&colon.  The file system which supports
CD-ROM drives.  This is typically implemented as a distinct file system in
32-bit operating systems like OS/2 and Windows NT.  On other platforms it is
implemented as a component of or addition to the underlying general file
system for disk drives.
:p.
:hp2.Character Device:ehp2.&colon.  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
:hp2.Block Device:ehp2..
:p.
:hp2.Character Mode:ehp2.&colon.  A display mode in which output is
displayed in a fixed font, typically with 80 columns in a line and 25 lines
on the screen (some systems allow you to increase the number of rows and
columns to other fixed sizes), and which cannot display graphics or
pictures.  See also :hp2.Graphics Mode:ehp2..
:p.
:hp2.CMD File:ehp2.&colon.  See :hp2.Batch File:ehp2..
:p.
:hp2.CMDLINE:ehp2.&colon.  An environment variable used to extend the
command line passed to another program beyond its normal length limits.
:p.
:hp2.Cold Reboot:ehp2.&colon.  The process of restarting the computer in a
way that physically resets most hardware devices, typically by pressing a
reset button, or by turning the power off and back on.  See also :hp2.Warm
Reboot:ehp2..
:p.
:hp2.Command Completion:ehp2.&colon.  A &4OS2. 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.
:p.
:hp2.Command Echoing:ehp2.&colon.  A feature which displays commands as they
are executed.  Echoing can be turned on and off.
:p.
:hp2.Command Grouping:ehp2.&colon.  A &4OS2. feature which allows you to group
several commands with parentheses, and have them treated as a single command
for most purposes.
:p.
:hp2.Command History Window:ehp2.&colon.  A pop-up window used by &4OS2. to
display the command history, allowing you to choose a previous command to
modify and/or execute.
:p.
:hp2.Command History:ehp2.&colon.  A &4OS2. feature which retains commands you
have executed, so that they can be modified and re-executed later.
:p.
:hp2.Command Processor:ehp2.&colon.  A program which interprets commands and
executes other programs.  Sometimes also called a :hp2.Command
Interpreter:ehp2..
:p.
:hp2.Command Recall:ehp2.&colon.  See :hp2.Command History:ehp2..
:p.
:hp2.Command Separator:ehp2.&colon.  A character used to separate multiple
commands on the same command line.
:p.
:hp2.Command Tail:ehp2.&colon.  The portion of a command consisting of all
the arguments, :hp1.i.e.:ehp1., everything but the command name itself.
:p.
:hp2.Compound Command:ehp2.&colon.  See :hp2.Multiple Commands:ehp2..
:p.
:hp2.Compression:ehp2.&colon.  An operating system feature which compresses
data as it is stored in a disk file, and decompresses it as it is read back,
resulting in more efficient use of disk space (at a slight cost in processor
time to perform the compression and decompression).  More generally, an
approach to data storage which reduces repeated or redundant information to
a smaller number of bytes in the compressed version than in the original, in
order to minimize the space required to store the information.
:p.
:hp2.COMSPEC:ehp2.&colon.  An environment variable which defines where to
find the character-mode command processor to start a secondary shell.
:p.
:hp2.Conditional Commands:ehp2.&colon.  A &4OS2. feature allowing commands to
be executed or skipped depending on the results of a previous command.   See
also :hp2.Exit Code:ehp2..
:p.
:hp2.Console:ehp2.&colon.  The PC keyboard and display.
:p.
:hp2.Console Mode:ehp2.&colon.  See :hp2.Character Mode:ehp2..
:p.
:hp2.Control Character:ehp2.&colon.  A character which is part of the ASCII
code, but does not have a normal text representation, and which can usually
be generated by pressing the Ctrl key along with another key.
:p.
:hp2.Coprocessor:ehp2.&colon.  See :hp2.Numeric Coprocessor:ehp2..
:p.
:hp2.Country Settings:ehp2.&colon.  The internal settings which tell the
operating system how to interpret keyboard characters which vary from
country to country, which character set to use, and how to retrieve and
display date, time, and other information in the format appropriate to a
particular country.  See also :hp2.Code Page:ehp2..
:p.
:hp2.CPU:ehp2.&colon.  The Central Processing Unit which performs all logic
and most calculations in a computer.  In PC-compatible systems, the CPU is
on a single microprocessor chip.
:p.
:hp2.CR:ehp2. or :hp2.Carriage Return:ehp2.&colon.  The ASCII character
"carriage return" (decimal value 13), generated by pressing the
:hp2.Enter:ehp2. key on the keyboard, and stored in most ASCII files at the
end of each line.
:p.
:hp2.Critical Error:ehp2.&colon.  An error, usually related to a physical or
hardware problem with input, output, or network access, which prevents a
program from continuing.
:p.
:hp2.Current Directory:ehp2.&colon.  The directory in which all file
operations will take place unless otherwise specified.  The current
directory is typically displayed as part of the command prompt.  Also called
the :hp2.Current Working Directory:ehp2..
:p.
:hp2.Current Drive:ehp2.&colon.  The disk drive on which all file operations
will take place unless otherwise specified.  The current drive is typically
displayed as part of the command prompt.
:p.
:hp2.Cursor:ehp2.&colon.  A movable marker on the screen to show where text
will be entered when you type at the keyboard, or which object on the screen
will be affected when a mouse button is clicked.  In character mode only the
text cursor is available; graphical systems typically show both a mouse
cursor and, when text can be entered, a separate text cursor.

.* --------------------------------------------------------------------------

:h3 name=Glossary_D.Glossary - D
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Date Range:ehp2.&colon.  A &4OS2. feature which allows you to select
files based on the date and time they were last modified.
:p.
:hp2.Date Stamp:ehp2.&colon.  Information stored in a file's directory entry
to show the dates on which the file was created, last modified, and last
accessed.  Creation and last access dates are not available in the FAT file
system.  See also :hp2.Time Stamp:ehp2..
:p.
:hp2.Default Directory:ehp2.&colon.  See :hp2.Current Directory:ehp2.
:p.
:hp2.Default Drive:ehp2.&colon.  See :hp2.Current Drive:ehp2..
:p.
:hp2.Delete Tracking:ehp2.&colon.  An operating system or utility software
feature which is designed to allow you to "undelete" or recover files which
have recently been deleted.  Delete tracking typically works by temporarily
retaining the deleted files and/or information about the deleted files in a
special area of the disk.
:p.
:hp2.Description:ehp2.&colon.  A string of characters assigned to describe a
file with the &4OS2. DESCRIBE command.
:p.
:hp2.Destination:ehp2.&colon.  In file processing commands (:hp1.e.g.:ehp1.
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 :hp2.Source:ehp2..
:p.
:hp2.Detached Process:ehp2.&colon.  A program which is "detached" from the
normal means of user input and output, and cannot use the keyboard, mouse,
or video display.
:p.
:hp2.Device Driver:ehp2.&colon.  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.
:p.
:hp2.Device:ehp2.&colon.  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.
:p.
:hp2.Directive:ehp2.&colon.  An individual item in the :hp1.&4OS2INI.:ehp1.
file, used to control the configuration of &4OS2..
:p.
:hp2.Directory:ehp2.&colon.  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.
:p.
:hp2.Directory History:ehp2.&colon.  A &4OS2. feature which allows you to
recall recently-used directory names in a popup window, and choose one to
switch to.
:p.
:hp2.Directory History Window:ehp2.&colon.  See :hp2.Directory History:ehp2..
:p.
:hp2.Directory Stack:ehp2.&colon.  A &4OS2. feature, implemented through the
PUSHD and POPD commands, which allows you to save the current directory and
return to it later.  See also :hp2.Stack:ehp2..
:p.
:hp2.Directory Tree:ehp2.&colon.  The branching structure of directories on
a hard disk, starting at the root directory.  The root of the tree is
usually considered as the "top" of the structure, so the actual structure
can be visualized as an upside-down tree with the root at the top and
branches going "down".  A portion or branch of the directory tree is
sometimes called a "subtree".
:p.
:hp2.DOS Memory:ehp2.&colon.  See Base Memory.
:p.
:hp2.DOS Session:ehp2.&colon.  See Session.
:p.
:hp2.DPMI:ehp2. or :hp2.DOS Protected Mode Interface:ehp2.&colon.  A
specification which allows DOS programs to access memory beyond 1 MB in
order to manage larger programs or larger amounts of information than will
fit in base memory.  DPMI support for DOS programs is provided by some DOS
memory managers, and by OS/2, Windows 3.1 and above, Windows 95, and Windows
NT.
:p.
:hp2.Drive Letter:ehp2.&colon.  A letter used to designate a specific local
disk volume, or part or all of a network server drive.  In most cases drive
letters range from A - Z, but some network operating systems allow the use
of certain punctuation characters as drive letters in order to support more
than 26 volumes.

.* --------------------------------------------------------------------------

:h3 name=Glossary_E.Glossary - E
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Echo:ehp2.&colon.  See :hp2.Command Echoing:ehp2..
:p.
:hp2.Environment:ehp2.&colon.  An area of memory which contains multiple
entries in the form "NAME=value".  See also :hp2.Master Environment
:ehp2.and :hp2.Passed Environment:ehp2..
:p.
:hp2.Environment Variable:ehp2.&colon.  The name of a single entry in the
environment.
:p.
:hp2.Error Level:ehp2.&colon.  A numeric value between 0 and 255 returned
from an external command to indicate its result (:hp1.e.g.:ehp1., success,
failure, response to a question).  See also :hp2.Exit Code:ehp2..
:p.
:hp2.Escape Character:ehp2.&colon.  In some contexts, the &4OS2. 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.
:p.
:hp2.Escape Sequence:ehp2.&colon.  A sequence of text characters which has a
special meaning and is not treated as normal text.  For example, the
character sequence <ESC>]K (where <ESC> is the ASCII "escape" character,
decimal value 27) will cause an ANSI driver to clear the screen from the
cursor to the end of the current line, rather than simply displaying the
string "ESC]K" on the screen.  Similarly, in &4OS2., the escape sequence ^f on
the command line is translated to a form feed, and is not treated as the
literal characters "^f".
:p.
:hp2.Executable Extensions:ehp2.&colon.  A &4OS2. feature which allows you to
specify the application to be executed when a file with a particular
extension is named at the command prompt.
:p.
:hp2.Executable File:ehp2.&colon.  A file, usually with the extension
:hp1..COM:ehp1. or :hp1..EXE:ehp1., which can be loaded into memory and run
as a program.
:p.
:hp2.Exit Code:ehp2.&colon.  The result code returned by an external command
or an internal command.  &4OS2. internal commands return an exit code of 0 if
successful, or non-zero if unsuccessful.  See also :hp2.Errorlevel:ehp2..
:p.
:hp2.Expansion:ehp2.&colon.  The process &4OS2. goes through when it scans a
command line and substitutes the appropriate actual values for aliases,
alias parameters, batch file parameters, and environment variables.  See
also :hp2.Parsing:ehp2..
:p.
:hp2.Extended ASCII Character:ehp2.&colon.  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.
:p.
:hp2.Extended Attributes:ehp2.&colon.  An OS/2 High Performance File System
(HPFS) feature which allows storage of additional information about a file,
separate from the file itself.  Extended attributes are typically used to
store icons for executable files, property or settings information, and
other information added by the user.
:p.
:hp2.Extended Directory Search:ehp2.&colon.  A &4OS2. feature which maintains
a directory search "database" or list, typically including all directories
in your system, and allows you to change quickly to any directory in the list.
:p.
:hp2.Extended Key Code:ehp2.&colon.  The code for a key on the PC keyboard
which has no representation in the standard ASCII character set, such as a
function key, cursor key, or :hp2.Alt:ehp2. plus another key.  The extended
key code for a key is often the same as the scan code for that key.
:p.
:hp2.Extended Memory:ehp2.&colon.  Any memory on a computer system with a
286, 386, 486, or Pentium processor which is above the first 1 MB (one
megabyte, or 1024*1024 bytes) of memory.  See also :hp2.XMS:ehp2..
:p.
:hp2.Extended Parent Directory Names:ehp2.&colon.  A &4OS2. feature which
allows you to use additional periods in a directory name to represent
directories which are successively higher in the directory tree.
:p.
:hp2.Extended Wildcard:ehp2.&colon.  A &4OS2. feature which extends the
traditional wildcard syntax and allows you to use multiple wildcard
characters, and character ranges (:hp1.e.g.:ehp1. [a-f] for the letters A
through F).  See also :hp2.Wildcard:ehp2..
:p.
:hp2.Extension:ehp2.&colon.  The final portion of a file name, preceded by a
period.  For example, in the file name :hp1.C&colon.\DIR1\LETTER.DAT:ehp1.
the extension is :hp1..DAT:ehp1..  In a long filename which contains
multiple periods, the extension is usually considered to be the portion of
the name after the final period.
:p.
:hp2.External Command:ehp2.&colon.  A program which resides in an executable
file, as opposed to an internal command which is part of the command
processor.
:p.
:hp2.EXTPROC:ehp2.&colon.  A command processor feature which allows you to
designate a specific external program to run a particular batch file.

.* --------------------------------------------------------------------------

:h3 name=Glossary_F.Glossary - F
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.FAT File System:ehp2.&colon.  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 :hp2.F:ehp2.ile :hp2.A:ehp2.llocation :hp2.T:ehp2.able
to keep track of allocated and unallocated space on the disk.
:p.
:hp2.FAT-Compatible File Name:ehp2.&colon.  See :hp2.SFN:ehp2..
:p.
:hp2.FF:ehp2. or :hp2.Form Feed:ehp2.&colon.  The ASCII character "form
feed" (decimal value 12), which typically causes a printer to skip to a new
page.  The FF character is not normally entered from the keyboard, but in
many cases it can be generated, if necessary, by holding the Alt key,
pressing 0-1-2, and releasing the Alt key.
:p.
:hp2.File Attribute:ehp2.&colon.  See :hp2.Attribute:ehp2..
:p.
:hp2.File Description:ehp2.&colon.  See :hp2.Description:ehp2..
:p.
:hp2.File Exclusion Range:ehp2.&colon.  A &4OS2. feature which allows you to
exclude files from processing by internal commands based on their names.
:p.
:hp2.Filename Completion:ehp2.&colon.  A &4OS2. 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.
:p.
:hp2.Free Memory:ehp2.&colon.  Usually, the amount of total memory which is
unoccupied and available for applications.

.* --------------------------------------------------------------------------

:h3 name=Glossary_G.Glossary - G
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Global Aliases:ehp2.&colon.  A &4OS2. option which allows you to store
aliases in a global area accessible to all copies of &4OS2., so that any
change made by one copy is immediately available to all other copies.  See
also :hp2.Local Aliases:ehp2..
:p.
:hp2.Global Directory History:ehp2.&colon.  An option which allows you to
store the directory history in a global area accessible to all copies of
&4OS2., so that any change made by one copy is immediately available to all
other copies.  See also :hp2.Local Directory History:ehp2..
:p.
:hp2.Global History:ehp2.&colon.  A &4OS2. option which allows you to store
the command history in a global area accessible to all copies of &4OS2., so
that any change made by one copy is immediately available to all other
copies.  See also :hp2.Local History:ehp2..
:p.
:hp2.Graphics Mode:ehp2.&colon.  A display mode in which output is displayed
in any one of a range of fonts, typically in resizable windows with a
variable number of text rows and columns, and which supports the display of
graphics and pictures along with text.  See also :hp2.Character Mode:ehp2..

.* --------------------------------------------------------------------------

:h3 name=Glossary_H.Glossary - H
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Hidden:ehp2.&colon.  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.
:p.
:hp2.History Window:ehp2.&colon.  See :hp2.Command History Window:ehp2. and
:hp2.Directory History:ehp2..
:p.
:hp2.History:ehp2.&colon.  See :hp2.Command History:ehp2..
:p.
:hp2.HMA:ehp2. or :hp2.High Memory Area:ehp2.&colon.  The area of PC memory
located in the first 64K bytes above the 1 megabyte that DOS can address
directly.  The HMA can be made addressable from DOS programs using special
hardware facilities, or an XMS driver.
:p.
:hp2.HPFS:ehp2. or :hp2.High Performance File System:ehp2.&colon.  A file
system distributed with OS/2 and Windows NT 3.51 and below which allows
longer file names, supports larger drives, and provides better performance
than the traditional FAT file system.

.* --------------------------------------------------------------------------

:h3 name=Glossary_I.Glossary - I
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.IFS:ehp2. or :hp2.Installable File System:ehp2.&colon.  A file system
which can be loaded when required to support devices such as CD-ROM or
network drives, or non-default disk formats like HPFS (in OS/2) or NTFS (in
Windows NT).  Installable file systems are primarily supported 32-bit
operating systems like OS/2 and Windows NT.  Depending on operating system
design they may be loaded at boot time, or loaded and unloaded dynamically
while the system is running.
:p.
:hp2.Include List:ehp2.&colon.  A concise method of specifying several files
or groups of files in the same directory, for use with all &4OS2. commands
which take file names as arguments.
:p.
:hp2.Inheritance:ehp2.&colon.  A feature which allows one copy of &4OS2. to
"inherit" the :hp1..INI:ehp1. file data, aliases, command history, and
directory history from a previous copy.  More generally, a system which
allows one program to pass information or settings on to another, often to a
second copy of the same program.
:p.
:hp2..INI File:ehp2.&colon.  The &4OS2. initialization file containing
directives which set the initial configuration of the command processor.
:p.
:hp2.Insert Mode:ehp2.&colon.  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 :hp2.Overstrike
Mode:ehp2..
:p.
:hp2.Internal Command:ehp2.&colon.  A command which is part of the command
processor, as opposed to an external command.
:p.
:hp2.Internal Variables:ehp2.&colon.  Environment variables created by &4OS2.
to provide information about your system.  Internal variables are evaluated
each time they are used, and are not actually stored in the environment.

.* --------------------------------------------------------------------------

:h3 name=Glossary_K.Glossary - K
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Key Code:ehp2.&colon.  The code passed to a program when a key is
pressed on the keyboard.  Depending on the key that is pressed, and the
software handling the keyboard, the code can be an ASCII code, a scan code,
or an extended key code.
:p.
:hp2.Key Mapping:ehp2.&colon.  A &4OS2. feature which allows you to assign new
keystrokes for command line functions such as manipulating the command
history or completing file names.
:p.
:hp2.Keyboard Buffer:ehp2.&colon.  A buffer which holds keystrokes you have
typed that have not yet been used by the currently executing program.
:p.
:hp2.Keystroke Alias:ehp2.&colon.  An alias assigned to a key, so that it
can be invoked or recalled with a single keystroke.

.* --------------------------------------------------------------------------

:h3 name=Glossary_L.Glossary - L
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Label:ehp2.&colon.  A marker in a batch file, with the format
:hp2.&colon.name:ehp2., allowing GOTO and GOSUB commands to "jump" to that
point in the file.  See also :hp2.Volume Label:ehp2..
:p.
:hp2.LF:ehp2. or :hp2.Line Feed:ehp2.&colon.  The ASCII character "line
feed" (decimal value 10), stored in most ASCII files at the end of each
line, after the CR character.  The LF character is not normally entered from
the keyboard, but in many cases it can be generated, if necessary, by
pressing Ctrl-Enter.
:p.
:hp2.Local Aliases:ehp2.&colon.  A &4OS2. option which allows you to store
aliases in a local area only accessible to the current copy of &4OS2., so that
a change made in the current copy of &4OS2. does not affect other copies, and
vice versa.  See also :hp2. Global Aliases:ehp2..
:p.
:hp2.Local Directory History:ehp2.&colon.  A &4OS2. option which allows you to
store the directory history in a local area only accessible to the current
copy of &4OS2., so that a change made in the current copy of &4OS2. does not
affect other copies, and vice versa.  See also :hp2.Global Directory
History:ehp2..
:p.
:hp2.Local History:ehp2.&colon.  A &4OS2. option which allows you to store the
command history in a local area only accessible to the current copy of &4OS2.,
so that a change made in the current copy of &4OS2. does not affect other
copies, and vice versa.  See also :hp2. Global History:ehp2..
:p.
:hp2.Logging:ehp2.&colon.  A &4OS2. feature, implemented via the LOG command,
which allows you to save a record of the commands you execute.

.* --------------------------------------------------------------------------

:h3 name=Glossary_M.Glossary - M
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Master Environment:ehp2.&colon.  The master copy of the environment
maintained by the command processor.
:p.
:hp2.Modulo:ehp2.&colon.  The remainder after an integer division.  For
example 11 modulo 3 is 2, because when 11 is divided by 3 the remainder is 2.
:p.
:hp2.Multiple Commands:ehp2.&colon.  A &4OS2. feature which allows multiple
commands to be placed on a line, separated by an ampersand
[:hp2.&amp.:ehp2.], or another, user-defined character.
:p.
:hp2.Multitasking:ehp2.&colon.  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 operating environments like Windows 3, and
complete operating systems like OS/2, Windows 95, and Windows NT.

.* --------------------------------------------------------------------------

:h3 name=Glossary_N.Glossary - N
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Network:ehp2.&colon.  A system which allows several computers to be
connected together to share files, printers, modems, or other resources, and
to pass electronic mail or other information between the systems on the
network.
:p.
:hp2.Network File System:ehp2.&colon.  Software which runs over a network to
allow access to files on the server.  A network file system may support the
same options as the file system used on local drives, or it may be more or
less restrictive than the local file system about file names, disk volume
capacity, and other similar features.
:p.
:hp2.NTFS :ehp2.or:hp2. New Technology File System:ehp2.&colon.  A file
system distributed with Windows NT which allows longer file names, supports
larger drives, and provides better performance than the traditional FAT file
system.
:p.
:hp2.Numeric Coprocessor:ehp2.&colon.  A chip which works in conjunction
with an Intel 8086, 80286, 80386, 80486, or Pentium CPU to perform decimal
arithmetic ("floating point") calculations.  Some 80486s and the Pentium CPU
have the numeric coprocessor built in to the CPU chip; in all other cases it
is on a physically separate chip, and is optional (when the coprocessor is
not avilable, the CPU performs decimal arithmetic through other, much slower
methods).

.* --------------------------------------------------------------------------

:h3 name=Glossary_O.Glossary - O
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Operating System:ehp2.&colon.  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.
:p.
:hp2.Option:ehp2.&colon.  See :hp2.Switch:ehp2..
:p.
:hp2.OR:ehp2.&colon.  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.
:p.
:hp2.Overstrike Mode:ehp2.&colon.  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 :hp2.Insert
Mode:ehp2..

.* --------------------------------------------------------------------------

:h3 name=Glossary_P.Glossary - P
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Parameter:ehp2.&colon.  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.
:p.
:hp2.Parent Directory:ehp2.&colon.  The directory in which a particular
subdirectory resides, often seen as the directory "above" a subdirectory.
:p.
:hp2.Parsing:ehp2.&colon.  The process &4OS2. performs to analyze the command
line, perform alias and environment variable expansion, and find the
appropriate internal command or external command to execute.  More
generally, the process of breaking down a string or message into its
individual components in order to process them properly.
:p.
:hp2.Passed Environment:ehp2.&colon.  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.
:p.
:hp2.Path:ehp2.&colon.  A specification of all the directories a file
resides in.  For example, the path for
:hp1.C&colon.\WPFILES\MYDIR\MEMO.TXT:ehp1. is
:hp1.C&colon.\WPFILES\MYDIR\:ehp1..  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.
:p.
:hp2.Pipe:ehp2.&colon.  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
:hp2.Redirection:ehp2..
:p.
:hp2.Previous Working Directory:ehp2.&colon.  The working directory used
most recently, just prior to the current working directory.  For example, if
:hp1.C&colon.\DATA :ehp1.is the current working directory and you switch to
:hp1.D&colon.\UTIL:ehp1., :hp1.C&colon.\DATA:ehp1. then becomes the previous
working directory.
:p.
:hp2.Primary Shell:ehp2.&colon.  The copy of the character-mode command
processor which is loaded by the operating system when the system boots or a
session opens.

.* --------------------------------------------------------------------------

:h3 name=Glossary_R.Glossary - R
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.RAM:ehp2. or :hp2.Random Access Memory:ehp2.&colon.  The physical
memory used to store data while a computer is operating.  The information in
most types of RAM is lost when power is turned off.
:p.
:hp2.RAM Disk:ehp2.&colon.  A pseudo "disk drive", created by software,
which appears like a normal physical disk drive to programs.  Sometimes also
called a :hp2.Virtual Disk:ehp2..
:p.
:hp2.Range:ehp2.&colon.  See :hp2.Date Range:ehp2., :hp2.Size Range:ehp2.,
:hp2.Time Range:ehp2., and :hp2.File Exclusion Range:ehp2..
:p.
:hp2.Read-Only:ehp2.&colon.  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.
:p.
:hp2.Reboot:ehp2.&colon.  The process of restarting the computer with
software, with the keyboard (:hp1.e.g. :ehp1.by pressing Ctrl-Alt-Del), by
pressing a reset button, or by turning the power off and back on.  See also
:hp2.Cold Reboot :ehp2.and :hp2.Warm Reboot:ehp2..
:p.
:hp2.Redirection:ehp2.&colon.  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 :hp2.Pipe:ehp2..
:p.
:hp2.REXX:ehp2.&colon.  A file and text processing language developed by
IBM, and available on many PC and other platforms.
:p.
:hp2.ROM:ehp2. or :hp2.Read Only Memory:ehp2.&colon.  A physical memory
device used to store information which cannot be readily modified, such as
the BIOS built into each PC system.  The information in ROM is typically
retained when power is turned off.
:p.
:hp2.Root Directory:ehp2.&colon.  The first directory on any disk, from
which all other directories are "descended."  The root directory is
referenced with a single backslash [:hp2.\:ehp2.].

.* --------------------------------------------------------------------------

:h3 name=Glossary_S.Glossary - S
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Scan Code:ehp2.&colon.  The physical code for a key on the PC
keyboard.  For the original U.S. English keyboard layout the scan code
represents the physical position of the key, starting with 1 for the key in
the upper left corner (Esc), and increasing from left to right and top to
bottom.  This order will vary for more recent keyboards or those designed
for other countries or languages.
:p.
:hp2.Search Path&colon.  :ehp2.See :hp2.PATH:ehp2..
:p.
:hp2.Secondary Shell:ehp2.&colon.  A copy of the command processor which is
started by another program, rather than by the operating system.
:p.
:hp2.Session:ehp2.&colon.  A general term for the individual windows or
tasks started by a multitasking system.  For example, under OS/2 you
might run a DOS application in one session, and &4OS2. in another.
:p.
:hp2.Shell:ehp2.&colon.  See :hp2.Command Processor:ehp2..  Also used to
refer to a program which gives access to operating system functions and
commands through a menu- or mouse-driven system, or which replaces the
primary user interface of the operating system.
:p.
:hp2.Size Range:ehp2.&colon.  A &4OS2. feature which allows you to select
files based on their size.
:p.
:hp2.Source:ehp2.&colon.  In file processing commands (:hp1.e.g.:ehp1. COPY
or MOVE), the original files before any copying or modification has taken
place, :hp1.i.e.:ehp1., those specified earlier on the command line.  See
also :hp2.Destination:ehp2..
:p.
:hp2.Stack:ehp2.&colon.  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.
:p.
:hp2.Standard Error, Standard Input,:ehp2. and :hp2.Standard
Output:ehp2.&colon.  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
normally refer to the console, unless redirection is used.
:p.
:hp2.Subdirectory:ehp2.&colon.  Any directory other than the root directory.
:p.
:hp2.Subtree:ehp2.&colon.  See :hp2.Directory Tree:ehp2..
:p.
:hp2.Swap File:ehp2.&colon.  A disk file created by an operating system or a
program to store unused information on disk, and thereby free up memory for
other purposes.
:p.
:hp2.Switch:ehp2.&colon.  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".
:p.
:hp2.System:ehp2.&colon.  A file attribute indicating that the file belongs
to the operating system or command processor, and should not be accessed by
other programs.

.* --------------------------------------------------------------------------

:h3 name=Glossary_T.Glossary - T
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Target:ehp2.&colon.  See :hp2.Destination:ehp2..
:p.
:hp2.Time Range:ehp2.&colon.  A &4OS2. feature which allows you to select
files based on the time they were last modified.
:p.
:hp2.Time Stamp:ehp2.&colon.  Information stored in a file's directory entry
to show the times at which the file was created, last modified, and last
accessed.  Creation time is not available in the FAT file system; last
access time is only available in the HPFS and NTFS file systems.  See also
:hp2.Date Stamp:ehp2..
:p.
:hp2.Tree:ehp2.&colon.  See :hp2.Directory Tree:ehp2..

.* --------------------------------------------------------------------------

:h3 name=Glossary_U.Glossary - U
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.UMB:ehp2. or :hp2.Upper Memory Block:ehp2.&colon.  An XMS Upper Memory
Block, whose address is above the end of base memory (normally, above 640K),
but within the 1 megabyte of memory that DOS can address directly.
:p.
:hp2.UNC:ehp2. or :hp2.Universal Naming Convention:ehp2.&colon.  A common
method for accessing files on a network drive without using a "mapped" drive
letter.  Names specified this way are called UNC names, and typically appear
as :hp2.\\server\volume\path\filename:ehp2., where :hp2.server:ehp2. is the
name of the network server where the files reside, :hp2.volume :ehp2. is the
name of a disk volume on that server, and the :hp2.path\filename:ehp2.
portion is a directory name and file name.

.* --------------------------------------------------------------------------

:h3 name=Glossary_V.Glossary - V
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Variable Expansion:ehp2.&colon.  The process of scanning a command line
and replacing each environment variable name, alias parameter, or batch file
parameter with its value.
:p.
:hp2.Variable Functions:ehp2.&colon.  Functions provided by &4OS2. to
manipulate strings, dates, and filenames; perform arithmetic; read and write
files; and perform other similar functions.  Variable functions are similar
to static environment variables or internal variables, but have parameters
and can perform actions rather than just returning static information.
:p.
:hp2.Variable:ehp2.&colon.  See :hp2.Alias Parameter:ehp2., :hp2.Batch File
Parameter:ehp2., and :hp2.Environment Variable:ehp2..
:p.
:hp2.Virtual Disk:ehp2.&colon.  See :hp2.RAM Disk:ehp2..
:p.
:hp2.Volume Label:ehp2.&colon.  A special, hidden file placed on any disk,
whose name constitutes a "label" for the entire disk.
:p.
:hp2.Volume&colon.  :ehp2.See :hp2.Disk Drive:ehp2..

.* --------------------------------------------------------------------------

:h3 name=Glossary_W.Glossary - W
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_X.X:elink.
:p.
:p.
:hp2.Warm Reboot:ehp2.&colon.  The process of restarting the computer with
software, or with the keyboard (:hp1.e.g. :ehp1.by pressing Ctrl-Alt-Del),
typically without physically resetting any hardware devices.  See also
:hp2.Cold Reboot:ehp2..
:p.
:hp2.White Space Character:ehp2.&colon.  A character used to separate
arguments on the command line.  The white space characters recognized by
&4OS2. are the space, tab, and comma.
:p.
:hp2.Wildcard:ehp2.&colon.  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
:hp2.Extended Wildcard:ehp2..
:p.
:hp2.Windows NT File System:ehp2.&colon.  See :hp2.NTFS:ehp2..

.* --------------------------------------------------------------------------

:h3 name=Glossary_X.Glossary - X
:p.
:link reftype=hd refid=Glossary_4.4:elink.
:link reftype=hd refid=Glossary_A.A:elink.
:link reftype=hd refid=Glossary_B.B:elink.
:link reftype=hd refid=Glossary_C.C:elink.
:link reftype=hd refid=Glossary_D.D:elink.
:link reftype=hd refid=Glossary_E.E:elink.
:link reftype=hd refid=Glossary_F.F:elink.
:link reftype=hd refid=Glossary_G.G:elink.
:link reftype=hd refid=Glossary_H.H:elink.
:link reftype=hd refid=Glossary_I.I:elink.
:link reftype=hd refid=Glossary_K.K:elink.
:link reftype=hd refid=Glossary_L.L:elink.
:link reftype=hd refid=Glossary_M.M:elink.
:link reftype=hd refid=Glossary_N.N:elink.
:link reftype=hd refid=Glossary_O.O:elink.
:link reftype=hd refid=Glossary_P.P:elink.
:link reftype=hd refid=Glossary_R.R:elink.
:link reftype=hd refid=Glossary_S.S:elink.
:link reftype=hd refid=Glossary_T.T:elink.
:link reftype=hd refid=Glossary_U.U:elink.
:link reftype=hd refid=Glossary_V.V:elink.
:link reftype=hd refid=Glossary_W.W:elink.
:p.
:p.
:hp2.XOR :ehp2.(exclusive OR)&colon.  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.
.* --------------------------------------------------------------------------
:euserdoc.
