Copyright (c) Hyperion Entertainment and contributors.

AmigaOS Manual: AmigaDOS Command Reference

From AmigaOS Documentation Wiki
Jump to navigation Jump to search

The commands in this chapter are executed from the Shell window. They are described in alphabetic order; however, some commands reserved for system use appear together at the end of the chapter.

Command Documentation

Each command documented in this manual is shown with the format, arguments, options, symbols, and abbreviations required for proper use.

This chapter and Chapter 7 provide command specifications for the AmigaDOS commands and the Workbench programs accessible through the Shell using the following standard outline:

Format
All the arguments and options accepted by a command. The special characters that indicate the particular type of argument are described on page 6-6.
Template
An optional on-line reminder of the command's format that is embedded in the program's code. Entering a command followed by a space and a question mark (for example, DIR ?) displays the template. A complete description of the template notation is found on page 6-8.
Location
The directory where the command is normally stored.
Examples
A sample use of the command. Examples are displayed in the courier typeface to distinguish them from normal text. The 1> represents the Shell prompt; do not type it as part of the example command. Lines in the example not prefaced by 1> represent the output of a command. Command names and keywords are shown in all upper case letters and file and directory names usually have the first letter in upper case; however, they do not need to be entered that way. Press Return to execute the command line.

Separate commands and arguments with spaces. Use punctuation only when required in the syntax of specific commands.

Format

The following lists the characters that indicate the type of argument shown in format listings. Do not use these characters as part of the command.

< > Angle brackets indicate where additional information, such as a file name, must be included. This argument is required if it is not surrounded by square brackets. (For example, [<filename>]; see below.)
[ ] Square brackets enclose optional arguments and keywords. Although not required, these arguments and keywords are accepted by the command.
{ } Braces enclose items that can be given once or repeated any number of times. For example, {<args>} indicates that several items can be given for this argument.
| Vertical bars separate lists of options from which you can choose only one. For example, [OPT R|S|RS] indicates a choice of the R option, the S option, or both options.
<n> A numeric value is expected by the argument.
KEYWORD Italics indicate that the argument's keyword is required if you include that argument.
... An ellipsis (...) after a string argument indicates that the string must be the final argument on the command line. Including a comment is not allowed. 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 are part of the string. If you specify the keyword, you can put leading and trailing spaces in the string.
command line indentation On command lines that are long enough to wrap to the next line, this manual shows the wrapped lines as indented for documentation purposes only. In practice, the wrapped lines align with the first character of the Shell prompt.

The format for the COPY command illustrates the use of these conventions: 

COPY [FROM] {<name | pattern>} [TO]<name | pattern>[ALL]
   [QUIET] [BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO]
   [COM] [NOREQ]

The [FROM] keyword is optional. If it is not specified, the command reads the file name ir pattern to copy by ist position on the command line.

The {<name | pattern>} argument must be provided. You must substitute either a file name or pattern. The braces indicate that more than one name or pattern can be given.

The [TO] keyword is optional. If it is not specified, the command reads the file name or device to copy to by its position on the command line.

The <name | pattern> argument must be provided. You can specify only one destination.

The [ALL], [QUIET], [CLONE], [DATES], [NOPRO], [COM], and [NOREQ] arguments are optional.

The [BUF | BUFFER=<n>] argument is optional. If given, the keyword is required, but you can use either BUF or BUFFER with the numerical argument. For example, both BUF=5 and BUFFER=5 are acceptable. The numerical argument can also be entered without the equals sign; spaces are optional.

Template

The Template is built into the system to serve as an on-line reminder of a command's syntax and to let you run the command from the Template line by providing a prompt at which you enter the command's arguments.

Display the Template by entering a question mark (?) after a command. The Shell assumes that you wish to run the command and it expects you to enter the command's arguments after the colon following the display. For example: 

1> TYPE ?
FROM/A/M,TO/K,OPT/K,HEX/S,NUMBER/S:

Pressing Return executes the command if it does not require any arguments to run properly. Entering the arguments and their respective keywords and then pressing Return also executes the command. If a command requires arguments and you do not supply them or if you enter anything other than the required arguments, pressing Return results in a non-fatal error message. Remember that you do not need to enter the entire format for a command at this prompt, just the required arguments.

The Templates are listed with the arguments separated by commas, followed by a slash (/), and a capital letter indicating the type of argument. These slash/letter combinations are displayed to remind you of the command's particular requirements and are not entered as part of the command. The following table explains the notation:

Template Notation Format Equivalent Meaning
argument/A <name> The argument is always required.
option/K KEYWORD The option's keyword is required if the argument is given.
option/S [KEYWORD] The option works as a switch. The name of the option must be entered to specify it. Most options are switches.
value/N <n> The argument is numeric.
argument/M {<name>} Multiple items are accepted for this argument. Although there is no limit to the number of possible arguments, they must be provided before the next argument or option.
string/F argument... The string must be the final argument on the command line; the remainder of the command line is taken as the desired string.
= KYWD | KEYWORD Two different forms of the keyword are equivalent and either are accepted. The equals sign is not entered as part of the command.

The Template for the COPY command illustrates the use of arguments: 

FROM/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,
CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S

FROM/M indicates that the argument is required and more than one argument is acceptable.

TO/A indicates that the argument is required.

ALL/S, QUIET/S, CLONE/S, DATES/S, NOPRO/S, COM/S, and NOREQ/S indicate that the keywords act as switches. If the keyword is present in the line, the option is used.

BUF=BUFFER/K/N indicates that the BUF or BUFFER keyword (/K) is required to specify this numerical (/N) argument. Both BUF and BUFFER are acceptable keywords (=).

Keywords and their arguments can be linked with an equals sign (=) to ensure correct assignments in complex cases. For example, BUF=20.

Command Listing

ADDBUFFERS

Instructs the file system to add or display cache buffers for a drive.

Format
ADDBUFFERS <drive> [<n>]
Template
DRIVE/A,BUFFERS/N
Location
C:

ADDBUFFERS adds <n> buffers to the list of buffers available for <drive>. Although adding buffers speeds disk access, each additional buffer reduces free memory by approximately 512 bytes. The default buffer allocation is 5 for sloppy drives and 30 for hard disk partitions.

The amount of extra available memory dictates the number of buffers you can add. There is no fixed upper limit; however, adding too many buffers reduces overall system performance by taking RAM away from other system functions. Specifying a negative number subtracts that many buffers from the current allocation. The minimum number of buffers is one; however, using only one is not recommended.

Twenty buffers are recommended for a floppy drive in a 512 KB system. Use the default value recommended by the HDToolBox program for hard disks. (Display this value by selecting the Advanced Options gadget on the Partitioning screen.)

If only the <drive> argument is specified, ADDBUFFERS displays the number of buffers currently allocated for that drive.

Example
1> ADDBUFFERS DF0:
DF0: has 5 buffers

A further example of ADDBUFFERS appears in Chapter 8.

ALIAS

Sets or displays command aliases.

Format
ALIAS [<name>] [<string...>]
Template
NAME,STRING/F
Location
Internal

ALIAS creates aliases, or alternative names, for AmigaDOS commands. ALIAS can be used to abbreviate frequently used commands or replace standard command names with different names.

When AmigaDOS encounters <name>, it replaces it with the defined <string>, integrate the result with the rest of the command line, and attempts to interpret and execute the resulting line as an AmigaDOS command <Name> is the alias for the command and <string> is the command to be substituted for the alias.

An alias must be entered at the beginning of the command line. You can enter arguments after the alias, but you cannot create an alias to represent a series of command arguments. For example, in the following command line: 

1> NEWSHELL WINDOW=CON:0/250/640/150/2SHELL/CLOSE

the WINDOW argument cannot be replaced with an alias.

You can substitute a file name or other instruction within an alias by placing square brackets ([ ]) with nothing between them in the <string>. Any argument entered after the alias is inserted at the brackets.

ALIAS <name> displays the <string> for that alias. Entering ALIAS alone lists all current aliases.

Aliases are local to the Shell in which they are defined. If you create another Shell with the NEWSHELL command, it shares the same aliases as its parent Shell. However, if you create another Shell with the Execute Command menu item, it des not recognize aliases created in your original Shell. A global lais that is recognized by all Shells can be crated by inserting the alias in the Shell-startup file.

To remove an ALIAS, use the UNALIAS command.

Example 1
1> ALIAS d1 DIR DF1:

Entering d1 displays a directory of the contents of the disk in DF1:; as if you entered DIR DF1:.

Example 2
1> ALIAS hex TYPE [ ] HEX

creates an alias called HEX that displays the contents of a specified file in hexadecimal format. The empty brackets indicate where the file name is inserted in this example. Entering: 

1> hex Myfile

displays the contents of Myfile in hexadecimal format.

See also: UNALIAS. Further examples of using ALIAS appear in Chapter 8.

ASK

Gets yes or no user input during script file execution.

Format
ASK <prompt>
Template
PROMPT/A
Location
Internal

ASK is used in scripts to write the string specified by <prompt> to the current window and then wait for keyboard input. Valid keyboard responses are Y (yes), N (no), and Return (no). Selecting Y sets the condition flag to 5 (WARN). Selecting N or pressing Return sets the condition flag to 0. Check the response using an IF statement.

If the <prompt> contains spaces, it must be enclosed in quotation marks.

Example

Assume a script contained the following commands: 

ASK Continue?
IF WARN
   ECHO Yes
ELSE
   ECHO No
ENDIF

At the ASK command, Continue? Is displayed on the screen. If Y is pressed, Yes is displayed on the screen. If N or a Return alone is pressed, No is displayed.

See also: IF, ELSE, ENDIF, REQUESTCHOICE, WARN

ASSIGN

Controls assignment of logical device names to files or directories.

Format
ASSIGN [<name>:] [{<target>}] [LIST] [EXISTS] [DISMOUNT] [DEFER] [PATH] [ADD] [REMOVE] [VOLS] [DIRS] [DEVICES]
Template
NAME,TARGET/M,LIST/S,EXISTS/;,DISMOUNT/S,DEFER/S,PATH/S,ADD/S,REMOVE/S,VOLS/S,DIRS/S,DEVICES/S
Location
C:

ASSIGN allows references to files or directories with short, convenient logical device names, rather than their usual names or complete paths. The ASSIGN command can create assignments, remove assignments, or list some or all current assignments.

If the <name> and {<target>} arguments are given, ASSIGN assigns the given logical name to the specified target. Each time the assigned logical device name is referred to, AmigaDOS accesses the specified target. If the <name> given is already assigned to a file or directory, the new target replaces the previous one. A colon must be included after the <name> argument.

If only the <name> argument is given, any existing ASSIGN of a file or directory to that logical device name is cancelled.

You can assign several logical device names to the same target by using multiple ASSIGN commands.

You can assign one logical device name to several targets by specifying each file or directory after the <name> argument or by using several ASSIGN commands with the ADD option. Specifying the ADD option does not replace any existing target assigned to <name>. This target is added to the ASSIGN list and the system searches for all the targets when <name> is encountered. If the first target is not available, ASSIGN uses the next target added.

The REMOVE option deletes a target name from the ASSIGN list.

If no arguments are given with ASSIGN or if the LIST keyword is used, a list of all current assignments is displayed. If the VOLS, DIRS, or DEVICES switch is specified, ASSIGN limits the display to volumes, directories, or devices.

When the EXISTS keyword is entered with a logical device name, AmigaDOS searches the ASSIGN list for that name and displays the volume and directory assigned to that device. If the device name is not found, the condition flag is set to 5 (WARN).

When the {<target>} argument is given, AmigaDOS immediately looks for that file or directory. If the ASSIGN commands are part of the User-startup, the targets must be present on a mounted disk during the boot procedure. If an assigned target cannot be found, a requester asks for the volume containing it. However, using the DEFER and PATH options make the system wait until the target is needed before searching for it.

Note
The assigned name does not have to retain the name of the file or directory and it does not have to be in upper case. For example, the name CLIPS: or Clips: can be assigned to the Ram Disk:Clipboards directory.

The DEFER option creates a late-binding ASSIGN. This ASSIGN takes effect when the assigned object is first referenced, rather than when the assignment is made. When the DEFER option is used, the disk containing the assigned target is not needed until the object is called. The assignment then remains valid until explicitly changed.

If you ASSIGN FONTS: to DF0:Fonts with the DEFER option, the system associates FONTS: with the disk that is in DF0: when FONTS: is referred to. For example, if you have a Workbench disk in DF0: at the time the FONTS: directory is needed, the system associates FONTS: with that particular Workbench disk. If you later remove that Workbench disk and insert another disk containing a Fonts directory, the system specifically requests the original Workbench disk the next time FONTS: is needed.

The PATH option creates a non-binding ASSIGN. A non-binding ASSIGN acts like a DEFERed ASSIGN, except that is re-evaluated each time the assigned name is referenced. For example, if you assign FONTS: to DF0:Fonts with the PATH option, any disk in DF0: is searched when FONTS: is referenced. As long as the disk contains a Fonts directory, it satisfies the ASSIGN. You cannot assign multiple directories with the PATH option.

Floppy disk only system users can find that using the PATH option eliminates the need to reinsert the original Workbench disk used to boot the system. As long as the drive you assigned with the PATH option contains a disk with the assigned directory name, the system uses that disk.

The DISMOUNT option disconnects a volume or device from the list of mounted devices. You must provide the device name in the argument. DISMOUNT removes the name form the list, but does not free resources. You cannot cancel a DISMOUNT without rebooting. DISMOUNT is meant for use by software developers only and can cause a software failure if not used carefully.

Example 1
1> ASSIGN FONTS: MyFonts:Fontdir

assigns the FONTS: directory to Fontdir on MyFonts:

Example 2
1> ASSIGN LIST
Volumes:
Ram Disk [Mounted]
Workbench [Mounted]
MyFonts [Mounted]

Directories:
LOCALE Workbench:Locale
KEYMAPS Workbench:Devs/Keymaps
PRINTERS Workbench:Devs/Printers
REXX Workbench:S
CLIPS Ram Disk:Clipboards
ENV Ram Disk:Env
T Ram Disk:T
ENVARC Workbench:Prefs/Env-Archive
SYS Workbench:
C Workbench:C
S Workbench:S
L Workbench:L
FONTS MyFonts:Fontdir
DEVS Workbench:Devs
LIBS Workbench:Libs
+ Workbench:Classes

Devices:
PIPE AUX RAM CON
RAW PAR SER PRT DF0

Shows a typical list of all current assignments. The plus sign indicates any additional directories with the same assignment.

Example 3
1> ASSIGN FONTS: EXISTS
FONTS: MyFonts:FontDir

is an inquiry into the assignment of FONTS:. AmigaDOS responds by showing that FONTS: is assigned to the FontDir directory of the MyFonts volume. The return code is set to 0 if it exists or to 5 if it does not.

Example 4
1> ASSIGN LIBS: SYS:Libs BigAssem:Libs ADD

is a multiple-directory assignment that creates a search path containing two Libs directories. Specifying ADD keeps the standard SYS:Classes assignment from being removed. These directories are searched in sequence each time LIBS: is invoked.

Example 5
1> ASSIGN DEVS:

removes the DEVS: assignment from the system.

Example 6
1> ASSIGN WorkDisk: DF0: DEFER
1> ASSIGN WorkDisk: EXISTS
WorkDisk <DF0:>

sets up a late-binding assignment of the logical device WorkDisk:. Until the first time you refer to the name WorkDisk:, you do not need to insert it in DF0: ASSIGN shows DF0: enclosed in angle brackets to indicate that it is DEFERred. After the first reference to WorkDisk:, the volume name of the disk that was in DF0: replaces <DF0:>.

Example 7
1> ASSIGN C: DF0:C PATH
1> ASSIGN C: EXISTS
C [Df0: C]

references the C directory fo the disk that is in DF0: when a command is searched for. ASSIGN shows DF0:C in square brackets to indicate that it is a non-binding ASSIGN.

Example 8
1> ASSIGN LIBS: Zcad:Libs ADD

adds Zcad:Libs to the list of directories assigned as LIBS:.

Example 9
1> ASSIGN LIBS: Zcad:Libs REMOVE

removes Zcad:Libs from the list of directories assigned as LIBS:.

For more examples using ASSIGN, see Chapter 8.

AVAIL

Reports the amount of Chip and Fast memory available.

Format
AVAIL [VHIP | FAST | TOTAL] [FLUSH]
Template
CHIPS/S,FAST/S,TOTAL/S,FLUSH/S
Location
C:

AVAIL gives a summary of the system RAM, both Chip and Fast. For each memory type, AVAIL reports the total amount of memory, how much is available, how much is currently in use, and the largest contiguous memory block not yet allocated.

Unless you want a complete summary, use the CHIP, FAST, and/or TOTAL options to have AVAIL display only the number of free bytes of Chip, Fast, or Total RAM available.

The FLUSH option frees memory by removing all unused libraries, devices, fonts, catalogs.

Example 1
1> AVAIL
Type Available In-Use Maximum Largest
chip 233592 282272 515864 76792
fast 341384 182896 524280 197360
total 574976 465168 1040144 197360

A complete summary of system RAM is displayed.

Example 2
1> AVAIL CHIP
233592

The number of free bytes of Chip RAM is displayed.

See Chapter 8 for more examples using AVAIL.

BREAK

Sets attention flags in the specified process.

Format
BREAK <process> [ALL | C | D | E | F]
Template
PROCESS/A/N,ALL/S,C/S,D/S,E/S,F/S
Location
C:

BREAK sets the specified attention flags in the <process> indicated. Use the STATUS command to display the current process numbers. C sets the Ctrl+C flag, D sets the Ctrl+D flag, and so on, ALL sets all the flags from Ctrl+C to Ctrl+F. By default, only the Ctrl+C flag is set.

BREAK acts the same as selecting the relevant process by clicking in its window and pressing the appropriate Ctrl+key combinations.

Ctrl+C is the default for sending a BREAK signal to halt a process. A process that has been aborted this way displays ***Break in the Shell window. Ctrl+D halts execution of a script file. The STATUS command displays the current process numbers. Ctrl+E is undefined.

Ctrl+F is used by programs that open windows to activate their window and bring it to the front of all windows. Not all programs respond to Ctrl+F.

Example 1
1> BREAK 7

sets the Ctrl+C attention flag of process 7. This is the same as selecting process 7 and pressing Ctrl+C.

Example 2
1> BREAK 5 D

sets the Ctrl+D attention flag of process 5.

See also: STATUS

CD

Sets or displays the current directory.

Format
CD [<dir | pattern>]
Template
DIR
Location
Internal

CD with no arguments displays the name of the current directory. When a valid directory name is given, CD makes the named directory the current directory.

You must specify a complete path to the directory since CD does not search through the disk for it. If CD cannot find the specified directory in the current directory or in the given path, a Can't find <directory> message is displayed.

To move up a level in the filing hierarchy to the parent directory of the current directory, enter CD followed by a space and a single slash (/). You can move to another directory in the parent at the same time by including its name after the slash. If the current directory is a root directory, CD / has no effect. Use multiple slashes with no spaces between them to refer to additional higher levels.

To move directly to the root directory of the current device, use CD followed by a space and a colon; for example, CD :

AmigaDOS supports an implied CD so that the CD command itself can often be left out. Enter the directory name, path, colon, or slashes at the prompt.

CD also supports pattern matching. When a directory matching the specified pattern is found, it becomes the current directory. If more than one directory matches the given pattern, an error message is displayed. You cannot use pattern matching with implied CD. For more information an pattern matching, see Chapter 3.

Example 1
1> CD DF1:Work

sets the current directory to the Work directory on the disk in drive DF1:.

Example 2
1> CD SYS:Com/Basic

makes the subdirectory Basic in the Com directory the current directory.

Example 3
1> //

using the implied CD, moves up two levels in the directory structure.

Example 4
1> CD SYS:Li#?

uses the #? pattern to match with the LIBS: directory.

For more examples using the CD command, see Chapter 8.

CHANGETASKPRI

Changes the priority of a currently running process.

Format
CHANGETASKPRI <priority> [PROCESS <process number>]
Template
PRI=PRIORITY/A/N,PROCESS/K/N
Location
C:

CHANGETASKPRI changes the priority of the specified Shell process. If no process is specified, the current Shell process is assumed. Any shell process started from <process number> inherits its priority.

Use the STATUS command to display the current process numbers.

The range of acceptable values for <priority> is the integers from -128 to 127, with higher values yielding a higher priority (a greater proportion of CPU time is allocated). However, do not enter values above +10 to avoid disrupting important system tasks.

Example
1> CHANGETASKPRI 4 Process 2

The priority of Process 2 is changed to 4. Any shell process started from this Shell also has a priority of 4. They have priority over any other user tasks created without using CHANGETASKPRI (those tasks have a priority of 0).

See also: STATUS. For another example for using CHANGETASKPRI, see Chapter 8.

COPY

Copies files or directories.

Format
COPY [FROM] {<name | pattern>} [TO] <name> [ALL] [quiet] [BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO] [COM] [NOREQ]
Template
FROM/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S
Location
C:

COPY copies the file or directory specified with the FROM argument to the file or directory specified by the TO argument. You can copy several items at once by giving more than one name/pattern in the FROM argument; they should be separated by spaces. If the FROM argument is a pattern or consists of multiple names, the TO argument must be a directory.

If a TO file name already exists, COPY overwrites the TO file with the FROM file. You can use a pair of double quotation marks ("") to refer to the current directory. When used as the FROM argument, "" copies all the files in the current directory. Do not put any spaces between the double quotation marks.

If the FROM argument is a directory, only the directory's files are copied; its subdirectories are not copied. Use the ALL option to copy the complete directory, including its files, subdirectories, and the subdirectories' files. It is possible to create a directory as you copy if you are copying more than one file. To give the new directory a name, specify the directory name as the last component in the TO argument's path. This can be any name, including the same name as the original if it is a different path.

COPY prints to the screen the name of each file as it is copied. This can be overridden by the QUIET option.

The BUF= option is used to set the number of 512-byte buffers used during the copy. (Default is 128 buffers, 64 KB of RAM.) Limit the number of buffers when copying to RAM:. BUF=0 uses a buffer the same size as the file to be copied.

By default, COPY gives a TO file the timestamp of when the copy was made, rather than that of the original file. Also by default, comments attached to the original FROM file are not copied and the protection bits of the FROM file are copied to the TO file. You can override these defaults using the following:

CLONE The timestamp, comments, and protection bits of the FROM file are copied to the TO file.
DATES The timestamp of the FROM file is copied to the TO file.
COM Any comment attached to the FROM file is copied to the TO file.
NOPRO The protection bits of the FROM file are not copied to the TO file. The TO file is given standard protection bits or r, w, e, and d.

COPY displays a requester if the COPY cannot continue. When the NOREQ option is given, all requesters are suppressed. Use this in scripts to prevent a COPY failure from stopping the script to wait for a response. With the NOREQ option, the COPY command is aborted and the script continues.

Example 1
1> COPY File1 TO :Work/File2

copies File1 in the current directory to the Work directory in the root of the current device, renaming it File2.

Example 2
1> COPY Chapter#? TO DF1:Backup

copies all the files whose names start with Chapter in the current directory to the Bakkup directory on the disk in DF1:. The Backup directory is created if it does not already exist.

Example 3
1> COPY Work:Test TO " "

copies the files in the Test directory on Work to the current directory; subdirectories in Test are not copied.

Example 4
1> COPY Work:Test TO DF0:Test ALL

copies all the files and any subdirectories of the Test directory on Work to the Test directory on DF0:. If a Test directory does not already exist on DF0:, COPY creates one.

Example 5
1> COPY DF0: TO DF1: ALL QUIET

copies all files and directories on the disk in DF0: to DF1:, without displaying on the screen any file/directory names as they are copied. (For disks less than half full, this can be faster than DiskCopy.)

For more examples using COPY, see Chapter 8.

CPU

Sets or displays processor options.

Format
CPU [CACHE | NONCACHE] [BURST | NOBURST] [DATACAHCE | NODATACACHE] [DATABURST | NODATABURST] [INSTCACHE | NOINSTCACHE] [INSTBURST | NOINSTBURST] [FASTROM | NOFASTROM] [TRAP | NOTRAP] [COPYBACK | NOCOPYBACK] [EXTERNALCACHE | NOEXTERNALCACHE] [NOMMUTEST] [CHECK 68010 | 68020 | 68030 | 68040 | 68881 | 68882 | 68851 | MMU | FPU]
Template
CACHES/S,BURST/S,NOCACHE/S,NOBURST/",DATACACHE/S,NODATACHE/S,DATABURST/S,NODATABURST/S,INSTCACHE/S,NOINSTCACHE/S,INSTBURST/S,NOINSTBURST/S,COPYBACK/S,NOCOPYBACK/S,EXTERNALCACHE/S,NOEXTERNALCACHE/S,FASTROM/S,NOFASTROM/S,TRAP/S,NOTRAP/S,NOMMUTEST/S,CHECK/K
Location
C:

CPU adjusts various options of the microprocessor installed in your Amiga. CPU also shows the processor and options that are currently enabled.

Many options only work with certain members of the 680x0 processor family. The 68020 has a special type of memory known as instruction cache. When instruction cache is used, instructions are executed more quickly. The 68030 and 68040 have two types of cache memory: instruction and data.

If mutually exclusive options are specified, the safest option is used. Availability of the following options depends on the type of microprocessor present.

CACHE Turns on all caches.
NOCACHE Turns off all caches.
BURST Turns on burst mode for both data and instructions.
NOBURST Turns off burst mode for data and instructions.
DATACACHE Turns on data cache.
NODATACACHE Turns off data cache.
DATABURST Turns on burst mode for data.
NODATABURST Turns off burst mode for data.
INSTCACHE Turns on instruction cache.
NOINSTCACHE Turns off instruction cache.
INSTBURST Turns on burst mode for instructions.
NOINSTBURST Turns off burst mode for instructions.
FASTROM With a processor having a supported MMU, copies the system ROM into 32-bit RAM, making access to operating system functions significantly faster. CPU then write-protects the RAM area so that the data cannot be changed.
NOFASTROM Turns off FASTROM.
TRAP This option is for developers only.
NOTRAP This option is for developers only.
COPYBACK Turns on 68040 copyback cache.
NOCOPYBACK Turns off 68040 copyback cache.
EXTERNALCACHE Turns on external cache.
NOEXTERNALCACHE Turns off external cache.
NOMMUTEST Allows the MMU settings to be changed without checking to see if an MMU is currently in use.

The CHECK option, when given with a keyword (68010, 68020, 68030, 68040, 68881, 68882, or 68851, MMU, FPU) checks for the presence of the processor indicated by the keyword.

Examples
1> CPU
System: 68030 68881 (INST: Cache Burst) (DATA: Cache NoBurst)

1> CPU NODATACACHE FASTROM
System: 68030 68881 FastRom (INST: Cache Burst)
(DATA: NoCache NoBurst)

1> CPU NOBURST DATACACHE NOINSTCACHE
System: 68030 68881 (INST: NoCache NoBurst) (DATA: Cache NoBurst)

DATE

Displays or sets the system date and/or time.

Format
DATE [<day>] [<date>] [
Template
DAY,DATE,TIME,TO=VER/K
Location
C:

DATE with no argument displays the currently set system time and date, including the day of the week. Time is displayed using a 24-hour clock.

DATE <date> sets only the date. The format for entry and display of <date> is DD-MMM-YY (day-month-year). The hyphens between the arguments are required. A leading zero in the date is not necessary. The number or the first three letters of the month (in English) must be used, as well as the last two digits of the year.

If the date is already set, you can reset it by specifying a day name. You can also use tomorrow or yesterday as the <day> argument. You cannot specify a day name to change the date to more than seven days into the future.

DATE

If your Amiga does not have a battery backed-up hardware clock and you do not set the date, when the system boots it sets the date to the date of the most recently created file on the boot disk.

If you specify the TO or VER option, followed by a file name, the output of the DATE command is sent to that file, overwriting any existing contents.

Adjustments made with DATE only change the software clock and do not survive powering off the system. To set the battery backed-up hardware clock from the Shell, you must set the date and use SETCLOCK SAVE.

Although DATE accepts and displays the date and time in a single format, programs such as Clock display the date and time according to your Locale country setting.

Example 1
1> DATE
6-Sep-92
Example 2
1> DATE 6-sep-92

sets the date to September 6, 1992. The time is not reset.

Example 3
1> DATE tomorrow

resets the date to one day ahead.

Example 4
1> DATE TO Fred

sends the current date to the file Fred.

Example 5
1> DATE 23:00

sets the current time to 11:00 p.m.

Example 6
1> DATE 1-jan-02

sets the date to January 1st, 2002. The earliest date you can set is January 1, 1978.

DELETE

Deletes files or directories.

Format
DELETE {<name | pattern>} [ALL] [QUIET] [FORCE]
Template
FILE/M/A,ALL/S,QUIET/S,FORCE/S
Location
C:

DELETE attempts to erase the specified items. You can delete multiple items at the same time by listing them individually or by using a wildcard to delete a specific set of files matching a pattern. The pattern can specify directory levels, as well as names. To abort a multiple-item DELETE, press Ctrl+C. A multiple-item DELETE aborts if and when it finds something that cannot be removed; for example, a file is delete-protected or in use. A pattern matching DELETE removes everything it can and lists the items that it did not delete, if any.

Note
AmigaDOS does not request confirmation of deletions. Do not use pattern matching to delete things if your are not familiar with the procedure; deleted items cannot be recovered, unless you have an up-to-date backup of the items deleted.

An error message warns you that you cannot delete directories that still contain files. Override this using the ALL option. DELETE ALL deletes the named directory, its subdirectories, and all files.

File names are displayed on the screen as they are deleted. To suppress the screen output, use the QUIET option.

If the d (deletable) protection bit of a file or directory has been cleared, that item cannot be deleted unless the FORCE option is used.

Example 1
1> DELETE Old-file

deletes the file named Old-file in the current directory.

Example 2
1> DELETE Work/Prog1 Work/Prog2 Work

deletes the files Prog1 and Prog2 in the Work directory and then deletes the Work directory if it contains no other files.

Example 3
1> DELETE T#?/#?(1|2)

deletes all the files that end in 1 or 2 in directories that start with T.

Example 4
1> DELETE DF1:#? ALL FORCE

deletes all the files on DF1:, even those set as not deletable.

See also: PROTECT. For more examples using DELETE, see Chapter 8.

DIR

Displays a sorted list of the files in a directory.

Format
DIR [<dir | pattern>] [OPT A | I | AI | D | F] [ALL] [DIRS] [FILES] [INTER]
Template
DIR,OPT/K,ALL/S,DIRS/S,FILES/S,INTER/S
Location
C:

DIR displays the file and directory names contained in the specified directory or the current directory. Directories are listed first, followed by an alphabetical list of the files in two columns. Pressing Ctrl+C aborts a directory listing.

The options are:

ALL Displays all subdirectories and their files.
DIRS Displays only directories.
FILES Displays only files.
INTER Enters an interactive listing mode.

The ALL, DIRS, FILES, and INTER keywords supersede the OPT A, D, F, and I options, respectively. The older keywords are retained for compatibility with earlier versions of AmigaDOS. Do not use OPT with the full keywords - ALL, DIRS, FILES, or INTER.

Interactive listing mode stops after each name to display a question mark at which you can enter commands. The acceptable responses are shown below:

Press Return Displays the next name on the list.
E Enters a directory; the files in that directory are displayed.
B Goes back one directory level.
DEL or DELETE Deletes a file or empty directory. DEL does not refer to the Del key; enter the letters D, E, and L.
T Types the contents of a file.
C or COMMAND Allows you to enter additional AmigaDOS commands.
Q Quits interactive editing.
? Displays a list of the available interactive-mode commands.

The COMMAND option allows almost any AmigaDOS command to be executed during the interactive directory list. To issue a command, enter C (or COMMAND) at the question mark prompt. DIR asks you for the command. Enter the desired command, then press Return. The command is executed and DIR continues. You can also combine the C and the command on one line by putting the command in quotation marks following the C.

For example, 

? C "type prefs.info hex"

is equivalent to pressing Q to exit interactive listing mode and return to a regular Shell prompt, then entering: 

1> TYPE Prefs.info HEX

to display the Prefs.info file on the screen in hexadecimal format.

Formatting a disk from the DIR interactive mode is not recommended since the format takes place immediately, without any confirmation requesters appearing. Do not start another interactive DIR from interactive mode since it results in garbled output.

Example 1
1> DIR Workbench:

displays a list of the directories and files on the Workbench disk.

Example 2
1> DIR MyDisk:#?.memo

displays all the directories and files on MyDisk that end in .memo.

Example 3
1> DIR Extras: ALL

displays the complete contents of the Extras drawer: all directories, all subdirectories, and all files, including those in the subdirectories.

Example 4
1> DIR Workbench: DIRS

displays only the directories on Workbench.

Example 5
1> DIR Workbench: INTER

begins an interactive list of the contents of the Workbench disk.

For more examples using DIR, see Chapter 8.

DISKCHANGE

Informs the Amiga that you have changed a disk in a disk drive.

Format
DISKCHANGE <device>
Template
DRIVE/A
Location
C:

You must use the DISKCHANGE command to inform the system when you change disks or cartridges in 5.25 inch floppy disk drives or removable media drives without automatic diskchange hardware.

Example

If a requester asks you to insert a new disk into your 5.25 inch drive, known as DF2:, you must insert the disk and then enter: 

1> DISKCHANGE DF2:

AmigaDOS then recognizes the new disk and you can proceed.

ECHO

Displays a string.

Format
ECHO [<string>] [NOLINE] [FIRST <n>] [LEN <n>] [TO <filename>]
Template
/M,LINE/S,FIRST/K/N,LEN/K/N,TO/K
Location
Internal

ECHO writes the specified string to the current output window or device. By default the string is sent to the screen, but if you use the TO option, you can send the string to any specified device or file.

When the NOLINE option is specified, ECHO does not automatically move the cursor to the next line after printing the string.

The FIRST and LEN options allow the echoing of a substring. FIRST <n> indicate the character position from which to begin the echo; LEN <n> indicates the number of characters of the substring to echo, beginning with the FIRST character. If the FIRST option is omitted and only the LEN keyword is given, the substring printed consists of the rightmost <n> characters of the main string. For example, if your string is 20 characters long and you specify LEN 4, the 17TH, 18th, 19th, and 20th characters of the string are echoed.

Examples
1> ECHO "hello out there!"

hello out there! 

1> ECHO "hello out there!" NOLINE FIRST 0 LEN 5 hello1>

For further examples using the ECHO command, see Chapter 8.

ED

Edits text files (a screen editor).

Format
ED [FROM] <filename> [Size <n>] [WITH <filename>] [WINDOW <window specification>] [TABS <n>] [WIDTH | COLS <n>] [HEIGHT | ROWS <n>]
Template
FROM/A,SIZE/N,WITH/K,WINDOW/K,TABS/N,WIDTH=COLS/N,HEIGHT=ROWS/N
Location
C:

See ED for more information. See Chapter 8 for an example using ED.

EDIT

Edits text files by processing the source file sequentially (a line editor).

Format
EDIT [FROM] <filename> [[TO <filename>] [WITH <filename>] [VER <filename>] [OPT P <lines> | W <chars> | P<lines>W<chars>] [WIDTH <chars>] [PREVIOUS <lines>]
Template
FROM/A,TO,WITH/K,VER/K,OPT/K,WIDTH/N,PREVIOUS/N
Location
C:

See EDIT for more information.

ELSE

Specifies an alternative for an IF statement in a script file.

Format
ELSE
Template
(none)
Location
Internal

ELSE must be used in conjunction with the IF command. ELSE is used in an IF block of a script to specify an alternative action if the IF condition is not true. If the IF condition is not true, execution of the script jumps from the IF line to the line after ELSE; all intervening commands are skipped. If the IF condition is true, the commands immediately following the IF statement are executed up to the ELSE. Then, execution skips to the ENDIF statement that concludes the IF block.

Example

Assume a script, called Display, contains the following block: 

IF exists picfile
   MultiView picfile
ELSE
   ECHO "picfile is not in this directory"
ENDIF

If picfile can be found in the current directory, the MultiView program is executed and picfile is displayed on the screen.

If picfile cannot be found in the current directory, the script skips to the ECHO command. The following message is displayed in the Shell window: 

picfile is not in this directory

See also: IF, ENDIF, EXECUTE

ENDCLI

Ends a Shell process.

Format
ENDCLI
Template
(none)
Location
Internal

ENDCLI ends a Shell process.

See also: ENDSHELL

ENDIF

Terminates an IF block in a script file.

Format
ENDIF
Template
(none)
Location
Internal

ENDIF must be used when an IF commands is used. ENDIF is used in scripts at the end of an IF block. If the IF condition is not true or if the true-condition commands are executed and an ELSE is encountered, the execution of the script skips to the next ENDIF command. Every IF statement must be terminated by an ENDIF.

The ENDIF applies to the most recent IF or ELSE command.

See also: IF, ELSE. For examples using the ENDIF command, see Chapter 8.

ENDSHELL

Ends a Shell process.

Format
ENDSHELL
Template
(none)
Location
Internal

ENDSHELL ends a Shell process and closes the Shell window.

The Shell process can also be ended by ENDCLI, by clicking on the close gadget, or by pressing CTRL+\.

Use ENDSHELL only when the Workbench or another Shell is running. If you quit the Workbench and you close your only Shell, you cannot communicate with the Amiga without rebooting.

The Shell window cannot close if any process that were launched from the Shell and not detached are still running. Even though the window stays open, the Shell does not accept new input. You must terminate those processes before the window closes. For example, if you opened an editor from the Shell, the Shell window does not close until you exit the editor.

For examples using the ENDSHELL command, see Chapter 8.

ENDSKIP

Terminates a SKIP block in a script file.

Format
ENDSKIP
Template
(none)
Location
Internal

ENDSKIP is used in scripts to terminate the execution of a SKIP block. A SKIP block allows you to jump over intervening commands if a certain condition is met. When an ENDSKIP is encountered, execution of the script resumes at the line following the ENDSKIP. The condition flag is set to 5 (WARN).

See also: SKIP

EVAL

Evaluates integer or Boolean expressions.

Format
EVAL <value1> {[<operation>] [<value2>]} [TO <file>] [LFORMAT=<string>]
Template
VALUE1/A,OP,VALUE2/M,TO/K,LFORMAT/K
Location
C:

EVAL is used to evaluate and print the answer of an integer expression. The fractional portion of input values and final results, if any, is truncated (cut off). If a non-integer is given as an input value, evaluation stops at the decimal point.

<Value1> and <value2> can be decimal (the default), hexadecimal, or octal numbers. Hexadecimal numbers are indicated by either a leading Ox or #x. Octal numbers are indicated by either a leading 0 or a leading #. Alphabetical characters are indicated by a leading single quotation mark (`) and are evaluated as their ASCII equivalent.

The LFORMAT keyword specifies the formatting string used to print the answer. You can use %X (hexadecimal), %O (octal), %N (decimal), or %C (character). The %X and %O options require a number of digits using the LFORMAT keyword, you can specify to print a new line by including *N in your string.

The supported operations and their corresponding symbols are shown in the following table.

addition +
subtraction -
multiplication *
division /
modulo mod, M, m, or %
bitwise AND &
bitwise OR |
bitwise NOT ~
left shift Ish, L, or l
right shift rsh, R, or r
negation -
exclusive OR xor, X, or x
bitwise equivalence eqv, E, or e

EVAL can be used in scripts as a counter for loops. In that case, use the TO option to send the output of EVAL to a file.

Parentheses can be used in the expressions.

Example 1
1> EVAL 64 / 8 + 2
10
Example 2
1> EVAL 0x5f / 010 LFORMAT="The answer is %X4*N"
The answer is 000B
1>

This divides hexadecimal 5f (95) by octal 10 (8), yielding 000B, the integer portion of the decimal answer 11.875. (The 1> prompt appears immediately after the 000B if *N is not specified in the LFORMAT string.)

For more examples using the EVAL command, see Chapter 8.

EXECUTE

Executes a script with optional argument substitution.

Format
EXECUTE <script> [{<arguments>}]
Template
FILE/A
Location
C:

EXECUTE is used to run scripts of AmigaDOS commands. The lines in the script are executed as if they had been entered at a Shell prompt. If the s protection bit of a file is set and the file is in the search path, enter only the file name; the EXECUTE command is not needed.

You can use parameter substitution in scripts by including special keywords in the script. When these keywords are used, you can pass variables to the script by including the variable in the EXECUTE command line. Before the script is executed, AmigaDOS checks the parameter names in the script against any arguments given on the command line. If any match, AmigaDOS substitutes the values specified on the command line for the parameter name in the script. You can also specify default values for AmigaDOS to use if no variables are given. If you have not specified a variable and there is no default specified in the script, then the value of the parameter is empty (no substitution is made).

The allowable keywords for parameter substitution are explained in Chapter 5. Each keyword command line must be prefaced with a dot character (.).

See also: IF, SKIP, FAILAT, LAB, ECHO, RUN, QUIT. For examples using the EXECUTE command, see Chapter 8.

FAILAT

Instructs a command sequence not to fail unless a given error condition is returned.

Format
FAILAT [<n>]
Template
RCLIM/N
Location
Internal

Commands indicate that they have failed by setting a nonzero return code. The return code, normally 5, 10, or 20, indicates the severity of the error. A return code greater than or equal to a certain limit, the fail limit, terminates a sequence of non-interactive commands (commands specified after RUN or in a script).

Use the FAILAT command to alter the fail limit RCLIM (Return Code Limit) from its initial value of 10. If you increase the limit, you indicate that certain classes of error should not be regarded as fatal and that execution of subsequent commands can proceed after the error. The argument must be a positive number. The fail limit is reset to the initial value of 10 on exit from the command sequence.

If the argument is omitted, the current fail limit is displayed.

Example

Assume a script contains the following lines: 

COPY DF0:MyFile to RAM:
ECHO "MyFile being copied."

If MyFile cannot be found, the scripts is aborted and the following message appears in the Shell window: 

COPY: object not found
COPY failed returncode 20:

However, if you changed the return code limit to higher than 20, the script continues even if the COPY command fails. For example, if you changed the script to read: 

FAILAT 21
COPY DF0:MyFile to RAM:
ECHO "MyFile being copied."

Even if MyFile cannot be found, the script continues. The following message appears in the Shell window: 

COPY: object not found
MyFile being copied.

See also: ECHO, EXECUTE.

FAULT

Prints the messages for the specified error numbers.

Format
FAULT {<n>}
Template
/N/M
Location
Internal

FAULT prints the messages corresponding to the error numbers supplied. As many error numbers, separated by spaces, as you want can be specified to print at the same time.

Example

If you receive the error message: 

Error when opening DF1:TestFile 205

and need more information, enter: 

1> FAULT 205
FAULT 205: object not found

This tells you that the error occurred because TestFile could not be found on DF1:.

A complete list of error messages appears in Appendix A.

FILENOTE

Attaches a comment to a file.

Format
FILENOTE [FILE] <file | pattern> [COMMENT <comment>] [ALL] [QUIET]
Template
FILE/A,COMMENT,ALL/S,QUIET/S
Location
C:

FILENOTE attaches an optional comment of up to 79 characters to the specified file or to all files matching the given pattern.

If the <comment> includes spaces, it must be enclosed in double quotation marks. To include double quotation marks in a filenote, each literal quotation mark must be immediately preceded by an asterisk (*) and the entire comment must be enclosed in quotation marks, regardless of whether the commend contains any spaces.

If the <comment> argument is omitted, any existing filenote is deleted from the named file.

Creating a comment with FILENOTE is the same as entering a comment into the Comment gadget of an icon's Information window. Changes made with FILENOTE are reflected in the Information window, and vice versa.

Use the LIST command to view comments made with FILENOTE. If a file has comments, LIST displays them below the file name.

When a existing file is copied to (specified as the TO argument of a COPY command), it is overwritten, but its original comment is retained. Any comment attached to a FROM file is not copied unless the CLONE or COM option of COPY is specified.

If the ALL option is given, FILENOTE adds the <comment> to all the files and subdirectories matching the pattern entered. If the QUIET options is given, screen output is suppressed.

Example 1
1> FILENOTE Sonata "allegro non troppo"

attaches the filenote allegro non troppo to the Sonata file.

Example 2
1> FILENOTE Toccata "*"presto*""

attaches the filenote "presto" to the Toccata file.

Retrieved from "http://wiki.amigaos.net/w/index.php?title=AmigaOS_Manual:_AmigaDOS_Command_Reference&oldid=6928"