Copyright (c) 2012-2016 Hyperion Entertainment and contributors.

Difference between revisions of "AmigaOS Manual: AmigaDOS Command Reference"

From AmigaOS Documentation Wiki
Jump to: navigation, search
(ADDNETINTERFACE)
(Updated command description)
 
(162 intermediate revisions by the same user not shown)
Line 108: Line 108:
  
 
= Command Listing =
 
= Command Listing =
 +
 +
== ADDAUDIOMODES ==
 +
 +
Manipulates the audio mode list.
 +
 +
; Format
 +
: ADDAUDIOMODES [FILES <file | pattern>] [QUIET] [REMOVE] [DBLSCAN]
 +
 +
; Template
 +
: FILES/M,QUIET/S,REFRESH/S,REMOVE/S,DBLSCAN/S
 +
 +
; Location
 +
: C:
 +
 +
Audio modes supported by the Amiga's audio system (ahi.device) are stored in the DEVS:Audiomodes directory as audio mode description files. Once the ahi.device is initiated, it scans the directory and builds an internal audio mode list based on the description files stored in the Audiomodes directory. The constructed audio mode list exists in RAM and can be manipulated by the ADDAUDIOMODES command.
 +
 +
The internal audio mode list can be cleared, new modes can be added to the list, or the original list can be restored. Note that any changes made to the audio mode list with the ADDAUDIOMODES command are not permanent.
 +
 +
The FILES parameter is used for adding audio modes to the list. The FILES parameter supplies the name or names of the audio mode description files which should be used for adding the new audio modes.
 +
 +
The REMOVE option will remove all audio modes from the internal audio mode list, while the REFRESH option restores the original audio modes by forcing the ahi.device to rebuild the internal audio mode list.
 +
 +
The DBLSCAN option does not have any effect on the audio mode list. Instead it will open and then immediately close a double-scan screen. On the original Amiga hardware this will enable over 28 kHz sample playback frequencies.
 +
 +
If the QUIET option is supplied, ADDAUDIOMODES will not print any messages.
 +
 +
; Example:
 +
Rebuild the audio mode list:
 +
1> ADDAUDIOMODES REFRESH
  
 
== ADDBUFFERS ==
 
== ADDBUFFERS ==
Line 149: Line 178:
 
: C:
 
: C:
  
ADDNETINTERFACE starts the specified network interfaces, thus starting the connection.
+
ADDNETINTERFACE starts the specified network interfaces, thus starting the connection. It accepts the following parameters:
  
; OPTIONS
+
{| class="wikitable"
INTERFACE/M
+
| INTERFACE/M || The name of the interface to add; this can be a plain interface name, such as "Ariadne", or the fully qualified file name which contains the interface configuration information. The tool expects the name of the file in question (without the prefixed path) to become the name of the interface. For historic reasons interface names cannot be longer than 15 characters.
    The name of the interface to add; this can be a plain interface
+
    name, such as "Ariadne", or the fully qualified file name which
+
    contains the interface configuration information. The tool
+
    expects the name of the file in question (without the prefixed
+
    path) to become the name of the interface. For historic reasons
+
    interface names cannot be longer than 15 characters.
+
 
+
    For your convenience, a wild card pattern can be specified in
+
    place of the file name to use.
+
 
+
    If several interface names are specified, they will be sorted in
+
    alphabetical order before they are added. If the interface
+
    files have icons attached, you can use tool types such as
+
    "PRI=5" or "PRIORITY=5" to select the order in which the interfaces
+
    will be sorted. Higher priority entries will appear before lower
+
    priority entries. If the priorities for two entries is identical,
+
    then the interface names will be compared. If no priority is
+
    given, the value 0 will be used.
+
  
QUIET/S
+
For your convenience, a wild card pattern can be specified in place of the file name to use.
    This option causes the program not to emit any error messages
+
    or progress reports. Also, if the program encounters an error
+
    it will flag this as failure code 5 which can be looked at
+
    using the "if warn" shell script command. If this option is
+
    not in effect, failure codes will be more severe and all sorts
+
    of progress information will be displayed.
+
 
+
TIMEOUT/K/N
+
    If you're going to use DHCP configuration for any of the
+
    interfaces, a default timeout value of 60 seconds will
+
    limit the time an interface can take to be configured.
+
    This parameter allows you to use a different timeout value.
+
    Note that due to how the configuration protocol works,
+
    the timeout cannot be shorter than ten seconds.
+
  
 +
If several interface names are specified, they will be sorted in alphabetical order before they are added. If the interface files have icons attached, you can use tool types such as "PRI=5" or "PRIORITY=5" to select the order in which the interfaces will be sorted. Higher priority entries will appear before lower priority entries. If the priorities for two entries is identical, then the interface names will be compared. If no priority is given, the value 0 will be used.
 +
|-
 +
| QUIET/S || This option causes the program not to emit any error messages or progress reports. Also, if the program encounters an error it will flag this as failure code 5 which can be looked at using the "if warn" shell script command. If this option is not in effect, failure codes will be more severe and all sorts of progress information will be displayed.
 +
|-
 +
| TIMEOUT/K/N || If you're going to use DHCP configuration for any of the interfaces, a default timeout value of 60 seconds will limit the time an interface can take to be configured. This parameter allows you to use a different timeout value. Note that due to how the configuration protocol works, the timeout cannot be shorter than ten seconds.
 +
|}
 
The 'AddNetInterface' command can be invoked from Workbench, too. It operates on the same configuration files with the same keywords, etc. To make it work, create an icon for your interface configuration file (it must be a project icon) and put 'AddNetInterface' into its default tool. Make sure that the project has enough stack space assigned (4000 bytes minimum), then double-click on the icon. If things should go wrong, you will see an error requester pop up, and no further initialization will be done. You can configure two options in the project file's tool types: QUIET and TIMEOUT. These are identical to the two parameters of the same name you could pass on the command line; they define whether the command should print any error messages (the default is to print them) and how long the command should wait for DHCP configuration to conclude (default is a timeout of 60 seconds).
 
The 'AddNetInterface' command can be invoked from Workbench, too. It operates on the same configuration files with the same keywords, etc. To make it work, create an icon for your interface configuration file (it must be a project icon) and put 'AddNetInterface' into its default tool. Make sure that the project has enough stack space assigned (4000 bytes minimum), then double-click on the icon. If things should go wrong, you will see an error requester pop up, and no further initialization will be done. You can configure two options in the project file's tool types: QUIET and TIMEOUT. These are identical to the two parameters of the same name you could pass on the command line; they define whether the command should print any error messages (the default is to print them) and how long the command should wait for DHCP configuration to conclude (default is a timeout of 60 seconds).
  
; NOTES
+
{{Note| This command is similar to the Unix "ifconfig" command.}}
This command is similar to the Unix "ifconfig" command.
+
  
The program makes two passes over the configuration files to be taken into account. In the first pass information is gathered on the interfaces to add, which is subsequently used to add those interfaces found. In the second pass interfaces are configured, setting their IP addresses, etc. If anything goes wrong in the first pass, processing will stop and no second pass will be done. If anything goes wrong in either the first or the second pass, that pass will not be completed.
+
{{Note| The program makes two passes over the configuration files to be taken into account. In the first pass information is gathered on the interfaces to add, which is subsequently used to add those interfaces found. In the second pass interfaces are configured, setting their IP addresses, etc. If anything goes wrong in the first pass, processing will stop and no second pass will be done. If anything goes wrong in either the first or the second pass, that pass will not be completed.}}
  
 
; CONFIGURATION FILES
 
; CONFIGURATION FILES
Line 200: Line 202:
 
Each line of the file must correspond to an option; if a line is introduced by a '#' or ';' character it will be ignored (so are empty lines). The following options are supported:
 
Each line of the file must correspond to an option; if a line is introduced by a '#' or ';' character it will be ignored (so are empty lines). The following options are supported:
  
    DEVICE/K
+
{| class="wikitable"
        Must be provided; the name of the SANA-II device driver. This
+
| DEVICE/K || Must be provided; the name of the SANA-II device driver. This should be the complete, fully qualified path to the driver. If no complete path is provided, the 'Devs:Networks' drawer will be checked. Thus, "DEVS:Networks/ariadne.device" is equivalent to "ariadne.device".
        should be the complete, fully qualified path to the driver. If
+
|-
        no complete path is provided, the 'Devs:Networks' drawer will be
+
| UNIT/K/N || Unit number of the device driver to open. The default is to use unit 0.
        checked. Thus, "DEVS:Networks/ariadne.device" is equivalent to
+
|-
        "ariadne.device".
+
| IPTYPE/K/N || You can use this parameter to override the packet type the stack uses when sending IP packets; default is 2048 (for Ethernet hardware).
 +
|-
 +
| ARPTYPE/K/N || You can use this parameter to override the packet type the stack uses when sending ARP packets. Default is 2054; this parameter only works with Ethernet hardware and should not be changed.
 +
|-
 +
| IPREQUESTS/K/N || The number of IP read requests to allocate and queue for the SANA-II device driver to use. The default value is 32, larger values can improve performance, especially with fast device drivers.
 +
|-
 +
| WRITEREQUESTS/K/N || The number of IP write requests to allocate and queue for the SANA-II device driver to use. The default value is 32, larger values can improve performance, especially with fast device drivers.
 +
|-
 +
| ARPREQUESTS/K/N || The number of ARP read requests to allocate and queue for the SANA-II device driver to use. The default value is 4.
 +
|-
 +
| DEBUG/K (possible parameters: YES or NO) || You can enable debug output for this interface (don't worry, you can always disable it later) to help in tracking down configuration problems. At this time of writing, the debug mode will, if enabled, produce information on the progress of the DHCP configuration process.
 +
|-
 +
| POINTTOPOINT/K (possible parameters: YES or NO) || This indicates that the device is used for point to point connections. The stack automatically figures out whether the SANA-II device driver is of the point to point type, so you should not need to specify this option.
 +
|-
 +
| MULTICAST/K (possible parameters: YES or NO) || This tells the stack that this device can handle multicast enabled by default anyway).
 +
|-
 +
| DOWNGOESOFFLINE/K (possible parameters: YES or NO) || This option is useful with point to point devices, like 'ppp.device'. When specified, bringing the interface 'down' (via the 'ConfigureNetInterface' program) or shutting down the stack will cause the associated SANA-II device driver to be switched offline (via the 'S2_OFFLINE' command).
 +
|-
 +
| REPORTOFFLINE/K (possible parameters: YES or NO) || When a device is switched offline, you may want to know about it. This is helpful with SLIP/PPP connections which run over a serial link which accumulates costs while it is open. When the connection is broken and the device goes offline, you will receive a brief notification of what happened. However, if you tell the library itself to shut down, no notification that a device was switched offline will be shown.
 +
|-
 +
| REQUIRESINITDELAY/K (possible parameters: YES or NO) || Some devices need a little time to settle after they have been opened or they will hickup and lose data after the first packet has been sent. The original 'Ariadne I' card is one such device. For these devices, the 'REQUIRESINITDELAY=YES' option will cause a delay of about a second before the first packet is sent.
  
    UNIT/K/N
+
This option defaults to YES.
        Unit number of the device driver to open. The default is to
+
|-
        use unit 0.
+
| COPYMODE/K (possible parameters: SLOW or FAST) || This option is for chasing subtle bugs in the driver interface with cards like the original 'Ariadne I'. Cards like these do not support writing to the hardware transmit buffer in units other than 16 bits a piece. Default is 'SLOW', which is compatible with the Ariadne I. But if you're feeling adventurous, try the 'FAST' option (and don't complain if it doesn't work for you!).
 +
|-
 +
| FILTER/K (possible parameters: OFF, LOCAL, IPANDARP or EVERYTHING) || This option enables the use of the Berkeley packet filter for this particular interface. Possible choices for the key are:
  
    IPTYPE/K/N
+
'''FILTER=OFF'''
        You can use this parameter to override the packet type the
+
        stack uses when sending IP packets; default is 2048 (for
+
        Ethernet hardware).
+
  
    ARPTYPE/K/N
+
Disables the filter.
        You can use this parameter to override the packet type the
+
        stack uses when sending ARP packets. Default is 2054; this
+
        parameter only works with Ethernet hardware and should not be
+
        changed.
+
  
    IPREQUESTS/K/N
+
'''FILTER=LOCAL'''
        The number of IP read requests to allocate and queue for the
+
        SANA-II device driver to use. The default value is 32, larger
+
        values can improve performance, especially with fast device
+
        drivers.
+
  
    WRITEREQUESTS/K/N
+
Enables filtering on all IP and ARP packets that are intended for this particular interface. Packets intended for other interfaces or hosts are ignored.
        The number of IP write requests to allocate and queue for the
+
        SANA-II device driver to use. The default value is 32, larger
+
        values can improve performance, especially with fast device
+
        drivers.
+
  
    ARPREQUESTS/K/N
+
'''FILTER=IPANDARP'''
        The number of ARP read requests to allocate and queue for the
+
        SANA-II device driver to use. The default value is 4.
+
  
    DEBUG/K  (possible parameters: YES or NO)
+
Enables filtering on all IP and ARP packets that happen to fly by this interface, no matter whether the packets are intended for it or not. This requires that the underlying network device driver is opened for exclusive access in so-called 'promiscuous' mode. This may not work if other clients (Envoy, ACS) need to keep the driver opened.
        You can enable debug output for this interface (don't worry,
+
        you can always disable it later) to help in tracking down
+
        configuration problems. At this time of writing, the debug
+
        mode will, if enabled, produce information on the progress of
+
        the DHCP configuration process.
+
  
    POINTTOPOINT/K  (possible parameters: YES or NO)
+
'''FILTER=EVERYTHING'''
        This indicates that the device is used for point to point
+
        connections. The stack automatically figures out whether the
+
        SANA-II device driver is of the point to point type, so you
+
        should not need to specify this option.
+
  
    MULTICAST/K  (possible parameters: YES or NO)
+
Identical to FILTER=IPANDARP, but will also filter all other kinds of packets that may show up.
        This tells the stack that this device can handle multicast
+
        packets. 'YES' only works with Ethernet hardware (where it's
+
        enabled by default anyway).
+
  
    DOWNGOESOFFLINE/K  (possible parameters: YES or NO)
+
Default for this option is 'FILTER=LOCAL'. Note that by using this option you merely define what the filter mechanism can do and what it cannot do. The filter is not enabled when you add the interface.
        This option is useful with point to point devices, like
+
|-
        'ppp.device'. When specified, bringing the interface 'down'
+
| HARDWAREADDRESS/K || You can specify the hardware address (layer 2 address, MAC address) this interface should respond to when it is first added and configured. This usually works only once for each interface, which means that once an address has been chosen you have to stick with it until the system is rebooted. And it also means that the first program to configure the address will manage to make its choice stick.
        (via the 'ConfigureNetInterface' program) or shutting down the
+
        stack will cause the associated SANA-II device driver to be
+
        switched offline (via the 'S2_OFFLINE' command).
+
  
    REPORTOFFLINE/K  (possible parameters: YES or NO)
+
The hardware address must be given as six bytes in hexadecimal notation, separated by colon characters, like this:
        When a device is switched offline, you may want to know about
+
        it. This is helpful with SLIP/PPP connections which run over a
+
        serial link which accumulates costs while it is open. When the
+
        connection is broken and the device goes offline, you will
+
        receive a brief notification of what happened. However, if you
+
        tell the library itself to shut down, no notification that a
+
        device was switched offline will be shown.
+
  
    REQUIRESINITDELAY/K  (possible parameters: YES or NO)
+
'''HARDWAREADDRESS=00:60:30:00:11:22'''
        Some devices need a little time to settle after they have been
+
        opened or they will hickup and lose data after the first
+
        packet has been sent. The original 'Ariadne I' card is one
+
        such device. For these devices, the 'REQUIRESINITDELAY=YES'
+
        option will cause a delay of about a second before the first
+
        packet is sent.
+
 
+
        This option defaults to YES.
+
 
+
    COPYMODE/K  (possible parameters: SLOW or FAST)
+
        This option is for chasing subtle bugs in the driver interface
+
        with cards like the original 'Ariadne I'. Cards like these do
+
        not support writing to the hardware transmit buffer in units
+
        other than 16 bits a piece. Default is 'SLOW', which is
+
        compatible with the Ariadne I. But if you're feeling
+
        adventurous, try the 'FAST' option (and don't complain if it
+
        doesn't work for you!).
+
 
+
    FILTER/K  (possible parameters: OFF, LOCAL, IPANDARP or EVERYTHING)
+
        This option enables the use of the Berkeley packet filter for
+
        this particular interface. Possible choices for the key are:
+
 
+
            FILTER=OFF
+
                Disables the filter.
+
 
+
            FILTER=LOCAL
+
                Enables filtering on all IP and ARP packets that are
+
                intended for this particular interface. Packets
+
                intended for other interfaces or hosts are ignored.
+
 
+
            FILTER=IPANDARP
+
                Enables filtering on all IP and ARP packets that
+
                happen to fly by this interface, no matter whether the
+
                packets are intended for it or not. This requires that
+
                the underlying network device driver is opened for
+
                exclusive access in so-called 'promiscuous' mode. This
+
                may not work if other clients (Envoy, ACS) need to
+
                keep the driver opened.
+
 
+
            FILTER=EVERYTHING
+
                Identical to FILTER=IPANDARP, but will also filter all
+
                other kinds of packets that may show up.
+
 
+
        Default for this option is 'FILTER=LOCAL'. Note that by using
+
        this option you merely define what the filter mechanism can do
+
        and what it cannot do. The filter is not enabled when you add
+
        the interface.
+
 
+
    HARDWAREADDRESS/K
+
        You can specify the hardware address (layer 2 address, MAC
+
        address) this interface should respond to when it is first
+
        added and configured. This usually works only once for each
+
        interface, which means that once an address has been chosen
+
        you have to stick with it until the system is rebooted. And it
+
        also means that the first program to configure the address
+
        will manage to make its choice stick.
+
 
+
        The hardware address must be given as six bytes in hexadecimal
+
        notation, separated by colon characters, like this:
+
 
+
            HARDWAREADDRESS=00:60:30:00:11:22
+
 
+
        Take care, there are rules that apply to the choice of the
+
        hardware address, which means that you cannot simply pick a
+
        convenient number and get away with it. It is assumed that you
+
        will want to configure an IEEE 802.3 MAC address, which works for
+
        Ethernet hardware and is six bytes (48 bits) in size.
+
  
 +
Take care, there are rules that apply to the choice of the hardware address, which means that you cannot simply pick a convenient number and get away with it. It is assumed that you will want to configure an IEEE 802.3 MAC address, which works for Ethernet hardware and is six bytes (48 bits) in size.
 +
|}
 
In addition to the purely static interface configuration information you can also tell the configuration program to do something about the interfaces once they have all been added. That's when the following configuration file parameters will be taken into account:
 
In addition to the purely static interface configuration information you can also tell the configuration program to do something about the interfaces once they have all been added. That's when the following configuration file parameters will be taken into account:
 +
{| class="wikitable"
 +
| ADDRESS/K || This configures the IP address of the interface. The parameter you supply should be an IP address in dotted-decimal notation ("192.168.0.1"). Don't pick a symbolic host name as the system may not yet be in a position to talk to name resolution server and translate the symbolic name.
  
    ADDRESS/K
+
In place of the IP address you can also specify "DHCP" (Dynamic Host Configuration Protocol). As the name suggests, this will start a configuration process involving the DHCP protocol which should eventually yield the right IP address for this host. Note that this configuration procedure only works for Ethernet hardware.
        This configures the IP address of the interface. The parameter
+
|-
        you supply should be an IP address in dotted-decimal notation
+
| ALIAS/K/M || In addition to the primary interface address you can assign several aliases to it. These must be specified in dotted-decimal notation ("192.168.0.1"). Alias addresses are added after the primary interface address has been configured.
        ("192.168.0.1"). Don't pick a symbolic host name as the system
+
|-
        may not yet be in a position to talk to name resolution server
+
| STATE/K || By default, interfaces whose addresses are configured will switch automatically to 'up' state, making it possible for the TCP/IP stack to use them for network I/O. You can override this by using the 'STATE=DOWN' switch. The alternatives 'online' (implies 'up', but tells the underlying network interface driver to go online first) and 'offline' (implies 'down' but tells the driver to go offline first) are available as well.
        and translate the symbolic name.
+
|-
 +
| NETMASK/K || This selects the subnet mask for the interface, which must be specified in dotted-decimal notation ("192.0.168.1").
  
        In place of the IP address you can also specify "DHCP"
+
In place of the subnet mask you can also specify "DHCP" (Dynamic Host Configuration Protocol). As the name suggests, this will start a configuration process involving the DHCP protocol which should eventually yield the right subnet mask for this host. Note that this configuration procedure only works for Ethernet hardware.
        (Dynamic Host Configuration Protocol). As the name suggests,
+
|-
        this will start a configuration process involving the DHCP
+
| DESTINATION=DESTINATIONADDR/K || The address of the point-to-point partner for this interface; must be specified in dotted-decimal notation ("192.168.0.1"). Only works for point-to-point connections, such as PPP.
        protocol which should eventually yield the right IP address
+
|-
        for this host. Note that this configuration procedure only
+
| METRIC/K/N || This configures the interface route metric value. Default is 0.
        works for Ethernet hardware.
+
|-
 +
| MTU/K/N || You can limit the maximum transmission size used by the TCP/IP stack to push data through the interface. The interface driver will have its own ideas about the maximum transmission size. You can therefore only suggest a smaller value than the driver's preferred hardware MTU size.
 +
|-
 +
| CONFIGURE/K (possible parameters: DHCP, AUTO or FASTAUTO) || You can use DHCP configuration for this interface and protocol stack internals, namely the list of routers (and the default gateway) to use and the domain name servers. This option allows you to bring up the complete network configuration in one single step.
  
    ALIAS/K/M
+
You can request that a particular IP address is assigned to this interface by the DHCP process by specifying CONFIGURE=DHCP and your choice of ADDRESS=xxx.xxx.xxx.xxx.
        In addition to the primary interface address you can assign
+
        several aliases to it. These must be specified in
+
        dotted-decimal notation ("192.168.0.1"). Alias addresses are
+
        added after the primary interface address has been configured.
+
  
    STATE/K
+
If your network has no DHCP server, you may choose CONFIGURE=AUTO to use automatic IPv4 address selection, based upon a protocol called ZeroConf. This protocol will select a currently unused address from a specially designated address range.
        By default, interfaces whose addresses are configured will
+
        switch automatically to 'up' state, making it possible for the
+
        TCP/IP stack to use them for network I/O. You can override
+
        this by using the 'STATE=DOWN' switch. The alternatives
+
        'online' (implies 'up', but tells the underlying network
+
        interface driver to go online first) and 'offline' (implies
+
        'down' but tells the driver to go offline first) are available
+
        as well.
+
  
    NETMASK/K
+
If you choose automatic configuration in a wireless network, you might want to use CONFIGURE=FASTAUTO instead of CONFIGURE=AUTO.
        This selects the subnet mask for the interface, which must be
+
        specified in dotted-decimal notation ("192.0.168.1").
+
  
        In place of the subnet mask you can also specify "DHCP"
+
Note that only the CONFIGURE=DHCP option will attempt to set up a default route and a set of DNS servers for you to use. The alternatives of CONFIGURE=FASTAUTO and CONFIGURE=AUTO are restricted to selecting the network interface IPv4 addresses.
        (Dynamic Host Configuration Protocol). As the name suggests,
+
|-
        this will start a configuration process involving the DHCP
+
| LEASE/K || This is a complex option which can be used to request how long an IP address should be bound to an interface, via the DHCP protocol. Several combinations of options are possible. Here is a short list:
        protocol which should eventually yield the right subnet mask
+
        for this host. Note that this configuration procedure only
+
        works for Ethernet hardware.
+
  
    DESTINATION=DESTINATIONADDR/K
+
'''LEASE=300'''
        The address of the point-to-point partner for this interface;
+
        must be specified in dotted-decimal notation ("192.168.0.1").
+
        Only works for point-to-point connections, such as PPP.
+
  
    METRIC/K/N
+
'''LEASE=300seconds'''
        This configures the interface route metric value. Default
+
        is 0.
+
  
    MTU/K/N
+
This requests a lease of exactly 300 seconds, or five minutes.
        You can limit the maximum transmission size used by the TCP/IP
+
        stack to push data through the interface. The interface driver
+
        will have its own ideas about the maximum transmission size.
+
        You can therefore only suggest a smaller value than the
+
        driver's preferred hardware MTU size.
+
  
    CONFIGURE/K  (possible parameters: DHCP, AUTO or FASTAUTO)
+
'''LEASE=30min'''
        You can use DHCP configuration for this interface and protocol
+
        stack internals, namely the list of routers (and the default
+
        gateway) to use and the domain name servers. This option
+
        allows you to bring up the complete network configuration in
+
        one single step.
+
  
        You can request that a particular IP address is assigned to
+
This requests a lease of 30 minutes.
        this interface by the DHCP process by specifying
+
        CONFIGURE=DHCP and your choice of ADDRESS=xxx.xxx.xxx.xxx.
+
  
        If your network has no DHCP server, you may choose
+
'''LEASE=2hours'''
        CONFIGURE=AUTO to use automatic IPv4 address selection,
+
        based upon a protocol called ZeroConf. This protocol will
+
        select a currently unused address from a specially
+
        designated address range.
+
  
        If you choose automatic configuration in a wireless network,
+
This requests a lease of 2 hours.
        you might want to use CONFIGURE=FASTAUTO instead of
+
        CONFIGURE=AUTO.
+
  
        Note that only the CONFIGURE=DHCP option will attempt to
+
'''LEASE=1day'''
        set up a default route and a set of DNS servers for you to
+
        use. The alternatives of CONFIGURE=FASTAUTO and
+
        CONFIGURE=AUTO are restricted to selecting the network
+
        interface IPv4 addresses.
+
  
    LEASE/K
+
This requests a lease of 1 day.
        This is a complex option which can be used to request how long
+
        an IP address should be bound to an interface, via the DHCP
+
        protocol. Several combinations of options are possible. Here
+
        is a short list:
+
  
            LEASE=300
+
'''LEASE=4weeks'''
            LEASE=300seconds
+
                This requests a lease of exactly 300 seconds, or
+
                five minutes.
+
  
            LEASE=30min
+
This requests a lease of 4 weeks.
                This requests a lease of 30 minutes.
+
  
            LEASE=2hours
+
'''LEASE=infinite'''
                This requests a lease of 2 hours.
+
  
            LEASE=1day
+
This requests that the IP address should be permanently bound.
                This requests a lease of 1 day.
+
  
            LEASE=4weeks
+
Blank spaces between the numbers and the qualifiers are supported. The qualifiers are tested using substring matching, which means for example that "30 minutes" is the same as "30 min" and "30 m".
                This requests a lease of 4 weeks.
+
 
+
            LEASE=infinite
+
                This requests that the IP address should be
+
                permanently bound.
+
 
+
        Blank spaces between the numbers and the qualifiers are
+
        supported. The qualifiers are tested using substring matching,
+
        which means for example that "30 minutes" is the same as "30
+
        min" and "30 m".
+
 
+
        Note that the requested lease time may be ignored by the DHCP
+
        server. After all, it is just a suggestion and not an order.
+
 
+
    ID/K
+
        This option works along with the CONFIGURE=DHCP process. It
+
        can be used to tell the DHCP server by which name the local
+
        host should be referred to. Some DHCP servers are on good
+
        terms with their local name resolution services and will add
+
        the name and the associated IP address to the local host
+
        database. The name you can supply here cannot be longer than
+
        255 characters and must be at least 2 characters long. Keep it
+
        brief: not all DHCP servers have room for the whole 255
+
        characters.
+
 
+
    DHCPUNICAST/K
+
        Some DHCP servers may not be able to respond to requests for
+
        assigning IP addresses unless the responses are sent directly
+
        to the computer which sent the requests. In such cases you
+
        might want to use DHCPUNICAST=YES option.
+
  
 +
Note that the requested lease time may be ignored by the DHCP server. After all, it is just a suggestion and not an order.
 +
|-
 +
| ID/K || This option works along with the CONFIGURE=DHCP process. It can be used to tell the DHCP server by which name the local host should be referred to. Some DHCP servers are on good terms with their local name resolution services and will add the name and the associated IP address to the local host database. The name you can supply here cannot be longer than 255 characters and must be at least 2 characters long. Keep it brief: not all DHCP servers have room for the whole 255 characters.
 +
|-
 +
| DHCPUNICAST/K || Some DHCP servers may not be able to respond to requests for assigning IP addresses unless the responses are sent directly to the computer which sent the requests. In such cases you might want to use DHCPUNICAST=YES option.
 +
|}
 
Unsupported keywords in the configuration file (or typos) will be reported, along with the name of the file and the line number.
 
Unsupported keywords in the configuration file (or typos) will be reported, along with the name of the file and the line number.
  
Line 511: Line 359:
  
 
Adds message routing paths.
 
Adds message routing paths.
 +
 +
; Format
 +
: ADDNETROUTE [QUIET] [DESTINATION=<IP>] [HOSTDESTINATION=<IP>] [NETDESTINATION=<IP>] [GATEWAY=<IP>] [DEFAULTGATEWAY=<IP>]
 +
 +
; Template
 +
: QUIET/S,DST=DESTINATION/K,HOSTDST=HOSTDESTINATION/K,NETDST=NETDESTINATION/K,VIA=GATEWAY/K,DEFAULT=DEFAULTGATEWAY/K
 +
 +
; Location
 +
: C:
  
 
== ALIAS ==
 
== ALIAS ==
Line 558: Line 415:
 
displays the contents of Myfile in hexadecimal format.
 
displays the contents of Myfile in hexadecimal format.
  
See also: UNALIAS. Further examples of using ALIAS appear in Chapter 8.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#UNALIAS|UNALIAS]]
  
 
== ARP ==
 
== ARP ==
Line 602: Line 460:
 
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.
 
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
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IF|IF]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ELSE|ELSE]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ENDIF|ENDIF]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#REQUESTCHOICE|REQUESTCHOICE]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#WARN|WARN]]
  
 
== ASSIGN ==
 
== ASSIGN ==
Line 609: Line 472:
  
 
; Format
 
; Format
: ASSIGN [<name>:] [{<target>}] [LIST] [EXISTS] [DISMOUNT] [DEFER] [PATH] [ADD] [REMOVE] [VOLS] [DIRS] [DEVICES]
+
: ASSIGN [<name>:{dir}] [FROM <file name>] [TO <file name>] [LIST] [EXISTS] [DISMOUNT] [DEFER] [PATH] [ADD] [PREPEND] [REMOVE] [VOLS] [DIRS] [DEVICES] [NOREQ]
  
 
; Template
 
; Template
: NAME,TARGET/M,LIST/S,EXISTS/;,DISMOUNT/S,DEFER/S,PATH/S,ADD/S,REMOVE/S,VOLS/S,DIRS/S,DEVICES/S
+
: NAME,TARGET/M,FROM/K,TO/K,LIST/S,EXISTS/S,DISMOUNT/S,DEFER/S,PATH/S,ADD=APPEND/S,PREPEND/S,REMOVE/S,VOLS/S,DIRS/S,DEVICES/S,NOREQ/S
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
ASSIGN allows directories to be referenced via short, convenient logical device names, rather than their usual names or complete paths. ASSIGN gives an alternative directory name, much as ALIAS permits alternative command names. 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 the <name> and {dir} arguments are given, ASSIGN assigns the given name to the specified directory. Each time the assigned logical device name is referred to, AmigaDOS accesses the specified directory. If the <name> given is already assigned to a directory, the new directory will replace the previous directory. (Always be sure to include a colon 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.
+
If only the <name> argument is given, any existing ASSIGN of a directory to that logical device will be cancelled.
  
You can assign several logical device names to the same target by using multiple ASSIGN commands.
+
You can assign several logical device names to the same directory 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.
+
You can assign one logical device name to several directories by specifying each directory after the <name> argument or by using the ADD or APPEND option. When the APPEND option is specified, any existing directory assigned to <name> is not cancelled. Instead, the newly specified directory is appended to the end of the assign list and the system will search for both directories when <name> is encountered. If the first directory is not available, ASSIGN will be satisfied with the newly added directory.
  
The REMOVE option deletes a target name from the ASSIGN list.
+
The PREPEND option does the same thing as the APPEND option except the additional assignment is added at the front of the assing list. The PREPEND option is available with Assing version 53.2 or higher.
  
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.
+
To delete a name from the assign list, use the REMOVE option.
  
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).
+
If no arguments are given with ASSIGN, or if the LIST keyword is used, a list of all current assignments will be displayed. If the VOLS, DIRS, or DEVICES switch is specified, ASSIGN will limit the display to volumes, directories, or devices, respectively.
  
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.
+
When the EXISTS keyword is given along with a logical device name, AmigaDOS will search the ASSIGN list for that name and display the volume and directory assigned to that device. If the device name is not found, the condition flag is set to 5 (WARN). This is commonly used in scripts.
  
{{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.}}
+
Normally, when the {dir} argument is given, AmigaDOS immediately looks for that directory. If the ASSIGN commands are part of S:startup-sequence, the directories need to be present on a mounted disk during the boot procedure. If an assigned directory cannot be found, a requester appears asking for the volume containing that directory. However, two new options, DEFER and PATH, will wait until the directory is actually needed before searching for it.
  
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.
+
{{Note|The assigned name does not have to retain the name of the 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.}}
  
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 DEFER option creates a "late-binding" ASSIGN. This ASSIGN only takes effect when the assigned object is first referenced, rather than when the assignment is made. This eliminates the need to insert disks during the boot procedure that contain the directories that are assigned during the startup-sequence. When the DEFER option is used, the disk containing the assigned directory is not needed until the object is actually called upon.
  
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.
+
For example, if you assign FONTS: to DF0:Fonts with the DEFER option, the system will associate FONTS: with whatever disk is in DF0: at the time FONTS: is called. If you have Workbench disk in DF0: at the time the FONTS: is needed, the system will associate FONTS: with that particular Workbench disk. If you later remove that Workbench disk and insert another disk containing a Fonts directory, the system will specifically request the original Workbench disk the next time FONTS: is needed.
  
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 PATH option creates a "non-binding" ASSIGN. A non-binding ASSIGN acts like a DEFERed ASSIGN, except that it is re-evaluated each time the assigned name is referenced. This prevents the system from expecting a particular volume in order to use a particular directory (such as the situation described in the example above). For instance, if you assign FONTS: to DF0:Fonts with the PATH option, any disk in DF0: will be searched when FONTS: is referenced. As long as the disk contains a Fonts directory, it will satisfy the ASSIGN. Up until V54 DOS library, you could not assign multiple directories with the PATH option.
  
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.
+
The PATH option is especially useful to users with floppy disk systems as it eliminates the need to reinsert the original Workbench disk used to boot the system. As long as the drive you have assigned with the PATH option contains a disk with the assigned directory name, the system will use that disk.
 +
 
 +
Instead of specifying on the command line which assignments to set up and how, you can tell the ASSIGN command to read a list of specifications from a file using the FROM option. In that file, there must be one assignment specification per line; lines beginning with the ';' character are ignored. The file could look like this:
 +
 
 +
FONTS: MyFonts:Fontdir
 +
LIBS: SYS:Libs BigAssem:Libs PDAssem:Libs
 +
WorkDisk: DF0: DEFER
 +
C: DF0:C PATH
 +
 
 +
As you can see, it is possible to set up deferred and path assignments and assignment lists, too.
 +
 
 +
To complement the FROM option there is the TO option which will store the current list of assignments in a file, suitable for use with the FROM option.
 +
 
 +
The NOREQ option will prevent any "Please insert volume..." requester windows from appearing which may be triggered by attempts to make assignments to volumes which are currently unavailable. While the command will fail to establish any assignment producing such an error, a script file in which the command is used can keep on running without requiring manual intervention.
 +
 
 +
{{Note|The DISMOUNT option (called REMOVE in V1.3) is no longer active. From V54+ use the new dedicated C:Dismount command instead.}}
  
 
; Example 1:
 
; Example 1:
Line 699: Line 577:
  
 
; Example 5:
 
; Example 5:
 
1> ASSIGN DEVS:
 
 
removes the DEVS: assignment from the system.
 
 
; Example 6:
 
  
 
  1> ASSIGN WorkDisk: DF0: DEFER
 
  1> ASSIGN WorkDisk: DF0: DEFER
Line 712: Line 584:
 
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:>.
 
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:
+
; Example 6:
  
 
  1> ASSIGN C: DF0:C PATH
 
  1> ASSIGN C: DF0:C PATH
Line 718: Line 590:
 
  C [Df0: C]
 
  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.
+
will reference the C directory of whatever disk is in DF0: at the time a command is searched for. Notice that ASSIGN shows DF0:C in square brackets to indicate that it is a non-binding ASSIGN.
  
; Example 8:
+
; Example 7:
  
 
  1> ASSIGN LIBS: Zcad:Libs ADD
 
  1> ASSIGN LIBS: Zcad:Libs ADD
Line 726: Line 598:
 
adds Zcad:Libs to the list of directories assigned as LIBS:.
 
adds Zcad:Libs to the list of directories assigned as LIBS:.
  
; Example 9:
+
; Example 8:
  
 
  1> ASSIGN LIBS: Zcad:Libs REMOVE
 
  1> ASSIGN LIBS: Zcad:Libs REMOVE
Line 739: Line 611:
  
 
; Format
 
; Format
: AVAIL [VHIP | FAST | TOTAL] [FLUSH]
+
: AVAIL [CHIP | FAST | VIRTUAL | TOTAL] [FLUSH] [SHOW=<BLOCKS|BYTES|SIZE>]
  
 
; Template
 
; Template
: CHIPS/S,FAST/S,TOTAL/S,FLUSH/S
+
: CHIP/S,FAST/S,TOTAL/S,FLUSH/S,VIRTUAL/S,SHOW/K
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
AVAIL reports the amount of installed memory and how musch of it is available free for use.
  
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 figures in the complete summary are localised.
  
The FLUSH option frees memory by removing all unused libraries, devices, fonts, catalogs.
+
The SHOW option selects the format in which the figures in the complete summary will be printed. This must be one of BYTE, KILO, or MEGA. "BYTE", which is the default, will display plain figures. "KILO" will display the same information in KB. "MEGA" will display the same information in MB.
 +
 
 +
By using the CHIP, FAST, VIRTUAL, or TOTAL options, you can have AVAIL display only the number of free bytes of Chip, Fast, Virtual, or total RAM available, instead of the complete summary. This value can be used for comparisons in scripts.
 +
 
 +
These types are obsolete as of AmigaOS 4.x and the options CHIP, FAST, and VIRTUAL are only kept to ensure compatibility with older scripts.
 +
 
 +
The FLUSH option is obsolete and does nothing.
  
 
; Example 1:
 
; Example 1:
 
  1> AVAIL
 
  1> AVAIL
  Type Available In-Use Maximum Largest
+
  Installed: 536.870.912
  chip 233592 282272 515864 76792
+
  Free:      437.252.096
fast 341384 182896 524280 197360
+
total 574976 465168 1040144 197360
+
 
+
A complete summary of system RAM is displayed.
+
  
 
; Example 2:
 
; Example 2:
  1> AVAIL CHIP
+
  1> AVAIL TOTAL
  233592
+
  437252096
  
The number of free bytes of Chip RAM is displayed.
+
; Example 3:
 
+
1> AVAIL SHOW=MEGA
See Chapter 8 for more examples using AVAIL.
+
Installed: 512,000 M
 +
Free:      416,104 M
  
 
== BREAK ==
 
== BREAK ==
Line 775: Line 650:
  
 
; Format
 
; Format
: BREAK <process> [ALL | C | D | E | F]
+
: BREAK <process> [NAME <program name or pattern>] [ALL | C | D | E | F]
  
 
; Template
 
; Template
: PROCESS/A/N,ALL/S,C/S,D/S,E/S,F/S
+
: PROCESS/N,NAME/K,ALL/S,C/S,D/S,E/S,F/S
  
 
; Location
 
; Location
 
: C:
 
: 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 sets the specified attention flags in the <process> indicated. 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, AmigaDOS only sets the Ctrl-C flag.
  
BREAK acts the same as selecting the relevant process by clicking in its window and pressing the appropriate Ctrl+key combinations.
+
Ctrl-C is used as the default for sending a BREAK signal to halt a process. A process that has been aborted this way will display ***BREAK in the Shell window. Ctrl-D is used to halt execution of a script file. Ctrl-E is used to exit Commodity Exchange programs. Ctrl-F is not currently used.
  
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.
+
A process can be signalled by giving a name or a wildcard pattern. The name will be compared against the program's name (including its full path, if available) and the program name (excluding the path), if the first test did not produce a match.
  
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.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#STATUS|STATUS]]
  
 
; Example 1:
 
; Example 1:
 
  1> BREAK 7
 
  1> BREAK 7
  
sets the Ctrl+C attention flag of process 7. This is the same as selecting process 7 and pressing Ctrl+C.
+
sets the Ctrl-C attention flag of process 7. This is identical to selecting process 7 and pressing Ctrl-C.
  
 
; Example 2:
 
; Example 2:
 
  1> BREAK 5 D
 
  1> BREAK 5 D
  
sets the Ctrl+D attention flag of process 5.
+
sets the Ctrl-D attention flag of process 5.
  
See also: STATUS
+
; Example 3:
 +
1> BREAK NAME "DIR#?"
 +
 
 +
sets the Ctrl-C attention flag of all processes whose name begin with the letters "DIR"; this would include the "DIR" program, for example.
  
 
== BUILDMAPTABLE ==
 
== BUILDMAPTABLE ==
Line 868: Line 747:
  
 
; Format
 
; Format
: CHANGETASKPRI <priority> [PROCESS <process number>]
+
: CHANGETASKPRI <priority> [<process>] [NAME <program name or pattern>]
  
 
; Template
 
; Template
: PRI=PRIORITY/A/N,PROCESS/K/N
+
: PRI=PRIORITY/A/N,PROCESS/K/N,NAME/K
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
Since the Amiga is multitasking, it uses priority numbers to determine the order in which current tasks should be serviced. Normally, most tasks have a priority of 0, and the time and instructions cycles of the CPU are divided equally among them. CHANGETASKPRI changes the priority of the specified Shell process. (If no process is specified, the current Shell process is assumed.) Any started from <process> inherit 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, or you may disrupt important system tasks. Too low a priority (less than 0) can result in a process taking unreasonably long to execute, priority -128 does not make much sense because at that priority runs the idle.task.
  
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.
+
The name of the process whose priority number should be changed can be given, or a wildcard pattern that should match it. The name will be compared against the program's name (including its full path, if available) and the program name (excluding the path), if the first test did not produce a match. If more than one command matches the pattern given, then all these commands will have their priorities changed.
  
; Example:
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#STATUS|STATUS]]
 +
 
 +
; Example 1:
 
  1> CHANGETASKPRI 4 Process 2
 
  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).
+
The priority of Process 2 is changed to 4. Any tasks started from this Shell will also have a priority of 4. They will have priority over any other user tasks created without using CHANGETASKPRI (those tasks will have a priority of 0).
  
See also: STATUS. For another example for using CHANGETASKPRI, see Chapter 8.
+
; Example 2:
 +
1> CHANGETASKPRI 4 NAME "DIR"
 +
 
 +
The priority of the program "DIR" is changed to 4. Note that if there is more than one command to match the name, CHANGETASKPRI will abort with an error message.
  
 
== CHARSETCONVERT ==
 
== CHARSETCONVERT ==
Line 933: Line 818:
  
 
; Format
 
; Format
: COPY [FROM] {<name | pattern>} [TO] <name> [ALL] [quiet] [BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO] [COM] [NOREQ]
+
: COPY [FROM] {<name | pattern>} [TO] <name> [ALL] [QUIET]  
 +
: [BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO] [COM] [NOREQ]
 +
: [NOREPLACE] [INTERACTIVE] [FORCE] [ARCHIVE] [NEWER]
 +
: [COPYLINKS] [FOLLOWLINKS]
  
 
; Template
 
; Template
: FROM/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S
+
: FROM/A/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S,NOREPLACE/S,INTERACTIVE/S,FORCE/S,ARCHIVE/S,NEWER/S,COPYLINKS/S,FOLLOWLINKS/S
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
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 FROM argument; each argument should be separated by spaces. You can use pattern matching to copy or exclude items whose names share a common set of characters or symbols.
  
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 a TO filename already exists, COPY overwrites the TO file with the FROM file. If you name a destination directory that does not exist, COPY will create a directory with that name. You can also use a pair of double quotes ("") to refer to the current directory when specifying a destination. (Do not put any spaces between the double quotes.)
  
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.
+
If the FROM argument is a directory, only the directory's files will be copied; its subdirectories will not be copied. Use the ALL option to copy the complete directory, including its files, subdirectories, and the subdirectories' files. If you want to copy a directory and you want the copy to have the same name as the original, you must include the directory name in the TO argument.
  
COPY prints to the screen the name of each file as it is copied. This can be overridden by the QUIET option.
+
COPY prints to the screen the name of each file as it is copied. This can be overridden by the QUIET option or the local shell variable _Verbosity with a negative value.
  
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.
+
The BUF option is used to set the number of 512-byte buffers used during the copy. (Default is 200 buffers, approximately 100K of RAM.) It is often useful to 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:
+
Normally, copy gives the TO file the date and time the copy was made. Any comments attached to the original FROM file are ignored. The protection bits of the FROM file are copied to the TO file. Several options allow you to override these defaults:
  
 
{| class="wikitable"
 
{| class="wikitable"
| CLONE || The timestamp, comments, and protection bits of the FROM file are copied to the TO file.
+
| DATES || The creation date of the FROM file is 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.
 
| 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.
+
| CLONE || The date, comments and protection bits of the FROM file are copied to the TO file.
 +
|-
 +
| NOPRO || The protection bits of the FROM file are not copied to the TO file. The TO file will be given standard protection bits of r, w, e and d.
 +
|-
 +
| NOREPLACE || Checks if the destination file already exists. If this is the case, then the file is not copied.
 +
|-
 +
| INTERACTIVE || Checks if the destination file already exists. In this case, you will be prompted to confirm that you want the file to be overwritten (answer 'y' for 'yes').
 +
|-
 +
| FORCE || If the destination file could not be created because there already is a file of that name which is protected against deletion or writing, then the protection will be removed first before the destination file is created.
 +
|-
 +
| ARCHIVE || Copy only those files for which the 'archived' flag is unset. After copying, the 'archived' flag will be set on the file just copied. Note that the ARCHIVE option implies the CLONE option which will be enabled by default.
 +
|-
 +
| NEWER || Overwrite files only if the destination file is older than the source file, or of there is no destination file by the same name as the source file.
 +
|-
 +
| COPYLINKS || Copy the contents of a file referenced by a hard or soft link; the default is to skip copying linked files.
 +
|-
 +
| FOLLOWLINKS || When used with the ALL option, the COPY command will follow hard and soft links to directories; the default is to skip links to directories.
 
|}
 
|}
  
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.
+
Normally, COPY displays a requester if the COPY cannot continue for some reason. When the NOREQ option is given, all requesters are suppressed. This is useful in scripts and can prevent a COPY failure from stopping the script while it waits for a response. For instance, if a script calls for a certain file to be copied and the system cannot find that file, normally the script would display a requester and would wait until a response was given. With the NOREQ option, the COPY command would be aborted and the script would continue.
  
 
; Example 1:
 
; Example 1:
 
  1> COPY File1 TO :Work/File2
 
  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.
+
copies File1 in the current directory to File2 in the Work directory.
  
 
; Example 2:
 
; Example 2:
  1> COPY Chapter#? TO DF1:Backup
+
  1> COPY ~(#?.info) TO DF1:Backup
  
copies all the files whose names start with Chapter in the current directory to the Backup directory on the disk in DF1:. The Backup directory is created if it does not already exist.
+
copies all the files not ending in .info in the current directory to the Backup directory on the disk in DF1:. This is a convenient use of pattern matching to save storage space when icons are not necessary.
  
 
; Example 3:
 
; Example 3:
 
  1> COPY Work:Test TO ""
 
  1> COPY Work:Test TO ""
  
copies the files in the Test directory on Work to the current directory; subdirectories in Test are not copied.
+
copies the files in the Test directory on Work to the current directory; subdirectories in Test will not be copied.
  
 
; Example 4:
 
; Example 4:
 
  1> COPY Work:Test TO DF0:Test ALL
 
  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.
+
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:, AmigaDOS will create one.
  
 
; Example 5:
 
; Example 5:
  1> COPY DF0: TO DF1: ALL QUIET
+
  1> COPY Work:Test% TO DF0: ALL
  
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.)
+
copies the directory Test including all the contained files and subdiretories to DF0:. If DF0:Test does not exist, it will be created.
 +
 
 +
; Example 6:
 +
1> COPY  (Dir1|Dir2|%)  TO  DF0:  ALL QUIET
 +
 
 +
copies the directories Dir1 and Dir2 including all the contained files and subdirectories to DF0:. If any of the directories does not already exist on DF0:, AmigaDOS will create each.
 +
 
 +
; Example 7:
 +
1> COPY DF0: TO DF1: ALL QUIET
  
For more examples using COPY, see Chapter 8.
+
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. (This is quite slow in comparison to DiskCopy.)
  
 
== COUNTLINES ==
 
== COUNTLINES ==
Line 1,099: Line 1,009:
  
 
; Format
 
; Format
: DATE [<day>] [<date>] [<time>] [TO | VER <filename>]
+
: DATE [<day>] [<date>] [< time >] [SERVER <name>] [PORT <n>] [OFFSET <n>]
 +
: [LFORMAT <string>] [TO | VER <filename>]
  
 
; Template
 
; Template
: DAY,DATE,TIME,TO=VER/K
+
: DAY,DATE,TIME,SERVER/K,PORT/K/N,OFFSET/K/N,LFORMAT/K,TO=VER/K
  
 
; Location
 
; Location
 
: C:
 
: 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 with no argument displays the currently set system date and time, 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.
+
DATE <date> sets just the date. The date can be specified either in the current default locale format or in the AmigaDOS format DD-MMM-YY (day-month-year). If the AmigaDOS format is used, the hyphens between the arguments are required. A leading zero in the date is not necessary. The first 3 letters of the month (in the current locale language) 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.
+
The date can also be reset by specifying a day name, thus setting the date forward to that day of the week. You can also use tomorrow or yesterday as the <day> argument.
  
DATE <time> sets the time. The format for entry and display of <time> is HH:MM:SS (hours:minutes:seconds). Seconds is optional.
+
DATE <time> sets the time. The time can be specified either in the current default locale format or in the AmigaDOS format HH:MM:SS (hours:minutes:seconds). Seconds are 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.
+
The SERVER option is used to retrieve the current date and time from a remote server over a TCP/IP connection using the Network Time Protocol (NTP). A list of NTP time servers and some good background information can be found at http://www.eecis.udel.edu/~mills/ntp/servers.html.
  
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.
+
The SERVER option may be set to the special value "PREFS" which will retrieve the date and time from the currently configured remote server information stored in the Time preferences.
  
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.
+
By using PORT you can specify a port number different to the default 123.
  
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.
+
The OFFSET argument allows to set the offset in minutes of your location with respect to Greenwich Mean Time (GMT). If OFFSET is not specified, the locale offset will be used.
 +
 
 +
The LFORMAT option modifies the output of DATE using one or more substitution operators. See below for available substitution operators.
 +
{| class="wikitable"
 +
| %a || abbreviated weekday name
 +
|-
 +
| %A || weekday name
 +
|-
 +
| %b || abbreviated month name
 +
|-
 +
| %B || month name
 +
|-
 +
| %c || same as "%a %b %d %H:%M:%S %Y"
 +
|-
 +
| %d || day number with leading 0s
 +
|-
 +
| %D || same as "%m/%d/%y"
 +
|-
 +
| %e || day number with leading spaces
 +
|-
 +
| %h || abbreviated month name
 +
|-
 +
| %H || hour using 24-hour style with leading 0s
 +
|-
 +
| %I || hour using 12-hour style with leading 0s
 +
|-
 +
| %j || julian date
 +
|-
 +
| %m || month number with leading 0s
 +
|-
 +
| %M || the number of minutes with leading 0s
 +
|-
 +
| %n || insert a linefeed
 +
|-
 +
| %p || AM or PM strings
 +
|-
 +
| %q || hour using 24-hour style
 +
|-
 +
| %Q || hour using 12-hour style
 +
|-
 +
| %r || same as "%I:%M:%S %p"
 +
|-
 +
| %R || same as "%H:%M"
 +
|-
 +
| %S || number of seconds with leadings 0s
 +
|-
 +
| %t || insert a tab character
 +
|-
 +
| %T || same as "%H:%M:%S"
 +
|-
 +
| %U || week number, taking Sunday as first day of week
 +
|-
 +
| %w || weekday number
 +
|-
 +
| %W || week number, taking Monday as first day of week
 +
|-
 +
| %x || same as "%m/%d/%y"
 +
|-
 +
| %X || same as "%H:%M:%S"
 +
|-
 +
| %y || year using two digits with leading 0s
 +
|-
 +
| %Y || year using four digits with leading 0s
 +
|}
 +
 
 +
If you specify the TO or VER option, followed by a filename, the output of the DATE command is sent to that file, overwriting any existing contents.
 +
 
 +
If your Amiga does not have a battery backed-up hardware clock and you do not set the date, the system, upon booting, will set the date to the date of the most recently created file on the boot disk.
 +
 
 +
{{Note| Adjustments made with DATE only change the software clock. They will not survive past power-down. To set the battery backed-up hardware clock from the Shell, you must set the date and use SETCLOCK SAVE.}}
 +
 
 +
If DATE succeeded in setting the system date and/or time, the primary return code (RC) will be set to 0. A return code of 5 or 20 indicates that DATE failed partially or completely. If an error occurred when trying to get time from a remote server, the primary return code will be set to 21. In this case the secondary return code (RESULT2) may contain a TCP stack socket/resolver error number and the corresponding error message will be displayed.
  
 
; Example 1:
 
; Example 1:
 
  1> DATE
 
  1> DATE
 
  6-Sep-92
 
  6-Sep-92
 +
 +
displays the current date and time.
  
 
; Example 2:
 
; Example 2:
  1> DATE 6-sep-92
+
  1> DATE LFORMAT "Today it's %A, %m/%d/%Y, %T"
  
sets the date to September 6, 1992. The time is not reset.
+
displays a message like "Today it's Monday, 02/17/2003, 22:30:56".
  
 
; Example 3:
 
; Example 3:
 +
1> DATE 1-jan-04
 +
 +
sets the date to January 1st, 2004 (the earliest date you can set is January 1, 1978). The time is not reset.
 +
 +
; Example 4:
 
  1> DATE tomorrow
 
  1> DATE tomorrow
  
 
resets the date to one day ahead.
 
resets the date to one day ahead.
  
; Example 4:
+
; Example 5:
 
  1> DATE TO Fred
 
  1> DATE TO Fred
  
 
sends the current date to the file Fred.
 
sends the current date to the file Fred.
  
; Example 5:
+
; Example 6:
 
  1> DATE 23:00
 
  1> DATE 23:00
  
 
sets the current time to 11:00 p.m.
 
sets the current time to 11:00 p.m.
  
; Example 6:
+
; Example 7:
  1> DATE 1-jan-02
+
  1> DATE SERVER foo.bar.com OFFSET -480
  
sets the date to January 1st, 2002. The earliest date you can set is January 1, 1978.
+
gets the current date and time from the foo.bar.com NTP server for a location based on the Pacific Standard Time used in the United States.
  
 
== DELETE ==
 
== DELETE ==
Line 1,157: Line 1,146:
  
 
; Format
 
; Format
: DELETE {<name | pattern>} [ALL] [QUIET] [FORCE]
+
: DELETE {<name|pattern>} [ALL] [QUIET] [INTER|INTERACTIVE]
 +
: [FORCE] [WIPE]
  
 
; Template
 
; Template
: FILE/M/A,ALL/S,QUIET/S,FORCE/S
+
: FILE/M/A,ALL/S,QUIET/S,INTER=INTERACTIVE,FORCE/S,WIPE/S
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
DELETE attempts to delete (erase) the specified file(s). If more than one file was specified, AmigaDOS continues to the next file in the list.
 +
 
 +
You can use pattern matching to delete files. The pattern may specify directory levels as well as filenames. All files that match the pattern are deleted. To abort a multiple-file DELETE, press Ctrl-C.
 +
 
 +
AmigaDOS does not request confirmation of deletions. An error in a pattern-matching DELETE can have severe consequences, as deleted files are unrecoverable. Be sure you understand pattern matching before you use this feature, and keep backups of important files.
 +
 
 +
Warning: If you try to delete a directory that contains files, you will receive a message stating that the directory could not be deleted as it is not empty. To override this, use the ALL option. DELETE ALL deletes the named directory, its subdirectories, and all files.
 +
 
 +
Filenames are displayed on the screen as they are deleted. To suppress the screen output, use the QUIET option or the local shell variable _Verbosity with a negative value.
 +
 
 +
If the d (deletable) protection bit of a file has been cleared, that file cannot be deleted unless the FORCE option is used.
 +
 
 +
If the INTERACTIVE option is used, you will be prompted to confirm each single deletion (enter 'y' to confirm). Note that the FORCE option will override the INTERACTIVE option, turning it off.
 +
 
 +
For most file systems deleting a single file will only make the storage space previously reserved for it available again, but will not render the contents of the file unrecoverable. In order to make recovery of sensitive data much harder, use the WIPE option which, prior to deleting the file, will overwrite the contents of the file up to 7 times using the United States Department of Defense 5220-22.M standard procedure for this purpose. This can take long to complete.
 +
 
 +
{{Note|The WIPE operation implemented by the DELETE command is suitable only for magnetic storage media, such as floppy disks or hard disk drives. To wipe optical, magneto-optical or solid state memory storage devices you would need a different method, which is not currently implemented by the DELETE command.
  
{{Note|AmigaDOS does not request confirmation of deletions. Do not use pattern matching to delete things if you are not familiar with the procedure; deleted items cannot be recovered, unless you have an up-to-date backup of the items deleted.}}
+
While the contents of the file will be overwritten, the name of the file and any directories to be deleted will not be overwritten. You may want to move or rename file and directories prior to deletion.
  
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.
+
While the contents of the file will be overwritten, the name of the file and any directories to be deleted will not be overwritten. You may want to move or rename file and directories prior to deletion.
  
File names are displayed on the screen as they are deleted. To suppress the screen output, use the QUIET option.
+
The DELETE command does not guarantee that the file contents will be securely deleted because the file system and the underlying storage hardware may reduce the effectiveness of the overwrite operations. The FORMAT command may be more effective in securely wiping a storage medium, albeit at the expense of wiping the entire partition/disk rather than just a single file.
  
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.
+
If the FORCE and WIPE options are combined, then each file will have its write and delete protection removed before it is wiped.}}
  
 
; Example 1:
 
; Example 1:
 
  1> DELETE Old-file
 
  1> DELETE Old-file
  
deletes the file named Old-file in the current directory.
+
deletes the Old-file file in the current directory.
  
 
; Example 2:
 
; Example 2:
 
  1> DELETE Work/Prog1 Work/Prog2 Work
 
  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.
+
deletes the files Prog1 and Prog2 in the Work directory, and then deletes the Work directory (if there are no other files left in it).
  
 
; Example 3:
 
; Example 3:
 
  1> DELETE T#?/#?(1|2)
 
  1> DELETE T#?/#?(1|2)
  
deletes all the files that end in 1 or 2 in directories that start with T.
+
deletes all files that end in 1 or 2 in directories that start with T.
  
 
; Example 4:
 
; Example 4:
 
  1> DELETE DF1:#? ALL FORCE
 
  1> DELETE DF1:#? ALL FORCE
  
deletes all the files on DF1:, even those set as not deletable.
+
deletes all the files on DF1:, even these set as not deletable.
  
See also: PROTECT. For more examples using DELETE, see Chapter 8.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#PROTECT|PROTECT]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FORMAT|FORMAT]]
  
 
== DELETENETROUTE ==
 
== DELETENETROUTE ==
Line 1,215: Line 1,223:
  
 
; Format
 
; Format
: DIR [<dir | pattern>] [OPT A | I | AI | D | F] [ALL] [DIRS] [FILES] [INTER]
+
: [<dir|pattern>] [OPT A|I|AI|D|F] [ALL] [DIRS] [FILES] [INTER]
 +
: [SHOWPROGRAMS] [MAXCOLUMNS <number of columns>]
  
 
; Template
 
; Template
: DIR,OPT/K,ALL/S,DIRS/S,FILES/S,INTER/S
+
: DIR,OPT/K,ALL/S,DIRS/S,FILES/S,INTER/S,SHOWPROGRAMS/S,MAXCOLUMNS/K/N
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
DIR displays the file and directory names contained in the specified directory, or the current directory if no name is given. 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:
 
The options are:
Line 1,234: Line 1,243:
 
|-
 
|-
 
| INTER || Enters an interactive listing mode.
 
| INTER || Enters an interactive listing mode.
 +
 +
 +
|-
 +
| SHOWPROGRAMS || Executable programs and script files will be highlighted in the listing, by printing their names in boldfaced script.
 +
|-
 +
| MAXCOLUMNS || How many file names will be printed per line depends upon the width of the output window and the lengths of the file names. You can, however, limit how many names will be printed in each line by specifying the maximum number of columns.
 
|}
 
|}
  
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.
+
{{Note|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:
+
The interactive listing mode stops after each name and displays a question mark at which you can enter commands. The acceptable responses are shown below:
  
 
{| class="wikitable"
 
{| class="wikitable"
| Press Return || Displays the next name on the list.
+
| Return || Displays the next name on the list.
 
|-
 
|-
 
| E || Enters a directory; the files in that directory are displayed.
 
| E || Enters a directory; the files in that directory are displayed.
Line 1,258: Line 1,273:
 
|}
 
|}
  
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.
+
The COMMAND option allows almost any AmigaDOS command to be executed during the interactive directory list. When you want to issue a command, type C (or COM) at the question mark prompt. DIR will ask you for the command. Type the desired command, then press Return. The command will be executed and DIR will continue. You can also combine the C and the command on one line, by putting the command in quotes 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:
+
For instance, C "type prefs.info hex" is equivalent to pressing Q to exit interactive listing mode and return to a regular Shell prompt, and typing:
  
 
  1> TYPE Prefs.info HEX
 
  1> TYPE Prefs.info HEX
  
to display the Prefs.info file on the screen in hexadecimal format.
+
The Prefs.info file would be typed to 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.
+
It is dangerous to format a disk from the DIR interactive mode, as the format will take place immediately, without any confirmation requesters appearing. Also, starting another interactive DIR from interactive mode will result in garbled output.
  
 
; Example 1:
 
; Example 1:
Line 1,297: Line 1,308:
 
begins an interactive list of the contents of the Workbench disk.
 
begins an interactive list of the contents of the Workbench disk.
  
For more examples using DIR, see Chapter 8.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LIST|LIST]]
  
 
== DISKCHANGE ==
 
== DISKCHANGE ==
Line 1,312: Line 1,324:
 
: C:
 
: 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.
+
The DISKCHANGE command is only necessary when you are using 5.25 inch floppy disk drives or removable media drives without automatic diskchange hardware. Whenever you change the disk or cartridge of such a drive, you must use DISKCHANGE to inform the system of the switch.
 +
 
 +
DISKCHANGE can also be used if you edit a disk icon image and wish to see the new icon on the Workbench screen immediately. This is the only way to display an altered hard disk icon without rebooting.
  
 
; Example:
 
; 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:
+
If a requester appears and asks you to insert a new disk into your 5.25 inch drive, known as DF2:, you must insert the disk and then type:
  
 
  1> DISKCHANGE DF2:
 
  1> DISKCHANGE DF2:
Line 1,425: Line 1,439:
 
  picfile is not in this directory
 
  picfile is not in this directory
  
See also: IF, ENDIF, EXECUTE
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IF|IF]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ENDIF|ENDIF]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]
  
 
== ENDCLI ==
 
== ENDCLI ==
Line 1,442: Line 1,459:
 
ENDCLI ends a Shell process.
 
ENDCLI ends a Shell process.
  
See also: ENDSHELL
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ENDSHELL|ENDSHELL]]
  
 
== ENDIF ==
 
== ENDIF ==
Line 1,461: Line 1,479:
 
The ENDIF applies to the most recent IF or ELSE command.
 
The ENDIF applies to the most recent IF or ELSE command.
  
See also: IF, ELSE. For examples using the ENDIF command, see Chapter 8.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IF|IF]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ELSE|ELSE]]
  
 
== ENDSHELL ==
 
== ENDSHELL ==
Line 1,478: Line 1,498:
 
ENDSHELL ends a Shell process and closes the Shell window.
 
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+\.
+
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.
 
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.
Line 1,501: Line 1,521:
 
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).
 
ENDSKIP is used in scripts to terminate the execution of a SKIP block. A SKIP block allows you to jump over intervening commands if a certain condition is met. When an ENDSKIP is encountered, execution of the script resumes at the line following the ENDSKIP. The condition flag is set to 5 (WARN).
  
See also: SKIP
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SKIP|SKIP]]
  
 
== EVAL ==
 
== EVAL ==
Line 1,577: Line 1,598:
  
 
; Template
 
; Template
: FILE/A
+
: FILE/A/F
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
EXECUTE is used to run scripts of AmigaDOS commands. The lines in the script are executed just as if they had been typed at a Shell prompt. If the s protection bit of a file is set and the file is in the search path, you only need to type the filename--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 you 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). EXECUTE is generally made resident during the startup-sequence.
 +
 
 +
The permissible keywords for parameter substitution are explained below. Each keyword must be prefaced with a dot character (.).
 +
 
 +
The .KEY (or .K) keyword specifies both keyword names and positions in a script. It tells EXECUTE how many parameters to expect and how to interpret them. In other words, .KEY serves as a template for the parameter values you specify. Only one .KEY statement is allowed per script. If present, it should be the first line in the file.
 +
 
 +
The arguments on the .KEY line can be given with the /A and /K directives, which work the same as in an AmigaDOS template. Arguments followed by /A are required; arguments followed by /K require the name of that argument as a keyword. For example, if a script starts with .KEY filename/A it indicates that a filename must be given on the EXECUTE command line after the name of the script. This filename will be substituted in subsequent lines of the script. For instance, if the first line of a script is:
 +
 
 +
.KEY filename/A, TOname/K
 +
 
 +
You must specify a filename variable. The TOname variable is optional, but if specified the TOname keyword must be used. For instance:
 +
 
 +
1> EXECUTE Script Textfile TOname NewFile
 +
 
 +
Before execution, AmigaDOS scans the script for any items enclosed by BRA and KET characters (< and >). Such items may consist of a keyword or a keyword and a default value. Wherever EXECUTE finds a keyword enclosed in angle brackets, it tries to substitute a parameter. However, if you want to use a string in your script file that contains angle brackets, you will have to define substitute "bracket" characters with the .BRA and .KET commands. .BRA <ch> changes the opening bracket character to <ch>, while .KEY changes the closing bracket character to <ch>. For example:
 +
 
 +
.KEY filename
 +
ECHO "This line does NOT print <angle> brackets."
 +
.BRA {
 +
.KET }
 +
ECHO "This line DOES print <angle> brackets."
 +
ECHO "The specified filename is {filename}."
 +
 
 +
would result in the following output:
 +
 
 +
1> EXECUTE script TestFile
 +
This line does NOT print brackets.
 +
This line DOES print <angle> brackets.
 +
The specified filename is TestFile.
 +
 
 +
AmigaDOS provides a number of commands that are useful in scripts, such as IF, ELSE, SKIP, LAB, and QUIT. These commands, as well as the EXECUTE command, can be nested in a script. That is, a script can contain EXECUTE commands.
 +
 
 +
To stop the execution of a script, press Ctrl-D. If you have nested script files, you can stop the set of EXECUTE commands by pressing Ctrl-C. Ctrl-D only stops the current script from executing.
 +
 
 +
The current Shell number can be referenced by the characters <$$>. This is useful in creating unique temporary files, logical assignments, and PIPE names.
 +
 
 +
; Example 1:
 +
Assume the script List contains the following:
 +
.K filename
 +
RUN COPY <filename> TO PRT: +
 +
ECHO "Printing of <filename> done"
 +
 
 +
The following command:
 +
1> EXECUTE List Test/Prg
 +
 
 +
acts as though you had typed the following commands at the keyboard:
 +
 
 +
1> RUN COPY Test/Prg TO PRT: +
 +
1> ECHO "Printing of Test/Prg done"
 +
 
 +
; Example 2:
 +
Another example, Display, uses more of the features described above:
 +
 
 +
.Key name/A
 +
IF EXISTS <name>
 +
TYPE <name> NUMBER ;if the file is in the given directory, type it with line numbers
 +
ELSE
 +
ECHO "<name> is not in this directory"
 +
ENDIF
 +
 
 +
The command:
  
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).
+
1> RUN EXECUTE Display Work/Prg2
  
The allowable keywords for parameter substitution are explained in Chapter 5. Each keyword command line must be prefaced with a dot character (.).
+
should display the Work/Prg2 file, with line numbers on the screen, if it exists on the current directory. If the file is not there, the screen displays an error message. Because of the /A, if a filename is not given on the command line after display, an error will occur.
  
See also: IF, SKIP, FAILAT, LAB, ECHO, RUN, QUIT. For examples using the EXECUTE command, see Chapter 8.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IF|IF]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SKIP|SKIP]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FAILAT|FAILAT]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LAB|LAB]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ECHO|ECHO]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#RUN|RUN]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#QUIT|QUIT]]
  
 
== FAILAT ==
 
== FAILAT ==
Line 1,632: Line 1,722:
 
  MyFile being copied.
 
  MyFile being copied.
  
See also: ECHO, EXECUTE.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ECHO|ECHO]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]
  
 
== FAULT ==
 
== FAULT ==
  
Prints the messages for the specified error numbers.
+
Prints the messages for the specified error codes.
  
 
; Format
 
; Format
: FAULT {<n>}
+
: FAULT [<error number>] [[,]<error number>[[,]<error number>...]]
  
 
; Template
 
; Template
Line 1,647: Line 1,739:
 
: Internal
 
: 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.
+
FAULT prints the messages corresponding to the error numbers supplied. If several error numbers are given, they can be separated by spaces or commas.
  
 
; Example:
 
; Example:
  
If you receive the error message:
+
If you received an error message:
  
 
  Error when opening DF1:TestFile 205
 
  Error when opening DF1:TestFile 205
  
and need more information, enter:
+
and need more information, type:
  
 
  1> FAULT 205
 
  1> FAULT 205
Line 1,663: Line 1,755:
  
 
A complete list of error messages appears in Appendix A.
 
A complete list of error messages appears in Appendix A.
 +
 +
== FDTOOL ==
 +
 +
Control and examine the current state of the a1floppy device.
 +
 +
; Format
 +
: FDTOOL [U | UNIT <unit number>] [D | DEBUG <debug level>] [A | AUTO] [M | MANUAL] [C | CHECKNOW] [I | INFO] [V | VERS | VERSION]
 +
 +
; Template
 +
: U=UNIT/K/N,D=DEBUG/K/N,A=AUTO/S,M=MANUAL/S,C=CHECKNOW/S,I=INFO/S,V=VERS=VERSION/S
 +
 +
; Location
 +
: C:
  
 
== FILENOTE ==
 
== FILENOTE ==
Line 1,669: Line 1,774:
  
 
; Format
 
; Format
: FILENOTE [FILE] <file | pattern> [COMMENT <comment>] [ALL] [QUIET]
+
: FILENOTE [FILE] {<file|pattern>} [COMMENT] <comment> [ALL]
 +
: [QUIET] [FILES] [DIRS]
  
 
; Template
 
; Template
: FILE/A,COMMENT,ALL/S,QUIET/S
+
: FILE/A/M,COMMENT/A,ALL/S,QUIET/S,FILES/S,DIRS/S
  
 
; Location
 
; Location
 
: C:
 
: C:
  
FILENOTE attaches an optional comment of up to 79 characters to the specified file or to all files matching the given pattern.
+
FILENOTE attaches an optional comment characters to the specified file or to all files matching the given pattern. The size of the comment is limited, which means that the <comment> argument may be truncated before it is used.
  
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> includes spaces, it must be enclosed in double quotes. To include double quotes in a filenote, each literal quote mark must be immediately preceded by an asterisk (*), and the entire comment must be enclosed in quotes, regardless of whether the comment contains any spaces.
  
If the <comment> argument is omitted, any existing filenote is deleted from the named file.
+
To delete an existing filenote from a file, use "" as the <comment> argument.
  
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.
+
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 will be 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 an existing file is copied to (specified as the TO argument of a COPY command), it will be overwritten, but its comment will be retained. Any comment attached to a FROM file will not be copied unless the CLONE or COM option of COPY is specified.
  
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.
+
FILENOTE's options are:
 +
{| class="wikitable"
 +
| ALL || If the ALL option is given, FILENOTE will add the <comment> to all the files in the specified directory.
 +
|-
 +
| QUIET || If the QUIET option is given, screen output is suppressed. The local shell variable _Verbosity with a negative value has the same effect.
 +
|-
 +
| FILES || Only change the comments of the files found.
 +
|-
 +
| DIRS || Only change the comments of the directories found.
 +
|}
  
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.
+
{{Note|The FILES and DIRS options work together: if you use FILES and omit DIRS, then only the files will be affected and the other way round. If none of FILES and DIRS is used, all files and directories will have their comments changed.}}
  
 
; Example 1:
 
; Example 1:
Line 1,699: Line 1,814:
 
  1> FILENOTE Toccata "*"presto*""
 
  1> FILENOTE Toccata "*"presto*""
  
attaches the filenote "presto" to the Toccata file.
+
Here the filenote is "presto".
  
 
== FILESIZE ==
 
== FILESIZE ==
Line 1,713: Line 1,828:
 
; Location
 
; Location
 
: C:
 
: C:
 +
 +
== FLASHTOOL ==
 +
 +
Reading, writing, and erasing for EEPROM memory chips.
 +
 +
; Format
 +
: FLASHTOOL <command> [<command arguments>]
 +
 +
; Template
 +
: COMMAND,ARGS/M
 +
 +
; Location
 +
: C:
 +
 +
FLASHTOOL is used for reading, erasing, and writing to EEPROM non-volatile memory chips. To utilize FLASHTOOL, an IDE Flasher must be installed in the primary or secondary IDE port.
 +
 +
FLASHTOOL provides the following commands:
 +
{| class="wikitable"
 +
|-
 +
! Name
 +
! Command
 +
! Description
 +
|-
 +
| ISPRESENT || -p <device name> <unit> || Check if a flasher device is present.
 +
|-
 +
| TYPE || -t <device name> <unit> || Return EEPROM type.
 +
|-
 +
| ERASE || -e <device name> <unit> || Erase an EEPROM.
 +
|-
 +
| ISBLANK || -b <device name> <unit> || Check if EEPROM is empty.
 +
|-
 +
| SAVE || -s <device name> <unit> <file name> || Save EEPROM content to a file. The saved file is in binary (raw) format.
 +
|-
 +
| WRITE || -w <device name> <unit> <file name> || Write a binary (raw) file to EEPROM.
 +
|-
 +
| VERIFY || -c <device name> <unit> <file name> || Check if EEPROM content matches the file's content. The file must be in binary (raw) form.
 +
|-
 +
| LISTSUPPORTED || -l || List supported EEPROMs.
 +
|-
 +
| VERSION || -v || Print FLASHTOOL version.
 +
|}
 +
 +
The <device name> argument tells which Amiga device is controlling the IDE Flasher, and the <unit> argument tells which device is used.
 +
 +
FLASHTOOL supports the following EEPROMs:
 +
* ATMEL AT29C512  512 Kbit (64K x 8-bit)
 +
* ATMEL AT29C010A  1 Mbit (128K x 8-bit)
 +
* ATMEL AT29C020  2 Mbit (256K x 8-bit)
 +
* ATMEL AT29C040  4 Mbit (512K x 8-bit)
 +
* ATMEL AT29C040A  4 Mbit (512K x 8-bit)
 +
* ATMEL AT49F004N  4 Mbit (512K x 8-bit)
 +
* ATMEL AT49F004T  4 Mbit (512K x 8-bit)
 +
* ATMEL AT49F010  1 Mbit (128K x 8-bit)
 +
* ATMEL AT49F020  2 Mbit (256K x 8-bit)
 +
* AMD AM29F010  1 Mbit (128K x 8-bit)
 +
* AMD AM29F010A  1 Mbit (128K x 8-bit)
 +
* AMD AM29F040B  4 Mbit (512K x 8-bit)
 +
* AMD AM29F002  2 Mbit (256K x 8-bit) Top Boot Block
 +
* AMD AM29F002  2 Mbit (256K x 8-bit) Bottom Boot Block
 +
* AMD AM29F004  4 Mbit (512K x 8-bit) Top Boot Block
 +
* AMD AM29F004  4 Mbit (512K x 8-bit) Bottom Boot Block
 +
* MOSEL VITELIC V29C51000T  512 Kbit (64K x 8-bit)
 +
* MOSEL VITELIC V29C51000B  512 Kbit (64K x 8-bit)
 +
* MOSEL VITELIC V29C51001T  1 Mbit (128K x 8-bit)
 +
* MOSEL VITELIC V29C51001B  1 Mbit (128K x 8-bit)
 +
* MOSEL VITELIC V29C51002T  2 Mbit (256K x 8-bit)
 +
* MOSEL VITELIC V29C51002B  2 Mbit (256K x 8-bit)
 +
* MOSEL VITELIC V29C51004T  4 Mbit (512K x 8-bit)
 +
* MOSEL VITELIC V29C51004B  4 Mbit (512K x 8-bit)
 +
* HYUNDAI HY29F002T  2 Mbit (256K x 8-bit)
 +
* HYUNDAI HY29F002B  2 Mbit (256K x 8-bit)
 +
* HYUNDAI HY29F040A  4 Mbit (512K x 8-bit)
 +
* SST SST29EE512  512 Kbit (64K x 8-bit)
 +
* SST SST29EE010  1 Mbit (128K x 8-bit)
 +
* SST SST29EE020  2 Mbit (256K x 8-bit)
 +
* SST SST39SF512  512Kbit (64K x 8-bit)
 +
* SST SST39SF010(A)  1 Mbit (128K x 8-bit)
 +
* SST SST39SF020A  2 Mbit (256K x 8-bit)
 +
* SST SST39SF040  4 Mbit (512K x 8-bit)
 +
* ST M29F010B  1 Mbit (128K x 8-bit)
 +
* ST M29F002T  1 Mbit (256K x 8-bit)
 +
* ST M29F002B  1 Mbit (256K x 8-bit)
 +
* ST M29F040B  4 Mbit (512K x 8-bit)
 +
* ST M29F040  4 Mbit (512K x 8-bit)
 +
* WINBOND W29C512A  512 Kbit (64K x 8-bit)
 +
* WINBOND W29C010M  1 Mbit (128K x 8-bit)
 +
* WINBOND W29C020  2 Mbit (256K x 8-bit)
 +
* WINBOND W29C040  4 Mbit (512K x 8-bit)
 +
* WINBOND W49C020  2 Mbit (256K x 8-bit)
 +
* WINBOND W49F002U  2 Mbit (256K x 8-bit)
 +
* WINBOND W49F002U mod 2 Mbit (256K x 8-bit)
 +
* MACRONIX MX29F040  4 Mbit (512K x 8-bit)
 +
* AMIC A29010  1 Mbit (128K x 8-bit)
 +
* AMIC A29040A  4 Mbit (512K x 8-bit)
 +
* AMIC A29001T  1 Mbit (128K x 8-bit)
 +
* AMIC A29001B  1 Mbit (128K x 8-bit)
 +
* AMIC A29002T  2 Mbit (256K x 8-bit)
 +
* AMIC A29002B  2 Mbit (256K x 8-bit)
 +
* Texas Instruments TMS29F040  4 Mbit (512K x 8-bit)
 +
* IMT IM29F001T  1 Mbit (128K x 8-bit)
 +
* IMT IM29F001B  1 Mbit (128K x 8-bit)
 +
* IMT IM29F002T  2 Mbit (256K x 8-bit)
 +
* IMT IM29F002B  2 Mbit (256K x 8-bit)
 +
* IMT IM29F004T  4 Mbit (512K x 8-bit)
 +
* IMT IM29F004B  4 Mbit (512K x 8-bit)
 +
* Fujitsu MBM29F002TC  2 Mbit (256K x 8-bit)
 +
* Fujitsu MBM29F002BC  2 Mbit (256K x 8-bit)
 +
* Fujitsu MBM29F004TC  4 Mbit (512K x 8-bit)
 +
* Fujitsu MBM29F004BC  4 Mbit (512K x 8-bit)
 +
* Fujitsu MBM29F040C  4 Mbit (512K x 8-bit)
 +
 +
; Example 1:
 +
Check if an IDE Flasher device is installed:
 +
  1> FLASHTOOL -p a1ide.device 0
 +
 +
; Example 2:
 +
Erase an EEPROM:
 +
  1> FLASHTOOL -e a1ide.device 0
 +
 +
; Example 3:
 +
Write file "uboot.bin" to EEPROM:
 +
  1> FLASHTOOL -w a1ide.device 0 uboot.bin
 +
 +
; Example 4:
 +
Verify the written data:
 +
  1> FLASHTOOL -c a1ide.device 0 uboot.bin
 +
 +
; Example 5:
 +
Save EEPROM content to file "backup.bin":
 +
  1> FLASHTOOL -s a1ide.device 0 backup.bin
  
 
== FTP ==
 
== FTP ==
Line 1,748: Line 1,993:
 
  Extras:Tools/MEmacs
 
  Extras:Tools/MEmacs
  
See also: SET
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SET|SET]]
  
 
== GETENV ==
 
== GETENV ==
Line 1,769: Line 2,015:
 
  Extras:Tools/MEmacs
 
  Extras:Tools/MEmacs
  
See also: SETENV
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SETENV|SETENV]]
  
 
== GETNETSTATUS ==
 
== GETNETSTATUS ==
  
 
Queries whether the network is operational.
 
Queries whether the network is operational.
 +
 +
; Format
 +
: GETNETSTATUS [CHECK=condition[,condition...]] [QUIET]
 +
 +
; Template
 +
: CHECK/K,QUIET
 +
 +
; Location
 +
: C:
  
 
== GROUP ==
 
== GROUP ==
  
 
Changes the access rights of a file or directory.
 
Changes the access rights of a file or directory.
 +
 +
; Format
 +
: GROUP [FILE] {<file | pattern>} [GROUP] <name or number> [ALL]
 +
 +
; Template
 +
: FILE/A/M,GROUP/A,ALL/S,QUIET/S
 +
 +
; Location
 +
: C:
  
 
== HELP ==
 
== HELP ==
  
 
Text based help command.
 
Text based help command.
 +
 +
; Format
 +
: HELP [<command name> [SHORT | LFORMAT]] | [SHOWLIST]
 +
 +
; Template
 +
: COMMANDNAME,SHORT/S,LFORMAT/S,SHOWLIST/S
 +
 +
; Location
 +
: Rexx:
 +
 +
HELP will display the help text of a command given in argument. If no arguments is given, a brief description of this help system is displayed.
 +
 +
By default all the available text for the supplied command name will be printed in the Shell.
 +
 +
If the SHORT argument is supplied, only a short description will be printed. This text is extracted from the section "NAME" of the help text.
 +
 +
Some commands use the LFORMAT argument to customize the command output. This argument is always used with several output qualifiers. Supplying the LFORMAT argument to the HELP command, only the details on the usage of the LFORMAT argument will be printed. This text is extracted from the section "LFORMAT" of the help text.
 +
 +
If the SHOWLIST argument is supplied, a list of all available help texts with the short description will be displayed.
 +
 +
The HELP command will look for text help files in HELP:<your language>/Shell and if it could not be found, it will look into HELP:english/Shell.
 +
 +
HELP will display the help texts with the program you specify in the PAGER environment variable. By default, help texts will be displayed with the MORE program. As an example, if you want to use the TYPE command, store it into the PAGER variable with "SETENV PAGER TYPE".
  
 
== HI ==
 
== HI ==
  
 
Halts all ARexx programs.
 
Halts all ARexx programs.
 +
 +
; Format
 +
: HI
 +
 +
; Template
 +
: (none)
 +
 +
; Location
 +
: C:
 +
 +
Sets the global halt flag, which causes all active ARexx programs to receive an external halt request. Each program will exit immediately unless its HALT interrupt has been enabled. The halt flag does not remain set, but is cleared automatically after all current programs have received the request.
 +
 +
; Example:
 +
1> HI
 +
Command returned 10/2: Execution halted
 +
rx failed returncode 10
  
 
== HISTORY ==
 
== HISTORY ==
  
 
Display, recall, or store the command line history.
 
Display, recall, or store the command line history.
 +
 +
; Format
 +
: HISTORY [[LINES] <number>] [START <number>] [LOAD <file name>] [SAVE <file name>] [SIZE <number>] [CLEAR] [SHOW] [NONUM]
 +
 +
; Template
 +
: LINES/N,START/K/N,LOAD/K,SAVE/K,SIZE/K/N,CLEAR/S,SHOW/S,NONUM/S
 +
 +
; Location
 +
: C:
  
 
== ICONX ==
 
== ICONX ==
Line 1,824: Line 2,137:
 
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.
 
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.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]
  
 
== IF ==
 
== IF ==
Line 1,886: Line 2,200:
 
If the previous command produces a return code greater than or equal to 10, AmigaDOS skips over the ECHO command to the errlab label.
 
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.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FAILAT|FAILAT]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LAB|LAB]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#QUIET|QUIET]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SKIP|SKIP]]
  
 
== INFO ==
 
== INFO ==
  
Gives information about mounted devices.
+
Gives information about the mounted devices.
  
 
; Format
 
; Format
: INFO [<device>]
+
: INFO [<device>] [DEVICES] [VOLUMES] [SHOW=<BLOCKS|BYTES|SIZE>]
 +
: [SORT=<NAME|FREE|USED|SIZE|VOLUME>]
  
 
; Template
 
; Template
: DEVICE
+
: DEVICE,DEVICES/S,VOLUMES/S,SHOW/K,SORT/K
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
INFO displays a line of information about each disk or partition. This includes the maximum size of the disk, the used and free space, the number of soft disk errors that have occurred, the status of the disk and the DOS type if available.
  
With the <device> argument, INFO provides information on the specified device or volume only.
+
With the DEVICE argument, INFO provides information on just one device or volume.
  
; Example:
+
The options are:
  1>INFO
+
{| class="wikitable"
 +
| DEVICES || Show only device information, omit volume data.
 +
|-
 +
| VOLUMES || Show only volume information, omit device data.
 +
|-
 +
| SHOW || Select the format in which the Free/Full column data should be printed. This must be one of BLOCKS, BYTES or SIZE. "BLOCKS", which is the default, will display the number blocks available for use and already allocated. "BYTES" will display the same information in bytes. Note that due to how the file system allocates storage space, this may not be an accurate figure. Typically, a file needs more storage space on disk than just the data stored in it. "SIZE" will print an approximate rough figure in the KByte/MByte/GByte range, similar to the "Size" column.
 +
|-
 +
| SORT || Choose by which criterion the device list should be sorted. This must be one of NAME (the default), FREE (by free space), USED (by allocated space), SIZE (total size) or VOLUME (volume name). Note that because block sizes may vary, for FREE, USED and SIZE the number of bytes is used account, not the number of blocks.
 +
|}
 +
 
 +
; Example 1:
 +
  1> INFO
 +
Unit Size Used Free Full Errors Status    Name        DOS Type
 +
DF0: 837K 1742  16  98%      0 Read Only  Workbench2.0 DOS\01
 +
DF1: 837K  211 1547  12%      0 Read/Write Text-6      DOS\03
 
   
 
   
  Unit Size Used Free Full Errs Status Name
+
Volumes available:
  DF0: 879K 1738 20 98% 0 Read Only Workbench
+
Workbench2.0 [Mounted]
  DF1: 879K 418 1140 24% 0 Read/Write Text-6
+
Text-6 [Mounted]
 +
 
 +
; Example 2:
 +
1> INFO SHOW=BYTES
 +
Mounted disks:
 +
  Unit Size   Used   Free Full Errors Status     Name         DOS Type
 +
  DF0: 837K 850096  7808  98%     0 Read Only Workbench2.0 DOS\01
 +
  DF1: 837K 102968 754936  12%     0 Read/Write Text-6       DOS\03
 
   
 
   
 
  Volumes available:
 
  Volumes available:
  Workbench [Mounted]
+
  Workbench2.0 [Mounted]
 +
Text-6 [Mounted]
 +
 
 +
; Example 3:
 +
1> INFO VOLUMES
 +
Volumes available:
 +
Workbench2.0 [Mounted]
 
  Text-6 [Mounted]
 
  Text-6 [Mounted]
  
Line 1,958: Line 2,305:
 
Alters packet filtering lists for IP packet input and output.
 
Alters packet filtering lists for IP packet input and output.
  
== IPSTAT ==
+
; Format
 +
: IPF [-AdDEInoPrsvVyzZ] [-l <block | pass | nomatch>] [-F <i| o | a | s | S>] -f <filename> [-f <filename> [...]]
  
Reports on packet filter statistics and filter list.
+
; Template
 +
: -A,-d,-D,-E,-I,-n,-o,-P,-r,-s,-v,-V,-y,-z,-Z,-l,-F,-f
 +
 
 +
; Location
 +
: C:
  
 
== IPMON ==
 
== IPMON ==
  
 
Monitors /dev/ipl for logged packets.
 
Monitors /dev/ipl for logged packets.
 +
 +
; Format
 +
: IPMON [-aDFhnpstvxX] [-N <device>] [-o [NSI]] [-O [NSI]] [-P <pidfile>] [-S <device>] [-f <device>] [<filename>]
 +
 +
; Template
 +
: -N,-F,-h,-s,-t,-v,-x,-X,-f
 +
 +
; Location
 +
: C:
  
 
== IPNAT ==
 
== IPNAT ==
  
 
Defines NAT (Network Address Translation) rules.
 
Defines NAT (Network Address Translation) rules.
 +
 +
; Format
 +
: IPNAT
 +
 +
; Template
 +
: (none)
 +
 +
; Location
 +
: C:
  
 
== JOIN ==
 
== JOIN ==
Line 2,007: Line 2,377:
 
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.
 
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.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SKIP|SKIP]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IF|IF]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]
  
 
== LIST ==
 
== LIST ==
Line 2,014: Line 2,387:
  
 
; Format
 
; 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]
+
: LIST [{<dir|pattern>}] [P|PAT <pattern>] [KEYS] [DATES] [NODATES]
 +
: [TO <name>] [SUB <string>] [SINCE <date>] [UPTO <date>] [QUICK]
 +
: [BLOCK] [NOHEAD] [FILES] [DIRS] [LFORMAT <string>]
 +
: [SORT [NAME] [SIZE] [DATE] [REVERSENAME] [REVERSESIZE]
 +
: [REVERSEDATE]] [USERS] [GROUPS] [MULTI] [ALL]
  
 
; Template
 
; 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
+
: 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,SORT/K,USERS/S,GROUPS/S,MULTI/S,ALL/S
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
LIST displays information about the contents of the current directory. If you specify a <dir>, <pattern>, or <filename> argument, LIST will display information about the specified directory, all directories or files that match the pattern, or the specified file, respectively.
  
 
Unless other options are specified, LIST displays the following:
 
Unless other options are specified, LIST displays the following:
Line 2,028: Line 2,405:
 
| name || The name of the file or directory.
 
| 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".
+
| size || The size of the file in bytes. If there is nothing in this file, the field will read 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.
+
| protection || The protection bits that are set for this file are shown as letters. The clear (unset) bits are shown as hyphens. Most files will show the default protection bits, ----rwed for readable/writable/executable/deleteable. See the PROTECT command for more on protection bits.
 
|-
 
|-
| date and time || The date and time the file was created or last changed.
+
| date and time || The date and time the file was created or last altered.
 
|-
 
|-
 
| comment || The comment, if any, placed on the file using the FILENOTE command. It is preceded by a colon (:).
 
| comment || The comment, if any, placed on the file using the FILENOTE command. It is preceded by a colon (:).
Line 2,039: Line 2,416:
 
LIST uses the following options to change the way the output is displayed:
 
LIST uses the following options to change the way the output is displayed:
 
{| class="wikitable"
 
{| class="wikitable"
 +
| PAT <pattern> || Lists only files which match the pattern <pattern>.
 +
|-
 
| KEYS || Displays the block number of each file header or directory.
 
| KEYS || Displays the block number of each file header or directory.
 
|-
 
|-
| DATES || Displays dates. (For example, DD-MMM-YY is the USA default).
+
| DATES || Displays dates in the form DD-MMM-YY (the default unless you use QUICK).
 
|-
 
|-
| NODATES || Does not display date and time information.
+
| NODATES || Will not display date and time information.
 
|-
 
|-
 
| TO <name> || Specifies an output file or device for LIST; by default, LIST outputs to the current window.
 
| TO <name> || Specifies an output file or device for LIST; by default, LIST outputs to the current window.
Line 2,049: Line 2,428:
 
| SUB <string> || Lists only files containing the substring <string>.
 
| SUB <string> || Lists only files containing the substring <string>.
 
|-
 
|-
| SINCE <date> || Lists only files timestamped on or after the specified date.
+
| SINCE <date> || Lists only files created on or after a certain date.
 
|-
 
|-
| UPTO <date> || Lists only files timestamped on or before the specified date.
+
| UPTO <date> || Lists only files created on or before a certain date.
 
|-
 
|-
 
| QUICK || Lists only the names of files and directories.
 
| QUICK || Lists only the names of files and directories.
 
|-
 
|-
| BLOCK || Displays file sizes in 512-byte blocks, rather than bytes.
+
| BLOCK || Displays file sizes in blocks, rather than bytes.
 
|-
 
|-
| NOHEAD || Suppresses printing of the header and summary information.
+
| NOHEAD || Suppresses the printing of the header information.
 
|-
 
|-
 
| FILES || Lists files only (no directories).
 
| FILES || Lists files only (no directories).
Line 2,065: Line 2,444:
 
| LFORMAT || Defines a string to specially format LIST output.
 
| LFORMAT || Defines a string to specially format LIST output.
 
|-
 
|-
| ALL || Lists the contents of all directories and subdirectories.
+
| SORT <order> || Sorts the directory entries before displaying it, based upon certain criteria. The SORT option requires a list of parameters which define in which order and by which criteria the output should be sorted. The SORT option parameter must match the following template:
 +
 
 +
N=NAME,D=DATE,S=SIZE,T=TYPE,RN=REVERSENAME,RD=REVERSEDATE,
 +
RS=REVERSESIZE,RT=REVERSETYPE
 +
 
 +
The order in which you specify the single options determines the order in which the criteria are matched. Thus, if you want the list to be sorted descending size and by name you would specify SORT=REVERSESIZE,NAME.
 +
|-
 +
| USERS || Attempt to resolve the name of the 'owner' of a file. If no name resolution is possible, then the numeric owner ID number will be displayed instead.
 +
|-
 +
| GROUPS || Attempt to resolve the name of the group the 'owner' of a file belongs to. If no name resolution is possible, then the numeric group ID number will be displayed instead.
 +
|-
 +
| MULTI || Display all linked directories in a multi-assignment. (V53)
 +
|-
 +
| ALL || Lists all files in 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 LFORMAT option modifies the output of LIST and can be used as a quick method of generating script files. When LFORMAT is specified, the QUICK and NOHEAD options are automatically selected. When using LFORMAT you must specify an output format specification string; this string is incorporated into the script file. If you want the output to be saved, you must redirect it to a file by using the > operator or specifying a TO file.
 +
 
 +
The format for the output format specification string is LFORMAT=<string>. To include the output of LIST in this string, use the substitution operator %S. The path and filename can be made part of the string this way. Whether the path or the filename is substituted for an occurrence of %S depends on how many occurrences are in the LFORMAT line, and their order, as follows:
  
The available substitution operators are:
+
{| class="wikitable"
 +
| || colspan="4" | Substituted with each occurrence
 +
|-
 +
|style="text-align:center;" | Occurrences of %S || 1st || 2nd || 3rd || 4th
 +
|-
 +
|style="text-align:center;" | 1 || filename || || ||
 +
|-
 +
|style="text-align:center;" | 2 || path || filename || ||
 +
|-
 +
|style="text-align:center;" | 3 || path || filename || filename ||
 +
|-
 +
|style="text-align:center;" | 4 || path || filename || path || filename
 +
|}
 +
 
 +
Some new options allow you to specify fields to be printed in the LFORMAT output. These options are:
 
{| class="wikitable"
 
{| class="wikitable"
 
| %A || Prints file attributes (protection bits).
 
| %A || Prints file attributes (protection bits).
Line 2,080: Line 2,488:
 
| %D || Prints the date associated with the file.
 
| %D || Prints the date associated with the file.
 
|-
 
|-
| %E || Prints just the file extension.
+
| %E || Prints the file extension.
 +
|-
 +
| %F || Prints the full file parent path.
 +
|-
 +
| %G || Prints the name of the group which 'owns' the file.
 
|-
 
|-
 
| %K || Prints the file key block number.
 
| %K || Prints the file key block number.
Line 2,092: Line 2,504:
 
| %P || Prints the file parent path.
 
| %P || Prints the file parent path.
 
|-
 
|-
| %S || Superseded by %N and %P; still functional.
+
| %R || Prints the name of the object the file/directory is linked to.
 
|-
 
|-
 
| %T || Prints the time associated with the file.
 
| %T || Prints the time associated with the file.
 +
|-
 +
| %U || Prints the name user who 'owns' the file.
 +
|-
 +
| %V || Prints group/other file attributes (protection bits).
 
|}
 
|}
  
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.
+
You can put a length specifier and/or a justification specifier between the percent size (%) and the field specifier.
 
+
The default output of the LIST command uses the following specification:
+
 
+
%-24 %7L %A %D %T
+
  
 
; Example 1:
 
; Example 1:
 
  > LIST Dirs
 
  > LIST Dirs
 
+
  Prefs Dir ----rwed 27-Jun-93 11:43:59
+
  Monitors    Dir ----       rwed     27-June-90      11:43:59
  T Dir ----rwed 16-Jul-93 11:37:43
+
  T           Dir ----       rwed     Wednesday      11:37:43
  Trashcan Dir ----rwed 21-Jun-93 17:54:20
+
  Trashcan     Dir ----       rwed     21-Jun-90      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.)
 
Only the directories in the current directory, in this case SYS:, are listed. (A shortened version of the typical output is shown above.)
Line 2,115: Line 2,527:
 
  1> LIST LI#? TO RAM:Libs.file
 
  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:.
+
LIST will search for any directories or files that start with LI. The output of LIST will be sent to the Libs.file in RAM:.
  
 
; Example 3:
 
; Example 3:
 
  1> LIST DF0:Documents UPTO 09-Oct-90
 
  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.
+
Only the files or directories on the Documents directory of DF0: that have not been changed since October 9, 1990, will be listed.
  
For further examples using the LIST command, see Chapter 8.
+
; Example 4:
 +
1> LIST >RAM:Scriptnotes #? LFORMAT="filenote %S%S Testnote"
  
== LOADMONDRVS ==
+
A new script file, Scriptnotes, is created in RAM:. The contents will include a list of all the files in the current directory. When Scriptnotes is executed, it will add the filenote Testnote to each file. For instance, if the current directory is S:, the contents of Scriptnotes as produced by this command might look like this:
 +
 
 +
: filenote s:HDBackup.config Testnote
 +
: filenote s:DPat Testnote
 +
: filenote s:Ed-startup Testnote
 +
: filenote s:PCD Testnote
 +
: filenote s:Shell-startup Testnote
 +
: filenote s:SPat Testnote
 +
: filenote s:Startup-sequence Testnote
  
Starts monitor drivers.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#PROTECT|PROTECT]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FILENOTE|FILENOTE]]
  
 
== LOADRESOURCE ==
 
== LOADRESOURCE ==
  
 
Preloads resources into memory to avoid excessive disk swaps.
 
Preloads resources into memory to avoid excessive disk swaps.
 +
 +
<span style="color: red;">NOTE: This command is obsolete.</span>
  
 
; Format
 
; Format
Line 2,176: Line 2,601:
  
 
; Format
 
; Format
: LOADWB [-DEBUG] [DELAY] [CLEANUP] [NEWPATH]
+
: LOADWB [-DEBUG] [DELAY] [CLEANUP] [NEWPATH] [SKIP=SKIPWBSTARTUP] [SIMPLEGELS]
  
 
; Template
 
; Template
: -DEBUG/S,DELAY/S,CLEANUP/S,NEWPATH/S
+
: -DEBUG/S,DELAY/S,CLEANUP/S,NEWPATH/S,SKIP=SKIPWBSTARTUP/S,SIMPLEGELS/S
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
LOADWB starts the Workbench. Normally, this is done when booting, by placing the LOADWB command in the Startup-Sequence file. If you shut down the Workbench, LOADWB can be used from a Shell to restart it.
  
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.
  
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.
+
LOADWB's command line options are:
 +
{| class="wikitable"
 +
| -DEBUG || Adds two additional menus which can assist software debugging. You should not use this feature unless you know how to use these menus.
 +
|-
 +
| DELAY || The LoadWB command will wait until the Workbench is loaded and initialized; otherwise, LoadWB will launch the Workbench and return immediately.
 +
|-
 +
| CLEANUP || Clean up the contents of the main Workbench window once Workbench has been launched.
 +
|-
 +
| NEWPATH || Update the Workbench command search path to use the settings of the shell the LoadWB program runs in. Workbench uses the search path (maintained through the shell PATH command) to find programs whose names do not include a directory name.
 +
|-
 +
| SKIPWBSTARTUP || Do not look into the "SYS:WBStartup" drawer and launch the programs stored in it.
 +
|-
 +
| SIMPLEGELS || When moving icons on the screen, try to use only the technique that Workbench has been using through versions 1.2-3.1. This is a compatibility switch which can be used to prevent Workbench from crashing if the graphics support software does not support the new icon rendering methods introduced in Workbench 3.5.
 +
|}
  
 
; Example 1:
 
; Example 1:
  
If you quit the Workbench and are working through a Shell, enter:
+
If you have quit the Workbench and are working through a Shell, typing:
  
 
  1> LOADWB
 
  1> LOADWB
  
to return the Workbench. Entering LOADWB when the Workbench is already loaded has no effect.
+
will bring the Workbench back. Typing LOADWB when the Workbench is already loaded has no effect.
  
 
; Example 2:
 
; Example 2:
Line 2,239: Line 2,677:
  
 
Locking a device is only good for the duration of the current session. Resetting or turning off the Amiga cancels the lock.
 
Locking a device is only good for the duration of the current session. Resetting or turning off the Amiga cancels the lock.
 
== LOGVIEWER ==
 
 
Captures any debug or notification messages sent by bsdsocket.library or its clients.
 
  
 
== MAGTAPE ==
 
== MAGTAPE ==
Line 2,271: Line 2,705:
  
 
; Format
 
; Format
: MAKEDIR {<name}
+
: MAKEDIR {<name>} [ALL] [FORCE]
  
 
; Template
 
; Template
: NAME/M
+
: NAME=DIRS/M/A,ALL/S,FORCE/S
  
 
; Location
 
; Location
 
: C:
 
: 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 creates one (or several) empty directory(s) with the name(s) you specify. By default, the command works within only one directory level at a time, so any directories on the given path(s) must already exist. When using the ALL option, directories missing on the path(s) are automatically created, if necessary. The command fails if a directory or a file of the same name already exists in the directory above it in the hierarchy. To avoid this, use the FORCE option which makes the command ignore directories which already exist.
  
MAKEDIR does not create a drawer icon for the new directory.
+
{{Note|MAKEDIR does not create a drawer icon for the new directory(s).}}
  
 
; Example 1:
 
; Example 1:
Line 2,289: Line 2,723:
  
 
; Example 2:
 
; Example 2:
  1> MAKEDIR DF1:Xyz
+
  1> MAKEDIR DF1:Abc/Xyz ALL
  
creates a directory Xyz in the root directory of the disk in DF1:.
+
creates a directory Abc in the root directory of the disk in DF1: if it doesnt exist yet, then creates directory Xyz in DF1:Abc/.
  
 
; Example 3:
 
; Example 3:
Line 2,297: Line 2,731:
 
  1> MAKEDIR Documents Payables Orders
 
  1> MAKEDIR Documents Payables Orders
  
creates three directories on the disk in DF0:: Documents, Payables, and Orders.
+
creates three directories, Documents, Payables, and Orders, on the disk in DF0:.
 
+
For more examples using MAKEDIR, see Chapter 8.
+
  
 
== MAKELINK ==
 
== MAKELINK ==
  
Creates a link between files.
+
Creates a link between files or directories.
  
 
; Format
 
; Format
: MAKELINK [FROM] <file> [TO] <file> [HARD] [FORCE]
+
: MAKELINK [FROM] <link> [TO] <file or directory> [SOFT] [HARD] [FORCE]
  
 
; Template
 
; Template
: FROM/A,TO/A,HARD/S,FORCE/S
+
: LINK=FROM/A,FILE=DIR=DIRECTORY=TO/A,SOFT/S,HARD/S,FORCE/S
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
MAKELINK creates a special file on a disk that is a pointer to another file or directory, this is known as a link. When an application or command tries to use the FROM file, the TO file or directory is actually used.
  
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.
+
There exist two types of links, hard links and soft links.
  
== MD5SUM ==
+
A hard link is some sort of "physical" link handled by the file system itself, it points to the physical location (e.g. a disk block) of the destination. This implies that both the link and the destination must be on the same volume, that renaming the destination (including renaming into another directory) cannot "break" the link (it will continue to point to the same object) and that even deleting the destination wont cause problems (the link will be replaced with the file or directory before the file or directory is deleted). Not all file systems support hard links.
  
Calculates and compares checksums of files.
+
A soft link is some sort of "logical" link handled by the file system, dos.library and the applications, it points to a name which describes the path of the destination. All types of paths can be used (absolute and relative, with or without file name). This implies that both the link and the destination can be located on different volumes and that renaming or deleting the destination will "break" the link (it will point to a no longer existing object). Old applications are sometimes not aware of soft links and will consider them to be directories or ignore them altogether. Not all file systems support soft links. Old file systems may have problems with relative path names in soft links ("///dir2/file3"). Some applications may have problems with "broken" soft links for which the respective destinations do not exist any more.
  
== MOUNT ==
+
By default, or when the SOFT keyword is given, MAKELINK tries to create a soft link. When the HARD keyword is given, MAKELINK tries to create a hard link. (Note that the default changed to this from version 53.3+)
  
Makes a device connected to the system available.
+
Also by default when doing soft links, if the destination path is relative (i.e. a path not prefixed by a volume name), MAKELINK will try to resolve it relative to the directory which will contain the link, it will not resolve it relative to the current directory like other commands. See examples below.
 +
 
 +
When creating a hard link, and the TO argument is a directory name, MAKELINK does not normally allow the creation of a hard link to a directory. When the FORCE keyword is also given, it allows it.
 +
 
 +
When creating a soft link, the link destination should exist, and MAKELINK will consider it an error if this is not the case. However, it is sometimes necessary to create a soft link before the link destination itself has been made available. In such a case, the FORCE keyword will cause MAKELINK to create the soft link regardless of whether the destination already exists or not.
 +
 
 +
; Example 1:
 +
SYS:> MakeLink RAM:Link S/User-Startup SOFT
 +
 
 +
will create a soft link to RAM:S/User-Startup (this file must exist) and not to SYS:S/User-Startup as one could expect.
 +
 
 +
; Example 2:
 +
SYS:> MakeLink RAM:Link SYS:S/User-Startup SOFT
 +
 
 +
will create a soft link to SYS:S/User-Startup (absolute path)
 +
 
 +
== MD5SUM ==
 +
 
 +
Calculates and compares checksums of files.
  
 
; Format
 
; Format
: MOUNT {device} [FROM <filename>]
+
: MD5SUM [{dir|file|pattern|device}] [ALL] [DEVICES] [TO <name>] [SORT] [BUF=BUFFERSIZE <size>] [CHECK|FROM <name>] [STATUS] [QUIET] [WARN] [ALGORITHM {?|<name>}]
  
 
; Template
 
; Template
: DEVICE/M,FROM/K
+
: NAMES/M,ALL/S,TO/K,DEVICES/S,SORT/S,BUF=BUFFERSIZE/K/N,CHECK=FROM/K,STATUS/S,WARN/S,QUIET/S,ALGORITHM/K
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
MD5SUM will read the contents of files or devices and calculate a checksum for each individual item. If you specify a <dir>, <pattern>, <filename>, or <device> argument, MD5SUM will calculate checksums for the specified directory, all directories, or files that match the pattern, or the specified file or device, respectively. MD5SUM can also determine whether a file or a checksum are consistent.
  
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:
+
MD5SUM has options which will change the way the output is displayed and how input is processed. These options are explained below.
  
# 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.
+
ALL calculates checksums for all files in directories and subdirectories.
# 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.}}
+
DEVICES indicates that rather than checking the contents of a device file by file, the checksums should be calculated over the raw storage blocks instead. Note that only file system devices can be used which store data in disk blocks. This includes "df0:", "df1:", etc. but not "ram:" or "prt:".
 +
 
 +
TO <name> specifies an output file or device for MD5SUM; by default, MD5SUM ouputs to the current window.
 +
 
 +
SORT sorts the list before printing.
 +
 
 +
BUFFERSIZE <size> sets the size of the read buffer being used. Default is 262144 bytes (256 kB). Larger values can increase performance.
 +
 
 +
CHECK <name> causes MD5SUM to read the contents of a list file <name> previously generated by MD5SUM and try to open each file listed in it, calculate its checksum and compare it with the value given in the list. If no matching file could be opened or the checksums do not match, an error message will be printed. Use the STATUS option to omit all output.
 +
 
 +
If the STATUS option is supplied, no output will be generated if a mismatch is found while a list is being checked. Instead, MD5SUM will immediately abort with WARN condition set; this can be tested in script files.
 +
 
 +
WARN causes MD5SUM to print a warning message for each line in the list to be checked which does not match the format MD5SUM expects.
 +
 
 +
QUIET prevents MD5SUM from printing progress reports while individual files or devices are being read. The local shell variable ''_Verbosity'' with a negative value has the same effect. Progress reports are printed in about each second. No progress reports are printed if the SORT option is effect.
 +
 
 +
ALGORITHM sets the checksumming algorithm to be used. The default algorithm is "MD5", but there may be more modern algorithms supported, too. To find out which algorithms are available, enter "MD5SUM ALGORITHM ?", which will list all the supported algorithms by name. At this time of writing the following algorithms are implemented:
 +
 
 +
{| class="wikitable"
 +
| MD5 || Message Digest #5, as defined in RFC 1321.
 +
 
 +
'''Note''': At this time of writing (2005-11-20) the MD5 algorithm can no longer be considered secure.
 +
|-
 +
| SHA-1 || Secure Hash Algorithm #1, as defined in U.S. Federal Information Processing Standard (FIPS) 180-1. This Algorithm produces 160 bits of checksum data.
 +
 
 +
'''Note''': At this time of writing (2005-11-20) the SHA-1 algorithm can no longer be considered secure.
 +
|-
 +
| SHA-256 || Secure Hash Algorithm, as defined in U.S. Federal Information Processing Standard (FIPS) 180-2. This Algorithm produces 256 bits of checksum data.
 +
|-
 +
| SHA-384 || Secure Hash Algorithm, as defined in U.S. Federal Information Processing Standard (FIPS) 180-2. This Algorithm produces 384 bits of checksum data.
 +
|-
 +
| SHA-512 || Secure Hash Algorithm, as defined in U.S. Federal Information Processing Standard (FIPS) 180-2. This Algorithm produces 512 bits of checksum data.
 +
|-
 +
| Whirlpool || As defined in ISO/IEC 10118-3. This algorithm produces 512 bits of checksum data.
 +
 
 +
You can choose an algorithm by the name given. Note that the output produced by this MD5SUM program may not be compatible with other "md5sum" shell commands from the Unix world if you choose any checksumming algorithm other than "MD5" here.
 +
 
 +
Good reasons why you might want to use a different checksumming algorithm are in the security of the original "MD5" algorithm.
 +
At this time of writing (2005-11-20) it is believed that both the "MD5" and "SHA-1" algorithms can no longer be considered
 +
secure and it is recommended that you use a more secure algorithm such as "SHA-256" or "Whirlpool" instead.
 +
 
 +
Support for the "MD5" algorithm is preserved in this command only because "MD5" file checksums are still very common on the Internet.
 +
|}
 +
 
 +
{{Note| The format of the data produced and used by the MD5SUM command is compatible with the Unix "md5sum" program.}}
  
 
; Example 1:
 
; Example 1:
1> MOUNT PIPE:
+
Calculate checksums for all files in the C: directory and sort the list by file name before printing it:
  
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.
+
  1> MD5SUM C: SORT
 +
  1bd137145fbb3c409771b6bd889adb07  c:AddBuffers
 +
  7ab3d10a31518a011a63e5a099beb876  c:AddDataTypes
 +
  0ca24f1b23fb52642b895010edf79b89  c:Assign
 +
  98abb6f23ca1097898cdf98a84c6d69f  c:Avail
 +
  891ec3cb98bd0744cbb5f7407e678c71  c:BindDrivers
  
 
; Example 2:
 
; Example 2:
1> MOUNT Work:Devices/PIPE
+
Calculate the checksums for all files on the Work: partition, sort the list and store it in a file:
  
This looks for a PIPE mount file in Work:Devices.
+
  1> MD5SUM Work: SORT TO Work.Checksums
  
 
; Example 3:
 
; Example 3:
1> MOUNT PIPE: FROM SYS:Mydevs/MountList
+
Calculate and compare the checksums for all files listed in the file 'Work.Checksums' and print the differences:
  
This scans for a PIPE entry in SYS:Mydevs/MountList.
+
  1> MD5SUM CHECK Work.Checksums
  
See Appendix B for further information on MountLists.
+
; Example 4:
 +
Calculate the checksums for the disks in the drives DF0 and DF1:
 +
 
 +
  1> MD5SUM DEVICES df0: df1:
 +
  b0af4fc275bf1cb26016bd6abccc2548  df0:
 +
  fc2b0af47b01ab5bf1cc6b48d6cc2526  df1:
 +
 
 +
; Example 5:
 +
List all the supported checksumming algorithms:
 +
 
 +
  1> MD5SUM Algorithm ?
 +
  MD5SUM: Supported algorithms are MD5, SHA-1, SHA-256, SHA-384,
 +
  SHA-512, Whirlpool.
 +
 
 +
== MOUNT ==
 +
 
 +
Makes a device connected to the system available.
 +
 
 +
; Format
 +
: MOUNT <device|pattern> [FROM <filename>] [QUIET] [REPLACE] [STARTUP <parameters>]
 +
 
 +
; Template
 +
: DEVICE/A/M,FROM/K,DEBUG/S,QUIET/S,REPLACE/S,STARTUP/K/F
 +
 
 +
; Location
 +
: C:
 +
 
 +
MOUNT causes AmigaDOS to recognize devices connected to the system. When the MOUNT command is issued, MOUNT looks in the DEVS:MountList file (or the optional FROM file) for the parameters of the device that is being mounted. It also looks for mount files named according to the respective device in the directories "DEVS:DOSDrivers" and "SYS:Storage/DOSDrivers". MOUNT commands are usually placed in the Startup-Sequence file.
 +
 
 +
In place of a device name, a wildcard pattern can be used to identify the names of the mount files to be used. For example, to mount all devices in "DEVS:DOSDrivers" you would use the following command:
 +
 
 +
1> Mount DEVS:DOSDrivers/~(#?.info)
 +
 
 +
MOUNT will complain if the device to be mounted has already been mounted (the warning message can be hidden by using the QUIET option). If you actually wanted to remount the device, perhaps with new parameters, you can use the REPLACE option: this will have the same effect as issuing the "ASSIGN <device name> DISMOUNT" command before the respective device is mounted again. Note that this is not normally a good idea since only few file systems and handlers will support it.
 +
 
 +
Some handlers need to receive additional instructions when they are started. Traditionally, such information goes into the mount file, following the "STARTUP = " text. At times it is more convenient to pass these instructions directly on the MOUNT command line, which then are passed down to the handler. This is what the STARTUP option will do. Note that all devices given on the MOUNT command line will receive these startup instructions and that these instructions will never override the startup instructions given in the mount file, etc.
 +
 
 +
MOUNT will look in both the mount file and in the tooltypes of the mount file icon for keywords. The DEBUG switch can be used to tell MOUNT that it shall complain about unknown tooltypes or tooltypes which are missing an equal sign.
  
 
== MOUNTINFO ==
 
== MOUNTINFO ==
  
Creates mount files for file systems.
+
Creates mount files for the file systems.
 +
 
 +
; Format
 +
: MOUNTINFO [<device>] [[TO=<file name> [ADDICON]] [ACTIVATE] [DEBUG]
 +
 
 +
; Template
 +
: DEVICE/A,TO/K,ADDICON/S,ACTIVATE/S,DEBUG/S
 +
 
 +
; Location
 +
: C:
  
 
== MOVE ==
 
== MOVE ==
  
 
Moves files or directories.
 
Moves files or directories.
 +
 +
; Format
 +
: MOVE
 +
 +
; Template
 +
: FROM/A/M,TO/A,QUIET/S,BUF=BUFFERS/K/N,NOREQ/S,NOREPLACE/S,INTERACTIVE/S,FORCE/S,COPYLINKS/S,FOLLOWLINKS/S
 +
 +
; Location
 +
: C:
  
 
== NETLOGVIEWER ==
 
== NETLOGVIEWER ==
  
Captures any debug or notification messages sent by bsdsocket.library or its clients.
+
Captures any debug or notification messages sent by the bsdsocket.library or its clients.
 +
 
 +
; Format
 +
: NETLOGVIEWER [<popup key>] [<priority>] [CX_POPUP=<no | yes>]
 +
 
 +
; Template
 +
: CX_POPKEY/K,CX_PRIORITY/K/N,CX_POPUP/K
 +
 
 +
; Location
 +
: C:
  
 
== NETSHUTDOWN ==
 
== NETSHUTDOWN ==
  
 
Shuts down the network in an orderly fashion.
 
Shuts down the network in an orderly fashion.
 +
 +
; Format
 +
: NETSHUTDOWN [<seconds>] [QUIET]
 +
 +
; Template
 +
: TIMEOUT/N,QUIET/S
 +
 +
; Location
 +
: C:
  
 
== NEWCLI ==
 
== NEWCLI ==
Line 2,457: Line 3,027:
 
| SMART || If you enlarge the window, the text does not expand to fill the newly available space. This saves memory.
 
| 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.
+
| 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.
 
|}
 
|}
  
Line 2,484: Line 3,054:
  
 
Prints the value of all or a named UBoot environment variable.
 
Prints the value of all or a named UBoot environment variable.
 +
 +
; Format
 +
: NVGETVAR <name>
 +
 +
; Template
 +
: NAME
 +
 +
; Location
 +
: C:
 +
 +
NVGETVAR <name> will print the value of the UBoot environment variable "name". If nothing is provided for the <name>, all variables are printed.
 +
 +
If the requested variable does not exists, NVGETVAR will print nothing, and set the condition flag to 5 (WARN).
 +
 +
; Example:
 +
1> NVGETVAR boot_config
 +
AmigaOS 4.1 FE
 +
 +
prints the value of the boot_config variable.
  
 
== OWNER ==
 
== OWNER ==
  
 
Changes the ownership of a file or directory.
 
Changes the ownership of a file or directory.
 +
 +
; Format
 +
: OWNER [FILE] {<file | pattern>} [OWNER] <name or number> [ALL] [QUIET]
 +
 +
; Template
 +
: FILE/A/M,OWNER/A,ALL/S,QUIET/S
 +
 +
; Location
 +
: C:
  
 
== PATH ==
 
== PATH ==
Line 2,531: Line 3,129:
 
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.
 
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.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ASSIGN|ASSIGN]]
  
 
== PATHPART ==
 
== PATHPART ==
  
 
Splits and assembles directory and file names.
 
Splits and assembles directory and file names.
 +
 +
; Format
 +
: PATHPART [DIR <path name>] [FILE <path name>] [ADD {<directory name | file name}]
 +
 +
; Template
 +
: DIR/K,FILE/K,ADD/K/N
 +
 +
; Location
 +
: C:
  
 
== PING ==
 
== PING ==
  
 
Sends ICMP ECHO_REQUEST packets to network hosts.
 
Sends ICMP ECHO_REQUEST packets to network hosts.
 +
 +
; Format
 +
: PING [-c | COUNT <number>] [-d | DEBUG] [-i | INTERVAL <wait>]
 +
: [-l | LOAD <preload>] [-n | NUMERICONLY | NUMERIC] [-q | QUIET]
 +
: [-R | RECORDROUTE] [DONTROUTE] [-s | SIZE <packet size>]
 +
: [-v | VERBOSE] [BELL] [HOST] <host name or IP address>
 +
 +
; Template
 +
: -c=COUNT/K/N,-d=DEBUG/S,-i=INTERVAL/K/N,-l=LOAD/K/N,-n=NUMERICONLY/S=NUMERIC/S,-q=QUIET/S,-R=RECORDROUTE/S,DONTROUTE/S,-s=SIZE/K/N,-v=VERBOSE/S,BELL/S,HOST/A
 +
 +
; Location
 +
: C:
  
 
== PIPE ==
 
== PIPE ==
  
 
Connects input and output streams of Shell commands.
 
Connects input and output streams of Shell commands.
 +
 +
; Format
 +
: PIPE <command>
 +
 +
; Template
 +
: COMMAND/A/F
 +
 +
; Location
 +
: Internal
  
 
== POPCD ==
 
== POPCD ==
  
 
Returns the directory last recently saved with the PUSHCD command.
 
Returns the directory last recently saved with the PUSHCD command.
 +
 +
; Format
 +
: POPCD
 +
 +
; Template
 +
: (none)
 +
 +
; Location
 +
: Internal
  
 
== PROMPT ==
 
== PROMPT ==
Line 2,607: Line 3,245:
  
 
; Format
 
; Format
: PROTECT [FILE] <file | pattern> [FLAGS][+ | -] [<flags>] [ADD | SUB] [ALL] [QUIET]
+
: PROTECT [FILE] <file|pattern> [FLAGS] [+|-] [<flags>] [CLEAR] [FILES] [DIRS]
  
 
; Template
 
; Template
: FILE/A,FLAGS,ADD/S,SUB/S,ALL/S,QUIET/S
+
: FILE/A,FLAGS,ADD/S,SUB/S,ALL/S,QUIET/S,USER/S,GROUP/S,OTHER/S,CLONE/S,CLEAR/S,FILES/S,DIRS/S
  
 
; Location
 
; Location
 
: C:
 
: 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.
+
All files have a series of protection bits stored with them which control their attributes. These bits can be altered to indicate the type of file and the file operations permitted. PROTECT is used to set or clear the protection bits of a file.
  
 
The protection bits are represented by letters:
 
The protection bits are represented by letters:
 
{| class="wikitable"
 
{| class="wikitable"
 +
| r || The file can be read.
 +
|-
 +
| w || The file can be written to (altered).
 +
|-
 +
| e || The file is executable (a program).
 +
|-
 +
| d || The file can be deleted.
 +
|-
 
| s || The file is a script.
 
| s || The file is a script.
 
|-
 
|-
Line 2,625: Line 3,271:
 
| a || The file has been archived.
 
| a || The file has been archived.
 
|-
 
|-
| r || The file can be read.
+
| h || The command file should be held resident in memory after it has been used (requires that the 'p' bit is set, too)
 +
|}
 +
 
 +
To see the protection bits associated with a file, use the LIST command. The protection field is displayed with set (on) bits shown by their letters and clear (off) bits shown by hyphens. For instance, a file that is readable, writable and deletable, will have ----rw-d in the protection field.
 +
 
 +
To specify the entire protection field at once, simply give the letters of the bits you want set as the FLAGS argument, without any other keywords. The named bits will be set, and all the others will be 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 letter(s) of the bit(s) to set or clear, respectively, and only those bits will be changed. Don't put a 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 letter(s). You cannot both set and clear bits in the same command.
 +
 
 +
The options are:
 +
 
 +
The options are:
 +
{| class="wikitable"
 +
| ALL || Change the protection bits of all subdirectories and their files.
 
|-
 
|-
| w || The file can be written to (altered).
+
| QUIET || Do not display progress report messages. The local shell variable _Verbosity with a negative value has the same effect.
 
|-
 
|-
| e || The file is executable (a program).
+
| USER || Only modify the 'user' protection bits (default).
 +
|-
 +
| GROUP || Only modify the 'group' protection bits
 +
|-
 +
| OTHER || Only modify the 'other' protection bits.
 +
|-
 +
| CLONE || Change the 'group' and/or 'other' protection bits to the same value as the 'user' protection bits. Requires at least one of the USER and GROUP options, and no protection bits specified.
 +
|-
 +
| CLEAR || Clear all protection bits.
 +
|-
 +
| FILES || Only change the protection bits of the files found.
 
|-
 
|-
| d || The file or directory can be deleted. (Files within a delete-protected directory can still be deleted.)
+
| DIRS || Only change the protection bits of the directories found.
 
|}
 
|}
  
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.
+
{{Note|The FILES and DIRS options work together: if you use FILES and omit DIRS, then only the files will be affected and the other way round. If none of FILES and DIRS is used, all files and directories will have their protection bits changed.}}
  
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.
+
{{Note|Since version 51.9 PROTECT doesnt allow to set the h, s, and p bits of directories. For files,
 
+
* Setting the h bit is only possible if the s bit is not set and the p, e and r bits are set.
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.
+
* Setting the p bit is only possible if the s bit is not set and the e and r bits are set.
 
+
* Setting the s bit is only possible when the r bit is set.
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.
+
* Setting the e bit is only possible when the r bit is set.
 +
* Setting the GROUP e bit is only possible when the GROUP r bit is set.
 +
* Setting the OTHER e bit is only possible when the OTHER r bit is set.}}
  
 
; Example 1:
 
; Example 1:
 
  1> PROTECT DF0:Memo +rw
 
  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.
+
sets only the protection bits r (readable) and w (writable) to the file Memo on DF0:. No other protection bits are changed.
  
 
; Example 2:
 
; Example 2:
Line 2,656: Line 3,327:
  
 
The protection status of Paint becomes "----rwed".
 
The protection status of Paint becomes "----rwed".
 +
 +
; Example 4:
 +
1> PROTECT Work:Write CLONE GROUP OTHER
 +
 +
The group and other protection bits of Write become a copy of the user protection bits.
 +
 +
; Example 5:
 +
1> PROTECT Work:Save CLEAR
 +
 +
Clear all the protection bits of Save.
 +
 +
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LIST|LIST]]
  
 
== PUSHCD ==
 
== PUSHCD ==
  
 
Saves the current directory on a stack and optionally changes it.
 
Saves the current directory on a stack and optionally changes it.
 +
 +
; Format
 +
: PUSHCD [<dir | pattern>]
 +
 +
; Template
 +
: DIR
 +
 +
; Location
 +
: Internal
  
 
== QUIT ==
 
== QUIT ==
Line 2,695: Line 3,388:
  
 
Reboots your Amiga.
 
Reboots your Amiga.
 +
 +
; Format
 +
: REBOOT [FAST=WARMREBOOT] [WAIT=<seconds>] [SYNC]
 +
 +
; Template
 +
: FAST=WARMREBOOT/S,WAIT/N/K,SYNC/S
 +
 +
; Location
 +
: C:
  
 
== RECORDER ==
 
== RECORDER ==
  
 
Captures console output and stores it in a file.
 
Captures console output and stores it in a file.
 +
 +
; Format
 +
: RECORDER [[TO] <file>] [APPEND] [OFF] [LINE] [SIZE <number>] [FLUSH]
 +
 +
; Template
 +
: TO,APPEND/S,OFF/S,LINE/S,SIZE/N/K,FLUSH/S
 +
 +
; Location
 +
: Internal
  
 
== RELABEL ==
 
== RELABEL ==
Line 2,777: Line 3,488:
  
 
; Format
 
; Format
: REQUESTCHOICE >TITLE> <body> {<gadgets>} [PUBSCREEN <public screen name>]
+
: REQUESTCHOICE <title text> <body text> {<gadgets>} [TYPE <type>] [TO <file>] [PUBSCREEN <public screen name>] [TIMEOUTSECS <seconds>] [CHARSET <character set>] [INACTIVE]
  
 
; Template
 
; Template
: TITLE/A,BODY/A,GADGETS/A/M,PUBSCREEN/K
+
: TITLE/A,BODY/A,GADGETS/A/M,TYPE/K,TO/K,PUBSCREEN/K,TIMEOUTSECS/K/N,CHARSET/K,INACTIVE/S
  
 
; Location
 
; Location
 
: C:
 
: C:
  
The <title> argument specifies the title of the requester.
+
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 BODY argument specifies the text of the requester. Line feeds can be embedded using *N. For other formatting options see the requester class autodoc: [http://wiki.amigaos.net/amiga/autodocs/requester_cl.doc.txt requester_cl.doc]
  
The <gadgets> argument specifies the text for the different gadgets. The gadget labels are separated with spaces.
+
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 TYPE argument specifies the type of requester to display. Possible types are INFO, QUESTION, WARNING, ERROR, and INSERTDISK. If not specified, INFO is assumed when a single gadget is specified, QUESTION otherwise.
 +
 
 +
The TO argument specifies an output file where the result is written to.
 +
 
 +
The TIMEOUTSECS argument specifies the maximum number of seconds to display the requester before its closed and the result -1 is returned. Specifying 0 timeout seconds means no timeout.
  
 
The PUBSCREEN argument allows the requester to open its window on a public screen.
 
The PUBSCREEN argument allows the requester to open its window on a public screen.
 +
 +
The CHARSET argument allows to specify the character set of the strings given in the BODY and GADGETS arguments. The TITLE argument is always displayed in the character set of the screen font.
 +
 +
The INACTIVE argument specifies that the requester window should not be activated when opened.
 +
 +
The number of the selected gadget is printed as a result to the console or written to the output file. The gadgets are numbered from left to right as 1, 2, 3, ..., 0. The special result -1 is printed when the TYPE argument was INSERTDISK and a disk was inserted. 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, 0 otherwise.
  
 
; Example:
 
; Example:
  
  1> RequestChoice >ENV:rcnum "New Title" "This is my requester*nSelect a gadget" "OK" "Maybe" "Cancel"
+
  1> RequestChoice >ENV:rcnum "New Title" "This is my requester.*nSelect a gadget." "_OK" "_Maybe" "_Cancel"
 +
 
 +
The local Shell variable ''rcnum'' contains 1, 2, or 0 (respectively) after a gadget is selected. The script can use this value to control its later execution.
  
 
[[File:DosFig6-1.png|center|frame|Sample RequestChoice Requester]]
 
[[File:DosFig6-1.png|center|frame|Sample RequestChoice Requester]]
Line 2,808: Line 3,531:
  
 
; Format
 
; 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>]
+
: 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
 
; Template
Line 2,848: Line 3,571:
  
 
Allows AmigaDOS and ARexx scripts to use custom string requesters.
 
Allows AmigaDOS and ARexx scripts to use custom string requesters.
 +
 +
; Format
 +
: REQUESTSTRING <title text> <body text> [POSITIVE <OK gadget text>] [NEGATIVE <Cancel gadget text>] [DEFSTRING <default text>] [MAXLEN=<n>] [NOTEMPTY] [INVISIBLE] [TO <filename>] [PUBSCREEN <public screen name>] [CHARSET <character set>] [INACTIVE]
 +
 +
; Template
 +
: TITLE/A,BODY/A,POSITIVE/K,NEGATIVE/K,DEFSTRING/K,MAXLEN/K/N,NOTEMPTY/S,INVISIBLE/S,TO/K,PUBSCREEN/K,CHARSET/K,INACTIVE/S
 +
 +
; Location
 +
: C:
 +
 +
The TITLE argument specifies the title of the requester.
 +
 +
The BODY argument specifies the text of the requester. Line feeds can be embedded using *N. For other formatting options see the requester class autodoc: [http://wiki.amigaos.net/amiga/autodocs/requester_cl.doc.txt requester_cl.doc]
 +
 +
The POSITIVE argument specifies the text for the OK gadget. Default is the localized "_OK" text.
 +
 +
The NEGATIVE argument specifies the text for the Cancel gadget. Default is the localized "_Cancel" text.
 +
 +
The DEFSTRING argument specifies the default text for the string gadget. Default is empty string.
 +
 +
The MAXLEN argument specifies the maximum length of the string. Default is 256. The length does not include the NULL termination, e.g. "A" is considered to have a length of 1. Negative and zero values are silently ignored and replaced with the default value.
 +
 +
The NOTEMPTY switch does not allow the user to enter an empty string.
 +
 +
The INVISIBLE switch specifies that the text in the string gadget should be displayed with '*' characters, e.g. for entering passwords that should not be visible to a person behind the user.
 +
 +
The TO argument specifies the file where to store the result string. If not specified, the string is written to the default output.
 +
 +
The PUBSCREEN argument specifies the name of the public screen where to open the requester window. If not specified, the current default public screen is used. The screen is brought to the front before opening the window if necessary, and to the back after closing the window if it was brought to the front before.
 +
 +
The CHARSET argument allows to specify the character set of the string given in the BODY, POSITIVE, NEGATIVE, and DEFSTRING arguments. The TITLE argument is always displayed in the character set of the screen font.
 +
 +
The INACTIVE argument specifies that the requester window should not be activated when opened.
 +
 +
RequestString will return with RETURN_FAIL (20) on any failure, with RETURN_WARN (5) if the user clicked the Cancel gadget (the result string is the provided default string in this case), and with RETURN_OK (0) otherwise. The result string (or the default string, if the user did cancel the requester) will be enclosed in quotation marks, then terminated with linefeed, and written to the file specified with the TO argument or the default output.
 +
 +
; Example:
 +
1> Set Title "Edit file comment"
 +
1> Set Body "Comment for MyFile:"
 +
1> Set Def "`List MyFile LFORMAT %c`"
 +
1> Set Note `RequestString "$Title" "$Body" DEFSTRING "$Def"`
 +
1> FileNote MyFile "$Note"
 +
 +
[[File:DosFig6-3.png|center|frame|Sample RequestString Requester]]
  
 
== RESIDENT ==
 
== RESIDENT ==
Line 2,909: Line 3,676:
 
restores the CD command to the system.
 
restores the CD command to the system.
  
See also: PROTECT, LIST.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#PROTECT|PROTECT]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LIST|LIST]]
  
 
== ROADSHOWCONTROL ==
 
== ROADSHOWCONTROL ==
  
 
Displays and changes the internal configuration options of the TCP/IP stack.
 
Displays and changes the internal configuration options of the TCP/IP stack.
 +
 +
; Format
 +
: ROADSHOWCONTROL [GET <option>] [SET <option>=<value>] [SAVE] [QUIET]
 +
 +
; Template
 +
: GET/K,SET/K/F,SAVE/S,QUIET/S
 +
 +
; Location
 +
: C:
  
 
== RUN ==
 
== RUN ==
Line 2,955: Line 3,733:
  
 
Launches an ARexx program.
 
Launches an ARexx program.
 +
 +
; Format
 +
: RX <name> [<arguments>]
 +
 +
; Template
 +
: NAME,ARG/F
 +
 +
; Location
 +
: C:
 +
 +
RX launches an ARexx program. If the specified name includes an explicit path, only that directory is searched for the program; otherwise, the current directory and REXX: are checked for a program with the given name. The optional argument string is passed to the program.
 +
 +
In place of the name of an ARexx program to be launched you can also write a short list of ARexx statements which will be executed as a single line command. To do so, enclose the statements in double quotes.
 +
 +
The RX program will try to start the ARexx resident process before it will attempt to launch a program.
 +
 +
You can also use the RX program from Workbench. Make it the default tool of an ARexx program, then double-click on the icon. The following tool types are supported:
 +
 +
{| class="wikitable"
 +
| CONSOLE || Overrides the default output console window specification, "CON://640/100/WAIT/RX Output".
 +
|-
 +
| CMD || Use the command given in the tool type text rather than attempt to execute the ARexx program the icon is attached to.
 +
|-
 +
| STARTUP || If present, try to run a different program before the ARexx program is launched. If this is omitted, "RexxMast" will be launched.
 +
|}
 +
 +
; Example 1:
 +
Launch the ARexx command "script.rexx" with argument "Names.txt".
 +
 +
1> RX script.rexx Names.txt
 +
 +
; Example 2:
 +
Launch the ARexx command "script.rexx". Note that the command name suffix is omitted and defaults to ".rexx"
 +
 +
1> RX script
 +
 +
; Example 3:
 +
Evaluate an ARexx expression.
 +
 +
1> RX "say 17 / 23"
  
 
== RXC ==
 
== RXC ==
  
 
Closes the ARexx resident process.
 
Closes the ARexx resident process.
 +
 +
; Format
 +
: RXC
 +
 +
; Template
 +
: (none)
 +
 +
; Location
 +
: C:
 +
 +
RXC closes the ARexx resident process. The "REXX" public port is withdrawn immediately and the resident process exits as soon as the last ARexx program finishes. No new programs can be launched after a close request.
  
 
== RXLIB ==
 
== RXLIB ==
  
 
Manages and lists ARexx function libraries and hosts.
 
Manages and lists ARexx function libraries and hosts.
 +
 +
; Format
 +
: RXLIB <name> [<priority> [<offset> [<version>]]]
 +
 +
; Template
 +
: NAME,PRIORITY,OFFSET/N,VERSION/N
 +
 +
; Location
 +
: C:
 +
 +
RXLIB manages function libraries and hosts, so that they can be called from ARexx, and it can also be used to list which libraries are currently defined.
 +
 +
To add a new library, specify its name, priority and offset value. The priority must be in the range -100.100. For your library to be invoked before the resident process has a look at a command, make sure that the priority is greater than -60. The offset value is the actual library vector offset and should be documented with each library. The last parameter, the required library version, can usually be omitted in which case 0 will be used (any library version is acceptable).
 +
 +
{{Note|title=Note|text=Do not get the library offset value wrong or ARexx will crash when the next attempt is made to call a function library!}}
 +
 +
To add a new host, specify its name and priority, but omit the offset value and version number. Note that at the time the host is added no test is performed to verify that a public message port of that name exists.
 +
 +
{{Note|title=Note|text=You cannot directly replace an existing function library or host with a new entry. The old entry needs to be removed before the new entry can be added.}}
 +
 +
To remove a library or host, specify its name and omit the priority, offset, and version parameters.
 +
 +
To list all function libraries and hosts, omit the library name, priority, offset, and version parameters.
 +
 +
; Example 1:
 +
Add "rexxsupport.library":
 +
1> RXLIB rexxsupport.library 0 -30
 +
 +
; Example 2:
 +
Show all active libraries and hosts:
 +
1> RXLIB
 +
rexxsupport.library (library)
 +
REXX (host)
 +
 +
; Example 3:
 +
Remove "rexxsupport.library":
 +
1> RXLIB rexxsupport.library
 +
 +
; Example 4:
 +
Add a new host by the name of "MORE":
 +
1> RXLIB MORE -1
  
 
== RXSET ==
 
== RXSET ==
  
Manages or lists the Clip List.
+
Manage or list the Clip List.
 +
 
 +
; Format
 +
: RXSET [<name> [[=] <value>]]
 +
 
 +
; Template
 +
: NAME,VALUE/F
 +
 
 +
; Location
 +
: C:
 +
 
 +
RXSET adds a name-value pair to the Clip List. Name strings are assumed to be in mixed case. If a pair with the same name already exists, its value is replaced with the current string. If a name without a value string is given, the entry is removed from the Clip List. If RXSET is invoked without arguments, it will list all name-value pairs in the Clip List.
 +
 
 +
{{Note|title=Note|text=The original RXSET command would preserve the exact number of blank spaces in the 'value' string. This is not the case with this new version of the command, which will always put exactly one blank space between the words in the 'value' string. If you need an exact number of blank spaces, you should put them into double quotes.}}
 +
 
 +
; Example 1:
 +
Add the name-value pair "answer=42" to the Clip List (more than one syntax is supported; all three examples are equivalent):
 +
1> RXSET answer=42
 +
1> RXSET answer = 42
 +
1> RXSET answer 42
 +
 
 +
; Example 2:
 +
Show the current Clip List contents:
 +
1> RXSET
 +
answer=42
  
 
== SEARCH ==
 
== SEARCH ==
Line 2,973: Line 3,867:
  
 
; Format
 
; Format
: SEARCH [FROM] {<name | pattern>} [SEARCH] <string | pattern> [ALL] [NONUM] [QUIET] [QUICK] [FILE] [PATTERN]
+
: SEARCH [FROM] <name|pattern> [SEARCH|NAME] <string|pattern>
 +
: [ALL] [NONUM] [QUIET] [QUICK] [FILE] [PATTERN] [CASE]
  
 
; Template
 
; Template
: FROM/M,SEARCH/A,ALL/S,NONUM/S,QUIET/S,QUICK/S,FILE/S,PATTERN/S
+
: FROM/M,SEARCH/A,ALL/S,NONUM/S,QUIET/S,QUICK/S,FILE/S,PATTERN/S,CASE/S
  
 
; Location
 
; Location
 
: C:
 
: C:
  
SEARCH looks through all the files in the FROM directory for the string given in the SEARCH string. (The FROM and SEARCH keywords are optional.) If the ALL switch is given, SEARCH also looks through all the subdirectories of the FROM directory. SEARCH displays the name of the file being searched and any line that contains the text sought. You must place quotation marks around any search text containing a space. The search is not case-sensitive.
+
SEARCH looks through all the files in the FROM directory for the given SEARCH string. (The FROM and SEARCH keywords are optional.) If the ALL switch is given, SEARCH also looks through all the subdirectories of the FROM directory. SEARCH displays the name of the file being searched and any line that contains the text sought. You must place quotation marks around any search text containing a space. The search is case-indifferent (capitalization is ignored) unless the CASE switch was specified.
  
The options are:
+
The options are as follows:
 
{| class="wikitable"
 
{| class="wikitable"
 
| NONUM || Line numbers are not printed with the strings.
 
| NONUM || Line numbers are not printed with the strings.
 
|-
 
|-
| QUIET || Searches quietly; file names being searched are not displayed.
+
| QUIET || Searches quietly; filenames being searched are not displayed. The local shell variable _Verbosity with a negative value has the same effect.
 
|-
 
|-
| QUICK || Use a more compact output format.
+
| QUICK || Uses a more compact output format.
 
|-
 
|-
 
| FILE || Looks for a file by the specified name, rather than for a string in the file.
 
| FILE || Looks for a file by the specified name, rather than for a string in the file.
 
|-
 
|-
| PATTERN || Uses pattern matching to search for the string.
+
| PATTERN || Uses pattern matching in the search.
 +
|-
 +
| CASE || Uses case sensitive string comparison in the search.
 
|}
 
|}
  
SEARCH leaves a 0 in the condition flag if the object is found, and a 5 (WARN) otherwise. To abandon the search of the current file and continue to the next file, if any, press Ctrl+D. SEARCH is aborted when Ctrl+C is pressed.
+
SEARCH leaves a 0 in the condition flag if the object is found, and a 5 (WARN) otherwise. This makes it useful in scripts. To abandon the search of the current file and continue to the next file, if any, type Ctrl-D. SEARCH is aborted when a Ctrl-C is typed.
  
; Examples
+
; Example 1
  1> SEARCH DEVS: DOSDrivers globvec
+
  1> Search DEVS: alternative
DOSDrivers (dir)
+
      Keymaps (dir)
PIPE..
+
      Printers (dir)
  6 GlobVec =-1
+
    clipboard.device..
  PIPE.info
+
    MountList..
 +
   
 +
    14 \* This is an example of an alternative type of non-filing device mount.
 +
    narrator.device..
 +
    parallel.device..
 +
    printer.device..
 +
    serial.device..
 +
    system-configuration..
 +
 
 +
searches through the DEVS: directory for the word alternative. It is found on line 14 of the MountList file.
 +
 
 +
; Example 2
 +
1> SEARCH Universe: "Intelligent life" ALL
 +
 
 +
searches for Intelligent life (or intelligent life) in every file on the volume Universe:.
 +
 
 +
; Example 3
 +
  1> Work:#?.source SEARCH Progtest.c?? FILE PATTERN
  
1> SEARCH utilities #?.info FILE
+
locates all Progtest.c files with a two-character suffix in directories ending in .source in the Work volume.
Workbench:Utilities/Clock.info
+
Workbench:Utilities/MultiView.info
+
  
 
== SET ==
 
== SET ==
Line 3,040: Line 3,952:
 
  This process launched from icon
 
  This process launched from icon
  
See also: GET, UNSET
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#GET|GET]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#UNSET|UNSET]]
  
 
== SETCLOCK ==
 
== SETCLOCK ==
Line 3,069: Line 3,983:
 
Some Amiga models do not have battery backed-up clocks unless an expansion unit has been installed.
 
Some Amiga models do not have battery backed-up clocks unless an expansion unit has been installed.
  
See also: DATE
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#DATE|DATE]]
  
 
== SETDATE ==
 
== SETDATE ==
Line 3,076: Line 3,991:
  
 
; Format
 
; Format
: SETDATE <file | pattern> [<weekday>] [<date>] [<time>] [ALL]
+
: SETDATE <file|pattern> [<date>] [<time>] [ALL] [QUIET] [FILES] [DIRS]
  
 
; Template
 
; Template
: FILE/A,WEEKDAY,DATE,TIME,ALL/S
+
: FILE/A,DATE,TIME,ALL/S,QUIET/S,FILES/S,DIRS/S
  
 
; Location
 
; Location
 
: C:
 
: C:
  
SETDATE changes the timestamp, the date and time of the creation or last change, of a file or directory. SETDATE <file> changes the date/time of the file to the current system date/time. SETDATE ALL changes the date and time of all the files and subdirectories matching the pattern entered.
+
SETDATE changes the timestamp (date and time of creation or last change) of a file or directory. SETDATE <file> changes the date/time of the file to the current system date/time. SETDATE does not affect the software or hardware clocks.
  
The system clocks are not affected by SETDATE.
+
The output of the DATE command may be used as input to SETDATE.
  
You can use output from the DATE command as input to SETDATE.
+
The options are:
 +
{| class="wikitable"
 +
| ALL || Change the dates of all subdirectories and their files.
 +
|-
 +
| QUIET || If the QUIET option is given, screen output is suppressed. The local shell variable _Verbosity with a negative value has the same effect.
 +
|-
 +
| FILES || Only change the dates of the files found.
 +
|-
 +
| DIRS || Only change the dates of the directories found.
 +
|}
 +
 
 +
{{Note|The FILES and DIRS options work together: if you use FILES and omit DIRS, then only the files will be affected and the other way round. If none of FILES and DIRS is used, all files and directories will have their dates changed.}}
  
 
; Example 1:
 
; Example 1:
Line 3,096: Line 4,022:
  
 
; Example 2:
 
; Example 2:
  1> SETDATE TestFile 01-04-91 13:45:32
+
  1> SETDATE TestFile 16-09-89 15:25:52
  
Changes the date and time associated with TestFile to April 1, 1991, 1:45 p.m.
+
change the date and time associated with TestFile to September 16, 1989, 3:25 p.m.
  
See also: DATE
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#DATE|DATE]]
  
 
== SETENV ==
 
== SETENV ==
Line 3,138: Line 4,065:
 
  C:ED
 
  C:ED
  
See also: GETENV, UNSETENV
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#GETENV|GETENV]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#UNSETENV|UNSETENV]]
  
 
== SETFONT ==
 
== SETFONT ==
Line 3,145: Line 4,074:
  
 
; Format
 
; Format
: SETFONT <font> <size> [SCALE] [PROP] [ITALIC] [BOLD] [UNDERLINE]
+
: SETFONT <font> <size> [SCALE] [PROP] [ITALIC] [BOLD] [UNDERLINE] [CHARSET]
 
+
 
; Template
 
; Template
: NAME/A,SIZE/N/A,SCALE/S,PROP/S,ITALIC/S,BOLD/S,UNDERLINE/S
+
: NAME/A,SIZE/A,SCALE/S,PROP/S,ITALIC/S,BOLD/S,UNDERLINE/S,CHARSET/K
  
 
; Location
 
; Location
 
: C:
 
: C:
  
SETFONT lets you change the font used in a particular Shell window, overriding the System Default Text setting specified in the Font editor. SETFONT is only effective in the window in which it is invoked.
+
SETFONT lets you change the font used in a particular Shell window, overriding the System Default Font setting specified in the [[AmigaOS_Manual:_Workbench_Preferences#Font_Editor|Font preferences editor]]. SETFONT is only effective in the window in which it is invoked.
  
You must specify both a font name and a size when using the SETFONT command. The other options are:
+
You must specify both a font name and a size when using the SETFONT command.
 +
 
 +
Invoking SETFONT will clear the Shell window of its current contents and display a new prompt, in the new font, at the top of the window.
 +
 
 +
The other options are:
 
{| class="wikitable"
 
{| class="wikitable"
 
| SCALE || Enables bitmap font scaling.
 
| SCALE || Enables bitmap font scaling.
Line 3,161: Line 4,093:
 
| PROP || Allows proportional fonts.
 
| PROP || Allows proportional fonts.
 
|-
 
|-
| ITALIC || The font is italic.
+
| ITALIC || The font will be italic.
 
|-
 
|-
| BOLD || The font is boldface.
+
| BOLD || The font will be boldface.
 
|-
 
|-
| UNDERLINE || The font is underlined.
+
| UNDERLINE || The font will be underlined.
 +
|-
 +
| CHARSET || The font will be in the specified charset, not in the current default charset.
 
|}
 
|}
 
Invoking SETFONT clears the Shell window of its current contents and displays a new prompt, in the new font, at the top of the window. Using proportional fonts in a Shell window is not recommended because the variable character spacing prevents columns of information from lining up and makes editing the command line difficult.
 
  
 
; Example:
 
; Example:
  1> SETFONT topaz 11 BOLD UNDERLINE
+
  1> SETFONT Fixed 13 BOLD UNDERLINE CHARSET ISO-8859-7
  
The Shell window clears and the new prompt is in 11 point Topaz, underlined and boldface.
+
The Shell window will clear, and the new prompt will be in 13 pixels Fixed.font, underlined and boldface, with greek glyphs for the characters above 0xA0.
  
 
== SETFONTCHARSET ==
 
== SETFONTCHARSET ==
  
 
Adds charset tag and version string to a FontContentsHeader file.
 
Adds charset tag and version string to a FontContentsHeader file.
 +
 +
; Format
 +
: SETFONTCHARSET <sourcefontfile> <charset> [VERSTRING]
 +
 +
; Template
 +
: BITMAPFONTFILENAME/A,CHARSET/A,VERSTRING/K
 +
 +
; Location
 +
: C:
  
 
== SETKEYBOARD ==
 
== SETKEYBOARD ==
  
Sets the keymap for the Shell.
+
Changes the keymap used by the current Amiga console.
  
 
; Format
 
; Format
: SETKEYBOARD <keymap name>
+
: SETKEYBOARD <keymap> [CHARSET]
  
 
; Template
 
; Template
: KEYMAP/A
+
: KEYMAP/A,CHARSET/K
  
 
; Location
 
; Location
 
: C:
 
: C:
  
SETKEYBOARD specifies the keymap used by the current Shell. The available files are listed below:
+
SETKEYBOARD specifies the keymap used by the Amiga for the current console. The keymap file must be present in KEYMAPS: for SETKEYBOARD to find it.
 +
 
 +
The other options are:
  
 
{| class="wikitable"
 
{| class="wikitable"
! Keymap !! Keyboard
 
 
|-
 
|-
| cdn || Canadian Français
+
| CHARSET || The keymap will be adjusted to the specified charset, not to the current default charset. You should only use this option when you also selected a different font charset with the [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SETFONT|SETFONT]] command. The adjustment does e.g. include the deadkey combinations which otherwise would produce confusing results.
|-
+
| ch1 || Suisse
+
|-
+
| ch2 || Schweiz
+
|-
+
| d || Deutsch
+
|-
+
| dk || Dansk
+
|-
+
| e || Español
+
|-
+
| f || Français
+
|-
+
| gb || British
+
|-
+
| i || Italiana
+
|-
+
| n || Norsk
+
|-
+
| po || Português
+
|-
+
| s || Svenskt
+
|-
+
| usa || American
+
|-
+
| usa2 || Dvorak
+
 
|}
 
|}
  
To specify the same permanent keymap, use the Preferences Input editor to save your choice.
+
; Example 1:
 
+
; Example:
+
  
 
To change to a French Canadian keymap, enter:
 
To change to a French Canadian keymap, enter:
  
  1> SETKEYBOARD cdn
+
  1> SETKEYBOARD cdn_f
  
The keymap file must be in the KEYMAPS: directory for SETKEYBOARD to find it.
+
; Example 2:
 +
 
 +
To switch the current console to ISO-8859-15 charset and german keymap, type:
 +
 
 +
1> SETFONT topaz 8 CHARSET ISO-8859-15
 +
1> SETKEYBOARD d_ISO-8859-15 CHARSET ISO-8859-15
  
 
== SHOWNETSTATUS ==
 
== SHOWNETSTATUS ==
  
 
Displays various information about the status of the network configuration.
 
Displays various information about the status of the network configuration.
 +
 +
; Format
 +
: SHOWNETSTATUS [INTERFACE=<itf>[,<itf>...]] [INTERFACES] [ARPCACHE=ARP] [ROUTES] [DNS=DOMAINNAMESERVERS] [ICMP] [IGMP] [IP] [MB=MEMORY] [MR=MULTICASTROUTING] [RT=ROUTING] [TCP] [UDP] [TCPSOCKETS] [UDPSOCKETS] [NAMES] [ALL] [REPEAT] [QUIET]
 +
 +
; Template
 +
: INTERFACE/M,INTERFACES/S,ARPCACHE=ARP/S,ROUTES/S,DNS=DOMAINNAMESERVERS/S,ICMP/S,IGMP/S,IP/S,MB=MEMORY/S,MR=MULTICASTROUTING/S,RT=ROUTING/S,TCP/S,UDP/S,TCPSOCKETS/S,UDPSOCKETS/S,NAMES/S,ALL/S,REPEAT/S,QUIET/S
 +
 +
; Location
 +
: C:
  
 
== SKIP ==
 
== SKIP ==
Line 3,288: Line 4,216:
 
  Document is not in this directory.
 
  Document is not in this directory.
  
See also: EXECUTE, LAB. For more examples using the SKIP command, see Chapter 8.
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LAB|LAB]]
 +
 
 +
== SMARTCTL ==
 +
 
 +
Control and monitor SMART disks.
 +
 
 +
; Format
 +
: SMARTCTL [<options>] <device>
 +
 
 +
; Template
 +
: LABEL,BACK/S
 +
 
 +
; Location
 +
: C:
  
 
== SORT ==
 
== SORT ==
Line 3,315: Line 4,258:
  
 
For more examples using the SORT command, see Chapter 8.
 
For more examples using the SORT command, see Chapter 8.
 +
 +
== SOUNDPLAYER ==
 +
 +
Plays a sound sample.
 +
 +
; Format
 +
: SOUNDPLAYER [VERBOSE] [QUIET] [R | RATE | SAMPLERATE <sample rate>] [<sample file>] [VOL | VOLUME <volume>]
 +
 +
; Template
 +
: V=VERBOSE/S,Q=QUIET/S,SR=RATE=SAMPLERATE/K/N,FROM/M,VOL=VOLUME/K/N
 +
 +
; Location
 +
: C:
  
 
== STACK ==
 
== STACK ==
Line 3,373: Line 4,329:
  
 
Interchanges the current directory and a stacked directory.
 
Interchanges the current directory and a stacked directory.
 +
 +
; Format
 +
: SWAPCD [<dir | pattern>] [LEVEL <number>]
 +
 +
; Template
 +
: DIR,LEVEL/N
 +
 +
; Location
 +
: Internal
  
 
== TCC ==
 
== TCC ==
  
 
Closes the ARexx tracing console window.
 
Closes the ARexx tracing console window.
 +
 +
; Format
 +
: TCC
 +
 +
; Template
 +
: (none)
 +
 +
; Location
 +
: C:
 +
 +
TCC closes the global ARexx tracing console as soon as all active programs are no longer using it. All read requests queued to the console must be satisfied before it can be closed.
  
 
== TCO ==
 
== TCO ==
Line 3,382: Line 4,358:
 
Opens the ARexx tracing console window.
 
Opens the ARexx tracing console window.
  
== TCP-HANDLER ==
+
; Format
 +
: TCO
 +
 
 +
; Template
 +
: (none)
 +
 
 +
; Location
 +
: C:
 +
 
 +
TCO opens the global ARexx tracing console. The tracing output from all active ARexx programs is diverted automatically to the new console. The console window can be moved and resized by the user and can be closed with the TCC command.
 +
 
 +
; Example:
 +
1> TCO
  
Access network resources through AmigaDOS.
+
[[File:DosFig6-4.png|center|frame|Sample ARexx tracing console]]
  
 
== TCPDUMP ==
 
== TCPDUMP ==
  
 
Dumps traffic on a network.
 
Dumps traffic on a network.
 +
 +
; Format
 +
: TCPDUMP [-aAdDeflLnNOpqRStuUvxX] [-c <count>] [-C <file_size>] [-E <algo:secret>] [-F <file>] [-i <interface>] [-r <file>] [-s <snaplen>] [-T <type>] [-w <file>] [-y <datalinktype>] [<expression>]
 +
 +
; Template
 +
: -a,-A,-d,-D,-e,-f,-l,-L,-n,-N,-O,-p,-q,-R,-S,-t,-u,-U,-v,-x,-X,-c,-C,-E,-F,-i,-r,-s,-T,-w,-y
 +
 +
; Location
 +
: C:
  
 
== TE ==
 
== TE ==
  
 
Clears the ARexx global tracing flag.
 
Clears the ARexx global tracing flag.
 +
 +
; Format
 +
: TE
 +
 +
; Template
 +
: (none)
 +
 +
; Location
 +
: C:
 +
 +
TE clears the global ARexx tracing flag, which forces the tracing mode to OFF for all active ARexx programs.
  
 
== TEE ==
 
== TEE ==
  
 
Sends data from the standard input to the standard output and prints it to the console.
 
Sends data from the standard input to the standard output and prints it to the console.
 +
 +
; Format
 +
: TEE [SIZE <number>] [LINE]
 +
 +
; Template
 +
: SIZE/N/K,LINE/S
 +
 +
; Location
 +
: Internal
  
 
== TRACEROUTE ==
 
== TRACEROUTE ==
  
 
Prints the network route packets.
 
Prints the network route packets.
 +
 +
; Format
 +
: TRACEROUTE [-d | DEBUG] [-m | MAXTTL <ttl>] [-n | NUMERIC] [-p | PORT <number>]
 +
: [-q | QUERIES <number>] [-r | DONTROUTE] [-s | SOURCE <address>]
 +
: [-t | TOS <type>] [-v | VERBOSE] [-w | WAIT <time>] [HOST <name>]
 +
: [PACKETSIZE <size>]
 +
 +
; Template
 +
: -d=DEBUG/S,-m=MAXTTL/K/N,-n=NUMERIC/S,-p=PORT/K/N,-q=QUERIES/K/N,-r=DONTROUTE/S,-s=SOURCE/K,-t=TOS/K/N,-v=VERBOSE/S,-w=WAIT/K/N,HOST/A,PACKETSIZE/N
 +
 +
; Location
 +
: C:
  
 
== TS ==
 
== TS ==
  
 
Starts ARexx's interactive tracing.
 
Starts ARexx's interactive tracing.
 +
 +
; Format
 +
: TS
 +
 +
; Template
 +
: (none)
 +
 +
; Location
 +
: C:
 +
 +
TS starts interactive ARexx tracing by setting the external trace flag, which forces all active ARexx programs into interactive tracing mode. Programs will start producing trace output and will pause after the next statement.
 +
 +
This command is useful for regaining control over programs caught in infinite loops or otherwise misbehaving. The trace flag remains set until cleared by the TE command, so subsequent program invocations will be executed in interactive tracing mode.
  
 
== TYPE ==
 
== TYPE ==
  
Displays the contents of a file.
+
Displays a text file.
  
 
; Format
 
; Format
: TYPE {<file | pattern>} [TO <name>] [OPT H | N] [HEX | NUMBER]
+
: TYPE {<file|pattern>} [TO <name>] [OPT H|N] [HEX] [NUMBER]
 +
: [AUTO] [TEXTONLY] [WIDTH <line width>] [BUF|BUFFER=<n>]
  
 
; Template
 
; Template
: FROM/A/M,TO/K,OPT/K,HEX/S,NUMBER/S
+
: FROM/A/M,TO/K,OPT/K,HEX/S,NUMBER/S,AUTO/S,TEXTONLY/S,WIDTH/K/N,BUF=BUFFER/K/N,MULTI/S
  
 
; Location
 
; Location
 
: C:
 
: C:
  
TYPE outputs the contents of the named file to the current window if no destination is given or to a specified output file. The TO keyword types information to a specified file. If more than one file name is specified, the file names are typed in sequence.
+
TYPE will output the contents of the named file to the current window, if no destination is given, or to a specified output file. If more than one filename is specified, and the TO keyword is not used, the filenames will be typed in sequence.
  
The OPT H and OPT N options are also available by the HEX and NUMBER keywords, respectively. However, the two options are mutually exclusive. The HEX option types the file as columns of hexadecimal numbers, with an ASCII character interpretation column. The NUMBER option numbers the lines as they are output.
+
The OPT H and OPT N options are also available by the HEX and NUMBER keywords, respectively. The HEX option causes the file to be typed as columns of hexadecimal numbers, with an ASCII character interpretation column. This is useful for analyzing object files. The NUMBER option will number the lines as they are output.
  
To pause output, press the Space bar. To resume output, press Backspace, Return, or Ctrl+X. To stop output, press Ctrl+C (***Break is displayed).
+
The AUTO option will make TYPE examine the first 256 characters of the file. If non-printable characters are found, TYPE will show the file as if the HEX option had been specified. Note that you can override the AUTO option with the HEX option, in which case you will always see the file(s) typed as columns of hexadecimal numbers.
  
; Example:
+
The WIDTH option controls how long each line in HEX mode form should become. For example, WIDTH=120 will try to print as much data in hexadecimal form as will fit into a line of up to 120 characters in total. The default is to print up to 61 characters per line.
1> TYPE S:Startup-sequence
+
  
The contents of the Startup-sequence file in the S: directory are displayed on the screen.
+
By default, TYPE will print the contents of the file as is read, including binary data (unprintable characters). To replace unprintable characters before output, use the TEXTONLY option. Any unprintable character will be replaced with '.'.
 +
 
 +
How much data is read and output at a time can be controlled with the BUFFER option. By default, a maximum of 2048 bytes will be read/written at a time.
 +
 
 +
To pause output, press the Space bar. To resume output, press Backspace, Return, or Ctrl-X. To stop output, press Ctrl-C (***BREAK is displayed).
 +
 
 +
The MULTI option was added in 54.1 and when specified, TYPE will also search multi-assignment paths for the file.
 +
 
 +
; Example:
 +
1> TYPE S:User-Startup
  
For more examples using TYPE, see Chapter 8.
+
The contents of the User-Startup file in the S: directory will be displayed on the screen.
  
 
== UNALIAS ==
 
== UNALIAS ==
Line 3,447: Line 4,498:
 
UNALIAS removes the named alias from the alias list. With no arguments, UNALIAS lists the current aliases.
 
UNALIAS removes the named alias from the alias list. With no arguments, UNALIAS lists the current aliases.
  
See also: ALIAS
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ALIAS|ALIAS]]
  
 
== UNSET ==
 
== UNSET ==
Line 3,464: Line 4,516:
 
UNSET removes the named local variable from the variable list for the current process. With no arguments, UNSET lists the current variables.
 
UNSET removes the named local variable from the variable list for the current process. With no arguments, UNSET lists the current variables.
  
See also: SET
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SET|SET]]
  
 
== UNSETENV ==
 
== UNSETENV ==
Line 3,481: Line 4,534:
 
UNSETENV removes the named global variable from the current variable list. With no arguments, UNSETENV lists the current variables.
 
UNSETENV removes the named global variable from the current variable list. With no arguments, UNSETENV lists the current variables.
  
See also: SETENV
+
;See also
 +
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SETENV|SETENV]]
  
 
== UPTIME ==
 
== UPTIME ==
  
 
Tells how long the system has been running.
 
Tells how long the system has been running.
 +
 +
; Format
 +
: UPTIME]
 +
 +
; Template
 +
: (none)
 +
 +
; Location
 +
: C:
 +
 +
UPTIME will find out how much time has passed since the Amiga was started and print that information. This will be given as the system start time followed by the total amount of time that has passed since (in days and seconds).
 +
 +
; Example:
 +
1> UPTIME
 +
System has been up since 02-Sep-03 09:42:05 (total uptime 00:14:08)
  
 
== VERSION ==
 
== VERSION ==
  
 
Finds software version and revision numbers.
 
Finds software version and revision numbers.
 +
 +
<span style="color: red;">NOTE: This command description is out of date.</span>
  
 
; Format
 
; Format
Line 3,548: Line 4,619:
 
== WAITFORPORT ==
 
== WAITFORPORT ==
  
Waits for public message port to appear.
+
Wait for a public message port to appear.
 +
 
 +
; Format
 +
: WAITFORPORT <name> [[TIMEOUT] <seconds>]
 +
 
 +
; Template
 +
: NAME/A,TIMEOUT/N
 +
 
 +
; Location
 +
: C:
 +
 
 +
WAITFORPORT waits 10 seconds for the specified message port to appear. A return code of 0 indicates that the port was found. A return code of 5 indicates that the application is not currently running or that the port does not exist.
 +
 
 +
{{Note|Port names are case sensitive.}}
 +
 
 +
You can choose how long WAITFORPORT will wait by using the TIMEOUT parameter.
 +
 
 +
To stop WAITFORPORT waiting, use the BREAK command or press Ctrl-C while the shell window is active that belongs to the WAITFORPORT command.
 +
 
 +
; Example 1:
 +
Wait for the message port "ED_1" to appear; wait for up to 10 seconds:
 +
 
 +
1> WAITFORPORT ED_1
 +
 
 +
; Example 2:
 +
Wait for 5 seconds for the message port "MyPort" to appear:
 +
 
 +
1> WAITFORPORT MyPort TIMEOUT 5
  
 
== WBINFO ==
 
== WBINFO ==
  
Opens Workbench information windows from a Shell.
+
Opens Workbench information windows from a shell.
 +
 
 +
; Format
 +
: WBINFO [<object> [<object>]...] [PUBSCREEN <public screen name>]
 +
 
 +
; Template
 +
: FILE=DRAWER=OBJECT/M/A,PUBSCREEN/K
 +
 
 +
; Location
 +
: C:
 +
 
 +
WBINFO opens Workbench information windows from a shell. For each given object (file, drawer, or disk) it will create a separate process which in turn requests Workbench to bring up the Icon information requester. Please note that WBINFO has to wait for the last requester to be satisfied before it can end.
 +
 
 +
The PUBSCREEN parameter allows to open the Icon information requesters on a named public screen.
 +
 
 +
; Example:
 +
1> WBINFO SYS:Utilities/Clock
 +
 
 +
[[File:DosFig6-5.png|center|frame|Icon Information Requester]]
  
 
== WBRUN ==
 
== WBRUN ==
  
 
Runs programs from Shell as if they were executed from the Workbench.
 
Runs programs from Shell as if they were executed from the Workbench.
 +
 +
; Format
 +
: WBRUN <program> [<arg1> [| <arg2>...]] [SHOW=ICONS | ALL]
 +
: [VIEWBY=ICON | NAME | DATE | SIZE | TYPE] [DELAY=<seconds>] [NOREQ]
 +
 +
; Template
 +
: PROG/A,ARGS/M,SHOW/K,VIEWBY/K,DELAY/N/K,NOREQ/S
 +
 +
; Location
 +
: C:
  
 
== WBSTARTUPCTRL ==
 
== WBSTARTUPCTRL ==
  
 
Manipulates the startup configuration of Workbench.
 
Manipulates the startup configuration of Workbench.
 +
 +
; Format
 +
: WBSTARTUPCTRL [<prefs file>] [ADD=<program>] [REMOVE=<program>] [QUIET]
 +
 +
; Template
 +
: PATH/K,ADD/K,REMOVE/K,QUIET
 +
 +
; Location
 +
: C:
  
 
== WHICH ==
 
== WHICH ==
Line 3,615: Line 4,750:
  
 
Builds a list of data types that datatypes.library can understand.
 
Builds a list of data types that datatypes.library can understand.
 +
 +
<span style="color: red;">NOTE: This command description is out of date.</span>
  
 
; Format
 
; Format
Line 3,653: Line 4,790:
  
 
Moves data between console windows and the Clipboard.
 
Moves data between console windows and the Clipboard.
 +
 +
<span style="color: red;">NOTE: This command description is out of date.</span>
  
 
; Format
 
; Format
Line 3,674: Line 4,813:
  
 
; Format
 
; Format
: IPREFS
+
: IPREFS [NEWMOUSE]
  
 
; Template
 
; Template
: (none)
+
: NEWMOUSE/S
  
 
; Location
 
; Location
 
: C:
 
: C:
  
IPREFS reads the individual system Preferences files and passes the information to the system. IPREFS is generally run in the Startup-sequence after the Preferences files are copied to ENV:. Each time a user selects Save or Use from within an editor, IPREFS is notified and passes the information to the system. If necessary, IPREFS resets Workbench to implement those changes. If any Shell, project, or tool windows are open, IPREFS displays a requester asking you to close them.
+
IPREFS reads the individual system Preferences files and passes the information to the system so that it can adapt accordingly. IPREFS is generally run in the Startup-sequence. Each time a user selects Save or Use from within an editor, IPREFS is notified and passes the information along to the system. If necessary, IPREFS will reset Workbench in order to implement the requested changes. If any project or tool windows are open, IPREFS will display a requester asking you to close any non-drawer windows.
 +
 
 +
If the NEWMOUSE command line option is specified, IPREFS generates NewMouse-style IECLASS_RAWKEY events for backwards compatibility to old applications that don't support standard AmigaOS mouse wheel events as introduced in Release 4.
 +
 
 +
== LOADMONDRVS ==
 +
 
 +
Starts the monitor drivers.
 +
 
 +
; Format
 +
: LOADMONDRVS [FROM=<path>] [EXCEPT=<file name>]
 +
 
 +
; Template
 +
: FROM/K,EXCEPT
 +
 
 +
; Location
 +
: C:
 +
 
 +
LOADMONDRVS starts the monitor drivers stored in the <path> directory. If the <path> argument is not given, drivers in the DEVS:Monitors directory will be started.
 +
 
 +
By default LOADMONDRVS starts all the drivers that it can find from the drivers' directory. To prevent LOADMONDRVS from starting a specific driver, use the EXCEPT parameter: <file name> is the name of the driver to be disabled.
 +
 
 +
; Example 1:
 +
1> LOADMONDRVS
 +
 
 +
starts all the monitor drives stored in the DEVS:Monitors directory.
 +
 
 +
; Example 2:
 +
1> LOADMONDRVS FROM="SYS:Storage/Monitors"
 +
 
 +
starts all the monitor drives stored in the SYS:Storage/Monitors directory.
 +
 
 +
; Example 3:
 +
1> LOADMONDRVS EXCEPT="VooDoo"
 +
 
 +
starts all the monitor drives stored in the DEVS:Monitors directory, except the VooDoo driver.
  
 
== SETPATCH ==
 
== SETPATCH ==
Line 3,689: Line 4,862:
  
 
; Format
 
; Format
: SETPATCH [QUIET] [NOCACHE] [REVERSE]
+
: SETPATCH [QUIET] [NOAGA] [NONSD] [PATCHCONFIGFILE=<NSDpatch file>]
 +
: [PATCHCONFIGLINE="PatchLine"] [PATCHINFO] [WAITFORVALIDATE]
 +
: [ADDCHIPRAM=<Size in MB>]
  
 
; Template
 
; Template
: QUIET/S,NOCACHE/S,REVERSE/S
+
: QUIET/S,NOAGA/S,NONSD/S,PATCHCONFIGFILE=PCF/K,PATCHCONFIGLINE=PCL/K,PATCHINFO=PI/S,WAITFORVALIDATE/S,ADDCHIPRAM/N/K
  
 
; Location
 
; Location
 
: C:
 
: C:
  
SETPATCH installs temporary modifications to the operating system. It must be run at the beginning of the Startup-sequence file. Updated versions of SETPATCH are made available when necessary as AmigaDOS development continues.
+
SETPATCH installs temporary modifications to the operating system. It must be executed at the beginning of the Startup-sequence file.
  
If QUIET is specified, no output is sent to the screen.
+
By default SETPATCH enables the AGA video modes when running on an Amiga Classic with AGA chipset and the chipset was not disabled in the early startup menu. If you don't want to enable the AGA video modes, specify the NOAGA argument on the command line. When running on non-classic platforms, SETPATCH will not enable the AGA video modes (this may have happened already before) and the NOAGA argument has no effect.
 +
 
 +
SETPATCH can patch devices that don't follow the NewStyleDevice (NSD) specification released by Amiga Inc. Patches will be applied according to the list in the Devs:NSDPatch.cfg file.
 +
 
 +
Use the NONSD argument if you don't want to install patches for devices that are not NSD compliant.
 +
 
 +
To use a device list other than Devs:NSDPatch.cfg, use the PATCHCONFIGFILE argument and specify the full name of your alternate file. It is also possible to apply a patch giving it as argument to SETPATCH after the PATCHCONFIGLINE keyword. Just specify a line with the same syntax as in the NSDpatch file. Note that a complete description of the patch format is located in the Devs:NSDPatch.cfg file.
 +
 
 +
To display the patches applied by SETPATCH use the PATCHINFO argument.
 +
 
 +
When a disk is validating (after a system crash for example) it can be annoying to boot the operating system while the filesystem is busy to fix the damaged partition. In this case, the boot process may be very slow. Use the WAITFORVALIDATE switch to ask SETPATCH to wait for the end of the validation process before proceeding. Doing so you are sure that you start the system with sane partitions. Note: Pressing Ctrl-C (when an input shell window is present) or both mouse buttons will abort waiting for disk validation.
 +
 
 +
The ADDCHIPRAM option can be used on non-classic machines for backwards compatibility to old broken programs which peek system structures which were always declared as private, to be used by the operating system only. It installs an old-style MemHeader in SysBase->MemList. Note: You don't need to activate this compatibility hack for programs which simply want to allocate some Chip RAM.
 +
 
 +
By default, SETPATCH displays the operating system version and copyright as well as the list of applied patches. But if the QUIET argument is specified or the local shell variable _Verbosity has a negative value, no output will be produced.
 +
 
 +
; Example 1:
 +
 
 +
Don't apply NSD patches and wait the end of the validation process.
 +
 
 +
1> SETPATCH NONSD WAITFORVALIDATE
 +
 
 +
; Example 2:
 +
 
 +
Applies only the patch on audio.device.
 +
 
 +
1> SETPATCH PATCHCONFIGLINE="DEVICE audio.device
 +
DEVICETYPE NSDEVTYPE_AUDIO VERSION 50 REVISION 5 ISNSD"
 +
 
 +
; Example 3:
  
NOCACHE prevents data caching from being activated on some 68030 and 68040 systems.
+
Adds a MemHeader with 2MB Chip RAM as backwards compatibility hack for broken applications and suppresses the normal output.
  
REVERSE stores patches in reverse order. This option is useful for CDTV developers only.
+
1> SETPATCH QUIET ADDCHIPRAM=2

Latest revision as of 04:26, 23 July 2018

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.

Contents

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

ADDAUDIOMODES

Manipulates the audio mode list.

Format
ADDAUDIOMODES [FILES <file | pattern>] [QUIET] [REMOVE] [DBLSCAN]
Template
FILES/M,QUIET/S,REFRESH/S,REMOVE/S,DBLSCAN/S
Location
C:

Audio modes supported by the Amiga's audio system (ahi.device) are stored in the DEVS:Audiomodes directory as audio mode description files. Once the ahi.device is initiated, it scans the directory and builds an internal audio mode list based on the description files stored in the Audiomodes directory. The constructed audio mode list exists in RAM and can be manipulated by the ADDAUDIOMODES command.

The internal audio mode list can be cleared, new modes can be added to the list, or the original list can be restored. Note that any changes made to the audio mode list with the ADDAUDIOMODES command are not permanent.

The FILES parameter is used for adding audio modes to the list. The FILES parameter supplies the name or names of the audio mode description files which should be used for adding the new audio modes.

The REMOVE option will remove all audio modes from the internal audio mode list, while the REFRESH option restores the original audio modes by forcing the ahi.device to rebuild the internal audio mode list.

The DBLSCAN option does not have any effect on the audio mode list. Instead it will open and then immediately close a double-scan screen. On the original Amiga hardware this will enable over 28 kHz sample playback frequencies.

If the QUIET option is supplied, ADDAUDIOMODES will not print any messages.

Example

Rebuild the audio mode list:

1> ADDAUDIOMODES REFRESH

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.

ADDNETINTERFACE

Makes network interfaces known to the protocol stack.

Format
ADDNETINTERFACE {<interface>} [QUIET] [TIMEOUT <n>]
Template
INTERFACE/M,QUIET/S,TIMEOUT/K/N
Location
C:

ADDNETINTERFACE starts the specified network interfaces, thus starting the connection. It accepts the following parameters:

INTERFACE/M The name of the interface to add; this can be a plain interface name, such as "Ariadne", or the fully qualified file name which contains the interface configuration information. The tool expects the name of the file in question (without the prefixed path) to become the name of the interface. For historic reasons interface names cannot be longer than 15 characters.

For your convenience, a wild card pattern can be specified in place of the file name to use.

If several interface names are specified, they will be sorted in alphabetical order before they are added. If the interface files have icons attached, you can use tool types such as "PRI=5" or "PRIORITY=5" to select the order in which the interfaces will be sorted. Higher priority entries will appear before lower priority entries. If the priorities for two entries is identical, then the interface names will be compared. If no priority is given, the value 0 will be used.

QUIET/S This option causes the program not to emit any error messages or progress reports. Also, if the program encounters an error it will flag this as failure code 5 which can be looked at using the "if warn" shell script command. If this option is not in effect, failure codes will be more severe and all sorts of progress information will be displayed.
TIMEOUT/K/N If you're going to use DHCP configuration for any of the interfaces, a default timeout value of 60 seconds will limit the time an interface can take to be configured. This parameter allows you to use a different timeout value. Note that due to how the configuration protocol works, the timeout cannot be shorter than ten seconds.

The 'AddNetInterface' command can be invoked from Workbench, too. It operates on the same configuration files with the same keywords, etc. To make it work, create an icon for your interface configuration file (it must be a project icon) and put 'AddNetInterface' into its default tool. Make sure that the project has enough stack space assigned (4000 bytes minimum), then double-click on the icon. If things should go wrong, you will see an error requester pop up, and no further initialization will be done. You can configure two options in the project file's tool types: QUIET and TIMEOUT. These are identical to the two parameters of the same name you could pass on the command line; they define whether the command should print any error messages (the default is to print them) and how long the command should wait for DHCP configuration to conclude (default is a timeout of 60 seconds).

Note
This command is similar to the Unix "ifconfig" command.
Note
The program makes two passes over the configuration files to be taken into account. In the first pass information is gathered on the interfaces to add, which is subsequently used to add those interfaces found. In the second pass interfaces are configured, setting their IP addresses, etc. If anything goes wrong in the first pass, processing will stop and no second pass will be done. If anything goes wrong in either the first or the second pass, that pass will not be completed.
CONFIGURATION FILES

Interfaces are configured through files stored in the "DEVS:NetInterfaces" or "SYS:Storage/NetInterfaces" directories. These are text files whose contents are described below.

Each line of the file must correspond to an option; if a line is introduced by a '#' or ';' character it will be ignored (so are empty lines). The following options are supported:

DEVICE/K Must be provided; the name of the SANA-II device driver. This should be the complete, fully qualified path to the driver. If no complete path is provided, the 'Devs:Networks' drawer will be checked. Thus, "DEVS:Networks/ariadne.device" is equivalent to "ariadne.device".
UNIT/K/N Unit number of the device driver to open. The default is to use unit 0.
IPTYPE/K/N You can use this parameter to override the packet type the stack uses when sending IP packets; default is 2048 (for Ethernet hardware).
ARPTYPE/K/N You can use this parameter to override the packet type the stack uses when sending ARP packets. Default is 2054; this parameter only works with Ethernet hardware and should not be changed.
IPREQUESTS/K/N The number of IP read requests to allocate and queue for the SANA-II device driver to use. The default value is 32, larger values can improve performance, especially with fast device drivers.
WRITEREQUESTS/K/N The number of IP write requests to allocate and queue for the SANA-II device driver to use. The default value is 32, larger values can improve performance, especially with fast device drivers.
ARPREQUESTS/K/N The number of ARP read requests to allocate and queue for the SANA-II device driver to use. The default value is 4.
DEBUG/K (possible parameters: YES or NO) You can enable debug output for this interface (don't worry, you can always disable it later) to help in tracking down configuration problems. At this time of writing, the debug mode will, if enabled, produce information on the progress of the DHCP configuration process.
POINTTOPOINT/K (possible parameters: YES or NO) This indicates that the device is used for point to point connections. The stack automatically figures out whether the SANA-II device driver is of the point to point type, so you should not need to specify this option.
MULTICAST/K (possible parameters: YES or NO) This tells the stack that this device can handle multicast enabled by default anyway).
DOWNGOESOFFLINE/K (possible parameters: YES or NO) This option is useful with point to point devices, like 'ppp.device'. When specified, bringing the interface 'down' (via the 'ConfigureNetInterface' program) or shutting down the stack will cause the associated SANA-II device driver to be switched offline (via the 'S2_OFFLINE' command).
REPORTOFFLINE/K (possible parameters: YES or NO) When a device is switched offline, you may want to know about it. This is helpful with SLIP/PPP connections which run over a serial link which accumulates costs while it is open. When the connection is broken and the device goes offline, you will receive a brief notification of what happened. However, if you tell the library itself to shut down, no notification that a device was switched offline will be shown.
REQUIRESINITDELAY/K (possible parameters: YES or NO) Some devices need a little time to settle after they have been opened or they will hickup and lose data after the first packet has been sent. The original 'Ariadne I' card is one such device. For these devices, the 'REQUIRESINITDELAY=YES' option will cause a delay of about a second before the first packet is sent.

This option defaults to YES.

COPYMODE/K (possible parameters: SLOW or FAST) This option is for chasing subtle bugs in the driver interface with cards like the original 'Ariadne I'. Cards like these do not support writing to the hardware transmit buffer in units other than 16 bits a piece. Default is 'SLOW', which is compatible with the Ariadne I. But if you're feeling adventurous, try the 'FAST' option (and don't complain if it doesn't work for you!).
FILTER/K (possible parameters: OFF, LOCAL, IPANDARP or EVERYTHING) This option enables the use of the Berkeley packet filter for this particular interface. Possible choices for the key are:

FILTER=OFF

Disables the filter.

FILTER=LOCAL

Enables filtering on all IP and ARP packets that are intended for this particular interface. Packets intended for other interfaces or hosts are ignored.

FILTER=IPANDARP

Enables filtering on all IP and ARP packets that happen to fly by this interface, no matter whether the packets are intended for it or not. This requires that the underlying network device driver is opened for exclusive access in so-called 'promiscuous' mode. This may not work if other clients (Envoy, ACS) need to keep the driver opened.

FILTER=EVERYTHING

Identical to FILTER=IPANDARP, but will also filter all other kinds of packets that may show up.

Default for this option is 'FILTER=LOCAL'. Note that by using this option you merely define what the filter mechanism can do and what it cannot do. The filter is not enabled when you add the interface.

HARDWAREADDRESS/K You can specify the hardware address (layer 2 address, MAC address) this interface should respond to when it is first added and configured. This usually works only once for each interface, which means that once an address has been chosen you have to stick with it until the system is rebooted. And it also means that the first program to configure the address will manage to make its choice stick.

The hardware address must be given as six bytes in hexadecimal notation, separated by colon characters, like this:

HARDWAREADDRESS=00:60:30:00:11:22

Take care, there are rules that apply to the choice of the hardware address, which means that you cannot simply pick a convenient number and get away with it. It is assumed that you will want to configure an IEEE 802.3 MAC address, which works for Ethernet hardware and is six bytes (48 bits) in size.

In addition to the purely static interface configuration information you can also tell the configuration program to do something about the interfaces once they have all been added. That's when the following configuration file parameters will be taken into account:

ADDRESS/K This configures the IP address of the interface. The parameter you supply should be an IP address in dotted-decimal notation ("192.168.0.1"). Don't pick a symbolic host name as the system may not yet be in a position to talk to name resolution server and translate the symbolic name.

In place of the IP address you can also specify "DHCP" (Dynamic Host Configuration Protocol). As the name suggests, this will start a configuration process involving the DHCP protocol which should eventually yield the right IP address for this host. Note that this configuration procedure only works for Ethernet hardware.

ALIAS/K/M In addition to the primary interface address you can assign several aliases to it. These must be specified in dotted-decimal notation ("192.168.0.1"). Alias addresses are added after the primary interface address has been configured.
STATE/K By default, interfaces whose addresses are configured will switch automatically to 'up' state, making it possible for the TCP/IP stack to use them for network I/O. You can override this by using the 'STATE=DOWN' switch. The alternatives 'online' (implies 'up', but tells the underlying network interface driver to go online first) and 'offline' (implies 'down' but tells the driver to go offline first) are available as well.
NETMASK/K This selects the subnet mask for the interface, which must be specified in dotted-decimal notation ("192.0.168.1").

In place of the subnet mask you can also specify "DHCP" (Dynamic Host Configuration Protocol). As the name suggests, this will start a configuration process involving the DHCP protocol which should eventually yield the right subnet mask for this host. Note that this configuration procedure only works for Ethernet hardware.

DESTINATION=DESTINATIONADDR/K The address of the point-to-point partner for this interface; must be specified in dotted-decimal notation ("192.168.0.1"). Only works for point-to-point connections, such as PPP.
METRIC/K/N This configures the interface route metric value. Default is 0.
MTU/K/N You can limit the maximum transmission size used by the TCP/IP stack to push data through the interface. The interface driver will have its own ideas about the maximum transmission size. You can therefore only suggest a smaller value than the driver's preferred hardware MTU size.
CONFIGURE/K (possible parameters: DHCP, AUTO or FASTAUTO) You can use DHCP configuration for this interface and protocol stack internals, namely the list of routers (and the default gateway) to use and the domain name servers. This option allows you to bring up the complete network configuration in one single step.

You can request that a particular IP address is assigned to this interface by the DHCP process by specifying CONFIGURE=DHCP and your choice of ADDRESS=xxx.xxx.xxx.xxx.

If your network has no DHCP server, you may choose CONFIGURE=AUTO to use automatic IPv4 address selection, based upon a protocol called ZeroConf. This protocol will select a currently unused address from a specially designated address range.

If you choose automatic configuration in a wireless network, you might want to use CONFIGURE=FASTAUTO instead of CONFIGURE=AUTO.

Note that only the CONFIGURE=DHCP option will attempt to set up a default route and a set of DNS servers for you to use. The alternatives of CONFIGURE=FASTAUTO and CONFIGURE=AUTO are restricted to selecting the network interface IPv4 addresses.

LEASE/K This is a complex option which can be used to request how long an IP address should be bound to an interface, via the DHCP protocol. Several combinations of options are possible. Here is a short list:

LEASE=300

LEASE=300seconds

This requests a lease of exactly 300 seconds, or five minutes.

LEASE=30min

This requests a lease of 30 minutes.

LEASE=2hours

This requests a lease of 2 hours.

LEASE=1day

This requests a lease of 1 day.

LEASE=4weeks

This requests a lease of 4 weeks.

LEASE=infinite

This requests that the IP address should be permanently bound.

Blank spaces between the numbers and the qualifiers are supported. The qualifiers are tested using substring matching, which means for example that "30 minutes" is the same as "30 min" and "30 m".

Note that the requested lease time may be ignored by the DHCP server. After all, it is just a suggestion and not an order.

ID/K This option works along with the CONFIGURE=DHCP process. It can be used to tell the DHCP server by which name the local host should be referred to. Some DHCP servers are on good terms with their local name resolution services and will add the name and the associated IP address to the local host database. The name you can supply here cannot be longer than 255 characters and must be at least 2 characters long. Keep it brief: not all DHCP servers have room for the whole 255 characters.
DHCPUNICAST/K Some DHCP servers may not be able to respond to requests for assigning IP addresses unless the responses are sent directly to the computer which sent the requests. In such cases you might want to use DHCPUNICAST=YES option.

Unsupported keywords in the configuration file (or typos) will be reported, along with the name of the file and the line number.

The name of the configuration file defines the name of the respective interface. Interface names must be unique, and the case of the names does not matter. For historic reasons interface names cannot be longer than 15 characters. Beyond this no restrictions on naming conventions apply.

DHCP PROTOCOL

A few words on DHCP (Dynamic Host Configuration Protocol). First, it only works for Ethernet hardware, so please don't try it with PPP or SLIP. Now it gets a bit technical. Unless you request an address to be permanently assigned, DHCP will assign addresses only for a limited period of time. This is called a 'lease'. Once an IP address has been assigned through DHCP, the lease will be repeatedly extended. The DHCP server may over time decide not to extend the lease or assign a new IP address to the interface. To stop the lease from getting extended over and over again, you must either change the interface's primary IP address or mark it 'down'. The library will make a brave attempt to get a DHCPRELEASE datagram out to notify the server that the previously allocated IP address is no longer in use. Don't count on it to work, though. First, the protocol stack might be going down so fast that it cannot get the datagram out. Second, when you mark an interface 'down' you will effectively pull it out of circulation, it will not send any further datagrams. Third, DHCP rides on UDP whose second name is 'unreliable datagram protocol', meaning that any datagram may get lost or corrupted and nobody will hear about it; this is rather hard on DHCP since the release message is sent only once. Don't worry. Unless you request permanent leases, the leases will eventually time out and the now unused IP address will finally return to the pool of addresses available for allocation.

Examples

Start the interface called "DSL" and run quietly.

1> AddNetInterface DSL QUIET

An example configuration file for the "Ariadne" interface, with some options commented out:

1> Type Devs:NetInterfaces/Ariadne
device=ariadne.device
unit=0
#iprequests=64
#writerequests=64
copymode=fast
#configure=dhcp
address=192.168.0.1
netmask=255.255.255.0
#alias=192.168.0.9
#hardwareaddress=00:60:30:00:11:22
#id=a3000ux
#debug=yes
#filter=everything

ADDNETROUTE

Adds message routing paths.

Format
ADDNETROUTE [QUIET] [DESTINATION=<IP>] [HOSTDESTINATION=<IP>] [NETDESTINATION=<IP>] [GATEWAY=<IP>] [DEFAULTGATEWAY=<IP>]
Template
QUIET/S,DST=DESTINATION/K,HOSTDST=HOSTDESTINATION/K,NETDST=NETDESTINATION/K,VIA=GATEWAY/K,DEFAULT=DEFAULTGATEWAY/K
Location
C:

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

ARP

Address resolution display control.

Format
ARP [-a|ALL] [-d|DELETE] [-s|SET] [HOSTNAME <name>] [ADDRESS <address>] [TEMP] [PUB|PUBLISH] [PRO|PROXY] [{-f|FILE} <file name>] [-n|NONAMES|NUMBERS]
Template
-a=ALL/S,-d=DELETE/S,-s=SET/S,HOSTNAME,ADDRESS,TEMP/S,PUB=PUBLISH/S,PRO=PROXY/S,-f=FILE/K,-n=NONAMES/S=NUMBERS/S
Location
C:

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

ASSIGN

Controls assignment of logical device names to files or directories.

Format
ASSIGN [<name>:{dir}] [FROM <file name>] [TO <file name>] [LIST] [EXISTS] [DISMOUNT] [DEFER] [PATH] [ADD] [PREPEND] [REMOVE] [VOLS] [DIRS] [DEVICES] [NOREQ]
Template
NAME,TARGET/M,FROM/K,TO/K,LIST/S,EXISTS/S,DISMOUNT/S,DEFER/S,PATH/S,ADD=APPEND/S,PREPEND/S,REMOVE/S,VOLS/S,DIRS/S,DEVICES/S,NOREQ/S
Location
C:

ASSIGN allows directories to be referenced via short, convenient logical device names, rather than their usual names or complete paths. ASSIGN gives an alternative directory name, much as ALIAS permits alternative command names. The ASSIGN command can create assignments, remove assignments, or list some or all current assignments.

If the <name> and {dir} arguments are given, ASSIGN assigns the given name to the specified directory. Each time the assigned logical device name is referred to, AmigaDOS accesses the specified directory. If the <name> given is already assigned to a directory, the new directory will replace the previous directory. (Always be sure to include a colon after the <name> argument.)

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

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

You can assign one logical device name to several directories by specifying each directory after the <name> argument or by using the ADD or APPEND option. When the APPEND option is specified, any existing directory assigned to <name> is not cancelled. Instead, the newly specified directory is appended to the end of the assign list and the system will search for both directories when <name> is encountered. If the first directory is not available, ASSIGN will be satisfied with the newly added directory.

The PREPEND option does the same thing as the APPEND option except the additional assignment is added at the front of the assing list. The PREPEND option is available with Assing version 53.2 or higher.

To delete a name from the assign list, use the REMOVE option.

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

When the EXISTS keyword is given along with a logical device name, AmigaDOS will search the ASSIGN list for that name and display the volume and directory assigned to that device. If the device name is not found, the condition flag is set to 5 (WARN). This is commonly used in scripts.

Normally, when the {dir} argument is given, AmigaDOS immediately looks for that directory. If the ASSIGN commands are part of S:startup-sequence, the directories need to be present on a mounted disk during the boot procedure. If an assigned directory cannot be found, a requester appears asking for the volume containing that directory. However, two new options, DEFER and PATH, will wait until the directory is actually needed before searching for it.

Note
The assigned name does not have to retain the name of the 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 only takes effect when the assigned object is first referenced, rather than when the assignment is made. This eliminates the need to insert disks during the boot procedure that contain the directories that are assigned during the startup-sequence. When the DEFER option is used, the disk containing the assigned directory is not needed until the object is actually called upon.

For example, if you assign FONTS: to DF0:Fonts with the DEFER option, the system will associate FONTS: with whatever disk is in DF0: at the time FONTS: is called. If you have Workbench disk in DF0: at the time the FONTS: is needed, the system will associate FONTS: with that particular Workbench disk. If you later remove that Workbench disk and insert another disk containing a Fonts directory, the system will specifically request 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 it is re-evaluated each time the assigned name is referenced. This prevents the system from expecting a particular volume in order to use a particular directory (such as the situation described in the example above). For instance, if you assign FONTS: to DF0:Fonts with the PATH option, any disk in DF0: will be searched when FONTS: is referenced. As long as the disk contains a Fonts directory, it will satisfy the ASSIGN. Up until V54 DOS library, you could not assign multiple directories with the PATH option.

The PATH option is especially useful to users with floppy disk systems as it eliminates the need to reinsert the original Workbench disk used to boot the system. As long as the drive you have assigned with the PATH option contains a disk with the assigned directory name, the system will use that disk.

Instead of specifying on the command line which assignments to set up and how, you can tell the ASSIGN command to read a list of specifications from a file using the FROM option. In that file, there must be one assignment specification per line; lines beginning with the ';' character are ignored. The file could look like this:

FONTS: MyFonts:Fontdir
LIBS: SYS:Libs BigAssem:Libs PDAssem:Libs
WorkDisk: DF0: DEFER
C: DF0:C PATH

As you can see, it is possible to set up deferred and path assignments and assignment lists, too.

To complement the FROM option there is the TO option which will store the current list of assignments in a file, suitable for use with the FROM option.

The NOREQ option will prevent any "Please insert volume..." requester windows from appearing which may be triggered by attempts to make assignments to volumes which are currently unavailable. While the command will fail to establish any assignment producing such an error, a script file in which the command is used can keep on running without requiring manual intervention.

Note
The DISMOUNT option (called REMOVE in V1.3) is no longer active. From V54+ use the new dedicated C:Dismount command instead.
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 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 6
1> ASSIGN C: DF0:C PATH
1> ASSIGN C: EXISTS
C [Df0: C]

will reference the C directory of whatever disk is in DF0: at the time a command is searched for. Notice that ASSIGN shows DF0:C in square brackets to indicate that it is a non-binding ASSIGN.

Example 7
1> ASSIGN LIBS: Zcad:Libs ADD

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

Example 8
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 [CHIP | FAST | VIRTUAL | TOTAL] [FLUSH] [SHOW=<BLOCKS|BYTES|SIZE>]
Template
CHIP/S,FAST/S,TOTAL/S,FLUSH/S,VIRTUAL/S,SHOW/K
Location
C:

AVAIL reports the amount of installed memory and how musch of it is available free for use.

The figures in the complete summary are localised.

The SHOW option selects the format in which the figures in the complete summary will be printed. This must be one of BYTE, KILO, or MEGA. "BYTE", which is the default, will display plain figures. "KILO" will display the same information in KB. "MEGA" will display the same information in MB.

By using the CHIP, FAST, VIRTUAL, or TOTAL options, you can have AVAIL display only the number of free bytes of Chip, Fast, Virtual, or total RAM available, instead of the complete summary. This value can be used for comparisons in scripts.

These types are obsolete as of AmigaOS 4.x and the options CHIP, FAST, and VIRTUAL are only kept to ensure compatibility with older scripts.

The FLUSH option is obsolete and does nothing.

Example 1
1> AVAIL
Installed: 536.870.912
Free:      437.252.096
Example 2
1> AVAIL TOTAL
437252096
Example 3
1> AVAIL SHOW=MEGA
Installed: 512,000 M
Free:      416,104 M

BREAK

Sets attention flags in the specified process.

Format
BREAK <process> [NAME <program name or pattern>] [ALL | C | D | E | F]
Template
PROCESS/N,NAME/K,ALL/S,C/S,D/S,E/S,F/S
Location
C:

BREAK sets the specified attention flags in the <process> indicated. 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, AmigaDOS only sets the Ctrl-C flag.

Ctrl-C is used as the default for sending a BREAK signal to halt a process. A process that has been aborted this way will display ***BREAK in the Shell window. Ctrl-D is used to halt execution of a script file. Ctrl-E is used to exit Commodity Exchange programs. Ctrl-F is not currently used.

A process can be signalled by giving a name or a wildcard pattern. The name will be compared against the program's name (including its full path, if available) and the program name (excluding the path), if the first test did not produce a match.

See also
Example 1
1> BREAK 7

sets the Ctrl-C attention flag of process 7. This is identical to selecting process 7 and pressing Ctrl-C.

Example 2
1> BREAK 5 D

sets the Ctrl-D attention flag of process 5.

Example 3
1> BREAK NAME "DIR#?"

sets the Ctrl-C attention flag of all processes whose name begin with the letters "DIR"; this would include the "DIR" program, for example.

BUILDMAPTABLE

Creates a binary mapping table to Unicode for diskfont.library from ASCII mapping table.

Format
BUILDMAPTABLE <ASCII mapping table> [CHARSET]
Template
UNICODEMAPTABLE/A,CHARSET/K
Location
SDK:C

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>] [NAME <program name or pattern>]
Template
PRI=PRIORITY/A/N,PROCESS/K/N,NAME/K
Location
C:

Since the Amiga is multitasking, it uses priority numbers to determine the order in which current tasks should be serviced. Normally, most tasks have a priority of 0, and the time and instructions cycles of the CPU are divided equally among them. CHANGETASKPRI changes the priority of the specified Shell process. (If no process is specified, the current Shell process is assumed.) Any started from <process> inherit its priority.

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, or you may disrupt important system tasks. Too low a priority (less than 0) can result in a process taking unreasonably long to execute, priority -128 does not make much sense because at that priority runs the idle.task.

The name of the process whose priority number should be changed can be given, or a wildcard pattern that should match it. The name will be compared against the program's name (including its full path, if available) and the program name (excluding the path), if the first test did not produce a match. If more than one command matches the pattern given, then all these commands will have their priorities changed.

See also
Example 1
1> CHANGETASKPRI 4 Process 2

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

Example 2
1> CHANGETASKPRI 4 NAME "DIR"

The priority of the program "DIR" is changed to 4. Note that if there is more than one command to match the name, CHANGETASKPRI will abort with an error message.

CHARSETCONVERT

Converts a text file from one charset into another.

Format
CHARSETCONVERT <from file> <fromcharset> [tofile] [tocharset] [EOL [CR] [LF] [CRLF]]
Template
FROM/A,FROMCHARSET/A,TO,TOCHARSET,EOL/K
Location
C:

CLIP

Reads or writes any clipboard unit.

Format
CLIP [<unit>] [WAIT] [ GET | PUT <string> | COUNT ]
Template
U=UNIT/N/K,W=WAIT/S,G=GET/S,P=PUT=S=SET/S,C=COUNT/S,TEXT
Location
C:

CONFIGURENETINTERFACE

Configure network interface parameters.

Format
CONFIGURENETINTERFACE [QUIET] [TIMEOUT=<n>] INTERFACE
Template
INTERFACE/A,QUIET/S,ADDRESS/K,NETMASK/K,BROADCASTADDR/K,DESTINATION=DESTINATIONADDR/K,METRIC/K/N,MTU/K/N,ALIASADDR/K,DELETEADDR/K,ONLINE/S,OFFLINE/S,UP/S,DOWN/S,DEBUG/K,COMPLETE/K,CONFIGURE/K,LEASE/K,RELEASE=RELEASEADDRESS/S,ID/K,TIMEOUT/K/N,DHCPUNICAST/K
Location
C:

COPY

Copies files or directories.

Format
COPY [FROM] {<name | pattern>} [TO] <name> [ALL] [QUIET]
[BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO] [COM] [NOREQ]
[NOREPLACE] [INTERACTIVE] [FORCE] [ARCHIVE] [NEWER]
[COPYLINKS] [FOLLOWLINKS]
Template
FROM/A/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S,NOREPLACE/S,INTERACTIVE/S,FORCE/S,ARCHIVE/S,NEWER/S,COPYLINKS/S,FOLLOWLINKS/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 FROM argument; each argument should be separated by spaces. You can use pattern matching to copy or exclude items whose names share a common set of characters or symbols.

If a TO filename already exists, COPY overwrites the TO file with the FROM file. If you name a destination directory that does not exist, COPY will create a directory with that name. You can also use a pair of double quotes ("") to refer to the current directory when specifying a destination. (Do not put any spaces between the double quotes.)

If the FROM argument is a directory, only the directory's files will be copied; its subdirectories will not be copied. Use the ALL option to copy the complete directory, including its files, subdirectories, and the subdirectories' files. If you want to copy a directory and you want the copy to have the same name as the original, you must include the directory name in the TO argument.

COPY prints to the screen the name of each file as it is copied. This can be overridden by the QUIET option or the local shell variable _Verbosity with a negative value.

The BUF option is used to set the number of 512-byte buffers used during the copy. (Default is 200 buffers, approximately 100K of RAM.) It is often useful to limit the number of buffers when copying to RAM:. BUF=0 uses a buffer the same size as the file to be copied.

Normally, copy gives the TO file the date and time the copy was made. Any comments attached to the original FROM file are ignored. The protection bits of the FROM file are copied to the TO file. Several options allow you to override these defaults:

DATES The creation date of the FROM file is copied to the TO file.
COM Any comment attached to the FROM file is copied to the TO file.
CLONE The date, comments and protection bits of the FROM file are copied to the TO file.
NOPRO The protection bits of the FROM file are not copied to the TO file. The TO file will be given standard protection bits of r, w, e and d.
NOREPLACE Checks if the destination file already exists. If this is the case, then the file is not copied.
INTERACTIVE Checks if the destination file already exists. In this case, you will be prompted to confirm that you want the file to be overwritten (answer 'y' for 'yes').
FORCE If the destination file could not be created because there already is a file of that name which is protected against deletion or writing, then the protection will be removed first before the destination file is created.
ARCHIVE Copy only those files for which the 'archived' flag is unset. After copying, the 'archived' flag will be set on the file just copied. Note that the ARCHIVE option implies the CLONE option which will be enabled by default.
NEWER Overwrite files only if the destination file is older than the source file, or of there is no destination file by the same name as the source file.
COPYLINKS Copy the contents of a file referenced by a hard or soft link; the default is to skip copying linked files.
FOLLOWLINKS When used with the ALL option, the COPY command will follow hard and soft links to directories; the default is to skip links to directories.

Normally, COPY displays a requester if the COPY cannot continue for some reason. When the NOREQ option is given, all requesters are suppressed. This is useful in scripts and can prevent a COPY failure from stopping the script while it waits for a response. For instance, if a script calls for a certain file to be copied and the system cannot find that file, normally the script would display a requester and would wait until a response was given. With the NOREQ option, the COPY command would be aborted and the script would continue.

Example 1
1> COPY File1 TO :Work/File2

copies File1 in the current directory to File2 in the Work directory.

Example 2
1> COPY ~(#?.info) TO DF1:Backup

copies all the files not ending in .info in the current directory to the Backup directory on the disk in DF1:. This is a convenient use of pattern matching to save storage space when icons are not necessary.

Example 3
1> COPY Work:Test TO ""

copies the files in the Test directory on Work to the current directory; subdirectories in Test will not be 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:, AmigaDOS will create one.

Example 5
1> COPY Work:Test% TO DF0: ALL

copies the directory Test including all the contained files and subdiretories to DF0:. If DF0:Test does not exist, it will be created.

Example 6
1> COPY  (Dir1|Dir2|%)  TO  DF0:  ALL QUIET

copies the directories Dir1 and Dir2 including all the contained files and subdirectories to DF0:. If any of the directories does not already exist on DF0:, AmigaDOS will create each.

Example 7
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. (This is quite slow in comparison to DiskCopy.)

COUNTLINES

Counts how many lines a file is made of.

Format
COUNTLINES {<filename>}
Template
NAME/A/M
Location
C:

COUNTLINES counts the number of lines of the file(s) given in argument. If several arguments are given, a sum of all line counts will be returned.

CPU

Adjusts various options of the microprocessor installed in your Amiga. The command also shows the processor and options that are currently enabled.

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:

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)

CUT

Cuts some characters or words from a string.

Format
CUT <string> [ CHAR <range> | WORD <range> [SEPARATOR] ]
Template
STRING/A,C=CHAR/K,W=WORD/K,S=SEPARATOR
Location
C:

DATE

Displays or sets the system date and/or time.

Format
DATE [<day>] [<date>] [< time >] [SERVER <name>] [PORT <n>] [OFFSET <n>]
[LFORMAT <string>] [TO | VER <filename>]
Template
DAY,DATE,TIME,SERVER/K,PORT/K/N,OFFSET/K/N,LFORMAT/K,TO=VER/K
Location
C:

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

DATE <date> sets just the date. The date can be specified either in the current default locale format or in the AmigaDOS format DD-MMM-YY (day-month-year). If the AmigaDOS format is used, the hyphens between the arguments are required. A leading zero in the date is not necessary. The first 3 letters of the month (in the current locale language) must be used, as well as the last two digits of the year.

The date can also be reset by specifying a day name, thus setting the date forward to that day of the week. You can also use tomorrow or yesterday as the <day> argument.

DATE

The SERVER option is used to retrieve the current date and time from a remote server over a TCP/IP connection using the Network Time Protocol (NTP). A list of NTP time servers and some good background information can be found at http://www.eecis.udel.edu/~mills/ntp/servers.html.

The SERVER option may be set to the special value "PREFS" which will retrieve the date and time from the currently configured remote server information stored in the Time preferences.

By using PORT you can specify a port number different to the default 123.

The OFFSET argument allows to set the offset in minutes of your location with respect to Greenwich Mean Time (GMT). If OFFSET is not specified, the locale offset will be used.

The LFORMAT option modifies the output of DATE using one or more substitution operators. See below for available substitution operators.

 %a abbreviated weekday name
 %A weekday name
 %b abbreviated month name
 %B month name
 %c same as "%a %b %d %H:%M:%S %Y"
 %d day number with leading 0s
 %D same as "%m/%d/%y"
 %e day number with leading spaces
 %h abbreviated month name
 %H hour using 24-hour style with leading 0s
 %I hour using 12-hour style with leading 0s
 %j julian date
 %m month number with leading 0s
 %M the number of minutes with leading 0s
 %n insert a linefeed
 %p AM or PM strings
 %q hour using 24-hour style
 %Q hour using 12-hour style
 %r same as "%I:%M:%S %p"
 %R same as "%H:%M"
 %S number of seconds with leadings 0s
 %t insert a tab character
 %T same as "%H:%M:%S"
 %U week number, taking Sunday as first day of week
 %w weekday number
 %W week number, taking Monday as first day of week
 %x same as "%m/%d/%y"
 %X same as "%H:%M:%S"
 %y year using two digits with leading 0s
 %Y year using four digits with leading 0s

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

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

Note
Adjustments made with DATE only change the software clock. They will not survive past power-down. To set the battery backed-up hardware clock from the Shell, you must set the date and use SETCLOCK SAVE.

If DATE succeeded in setting the system date and/or time, the primary return code (RC) will be set to 0. A return code of 5 or 20 indicates that DATE failed partially or completely. If an error occurred when trying to get time from a remote server, the primary return code will be set to 21. In this case the secondary return code (RESULT2) may contain a TCP stack socket/resolver error number and the corresponding error message will be displayed.

Example 1
1> DATE
6-Sep-92

displays the current date and time.

Example 2
1> DATE LFORMAT "Today it's %A, %m/%d/%Y, %T"

displays a message like "Today it's Monday, 02/17/2003, 22:30:56".

Example 3
1> DATE 1-jan-04

sets the date to January 1st, 2004 (the earliest date you can set is January 1, 1978). The time is not reset.

Example 4
1> DATE tomorrow

resets the date to one day ahead.

Example 5
1> DATE TO Fred

sends the current date to the file Fred.

Example 6
1> DATE 23:00

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

Example 7
1> DATE SERVER foo.bar.com OFFSET -480

gets the current date and time from the foo.bar.com NTP server for a location based on the Pacific Standard Time used in the United States.

DELETE

Deletes files or directories.

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

DELETE attempts to delete (erase) the specified file(s). If more than one file was specified, AmigaDOS continues to the next file in the list.

You can use pattern matching to delete files. The pattern may specify directory levels as well as filenames. All files that match the pattern are deleted. To abort a multiple-file DELETE, press Ctrl-C.

AmigaDOS does not request confirmation of deletions. An error in a pattern-matching DELETE can have severe consequences, as deleted files are unrecoverable. Be sure you understand pattern matching before you use this feature, and keep backups of important files.

Warning: If you try to delete a directory that contains files, you will receive a message stating that the directory could not be deleted as it is not empty. To override this, use the ALL option. DELETE ALL deletes the named directory, its subdirectories, and all files.

Filenames are displayed on the screen as they are deleted. To suppress the screen output, use the QUIET option or the local shell variable _Verbosity with a negative value.

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

If the INTERACTIVE option is used, you will be prompted to confirm each single deletion (enter 'y' to confirm). Note that the FORCE option will override the INTERACTIVE option, turning it off.

For most file systems deleting a single file will only make the storage space previously reserved for it available again, but will not render the contents of the file unrecoverable. In order to make recovery of sensitive data much harder, use the WIPE option which, prior to deleting the file, will overwrite the contents of the file up to 7 times using the United States Department of Defense 5220-22.M standard procedure for this purpose. This can take long to complete.

Note
The WIPE operation implemented by the DELETE command is suitable only for magnetic storage media, such as floppy disks or hard disk drives. To wipe optical, magneto-optical or solid state memory storage devices you would need a different method, which is not currently implemented by the DELETE command.

While the contents of the file will be overwritten, the name of the file and any directories to be deleted will not be overwritten. You may want to move or rename file and directories prior to deletion.

While the contents of the file will be overwritten, the name of the file and any directories to be deleted will not be overwritten. You may want to move or rename file and directories prior to deletion.

The DELETE command does not guarantee that the file contents will be securely deleted because the file system and the underlying storage hardware may reduce the effectiveness of the overwrite operations. The FORMAT command may be more effective in securely wiping a storage medium, albeit at the expense of wiping the entire partition/disk rather than just a single file.

If the FORCE and WIPE options are combined, then each file will have its write and delete protection removed before it is wiped.

Example 1
1> DELETE Old-file

deletes the Old-file 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 there are no other files left in it).

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

deletes all 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 these set as not deletable.

See also

DELETENETROUTE

Deletes a message routing path currently in use.

Format
DELETENETROUTE [QUIET] [DESTINATION=<ip>] [DEFAULTGATEWAY=<ip>]
Template
QUIET/S,DST=DESTINATION/K,DEFAULT=DEFAULTGATEWAY/K
Location
C:

DIR

Displays a sorted list of the files in a directory.

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

DIR displays the file and directory names contained in the specified directory, or the current directory if no name is given. 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.


SHOWPROGRAMS Executable programs and script files will be highlighted in the listing, by printing their names in boldfaced script.
MAXCOLUMNS How many file names will be printed per line depends upon the width of the output window and the lengths of the file names. You can, however, limit how many names will be printed in each line by specifying the maximum number of columns.
Note
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.

The interactive listing mode stops after each name and displays a question mark at which you can enter commands. The acceptable responses are shown below:

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. When you want to issue a command, type C (or COM) at the question mark prompt. DIR will ask you for the command. Type the desired command, then press Return. The command will be executed and DIR will continue. You can also combine the C and the command on one line, by putting the command in quotes following the C.

For instance, C "type prefs.info hex" is equivalent to pressing Q to exit interactive listing mode and return to a regular Shell prompt, and typing:

1> TYPE Prefs.info HEX

The Prefs.info file would be typed to the screen in hexadecimal format.

It is dangerous to format a disk from the DIR interactive mode, as the format will take place immediately, without any confirmation requesters appearing. Also, starting another interactive DIR from interactive mode will result 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.

See also

DISKCHANGE

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

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

The DISKCHANGE command is only necessary when you are using 5.25 inch floppy disk drives or removable media drives without automatic diskchange hardware. Whenever you change the disk or cartridge of such a drive, you must use DISKCHANGE to inform the system of the switch.

DISKCHANGE can also be used if you edit a disk icon image and wish to see the new icon on the Workbench screen immediately. This is the only way to display an altered hard disk icon without rebooting.

Example

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

1> DISKCHANGE DF2:

AmigaDOS then recognizes the new disk and you can proceed.

DISMOUNT

Shuts down a file system device and all its associated volumes.

Format
DISMOUNT <device> [SOFT] [FORCE]
Template
DEVICE/A,SOFT/S,FORCE/S
Location
C:

ECHO

Displays a string.

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

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

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

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

Examples
1> ECHO "hello out there!"

hello out there!

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

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

ED

Edits text files (a screen editor).

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

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

EDIT

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

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

See EDIT for more information.

ELSE

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

Format
ELSE
Template
(none)
Location
Internal

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

Example

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

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

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

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

picfile is not in this directory
See also

ENDCLI

Ends a Shell process.

Format
ENDCLI
Template
(none)
Location
Internal

ENDCLI ends a Shell process.

See also

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

ENDSHELL

Ends a Shell process.

Format
ENDSHELL
Template
(none)
Location
Internal

ENDSHELL ends a Shell process and closes the Shell window.

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

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

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

For examples using the ENDSHELL command, see Chapter 8.

ENDSKIP

Terminates a SKIP block in a script file.

Format
ENDSKIP
Template
(none)
Location
Internal

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

See also

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/F
Location
C:

EXECUTE is used to run scripts of AmigaDOS commands. The lines in the script are executed just as if they had been typed at a Shell prompt. If the s protection bit of a file is set and the file is in the search path, you only need to type the filename--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 you 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). EXECUTE is generally made resident during the startup-sequence.

The permissible keywords for parameter substitution are explained below. Each keyword must be prefaced with a dot character (.).

The .KEY (or .K) keyword specifies both keyword names and positions in a script. It tells EXECUTE how many parameters to expect and how to interpret them. In other words, .KEY serves as a template for the parameter values you specify. Only one .KEY statement is allowed per script. If present, it should be the first line in the file.

The arguments on the .KEY line can be given with the /A and /K directives, which work the same as in an AmigaDOS template. Arguments followed by /A are required; arguments followed by /K require the name of that argument as a keyword. For example, if a script starts with .KEY filename/A it indicates that a filename must be given on the EXECUTE command line after the name of the script. This filename will be substituted in subsequent lines of the script. For instance, if the first line of a script is:

.KEY filename/A, TOname/K

You must specify a filename variable. The TOname variable is optional, but if specified the TOname keyword must be used. For instance:

1> EXECUTE Script Textfile TOname NewFile

Before execution, AmigaDOS scans the script for any items enclosed by BRA and KET characters (< and >). Such items may consist of a keyword or a keyword and a default value. Wherever EXECUTE finds a keyword enclosed in angle brackets, it tries to substitute a parameter. However, if you want to use a string in your script file that contains angle brackets, you will have to define substitute "bracket" characters with the .BRA and .KET commands. .BRA <ch> changes the opening bracket character to <ch>, while .KEY changes the closing bracket character to <ch>. For example:

.KEY filename
ECHO "This line does NOT print <angle> brackets."
.BRA {
.KET }
ECHO "This line DOES print <angle> brackets."
ECHO "The specified filename is {filename}."

would result in the following output:

1> EXECUTE script TestFile
This line does NOT print brackets.
This line DOES print <angle> brackets.
The specified filename is TestFile.

AmigaDOS provides a number of commands that are useful in scripts, such as IF, ELSE, SKIP, LAB, and QUIT. These commands, as well as the EXECUTE command, can be nested in a script. That is, a script can contain EXECUTE commands.

To stop the execution of a script, press Ctrl-D. If you have nested script files, you can stop the set of EXECUTE commands by pressing Ctrl-C. Ctrl-D only stops the current script from executing.

The current Shell number can be referenced by the characters <$$>. This is useful in creating unique temporary files, logical assignments, and PIPE names.

Example 1

Assume the script List contains the following:

.K filename
RUN COPY <filename> TO PRT: +
ECHO "Printing of <filename> done"

The following command:

1> EXECUTE List Test/Prg

acts as though you had typed the following commands at the keyboard:

1> RUN COPY Test/Prg TO PRT: +
1> ECHO "Printing of Test/Prg done"
Example 2

Another example, Display, uses more of the features described above:

.Key name/A
IF EXISTS <name>
TYPE <name> NUMBER ;if the file is in the given directory, type it with line numbers
ELSE
ECHO "<name> is not in this directory"
ENDIF

The command:

1> RUN EXECUTE Display Work/Prg2

should display the Work/Prg2 file, with line numbers on the screen, if it exists on the current directory. If the file is not there, the screen displays an error message. Because of the /A, if a filename is not given on the command line after display, an error will occur.

See also

FAILAT

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

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

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

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

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

Example

Assume a script contains the following lines:

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

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

COPY: object not found
COPY failed returncode 20:

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

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

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

COPY: object not found
MyFile being copied.
See also

FAULT

Prints the messages for the specified error codes.

Format
FAULT [<error number>] [[,]<error number>[[,]<error number>...]]
Template
/N/M
Location
Internal

FAULT prints the messages corresponding to the error numbers supplied. If several error numbers are given, they can be separated by spaces or commas.

Example

If you received an error message:

Error when opening DF1:TestFile 205

and need more information, type:

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.

FDTOOL

Control and examine the current state of the a1floppy device.

Format
FDTOOL [U | UNIT <unit number>] [D | DEBUG <debug level>] [A | AUTO] [M | MANUAL] [C | CHECKNOW] [I | INFO] [V | VERS | VERSION]
Template
U=UNIT/K/N,D=DEBUG/K/N,A=AUTO/S,M=MANUAL/S,C=CHECKNOW/S,I=INFO/S,V=VERS=VERSION/S
Location
C:

FILENOTE

Attaches a comment to a file.

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

FILENOTE attaches an optional comment characters to the specified file or to all files matching the given pattern. The size of the comment is limited, which means that the <comment> argument may be truncated before it is used.

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

To delete an existing filenote from a file, use "" as the <comment> argument.

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 will be reflected in the Information window, and vice versa.

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

FILENOTE's options are:

ALL If the ALL option is given, FILENOTE will add the <comment> to all the files in the specified directory.
QUIET If the QUIET option is given, screen output is suppressed. The local shell variable _Verbosity with a negative value has the same effect.
FILES Only change the comments of the files found.
DIRS Only change the comments of the directories found.
Note
The FILES and DIRS options work together: if you use FILES and omit DIRS, then only the files will be affected and the other way round. If none of FILES and DIRS is used, all files and directories will have their comments changed.
Example 1
1> FILENOTE Sonata "allegro non troppo"

attaches the filenote allegro non troppo to the Sonata file.

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

Here the filenote is "presto".

FILESIZE

Collects information on the size of files stored on a disk.

Format
FILESIZE [{<dir|file|pattern|device>}] [FORM <file name>] [ALL]
Template
FILES/M,FROM/K,ALL/S,REPORT/S,FORMAT/K
Location
C:

FLASHTOOL

Reading, writing, and erasing for EEPROM memory chips.

Format
FLASHTOOL <command> [<command arguments>]
Template
COMMAND,ARGS/M
Location
C:

FLASHTOOL is used for reading, erasing, and writing to EEPROM non-volatile memory chips. To utilize FLASHTOOL, an IDE Flasher must be installed in the primary or secondary IDE port.

FLASHTOOL provides the following commands:

Name Command Description
ISPRESENT -p <device name> <unit> Check if a flasher device is present.
TYPE -t <device name> <unit> Return EEPROM type.
ERASE -e <device name> <unit> Erase an EEPROM.
ISBLANK -b <device name> <unit> Check if EEPROM is empty.
SAVE -s <device name> <unit> <file name> Save EEPROM content to a file. The saved file is in binary (raw) format.
WRITE -w <device name> <unit> <file name> Write a binary (raw) file to EEPROM.
VERIFY -c <device name> <unit> <file name> Check if EEPROM content matches the file's content. The file must be in binary (raw) form.
LISTSUPPORTED -l List supported EEPROMs.
VERSION -v Print FLASHTOOL version.

The <device name> argument tells which Amiga device is controlling the IDE Flasher, and the <unit> argument tells which device is used.

FLASHTOOL supports the following EEPROMs:

  • ATMEL AT29C512 512 Kbit (64K x 8-bit)
  • ATMEL AT29C010A 1 Mbit (128K x 8-bit)
  • ATMEL AT29C020 2 Mbit (256K x 8-bit)
  • ATMEL AT29C040 4 Mbit (512K x 8-bit)
  • ATMEL AT29C040A 4 Mbit (512K x 8-bit)
  • ATMEL AT49F004N 4 Mbit (512K x 8-bit)
  • ATMEL AT49F004T 4 Mbit (512K x 8-bit)
  • ATMEL AT49F010 1 Mbit (128K x 8-bit)
  • ATMEL AT49F020 2 Mbit (256K x 8-bit)
  • AMD AM29F010 1 Mbit (128K x 8-bit)
  • AMD AM29F010A 1 Mbit (128K x 8-bit)
  • AMD AM29F040B 4 Mbit (512K x 8-bit)
  • AMD AM29F002 2 Mbit (256K x 8-bit) Top Boot Block
  • AMD AM29F002 2 Mbit (256K x 8-bit) Bottom Boot Block
  • AMD AM29F004 4 Mbit (512K x 8-bit) Top Boot Block
  • AMD AM29F004 4 Mbit (512K x 8-bit) Bottom Boot Block
  • MOSEL VITELIC V29C51000T 512 Kbit (64K x 8-bit)
  • MOSEL VITELIC V29C51000B 512 Kbit (64K x 8-bit)
  • MOSEL VITELIC V29C51001T 1 Mbit (128K x 8-bit)
  • MOSEL VITELIC V29C51001B 1 Mbit (128K x 8-bit)
  • MOSEL VITELIC V29C51002T 2 Mbit (256K x 8-bit)
  • MOSEL VITELIC V29C51002B 2 Mbit (256K x 8-bit)
  • MOSEL VITELIC V29C51004T 4 Mbit (512K x 8-bit)
  • MOSEL VITELIC V29C51004B 4 Mbit (512K x 8-bit)
  • HYUNDAI HY29F002T 2 Mbit (256K x 8-bit)
  • HYUNDAI HY29F002B 2 Mbit (256K x 8-bit)
  • HYUNDAI HY29F040A 4 Mbit (512K x 8-bit)
  • SST SST29EE512 512 Kbit (64K x 8-bit)
  • SST SST29EE010 1 Mbit (128K x 8-bit)
  • SST SST29EE020 2 Mbit (256K x 8-bit)
  • SST SST39SF512 512Kbit (64K x 8-bit)
  • SST SST39SF010(A) 1 Mbit (128K x 8-bit)
  • SST SST39SF020A 2 Mbit (256K x 8-bit)
  • SST SST39SF040 4 Mbit (512K x 8-bit)
  • ST M29F010B 1 Mbit (128K x 8-bit)
  • ST M29F002T 1 Mbit (256K x 8-bit)
  • ST M29F002B 1 Mbit (256K x 8-bit)
  • ST M29F040B 4 Mbit (512K x 8-bit)
  • ST M29F040 4 Mbit (512K x 8-bit)
  • WINBOND W29C512A 512 Kbit (64K x 8-bit)
  • WINBOND W29C010M 1 Mbit (128K x 8-bit)
  • WINBOND W29C020 2 Mbit (256K x 8-bit)
  • WINBOND W29C040 4 Mbit (512K x 8-bit)
  • WINBOND W49C020 2 Mbit (256K x 8-bit)
  • WINBOND W49F002U 2 Mbit (256K x 8-bit)
  • WINBOND W49F002U mod 2 Mbit (256K x 8-bit)
  • MACRONIX MX29F040 4 Mbit (512K x 8-bit)
  • AMIC A29010 1 Mbit (128K x 8-bit)
  • AMIC A29040A 4 Mbit (512K x 8-bit)
  • AMIC A29001T 1 Mbit (128K x 8-bit)
  • AMIC A29001B 1 Mbit (128K x 8-bit)
  • AMIC A29002T 2 Mbit (256K x 8-bit)
  • AMIC A29002B 2 Mbit (256K x 8-bit)
  • Texas Instruments TMS29F040 4 Mbit (512K x 8-bit)
  • IMT IM29F001T 1 Mbit (128K x 8-bit)
  • IMT IM29F001B 1 Mbit (128K x 8-bit)
  • IMT IM29F002T 2 Mbit (256K x 8-bit)
  • IMT IM29F002B 2 Mbit (256K x 8-bit)
  • IMT IM29F004T 4 Mbit (512K x 8-bit)
  • IMT IM29F004B 4 Mbit (512K x 8-bit)
  • Fujitsu MBM29F002TC 2 Mbit (256K x 8-bit)
  • Fujitsu MBM29F002BC 2 Mbit (256K x 8-bit)
  • Fujitsu MBM29F004TC 4 Mbit (512K x 8-bit)
  • Fujitsu MBM29F004BC 4 Mbit (512K x 8-bit)
  • Fujitsu MBM29F040C 4 Mbit (512K x 8-bit)
Example 1

Check if an IDE Flasher device is installed:

 1> FLASHTOOL -p a1ide.device 0
Example 2

Erase an EEPROM:

 1> FLASHTOOL -e a1ide.device 0
Example 3

Write file "uboot.bin" to EEPROM:

 1> FLASHTOOL -w a1ide.device 0 uboot.bin
Example 4

Verify the written data:

 1> FLASHTOOL -c a1ide.device 0 uboot.bin
Example 5

Save EEPROM content to file "backup.bin":

 1> FLASHTOOL -s a1ide.device 0 backup.bin

FTP

ARPANET file transfer program.

Format
FTP [-v|VERBOSE] [-d|DEBUG] [-t|TRACE] [-i|NOPROMPT] [-n|NOAUTOLOGIN] [-g|NOGLOBBING] [<host>] [<n>]
Template
-v=VERBOSE/S,-d=DEBUG/S,-t=TRACE/S,-i=NOPROMPT/S,-n=NOAUTOLOGIN/S,-g=NOGLOBBING/S,HOST,PORT/N
Location
C:

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
See also

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
See also

GETNETSTATUS

Queries whether the network is operational.

Format
GETNETSTATUS [CHECK=condition[,condition...]] [QUIET]
Template
CHECK/K,QUIET
Location
C:

GROUP

Changes the access rights of a file or directory.

Format
GROUP [FILE] {<file | pattern>} [GROUP] <name or number> [ALL]
Template
FILE/A/M,GROUP/A,ALL/S,QUIET/S
Location
C:

HELP

Text based help command.

Format
HELP [<command name> [SHORT | LFORMAT]] | [SHOWLIST]
Template
COMMANDNAME,SHORT/S,LFORMAT/S,SHOWLIST/S
Location
Rexx:

HELP will display the help text of a command given in argument. If no arguments is given, a brief description of this help system is displayed.

By default all the available text for the supplied command name will be printed in the Shell.

If the SHORT argument is supplied, only a short description will be printed. This text is extracted from the section "NAME" of the help text.

Some commands use the LFORMAT argument to customize the command output. This argument is always used with several output qualifiers. Supplying the LFORMAT argument to the HELP command, only the details on the usage of the LFORMAT argument will be printed. This text is extracted from the section "LFORMAT" of the help text.

If the SHOWLIST argument is supplied, a list of all available help texts with the short description will be displayed.

The HELP command will look for text help files in HELP:<your language>/Shell and if it could not be found, it will look into HELP:english/Shell.

HELP will display the help texts with the program you specify in the PAGER environment variable. By default, help texts will be displayed with the MORE program. As an example, if you want to use the TYPE command, store it into the PAGER variable with "SETENV PAGER TYPE".

HI

Halts all ARexx programs.

Format
HI
Template
(none)
Location
C:

Sets the global halt flag, which causes all active ARexx programs to receive an external halt request. Each program will exit immediately unless its HALT interrupt has been enabled. The halt flag does not remain set, but is cleared automatically after all current programs have received the request.

Example
1> HI
Command returned 10/2: Execution halted
rx failed returncode 10

HISTORY

Display, recall, or store the command line history.

Format
HISTORY [[LINES] <number>] [START <number>] [LOAD <file name>] [SAVE <file name>] [SIZE <number>] [CLEAR] [SHOW] [NONUM]
Template
LINES/N,START/K/N,LOAD/K,SAVE/K,SIZE/K/N,CLEAR/S,SHOW/S,NONUM/S
Location
C:

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

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 <b> 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 <b> 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

INFO

Gives information about the mounted devices.

Format
INFO [<device>] [DEVICES] [VOLUMES] [SHOW=<BLOCKS|BYTES|SIZE>]
[SORT=<NAME|FREE|USED|SIZE|VOLUME>]
Template
DEVICE,DEVICES/S,VOLUMES/S,SHOW/K,SORT/K
Location
C:

INFO displays a line of information about each disk or partition. This includes the maximum size of the disk, the used and free space, the number of soft disk errors that have occurred, the status of the disk and the DOS type if available.

With the DEVICE argument, INFO provides information on just one device or volume.

The options are:

DEVICES Show only device information, omit volume data.
VOLUMES Show only volume information, omit device data.
SHOW Select the format in which the Free/Full column data should be printed. This must be one of BLOCKS, BYTES or SIZE. "BLOCKS", which is the default, will display the number blocks available for use and already allocated. "BYTES" will display the same information in bytes. Note that due to how the file system allocates storage space, this may not be an accurate figure. Typically, a file needs more storage space on disk than just the data stored in it. "SIZE" will print an approximate rough figure in the KByte/MByte/GByte range, similar to the "Size" column.
SORT Choose by which criterion the device list should be sorted. This must be one of NAME (the default), FREE (by free space), USED (by allocated space), SIZE (total size) or VOLUME (volume name). Note that because block sizes may vary, for FREE, USED and SIZE the number of bytes is used account, not the number of blocks.
Example 1
1> INFO
Unit Size Used Free Full Errors Status     Name         DOS Type
DF0: 837K 1742   16  98%      0 Read Only  Workbench2.0 DOS\01
DF1: 837K  211 1547  12%      0 Read/Write Text-6       DOS\03

Volumes available:
Workbench2.0 [Mounted]
Text-6 [Mounted]
Example 2
1> INFO SHOW=BYTES
Mounted disks:
Unit Size   Used   Free Full Errors Status     Name         DOS Type
DF0: 837K 850096   7808  98%      0 Read Only  Workbench2.0 DOS\01
DF1: 837K 102968 754936  12%      0 Read/Write Text-6       DOS\03

Volumes available:
Workbench2.0 [Mounted]
Text-6 [Mounted]
Example 3
1> INFO VOLUMES
Volumes available:
Workbench2.0 [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 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:.

IPF

Alters packet filtering lists for IP packet input and output.

Format
IPF [-AdDEInoPrsvVyzZ] [-l <block | pass | nomatch>] [-F <i| o | a | s | S>] -f <filename> [-f <filename> [...]]
Template
-A,-d,-D,-E,-I,-n,-o,-P,-r,-s,-v,-V,-y,-z,-Z,-l,-F,-f
Location
C:

IPMON

Monitors /dev/ipl for logged packets.

Format
IPMON [-aDFhnpstvxX] [-N <device>] [-o [NSI]] [-O [NSI]] [-P <pidfile>] [-S <device>] [-f <device>] [<filename>]
Template
-N,-F,-h,-s,-t,-v,-x,-X,-f
Location
C:

IPNAT

Defines NAT (Network Address Translation) rules.

Format
IPNAT
Template
(none)
Location
C:

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

LIST

Lists specified information about directories and files.

Format
LIST [{<dir|pattern>}] [P|PAT <pattern>] [KEYS] [DATES] [NODATES]
[TO <name>] [SUB <string>] [SINCE <date>] [UPTO <date>] [QUICK]
[BLOCK] [NOHEAD] [FILES] [DIRS] [LFORMAT <string>]
[SORT [NAME] [SIZE] [DATE] [REVERSENAME] [REVERSESIZE]
[REVERSEDATE]] [USERS] [GROUPS] [MULTI] [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,SORT/K,USERS/S,GROUPS/S,MULTI/S,ALL/S
Location
C:

LIST displays information about the contents of the current directory. If you specify a <dir>, <pattern>, or <filename> argument, LIST will display information about the specified directory, all directories or files that match the pattern, or the specified file, respectively.

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 will read 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 will show the default protection bits, ----rwed for readable/writable/executable/deleteable. See the PROTECT command for more on protection bits.
date and time The date and time the file was created or last altered.
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:

PAT <pattern> Lists only files which match the pattern <pattern>.
KEYS Displays the block number of each file header or directory.
DATES Displays dates in the form DD-MMM-YY (the default unless you use QUICK).
NODATES Will 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 created on or after a certain date.
UPTO <date> Lists only files created on or before a certain date.
QUICK Lists only the names of files and directories.
BLOCK Displays file sizes in blocks, rather than bytes.
NOHEAD Suppresses the printing of the header information.
FILES Lists files only (no directories).
DIRS Lists directories only (no files).
LFORMAT Defines a string to specially format LIST output.
SORT <order> Sorts the directory entries before displaying it, based upon certain criteria. The SORT option requires a list of parameters which define in which order and by which criteria the output should be sorted. The SORT option parameter must match the following template:
N=NAME,D=DATE,S=SIZE,T=TYPE,RN=REVERSENAME,RD=REVERSEDATE,
RS=REVERSESIZE,RT=REVERSETYPE

The order in which you specify the single options determines the order in which the criteria are matched. Thus, if you want the list to be sorted descending size and by name you would specify SORT=REVERSESIZE,NAME.

USERS Attempt to resolve the name of the 'owner' of a file. If no name resolution is possible, then the numeric owner ID number will be displayed instead.
GROUPS Attempt to resolve the name of the group the 'owner' of a file belongs to. If no name resolution is possible, then the numeric group ID number will be displayed instead.
MULTI Display all linked directories in a multi-assignment. (V53)
ALL Lists all files in directories and subdirectories.

The LFORMAT option modifies the output of LIST and can be used as a quick method of generating script files. When LFORMAT is specified, the QUICK and NOHEAD options are automatically selected. When using LFORMAT you must specify an output format specification string; this string is incorporated into the script file. If you want the output to be saved, you must redirect it to a file by using the > operator or specifying a TO file.

The format for the output format specification string is LFORMAT=<string>. To include the output of LIST in this string, use the substitution operator %S. The path and filename can be made part of the string this way. Whether the path or the filename is substituted for an occurrence of %S depends on how many occurrences are in the LFORMAT line, and their order, as follows:

Substituted with each occurrence
Occurrences of %S 1st 2nd 3rd 4th
1 filename
2 path filename
3 path filename filename
4 path filename path filename

Some new options allow you to specify fields to be printed in the LFORMAT output. These options 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 the file extension.
 %F Prints the full file parent path.
 %G Prints the name of the group which 'owns' the file.
 %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.
 %R Prints the name of the object the file/directory is linked to.
 %T Prints the time associated with the file.
 %U Prints the name user who 'owns' the file.
 %V Prints group/other file attributes (protection bits).

You can put a length specifier and/or a justification specifier between the percent size (%) and the field specifier.

Example 1
> LIST Dirs

Monitors     Dir ----        rwed     27-June-90      11:43:59
T            Dir ----        rwed     Wednesday       11:37:43
Trashcan     Dir ----        rwed     21-Jun-90       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 will search for any directories or files that start with LI. The output of LIST will be sent to the Libs.file in RAM:.

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

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

Example 4
1> LIST >RAM:Scriptnotes #? LFORMAT="filenote %S%S Testnote"

A new script file, Scriptnotes, is created in RAM:. The contents will include a list of all the files in the current directory. When Scriptnotes is executed, it will add the filenote Testnote to each file. For instance, if the current directory is S:, the contents of Scriptnotes as produced by this command might look like this:

filenote s:HDBackup.config Testnote
filenote s:DPat Testnote
filenote s:Ed-startup Testnote
filenote s:PCD Testnote
filenote s:Shell-startup Testnote
filenote s:SPat Testnote
filenote s:Startup-sequence Testnote
See also

LOADRESOURCE

Preloads resources into memory to avoid excessive disk swaps.

NOTE: This command is obsolete.

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] [SKIP=SKIPWBSTARTUP] [SIMPLEGELS]
Template
-DEBUG/S,DELAY/S,CLEANUP/S,NEWPATH/S,SKIP=SKIPWBSTARTUP/S,SIMPLEGELS/S
Location
C:

LOADWB starts the Workbench. Normally, this is done when booting, by placing the LOADWB command in the Startup-Sequence file. If you shut down the Workbench, LOADWB can be used from a Shell to restart it.

Workbench snapshots the current paths in effect when the LOADWB command is executed. It uses these paths for each Shell started from Workbench.

LOADWB's command line options are:

-DEBUG Adds two additional menus which can assist software debugging. You should not use this feature unless you know how to use these menus.
DELAY The LoadWB command will wait until the Workbench is loaded and initialized; otherwise, LoadWB will launch the Workbench and return immediately.
CLEANUP Clean up the contents of the main Workbench window once Workbench has been launched.
NEWPATH Update the Workbench command search path to use the settings of the shell the LoadWB program runs in. Workbench uses the search path (maintained through the shell PATH command) to find programs whose names do not include a directory name.
SKIPWBSTARTUP Do not look into the "SYS:WBStartup" drawer and launch the programs stored in it.
SIMPLEGELS When moving icons on the screen, try to use only the technique that Workbench has been using through versions 1.2-3.1. This is a compatibility switch which can be used to prevent Workbench from crashing if the graphics support software does not support the new icon rendering methods introduced in Workbench 3.5.
Example 1

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

1> LOADWB

will bring the Workbench back. Typing 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>} [ALL] [FORCE]
Template
NAME=DIRS/M/A,ALL/S,FORCE/S
Location
C:

MAKEDIR creates one (or several) empty directory(s) with the name(s) you specify. By default, the command works within only one directory level at a time, so any directories on the given path(s) must already exist. When using the ALL option, directories missing on the path(s) are automatically created, if necessary. The command fails if a directory or a file of the same name already exists in the directory above it in the hierarchy. To avoid this, use the FORCE option which makes the command ignore directories which already exist.

Note
MAKEDIR does not create a drawer icon for the new directory(s).
Example 1
1> MAKEDIR Tests

creates a directory called Tests in the current directory.

Example 2
1> MAKEDIR DF1:Abc/Xyz ALL

creates a directory Abc in the root directory of the disk in DF1: if it doesnt exist yet, then creates directory Xyz in DF1:Abc/.

Example 3
1> CD DF0:
1> MAKEDIR Documents Payables Orders

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

MAKELINK

Creates a link between files or directories.

Format
MAKELINK [FROM] <link> [TO] <file or directory> [SOFT] [HARD] [FORCE]
Template
LINK=FROM/A,FILE=DIR=DIRECTORY=TO/A,SOFT/S,HARD/S,FORCE/S
Location
C:

MAKELINK creates a special file on a disk that is a pointer to another file or directory, this is known as a link. When an application or command tries to use the FROM file, the TO file or directory is actually used.

There exist two types of links, hard links and soft links.

A hard link is some sort of "physical" link handled by the file system itself, it points to the physical location (e.g. a disk block) of the destination. This implies that both the link and the destination must be on the same volume, that renaming the destination (including renaming into another directory) cannot "break" the link (it will continue to point to the same object) and that even deleting the destination wont cause problems (the link will be replaced with the file or directory before the file or directory is deleted). Not all file systems support hard links.

A soft link is some sort of "logical" link handled by the file system, dos.library and the applications, it points to a name which describes the path of the destination. All types of paths can be used (absolute and relative, with or without file name). This implies that both the link and the destination can be located on different volumes and that renaming or deleting the destination will "break" the link (it will point to a no longer existing object). Old applications are sometimes not aware of soft links and will consider them to be directories or ignore them altogether. Not all file systems support soft links. Old file systems may have problems with relative path names in soft links ("///dir2/file3"). Some applications may have problems with "broken" soft links for which the respective destinations do not exist any more.

By default, or when the SOFT keyword is given, MAKELINK tries to create a soft link. When the HARD keyword is given, MAKELINK tries to create a hard link. (Note that the default changed to this from version 53.3+)

Also by default when doing soft links, if the destination path is relative (i.e. a path not prefixed by a volume name), MAKELINK will try to resolve it relative to the directory which will contain the link, it will not resolve it relative to the current directory like other commands. See examples below.

When creating a hard link, and the TO argument is a directory name, MAKELINK does not normally allow the creation of a hard link to a directory. When the FORCE keyword is also given, it allows it.

When creating a soft link, the link destination should exist, and MAKELINK will consider it an error if this is not the case. However, it is sometimes necessary to create a soft link before the link destination itself has been made available. In such a case, the FORCE keyword will cause MAKELINK to create the soft link regardless of whether the destination already exists or not.

Example 1
SYS:> MakeLink RAM:Link S/User-Startup SOFT

will create a soft link to RAM:S/User-Startup (this file must exist) and not to SYS:S/User-Startup as one could expect.

Example 2
SYS:> MakeLink RAM:Link SYS:S/User-Startup SOFT

will create a soft link to SYS:S/User-Startup (absolute path)

MD5SUM

Calculates and compares checksums of files.

Format
MD5SUM [{dir|file|pattern|device}] [ALL] [DEVICES] [TO <name>] [SORT] [BUF=BUFFERSIZE <size>] [CHECK|FROM <name>] [STATUS] [QUIET] [WARN] [ALGORITHM {?|<name>}]
Template
NAMES/M,ALL/S,TO/K,DEVICES/S,SORT/S,BUF=BUFFERSIZE/K/N,CHECK=FROM/K,STATUS/S,WARN/S,QUIET/S,ALGORITHM/K
Location
C:

MD5SUM will read the contents of files or devices and calculate a checksum for each individual item. If you specify a <dir>, <pattern>, <filename>, or <device> argument, MD5SUM will calculate checksums for the specified directory, all directories, or files that match the pattern, or the specified file or device, respectively. MD5SUM can also determine whether a file or a checksum are consistent.

MD5SUM has options which will change the way the output is displayed and how input is processed. These options are explained below.

ALL calculates checksums for all files in directories and subdirectories.

DEVICES indicates that rather than checking the contents of a device file by file, the checksums should be calculated over the raw storage blocks instead. Note that only file system devices can be used which store data in disk blocks. This includes "df0:", "df1:", etc. but not "ram:" or "prt:".

TO <name> specifies an output file or device for MD5SUM; by default, MD5SUM ouputs to the current window.

SORT sorts the list before printing.

BUFFERSIZE <size> sets the size of the read buffer being used. Default is 262144 bytes (256 kB). Larger values can increase performance.

CHECK <name> causes MD5SUM to read the contents of a list file <name> previously generated by MD5SUM and try to open each file listed in it, calculate its checksum and compare it with the value given in the list. If no matching file could be opened or the checksums do not match, an error message will be printed. Use the STATUS option to omit all output.

If the STATUS option is supplied, no output will be generated if a mismatch is found while a list is being checked. Instead, MD5SUM will immediately abort with WARN condition set; this can be tested in script files.

WARN causes MD5SUM to print a warning message for each line in the list to be checked which does not match the format MD5SUM expects.

QUIET prevents MD5SUM from printing progress reports while individual files or devices are being read. The local shell variable _Verbosity with a negative value has the same effect. Progress reports are printed in about each second. No progress reports are printed if the SORT option is effect.

ALGORITHM sets the checksumming algorithm to be used. The default algorithm is "MD5", but there may be more modern algorithms supported, too. To find out which algorithms are available, enter "MD5SUM ALGORITHM ?", which will list all the supported algorithms by name. At this time of writing the following algorithms are implemented:

MD5 Message Digest #5, as defined in RFC 1321.

Note: At this time of writing (2005-11-20) the MD5 algorithm can no longer be considered secure.

SHA-1 Secure Hash Algorithm #1, as defined in U.S. Federal Information Processing Standard (FIPS) 180-1. This Algorithm produces 160 bits of checksum data.

Note: At this time of writing (2005-11-20) the SHA-1 algorithm can no longer be considered secure.

SHA-256 Secure Hash Algorithm, as defined in U.S. Federal Information Processing Standard (FIPS) 180-2. This Algorithm produces 256 bits of checksum data.
SHA-384 Secure Hash Algorithm, as defined in U.S. Federal Information Processing Standard (FIPS) 180-2. This Algorithm produces 384 bits of checksum data.
SHA-512 Secure Hash Algorithm, as defined in U.S. Federal Information Processing Standard (FIPS) 180-2. This Algorithm produces 512 bits of checksum data.
Whirlpool As defined in ISO/IEC 10118-3. This algorithm produces 512 bits of checksum data.

You can choose an algorithm by the name given. Note that the output produced by this MD5SUM program may not be compatible with other "md5sum" shell commands from the Unix world if you choose any checksumming algorithm other than "MD5" here.

Good reasons why you might want to use a different checksumming algorithm are in the security of the original "MD5" algorithm. At this time of writing (2005-11-20) it is believed that both the "MD5" and "SHA-1" algorithms can no longer be considered secure and it is recommended that you use a more secure algorithm such as "SHA-256" or "Whirlpool" instead.

Support for the "MD5" algorithm is preserved in this command only because "MD5" file checksums are still very common on the Internet.

Note
The format of the data produced and used by the MD5SUM command is compatible with the Unix "md5sum" program.
Example 1

Calculate checksums for all files in the C: directory and sort the list by file name before printing it:

 1> MD5SUM C: SORT
 1bd137145fbb3c409771b6bd889adb07  c:AddBuffers
 7ab3d10a31518a011a63e5a099beb876  c:AddDataTypes
 0ca24f1b23fb52642b895010edf79b89  c:Assign
 98abb6f23ca1097898cdf98a84c6d69f  c:Avail
 891ec3cb98bd0744cbb5f7407e678c71  c:BindDrivers
Example 2

Calculate the checksums for all files on the Work: partition, sort the list and store it in a file:

 1> MD5SUM Work: SORT TO Work.Checksums
Example 3

Calculate and compare the checksums for all files listed in the file 'Work.Checksums' and print the differences:

 1> MD5SUM CHECK Work.Checksums
Example 4

Calculate the checksums for the disks in the drives DF0 and DF1:

 1> MD5SUM DEVICES df0: df1:
 b0af4fc275bf1cb26016bd6abccc2548  df0:
 fc2b0af47b01ab5bf1cc6b48d6cc2526  df1:
Example 5

List all the supported checksumming algorithms:

 1> MD5SUM Algorithm ?
 MD5SUM: Supported algorithms are MD5, SHA-1, SHA-256, SHA-384,
 SHA-512, Whirlpool.

MOUNT

Makes a device connected to the system available.

Format
MOUNT <device|pattern> [FROM <filename>] [QUIET] [REPLACE] [STARTUP <parameters>]
Template
DEVICE/A/M,FROM/K,DEBUG/S,QUIET/S,REPLACE/S,STARTUP/K/F
Location
C:

MOUNT causes AmigaDOS to recognize devices connected to the system. When the MOUNT command is issued, MOUNT looks in the DEVS:MountList file (or the optional FROM file) for the parameters of the device that is being mounted. It also looks for mount files named according to the respective device in the directories "DEVS:DOSDrivers" and "SYS:Storage/DOSDrivers". MOUNT commands are usually placed in the Startup-Sequence file.

In place of a device name, a wildcard pattern can be used to identify the names of the mount files to be used. For example, to mount all devices in "DEVS:DOSDrivers" you would use the following command:

1> Mount DEVS:DOSDrivers/~(#?.info)

MOUNT will complain if the device to be mounted has already been mounted (the warning message can be hidden by using the QUIET option). If you actually wanted to remount the device, perhaps with new parameters, you can use the REPLACE option: this will have the same effect as issuing the "ASSIGN <device name> DISMOUNT" command before the respective device is mounted again. Note that this is not normally a good idea since only few file systems and handlers will support it.

Some handlers need to receive additional instructions when they are started. Traditionally, such information goes into the mount file, following the "STARTUP = " text. At times it is more convenient to pass these instructions directly on the MOUNT command line, which then are passed down to the handler. This is what the STARTUP option will do. Note that all devices given on the MOUNT command line will receive these startup instructions and that these instructions will never override the startup instructions given in the mount file, etc.

MOUNT will look in both the mount file and in the tooltypes of the mount file icon for keywords. The DEBUG switch can be used to tell MOUNT that it shall complain about unknown tooltypes or tooltypes which are missing an equal sign.

MOUNTINFO

Creates mount files for the file systems.

Format
MOUNTINFO [<device>] [[TO=<file name> [ADDICON]] [ACTIVATE] [DEBUG]
Template
DEVICE/A,TO/K,ADDICON/S,ACTIVATE/S,DEBUG/S
Location
C:

MOVE

Moves files or directories.

Format
MOVE
Template
FROM/A/M,TO/A,QUIET/S,BUF=BUFFERS/K/N,NOREQ/S,NOREPLACE/S,INTERACTIVE/S,FORCE/S,COPYLINKS/S,FOLLOWLINKS/S
Location
C:

NETLOGVIEWER

Captures any debug or notification messages sent by the bsdsocket.library or its clients.

Format
NETLOGVIEWER [<popup key>] [<priority>] [CX_POPUP=<no | yes>]
Template
CX_POPKEY/K,CX_PRIORITY/K/N,CX_POPUP/K
Location
C:

NETSHUTDOWN

Shuts down the network in an orderly fashion.

Format
NETSHUTDOWN [<seconds>] [QUIET]
Template
TIMEOUT/N,QUIET/S
Location
C:

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.

NVGETVAR

Prints the value of all or a named UBoot environment variable.

Format
NVGETVAR <name>
Template
NAME
Location
C:

NVGETVAR <name> will print the value of the UBoot environment variable "name". If nothing is provided for the <name>, all variables are printed.

If the requested variable does not exists, NVGETVAR will print nothing, and set the condition flag to 5 (WARN).

Example
1> NVGETVAR boot_config
AmigaOS 4.1 FE

prints the value of the boot_config variable.

OWNER

Changes the ownership of a file or directory.

Format
OWNER [FILE] {<file | pattern>} [OWNER] <name or number> [ALL] [QUIET]
Template
FILE/A/M,OWNER/A,ALL/S,QUIET/S
Location
C:

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

PATHPART

Splits and assembles directory and file names.

Format
PATHPART [DIR <path name>] [FILE <path name>] [ADD {<directory name | file name}]
Template
DIR/K,FILE/K,ADD/K/N
Location
C:

PING

Sends ICMP ECHO_REQUEST packets to network hosts.

Format
PING [-c | COUNT <number>] [-d | DEBUG] [-i | INTERVAL <wait>]
[-l | LOAD <preload>] [-n | NUMERICONLY | NUMERIC] [-q | QUIET]
[-R | RECORDROUTE] [DONTROUTE] [-s | SIZE <packet size>]
[-v | VERBOSE] [BELL] [HOST] <host name or IP address>
Template
-c=COUNT/K/N,-d=DEBUG/S,-i=INTERVAL/K/N,-l=LOAD/K/N,-n=NUMERICONLY/S=NUMERIC/S,-q=QUIET/S,-R=RECORDROUTE/S,DONTROUTE/S,-s=SIZE/K/N,-v=VERBOSE/S,BELL/S,HOST/A
Location
C:

PIPE

Connects input and output streams of Shell commands.

Format
PIPE <command>
Template
COMMAND/A/F
Location
Internal

POPCD

Returns the directory last recently saved with the PUSHCD command.

Format
POPCD
Template
(none)
Location
Internal

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>] [CLEAR] [FILES] [DIRS]
Template
FILE/A,FLAGS,ADD/S,SUB/S,ALL/S,QUIET/S,USER/S,GROUP/S,OTHER/S,CLONE/S,CLEAR/S,FILES/S,DIRS/S
Location
C:

All files have a series of protection bits stored with them which control their attributes. These bits can be altered to indicate the type of file and the file operations permitted. PROTECT is used to set or clear the protection bits of a file.

The protection bits are represented by letters:

r The file can be read.
w The file can be written to (altered).
e The file is executable (a program).
d The file can be deleted.
s The file is a script.
p The file is a pure command and can be made resident.
a The file has been archived.
h The command file should be held resident in memory after it has been used (requires that the 'p' bit is set, too)

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

To specify the entire protection field at once, simply give the letters of the bits you want set as the FLAGS argument, without any other keywords. The named bits will be set, and all the others will be 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 letter(s) of the bit(s) to set or clear, respectively, and only those bits will be changed. Don't put a 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 letter(s). You cannot both set and clear bits in the same command.

The options are:

The options are:

ALL Change the protection bits of all subdirectories and their files.
QUIET Do not display progress report messages. The local shell variable _Verbosity with a negative value has the same effect.
USER Only modify the 'user' protection bits (default).
GROUP Only modify the 'group' protection bits
OTHER Only modify the 'other' protection bits.
CLONE Change the 'group' and/or 'other' protection bits to the same value as the 'user' protection bits. Requires at least one of the USER and GROUP options, and no protection bits specified.
CLEAR Clear all protection bits.
FILES Only change the protection bits of the files found.
DIRS Only change the protection bits of the directories found.
Note
The FILES and DIRS options work together: if you use FILES and omit DIRS, then only the files will be affected and the other way round. If none of FILES and DIRS is used, all files and directories will have their protection bits changed.
Note
Since version 51.9 PROTECT doesnt allow to set the h, s, and p bits of directories. For files,
  • Setting the h bit is only possible if the s bit is not set and the p, e and r bits are set.
  • Setting the p bit is only possible if the s bit is not set and the e and r bits are set.
  • Setting the s bit is only possible when the r bit is set.
  • Setting the e bit is only possible when the r bit is set.
  • Setting the GROUP e bit is only possible when the GROUP r bit is set.
  • Setting the OTHER e bit is only possible when the OTHER r bit is set.
Example 1
1> PROTECT DF0:Memo +rw

sets only the protection bits r (readable) and w (writable) to 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".

Example 4
1> PROTECT Work:Write CLONE GROUP OTHER

The group and other protection bits of Write become a copy of the user protection bits.

Example 5
1> PROTECT Work:Save CLEAR

Clear all the protection bits of Save.

See also

PUSHCD

Saves the current directory on a stack and optionally changes it.

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

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.

REBOOT

Reboots your Amiga.

Format
REBOOT [FAST=WARMREBOOT] [WAIT=<seconds>] [SYNC]
Template
FAST=WARMREBOOT/S,WAIT/N/K,SYNC/S
Location
C:

RECORDER

Captures console output and stores it in a file.

Format
RECORDER [[TO] <file>] [APPEND] [OFF] [LINE] [SIZE <number>] [FLUSH]
Template
TO,APPEND/S,OFF/S,LINE/S,SIZE/N/K,FLUSH/S
Location
Internal

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 text> <body text> {<gadgets>} [TYPE <type>] [TO <file>] [PUBSCREEN <public screen name>] [TIMEOUTSECS <seconds>] [CHARSET <character set>] [INACTIVE]
Template
TITLE/A,BODY/A,GADGETS/A/M,TYPE/K,TO/K,PUBSCREEN/K,TIMEOUTSECS/K/N,CHARSET/K,INACTIVE/S
Location
C:

The TITLE argument specifies the title of the requester.

The BODY argument specifies the text of the requester. Line feeds can be embedded using *N. For other formatting options see the requester class autodoc: requester_cl.doc

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

The TYPE argument specifies the type of requester to display. Possible types are INFO, QUESTION, WARNING, ERROR, and INSERTDISK. If not specified, INFO is assumed when a single gadget is specified, QUESTION otherwise.

The TO argument specifies an output file where the result is written to.

The TIMEOUTSECS argument specifies the maximum number of seconds to display the requester before its closed and the result -1 is returned. Specifying 0 timeout seconds means no timeout.

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

The CHARSET argument allows to specify the character set of the strings given in the BODY and GADGETS arguments. The TITLE argument is always displayed in the character set of the screen font.

The INACTIVE argument specifies that the requester window should not be activated when opened.

The number of the selected gadget is printed as a result to the console or written to the output file. The gadgets are numbered from left to right as 1, 2, 3, ..., 0. The special result -1 is printed when the TYPE argument was INSERTDISK and a disk was inserted. 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, 0 otherwise.

Example
1> RequestChoice >ENV:rcnum "New Title" "This is my requester.*nSelect a gadget." "_OK" "_Maybe" "_Cancel"

The local Shell variable rcnum contains 1, 2, or 0 (respectively) after a gadget is selected. The script can use this value to control its later execution.

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.

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

Example
1> REQUESTFILE DRAWER Devs: TITLE "My Req" NOICONS
Sample RequestFile Requester

REQUESTSTRING

Allows AmigaDOS and ARexx scripts to use custom string requesters.

Format
REQUESTSTRING <title text> <body text> [POSITIVE <OK gadget text>] [NEGATIVE <Cancel gadget text>] [DEFSTRING <default text>] [MAXLEN=<n>] [NOTEMPTY] [INVISIBLE] [TO <filename>] [PUBSCREEN <public screen name>] [CHARSET <character set>] [INACTIVE]
Template
TITLE/A,BODY/A,POSITIVE/K,NEGATIVE/K,DEFSTRING/K,MAXLEN/K/N,NOTEMPTY/S,INVISIBLE/S,TO/K,PUBSCREEN/K,CHARSET/K,INACTIVE/S
Location
C:

The TITLE argument specifies the title of the requester.

The BODY argument specifies the text of the requester. Line feeds can be embedded using *N. For other formatting options see the requester class autodoc: requester_cl.doc

The POSITIVE argument specifies the text for the OK gadget. Default is the localized "_OK" text.

The NEGATIVE argument specifies the text for the Cancel gadget. Default is the localized "_Cancel" text.

The DEFSTRING argument specifies the default text for the string gadget. Default is empty string.

The MAXLEN argument specifies the maximum length of the string. Default is 256. The length does not include the NULL termination, e.g. "A" is considered to have a length of 1. Negative and zero values are silently ignored and replaced with the default value.

The NOTEMPTY switch does not allow the user to enter an empty string.

The INVISIBLE switch specifies that the text in the string gadget should be displayed with '*' characters, e.g. for entering passwords that should not be visible to a person behind the user.

The TO argument specifies the file where to store the result string. If not specified, the string is written to the default output.

The PUBSCREEN argument specifies the name of the public screen where to open the requester window. If not specified, the current default public screen is used. The screen is brought to the front before opening the window if necessary, and to the back after closing the window if it was brought to the front before.

The CHARSET argument allows to specify the character set of the string given in the BODY, POSITIVE, NEGATIVE, and DEFSTRING arguments. The TITLE argument is always displayed in the character set of the screen font.

The INACTIVE argument specifies that the requester window should not be activated when opened.

RequestString will return with RETURN_FAIL (20) on any failure, with RETURN_WARN (5) if the user clicked the Cancel gadget (the result string is the provided default string in this case), and with RETURN_OK (0) otherwise. The result string (or the default string, if the user did cancel the requester) will be enclosed in quotation marks, then terminated with linefeed, and written to the file specified with the TO argument or the default output.

Example
1> Set Title "Edit file comment"
1> Set Body "Comment for MyFile:"
1> Set Def "`List MyFile LFORMAT %c`"
1> Set Note `RequestString "$Title" "$Body" DEFSTRING "$Def"`
1> FileNote MyFile "$Note"
Sample RequestString Requester

RESIDENT

Displays and modifies the list of resident commands.

Format
RESIDENT [<resident name>] [<filename>] [REMOVE] [ADD] [REPLACE] [PURE | FORCE] [SYSTEM]
Template
NAME,FILE,REMOVE/S,ADD/S,REPLACE/S,PURE=FORCE/S,SYSTEM/S
Location
Internal

RESIDENT loads a command into memory and adds it to the resident list maintained by the Shell. This allows the command to be executed without reloading it from disk each time. If RESIDENT is invoked with no options, it lists the programs on the resident list.

To be made resident, a command should be pure, meaning that it is both re-entrant and re-executable. A re-entrant command can properly support independent use by two or more programs at the same time. A re-executable command dies not have to be reloaded to be executed again. Commands that have these characteristics are called pure and have the p (pure) protection bit set.

The following commands cannot be made resident: BINDDRIVERS, CONCLIP, IPREFS, LOADRESOURCE, LOADWB, and SETPATCH.

LIST the C: directory to check for the presence of the p protection bit to determine which commands are pure.

Many of the commands in the C: directory, as well as the MORE command in Utilities, are pure commands and can be made resident. If a command does not have its pure bit set, it probably cannot be made resident safely. (Setting the pure bit does not make a command or program pure.)

The REPLACE option is the default option and does not need to be explicitly stated. If no <resident name> is specified (for example, only a file name is specified), RESIDENT uses the file name portion as the name on the resident list. The full path to the file must be used.

If a <resident name> is specified and RESIDENT finds a program with that name already on the list, it attempts to replace the command. That <resident name> must be used to reference the resident version of the command. The replacement succeeds only if the already-resident command is not in use.

To override REPLACEment and make several versions of a command resident simultaneously, use the ADD option, giving a different <resident name> for each version loaded.

If the System option is specified, the command is added to the system portion of the resident list and becomes available as a system component. Any commands added to the resident list with the SYSTEM option cannot be removed. To list these files on the RESIDENT list, you must specify the SYSTEM option.

The PURE option forces RESIDENT to load commands that are not marked as pure and use them to test the pureness of other commands and programs. Use the PURE option with caution. Be sure the programs that you make RESIDENT meet the criteria to be resident or be careful to use the command in only one process at a time.

The availability of internal commands can also be controlled with RESIDENT. To deactivate an Internal command (for example, if an application has its own command of the same name), use RESIDENT <command> REMOVE. The command can be reactivated with the REPLACE option.

Example 1
1> RESIDENT C:COPY

makes the COPY command resident (replaces any previous version).

Example 2
1> RESIDENT Copy2 DF1:C/COPY ADD

adds another version of COPY to the resident list, under the name Copy2.

Example 3
1> RESIDENT Xdir DF1:C/Xdir PURE

makes an experimental, non-pure version of the DIR command resident.

Example 4
1> RESIDENT CD REMOVE

makes the Internal CD command unavailable.

Example 5
1> RESIDENT CD REPLACE

restores the CD command to the system.

See also

ROADSHOWCONTROL

Displays and changes the internal configuration options of the TCP/IP stack.

Format
ROADSHOWCONTROL [GET <option>] [SET <option>=<value>] [SAVE] [QUIET]
Template
GET/K,SET/K/F,SAVE/S,QUIET/S
Location
C:

RUN

Executes commands as background processes.

Format
RUN <command...> [{+ <command>}]
Template
COMMAND/F
Location
Internal

RUN is used to start background processes. A background process does not open its own window for input or output and does not take over the parent Shell.

RUN attempts to execute the <command> and any arguments entered on the command line. You can RUN multiple command lines by separating them with plus signs (+). If you press Return after a plus sign, RUN interprets the next line as a continuation of the same command line.

To make it possible to close the Shell window in which the process was started, redirect the output of RUN with RUN >NIL: <command>.

A new background Shell has the same search path and command stack size as the Shell from which RUN is given.

You can RUN commands stored to the resident list. Resident commands are checked before commands in the command path. A Shell started with RUN NEWSHELL uses the default startup file, S:Shell-startup.

Example 1
1> RUN COPY Text TO PRT:+
DELETE Text +
ECHO "Printing finished"

prints the Text file by copying it to the printer device, deletes it, then displays the given message. Plus signs string together the command lines, causing each command to be run after the previous command finishes.

Example 2
1> RUN EXECUTE Comseq

executes, in the background, all the commands in the script file Comseq.

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

RX

Launches an ARexx program.

Format
RX <name> [<arguments>]
Template
NAME,ARG/F
Location
C:

RX launches an ARexx program. If the specified name includes an explicit path, only that directory is searched for the program; otherwise, the current directory and REXX: are checked for a program with the given name. The optional argument string is passed to the program.

In place of the name of an ARexx program to be launched you can also write a short list of ARexx statements which will be executed as a single line command. To do so, enclose the statements in double quotes.

The RX program will try to start the ARexx resident process before it will attempt to launch a program.

You can also use the RX program from Workbench. Make it the default tool of an ARexx program, then double-click on the icon. The following tool types are supported:

CONSOLE Overrides the default output console window specification, "CON://640/100/WAIT/RX Output".
CMD Use the command given in the tool type text rather than attempt to execute the ARexx program the icon is attached to.
STARTUP If present, try to run a different program before the ARexx program is launched. If this is omitted, "RexxMast" will be launched.
Example 1

Launch the ARexx command "script.rexx" with argument "Names.txt".

1> RX script.rexx Names.txt
Example 2

Launch the ARexx command "script.rexx". Note that the command name suffix is omitted and defaults to ".rexx"

1> RX script
Example 3

Evaluate an ARexx expression.

1> RX "say 17 / 23"

RXC

Closes the ARexx resident process.

Format
RXC
Template
(none)
Location
C:

RXC closes the ARexx resident process. The "REXX" public port is withdrawn immediately and the resident process exits as soon as the last ARexx program finishes. No new programs can be launched after a close request.

RXLIB

Manages and lists ARexx function libraries and hosts.

Format
RXLIB <name> [<priority> [<offset> [<version>]]]
Template
NAME,PRIORITY,OFFSET/N,VERSION/N
Location
C:

RXLIB manages function libraries and hosts, so that they can be called from ARexx, and it can also be used to list which libraries are currently defined.

To add a new library, specify its name, priority and offset value. The priority must be in the range -100.100. For your library to be invoked before the resident process has a look at a command, make sure that the priority is greater than -60. The offset value is the actual library vector offset and should be documented with each library. The last parameter, the required library version, can usually be omitted in which case 0 will be used (any library version is acceptable).

Note
Do not get the library offset value wrong or ARexx will crash when the next attempt is made to call a function library!

To add a new host, specify its name and priority, but omit the offset value and version number. Note that at the time the host is added no test is performed to verify that a public message port of that name exists.

Note
You cannot directly replace an existing function library or host with a new entry. The old entry needs to be removed before the new entry can be added.

To remove a library or host, specify its name and omit the priority, offset, and version parameters.

To list all function libraries and hosts, omit the library name, priority, offset, and version parameters.

Example 1

Add "rexxsupport.library":

1> RXLIB rexxsupport.library 0 -30
Example 2

Show all active libraries and hosts:

1> RXLIB
rexxsupport.library (library)
REXX (host)
Example 3

Remove "rexxsupport.library":

1> RXLIB rexxsupport.library
Example 4

Add a new host by the name of "MORE":

1> RXLIB MORE -1

RXSET

Manage or list the Clip List.

Format
RXSET [<name> [[=] <value>]]
Template
NAME,VALUE/F
Location
C:

RXSET adds a name-value pair to the Clip List. Name strings are assumed to be in mixed case. If a pair with the same name already exists, its value is replaced with the current string. If a name without a value string is given, the entry is removed from the Clip List. If RXSET is invoked without arguments, it will list all name-value pairs in the Clip List.

Note
The original RXSET command would preserve the exact number of blank spaces in the 'value' string. This is not the case with this new version of the command, which will always put exactly one blank space between the words in the 'value' string. If you need an exact number of blank spaces, you should put them into double quotes.
Example 1

Add the name-value pair "answer=42" to the Clip List (more than one syntax is supported; all three examples are equivalent):

1> RXSET answer=42
1> RXSET answer = 42
1> RXSET answer 42
Example 2

Show the current Clip List contents:

1> RXSET
answer=42

SEARCH

Looks for the specified text string in the files of the specified directories.

Format
SEARCH [FROM] <name|pattern> [SEARCH|NAME] <string|pattern>
[ALL] [NONUM] [QUIET] [QUICK] [FILE] [PATTERN] [CASE]
Template
FROM/M,SEARCH/A,ALL/S,NONUM/S,QUIET/S,QUICK/S,FILE/S,PATTERN/S,CASE/S
Location
C:

SEARCH looks through all the files in the FROM directory for the given SEARCH string. (The FROM and SEARCH keywords are optional.) If the ALL switch is given, SEARCH also looks through all the subdirectories of the FROM directory. SEARCH displays the name of the file being searched and any line that contains the text sought. You must place quotation marks around any search text containing a space. The search is case-indifferent (capitalization is ignored) unless the CASE switch was specified.

The options are as follows:

NONUM Line numbers are not printed with the strings.
QUIET Searches quietly; filenames being searched are not displayed. The local shell variable _Verbosity with a negative value has the same effect.
QUICK Uses a more compact output format.
FILE Looks for a file by the specified name, rather than for a string in the file.
PATTERN Uses pattern matching in the search.
CASE Uses case sensitive string comparison in the search.

SEARCH leaves a 0 in the condition flag if the object is found, and a 5 (WARN) otherwise. This makes it useful in scripts. To abandon the search of the current file and continue to the next file, if any, type Ctrl-D. SEARCH is aborted when a Ctrl-C is typed.

Example 1
1> Search DEVS: alternative
     Keymaps (dir)
     Printers (dir)
   clipboard.device..
   MountList..

   14 \* This is an example of an alternative type of non-filing device mount.
   narrator.device..
   parallel.device..
   printer.device..
   serial.device..
   system-configuration..

searches through the DEVS: directory for the word alternative. It is found on line 14 of the MountList file.

Example 2
1> SEARCH Universe: "Intelligent life" ALL

searches for Intelligent life (or intelligent life) in every file on the volume Universe:.

Example 3
1> Work:#?.source SEARCH Progtest.c?? FILE PATTERN

locates all Progtest.c files with a two-character suffix in directories ending in .source in the Work volume.

SET

Sets a local vaiable.

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

SET with no arguments lists the current local variables.

SET with <name> and <string> arguments creates a new environment variable. The first word after SET is taken as the <name>. Everything else on the command line is taken as the <string> argument. Quotation marks are not required.

An environment variable created with SET is local to the Shell in which it was created. If you create a new Shell with the NEWSHELL command, that Shell also recognizes any variables created in its parent Shell. However, if you create a new Shell with the Execute Command Workbench menu item or by opening the Shell icon, variables created with SET are not recognized in the new Shells.

You can call environment variables in a script or on a command line by placing a dollar sign ($) in front of the variable name.

To remove a local variable definition, use the UNSET command.

Examples
1> SET Origin This process launched from icon

creates the local variable Origin that sores a reminder that a Shell was invoked from an icon rather than a NEWSHELL.

1> ECHO $Origin
This process launched from icon
See also

SETCLOCK

Sets or reads the battery backed-up hardware clock.

Format
SETCLOCK LOAD | SAVE | RESET
Template
LOAD/S,SAVE/S,RESET/S
Location
C:

SETCLOCK SAVE sets the date and time of the battery backed-up hardware clock (if your system has one) from the current system time, which is set with the Time editor or with the DATE command. SETCLOCK SAVE is typically used after a DATE command.

SETCLOCK LOAD sets the current system time from the battery backed-up clock. This is done automatically during the boot process.

The RESET option resets the clock completely. Use this option if the clock is accidentally turned off or LOAD and SAVE do not appear to work correctly.

Example
1> DATE 22-Jan-93 07:15:25
1> SETCLOCK SAVE

saves the date, January 22, 1993, and the time, 7:15 a.m., to the battery backed-up hardware clock. When the system is booted, the system clock is set with the time saved in the hardware clock.

Some Amiga models do not have battery backed-up clocks unless an expansion unit has been installed.

See also

SETDATE

Change the timestamp of a file or directory.

Format
SETDATE <file|pattern> [<date>] [<time>] [ALL] [QUIET] [FILES] [DIRS]
Template
FILE/A,DATE,TIME,ALL/S,QUIET/S,FILES/S,DIRS/S
Location
C:

SETDATE changes the timestamp (date and time of creation or last change) of a file or directory. SETDATE <file> changes the date/time of the file to the current system date/time. SETDATE does not affect the software or hardware clocks.

The output of the DATE command may be used as input to SETDATE.

The options are:

ALL Change the dates of all subdirectories and their files.
QUIET If the QUIET option is given, screen output is suppressed. The local shell variable _Verbosity with a negative value has the same effect.
FILES Only change the dates of the files found.
DIRS Only change the dates of the directories found.
Note
The FILES and DIRS options work together: if you use FILES and omit DIRS, then only the files will be affected and the other way round. If none of FILES and DIRS is used, all files and directories will have their dates changed.
Example 1
1> SETDATE TestFile

changes the date and time associated with TestFile to the current date and time.

Example 2
1> SETDATE TestFile 16-09-89 15:25:52

change the date and time associated with TestFile to September 16, 1989, 3:25 p.m.

See also

SETENV

Sets a global variable.

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

SETENV with no arguments lists the current global variables.

SETENV with <name> and <string> arguments creates a new global environment variable. The first word after SETENV is taken as the <name>. Everything else on the command line is taken as the <string> argument. Quotation marks are not required.

Global variables are stored in the ENV: directory and are available to all processes. However, if a local variable (defined by SET) and a global variable share the same name, the local variable is used.

Environment variables are called by scripts or other commands by including a dollar sign ($) in front of the variable name.

To remove a global variable definition, use the UNSETENV command.

Example 1
1> SETENV Editor Extras:Tools/MEmacs

creates the environment variable Editor That can be used with the MORE utility. This specifies the editor as MEmacs, located in the Tools drawer of EXTRAS:. The variable Editor is available in any Shell.

Example 2
1> SETENV Editor C:ED

same as above, only the editor specified is ED.

1> ECHO $Editor
C:ED
See also

SETFONT

Changes the font of the current Shell.

Format
SETFONT <size> [SCALE] [PROP] [ITALIC] [BOLD] [UNDERLINE] [CHARSET]
Template
NAME/A,SIZE/A,SCALE/S,PROP/S,ITALIC/S,BOLD/S,UNDERLINE/S,CHARSET/K
Location
C:

SETFONT lets you change the font used in a particular Shell window, overriding the System Default Font setting specified in the Font preferences editor. SETFONT is only effective in the window in which it is invoked.

You must specify both a font name and a size when using the SETFONT command.

Invoking SETFONT will clear the Shell window of its current contents and display a new prompt, in the new font, at the top of the window.

The other options are:

SCALE Enables bitmap font scaling.
PROP Allows proportional fonts.
ITALIC The font will be italic.
BOLD The font will be boldface.
UNDERLINE The font will be underlined.
CHARSET The font will be in the specified charset, not in the current default charset.
Example
1> SETFONT Fixed 13 BOLD UNDERLINE CHARSET ISO-8859-7

The Shell window will clear, and the new prompt will be in 13 pixels Fixed.font, underlined and boldface, with greek glyphs for the characters above 0xA0.

SETFONTCHARSET

Adds charset tag and version string to a FontContentsHeader file.

Format
SETFONTCHARSET <sourcefontfile> <charset> [VERSTRING]
Template
BITMAPFONTFILENAME/A,CHARSET/A,VERSTRING/K
Location
C:

SETKEYBOARD

Changes the keymap used by the current Amiga console.

Format
SETKEYBOARD <keymap> [CHARSET]
Template
KEYMAP/A,CHARSET/K
Location
C:

SETKEYBOARD specifies the keymap used by the Amiga for the current console. The keymap file must be present in KEYMAPS: for SETKEYBOARD to find it.

The other options are:

CHARSET The keymap will be adjusted to the specified charset, not to the current default charset. You should only use this option when you also selected a different font charset with the SETFONT command. The adjustment does e.g. include the deadkey combinations which otherwise would produce confusing results.
Example 1

To change to a French Canadian keymap, enter:

1> SETKEYBOARD cdn_f
Example 2

To switch the current console to ISO-8859-15 charset and german keymap, type:

1> SETFONT topaz 8 CHARSET ISO-8859-15
1> SETKEYBOARD d_ISO-8859-15 CHARSET ISO-8859-15

SHOWNETSTATUS

Displays various information about the status of the network configuration.

Format
SHOWNETSTATUS [INTERFACE=<itf>[,<itf>...]] [INTERFACES] [ARPCACHE=ARP] [ROUTES] [DNS=DOMAINNAMESERVERS] [ICMP] [IGMP] [IP] [MB=MEMORY] [MR=MULTICASTROUTING] [RT=ROUTING] [TCP] [UDP] [TCPSOCKETS] [UDPSOCKETS] [NAMES] [ALL] [REPEAT] [QUIET]
Template
<