AmigaOS Manual: AmigaDOS Command Reference

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.

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>] [] [TO | VER <filename>]

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 sets the time. The format for entry and display of is HH:MM:SS (hours:minutes:seconds). Seconds is optional.

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

ENDCLI

Ends a Shell process.

Format: ENDCLI

Template: (none)

Location: Internal

ENDCLI ends a Shell process.

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).

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.

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.

GET

Gets the value of a local variable.

Format: GET <name>

Template: NAME/A

Location: Internal

GET is used to retrieve and display the value of a local environment variable. The value is displayed in the current window.

Local environment variables are only recognized by the Shell in which they are created or by any Shells created from a NEWSHELL command executed in the original Shell. If you open an additional Shell by opening the Shell icon or by using the Execute Command menu item, previously created local environment variables are not available.

Example

1> GET editor
Extras:Tools/MEmacs

GETENV

Gets the value of a global variable.

Format: GETENV <name>

Template: NAME/A

Location: Internal

GETENV is used to retrieve and display the value of a global environment variable. The value is displayed in the current window. Global variables are stored in ENV: and are recognized by all Shells.

Example

1> GETENV editor
Extras:Tools/MEmacs

ICONX

Note
ICONX is used only as a default tool in a project icon and cannot be used as a Shell command.

Allows execution of a script file of AmigaDOS commands from an icon.

Format: ICONX

Template: (none)

Location: C:

To use ICONX, create or copy a project icon for the script. Open the icon's Information window and change the Default Tool of the icon to C:ICONX and select Save to store the changed .info file. The script can then be executed by double-clicking on the icon.

When the icon is opened, ICONX changes the current directory to the directory containing the project icon before executing the script. A console window can be opened on the Workbench screen if the script produces output.

Several Tool Types can be specified in the script icon. The WINDOW Tool Type provides an alternate window specification for the input/output window. By default, the window's specification is:

WINDOW=CON:0/50//80/IconX/AUTO/WAIT/CLOSE

The AUTO option opens a window only if there is output created by the script. If a window opens, the WAIT option forces it to remain open after the script terminates until you specifically close it. The CLOSE option gives the window a close gadget.

The WAIT Tool Type (not to be confused with the WAIT option of the WINDOW Tool Type) specifies the number of seconds the input/output window should remain open after the script terminates. If you use this option the default input/output window cannot be closed before the WAIT period has expired. There is also a DELAY Tool Type that works in very similar way, except that its parameter is in 1/50th of a second, instead of in seconds.

The STACK Tool Type specifies the number of bytes to use for stack during script execution. If this Tool Type is not provided, the default 4096 bytes is used.

Finally, the USERSHELL Tool Type runs the script file using the current Use Shell instead of the normal ROM Shell. You must specify USERSHELL=YES. User Shells are third party shells that you can purchase and install in your system to replace the standard Amiga Shell environment that comes with the operating system.

Extended selection passes files that have icons to the script. Their file names appear to the script as keywords. To use this facility, the .KEY keyword must appear at the start of the script. In this case, the AmigaDOS EXECUTE command is used to execute the script file.

See also: EXECUTE. For examples using the ICONX command, see Chapter 8.

IF

Evaluates conditional operations in script files.

Format: IF [NOT] [WARN | ERROR | FAIL] [<string> EQ| GT | GE <string>] [VAL] [EXISTS <filename>]

Template: NOT/S,WARN/S,ERROR/S,FAIL/S,EQ/K,GT/K,GE/K,VAL/S,EXISTS/K

Location: Internal

In a script file, IF, when its conditional is true, carries out all the subsequent commands until an ENDIF or ELSE command is found. IF must be used in conjunction with ENDIF, however, ELSE is optional. When the conditional is not true, execution skips directly to the ENDIF or to an ELSE. The conditions and commands in IF and ELSE blocks can span more than one line before their corresponding ENDIFs.

Nested Ifs jump to the matching ENDIF.

The additional keywords are as follows:

NOT	Reverses the interpretation of the result.
WARN	True if previous return code is greater than or equal to 5.
ERROR	True if previous return codes is greater than or equal to 10; only available if FAILAT is set to greater than 10.
FAIL	True if previous return code is greater than or equal to 20; only available if FAILAT is set to greater than 20.
<a> GT	True if the test of a is greater than the text of b (disregarding case). Use NOT GT for less than.
<a> GE	True if the text of a is greater than or equal to the text of b (disregarding case). Use NOT GE for less than or equal to.
<a> EQ	True if the text of a and b is identical (disregarding case).
VAL	Specifies a numeric comparison.
EXISTS <file>	True if the file exists.

If more than one of the three condition-flag keywords (WARN, ERROR, FAIL) are given, the one with the lowest value is used.

You can use local or global variables with IF by prefacing the variable name with a $ character.

Example 1

IF EXISTS Work/Prog
   TYPE Work/Prog HEX
ELSE
   ECHO "It's not here"
ENDIF

AmigaDOS displays the file Work/Prog if it exists in the current directory. Otherwise, AmigaDOS displays the message It's not here and continues after the ENDIF.

Example 2

IF ERROR
   SKIP errlab
ENDIF
ECHO "No error"
LAB errlab

If the previous command produces a return code greater than or equal to 10, AmigaDOS skips over the ECHO command to the errlab label.

See also: EXECUTE, FAILAT, LAB, QUIET, SKIP. For more examples using the IF command, see Chapter 8.

INFO

Gives information about mounted devices.

Format: INFO [<device>]

Template: DEVICE

Location: C:

INFO displays a line of information about each mounted storage device, including floppy disk drive and hard disk partitions. Listed are the unit name, maximum size of the disk, the used and free space in blocks, the percentage of the disk that is full, the number of soft disk errors that have occurred, the status of the disk, and the name of the disk.

With the <device> argument, INFO provides information on the specified device or volume only.

Example

1>INFO

Unit Size Used Free Full Errs Status Name
DF0: 879K 1738 20 98% 0 Read Only Workbench
DF1: 879K 418 1140 24% 0 Read/Write Text-6

Volumes available:
Workbench [Mounted]
Text-6 [Mounted]

INSTALL

Writes or inspects a boot blocks on a formatted floppy disk or PCMCIA card, specifying whether it should be bootable.

Format: INSTALL [DRIVE] <DF0: | DF1: | DF2: | DF3: | CC0:> [NOBOOT] [CHECK] [FFS]

Template: DRIVE/A,NOBOOT/S,CHECK/S,FFS/S

Location: C:

INSTALL clears a floppy disk's or PCMCIA memory card's boot block area and writes a valid boot onto it. INSTALL does not affect any files or directories on the disk or card. The necessary files and directories must still be present on a device to boot from it successfully.

The NOBOOT option removes the boot block from an AmigaDOS disk or card, making it not bootable.

The CHECK option checks for valid boot code. It reports whether a disk or card is bootable and whether standard Commodore-Amiga boot code is present on the media. This is useful in detecting some viruses.

The FFS switch is ignored. It remains part of the template to ensure compatibility with earlier scripts and programs.

Example 1

1> INSTALL DF0: CHECK
No bootblock installed

indicates that there is a non-bootable floppy in DF0:.

Example 2

1> INSTALL DF0:

makes the disk in drive DF0: a bootable disk.

Example 3

1> INSTALL DF0: CHECK
Appears to be FFS bootblock

indicates that there is a bootable FFS floppy in DF0:.

JOIN

Concatenates two or more files into a new file.

Format: JOIN [FILE] <file | pattern>} AS | TO <filename>

Template: FILE/M/A,AS=TO/K/A

Location: C:

JOIN copies all the listed files, in the order given, to one new file. This destination file cannot have the same name as any of the source files. You must supply a destination file name. The original files remain unchanged. Any number of files can be JOINed in one operation.

TO can be used as a synonym for AS.

Example

1> JOIN Part1 Part2 Part3 AS Textfile

For another example using JOIN, see Chapter 8.

LAB

Specified a label in a script file.

Format: LAB [<string>]

Template: (none)

Location: Internal

LAB is used in script to define a label that is searched for by the SKIP command. The label <string> can be of any length, but must be alphanumeric. No symbols are allowed. If the <string> contains spaces, it must be enclosed in quotation marks.

See also: SKIP, IF, EXECUTE. For more examples using LAB, see Chapter 8.

LIST

Lists specified information about directories and files.

Format: LIST [{<dir | pattern | filename>}] [P | PAT <pattern>] [KEYS] [DATES] [NODATES] [TO <name>] [DUB <string>] [SINCE <date>] [UPTO <date>] [QUICK] [BLOCK] [NOHEAD] [FILES] [DIRS] [LFORMAT <string>] [ALL]

Template: DIR/M,P=PAT/K,KEYS/S,DATES/S,NODATES/S,TO/K,SUB/K,SINCE/K,UPTO/K,QUICK/S,BLOCK/S,NOHEAD/S,FILES/S,DIRS/S,LFORMAT/K,ALL/S

Location: C:

LIST displays information about the contents of the current directory. If you specify a <dir>, <pattern>, or <filename> argument, LIST displays information about the specified directory, all directories or files that match the pattern, or the specified file, respectively. The PAT argument lets you specify an additional pattern to match.

Unless other options are specified, LIST displays the following:

name	The name of the file or directory.
size	The size of the file in bytes. If there is nothing in this file, the field reads "empty". For directories, this entry reads "Dir".
protection	The protection bits that are set for this file are shown as letters. The clear (unset) bits are shown as hyphens. Most files show the default protection bits, ----rwed for readable/writable/executable/deletable. See the PROTECT command for more on protection bits.
date and time	The date and time the file was created or last changed.
comment	The comment, if any, placed on the file using the FILENOTE command. It is preceded by a colon (:).

LIST uses the following options to change the way the output is displayed:

KEYS	Displays the block number of each file header or directory.
DATES	Displays dates. (For example, DD-MMM-YY is the USA default).
NODATES	Does not display date and time information.
TO <name>	Specifies an output file or device for LIST; by default, LIST outputs to the current window.
SUB <string>	Lists only files containing the substring <string>.
SINCE <date>	Lists only files timestamped on or after the specified date.
UPTO <date>	Lists only files timestamped on or before the specified date.
QUICK	Lists only the names of files and directories.
BLOCK	Displays file sizes in 512-byte blocks, rather than bytes.
NOHEAD	Suppresses printing of the header and summary information.
FILES	Lists files only (no directories).
DIRS	Lists directories only (no files).
LFORMAT	Defines a string to specially format LIST output.
ALL	Lists the contents of all directories and subdirectories.

The LFORMAT option modifies the output of LIST and can be used as a quick method of generating script files. When using LFORMAT, specify an output format string; this string is output for each file or directory normally listed. It can contain any text you specify, plus the usual LIST output information. When LFORMAT is specified, the QUICK and NOHEAD options are automatically selected. To save the output, you must redirect it to a file by using the > operator or specifying a TO file. (For examples using the LIST LFORMAT option, see Chapter 8.)

The available substitution operators are:

%A	Prints file attributes (protection bits).
%B	Prints size of file in blocks.
%C	Prints any comments attached to the file.
%D	Prints the date associated with the file.
%E	Prints just the file extension.
%K	Prints the file key block number.
%L	Prints the length of the file in bytes.
%M	Prints the file name only, omitting any extension.
%N	Prints the name of the file.
%P	Prints the file parent path.
%S	Superseded by %N and %P; still functional.
%T	Prints the time associated with the file.

You can put a length specifier and/or a justification specifier between the percent sign (%) and the field specifier. To specify left justification, place a minus sign (-) before the length specifier. Otherwise, the information displayed is right justified.

The default output of the LIST command uses the following specification:

%-24 %7L %A %D %T

Example 1

> LIST Dirs

Prefs Dir ----rwed 27-Jun-93 11:43:59
T Dir ----rwed 16-Jul-93 11:37:43
Trashcan Dir ----rwed 21-Jun-93 17:54:20

Only the directories in the current directory, in this case SYS:, are listed. (A shortened version of the typical output is shown above.)

Example 2

1> LIST LI#? TO RAM:Libs.file

LIST searches for any directories or files that start with LI. The output of LIST is sent to Libs.file in RAM:.

Example 3

1> LIST DF0:Documents UPTO 09-Oct-90

Only the files or directories in the Documents directory of DF0: that have not been changed since October 9, 1990 are listed.

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

LOADRESOURCE

Preloads resources into memory to avoid excessive disk swaps.

Format: LOADRESOURCE {<name>} [LOCK | UNLOCK]

Template: NAME/M,LOCK/S,UNLOCK/S

Location: C:

LOADRESOURCE reduces the need for excessive disk swaps on floppy-only systems by preloading the following of resources into memory:

Libraries	Specify the path name to the library.
Devices	Specify the path name to the device; you cannot LOCK devices into memory.
Fonts	Specify the path name to the exact font file to be loaded.
Catalogs	Specify a path name as LOCALE:Catalogs/<language>/Sys/<catalog>.

The {<name>} option specifies the paths of the resources to load. The LOCK option tells the command to lock resources, such as libraries, fonts, and catalogs, into memory. This prevents the system from flushing the resource from RAM if memory is low. Although you can preload devices into memory using LOADRESOURCE, you cannot force them to stay in memory using the LOCK option. The UNLOCK option tells the command to unlock the resource from memory, allowing it to be flushed from RAM.

Entering LOADRESOURCE with no options lists all the LOCKed resources in RAM.

Example 1

LOADRESOURCE LIBS:asl.library

loads asl.library into memory. The system can flush this library from RAM the next time it runs low on memory, unless the LOCK option is included in the command line.

Example 2

LOADRESOURCE FONTS:topaz/11

loads the Topaz 11 font into memory.

Example 3

LOADRESOURCE LOCALE:Catalogs/English/Sys/monitors.catalog

is a valid path name.

LOADWB

Starts Workbench.

Format: LOADWB [-DEBUG] [DELAY] [CLEANUP] [NEWPATH]

Template: -DEBUG/S,DELAY/S,CLEANUP/S,NEWPATH/S

Location: C:

LOADWB starts the Workbench. Normally, this is in the Startup-sequence file that starts Workbench when booting. If you close the Workbench, LOADWB can restart it from a Shell.

The -DEBUG option makes a special developer menu, Debug, available in the Workbench menu bar. If the DELAY option is specified, LOADWB waits three seconds before executing to allow disk activity time to stop. The CLEANUP option automatically performs a cleanup of the initial disk window.

Workbench snapshots the current paths in effect when the LOADWB command is executed. It uses these paths for each Shell started from Workbench. NEWPATH allows you to specify a new path that is snapshot from the current Shell.

Example 1

If you quit the Workbench and are working through a Shell, enter:

1> LOADWB

to return the Workbench. Entering LOADWB when the Workbench is already loaded has no effect.

Example 2

1> PATH DF2:bin ADD
1> LOADWB NEWPATH

loads the Workbench. Any Shells started from the icon have the same path as the Shell used to run the LOADWB NEWPATH command.

LOCK

Sets the write-protect status of a device.

Format: LOCK <drive> [ON | OFF] [<passkey>]

Template: DRIVE/A,ON/S,OFF/S,PASSKEY

Location: C:

LOCK sets or unsets the write-protect status of a device or partition. The LOCK remains on until the system is rebooted or until the LOCK is turned off with the LOCK OFF command.

An optional passkey can be specified. If the passkey is used to lock a hard disk partition, the same passkey must be specified to unlock the partition. The passkey can be any number of characters long.

Example

1> LOCK Work: ON SecretCode

The Work partition is locked. You can read the contents of Work with commands such as DIR, LIST, or MORE but you cannot alter the contents of the partition. If you try to edit the contents of a file on Work, a requester indicates that Work is write-protected. For example, if you try to create a new directory by entering the following:

1> MAKEDIR WORK:Test

the following message appears:

Can't create directory Work:Test
Disk is write-protected

To unlock the partition, enter:

1> LOCK Work: OFF SecretCode

Locking a device is only good for the duration of the current session. Resetting or turning off the Amiga cancels the lock.

MAGTAPE

Retensions, rewinds, or skips forward SCSI (Small Computer System Interface) tapes.

Format: MAGTAPE [DEVICE <device name>] [UNIT <n>] [RET | RETENSION] [REW | REWIND] [SKIP <n>]

Template: DEVICE/K,UNIT/N/K,RET=RETENSION/S,REW=REWIND/S,SKIP/N/K

Location: C:

By default, MAGTAPE uses SCSI device unit 4. To change the default, you must use both the DEVICE and UNIT keywords.

The RET | RETENSION option runs the tape to the end and rewinds it. The REW | REWIND option rewinds the tape. The SKIP <n> option skips <n> files on the tape.

MAGTAPE tests to see if the unit is ready before sending the command. If your tape is not on-line, repeat the command.

Example

1> MAGTAPE DEVICE second_scsi.device UNIT 0 REW

MAKEDIR

Creates a new directory.

Format: MAKEDIR {<name}

Template: NAME/M

Location: C:

MAKEDIR creates new, empty directories with the names you specify. The command works within only one directory level at a time, so any directories on the given paths must already exist. The command fails of a directory or a file of the same name already exists in the directory in which you attempt to create a new one.

MAKEDIR does not create a drawer icon for the new directory.

Example 1

1> MAKEDIR Tests

creates a directory called Tests in the current directory.

Example 2

1> MAKEDIR DF1:Xyz

creates a directory Xyz in the root directory of the disk in DF1:.

Example 3

1> CD DF0:
1> MAKEDIR Documents Payables Orders

creates three directories on the disk in DF0:: Documents, Payables, and Orders.

For more examples using MAKEDIR, see Chapter 8.

MAKELINK

Creates a link between files.

Format: MAKELINK [FROM] <file> [TO] <file> [HARD] [FORCE]

Template: FROM/A,TO/A,HARD/S,FORCE/S

Location: C:

MAKELINK creates a FROM file, known as a link, that is a pointer to another file, the TO file, on the disk. When an application or command falls the FROM file, the TO file is used. By default, MAKELINK supports hard links: the FROM file and TO file must be on the same volume.

Normally, MAKELINK does not support directory links. To create a directory link, you must use the FORCE option. If MAKELINK detects that you are creating a circular link, such as a link to a parent directory, a Link loop not allowed message is issued.

MOUNT

Makes a device connected to the system available.

Format: MOUNT {device} [FROM <filename>]

Template: DEVICE/M,FROM/K

Location: C:

MOUNT reads a device's configuration parameters from a file. It then uses the parameter information to mount the devices or make them available to the system. Multiple devices can be mounted with a single command. The {device} argument specifies the names of the devices to be mounted.

MOUNT can process either DOSDrivers mount files or a traditional multiple-entry MountList file, depending on which of the following three ways the arguments are specified:

Given a device name, MOUNT tries to find a mount file of that name in DEVS:DOSDrivers, then in SYS:Storage/DOSDrivers, and finally as an entry in DEVS:MountList. This method is best if you have only one configuration for that device on your system.
Given a path, MOUNT looks for a mount file in that location. Wildcards may be used to mount multiple devices; as in MOUNT DEVS:DOSDrivers/~(#?.info). Use this method when you have mount files stored somewhere other than the DOSDrivers drawers or if you have several mount file to process at once.
Given the FROM keyword and a path, MOUNT specifies the location of a MountList file to process. Use this method if you have a MountList stored somewhere other than DEVS: or if you have several MountLists.

Note
A mount file's icon Tool Types, if any, override parameters of the same name in the mount file itself.

Example 1

1> MOUNT PIPE:

This looks for the mount file DEVS:DOSDrivers/PIPE and processes it if found. If DEVS:DOSDrivers/PIPE does not exist, MOUNT looks for SYS:Storage/DOSDrivers/PIPE. If this also fails, then MOUNT looks for a PIPE: entry in DEVS:MountList.

Example 2

1> MOUNT Work:Devices/PIPE

This looks for a PIPE mount file in Work:Devices.

Example 3

1> MOUNT PIPE: FROM SYS:Mydevs/MountList

This scans for a PIPE entry in SYS:Mydevs/MountList.

See Appendix B for further information on MountLists.

NEWCLI

Opens a new Shell window.

Format: NEWCLI [<window specification>] [FROM <filename>]

Template: WINDOW,FROM

Location: Internal

NEWCLI starts a new Shell process. It is the same as using the NEWSHELL command.

NEWSHELL

Opens a new Shell window.

Format: NEWSHELL [<window specification>] [FROM <filename>]

Template: WINDOW,FROM

Location: Internal

The new Shell window becomes the currently-selected window and process. The new window has the same current directory, prompt string, path, local environment variables, and stack size as the one from which it is invoked. However, each Shell window is independent, allowing separate input, output, and program execution.

The window can be sized, dragged, zoomed, and depth-adjusted like most other Amiga windows.

To create a custom window, you can include the <window specification> argument. Specify the initial dimensions, location, and title of the window with this <window specification> syntax:

CON:x/y/width/height/title/options

where:

x	Is the number of pixels from the left edge of the screen to the left border of the Shell window. Use a value (//) to specify the minimum possible pixels.
y	Is the number of pixels from the top of the screen to the top of the Shell window. Use no value (//) to specify the minimum possible pixels.
width	Is the width of the Shell window, in pixels. Use no value (//) to specify the full width of the screen.
height	Is the height of the Shell window, in pixels. Use no value (//) to specify minimum possible height.
title	Is the text that appears in the Shell window title bar.

Use slashes to separate the parameters and options. If any spaces appear in the specification argument, the entire argument must be enclosed in double quotation marks (").

The allowable options are:

AUTO	The window automatically appears when the program needs input or produces output. With the Shell window, it opens for input immediately. The window can only be closed with the ENDSHELL command. Selecting the Shell's close gadget closes the window, but it re-opens immediately since it is expecting input.
ALT	The window appears in the specified size and position when the zoom gadget is clicked. The four parameters must be separated with slashes (for example, ALT30/30/200/200).
BACKDROP	The window appears on the backdrop, behind all the Workbench windows. This Shell window cannot be brought to the front of the screen; you have to resize the Workbench windows to see it.
CLOSE	The window has all the standard gadgets, including a close gadget. This is the default for Shell windows, but you must specify it to get a standard Shell if you use the WINDOW argument.
INACTIVE	The window opens, but is not made the active window.
NOBORDER	The window opens without any left or bottom window border. Only the zoom, depth, and sizing gadgets are available.
NOCLOSE	The window does not have a close gadget. If you open a console normally, there is no close gadget. If you open a console using the AUTO option, there is automatically a close gadget on the window.
NODEPTH	The window has no window depth gadget.
NODRAG	The window cannot be dragged. It has zoom, depth and sizing gadgets, but no close gadget.
NOSIZE	The window only has a depth gadget.
SCREEN	The window opens on a public screen. The screen must already exist. You must specify the name of the screen after the SCREEN keyword.
SIMPLE	If you enlarge the window, the text expands to fill the newly available space, allowing you to see text that had been scrolled out of the window. This is the default for standard Shells.
SMART	If you enlarge the window, the text does not expand to fill the newly available space. This saves memory.
WAIT	The window can only be closed by selecting the close gadget or entering Ctrl+\. If WAIT is the only option, there is no close gadget.

NEWSHELL uses the default startup file S:Shell-startup, unless a FROM file name is specified. S:Shell-startup is a standard AmigaDOS script file. For example, you can have several different Shell-startup files, each having different command aliases. You can call such customized Shell environments with FROM.

The NEWCLI command has the same effect as NEWSHELL; it invokes a new Shell process.

Example 1

1> NEWSHELL

opens a new Shell window with the default window specification.

Example 2

1> NEWSHELL "CON://640/200/My Shell/CLOSE"

A window starting in the upper left corner of the screen and measuring 640 pixels wide and 200 pixels high opens. The window is titled My Shell and it has a close gadget. The entire argument is enclosed in quotation marks because the title contains a space. If you add the command to your User-startup file, a Shell window opens automatically when your Amiga is booted.

Example 3

1> NEWSHELL FROM S:Programming.startup

opens a new Shell, but instead of executing the Shell-startup file, the Programming.startup file is executed. You can have aliases and prompt commands in the Programming.startup file that are used only when you are programming.

For more examples using NEWSHELL, see Chapter 8.

PATH

Controls the directory list that the Shell searches to find commands.

Format: PATH [{<dir>}] [ADD] [SHOW] [RESET] [REMOVE] [QUIET]

Template: PATH/M,ADD/S,SHOW/S,RESET/S,REMOVE/S,QUIET/S

Location: Internal

PATH lets you see, add to, or change the search path the AmigaDOS follows when looking for a command or program to execute. When a directory is in the search path, you do not need to specify the complete path to any command within that directory. Entering the name alone makes AmigaDOS look through the directories in the search path until it finds the file.

Note
The search path is only relevant when AmigaDOS is searching for a command or program to execute. Full path specifications are always necessary in arguments for commands such as COPY and DELETE.

Enter the PATH command alone or with the SHOW option to display directory names in the current search path. Normally, when PATH is displaying the directory names, a requester appears if a volume that is part of the search path cannot be found. For example, if you add a floppy disk to the search path and then remove that disk from the disk drive, a requester asks you to insert the disk.

If you specify the QUIET option, PATH does not display requesters for volumes that are not currently mounted. If PATH encounters an unmounted volume, it displays the message device (or volume) is not mounted . The names of any directories on that volume included in the PATH are not displayed.

The ADD option specifies directory to be added to the current PATH. You can add any number of directories with one PATH ADD command (the ADD keyword is optional); names of the directories must be separated by at least one space. When you issue the PATH command, AmigaDOS searches for each of the ADDed directories.

To replace the existing search path with a new one, use PATH RESET followed by the names of the new directories. The existing search path, except for the current directory and C:, is erased and the new one is substituted.

The REMOVE option eliminates the named directory from the search path.

Example

1> PATH EXTRAS:Tools ADD

adds the Tools directory in the Extras drawer to the search path of the Shell. If the EXTRAS: is not in a disk drive, a requester asks you to insert it in any drive.

If you remove EXTRAS: from the drive and enter:

1> PATH

a list of directories in the search path is displayed. A requester asks you to insert EXTRAS:. If you enter:

1> PATH QUIET

the list of directories in the search path is displayed. However, when the path comes to Extras:Tools, the error message appears in the list.

See also: ASSIGN. For more examples using PATH, see Chapter 8.

PROMPT

Changes the prompt string of the current Shell.

Format: PROMPT [<prompt>]

Template: PROMPT

Location: Internal

PROMPT allows you to customize the prompt string, the text printed by the Shell at the beginning of a command line. The prompt string can contain any characters, including escape sequences.

This manual shows the prompt string as 1>.

The default prompt string is:

"%N.%S>"

which displays the Shell number, a period, the current directory, a right angle-bracket, and a space. Entering PROMPT without a string argument resets the prompt to this default.

The substitutions available for the <prompt> string are:

%N	Displays the process number for the Shell.
%S	Displays the current directory.
%R	Displays the return code for the last operation.

A space is not automatically added to the end of the string. If you want a space between the prompt and typed-in text, place it in the string, and enclose the string in double quotation marks,

You can embed commands in the prompt string by enclosing the command in back apostrophes (`).

Example 1

1> PROMPT %N
1

Only the Shell number is shown. The > is removed from the prompt.

Example 2

1> PROMPT "%N.%S.%R>"
1.Work:Snim.0>

The Shell number, current directory, and return code of the previous command are shown. A space is included after the >.

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

PROTECT

Changes the protection bits of a file or directory.

Format: PROTECT [FILE] <file | pattern> [FLAGS][+ | -] [<flags>] [ADD | SUB] [ALL] [QUIET]

Template: FILE/A,FLAGS,ADD/S,SUB/S,ALL/S,QUIET/S

Location: C:

All files and directories have a series of protection bits (attributes) stored with them that control their properties. These bits can be altered to indicate the type of file and the operations permitted. PROTECT is used to set or clear the protection bits. For directories, only the d bit is significant.

The protection bits are represented by letters:

s	The file is a script.
p	The file is a pure command and can be made resident.
a	The file has been archived.
r	The file can be read.
w	The file can be written to (altered).
e	The file is executable (a program).
d	The file or directory can be deleted. (Files within a delete-protected directory can still be deleted.)

Use the LIST command to see the protection bits associated with a file. The protection field is displayed with set (on) bits shown by their letters and clear (off) bits shown by hyphens. For example, a file that is readable, writable, and deletable has ----rw-d in the protection field.

To specify the entire protection field at the same time, enter the letters of the bits you want set as the FLAGS argument without any other keywords. The named bits are set and all the others are cleared.

The symbols + and - (or the equivalent keywords ADD and SUB) are used to control specific bits without affecting the state of unspecified bits. Follow + or - with the letters of the bits to set or clear, respectively, and only those bits are changed. There is no space after the symbol or between the letters. The order of the letters does not matter. ADD and SUB work similarly, but there must be a space between the keyword and the letters. You cannot both set and clear bits in the same command.

The ALL options adds or removes the specified protection bits from all the files and subdirectories matching the pattern entered. The QUIET option suppresses the screen output.

Example 1

1> PROTECT DF0:Memo +rw

sets only the protection bits r (readable) and w (writable) of the file Memo on DF0:. No other protection bits are changed.

Example 2

1> PROTECT L:#? e SUB

clears the e (executable) protection bit from all the files in the L: directory.

Example 3

1> PROTECT Work:Paint rwed

The protection status of Paint becomes "----rwed".

QUIT

Exits from a script file with a specified return code.

Format: QUIT [<return code>]

Template: RC/N

Location: Internal

QUIT stops the execution of the script at the specified return code. The default return code is zero. We recommend you use the standard return code values of 5, 10, and 20.

Example

ASK "Do you want to stop now?"
IF WARN
   QUIT 5
ENDIF
ECHO "OK"
ECHO "The script is continuing."

If you press Y at the prompt, the script is aborted, since WARN is equal to a return code of 5. If you press N or press Return:

OK
The script is continuing.

Is displayed in the Shell window.

RELABEL

Changes the volume name of the disk in the given drive to the specified name.

Format: RELABEL [DRIVE] <drive> [NAME] <name>

Template: DRIVE/A,NAME/A

Location: C:

Volume names are set when disks are initially formatted. RELABEL allows you to change a disk's volume name to any name specified.

On floppy-only systems with one drive, be sure to specify the disks by volume name instead of drive name.

Examples

1> RELABEL Workbench: MyDisk

changes the name of the Workbench disk to MyDisk. No colon is necessary after the second name.

1> RELABEL DF2: DataDisk

changes the name of the disk in DF2: to DataDisk.

REMRAD

Removes the recoverable RAM disk.

Format: REMRAD [<device>] [FORCE]

Template: DEVICE,FORCE/S

Location: C:

REMRAD allows you to remove the recoverable RAM disk (usually mounted as RAD:) from memory without powering off the system. If you have mounted more than one recoverable RAM disk, use the DEVICE specification.

REMRAD instructs RAD: to delete all of its files and become inactive. However, the RAD: RAM_0 disk icon does not disappear. The next time the Amiga is rebooted. RAD: is removed from memory completely and the icon is no longer displayed.

If the device is in use when the REMRAD command is given, the operation aborts with a device in use message. To remove it if it is in use, you must use the FORCE option.

RENAME

Changes the name of or moves a file or directory.

Format: RENAME [FROM] {<name} [TO | AS] <name>

Template: FROM/A/M,TO=AS/A,QUIET/S

Location: C:

RENAME renames the FROM file or directory with the specified TO name. The FROM and TO files or directories must be on the same volume. If the name refers to a directory, RENAME changes the directory name without changing the names of the files or subdirectories in that directory. When there are multiple items in the FROM argument, the TO argument must be a directory.

If you rename a directory or if you use RENAME to give a file another directory name, AmigaDOS changes the position of that directory or file in the filing system hierarchy. This effectively moves the items.

Example 1

1> RENAME Work/Ex1 AS :Test/Ex2

renames the file Ex1 as Ex2 and moves it from the Work directory to the Test directory. The Test directory must exist in the root directory for this command to work.

Example 2

1> RENAME 3.doc 5.doc a.doc TO Docs

moves the 3.doc, 5.doc, and a.doc files to the Docs directory. The Docs directory must already exist.

REQUESTCHOICE

Allows AmigaDOS and ARexx scripts to use custom requesters.

Format: REQUESTCHOICE >TITLE> <body> {<gadgets>} [PUBSCREEN <public screen name>]

Template: TITLE/A,BODY/A,GADGETS/A/M,PUBSCREEN/K

Location: C:

The <title> argument specifies the title of the requester.

The <body> argument specifies the text of the requester. Linefeeds can be embedded using *N.

The <gadgets> argument specifies the text for the different gadgets. The gadget labels are separated with spaces.

The number of the selected gadget is printed as a result to the console. For evaluation in a script file, you can redirect this output into an environment variable. If the requester cannot be opened, the command generates a return code of 20.

The PUBSCREEN argument allows the requester to open its window on a public screen.

Example

1> RequestChoice >ENV:rcnum "New Title" "This is my requester*nSelect a gadget" "OK" "Maybe" "Cancel"

Sample RequestChoice Requester

ENV:rcnum contains 0, 1, or 2 after a gadget is selected. The script can use this value to control its later execution.

REQUESTFILE

Allows AmigaDOS and ARexx scripts to use a file requester.

Format: REQUESTFILE [Drawer <drawer name>] [FILE <file>] [PATTERN <pattern>] [TITLE <title>] [POSITIVE <text>] [NEGATIVE <text>] [ACCEPTPATTERN <pattern>] [REJECTPATTERN <pattern>] [SAVEMODE] [MULTISELECT] [DRAWERSONLY] [NOICONS] [PUBSCREEN <public screen name>]

Template: DRAWER,FILE/K,PATTERN/K,TITLE/K,POSITIVE/K,NEGATIVE/K,ACCEPTPATTERN/K,REJECTPATTERN/K,SAVEMODE/S,MULTISELECT/S,DRAWERSONLY/S,NOICONS/S,PUBSCREEN/K

Location: C:

When entered with no arguments, a file requester with OK, Volumes, Parent, and Cancel buttons is created. Ist Drawer and File gadgets are empty and it displays the contents of the current directory.

The DRAWER argument specifies the initial contents of the Drawer gadget.

The FILE option specifies the initial contents of the File gadget.

The PATTERN option allows the use of a standard AmigaDOS pattern. It includes a Pattern gadget in the requester and specifies the initial contents of the gadget. If this option is not provided, the file requester does not have any Pattern gadget.

The TITLE option specifies the title of the requester.

The POSITIVE option specifies the text to appear in the positive (left) choice in the file requester.

The NEGATIVE option specifies the text to appear in the negative (right) choice in the file requester.

The ACCEPTPATTERN option specifies a standard AmigaDOS pattern. Only files matching this pattern are displayed in the file requester.

The REJECTPATTERN option specifies a standard AmigaDOS pattern. Files matching this pattern are not displayed in the file requester.

If SAVEMODE is specified, the requester is used for writing files to disk. If MULTISELECT is specified, the requester allows multiple files to be selected at once. If DRAWERSONLY is specified, the requester does not have a File gadget. This effectively turns the file requester into a directory requester. If NOICONS is specified, the requester does not display icons (.info files).

The selected files are returned on the command line, enclosed in double quotation marks and separated with spaces. The command generates a return code of 0 if you select a file or 5 if you cancel the requester.