AmigaOS Manual: AmigaDOS Command Examples

The command examples elsewhere in this book are primarily to illustrate the proper syntax and general operation of AmigaDOS. This chapter shows you how to use the commands needed for a wide variety of common tasks.

The chapter is organized as follows:

• Basic tasks
• Occasional tasks
• Advanced tasks

Basic Tasks

This section is oriented toward the novice Shell user, showing commands and short scripts to accomplish basic tasks. Use the commands shown as models for your own commands, substituting the names of your disks, directories, and files. To use the commands, type what appears after the prompt (usually 1>). Press Return to enter the command line you type.

Opening a Shell Window

To open a Shell window from Workbench:

1. Open the System drawer on your Workbench disk or partition.
2. Double-click on the Shell icon.

OR

1. Choose the Execute Command... item from the Workbench menu.
2. In the requester that appears, enter the command NEWSHELL.

To open another Shell window from a Shell, enter the NEWSHELL command at a Shell prompt:

1> NEWSHELL

Running Programs from the Shell

To run a program that is on the search path, enter the program name at the prompt:

1> CLOCK

To run a program that is not on the search path, enter the full path to the program:

1> Tempus:Fugit/Utils/SuperClock

To run a program that is not on the search path but is in a subdirectory of the current directory, enter the relative path to the program:

1> Utils/SuperClock

Stopping a Program

AmigaDOS commands and most Workbench programs started from the Shell can be exited, or stopped if currently running, by pressing Ctrl+C. This is important in case you need to abort a pattern matching DELETE, or to interrupt a directory listing or other lengthy process. Scripts can be stopped with Ctrl+D.

To stop a command or program that is currently running:

1. Make the Shell window from which the command or program was started the current window by clicking in it.
2. Press Ctrl+C.

In some cases you may need to press Return after Ctrl+C to bring back the Shell prompt.

To stop a script that is currently running:

1. Make the Shell window from which the script was started the current window by clicking in it.
2. Press Ctrl+D.

Changing the Current Directory

The current directory is normally part of the standard Shell prompt, as in 1.Workbench:>. In the following examples, notice the prompt to see how the current directory changes.

To save typing, change the current directory to the one in which you are working.

If you are issuing two or more commands that refer to things in a certain directory, make it the current directory using the CD command. The following two sets of commands both accomplish the same task:

1.Work:> COPY Storage/Keymaps/usa2 TO DEVS:Keymaps
1.Work:> DELETE Storage/Keymaps/usa2

1.Work:> CD Storage/Keymaps
1.Storage:Keymaps> COPY usa2 TO DEVS:Keymaps
1.Storage:Keymaps> DELETE usa2

Entering the second set of commands instead of the first saves over a dozen keystrokes. This savings is even greater if further work in Storage/Keymaps is needed.

To change the current directory with as little typing as possible, omit the CD command, and use the slash and colon to move though the directory structure:

1.Workbench:Devs/Monitors> /Printers
1.Workbench:Devs/Printers> :Prefs/Presets
1.Workbench:Prefs/Presets> /
1.Workbench:Prefs>

To switch quickly between two current directories, use the PCD script (located in the S: directory):

1.Workbench:> PCD Devs/DOSDrivers
1.Workbench:Devs/DOSDrivers> Extras:Storage
1.Extras:Storage> PCD
1.Workbench:>

To see the current directory, if the Shell prompt does not show it, use the CD command alone:

1> CD
Workbench:

Changing the Search Path

To create a directory on the SYS: volume for additional commands and add it to the search path for the current Shell:

1> MAKEDIR SYS:MyCommands
1> PATH SYS:MyCommands ADD

To add MyCommands to the search path, effective for the whole system, use an ASSIGN command instead of PATH:

1> ASSIGN C: SYS:MyCommands ADD

To have the Amiga look for commands in a C directory on any disk inserted in drive DF0:, use ASSIGN with the PATH option:

1> ASSIGN C: DF0: C PATH 

Displaying the Contents of a Directory

To display the names of files and subdirectories in a directory use DIR:

1> DIR DEVS:
DataTypes (dir)
Monitors (dir)
DOSDrivers (dir)
Keymaps (dir)
Printers (dir)
clipboard.device DataTypes.info
DOSDrivers.info Keymaps.info
mfm.device Monitors.info
parallel.device postscript_init_ps
printer.device Printers.info
serial.device system-configuration

To display the names of files, subdirectories, and files in the subdirectories in a directory, add the ALL keyword (a partial listing of the output is shown here):

1> DIR DEVS: ALL
DataTypes (dir)
8SVX 8SVX.info
AmigaGuide AmigaGuide.info
ANIM ANIM.info
CDXL CDXL.info
FTXT FTXT.info
ILBM ILBM.info
Monitors (dir)
A2024 A2024.info

To display the names of files only, with no directories, add the FILES keyword:

1> DIR DEVS: FILES
clipboard.device DataTypes.info
DOSDrivers.info Keymaps.info
mfm.device Monitors.info
parallel.device postscript_init_ps
printer.device Printers.info
serial.device system-configuration

To display the names of files only, without .info files, use pattern matching:

1> DIR DEVS:~ (#?.info) FILES
clipboard.device mfm.device
parallel.device postscript_init_ps
printer.device serial.device
system-configuration

To display information about files that includes their size and protection bits, without date and time, use LIST with the FILES and NODATES keywords:

1> LIST DEVS:~ (#?.info) FILES NODATES
clipboard.device 6944 ----rw-d
mfm.device 6684 ----rw-d
parallel.device 4272 ----rw-d
postscript_init_ps 5014 ----rw-d
printer.device 27420 ----rw-d
serial.device 5412 ----rw-d
system-configuration 232 ----rw-d

To display information about a single file, use LIST with the path on the file:

1> LIST S:Startup-sequence
Directory "S:" on Tuesday 01-Dec-92
Startup-sequence 1360 -s--rw-d 30-Oct-92 12:00:21
1 file - 4 blocks used

To display the amount of space used by a directory and its contents, including all files in subdirectories, use the ALL keyword:

1> LIST ALL

After the contents of the current directory are listed, a summary line such as the following is displayed:

TOTAL: 113 files - 762 blocks used

Divide the number of blocks by two to get the number of kilobytes (KB).

To see information from LIST, DIR, or other commands that have scrolled off the Shell window:

Select the Shell window's zoom gadget once to switch to its alternate size, which normally fills the screen. As much of the previous output as fits fills the window. Select zoom again to restore the window to its previous size.

If the window's maximum height is not large enough to reveal the desired output, reissue the command by pressing the up arrow and then Return. Pause and resume the scrolling of the output when necessary by pressing the spacebar and backspace, respectively.

To combine the CD and DIR commands:

Create the following script and save it as S:CDD. (For an example of how to create a script, see "Creating a User-startup File" on page 8-8.)

.KEY dirpath
CD <dirpath>
DIR

Set the script's protection bit by entering PROTECT S:CDD +s. Then whenever you enter CDD followed by the path to a directory, this script makes that directory the current directory and lists its contents.

Copying Files and Directories

When copying a single file from one place to another, you need to include only the paths for each. FROM and TO keywords are optional. For clarity, most COPY examples in this book use the TO keyword, but omit the FROM keyword.

To copy a file to an existing directory using optional keywords:

1> COPY FROM DF0: Pix/Fractal3 TO Work:Pictures

To copy the file omitting optional keywords:

1> COPY DF0: Pix/Fractal3 Work:Pictures

To copy a file and rename it at the same time, include the new file name in the TO argument:

1> COPY DF0: Pix/Fractal3 TO Work:Pictures/BestPic

To copy all the files in a directory to another directory, without copying the directory itself or the subdirectories it contains:

1> COPY DF0:Pix TO Work:Pictures

The contents of DF0:Pix are deposited in Work:Pictures, not grouped in their own directory. If Pix contained directories, they are not copied, but any .info files for drawers Pix contained are copied, making it appear at first that the drawers were copied.

To copy all the files in a directory to another directory, copying the directory itself but not the subdirectories it contains:

1> COPY DF0:Pix TO Work:Pictures/Pix

The directory Pix is created in Work:Pictures if it does not already exist. The destination directory does not have to be the same name as the source; you can copy to Work:Pictures/Fractals, for example.

To copy a complete directory and its contents to another directory, use the ALL keyword:

1> COPY DF0:Pix TO Work:Pictures/Pix ALL

Work:Pictures/Pix is a duplicate of DF0:Pix.

To copy only certain files to another directory, use pattern matching if their names are similar:

1> COPY DF0:Pix/Fractal[3-7] TO Work:Pictures/Pix

Files in DF0:Pix with names beginning in Fractal and ending in the digits 3 through 7 are copied.

To copy specific files to another directory, include all the file names. Change to the source directory first to avoid having to enter the full path for each:

1> CD DF0:Pix
1> COPY Fractal3 Julia Dragon TO Work:Pictures/Pix

When copying more than one file at once without using the TO keyword, COPY excepts the last name to be the destination directory. With whole-directory, multiple-file, and pattern matching operations, COPY outputs the names of the files copied and directories created as it executes.

Creating a User-startup File

A User-startup file is the Shell equivalent of the Workbench WBStartup drawer. It is a text file that is executed as a script by the default Startup-sequence. Place here any configuration commands, such as ASSIGNs, and the names of programs you wish to run automatically whenever you boot.

To create a User-startup file:

1> RUN ED S:User-startup

After the ED window opens, enter the commands you want on subsequent lines. For example, you can add some cache buffers to speed floppy access, add a directory of custom commands to the path, and start the screen blanker, by entering these lines:

ADDBUFFERS >NIL: DF0: 25
PATH >NIL: SYS:MyCommands ADD
RUN Blanker CX_POPUP=NO SECONDS=600 ANIMATION=YES

Then save the file and exit by pressing Esc,X,Return. The next time you boot or reboot, these commands are executed. When you have more commands to add, edit the file by entering RUN ED S:User-startup again.

Creating an Assignment

On a floppy-only system, a requester similar to that illustrated in Figure 8-1 usually means that you need to insert the named floppy disk.

Command Sample System Requester

The most likely reason for this requester on a hard disk system, aside from entering a command with a misplaced colon (:), is that an application you are running requires an assignment to be made with the ASSIGN command. This is often done for you by an installation program, but not all applications have an installation program or one that works correctly for all systems.

The assignment tells the application to look on your hard drive instead of a floppy drive for things it needs. If the application is one you use regularly, you should place the ASSIGN statement in your User-startup. When the requester first comes up, however, you can enter the assignment in the Shell and then select the requester's Retry gadget.

To allow you to continue your work with a program installed from a disk called ProFusion to the Work:volume, enter the statement:

1> ASSIGN ProFusion: Work:ProFusion

where the first argument is the volume requested, followed by a colon, and the second argument is the device and directory where ProFusion is installed. Click the Retry gadget after entering the command. If the statement is correct, your application works properly and you should add the statement you entered to your User-startup. If it does not work, the second argument needs to be modified.

Accessing the Expanded ED Menus

The default S:Ed-startup file sets up a series of menus for the ED text editor. There is also an expanded set of menus that is built into ED, containing more options. You can make these available by renaming Ed-startup, which prevents it form being executed.

To allow access to the expanded ED menus, enter the following command:

1> RENAME S:Ed-startup TO S:Ed-startup.not 

Working with a Single Shell

Although you can open several independent Shell windows at once, you may wish to avoid cluttering the Workbench screen with several windows. Starting a program from a Shell normally takes over that Shell window while the program is running, forcing you to open another Shell to enter additional commands. Use the following techniques to avoid this and allow any number of programs to run from a single Shell.

To run a program in the background so that the Shell window prompt returns, use the RUN command:

1> RUN DMC OPT def RHYME on
[CLI 2]
1>

The message in square brackets indicates the number of the new process started to run the program. The prompt returns immediately.

Even when a program is run this way, the Shell window cannot be closed until all programs started from it are exited. To avoid this, you can detach the program using redirection.

To detach a program, RUN it, adding output redirection to the NIL: device:

1> RUN >NIL: MultiView 8SVX/Sample
[CLI 2]
1>

You can now close the Shell window if necessary.

Note
Redirection to NIL: also prevents any console output the program produces from appearing in the Shell window.

Attaching Icons

To attach an icon to a file or directory, you can create an icon with the IconEdit tool. However, it is often easier just to copy an existing icon with a Shell command.

You must copy a .info file of the right icon type, giving it a name that matches the file or directory to which you are attaching it plus the .info extension. If necessary, use the Information menu item to adjust the Default Tool of a copied Project icon, or the Tool Types of a copied Tool icon, as appropriate for the file.

Note
The capitalization of the name under the icon matches that given in the COPY command, regardless of the capitalization of the associated file or directory.

To attach an icon to a file called PCX in the DataTypes directory, copy the .info file of an existing DataType in the directory:

1> COPY DataTypes/ILBM.info TO DataTypes/PCX.info

An icon titled PCX appears in the DataTypes window when you open it or choose Update from the Window menu.

Note
If the icon you copy is snapshotted, the new icon retains the original icon's position and appears directly on top of it. Drag the new icon on a different position and Snapshot it to keep the two icons separate.

To attach a custom icon to a disk called VidTools, copy the desired disk-type .info file to the root directory of the disk, giving it the name disk.info:

1> COPY SYS:disk.info TO VidTools:disk.info

You must eject and reinsert the disk or reboot for a new disk icon to appear on the Workbench.

Creating Scripts Conveniently

To make creating and editing scripts easier:

Create a script containing the following lines, and save it as S:Edscr. (For an example of how to create a script, see "Creating a User-startup File" on page 8-8.)

.KEY script/A
ED S:<script>
FAILAT 11
IF EXISTS S:<script>
   PROTECT S:<script> srwd
ENDIF

Set the script's protection bit by entering PROTECT S:Edscr srwd. Now using Edscr you can create and edit scripts without having to decide where to put them or remember to set their s bit. Just enter Edscr followed by the name of a script.

When you save and exit from ED, the script you worked on is saved in the S: directory under the name you gave. Its s protection bit is set automatically so that you can run the script from a Shell without needing the EXECUTE command.

Occasional Tasks

Tasks in this section are used les often, but almost every user needs to do these things at some time. These examples assume a certain amount of familiarity with AmigaDOS and the Shell.

Creating Aliases To Reduce Keystrokes

The aliases listed below can help speed your Shell work by reducing the number of keystrokes required for common commands.

To enable these as global aliases, edit S:Shell-startup as described previously for User-startup, adding these lines:

ALIAS c0 CD DF0:
ALIAS cs CD SYS:
ALIAS css CD S:
ALIAS d0 DIR DF0:
ALIAS dr DIR RAM:
ALIAS qdir DIR ~ (#?.info)
ALIAS 1s LIST
ALIAS cp COPY
ALIAS cc COPY [] CLONE
ALIAS del DELETE
ALIAS ren RENAME
ALIAS ns NEWSHELL
ALIAS es ENDSHELL
ALIAS pf printfiles
ALIAS fmt0 FORMAT DRIVE DF0: NAME [] FFS NOICONS DIRCACHE
ALIAS edus RUN ED S:User-startup
ALIAS edsh RUN ED S:Shell-startup
ALIAS ednew RUN ED RAM:newfile
ALIAS chip ECHO "There are `avail chip` bytes of Chip memory free."

Modify the alias names as desired. Use these as models for your own aliases.

Customizing NEWSHELL

You can control the Shell window with the WINDOW argument of the NEWSHELL command. It allows you to specify custom sizes, positions, and features for the Shell window. Following are two examples of different window specifications.

To open a convenient Shell window on your Workbench screen, enter the following command in a Shell or as a line in User-startup:

NEWSHELL CON://400/100/Ashell/CLOSE/ALT0/12/640/388

This creates a small Shell window titled AShell that leaves the left side of the Workbench window clear so that disk icons are not obscured. It has a close gadget and, on a High-Res Interlace screen, it expands to fill the entire screen for the screen title bar when you select its zoom gadget.

To open a Shell window on a public screen, such as telecommunication program's terminal screen, use a window specification with the SCREEN option:

CON:0/20//???/CLOSE/SCREENTerm

This creates a Shell window called ??? that is near the top of the screen and is as wide and short as possible. The window opens on a public screen named Term, if that screen is available. It it is not, the Shell opens on the Workbench screen.

Modifying the Prompt

The Shell prompt is easily modified using the PROMPT command. You can add any fixed text to the prompt string and include, reorder, or leave out the substitution operators that display the process number, current directory, and return code. Placing escape sequences in the prompt string lets you make the prompt stand out visually from the command line and command output. You can also embed a command in the prompt with the back apostrophe feature.

Figure 8-2 illustrates two ways of modifying the prompt. The first uses escape sequences to produce a boldface, color 2 (white) prompt; see Appendix D for a listing of escape sequences. The second shifts the usual position of the substitution operators, embeds a DATE command using the back apostrophe, and changes the final character to a dollar sign ($).

Sample Uses of PROMPT Command

Creating a Custom Ram Disk Icon

To have a custom icon for the Ram Disk, you need to place a COPY statement in User-startup. First, create the icon in IconEdit. Make sure it is a Disk type icon, then save it on your boot disk as DEVS:Ramdisk.info.

Note
This example uses the DEVS: directory, but it does not matter where you store this icon. It is not visible, even in Show All Files mode, because Disk icons are visible only in the Workbench window.

To make your custom Ram Disk icon appear in the Workbench window, enter this line in the S:User-startup file, save the changed file, and reboot:

COPY DEVS:Ramdisk.info TO RAM:disk.info

If you also want to rename Ram Disk, include a RELABEL statement in User-startup after the COPY statement, such as:

RELABEL RAM:ramname

Deleting Files with Icons

To delete a file that has an icon and the file's.info file with a single command:

1. Create and save the following script as S:Delinf:

.KEY file/A
DELETE <file> <file>.info QUIET

2. Enter EXECUTE Delinf with the name of the file as its argument.

Testing Commands

It is sometimes necessary to test the results of certain commands before using them on actual files. This is particularly true when using complex pattern matching with potentially destructive commands, such as DELETE, or escape sequences, with which it can be difficult to predict the outcome. There are various ways of testing commands that are quick and safe.

To test a potentially destructive pattern matching command:

1. Enter a non-destructive command such as LIST containing the pattern. For example,
   LIST ~ (#?.info|#?.c| [0-9]#?)
2. Check the output to see whether the intended files were matched.
3. Modify the pattern if necessary and repeat the command until the command lists only the desired files.
4. Enter the intended command, using the same pattern.

To test the effects of escape sequences:

1. Enter an ECHO command containing the escape sequences and an example word. For example,
   ECHO "*E[1mBOLD*E[Om"
2. Check to see whether the output is as intended.
3. Modify the escape sequences if necessary and repeat the command until the desired result appears.
4. Use the escape sequences in the intended command, such as PROMPT.

To clear the window and reset all escape sequence modes to the defaults, enter:

Esc,c,Return

You must use a lower case c. After the window is cleared and reset, the Shell displays a harmless :Unknown command message on the window's top line.

To create a test file in the Ram Disk, enter:

1> ECHO "This is only a test" TO RAM:foo

This provides a small, expendable file on which to test other commands. It is best to create such files in RAM:, to avoid cluttering your disks with small, useless files. Traditionally, files like this are named "foo" or "bar."

To test commands safely on actual files, copy the files to a directory in the Ram Disk and test with those files:

1> COPY Work:MyFiles/#? TO RAM:Testdir

Creating a Script to Move Files

AmigaDOS does have a Move command which normally should be used to move files. There are two other ways of moving a file with AmigaDOS: a RENAME command or a combination of COPY and DELETE commands.

Using RENAME to move a file is possible only when moving the file to a destination on the same volume. Attempting to rename across devices causes an error. The copy-and-delete method works in any situation, but is cumbersome.

To create a Move command that lets you move a file within or across devices with a single command, create a script with the following commands:

1> RUN ED S:Move+
PROTECT S:Move swrd

Enter these commands in the ED window:

.KEY source/A, to/A
.BRA {
.KET }
FAILAT 21
RENAME >NIL: {source} TO {to}
IF WARN
   COPY {source} TO {to}
   IF WARN
      ECHO "The file {source} could not be moved."
      QUIT 20
   ENDIF
   DELETE {source} QUIET
ENDIF
ECHO {source} "has been moved to" {to}

Save the script and exit ED. The s protection bit is automatically set after you exit.

Use this script the same as you would use a command. Enter MOVE followed by two arguments: the current path of the file to move and the path to the desired location.

Deleting with Interactive DIR

The DIR command has an interactive mode that pauses after each file or directory it lists and allows you to enter one of several simple commands. One option is to delete the item, which can be useful in certain situations.

For example, if you accidentally name a file #? (the wildcard combination that matches anything), attempting to delete it through normal methods is inadvisable. This is because DELETE #? Deletes everything in the directory, including any other valuable files that are there.

The interactive DIR can solve this problem and be used as a general-purpose query/delete tool. This is helpful when you have a large directory containing many items to delete, but the file names do not have enough in common to make a pattern matching DELETE practical.

To delete various files on a disk called Debris safely with an interactive DIR, enter:

1> DIR Debris: INTER

DIR lists the names of the files in Debris alphabetically one by one, each followed by a question mark prompt. Press Return to go to the next file or E to enter a directory. When the name of an unwanted file appears, enter DEL to delete the file. Enter Q to leave the interactive DIR.

Generating Scripts with LIST LFORMAT

One of the prime uses of the LIST command's LFORMAT option is for automatically creating scripts used to process a series of files. You can produce a raw script using a LIST statement with LFORMAT, a TO argument to redirect the LIST output to a file, and pattern matching. You can then view the script and edit it manually if necessary before executing it.

To create a script that renames all the files in the current directory, adds the extension .IFF to their present file names, and places them in a directory called Paintfiles in the Work partition:

1> LIST #? TO T:renamer LFORMAT="RENAME %P%N TO Work:Paintfiles/%N.IFF"

Enter ED T:renamer to check the script, which should resemble the following. If the match pattern lists files that you did not want processed or your LFORMAT string does not work as expected, you can edit the script or modify and reenter the command.

RENAME Paint:Vince TO Work:Paintfiles/Vince.IFF
RENAME Paint:Henro TO Work:Paintfiles/Henri.IFF
RENAME Paint:Paul TO Work:Paintfiles/Paul.IFF
RENAME Paint:Pablo TO Work:Paintfiles/Pablo.IFF
RENAME Paint:Andy TO Work:Paintfiles/Andy.IFF

When the script is correct, leave ED and enter EXECUTE T:renamer .

See the "Recursive AmigaDOS Command Script" example for a more advanced use of LIST LFORMAT.