ARP Users Manual V1.1 (REL2)
ARP Users Manual V1.1
(REL2)
[4mABSTRACT[0m
Wherein we present some of the truly outstanding features
of the new ARP programs, attempting to point the way for
new users of ARP to take immediate advantage of the ARP
software. If you have already been using ARP for a while,
you might wish to begin reading with section 2.
CONTENTS
1. General Features of ARP Programs.................... 1
1.1 Command format................................. 1
1.2 Commands and Templates......................... 3
1.3 Escapes........................................ 5
1.4 ARP and Wildcards.............................. 7
2. Status of V1.1 (REL2) of ARP........................ 8
2.1 Support for Release 2.......................... 8
3. REL2 improvements and additions..................... 9
3.1 Changes to old commands........................ 9
3.1.1 Assign 10
3.1.2 Type 10
3.1.3 Set and Environment variables 11
3.2 Introducing Resident and Resident Programs..... 11
3.3 Other new programs............................. 11
- i -
ARP Users Manual V1.1 Software (REL2) February 27, 1988
1. [4mGeneral Features of ARP Programs[0m
Since one of the goals of ARP is to make the Amiga easier
for you to use, we tried as hard as we could to make it
possible for you to install ARP, and continue to use
previously written batch files without any change at all.
Additionally, you should be able to use the ARP programs
immediately, without learning anything more about them,
since the degree of compatibility is very high. However,
ARP programs are generally enhanced and improved, and
generally much easier to use. To take advantage of these
new features, you have to learn about them, so read on!
1.1 [4mCommand format[0m
One of the problems with the original AmigaDOS programs was
that they are too inconsistant. Some programs accepted 10 or
20 filenames, and also allowed you to use wildcards to
specify files. Some programs accepted multiple files, but
didn't allow wild cards. And some programs accepted only one
filename. We have tried to fix this in ARP. Where it is
reasonable to expect to be able to supply multiple arguments
to a program, we have provided that capability*. Where it
is reasonable to expect to be able to use wildcards, we have
provided that capability also. We have attempted to make
the command templates for programs more consistant as well,
allowing abbreviations for commonly used switches and
options.
Commercial or public domain commands which use
arp.library will be able to implement this same kind of
consistant user interface.
This consistant command interface provides a lot of
power. As a simple example, consider the problem of dumping
a lot of files to your printer for a quick reference. Let's
say you want to send all the files in the current directory
which end in ".c" to the printer. Due to the ARP command
structure, there are no less than three ways to do this, and
all of them use remarkably similar command lines:
__________
* In REL2 of ARP there are no longer any limits to the
number of commands you may enter. See chap.2 for more
information.
Page 1
ARP Users Manual V1.1 Software (REL2) February 27, 1988
1> Type #?.c to PRT:
1> Copy #?.c to PRT:
1> Join #?.c to PRT:
Incidentally, we also supply a more standard set of
wildcards, in addition to the ones in use on the Amiga, so
you could also do
1> Type *.c to PRT:
1> Copy *.c to PRT:
1> Join *.c to PRT:
If you were to try the same thing using the AmigaDOS
programs, you would be in for a rude shock. First, let's
try type:
1> Type #?.c to PRT:
Can't open #?.c
It appears that the AmigaDOS type doesn't understand
wildcards. Well, let's try Copy:
1> Copy #?.c to PRT:
Destination must be a directory
Cute, Copy lets you use wildcards, but then you can't copy
anything to the printer. It turns out that the only way to
send all your files to the printer is to specify each one in
full. And if you wanted to use the special capabilities of
Type, for example, to add line numbers to the files as you
print them out, you are reduced to multiple Type commands,
since the AmigaDOS type only accepts one argument. Using
the ARP Type, you can supply multiple arguments, and each
argument can contain wildcards.
The main point to notice here is how ARP provides you
with a consistant command environment. Because the ARP
programs don't impose artificial limitations, each command
is more powerful and more useful. And because ARP programs
strive to be consistant with each other, you don't have to
remember silly special cases, and can apply what you have
learned about one program to a new one. For example, having
noticed that Copy, Join and Type all allow wildcards, you
Page 2
ARP Users Manual V1.1 Software (REL2) February 27, 1988
can probably assume that a command like Rename does as well,
and you would be correct. As another example of the
increased power of ARP, let's say you wanted to move the
three files memo1, memo2 and memo3 to a directory on the
same disk called OLD_EMOS. Using AmigaDOS, you would have to
do it this way:
1> Rename memo1 OLD_EMOS
1> Rename memo2 OLD_EMOS
1> Rename memo3 OLD_EMOS
This kind of thing can get old pretty quickly. Using the
ARP Rename, you would simply do
1> Rename memo? OLD_EMOS
The '?' is of course a wildcard that matches any single
character.
1.2 [4mCommands and Templates[0m
When we spoke to Amiga users, one of the things they liked
about the current Amiga programs were the use of command
templates to specify the arguments to a program. Since
people liked this, and it seemed like a good idea, we kept
it in ARP. We extended and modified individual templates
for commands, and we also have an extended help feature.
Under AmigaDOS, if you supply a question mark (?) as the
first argument to a command, it presents you with its
command template, and waits for you to hand it some
arguments. The same thing is true of ARP programs, but if
you need even more information, just type another question
mark when you get the template, like this:
1> Type ?
FROM/...,TO/k,OPT/k: ?
Type wildcards [TO Output] [OPT H(ex)|N(um)]
FROMA/...,TO/k,OPT/k:
The first thing Type gives you when you supply a question
mark is its command template*. If that is not enough
Page 3
ARP Users Manual V1.1 Software (REL2) February 27, 1988
information for you (for example, if you forget what options
you can pass to type), typing another question mark after
you get the template causes an additional help message to be
displayed, and then the template is reprinted, and the
command waits again for you to supply it with some
arguments. This allows you to get extra help for commands
you don't use often, and not be bothered by a lot of
information for commands that you do use a lot.
Another thing ARP tries hard to do is to give
informative error messages. For example, when you type the
following under AmigaDOS:
1> Echo "Hello World!
Bad Args to Echo
You get a not too helpful message. The same action using
the ARP echo would cause:
1> Echo "Hello World!
Bad Args: Unmatched quotes
ARP attempts to help you identify the problem, so you can
fix it more rapidly. As under AmigaDOS, you can supply
arguments to ARP programs using either keywords, or using**
positions:
1> Type infile
1> Type FROM infile
1> Type FROM infile TO outfile
1> Type OPT h TO outfile FROM infile
All of the above will work. In addition, if you make an
error:
__________
* The template type for the FROM keyword (/...) is an ARP
innovation, see chap.2 for more details.
** The template keywords are given in upper case only for
clarity - you can use any case you like.
Page 4
ARP Users Manual V1.1 Software (REL2) February 27, 1988
1> Type FROM
Bad Args: Keyword needs an argument
or
1> Type infile From outfile
Bad Args: Bad positional argument
the ARP programs once again attempt to help you diagnose the
problem. In the first example, you specified a file by
keyword (the FROM), but left off the filename. (If you
really wanted to type a file by the name of FROM, you need
to use double quotes, for example, Type "FROM". ARP
programs, like AmigaDOS programs, assume that names inside
of quotes are filenames and not template keywords.) In the
second case, you gave the first argument twice, once by
position, and then by keyword. Type doesn't know what you
mean, since you appeared to have misused a positional
argument.
1.3 [4mEscapes[0m
AmigaDOS programs regard an asterisk inside of quotes as an
'escape' character, or a character that has a special
meaning. Typically, the escape character is used to modify
the meaning of the character that follows the escape. For
example, "*F" would not display the two characters "*" and
"F", the escape character "*" changes the meaning of the "F"
character to a formfeed, which will clear the terminal
screen, or advance the printer paper.
A lot of people didn't care for "*" as an escape
character. It is an unusual choice, most of the popular
operating systems use a backslash (\) instead. In addition,
the '*' character is a bit overloaded on the Amiga, it
refers to the current window, the BCPL escape, and it is
also ARPs (and most other Operating Systems) universal
wildcard. You can use the Set program to change the
wildcard character to a backslash like this:
Set ESCAPE \
Just substitute your favorite escape character for the \ in
the above example. The examples which follow assume you
have your escape character set to a \, as shown above.
ARP recognizes the following characters as special when
preceeded by the current escape character:
Page 5
ARP Users Manual V1.1 Software (REL2) February 27, 1988
\N Newline
\T Horizontal Tab
\V Vertical Tab
\B Backspace
\R Return
\F Formfeed
\E Escape (ascii 27)
\Xnn Hex number nn
those of you familiar with the limited escapes supported by
AmigaDOS will notice that ARP supports a much greater
variety of escape characters and options, although ARP
programs (like AmigaDOS) programs, will only recognize the
escape character inside of double quotes*, so if you want to
use escapes, you must also use the double quotes. To
include a single escape inside of quotes, you need to use
two of them, like this "\\". You can also include double
quotes inside of double quotes, by escaping them as well,
for example, "\"Inside Quotes\"". As usual, of course, the
special escaped characters can be either upper or lower
case. If you use hex digits, there can be one or two of
them, and they can also be either upper or lower case.
Escapes can be very convenient to use, for example, to
advance your printer paper to the next sheet, you can do:
1> Echo >PRT: "\F"
Which sends a formfeed to the printer. You should generally
be careful about using escapes in filenames, since this can
lead to confusion. One place escape characters might be
appropriate is in Filenotes, for example:
1> Filenote "Filename" "\X9B7mReverse Print Comment\X9B0m"
Which will cause the filenote to List in reverse print when
you display it, making it stand out more clearly.
__________
* An exception to this is Echo, which always escapes its
arguments. This is an example of ARP favoring
convenience over consistancy.
Page 6
ARP Users Manual V1.1 Software (REL2) February 27, 1988
1.4 [4mARP and Wildcards[0m
ARP has an extensive set of wildcards, and most ARP programs
allow them to be used. ARP supports ALL of the AmigaDOS set
of wildcards, as well as the more standard Unix* style of
wildcards. ARP supports the following wildcard characters,
note that these are valid inside or out of quotes:
(a|b|c) Will match one of a, b or c.
These can be patterns.
? Matches any single character
#<pat> Pattern repeated 0 or more times,
in particular, #? matches anything.
[char] A set of characters, for example,
[abc] or [a..c] specify the same set.
[^char] Match everything but this set of characters.
* 0 or more occurances of any character.
These can be used in combination, of course, so that *.(c|h)
or *.[ch] will match any filenames ending in either .c or .h
preceeded by any number of characters, including no
characters.
In addition, ARP allows wildcards to be used at
multiple levels of a directory hierarchy. For example, if
you want to type all the files in all the directories of
your INCLUDE directory, you could use
1> Type DF0:Include/*/*
Which will take care of things nicely. You can be more
selective, for example only typing files that start with T
in directories that start with E:
__________
* Unix is a trademark of AT&T.
Page 7
ARP Users Manual V1.1 Software (REL2) February 27, 1988
1> Type DF0:Include/E*/T*
But the best way to get used to the increased power of the
ARP wildcard system is to sit down and enjoy using it.
2. [4mStatus of V1.1 (REL2) of ARP[0m
This release fixes all known bugs in the command programs
and library, and largely meets ARP's initial goals of
freeing the Amiga from a dependence on the BCPL library and
interface by replacing the command programs in the C
directory. The few programs not replaced are either already
in C (i.e., DiskCopy, Format) or require major integration
of new system components, such as NewCLI, RUN and Execute.
These are being worked on and will be released (possibly as
a separate release) in the next few months.
We have also added support for international date
formats in all the date handling programs and in the
library. This was largely the work of Ken Salmon who also
contributed some of the new command programs.
The initial acceptance of ARP has been very
encouraging, and we would like to thank the thousands of new
users, especially those who sent in bug reports and/or
suggestions.
2.1 [4mSupport for Release 2[0m
There have been two preliminary releases since version 1.0,
both of them for magazines ("Transactor for the Amiga" and
"AmNews") which were carrying articles about ARP. While
these releases represent advances over Release 1, they will
not be supported. This is the official second releases
(REL2) of ARP, with the corresponding version number of 1.1.
If you have one of these preliminary versions of ARP, please
upgrade to this one.
You can use the ARP Version command to get the current
versions of Kickstart, Workbench and ARP. Another way to
get the ARP version is to type the following command from
the CLI:
1> run LIBS:arp.library
LIBS:arp.library failed returncode XX
Page 8
ARP Users Manual V1.1 Software (REL2) February 27, 1988
The 'XX' will be the current major revision number of
arp.library. For REL2, XX should read "34". If you have
one of these preliminary releases, XX (or version) will be
32 or 33.
3. [4mREL2 improvements and additions.[0m
3.1 [4mChanges to old commands[0m
A major change in all commands has been the introduction of
a new argument template type. This type allows you to enter
any number of arguments to a command. You are no longer
reduced to counting comma's to see how many arguments a
command requires. Here is a comparison of the two:
REL1 and ADos:
Delete ,,,,,,,,,, Allows 10 (?) arguments
REL2 of ARP:
Delete Files/... Allows any number of arguments.
we think the new template type is clearer, and much
more convenient to use. Anytime you see this new
template type, please feel free to enter as many
commands as the current CLI will let you. This new
template type is used in most of the ARP commands that
expect multiple arguments, old and new. The usage of
this template type is compatible with the older
templates, so this should not cause any problems with
scripts or habits.
Another command change/innovation is the use of
the star "*" character in some commands to refer to the
current directory. Both Rename and Copy use this
convention, as well as supporting a limited form of
prefix/postfix name additions. This is extremely
convenient, and is another example of something ARP
brings to the Amiga which has not been present in the
BCPL versions of these programs.
Another change which users should appreciate is
the removal of the recoverable alert (GURU) when an ARP
program could not find arp.library. This caused some
confusion in the initial installations of arp, and we
have removed it at the small cost of making programs
about 62 bytes larger. You will now get a message on
your terminal which says "You need ArpLib V34+ or
Page 9
ARP Users Manual V1.1 Software (REL2) February 27, 1988
larger", instead of the older guru meditation. This
means either you do not have an arp.library in your
LIBS: logical directory, or you do not have the most
recent version. There is also a new CLI command called
LoadLib that can help out in situations like this. It
can load arp.library (or any other library) into the
Amiga and put it where programs can find it. This is
useful when you must boot from a disk that does not
have arp.library on it, but still want to use the ARP
commands. This occasionally occurs with some copy
protected software.
International date formats are now supported for
both input and output. Programs which use dates (Date,
List, SetDate) output dates and expect input in the
format defined by the environment variable dateformat.
If no dateformat is defined, they default to the
current AmigaDOS format. The formats supported are:
- AmigaDOS (the default)
- International
- United States
- Europe and Canadia.
3.1.1 [4mAssign[0m Assign now uses the new multiarged templates,
but this by itself is not enough to earn it a spot in this
overview. REL2 of Assign allows you to remove multiple
assignments, or mix adding and removing assignments on the
same line by using a dash (-) in place of the directory
name. For example:
- Assign FOOBAR: DF0: GROK: - ARP: DF0:C
This causes Assign to create assignments for ARP and FOOBAR,
but to delete any existing assignments for GROK. Admittedly,
this is a strange syntax, but we are constrained by the
earlier Assign syntax so we can't change it to one more like
Set uses.
3.1.2 [4mType[0m If you do not provide an input file to Type it
will expect to receive keyboard input. It will send the
output to any file or device you have specified on the
command line as its output. This allows you to send output
to the printer or disk files without having to enter into
collisions with the ARP supported wildcard (*) and the
original AmigaDOS's current window character, which
unfortunately are the same thing. (See the description of
Set, below).
Page 10
ARP Users Manual V1.1 Software (REL2) February 27, 1988
This is a convention widely used in advanced operating
systems, and we are pleased to introduce it to the Amiga.
Here are two examples of its use:
1> TYPE TO PRT:
or
1> TYPE TO DF0:MyFile
The first sends keyboard output to the printer, while the
second diverts it to MyFile on drive 0. If you simply use
TYPE by itself, then it will echo your input to the current
window.
3.1.3 [4mSet and Environment variables[0m Set has several new
features. You can use Set to define your choice of escape
character, and also to increase the level of BCPL
compatibility for a few commands. Of course this must be
done at a cost, but it may occasionally be needed. See the
Set manual page for more information.
There are also now two environment variables that are
used by the ARP programs, dateformat and copyflags. See the
Environment manual page for more information on these
variables.
3.2 [4mIntroducing Resident and Resident Programs[0m
Thie release of ARP also introduces resident programs to
Amiga users. These are programs which are loaded into memory
once, no matter how many times they are executed. These
programs can be big memory savers, since multiple
invocations of a resident program will all use the same
code. See the manual pages for Resident and ARun for more
information on how to take advantage of this new feature.
3.3 [4mOther new programs[0m
There are obviously many new programs, in fact, this is
largely a complete set. For descriptions of these, please
see the manual pages.
Page 11
