Command Conventions

When you invoke an AmigaDOS command, you usually do more than enter the command name at a Shell prompt. Many commands require arguments or support options that send the AmigaOne additional information as to what you want to do. For example, if you enter:

The following commands have corresponding pages to explain their use. For AmigaDOS derived commands, it uses a format adapted from the original Amiga manuals, while GPL derived commands uses a slightly different format, as follows:

Purpose	A short explanation of the command's function.
Format	All the arguments and options accepted by an AmigaDOS derived command.
Template	A built-in reminder of the command format for an AmigaDOS derived command. The template is embedded in the program's code. If you enter a command followed by a question mark (DIR ?), the template will appear on the screen.
Path	The directory where the command is normally stored. For most commands this will be the C: directory. The exceptions are the Internal commands, which are copied into ROM, and the Workbench programs.
Specification	A description of the command and all of it arguments.
Examples	Where examples are given, the command and any screen output are displayed in a san-serif font to distinguish them from the main text. A generic 3.OS4:> prompt indicates what should be entered at the Shell prompt. All command names and arguments are CAPITALISED for clarity. Case does not matter when entering commands. To execute the command line, you must press <Enter>.

Remember, commands and arguments should be separated by spaces. (it does not have to be just one space; multiple spaces are acceptable.) No other punctuation should be used unless it is called for in the syntax of the specific command.

Return to Commands Selection

Format

In the Format listings, arguments are enclosed in different kinds of brackets to indicate the type of argument. The brackets are not to be entered as part of the command.

< >	Angle brackets enclose arguments that must be provided. For example, <filename> means that you must enter the appropriate filename in that position. Unless square brackets surround the argument (see below), the argument is required. The command will not work unless it is specified.
[ ]	Square brackets enclose arguments and keywords that are optional. They will be accepted by the command but are not required.
{ }	Braces enclose items that can be given once or repeated any number of times. For example, {<args>} means that several items may be given for this argument.
|	A vertical bar is used to separate options from which you can choose only one. For example, [OPT R | S | RS] means that you can choose the R option, the S option or the RS option.

The Format for the COPY command is shown below:

[FROM] is an optional keyword. If it is not specified, the command reads the filename or pattern to copy from by its position in the command line.

{<name | pattern>} is a mandatory multi-value argument, meaning that at least one <name> or <pattern> argument must be provided, to identify the objects to be copied. Multiple objects can be specified as long as they are separated by a space.

[TO] is another optional keyword. If it is not specified, the command reads the filename or pattern to copy to by its position in the command line.

<name | pattern> is a mandatory single-value argument, meaning that one, and only one, <name> or <pattern> argument must be provided to specify the destination.

The [ALL], [CLONE], [DATES], [FORCE] and [NEWER] arguments are all optional keywords.

The [Q | QUIET], [NOPRO | NOPROTECTION], [COM | COMMENTS], [NOREQ | NOREQUESTERS], [NOREP | NOREPLACE], [INTER | INTERACTIVE] and [ARC | ARCHIVE] arguments are optional keywords where alternate keywords are available which mean the same thing so you can use either keyword. For example, Q and QUIET are equivalent.

Finally, [BUF | BUFFER <n>] is an optional keyword argument that requires a value to be specified. If given, you can use either BUF or BUFFER but it must be followed by a numeric argument. For example, both BUF 5 and BUFFER 5 are acceptable.

Return to Commands Selection

Template

The Template is more condensed than the Format and is built into the system. If you enter a question mark (?) after a command, the Template will appear to remind you of the proper syntax.

In Template listings, arguments are separated by commas and followed by a slash (/) and a capital letter which indicates the type of argument. The slash/letter combinations, which are not to be entered as part of the command, are explained below:

argument/A	The argument must always be given.
option/K	The option's keyword must be used if the argument is given.
option/S	The option works as a switch. You must enter the name of the option in order to specify that option. Most options are switches.
option/T	The option works as a toggle. You must enter the name of the option and the toggle value. Most values toggle between YES and NO or ON and OFF or sometimes all of them where YES and ON are equivalent.
value/N	The argument is numeric.
argument/M	Multiple arguments are accepted. This is the Template equivalent of braces. There is no limit on the number of possible arguments. However, the multiple arguments must be given before any other argument or option.
string/F	The string must be the final argument on the command line. The remainder of the command line is taken as the desired string. Quotation marks (") are not needed around the string, even if it contains spaces. If you enter quotation marks, they will be passed to the command. If you specify the keyword, you can pass leading and trailing spaces.
=	An equals sign indicates that two different forms of the keyword are equivalent. Either will be accepted. The equals sign is not entered as part of the command.

The Template for the COPY command is shown below:

TO/A indicates that the argument must always be given.

ALL/S, CLONE/S, DATES/S, FORCE/S and NEWER/S indicate that the keywords act as switches. If the keyword is present in the line, the option will be used.

Q=QUIET/S, NOPRO=NOPROTECTION/S, COM=COMMENTS/S, NOREQ=NOREQUESTERS/S, NOREP=NOREPLACE/S, INTER=INTERACTIVE/S and ARC=ARCHIVE/S indicate that the keywords act as switches, and that either keyword can be used. If the either version of the keyword is present in the line, the option will be used.

BUF=BUFFER/K/N indicates that a numerical (/N) argument must be given if the either version of the keyword (/K) is used. Both BUF and BUFFER are acceptable keywords (=).

Generally you can link keywords and their arguments with an equal sign (=) which serves to ensure correct assignments in complex cases. For example, BUF=20.

Return to Commands Selection

Pattern Matching

Pattern matching allows you to specify filenames by using special wildcard characters to match characters in the filenames. This lets you work on multiple files with one command. For example, you can copy or rename all the files that begin with a specific letter, end with the same prefix, or reside in the same directory, all with one command.

Several different wildcards allow you to specify the type of match. To remove the special effect of these characters and search for a wildcard character, preface the character with an apostrophe ('). For example, '? will match ?, and '' (two single apostrophes) will match '. In the list below, a <p> indicates that either a single or multiple character string immediately adjacent to the wildcard will be matched. The wildcards are:

?	Matches any single character.
#<p>	Matches zero or more occurrences of <p>.
<p1>|<p2>	Matches if <p1> or <p2> matches.
~<p>	Matches everything but <p>.
(<p1><p2>...)	Groups items together.
%	Matches the null string.
<p>–<p>	Delimits a character range.

For example:

A?B	Matches any three letter name beginning with A and ending with B, such as AcB, AzB and alb.
A#BC	Matches any name beginning with A, ending with C, and having any number of Bs in between, such as AC, ABC, ABBC, ABBBC.
ABC#?	Matches any name beginning with ABC, regardless of what follows, such as ABCD, ABCDEF.info or ABCXYZ.
#?XYZ	Matches any name ending in XYZ, regardless of what precedes it, such as ABCXYZ and ABCDEFXYZ.
A(B|C)D	Matches ABD or ACD.
~(XYZ)	Matches anything but XYZ.
~(#?XYZ)	Matches anything not ending in XYZ.
A#(BC)	Matches any name beginning with A followed by any number of BC combinations, such as ABC, ABCBC, and ABCBCBC.
A(B|D|%)#C	Matches ABC, ADC, AC (% is the null string), ABCC, ADCC, ACCC etc.
[A–D]#?	Matches any name beginning with A, B, C or D.

The most frequently used combination is #? (matches any characters). Note that #? is equivalent to the * wildcard used by some other computer systems. For example, to delete all the .info files in the Picture directory, you would enter:

Return to Commands Selection

AmigaOS environment variables

The AmigaOS shell both consults and changes certain environment variables while it processes commands. Here is a complete list:

Echo	If this is set to ON, TRUE or 1, each command line will be printed before it is executed.
Interactive	If this is set to ON, TRUE or 1, you will have to confirm every command before it is executed.
KeepDoubleQuotes	When the command line is passed to a helper command, such as RX (for launching ARexx scripts), it may be enclosed in double quotes, if necessary. If the KeepDoubleQuotes variable is set to ON, TRUE or 1 any double quotes on the command line will remain unchanged, otherwise they will be removed.
OldRedirect	If this is set to ON, TRUE or 1, redirection for the commands Run, Pipe and Alias will be disabled and redirection of the standard error output stream will be disallowed.
Process	This is set to the CLI process number of this shell (which you can check with the STATUS command).
RC	This is set to the failure code of the last command invoked, e.g. 0 for success and 10, 20, etc. for failure.
Result2	This is set to the error code set by the last command invoked. The WHY command will consult this and print the error message corresponding to the code.
VIEWER	The name of the command to invoke for a picture, sound, animation, text or data file, if the DataTypes system feels responsible for a file. For example, if you set "VIEWER" to "MultiView" and then enter the name of a picture file on the command line, then the shell will automatically invoke the "MultiView" command on it.
_DefaultStack	The default stack size with which shell commands are started, as maintained by the STACK command.
_FailLevel	The minimum failure level that has to be raised by a shell command before execution of a script file is aborted, as maintained by the FAILAT command.
_mchar	The character(s) which ties together several programs whose output should be merged with the output of the next program in the command line.
_pchar	The character(s) which ties together several programs whose input should be fed into the output of the next program in the command line.
_Prompt	The text that is displayed when the shell prompts you to enter the next command, as maintained by the PROMPT command.
_RunTime	This is set to the amount of time it took to execute the last command. Only actual execution time is counted and not how long it took to load the command. That number is given as the number of seconds, followed by an optional decimal point and the fraction of a second, e.g. "12.34".
_ScriptFile	The name of the script file currently being processed, as started by using the EXECUTE command.
_ScriptLine	The current line number of the script file being processed, as started by using the EXECUTE command.
_ShellVersion	Version and revision number of the shell executing your command or script file, e.g. "51.49".
_Title	The shell window title to be used; it supports the same formatting commands as the shell prompt.
_verbosity	If this is set to ON, TRUE or 1, the shell will not try to display any error messages - equivalent to specifying QUIET for every command.
_WarpUP_Kludge	If this is set to ON, TRUE or 1, the shell will not try to release any signals which the previous command allocated but neglected to release when it returned. This must be done for WarpUP programs which will otherwise cause the shell to hang.

Return to Commands Selection