AmigaOS Documentation Wiki - User contributions [en]

Math Libraries

2023-08-03T09:53:32Z

Rob Cranley: /* FFP Floating Point Data Format */ Added "(bit 7)" to identify the sign bit as it was not otherwise obvious

== Introduction ==

The math libraries described in this section are implemented in 68K assembly language and are designed to only be callable from 68K code. They are provided for backwards compatibility with pre-4.0 versions of AmigaOS.

For AmigaOS 4.0 and higher the math libraries you choose will depend on the application. A vast majority of the time the built-in math routines provided by the [[Newlib_Library|Newlib Library]] and built-in functions of GCC will suffice.

== Math Libraries ==

This chapter describes the structure and calling sequences required to access the Motorola Fast Floating Point (FFP), the IEEE single-precision math libraries and the IEEE double-precision math libraries via the Amiga-supplied interfaces.

In its present state, the FFP library consists of three separate entities: the basic math library, the transcendental math library, and C and assembly-language interfaces to the basic math library plus FFP conversion functions. The IEEE single-precision and the double-precision libraries each presently consists of two entities: the basic math library and the transcendental math library.

{{Note|title=Open Each Library Separately|text=Each Task using an IEEE math library must open the library itself. Library base pointers to these libraries may ''not'' be shared. Libraries can be context sensitive and may use the Task structure to keep track of the current context. Sharing of library bases by Tasks may seem to work in some systems. This is true for any of the IEEE math libraries.}}

Depending on the compiler used, it is not always necessary to explicitly call the library functions for basic floating point operations as adding, subtracting, dividing, etc. Consult the manual supplied with the compiler for information regarding the compiler options for floating point functions.

== Math Libraries and Functions ==

There are six math libraries providing functions ranging from adding two floating point numbers to calculating a hyperbolic cosine. They are:

; mathffp.library
: the basic function library

; mathtrans.library
: the FFP transcendental math library

; mathieeesingbas.library
: the IEEE single-precision library

; mathieesingtrans.library
: the IEEE single-precision transcendental library

; mathieeedoubbas.library
: the IEEE double-precision library

; mathieesingtrans.library
: the IEEE double-precision transcendental library

== FFP Floating Point Data Format ==

FFP floating-point variables are defined within C by the float or FLOAT directive. In assembly language they are simply defined by a DC.L/DS.L statement. All FFP floating-point variables are defined as 32-bit entities (longwords) with the following format:

_____________________________________________
| |
| MMMMMMMM MMMMMMMM MMMMMMMM EEEEEEE |
| 31 23 15 7 |
|_____________________________________________|

The mantissa is considered to be a binary fixed-point fraction; except for 0, it is always normalized (the mantissa is shifted over and the exponent adjusted, so that the mantissa has a 1 bit in its highest position). Thus, it represents a value of less than 1 but greater than or equal to 1/2.

The sign bit (bit 7) is reset (0) for a positive value and set (1) for a negative value.

The exponent is the power of two needed to correctly position the mantissa to reflect the number's true arithmetic value. It is held in excess-64 notation, which means that the two's-complement values are adjusted upward by 64, thus changing $40 (-64) through $3F (+63) to $00 through $7F. This facilitates comparisons among floating-point values.

The value of 0 is defined as all 32 bits being 0s. The sign, exponent, and mantissa are entirely cleared. Thus, 0s are always treated as positive.

The range allowed by this format is as follows:

; DECIMAL
: 9.22337177 * 10^18 > +VALUE > 5.42101070 * 10^-20
: -9.22337177 * 10^18 < -VALUE < -2.71050535 * 10^-20

; BINARY (HEXADECIMAL):
: .FFFFFF * 2^63 > +VALUE > .800000 * 2^-63
: -.FFFFFF * 2^63 < -VALUE < -.800000 * 2^-64

Remember that you cannot perform ''any'' arithmetic on these variables without using the fast floating-point libraries. The formats of the variables are ''incompatible'' with the arithmetic format of C-generated code; hence, all floating-point operations are performed through function calls.

== FFP Basic Mathematics Library ==

The FFP basic math library contains entries for the basic mathematics functions such as add, subtract and divide. It resides in ROM and is opened by calling OpenLibrary() with "mathffp.library" as the argument.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathffp.h>

#include <clib/mathffp_protos.h>

struct Library *MathBase;

VOID main()
{
if (MathBase = OpenLibrary("mathffp.library", 0))
{
. . .

CloseLibrary(MathBase);
}
else
printf("Can't open mathffp.library\n");
}
</syntaxhighlight>

The global variable '''MathBase''' is used internally for all future library references.

=== FFP Basic Functions ===

; SPAbs() FLOAT SPAbs( FLOAT parm );
: Take absolute value of FFP variable.

; SPAdd() FLOAT SPAdd( FLOAT leftParm, FLOAT rightParm);
: Add two FFP variables.

; SPCeil() FLOAT SPCeil( FLOAT parm );
: Computer largest integer less than or equal to variable.

; SPCmp() LONG SPCmp( FLOAT leftParm, FLOAT rightParm)
: Compare two FFP variables.

; SPDiv() FLOAT SPDiv( FLOAT leftParm, FLOAT rightParm);
: Divide two FFP variables.

; SPFix() LONG SPFix( FLOAT parm );
: Convert FFP variable to integer.

; SPFloor() FLOAT SPFloor( FLOAT parm );
: Compute least integer greater than or equal to variable.

; SPFlt() FLOAT SPFlt( long integer );
: Convert integer variable to FFP.

; SPMul() FLOAT SPMul( FLOAT leftParm, FLOAT rightParm);
: Multiply two FFP variables.

; SPNeg() FLOAT SPNeg( FLOAT parm );
: Take two's complement of FFP variable.

; SPSub() FLOAT SPSub( FLOAT leftParm, FLOAT rightParm);
: Subtract two FFP variables.

; SPTst() LONG SPTst( FLOAT parm );
: Test an FFP variable against zero.

Be sure to include the proper data type definitions shown below.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathffp.h>

#include <clib/mathffp_protos.h>

struct Library *MathBase;

VOID main()
{
FLOAT f1, f2, f3;
LONG i1;

if (MathBase = OpenLibrary("mathffp.library", 0))
{
i1 = SPFix(f1); /* Call SPFix entry */
f1 = SPFlt(i1); /* Call SPFlt entry */

if (SPCmp(f1,f2)) {}; /* Call SPCmp entry */
if (!(SPTst(f1))) {}; /* Call SPTst entry */

f1 = SPAbs(f2); /* Call SPAbs entry */
f1 = SPNeg(f2); /* Call SPNeg entry */
f1 = SPAdd(f2, f3); /* Call SPAdd entry */
f1 = SPSub(f2, f3); /* Call SPSub entry */
f1 = SPMul(f2, f3); /* Call SPMul entry */
f1 = SPDiv(f2, f3); /* Call SPDiv entry */
f1 = SPCeil(f2); /* Call SPCeil entry */
f1 = SPFloor(f2); /* Call SPFloor entry */

CloseLibrary(MathBase);
}
else
printf("Can't open mathffp.library\n");
}
</syntaxhighlight>

The assembly language interface to the FFP basic math routines is shown below, including some details about how the system flags are affected by each operation. The access mechanism is:

<pre>
MOVEA.L _MathBase,A6
JSR _LVOSPFix(A6)
</pre>

{| class="wikitable"
|+ FFP Basic Assembly Functions
! Function
! Input
! Output
! Condition Codes
|-
| _LVOSPAbs
| D0 = FFP argument
| D0 = FFP absolute value
| N = 0 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined
|-
| _LVOSPAdd
| D1 = FFP argument 1 
D0 = FFP addition
| D0 = FFP addition of arg1 + arg2
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result overflowed 
C = undefined 
Z = undefined
|-
| _LVOSPCeil
| D0 = FFP argument
| D0 = least integer >= arg
| N = 1 if result is negative 
Z = 1 if result is zero 
V = undefined 
C = undefined 
Z = undefined
|-
| _LVOSPCmp
| D1 = FFP argument 1 
D0 = FFP argument 2 
| D0 = +1 if arg1 > arg2 
D0 = -1 if arg1 < arg2 
D0 = 0 if arg1 = arg2
| N = 0 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined 
GT = arg2 > arg1 
GE = arg2 >= arg1 
EQ = arg2 = arg1 
NE = arg2 != arg1 
LT = arg2 < arg1 
LE = arg2 <= arg1
|-
| _LVOSPDiv
| D1 = FFP argument 1 
D0 = FFP argument 2
| D0 = FFP division of arg2/arg1
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result overflowed 
C = undefined 
Z = undefined
|-
| _LVOSPFix
| D0 = FFP argument
| D0 = Integer (two's complement)
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if overflow occurred 
C = undefined 
X = undefined
|-
| _LVOSPFloor
| D0 = FFP argument
| D0 = largest integer <= argument
| N = 1 if result is negative
Z = 1 if result is zero 
V = undefined 
C = undefined 
Z = undefined
|-
| _LVOSPFlt
| D0 = Integer (two's complement)
| D0 = FFP result
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined
|-
| _LVOSPMul
| D0 = FFP argument 1 
D1 = FFP argument 2
| D0 = FFP multiplication of arg1 * arg2
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result overflowed 
C = undefined 
Z = undefined
|-
| _LVOSPNeg
| D0 = FFP argument
| D0 = FFP negated
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined
|-
| _LVOSPSub
| D1 = FFP argument 1 
D0 = FFP argument 2
| D0 = FFP subtraction of arg2 - arg1
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result overflowed 
C = undefined 
Z = undefined
|-
| _LVOSPTst
| D1 = FFP argument 
''Note'': This routine trashes the argument in D1.
| D0 = +1 if arg > 0.0 
D0 = -1 if arg < 0.0 
D0 = 0 if arg = 0.0
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined 
EQ = arg = 0.0 
NE = arg != 0.0 
PL = arg >= 0.0 
MI = arg < 0.0
|}

== FFP Transcendental Mathematics Library ==

The FFP transcendental math library contains entries for the transcendental math functions sine, cosine, and square root. It resides on disk and is opened by calling OpenLibrary() with "mathtrans.library" as the argument.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathffp.h>

#include <clib/mathffp_protos.h>
#include <clib/mathtrans_protos.h>

struct Library *MathTransBase;

VOID main()
{
if (MathTransBase = OpenLibrary("mathtrans.library",0))
{
.
.
.
CloseLibrary(MathTransBase);
}
else
printf("Can't open mathtrans.library\n");
}
</syntaxhighlight>

The global variable MathTransBase is used internally for all future library references. Note that the transcendental math library is dependent upon the basic math library, which it will open if it is not open already. If you want to use the basic math functions in conjunction with the transcendental math functions however, you have to specifically open the basic math library yourself.

=== FFP Transcendental Functions ===

; SPAsin() FLOAT SPAsin( FLOAT parm );
: Return arcsine of FFP variable.

; SPAcos() FLOAT SPAcos( FLOAT parm );
: Return arccosine of FFP variable.

; SPAtan() FLOAT SPAtan( FLOAT parm );
: Return arctangent of FFP variable.

; SPSin() FLOAT SPSin( FLOAT parm );
: Return sine of FFP variable. This function accepts an FFP radian argument and returns the trigonometric sine value. For extremely large arguments where little or no precision would result, the computation is aborted and the "V" condition code is set. A direct return to the caller is made.

; SPCos() FLOAT SPCos( FLOAT parm );
: Return cosine of FFP variable. This function accepts an FFP radian argument and returns the trigonometric cosine value. For extremely large arguments where little or no precision would result, the computation is aborted and the "V" condition code is set. A direct return to the caller is made.

; SPTan() FLOAT SPTan( FLOAT parm );
: Return tangent of FFP variable. This function accepts an FFP radian argument and returns the trigonometric tangent value. For extremely large arguments where little or no precision would result, the computation is aborted and the "V" condition code is set. A direct return to the caller is made.

; SPSincos() FLOAT SPSincos( FLOAT *cosResult, FLOAT parm);
: Return sine and cosine of FFP variable. This function accepts an FFP radian argument and returns the trigonometric sine as its result and the trigonometric cosine in the first parameter. If both the sine and cosine are required for a single radian value, this function will result in almost twice the execution speed of calling the SPSin() and SPCos() functions independently. For extremely large arguments where little or no precision would result, the computation is aborted and the "V" condition code is set. A direct return to the caller is made.

; SPSinh() FLOAT SPSinh( FLOAT parm );
: Return hyperbolic sine of FFP variable.

; SPCosh() FLOAT SPCosh( FLOAT parm );
: Return hyperbolic cosine of FFP variable.

; SPTanh() FLOAT SPTanh( FLOAT parm );
: Return hyperbolic tangent of FFP variable.

; SPExp() FLOAT SPExp( FLOAT parm );
: Return ''e'' to the FFP variable power. This function accepts an FFP argument and returns the result representing the value of ''e'' (2.71828...) raised to that power.

; SPLog() FLOAT SPLog( FLOAT parm );
: Return natural log (base ''e'') of FFP variable.

; SPLog10() FLOAT SPLog10( FLOAT parm );
: Return log (base 10) of FFP variable.

; SPPow() FLOAT SPPow( FLOAT power, FLOAT arg );
: Return FFP arg2 to FFP arg1.

; SPSqrt() FLOAT SPSqrt( FLOAT parm );
: Return square root of FFP variable.

; SPTieee() FLOAT SPTieee( FLOAT parm );
: Convert FFP variable to IEEE format

; SPFieee() FLOAT SPFieee( FLOAT parm );
: Convert IEEE variable to FFP format.

Be sure to include proper data type definitions, as shown in the example below.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathffp.h>

#include <clib/mathffp_protos.h>
#include <clib/mathtrans_protos.h>

struct Library *MathTransBase;

VOID main()
{
FLOAT f1, f2, f3;
FLOAT i1;

if (MathTransBase = OpenLibrary("mathtrans.library",33))
{
f1 = SPAsin(f2); /* Call SPAsin entry */
f1 = SPAcos(f2); /* Call SPAcos entry */
f1 = SPAtan(f2); /* Call SPAtan entry */

f1 = SPSin(f2); /* Call SPSin entry */
f1 = SPCos(f2); /* Call SPCos entry */
f1 = SPTan(f2); /* Call SPTan entry */
f1 = SPSincos(&f3, f2); /* Call SPSincos entry */

f1 = SPSinh(f2); /* Call SPSinh entry */
f1 = SPCosh(f2); /* Call SPCosh entry */
f1 = SPTanh(f2); /* Call SPTanh entry */

f1 = SPExp(f2); /* Call SPExp entry */
f1 = SPLog(f2); /* Call SPLog entry */
f1 = SPLog10(f2); /* Call SPLog10 entry */
f1 = SPPow(f2); /* Call SPPow entry */
f1 = SPSqrt(f2); /* Call SPSqrt entry */

i1 = SPTieee(f2); /* Call SPTieee entry */
f1 = SPFieee(i1); /* Call SPFieee entry */

CloseLibrary(MathTransBase);
}
else
printf("Can't open mathtrans.library\n");
}
</syntaxhighlight>

The Amiga assembly language interface to the FFP transcendental math routines is shown below, including some details about how the system flags are affected by the operation. This interface resides in the library file ''amiga.lib'' and must be linked with the user code. Note that the access mechanism from assembly language is:

<pre>
MOVEA.L _MathTransBase,A6
JSR _LVOSPAsin(A6)
</pre>

{| class="wikitable"
|+ FFP Transcendental Assembly Functions
! Function
! Input
! Output
! Condition Codes
|-
| _LVOSPAsin
| D0 = FFP argument
| D0 = FFP arcsine radian
| N = 0
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined
|-
| _LVOSPAcos
| D0 = FFP argument
| D0 = FFP arccosine radian
| N = 0 
Z = 1 if result is zero 
V = 1 if overflow occurred 
C = undefined 
X = undefined
|-
| _LVOSPAtan
| D0 = FFP argument
| D0 = FFP arctangent radian
| N = 0 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined
|-
| _LVOSPSin
| D0 = FFP argument in radians
| D0 = FFP sine
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result is meaningless (that is, input magnitude too large) 
C = undefined 
X = undefined
|-
| _LVOSPCos
| D0 = FFP argument in radians
| D0 = FFP cosine
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result is meaningless (that is, input magnitude too large) 
C = undefined 
X = undefined
|-
| _LVOSPTan
| D0 = FFP argument in radians
| D0 = FFP tangent
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result is meaningless (that is, input magnitude too large) 
C = undefined 
X = undefined
|-
| _LVOSPSincos
| D0 = FFP argument in radians 
D1 = Address to store cosine result
| D0 = FFP sine 
(D1) = FFP cosine
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result is meaningless (that is, input magnitude too large) 
C = undefined 
X = undefined
|-
| _LVOSPSinh
| D0 = FFP argument in radians
| D0 = FFP hyperbolic sine
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if overflow occurred 
C = undefined 
X = undefined
|-
| _LVOSPCosh
| D0 = FFP argument in radians
| D0 = FFP hyperbolic cosine
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if overflow occurred 
C = undefined 
X = undefined
|-
| _LVOSPTanh
| D0 = FFP argument in radians
| D0 = FFP hyperbolic tangent
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if overflow occurred 
C = undefined 
X = undefined
|-
| _LVOSPExp
| D0 = FFP argument
| D0 = FFP exponential
| N = 0 
Z = 1 if result is zero 
V = 1 if overflow occurred 
C = undefined 
Z = undefined
|-
| _LVOSPLog
| D0 = FFP argument
| D0 = FFP natural logarithm
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if argument negative or zero 
C = undefined 
Z = undefined
|-
| _LVOSPLog10
| D0 = FFP argument
| D0 = FFP logarithm (base 10)
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if argument negative or zero 
C = undefined 
Z = undefined
|-
| _LVOSPPow
| D0 = FFP exponent value 
D1 = FFP argument value
| D0 = FFP result of arg taken to exp power
| N = 0 
Z = 1 if result is zero 
V = 1 if result overflowed or arg < 0 
C = undefined 
Z = undefined
|-
| _LVOSPSqrt
| D0 = FFP argument
| D0 = FFP square root
| N = 0 
Z = 1 if result is zero 
V = 1 if argument was negative 
C = undefined 
Z = undefined
|-
| _LVOSPTieee
| D0 = FFP format argument
| D0 = IEEE floating-point format
| N = 1 if result is negative 
Z = 1 if result is zero 
V = undefined 
C = undefined 
Z = undefined
|-
| _LVOSPFieee
| D0 = IEEE floating-point format argument
| D0 = FFP format
| N = undefined 
Z = 1 if result is zero 
V = 1 if result overflowed 
C = undefined 
Z = undefined
|}

== FFP Mathematics Conversion Library ==

The FFP mathematics conversion library provides functions to convert ASCII strings to their FFP equivalents and vice versa.

It is accessed by linking code into the executable file being created. The name of the file to include in the library description of the link command line is ''amiga.lib''. When this is included, direct calls are made to the conversion functions. Only a C interface exists for the conversion functions; there is no assembly language interface. The basic math library is required in order to access these functions.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathffp.h>

#include <clib/mathffp_protos.h>

struct Library *MathBase;

VOID main()
{
if (MathBase = OpenLibrary("mathffp.library", 33))
{
. . .

CloseLibrary(MathBase);
}
else
printf("Can't open mathffp.library\n");
}
</syntaxhighlight>

=== Math Support Functions ===

; afp() FLOAT afp( BYTE *string );
: Convert ASCII string into FFP equivalent.

; arnd() VOID arnd( LONG place, LONG exp, BYTE *string);
: Round ASCII representation of FFP number.

; dbf() FLOAT dbf( ULONG exp, ULONG mant);
: Convert FFP dual-binary number to FFP equivalent.

; fpa() LONG fpa( FLOAT fnum, BYTE *string);
: Convert FFP variable into ASCII equivalent.

Be sure to include proper data type definitions, as shown in the example below. Print statements have been included to help clarify the format of the math conversion function calls.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathffp.h>

#include <clib/mathffp_protos.h>
#include <clib/alib_protos.h>

struct Library *MathBase;

UBYTE st1[80] = "3.1415926535897";
UBYTE st2[80] = "2.718281828459045";
UBYTE st3[80], st4[80];

VOID main()
{
FLOAT num1, num2;
FLOAT n1, n2, n3, n4;
LONG exp1, exp2, exp3, exp4;
LONG mant1, mant2, mant3, mant4;
LONG place1, place2;

if (MathBase = OpenLibrary("mathffp.library", 33))
{

n1 = afp(st1); /* Call afp entry */
n2 = afp(st2); /* Call afp entry */
printf("\n\nASCII %s converts to floating point %f", st1, n1);
printf("\nASCII %s converts to floating point %f", st2, n2);

num1 = 3.1415926535897;
num2 = 2.718281828459045;

exp1 = fpa(num1, st3); /* Call fpa entry */
exp2 = fpa(num2, st4); /* Call fpa entry */
printf("\n\nfloating point %f converts to ASCII %s", num1, st3);
printf("\nfloating point %f converts to ASCII %s", num2, st4);

place1 = -2;
place2 = -1;
arnd(place1, exp1, st3); /* Call arnd entry */
arnd(place2, exp2, st4); /* Call arnd entry */
printf("\n\nASCII round of %f to %d places yields %s", num1, place1, st3);
printf("\nASCII round of %f to %d places yields %s", num2, place2, st4);

exp1 = -3; exp2 = 3; exp3 = -3; exp4 = 3;
mant1 = 12345; mant2 = -54321; mant3 = -12345; mant4 = 54321;

n1 = dbf(exp1, mant1); /* Call dbf entry */
n2 = dbf(exp2, mant2); /* Call dbf entry */
n3 = dbf(exp3, mant3); /* Call dbf entry */
n4 = dbf(exp4, mant4); /* Call dbf entry */
printf("\n\ndbf of exp = %d and mant = %d yields FFP number of %f", exp1, mant1, n1);
printf("\ndbf of exp = %d and mant = %d yields FFP number of %f", exp2, mant2, n2);
printf("\ndbf of exp = %d and mant = %d yields FFP number of %f", exp3, mant3, n3);
printf("\ndbf of exp = %d and mant = %d yields FFP number of %f", exp4, mant4, n4);

CloseLibrary(MathBase);
}
else
printf("Can't open mathffp.library\n");
}
</syntaxhighlight>

== IEEE Single-Precision Data Format ==

The IEEE single-precision variables are defined as 32-bit entities with the following format:

______________________________________________
| |
| SEEEEEEE MMMMMMMM MMMMMMMM MMMMMMMM |
| 31 23 15 7 |
|______________________________________________|

{{Note|title=Hidden Bit In The Mantissa|text=There is a "hidden" bit in the mantissa part of the IEEE numbers. Since all numbers are normalized, the ''integer'' (high) bit of the mantissa is dropped off. The IEEE single-precision range is 1.3E-38 (1.4E-45 de-normalized) to 3.4E+38.}}

The exponent is the power of two needed to correctly position the mantissa to reflect the number's true arithmetic value. If both the exponent and the mantissa have zero in every position, the value is zero. If only the exponent has zero in every position, the value is an ''unnormal'' (extremely small). If all bits of the exponent are set to 1 the value is either a positive or negative infinity or a ''Not a Number (NaN)''. NaN is sometimes used to indicate an uninitialized variable.

== IEEE Single-Precision Basic Math Library ==

The ROM-based IEEE single-precision basic math library was introduced in V36. This library contains entries for the basic IEEE single-precision mathematics functions, such as add, subtract, and divide.

The library is opened by making calling OpenLibrary() with "mathieeesingbas.library" as the argument. Do not share the library base pointer between tasks - see note at beginning of chapter for details.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathieeesp.h>

#include <clib/mathsingbas_protos.h>

struct Library *MathIeeeSingBasBase;

VOID main()
{
/* do not share base pointer between tasks. */
if (MathIeeeSingBasBase = OpenLibrary("mathieeesingbas.library", 37))
{
.
.
.
CloseLibrary(MathIeeeSingBasBase);
}
else
printf("Can't open mathieeesingbas.library\n");
}
</syntaxhighlight>

The global variable MathIeeeSingBasBase is used internally for all future library references.

If an ''680x0''/''68881''/''68882'' processor combination is available, it will be used by the IEEE single-precision basic library instead of the software emulation. Also, if an autoconfigured math resource is available, that will be used. Typically this is a 68881 designed as a 16 bit I/O port, but it could be another device as well.

=== SP IEEE Basic Functions (V36 or greater) ===

; IEEESPAbs() FLOAT ( FLOAT parm );
: Take absolute value of IEEE single-precision variable.

; IEEESPAdd() FLOAT IEEESPAdd( FLOAT leftParm, FLOAT rightParm);
: Add two IEEE single-precision variables.

; IEEESPCeil() FLOAT IEEESPCeil( FLOAT parm );
: Compute least integer greater than or equal to variable.

; IEEESPCmp() LONG IEEESPCmp( FLOAT leftParm, FLOAT rightParm );
: Compare two IEEE single-precision variables.

; IEEESPDiv() FLOAT IEEESPDiv( FLOAT dividend, FLOAT divisor );
: Divide two IEEE single-precision variables.

; IEEESPFix() LONG IEEESPFix( FLOAT parm );
: Convert IEEE single-precision variable to integer.

; IEEESPFloor() FLOAT IEEESPFloor( FLOAT parm );
: Compute largest integer less than or equal to variable.

; IEEESPFlt() FLOAT IEEESPFlt( long integer );
: Convert integer variable to IEEE single-precision.

; IEEESPMul() FLOAT IEEESPMul( FLOAT leftParm, FLOAT rightParm );
: Multiply two IEEE single-precision variables.

; IEEESPNeg() FLOAT IEEESPNeg( FLOAT parm );
: Take two's complement of IEEE single-precision variable.

; IEEESPSub() FLOAT IEEESPSub( FLOAT leftParm, FLOAT rightParm );
: Subtract two IEEE single-precision variables.

; IEEESPTst() LONG IEEESPTst( FLOAT parm );
: Test an IEEE single-precision variable against zero.

Be sure to include proper data type definitions, as shown in the example below.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathieeesp.h>

#include <clib/mathsingbas_protos.h>

struct Library *MathIeeeSingBasBase;

VOID main()
{
FLOAT f1, f2, f3;
LONG i1;

if (MathIeeeSingBasBase = OpenLibrary("mathieeesingbas.library",37))
{
i1 = IEEESPFix(f1); /* Call IEEESPFix entry */
fi = IEEESPFlt(i1); /* Call IEEESPFlt entry */
switch (IEEESPCmp(f1, f2)) {}; /* Call IEEESPCmp entry */
switch (IEEESPTst(f1)) {}; /* Call IEEESPTst entry */
f1 = IEEESPAbs(f2); /* Call IEEESPAbs entry */
f1 = IEEESPNeg(f2); /* Call IEEESPNeg entry */
f1 = IEEESPAdd(f2, f3); /* Call IEEESPAdd entry */
f1 = IEEESPSub(f2, f3); /* Call IEEESPSub entry */
f1 = IEEESPMul(f2, f3); /* Call IEEESPMul entry */
f1 = IEEESPDiv(f2, f3); /* Call IEEESPDiv entry */
f1 = IEEESPCeil(f2); /* Call IEEESPCeil entry */
f1 = IEEESPFloor(f2); /* Call IEEESPFloor entry */

CloseLibrary(MathIeeeSingBasBase);
}
else
printf("Can't open mathieeesingbas.library\n");
}
</syntaxhighlight>

The Amiga assembly language interface to the IEEE single-precision basic math routines is shown below, including some details about how the system flags are affected by each operation. Note that the access mechanism from assembly language is as shown below:

<pre>
MOVEA.L _MathIeeeSingBasBase,A6
JSR _LVOIEEESPFix(A6)
</pre>

{| class="wikitable"
|+ SP IEEE Basic Assembly Functions
! Function
! Input
! Output
! Condition Codes
|-
| _LVOIEEESPFix
| D0 = IEEE double-precision argument
| D0 = Integer (two's complement)
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPFlt
| D0 = Integer argument (two's complement)
| D0 = IEEE single-precision
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPCmp
| D0 = IEEE single-precision argument 1 
D1 = IEEE single-precision argument 2
| D0 = +1 if arg1 > arg2 
D0 = -1 if arg1 < arg2 
D0 = 0 if arg1 = arg2
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined 
GT = arg2 > arg1 
GE = arg2 >= arg1 
EQ = arg2 = arg1 
NE = arg2 != arg1 
LT = arg2 < arg1 
E= arg2 <= arg1
|-
| _LVOIEEESPTst
| D0 = IEEE single-precision argument
| D0 = +1 if arg > 0.0 
D0 = -1 if arg < 0.0 
D0 = 0 if arg = 0.0
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined 
EQ = arg = 0.0 
NE = arg != 0.0 
PL = arg >= 0.0 
MI = arg < 0.0
|-
| _LVOIEEESPAbs
| D0 = IEEE single-precision argument
| D0 = IEEE single-precision absolute value
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPNeg
| D0 = IEEE single-precision argument
| D0 = IEEE single-precision negated
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPAdd
| D0 = IEEE single-precision argument 1 
D1 = IEEE single-precision argument 2
| D0 = IEEE single-precision addition of arg1+arg2
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPSub
| D0 = IEEE single-precision argument 1 
D1 = IEEE single-precision argument 2
| D0 = IEEE single-precision subtraction of arg1-arg2
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPMul
| D0 = IEEE single-precision argument 1 
D1 = IEEE single-precision argument 2
| D0 = IEEE single-precision multiplication of arg1 * arg2
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPDiv
| D0 = IEEE single-precision argument 1 
D1 = IEEE single-precision argument 2
| D0 = IEEE single-precision division of arg1/arg2
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPCeil
| D0 = IEEE single-precision variable
| D0 = least integer >= variable
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPFloor
| D0 = IEEE single-precision variable
| D0 = largest integer <= argument
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|}

== IEEE Single-Precision Transcendental Math Library ==

The IEEE single-precision transcendental math library was introduced in V36. It contains entries for transcendental math functions such as sine, cosine, and square root.

This library resides on disk and is opened by calling OpenLibrary() with "mathieeesingtrans.library" as the argument. Do not share the library base pointer between tasks - see note at beginning of chapter.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathieeesp.h>

struct Library *MathIeeeSingTransBase;

#include <clib/mathsingtrans_protos.h>

VOID main()
{
if (MathIeeeSingTransBase = OpenLibrary("mathieeesingtrans.library",37))
{
. . .

CloseLibrary(MathIeeeSingTransBase);
}
else printf("Can't open mathieeesingtrans.library\n");
}
</syntaxhighlight>

The global variable MathIeeeSingTransBase is used internally for all future library references.

The IEEE single-precision transcendental math library is dependent upon the IEEE single-precision basic math library, which it will open if it is not open already. If you want to use the IEEE single-precision basic math functions in conjunction with the transcendental math functions however, you have to specifically open the basic math library yourself.

Just as the IEEE single-precision basic math library, the IEEE single-precision transcendental math library will take advantage of a ''680x0''/''68881'' combination or another math resource, if present.

=== SP IEEE Transcendental Functions (V36 or greater) ===

; IEEESPAsin() FLOAT IEEESPAsin( FLOAT parm );
: Return arcsine of IEEE single-precision variable.

; IEEESPAcos() FLOAT IEEESPAcos( FLOAT parm );
: Return arccosine of IEEE single-precision variable.

; IEEESPAtan() FLOAT IEEESPAtan( FLOAT parm );
: Return arctangent of IEEE single-precision variable.

; IEEESPSin() FLOAT IEEESPSin( FLOAT parm );
; Return sine of IEEE single-precision variable. This function accepts an IEEE radian argument and returns the trigonometric sine value.

; IEEESPCos() FLOAT IEEESPCos( FLOAT parm );
: Return cosine of IEEE single-precision variable. This function accepts an IEEE radian argument and returns the trigonometric cosine value.

; IEEESPTan() FLOAT IEEESPTan( FLOAT parm );
: Return tangent of IEEE single-precision variable. This function accepts an IEEE radian argument and returns the trigonometric tangent value.

; IEEESPSincos() FLOAT IEEESPSincos( FLOAT *cosptr, FLOAT parm );
: Return sine and cosine of IEEE single-precision variable. This function accepts an IEEE radian argument and returns the trigonometric sine as its result and the cosine in the first parameter.

; IEEESPSinh() FLOAT IEEESPSinh( FLOAT parm );
: Return hyperbolic sine of IEEE single-precision variable.

; IEEESPCosh() FLOAT IEEESPCosh( FLOAT parm );
: Return hyperbolic cosine of IEEE single-precision variable.

; IEEESPTanh() FLOAT IEEESPTanh( FLOAT parm );
: Return hyperbolic tangent of IEEE single-precision variable.

; IEEESPExp() FLOAT IEEESPExp( FLOAT parm );
: Return ''e'' to the IEEE variable power. This function accept an IEEE single-precision argument and returns the result representing the value of ''e'' (2.712828...) raised to that power.

; IEEESPFieee() FLOAT IEEESPFieee( FLOAT parm );
: Convert IEEE single-precision number to IEEE single-precision number. The only purpose of this function is to provide consistency with the double-precision math IEEE library.

; IEEESPLog() FLOAT IEEESPLog( FLOAT parm );
: Return natural log (base ''e'' of IEEE single-precision variable.

; IEEESPLog10() FLOAT IEEESPLog10( FLOAT parm );
: Return log (base 10) of IEEE single-precision variable.

; IEEESPPow() FLOAT IEEESPPow( FLOAT exp, FLOAT arg );
: Return IEEE single-precision arg2 to IEEE single-precision arg1.

; IEEESPSqrt() FLOAT IEEESPSqrt( FLOAT parm );
: Return square root of IEEE single-precision variable.

; IEEESPTieee() FLOAT IEEESPTieee( FLOAT parm );
: Convert IEEE single-precision number to IEEE single-precision number. The only purpose of this function is to provide consistency with the double-precision math IEEE library.

Be sure to include the proper data type definitions as shown below.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathieeesp.h>

#include <clib/mathsingtrans_protos.h>

struct Library *MathIeeeSingTransBase;

VOID main()
{
FLOAT f1, f2, f3;

if (MathIeeeSingTransBase = OpenLibrary("mathieeesingtrans.library",37))
{
f1 = IEEEDPAsin(f2); /* Call IEEESPAsin entry */
f1 = IEEEDPAcos(f2); /* Call IEEESPAcos entry */
f1 = IEEEDPAtan(f2); /* Call IEEESPAtan entry */
f1 = IEEEDPSin(f2); /* Call IEEESPSin entry */
f1 = IEEEDPCos(f2); /* Call IEEESPCos entry */
f1 = IEEEDPTan(f2); /* Call IEEESPTan entry */
f1 = IEEEDPSincos(&f3, f2); /* Call IEEESPSincos entry */
f1 = IEEEDPSinh(f2); /* Call IEEESPSinh entry */
f1 = IEEEDPCosh(f2); /* Call IEEESPCosh entry */
f1 = IEEEDPTanh(f2); /* Call IEEESPTanh entry */
f1 = IEEEDPExp(f2); /* Call IEEESPExp entry */
f1 = IEEEDPLog(f2); /* Call IEEESPLog entry */
f1 = IEEEDPLog10(f2); /* Call IEEESPLog10 entry */
f1 = IEEEDPPow(d2, f3); /* Call IEEESPPow entry */
f1 = IEEEDPSqrt(f2); /* Call IEEESPSqrt entry */

CloseLibrary(MathIeeeSingTransBase);
}
else printf("Can't open mathieeesingtrans.library\n");
}
</syntaxhighlight>

The section below describes the Amiga assembly interface to the IEEE single-precision transcendental math library. The access mechanism from assembly language is:

<pre>
MOVEA.L _MathIeeeSingTransBase,A6
JSR _LVOIEEESPAsin(A6)
</pre>

{| class="wikitable"
|+ SP IEEE Transcendental Assembly Functions
! Function
! Input
! Output
! Condition Codes
|-
| _LVOIEEESPAsin
| D0 = IEEE argument
| D0 = IEEE arcsine radian
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPAcos
| D0 = IEEE single-precision argument
| D0 = IEEE arccosine radian
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPAtan
| D0 = IEEE single-precision argument
| D0 = IEEE arctangent radian
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPSin
| D0 = IEEE single-precision argument in radians
| D0 = IEEE sine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPCos
| D0 = IEEE single-precision argument in radians
| D0 = IEEE cosine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPTan
| D0 = IEEE single-precision argument in radians
| D0 = IEEE tangent
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPSincos
| A0 = Address to store cosine result 
D0 = IEEE argument in radians
| D0 = IEEE sine 
(A0) = IEEE cosine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPSinh
| D0 = IEEE single-precision argument in radians
| D0 = IEEE hyperbolic sine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPCosh
| D0 = IEEE single-precision argument in radians
| D0 = IEEE hyperbolic cosine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPTanh
| D0 = IEEE single-precision argument in radians
| D0 = IEEE hyperbolic tangent
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPExp
| D0 = IEEE single-precision argument
| D0 = IEEE exponential
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPLog
| D0 = IEEE single-precision argument
| D0 = IEEE natural logarithm
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPLog10
| D0 = IEEE single-precision argument
| D0 = IEEE logarithm (base 10)
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPPow
| D0 = IEEE single-precision exponent value 
D1 = IEEE single-precision argument value
| D0 = IEEE result of arg taken to exp power
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEESPSqrt
| D0 = IEEE single-precision argument
| D0 = IEEE square root
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|}

== IEEE Double-Precision Data Format ==

The IEEE double-precision variables are defined as 64-bit entities with the following format:

______________________________________________
| |
| SEEEEEEE EEEEEIMM MMMMMMMM MMMMMMMM |
| 63 55 47 39 |
|______________________________________________|

______________________________________________
| |
| MMMMMMMM MMMMMMMM MMMMMMMM MMMMMMMM |
| 31 23 15 7 |
|______________________________________________|

{{Note|title=Hidden Bit In The Mantissa|text=There is a "hidden" bit in the mantissa part of the IEEE numbers. Since all numbers are normalized, the ''integer'' (high) bit of the mantissa is dropped off. The IEEE double-precision range is 2.2E-308 (4.9E-324 de-normalized) to 1.8E+307.}}

The exponent is the power of two needed to correctly position the mantissa to reflect the number's true arithmetic value. If both the exponent and the mantissa have zero in every position, the value is zero. If only the exponent has zero in every position, the value is an ''unnormal'' (extremely small). If all bits of the exponent are set to 1 the value is either a positive or negative infinity or a ''Not a Number (NaN)''. NaN is sometimes used to indicate an uninitialized variable.

== IEEE Double-Precision Basic Math Library ==

The IEEE double-precision basic math library contains entries for the basic IEEE mathematics functions, such as add, subtract, and divide. This library resides on disk and is opened by calling OpenLibrary() with "mathieeedoubbas.library" as the argument. Do not share the library base pointer between tasks - see note at beginning of chapter for details.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathieeedp.h>

#include <clib/mathdoubbas_protos.h>

struct Library *MathIeeeDoubBasBase;

VOID main()
{
/* do not share base pointer between tasks. */
if (MathIeeeDoubBasBase = OpenLibrary("mathieeedoubbas.library", 34))
{
. . .

CloseLibrary(MathIeeeDoubBasBase);
}
else printf("Can't open mathieeedoubbas.library\n");
}
</syntaxhighlight>

The global variable MathIeeeDoubBasBase is used internally for all future library references.

If an ''680x0''/''68881''/''68882'' processor combination is available, it will be used by the IEEE basic library instead of the software emulation. Also, if an autoconfigured math resource is available, that will be used. Typically this is a 68881 designed as a 16 bit I/O port, but it could be another device as well.

=== DP IEEE Basic Functions ===

; IEEEDPAbs() DOUBLE IEEEDPAbs( DOUBLE parm );
: Take absolute value of IEEE double-precision variable.

; IEEEDPAdd() DOUBLE IEEEDPAdd( DOUBLE leftParm, DOUBLE rightParm );
: Add two IEEE double-precision variables.

; IEEEDPCeil() DOUBLE IEEEDPCeil( DOUBLE parm );
: Compute least integer greater than or equal to variable.

; IEEEDPCmp() LONG IEEEDPCmp( DOUBLE leftParm, DOUBLE rightParm );
: Compare two IEEE double-precision variables.

; IEEEDPDiv() DOUBLE IEEEDPDiv( DOUBLE dividend, DOUBLE divisor );
: Divide two IEEE double-precision variables.

; IEEEDPFix() LONG IEEEDPFix( DOUBLE parm );
: Convert IEEE double-precision variable to integer.

; IEEEDPFloor() DOUBLE IEEEDPFloor( DOUBLE parm );
: Compute largest integer less than or equal to variable.

; IEEEDPFlt() DOUBLE IEEEDPFlt( long integer );
: Convert integer variable to IEEE double-precision.

; IEEEDPMul() DOUBLE IEEEDPMul( DOUBLE factor1, DOUBLE factor2 );
: Multiply two IEEE double-precision variables.

; IEEEDPNeg() DOUBLE IEEEDPNeg( DOUBLE parm );
: Take two's complement of IEEE double-precision variable.

; IEEEDPSub() DOUBLE IEEEDPSub( DOUBLE leftParm, DOUBLE rightParm );
: Subtract two IEEE double-precision variables.

; IEEEDPTst() LONG IEEEDPTst( DOUBLE parm );
: Test an IEEE double-precision variable against zero.

Be sure to include proper data type definitions, as shown in the example below.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathieeedp.h>

#include <clib/mathieeedoubbas_protos.h>

struct Library *MathIeeeDoubBasBase;

VOID main()
{
DOUBLE d1, d2, d3;
LONG i1;

if (MathIeeeDoubBasBase = OpenLibrary("mathieeedoubbas.library",34))
{

i1 = IEEEDPFix(d1); /* Call IEEEDPFix entry */
fi = IEEEDPFlt(i1); /* Call IEEEDPFlt entry */
switch (IEEEDPCmp(d1, d2)) {}; /* Call IEEEDPCmp entry */
switch (IEEEDPTst(d1)) {}; /* Call IEEEDPTst entry */
d1 = IEEEDPAbs(d2); /* Call IEEEDPAbs entry */
d1 = IEEEDPNeg(d2); /* Call IEEEDPNeg entry */
d1 = IEEEDPAdd(d2, d3); /* Call IEEEDPAdd entry */
d1 = IEEEDPSub(d2, d3); /* Call IEEEDPSub entry */
d1 = IEEEDPMul(d2, d3); /* Call IEEEDPMul entry */
d1 = IEEEDPDiv(d2, d3); /* Call IEEEDPDiv entry */
d1 = IEEEDPCeil(d2); /* Call IEEEDPCeil entry */
d1 = IEEEDPFloor(d2); /* Call IEEEDPFloor entry */

CloseLibrary(MathIeeeDoubBasBase);
}
else printf("Can't open mathieeedoubbas.library\n");
}
</syntaxhighlight>

The Amiga assembly language interface to the IEEE double-precision floating-point basic math routines is shown below, including some details about how the system flags are affected by each operation. The access mechanism from assembly language is:

<pre>
MOVEA.L _MathIeeeDoubBasBase,A6
JSR _LVOIEEEDPFix(A6)
</pre>

{| class="wikitable"
|+ DP IEEE Basic Assembly Functions
! Function
! Input
! Output
! Condition Codes
|-
| _LVOIEEEDPFix
| D0/D1 = IEEE double-precision argument
| D0 = Integer (two's complement)
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPFl
| D0 = Integer (two's complement) argument
| D0/D1 = IEEE double-precision
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPCmp
| D0/D1 = IEEE double-precision argument 1 
D2/D3 = IEEE double-precision argument 2
| D0 = +1 if arg1 > arg2 
D0 = -1 if arg1 < arg2 
D0 = 0 if arg1 = arg2
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined 
GT = arg2 > arg1 
GE = arg2 >= arg1 
EQ = arg2 = arg1 
NE = arg2 != arg1 
LT = arg2 < arg1 
LE = arg2 <= arg1
|-
| _LVOIEEEDPTst
| D0/D1 = IEEE double-precision argument
| D0 = +1 if arg > 0.0 
D0 = -1 if arg < 0.0 
D0 = 0 if arg = 0.0
| N = 1 if result is negative 
Z = 1 if result is zero 
V = 0 
C = undefined 
X = undefined 
EQ = arg = 0.0 
NE = arg != 0.0 
PL = arg >= 0.0 
MI = arg < 0.0
|-
| _LVOIEEEDPAbs
| D0/D1 = IEEE double-precision argument
| D0/D1 = IEEE double-precision absolute value
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPNeg
| D0/D1 = IEEE double-precision argument
| D0/D1 = IEEE double-precision negated
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPAdd
| D0/D1 = IEEE double-precision argument 1 
D2/D3 = IEEE double-precision argument 2
| D0/D1 = IEEE double-precision addition of arg1+arg2
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPSub
| D0/D1 = IEEE double-precision argument 1 
D2/D3 = IEEE double-precision argument 2
| D0/D1 = IEEE double-precision subtraction of arg1-arg2
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPMul
| D0/D1 = IEEE double-precision argument 1 
D2/D3 = IEEE double-precision argument 2
| D0/D1 = IEEE double-precision multiplication of arg1*arg2
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPDiv
| D0/D1 = IEEE double-precision argument 1 
D2/D3 = IEEE double-precision argument 2
| D0/D1 = IEEE double-precision division of arg1/arg2
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPCeil
| D0/D1 = IEEE double-precision argument
| D0/D1 = least integer >= argument
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPFloor
| D0/D1 = IEEE double-precision argument
| D0/D1 = largest integer <= argument
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|}

== IEEE Double-Precision Transcendental Math Library ==

The IEEE double-precision transcendental math library contains entries for the transcendental math functions such as sine, cosine, and square root. The library resides on disk and is opened by calling OpenLibrary() with "mathieeedoubtrans.library" as the argument. Do not share the library base pointer between tasks - see note at beginning of chapter for details.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathieeedp.h>

#include <clib/mathdoubtrans_protos.h>

struct Library *MathIeeeDoubTransBase;

VOID main()
{
if (MathIeeeDoubTransBase = OpenLibrary("mathieeedoubtrans.library",34))
{
. . .

CloseLibrary(MathIeeeDoubTransBase);
}
else printf("Can't open mathieeedoubtrans.library\n");
}
</syntaxhighlight>

The global variable MathIeeeDoubTransBase is used internally for all future library references.

The IEEE double-precision transcendental math library is dependent upon the IEEE double-precision basic math library, which it will open if it is not open already. If you want to use the IEEE double-precision basic math functions in conjunction with the transcendental math functions however, you have to specifically open the basic math library yourself.

Just as the IEEE double-precision basic math library, the IEEE double-precision transcendental math library will take advantage of a ''680x0''/''68881'' combination or another math resource, if present.

=== DP IEEE Transcendental Functions ===

; IEEEDPAsin() DOUBLE IEEEDPAsin( DOUBLE parm );
: Return arcsine of IEEE variable.

; IEEEDPAcos() DOUBLE IEEEDPAcos( DOUBLE parm );
: Return arccosine of IEEE variable.

; IEEEDPAtan() DOUBLE IEEEDPAtan( DOUBLE parm );
: Return arctangent of IEEE variable.

; IEEEDPSin() DOUBLE IEEEDPSin( DOUBLE parm );
: Return sine of IEEE variable. This function accepts an IEEE radian argument and returns the trigonometric sine value.

; IEEEDPCos() DOUBLE IEEEDPCos( DOUBLE parm )
: Return cosine of IEEE variable. This function accepts an IEEE radian argument and returns the trigonometric cosine value.

; IEEEDPTan() DOUBLE IEEEDPTan( DOUBLE parm );
: Return tangent of IEEE variable. This function accepts an IEEE radian argument and returns the trigonometric tangent value.

; IEEEDPSincos() DOUBLE IEEEDPSincos( DOUBLE *pf2, DOUBLE parm );
: Return sine and cosine of IEEE variable. This function accepts an IEEE radian argument and returns the trigonometric sine as its result and the trigonometric cosine in the first parameter.

; IEEEDPSinh() DOUBLE IEEEDPSinh( DOUBLE parm );
: Return hyperbolic sine of IEEE variable.

; IEEEDPCosh() DOUBLE IEEEDPCosh( DOUBLE parm );
: Return hyperbolic cosine of IEEE variable.

; IEEEDPTanh() DOUBLE IEEEDPTanh( DOUBLE parm );
: Return hyperbolic tangent of IEEE variable.

; IEEEDPExp() DOUBLE IEEEDPExp( DOUBLE parm );
: Return ''e'' to the IEEE variable power. This function accept an IEEE argument and returns the result representing the value of ''e'' (2.712828...) raised to that power.

; IEEEDPFieee() DOUBLE IEEEDPFieee( FLOAT single );
: Convert IEEE single-precision number to IEEE double-precision number.

; IEEEDPLog() DOUBLE IEEEDPLog( DOUBLE parm );
: Return natural log (base ''e'' of IEEE variable.

; IEEEDPLog10() DOUBLE IEEEDPLog10( DOUBLE parm );
: Return log (base 10) of IEEE variable.

; IEEEDPPow() DOUBLE IEEEDPPow( DOUBLE exp, DOUBLE arg );
: Return IEEE arg2 to IEEE arg1.

; IEEEDPSqrt() DOUBLE IEEEDPSqrt( DOUBLE parm );
: Return square root of IEEE variable.

; IEEEDPTieee() FLOAT IEEEDPTieee( DOUBLE parm );
: Convert IEEE double-precision number to IEEE single-precision number.

Be sure to include proper data type definitions as shown below.

<syntaxhighlight>
#include <exec/types.h>
#include <libraries/mathieeedp.h>
#include <clib/mathdoubtrans_protos.h>

struct Library *MathIeeeDoubTransBase;

VOID main()
{
DOUBLE d1, d2, d3;
FLOAT f1;

if (MathIeeeDoubTransBase = OpenLibrary("mathieeedoubtrans.library",34))
{
d1 = IEEEDPAsin(d2); /* Call IEEEDPAsin entry */
d1 = IEEEDPAcos(d2); /* Call IEEEDPAcos entry */
d1 = IEEEDPAtan(d2); /* Call IEEEDPAtan entry */
d1 = IEEEDPSin(d2); /* Call IEEEDPSin entry */
d1 = IEEEDPCos(d2); /* Call IEEEDPCos entry */
d1 = IEEEDPTan(d2); /* Call IEEEDPTan entry */
d1 = IEEEDPSincos(&d3, d2); /* Call IEEEDPSincos entry */
d1 = IEEEDPSinh(d2); /* Call IEEEDPSinh entry */
d1 = IEEEDPCosh(d2); /* Call IEEEDPCosh entry */
d1 = IEEEDPTanh(d2); /* Call IEEEDPTanh entry */
d1 = IEEEDPExp(d2); /* Call IEEEDPExp entry */
d1 = IEEEDPLog(d2); /* Call IEEEDPLog entry */
d1 = IEEEDPLog10(d2); /* Call IEEEDPLog10 entry */
d1 = IEEEDPPow(d2, d3); /* Call IEEEDPPow entry */
d1 = IEEEDPSqrt(d2); /* Call IEEEDPSqrt entry */
f1 = IEEEDPTieee(d2); /* Call IEEEDPTieee entry */
d1 = IEEEDPFieee(f1); /* Call IEEEDPFieee entry */

CloseLibrary(MathIeeeDoubTransBase);
}
else printf("Can't open mathieeedoubtrans.library\n");
}
</syntaxhighlight>

The section below describes the Amiga assembly interface to the IEEE double-precision transcendental math library. The access mechanism from assembly language is:

<pre>
MOVEA.L _MathIeeeDoubTransBase,A6
JSR _LVOIEEEDPAsin(A6)
</pre>

{| class="wikitable"
|+ DP IEEE Transcendental Assembly Functions
! Function
! Input
! Output
! Condition Codes
|-
| _LVOIEEEDPAsin
| D0/D1 = IEEE argument
| D0/D1 = IEEE arcsine radian
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPAcos
| D0/D1 = IEEE argument
| D0/D1 = IEEE arccosine radian
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPAtan
| D0/D1 = IEEE argument
| D0/D1 = IEEE arctangent radian
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPSin
| D0/D1 = IEEE argument in radians
| D0/D1 = IEEE sine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPCos
| D0/D1 = IEEE argument in radians
| D0/D1 = IEEE cosine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPTan
| D0/D1 = IEEE argument in radians
| D0/D1 = IEEE tangent
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPSincos
| A0 = Address to store cosine result 
D0/D1 = IEEE argument in radians
| D0/D1 = IEEE sine 
(A0) = IEEE cosine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPSin
| D0/D1 = IEEE argument in radians
| D0/D1 = IEEE hyperbolic sine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPCosh
| D0/D1 = IEEE argument in radians
| D0/D1 = IEEE hyperbolic cosine
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPTanh
| D0/D1 = IEEE argument in radians
| D0/D1 = IEEE hyperbolic tangent
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPExp
| D0/D1 = IEEE argument
| D0/D1 = IEEE exponential
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPLog
| D0/D1 = IEEE argument
| D0/D1 = IEEE natural logarithm
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPLog10
| D0/D1 = IEEE argument
| D0/D1 = IEEE logarithm (base 10)
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPPow
| D0/D1 = IEEE exponent 
D2/D3 = IEEE argument
| D0/D1 = IEEE result of arg taken to exp power
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPSqrt
| D0/D1 = IEEE argument
| D0/D1 = IEEE square root
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|-
| _LVOIEEEDPTieee
| D0/D1 = IEEE format argument
| D0 = single-precision IEEE floating-point format
| N = undefined 
Z = undefined 
V = undefined 
C = undefined 
X = undefined
|}

== Function Reference ==

Here's a brief summary of the functions covered in this chapter. Refer to the SDK for additional information.

{| class="wikitable"
|+ FFP Basic Functions
! Function
! Description
|-
| SPAbs()
| Take absolute value of FFP variable
|-
| SPAdd()
| Add two FFP variables
|-
| SPCeil()
| Compute least integer greater than or equal to variable.
|-
| SPCmp()
| Compare two FFP variables
|-
| SPDiv()
| Divide two FFP variables
|-
| SPFix()
| Convert FFP variable to integer
|-
| SPFloor()
| Computer largest integer less than or equal to variable.
|-
| SPFlt()
| Convert integer variable to FFP
|-
| SPMul()
| Multiply two FFP variables
|-
| SPNeg()
| Take two‚Äôs complement of FFP variable
|-
| SPSub()
| Subtract two FFP variables
|-
| SPTst()
| Test an FFP variable against zero
|}

{| class="wikitable"
|+ FFP Transcendental Functions
! Function
! Description
|-
| SPAcos()
| Return arccosine of FFP variable.
|-
| SPAsin()
| Return arcsine of FFP variable.
|-
| SPAtan()
| Return arctangent of FFP variable.
|-
| SPCos()
| Return cosine of FFP variable.
|-
| SPCosh()
| Return hyperbolic cosine of FFP variable.
|-
| SPExp()
| Return ''e'' to the FFP variable power.
|-
| SPFieee()
| Convert IEEE variable to FFP format.
|-
| SPLog()
| Return natural log (base ''e'') of FFP variable.
|-
| SPLog10()
| Return log (base 10) of FFP variable.
|-
| SPPow()
| Return FFP arg2 to FFP arg1.
|-
| SPSin()
| Return sine of FFP variable.
|-
| SPSincos()
| Return sine and cosine of FFP variable.
|-
| SPSinh()
| Return hyperbolic sine of FFP variable.
|-
| SPSqrt()
| Return square root of FFP variable.
|-
| SPTan()
| Return tangent of FFP variable.
|-
| SPTanh()
| Return hyperbolic tangent of FFP variable.
|-
| SPTieee()
| Convert FFP variable to IEEE format
|}

{| class="wikitable"
|+ Math Support Functions
! Function
! Description
|-
| afp()
| Convert ASCII string into FFP equivalent.
|-
| fpa()
| Convert FFP variable into ASCII equivalent.
|-
| arnd()
| Round ASCII representation of FFP number.
|-
| dbf()
| Convert FFP dual-binary number to FFP equivalent.
|}

{| class="wikitable"
|+ SP IEEE Basic Functions
! Function
! Description
|-
| IEEESPAbs()
| Take absolute value of IEEE single-precision variable
|-
| IEEESPAdd()
| Add two IEEE single-precision variables
|-
| IEEESPCeil()
| Compute least integer greater than or equal to variable
|-
| IEEESPCmp()
| Compare two IEEE single-precision variables
|-
| IEEESPDiv()
| Divide two IEEE single-precision variables
|-
| IEEESPFix()
| Convert IEEE single-precision variable to integer
|-
| IEEESPFloor()
| Compute largest integer less than or equal to variable
|-
| IEEESPFlt()
| Convert integer variable to IEEE single-precision
|-
| IEEESPMul()
| Multiply two IEEE single-precision variables
|-
| IEEESPNeg()
| Take two's complement of IEEE single-precision variable
|-
| IEEESPSub()
| Subtract two IEEE single-precision variables
|-
| IEEESPTst()
| Test an IEEE single-precision variable against zero
|}

{| class="wikitable"
|+ SP IEEE Transcendental Functions
! Function
! Description
|-
| IEEESPACos()
| Return arccosine of IEEE single-precision variable.
|-
| IEEESPASin()
| Return arcsine of IEEE single-precision variable.
|-
| IEEESPAtan()
| Return arctangent of IEEE single-precision variable.
|-
| IEEESPCos()
| Return cosine of IEEE single-precision variable.
|-
| IEEESPCosh()
| Return hyperbolic cosine of IEEE single-precision variable.
|-
| IEEESPExp()
| Return ''e'' to the IEEE variable power.
|-
| IEEESPLog()
| Return natural log (base ''e'' of IEEE single-precision variable.
|-
| IEEESPLog10()
| Return log (base 10) of IEEE single-precision variable.
|-
| IEEESPPow()
| Return power of IEEE single-precision variable.
|-
| IEEESPSin()
| Return sine of IEEE single-precision variable.
|-
| IEEESPSincos()
| Return sine and cosine of IEEE single-precision variable.
|-
| IEEESPSinh()
| Return hyperbolic sine of IEEE single-precision variable.
|-
| IEEESPSqrt()
| Return square root of IEEE single-precision variable.
|-
| IEEESPTan()
| Return tangent of IEEE single-precision variable.
|-
| IEEESPTanh()
| Return hyperbolic tangent of IEEE single-precision variable.
|}

{| class="wikitable"
|+ DP IEEE Basic Functions
! Function
! Description
|-
| IEEEDPAbs()
| Take absolute value of IEEE double-precision variable
|-
| IEEEDPAdd()
| Add two IEEE double-precision variables
|-
| IEEEDPCeil()
| Compute least integer greater than or equal to variable
|-
| IEEEDPCmp()
| Compare two IEEE double-precision variables
|-
| IEEEDPDiv()
| Divide two IEEE double-precision variables
|-
| IEEEDPFix()
| Convert IEEE double-precision variable to integer
|-
| IEEEDPFloor()
| Compute largest integer less than or equal to variable
|-
| IEEEDPFlt()
| Convert integer variable to IEEE double-precision
|-
| IEEEDPMul()
| Multiply two IEEE double-precision variables
|-
| IEEEDPNeg()
| Take two's complement of IEEE double-precision variable
|-
| IEEEDPSub()
| Subtract two IEEE single-precision variables
|-
| IEEEDPTst()
| Test an IEEE double-precision variable against zero
|}

{| class="wikitable"
|+ DP IEEE Transcendental Functions
! Function
! Description
|-
| IEEEDPACos()
| Return arccosine of IEEE double-precision variable.
|-
| IEEEDPASin()
| Return arcsine of IEEE double-precision variable.
|-
| IEEEDPAtan()
| Return arctangent of IEEE double-precision variable.
|-
| IEEEDPCos()
| Return cosine of IEEE double-precision variable.
|-
| IEEEDPCosh()
| Return hyperbolic cosine of IEEE double-precision variable.
|-
| IEEEDPExp()
| Return ''e'' to the IEEE variable power.
|-
| IEEEDPFieee()
| Convert IEEE single-precision number to IEEE double-precision number.
|-
| IEEEDPLog()
| Return natural log (base ''e'' of IEEE double-precision variable.
|-
| IEEEDPLog10()
| Return log (base 10) of IEEE double-precision variable.
|-
| IEEEDPPow()
| Return power of IEEE double-precision variable.
|-
| IEEEDPSin()
| Return sine of IEEE double-precision variable.
|-
| IEEEDPSincos()
| Return sine and cosine of IEEE double-precision variable.
|-
| IEEEDPSinh()
| Return hyperbolic sine of IEEE double-precision variable.
|-
| IEEEDPSqrt()
| Return square root of IEEE double-precision variable.
|-
| IEEEDPTan()
| Return tangent of IEEE double-precision variable.
|-
| IEEEDPTanh()
| Return hyperbolic tangent of IEEE double-precision variable.
|-
| IEEEDPTieee()
| Convert IEEE double-precision number to IEEE single-precision number.
|}

Workbench ARexx Port

2023-07-08T16:39:33Z

Rob Cranley: /* ARexx Interface */

= ARexx Interface =

Workbench acts as an ARexx host under the name of '''WORKBENCH'''. It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the [[AmigaOS_Manual:_System_Tools#RexxMast|RexxMast]] program must have been started.

{| class="wikitable"
! style="text-align:left;"| Command
! style="text-align:left;"| Description
|- style="vertical-align:top;"
| [[#ACTIVATEWINDOW_command|ACTIVATEWINDOW]] WINDOW || This command will attempt to make a window the active one.
|- style="vertical-align:top;"
| [[#CHANGEWINDOW_command|CHANGEWINDOW]] WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N || This command will attempt to change the size and the position of a window.
|- style="vertical-align:top;"
| [[#DELETE_command|DELETE]] NAME/A,ALL/S || This command is for deleting files and drawers (and their contents).
|- style="vertical-align:top;"
| [[#FAULT_command|FAULT]] CODE/A/N || This command will return a human readable explanation corresponding to an error code.
|- style="vertical-align:top;"
| [[#GETATTR_command|GETATTR]] OBJECT/A,NAME/K,STEM/K,VAR/K || This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.
|- style="vertical-align:top;"
| [[#HELP_command|HELP]] COMMAND/K,MENUS/S,PROMPT/S || This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.
|- style="vertical-align:top;"
| [[#ICON_command|ICON]] WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K || This command is for manipulating the icons displayed in a window.
|- style="vertical-align:top;"
| [[#INFO_command|INFO]] NAME/A || This command is for opening the Workbench icon information requester.
|- style="vertical-align:top;"
| [[#KEYBOARD_command|KEYBOARD]] NAME/A,ADD/S,REMOVE/S,KEY,CMD/F || This command can be used to bind ARexx commands to key combinations.
|- style="vertical-align:top;"
| [[#LOCKGUI_command|LOCKGUI]] || This command will block access to all Workbench drawer windows.
|- style="vertical-align:top;"
| [[#MENU_command|MENU]] WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F || This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.
|- style="vertical-align:top;"
| [[#MOVEWINDOW_command|MOVEWINDOW]] WINDOW,LEFTEDGE/N,TOPEDGE/N || This command will attempt to change the position of a window.
|- style="vertical-align:top;"
| [[#NEWDRAWER_command|NEWDRAWER]] NAME/A || This command is for creating new drawers.
|- style="vertical-align:top;"
| [[#RENAME_command|RENAME]] OLDNAME/A,NEWNAME/A || This command is for renaming files, drawers and volumes.
|- style="vertical-align:top;"
| [[#RX_command|RX]] CONSOLE/S,ASYNC/S,CMD/A/F || This command is for executing ARexx scripts and commands.
|- style="vertical-align:top;"
| [[#SIZEWINDOW_command|SIZEWINDOW]] WINDOW,WIDTH/N,HEIGHT/N || This command will attempt to change the size of a window.
|- style="vertical-align:top;"
| [[#UNLOCKGUI_command|UNLOCKGUI]] || This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.
|- style="vertical-align:top;"
| [[#UNZOOMWINDOW_command|UNZOOMWINDOW]] WINDOW || This command will attempt to return a window to its original position and dimensions.
|- style="vertical-align:top;"
| [[#VIEW_command|VIEW]] WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S || This command will change the position of the viewable display area of a window.
|- style="vertical-align:top;"
| [[#WINDOW_command|WINDOW]] WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K || This command will change, open, close or snapshot windows.
|- style="vertical-align:top;"
| [[#WINDOWTOBACK_command|WINDOWTOBACK]] WINDOW || This command will push a window into the background.
|- style="vertical-align:top;"
| [[#WINDOWTOFRONT_command|WINDOWTOFRONT]] WINDOW || This command will bring a window to the foreground.
|- style="vertical-align:top;"
| [[#ZOOMWINDOW_command|ZOOMWINDOW]] WINDOW || This command will change a window to alternate position and dimensions.
|}

== ACTIVATEWINDOW command ==

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Activate the root window. */
ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

== CHANGEWINDOW command ==

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

== DELETE command ==

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
<syntaxhighlight lang="rexx">
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

== FAULT command ==

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

== GETATTR command ==

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
<syntaxhighlight lang="rexx">
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO ( window_list.count - 1 )
SAY window_list.i
END

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

== HELP command ==

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
<syntaxhighlight lang="rexx">
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR' command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

== ICON command ==

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

== INFO command ==

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

== KEYBOARD command ==

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

== LOCKGUI command ==

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
<syntaxhighlight lang="rexx">
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

== MENU command ==

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

== MOVEWINDOW command ==

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

== NEWDRAWER command ==

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
<syntaxhighlight lang="rexx">
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

== RENAME command ==

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
<syntaxhighlight lang="rexx">
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

== RX command ==

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

== SIZEWINDOW command ==

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window size to 200x100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

== UNLOCKGUI command ==

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
<syntaxhighlight lang="rexx">
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

== UNZOOMWINDOW command ==

; Purpose:
: This command will attempt to return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

== VIEW command ==

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Moves the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Moves the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Moves the view left by about 1/8 of the window width. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Moves the view right by about 1/8 of the window width. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window's current view position, use the GETATTR command and query the window's WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

== WINDOW command ==

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

== WINDOWTOBACK command ==

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

== WINDOWTOFRONT command ==

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

== ZOOMWINDOW command ==

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

Workbench ARexx Port

2023-07-08T16:38:46Z

Rob Cranley: /* ARexx Interface */ Fixed internal links in top table

= ARexx Interface =

Workbench acts as an ARexx host under the name of '''WORKBENCH'''. It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the [[AmigaOS_Manual:_System_Tools#RexxMast|RexxMast]] program must have been started.

{| class="wikitable"
! style="text-align:left;"| Command
! style="text-align:left;"| Description
|- style="vertical-align:top;"
| [[ACTIVATEWINDOW_command|ACTIVATEWINDOW]] WINDOW || This command will attempt to make a window the active one.
|- style="vertical-align:top;"
| [[CHANGEWINDOW_command|CHANGEWINDOW]] WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N || This command will attempt to change the size and the position of a window.
|- style="vertical-align:top;"
| [[DELETE_command|DELETE]] NAME/A,ALL/S || This command is for deleting files and drawers (and their contents).
|- style="vertical-align:top;"
| [[FAULT_command|FAULT]] CODE/A/N || This command will return a human readable explanation corresponding to an error code.
|- style="vertical-align:top;"
| [[GETATTR_command|GETATTR]] OBJECT/A,NAME/K,STEM/K,VAR/K || This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.
|- style="vertical-align:top;"
| [[HELP_command|HELP]] COMMAND/K,MENUS/S,PROMPT/S || This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.
|- style="vertical-align:top;"
| [[ICON_command|ICON]] WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K || This command is for manipulating the icons displayed in a window.
|- style="vertical-align:top;"
| [[INFO_command|INFO]] NAME/A || This command is for opening the Workbench icon information requester.
|- style="vertical-align:top;"
| [[KEYBOARD_command|KEYBOARD]] NAME/A,ADD/S,REMOVE/S,KEY,CMD/F || This command can be used to bind ARexx commands to key combinations.
|- style="vertical-align:top;"
| [[LOCKGUI_command|LOCKGUI]] || This command will block access to all Workbench drawer windows.
|- style="vertical-align:top;"
| [[MENU_command|MENU]] WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F || This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.
|- style="vertical-align:top;"
| [[MOVEWINDOW_command|MOVEWINDOW]] WINDOW,LEFTEDGE/N,TOPEDGE/N || This command will attempt to change the position of a window.
|- style="vertical-align:top;"
| [[NEWDRAWER_command|NEWDRAWER]] NAME/A || This command is for creating new drawers.
|- style="vertical-align:top;"
| [[RENAME_command|RENAME]] OLDNAME/A,NEWNAME/A || This command is for renaming files, drawers and volumes.
|- style="vertical-align:top;"
| [[RX_command|RX]] CONSOLE/S,ASYNC/S,CMD/A/F || This command is for executing ARexx scripts and commands.
|- style="vertical-align:top;"
| [[SIZEWINDOW_command|SIZEWINDOW]] WINDOW,WIDTH/N,HEIGHT/N || This command will attempt to change the size of a window.
|- style="vertical-align:top;"
| [[UNLOCKGUI_command|UNLOCKGUI]] || This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.
|- style="vertical-align:top;"
| [[UNZOOMWINDOW_command|UNZOOMWINDOW]] WINDOW || This command will attempt to return a window to its original position and dimensions.
|- style="vertical-align:top;"
| [[VIEW_command|VIEW]] WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S || This command will change the position of the viewable display area of a window.
|- style="vertical-align:top;"
| [[WINDOW_command|WINDOW]] WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K || This command will change, open, close or snapshot windows.
|- style="vertical-align:top;"
| [[WINDOWTOBACK_command|WINDOWTOBACK]] WINDOW || This command will push a window into the background.
|- style="vertical-align:top;"
| [[WINDOWTOFRONT_command|WINDOWTOFRONT]] WINDOW || This command will bring a window to the foreground.
|- style="vertical-align:top;"
| [[ZOOMWINDOW_command|ZOOMWINDOW]] WINDOW || This command will change a window to alternate position and dimensions.
|}

== ACTIVATEWINDOW command ==

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Activate the root window. */
ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

== CHANGEWINDOW command ==

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

== DELETE command ==

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
<syntaxhighlight lang="rexx">
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

== FAULT command ==

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

== GETATTR command ==

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
<syntaxhighlight lang="rexx">
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO ( window_list.count - 1 )
SAY window_list.i
END

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

== HELP command ==

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
<syntaxhighlight lang="rexx">
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR' command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

== ICON command ==

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

== INFO command ==

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

== KEYBOARD command ==

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

== LOCKGUI command ==

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
<syntaxhighlight lang="rexx">
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

== MENU command ==

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

== MOVEWINDOW command ==

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

== NEWDRAWER command ==

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
<syntaxhighlight lang="rexx">
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

== RENAME command ==

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
<syntaxhighlight lang="rexx">
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

== RX command ==

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

== SIZEWINDOW command ==

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window size to 200x100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

== UNLOCKGUI command ==

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
<syntaxhighlight lang="rexx">
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

== UNZOOMWINDOW command ==

; Purpose:
: This command will attempt to return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

== VIEW command ==

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Moves the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Moves the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Moves the view left by about 1/8 of the window width. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Moves the view right by about 1/8 of the window width. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window's current view position, use the GETATTR command and query the window's WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

== WINDOW command ==

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

== WINDOWTOBACK command ==

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

== WINDOWTOFRONT command ==

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

== ZOOMWINDOW command ==

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: ARexx

2023-07-04T21:50:00Z

Rob Cranley: /* Sources of Additional Information */ Added link to Workbench ARexx port information

= Welcome =

ARexx, the Amiga counterpart of the IBM REXX programming language, provides the freedom to customize your work environment. It is especially useful as a scripting language which allows you to control and modify applications and to direct how they interact with each other.

This manual introduces you to ARexx, tells you how to create ARexx programs and provides a reference section of ARexx commands.

[[AmigaOS Manual: ARexx Introducing ARexx|Chapter 1. Introducing ARexx]] This chapter gives an overview of ARexx, how it works on the Amiga, and the basic features of the programming language.

[[AmigaOS Manual: ARexx Getting Started|Chapter 2. Getting Started]] This chapter tells you where to store your ARexx programs, how to execute an ARexx program, and provides several programming examples.

[[AmigaOS Manual: ARexx Elements of ARexx|Chapter 3. Elements of ARexx]] This chapter details the rules and concepts that make up the ARexx programming language.

[[AmigaOS Manual: ARexx Instructions|Chapter 4. Instructions]] This chapter contains an alphabetical listing of ARexx instructions, which are language statements that dictate an action.

[[AmigaOS Manual: ARexx Functions|Chapter 5. Functions]] This chapter describes the use of functions, which are program statements used by ARexx, and provides an alphabetical listing of the built-in ARexx functions.

[[AmigaOS Manual: ARexx Debugging|Chapter 6. Debugging]] This chapter focuses on the source-level debugging features used in the development and testing of programs.

[[AmigaOS Manual: ARexx Parsing|Chapter 7. Parsing]] This chapter explains how to extract patterns of information from strings.

[[AmigaOS Manual: ARexx Input and Output|Chapter 8. Input and Output]] This chapter explains the ARexx's input and output model.

[[AmigaOS Manual: Sounds|Chapter 9. Sounds]] This chapter explains how to record and play sounds.

[[AmigaOS Manual: Printing|Chapter 10. Printing]] This chapter explains how to print.

[[AmigaOS Manual: Serial and parallel ports|Chapter 11. Serial and parallel ports]] This chapter explains how to receive and send data through the serial and parallel ports.

[[AmigaOS Manual: Network resources|Chapter 12. Network resources]] This chapter explains how you can connect to a remote server and exchange data with it.

[[AmigaOS Manual: ARexx Error Messages|Appendix A. Error Messages]] This appendix lists the ARexx error messages.

[[AmigaOS Manual: ARexx Command Utilities|Appendix B. Command Utilities]] This appendix lists the ARexx commands that can be run from the Shell.

[[AmigaOS Manual: ARexx Special Variables|Appendix C. Special Variables]] This appendix lists the ARexx special variables.

[[AmigaOS Manual: External Function Libraries|Appendix D. External Function Libraries]] This appendix lists the external ARexx function libraries.

[[AmigaOS Manual: External Function Hosts|Appendix E. External Function Hosts]] This appendix lists the external function hosts.

[[AmigaOS Manual: ARexx Compatible Applications|Appendix F. ARexx Compatible Applications]] This appendix lists the operating system applications which have an ARexx interface.

[[AmigaOS Manual: Control Sequences|Appendix G. Control Sequences]] This appendix lists the control sequences for the text output.

[[AmigaOS Manual: Limits|Appendix H. Limits]] This appendix lists the ARexx implementation limits.

[[AmigaOS Manual: ARexx Glossary|Glossary]] The glossary contains common ARexx terms.

= Document Conventions =

The following conventions are used in this manual:

; KEYWORDS
: Keywords are displayed in all uppercase letters, however, the arguments are case-insensitive.

; | (vertical bar)
: Alternative selections are separated by a vertical bar.

; { } (braces)
: Required alternatives are enclosed by braces.

; [ ] (brackets)
: Optional instruction parts are enclosed in brackets.

; <n>
: Variables are displayed in angle brackets. Do not enter the angle brackets when entering the variable.

; Courier
: Text appearing in the Courier font represents output from your ARexx programs or other information that displays on your screen.

; Key1 + Key2
: Key combinations displayed with a plus sign (+) connecting them indicates pressing the keys simultaneously.

; Key1, Key2
: Key combinations displayed with a comma sign (,) separating them indicates pressing the keys in sequence.

; Amiga keys
: Two keys on the Amiga keyboard used for special functions. The left Amiga key is to the left of the space bar and is marked with a large solid A. The right Amiga key is to the right of the space bar and is an outlined A.

= Sources of Additional Information =

Further information on learning and using ARexx can be found in:

<div style="column-count: 2; font-size: 95%;">
* [[Special:BookSources/978-0135973295|Modern Programming Using REXX]], by R.P. O'Hara and D.G. Gomberg, Prentice-Hall, 1985.
* [[Special:BookSources/978-0137806515|The REXX Language: A Practical Approach to Programming]], by M.F. Cowlishaw, Prentice-Hall, 1985.
* [[Special:BookSources/978-0070153059|Programming in REXX]], J. Ranade IBM Series, by Charles Daney, McGraw-Hill Companies, 1990.
* [[Special:BookSources/978-1557551146|Using ARexx on the Amiga]], by Chris Zamara and Nick Sullivan, Abacus, 1991.
* [[Libraries|Libraries]]
* [[Workbench_ARexx_Port|The Workbench ARexx Port]]
</div>

Communities

<div style="column-count: 2; font-size: 95%;">
* [http://www.rexxla.org/ The Rexx Language Association]
</div>

AmigaOS Manual: Workbench Using

2022-11-29T09:06:07Z

Rob Cranley: /* ARexx Interface */ Moved advanced reference documentation of ARexx interface to a more intuitive and suitable section than the basic Workbench use section for clarity, readability and consistency.

This chapter describes the Amiga Workbench, an icon-based environment that allows you to give instructions by manipulating graphic symbols with a mouse rather than by typing in commands at a keyboard. Included in this chapter are descriptions of the following:

* The Workbench Screen
* The Workbench Window
* The Workbench Menus
* Workbench Programs

= Workbench Screen =

The Workbench screen, illustrated in Figure 4-1, is the primary visual component of your system. Icons and other windows appear on it.

The Workbench screen is identified by the Amiga Workbench title bar located along the top border of the display. The Workbench screen's title bar also displays the number of bytes of graphics (Chip) memory and other (Fast) memory currently available when any window, except a Shell window is selected.

The Amiga provides Preferences editors (described in Chapter 5) that allow you to customize the Workbench screen. You can define an extra-large virtual Workbench screen that is larger than the viewable area with more space for windows.

== Workbench Window ==

When you boot you Amiga, the Workbench window fills the Workbench screen. This window contains icons for any floppy disks inserted into floppy drives, the Ram Disk, and any other icons determined by your system's configuration.

Although the Workbench window appears and functions like an application window, it is an essential part of the Workbench screen.

[[File:WorkbenchFig4-1.png|frame|none|Workbench Screen]]

= Workbench Menus =

The workbench has the following four menus:

{| class="wikitable"
| Workbench || Contains options for working with Workbench and windows opened on the Workbench screen.
|-
| Windows || Contains options for working within the currently selected window.
|-
| Icons || Contains options for working with the currently selected icon or group of icons.
|-
| Tools || Is available for applications to use or for user-created menu items.
|}

== Workbench Menu ==

The Workbench menu contains general Workbench options and options for windows opened on the Workbench screen. You can, for example, use the Workbench menu to update the screen display or see which version of the system software is in use.

On the Workbench menu you can select the following options:

=== Update software ===

=== Backdrop ===

The Backdrop menu item creates more room on the Workbench screen for displaying windows and icons. Backdrop switches between a normal window for your Workbench and a special borderless window that is always behind other windows opened on the Workbench.

Choosing Backdrop removes the Workbench window borders so that the disk icons appear to be on the Workbench screen without being enclosed in a window. To return to the normal Workbench window, choose Backdrop again. Backdrop is reset to off if you power off or reboot your computer. To save your Backdrop selection choose the Snapshot item in the Windows menu while the Workbench window is selected.

=== Execute Command ===

{{Note|This menu item is provided for users familiar with AmigaDOS.}}

The Execute Command executes (starts) an AmigaDOS command without opening a Shell window. Figure 4-2 illustrates an Execute Command requester.

[[File:WorkbenchFig4-2.png|frame|none|Execute Command Window]]

Enter the command and all of its arguments in the requester.

A Workbench Output Window is automatically opened when a command results in output and it remains there until you select its close gadget. The current directory for an Execute Command operation is RAM:.

=== Open volume ===

=== Redraw All ===

Redraw All redraws all open Workbench windows in the Workbench screen and can be used in the event of a disturbance to the Workbench. If Redraw All does not restore the windows to their proper appearance, reboot the computer.

=== Update All ===

Update All reopens each open Workbench window, updating its appearance to show its current state.

{{Note|If you have several windows open and have been using the Shell or an application to change to the contents of a disk, the changes may not be reflected in its windows until you close the windows and reopen them or choose Update All.}}

=== Last Message ===

Last Message retrieves the last information or error message that appeared on the title bar.

=== About ===

About opens a requester showing the internal version number of the Workbench and Kickstart software, as well as copyright information. Select the OK gadget to close the requester.

=== Quit ===

Quit closes all Workbench operations, making additional RAM available if needed. The Workbench does not close if there are any programs running, including programs that do not open a window and programs that are in your WBStartup drawer.

The only windows that can remain open while using Quit are the disk, drawer, and Shell windows. Once you OK the Quit requester, a Shell window is your only link to the Amiga. You can use the Shell icon in the System drawer to open a Shell window before quitting the Workbench.

Return to the Workbench by typing LOADWB (load Workbench) at the Shell prompt and pressing Return. If there is no Shell window open, you must reboot to return to the Workbench.

The close gadget on the Workbench window is the same as choosing Quit.

== Window Menu ==

The Window menu is only available when a Workbench window is selected. The Window menu allows you to create new drawers, select the contents of the window, rearrange the contents, change how the contents are displayed, and close the window. The available window options are:

=== New Drawer ===

To create a new drawer:

# Select the window in which you want to create the drawer.
# Choose New Drawer from the Window menu. The drawer is created and named "Unnamed1".
# A Rename requester prompts you to change the name of the drawer.
# Delete the existing name using the DEL key, enter a new name, and press Return or select OK. Selecting Cancel leaves the default name on the new drawer.

=== Open Parent ===

A window's parent is the window that contains its icon. With the exception of the Workbench window, every Workbench disk window has a parent window.

Open Parent opens the selected window's parent or brings it to the front of the display if it is already open.

=== Close ===

Close closes and removes the selected window from the screen.

Mouse shortcut: For many windows, you can select the close gadget in the upper left corner of the window.

=== Update ===

Update redraws the selected window, including any changes made to the contents through the Shell or the Execute Command menu item. Such changes are not reflected until the window is updated or reopened.

=== Select Contents ===

Select Contents selects all of the icons in the current window.

=== Clean Up ===

Clean Up automatically arranges all the icons in the selected window so that they do not overlap. This arrangement is not saved until you use the Snapshot menu item described below.

=== Snapshot ===

Snapshot saves the arrangement and position of icons in a window. It is commonly used following Clean Up. Snapshot has a submenu containing two items: Window and All.

Snapshot Window saves the position and size of the selected window, as well as the Show and View By settings described below. However, it does not save the position of the icons in the window.

Snapshot All saves the position and other settings of all the icons in the selected window, as well as the position and size of the window.

=== Show ===

Show controls the types of icons that are displayed on a window. Show has two submenu items: Only Icons and All Files.

Show Only Icons is the default Show mode, displaying only those files and drawers that have icons (.info files).

Show All Files provides a pseudo-icon for each file or drawer in the selected window that does not have a real icon. Pseudo-icons can be treated like any other icon, including manipulating them with the menu items in the Icon menu.

You may have to scroll in the window to see the new pseudo-icons.

=== View By ===

View By changes how the information in the window is displayed. View By has four submenu items: Icons, Name, Date, and Size.

View By Icons is the window's default mode.

Choosing View By Name, View By Date, or View By Size displays a window's contents in text form, including the size of the file, its attributes (whether it can be read, deleted, executed, or written to), and its timestamp.

File and drawer names can be selected, opened, dragged, and manipulated just like icons.

View By Name sorts the file list in alphabetical order.

View By Date sorts the list in chronological order, with the most recently created file listed first.

View By Size sorts the list by size, listing the smallest file first.

== Icons Menu ==

The Icons menu allows you to work with the icons on the screen. An icon must be selected before the menu options illustrated in Figure 4-3 become available.

[[File:WorkbenchFig4-3.png|frame|none|Icons Menu]]

=== Open ===

Opening an icon makes a program or window available.

When you open a disk or drawer icon, a window displays the icons contained on that disk or in that drawer. When an individual project or tool is opened, the corresponding program starts.

Open an icon by selecting it an choosing Open.

Mouse Shortcut: Point to the icon and double-click the selection button.

=== Copy ===

Copy allows you to duplicate disks, drawers, programs, or files within a window. To copy material to another window, use the drag-copy method described in Chapter 3. Drag-copying is the easiest method of copying a disk on a two-floppy-system.

Use Copy for making backup copies of your disks.

To copy a drawer, project, or icon:

# Select the icon.
# Choose Copy from the Icons menu.

Copying disks on single-floppy disk drive systems entails a process known as swapping. Source and destination disks are swapped in the single drive as the system first reads information from the source disk and the writes it to the destination disk. The destination disk must be write-enabled, but need not be formatted since Copy formats the disk as it writes to it. Be sure to copy to disks of the same density as the original disks.

To copy a disk on a single-floppy disk drive system:

# Insert the source disk into the Amiga's internal disk drive.
# Select the source disk's icon.
# Choose Copy from the Icons menu. Insert the Workbench disk, if necessary.
# If the disk copy requires at least five swaps, a requester tells you how many swaps are needed. Closing any unnecessary windows or stopping any unwanted programs helps reduce the number of swaps.
# Select the Continue gadget in the swap requester. During the disk copy, the icon for the disk being copied is unavailable and is labeled "BUSY".
# Insert the source disk into the drive when prompted and select Continue. A horizontal bar gauge shows the percentage of the disk copy completed.
# Insert the destination disk into the drive when prompted and select Continue to copy the information read in from the source disk. Swap the disks as often as requested. When the copy is finished, a Disk Copy Finished message appears.
# Remove the destination disk from the drive and label it. The destination disk's icon is labeled with a copy_of_prefix (for example, copy_of_DataDisk).

=== Rename ===

Rename changes the name of an icon. It is used to remove the copy_of_prefix from something you copied, as well as for changing the names of drawers, disks, and files.

To rename an icon:

# Select the icon.
# Choose Rename from the Icons menu. A requester containing a text gadget displays the current name of the icon.
# Delete the old name using Backspace or right Amiga+X and enter the new name. Do not use spaces before or after the new name. Because embedded spaces are not visible, they can cause confusion if you have to type in the icon name again.
# Press Return. The new name appears under the icon.

=== Information ===

Information displays status information about the selected icon's file. Certain data can also be modified in the Information window. Figure 4-4 illustrates the Information window.

[[File:WorkbenchFig4-4.png|frame|none|Icon Information Window]]

Although the contents of the window varies with the icon, the following information is always displayed:

{| class="wikitable"
| title bar || The window title bar indicates the path to the icon.
|-
| name || The icon name and its type in parentheses (Volume, Drawer, Tool, Project, or Trashcan).
|-
| image || A picture of the icon.
|-
| size || The number of blocks and bytes that the disk, project, or tool fills.
|-
| stack || The amount of memory reserved as temporary storage for a specific tool.
|-
| last changed date || The date on which the icon was created or the last time it was changed (its timestamp).
|}

For a disk icon, the window also shows whether a disk is write-enabled (Read/Write) or write-protected (Read Only).

For a drawer, trashcan, project, or tool, the following attributes can be set or cleared by clicking on the attribute's check box.

{| class="wikitable"
| Script || If set, the file is a script (a text file of AmigaDOS commands) and can be run without using the EXECUTE command.
|-
| Archived || This attribute is set by backup programs to indicate that a file or directory has been archived (backed up). It is cleared whenever the file is saved.
|-
| Readable || If set, information in the file can be read. If this attribute is clear, a tool will not run and a project cannot be loaded by its Default Tool.
|-
| Writable || If set, information can be written into the file. Unless Writable is set, you cannot make changes to the file.
|-
| Executable || If set, the file is a tool that can be run from Workbench or the Shell. If this attribute is clear, the tool cannot be run from the Shell.
|-
| Deletable || If set, the drawer, project, or tool can be erased from the disk. If clear, the object is protected from deletion.
|}

If the icon represents a project, there is a Default Tool gadget. This specifies the path to the tool that created the project. When the project icon is opened, the default toll is also opened to work on the project.

If there is a Comments box, you can add a note of up to 79 characters by selecting the text gadget next to Comments, entering the text, and pressing Return.

The Tool Types box specifies different startup options for some programs or files. Icon Tool Types are described in Chapter 3.

To save any changes made to the Information window, select the Save gadget in the lower left corner.

=== Snapshot ===

Snapshot saves the positions of all the currently selected icons. The next time you open the window, the icons that you selected appear in their saved positions. You can save the positions of several icons at one time by using drag selection or extended selection.

To save the position of an icon:

# Select the icon.
# Choose Snapshot.

=== UnSnapshot ===

UnSnapshot cancels the snapshot position of an icon. The next time you open the window, the icons are rearranged.

To release the snapshot position of an icon:

# Select the icon.
# Choose UnSnapshot.

=== Leave Out ===

Leave Out moves an often-used icon out of its original window and into the Workbench window for faster access. The file represented by the icon remains in its original drawer on the disk; only the icon is moved. The icon remains in the Workbench window, even if the machine is rebooted. This menu item cannot be used with disks or the Trashcan.

To use Leave Out:

# Select the icon.
# Choose Leave Out.

The icon moves into the Workbench window.

=== Put Away ===

Put Away returns an icon that was left out to its original drawer.

To use Put Away:

# Select the icon.
# Choose Put Away.

=== Delete ===

Delete erases files and their icons from your disks.

{{Note|title=Caution|text=Use Delete with caution; you cannot retrieve something that was deleted.}}

To delete a file or drawer:

# Select its icon. Use drag selection or extended selection to choose more than one icon to be deleted. Disks and the Trashcan cannot be removed with Delete.
# Choose Delete from the Icons menu. A warning requester appears, listing the number of files and drawers currently selected. Verify that you want to erase permanently the items listed. Remember that if you delete a drawer, everything contained in it is also deleted.
# Select the OK gadget. The icon and the files associated with it are erased from your disk. If you do not want to delete everything currently selected, select the Cancel gadget.

=== Format Disk ===

Formatting a disk prepares it for storing information. Format disks that are new and unformatted, disks that develop errors, or disks on which you wish to use different file system options.

{{Note|title=Caution|text=Formatting erases all information on a disk. Be careful not to format disks that hold information that you do not want to lose, particularly your original system and software applications disks.}}

Select the icon of the disk to be formatted and choose Format Disk from the Icons menu. The Format window, illustrated in Figure 4-5, displays the current information about the disk. If the disk is already formatted, its volume name and the percentage of the disk currently in use are displayed. A text gadget allows you to enter a new Volume name for the disk.

[[File:WorkbenchFig4-5.png|frame|none|Format Window]]

Five items can be selected (checked) in the Format window:

{| class="wikitable"
| Put Trashcan || Allows you to put a Trashcan on the disk.
|-
| Fast File System || Allows the Amiga to fit more information on a disk. It is faster than the standard file system. Fast File System disks are incompatible with Workbench software releases prior to Release 2.
|-
| International Mode || Fully supports international characters in file names. We recommend that you set this option on. International Mode is incompatible with Workbench software releases prior to Release 2.
|-
| Directory Cache || Speeds up the opening of drawers, file requesters, and listings. This option is off by default. Disks using Directory Cache are incompatible with Workbench software releases prior to Release 3.
|-
| Long names ||
|}

Fast File System, International Mode, and Directory Cache can only be specified for AmigaDOS disks. Selecting the Directory Cache option automatically selects International Mode. Disks created with the Directory Cache option can only be read by Amigas running Workbench Release 3.0 and above.

Quick format is for reformatting a disk that was previously formatted. You cannot format a new blank disk with Quick Format. Choosing the Quick Format option is faster than formatting the entire disk; however, it does not detect any read/write errors on the disk that could be eliminated by a full format.

When the disk is formatted, if you did not change he name in the Format window, it is labeled Empty. This name can be changed using the Rename item in the Icons menu.

==== Formatting Hard Disks ====

You must format your hard disk under the following conditions if:

* It is a new unformatted disk.
* You have a serious unrecoverable disk error.
* You have repartitioned the disk.
* You wish to use a different file system option on the disk, such as the Directory Cache option.

Before reformatting your hard disk, be sure to back up all important information from the disk.

The Ram Disk cannot be formatted. If you accidentally select the Ram Disk for formatting, a requester reports that there is a format failure and requires you to select Cancel.

If you have more than one disk icon selected, more than one Format window opens when the Format Disk item is selected from the Icons menu. The format windows open one on top of another so that only one Format window is initially visible. Drag the windows until all are visible. Be sure to check the Current Information field in the Format window for the intended Device and Volume names before allowing the format to continue.

{{Note|title=Caution|text=Check the device and volume names carefully. If you accidentally reformat your hard disk instead of a floppy, you will eras all of your files.}}

==== Formatting Floppy Disks ====

The Amiga does not recognize floppy disks that are not formatted; therefore, blank disks must be formatted before anything can be written on them. Disks can be formatted at any time, including while running one or more applications. Disks usually have to be formatted only once.

To determine if a floppy disk is formatted, insert it into a floppy drive and check the disk icon on the Workbench screen. If the Amiga cannot recognize the disk, four question marks (????) follow the drive designation in the icon's label.

To format a blank disk:

# Write-enable the disk and insert it into a floppy drive.
# Select its disk icon when it appears on the Workbench screen.
# Holding down the menu button, point to the Icons menu, move the pointer to the Format Disk item, and release the button.
# If you have a hard drive on your Amiga, skip to Step 7. If you do not have a hard drive on your Amiga, at the requester insert the workbench disk into any drive.
# When the Format program has been loaded from the Workbench disk remove the disk from the drive.
# At the requester, insert the blank disk and select the Continue gadget.
# In the Format window, change the volume name of the disk from the default Empty; choose whether to put the Trashcan on the disk an other options. Then select Format to continue.
# A requester warning that all data will be lost if you continue the format appears on the screen. Select either Format or Cancel.
# During the format a window is displayed that shows the percentage of disk that has been formatted. This window also has a Stop gadget that allows you to cancel the format at any time.

A disk that is partially formatted is not usable.

To format a disk as an MS-DOS disk through CrossDOS, you must have a CrossDos DOSdriver activated. If the PC0 DOSdriver is active, select the disk icon labeled PC0:???? for formatting.

=== Empty Trash ===

Empty Trash deletes the contents of the Trashcan. To use the Trashcan, drag an icon over the Trashcan icon and release the selection button. The icon is then stored in the Trashcan drawer until you decide to permanently throw it away with Empty Trash.

To delete an icon with Empty Trash:

# Drag the icon over the Trashcan and release the selection button. If you open the Trashcan, the icon appears in the Trashcan window.
# Make sure the Trashcan icon is selected (the lid is displayed open) and choose Empty Trash from the Icons menu. The Trashcan contents are deleted.

An icon can be retrieved from the Trashcan as long as Empty Trash is not chosen. Retrieve an icon by opening the Trashcan window and dragging the icon into any window. You may wish to open the Trashcan window in Show All Files mode and verify its contents before choosing Empty Trash.

The following rules apply to the Trashcan:

* Icons can only be moved to a Trashcan on the same volume.
* Disks cannot be deleted using the Trashcan.
* The Trashcan cannot be moved into a drawer.
* The Trashcan cannot be left out.
* The Trashcan cannot be deleted with the Delete menu item.

== Tools Menu ==

The Tools Menu initially contains only ResetWB for resetting the Workbench. Other Amiga applications and utilities can add items to the Tools menu. Consult the documentation that came with your applications software for information on adding items to the Tools menu.

= ARexx Interface =

Workbench acts as an ARexx host under the name of '''WORKBENCH'''. It supports a number of commands as described in [[Workbench ARexx Port|Appendix F: Workbench ARexx Port]].

= Workbench Programs =

Everything under this title is obsolete!

== WBStartup Drawer ==

This drawer is obsolete!

The WBStartup drawer is provided to hold icons for programs that you want opened at the time the Workbench is started. For example, you may want the Clock program running when you reboot or power on your Amiga. Drag the icon for each desired program into the WBStartup window. The WBStartup drawer is empty by default.

=== Tool Types ===

Programs in the WBStartup drawer can include the following Tool Types:

{| class="wikitable"
| DONOTWAIT || Normally the Workbench waits for one program to finish before it opens the next. DONOTWAIT overrides this, which can cause unwanted requesters after booting. DONOTWAIT does not take an argument.
|-
| WAIT=<seconds> || Specifies how many seconds the Workbench should wait before opening the next icon in the WBStartup drawer.
|-
| STARTPRI=<priority> || Assigns a priority to an icon so that it opens before or after other icons. By default, all icons have a priority of 0. The acceptable range is from -128 to +127; the higher the value, the higher the program's priority.
|}

== Expansion Drawer ==

This drawer is obsolete!

The Expansion drawer is used to store software drivers for additional hardware devices that you install on your Amiga. If a hardware device uses the Expansion drawer, it is explained in the documentation packaged with that product. To activate the new device, drag the icon for the device's software driver into the Expansion drawer and then reboot your system to make the device available.

AmigaOS Manual: Workbench

2022-11-29T09:02:53Z

Rob Cranley: Added link to appendix for ARexx interface details

{{WIP}}
= Welcome =

The Amiga line of personal computers offers a unique combination of versatility, computing power, and usability.

By working with the Amiga's easy-to-learn, easy-to-use Workbench interface, any level user - even a beginner - can quickly accomplish tasks or run programs. With Workbench there is no need to memorize long lists of commands. All you have to do is use your mouse to select icons (small pictures that represent tasks) or items from list-like menus to control your Amiga.

Workbench also offers you the freedom to design your own custom system configuration using the Preferences editors and Tools programs provided. You can, for example, create icons and menus for the tasks that you do most. You can fine-tune the system to take ultimate advantage of your Amiga's superior graphics capability.

Workbench lets you work in your own language and use the monetary and numeric symbols with which you are familiar. Through a simple easy-to-follow process, you can display the Workbench in the language of your choice.

Workbench is not only user-friendly and flexible, but it is also extremely powerful. The Workbench takes full advantage of the Amiga's ability to multitask, or run several independent programs simultaneously. By simply clicking on an icon, you can switch between programs when you need to. Not only can programs run at the same time on the Amiga, but they can also share information and computer resources, allowing you to do more work without requiring additional software and memory.

Your Amiga and the Workbench provide you with a powerful tool for work or pleasure. Enjoy it!

= Using This Manual =

This manual provides operational instructions and reference material for using your Amiga Workbench. If you have never used an Amiga before, read the entire manual to become familiar with the general operations of your Amiga and the Workbench system. Once you learn the basics, this document can serve as a reference tool. If you are already familiar with the Amiga, be sure to read through the manual for new information that you may not know.

[[AmigaOS Manual: Workbench Before You Start|Chapter 1. Before You Start]] This chapter provides instructions for things you need to do and information you need to know before you start using your Amiga, including language selection and installation procedures.

[[AmigaOS Manual: Workbench Basic Operations|Chapter 2. Basic Operations]] This chapter describes starting your Amiga, creating and managing disks and files, and using your mouse and keyboard.

[[AmigaOS Manual: Workbench Fundamentals|Chapter 3. Fundaments of Workbench]] This chapter describes the elements that comprise the Workbench environment, including screens, windows, menus, icons, gadgets, and requesters.

[[AmigaOS Manual: Workbench Using|Chapter 4. Using Workbench]] This chapter provides an overview of the Amiga Workbench system and explains how to command Workbench through its ARexx interface.

[[AmigaOS Manual: Workbench Preferences|Chapter 5. Preferences]] This chapter details the information needed to set your Amiga to work monitors, printers, and other peripherals and how to customize your individual Workbench environment.

[[AmigaOS Manual: Emulation|Chapter 6. Classic Amiga Emulation]] This chapter provides information on how to run Classic Amiga programs.

[[AmigaOS Manual: Internet|Chapter 7. Internet]] This chapter explains the programs in the Internet drawer.

[[AmigaOS Manual: System Tools|Chapter 8. System Tools]] This chapter explains the control programs in the System drawer.

[[AmigaOS Manual: Utilities|Chapter 9. Utilities]] This chapter explains the programs in the Utilities drawer.

[[AmigaOS Manual: Devices|Chapter 10. Devices]] In this chapter you will learn how to install and uninstall data types, DOS drivers, key maps, monitors, net interfaces, and printers.

[[AmigaOS Manual: Workbench Localization|Chapter 11. Localization]] This chapter describes the localization options available on the Amiga Workbench including language, date, time, and numeric format.

[[AmigaOS Manual: Workbench Monitors|Chapter 12. Monitors]] This chapter describes the monitors that you can use with your Amiga. It includes choosing a monitor and monitor settings for your system. Advanced Graphics Architecture (AGA or AA)-specific information, and a list of the monitor display modes.

[[AmigaOS Manual: Workbench Fonts|Chapter 13. Fonts]] This chapter explains how to install and use both bitmap and outline fonts on the Amiga.

[[AmigaOS Manual: Workbench Printers|Chapter 14. Printers]] This chapter describes printers and printer options for producing the output that best suits your needs and equipment.

[[AmigaOS Manual: Workbench Other Programs|Chapter 15. Other Amiga Programs]] This chapter explains the programs in the Utilities and Commodities drawers.

[[AmigaOS Manual: Workbench CrossDOS|Chapter 16. CrossDOS]] This chapter describes CrossDOS, which allows you to read and write MS-DOS formatted disks on your Amiga.

[[AmigaOS_Manual:_AmigaDOS_Using_the_Editors#ED|Chapter 17. ED Editor]] This chapter explains how to use the ED text editor to create and edit text files.

[[AmigaOS Manual: Workbench Troubleshooting|Appendix A. Troubleshooting]] This appendix provides solutions to common problems that can occur.

Appendix B. Using Floppy-Only Systems: This appendix provides information for using floppy-only Amigas, including how to copy disks, how to set Preferences, and how to work faster. '''Obsolete'''

[[AmigaOS Manual: AmigaGuide|Appendix C. AmigaGuide]] This appendix describes AmigaGuide, a hypertext on-line help system available with some applications. Included in this chapter are instructions for using AmigaGuide and descriptions of its menus.

[[AmigaOS Manual: Early Startup|Appendix D. Special Early Startup Control Options]] This appendix provides information on special boot options that allow you to choose display options, diagnose expansion board failures, and to disable devices and processor caches for software compatibility.

[[Keyboard Shortcuts|Appendix E. Keyboard Shortcuts]] This appendix lists the AmigaOS keyboard shortcuts.

[[Workbench ARexx Port|Appendix F. Workbench ARexx Port]] This appendix documents the Workbench ARexx port and supported ARexx commands.

[[AmigaOS Manual: Workbench Glossary|Glossary]]

= Documentation Conventions =

The following conventions are used in this manual:

{| class="wikitable"
| KEYWORDS || Keywords are displayed in all upper case letters, however, the arguments are not case-sensitive.
|-
| <n> || Angle brackets enclose variable information that you must supply. In place of <n>, substitute the value, text, or option desired. Do not enter the angle brackets when entering the variable.
|-
| Courier || Text appearing in the Courier font represents information displayed on your screen.
|-
| Key1 + Key2 || Key combinations displayed with a + (plus) sign connecting them indicate pressing the keys simultaneously. For example, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">O</kbd> means to hold down the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> key and, while holding it down, press <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">O</kbd>.
|-
| Key1, Key2 || Key combinations displayed with a comma separating them indicate pressing the keys in sequence. For example, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Esc</kbd>,<kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">O</kbd>,<kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">P</kbd> means to press the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Esc</kbd> key, followed by the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">O</kbd> key, and then followed by the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">P</kbd> key.
|-
| Amiga keys || Two keys on the Amiga keyboard used for special functions. The left Amiga key is to the left of the space bar and is marked with a large solid A. The right Amiga key is to the right of the space bar and is an outlined A.
|}

Workbench ARexx Port

2022-11-29T09:02:06Z

Rob Cranley: Created new appendix as a more intuitive and suitable place for the Workbench ARexx documentation

= ARexx Interface =

Workbench acts as an ARexx host under the name of '''WORKBENCH'''. It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the [[AmigaOS_Manual:_System_Tools#RexxMast|RexxMast]] program must have been started.

{| class="wikitable"
! style="text-align:left;"| Command
! style="text-align:left;"| Description
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#ACTIVATEWINDOW_command|ACTIVATEWINDOW]] WINDOW || This command will attempt to make a window the active one.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#CHANGEWINDOW_command|CHANGEWINDOW]] WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N || This command will attempt to change the size and the position of a window.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#DELETE_command|DELETE]] NAME/A,ALL/S || This command is for deleting files and drawers (and their contents).
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#FAULT_command|FAULT]] CODE/A/N || This command will return a human readable explanation corresponding to an error code.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#GETATTR_command|GETATTR]] OBJECT/A,NAME/K,STEM/K,VAR/K || This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#HELP_command|HELP]] COMMAND/K,MENUS/S,PROMPT/S || This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#ICON_command|ICON]] WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K || This command is for manipulating the icons displayed in a window.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#INFO_command|INFO]] NAME/A || This command is for opening the Workbench icon information requester.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#KEYBOARD_command|KEYBOARD]] NAME/A,ADD/S,REMOVE/S,KEY,CMD/F || This command can be used to bind ARexx commands to key combinations.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#LOCKGUI_command|LOCKGUI]] || This command will block access to all Workbench drawer windows.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#MENU_command|MENU]] WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F || This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#MOVEWINDOW_command|MOVEWINDOW]] WINDOW,LEFTEDGE/N,TOPEDGE/N || This command will attempt to change the position of a window.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#NEWDRAWER_command|NEWDRAWER]] NAME/A || This command is for creating new drawers.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#RENAME_command|RENAME]] OLDNAME/A,NEWNAME/A || This command is for renaming files, drawers and volumes.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#RX_command|RX]] CONSOLE/S,ASYNC/S,CMD/A/F || This command is for executing ARexx scripts and commands.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#SIZEWINDOW_command|SIZEWINDOW]] WINDOW,WIDTH/N,HEIGHT/N || This command will attempt to change the size of a window.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#UNLOCKGUI_command|UNLOCKGUI]] || This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#UNZOOMWINDOW_command|UNZOOMWINDOW]] WINDOW || This command will attempt to return a window to its original position and dimensions.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#VIEW_command|VIEW]] WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S || This command will change the position of the viewable display area of a window.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#WINDOW_command|WINDOW]] WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K || This command will change, open, close or snapshot windows.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#WINDOWTOBACK_command|WINDOWTOBACK]] WINDOW || This command will push a window into the background.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#WINDOWTOFRONT_command|WINDOWTOFRONT]] WINDOW || This command will bring a window to the foreground.
|- style="vertical-align:top;"
| [[AmigaOS_Manual:_Workbench_Using#ZOOMWINDOW_command|ZOOMWINDOW]] WINDOW || This command will change a window to alternate position and dimensions.
|}

== ACTIVATEWINDOW command ==

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Activate the root window. */
ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

== CHANGEWINDOW command ==

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

== DELETE command ==

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
<syntaxhighlight lang="rexx">
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

== FAULT command ==

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

== GETATTR command ==

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
<syntaxhighlight lang="rexx">
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO ( window_list.count - 1 )
SAY window_list.i
END

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

== HELP command ==

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
<syntaxhighlight lang="rexx">
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR' command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

== ICON command ==

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

== INFO command ==

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

== KEYBOARD command ==

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

== LOCKGUI command ==

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
<syntaxhighlight lang="rexx">
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

== MENU command ==

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

== MOVEWINDOW command ==

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

== NEWDRAWER command ==

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
<syntaxhighlight lang="rexx">
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

== RENAME command ==

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
<syntaxhighlight lang="rexx">
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

== RX command ==

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

== SIZEWINDOW command ==

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window size to 200x100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

== UNLOCKGUI command ==

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
<syntaxhighlight lang="rexx">
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

== UNZOOMWINDOW command ==

; Purpose:
: This command will attempt to return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

== VIEW command ==

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Moves the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Moves the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Moves the view left by about 1/8 of the window width. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Moves the view right by about 1/8 of the window width. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window's current view position, use the GETATTR command and query the window's WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

== WINDOW command ==

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

== WINDOWTOBACK command ==

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

== WINDOWTOFRONT command ==

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
<syntaxhighlight lang="rexx">
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

== ZOOMWINDOW command ==

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
<syntaxhighlight lang="rexx">
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

User talk:Janne Peräaho

2020-01-31T16:07:05Z

Rob Cranley:

== Moved Workbench ARexx commands ==

Janne, you have moved the Workbench ARexx commands chapter from ARexx to the Workbench manual... But there's no obvious chapter for ARexx in the Workbench manual, and there's no link from the ARexx manual either. How should people find this information? Ideally you should have both.

Thanks,
Rob

: Hello Rob,

: Yes, I moved the Workbench ARexx commands to the Workbench manual's [[AmigaOS_Manual:_Workbench_Using|Chapter 4. Using Workbench]], under the title [[AmigaOS_Manual:_Workbench_Using#ARexx_Interface|3 ARexx Interface]]. The reason for doing this was that Workbench is not the only program included in AmigaOS that has an ARexx port. The idea was that all programs included in AmigaOS that have an ARexx port will be listed in the ARexx manual's [[AmigaOS_Manual:_ARexx_Compatible_Applications|Appendix F. ARexx Compatible Applications]] along with some general information. The list was supposed to make it easier to find the ARexx compatible applications and their ARexx commands.
:
: I admit the application list is somewhat hidden. A better solution would be to create a new chapter in the ARexx manual and explain how one can control applications using ARexx and present the application list in that chapter. Workbench could have its own section in the chapter, but I would keep the Workbench ARexx commands in the Workbench manual just like the other applications' ARexx commands are part of their documentation.

: [[User:Janne Peräaho|Janne Peräaho]] ([[User talk:Janne Peräaho|talk]]) 04:39, 8 September 2019 (CEST)

Hi Janne,
It's true there are plenty of other applications that support ARexx, but Workbench is pretty special in that it's the core of the whole user interaction with the machine, which is why the ARexx manual (which is an OS manual, remember, not a manual for every application) included Workbench.

But the problem is not the obscurity of the list of applications, it's the location of the Workbench ARexx information. There is still no easy link to it from either the ARexx or Workbench manuals, requiring a lot of to-ing and fro-ing to find it. So in recent times, I just refer to the 3.9 manual, which is laid out more logically. But, regardless of whether it should be in the Workbench manual or in the ARexx manual isn't a big deal - the real problem with how you've arranged it is that it's not discoverable. You've tacked it onto the end of the usage chapter, which is a very different level of focus to ARexx information - if someone needs to be looking in the chapter that explains what the Rename menu item does, they're probably not at the level of experience needed for automating such features in their own programs. And similarly, if someone is looking for the syntax for accessing icon metadata from ARexx, they don't really need to scroll down past the descriptions of what the Icon information window does to get there. It needs its own, separate chapter - since it's not originally in the Workbench manual, the place that makes most sense is as a new appendix. After all, it was an appendix of the ARexx manual in the first place.

Please move the ARexx section into its own chapter, and add suitable high-level references to the ARexx chapter from wherever else you feel appropriate. I would suggest in the main contents of the ARexx manual, since users familiar with the manual from previous versions of the OS will expect it there. It's a waste having the information squirrelled away where only you can easily find it. If you prefer, I'll do it the way I see fit, but I'll leave it for a while to let you have a chance to do it your way first.

Rob

User talk:Janne Peräaho

2020-01-31T16:06:50Z

Rob Cranley:

User talk:Janne Peräaho

2019-09-07T00:36:12Z

Rob Cranley: Created page with "Janne, you have moved the Workbench ARexx commands chapter from ARexx to the Workbench manual... But there's no obvious chapter for ARexx in the Workbench manual, and there's..."

Janne, you have moved the Workbench ARexx commands chapter from ARexx to the Workbench manual... But there's no obvious chapter for ARexx in the Workbench manual, and there's no link from the ARexx manual either. How should people find this information? Ideally you should have both.

Thanks,
Rob

AmigaOS Manual: AmigaDOS Command Reference

2019-02-06T09:37:49Z

Rob Cranley: /* ADDBUFFERS */ Fixed typo (sloppy drives -> floppy drives...)

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

= Command Documentation =

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

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

; Format
: All the arguments and options accepted by a command. The special characters that indicate the particular type of argument are described on page 6-6.

; Template
: An optional on-line reminder of the command's format that is embedded in the program's code. Entering a command followed by a space and a question mark (for example, DIR ?) displays the template. A complete description of the template notation is found on page 6-8.

; Location
: The directory where the command is normally stored.

; Examples
: A sample use of the command. Examples are displayed in the courier typeface to distinguish them from normal text. The 1> represents the Shell prompt; do not type it as part of the example command. Lines in the example not prefaced by 1> represent the output of a command. Command names and keywords are shown in all upper case letters and file and directory names usually have the first letter in upper case; however, they do not need to be entered that way. Press Return to execute the command line.

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

== Format ==

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

{| class="wikitable"
| < > || 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.
|-
| <nowiki>|</nowiki> || Vertical bars separate lists of options from which you can choose only one. For example, <nowiki>[OPT R|S|RS]</nowiki> 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:

{| class="wikitable"
! 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 <nowiki>|</nowiki> 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 floppy 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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|Chapter 8]].

== ADDNETINTERFACE ==

Makes network interfaces known to the protocol stack.

; Format
: ADDNETINTERFACE {<interface>} [QUIET] [TIMEOUT <seconds>]

; 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:

{| class="wikitable"
| INTERFACE || 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 || 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 || 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:

{| class="wikitable"
| 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:
{| 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.

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:

ADDNETROUTE allows to define routes to hosts or networks via an interface.

The options are:
{| class="wikitable"
| QUIET || 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.
|-
| DST or DESTINATION || The destination address of a route (or in other words, where the route to be added leads to). This must be an IP address or a symbolic name. Some routes may require you to specify a gateway address through which the route has to pass. Depending upon the address you specify, the protocol stack will attempt to figure out whether the destination is supposed to be a host or a network.
|-
| HOSTDST or HOSTDESTINATION || Same as the DST/DESTINATION parameter, except that the destination is assumed to be a host (rather than a network).
|-
| NETDST or NETDESTINATION || Same as the DST/DESTINATION parameter, except that the destination is assumed to be a network (rather than a host).
|- VIA or GATEWAY || This parameter complements the route destination address; it indicates the address to which a message should be sent for it to be passed to the destination. This must be an IP address or a symbolic name.
|-
| DEFAULT or DEFAULTGATEWAY || This parameter selects the default gateway address (which must be specified as an IP address or a symbolic host name) all messages are sent to which don't have any particular other routes associated with them. Another, perhaps less misleading name for "default gateway address" is "default route".
|}

{{Note|The command is similar to the Unix "route" command.}}

{{Note|If you use the DEFAULT/DEFAULTGATEWAY parameter, all other destination addresses you may have specified will be ignored. Only one of DESTINATION, HOSTDESTINATION or NETDESTINATION will be used; choose only one. Before you add a new default gateway you should delete the old one or you'll get an error message instead.}}

; Example 1:
Define a route to the host 192.168.10.12 through a gateway at 192.168.1.1
1> ADDNETROUTE HOSTDESTINATION 192.168.10.12 VIA 192.168.1.1

; See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#DELETENETROUTE|DELETENETROUTE]]

== 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#UNALIAS|UNALIAS]]

== APPLISTINFO ==

?

; Format
: <file>

; Template
: FILENAME/S

; Location
: C:

Missing description.

== ARP ==

Displays and modifies the address translation tables.

; Format
: ARP [-a|ALL] [-d|DELETE] [-s|SET] [HOSTNAME <host>] [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:

The ARP command displays and modifies the Internet-to-Ethernet address translation tables used by the Address Resolution Protocol (ARP). The host to be inspected or modified can be specified by name or by number, using the Internet dot notation.

The options are:
{| class="wikitable"
| ALL or -a || Display all of the current ARP entries.
|-
| DELETE or -d || Removes any ARP table entry for the host specified with the HOSTNAME parameter. See example 3.
|-
| SET or -s || Create a new ARP address mapping entry for the host with the supplied hardware address. The HOSTNAME parameter tells the host and the ADDRESS parameter the hardware address.
|-
| HOSTNAME || Name of the host which entries will be listed or modified.
|-
| ADDRESS || A hardware address (Ethernet address) of the host to be added or to be deleted from the ARP table. The address is given as six hex bytes separated by colons. See example 2.
|-
| TEMP || Add a temporary ARP entry. This option is used only with the SET parameter.
|-
| PUB or PUBLISH || The added ARP entry will be 'published'. The host will act as an ARP server, responding to requests for hostname even though the host address is not its own. This option is used only with the SET parameter.
|-
| PRO or PROXY || Adds a proxy ARP entry. This option is used only with the SET parameter.
|-
| FILE or -f || Causes the file <file name> to be read and multiple entries to be set in the ARP tables. Entries in the file should be of the form
: <hostname> <ether_addr> [TEMP] [PUB]
with argument meanings as given for the SET option.
|-
| NONAMES or -n or NUMBERS || Show network addresses as numbers (normally ARP attempts to display addresses symbolically).
|}

;Example 1:
List the current ARP entries:
1> ARP ALL

;Example 2:
Create a temporary ARP entry for the host 'Oberon' and publish it.
1> ARP SET Oberon 00:30:ab:0e:d5:ee TEMP PUB

;Example 3:
Delete any ARP entry of the host 'Oberon':
1> ARP DELETE Oberon

== 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:
<syntaxhighlight lang="text">
ASK Continue?
IF WARN
ECHO Yes
ELSE
ECHO No
ENDIF
</syntaxhighlight>
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
* [[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 ==

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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#STATUS|STATUS]]

; 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 an ASCII mapping table.

; Format
: BUILDMAPTABLE <ASCII mapping table> [CHARSET]

; Template
: UNICODEMAPTABLE/A,CHARSET/K

; Location
: SDK:C

BUILDMAPTABLE converts Charset-To-Unicode mapping tables in text form (e.g. available at http://www.unicode.org/Public/MAPPINGS/) to mapping tables in binary form usable by diskfont library.

You must specify a charset mapping table file name when using the BUILDMAPTABLE command.

BUILDMAPTABLE can either display a text form of the parsed table or create a binary mapping table in the L:Charsets/ directory. Currently only 8-bit charset mapping tables are supported.

If L:Charsets/character-sets or L:Charsets/custom-character-sets contains a MIME name for an 8-bit charset where no mapping table in L:Charsets/ does exist, and you have a mapping table in text form, use BUILDMAPTABLE to create the binary mapping table and reboot (diskfont library searches tables only once) to be able to use the new charset (e.g. in fonts or catalog files).

The expected format of text mapping tables is as follows:
* Anything from a '#' character to the end of a line is considered a comment.
* A valid line does contain the index on the left and the Unicode code point at the right side, in either hexadecimal (starting with 0x or 0X) or octal (starting with 0) or decimal form, separated by empty space. Example:
<syntaxhighlight lang="text">
0xA4 0x20AC # EURO SIGN
</syntaxhighlight>
The other options are:
{| class="wikitable"
| CHARSET || Specify a MIME charset name or alias. The MIME charset name obtained from diskfont library will be used as file name of the binary charset mapping table which will be stored in L:Charsets/. If the CHARSET parameter is omitted, no file will be written, instead the resulting mapping table is displayed in text form.
|}

;Example 1:
1> BUILDMAPTABLE CP1258.TXT

Will parse the text file CP1258.TXT and display a list of entries with the index on the left and the Unicode codepoint at the right side. Note: unmapped entries (with Unicode codepoint 0) are not displayed.

;Example 2:
1> BUILDMAPTABLE 8859-1.TXT CHARSET LATIN1

Will parse the text file 8859-1.TXT and create the file L:Charsets/ISO-8859-1 (latin1 is an alias for ISO-8859-1) which is useless (the ISO-8859-1 mapping table is a builtin part of diskfont library and will not be loaded from disk).

== CACHESTAT ==

Displays information on the system caches.

; Format
: [VERBOSE]

; Template
: VERBOSE/S

; Location
: C:

Missing description.

== 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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#STATUS|STATUS]]

; 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 character set into another.

; Format
: CHARSETCONVERT <from file> <from charset> [to file] [to charset] [EOL [CR] [LF] [CRLF]]

; Template
: FROM/A,FROMCHARSET/A,TO,TOCHARSET,EOL/K

; Location
: C:

CHARSETCONVERT converts the text file specified with the FROM argument from the character set specified with the FROMCHARSET argument to the character set specified with the TOCHARSET argument or to the current system default character set if the TOCHARSET argument is not specified. The result is written to the file specified with the TO argument or output to the current window if the TO argument is not specified.

The FROMCHARSET and TOCHARSET parameters are MIME character set names or aliases registered at IANA stored in L:Charsets/character-sets or custom character set names or aliases stored in L:Charsets/custom-character-sets. Currently only 8-bit character sets with a mapping table to Unicode (which can be created by the [[AmigaOS_Manual:_AmigaDOS_Command_Reference#BUILDMAPTABLE|BUILDMAPTABLE]] command) in L:Charsets/ are supported, plus those additional charsets:
* FROMCHARSET may also be UTF-7, UTF-8, UTF-16BE, UTF-16LE, UTF-32BE or UTF-32LE.
* TOCHARSET may also be UTF-8.

CHARSETCONVERT will return with result code 20 (FAILURE) when a severe error occurs, with result code 10 (ERROR) when the input file contains invalid data (NULL or a character or encoding sequence which is undefined or invalid in FROMCHARSET found in FROM file), with result code 5 (WARN) when at least one input character could not be represented in the TOCHARSET and was replaced by an "<UXXXX>" sequence, and with result code 0 (OK) if all went well.

CHARSETCONVERT has options which will change the way the output is displayed. These options are explained below:

{| class="wikitable"
| TO <name> || Specifies an output file or device for CHARSETCONVERT; by default, CHARSETCONVERT outputs to the current window.
|-
| TOCHARSET <name> || Specifies the destination character set for CHARSETCONVERT; by default, CHARSETCONVERT converts to the current system default character set.
|-
| EOL <type> || Converts End-Of-Line (EOL) sequences to the specified type. If not specified, no EOL conversion does happen. The EOL type parameter must match one of the following keywords:
{| class="wikitable"
| CR || output EOL as CR (0x0D, "\r") (Mac style).
|-
| LF || output EOL as LF (0x0A, "\n") (Amiga style).
|-
| CRLF || output EOL as CRLF (0x0D0A, "\r\n") (PC style).
|}
|}

;Example 1:
1> CHARSETCONVERT russian KOI8-R russian-ISO ISO-8859-5 EOL=LF

Will read the text file russian, convert the character set from KOI8-R to ISO-8859-5, convert the EOL sequences to Amiga style, and write the result to russian-ISO.

;Example 2:
1> CHARSETCONVERT czech.txt X-ATO-E2 czech-ISO2.txt ISO-8859-2

Will read the text file czech.txt, convert the character set from X-ATO-E2 (the character set of the OS3.x czech catalog files) to ISO-8859-2, replace unconvertable characters with an <UXXXX> sequence and write the result to czech-ISO2.txt.

;Example 3:
1> SETFONT topaz 8 CHARSET ISO-8859-16
1> CHARSETCONVERT polish.txt X-ATO-PL TOCHARSET ISO-8859-16

Will read the text file polish.txt, convert the character set from X-ATO-PL (the character set of the OS3.x polish catalog files) to ISO-8859-16 and display the result in the current window with topaz.font, size 8, in ISO-8859-16.

== 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:

CLIP can store some text in the clipboard, retrieve some text from it or count how many clipboard units are filled.

Using the GET argument will retrieve text from the specified unit number (if supplied). Using the SET argument and a <string> will store this <string> into the specified unit number (if supplied). Using the COUNT argument will count and display the number of filled clipboard units.

The UNIT argument is used to specify which of the clipboard units should be used for the GET/PUT action.

The TEXT argument is the text data to be stored in the clipboard unit.

The WAIT argument, used along with the GET action, will wait for the unit to be filled with text data. Then it will perform the GET action. It may be useful in scripts.

If no GET, PUT or COUNT argument is specified, text will be retrieved. i.e. GET is the default action. If no unit number is specified, text will be written to/read from unit 0.

;Example 1:
Store the text "Amiga" in the clipboard unit 2

1> CLIP PUT Amiga UNIT 2

;Example 2:
Retrieve and display the text stored in the clipboard unit 2

1> CLIP UNIT 2
Amiga

;Example 3:
Display how many clipboard units contain data

1> CLIP COUNT
1

;Example 4:
Delete the content of clipboard unit 0

1> CLIP SET

== CMIBOOST ==

Boosts microphone input.

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== CONFIGURENETINTERFACE ==

Configure network interface parameters.

; Format
: CONFIGURENETINTERFACE [QUIET] [TIMEOUT=<seconds>] INTERFACE Incomplete

; 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:

CONFIGURENETINTERFACE is used to define how a network interface will react and how it will interact with your network.

The options are:
{| class="wikitable"
| INTERFACE || The name of the interface to be configured. This is a required parameter.
|-
| QUIET || 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.
|-
| ADDRESS || The IP address to assign to this interface. This should be specified in dotted-decimal notation ("192.168.0.1") and not as symbolic name since the system may not be in a state to perform a name resolution.

In place of the IP address you can also specify "DHCP". 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.
|-
| NETMASK || The subnet mask to assign to this interface. This must be specified in dotted-decimal notation ("192.168.0.1").

In place of the subnet mask you can also specify "DHCP". 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.
|-
| BROADCASTADDR || The broadcast address to be used by this interface; must be specified in dotted-decimal notation ("192.168.0.1") and only works with interfaces that support broadcasts in the first place (i.e. Ethernet hardware).
|-
| DESTINATION or DESTINATIONADDR || 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 || Route metric value for this interface.
|-
| MTU || 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.
|-
| ALIASADDR || This adds another address to this interface to respond to. You can add as many aliases as you like, provided you don't run out of memory.
|-
| DELETEADDR || This removes an alias address from the list the interface is to respond to.
|-
| Options ONLINE, OFFLINE, UP, and DOWN || The 'line state' of the interface is configured through the following four options:
{| class="wikitable"
| ONLINE || An attempt is made to put the underlying networking driver online. If that works, then the protocol stack will attempt to transmit messages through this interface.
|-
| OFFLINE || The underlying networking device driver is put offline and the protocol stack will no longer try to send messages through the interface either.
|-
| UP || The protocol stack will attempt to transmit messages through this interface (even though it might not be online yet).
|-
| DOWN || The protocol stack will no longer attempt to transmit messages through this interface (even though it might still be online).
|}
|-
| DEBUG || Possible parameters are YES and NO. You can enable debug output for this interface 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.
|-
| COMPLETE || Possible parameters are YES and NO. If you configure an interface in several steps, use this parameter in the final invocation of the program. It will tell the TCP/IP stack that the configuration for this interface is complete. This has the effect of causing the static route definition file to be reread, if necessary.
|-
| RELEASEADDRESS || If an IP address was dynamically assigned to an interface, this switch will tell ConfigureNetInterface to release it. Note that you can only release what was previously allocated.
|-
| CONFIGURE || Possible parameters are DHCP, AUTO, and 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.
|-
| TIMEOUT || 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.
|-
| LEASE || This is a complex option which can be used to request how long an IP address should be bound to an interface. 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 || 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 || Possible parameters are YES and NO. 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|The command is similar to the Unix "ifconfig" command.}}

{{Note|If you tell an interface to go online then the program's return code will tell you if the command succeeded: a return value of 0 indicates success (the interface is now online), and a value of 5 indicates that it didn't quite work.}}

{{Note|Configuring the address of an interface has two effects: first, the interface will be marked as 'up', meaning that the protocol stack will attempt to send messages through it when appropriate. Second, a direct route to the interface will be established.}}

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ADDNETINTERFACE|ADDNETINTERFACE]]

== 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:

{| class="wikitable"
| 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.

{| class="wikitable"
| 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:

CUT will extract any number of characters or words out of a string.

The extracted string is defined by a begin and an end position. Those values will be characters or words positions in the original string. I.e you may want to extract a string beginning with a character at position P1 and ending with a character at position P2. Behaviour is the same with words instead of characters.

Use the CHAR argument if you want to use begin/end values defined in characters. Use the WORD argument if you want to extract any number of words. Words are strings separated by the "space" character (default). Using the SEPARATOR argument, you can specify a string of any length to be used to split the original string in words.

The length of the string to extract will depend on the begin (P1) and the end (P2) position in the original string. This P1-P2 range to give after the CHAR (or WORD) argument follows the template:

P1[-P2] | [P1-]P2 | [P1]-P2 | P1-[P2]

The begin (P1) and end (P2) values are optional.

This allows to extract only one character (or word) if you omit the end value. i.e with the argument like "CHAR P1"

In order to extract several characters (or words), you need to specify a range with the "-" character like "CHAR P1-P2"

You can omit P1 if you want a string starting at the beginning of <string> with "CHAR -P2". And you do not need to know the string length because P2 can be omited like "CHAR P1-". This will extract the string beginning with character at position P1 and ending at the end of the original <string>.

;Example 1:
To extract one character:

1> CUT "Hello world" CHAR=2 -> e

;Example 2:
To extract from character 1 to 5:

1> CUT "Hello world" CHAR=1-5 -> Hello

;Example 3:
The same without specifying the beginning position.

1> CUT "Hello world" CHAR=-5 -> Hello

;Example 4:
To extract from character 7 of the string till the end:

1> CUT "Hello world" CHAR=7- -> world

;Example 5:
To extract one word (with another separator):

1> CUT "Hello world" WORD=1 separator="ll" -> He

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

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.
{| 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:
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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#PROTECT|PROTECT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FORMAT|FORMAT]]

== 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:

The commands removes a route that was defined in your network. The available options are:
{| class="wikitable"
| QUIET || 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.
|-
| DST or DESTINATION || The destination address of a route (or in other words, where the route to be added leads to) that should be deleted. This must be an IP address or a symbolic name.
|-
| DEFAULT or DEFAULTGATEWAY || The default gateway address to be deleted. This must be an IP address or a symbolic name.
|}

{{Note|This command is similar to the Unix "route" command.}}

{{Note|You can try to delete a route that doesn't exist, but it will get you an error message instead of failing gracefully.}}

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ADDNETROUTE|ADDNETROUTE]]

== 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:
{| class="wikitable"
| 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:

{| class="wikitable"
| 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LIST|LIST]]

== 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:

DISMOUNT can be used to shut down a file system device, such as "DF0:" and all its associated volumes. If the request to shut down a file system device is acknowledged, by default, it will appear as if the file system had never been mounted in the first place.

Using the SOFT keyword, will only cause the current volume to dismount, the device (and associated geometry) will remain mounted so that the next access to the device name will cause dos.library to restart the filesystem process once again, with the same characteristics as before.

The options are:
{| class="wikitable"
| DEVICE || This must be the name of a file system device, such as "DF0:". It is not permitted to use the name of an assignment or volume instead.
|-
| SOFT || This switch will cause only the volume to be dismounted, the device will remain mounted and will restart a new filesystem process upon the next access to the device name.
|-
| FORCE || Attempt to remove the file system device data from memory even if the file system itself is unwilling to go. This is a potentially dangerous option and should be used only as a last resort when everything else has failed. Note that this option may not succeed in cleaning up all the resources the file system may still be using.
|}

{{Note|A file system device has to acknowledge the request to be shut down, which means that it might not respond to your request at all.}}

== DUMPDEBUGBUFFER ==

Dumps kernel's debug output to a shell.

; Format
: DUMPDEBUGBUFFER [<file>] [CLEAR]

; Template
: FILE,CLEAR/S

; Location
: C:

DUMPDEBUGBUFFER dumps the current content of the kernel's debug buffer to the standard output (shell). Optionally the buffer content can be saved to a file with the FILE parameter. If the CLEAR option is given, the debug buffer is cleared.

;Example 1
Print the debug buffer content:
1> DUMPDEBUGBUFFER
gfx AltiVec/VMX enabled
gfx PPC64xx optimizations enabled
a1ide.device 53.20 (24.9.2014)
[a1ide/ata_read_drive_properties] unit refused ATACMD_SET_FEATURES, SETFEATURES_EN_RLA
it8212ide.device 53.20 (24.9.2014)
lsi53c8xx.device 53.20 (24.9.2014)
sii0680ide.device 53.20 (24.9.2014)
sii3112ide.device 53.20 (24.9.2014)
sii3114ide.device 53.20 (24.9.2014)
sii3512ide.device 53.20 (24.9.2014)
CS4281 DRIVEINIT
No card present.
No CMI8738 found! :-(
No Envy24 found! :-(
No SB128 found! :-(
No SOLO_ONE found! :-(
[VIA-AC97] Error: sorry, you don't seem to have the AC'97 codec!
Unable to initialize Card subsystem

;Example 2
Save the debug buffer content to a file "debug.log".
1> DUMPDEBUGBUFFER "debug.log"
Buffer saved as 'debug.log'

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#KDEBUG|KDEBUG]]

== 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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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 [[AmigaOS_Manual:_AmigaDOS_Using_the_Editors#ED|ED]] for more information. See [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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 [[AmigaOS_Manual:_AmigaDOS_Using_the_Editors#EDIT|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:
<syntaxhighlight lang="text">
IF exists picfile
MultiView picfile
ELSE
ECHO "picfile is not in this directory"
ENDIF
</syntaxhighlight>
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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IF|IF]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ENDIF|ENDIF]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]

== ENDCLI ==

Ends a Shell process.

; Format
: ENDCLI

; Template
: (none)

; Location
: Internal

ENDCLI ends a Shell process.

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ENDSHELL|ENDSHELL]]

== ENDIF ==

Terminates an IF block in a script file.

; Format
: ENDIF

; Template
: (none)

; Location
: Internal

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

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

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IF|IF]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ELSE|ELSE]]

== 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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SKIP|SKIP]]

== EVAL ==

Evaluates integer or Boolean expressions.

; Format
: EVAL <value1> {[<operation>] [<value2>]} [TO <file>] [LFORMAT=<string>]

; Template
: VALUE1/A,OP,VALUE2/M,TO/K,LFORMAT/K

; Location
: C:

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

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

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

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

{| class="wikitable"
| addition || +
|-
| subtraction || -
|-
| multiplication || *
|-
| division || /
|-
| modulo || mod, M, m, or %
|-
| bitwise AND || &
|-
| bitwise OR || <nowiki>|</nowiki>
|-
| 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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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:
<syntaxhighlight lang="text">
.KEY filename/A, TOname/K
</syntaxhighlight>
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:
<syntaxhighlight lang="text">
.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}."
</syntaxhighlight>
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:
<syntaxhighlight lang="text">
.K filename
RUN COPY <filename> TO PRT: +
ECHO "Printing of <filename> done"
</syntaxhighlight>

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:
<syntaxhighlight lang="text">
.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
</syntaxhighlight>

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
* [[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 ==

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:
<syntaxhighlight lang="text">
COPY DF0:MyFile to RAM:
ECHO "MyFile being copied."
</syntaxhighlight>

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:
<syntaxhighlight lang="text">
FAILAT 21
COPY DF0:MyFile to RAM:
ECHO "MyFile being copied."
</syntaxhighlight>

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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ECHO|ECHO]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]

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

== FC-CACHE ==

Builds FreeType font information cache files.

; Format
: FC-CACHE [ -EfrsvVh ] [ -y <sysroot> ] [ --error-on-no-fonts ] [ --force | --really-force ] [ --sysroot=<sysroot>] [ --system-only ] [ --verbose ] [ --version ] [ --help ] [ <directories> ]

; Template
: -E=--error-on-no-fonts,-f=--force,-r=--really-force,-s=--system-only,-v=--verbose,-V=--version,-h=--help,-y=--sysroot,DIRECTORY/M

; Location
: C:

FC-CACHE scans the font directories on the system and builds font information cache files for applications using fontconfig for their font handling.

If directory arguments are not given, FC-CACHE uses each directory in the current font configuration. Each directory is scanned for font files readable by FreeType. A cache is created which contains properties of each font and the associated filename. This cache is used to speed up application startup when using the fontconfig library.

{{Note|FC-CACHE must be executed once per architecture to generate font information customized for that architecture.}}

The command parameters are:
{| class="wikitable"
| -E or --error-on no-fonts || Raise an error if there are no fonts in <directories>.
|-
| -f or --force || Scan directories with apparently valid caches.
|-
| -r or --really-force || Erase all existing caches, then rescan.
|-
| -s or --system-only || Scan system-wide directories only.
|-
| -y or --sysroot <sysroot> || Prepend <sysroot> to all paths for scanning.
|-
| -v or --verbose || Display status information while busy.
|-
| -V or --version || Display font config version and exit.
|-
| -h or --help || Display command help and exit
|}

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-CAT|FC-CAT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-LIST|FC-LIST]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-MATCH|FC-MATCH]]

== FC-CAT ==

Reads FreeType font information cache files.

; Format
: FC-CAT [ -rvVh ] [ --recurse ] [ --verbose ] [ --version ] [ --help ] [ [ <fonts-cache-2-files> ] [ <directories> ] ... ]

; Template
: -r=--recurse,-v=--verbose,-V=--version,-h=--help,FILE/M,DIRECTORY/M

; Location
: C:

FC-CAT reads the FreeType font information from cache files or related to font directories and emits it in ASCII form. The command parameters are:

{| class="wikitable"
| -r or --recurse || Recurse into subdirectories.
|-
| -v or --verbose || Be verbose.
|-
| -V or --version || Show version of the program and exit.
|-
| -h or --help || Show command help.
|}

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-CACHE|FC-CACHE]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-LIST|FC-LIST]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-MATCH|FC-MATCH]]

== FC-LIST ==

Lists the available FreeType fonts.

; Format
: FC-LIST [ -vqVh ] [ -f <format> ] [ --verbose ] [ --format=<format> ] [ --quiet ] [ --version ] [ --help ] [ <pattern> ] [ <element>... ]

; Template
: -v=--verbose,-q=--quiet,-V=--version,-h=--help,-f=--format,PATTERN,ELEMENT/M

; Location
: C:

FC-LIST lists TrueType fonts and styles which are available for the applications using fontconfig.

{| class="wikitable"
| -v or --verbose || Print verbose output of the whole font pattern for each match, or elements if any is provided.
|-
| -q or --quiet || Suppress all normal output. The command returns 1, if there were no font matches.
|-
| -V or --version || Show version of the program and exit.
|-
| -h or --help || Show command help and exit.
|-
| -f or --format || Format output according to the format specifier <format>.
|-
| <pattern> || If this argument is set, only fonts matching <pattern> are displayed.
|-
| <element> || If set, the <element> property is displayed for matching fonts.
|}

;Example 1:
List all font faces.
1> FC-LIST

;Example 2:
List font faces that cover Hindi.
1> FC-LIST :lang=hi

;Example 3:
List the filename and spacing value for each font face. ":" is an empty pattern that matches all fonts.
1> FC-LIST : family style file spacing

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-CACHE|FC-CACHE]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-CAT|FC-CAT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-MATCH|FC-MATCH]]

== FC-MATCH ==

Matches available FreeType fonts.

; Format
: FC-MATCH [ -savVh ] [ -f <format> ] [ --sort ] [ --all ] [ --verbose ] [ --format=<format> ] [ --version ] [ --help ] [ <pattern> ] [ <element>... ]

; Template
: -s=--sort,-a=--all,-v=--verbose,-V=--version,-h=--help,-f=--format,PATTERN,ELEMENT/M

; Location
: C:

FC-MATCH matches pattern (empty pattern by default) using the normal fontconfig matching rules to find the best FreeType font available. If --sort is given, the sorted list of best matching fonts is displayed. The --all option works like --sort except that no pruning is done on the list of fonts.

If any elements are specified, only those are printed. Otherwise short file name, family, and style are printed, unless verbose output is requested.

The command parameters are:
{| class="wikitable"
| -s or --sort || Displays sorted list of best matching fonts.
|-
| -a or --all || Displays sorted list of best matching fonts, but do not do any pruning on the list.
|-
| -v or --verbose || Print verbose output of the whole font pattern for each match, or <elements> if any is provided.
|-
| -V or --version || Show version of the command and exit.
|-
| -h or --help || Show the command help and exit.
|-
| -f or --format || Format output according to the format specifier <format>.
|-
| <pattern> || Displays fonts matching <pattern> (uses empty pattern by default).
|-
| <element> || If set, the element property is displayed for matching fonts.
|}

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-CACHE|FC-CACHE]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-CAT|FC-CAT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FC-LIST|FC-LIST]]

== FDTOOL ==

Control and examine the current state of floppy drives.

; 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:

The current state of floppy drives controlled by the a1floppy device can be externally controlled and examined with the FDTOOL. The command options are as follows:

{| class="wikitable"
| U or UNIT || The target floppy drive: 0 or 1. Unit number 0 is the first floppy drive and 1 is the second drive. The default unit number is 0.
|-
| D or DEBUG || Set the current debug level. The valid levels are between 0 and 30. The default is 0 (debugging off).
|-
| A or AUTO || Start auto checking.
|-
| M or MANUAL || Stop auto checking.
|-
| C or CHECKNOW || Force a single disk check.
|-
| I or INFO || Print information about a floppy drive and the controlling device.
|-
| V, VERS, or VERSION || Print the FDTOOL and a1floppy device versions.
|}

FDTOOL has a built-in debugging system which provides profound information on error situations. How detailed debugging information, if any, will be printed is controlled by the DEBUG argument which sets the debug level. When the debugging system is active, the debugging information is printed to the debug port (which may be serial port 0) and not to the standard output. The debug levels are:
{| class="wikitable"
! Level !! Output type
|-
| 0 - 4 || No output. This is the default setting.
|-
| 5 - 10 || Fatal errors
|-
| 11 - 15 || Recoverable errors (retries, etc)
|-
| 16 - 20 || Explanatory notes about recoverable errors (reasons, etc)
|-
| 21 - 25 || Explanatory notes about intermediate values (good data)
|-
| 26 - 30 || Flow of control ("Kilroy wuz here" messages)
|}

To detect if the user has ejected or inserted a disk, the a1floppy device checks the disk drives regularly for any change. On every check the drive's led will light and you will hear a click from the drive's mechanism. On some drives a single check will start the drive's motor for several seconds, which will cause the motor to run continuously because of the regular checks. To prevent the drive from spinning countinuously and wearing out, the automatic disk checking can be turned off with the MANUAL option.

Note that when the automatic disk checking function is turned off, Amiga will no longer detect disk changes. In order to notify the system that a disk has been ejected or inserted, use the [[AmigaOS_Manual:_AmigaDOS_Command_Reference#DISKCHANGE|DISKCHANGE]] command or FDTOOL's CHECKNOW option.

;Example 1:
Print information about the first floppy drive (unit number 0):
1> FDTOOL UNIT=0 INFO
Current state of A1Floppy Drive Unit 0
Version: 53 Revision: 2
Controller state: free
Debug level: 0
Task readiness state: ready
Disk state: drive empty
Drive status: ST0=20 ST1=00 ST2=00 ST3=38
Drive currently on cylinder 0
Drive state:
Interrupt state 0
Data count 0, status count 0
Unit Open count: 2
Change number: 0
Recovered errors this disk: 1
Config word: 00000200

;Example 2:
Turn off the automatic disk change detection on drive 0:
1> FDTOOL MANUAL
Regular check not set on drive 0

;Example 3:
Enable the automatic disk change detection on drive 0:
1> FDTOOL AUTO
Starting regular check on drive 0

;Example 4:
Manually check if the user has ejected or inserted a disk on drive 0:
1> FDTOOL CHECKNOW
Requesting a check now on drive 0

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#DISKCHANGE|DISKCHANGE]]

== 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:
{| 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.
|}

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

; Format
: FILESIZE [{<dir|file|pattern|device>}] [FORM <file name>] [ALL]

; Template
: FILES/M,FROM/K,ALL/S,REPORT/S,FORMAT/K

; Location
: C:

FILESIZE will collect information on files stored on a disk, adding up the number of bytes and blocks used, counting the number of files found. If you specify a <dir>, <pattern> or <filename> argument, FILESIZE will add the file data for the specified directory, all directories or files that match the pattern, or the specified file or device, respectively. Instead of providing the names on the command line, you can also specify the name of a file from which the names should be read.

The options are:
{| class="wikitable"
| FILES || A list of files, directories or wildcard patterns which should be examined. You either need to provide this parameter or the a file name with the FROM option.
|-
| FROM || The name of a text file which contains the names of files, directories or wildcard patterns which should be examined. You either need to provide this parameter or a list of names with the FILES option.
|-
| ALL || Also examines the files in all directories and subdirectories.
|-
| REPORT || Print progress reports as directory contents are scanned. Each such report will be prefixed by the name of the directory and final total number of files, blocks, bytes will be prefixed by "TOTAL".
|-
| FORMAT || Defines a string to specially format FILESIZE output. Supported format specifiers are:
{| class="wikitable"
| %b || Prints the number of blocks used
|-
| %B || Prints the number of blocks used, but uses the current locale formatting rules
|-
| %l || Prints the number of bytes used
|-
| %L || Prints the number of bytes used, but uses the current locale formatting rules
|-
| %S || Prints the number of bytes used, rounded to Kilobytes, Megabytes, Gigabytes, etc. (Binary)
|-
| %f || Prints the number of files found
|-
| %F || Prints the number of files found, but uses the current locale formatting rules
|-
| %N || Prints the full name of the directory the information has been gathered for, or the label "TOTAL" for the grand total of all data gathered
|-
| %% || Prints the percent character
|}

The escape sequences '*E' and '*N' are expanded, too.

If you do not specify a special format, FILESIZE will use "%F files, %L bytes, %B blocks" and, if the "REPORT" option is used, "%N: %F files, %L bytes, %B blocks".

Output formatting follows 'C' conventions, e.g. "%10l" will print at least 10 digits for the number of bytes used, right justified.
|}

;Example 1:
Examine the contents of the C: directory, adding up the sizes of all files found, then print just the number of bytes used:

1> FILESIZE C: FORMAT "%l"
1958872

;Example 2:
Same as above, but print the size as a rounded number. Note that a Kilobyte is worth 1024 bytes (and not 1000).

1> FILESIZE C: FORMAT "%s"
1912K

;Example 3:
Find out how many files are stored in the LIBS: directory:

1> FILESIZE LIBS: ALL FORMAT "%F files found"
178 files found

;Example 4:
Print reports on the individual directories found on SYS:

1> FILESIZE SYS:#? ALL REPORT
SYS:C: 71 files, 354,230 bytes, 722 blocks
SYS:Classes: 49 files, 786,244 bytes, 1,560 blocks
SYS:Devs: 278 files, 1,734,474 bytes, 3,502 blocks
SYS:Expansion: 0 files, 0 bytes, 0 blocks
SYS:Fonts: 62 files, 777,024 bytes, 1,554 blocks
SYS:L: 10 files, 106,488 bytes, 215 blocks
SYS:Libs: 73 files, 2,147,780 bytes, 4,232 blocks
SYS:Prefs: 585 files, 14,115,024 bytes, 27,836 blocks
SYS:Rexxc: 10 files, 4,628 bytes, 13 blocks
SYS:S: 19 files, 14,100 bytes, 38 blocks
SYS:Storage: 292 files, 1,408,042 bytes, 2,868 blocks
SYS:System: 16 files, 154,916 bytes, 310 blocks
SYS:T: 0 files, 0 bytes, 0 blocks
SYS:Tools: 49 files, 686,316 bytes, 1,364 blocks
SYS:Utilities: 88 files, 2,267,465 bytes, 4,470 blocks
SYS:WBStartup: 11 files, 257,923 bytes, 509 blocks
SYS:Locale: 460 files, 2,581,114 bytes, 5,295 blocks
TOTAL: 2,082 files, 27,422,060 bytes, 54,545 blocks

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

== FOREACH ==

Executes a script for each file encountered.

; Format
: FOREACH {<file|pattern>} [PATH <path name>] {<name>} [FROM <number>] [TO <number>]
: [STEP <number>] [SCRIPT <name>] [COM "<command string>"] [WITH <name>] [ALL]
: [FILES] [DIRS] [SORT] [SINCE <date>] [UPTO <date>]

; Template
: NAME,PATH/K,IN/M,FROM/K/N,TO/K/N,STEP/K/N,SCRIPT/K,COM/K,WITH/K,ALL/S,FILES/S,DIRS/S,SORT/S,SINCE/K,UPTO/K

; Location
: C:

The FOREACH command allows you to loop within scripts with a loop variable set to a value selected from a list of names. FOREACH will execute a script of your choice; if no script is given, the FOREACH command allows you to type a temporary one in from the command line. If used from within a script, the FOREACH command will loop within the script.

The FOREACH loop is bounded by a END directive (or an EOF, or a control-\).

The FOREACH loop is executed once for each name specified by the IN keyword. Full pattern matching is supported. Names specified with the IN option don't necessarily have to actually exist as files or directories to be used, which allows you to create files.

The NAME keyword allows you to pick a variable name; each time through the loop, that variable is set to the name currently selected from the list of names specified with the IN keyword.

If no name is specified, no local variables will be created.

The PATH keyword allows you to select a local variable name where the PATH will be stored; if no PATH keyword is specified, this will be stored in a variable with the same name as NAME but with .PATH appended.

The basename and extension local variables work in a similar manner, except that the names are always based on the name specied by the NAME keyword with an appended extension. The extension for the basename of the file found is .BASE The extension (if any) will be found in the variable name with the .EXT extension.

The nametype local variable contains the type of thing, either dir (for directory), file (for file), or name (for couldn't find one of those).

Remember, to access variables that contain non-alphanumeric characters (like a .) on the command line (like a .) you have to surround the name with { } like: ${i.base}

The ALL keyword causes any pattern matching used in any member of the IN namelist to be recursive.

The FILES keyword is a 'files only' keyword. When this is used, only files (non-directories) will be selected from the list of IN names.

The DIRS keyword is a 'directories only' keyword. When this is used, only directories (non-files) will be selected from the list of IN names.

In either the file only or the directory only mode all names which are neither files or directories (ie names that don't exist) are selected as well.

Even if the FILES only keyword is used, if the ALL option is specified, directories _will_ be entered.

{{Note|Directories are listed _last_ after all files (and/or subdirectories) in them are used. This allows the FOREACH command to be used as an interactive Delete command.}}

The COM keyword allows you to specify a single command to execute. Remember to use quotes around the entire command; if one of the arguments inside requires quotes, you must escape those quotes using the *. Within the COM argument, all variables must be preceeded by an additional $, to avoid expansion on the command line before the command is executed. By using *N within the COM string, you can define multi-command COM arguments, which is especially useful when making aliases that use the FOREACH command.

The SCRIPT keyword allows you to specify a script file to execute. If no script keyword is used (and no COM keyword is specified) you will be prompted to create a temporary script.

The WITH keyword allows you to specify a file containing a list of names. This list is used after any command line names are used.

The FROM, TO and (optional) STEP keywords allow you to specify a numeric range; the loop variable will be set to each of the values in the range in turn. Both are required to be specified to use this feature. The STEP keyword is optional; it allows you to pick an increment other than 1. FROM, TO, and STEP can be negative. STEP cannot be zero, however.

The SORT keyword causes the FOREACH command to do an alphanumeric sort on the name list before doing any script execution.

The SINCE and UPTO keywords are for date comparisons; SINCE will limit operations to files/directories since (and including) the specified date/time. UPTO will limit operations to files/directories up to (and including) the specified date/time. The usual AmigaDOS shortcuts (today, yesterday, and so on) are allowed.

The FOREACH command nests. WARNING: The same variable name should not be used for nested FOREACH commands; make sure the inner loop variable name is not the same as the outside loop variable name.

The FOREACH command places its temporary files in T:. If T: is not assigned then RAM: is used instead.

;Bugs

It is sometimes hard to stop the FOREACH command from the Shell. Many things are looking at the signal bits, and the FOREACH command is low on the chain. It is often easier to go to another Shell, use STATUS to find out the process number of the FOREACH command, and send that process a BREAK ALL. Like this, for instance:

1> BREAK `STATUS com=foreach` all

;Example 1:
<syntaxhighlight lang="text">
foreach i in qwe1 qwe2 ram:#$
echo "file is $i, path is ${i.path}"
foreach j in test1 test2
echo "subname is $j"
echo "Current local vars are:"
set
end
end
</syntaxhighlight>

;Example 2:
Here's a handy alias using FOREACH that gives an interactive delete command. Note: The alias must be defined on one line. It is shown on two lines for clarity.

1> alias del foreach i []
com "failat 21*Nask *"delete $i ?*"*N if warn *Ndelete ${i.path}$i*N endif"

;Example 3:
Rename all the .a files to .asm.
<syntaxhighlight lang="text">
foreach i in #?.a
rename $i ${i.base}.asm
end
</syntaxhighlight>

== FS_PLUGIN_CACHE ==

Increases performance of a FFS2 file system.

; Format
: FS_PLUGIN_CACHE <device name> [ CACHESIZE=<cache size>] [ READAHEAD=<blocks>]
: [ MEMLIMIT=<limit> ] [ QUIET ] [ WRITEAROUND ] [ NOCHECKSUM ]

; Template
: DEVICE/A,S=CACHESIZE/K/N,R=READAHEAD/K/N,MEMLIMIT/K/N,QUIET/S,WA=WRITEAROUND/S,NC=NOCHECKSUMS/S

; Location
: C:

FS_PLUGIN_CACHE starts a FastFileSystem 2 (FFS2) cache plug-in on a device <device name>. The plug-in will increase file system performance by buffering disk data that was accessed before and might be accessed again, or which was never accessed before but has a good chance of being needed soon.

You can tell the plug-in how large the cache should become that it is supposed to maintain. By default it will try to use cache about 1% the size of the device it is installed on. You can override this number with the CACHESIZE parameter. The size you specify will be multiplied by 1024. Thus, a cache size of 8192 would result in a cache size of 8 MB.

The cache plug-in supports also a feature called read-ahead. With this feature enabled, the file system will always read a little more data than is strictly necessary in the hope that the data read will be useful later. You can tell the file system how many blocks should be read using the READAHEAD parameter. Note that a read-ahead cache makes sense only if reading the extra data does not noticeably increase the overhead of transferring data from the disk. Thus, smaller read-aheads sizes are likely to be more successful than larger ones.

The other command options are:
{| class="wikitable"
| MEMLIMIT || Missing description.
|-
| QUIET || Missing description.
|-
| WRITEAROUND or WA || Missing description.
|-
| NOCHECKSUMS or NC || Missing description.
|}

Missing examples.

== FS_PLUGIN_ENCRYPT ==

Enables FFS2 file system's data encryption.

; Format
: FS_PLUGIN_ENCRYPT <device name> [ BLOCKS=<blocks> ] [ QUIET ]

; Template
: DEVICE/A,BLOCKS/K/N,QUIET/S

; Location
: C:

FS_PLUGIN_ENCRYPT starts a FastFileSystem 2 (FFS2) data encryption plug-in on a device <device name>. The plug-in performs on the fly data encryption and decryption on the device it works.

The plug-in begins by asking you for a password to use for encryption. Enter your password and press Enter to begin. Note that you can abort the password entry by pressing Ctrl-C.

Your password will be used to set up a block cipher algorithm by the name of Blowfish. Next, the file system will be taken out of service temporarily, the plug-in will be installed and the file system will be reactivated. If you entered the correct password, the file system will suddenly start to make sense of the encrypted data.

{{Note|You have to reformat a file system with the encryption plug-in installed in order to use it.}}

The FFS2 file system's block transform plug-in feature permits you to cascade plug-ins. That is, you can set up several plug-ins with different passwords on the same device. Note that the order in which the plug-ins are set up defines the order in which the encryption will be applied. When you want to access your data later, you will have to set up the different encryptions in exactly the same order again.

There are two further parameters for the FS_PLUGIN_ENCRYPT command in addition to the mandatory DEVICE parameter. Using the BLOCKS parameter you can tell the file system how many data blocks it should try to encrypt at a time. The more blocks it uses, the faster it can encrypt data to be written to disk. The QUIET parameter tells the plug-in not to announce what it is about to do, except for printing error messages and prompting you to enter the password.

;Warning
Do not forget you password! The Blowfish cipher is hard to break, and it does not get any easier because the password does not go directly into the cipher algorithm.

== FS_SET_FLUSH_STRATEGY ==

Changes volume's flushing strategy.

; Format
: FS_SET_FLUSH_STRATEGY [ <volume name> ] [ <strategy> ]

; Template
: VOLUME,STRATEGY/N

; Location
: C:

The FS_SET_FLUSH_STRATEGY command can be used for changing the flush strategy of a volume <volume name>.

Whenever changes are made to the contents of a FastFileSystem 2 (FFS2) file system, the file system data structures may need to be updated. The updating process can involve changing several disk data blocks. If this process is interrupted, the data on the disk may no longer be consistent and require repairs. The FastFileSystem 2 tries hard not to leave the disk's data structures in an inconsistent state when changes are made. Unfortunately, for this goal to be reached, the data block manipulations have to be carried out in a certain order, and the changes need to be written back to disk at once. This takes time and has a negative impact on write performance.

If you are certain that you can do without this elaborate and slow data management scheme, you can change the file system's data flushing strategy. The default is "strict", which means that for each change made, the respective data block changes are immediately written back ("flushed") to disk. The alternative is the "relaxed" strategy, which will delay writing back block changes until either no disk activity has taken place in a while or further block changes are making it necessary to write older modified blocks back to disk. The relaxed strategy is generally faster, but also generally less reliable than the strict one.

The VOLUME parameter tells which FFS2 formatted volume's flushing strategy will be displayed or changed and the STRATEGY parameter which strategy will be selected. Value of 0 chooses the strict flushing strategy and 1 chooses the relaxed strategy. If you leave out the STRATEGY parameter, FS_SET_FLUSH_STRATEGY displays the current flushing strategy of the supplied volume.

;Example 1
Display volume's "Workbench" current flushing strategy.

1> FS_SET_FLUSH_STRATEGY Workbench:
'Workbench:' flush strategy = strict (was strinct).

;Example 2
Select "relaxed" flushing strategy for volume "Workbench".

1> FS_SET_FLUSH_STRATEGY Workbench: 1
'Workbench:' flush strategy = relaxed (was strinct).

== 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:

FTP is the user interface to the ARPANET standard File Transfer Protocol. The program allows a user to transfer files to and from a remote network site.

Options may be specified at the command line, or to the command interpreter.

{| class="wikitable"
| -v or VERBOSE || Verbose option forces FTP to show all responses from the remote server, as well as report on data transfer statistics.
|-
| -n or NOAUTOLOGIN || Restrains FTP from attempting "auto-login" upon initial connection. If auto-login is enabled, FTP will check the .netrc (see below) file in the user's home directory for an entry describing an account on the remote machine. If no entry exists, FTP will prompt for the remote machine login name (default is the user identity on the local machine), and, if necessary, prompt for a password and an account with which to login.
|-
| -i or NOPROMPT || Turns off interactive prompting during multiple file transfers.
|-
| -d or DEBUG || Enables debugging.
|-
| -g or NOGLOBBING || Disables file name globbing.
|}

The client host with which FTP is to communicate may be specified on the command line. If this is done, FTP will immediately attempt to establish a connection to an FTP server on that host; otherwise, FTP will enter its command interpreter and await instructions from the user. When FTP is awaiting commands from the user the prompt "ftp>" is provided to the user. The following commands are recognized by FTP:

{| class="wikitable"
| $ <macro-name> [<args>] || Execute the <macro macro-name> that was defined with the macdef command. Arguments are passed to the macro unglobbed.
|-
| account [<passwd>] || Supply a supplemental password required by a remote system for access to resources once a login has been successfully completed. If no argument is included, the user will be prompted for an account password in a non-echoing input mode.
|-
| append <local-file> [<remote-file>] || Append a local file to a file on the remote machine. If remote-file is left unspecified, the local file name is used in naming the remote file after being altered by any ntrans or nmap setting. File transfer uses the current settings for type, format, mode, and structure.
|-
| ascii || Set the file transfer type to network ASCII. This is the default type.
|-
| bell || Arrange that a bell be sounded after each file transfer command is completed.
|-
| binary|| Set the file transfer type to support binary image transfer.
|-
| bye || Terminate the FTP session with the remote server and exit FTP. An end of file will also terminate the session and exit.
|-
| case || Toggle remote computer file name case mapping during mget commands. When case is on (default is off), remote computer file names with all letters in upper case are written in the local directory with the letters mapped to lower case.
|-
| cd <remote-directory> || Change the working directory on the remote machine to <remote-directory>.
|-
| cdup || Change the remote machine working directory to the parent of the current remote machine working directory.
|-
| chmod <mode> <file-name> || Change the permission modes of the file <file-name> on the remote system to <mode>.
|-
| close || Terminate the FTP session with the remote server, and return to the command interpreter. Any defined macros are erased.
|-
| cr || Toggle carriage return stripping during ascii type file retrieval. Records are denoted by a carriage return/linefeed sequence during ascii type file transfer. When cr is on (the default), carriage returns are stripped from this sequence to conform with the UNIX single linefeed record delimiter. Records on non-UNIX remote systems may contain single linefeeds; when an ascii type transfer is made, these linefeeds may be distinguished from a record delimiter only when cr is off.
|-
| delete <remote-file> || Delete the file <remote-file> on the remote machine.
|-
| debug [<debug-value>] || Toggle debugging mode. If an optional debug value is specified it is used to set the debugging level. When debugging is on, FTP prints each command sent to the remote machine, preceded by the string "-->"
|-
| dir [<remote-directory>] [<local-file>] || Print a listing of the directory contents in the directory, <remote-directory>, and, optionally, placing the output in <local-file>. If interactive prompting is on, FTP will prompt the user to verify that the last argument is indeed the target local file for receiving dir output. If no directory is specified, the current working directory on the remote machine is used. If no local file is specified, or local-file is -, output comes to the terminal.
|-
| disconnect || A synonym for close.
|-
| form <format> || Set the file transfer form to <format>. The default format is "file".
|-
| get <remote-file> [<local-file>] || Retrieve the <remote-file> and store it on the local machine. If the local file name is not specified, it is given the same name it has on the remote machine, subject to alteration by the current case, ntrans, and nmap settings. The current settings for type, form, mode, and structure are used while transferring the file.
|-
| glob || Toggle filename expansion for mdelete, mget and mput. If globbing is turned off with glob, the file name arguments are taken literally and not expanded. Globbing for mput is done as in csh(1). For mdelete and mget, each remote file name is expanded separately on the remote machine and the lists are not merged. Expansion of a directory name is likely to be different from expansion of the name of an ordinary file: the exact result depends on the foreign operating system and FTP server, and can be previewed by doing "mls remote-files -" Note: mget and mput are not meant to transfer entire directory subtrees of files. That can be done by transferring a tar(1) archive of the subtree (in binary mode).
|-
| hash || Toggle hash-sign ("#") printing for each data block transferred. The size of a data block is 1024 bytes.
|-
| help [<command>] || Print an informative message about the meaning of command. If no argument is given, FTP prints a list of the known commands.
|-
| idle [<seconds>] || Set the inactivity timer on the remote server to seconds seconds. If seconds is omitted, the current inactivity timer is printed.
|-
| lcd [<directory>] || Change the working directory on the local machine. If no directory is specified, the user's home directory is used.
|-
| ls [<remote-directory>] [<local-file>] || Print a listing of the contents of a directory on the remote machine. The listing includes any system-dependent information that the server chooses to include; for example, most UNIX systems will produce output from the command "ls -l". (See also nlist.) If remote directory is left unspecified, the current working directory is used. If interactive prompting is on, FTP will prompt the user to verify that the last argument is indeed the target local file for receiving ls output. If no local file is specified, or if <local-file> is "-", the output is sent to the terminal.
|-
| macdef <macro-name> || Define a macro. Subsequent lines are stored as the macro <macro-name>; a null line (consecutive newline characters in a file or carriage returns from the terminal) terminates macro input mode. There is a limit of 16 macros and 4096 total characters in all defined macros. Macros remain defined until a close command is executed. The macro processor interprets "$" and "\" as special characters. A "$" followed by a number (or numbers) is replaced by the corresponding argument on the macro invocation command line. A "$" followed by an "i" signals that macro processor that the executing macro is to be looped. On the first pass "$i" is replaced by the first argument on the macro invocation command line, on the second pass it is replaced by the second argument, and so on. A "\" followed by any character is replaced by that character. Use the "\" to prevent special treatment of the "$".
|-
| mdelete [<remote-files>] || Delete the <remote-files> on the remote machine.
|-
| mdir <remote-files> <local-file> || Like dir, except multiple remote files may be specified. If interactive prompting is on, FTP will prompt the user to verify that the last argument is indeed the target local file for receiving mdir output.
|-
| mget <remote-files> || Expand the <remote-files> on the remote machine and do a get for each file name thus produced. See glob for details on the filename expansion. Resulting file names will then be processed according to case, ntrans, and nmap settings. Files are transferred into the local working directory, which can be changed with "lcd directory"; new local directories can be created with "! mkdir directory".
|-
| mkdir <directory-name> || Make a directory on the remote machine.
|-
| mls <remote-files> <local-file> || Like nlist, except multiple remote files may be specified, and the <local-file> must be specified. If interactive prompting is on, FTP will prompt the user to verify that the last argument is indeed the target local file for receiving mls output.
|-
| mode [<mode-name>] || Set the file transfer mode to <mode-name>. The default mode is "stream" mode.
|-
| modtime <file-name> || Show the last modification time of the file on the remote machine.
|-
| mput <local-files> || Expand wild cards in the list of local files given as arguments and do a put for each file in the resulting list. See glob for details of filename expansion. Resulting file names will then be processed according to ntrans and nmap settings.
|-
| newer <file-name> || Get the file only if the modification time of the remote file is more recent that the file on the current system. If the file does not exist on the current system, the remote file is considered newer. Otherwise, this command is identical to get.
|-
| nlist [<remote-directory>] [<local-file>] || Print a list of the files in a directory on the remote machine. If remote directory is left unspecified, the current working directory is used. If interactive prompting is on, FTP will prompt the user to verify that the last argument is indeed the target local file for receiving nlist output. If no local file is specified, or if local-file is -, the output is sent to the terminal.
|-
| nmap [<inpattern> <outpattern>] || Set or unset the filename mapping mechanism. If no arguments are specified, the filename mapping mechanism is unset. If arguments are specified, remote filenames are mapped during mput commands and put commands issued without a specified remote target filename. If arguments are specified, local filenames are mapped during mget commands and get commands issued without a specified local target filename. This command is useful when connecting to a non-UNIX remote computer with different file naming conventions or practices. The mapping follows the pattern set by <inpattern> and <outpattern>. <inpattern> is a template for incoming filenames (which may have already been processed according to the ntrans and case settings). Variable templating is accomplished by including the sequences "$1", "$2", ..., "$9" in <inpattern>. Use "\" to prevent this special treatment of the "$" character. All other characters are treated literally, and are used to determine the nmap [<inpattern>] variable values. For example, given inpattern $1.$2 and the remote file name "mydata.data", $1 would have the value "mydata", and $2 would have the value "data". The <outpattern> determines the resulting mapped filename. The sequences "$1", "$2", ...., "$9" are replaced by any value resulting from the inpattern template. The sequence "$0" is replace by the original filename. Additionally, the sequence "[seq1, seq2]" is replaced by [seq1] if seq1 is not a null string; otherwise it is replaced by seq2. For example, the command

: nmap $1.$2.$3 [$1,$2].[$2,file]

would yield the output filename "myfile.data" for input filenames "myfile.data" and "myfile.data.old", "myfile.file" for the input filename "myfile", and "myfile.myfile" for the input filename ".myfile". Spaces may be included in <outpattern>, as in the example: nmap $1 sed "s/ *$//" > $1. Use the "\" character to prevent special treatment of the "$",'[','[', and "," characters.
|-
| ntrans [<inchars> [<outchars>]] || Set or unset the filename character translation mechanism. If no arguments are specified, the filename character translation mechanism is unset. If arguments are specified, characters in remote filenames are translated during mput commands and put commands issued without a specified remote target filename. If arguments are specified, characters in local filenames are translated during mget commands and get commands issued without a specified local target filename. This command is useful when connecting to a non-UNIX remote computer with different file naming conventions or practices. Characters in a filename matching a character in <inchars> are replaced with the corresponding character in <outchars>. If the character's position in <inchars> is longer than the length of <outchars>, the character is deleted from the file name.
|-
| open <host> [<port>] || Establish a connection to the specified host FTP server. An optional port number may be supplied, in which case, FTP will attempt to contact an FTP server at that port. If the auto-login option is on (default), FTP will also attempt to automatically log the user in to the FTP server (see below).
|-
| passive || Toggle passive mode. If passive mode is turned on (default is off), the FTP client will send a PASV command for all data connections instead of the usual PORT command. The PASV command requests that the remote server open a port for the data connection and return the address of that port. The remote server listens on that port and the client connects to it. When using the more traditional PORT command, the client listens on a port and sends that address to the remote server, who connects back to it. Passive mode is useful when using FTP through a gateway router or host that controls the directionality of traffic. (Note that though FTP servers are required to support the PASV command by RFC 1123, some do not.)
|-
| prompt|| Toggle interactive prompting. Interactive prompting occurs during multiple file transfers to allow the user to selectively retrieve or store files. If prompting is turned off (default is on), any mget or mput will transfer all files, and any mdelete will delete all files.
|-
| proxy <ftp-command> || Execute an FTP command on a secondary control connection. This command allows simultaneous connection to two remote FTP servers for transferring files between the two servers. The first proxy command should be an open, to establish the secondary control connection. Enter the command "proxy ?" to see other FTP commands executable on the secondary connection. The following commands behave differently when prefaced by proxy: open will not define new macros during the auto-login process, close will not erase existing macro definitions, get and mget transfer files from the host on the primary control connection to the host on the secondary control connection, and put, mput, and append transfer files from the host on the secondary control connection to the host on the primary control connection. Third party file transfers depend upon support of the FTP protocol PASV command by the server on the secondary control connection.
|-
| put <local-file> [<remote-file>] || Store a local file on the remote machine. If <remote-file> is left unspecified, the local file name is used after processing according to any ntrans or nmap settings in naming the remote file. File transfer uses the current settings for type, format, mode, and structure.
|-
| pwd || Print the name of the current working directory on the remote machine.
|-
| quit || A synonym for bye.
|-
| quote <arg1> <arg2> ... || The arguments specified are sent, verbatim, to the remote FTP server.
|-
| recv <remote-file> [<local-file>] || A synonym for get.
|-
| reget <remote-file> [<local-file>] || Reget acts like get, except that if <local-file> exists and is smaller than <remote-file>, <local-file> is presumed to be a partially transferred copy of <remote-file> and the transfer is continued from the apparent point of failure. This command is useful when transferring very large files over networks that are prone to dropping connections.
|-
| remotehelp [<command-name>] || Request help from the remote FTP server. If a <command-name> is specified it is supplied to the server as well.
|-
| remotestatus [<file-name>] || With no arguments, show status of remote machine. If <file-name> is specified, show status of <file-name> on remote machine.
|-
| rename [<from>] [<to>] || Rename the file <from> on the remote machine, to the file <to>.
|-
| reset || Clear reply queue. This command re-synchronizes command/reply sequencing with the remote FTP server. Resynchronization may be necessary following a violation of the FTP protocol by the remote server.
|-
| restart <marker> || Restart the immediately following get or put at the indicated marker. On UNIX systems, marker is usually a byte offset into the file.
|-
| rmdir <directory-name> || Delete a directory on the remote machine.
|-
| runique || Toggle storing of files on the local system with unique filenames. If a file already exists with a name equal to the target local filename for a get or mget command, a ".1" is appended to the name. If the resulting name matches another existing file, a ".2" is appended to the original name. If this process continues up to ".99", an error message is printed, and the transfer does not take place. The generated unique filename will be reported. Note that runique will not affect local files generated from a shell command (see below). The default value is off.
|-
| send <local-file> [<remote-file>] || A synonym for put.
|-
| sendport || Toggle the use of PORT commands. By default, FTP will attempt to use a PORT command when establishing a connection for each data transfer. The use of PORT commands can prevent delays when performing multiple file transfers. If the PORT command fails, FTP will use the default data port. When the use of PORT commands is disabled, no attempt will be made to use PORT commands for each data transfer. This is useful for certain FTP implementations which do ignore PORT commands but, incorrectly, indicate they've been accepted.
|-
| site <arg1> <arg2> ... || The arguments specified are sent, verbatim, to the remote FTP server as a SITE command.
|-
| size <file-name> || Return size of <file-name> on remote machine.
|-
| status || Show the current status of FTP.
|-
| struct [<struct-name>] || Set the file transfer structure to struct-name. By default "stream" structure is used.
|-
| sunique || Toggle storing of files on remote machine under unique file names. Remote FTP server must support FTP protocol STOU command for successful completion. The remote server will report unique name. Default value is off.
|-
| system || Show the type of operating system running on the remote machine.
|-
| tenex || Set the file transfer type to that needed to talk to TENEX machines.
|-
| trace || Toggle packet tracing.
|-
| type [<type-name>] || Set the file transfer type to <type-name>. If no type is specified, the current type is printed. The default type is network ASCII.
|-
| umask [<newmask>] || Set the default umask on the remote server to <newmask>. If <newmask> is omitted, the current umask is printed.
|-
| user <user-name> [<password>] [<account>] || Identify yourself to the remote FTP server. If the password is not specified and the server requires it, FTP will prompt the user for it (after disabling local echo). If an account field is not specified, and the FTP server requires it, the user will be prompted for it. If an account field is specified, an account command will be relayed to the remote server after the login sequence is completed if the remote server did not require it for logging in. Unless FTP is invoked with "auto-login" disabled, this process is done automatically on initial connection to the FTP server.
|-
| verbose || Toggle verbose mode. In verbose mode, all responses from the FTP server are displayed to the user. In addition, if verbose is on, when a file transfer completes, statistics regarding the efficiency of the transfer are reported. By default, verbose is on.
|-
| ? [<command>] || A synonym for help.
|}

;Aborting a file transfer
To abort a file transfer, use the terminal interrupt key (usually Ctrl-C). Sending transfers will be immediately halted. Receiving transfers will be halted by sending a FTP protocol ABOR command to the remote server, and discarding any further data received. The speed at which this is accomplished depends upon the remote server's support for ABOR processing. If the remote server does not support the ABOR command, an "ftp>" prompt will not appear until the remote server has completed sending the requested file.

The terminal interrupt key sequence will be ignored when FTP has completed any local processing and is awaiting a reply from the remote server. A long delay in this mode may result from the ABOR processing described above, or from unexpected behavior by the remote server, including violations of the FTP protocol. If the delay results from unexpected remote server behavior, the local FTP program must be killed by hand.

;File naming conventions
Files specified as arguments to FTP commands are processed according to the following rules.

# If the file name "-" is specified, the stdin (for reading) or stdout (for writing) is used.
# If the first character of the file name is "|", the remainder of the argument is interpreted as a shell command. FTP then forks a shell, using popen(3) with the argument supplied, and reads (writes) from the stdout (stdin). If the shell command includes spaces, the argument must be quoted; e.g. "ls -lt". A particularly useful example of this mechanism is: "dir more".
# Failing the above checks, if "globbing" is enabled, local file names are expanded according to the rules used in the csh(1); c.f. the glob command. If the FTP command expects a single local file (.e.g. put), only the first filename generated by the "globbing" operation is used.
# For mget commands and get commands with unspecified local file names, the local filename is the remote filename, which may be altered by a case, ntrans, or nmap setting. The resulting filename may then be altered if runique is on.
# For mput commands and put commands with unspecified remote file names, the remote filename is the local filename, which may be altered by a ntrans or nmap setting. The resulting filename may then be altered by the remote server if sunique is on.

;File transfer parameters
The FTP specification specifies many parameters which may affect a file transfer. The type may be one of "ascii", "image" (binary), "ebcdic", and "local byte size" (for PDP-10's and PDP-20's mostly). FTP supports the ascii and image types of file transfer, plus local byte size 8 for tenex mode transfers.

FTP supports only the default values for the remaining file transfer parameters: mode, form, and struct.

;The .netrc file
The .netrc file contains login and initialization information used by the auto-login process. It resides in the user's home directory. The following tokens are recognized; they may be separated by spaces, tabs, or new-lines:

{| class="wikitable"
| machine name || Identify a remote machine name. The auto-login process searches the .netrc file for a machine token that matches the remote machine specified on the FTP command line or as an open command argument. Once a match is made, the subsequent .netrc tokens are processed, stopping when the end of file is reached or another machine or a default token is encountered.
|-
| default || This is the same as machine name except that default matches any name. There can be only one default token, and it must beafter all machine tokens. This is normally used as:

: default login anonymous password user@site

thereby giving the user automatic anonymous FTP login to machines not specified in .netrc. This can be overridden by using the -n flag to disable auto-login.
|-
| login name || Identify a user on the remote machine. If this token is present, the auto-login process will initiate a login using the specified name.
|-
| password string || Supply a password. If this token is present, the auto-login process will supply the specified string if the remote server requires a password as part of the login process. Note that if this token is present in the .netrc file for any user other than anonymous, FTP will abort the auto-login process if the .netrc is readable by anyone besides the user.
|-
| account string || Supply an additional account password. If this token is present, the auto-login process will supply the specified string if the remote server requires an additional account password, or the auto-login process will initiate an ACCT command if it does not.
|-
| macdef name || Define a macro. This token functions like the FTP macdef command functions. A macro is defined with the specified name; its contents begin with the next .netrc line and continue until a null line (consecutive new-line characters) is encountered. If a macro named init is defined, it is automatically executed as the last step in the auto-login process.
|}

;Environment
FTP utilizes the following environment variables.
{| class="wikitable"
| HOME || For default location of a .netrc file, if one exists.
|-
| SHELL || For default shell.
|}

;Bugs
Correct execution of many commands depends upon proper behavior by the remote server.

An error in the treatment of carriage returns in the 4.2BSD ascii-mode transfer code has been corrected. This correction may result in incorrect transfers of binary files to and from 4.2BSD servers using the ascii type. Avoid this problem by using the binary image type.

;Example 1:
Missing examples.

== 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SET|SET]]

== 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SETENV|SETENV]]

== GETNETSTATUS ==

Queries whether the network is operational.

; Format
: GETNETSTATUS [CHECK=condition[,condition...]] [QUIET]

; Template
: CHECK/K,QUIET

; Location
: C:

The command is used to check/display which interfaces are currently running and which settings are being configured. It can be used in script files or for quick diagnostic purposes. The options are:
{| class="wikitable"
| CHECK || A list of conditions to check, which must be separated by commas. The following conditions can be checked:
{| class="wikitable"
| INTERFACES || Are any networking interfaces configured and operational?
|-
| PTPINTERFACES || Are any point-to-point interfaces, e.g. SLIP and PPP, configured and operational?
|-
| BCASTINTERFACES || Are any broadcast interfaces, e.g. Ethernet, configured and operational?
|-
| RESOLVER || Are any name resolution servers configured?
|-
| ROUTES || Is any routing information configured?
|-
| DEFAULTROUTE || Is the default route configured?
|}
If any of the conditions to test for is not satisfied, a message to this effect will be printed and the command will exit with status 5, which can be tested in script files using the 'IF WARN' command.
|-
| QUIET || Whatever happens, except for errors no output will be produced.
|}

If no conditions are to be checked for, then this command will print version information and the list of conditions that can be tested for, indicating which ones are satisfied and which are not.

;Example 1:
Find out which conditions can be tested.
1> GETNETSTATUS
bsdsocket.library 4.307 (9.2.2012) [Roadshow 4.307 (9.2.2012)]
Networking interfaces are available and configured.
'''No''' point-to-point networking interfaces are available and configured.
Broadcast networking interfaces are available and configured.
Name resolution servers are configured.
Routing information is configured.
The default route is configured.

;Example 2:
A script to test if the interfaces are operational.
<syntaxhighlight lang="text">
GETNETSTATUS CHECK="INTERFACES" QUIET
IF NOT WARN
ECHO "All interfaces are operational."
ELSE
GETNETSTATUS
ENDIF
</syntaxhighlight>

== GROUP ==

Changes the access rights of a file or directory.

; Format
: GROUP [FILE] {<file | pattern>} [GROUP] <name or number> [ALL] [QUIET]

; Template
: FILE/A/M,GROUP/A,ALL/S,QUIET/S

; Location
: C:

Each file or directory bears information which describes who may access it. This information can be displayed by the LIST command and is important if that file or directory is made accessible through a networked file system.

The GROUP command will change the access rights of one or more files or directories. The 'group' must be given either as a name or a number. The file system will have to understand the name given, or you will see an error message to this effect. If you know in advance which numeric group ID should be used in place of a name, you can provide this instead. Note that group names cannot be longer than 31 characters and that numeric group IDs must be in the range 0..65535. An empty name given for the group will remove the access rights information.

The options are:
{| class="wikitable"
| ALL || If the ALL option is given, GROUP will change the access rights of 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.
|}

;Example 1:
1> GROUP textfile admin

Grants access rights to "textfile" to the group "admin"

;Example 2:
1> GROUP textfile ""

Removes any access rights from "textfile".

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

Displays, recalls, or stores 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:

HISTORY can be used to show the past command line history, to save it to a file or load it from a file. If no other options are specified, it will show the command line history, each line prefixed by a number.

To restrict the number of history lines shown, use the LINES parameter; the default is to list all history lines, starting with the first one. To start the listing with a different line, use the START parameter. Each line will be prefixed by a number; to ignore the number, use the NONUM parameter.

The command history can be stored in or loaded from a file. To do either, specify the name of the file to be used with the LOAD or SAVE commands. These commands can be combined: the history command will always perform the SAVE command first before it performs the LOAD command. Note that the command line history will be added to the current list if loaded with the LOAD parameter unless you use the CLEAR parameter, too. Used all by itself, the CLEAR parameter will drop the current command line history.

The SIZE parameter controls the size of the command line history buffer which by default has room for about four complete command lines of maximum length. Changing the size tries to retain the contents of the current command line history buffer.

;Example 1:
1> HISTORY

Lists the current command line history, starting with the first line, printing all lines in the buffer.

;Example 2:
1> HISTORY LINES 5 START 3

Prints five lines of command line history, starting with the third line. If fewer lines are stored in the buffer, fewer will be printed.

;Example 3:
1> HISTORY SAVE old-history LOAD new-history CLEAR

Saves the current command line history in the file 'old-history', then clears the history buffer and eventually loads the command line history from the file 'new-history'. Note that if either the save or the load command fails no changes will be made to the contents of the current history buffer.

;Example 4:
1> HISTORY SIZE 16

Sets the maximum size of the history buffer to about 8,000 characters.

;Example 5:
1> HISTORY START -2 LINES 1 NONUM

Displays the last command line entered (preceding the 'HISTORY START -2 LINES 1 NONUM' command).

== 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]

== IDENTD ==

TCP/IP IDENT protocol server.

; Format
: IDENTD

; Template
: (none)

; Location
: C:

When running IDENTD returns user information to a remote host that a user is requesting a service from.

== IDETOOL ==

Modfies ATA/ATAPI device driver parameters.

; Format
: IDETOOL [ <command> [ <argument>... ] ]...

; Template
: -v,-c,-l,-u,-d,-r,-x,-p,-i,-o,-j,-m,-w,-s,-a,-b,-e,-f,-t,-g,-0,-1,-2,-3,-4,-5,-6,-7,-8,-9

; Location
: C:

IDETOOL allows querying and modifying internal parameters of the following ATA/ATAPI device drivers:
* a1ide.device, which controls the VIA686B PATA IDE controller
* sii0680ide.device, which controls Silicon Image SiI0680(A)-based PCI PATA IDE controller
* sii3112ide.device, which controls Silicon Image SiI3112(A)-based PCI SATA IDE controller
* sii3114ide.device, which controls Silicon Image SiI3114-based PCI SATA IDE controller
* sii3512ide.device, which controls Silicon Image SiI3512-based PCI SATA IDE controller
* lsi53c8xx.device, which controls LSI Logic 53c8xx-based SCSI PCI controllers

IDETOOL can also be used to examine and modify any PCI device configuration and I/O space (only use this feature if you really know what you are doing). A word on PCI device configuration space:

* All PCI devices are uniquely identified by a Vendor and a Product code. Those are 16 bit figures, which can be represented as 4 hex digit values. Example: the VIA IDE controller is identified by vendor code 0x1106 and product code 0x0571.
* All PCI devices expose on the bus, 256 bytes of configuration data called the "configuration space". This configuration space contains a part which is rigidly defined in the PCI specification, and a part which structure is up to the device manufacturer. In the standardized part, we find things like the vendor & product codes, the PCI latency setting for the device, the interrupt pin / line settings for the device etc.
* Additionnally to this configuration space, each PCI device can have up to 5 address ranges, which can either be "IO space" or "memory space", for whatever usage. Example: a graphics card will probably have a memory mapped area which contains a linearly addressed image of its framebuffer memory.

The purpose of the PCI configuration and IO manipulation features in IDETOOL is primarily to be able to finetune the IDE device operation, but it can also be used as a general purpose diagnostic and tuning tool for all other PCI devices (USB, Ethernet, Audio, Graphic cards etc.).

IDETOOL recognizes the following commads:
{| class="wikitable"
| -v || tell version
|-
| -c || tell CPU configuration
|-
| -l <device name> || tell unit info for all device <device name> units
|-
| -u <device name> <unit> || tell unit info for unit <unit>
|-
| -d <device name> <unit> || tell drive info for unit <unit>
|-
| -r <device name> <unit> || tell raw drive info for unit <unit>
|-
| -x <device name> <unit> <mode> || put drive <unit> into transfer mode <mode>
|-
| -p <device name> <unit> <mode> || put drive <unit> into power mode <mode>: 2 = spin up, 3 = spin down, 5 = sleep forever
|-
| -i <device name> <unit> <mode> || put drive <unit> into interrupt mode <mode>: 0 = don't use irq's, 1 = use irq's
|-
| -o <device name> <unit> || just open & close <device name>/<unit>
|-
| -j <device name> <unit> e | l || eject/load disk in drive <unit>. e = eject, l = load
|-
| -m <device name> <unit> <read speed> <write speed> || set <unit> medium read / write speed: 1 .. n for x1 ... xn, or 0xFFFF for max.
|-
| -w || tell VIA686b PCI IDE configuration
|-
| -s || tell SiI0680 PCI IDE configuration
|-
| -a || tell SiI3112 PCI IDE configuration
|-
| -b || tell SiI3114 PCI IDE configuration
|-
| -e || tell SiI3512 PCI IDE configuration
|-
| -f || tell LSI53cxxx PCI SCSI configuration
|-
| -t <vendor> <device> || tell PCI device <vendor>/<device> configuration
|-
| -g <reg> <val> || patch LSI53cxxx configspace byte <reg> with value <val>
|-
| -0 <reg> <val> || patch VIA function 0 (ISA) configspace byte <reg> with value <val>
|-
| -1 <reg> <val> || patch VIA function 1 (IDE) configspace byte <reg> with value <val>
|-
| -2 <reg> <val> || patch SiI0680 configspace byte <reg> with value <val>
|-
| -3 <reg> <val> || patch SiI3112 configspace byte <reg> with value <val>
|-
| -4 <reg> <val> || patch SiI3114 configspace byte <reg> with value <val>
|-
| -5 <reg> <val> || patch SiI3512 configspace byte <reg> with value <val>
|-
| -6 <vendor> <device> <reg> || tell PCI device <vendor>/<device> I/O byte <reg> value
|-
| -7 <vendor> <device> <reg> <val> || patch PCI device <vendor>/<device> I/O byte <reg> with value <val>
|-
| -8 <vendor> <device> <reg> || tell PCI device <vendor>/<device> configspace byte <reg> value
|-
| -9 <vendor> <device> <reg> <val> || patch PCI device <vendor>/<device> configspace byte <reg> with value <val>
|}

{{Note|Note on inputting numeric values: if the first character is 0 and the second character is not 'x' or 'X', the string is interpreted as an octal integer; otherwise, it is interpreted as a decimal number. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer.}}

'''Beware''': Do not use IDETOOL except if you really know what you are doing.

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

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

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

; Example 1:
<syntaxhighlight lang="text">
IF EXISTS Work/Prog
TYPE Work/Prog HEX
ELSE
ECHO "It's not here"
ENDIF
</syntaxhighlight>

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:
<syntaxhighlight lang="text">
IF ERROR
SKIP errlab
ENDIF
ECHO "No error"
LAB errlab
</syntaxhighlight>

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
* [[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 ==

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:
{| 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

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 |</nowiki> o <nowiki>|</nowiki> a <nowiki>|</nowiki> s <nowiki>|</nowiki> 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:

IPF opens the filenames listed (treating "-" as stdin) and parses the file for a set of rules which are to be added or removed from the packet filter rule set.

Each rule processed by IPF is added to the kernel's internal lists if there are no parsing problems. Rules are added to the end of the internal lists, matching the order in which they appear when given to IPF.

The options are:
{| class="wikitable"
| -A || Set the list to make changes to the active list (default).
|-
| -d || Turn debug mode on.Causes a hexdump of filter rules to be generated as it processes each one.
|-
| -D || Disable the filter (if enabled). Not effective for loadable kernel versions.
|-
| -E || Enable the filter (if disabled). Not effective for loadable kernel versions.
|-
| -F |</nowiki> o <nowiki>|</nowiki> a> || This option specifies which filter list to flush. The parameter should either be "i" (input), "o" (output) or "a" (remove all filter rules). Either a single letter or an entire word starting with the appropriate letter maybe used. This option maybe before, or after, any other with the order on the command line being that used to execute options.
|-
| -F <s <nowiki>|</nowiki> S> || To flush entries from the state table, the -F option is used in conjuction with either "s" (removes state information about any non-fully established connections) or "S" (deletes the entire state table). Only one of the two options may be given. A fully established connection will show up in IPFSTAT -s output as 4/4, with deviations either way indicating it is not fully established any more.
|-
| -f <filename> || This option specifies which files IPF should use to get input from for modifying the packet filter rule lists.
|-
| -I || Set the list to make changes to the inactive list.
|-
| -l <pass <nowiki>|</nowiki> block <nowiki>|</nowiki> nomatch> || Use of the -l flag toggles default logging of packets. Valid arguments to this option are pass, block and nomatch. When an option is set, any packet which exits filtering and matches the set category is logged. This is most useful for causing all packets which don't match any of the loaded rules to be logged.
|-
| -n || This flag (no-change) prevents IPF from actually making any ioctl calls or doing anything which would alter the currently running kernel.
|-
| -o || Force rules by default to be added/deleted to/from the output list, rather than the (default) input list.
|-
| -P || Add rules as temporary entries in the authentication rule table.
|-
| -r || Remove matching filter rules rather than add them to the internal lists
|-
| -s || Swap the active filter list in use to be the "other" one.
|-
| -v || Turn verbose mode on. Displays information relating to rule processing.
|-
| -V || Show version information. This will display the version information compiled into the IPF binary and retrieve it from the kernel code (if running/present). If it is present in the kernel, information about its current state will be displayed (whether logging is active, default filtering, etc).
|-
| -y || Manually resync the in-kernel interface list maintained by IP Filter with the current interface status list.
|-
| -z || For each rule in the input file, reset the statistics for it t zero and display the statistics prior to them being zero'd.
|-
| -Z || Zero global statistics held in the kernel for filtering only (this doesn't affect fragment or state statistics).
|}

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPFTEST|IPFTEST]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#MKFILTERS|MKFILTERS]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPL|IPL]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPFSTAT|IPFSTAT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPMON|IPMON]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPNAT|IPNAT]]

== IPFSTAT ==

Reports on packet filter statistics and filter list.

; Format
: IPFSTAT [ -aAfghIinosv ] [ -d <device> ]
:
: IPFSTAT -t [ -C ] [ -D <addrport> ] [ -P <protocol> ] [ -S <addrport> ] [ -T <refresh time> ] [ -d <device> ]

; Template
: -a,-A,-f,-g,-h,-I,-i,-n,-o,-s,-v,-d
: -t,-C,-D,-P,-S,-T,-d

; Location
: C:

IPFSTAT examines /dev/kmem using the symbols _fr_flags, _frstats, _filterin, and _filterout. To run and work, it needs to be able to read both /dev/kmem and the kernel itself. The kernel name defaults to /vmunix.

The default behaviour of IPFSTAT is to retrieve and display the accumulated statistics which have been accumulated over time as the kernel has put packets through the filter.

The options are:
{| class="wikitable"
| -a || Display the accounting filter list and show bytes counted against each rule.
|-
| -A || Display packet authentication statistics.
|-
| -C || This option is only valid in combination with -t. Display "closed" states as well in the top. Normally, a TCP connection is not displayed when it reaches the CLOSE_WAIT protocol state. With this option enabled, all state entries are displayed.
|-
| -d <device> || Use a device other than /dev/ipl for interfacing with the kernel.
|-
| -D <addrport> || This option is only valid in combination with -t. Limit the state top display to show only state entries whose destination IP address and port match the addport argument. The addrport specification is of the form ipaddress[,port]. The ipaddress and port should be either numerical or the string "any" (specifying any ip address resp. any port). If the -D option is not specified, it defaults to "-D any,any".
|-
| -f || Show fragment state information (statistics) and held state information (in the kernel) if any is present.
|-
| -g || Show groups currently configured (both active and inactive).
|-
| -h || Show per-rule the number of times each one scores a "hit". For use in combination with -i.
|-
| -i || Display the filter list used for the input side of the kernel IP processing.
|-
| -I || Swap between retrieving "inactive"/"active" filter list details. For use in combination with -i.
|-
| -n || Show the "rule number" for each rule as it is printed.
|-
| -o || Display the filter list used for the output side of the kernel IP processing.
|-
| -P <protocol> || This option is only valid in combination with -t. Limit the state top display to show only state entries that match a specific protocol. The argument can be a protocol name (as defined in /etc/protocols) or a protocol number. If this option is not specified, state entries for any protocol are specified.
|-
| -s || Show packet/flow state information (statistics only).
|-
| -sl || Show held state information (in the kernel) if any is present (no statistics).
|-
| -S <addrport> || This option is only valid in combination with -t. Limit the state top display to show only state entries whose source IP address and port match the addport argument. The addrport specification is of the form ipaddress[,port]. The ipaddress and port should be either numerical or the string "any" (specifying any ip address resp. any port). If the -S option is not specified, it defaults to "-S any,any".
|-
| -t || Show the state table in a way similar to they way top(1) shows the process table. States can be sorted using a number of different ways. This options requires ncurses(3) and needs to be compiled in. It may not be available on all operating systems. See below, for more information on the keys that can be used while IPFSTAT is in top mode.
|-
| -T <refreshtime> || This option is only valid in combination with -t. Specifies how often the state top display should be updated. The refresh time is the number of seconds between an update. Any postive integer can be used. The default (and minimal update time) is 1.
|-
| -v || Turn verbose mode on. Displays more debugging information.
|}

;Synopsis
The role of IPFSTAT is to display current kernel statistics gathered as a result of applying the filters in place (if any) to packets going in and out of the kernel. This is the default operation when no command line parameters are present.

When supplied with either -i or -o, it will retrieve and display the appropriate list of filter rules currently installed and in use by the kernel.

;State top
Using the -t option IPFSTAT will enter the state top mode. In this mode the state table is displayed similar to the way top displays the process table. The -C, -D, -P, -S and -T commandline options can be used to restrict the state entries that will be shown and to specify the frequency of display updates.

In state top mode, the following keys can be used to influence the displayed information:
{| class="wikitable"
| d || select information to display.
|-
| l || redraw the screen.
|-
| q || quit the program.
|-
| s || switch between different sorting criterion.
|-
| r || reverse the sorting criterion.
|}

States can be sorted by protocol number, by number of IP packets, by number of bytes and by time-to-live of the state entry. The default is to sort by the number of bytes. States are sorted in descending order, but you can use the r key to sort them in ascending order.

;State top limitations
It is currently not possible to interactively change the source, destination and protocol filters or the refresh frequency. This must be done from the command line.

The screen must have at least 80 columns. This is however not checked.

Only the first X-5 entries that match the sort and filter criteria are displayed (where X is the number of rows on the display. There is no way to see more entries.

No support for IPv6

;Files
* /dev/kmem
* /dev/ipl
* /dev/ipstate
* /vmunix

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPF|IPF]]

== 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:

IPMON opens /dev/ipl for reading and awaits data to be saved from the packet filter. The binary data read from the device is reprinted in human readable for, however, IP#'s are not mapped back to hostnames, nor are ports mapped back to service names. The output goes to standard output by default or a filename, if given on the command line. Should the -s option be used, output is instead sent to SYSLOGD. Messages sent via syslog have the day, month and year removed from the message, but the time (including microseconds), as recorded in the log, is still included.

Messages generated by IPMON consist of whitespace separated fields. Fields common to all messages are:

# The date of packet receipt. This is suppressed when the message is sent to syslog.
# The time of packet receipt. This is in the form HH:MM:SS.F, for hours, minutes seconds, and fractions of a second (which can be several digits long).
# The name of the interface the packet was processed on, e.g., we1.
# The group and rule number of the rule, e.g., @0:17. These can be viewed with IPFSTAT -n.
# The action: p for passed or b for blocked.
# The addresses. This is actually three fields: the source address and port (separted by a comma), the -> symbol, and the destination address and port. E.g.: 209.53.17.22,80 -> 198.73.220.17,1722.
# PR followed by the protocol name or number, e.g., PR tcp.
# len followed by the header length and total length of the packet, e.g., len 20 40.

If the packet is a TCP packet, there will be an additional field starting with a hyphen followed by letters corresponding to any flags that were set. See the ipf.conf manual page for a list of letters and their flags. If the packet is an ICMP packet, there will be two fields at the end, the first always being "icmp", and the next being the ICMP message and submessage type, separated by a slash, e.g., icmp 3/3 for a port unreachable message.

In order for IPMON to properly work, the kernel option IPFILTER_LOG must be turned on in your kernel. Please see options for more details.

The options are:
{| class="wikitable"
| -a || Open all of the device logfiles for reading log entries from. All entries are displayed to the same output "device" (stderr or syslog).
|-
| -D || Cause IPMON to turn itself into a daemon. Using subshells or backgrounding of IPMON is not required to turn it into an orphan so it can run indefinately.
|-
| -f <device> || specify an alternative device/file from which to read the log information for normal IP Filter log records.
|-
| -F || Flush the current packet log buffer. The number of bytes flushed is displayed, even should the result be zero.
|-
| -n || IP addresses and port numbers will be mapped, where possible, back into hostnames and service names.
|-
| -N <device> || Set the logfile to be opened for reading NAT log records from to <device>.
|-
| -o || Specify which log files to actually read data from. N - NAT logfile, S - State logfile, I - normal IP Filter logfile. The -a option is equivalent to using -o NSI.
|-
| -O || Specify which log files you do not wish to read from. This is most sensibly used with the -a. Letters available as paramters to this are the same as for -o.
|-
| -p || Cause the port number in log messages to always be printed as a number and never attempt to look it up as from /etc/services, etc.
|-
| -P <pidfile> || Write the pid of the IPMON process to a file. By default this is //etc/opt/ipf/IPMON.pid (Solaris), /var/run/IPMON.pid (44BSD or later) or /etc/IPMON.pid for all others.
|-
| -s || Packet information read in will be sent through SYSLOGD rather than saved to a file. The default facility when compiled and installed is local0.
The following levels are used:
{| class="wikitable"
| LOG_INFO || packets logged using the "log" keyword as the action rather than pass or block.
|-
| LOG_NOTICE || packets logged which are also passed
|-
| LOG_WARNING || packets logged which are also blocked
|-
| LOG_ERR || packets which have been logged and which can be considered "short".
|}
|-
| -S <device> || Set the logfile to be opened for reading state log records from to <device>.
|-
| -t || read the input file/device in a manner akin to TAIL.
|-
| -v || show tcp window, ack and sequence fields.
|-
| -x || show the packet data in hex.
|-
| -X || show the log header record data in hex.
|}

;Diagnostics
IPMON expects data that it reads to be consistent with how it should be saved and will abort if it fails an assertion which detects an anomaly in the recorded data.

;Files
* /dev/ipl
* /dev/ipnat
* /dev/ipstate
* /etc/services

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPL|IPL]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPF|IPF]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPFSTAT|IPFSTAT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPNAT|IPNAT]]

== IPNAT ==

Defines NAT (Network Address Translation) rules.

; Format
: IPNAT [ -lnrsvCF ] -f <filename>

; Template
: -l,-n,-r,-s,-v,-C,-F,-f

; Location
: C:

IPNAT opens the filename given (treating "-" as stdin) and parses the file for a set of rules which are to be added or removed from the IP NAT.

Each rule processed by IPNAT is added to the kernels internal lists if there are no parsing problems. Rules are added to the end of the internal lists, matching the order in which they appear when given to IPNAT.

The options are:
{| class="wikitable"
| -C || delete all entries in the current NAT rule listing (NAT rules)
|-
| -F || delete all active entries in the current NAT translation table (currently active NAT mappings)
|-
| -l || Show the list of current NAT table entry mappings.
|-
| -n || This flag (no-change) prevents ipf from actually making any ioctl calls or doing anything which would alter the currently running kernel.
|-
| -s || Retrieve and display NAT statistics
|-
| -r || Remove matching NAT rules rather than add them to the internal lists
|-
| -v || Turn verbose mode on. Displays information relating to rule processing and active rules/table entries.
|}

;Files
* /dev/IPNAT

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPNAT|IPNAT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPF|IPF]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IPFSTAT|IPFSTAT]]

== 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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|Chapter 8]].

== KDEBUG ==

Controls kernel debug options.

; Format
: <command>

; Template
: COMMAND/F

; Location
: C:

KDEBUG is a simple interface to set kernel parameters from the command line. The command is sent verbatim for further processing and the actual parsing is left to the kernel itself.

The following kernel commands are available:
{| class="wikitable"
| debuglevel <level> || Sets the verbosity of debug output of the kernel.
{| class="wikitable"
| 0 || means no output.
|-
| 5 || is low (only warnings and critical errors)
|-
| 10 || is verbose (more information)
|-
| 20 || means it will log every function entry and exit in the kernel
|}
|-
| console <name> || Select the console. This is either "serial" or "memory".

Kernels before version 51.44 default to the serial console, 8N1, the baudrate can be specified in UBoot (AmigaOne) or the BootLoader commandline (classic machines). Since kernel version 51.44 the default console is the memory console, to use the serial port instead you can specify the "serial" or "serial=1" keyword on the kernel commandline in UBoot or BootLoader.

To view the memory buffer use the DumpDebugBuffer command.

When switching the console, this setting survives a soft reboot.

Note: the memory console has no input parameters.
|-
| alignment [ warn | nowarn ] || Controls alignment exception warnings. This is either "warn" or "nowarn". Defaults to not warn about alignment exceptions.
|-
| memorymap || Dumps the current memory map if the debug level is 3 or higher.
|-
| pagestat [numpages] || Dumps memory paging statistics. The number of pages to output may be specified. Defaults to print out 20 pages.
|-
| status || Dumps the status of various kernel options.
|}

;Example 1
Set the kernel debug level to 5.

1> KDEBUG debuglevel 5

;Example 2
Enable serial debug output.

1> KDEBUG console serial

;Example 3
Dump the memory map.

1> KDEBUG debuglevel 3
1> KDEBUG memorymap

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#DUMPDEBUGBUFFER|DUMPDEBUGBUFFER]]

== 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SKIP|SKIP]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#IF|IF]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#EXECUTE|EXECUTE]]

== 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:
{| class="wikitable"
| 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:
{| class="wikitable"
| 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:

{| 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"
| %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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#PROTECT|PROTECT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#FILENOTE|FILENOTE]]

== 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:
{| class="wikitable"
| 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:
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:
1> LOADRESOURCE FONTS:topaz/11

loads the Topaz 11 font into memory.

; Example 3:
1> 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:
{| 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:

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:

{| 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:
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.

== MEMSTAT ==

?

; Format
: [VERBOSE] [KB] [DETAILED]

; Template
: VERBOSE/S,KB/S,DETAILED/S

; Location
: C:

Missing description.

== MKNTFS ==

Creates an NTFS file system.

; Format
: MKNTFS [options] device [number-of-sectors]
: MKNTFS [ -C ] [ -c cluster-size ] [ -F ] [ -f ] [ -H heads ] [ -h ] [ -I ]
: [ -L volume-label ] [ -l ] [ -n ] [ -p part-start-sect ] [ -Q ] [ -q ]
: [ -S sectors-per-track ] [ -s sector-size ] [ -T ] [ -U ] [ -V ] [ -v ]
: [ -z mft-zone-multiplier ] [ --debug ] device [ number-of-sectors ]

; Template
: Missing

; Location
: C:

MKNTFS is used to create an NTFS file system on a device (usually a disk partition) or file. device is the special file corresponding to the device (e.g /dev/hdXX). number-of-sectors is the number of sectors on the device. If omitted, MKNTFS automagically figures the file system size.

Below is a summary of all the options that MKNTFS accepts. Nearly all options have two equivalent names. The short name is preceded by - and the long name is preceded by --. Any single letter options, that don‚t take an argument, can be combined into a single command, e.g. -fv is equivalent to -f -v. Long named options can be abbreviated to any unique prefix of their name.

;Basic options
{| class="wikitable"
| -f, --fast, -Q, or --quick || Perform quick (fast) format. This will skip both zeroing of the volume and bad sector checking.
|-
| -L, --label STRING || Set the volume label for the filesystem.
|-
| -C or --enable-compression || Enable compression on the volume.
|-
| -n or --no-action || Causes MKNTFS to not actually create a filesystem, but display what it would do if it were to create a filesystem. All steps of the format are carried out except the actual writing to the device.
|}

;Advanced options
{| class="wikitable"
| -c, --cluster-size BYTES || Specify the size of clusters in bytes. Valid cluster size values are powers of two, with at least 256, and at most 65536 bytes per cluster. If omitted, MKNTFS uses 4096 bytes as the default cluster size.
Note that the default cluster size is set to be at least equal to the sector size as a cluster cannot be smaller than a sector. Also, note that values greater than 4096 have the side effect that compression is disabled on the volume (due to limitations in the NTFS compression algorithm currently in use by Windows).
|-
| -s, --sector-size BYTES || Specify the size of sectors in bytes. Valid sector size values are 256, 512, 1024, 2048 and 4096 bytes per sector. If omitted, MKNTFS attempts to determine the sector-size automatically and if that fails a default of 512 bytes per sector is used.
|-
| -p, --partition-start SECTOR || Specify the partition start sector. The maximum is 4294967295 (2^32-1). If omitted, MKNTFS attempts to determine part-start-sect automatically and if that fails a default of 0 is used. Note that part-start-sect is required for Windows to be able to boot from the created volume.
|-
| -H, --heads NUM || Specify the number of heads. The maximum is 65535 (0xffff). If omitted, MKNTFS attempts to determine the number of heads automatically and if that fails a default of 0 is used. Note that heads is required for Windows to be able to boot from the created volume.
|-
| -S, --sectors-per-track NUM || Specify the number of sectors per track. The maximum is 65535 (0xffff). If omitted, MKNTFS attempts to determine the number of sectors-per-track automatically and if that fails a default of 0 is used. Note that sectors-per-track is required for Windows to be able to boot from the created volume.
|-
| -z, --mft-zone-multiplier NUM || Set the MFT zone multiplier, which determines the size of the MFT zone to use on the volume. The MFT zone is the area at the beginning of the volume reserved for the master file table (MFT), which stores the on disk inodes (MFT records). It is noteworthy that small files are stored entirely within the inode; thus, if you expect to use the volume for storing large numbers of very small files, it is useful to set the zone multiplier to a higher value. Note, that the MFT zone is resized on the fly as required during operation of the NTFS driver but choosing a good value will reduce fragmentation. Valid values are 1, 2, 3 and 4. The values have the following meaning:
{| class="wikitable" style="text-align: center;"
! MFT zone multiplier
! MFT zone size (% of volume size)
|-
| 1 || 12.5% (default)
|-
| 2 || 25.0%
|-
| 3 || 37.5%
|-
| 4 || 50.0%
|}
|-
| -T or --zero-time || Fake the time to be 00:00:00 UTC, Jan 1, 1970 instead of the current system time. This is only really useful for debugging purposes.
|-
| -U or --with-uuid || Generate a random volume UUID.
|-
| -I or --no-indexing || Disable content indexing on the volume. (This is only meaningful on Windows 2000 and later. Windows NT 4.0 and earlier ignore this as they do not implement content indexing at all.)
|-
| -F or --force || Force MKNTFS to run, even if the specified device is not a block special device, or appears to be mounted.
|}

;Output options
{| class="wikitable"
| -q or --quiet || Quiet execution; only errors are written to stderr, no output to stdout occurs at all. Useful if MKNTFS is run in a script.
|-
| -v or --verbose || Verbose execution.
|-
| --debug || Really verbose execution; includes the verbose output from the -v option as well as additional output useful for debugging MKNTFS.
|}

;Help options
{| class="wikitable"
| -V or --version || Print the version number of MKNTFS and exit.
|-
| -l or --license || Print the licensing information of MKNTFS and exit.
|-
| -h or --help || Show a list of options with a brief description of each one.
|}

;Known Issues
When applying CHKDSK to a file system, it sometimes throws a warning "Correcting errors in the uppercase file." The uppercase file is created while formatting and it defines the mapping of lower case characters to upper case ones, as needed to sort file names in directories. The warning means that the uppercase file defined on the file system is not the same as the one used by the Windows OS on which chkdsk is running, and this may happen because newer versions of Windows take into account new characters defined by the Unicode consortium.

Currently, MKNTFS creates the uppercase table so that no warning is thrown by Windows Vista, Windows 7 or Windows 8. A warning may be thrown by other Windows versions, or if chkdsk is applied in succession on different Windows versions.

== 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:

MOUNTINFO gathers information on a device in order to create a mount file for it which can later be used to mount that device again. This is useful for removable media or data recovery in case the partition information for a hard disk was destroyed, but the contents of the partition survived.

In addition to creating mount files, MOUNTINFO can also provide debugging information for software developers and customer support.

The options are:
{| class="wikitable"
| DEVICE || This must be the name of the device to provide mount information for. It must be a device name with a trailing ':' character, such as "DF0:".
|-
| TO || This option tells MOUNTINFO to write the mount file data to a named file rather than just printing it on the console window.
|-
| ADDICON || If you told MOUNTINFO to write the mount file data to a named file, you might want to have an icon added to it as well, so that you can drop the resulting mount file into the "SYS:Storage/DOSDrivers" or "DEVS:DOSDrivers" drawers for later use. MOUNTINFO will try to use the default mount file icon stored in "ENV:sys/def_mountfile.info" and revert to use a generic project icon if the mount file icon cannot be found.
|-
| ACTIVATE || If this option is used MOUNTINFO will store the mount file in a manner which will activate the file system as soon as it has been mounted. If an icon is added to the mount file (by using the ADDICON option) then the "Activate=Yes" tool type will be added to the icon. If the ADDICON is not used, the "Activate=Yes" line will be added to the end of the mount file data.
|-
| DEBUG || If this option is used, the TO and ADDICON options will be ignored. The mount information for the device, assignment or volume you provided will be gathered and printed in a special format instead, suitable for use by software developers and customer support. For disk drives the MOUNTINFO command will try to determine which file system is responsible for managing the volume and print both the signature of the file system assigned to the volume and the signature of the file system, as stored on the first block of the partition. Note that not all file systems store a signature value in the first block of the partition, so the information provided may not be relevant.
|-
| NOTES || Not all file system devices can be asked to provide mount information. An exception is, for example, the RAM: device.
|}

;Example 1:
1> MOUNTINFO DF0:
\* DF0: (02/03/06 12:51 PM) *\
Surfaces = 2
SectorsPerTrack = 11
LowCyl = 0
HighCyl = 79
BufMemType = 1
MaxTransfer = 2097152
Mask = 0x7FFFFFFE
BootPri = 5
BootBlocks = 2
Device = "trackdisk.device"
GlobVec = 0

;Example 2:
1> MOUNTINFO RAM:
RAM: object is not of required type

;Example 3:
1> MOUNTINFO WB_2.x: DEBUG
dol_Type = DLT_DEVICE
dol_Task = 0x802B6CC
dol_Lock = NULL
dol_Handler = NULL
dol_StackSize = 600
dol_Priority = 10
fssm_Device = "scsi.device"
fssm_Unit = 0
fssm_Flags = 0
de_TableSize = 16
de_SizeBlock = 512 bytes
de_SecOrg = 0
de_Surfaces = 19
de_SectorPerBlock = 1
de_BlocksPerTrack = 240
de_Reserved = 2
de_PreAlloc = 0
de_Interleave = 0
de_LowCyl = 2
de_HighCyl = 46
de_NumBuffers = 100
de_BufMemType = MEMF_ANY
de_MaxTransfer = 16777215
de_Mask = 0x7FFFFFFE
de_BootPri = 1
de_DosType = DOS\1 0x444F5301
(different signature on disk = DOS\3 0x444F5303)
dol_SegList = 0xF9DC44
dol_GlobVec = 0
dol_Name = "WB_2.x"

== MOVE ==

Moves files or directories.

; Format
: MOVE [FROM] {<name|pattern>} [TO] <name> [QUIET] [BUF|BUFFER=<n>]
: [NOREQ] [NOREPLACE] [INTERACTIVE] [FORCE] [COPYLINKS] [FOLLOWLINKS]

; 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:

MOVE copies the file or directory specified with the FROM argument to the file or directory specified by the TO argument, removing the source file after the copy has been created (thus, 'moving' the files). You can move several items at once by giving more than one FROM argument; each argument should be separated by spaces. You can use pattern matching to move or exclude items whose names share a common set of characters or symbols.

If a TO filename already exists, MOVE overwrites the TO file with the FROM file. If you name a destination directory that does not exist, MOVE 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, its files, subdirectories, and the subdirectories' files will be moved. If you want to move 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.

MOVE prints to the screen the name of each file as it is moved. 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.

The options are:
{| class="wikitable"
| NOREPLACE || Checks if the destination file already exists. If this is the case, then the file is not moved.
|-
| 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.
|-
| COPYLINKS || If files need to be copied, copy the contents of a file referenced by a hard or soft link; the default is to skip copying linked files.
|-
| FOLLOWLINKS || Follow hard and soft links to directories; the default is to skip links to directories.

Normally, MOVE displays a requester if the MOVE cannot continue for some reason. When the NOREQ option is given, all requesters are suppressed. This is useful in scripts and can prevent a MOVE failure from stopping the script while it waits for a response. For instance, if a script calls for a certain file to be moved 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 MOVE command would be aborted and the script would continue.
|}

;Example 1:
1> MOVE File1 TO :Work/File2

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

;Example 2:
1> MOVE (#?.info) TO DF1:Backup

moves 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> MOVE Work:Test TO DF0:Test

moves 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 4:
1> MOVE DF0: TO DF1: QUIET

moves all files and directories on the disk in DF0: to DF1:, without displaying on the screen any file/directory names as they are moved.

== 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:

Normally, any message that bsdsocket.library or its clients produce is displayed in a console window. This program will capture and display any of these messages in a special window where the messages can be reviewed and even saved to disk.

The options are:
{| class="wikitable"
| CX_POPKEY || Key combination to be pressed in order to show the log message window. Default is "shift alt f8".
|-
| CX_PRIORITY || Priority this tool's input event handler has in the Commodities filter chain. Default is 0, which should not be changed.
|-
| CX_POPUP || Whether or not the log window should appear when the program is first started. Defaults to "yes" (use "no" to hide the window)
|}

{{Note|The NETLOGVIEWER program can be started from Workbench, too. In this case it will check its icon for tool types whose names and purposes match the command template described above.}}

{{Note|You can and should start the NETLOGVIEWER program before you add the first networking interface (in order to capture any error output). Note, however, that if you shut down the bsdsocket.library (by using the NETLOGVIEWER command) the NETLOGVIEWER program will exit, too.}}

== NETSHUTDOWN ==

Shuts down the network in an orderly fashion.

; Format
: NETSHUTDOWN [<seconds>] [QUIET]

; Template
: TIMEOUT/N,QUIET/S

; Location
: C:

The command will stop all running interfaces. The options are:
{| class="wikitable"
| TIMEOUT || How many seconds this command should wait until it gives up. By default, it will wait up to 5 seconds for the network to shut down once it has triggered the shutdown process.
|-
| QUIET || Use this parameter to stop the command from reporting what it is currently doing.
|}

The NETSHUTDOWN command will trigger the shutdown process of the network. This process cannot be stopped once it has started. However, this command can make an attempt to wait until the shutdown has completed. Normally, the shutdown should be finished in a fraction of a second, but at times when other clients still hang onto the network resources, the shutdown can fail to complete quite so quickly. In that case, the NETSHUTDOWN command will tell you that it could not complete its task within the allocated time frame (within five seconds, or whatever timeout you specified). The shutdown, however, will proceed and may conclude at a later time.

When this command starts up it begins by checking if the network is currently operational. If this is not the case, it will exit immediately, printing a message to this effect.

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ADDNETINTERFACE|ADDNETINTERFACE]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SHOWNETSTATUS|SHOWNETSTATUS]]

== 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:
{| class="wikitable"
| 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:
{| class="wikitable"
| 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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|Chapter 8]].

== NTFSCAT ==

Prints NTFS files and streams.

; Format
: NTFSCAT [options] <device> [<file>]

; Template
: -a=--attribute,-n=--attribute-name,-i=--inode,-f=--force,-h=--help,-q=--quiet,-V=--version,-v=--verbose,DEVICE,FILE

; Location
: C:

NTFSCAT reads a file or a stream from an NTFS volume and displays the content on the standard output.

The case of the filename passed to NTFSCAT is ignored.

Below is a summary of all the options that NTFSCAT accepts. Nearly all options have two equivalent names. The short name is preceded by - and the long name is preceded by --. Any single letter options, that don’t take an argument, can be combined into a single command, e.g. -fv is equivalent to -f -v. Long named options can be abbreviated to any unique prefix of their name.

{| class="wikitable"
|- style="vertical-align:top;"
| -a <type> or --attribute <type> || Display the contents of a particular attribute type. By default, the unnamed $DATA attribute will be shown. The attribute can be specified by a number in decimal or hexadecimal, or by name.
{| class="wikitable"
! Hex !! Decimal !! Name
|-
| 0x10 || 16 || "$STANDARD_INFORMATION"
|-
| 0x20 || 32 || "$ATTRIBUTE_LIST"
|-
| 0x30 || 48 || "$FILE_NAME"
|-
| 0x40 || 64 || "$OBJECT_ID"
|-
| 0x50 || 80 || "$SECURITY_DESCRIPTOR"
|-
| 0x60 || 96 || "$VOLUME_NAME"
|-
| 0x70 || 112 || "$VOLUME_INFORMATION"
|-
| 0x80 || 128 || "$DATA"
|-
| 0x90 || 144 || "$INDEX_ROOT"
|-
| 0xA0 || 160 || "$INDEX_ALLOCATION"
|-
| 0xB0 || 176 || "$BITMAP"
|-
| 0xC0 || 192 || "$REPARSE_POINT"
|-
| 0xD0 || 208 || "$EA_INFORMATION"
|-
| 0xE0 || 224 || "$EA"
|-
| 0xF0 || 240 || "$PROPERTY_SET"
|-
| 0x100 || 256 || "$LOGGED_UTILITY_STREAM"
|}
{{Note|The attribute names may be given without the leading $ symbol. If you use the $ symbol, you must quote the name to prevent the shell interpreting the name.}}
|-
| -n <name> or --attribute-name <name> || Display this named attribute, stream.
|-
| -i <number> or --inode <number> || Specify a file by its inode number <number> instead of its name.
|-
| -f or --force || This will override some sensible defaults, such as not using a mounted volume. Use this option with caution.
|-
| -h or --help || Show a list of options with a brief description of each one.
|-
| -q or --quiet || Suppress some debug/warning/error messages.
|-
| -V or --version || Show the version number, copyright and license ntfscat.
|-
| -v or --verbose || Display more debug/warning/error messages.
|}

; Example 1:
Display the contents of a file in the root of an NTFS volume.

1> ntfscat /dev/hda1 boot.ini

; Example 2:
Display the contents of a file in a subdirectory of an NTFS volume.

1> ntfscat /dev/hda1 /winnt/system32/drivers/etc/hosts

; Example 3:
Display the contents of the $INDEX_ROOT attribute of the root directory (inode 5).

1> ntfscat /dev/hda1 -a INDEX_ROOT -i 5 | hexdump -C

== NTFSCK ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== NTFSCLUSTER ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== NTFSFIX ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== NTFSINFO ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== NTFSLABEL ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== NTFSLS ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== NTFSUNDELETE ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== NTFSWIPE ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

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

== NVSETVAR ==

Set the value of, create, or delete a named UBoot environment variable.

; Format
: NVSETVAR <name> <value>

; Template
: NAME/A,VALUE/F

; Location
: C:

NVSETVAR <name> <value> will set the value of the UBoot environment variable <name>. If <name> exists and nothing is provided for the <value>, the variable <name> will be deleted. If <name> does not exist and something is provided for the <value>, a new variable <name> with a value <value> will be created.

If the variable <name> is not provided, or does not exist and no <value> is provided, NVSETVAR will print nothing, and set the condition flag to 5 (WARN).

; Example:
1> NVSETVAR boot_config "AmigaOS 4.1 FE"

Sets the value of the boot_config variable to "AmigaOS 4.1 FE".

== OPENSSL ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== 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:

Each file or directory bears information which describes who owns it. This information can be displayed by the [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LIST|LIST]] command. The ownership of a file or a directory is important when the file or directory is made accessible through a networked file system.

The OWNER command will change the ownership of one or more files or directories. The "owner" must be given either as a name or a number. The file system needs to understand the given name. If not, you will see an error message. If you know which numeric owner ID should be used in place of a name, you can provide this instead. Note that owner names cannot be longer than 31 characters and that numeric owner IDs must be in the range of 0 to 65535. An empty name given for the owner will remove the ownership information.

The options are:
{| class="wikitable"
| ALL || If the ALL option is given, OWNER will change the ownership of 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.
|}

; Example 1:
1> OWNER textfile admin
Assigns the ownership of "textfile" to the user "admin".

; Example 2:
1> OWNER textfile ""
Removes any ownership information from "textfile".

== 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ASSIGN|ASSIGN]]

== 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:

PATHPART can break down directory and file names into their respective directory and file name components, and is also able to (re-) assemble the individual names into combined path names again. This can be of great use in script files.

; Example 1:
Obtain the directory name component of a path name:
1> PATHPART DIR Work:Files/Data
Work:Files

; Example 2:
Obtain the file name component of a path name:
1> PATHPART FILE Work:Files/Data
Data

; Example 3:
Build a complete path name from components:
1> PATHPART ADD Work: Files Data
Work:Files/Data

; Example 4:
Remove the last part of a path name, then replace it with a new name:
1> PATHPART ADD `PATHPART DIR Work:Files/Data` Information
Work:Files/Information

== PETUNE ==

Changes the debug options of the Motorola 68040 CPU emulation.

; Format
: ?

; Template
: GLOBALDEBUGLEVEL=GDL/K/N,DEBUGLEVEL=DL/K/N,DEBUGOFFSET=DO/K,INSTSTATS/K,EMULATOR=EMU/K,SEGMENTLIST=SL/S

; Location
: C:

Missing description.

== 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:

OBS! Missing description.

== PIPE ==

Connects input and output streams of Shell commands.

; Format
: PIPE <command>

; Template
: COMMAND/A/F

; Location
: Internal

The PIPE command is used by the shell to connect the input and output streams of shell commands. It is not useful beyond that point and should not be used by user shell scripts.

'''Warning'''

The PIPE command may be removed in a future shell version.

== POOLSTAT ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== POPCD ==

Returns the directory last recently saved with the PUSHCD command.

; Format
: POPCD

; Template
: (none)

; Location
: Internal

POPCD is the counterpart to the PUSHCD command. It will recall the directory least recently saved by PUSHCD and return to it. If no directory can be popped from the stack, PUSHCD will return to the SYS: directory instead.

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#CD|CD]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#PUSHCD|PUSHCD]]

== 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:

{| class="wikitable"
| %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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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:
{| 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.
|-
| 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:
{| class="wikitable"
| 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LIST|LIST]]

== PUSHCD ==

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

; Format
: PUSHCD [<dir | pattern>]

; Template
: DIR

; Location
: Internal

PUSHCD saves the current directory on a stack. If an optional directory name or pattern is provided, the current directory will be saved first and then changed. The PUSHCD command can be undone with the POPCD command.

Up to 100 directories can be pushed onto the stack.

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#CD|CD]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#POPCD|POPCD]]

== PYTHON ==

Launches a Python program.

; Format
: PYTHON [<option>] ... [-c <command> | -m <module> | <file> | <stdin>] [<arguments to program>]

; Template
: -c,-d,-E,-h,-i,-m,-O,-OO,-Q,-S,-t,-u,-v,-V,-W,-x,file,args

; Location
: C:

OBS! Missing description.

== 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:
<syntaxhighlight lang="text">
ASK "Do you want to stop now?"
IF WARN
QUIT 5
ENDIF
ECHO "OK"
ECHO "The script is continuing."
</syntaxhighlight>

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:

REBOOT will reboot the Amiga system. You can either reboot the machine completely or only the operating system. If you do not use the FAST (WARMREBOOT) argument, your Amiga will be restarted completely.

REBOOT has the same effect as if you turned your Amiga off and on again. If you specify the FAST argument, only AmigaOS will be restarted which will boot AmigaOS again with the same [[AmigaOS_Manual:_AmigaDOS_Glossary#KERNEL MODULE|kernel modules]].

With the WAIT argument, the reboot can be delayed for a specified number of seconds.

With the SYNC argument, REBOOT will try to inhibit all partitions in order to reboot more safely (with no current disk operations).

; Example 1:
To reboot only the operating system after 2 seconds delay:
1> Reboot FAST WAIT 2

; Example 2:
To reboot completely after all disk operations are finished:
1> Reboot SYNC

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

OBS! Missing description.

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

;Example 1:
1> RELABEL Workbench: MyDisk

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

;Example 2:
1> RELABEL DF2: DataDisk

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

== RELOADAPPLIST ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== REMOVENETINTERFACE ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== 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: [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 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.

[[File:DosFig6-1.png|center|frame|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

[[File:DosFig6-2.png|center|frame|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: [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 ==

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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#PROTECT|PROTECT]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LIST|LIST]]

== 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:

OBS! Missing description.

== 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 [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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:

{| 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 ==

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

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

== SAMPLENETSPEED ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== 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:
{| class="wikitable"
| 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.

;Example:
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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#GET|GET]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#UNSET|UNSET]]

== 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#DATE|DATE]]

== 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:
{| 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:
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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#DATE|DATE]]

== SETDOSDEBUG ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== 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
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#GETENV|GETENV]]
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#UNSETENV|UNSETENV]]

== 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 [[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.

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"
| 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:

{| class="wikitable"
|-
| 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.
|}

; 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

== SHOW68LOADS ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== SHOWAPPLIST ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== 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
: 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:

Missing description.

== SKIP ==

Skips to a label when executing script files.

; Format
: SKIP [<label>] [BACK]

; Template
: LABEL,BACK/S

; Location
: Internal

SKIP is used in scripts to allow you to skip ahead in the script to a <label> defined by a LAB statement. If no <label> is specified, SKIP jumps to the next LAB statement.

SKIP always searches forward from the current line of the file. However, when the BACK option is used, SKIP starts searching for the label from the beginning of the file. This allows SKIPs to points prior to the SKIP command.

You can only SKIP as far back as the last EXECUTE statement. If there are no EXECUTE statements in a script, you SKIP back to the beginning of the file.

If SKIP does not find the label specified, the command sequence terminates and the message Label <label> not found by Skip is displayed.

; Example:
Assume you have the following script, called CheckFile:
<syntaxhighlight lang="text">
.KEY name
IF exists <name>
SKIP message
ELSE
ECHO "<name> is not in this directory."
QUIT
ENDIF
LAB message
ECHO "The <name> file exists."
</syntaxhighlight>

You can run the script by entering:

1> EXECUTE CheckFile Document

If the Document file exists in the current directory, the execution of the script SKIPs ahead to the LAB command. The message:

The Document file exists.

Is displayed in the Shell window.

If the Document file is not in the current directory, the execution of the script jumps to the line after the ELSE statement, displaying the message:

Document is not in this directory.

;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:

OBS! Missing description.

== SORT ==

Alphabetically sorts the lines of a file.

; Format
: SORT [FROM] <file | pattern> [TO] <filename> [COLSTART <n>] [CASE] [NUMERIC]

; Template
: FROM/A,TO/A,COLSTART/K,CASE/S,NUMERIC/S

; Location
: C:

SORT sorts the FROM file alphabetically, line-by-line, sending the sorted results to the TO file. SORT assumes the file is a normal text file in which lines are separated by line feeds. SORT normally disregards case. If the CASE switch is given, upper-cased items are output first.

The COLSTART keyword specifies the character column at which the comparison begins. SORT starts comparing the lines from that point, wrapping around to the beginning of the line if the compared lines match to the end.

When the NUMERIC option is specified, the lines are interpreted as numbers from the first column reading to the right, stopping at the first non-numeric character. Lines not beginning with numbers are treated as 0. The lines are output in numerical order. CASE is ignored when NUMERIC is specified.

; Example:
1> SORT DF0:Glossary TO DF0:Glossary.alpha

sorts the lines in the Glossary file, arranges them alphabetically, and outputs them to a next file called Glossary.alpha. The case of the words is disregarded.

For more examples using the SORT command, see [[AmigaOS_Manual:_AmigaDOS_Command_Examples|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:

OBS! Missing description.

== STACK ==

Displays or sets the stack size within the current Shell.

; Format
: STACK [[SIZE] <stack size>]

; Template
: SIZE/N

; Location
: Internal

A Shell uses a certain amount of stack, a special area in memory allocated for it. Each Shell has a specific stack size. If a program causes a system failure, changing the Shell's stack size may solve the problem. Commands performing operations consisting of multiple levels can require additional stack space.

Stack sizes typically range from 4096 to 40000 bytes. If the stack size is too small, a system failure can occur. If the stack size is too large, it can use too much memory.

{{Note|A software failure message is displayed if you run out of stack space. Increase the stack space for the Shell that caused the error.}}

Entering the STACK command with no arguments displays the current stack size.

== STATUS ==

Lists information about Shell processes.

; Format
: STATUS [<process>] [FULL] [TCB] [CLI | ALL] [COM | COMMAND <command>]

; Template
: PROCESS/N,FULL/S,TCB/S,CLI=ALL/S,COM=COMMAND/K

; Location
: C:

STATUS without any arguments lists the numbers of the current Shell processes and the program or command running in each. The <process> argument specifies a process number, limiting STATUS to giving information about that process only.

For information on the stack size, global vector size, priority, and the current command for each process, use the FULL keyword. The TCB keyword is similar, omitting the command information. The CLI=ALL keyword gives only the command information.

STATUS searches for a command when you use the COMMAND option. STATUS scans the Shell list, looking for the specified <command>. If the command is found, the Shell's process number is output, and the condition flag is set to 0. Otherwise, the flag is set to 5 (WARN).

; Example 1:
1> STATUS 1
Process 1: Loaded as command: status

; Example 2:
1> STATUS 1 FULL
Process 1: stk 4000, gv 150, pri 0 Loaded as command: status

; Example 3:
1> STATUS >RAM:Xyz COMMAND=COPY
1> BREAK <RAM:Xyz >NIL: ?

sends a break to the process executing COPY.

== SWAPCD ==

Interchanges the current directory and a stacked directory.

; Format
: SWAPCD [<dir | pattern>] [LEVEL <number>]

; Template
: DIR,LEVEL/N

; Location
: Internal

OBS! Missing description.

== TCC ==

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

Opens the ARexx tracing console window.

; 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

[[File:DosFig6-4.png|center|frame|Sample ARexx tracing console]]

== TCPDUMP ==

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:

OBS! Missing description.

== TE ==

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

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

The TEE command will read data from its standard input and send it to its standard output, but additionally it will also send a copy of the data to the console. This allows for pipe commands to be monitored.

By default the TEE command reads data in chunks of 512 bytes each, which can be changed with the SIZE parameter; it controls how many bytes will be read apiece. Alternatively, you can tell the TEE command to read the input line by line. The LINE parameter activates this mode of operation.

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#PIPE|PIPE]]

== TRACEROUTE ==

Prints the route packets take to network host.

; 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:

The Internet is a large and complex aggregation of network hardware, connected together by gateways. Tracking the route one's packets follow (or finding the miscreant gateway that's discarding your packets) can be difficult. TRACEROUTE utilizes the IP protocol `time to live' field and attempts to elicit an ICMP TIME_EXCEEDED response from each gateway along the path to some host.

The only mandatory parameter is the destination host name or IP number. The default probe datagram length is 38 bytes, but this may be increased by specifying a packet size (in bytes) after the destination host name.

TRACEROUTE options are:
{| class="wikitable"
| -m, MAXTTL || Set the max time-to-live (max number of hops) used in outgoing probe packets. The default is 30 hops (the same default used for TCP connections).
|-
| -n, NUMERIC || Print hop addresses numerically rather than symbolically and numerically (saves a nameserver address-to-name lookup for each gateway found on the path).
|-
| -p, PORT || Set the base UDP port number used in probes (default is 33434). TRACEROUTE hopes that nothing is listening on UDP ports base to base+nhops-1 at the destination host (so an ICMP PORT_UNREACHABLE message will be returned to terminate the route tracing). If something is listening on a port in the default range, this option can be used to pick an unused port range.
|-
| -q, QUERIES || Set the number of probes per ``ttl'' (default is three probes).
|-
| -r, DONTROUTE || Bypass the normal routing tables and send directly to a host on an attached network. If the host is not on a directly-attached network, an error is returned. This option can be used to ping a local host through an interface that has no route through it.
|-
| -s, SOURCE || Use the following IP address (which must be given as an IP number, not a hostname) as the source address in outgoing probe packets. On hosts with more than one IP address, this option can be used to force the source address to be something other than the IP address of the interface the probe packet is sent on. If the IP address is not one of this machine's interface addresses, an error is returned and nothing is sent.
|-
| -t, TOS || Set the type-of-service in probe packets to the following value (default zero). The value must be a decimal integer in the range 0 to 255. This option can be used to see if different types-of-service result in different paths. Not all values of TOS are legal or meaningful - see the IP spec for definitions. Useful values are probably `-t 16' (low delay) and `-t 8' (high throughput).
|-
| -v, VERBOSE || Verbose output. Received ICMP packets other than TIME_EXCEEDED and UNREACHABLEs are listed.
|-
| -w, WAIT || Set the time (in seconds) to wait for a response to a probe (default 3 sec.).
|}

TRACEROUTE attempts to trace the route an IP packet would follow to some internet host by launching UDP probe packets with a small ttl (time to live) then listening for an ICMP "time exceeded" reply from a gateway. We start our probes with a ttl of one and increase by one until we get an ICMP "port unreachable" (which means we got to "host") or hit a max (which defaults to 30 hops & can be changed with the -m flag). Three probes (changed with -q flag) are sent at each ttl setting and a line is printed showing the ttl, address of the gateway and round trip time of each probe. If the probe answers come from different gateways, the address of each responding system will be printed. If there is no response within a 3 sec. timeout interval (changed with the -w flag), a "*" is printed for that probe.

We don't want the destination host to process the UDP probe packets so the destination port is set to an unlikely value (if some clod on the destination is using that value, it can be changed with the -p flag).

A sample use and output might be:

1> TRACEROUTE nis.nsf.net.
traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 56 byte packet
1 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms
2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms
3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms
4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms
5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms
6 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms
7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms
8 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms
9 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms
10 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms
11 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms

Note that lines 2 & 3 are the same. This is due to a buggy kernel on the 2nd hop system - lbl-csam.arpa - that forwards packets with a zero ttl (a bug in the distributed version of 4.3 BSD). Note that you have to guess what path the packets are taking cross-country since the NSFNet (129.140) doesn't supply address-to-name translations for its NSSes.

A more interesting example is:

1> TRACEROUTE allspice.lcs.mit.edu.
traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max
1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms
2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms
3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms
4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms
5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms
6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms
7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms
8 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms
9 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms
10 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms
11 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms
12 * * *
13 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms
14 * * *
15 * * *
16 * * *
17 * * *
18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms

Note that the gateways 12, 14, 15, 16 & 17 hops away either don't send ICMP "time exceeded" messages or send them with a ttl too small to reach us. 14 - 17 are running the MIT C Gateway code that doesn't send "time exceeded"s. God only knows what's going on with 12.

The silent gateway 12 in the above may be the result of a bug in the 4.[23] BSD network code (and its derivatives): 4.x (x <= 3) sends an unreachable message using whatever ttl remains in the original datagram. Since, for gateways, the remaining ttl is zero, the ICMP "time exceeded" is guaranteed to not make it back to us. The behavior of this bug is slightly more interesting when it appears on the destination system:

1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms
2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms
3 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms
4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms
5 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms
6 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms
7 * * *
8 * * *
9 * * *
10 * * *
11 * * *
12 * * *
13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms !

Notice that there are 12 "gateways" (13 is the final destination) and exactly the last half of them are "missing". What's really happening is that rip (a Sun-3 running Sun OS3.5) is using the ttl from our arriving datagram as the ttl in its ICMP reply. So, the reply will time out on the return path (with no notice sent to anyone since ICMP's aren't sent for ICMP's) until we probe with a ttl that's at least twice the path length. I.e., rip is really only 7 hops away. A reply that returns with a ttl of 1 is a clue this problem exists. TRACEROUTE prints a "!" after the time if the ttl is <= 1. Since vendors ship a lot of obsolete (DEC's Ultrix, Sun 3.x) or non-standard (HPUX) software, expect to see this problem frequently and/or take care picking the target host of your probes. Other possible annotations after the time are !H, !N, !P (got a host, network or protocol unreachable, respectively), !S or !F (source route failed or fragmentation needed - neither of these should ever occur and the associated gateway is busted if you see one). If almost all the probes result in some kind of unreachable, TRACEROUTE will give up and exit.

This program is intended for use in network testing, measurement and management. It should be used primarily for manual fault isolation. Because of the load it could impose on the network, it is unwise to use TRACEROUTE during normal operations or from automated scripts.

== TS ==

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

Displays a text file.

; Format
: TYPE {<file|pattern>} [TO <name>] [OPT H|N] [HEX] [NUMBER]
: [AUTO] [TEXTONLY] [WIDTH <line width>] [BUF|BUFFER=<n>]

; Template
: 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
: C:

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

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.

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.

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

The contents of the User-Startup file in the S: directory will be displayed on the screen.

== UNALIAS ==

Removes an alias.

; Format
: UNALIAS [<name>]

; Template
: NAME

; Location
: Internal

UNALIAS removes the named alias from the alias list. With no arguments, UNALIAS lists the current aliases.

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ALIAS|ALIAS]]

== UNSET ==

Removes a local variable.

; Format
: UNSET [<name>]

; Template
: NAME

; Location
: Internal

UNSET removes the named local variable from the variable list for the current process. With no arguments, UNSET lists the current variables.

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SET|SET]]

== UNSETENV ==

Removes a global variable.

; Format
: UNSETENV [<name>]

; Template
: NAME

; Location
: Internal

UNSETENV removes the named global variable from the current variable list. With no arguments, UNSETENV lists the current variables.

;See also
* [[AmigaOS_Manual:_AmigaDOS_Command_Reference#SETENV|SETENV]]

== UPTIME ==

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)

== URLOPEN ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== USBCTRL ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== VERSION ==

Finds software version and revision numbers.

; Format
: VERSION [<library | device | file>] [<version #>] [<revision #>]
: [FILE] [FULL] [<unit #>] [INTERNAL] [RES] [VSTRING]

; Template
: NAME,VERSION/N,REVISION/N,FILE/S,FULL/S,UNIT/N,INTERNAL/S,RES/S,VSTRING/S

; Location
: C:

VERSION finds the version and revision number of a library, device, command, or Workbench disk. VERSION can also test for a specific version/revision and set the condition flags if the version/revision is greater. This is useful in scripts.

VERSION with no <library | device | file> argument prints the [[AmigaOS_Manual:_AmigaDOS_Glossary#KICKSTART|Kickstart]] version number and the [[AmigaOS_Manual:_AmigaDOS_Glossary#WORKBENCH|Workbench]] version number and sets the environment variables. If a name is specified, version attempts to open the library, device, drive, or file and read the version information.

When a <version #> (and possibly a <revision #>) is specified, VERSION sets the condition flag to 0 if the version (and revision) number of the Kickstart, library, or device driver is greater than or equal to the specified values. Otherwise, the flag is set to 5 (WARN). (If a revision number is not specified, no comparison on the revision number is performed.)

The <unit #> option allows you to specify a unit number other than 0. This may be necessary for accessing multi-unit devices.

The NAME may be a wildcard pattern, in which case VERSION will examine all files matching the pattern. If a version number is given, scanning will stop as soon as a file is found whose version number is smaller than the one specified.

By default, only the name and the version number are printed. Further information might be available, such as the last modification time. To print it as well, use the FULL option.

The FILE option makes the VERSION command ignore libraries and commands already loaded and specifically checks the named file instead (this is also the case if you use wildcard patterns with the NAME parameter).

The VSTRING keyword requires a NAME parameter that is not a wildcard pattern. If version information can be found for the named object, it will be printed in the standard format; if no such information is available, an empty line will be printed instead. This feature is useful for script files.

The INTERNAL and RES options are obsolete and are retained solely for the purpose of backwards compatibility with existing script files. Their original purpose was to restrict the search for commands to the internal shell command list or the list of currently resident commands.

; Example 1:
1> VERSION
Kickstart 53.70 Workbench 53.16

; Example 2:
1> VERSION SYS:Prefs/Font
Font 53.6

; Example 3:
1> VERSION C:Version VSTRING
$VER: Version 53.10 (7.12.2016)

== WAIT ==

Waits for the specified time.

; Format
: WAIT [<n>] [SEC | SECS |MIN | MINS] [UNTIL <time>]

; Template
: /N,SEC=SECS/S,MIN=MINS/S,UNTIL/K

; Location
: C:

WAIT is used in command sequences or after RUN to wait for a certain period of time or until a specific time. The default waiting period is one second.

The <n> argument specifies the number of seconds or minutes to wait. These options are mutually exclusive; you can only enter seconds or minutes.

Use the keyword UNTIL to wait until a particular time of the day, given in the format HH:MM.

; Example 1:
1> WAIT 10 MINS

waits ten minutes.

; Example 2:
1> WAIT UNTIL 21:15

waits until 9:15 p.m.

== WAITFORPORT ==

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

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

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:

WBRUN will execute the program specified in argument, just like it would be if started from the WorkBench. So it will be exactly like if you double-clicked the program icon. It means that the processed program will be able to process WB messages.

When you run a program on the WorkBench, you can make it handle other icons you have selected. You can do the same with WBRUN, passing the filenames as arguments.

When used with a volume/directory name, WBRUN will open a volume/drawer window and display its content according to the SHOW and VIEWBY arguments.

SHOW allows you to open a WB window displaying there only icons (default) if "ICONS" is defined, or all files i.e. even files with no icon, if "ALL" is defined.

The VIEWBY argument allows you to define layout of the WB window that will be opened: either displaying ICON, or in list mode sorted by NAME, or sorted by DATE, or by size SIZE or by TYPE.

Also, you can define a DELAY (in seconds) WBRUN will wait before executing the program in argument.

If you don't want the executed program to open a console window for any output it may produce, specify the NOREQ argument.

; Example 1:
Running a picture viewer with some images as arguments

1> WBRUN Work:picviewer Image1.iff Image2.png

; Example 2:
Opening the SYS: drawer in list mode with all files

1> WBRUN Sys: SHOW=all VIEWBY=name

== WBSTARTUPCTRL ==

Manipulates the startup configuration of Workbench.

; Format
: WBSTARTUPCTRL [PATH=<prefs file>] [ADD=<program>] [REMOVE=<program>] [QUIET]

; Template
: PATH/K,ADD/K,REMOVE/K,QUIET

; Location
: C:

WBSTARTUPCTRL allows manipulation of the configured startup modules that Workbench will load without having to open the WBStartup preferences editor.

The parameters that can be specified are as follows:
{| class="wikitable"
| PATH || This creates the updated preferences file at the location specified. This should be a path AND filename to save the file as. By default, it will use SYS:Prefs/Env-Archive/Sys/wbstartup.prefs.
|-
| ADD || This command will add the specified program to the internal list of modules that are executed when Workbench starts. This must be the full path to the program to add. If the file can not be found, an error message will be displayed.
|-
| REMOVE || This command removes the specified program from the internal list. The argument may contain the full path to the program to be removed, or if the path is not known, just the program name may be supplied and the list will be searched for a suitable match.
|-
| QUIET || Turn off any messages that may be output to the console.
|}

The use of the above parameters has been designed to allow installers or scripts to add or remove files from the configuration easily. Usually, when an installer has copied a program and its data, it will know the path that it has been copied to, and a simple call of this command with the correct arguments will add it to Workbench's list of programs to start.

Because the path may not be known when trying to remove a program from the list, the matching feature has been included. An addition or a removal will show a message to the standard output, which may be suppressed by using the QUIET switch.

; Example 1:
Under script control, the ContextMenus commodity may be added with a call like so:

1> WBSTARTUPCTRL ADD SYS:Utilities/Commodities/ContextMenus

This program will now be launched each time Workbench starts.

; Example 2:
A script may want to remove a program whose location is not known, like so:

1> WBSTARTUPCTRL REMOVE MouseBlanker

The first entry in the list that matches will be removed.

== WHICH ==

Searches the command path for a particular item.

; Format
: WHICH <command> [NORES] [RES] [ALL]

; Template
: FILE/A,NORES/S,RES/S,ALL/S

; Location
: C:

WHICH lets you find a specific command, program, or directory by entering its name. If the named item is in the search path, WHICH displays the complete path to that item. WHICH lists resident commands as RESIDENT and internal commands as INTERNAL.

Normally, WHICH searches the resident list, the current directory, the command paths, and the C: directory. If the item is not found, WHICH sets the condition flag to 5 (WARN), but does not print any error message.

If the NORES option is specified, the resident list is not searched. If the RES option is specified, only the resident list is searched.

The ALL switch continues the search through the full search path, finding and listing all locations of a command or program. It can, however, lead to multiple listings of the same command if that command is reached by more than one route (such as C: and the current directory).

; Examples:
1> WHICH avail
C:Avail

1> WHICH C:
Workbench:C

1> WHICH alias
INTERNAL alias

== WHY ==

Prints an error message explaining why the previous command failed.

; Format
: WHY

; Template
: (none)

; Location
: Internal

When a command fails, the screen displays a brief message. This message typically includes the name of the file, if that was the problem, but provides no details. If the reason for a failure is not evident, enter WHY for a more complete explanation.

== XAD2LHA ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XADLIBINFO ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XADLIST ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XADUNDISK ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XADUNF ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XADUNFILE ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XADUNFILEM ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XADUNTAR ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XBENCH ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XDIR ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XLOADSEG ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XPACK ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XPK ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XQUERY ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XSCAN ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XTYPE ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

== XUP ==

?

; Format
: ?

; Template
: ?

; Location
: C:

Missing description.

= System Commands =

System commands are required for normal system operation. They are used by the standard Startup-sequence or called automatically by the system for applications. The user does not typically invoke these commands.

== ADDDATATYPES ==

Makes new datatypes available to the system.

; Format
: ADDDATATYPES [<datatype> [<datatype>...]] [QUIET] [REFRESH] [LIST]

; Template
: FILES/M,QUIET/S,REFRESH/S,LIST/S

; Location
: C:

ADDDATATYPES can load datatype descriptors in memory. When they are loaded, applications can use them immediately.

ADDDATATYPES can also be loaded from Workbench which allows using it as default tool in an icon of a datatype descriptor file in DEVS:DataTypes/ or SYS:Storage/DataTypes/.

If the QUIET argument is used, or the local shell variable _Verbosity has a negative value, ADDDATATYPES will not display potential errors.

If the REFRESH argument is used, any newly added datatype will be added to the datatype list in memory. It has the same effect as defining all datatype names in the command line.

If the LIST argument is used, ADDDATATYPES will display the list of all datatypes in memory.

; Example
Add two newly added datatypes to the datatype list:

1> ADDDATATYPES iff jpeg

== BINDDRIVERS ==

Binds device drivers to hardware.

; Format
: BINDDRIVERS

; Template
: (none)

; Location
: C:

BINDDRIVERS loads and runs device drivers for add-on hardware. These devices are automatically configured by the expansion library if their device drivers are in the SYS:Expansion directory.

The BINDDRIVERS command must appear in the Startup-sequence file to configure the hardware when the system is booted.

== CONCLIP ==

Enables or disables cut/copy/paste functionality in console windows and string gadgets

; Format
: CONCLIP [[UNIT|CLIPUNIT] <unit number>] [ON|OFF]

; Template
: CLIPUNIT=UNIT/N,ON/S,OFF/S

; Location
: C:

Copy and paste operations in console windows will use the console's own private clipboard. While text can be exchanged between console windows, no other applications can access it. CONCLIP changes this by switching the console over to use the regular, system-wide clipboard functionality. Also, cut/copy/paste operations in string gadgets can be switched over to use the system-wide clipboard.

The options are:
{| class="wikitable"
| CLIPUNIT=<unit number> || Switch the clipboard unit number to use; default is 0.
|-
| ON and OFF || Turn the clipboard functionality either on or off.
|}

== IPREFS ==

Communicates Preferences information stored in the individual editor files to the operating system.

; Format
: IPREFS [NEWMOUSE]

; Template
: NEWMOUSE/S

; Location
: C:

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

Makes ROM patches in system software.

; Format
: SETPATCH [QUIET] [NOAGA] [NONSD] [PATCHCONFIGFILE=<NSDpatch file>]
: [PATCHCONFIGLINE="PatchLine"] [PATCHINFO] [WAITFORVALIDATE]
: [ADDCHIPRAM=<Size in MB>]

; Template
: QUIET/S,NOAGA/S,NONSD/S,PATCHCONFIGFILE=PCF/K,PATCHCONFIGLINE=PCL/K,PATCHINFO=PI/S,WAITFORVALIDATE/S,ADDCHIPRAM/N/K

; Location
: C:

SETPATCH installs temporary modifications to the operating system. It must be executed at the beginning of the Startup-sequence file.

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:

Adds a MemHeader with 2MB Chip RAM as backwards compatibility hack for broken applications and suppresses the normal output.

1> SETPATCH QUIET ADDCHIPRAM=2

AmigaOS Manual: AmigaDOS Command Examples

2019-01-15T10:08:29Z

Rob Cranley: /* Recursive AmigaDOS Command Scripts */ Fix typo that would prevent example script from working (Z: -> T:)

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

The chapter is organized as follows:

* Basic tasks
* Occasional tasks
* Advanced tasks

= Basic Tasks =

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

== Opening a Shell Window ==

To open a Shell window from Workbench:

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

OR

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

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

1> NEWSHELL

== Running Programs from the Shell ==

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

1> CLOCK

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

1> Tempus:Fugit/Utils/SuperClock

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

1> Utils/SuperClock

== Stopping a Program ==

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

To stop a command or program that is currently running:

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

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

To stop a script that is currently running:

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

== Changing the Current Directory ==

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

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

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

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

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

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

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

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

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

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

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

1> CD
Workbench:

== Changing the Search Path ==

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

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

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

1> ASSIGN C: SYS:MyCommands ADD

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

1> ASSIGN C: DF0: C PATH

== Displaying the Contents of a Directory ==

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

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

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

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

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

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

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

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

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

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

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

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

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

1> LIST ALL

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

TOTAL: 113 files - 762 blocks used

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

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

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

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

To combine the CD and DIR commands:

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

.KEY dirpath
CD <dirpath>
DIR

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

== Copying Files and Directories ==

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

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

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

To copy the file omitting optional keywords:

1> COPY DF0: Pix/Fractal3 Work:Pictures

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

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

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

1> COPY DF0:Pix TO Work:Pictures

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

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

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

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

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

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

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

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

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

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

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

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

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

== Creating a User-startup File ==

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

To create a User-startup file:

1> RUN ED S:User-startup

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

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

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

== Creating an Assignment ==

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

[[File:DosFig8-1.png|center|frame|Command Sample System Requester]]

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

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

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

1> ASSIGN ProFusion: Work:ProFusion

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

== Accessing the Expanded ED Menus ==

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

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

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

== Working with a Single Shell ==

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

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

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

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

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

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

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

You can now close the Shell window if necessary.

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

== Attaching Icons ==

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

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

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

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

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

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

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

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

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

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

== Creating Scripts Conveniently ==

To make creating and editing scripts easier:

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

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

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

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

= Occasional Tasks =

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

== Creating Aliases To Reduce Keystrokes ==

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

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

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

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

== Customizing NEWSHELL ==

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

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

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

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

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

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

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

== Modifying the Prompt ==

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

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

[[File:DosFig8-2.png|center|frame|Sample Uses of PROMPT Command]]

== Creating a Custom Ram Disk Icon ==

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

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

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

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

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

RELABEL RAM:ramname

== Deleting Files with Icons ==

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

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

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

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

== Testing Commands ==

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

To test a potentially destructive pattern matching command:

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

To test the effects of escape sequences:

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

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

Esc,c,Return

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

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

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

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

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

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

== Creating a Script to Move Files ==

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

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

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

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

Enter these commands in the ED window:

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

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

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

== Deleting with Interactive DIR ==

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

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

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

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

1> DIR Debris: INTER

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

== Generating Scripts with LIST LFORMAT ==

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

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

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

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

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

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

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

== Customizing LIST Output ==

You can also use LFORMAT to customize the output of LIST for special purposes. Save the line as an alias to make it easier to use in the future.

To create an alias for LIST that displays information only on files created since the date you enter, with the date first and protection bits and time omitted:

1> ALIAS lsince LIST FILES SINCE [] LFORMAT="%D%-25N %L"

If the current directory is S:, the output of lsince 01-sep-92 would be similar to this:

19-Oct-92 PCD 715
30-Nov-92 Startup-sequence 1360
Friday Shell-startup 671
Yesterday User-startup 609

== Using ICONX to Run Scripts ==

If you prefer to work with the mouse whenever possible or you are setting up an Amiga for a Workbench-only user, ICONX is useful. Using C:ICONX as the Default Tool of a project icon lets you run a script (or a command that lacks a Workbench interface) from the icon. It lets you start the script by opening the icon, as if the script were a standard Workbench tool.

There are also advantages to starting programs this way for the advanced user, including scripting preparatory steps (such as loading special Preferences presets) before launching a program and allowing the program's task priority to be changed easily. The following example demonstrates these techniques.

To start an application called OldApp from an ICONX icon, first loading a special Preferences font preset, and adjusting the application's task priority, create this script for the icon:

CD SYS:
Prefs/Font FROM SYS:Prefs/Presets/defscrn.pre USE
CHANGETASKPRI -1
OldApp

== Preventing Displayable Output From Scripts ==

In scripts, you often want to execute a command without the command displaying its usual Shell output. This can prevent an unnecessary series of messages or keep an output window from opening at an inopportune time.

To prevent all console output, redirect command output to a dummy destination with the >NIL: argument:

1> DELETE >NIL: T:Tempfile

The >NIL: argument prevents the printing of the message T:Tempfile Deleted , or any error messages.

To prevent console output except for error messages, use the QUIET option with those commands that support it:

1> DELETE T:Tempfile QUIET

The T:Tempfile Deleted message is not printed; however, if T:Tempfile does not exist, the No file to delete message appears.

== Entering and Testing ARexx Macros ==

To make entering and testing ARexx macros simpler:

Enter the following AmigaDOS script and save it as S:Edrx:

.KEY mac
ED REXX:<mac>.rexx
PROTECT S:<mac>.rexx +S-E
RX REXX:<mac>

Use this script when experimenting with ARexx macros. Enter Edrx followed bythe name of the macro. Edrx invokes the editor without you having to type in the .rexx extension and directly calls the ARexx interpreter RX with your macro as an argument when you exit.

== Sorting and Joining Files ==

If you regularly capture a list of new files each time you log on to a telecommunications service, you might want to add them to a list of existing files and sort all the entries by date. Each file name has the same prefix and a suffix that reflects the date, such as NewFiles.921009 for the list of files on October 9, 1992.

To create a single list of the files, sorted by date, use a pattern matching JOIN and SORT:

JOIN NewFiles.#? TO RAM.Temp.joined
SORT RAM:Temp.joined TO NewFiles.sorted
DELETE RAM:Temp.joined

= Advanced Tasks =

The following examples illustrate advanced tasks for users who are quite familiar with AmigaDOS.

== Testing Software Versions ==

You might need to control what a script does depending on which software version a user of the script has. It is easy to test for specific version numbers from a script.

To test whether a script is running on an Amiga with Release 4 level system software, preface the version-dependent portion of the script with a sequence similar to this:

VERSION >NIL: 50
IF WARN
ECHO "It's really time to update your system."
QUIT
ELSE
ECHO "You have Release 4 or better. Good!"
ECHO "Let's continue."
ENDIF

Versions below 50 are pre-Release 4. See [[AmigaOS_Versions|AmigaOS Versions]] for a complete list of release versions.

== Flushing Unused Fonts and Libraries ==

When fonts and libraries are loaded into memory, they remain in memory even if they are not currently in use. They are removed from memory automatically only when the memory they occupy is needed for some other purpose. In some cases it is useful to remove unneeded resources yourself.

For example, if you want to edit and then test a font or find the version number of a library on a new disk, the Amiga may appear not to see the new font or library. This is because AmigaDOS uses the font or library that is in memory whenever possible. You can flush unused resources from memory and decrease memory fragmentation by using the AVAIL command's FLUSH option.

To flush an unused font or library from memory without having to reboot the Amiga, enter:

1> AVAIL FLUSH

For this command to eliminate a font or library, the library or font must not be in use by the Workbench or some other application.

== AmigaDOS Loops Using EVAL ==

To create a loop in AmigaDOS that can prompt for the number of times to loop:

Enter the following script and save it as Aloop:

.KEY loop
; change bracket characters used for substitution
; since script uses < and > for redirection:
.BRA {
.KET }
; test whether user provided an argument
; for the number of loops, prompt if not:
IF NOT {loop}
ECHO "Please type in the number of loops"
ECHO "and press Return: " NOLINE
SETENV >NIL: loop{$$} ?
ELSE
; there was an argument, so store its value
ECHO >ENV:Loop{$$} {loop}
ENDIF
;
LAB start ; top of loop
ECHO "Loop #" NOLINE ; here, substitute the
TYPE ENV:Loop{$$} ; commands to repeat
EVAL <ENV:Loop{$$} >NIL: TO=T:Qwe{$$} VALUE2=1
OP=- ?
TYPE >ENV:Loop{$$} T:Qwe{$$}
IF VAL $loop{$$} GT 0
SKIP start BACK ;loop not finished yet
ENDIF
;
DELETE ENV:loop{$$} T:Qwe{$$} QUIET ; clean up
ECHO "Done"

If you invoke this script without providing a number as an argument, you are asked for input and this value is used as the initial loop number. If you do provide a number, as in:

1> EXECUTE Aloop 5

the following results are displayed:

Loop #5
Loop #4
Loop #3
Loop #2
Loop #1
Done

The only action inside the loop is to display the current loop count. However, you can insert more meaningful actions using the Loop{$$} environment variable.

The first IF block checks whether an argument was given when the script was invoked. If not, the script prompts for a value. In either case, the script stores the value in the ENV:Loop{$$} variable file. The {$$} operator appends the process number to the name Loop to create a unique file name to avoid potential conflicts while multitasking. For example, the file name in ENV: might be Loop4.

Within the loop, an ECHO command coupled with a TYPE command displays Loop # followed by the number given as the loop argument. The first time through the loop, it displays Loop #5 .

The EVAL command takes the number in the ENV:Loop{$$} file as <value1>, making the question mark at the end of the line necessary. <Value2> is 1 and the operation is subtraction. The output of the EVAL command is sent to the T:Qwe{$$} file. The next TYPE command sends the value in T:Qwe($$) to the ENV:Lopp{$$} file. The effect of these two lines is to subtract one from the value in ENV:Loop{$$}.

The IF statement instructs the script to start over as long as the value for Loop{$$} is greater than 0. This results in the Loop # line being printed again showing the new value.

The script continues until Loop{$$} is equal to 0. At the end of the script, the two temporary files are deleted.

== Using PIPE: ==

To get a listing of one device's contents to another process:

From process 1:

1> LIST Work: TO PIPE: ALL

From process 2:

2> TYPE pipe:

To gather the results of several C compilations:

1> sc >pipe:11 milk.c
1> sc >pipe:11 snap.c
1> sc >pipe:11 crackle.c
1> sc >pipe:11 pop.c
1> TYPE pipe:11

To use channel names:

1> LIST >pipe:crazy

This lists to a pipe called "crazy".

1> COPY #?.c TO >pipe:all_c/32000

This specifies a channel called "all_c" and a buffer size of 32000 bytes.

To set a limit on the number of buffers to 5:

1> DIR >pipe://5

This creates a channel without a channel name and allows only 5 buffers.

== Recursive AmigaDOS Command Scripts ==

To create a script that allows you to apply any AmigaDOS command to the contents of a directory, including all its subdirectories and their contents, enter this script and save it as S:RPAT:

.KEY COM/A,PATH,OPT,RD
;enter the command for COM, enter the path to the
;directory tree to process for PATH, if it is not
;the current directory, and enter an option for
;the command as OPT. You do not need to enter
;anything for RD.
;
.BRA {
.KET }
FAILAT 21 ; do not sdtop when List finds nothing
;
; first scan for files, then generate new script:
LIST >T:trf{$$} "{PATH}" FILES LFORMAT=" {COM} *"%p%n*" {OPT}"
IF EXISTS T:trf{$$}
; files were found, execute the new script and
; clean up
EXECUTE T:trf{$$}
DELETE T:trf{$$}
ENDIF
;
;list any subdirectories, call RPAT for each one:
LIST >T:trd{$$}{RD} "{PATH}" DIRS LFORMAT="RPAT *"{COM}*" *"%p%n*" *"{OPT}*" RD=.{RD}"
;the RD argument appends periods to the names of
;the temporary script files to distinguish each
;level
;
IF EXISTS T:trd{$$}{RD}
; subdirectories exist, execute new script
; file and clean up
EXECUTE T:trd{$$}{RD}
DELETE T:trd{$$}{RD}
ENDIF

Make sure the RPAT script has its a protection bit set and that RPAT is in the search path when you run it. Examine the S:SPAT and S:DPAT scripts that come with your system for examples of similar techniques.

GadTools Gadgets

2017-06-29T16:35:57Z

Rob Cranley: /* Slider Gadgets */ Fixed typo (possible Unicode copy/paste error).

=== Introduction ===

{{Note|text=GadTools-based GUIs are largely obsolete. Prefer to use a modern BOOPSI-based GUI system instead.}}

The heart of GadTools is in its ability to easily create and manipulate a sophisticated and varied array of gadgets. GadTools supports the following kinds of gadgets:

{| class="wikitable"
|+ Standard Gadget Types Supported by the GadTools Library
! Gadget Type
! Description or Example Usage
|-
| Button
| Familiar action gadgets, such as "OK" or "Cancel".
|-
| String
| For text entry.
|-
| Integer
| For numeric entry.
|-
| Checkboxes
| For on/off items.
|-
| Mutually exclusive
| Radio buttons, select one choice among several.
|-
| Cycle
| Multiple-choice, pick one of a small number of choices.
|-
| Sliders
| To indicate a level within a range.
|-
| Scrollers
| To indicate a position in a list or area.
|-
| Listviews
| Scrolling lists of text.
|-
| Palette
| Color selection.
|-
| Text-display
| Read-only text.
|-
| Numeric-display
| Read-only numbers.
|}

GadTools gadget handling consists of a body of routines to create, manage and delete any of the 12 kinds of standard gadgets listed in the previous table, such as buttons, sliders, mutually exclusive buttons and scrolling lists.

To illustrate the flexibility, power and simplicity that GadTools offers, consider the GadTools slider gadget. This gadget is used to indicate and control the level of something, for example volume, speed or color intensity. Without GadTools, applications have to deal directly with Intuition proportional and their arcane variables, such as HorizBody to control the slider knob's size and HorizPot to control the knob's position. Using the GadTools slider allows direct specification of the minimum and maximum levels of the slider, as well as its current level. For example, a color slider might have a minimum level of 0, a maximum level of 15 and a current level of 11.

To simplify event-processing for the slider, GadTools only sends the application a message when the knob has moved far enough to cause the slider level, as expressed in application terms, to change. If a user were to slowly drag the knob of this color slider all the way to the right, the program will only hear messages for levels 12, 13, 14 and 15, with an optional additional message when the user releases the mouse-button.

Changing the current level of the slider from within the program is as simple as specifying the new level in a function call. For instance, the application might set the slider's value to 5.

As a final point, the slider is very well-behaved. When the user releases the mouse-button, the slider immediately snaps to the centered position for the level. If a user sets their background color to light gray, which might have red = green = blue = 10, all three color sliders will have their knobs at precisely the same relative position, instead of anywhere in the range that means "ten".

==== The NewGadget Structure ====

For most gadgets, the NewGadget structure is used to specify its common attributes. Additional attributes that are unique to specific kinds of gadgets are specified as tags sent to the CreateGadget() function (described below).

The NewGadget structure is defined in <intuition/gadtools.h> as:

<syntaxhighlight>
struct NewGadget
{
WORD ng_LeftEdge, ng_TopEdge;
WORD ng_Width, ng_Height;
UBYTE *ng_GadgetText;
struct TextAttr *ng_TextAttr;
UWORD ng_GadgetID;
ULONG ng_Flags;
APTR ng_VisualInfo;
APTR ng_UserData;
};
</syntaxhighlight>

The fields of the NewGadget structure are used as follows:

; ng_LeftEdge, ng_TopEdge
: Define the position of the gadget being created.

; ng_Width, ng_Height
: Define the size of the gadget being created.

; ng_GadgetText
: Most gadgets have an associated label, which might be the text in a button or beside a checkmark. This field contains a pointer to the appropriate string. Note that only the pointer to the text is copied, the text itself is not. The string supplied must remain constant and valid for the life of the gadget.

; ng_TextAttr
: The application must specify a font to use for the label and any other text that may be associated with the gadget.

: Used to describe general aspects of the gadget, which includes where the label is to be placed and whether the label should be rendered in the highlight color. The label may be positioned on the left side, the right side, centered above, centered below or dead-center on the gadget. For most gadget kinds, the label is placed on the left side by default, exceptions will be noted.

; ng_GadgetID, ng_Flags, ng_UserData
: These user fields are copied into the resulting Gadget structure.

; ng_VisualInfo
: This field must contain a pointer to an instance of the VisualInfo structure, which contains information needed to create and render GadTools gadgets. The VisualInfo structure itself is private to GadTools and subject to change. Use the specialized GadTools functions for accessing the VisualInfo pointer, defined below. Never access or modify fields within this structure.

==== Creating Gadgets ====

The main call used to create a gadget with GadTools is CreateGadget(). This function can be used to create a single gadget or it can be called repeatedly to create a linked list of gadgets. It takes three arguments followed by a set of tags:

<syntaxhighlight>
struct Gadget *CreateGadget( ULONG kind, struct Gadget *prevgad, struct NewGadget *newgad,
struct TagItem *taglist);
struct Gadget *CreateGadgetA(ULONG kind, struct Gadget *prevgad, struct NewGadget *newgad,
Tag tag1, ...);
</syntaxhighlight>

Set the kind argument to one of the 12 gadget types supported by GadTools. Set the prevgad argument to the gadget address returned by CreateContext() if this is the first (or only) gadget in the list. Subsequent calls to CreateGadget() can be used to create and link gadgets together in a list in which case the prevgad argument is set to the address of the gadget returned by the preceding call to CreateGadget().

Set the newgad argument to the address of the NewGadget structure describing the gadget to be created and set any special attributes for this gadget type using the tag arguments, tag1 or taglist. For instance, the following code fragment might be used to create the color slider discussed earlier:

<syntaxhighlight>
slidergad = IGadTools->CreateGadget(SLIDER_KIND, newgadget, prevgad,
GTSL_Min, 0,
GTSL_Max, 15,
GTSL_Level, 11,
TAG_END);
</syntaxhighlight>

CreateGadget() typically allocates and initializes all the necessary Intuition structures, including in this case the Gadget, IntuiText and PropInfo structures, as well as certain buffers. For more about these underlying structures, see [[Intuition_Gadgets|Intuition Gadgets]].

Since CreateGadget() is a tag-based function, it is easy to add more tags to get a fancier gadget. For example, GadTools can optionally display the running level beside the slider. The caller must supply a printf()-style formatting string and the maximum length that the string will resolve to when the number is inserted:

<syntaxhighlight>
slidergad = IGadTools->CreateGadget(SLIDER_KIND, newgadget, prevgad,
GTSL_Min, 0,
GTSL_Max, 15,
GTSL_Level, 11,
GTSL_LevelFormat, "%2ld", /* printf()-style formatting string */
GTSL_MaxLevelLen, 2, /* maximum length of string */
TAG_END);
</syntaxhighlight>

The level, 0 to 15 in this example, would then be displayed beside the slider. The formatting string could instead be "%2ld/15" so the level would be displayed as "0/15" through "15/15".

==== Handling Gadget Messages ====

GadTools gadgets follow the same input model as other Intuition components. When the user operates a GadTools gadget, Intuition notifies the application about the input event by sending an IntuiMessage. The application can get these messages at the Window.UserPort. However GadTools gadgets use different message handling functions to get and reply these messages. Instead of the Exec functions GetMsg() and ReplyMsg(), applications should get and reply these messages through a pair of special GadTools functions, GT_GetIMsg() and GT_ReplyIMsg().

<syntaxhighlight>
struct IntuiMessage *GT_GetIMsg(struct MsgPort *iport);
VOID GT_ReplyIMsg(struct IntuiMessage *imsg);
</syntaxhighlight>

For GT_GetIMsg(), the iport argument should be set to the window's UserPort. For GT_ReplyIMsg(), the imsg argument should be set to a pointer to the IntuiMessage returned by GT_GetIMsg().

These functions ensure that the application only sees the gadget events that concern it and in a desirable form. For example, with a GadTools slider gadget, a message only gets through to the application when the slider's level actually changes and that level can be found in the IntuiMessage's Code field:

<syntaxhighlight>
imsg = IGadTools->GT_GetIMsg(win->UserPort);
object = imsg->IAddress;
class = imsg->Class;
code = imsg->Code;
IGadTools->GT_ReplyIMsg(imsg);
switch (class)
{
case IDCMP_MOUSEMOVE:
if (object == slidergad)
{
IDOS->Printf("Slider at level %ld\n", code);
}
...
break;
...
}
</syntaxhighlight>

In general, the IntuiMessages received from GadTools contain more information in the Code field than is found in regular Intuition gadget messages. Also, when dealing with GadTools a lot of messages (mostly IDCMP_MOUSEMOVEs) do not have to be processed by the application. These are two reasons why dealing with GadTools gadgets is much easier than dealing with regular Intuition gadgets. Unfortunately this processing cannot happen magically, so applications must use GT_GetIMsg() and GT_ReplyIMsg() where they would normally have used GetMsg() and ReplyMsg().

GT_GetIMsg() actually calls GetMsg() to remove a message from the specified window's UserPort. If the message pertains to a GadTools gadget then some dispatching code in GadTools will be called to process the message. What the program will receive from GT_GetIMsg() is actually a copy of the real IntuiMessage, possibly with some supplementary information from GadTools, such as the information typically found in the Code field.

The GT_ReplyIMsg() call will take care of cleaning up and replying to the real IntuiMessage.

{{Note|title=Warning|text=When an IDCMP_MOUSEMOVE message is received from a GadTools gadget, GadTools arranges to have the gadget's pointer in the IAddress field of the IntuiMessage. While this is extremely convenient, it is also untrue of messages from regular Intuition gadgets (described in [[Intuition_Gadgets|Intuition Gadgets]]). Do not make the mistake of assuming it to be true.}}

This description of the inner workings of GT_GetIMsg() and GT_ReplyIMsg() is provided for understanding only; it is crucial that the program make no assumptions or interpretations about the real IntuiMessage. Any such inferences are not likely to hold true in the future. See the section on documented side-effects for more information.

=== IDCMP Flags ===

The various GadTools gadget types require certain classes of IDCMP messages in order to work. Applications specify these IDCMP classes when the window is opened or later with ModifyIDCMP() (see [[Intuition_Windows|Intuition Windows]] for more on this). Each kind of GadTools gadget requires one or more of these IDCMP classes: IDCMP_GADGETUP, IDCMP_GADGETDOWN, IDCMP_MOUSEMOVE, IDCMP_MOUSEBUTTONS and IDCMP_INTUITICKS. As a convenience, the IDCMP classes required by each kind of gadget are defined in <libraries/gadtools.h>. For example, SLIDERIDCMP is defined to be:

<syntaxhighlight>
#define SLIDERIDCMP (IDCMP_GADGETUP | IDCMP_GADGETDOWN | IDCMP_MOUSEMOVE)
</syntaxhighlight>

{{Note|title=Always OR the IDCMP Flag Bits|text=When specifying the IDCMP classes for a window, never add the flags together, always OR the bits together. Since many of the GadTools IDCMP constants have multiple bits set, adding the values will not lead to the proper flag combination.}}

If a certain kind of GadTools gadget is used, the window must use all IDCMP classes required by that kind of gadget. Do not omit any that are given for that class, even if the application does require the message type.

Because of the way GadTools gadgets are implemented, programs that use them always require notification about window refresh events. Even if the application performs no rendering of its own, it may not use the WFLG_NOCAREREFRESH window flag and must always set IDCMP_REFRESHWINDOW. See the section on "Gadget Refresh Functions" below for more on this.

=== Freeing Gadgets ===

After closing the window, the gadgets allocated using CreateGadget() must be released. FreeGadgets() is a simple call that will free all the GadTools gadgets that it finds, beginning with the gadget whose pointer is passed as an argument.

<syntaxhighlight>
VOID FreeGadgets( struct Gadget *gad );
</syntaxhighlight>

The gad argument is a pointer to the first gadget to be freed. It is safe to call FreeGadgets() with a NULL gadget pointer, the function will then return immediately. Before calling FreeGadgets(), the application must first either remove the gadgets or close the window.

When the gadget passed to FreeGadgets() is the first gadget in a linked list, the function frees all the GadTools gadgets on the list without patching pointers or trying to maintain the integrity of the list. Any non-GadTools gadgets found on the list will not be freed, hence the result will not necessarily form a nice list since any intervening GadTools gadgets will be gone.

See the section on "Creating Gadget Lists" for more information on using linked lists of gadgets.

=== Simple GadTools Gadget Example ===

The example listed here shows how to use the NewGadget structure and the GadTools library functions discussed above to create a simple button gadget.

<syntaxhighlight>
/* simplegtgadget.c
Simple example of a GadTools gadget.
*/
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/gadgetclass.h>
#include <libraries/gadtools.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/gadtools.h>

/* Gadget defines of our choosing, to be used as GadgetID's. */
#define MYGAD_BUTTON (4)

VOID process_window_events(struct Window *);
VOID gadtoolsWindow(VOID);

struct TextAttr Topaz80 = { "topaz.font", 8, 0, 0, };

struct InuitionIFace *IIntuition;
struct GadToolsIFace *IGadTools;

/*
** Open all libraries and run. Clean up when finished or on error..
*/
int main()
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

struct Library *GadToolsBase = IExec->OpenLibrary("gadtools.library", 50);
IGadTools = (struct GadToolsIFace*)IExec->GetInterface(GadToolsBase, "main", 1, NULL);

if (IIntuition != NULL && IGadTools != NULL)
{
gadtoolsWindow();
}

IExec->DropInterface((struct Interface*)IGadTools);
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(GadToolsBase);
IExec->CloseLibrary(IntuitionBase);
return 0;
}

/*
** Prepare for using GadTools, set up gadgets and open window.
** Clean up and when done or on error.
*/
VOID gadtoolsWindow(VOID)
{
struct Screen *mysc;
struct Window *mywin;
struct Gadget *glist, *gad;
struct NewGadget ng;
void *vi;

glist = NULL;

if ( (mysc = IIntuition->LockPubScreen(NULL)) != NULL )
{
if ( (vi = IGadTools->GetVisualInfo(mysc, TAG_END)) != NULL )
{
/* GadTools gadgets require this step to be taken */
gad = IGadTools->CreateContext(&glist);

/* create a button gadget centered below the window title */
ng.ng_TextAttr = &Topaz80;
ng.ng_VisualInfo = vi;
ng.ng_LeftEdge = 150;
ng.ng_TopEdge = 20 + mysc->WBorTop + (mysc->Font->ta_YSize + 1);
ng.ng_Width = 100;
ng.ng_Height = 12;
ng.ng_GadgetText = "Click Here";
ng.ng_GadgetID = MYGAD_BUTTON;
ng.ng_Flags = 0;
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng, TAG_END);

if (gad != NULL)
{
if ( (mywin = IIntuition->OpenWindowTags(NULL,
WA_Title, "GadTools Gadget Demo",
WA_Gadgets, glist, WA_AutoAdjust, TRUE,
WA_Width, 400, WA_InnerHeight, 100,
WA_DragBar, TRUE, WA_DepthGadget, TRUE,
WA_Activate, TRUE, WA_CloseGadget, TRUE,
WA_IDCMP, IDCMP_CLOSEWINDOW |
IDCMP_REFRESHWINDOW | BUTTONIDCMP,
WA_PubScreen, mysc,
TAG_END)) != NULL )
{
IGadTools->GT_RefreshWindow(mywin, NULL);

process_window_events(mywin);

IIntuition->CloseWindow(mywin);
}
}
/* FreeGadgets() must be called after the context has been
** created. It does nothing if glist is NULL
*/
IGadTools->FreeGadgets(glist);
IGadTools->FreeVisualInfo(vi);
}
IIntuition->UnlockPubScreen(NULL, mysc);
}
}

/*
** Standard message handling loop with GadTools message handling functions
** used (GT_GetIMsg() and GT_ReplyIMsg()).
*/
VOID process_window_events(struct Window *mywin)
{
struct IntuiMessage *imsg;
struct Gadget *gad;
BOOL terminated = FALSE;

while (!terminated)
{
IExec->Wait (1 << mywin->UserPort->mp_SigBit);

/* Use GT_GetIMsg() and GT_ReplyIMsg() for handling */
/* IntuiMessages with GadTools gadgets. */
while ((!terminated) && (imsg = IGadTools->GT_GetIMsg(mywin->UserPort)))
{
/* GT_ReplyIMsg() at end of loop */

switch (imsg->Class)
{
case IDCMP_GADGETUP: /* Buttons only report GADGETUP */
gad = (struct Gadget *)imsg->IAddress;
if (gad->GadgetID == MYGAD_BUTTON)
IDOS->Printf("Button was pressed.\n");
break;
case IDCMP_CLOSEWINDOW:
terminated = TRUE;
break;
case IDCMP_REFRESHWINDOW:
/* This handling is REQUIRED with GadTools. */
IGadTools->GT_BeginRefresh(mywin);
IGadTools->GT_EndRefresh(mywin, TRUE);
break;
}
/* Use the toolkit message-replying function here... */
IGadTools->GT_ReplyIMsg(imsg);
}
}
}
</syntaxhighlight>

=== Modifying Gadgets ===

The attributes of a gadget are set up when the gadget is created. Some of these attributes can be changed later by using the GT_SetGadgetAttrs() function:

<syntaxhighlight>
VOID GT_SetGadgetAttrs (struct Gadget *gad, struct Window *win, struct Requester *req, Tag tag1, ... );
VOID GT_SetGadgetAttrsA(struct Gadget *gad, struct Window *win, struct Requester *req, struct TagItem *taglist);
</syntaxhighlight>

The gad argument specifies the gadget to be changed while the win argument specifies the window the gadget is in. Currently, the req argument is unused and must be set to NULL.

The gadget attributes are changed by passing tag arguments to these functions. The tag arguments can be either a set of TagItems on the stack for GT_SetGadgetAttrs(), or a pointer to an array of TagItems for GT_SetGadgetAttrsA(). The tag items specify the attributes that are to be changed for the gadget. Keep in mind though that not every gadget attribute can be modified this way.

For example, in the slider gadget presented earlier, the level-formatting string may not be changed after the gadget is created. However, the slider's level may be changed to 5 as follows:

<syntaxhighlight>
IGadTools->GT_SetGadgetAttrs(slidergad, win, req,
GTSL_Level, 5,
TAG_END);
<syntaxhighlight>

Here are some other example uses of GT_SetGadgetAttrs() to change gadget attributes after it is created.

<syntaxhighlight>
/* Disable a button gadget */
IGadTools->GT_SetGadgetAttrs(buttongad, win, NULL,
GA_Disabled, TRUE,
TAG_END);

/* Change a slider's range to be 1 to 100, currently at 50 */
IGadTools->GT_SetGadgetAttrs(slidergad, win, NULL,
GTSL_Min, 1,
GTSL_Max, 100,
GTSL_Level, 50,
TAG_END);

/* Add a node to the head of listview's list, and
make it the selected one */
IGadTools->GT_SetGadgetAttrs(listviewgad, win, NULL,
/* detach list before modifying */
GTLV_Labels, ~0,
TAG_END);
IExec->AddHead(&lvlabels, &newnode);
IGadTools->GT_SetGadgetAttrs(listviewgad, win, NULL,
/* re-attach list */
GTLV_Labels, &lvlabels,
GTLV_Selected, 0,
TAG_END);
</syntaxhighlight>

When changing a gadget using these functions, the gadget will automatically update its visuals. No refresh is required, nor should any refresh call be performed.

{{Note|title=Warning|text=The GT_SetGadgetAttrs() functions may not be called inside of a GT_BeginRefresh()/GT_EndRefresh() pair. This is true of Intuition gadget functions generally, including those discussed in [[Intuition_Gadgets|Intuition Gadgets]].}}

In the sections that follow all the possible attributes for each kind of gadget are discussed. The tags are also described in the Autodocs for GT_SetGadgetAttrs() in the SDK.

{{Note|title=Important|text=Tags that can only be sent to CreateGadget() and not to GT_SetGadgetAttrs() will be marked as ''create only'' in the discussion that follows. Those that are valid parameters to both functions will be marked as ''create and set''.}}

=== The Kinds of GadTools Gadgets ===

This section discusses the unique features of each kind of gadget supported by the GadTools library.

==== Button Gadgets ====

Button gadgets (BUTTON_KIND) are perhaps the simplest kind of GadTools gadget. Button gadgets may be used for objects like the "OK" and "Cancel" buttons in requesters. GadTools will create a hit-select button with a raised bevelled border. The label supplied will be centered on the button's face. Since the label is not clipped, be sure that the gadget is large enough to contain the text supplied.

Button gadgets recognize only one tag:

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable or ghost the button gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user selects a button gadget, the program will receive an IDCMP_GADGETUP event.

If clicking on a button causes a requester to appear, for example a button that brings up a color requester, then the button text should end in ellipsis (...), as in "Quit..."

==== Text-Entry and Number-Entry Gadgets ====

Text-entry (STRING_KIND) and number-entry (INTEGER_KIND) gadgets are fairly typical Intuition string gadgets. The typing area is contained by a border which is a raised ridge.

Text-entry gadgets accept the following tags:

; GTST_String (STRPTR)
: A pointer to the string to be placed into the text-entry gadget buffer or NULL to get an empty text-entry gadget. The string itself is actually copied into the gadget's buffer. The default is NULL. (Create and set.)

; GTST_MaxChars (UWORD)
: The maximum number of characters that the text-entry gadget should hold. The string buffer that gets created for the gadget will actually be one bigger than this number, in order to hold the trailing NULL. The default is 64. (Create only.)

Number-entry gadgets accept the following tags:

; GTIN_Number (ULONG)
: The number to be placed into the number-entry gadget. The default is zero. (Create and set.)

; GTIN_MaxChars (UWORD)
: The maximum number of digits that the number-entry gadget should hold. The string buffer that gets created for the gadget will actually be one bigger than this, in order to hold the trailing NULL. The default is 10. (Create only.)

Both text-entry and number-entry gadgets, which are collectively called string gadgets, accept these common tags:

; STRINGA_Justification
: This attribute controls the placement of the string or number within its box and can be one of GACT_STRINGLEFT, GACT_STRINGRIGHT or GACT_STRINGCENTER. The default is GACT_STRINGLEFT. (Create only.)

; STRINGA_ReplaceMode (BOOL)
: Set STRINGA_ReplaceMode to TRUE to get a string gadget which is in replace-mode, as opposed to auto-insert mode. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the string gadget, otherwise to FALSE. The default is FALSE. (Create and set.)

; STRINGA_ExitHelp (BOOL)
: Set this attribute to TRUE if the application wants to hear the Help key from within this string gadget. This feature allows the program to hear the press of the Help key in all cases. If TRUE, pressing the help key while this gadget is active will terminate the gadget and send a message. The program will receive an IDCMP_GADGETUP message having a Code value of 0x5F, the rawkey code for Help. Typically, the program will want to reactivate the gadget after performing the help-display. The default is FALSE. (Create only.)

; GA_TabCycle (BOOL)
: If the user types Tab or Shift Tab into a GA_TabCycle gadget, Intuition will activate the next or previous such gadget in sequence. This gives the user easy keyboard control over which text-entry or number-entry gadget is active. Tab moves to the next GA_TabCycle gadget in the gadget list and Shift Tab moves to the previous one. When the user presses Tab or Shift Tab, Intuition will deactivate the gadget and send this program an IDCMP_GADGETUP message with the code field set to 0x09, the ASCII value for a tab. Intuition will then activate the next indicated gadget. Check the shift bits of the qualifier field to learn if Shift Tab was typed. The ordering of the gadgets may only be controlled by the order in which they were added to the window. For special cases, for example, if there is only one string gadget in the window, this feature can be suppressed by specifying the tagitem pair {GA_TabCycle, FALSE}. The default is TRUE. (Create only.)

; GTST_EditHook (struct Hook *)
: Pointer to a custom editing hook for this string or integer gadget. See [[Intuition_Gadgets|Intuition Gadgets]] for more information on string gadget edit-hooks.

As with all Intuition string gadgets, the program will receive an IDCMP_GADGETUP message only when the user presses Enter, Return, Help, Tab or Shift Tab while typing in the gadget. Note that, like Intuition string gadgets, the program will not hear anything if the user deactivates the string gadget by clicking elsewhere. Therefore, it is a good idea to always check the string gadget's buffer before using its contents, instead of just tracking its value as IDCMP_GADGETUP messages are received for this gadget.

Be sure the code is designed so that nothing drastic happens, like closing a requester or opening a file, if the IDCMP_GADGETUP message has a non-zero Code field; the program will want to handle the Tab and Help cases intelligently.

To read the string gadget's buffer, look at the Gadget's StringInfo Buffer:

<syntaxhighlight>
((struct StringInfo *)gad->SpecialInfo)->Buffer
</syntaxhighlight>

To determine the value of an integer gadget, look at the Gadget's StringInfo LongInt in the same way.

Always use the GTST_String or GTIN_Number tags to set these values. Never write to the StringInfo->Buffer or StringInfo->LongInt fields directly.

GadTools string and integer gadgets do not directly support the GA_Immediate property (which would cause Intuition to send an IDCMP_GADGETDOWN event when such a gadget is first selected). However, this property can be very important. Therefore, the following technique can be used to enable this property.

{{Note|title=Warning|text=Note that the technique shown here relies on directly setting flags in a GadTools gadget; this is not normally allowed since it hinders future compatibility. Do not attempt to change other flags or properties of GadTools gadgets except through the defined interfaces of CreateGadgetA() and GT_SetGadgetAttrsA(). Directly modifying flags or properties is legal only when officially sanctioned by the AmigaOS development team.}}

To get the GA_Immediate property, pass the {GA_Immediate, TRUE} tag to CreateGadgetA().

==== Checkbox Gadgets ====

Checkboxes (CHECKBOX_KIND) are appropriate for presenting options which may be turned on or off. This kind of gadget consists of a raised box which contains a checkmark if the option is selected or is blank if the option is not selected. Clicking on the box toggles the state of the checkbox.

The width and height of a checkbox are by default not scaled and fixed (CHECKBOXWIDTH by CHECKBOXHEIGHT). To scale a checkbox gadget, set the GTCB_Scaled tag to TRUE, and set the desired width and height in the ng_Width and ng_Height fields of the NewGadget structure.

The checkbox may be controlled with the following tags:

; GTCB_Checked (BOOL)
: Set this attribute to TRUE to set the gadget's state to ''checked''. Set it to FALSE to mark the gadget as ''unchecked''. The default is FALSE. (Create and set.)

; GTCB_Scaled (BOOL)
: Scales the checkbox gadget if set to TRUE. The default is FALSE. (Create and set.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the checkbox, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user selects a checkbox, the program will receive an IntuiMessage with a class of IDCMP_GADGETUP. As this gadget always toggles, the program can easily track the state of the gadget. Feel free to read the gadget->Flags GFLG_SELECTED bit. Note, however, that the Gadget structure itself is not synchronized to the IntuiMessages received. If the user clicks a second time, the GFLG_SELECTED bit can toggle again before the program gets a chance to read it. This is true of any of the dynamic fields of the Gadget structure, and is worth being aware of, although only rarely will an application have to account for it.

==== Mutually-Exclusive Gadgets ====

Use mutually exclusive gadgets (MX_KIND), or ''radio buttons'', when the user must choose only one option from a short list of possibilities. Mutually exclusive gadgets are appropriate when there are a small number of choices, perhaps eight or less.

A set of mutually exclusive gadgets consists of a list of labels and beside each label, a small raised oval that looks like a button. Exactly one of the ovals is recessed and highlighted, to indicate the selected choice. The user can pick another choice by clicking on any of the raised ovals. This choice will become active and the previously selected choice will become inactive. That is, the selected oval will become recessed while the previous one will pop out, like the buttons on a car radio.

Mutually exclusive gadgets recognize these tags:

; GTMX_Labels (STRPTR *)
: A NULL-pointer-terminated array of strings which are to be the labels beside each choice in the set of mutually exclusive gadgets. This array determines how many buttons are created. This array must be supplied to CreateGadget() and may not be changed. The strings themselves must remain valid for the lifetime of the gadget. (Create only.)

; GTMX_Active (UWORD)
: The ordinal number, counting from zero, of the active choice of the set of mutually exclusive gadgets. The default is zero. (Create and set.)

; GTMX_Spacing (UWORD)
: The amount of space, in pixels, that will be placed between successive choices in a set of mutually exclusive gadgets. The default is one. (Create only.)

; GTMX_Scaled (BOOL)
: Indicates whether the mutually exclusive gadget should be scaled or not. The default is FALSE. (Create only.)

; GTMX_TitlePlace (UWORD)
: Where to place the title of the mutually exclusive gadget. The gadget obtains its title from the ng_GadgetText field of the NewGadget structure. The default is no title. (Create only.)
:{| class="wikitable"
| PLACETEXT_LEFT || Right-align text on left side
|-
| PLACETEXT_RIGHT || Left-align text on right side
|-
| PLACETEXT_ABOVE || Center text above
|-
| PLACETEXT_BELOW || Center text below
|}

When the user selects a new choice from a set of mutually exclusive gadgets, the program will receive an IDCMP_GADGETDOWN IntuiMessage. Look in the IntuiMessage's Code field for the ordinal number of the new active selection.

The ng_GadgetText field of the NewGadget structure is used to display the title for mutually exclusive gadgets. The text position specified in ng_Flags determines whether the item labels are placed to the left or the right of the radio buttons themselves. By default, the labels appear on the left. Do not specify PLACETEXT_ABOVE, PLACETEXT_BELOW or PLACETEXT_IN for this kind of gadget.

To scale a mutually exclusive gadget, set the GTMX_Scaled tag to TRUE, and set the desired width and height in the ng_Width and ng_Height fields of the NewGadget structure. The default value of GTMX_Scaled is FALSE, meaning use the default size of MXWIDTH by MXHEIGHT respectively. If you scale mutually exclusive gadgets, you must also set the
GTMX_Spacing tag to NewGadget.ng_TextAttr->ta_YSize + 1 to properly space the buttons with respect to the font.

==== Cycle Gadgets ====

Like mutually exclusive gadgets, cycle gadgets (CYCLE_KIND) allow the user to choose exactly one option from among several.

The cycle gadget appears as a raised rectangular button with a vertical divider near the left side. A circular arrow glyph appears to the left of the divider, while the current choice appears to the right. Clicking on the cycle gadget advances to the next choice, while shift-clicking on it changes it to the previous choice.

Cycle gadgets are more compact than mutually exclusive gadgets, since only the current choice is displayed. They are preferable to mutually exclusive gadgets when a window needs to have several such gadgets as in the PrinterGfx Preferences editor, or when there is a medium number of choices. If the number of choices is much more than about a dozen, it may become too frustrating and inefficient for the user to find the desired choice. In that case, use a listview (scrolling list) instead.

The tags recognized by cycle gadgets are:

; GTCY_Labels (STRPTR *)
: Like GTMX_Labels, this tag is associated with a NULL-pointer-terminated array of strings which are the choices that this gadget allows. This array must be supplied to CreateGadget() and can be changed. The strings themselves must remain valid for the lifetime of the gadget. (Create and set.)

; GTCY_Active (UWORD)
: The ordinal number, counting from zero, of the active choice of the cycle gadget. The default is zero. (Create and set.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the cycle gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user clicks or shift-clicks on a cycle gadget, the program will receive an IDCMP_GADGETUP IntuiMessage. Look in the Code field of the IntuiMessage for the ordinal number of the new active selection.

==== Slider Gadgets ====

Sliders are one of the two kinds of proportional gadgets offered by GadTools. Slider gadgets (SLIDER_KIND) are used to control an amount, a level or an intensity, such as volume or color. Scroller gadgets (SCROLLER_KIND) are discussed below.

Slider gadgets accept the following tags:

; GTSL_Min (WORD)
: The minimum level of a slider. The default is zero. (Create and set.)

; GTSL_Max (WORD)
: The maximum level of a slider. The default is 15. (Create and set.)

; GTSL_Level (WORD)
: The current level of a slider. The default is zero. When the level is at its minimum, the knob will be all the way to the left for a horizontal slider or all the way at the bottom for a vertical slider. Conversely, the maximum level corresponds to the knob being to the extreme right or top. (Create and set.)

; GTSL_LevelFormat (STRPTR)
: The current level of the slider may be displayed in real-time alongside the gadget. To use the level-display feature, the program must be using a monospace font for this gadget.

: GTSL_LevelFormat specifies a printf()-style formatting string used to render the slider level beside the slider (the complete set of formatting options is described in the Exec library function RawDoFmt()). Be sure to use the "l" (long word) modifier for the number. Field-width specifiers may be used to ensure that the resulting string is always of constant width. The simplest would be "%2ld". A 2-digit hexadecimal slider might use "%02lx", which adds leading zeros to the number. Strings with extra text, such as "%3ld hours", are permissible. If this tag is specified, the program must also provide GTSL_MaxLevelLen. By default, the level is not displayed. (Create only.)

; GTSL_MaxLevelLen (UWORD)
: The maximum length of the string that will result from the given level-formatting string. If this tag is specified, the program must also provide GTSL_LevelFormat. By default, the level is not displayed. (Create only.)

; GTSL_LevelPlace
: To choose where the optional display of the level is positioned. It must be one of PLACETEXT_LEFT, PLACETEXT_RIGHT, PLACETEXT_ABOVE or PLACETEXT_BELOW. The level may be placed anywhere with the following exception: the level and the label may not be both above or both below the gadget. To place them both on the same side, allow space in the gadget's label (see the example). The default is PLACETEXT_LEFT. (Create only.)

; GTSL_DispFunc (LONG (*function)(struct Gadget *, WORD))
: Optional function to convert the level for display. A slider to select the number of colors for a screen may operate in screen depth (1 to 5, for instance), but actually display the number of colors (2, 4, 8, 16 or 32). This may be done by providing a GTSL_DispFunc function which returns 1 << level. The function must take a pointer to the Gadget as the first parameter and the level, a WORD, as the second and return the result as a LONG. The default behavior for displaying a level is to do so without any conversion. (Create only.)

; GA_Immediate (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETDOWN IntuiMessage when the user presses the mouse button over the slider. The default is FALSE. (Create only.)

; GA_RelVerify (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETUP IntuiMessage when the user releases the mouse button after using the slider. The default is FALSE. (Create only.)

; PGA_Freedom
: Specifies which direction the knob may move. Set to LORIENT_VERT for a vertical slider or LORIENT_HORIZ for a horizontal slider. The default is LORIENT_HORIZ. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the slider, to FALSE otherwise. The default is FALSE. (Create and set.)

Up to three different classes of IntuiMessage may be received at the port when the user plays with a slider, these are IDCMP_MOUSEMOVE, IDCMP_GADGETUP and IDCMP_GADGETDOWN. The program may examine the IntuiMessage Code field to discover the slider's level.

IDCMP_MOUSEMOVE IntuiMessages will be heard whenever the slider's level changes. IDCMP_MOUSEMOVE IntuiMessages will not be heard if the knob has not moved far enough for the level to actually change. For example if the slider runs from 0 to 15 and is currently set to 12, if the user drags the slider all the way up the program will hear no more than three IDCMP_MOUSEMOVEs, one each for 13, 14 and 15.

If {GA_Immediate, TRUE} is specified, then the program will always hear an IDCMP_GADGETDOWN IntuiMessage when the user begins to adjust a slider. If {GA_RelVerify, TRUE} is specified, then the program will always hear an IDCMP_GADGETUP IntuiMessage when the user finishes adjusting the slider. If IDCMP_GADGETUP or IDCMP_GADGETDOWN IntuiMessages are requested, the program will always hear them, even if the level has not changed since the previous IntuiMessage.

Note that the Code field of the IntuiMessage structure is a UWORD, while the slider's level may be negative, since it is a WORD. Be sure to copy or cast the IntuiMessage->Code into a WORD if the slider has negative levels.

If the user clicks in the container next to the knob, the slider level will increase or decrease by one. If the user drags the knob itself, then the knob will snap to the nearest integral position when it is released.

Here is an example of the screen-depth slider discussed earlier:

<syntaxhighlight>
/* NewGadget initialized here. Note the three spaces
* after "Slider:", to allow a blank plus the two digits
* of the level display
*/
ng.ng_Flags = PLACETEXT_LEFT;
ng.ng_GadgetText = "Slider: ";

LONG DepthToColors(struct Gadget *gad, WORD level)
{
return ((WORD)(1 << level));
}

...

gad = IGadTools->CreateGadget(SLIDER_KIND, gad, &ng,
GTSL_Min, 1,
GTSL_Max, 5,
GTSL_Level, current_depth,
GTSL_MaxLevelLen, 2,
GTSL_LevelFormat, "%2ld",
GTSL_DispFunc, DepthToColors,
TAG_END);
</syntaxhighlight>

==== Scroller Gadgets ====

Scrollers (SCROLLER_KIND) bear some similarity to sliders, but are used for a quite different job: they allow the user to adjust the position of a limited view into a larger area. For example, Workbench's windows have scrollers that allow the user to see icons that are outside the visible portion of a window. Another example is a scrolling list in a file requester which has a scroller that allows the user to see different parts of the whole list.

A scroller consists of a proportional gadget and usually also has a pair of arrow buttons.

While the slider deals in minimum, maximum and current level, the scroller understands Total, Visible and Top. For a scrolling list, Total would be the number of items in the entire list, Visible would be the number of lines visible in the display area and Top would be the number of the first line displayed in the visible part of the list. Top would run from zero to Total - Visible. For an area-scroller such as those in Workbench's windows, Total would be the height (or width) of the whole area, Visible would be the visible height (or width) and Top would be the top (or left) edge of the visible part.

Note that the position of a scroller should always represent the position of the visible part of the project and never the position of a cursor or insertion point.

Scrollers respect the following tags:

; GTSC_Top (WORD)
: The top line or position visible in the area that the scroller represents. The default is zero. (Create and set.)

; GTSC_Total (WORD)
: The total number of lines or positions that the scroller represents. The default is zero. (Create and set.)

; GTSC_Visible (WORD)
: The visible number of lines or positions that the scroller represents. The default is two. (Create and set.)

; GTSC_Arrows (UWORD)
: Asks for arrow gadgets to be attached to the scroller. The value supplied will be used as the width of each arrow button for a horizontal scroller or the height of each arrow button for a vertical scroller, the other dimension will be set by GadTools to match the scroller size. It is generally recommend that arrows be provided. The default is no arrows. (Create only.)

; GA_Immediate (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETDOWN IntuiMessage when the user presses the mouse button over the scroller. The default is FALSE. (Create only.)

; GA_RelVerify (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETUP IntuiMessage when the user releases the mouse button after using the scroller. The default is FALSE. (Create only.)

; PGA_Freedom
: Specifies which direction the knob may move. Set to LORIENT_VERT for a vertical scroller or LORIENT_HORIZ for a horizontal scroller. The default is LORIENT_HORIZ. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the scroller, to FALSE otherwise. The default is FALSE. (Create and set.)

The IntuiMessages received for a scroller gadget are the same in nature as those for a slider defined above, including the fact that messages are only heard by the program when the knob moves far enough for the Top value to actually change. The Code field of the IntuiMessage will contain the new Top value of the scroller.

If the user clicks on an arrow gadget, the scroller moves by one unit. If the user holds the button down over an arrow gadget, it repeats.

If the user clicks in the container next to the knob, the scroller will move by one page, which is the visible amount less one. This means that when the user pages through a scrolling list, any pair of successive views will overlap by one line. This helps the user understand the continuity of the list. If the program is using a scroller to pan through an area then there will be an overlap of one unit between successive views. It is recommended that Top, Visible and Total be scaled so that one unit represents about five to ten percent of the visible amount.

==== Listview Gadgets ====

Listview gadgets (LISTVIEW_KIND) are scrolling lists. They consist of a scroller with arrows, an area where the list itself is visible and optionally a place where the current selection is displayed, which may be editable. The user can browse through the list using the scroller or its arrows and may select an entry by clicking on that item.

There are a number of tags that are used with listviews:

; GTLV_Labels (struct List *)
: An Exec list whose nodes' ln_Name fields are to be displayed as items in the scrolling list. If the list is empty, an empty List structure or a NULL value may be used for GTLV_Labels. This tag accepts a value of "~0" to detach the list from the listview, defined below. The default is NULL. (Create and set.)

; GTLV_Top (UWORD)
: The ordinal number of the top item visible in the listview. The default is zero. (Create and set.)

; GTLV_ReadOnly (BOOL)
: Set this to TRUE for a read-only listview, which the user can browse, but not select items from. A read-only listview can be recognized because the list area is recessed, not raised. The default is FALSE. (Create only.)

; GTLV_ScrollWidth (UWORD)
: The width of the scroller to be used in the listview. Any value specified must be reasonably bigger than zero. The default is 16. (Create only.)

; GTLV_ShowSelected (struct Gadget *)
: Use this tag to show the currently selected entry displayed underneath the listview. Set its value to NULL to get a read-only (TEXT_KIND) display of the currently selected entry or set it to a pointer to an already-created GadTools STRING_KIND gadget to allow the user to directly edit the current entry. By default, there is no display of the currently selected entry. (Create only.)

; GTLV_Selected (UWORD)
: Ordinal number of the item to be placed into the display of the current selection under the listview. This tag is ignored if GTLV_ShowSelected is not used. Set it to "~0" to have no current selection. The default is "~0". (Create and set.)

; LAYOUTA_Spacing (UWORD)
: Extra space, in pixels, to be placed between the entries in the listview. The default is zero. (Create only.)

The program will only hear from a listview when the user selects an item from the list. The program will then receive an IDCMP_GADGETUP IntuiMessage. This message will contain the ordinal number of the item within the list that was selected in the Code field of the message. This number is independent of the displayed listview, it is the offset from the start of the list of items.

If the program attaches a display gadget by using the TagItem {GTLV_ShowSelected, NULL}, then whenever the user clicks on an entry in the listview it will be copied into the display gadget.

If the display gadget is to be editable, then the program must first create a GadTools STRING_KIND gadget whose width matches the width of the listview. The TagItem {GTLV_ShowSelected, stringgad} is used to install the editable gadget, where stringgad is the pointer returned by CreateGadget(). When the user selects any entry from the listview, it gets copied into the string gadget. The user can edit the string and the program will hear normal string gadget IDCMP_GADGETUP messages from the STRING_KIND gadget.

The Exec List and its Node structures may not be modified while they are attached to the listview, since the list might be needed at any time. If the program has prepared an entire new list, including a new List structure and all new nodes, it may replace the currently displayed list in a single step by calling GT_SetGadgetAttrs() with the TagItem {GTLV_Labels, newlist}. If the program needs to operate on the list that has already been passed to the listview, it should detach the list by setting the GTLV_Labels attribute to "~0". When done modifying the list, resubmit it by setting GTLV_Labels to once again point to it. This is better than first setting the labels to NULL and later back to the list, since setting GTLV_Labels to NULL will visually clear the listview. If the GTLV_Labels attribute is set to "~0", the program is expected to set it back to something determinate, either a list or NULL, soon after.

The height specified for the listview will determine the number of lines in the list area. When creating a listview, it will be no bigger than the size specified in the NewGadget structure. The size will include the current-display gadget, if any, that has been requested via the GTLV_ShowSelected tag. The listview may end up being less tall than the application asked for, since the calculated height assumes an integral number of lines in the list area.

By default, the gadget label will be placed above the listview. This may be overridden using ng_Flags.

==== Palette Gadgets ====

Palette gadgets (PALETTE_KIND) let the user pick a color from a set of several. A palette gadget consists of a number of colored squares, one for each color available. There may also be an optional indicator square which is filled with the currently selected color. To create a color editor, a palette gadget would be combined with some sliders to control red, green and blue components, for example.

Palette gadgets use the following tags:

; GTPA_Depth (UWORD)
: The number of bitplanes that the palette represents. There will be 1 << depth (2^depth) squares in the palette gadget. The default is one. (Create only.)

; GTPA_Color (UBYTE)
: The selected color of the palette. The default is one. (Create and set.)

; GTPA_ColorOffset (UBYTE)
: The first color to use in the palette. For example, if GTPA_Depth is two and GTPA_ColorOffset is four, then the palette will have squares for colors four, five, six and seven. The default is zero. (Create only.)

; GTPA_IndicatorWidth (UWORD)
: The desired width of the current-color indicator. By specifying this tag, the application is asking for an indicator to be placed to the left of the color selection squares. The indicator will be as tall as the gadget itself. By default there is no indicator. (Create only.)

; GTPA_IndicatorHeight (UWORD)
: The desired height of the current-color indicator. By specifying this tag, the application is asking for an indicator to be placed above the color selection squares. The indicator will be as wide as the gadget itself. By default there is no indicator. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the palette gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

An IDCMP_GADGETUP IntuiMessage will be received when the user selects a color from the palette. The current-color indicator is recessed, indicating that clicking on it has no effect.

If the palette is wide and not tall, use the GTPA_IndicatorWidth tag to put the indicator on the left. If the palette is tall and narrow, put the indicator on top using GTPA_IndicatorHeight.

By default, the gadget's label will go above the palette gadget, unless GTPA_IndicatorWidth is specified, in which case the label will go on the left. In either case, the default may be overridden by setting the appropriate flag in the NewGadget's ng_Flags field.

The size specified for the palette gadget will determine how the area is subdivided to make the individual color squares. The actual size of the palette gadget will be no bigger than the size given, but it can be smaller in order to make the color squares all exactly the same size.

==== Text-Display and Numeric-Display Gadgets ====

Text-display (TEXT_KIND) and numeric-display (NUMBER_KIND) gadgets are read-only displays of information. They are useful for displaying information that is not editable or selectable, while allowing the application to use the GadTools formatting and visuals. Conveniently, the visuals are automatically refreshed through normal GadTools gadget processing. The values displayed may be modified by the program in the same way other GadTools gadgets may be updated.

Text-display and number-display gadgets consist of a fixed label (the one supplied as the NewGadget's ng_GadgetText), as well as a changeable string or number (GTTX_Text or GTNM_Number respectively). The fixed label is placed according to the PLACETEXT_ flag chosen in the NewGadget ng_Flags field. The variable part is aligned to the left-edge of the gadget.

Text-display gadgets recognize the following tags:

; GTTX_Text (STRPTR)
: Pointer to the string to be displayed or NULL for no string. The default is NULL. (Create and set.)

; GTTX_Border (BOOL)
: Set to TRUE to place a recessed border around the displayed string. The default is FALSE. (Create only.)

; GTTX_CopyText (BOOL)
: This flag instructs the text-display gadget to copy the supplied GTTX_Text string instead of using only a pointer to the string. This only works for the value of GTTX_Text set at CreateGadget() time. If GTTX_Text is changed, the new text will be referenced by pointer, not copied. Do not use this tag without a non-NULL GTTX_Text. (Create only.)

Number-display gadgets have the following tags:

; GTNM_Number (LONG)
: The number to be displayed. The default is zero. (Create or set.)

; GTNM_Border (BOOL)
: Set to TRUE to place a recessed border around the displayed number. The default is FALSE. (Create only.)

Since they are not selectable, text-display and numeric-display gadgets never cause IntuiMessages to be sent to the application.

==== Generic Gadgets ====

If the application requires a specialized gadget which does not fit into any of the defined GadTools kinds but would still like to use the GadTools gadget creation and deletion functions, it may create a GadTools generic gadget and use it any way it sees fit. In fact, all of the kinds of GadTools gadgets are created out of GadTools GENERIC_KIND gadgets.

The gadget that gets created will heed almost all the information contained in the NewGadget structure supplied.

If ng_GadgetText is supplied, the gadget's GadgetText will point to an IntuiText structure with the provided string and font. However, do not specify any of the PLACETEXT ng_Flags, as they are currently ignored by GENERIC_KIND gadgets. PLACETEXT flags may be supported by generic GadTools gadgets in the future.

It is up to the program to set the Flags, Activation, GadgetRender, SelectRender, MutualExclude and SpecialInfo fields of the Gadget structure.

The application must also set the GadgetType field, but be certain to preserve the bits set by CreateGadget().

For instance, to make a gadget boolean, use:

<syntaxhighlight>
gad->GadgetType |= GTYP_BOOLGADGET;
</syntaxhighlight>

and not

<syntaxhighlight>
gad->GadgetType = GTYP_BOOLGADGET;
</syntaxhighlight>

Using direct assignment, (the = operator), clears all other flags in the GadgetType field and the gadget may not be properly freed by FreeGadgets().

=== Functions for Setting up GadTools Menus and Gadgets ===

This section gives all the details on the functions used to set up GadTools menus and gadgets that were mentioned briefly earlier in this article.

==== GetVisualInfo() and FreeVisualInfo() ====

In order to ensure their best appearance, GadTools gadgets and menus need information about the screen on which they will appear. Before creating any GadTools gadgets or menus, the program must get this information using the GetVisualInfo() call.

<syntaxhighlight>
APTR GetVisualInfoA( struct Screen *screen, struct TagItem *taglist );
APTR GetVisualInfo( struct Screen *screen, Tag tag1, ... );
</syntaxhighlight>

Set the screen argument to a pointer to the screen you are using. The tag arguments, tag1 or taglist, are reserved for future extensions. Currently none are recognized, so only TAG_END should be used.

The function returns an abstract handle called the VisualInfo. For GadTools gadgets, the ng_VisualInfo field of the NewGadget structure must be set to this handle before the gadget can be added to the window. GadTools menu layout and creation functions also require the VisualInfo handle as an argument.

There are several ways to get the pointer to the screen on which the window will be opened. If the application has its own custom screen, this pointer is known from the call to OpenScreen() or OpenScreenTags(). If the application already has its window opened on the Workbench or some other public screen, the screen pointer can be found in Window.WScreen. Often the program will create its gadgets and menus before opening the window. In this case, use LockPubScreen() to get a pointer to the desired public screen, which also provides a lock on the screen to prevent it from closing. See [[Intuition_Screens|Intuition Screens]] and [[Intuition_Windows|Intuition Windows]] for more about public screens.

The VisualInfo data must be freed after all the gadgets and menus have been freed but before releasing the screen. Custom screens are released by calling CloseScreen(), public screens are released by calling CloseWindow() or UnlockPubScreen(), depending on the technique used. Use FreeVisualInfo() to free the visual info data.

<syntaxhighlight>
VOID FreeVisualInfo( APTR vi );
</syntaxhighlight>

This function takes just one argument, the VisualInfo handle as returned by GetVisualInfo(). The sequence of events for using the VisualInfo handle could look like this:

<syntaxhighlight>
void init()
{
myscreen = IIntuition->LockPubScreen(NULL);
if (!myscreen)
{
cleanup("Failed to lock default public screen");
}
vi = IGadTools->GetVisualInfo(myscreen);
if (!vi)
{
cleanup("Failed to GetVisualInfo");
}
/* Create gadgets here */
ng.ng_VisualInfo = vi;
...
}

void cleanup(STRPTR errorstr)
{
/* These functions may be safely called with a NULL parameter: */
IGadTools->FreeGadgets(glist);
IGadTools->FreeVisualInfo(vi);

if (myscreen)
IIntuition->UnlockPubScreen(NULL, myscreen);

IDOS->Printf(errorstr);
}
</syntaxhighlight>

==== CreateContext() ====

Use of GadTools gadgets requires some per-window context information. CreateContext() establishes a place for that information to go. This function must be called before any GadTools gadgets are created.

<syntaxhighlight>
struct Gadget *CreateContext( struct Gadget **glistptr );
</syntaxhighlight>

The glistptr argument is a double-pointer to a Gadget structure. More specifically, this is a pointer to a NULL-initialized pointer to a Gadget structure.

The return value of CreateContext() is a pointer to this gadget, which should be fed to the program's first call to CreateGadget(). This pointer to the Gadget structure returned by CreateContext(), may then serve as a handle to the list of gadgets as they are created. The code fragment listed in the next section shows how to use CreateContext() together with CreateGadget() to make a linked list of GadTools gadgets.

=== Creating Gadget Lists ===

In the discussion of CreateGadget() presented earlier, the examples showed only how to make a single gadget. For most applications that use GadTools, however, a whole list of gadgets will be needed. To do this, the application could use code such as this:

<syntaxhighlight>
struct NewGadget *newgad1, *newgad2, *newgad3;
struct Gadget *glist = NULL;
struct Gadget *pgad;

...
/* Initialize NewGadget structures */
...

/* Note that CreateContext() requires a POINTER to a NULL-initialized
* pointer to struct Gadget:
*/
pgad = IGadTools->CreateContext(&glist);

pgad = IGadTools->CreateGadget(BUTTON_KIND, pgad, newgad1, TAG_END);
pgad = IGadTools->CreateGadget(STRING_KIND, pgad, newgad2, TAG_END);
pgad = IGadTools->CreateGadget(MX_KIND, pgad, newgad3, TAG_END);

if (!pgad)
{
IGadTools->FreeGadgets(glist);
exit_error();
}
else
{
if ( mywin = IIntuition->OpenWindowTags(NULL,
WA_Gadgets, glist,
...
/* Other tags... */
...
TAG_END) )
{
/* Complete the rendering of the gadgets */
IGadTools->GT_RefreshWindow(win, NULL);
...
/* and continue on... */
...
IIntuition->CloseWindow(mywin);
}

IGadTools->FreeGadgets(glist);
}
</syntaxhighlight>

The pointer to the previous gadget, pgad in the code fragment above, is used for three purposes. First, when CreateGadget() is called multiple times, each new gadget is automatically linked to the previous gadget's NextGadget field, thus creating a gadget list. Second, if one of the gadget creations fails (usually due to low memory, but other causes are possible), then for the next call to CreateGadget(), pgad will be NULL and CreateGadget() will fail immediately. This means that the program can perform several successive calls to CreateGadget() and only have to check for failure at the end.

Finally, although this information is hidden in the implementation and not important to the application, certain calls to CreateGadget() actually cause several Intuition gadgets to be allocated and these are automatically linked together without program interaction, but only if a previous gadget pointer is supplied. If several gadgets are created by a single CreateGadget() call, they work together to provide the functionality of a single GadTools gadget. The application should always act as though the gadget pointer returned by CreateGadget() points to a single gadget instance. See "Documented Side-Effects" for a warning.

There is one exception to the fact that a program only has to check for failure after the last CreateGadget() call and that is when the application depends on the successful creation of a gadget and caches or immediately uses the gadget pointer returned by CreateGadget().

For instance, if the program wants to create a string gadget and save a pointer to the string buffer, it might do so as follows:

<syntaxhighlight>
gad = IGadTools->CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "Hello World",
TAG_END);
if (gad)
{
stringbuffer = ((struct StringInfo *)(gad->SpecialInfo))->Buffer;
}

/* Creation can continue here: */
gad = IGadTools->CreateGadget(..._KIND, gad, &ng2,
...
TAG_END);
</syntaxhighlight>

A major benefit of having a reusable NewGadget structure is that often many fields do not change and some fields change incrementally. For example, the application can set just the NewGadget's ng_VisualInfo and ng_TextAttr only once and never have to modify them again even if the structure is reused to create many gadgets. A set of similar gadgets may share size and some positional information so that code such as the following might be used:

<syntaxhighlight>
/* Assume that the NewGadget structure 'ng' is fully
* initialized here for a button labelled "OK"
*/
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng,
TAG_END);

/* Modify only those fields that need to change: */
ng.ng_GadgetID++;
ng.ng_LeftEdge += 80;
ng.ng_GadgetText = "Cancel";
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng,
TAG_END);
</syntaxhighlight>

{{Note|title=Warning|text=All gadgets created by GadTools currently have the GADTOOL_TYPE bit set in their GadgetType field. It is not correct to check for, set, clear or otherwise rely on this since it is subject to change.}}

=== Gadget Refresh Functions ===

Normally, GadTools gadgets are created and then attached to a window when the window is opened, either through the WA_FirstGadget tag or the NewWindow.FirstGadget field. Alternately, they may be added to a window after it is open by using the functions AddGList() and RefreshGList().

Regardless of which way gadgets are attached to a window, the program must then call the GT_RefreshWindow() function to complete the rendering of GadTools gadgets. This function takes two arguments.

<syntaxhighlight>
VOID GT_RefreshWindow( struct Window *win, struct Requester *req );
</syntaxhighlight>

This win argument is a pointer to the window that contains the GadTools gadgets. The req argument is currently unused and should be set to NULL. This function should only be called immediately after adding GadTools gadgets to a window. Subsequent changes to GadTools gadget imagery made through calls to GT_SetGadgetAttrs() will be automatically performed by GadTools when the changes are made. (There is no need to call GT_RefreshWindow() in that case.)

As mentioned earlier, applications must always ask for notification of window refresh events for any window that uses GadTools gadgets. When the application receives an IDCMP_REFRESHWINDOW message for a window, Intuition has already refreshed its gadgets. Normally, a program would then call Intuition's BeginRefresh(), perform its own custom rendering operations, and finally call EndRefresh(). But for a window that uses GadTools gadgets, the application must call GT_BeginRefresh() and GT_EndRefresh() in place of BeginRefresh() and EndRefresh(). This allows the the GadTools gadgets to be fully refreshed.

<syntaxhighlight>
VOID GT_BeginRefresh( struct Window *win );
VOID GT_EndRefresh ( struct Window *win, LONG complete );
</syntaxhighlight>

For both functions, the win argument is a pointer to the window to be refreshed. For GT_EndRefresh(), set the complete argument to TRUE if refreshing is complete, set it to FALSE otherwise. See the discussion of BeginRefresh() and EndRefresh() in [[Intuition_Windows|Intuition Windows]] for more about window refreshing.

When using GadTools gadgets, the program may not set the window's WFLG_NOCAREREFRESH flag. Even if there is no custom rendering to be performed, GadTools gadgets requires this minimum code to handle IDCMP_REFRESHWINDOW messages:

<syntaxhighlight>
case IDCMP_REFRESHWINDOW:
IGadTools->GT_BeginRefresh(win);
/* custom rendering, if any, goes here */
IGadTools->GT_EndRefresh(win, TRUE);
break;
</syntaxhighlight>

=== Other GadTools Functions ===

This section discusses some additional support functions in the GadTools library that serve special needs.

==== GT_FilterIMsg() and GT_PostFilterIMsg() ====

For most GadTools programs, GT_GetIMsg() and GT_ReplyIMsg() work perfectly well. In rare cases an application may find they pose a bit of a problem. A typical case is when all messages are supposed to go through a centralized ReplyMsg() that cannot be converted to a GT_ReplyIMsg(). Since calls to GT_GetIMsg() and GT_ReplyIMsg() must be paired, there would be a problem.

For such cases, the GT_FilterIMsg() and GT_PostFilterIMsg() functions are available. These functions allow GetMsg() and ReplyMsg() to be used in a way that is compatible with GadTools.

{{Note|title=Warning|text=These functions are for specialized use only and will not be used by the majority of applications. See GT_GetIMsg() and GT_ReplyIMsg() for standard message handling.}}

<syntaxhighlight>
struct IntuiMessage *GT_FilterIMsg( struct IntuiMessage *imsg );
struct IntuiMessage *GT_PostFilterIMsg( struct IntuiMessage *imsg );
</syntaxhighlight>

The GT_FilterIMsg() function should be called right after GetMsg(). It takes a pointer to the original IntuiMessage and, if the message applies to a GadTools gadget, returns either a modified IntuiMessage or a NULL. A NULL return signifies that the message was consumed by a GadTools gadget (and not needed by the application).

The GT_PostFilterIMsg() function should be called before replying to any message modified by GT_FilterIMsg(). It takes a pointer to the modified version of an IntuiMessage obtained with GT_FilterIMsg() and returns a pointer to the original IntuiMessage.

The typical calling sequence for a program that uses these functions, is to call GetMsg() to get the IntuiMessage. Then, if the message applies to a window which contains GadTools gadgets, call GT_FilterIMsg(). Any message returned by GT_FilterIMsg() should be used like a message returned from GT_GetIMsg().

When done with the message, the application must call GT_PostFilterIMsg() to perform any clean up necessitated by the previous call to GT_FilterIMsg(). In all cases, the application ''must'' then reply the original IntuiMessage using ReplyMsg(). This is true even for consumed messages as these are ''not'' replied by GadTools. For example, the application could use code such as this:

<syntaxhighlight>
/* port is a message port receiving different messages */
/* gtwindow is the window that contains GadTools gadgets */

imsg = IExec->GetMsg(port);

/* Is this the window with GadTools gadgets? */
if (imsg->IDCMPWindow == gtwindow)
{
/* Filter the message and see if action is needed */
if (gtimsg = IGadTools->GT_FilterIMsg(imsg))
{
switch (gtimsg->Class)
{
/* Act depending on the message */
...
}
/* Clean up the filtered message. The return value is not needed */
/* since we already have a pointer to the original message. */
IGadTools->GT_PostFilterIMsg(gtimsg);
}
}
/* other stuff can go here */
IExec->ReplyMsg(imsg);
</syntaxhighlight>

You should not make any assumptions about the contents of the unfiltered IntuiMessage (imsg in the above example). Only two things are guaranteed: the unfiltered IntuiMessage must be replied to and the unfiltered IntuiMessage (if it produces anything when passed through GT_FilterIMsg()) will produce a meaningful GadTools IntuiMessage like those described in the section on the different kinds of gadgets. The relationship between the unfiltered and filtered messages are expected to change in the future. See the section on documented side-effects for more information.

==== DrawBevelBox() ====

A key visual signature shared by most GadTools gadgets is the raised or recessed beveled box imagery. Since the program may wish to create its own boxes to match, GadTools provides the DrawBevelBox() and DrawBevelBoxA() functions.

<syntaxhighlight>
VOID DrawBevelBoxA( struct RastPort *rport, LONG left, LONG top, LONG width, LONG height,
struct TagItem *taglist );
VOID DrawBevelBox ( struct RastPort *rport, LONG left, LONG top, LONG width, LONG height,
Tag tag1, ... );
</syntaxhighlight>

The rport argument is a pointer to the RastPort into which the box is to be rendered. The left, top, width and height arguments specify the dimensions of the desired box.

The tag arguments, tag1 or taglist, may be set as follows:

; GT_VisualInfo (APTR)
: The VisualInfo handle as returned by a prior call to GetVisualInfo(). This value is required.

; GTBB_Recessed (BOOL)
: A beveled box may either appear to be raised to signify an area of the window that is selectable or recessed to signify an area of the window in which clicking will have no effect. Set this boolean tag to TRUE to get a recessed box. Omit this tag entirely to get a raised box.

DrawBevelBox() is a rendering operation, not a gadget. This means that the program must refresh any beveled boxes rendered through this function if the window gets damaged.

=== Gadget Keyboard Equivalents ===

Often, users find it convenient to control gadgets using the keyboard. The keyboard equivalent will be an underscored character in the gadget label, for easy identification. At the present time, however, the application is still responsible for implementing the reaction to each keypress.

==== Denoting a Gadget's Keyboard Equivalent ====

In order to denote the key equivalent, the application may add a marker-symbol to the gadget label. This is done by placing the marker-symbol immediately before the character to be underscored. This symbol can be any character that is not used in the label. The underscore character, "_" is the recommended marker-symbol. So, for example, to mark the letter "F" as the keyboard equivalent for a button labelled "Select Font ...", create the gadget text:

<syntaxhighlight>
ng.ng_GadgetText = "Select _Font ...";
</syntaxhighlight>

To inform GadTools of the underscore in the label, pass the GA_Underscore tag to CreateGadget() or CreateGadgetA(). The data-value associated with this tag is a character, not a string, which is the marker-symbol used in the gadget label:

<syntaxhighlight>
GA_Underscore, '_', /* Note '_', not "_" !!! */
</syntaxhighlight>

GadTools will create a gadget label which consists of the text supplied with the marker-symbol removed and the character following the marker-symbol underscored.

The gadget's label would look something like:

Select Font ...

==== Implementing a Gadget's Keyboard Equivalent Behavior ====

Currently, GadTools does not process keyboard equivalents for gadgets. It is up to the application writer to implement the correct behavior, normally by calling GT_SetGadgetAttrs() on the appropriate gadget. For some kinds of gadget, the behavior should be the same regardless of whether the keyboard equivalent was pressed with or without the shift key. For other gadgets, shifted and unshifted keystrokes will have different, usually opposite, effects.

Here is the correct behavior for keyboard equivalents for each kind of GadTools gadget:

; Button Gadgets
: The keyboard equivalent should invoke the same function that clicking on the gadget does. There is currently no way to highlight the button visuals programmatically when accessing the button through a keyboard equivalent.

; Text-Entry and Number-Entry Gadgets
: The keyboard equivalent should activate the gadget so the user may type into it. Use Intuition's ActivateGadget() call.

; Checkbox Gadgets
: The keyboard equivalent should toggle the state of the checkbox. Use GT_SetGadgetAttrs() and the GTCB_Checked tag.

; Mutually-Exclusive Gadgets
: The unshifted keystroke should activate the next choice, wrapping around from the last to the first. The shifted keystroke should activate the previous choice, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTMX_Active tag.

; Cycle Gadgets
: The unshifted keystroke should activate the next choice, wrapping around from the last to the first. The shifted keystroke should activate the previous choice, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTCY_Active tag.

; Slider Gadgets
: The unshifted keystroke should increase the slider's level by one, stopping at the maximum, while the shifted keystroke should decrease the level by one, stopping at the minimum. Use GT_SetGadgetAttrs() and the GTSL_Level tag.

; Scroller Gadgets
: The unshifted keystroke should increase the scroller's top by one, stopping at the maximum, while the shifted keystroke should decrease the scroller's top by one, stopping at the minimum. Use GT_SetGadgetAttrs() and the GTSC_Top tag.

; Listview Gadgets
: The unshifted keystroke should cause the next entry in the list to become the selected one, stopping at the last entry, while the shifted keystroke should cause the previous entry in the list to become the selected one, stopping at the first entry. Use GT_SetGadgetAttrs() and the GTLV_Top and GTLV_Selected tags.

; Palette Gadgets
: The unshifted keystroke should select the next color, wrapping around from the last to the first. The shifted keystroke should activate the previous color, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTPA_Color tag.

; Text-Display and Number-Display Gadgets
: These kinds of GadTools gadget have no keyboard equivalents since they are not selectable.

; Generic Gadgets
: Define appropriate keyboard functions based on the kinds of keyboard behavior defined for other GadTools kinds.

=== Complete GadTools Gadget Example ===

Here's a working example showing how to set up and use a linked list of GadTools gadgets complete with keyboard shortcuts.

<syntaxhighlight>
/* gadtoolsgadgets.c
** Simple example of using a number of gadtools gadgets.
**
*/
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/gadgetclass.h>
#include <libraries/gadtools.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/graphics.h>
#include <proto/intuition.h>
#include <proto/gadtools.h>

/* Gadget defines of our choosing, to be used as GadgetID's,
** also used as the index into the gadget array my_gads[].
*/
#define MYGAD_SLIDER (0)
#define MYGAD_STRING1 (1)
#define MYGAD_STRING2 (2)
#define MYGAD_STRING3 (3)
#define MYGAD_BUTTON (4)

/* Range for the slider: */
#define SLIDER_MIN (1)
#define SLIDER_MAX (20)

struct TextAttr Topaz80 = { "topaz.font", 8, 0, 0, };

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct GadToolsIFace *IGadTools;

/* Print any error message. We could do more fancy handling (like
** an EasyRequest()), but this is only a demo.
*/
void errorMessage(STRPTR error)
{
if (error)
IDOS->Printf("Error: %s\n", error);
}

/*
** Function to handle a GADGETUP or GADGETDOWN event. For GadTools gadgets,
** it is possible to use this function to handle MOUSEMOVEs as well, with
** little or no work.
*/
VOID handleGadgetEvent(struct Window *win, struct Gadget *gad, UWORD code,
WORD *slider_level, struct Gadget *my_gads[])
{
switch (gad->GadgetID)
{
case MYGAD_SLIDER:
/* Sliders report their level in the IntuiMessage Code field: */
IDOS->Printf("Slider at level %ld\n", code);
*slider_level = code;
break;
case MYGAD_STRING1:
/* String gadgets report GADGETUP's */
IDOS->Printf("String gadget 1: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_STRING2:
/* String gadgets report GADGETUP's */
IDOS->Printf("String gadget 2: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_STRING3:
/* String gadgets report GADGETUP's */
IDOS->Printf("String gadget 3: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_BUTTON:
/* Buttons report GADGETUP's (button resets slider to 10) */
IDOS->Printf("Button was pressed, slider reset to 10.\n");
*slider_level = 10;
IGadTools->GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
}
}

/*
** Function to handle vanilla keys.
*/
VOID handleVanillaKey(struct Window *win, UWORD code,
WORD *slider_level, struct Gadget *my_gads[])
{
switch (code)
{
case 'v':
/* increase slider level, but not past maximum */
if (++*slider_level > SLIDER_MAX)
*slider_level = SLIDER_MAX;
IGadTools->GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'V':
/* decrease slider level, but not past minimum */
if (--*slider_level < SLIDER_MIN)
*slider_level = SLIDER_MIN;
IGadTools->GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'c':
case 'C':
/* button resets slider to 10 */
*slider_level = 10;
IGadTools->GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'f':
case 'F':
IIntuition->ActivateGadget(my_gads[MYGAD_STRING1], win, NULL);
break;
case 's':
case 'S':
IIntuition->ActivateGadget(my_gads[MYGAD_STRING2], win, NULL);
break;
case 't':
case 'T':
IIntuition->ActivateGadget(my_gads[MYGAD_STRING3], win, NULL);
break;
}
}

/*
** Here is where all the initialization and creation of GadTools gadgets
** take place. This function requires a pointer to a NULL-initialized
** gadget list pointer. It returns a pointer to the last created gadget,
** which can be checked for success/failure.
*/
struct Gadget *createAllGadgets(struct Gadget **glistptr, void *vi,
UWORD topborder, WORD slider_level, struct Gadget *my_gads[])
{
struct NewGadget ng;
struct Gadget *gad;

/* All the gadget creation calls accept a pointer to the previous gadget, and
** link the new gadget to that gadget's NextGadget field. Also, they exit
** gracefully, returning NULL, if any previous gadget was NULL. This limits
** the amount of checking for failure that is needed. You only need to check
** before you tweak any gadget structure or use any of its fields, and finally
** once at the end, before you add the gadgets.
*/

/* The following operation is required of any program that uses GadTools.
** It gives the toolkit a place to stuff context data.
*/
gad = IGadTools->CreateContext(glistptr);

/* Since the NewGadget structure is unmodified by any of the CreateGadget()
** calls, we need only change those fields which are different.
*/
ng.ng_LeftEdge = 140;
ng.ng_TopEdge = 20+topborder;
ng.ng_Width = 200;
ng.ng_Height = 12;
ng.ng_GadgetText = "_Volume: ";
ng.ng_TextAttr = &Topaz80;
ng.ng_VisualInfo = vi;
ng.ng_GadgetID = MYGAD_SLIDER;
ng.ng_Flags = NG_HIGHLABEL;

my_gads[MYGAD_SLIDER] = gad = IGadTools->CreateGadget(SLIDER_KIND, gad, &ng,
GTSL_Min, SLIDER_MIN,
GTSL_Max, SLIDER_MAX,
GTSL_Level, slider_level,
GTSL_LevelFormat, "%2ld",
GTSL_MaxLevelLen, 2,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_Height = 14;
ng.ng_GadgetText = "_First:";
ng.ng_GadgetID = MYGAD_STRING1;
my_gads[MYGAD_STRING1] = gad = IGadTools->CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "Try pressing",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_GadgetText = "_Second:";
ng.ng_GadgetID = MYGAD_STRING2;
my_gads[MYGAD_STRING2] = gad = IGadTools->CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "TAB or Shift-TAB",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_GadgetText = "_Third:";
ng.ng_GadgetID = MYGAD_STRING3;
my_gads[MYGAD_STRING3] = gad = IGadTools->CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "To see what happens!",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_LeftEdge += 50;
ng.ng_TopEdge += 20;
ng.ng_Width = 100;
ng.ng_Height = 12;
ng.ng_GadgetText = "_Click Here";
ng.ng_GadgetID = MYGAD_BUTTON;
ng.ng_Flags = 0;
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng,
GT_Underscore, '_',
TAG_END);
return(gad);
}

/*
** Standard message handling loop with GadTools message handling functions
** used (GT_GetIMsg() and GT_ReplyIMsg()).
*/
VOID process_window_events(struct Window *mywin,
WORD *slider_level, struct Gadget *my_gads[])
{
struct IntuiMessage *imsg;
ULONG imsgClass;
UWORD imsgCode;
struct Gadget *gad;
BOOL terminated = FALSE;

while (!terminated)
{
Wait (1 << mywin->UserPort->mp_SigBit);

/* GT_GetIMsg() returns an IntuiMessage with more friendly information for
** complex gadget classes. Use it wherever you get IntuiMessages where
** using GadTools gadgets.
*/
while ((!terminated) &&
(imsg = IGadTools->GT_GetIMsg(mywin->UserPort)))
{
/* Presuming a gadget, of course, but no harm...
** Only dereference this value (gad) where the Class specifies
** that it is a gadget event.
*/
gad = (struct Gadget *)imsg->IAddress;

imsgClass = imsg->Class;
imsgCode = imsg->Code;

/* Use the toolkit message-replying function here... */
IGadTools->GT_ReplyIMsg(imsg);

switch (imsgClass)
{
/* --- WARNING --- WARNING --- WARNING --- WARNING --- WARNING ---
** GadTools puts the gadget address into IAddress of IDCMP_MOUSEMOVE
** messages. This is NOT true for standard Intuition messages,
** but is an added feature of GadTools.
*/
case IDCMP_GADGETDOWN:
case IDCMP_MOUSEMOVE:
case IDCMP_GADGETUP:
handleGadgetEvent(mywin, gad, imsgCode, slider_level, my_gads);
break;
case IDCMP_VANILLAKEY:
handleVanillaKey(mywin, imsgCode, slider_level, my_gads);
break;
case IDCMP_CLOSEWINDOW:
terminated = TRUE;
break;
case IDCMP_REFRESHWINDOW:
/* With GadTools, the application must use GT_BeginRefresh()
** where it would normally have used BeginRefresh()
*/
IGadTools->GT_BeginRefresh(mywin);
IGadTools->GT_EndRefresh(mywin, TRUE);
break;
}
}
}
}

/*
** Prepare for using GadTools, set up gadgets and open window.
** Clean up and when done or on error.
*/
VOID gadtoolsWindow(VOID)
{
struct TextFont *font;
struct Screen *mysc;
struct Window *mywin;
struct Gadget *glist, *my_gads[4];
void *vi;
WORD slider_level = 5;
UWORD topborder;

/* Open topaz 8 font, so we can be sure it's openable
** when we later set ng_TextAttr to &Topaz80:
*/
if (NULL == (font = IGraphics->OpenFont(&Topaz80)))
errorMessage( "Failed to open Topaz 80");
else
{
if (NULL == (mysc = IIntuition->LockPubScreen(NULL)))
errorMessage( "Couldn't lock default public screen");
else
{
if (NULL == (vi = IGadTools->GetVisualInfo(mysc, TAG_END)))
errorMessage( "GetVisualInfo() failed");
else
{
/* Here is how we can figure out ahead of time how tall the */
/* window's title bar will be: */
topborder = mysc->WBorTop + (mysc->Font->ta_YSize + 1);

if (NULL == createAllGadgets(&glist, vi, topborder,
slider_level, my_gads))
errorMessage( "createAllGadgets() failed");
else
{
if (NULL == (mywin = IIntuition->OpenWindowTags(NULL,
WA_Title, "GadTools Gadget Demo",
WA_Gadgets, glist, WA_AutoAdjust, TRUE,
WA_Width, 400, WA_MinWidth, 50,
WA_InnerHeight, 140, WA_MinHeight, 50,
WA_DragBar, TRUE, WA_DepthGadget, TRUE,
WA_Activate, TRUE, WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE, WA_SimpleRefresh, TRUE,
WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_REFRESHWINDOW |
IDCMP_VANILLAKEY | SLIDERIDCMP | STRINGIDCMP |
BUTTONIDCMP,
WA_PubScreen, mysc,
TAG_END)))
errorMessage( "OpenWindow() failed");
else
{
/* After window is open, gadgets must be refreshed with a
** call to the GadTools refresh window function.
*/
IGadTools->GT_RefreshWindow(mywin, NULL);

process_window_events(mywin, &slider_level, my_gads);

IIntuition->CloseWindow(mywin);
}
}
/* FreeGadgets() even if createAllGadgets() fails, as some
** of the gadgets may have been created...If glist is NULL
** then FreeGadgets() will do nothing.
*/
IGadTools->FreeGadgets(glist);
IGadTools->FreeVisualInfo(vi);
}
IIntuition->UnlockPubScreen(NULL, mysc);
}
IGraphics->CloseFont(font);
}
}

/*
** Open all libraries and run. Clean up when finished or on error..
*/
int main()
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if (IIntuition == NULL)
errorMessage( "Requires V50 intuition.library");
else
{
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);
if (IGraphics == NULL))
errorMessage( "Requires V50 graphics.library");
else
{
struct Library *GadToolsBase = IExec->OpenLibrary("gadtools.library", 50);
IGadTools = (struct GadToolsIFace*)IExec->GetInterface(GadToolsBase, "main", 1, NULL);
if (IGadTools == NULL)
errorMessage( "Requires V50 gadtools.library");
else
{
gadtoolsWindow();

IExec->DropInterface((struct Interface*)IGadTools);
IExec->CloseLibrary(GadToolsBase);
}
IExec->DropInterface((struct Interface*)IGraphics);
IExec->CloseLibrary(GfxBase);
}
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);
}
return 0;
}
</syntaxhighlight>

=== Restrictions on GadTools Gadgets ===

There is a strict set of functions and operations that are permitted on GadTools gadgets. Even if a technique is discovered that works for a particular case, be warned that it cannot be guaranteed and should not be used. If the trick concocted only works most of the time, it may introduce subtle problems in the future.

Never selectively or forcibly refresh gadgets. The only gadget refresh that should ever be performed is the initial GT_RefreshWindow() after a window is opened with GadTools gadgets attached. It is also possible to add gadgets after the window is opened by calling AddGlist() and RefreshGlist() followed by GT_RefreshWindow(). These refresh functions should not be called at any other time.

GadTools gadgets may not overlap with each other, with other gadgets or with other imagery. Doing this to modify the gadget's appearance is not supported.

GadTools gadgets may not be selectively added or removed from a window. This has to do with the number of Intuition gadgets that each call to CreateGadget() produces and with refresh constraints.

Never use OnGadget() or OffGadget() or directly modify the GFLG_DISABLED Flags bit. The only approved way to disable or enable a gadget is to use GT_SetGadgetAttrs() and the GA_Disabled tag. Those kinds of GadTools gadgets that do not support GA_Disabled may not be disabled (for now).

The application should never write into any of the fields of the Gadget structure or any of the structures that hang off it, with the exception noted earlier for GENERIC_KIND gadgets. Avoid making assumptions about the contents of these fields unless they are explicitly programmer fields (GadgetID and UserData, for example) or if they are guaranteed meaningful (Left, Top, Width, Height, Flags). On occasion, the program is specifically invited to read a field, for example the StringInfo->Buffer field.

GadTools gadgets may not be made relative sized or relative positioned. This means that the gadget flags GFLG_RELWIDTH, GFLG_RELHEIGHT, GFLG_RELBOTTOM and GFLG_RELRIGHT may not be specified. The activation type of the gadget may not be modified (for example changing GACT_IMMEDIATE to GACT_RELVERIFY). The imagery or the highlighting method may not be changed.

These restrictions are not imposed without reason; subtle or blatant problems may arise now or in future versions of GadTools for programs that violate these guidelines.

=== Documented Side-Effects ===

There are certain aspects of the behavior of GadTools gadgets that should not be depended on. This will help current applications remain compatible with future releases of the GadTools library.

When using GT_FilterIMsg() and GT_PostFilterIMsg(), never make assumptions about the message before or after filtering. I.e., do not interpret the unfiltered message, assume that it will or will not result in certain kinds of filtered message or assume it will result in a consumed message (i.e., when GT_FilterIMsg() returns NULL).

IDCMP_INTUITICKS messages are consumed when a scroller's arrows are repeating. That is, IDCMP_INTUITICKS will not be received while the user is pressing a scroller arrows. Do not depend or rely on this side effect, though, it will not necessarily remain so in the future.

A single call to CreateGadget() may create one or more actual gadgets. These gadgets, along with the corresponding code in GadTools, define the behavior of the particular kind of GadTools gadget requested. Only the behavior of these gadgets is documented, the number or type of actual gadgets is subject to change. Always refer to the gadget pointer received from CreateGadget() when calling GT_SetGadgetAttrs(). Never refer to other gadgets created by GadTools, nor create code which depends on their number or form.

For text-display gadgets, the GTTX_CopyText tag does not cause the text to be copied when the text is later changed with GTTX_Text.

The PLACETEXT ng_Flags are currently ignored by GENERIC_KIND gadgets. However, this may not always be so.

All GadTools gadgets set GADTOOL_TYPE in the gadget's GadgetType field. Do not use this flag to identify GadTools gadgets, as this flag is not guaranteed to be set in the future.

The palette gadget subdivides its total area into the individual color squares. Do not assume that the subdivision algorithm won't change.

AmigaOS Manual: AmigaDOS Additional Amiga Directories

2017-05-21T15:42:36Z

Rob Cranley: /* Creating a MountFile or MountList Entry */ Fixed typo

In addition to the AmigaDOS commands, there are other files and directories on your Workbench disk. This chapter includes the following:

* DEVS:
* S:
* L:
* FONTS:
* LIBS:
* REXX:
* LOCALE:
* ENVARC:
* ENV:
* CLIPS:
* T:
* Classes
* C:

The drawers contained in DEVS: are described in the Workbench User's Guide .

You do not need a detailed understanding of the contents of the directories listed here. Unless specifically directed otherwise, you can safely ignore them. However, you should know their purposes and locations in case you inadvertently delete or rename a file in a directory or need to copy something to the appropriate directory.

Figure B-1 illustrates the standard directory structure of a hard disk Amiga system. Directories with icons visible from Workbench (drawers) are shown on the left; other directories are on the right. The standard contents and structure of these directories may change as the AmigaOS development team adds, changes, or removes resources.

[[File:DosFigB-1.png|center|frame|System Directory Tree]]

Most of these directories are automatically assigned to the SYS: volume or to the Ram Disk. These directories, as well as SYS:, can be ASSIGNed to different volume when necessary.

For example, you can assign FONTS: to a particular disk, such as FontDisk:. Most applications automatically look for the fonts that they need in the FONTS: directory, regardless of where that is. By changing the FONTS: assignment, you can allow applications to use the fonts on FontDisk:

= DEVS: =

In addition to the DOSDrivers, Keymaps, Printers, Monitors, and DataTypes drawers described in the Workbench User's Guide, the DEVS: drawer contains files and subdirectories that pertain to the devices that can be used with the Amiga.

Note that you can refer to the DEVS:Keymaps and DEVS:Printers drawers by their assigned names KEYMAPS: and PRINTERS:, respectively.

== Device Files ==

The following lists the .device files in DEVS: and their functions:

{| class="wikitable"
| clipboard.device || Controls access to CLIPS:.
|-
| Parallel.device || Controls access to the parallel port.
|-
| printer.device || Controls access to the printer device.
|-
| Serial.device || Controls access to the serial port.
|-
| mfm.device || Controls access to MS-DOS disks with CrossDOS.
|}

For more information on the .device files, see [[Devices|Amiga Devices]].

== Other Files ==

The following additional files are found in DEVS:

{| class="wikitable"
| system-configuration || Holds certain Preferences configuration data needed when booting.
|-
| Postscript_init.ps || Holds information needed to initialize a PostScript printer when using PrinterPS.
|}

=== Using Mount Files or a MountList ===

To access new devices, the Amiga must be informed when any are added. These may be physical devices, such as a tape drive, or software (logical) devices, such as a recoverable RAM disk. There are several ways to do this:

* Placing a driver in the Expansion drawer
* Placing a mount file in the DOSDrivers drawer
* Making an entry for the device in a MountList file and using the MOUNT command

A mount file represents a device, handler, or file system. Standard devices have their own mount file with icons in the DOSDrivers drawer in DEVS:. These are mounted automatically during the standard Startup-sequence. Alternatively, devices can use the MOUNT command to read a MountList entry that determines the characteristics of the device.

The need to use a MountList and the MOUNT command has been eliminated by the mount file method used in Amiga system software Release 2.1 and beyond. Rather than requiring a MountList file with entries for each device you want to mount, DEVS: now contains the DOSDrivers drawer, which holds a separate mount file or DOS driver for each device. The contents of a mount file are essentially the same as an individual MountList entry.

You can, however, continue to use a MountList to mount devices. Copy the MountList to DEVS: and remove any DOS drivers in the DOSDrivers drawers that have the same name as one of your MountList entries. (A mount file overrides a MountList entry of the same name.)

=== Creating a MountFile or MountList Entry ===

The following information on mount files also applies to MountLists, except as noted.

Mount files contain keywords describing the device, handler, or file system, as well as values for those keywords. Some keywords apply only to a file system or a handler. If a keyword is omitted, a default value is used. Be sure that the default value is appropriate for the device.

The following are rules for creating a mount file or MountList:

* The file must be a plain ASCII text file.
* The mount file name must be the name of the device; the name of a MountList should be MountList.
* Each entry in a MountList must start with the name of the device. Omit this for a mount file.
* Keywords are followed by an equals sign (=).
* Keywords must be separated by a semicolon or be placed on separate lines.
* Comments are allowed in standard C style (that is, comments start with /* and end with */).
* Each MountList entry must end with the # symbol. Omit this for a mount file.

When creating a new mount file or MountList entry, refer to the documentation that came with the device or start with an example of one for a similar device. Change or add only the necessary keywords.

The following table, lists keywords and their default values supported in a mount file or MountList and their functions. Default values are shown in angle brackets.

{| class="wikitable"
! Keyword !! Function
|-
| Handler=<none> || A handler entry (for example, Handler = L:eque-handler).
|-
| Ehandler=<none> || An environment handler entry.
|-
| FileSystem=<none> || A file system entry (for example, FileSystem = L:CrossDosFileSystem).
|-
| Device=<none> || A device entry (for example, Device = DEVS:mfm.device). This argument is required to mount a file system. There is no default value for Device; you must supply a value.
|-
| Priority=<10> || The priority of the process; 5 is good for handlers, 10 for file systems.
|-
| Unit=<0> || The unit number of the device (for example, 0 for PC0:).
|-
| Flags=<0> || Flags for OpenDevice (usually 0).
|-
| Surfaces=<none> || The number of surfaces (2 for floppy devices, varies for hard drives). This argument is required to mount a file system. There is no default value for Surfaces; you must supply a value.
|-
| SectorsPerBlock=<none> || Defines the number of physical disk sectors in each logical block used by the file system.
|-
| SectorsPerTrack=<none> || The number of blocks per track. This argument is required to mount a file system. There is no default value for SectorsPerTrack; you must supply a value.
|-
| SectorSize=<512> || Specifies the number of bytes in a block on the device. Most devices use a 512 byte block; however, some devices use other sizes (for example, CD-ROMs use 2048 bytes).
|-
| Reserved=<2> || The number of blocks reserved for the boot block; should be 2.
|-
| Interleave=<0> || Interleave value; varies with the device.
|-
| LowCyl=<none> || Starting cylinder to use. This argument is required to mount a file system. There is no default value for LowCyl; you must supply a value.
|-
| HighCyl_<none> || Ending cylinder to use. This argument is required to mount a file system. There is no default value for HighCyl; you must supply a value.
|-
| Stacksize=<600> || Amount of stack allocated to the process.
|-
| Buffers=<5> || Number of initial 512-byte cache buffers. Increase this for higher disk performance if you have RAM to spare.
|-
| BufMem Type=<3> || Memory type used for buffers; (0 and 1 = Any, 2 and 3 = Chip, 4 and 5 = Fast).
|-
| Mount=<0> || See the description of ACTIVATE, which is a synonym for MOUNT.
|-
| MaxTransfer=<0x7ffffff> || The maximum number of bytes transferred at one time with any file system. Use Max Transfer for compatibility with older hard drive systems.
|-
| Mask=<0xffffffff> || Address Mask to specify memory range that DMA transfers can use at one time with any file system. Use Mask for compatibility with older hard drive systems.
|-
| Glob Vec=<2> || A global vector for the process; -1 is no Global Vector (for C and assembler programs), 0 sets up a private GV; if the keyword is absent, the shared Global Vector is used. Omit this keyword for Amiga file system devices.
|-
| Startup=<none> || A string passed to the device, handler, or file system on startup as a BPTR to a BSTR.
|-
| Activate=<0> || If a positive value, ACTIVATE loads the device or handler immediately rather than waiting for first access. Synonymous with MOUNT.
|-
| BootPri=<0> || A value that sets the boot priority of a bootable and mountable device. This value can range from -129 to 127. By convention, -129 indicates that the device is not bootable and is not automatically mounted.
|-
| DosType=<0x444F5300> || Indicates the type of file system, giving hexadecimal ASCII codes for three letters and a concluding number as follows:
{| class="wikitable"
! Value !! ASCII !! File System
|-
| 0x444F5300 || DOS0 || Original (OFS)
|-
| 0x444F5301 || DOS1 || FastFileSystem (FFS)
|-
| 0x444F5302 || DOS2 || International Mode OFS
|-
| 0x444F5303 || DOS3 || International Mode FFS
|-
| 0x444F5304 || DOS4 || Directory caching International Mode OFS
|-
| 0x444F5305 || DOS5 || Directory caching International Mode FFS
|-
| 0x4D534400 || MSD0 || MS-DOS
|}
|-
| Baud=<1200> || Serial device baud rate.
|-
| Control=<0> || Serial device word length, parity, and stop bits.
|-
| Forceload=<0> || Forces a file system to be loaded form disk even though a suitable entry is in the resource list. If 0 (the default), check the resource list before the disk. If 1, always load from disk.
|}

= S: Directory =

The S: directory is generally reserved for AmigaDOS and ARexx scripts. However, you may place non-script files in S: or place script files in other directories. In addition to the Startup-sequence file, the User-startup file that you create, and Shell-startup files, the S: directory also contains teh scripts described in this section.

== ED-Startup ==

This file contains ED commands used to configure the ED text editor, assigning the default function key options. Key assignments can be customized by editing this file. Removing or renaming this file activates expanded ED command menus; see Chapter 4 for instructions on how to do this.

Other files containing ED commands can be stored in S: for use by the WITH keyword of ED, which allows ED command files to perform custom editing operations.

== SPat, DPat ==

These scripts allow pattern matching with commands that do not normally support it. When run with a command, SPat and DPat use the LIST command to create temporary script files in the T: directory and then execute the scripts. SPat and DPat can be used within command aliases.

SPat adds pattern matching to single-argument commands. For example, to use ED to edit all the files in the S: directory beginning with the letter's, enter:

1> SPat ED S:s#?

A script similiar to the following is generated:

ED "s:Shell-startup"
ED "s:SPat"
ED "s:Startup-sequence"

SPat executes the script, invoking ED three times to display the files.

DPat adds pattern matching to double-argument commands. After DPat and the command name, enter the two arguments separated by a space, using the wildcards required to produce the desired matches.

== PCD ==

Like the CD command, the PCD script changes the current directory. However, PCD also remembers the directory from which you are changing, so you can return to it without entering the entire path. Each Shell has an independent PCD memory.

The first time you use PCD in a given Shell, you must give it the path to a directory. When entered with this path argument, PCD has the same effect as CD, changing to the named directory, but it also stores the path to the directory from which you changed. You can then change the current directory by the usual methods. To return to the initial directory, enter PCD alone. For example:

1.System:> PCD Work:Paint/24bit
1.Work:Paint/24bit> PCD
1.System:>

Subsequent invocations of PCD switch to the directory in which you last used PCD:

1.System:> PCD
1.Work:Paint/24bit> /
1.Work:Paint> PCD
1.System:>

PCD use the assign list to store the remembered directory. When you use PCD, the list contains the assignment from<n> , where <n> is the Shell number. Using PCD with no argument before establishing the first from directory produces an error requester.

For further examples of PCD, see Chapter 8.

= L: Directory =

This directory contains device handlers, which are software modules that go between AmigaDOS and the devices used by the Amiga. However, most handlers are treated as if they are actual physical devices and they are referred to by their device name.

Handlers must be named in the mount file or MountList for their respective devices. Handlers are called and manipulated by programs, not users. New handlers can be supplied with some devices or programs and should be copied to the L: directory.

== Aux-Handler ==

The Aux-handler provides unbuffered serial input and output. It is essentially a console handler that uses the serial port rather than the Amiga screen and keyboard.

The DOSDrivers mount file for AUX is:

Handler = L:Aux-handler
Stacksize = 1000
Priority = 5

You can use Aux-Handler to use a serial terminal with your Amiga. For example:

1> NEWSHELL AUX:

== Queue-Handler (PIPE:) ==

The Queue-Handler is an input/output mechanism used to provide I/O communication between programs. It creates an interprocess communication channel named PIPE. For more information about PIPE:, see Appendix D.

== Port-Handler ==

The Port-Handler is the AmigaDOS interface for the SER:, PAR:, and PRT: devices.

When accessing SER:, you can supply settings for the baud rate and control information. The form for this is SER:<baud/control>, where baud is a number representing the baud rate and where control is a three character sequence indicating the following:

{| class="wikitable"
| Number of read/write bits || First character; either 7 or 8
|-
| Parity || Second character; N (no parity), O (odd parity), E (even parity), M (mark parity), S (space parity)
|-
| Number of stops bits || Third character; either 1 or 2
|}

For example:

SER:9600/8N1

connects to the serial port, sets the baud rate to 9600 with a bit data, no parity, and one stop bit.

If you specify no baud rate or control values when accessing SER:, the values set in the Serial Preferences editor are used.

== CrossDOSFileSystem ==

The CrossDOSFileSystem is required to use CrossDOS.

== FileSystem_Trans ==

The FileSystem_Trans directory contains the following files required for CrossDOS text translation:

{| class="wikitable"
| DANSK.crossdos || Filters Danish text files
|-
| INTL.crossdos || Preserves international characters
|-
| MAC.crossdos || Converts Apple Macintosh ASCII files
|}

== CDFileSystem ==

The CDFileSystem is required to use a CD-ROM drive.

= FONTS: =

FONTS: is the disk or directory that contains the information for all of the different styles of fonts available to the Amiga. Font information is stored differently for bitmap and outline fonts.

== Bitmap Fonts ==

For each bitmap font, there is a subdirectory and a .font file. The font subdirectory contains files for the different point sizes that are available. Each of these files contains the bitmap representation of every character in the font at that point size.

For example, for the Emerald font, there is an Emerald directory and an Emerald.font file. The Emerald directory contains two files: 17 and 20. The files contain the data needed for the 17 point Emerald font and the 20 point Emerald font, respectively. The Emerald.font file contains the list of point sizes and any available styles, such as bold and italics for the font.

Many word processor or desktop publishing programs contain additional fonts that you should copy to your FONTS: directory. After you add new fonts to FONTS:, run the FixFonts program to create the .font file for the new additions.

The Topaz font is the default font used by the Amiga. In addition to existing in FONTS:, Topaz 8 and Topaz 9 are built into ROM so that text can always be displayed; however only Topaz 11 is in the Topaz directory.

== Outline Fonts ==

The Compugraphic Intellifont outline font system used on the Amiga stores font data differently. As with the bitmap fonts, there is a .font file for each typeface. There is also a .otag file for each. The two subdirectories _bullet and _bullet_outlines contain the actual outline information for the typefaces installed on your system. You should not try to manipulate these files directly. Always use the Intellifont program or your applications' font installation tools to manage outline fonts.

= LIBS: Directory =

LIBS: contains libraries of software routines and math functions commonly used by the operating system and applications. The files found in the LIBS: directory are:

{| class="wikitable"
! .library File !! Function
|-
| amigaguide.library || Functions used by the AmigaGuide hypertext system.
|-
| asl.library || File, font, and screen mode requester functions.
|-
| Bullet.library || Library functions for finding and loading outline fonts.
|-
| Commodities.library || Functions used by Commodities Exchange programs.
|-
| datatypes.library || Functions for enabling manipulation ot the file types in DEVS:DataTypes.
|-
| Diskfont.library || Library functions for finding and loading font files.
|-
| iffparse.library || Functions to read IFF files.
|-
| locale.library || Functions for using localization features in the Amiga operating system.
|-
| lowlevel.library || Library to aid in game programming.
|-
| mathieeedoubbas.library || Double-precision IEEE math routine functions for basic functions (addition, subtraction, and so forth).
|-
| mathieeedoubtrans.library || Double-precision IEEE math routine functions for transcendental functions (sine, cosine, and so forth).
|-
| mathieeesingtrans.library || Fast single-precision IEEE math routine functions.
|-
| Mathtrans.library || FFP transcendental function math routine functions.
|-
| Realtime.library || Function to synchronize multimedia events, such as music and animation.
|-
| Rexxsupport.library || Functions used by ARexx.
|-
| Rexxsyslib.library || Main ARexx functions.
|-
| Version.library || Contains current software version and revision information.
|-
| 68040.library || Functions needed on Amigas using the 68040 microprocessor chip.
|}

= REXX: =

REXX: is another name normally assigned to the SYS:S directory in addition to S:. Storing any ARexx programs you write in REXX: allows you to execute them without entering the full path. Create a new directory and reASSIGN REXX: to it if you wish to keep ARexx programs separate from AmigaDOS scripts.

= LOCALE: =

LOCALE: is where the Amiga looks for language and country files when it needs to display non-English text. On floppy systems, LOCALE: is the Locale floppy. On hard disk systems, it is the SYS:Locale directory.

LOCALE: contains four directories:

{| class="wikitable"
| Countries || Contains a .country file for all available countries. These files hold country-specific information, such as date/time format and monetary symbols.
|-
| Languages || Contains .language files for the available languages. These files hold general language-specific information, such as the days of the week.
|-
| Catalogs || Contains subdirectories for the available languages, each of which contains a Sys directory. This directory holds translated text for that language. Catalogs/<language>/Sys holds menu, gadget, and message text for that language.
|-
| Help (HELP:) || Contains subdirectories for the available languages, each of which contains a Sys directory. This directory holds translated text for that language. Help/<language>/Sys is reserved for AmigaGuide text files for any applications that have AmigaGuide help in that language.
|}

= ENVARC: =

ENVARC: is the name assigned to the directory SYS:Prefs/Env-Archive. ENVARC: always contains a Sys directory, in which each of the Preferences editors stores the .prefs file created when you save a setting with its Save gadget. Custom default icons created in IconEdit are also saved here. (Named settings saved with the Save As menu item in an Editor are stored by default in the Prefs/Presets drawer.)

Other Workbench programs that allow you to save configuration settings, such as MultiView, also place their files in ENVARC:

= ENV: =

ENV: is the directory RAM:Env, into which the contents of ENVARC: are copied when booting. Preferences settings activated with Save or Use gadgets are stored in ENV:. Global environment variables are also stored here, as small files.

= CLIPS: =

The directory RAM:Clipboards has the assigned name CLIPS:. It stores information clipped with the Cut or Copy items on a program's Edit menu.

= T: =

T: is the RAM:T directory, which may be used by scripts and some commands for storing miscellaneous temporary files.

= Classes =

The Classes directory stores information related to the object-oriented features of the Workbench, such as the DataTypes system upon which MultiView is based. Classes contains the directories DataTypes and Gadgets.

= C: =

C: is the SYS:C directory, which stores non-internal AmigaDOS commands. It is always in the search path.

GadTools Gadgets

2015-06-24T14:41:47Z

Rob Cranley: /* Documented Side-Effects */ Fix typo/Unicode error on apostrophe

{{CodeReview}}
=== Introduction ===

{{Note|text=GadTools-based GUIs are largely obsolete. Prefer to use a modern BOOPSI-based GUI system instead.}}

The heart of GadTools is in its ability to easily create and manipulate a sophisticated and varied array of gadgets. GadTools supports the following kinds of gadgets:

{| class="wikitable"
|+ Standard Gadget Types Supported by the GadTools Library
! Gadget Type
! Description or Example Usage
|-
| Button
| Familiar action gadgets, such as "OK" or "Cancel".
|-
| String
| For text entry.
|-
| Integer
| For numeric entry.
|-
| Checkboxes
| For on/off items.
|-
| Mutually exclusive
| Radio buttons, select one choice among several.
|-
| Cycle
| Multiple-choice, pick one of a small number of choices.
|-
| Sliders
| To indicate a level within a range.
|-
| Scrollers
| To indicate a position in a list or area.
|-
| Listviews
| Scrolling lists of text.
|-
| Palette
| Color selection.
|-
| Text-display
| Read-only text.
|-
| Numeric-display
| Read-only numbers.
|}

GadTools gadget handling consists of a body of routines to create, manage and delete any of the 12 kinds of standard gadgets listed in the previous table, such as buttons, sliders, mutually exclusive buttons and scrolling lists.

To illustrate the flexibility, power and simplicity that GadTools offers, consider the GadTools slider gadget. This gadget is used to indicate and control the level of something, for example volume, speed or color intensity. Without GadTools, applications have to deal directly with Intuition proportional and their arcane variables, such as HorizBody to control the slider knob's size and HorizPot to control the knob's position. Using the GadTools slider allows direct specification of the minimum and maximum levels of the slider, as well as its current level. For example, a color slider might have a minimum level of 0, a maximum level of 15 and a current level of 11.

To simplify event-processing for the slider, GadTools only sends the application a message when the knob has moved far enough to cause the slider level, as expressed in application terms, to change. If a user were to slowly drag the knob of this color slider all the way to the right, the program will only hear messages for levels 12, 13, 14 and 15, with an optional additional message when the user releases the mouse-button.

Changing the current level of the slider from within the program is as simple as specifying the new level in a function call. For instance, the application might set the slider's value to 5.

As a final point, the slider is very well-behaved. When the user releases the mouse-button, the slider immediately snaps to the centered position for the level. If a user sets their background color to light gray, which might have red = green = blue = 10, all three color sliders will have their knobs at precisely the same relative position, instead of anywhere in the range that means "ten".

==== The NewGadget Structure ====

For most gadgets, the NewGadget structure is used to specify its common attributes. Additional attributes that are unique to specific kinds of gadgets are specified as tags sent to the CreateGadget() function (described below).

The NewGadget structure is defined in <intuition/gadtools.h> as:

<syntaxhighlight>
struct NewGadget
{
WORD ng_LeftEdge, ng_TopEdge;
WORD ng_Width, ng_Height;
UBYTE *ng_GadgetText;
struct TextAttr *ng_TextAttr;
UWORD ng_GadgetID;
ULONG ng_Flags;
APTR ng_VisualInfo;
APTR ng_UserData;
};
</syntaxhighlight>

The fields of the NewGadget structure are used as follows:

; ng_LeftEdge, ng_TopEdge
: Define the position of the gadget being created.

; ng_Width, ng_Height
: Define the size of the gadget being created.

; ng_GadgetText
: Most gadgets have an associated label, which might be the text in a button or beside a checkmark. This field contains a pointer to the appropriate string. Note that only the pointer to the text is copied, the text itself is not. The string supplied must remain constant and valid for the life of the gadget.

; ng_TextAttr
: The application must specify a font to use for the label and any other text that may be associated with the gadget.

: Used to describe general aspects of the gadget, which includes where the label is to be placed and whether the label should be rendered in the highlight color. The label may be positioned on the left side, the right side, centered above, centered below or dead-center on the gadget. For most gadget kinds, the label is placed on the left side by default, exceptions will be noted.

; ng_GadgetID, ng_Flags, ng_UserData
: These user fields are copied into the resulting Gadget structure.

; ng_VisualInfo
: This field must contain a pointer to an instance of the VisualInfo structure, which contains information needed to create and render GadTools gadgets. The VisualInfo structure itself is private to GadTools and subject to change. Use the specialized GadTools functions for accessing the VisualInfo pointer, defined below. Never access or modify fields within this structure.

==== Creating Gadgets ====

The main call used to create a gadget with GadTools is CreateGadget(). This function can be used to create a single gadget or it can be called repeatedly to create a linked list of gadgets. It takes three arguments followed by a set of tags:

<pre>
struct Gadget *CreateGadget( ULONG kind, struct Gadget *prevgad, struct NewGadget *newgad,
struct TagItem *taglist);
struct Gadget *CreateGadgetA(ULONG kind, struct Gadget *prevgad, struct NewGadget *newgad,
Tag tag1, ...);
</pre>

Set the kind argument to one of the 12 gadget types supported by GadTools. Set the prevgad argument to the gadget address returned by CreateContext() if this is the first (or only) gadget in the list. Subsequent calls to CreateGadget() can be used to create and link gadgets together in a list in which case the prevgad argument is set to the address of the gadget returned by the preceding call to CreateGadget().

Set the newgad argument to the address of the NewGadget structure describing the gadget to be created and set any special attributes for this gadget type using the tag arguments, tag1 or taglist. For instance, the following code fragment might be used to create the color slider discussed earlier:

<pre>
slidergad = CreateGadget(SLIDER_KIND, newgadget, prevgad,
GTSL_Min, 0,
GTSL_Max, 15,
GTSL_Level, 11,
TAG_END);
</pre>

CreateGadget() typically allocates and initializes all the necessary Intuition structures, including in this case the Gadget, IntuiText and PropInfo structures, as well as certain buffers. For more about these underlying structures, see [[Intuition_Gadgets|Intuition Gadgets]].

Since CreateGadget() is a tag-based function, it is easy to add more tags to get a fancier gadget. For example, GadTools can optionally display the running level beside the slider. The caller must supply a printf()-style formatting string and the maximum length that the string will resolve to when the number is inserted:

<pre>
slidergad = CreateGadget(SLIDER_KIND, newgadget, prevgad,
GTSL_Min, 0,
GTSL_Max, 15,
GTSL_Level, 11,
GTSL_LevelFormat, "%2ld", /* printf()-style formatting string */
GTSL_MaxLevelLen, 2, /* maximum length of string */
TAG_END);
</pre>

The level, 0 to 15 in this example, would then be displayed beside the slider. The formatting string could instead be "%2ld/15" so the level would be displayed as "0/15" through "15/15".

==== Handling Gadget Messages ====

GadTools gadgets follow the same input model as other Intuition components. When the user operates a GadTools gadget, Intuition notifies the application about the input event by sending an IntuiMessage. The application can get these messages at the Window.UserPort. However GadTools gadgets use different message handling functions to get and reply these messages. Instead of the Exec functions GetMsg() and ReplyMsg(), applications should get and reply these messages through a pair of special GadTools functions, GT_GetIMsg() and GT_ReplyIMsg().

<syntaxhighlight>
struct IntuiMessage *GT_GetIMsg(struct MsgPort *iport);
VOID GT_ReplyIMsg(struct IntuiMessage *imsg);
</syntaxhighlight>

For GT_GetIMsg(), the iport argument should be set to the window's UserPort. For GT_ReplyIMsg(), the imsg argument should be set to a pointer to the IntuiMessage returned by GT_GetIMsg().

These functions ensure that the application only sees the gadget events that concern it and in a desirable form. For example, with a GadTools slider gadget, a message only gets through to the application when the slider's level actually changes and that level can be found in the IntuiMessage's Code field:

<syntaxhighlight>
imsg = IGadTools->GT_GetIMsg(win->UserPort);
object = imsg->IAddress;
class = imsg->Class;
code = imsg->Code;
IGadTools->GT_ReplyIMsg(imsg);
switch (class)
{
case IDCMP_MOUSEMOVE:
if (object == slidergad)
{
IDOS->Printf("Slider at level %ld\n", code);
}
...
break;
...
}
</syntaxhighlight>

In general, the IntuiMessages received from GadTools contain more information in the Code field than is found in regular Intuition gadget messages. Also, when dealing with GadTools a lot of messages (mostly IDCMP_MOUSEMOVEs) do not have to be processed by the application. These are two reasons why dealing with GadTools gadgets is much easier than dealing with regular Intuition gadgets. Unfortunately this processing cannot happen magically, so applications must use GT_GetIMsg() and GT_ReplyIMsg() where they would normally have used GetMsg() and ReplyMsg().

GT_GetIMsg() actually calls GetMsg() to remove a message from the specified window's UserPort. If the message pertains to a GadTools gadget then some dispatching code in GadTools will be called to process the message. What the program will receive from GT_GetIMsg() is actually a copy of the real IntuiMessage, possibly with some supplementary information from GadTools, such as the information typically found in the Code field.

The GT_ReplyIMsg() call will take care of cleaning up and replying to the real IntuiMessage.

{{Note|title=Warning|text=When an IDCMP_MOUSEMOVE message is received from a GadTools gadget, GadTools arranges to have the gadget's pointer in the IAddress field of the IntuiMessage. While this is extremely convenient, it is also untrue of messages from regular Intuition gadgets (described in the [[Intuition_Gadgets|Intuition Gadgets]] chapter). Do not make the mistake of assuming it to be true.}}

This description of the inner workings of GT_GetIMsg() and GT_ReplyIMsg() is provided for understanding only; it is crucial that the program make no assumptions or interpretations about the real IntuiMessage. Any such inferences are not likely to hold true in the future. See the section on documented side-effects for more information.

=== IDCMP Flags ===

The various GadTools gadget types require certain classes of IDCMP messages in order to work. Applications specify these IDCMP classes when the window is opened or later with ModifyIDCMP() (see [[Intuition_Windows|Intuition Windows]] chapter for more on this). Each kind of GadTools gadget requires one or more of these IDCMP classes: IDCMP_GADGETUP, IDCMP_GADGETDOWN, IDCMP_MOUSEMOVE, IDCMP_MOUSEBUTTONS and IDCMP_INTUITICKS. As a convenience, the IDCMP classes required by each kind of gadget are defined in <libraries/gadtools.h>. For example, SLIDERIDCMP is defined to be:

<syntaxhighlight>
#define SLIDERIDCMP (IDCMP_GADGETUP | IDCMP_GADGETDOWN | IDCMP_MOUSEMOVE)
</syntaxhighlight>

{{Note|title=Always OR the IDCMP Flag Bits|text=When specifying the IDCMP classes for a window, never add the flags together, always OR the bits together. Since many of the GadTools IDCMP constants have multiple bits set, adding the values will not lead to the proper flag combination.}}

If a certain kind of GadTools gadget is used, the window must use all IDCMP classes required by that kind of gadget. Do not omit any that are given for that class, even if the application does require the message type.

Because of the way GadTools gadgets are implemented, programs that use them always require notification about window refresh events. Even if the application performs no rendering of its own, it may not use the WFLG_NOCAREREFRESH window flag and must always set IDCMP_REFRESHWINDOW. See the section on "Gadget Refresh Functions" below for more on this.

=== Freeing Gadgets ===

After closing the window, the gadgets allocated using CreateGadget() must be released. FreeGadgets() is a simple call that will free all the GadTools gadgets that it finds, beginning with the gadget whose pointer is passed as an argument.

<pre>
VOID FreeGadgets( struct Gadget *gad );
</pre>

The gad argument is a pointer to the first gadget to be freed. It is safe to call FreeGadgets() with a NULL gadget pointer, the function will then return immediately. Before calling FreeGadgets(), the application must first either remove the gadgets or close the window.

When the gadget passed to FreeGadgets() is the first gadget in a linked list, the function frees all the GadTools gadgets on the list without patching pointers or trying to maintain the integrity of the list. Any non-GadTools gadgets found on the list will not be freed, hence the result will not necessarily form a nice list since any intervening GadTools gadgets will be gone.

See the section on "Creating Gadget Lists" for more information on using linked lists of gadgets.

=== Simple GadTools Gadget Example ===

The example listed here shows how to use the NewGadget structure and the GadTools library functions discussed above to create a simple button gadget.

<pre>
;/* simplegtgadget.c -- execute me to compile me
lc -b1 -cfistq -v -y simplegtgadget
blink FROM LIB:c.o simplegtgadget.o TO simplegtgadget LIB LIB:lc.lib LIB:amiga.lib
quit

Simple example of a GadTools gadget. Compiled with SAS C v5.10a
*/
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/gadgetclass.h>
#include <libraries/gadtools.h>

#include <clib/exec_protos.h>
#include <clib/intuition_protos.h>
#include <clib/gadtools_protos.h>

#include <stdio.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif

/* Gadget defines of our choosing, to be used as GadgetID's. */
#define MYGAD_BUTTON (4)

VOID process_window_events(struct Window *);
VOID gadtoolsWindow(VOID);

struct TextAttr Topaz80 = { "topaz.font", 8, 0, 0, };

struct Library *IntuitionBase;
struct Library *GadToolsBase;

/*
** Open all libraries and run. Clean up when finished or on error..
*/
void main(void)
{
if ( (IntuitionBase = OpenLibrary("intuition.library", 37)) != NULL )
{
if ( (GadToolsBase = OpenLibrary("gadtools.library", 37)) != NULL )
{
gadtoolsWindow();

CloseLibrary(GadToolsBase);
}
CloseLibrary(IntuitionBase);
}
}

/*
** Prepare for using GadTools, set up gadgets and open window.
** Clean up and when done or on error.
*/
VOID gadtoolsWindow(VOID)
{
struct Screen *mysc;
struct Window *mywin;
struct Gadget *glist, *gad;
struct NewGadget ng;
void *vi;

glist = NULL;

if ( (mysc = LockPubScreen(NULL)) != NULL )
{
if ( (vi = GetVisualInfo(mysc, TAG_END)) != NULL )
{
/* GadTools gadgets require this step to be taken */
gad = CreateContext(&glist);

/* create a button gadget centered below the window title */
ng.ng_TextAttr = &Topaz80;
ng.ng_VisualInfo = vi;
ng.ng_LeftEdge = 150;
ng.ng_TopEdge = 20 + mysc->WBorTop + (mysc->Font->ta_YSize + 1);
ng.ng_Width = 100;
ng.ng_Height = 12;
ng.ng_GadgetText = "Click Here";
ng.ng_GadgetID = MYGAD_BUTTON;
ng.ng_Flags = 0;
gad = CreateGadget(BUTTON_KIND, gad, &ng, TAG_END);

if (gad != NULL)
{
if ( (mywin = OpenWindowTags(NULL,
WA_Title, "GadTools Gadget Demo",
WA_Gadgets, glist, WA_AutoAdjust, TRUE,
WA_Width, 400, WA_InnerHeight, 100,
WA_DragBar, TRUE, WA_DepthGadget, TRUE,
WA_Activate, TRUE, WA_CloseGadget, TRUE,
WA_IDCMP, IDCMP_CLOSEWINDOW |
IDCMP_REFRESHWINDOW | BUTTONIDCMP,
WA_PubScreen, mysc,
TAG_END)) != NULL )
{
GT_RefreshWindow(mywin, NULL);

process_window_events(mywin);

CloseWindow(mywin);
}
}
/* FreeGadgets() must be called after the context has been
** created. It does nothing if glist is NULL
*/
FreeGadgets(glist);
FreeVisualInfo(vi);
}
UnlockPubScreen(NULL, mysc);
}
}

/*
** Standard message handling loop with GadTools message handling functions
** used (GT_GetIMsg() and GT_ReplyIMsg()).
*/
VOID process_window_events(struct Window *mywin)
{
struct IntuiMessage *imsg;
struct Gadget *gad;
BOOL terminated = FALSE;

while (!terminated)
{
Wait (1 << mywin->UserPort->mp_SigBit);

/* Use GT_GetIMsg() and GT_ReplyIMsg() for handling */
/* IntuiMessages with GadTools gadgets. */
while ((!terminated) && (imsg = GT_GetIMsg(mywin->UserPort)))
{
/* GT_ReplyIMsg() at end of loop */

switch (imsg->Class)
{
case IDCMP_GADGETUP: /* Buttons only report GADGETUP */
gad = (struct Gadget *)imsg->IAddress;
if (gad->GadgetID == MYGAD_BUTTON)
printf("Button was pressed.\n");
break;
case IDCMP_CLOSEWINDOW:
terminated = TRUE;
break;
case IDCMP_REFRESHWINDOW:
/* This handling is REQUIRED with GadTools. */
GT_BeginRefresh(mywin);
GT_EndRefresh(mywin, TRUE);
break;
}
/* Use the toolkit message-replying function here... */
GT_ReplyIMsg(imsg);
}
}
}
</pre>

=== Modifying Gadgets ===

The attributes of a gadget are set up when the gadget is created. Some of these attributes can be changed later by using the GT_SetGadgetAttrs() function:

<syntaxhighlight>
VOID GT_SetGadgetAttrs (struct Gadget *gad, struct Window *win, struct Requester *req, Tag tag1, ... );
VOID GT_SetGadgetAttrsA(struct Gadget *gad, struct Window *win, struct Requester *req, struct TagItem *taglist);
</syntaxhighlight>

The gad argument specifies the gadget to be changed while the win argument specifies the window the gadget is in. Currently, the req argument is unused and must be set to NULL.

The gadget attributes are changed by passing tag arguments to these functions. The tag arguments can be either a set of TagItems on the stack for GT_SetGadgetAttrs(), or a pointer to an array of TagItems for GT_SetGadgetAttrsA(). The tag items specify the attributes that are to be changed for the gadget. Keep in mind though that not every gadget attribute can be modified this way.

For example, in the slider gadget presented earlier, the level-formatting string may not be changed after the gadget is created. However, the slider's level may be changed to 5 as follows:

<syntaxhighlight>
IGadTools->GT_SetGadgetAttrs(slidergad, win, req,
GTSL_Level, 5,
TAG_END);
<syntaxhighlight>

Here are some other example uses of GT_SetGadgetAttrs() to change gadget attributes after it is created.

<syntaxhighlight>
/* Disable a button gadget */
IGadTools->GT_SetGadgetAttrs(buttongad, win, NULL,
GA_Disabled, TRUE,
TAG_END);

/* Change a slider's range to be 1 to 100, currently at 50 */
IGadTools->GT_SetGadgetAttrs(slidergad, win, NULL,
GTSL_Min, 1,
GTSL_Max, 100,
GTSL_Level, 50,
TAG_END);

/* Add a node to the head of listview's list, and
make it the selected one */
IGadTools->GT_SetGadgetAttrs(listviewgad, win, NULL,
/* detach list before modifying */
GTLV_Labels, ~0,
TAG_END);
IExec->AddHead(&lvlabels, &newnode);
IGadTools->GT_SetGadgetAttrs(listviewgad, win, NULL,
/* re-attach list */
GTLV_Labels, &lvlabels,
GTLV_Selected, 0,
TAG_END);
</syntaxhighlight>

When changing a gadget using these functions, the gadget will automatically update its visuals. No refresh is required, nor should any refresh call be performed.

{{Note|title=Warning|text=The GT_SetGadgetAttrs() functions may not be called inside of a GT_BeginRefresh()/GT_EndRefresh() pair. This is true of Intuition gadget functions generally, including those discussed in the [[Intuition_Gadgets|Intuition Gadgets]] chapter.}}

In the sections that follow all the possible attributes for each kind of gadget are discussed. The tags are also described in the Autodocs for GT_SetGadgetAttrs() in the SDK.

{{Note|title=Important|text=Tags that can only be sent to CreateGadget() and not to GT_SetGadgetAttrs() will be marked as ''create only'' in the discussion that follows. Those that are valid parameters to both functions will be marked as ''create and set''.}}

=== The Kinds of GadTools Gadgets ===

This section discusses the unique features of each kind of gadget supported by the GadTools library.

==== Button Gadgets ====

Button gadgets (BUTTON_KIND) are perhaps the simplest kind of GadTools gadget. Button gadgets may be used for objects like the "OK" and "Cancel" buttons in requesters. GadTools will create a hit-select button with a raised bevelled border. The label supplied will be centered on the button's face. Since the label is not clipped, be sure that the gadget is large enough to contain the text supplied.

Button gadgets recognize only one tag:

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable or ghost the button gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user selects a button gadget, the program will receive an IDCMP_GADGETUP event.

If clicking on a button causes a requester to appear, for example a button that brings up a color requester, then the button text should end in ellipsis (...), as in "Quit..."

==== Text-Entry and Number-Entry Gadgets ====

Text-entry (STRING_KIND) and number-entry (INTEGER_KIND) gadgets are fairly typical Intuition string gadgets. The typing area is contained by a border which is a raised ridge.

Text-entry gadgets accept the following tags:

; GTST_String (STRPTR)
: A pointer to the string to be placed into the text-entry gadget buffer or NULL to get an empty text-entry gadget. The string itself is actually copied into the gadget's buffer. The default is NULL. (Create and set.)

; GTST_MaxChars (UWORD)
: The maximum number of characters that the text-entry gadget should hold. The string buffer that gets created for the gadget will actually be one bigger than this number, in order to hold the trailing NULL. The default is 64. (Create only.)

Number-entry gadgets accept the following tags:

; GTIN_Number (ULONG)
: The number to be placed into the number-entry gadget. The default is zero. (Create and set.)

; GTIN_MaxChars (UWORD)
: The maximum number of digits that the number-entry gadget should hold. The string buffer that gets created for the gadget will actually be one bigger than this, in order to hold the trailing NULL. The default is 10. (Create only.)

Both text-entry and number-entry gadgets, which are collectively called string gadgets, accept these common tags:

; STRINGA_Justification
: This attribute controls the placement of the string or number within its box and can be one of GACT_STRINGLEFT, GACT_STRINGRIGHT or GACT_STRINGCENTER. The default is GACT_STRINGLEFT. (Create only.)

; STRINGA_ReplaceMode (BOOL)
: Set STRINGA_ReplaceMode to TRUE to get a string gadget which is in replace-mode, as opposed to auto-insert mode. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the string gadget, otherwise to FALSE. The default is FALSE. (Create and set.)

; STRINGA_ExitHelp (BOOL)
: Set this attribute to TRUE if the application wants to hear the Help key from within this string gadget. This feature allows the program to hear the press of the Help key in all cases. If TRUE, pressing the help key while this gadget is active will terminate the gadget and send a message. The program will receive an IDCMP_GADGETUP message having a Code value of 0x5F, the rawkey code for Help. Typically, the program will want to reactivate the gadget after performing the help-display. The default is FALSE. (Create only.)

; GA_TabCycle (BOOL)
: If the user types Tab or Shift Tab into a GA_TabCycle gadget, Intuition will activate the next or previous such gadget in sequence. This gives the user easy keyboard control over which text-entry or number-entry gadget is active. Tab moves to the next GA_TabCycle gadget in the gadget list and Shift Tab moves to the previous one. When the user presses Tab or Shift Tab, Intuition will deactivate the gadget and send this program an IDCMP_GADGETUP message with the code field set to 0x09, the ASCII value for a tab. Intuition will then activate the next indicated gadget. Check the shift bits of the qualifier field to learn if Shift Tab was typed. The ordering of the gadgets may only be controlled by the order in which they were added to the window. For special cases, for example, if there is only one string gadget in the window, this feature can be suppressed by specifying the tagitem pair {GA_TabCycle, FALSE}. The default is TRUE. (Create only.)

; GTST_EditHook (struct Hook *)
: Pointer to a custom editing hook for this string or integer gadget. See [[Intuition_Gadgets|Intuition Gadgets]] for more information on string gadget edit-hooks.

As with all Intuition string gadgets, the program will receive an IDCMP_GADGETUP message only when the user presses Enter, Return, Help, Tab or Shift Tab while typing in the gadget. Note that, like Intuition string gadgets, the program will not hear anything if the user deactivates the string gadget by clicking elsewhere. Therefore, it is a good idea to always check the string gadget's buffer before using its contents, instead of just tracking its value as IDCMP_GADGETUP messages are received for this gadget.

Be sure the code is designed so that nothing drastic happens, like closing a requester or opening a file, if the IDCMP_GADGETUP message has a non-zero Code field; the program will want to handle the Tab and Help cases intelligently.

To read the string gadget's buffer, look at the Gadget's StringInfo Buffer:

<syntaxhighlight>
((struct StringInfo *)gad->SpecialInfo)->Buffer
</syntaxhighlight>

To determine the value of an integer gadget, look at the Gadget's StringInfo LongInt in the same way.

Always use the GTST_String or GTIN_Number tags to set these values. Never write to the StringInfo->Buffer or StringInfo->LongInt fields directly.

GadTools string and integer gadgets do not directly support the GA_Immediate property (which would cause Intuition to send an IDCMP_GADGETDOWN event when such a gadget is first selected). However, this property can be very important. Therefore, the following technique can be used to enable this property.

{{Note|title=Warning|text=Note that the technique shown here relies on directly setting flags in a GadTools gadget; this is not normally allowed since it hinders future compatibility. Do not attempt to change other flags or properties of GadTools gadgets except through the defined interfaces of CreateGadgetA() and GT_SetGadgetAttrsA(). Directly modifying flags or properties is legal only when officially sanctioned by the AmigaOS development team.}}

To get the GA_Immediate property, pass the {GA_Immediate, TRUE} tag to CreateGadgetA(). Even though this tag is ignored for string and integer gadgets under V37, this will allow future versions of GadTools to learn of your request in the correct way. Then, under V37 only, set the GACT_IMMEDIATE flag in the gadget's Activation field:

<pre>
gad = CreateGadget( STRING_KIND, gad, &ng,
/* string gadget tags go here */
GTST_...,

/* Add this tag for future GadTools releases */
GA_Immediate, TRUE,
...
TAG_END );

if ( ( gad ) && ( GadToolsBase->lib_Version == 37) )
{
/* Under GadTools V37 only, set this attribute
* directly. Do not set this attribute under
* future versions of GadTools, or for gadgets
* other than STRING_KIND or INTEGER_KIND.
*/
gad->Activation |= GACT_IMMEDIATE;
}
</pre>

==== Checkbox Gadgets ====

Checkboxes (CHECKBOX_KIND) are appropriate for presenting options which may be turned on or off. This kind of gadget consists of a raised box which contains a checkmark if the option is selected or is blank if the option is not selected. Clicking on the box toggles the state of the checkbox.

The width and height of a checkbox are by default not scaled and fixed (CHECKBOXWIDTH by CHECKBOXHEIGHT). To scale a checkbox gadget, set the GTCB_Scaled tag to TRUE, and set the desired width and height in the ng_Width and ng_Height fields of the NewGadget structure.

The checkbox may be controlled with the following tags:

; GTCB_Checked (BOOL)
: Set this attribute to TRUE to set the gadget's state to ''checked''. Set it to FALSE to mark the gadget as ''unchecked''. The default is FALSE. (Create and set.)

; GTCB_Scaled (BOOL)
: Scales the checkbox gadget if set to TRUE. The default is FALSE. (Create and set.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the checkbox, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user selects a checkbox, the program will receive an IntuiMessage with a class of IDCMP_GADGETUP. As this gadget always toggles, the program can easily track the state of the gadget. Feel free to read the gadget->Flags GFLG_SELECTED bit. Note, however, that the Gadget structure itself is not synchronized to the IntuiMessages received. If the user clicks a second time, the GFLG_SELECTED bit can toggle again before the program gets a chance to read it. This is true of any of the dynamic fields of the Gadget structure, and is worth being aware of, although only rarely will an application have to account for it.

==== Mutually-Exclusive Gadgets ====

Use mutually exclusive gadgets (MX_KIND), or ''radio buttons'', when the user must choose only one option from a short list of possibilities. Mutually exclusive gadgets are appropriate when there are a small number of choices, perhaps eight or less.

A set of mutually exclusive gadgets consists of a list of labels and beside each label, a small raised oval that looks like a button. Exactly one of the ovals is recessed and highlighted, to indicate the selected choice. The user can pick another choice by clicking on any of the raised ovals. This choice will become active and the previously selected choice will become inactive. That is, the selected oval will become recessed while the previous one will pop out, like the buttons on a car radio.

Mutually exclusive gadgets recognize these tags:

; GTMX_Labels (STRPTR *)
: A NULL-pointer-terminated array of strings which are to be the labels beside each choice in the set of mutually exclusive gadgets. This array determines how many buttons are created. This array must be supplied to CreateGadget() and may not be changed. The strings themselves must remain valid for the lifetime of the gadget. (Create only.)

; GTMX_Active (UWORD)
: The ordinal number, counting from zero, of the active choice of the set of mutually exclusive gadgets. The default is zero. (Create and set.)

; GTMX_Spacing (UWORD)
: The amount of space, in pixels, that will be placed between successive choices in a set of mutually exclusive gadgets. The default is one. (Create only.)

; GTMX_Scaled (BOOL)
: Indicates whether the mutually exclusive gadget should be scaled or not. The default is FALSE. (Create only.)

; GTMX_TitlePlace (UWORD)
: Where to place the title of the mutually exclusive gadget. The gadget obtains its title from the ng_GadgetText field of the NewGadget structure. The default is no title. (Create only.)
:{| class="wikitable"
| PLACETEXT_LEFT || Right-align text on left side
|-
| PLACETEXT_RIGHT || Left-align text on right side
|-
| PLACETEXT_ABOVE || Center text above
|-
| PLACETEXT_BELOW || Center text below
|}

When the user selects a new choice from a set of mutually exclusive gadgets, the program will receive an IDCMP_GADGETDOWN IntuiMessage. Look in the IntuiMessage's Code field for the ordinal number of the new active selection.

The ng_GadgetText field of the NewGadget structure is used to display the title for mutually exclusive gadgets. The text position specified in ng_Flags determines whether the item labels are placed to the left or the right of the radio buttons themselves. By default, the labels appear on the left. Do not specify PLACETEXT_ABOVE, PLACETEXT_BELOW or PLACETEXT_IN for this kind of gadget.

To scale a mutually exclusive gadget, set the GTMX_Scaled tag to TRUE, and set the desired width and height in the ng_Width and ng_Height fields of the NewGadget structure. The default value of GTMX_Scaled is FALSE, meaning use the default size of MXWIDTH by MXHEIGHT respectively. If you scale mutually exclusive gadgets, you must also set the
GTMX_Spacing tag to NewGadget.ng_TextAttr->ta_YSize + 1 to properly space the buttons with respect to the font.

==== Cycle Gadgets ====

Like mutually exclusive gadgets, cycle gadgets (CYCLE_KIND) allow the user to choose exactly one option from among several.

The cycle gadget appears as a raised rectangular button with a vertical divider near the left side. A circular arrow glyph appears to the left of the divider, while the current choice appears to the right. Clicking on the cycle gadget advances to the next choice, while shift-clicking on it changes it to the previous choice.

Cycle gadgets are more compact than mutually exclusive gadgets, since only the current choice is displayed. They are preferable to mutually exclusive gadgets when a window needs to have several such gadgets as in the PrinterGfx Preferences editor, or when there is a medium number of choices. If the number of choices is much more than about a dozen, it may become too frustrating and inefficient for the user to find the desired choice. In that case, use a listview (scrolling list) instead.

The tags recognized by cycle gadgets are:

; GTCY_Labels (STRPTR *)
: Like GTMX_Labels, this tag is associated with a NULL-pointer-terminated array of strings which are the choices that this gadget allows. This array must be supplied to CreateGadget() and can be changed. The strings themselves must remain valid for the lifetime of the gadget. (Create and set.)

; GTCY_Active (UWORD)
: The ordinal number, counting from zero, of the active choice of the cycle gadget. The default is zero. (Create and set.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the cycle gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user clicks or shift-clicks on a cycle gadget, the program will receive an IDCMP_GADGETUP IntuiMessage. Look in the Code field of the IntuiMessage for the ordinal number of the new active selection.

==== Slider Gadgets ====

Sliders are one of the two kinds of proportional gadgets offered by GadTools. Slider gadgets (SLIDER_KIND) are used to control an amount, a level or an intensity, such as volume or color. Scroller gadgets (SCROLLER_KIND) are discussed below.

Slider gadgets accept the following tags:

; GTSL_Min (WORD)
: The minimum level of a slider. The default is zero. (Create and set.)

; GTSL_Max (WORD)
: The maximum level of a slider. The default is 15. (Create and set.)

; GTSL_Level (WORD)
: The current level of a slider. The default is zero. When the level is at its minimum, the knob will be all the way to the left for a horizontal slider or all the way at the bottom for a vertical slider. Conversely, the maximum level corresponds to the knob being to the extreme right or top. (Create and set.)

; GTSL_LevelFormat (STRPTR)
: The current level of the slider may be displayed in real-time alongside the gadget. To use the level-display feature, the program must be using a monospace font for this gadget.

: GTSL_LevelFormat specifies a printf()-style formatting string used to render the slider level beside the slider (the complete set of formatting options is described in the Exec library function RawDoFmt()). Be sure to use the "l" (long word) modifier for the number. Field-width specifiers may be used to ensure that the resulting string is always of constant width. The simplest would be "%2ld". A 2-digit hexadecimal slider might use "%02lx", which adds leading zeros to the number. Strings with extra text, such as "%3ld hours", are permissible. If this tag is specified, the program must also provide GTSL_MaxLevelLen. By default, the level is not displayed. (Create only.)

; GTSL_MaxLevelLen (UWORD)
: The maximum length of the string that will result from the given level-formatting string. If this tag is specified, the program must also provide GTSL_LevelFormat. By default, the level is not displayed. (Create only.)

; GTSL_LevelPlace
: To choose where the optional display of the level is positioned. It must be one of PLACETEXT_LEFT, PLACETEXT_RIGHT, PLACETEXT_ABOVE or PLACETEXT_BELOW. The level may be placed anywhere with the following exception: the level and the label may not be both above or both below the gadget. To place them both on the same side, allow space in the gadget's label (see the example). The default is PLACETEXT_LEFT. (Create only.)

; GTSL_DispFunc (LONG (*function)(struct Gadget *, WORD))
: Optional function to convert the level for display. A slider to select the number of colors for a screen may operate in screen depth (1 to 5, for instance), but actually display the number of colors (2, 4, 8, 16 or 32). This may be done by providing a GTSL_DispFunc function which returns 1 << level. The function must take a pointer to the Gadget as the first parameter and the level, a WORD, as the second and return the result as a LONG. The default behavior for displaying a level is to do so without any conversion. (Create only.)

; GA_Immediate (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETDOWN IntuiMessage when the user presses the mouse button over the slider. The default is FALSE. (Create only.)

; GA_RelVerify (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETUP IntuiMessage when the user releases the mouse button after using the slider. The default is FALSE. (Create only.)

; PGA_Freedom
: Specifies which direction the knob may move. Set to LORIENT_VERT for a vertical slider or LORIENT_HORIZ for a horizontal slider. The default is LORIENT_HORIZ. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the slider, to FALSE otherwise. The default is FALSE. (Create and set.)

Up to three different classes of IntuiMessage may be received at the port when the user plays with a slider, these are IDCMP_MOUSEMOVE, IDCMP_GADGETUP and IDCMP_GADGETDOWN. The program may examine the IntuiMessage Code field to discover the slider‚Äôs level.

IDCMP_MOUSEMOVE IntuiMessages will be heard whenever the slider's level changes. IDCMP_MOUSEMOVE IntuiMessages will not be heard if the knob has not moved far enough for the level to actually change. For example if the slider runs from 0 to 15 and is currently set to 12, if the user drags the slider all the way up the program will hear no more than three IDCMP_MOUSEMOVEs, one each for 13, 14 and 15.

If {GA_Immediate, TRUE} is specified, then the program will always hear an IDCMP_GADGETDOWN IntuiMessage when the user begins to adjust a slider. If {GA_RelVerify, TRUE} is specified, then the program will always hear an IDCMP_GADGETUP IntuiMessage when the user finishes adjusting the slider. If IDCMP_GADGETUP or IDCMP_GADGETDOWN IntuiMessages are requested, the program will always hear them, even if the level has not changed since the previous IntuiMessage.

Note that the Code field of the IntuiMessage structure is a UWORD, while the slider's level may be negative, since it is a WORD. Be sure to copy or cast the IntuiMessage->Code into a WORD if the slider has negative levels.

If the user clicks in the container next to the knob, the slider level will increase or decrease by one. If the user drags the knob itself, then the knob will snap to the nearest integral position when it is released.

Here is an example of the screen-depth slider discussed earlier:

<pre>
/* NewGadget initialized here. Note the three spaces
* after "Slider:", to allow a blank plus the two digits
* of the level display
*/
ng.ng_Flags = PLACETEXT_LEFT;
ng.ng_GadgetText = "Slider: ";

LONG DepthToColors(struct Gadget *gad, WORD level)
{
return ((WORD)(1 << level));
}

...

gad = CreateGadget(SLIDER_KIND, gad, &ng,
GTSL_Min, 1,
GTSL_Max, 5,
GTSL_Level, current_depth,
GTSL_MaxLevelLen, 2,
GTSL_LevelFormat, "%2ld",
GTSL_DispFunc, DepthToColors,
TAG_END);
</pre>

==== Scroller Gadgets ====

Scrollers (SCROLLER_KIND) bear some similarity to sliders, but are used for a quite different job: they allow the user to adjust the position of a limited view into a larger area. For example, Workbench's windows have scrollers that allow the user to see icons that are outside the visible portion of a window. Another example is a scrolling list in a file requester which has a scroller that allows the user to see different parts of the whole list.

A scroller consists of a proportional gadget and usually also has a pair of arrow buttons.

While the slider deals in minimum, maximum and current level, the scroller understands Total, Visible and Top. For a scrolling list, Total would be the number of items in the entire list, Visible would be the number of lines visible in the display area and Top would be the number of the first line displayed in the visible part of the list. Top would run from zero to Total - Visible. For an area-scroller such as those in Workbench's windows, Total would be the height (or width) of the whole area, Visible would be the visible height (or width) and Top would be the top (or left) edge of the visible part.

Note that the position of a scroller should always represent the position of the visible part of the project and never the position of a cursor or insertion point.

Scrollers respect the following tags:

; GTSC_Top (WORD)
: The top line or position visible in the area that the scroller represents. The default is zero. (Create and set.)

; GTSC_Total (WORD)
: The total number of lines or positions that the scroller represents. The default is zero. (Create and set.)

; GTSC_Visible (WORD)
: The visible number of lines or positions that the scroller represents. The default is two. (Create and set.)

; GTSC_Arrows (UWORD)
: Asks for arrow gadgets to be attached to the scroller. The value supplied will be used as the width of each arrow button for a horizontal scroller or the height of each arrow button for a vertical scroller, the other dimension will be set by GadTools to match the scroller size. It is generally recommend that arrows be provided. The default is no arrows. (Create only.)

; GA_Immediate (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETDOWN IntuiMessage when the user presses the mouse button over the scroller. The default is FALSE. (Create only.)

; GA_RelVerify (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETUP IntuiMessage when the user releases the mouse button after using the scroller. The default is FALSE. (Create only.)

; PGA_Freedom
: Specifies which direction the knob may move. Set to LORIENT_VERT for a vertical scroller or LORIENT_HORIZ for a horizontal scroller. The default is LORIENT_HORIZ. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the scroller, to FALSE otherwise. The default is FALSE. (Create and set.)

The IntuiMessages received for a scroller gadget are the same in nature as those for a slider defined above, including the fact that messages are only heard by the program when the knob moves far enough for the Top value to actually change. The Code field of the IntuiMessage will contain the new Top value of the scroller.

If the user clicks on an arrow gadget, the scroller moves by one unit. If the user holds the button down over an arrow gadget, it repeats.

If the user clicks in the container next to the knob, the scroller will move by one page, which is the visible amount less one. This means that when the user pages through a scrolling list, any pair of successive views will overlap by one line. This helps the user understand the continuity of the list. If the program is using a scroller to pan through an area then there will be an overlap of one unit between successive views. It is recommended that Top, Visible and Total be scaled so that one unit represents about five to ten percent of the visible amount.

==== Listview Gadgets ====

Listview gadgets (LISTVIEW_KIND) are scrolling lists. They consist of a scroller with arrows, an area where the list itself is visible and optionally a place where the current selection is displayed, which may be editable. The user can browse through the list using the scroller or its arrows and may select an entry by clicking on that item.

There are a number of tags that are used with listviews:

; GTLV_Labels (struct List *)
: An Exec list whose nodes' ln_Name fields are to be displayed as items in the scrolling list. If the list is empty, an empty List structure or a NULL value may be used for GTLV_Labels. This tag accepts a value of "~0" to detach the list from the listview, defined below. The default is NULL. (Create and set.)

; GTLV_Top (UWORD)
: The ordinal number of the top item visible in the listview. The default is zero. (Create and set.)

; GTLV_ReadOnly (BOOL)
: Set this to TRUE for a read-only listview, which the user can browse, but not select items from. A read-only listview can be recognized because the list area is recessed, not raised. The default is FALSE. (Create only.)

; GTLV_ScrollWidth (UWORD)
: The width of the scroller to be used in the listview. Any value specified must be reasonably bigger than zero. The default is 16. (Create only.)

; GTLV_ShowSelected (struct Gadget *)
: Use this tag to show the currently selected entry displayed underneath the listview. Set its value to NULL to get a read-only (TEXT_KIND) display of the currently selected entry or set it to a pointer to an already-created GadTools STRING_KIND gadget to allow the user to directly edit the current entry. By default, there is no display of the currently selected entry. (Create only.)

; GTLV_Selected (UWORD)
: Ordinal number of the item to be placed into the display of the current selection under the listview. This tag is ignored if GTLV_ShowSelected is not used. Set it to "~0" to have no current selection. The default is "~0". (Create and set.)

; LAYOUTA_Spacing (UWORD)
: Extra space, in pixels, to be placed between the entries in the listview. The default is zero. (Create only.)

The program will only hear from a listview when the user selects an item from the list. The program will then receive an IDCMP_GADGETUP IntuiMessage. This message will contain the ordinal number of the item within the list that was selected in the Code field of the message. This number is independent of the displayed listview, it is the offset from the start of the list of items.

If the program attaches a display gadget by using the TagItem {GTLV_ShowSelected, NULL}, then whenever the user clicks on an entry in the listview it will be copied into the display gadget.

If the display gadget is to be editable, then the program must first create a GadTools STRING_KIND gadget whose width matches the width of the listview. The TagItem {GTLV_ShowSelected, stringgad} is used to install the editable gadget, where stringgad is the pointer returned by CreateGadget(). When the user selects any entry from the listview, it gets copied into the string gadget. The user can edit the string and the program will hear normal string gadget IDCMP_GADGETUP messages from the STRING_KIND gadget.

The Exec List and its Node structures may not be modified while they are attached to the listview, since the list might be needed at any time. If the program has prepared an entire new list, including a new List structure and all new nodes, it may replace the currently displayed list in a single step by calling GT_SetGadgetAttrs() with the TagItem {GTLV_Labels, newlist}. If the program needs to operate on the list that has already been passed to the listview, it should detach the list by setting the GTLV_Labels attribute to "~0". When done modifying the list, resubmit it by setting GTLV_Labels to once again point to it. This is better than first setting the labels to NULL and later back to the list, since setting GTLV_Labels to NULL will visually clear the listview. If the GTLV_Labels attribute is set to "~0", the program is expected to set it back to something determinate, either a list or NULL, soon after.

The height specified for the listview will determine the number of lines in the list area. When creating a listview, it will be no bigger than the size specified in the NewGadget structure. The size will include the current-display gadget, if any, that has been requested via the GTLV_ShowSelected tag. The listview may end up being less tall than the application asked for, since the calculated height assumes an integral number of lines in the list area.

By default, the gadget label will be placed above the listview. This may be overridden using ng_Flags.

==== Palette Gadgets ====

Palette gadgets (PALETTE_KIND) let the user pick a color from a set of several. A palette gadget consists of a number of colored squares, one for each color available. There may also be an optional indicator square which is filled with the currently selected color. To create a color editor, a palette gadget would be combined with some sliders to control red, green and blue components, for example.

Palette gadgets use the following tags:

; GTPA_Depth (UWORD)
: The number of bitplanes that the palette represents. There will be 1 << depth (2^depth) squares in the palette gadget. The default is one. (Create only.)

; GTPA_Color (UBYTE)
: The selected color of the palette. The default is one. (Create and set.)

; GTPA_ColorOffset (UBYTE)
: The first color to use in the palette. For example, if GTPA_Depth is two and GTPA_ColorOffset is four, then the palette will have squares for colors four, five, six and seven. The default is zero. (Create only.)

; GTPA_IndicatorWidth (UWORD)
: The desired width of the current-color indicator. By specifying this tag, the application is asking for an indicator to be placed to the left of the color selection squares. The indicator will be as tall as the gadget itself. By default there is no indicator. (Create only.)

; GTPA_IndicatorHeight (UWORD)
: The desired height of the current-color indicator. By specifying this tag, the application is asking for an indicator to be placed above the color selection squares. The indicator will be as wide as the gadget itself. By default there is no indicator. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the palette gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

An IDCMP_GADGETUP IntuiMessage will be received when the user selects a color from the palette. The current-color indicator is recessed, indicating that clicking on it has no effect.

If the palette is wide and not tall, use the GTPA_IndicatorWidth tag to put the indicator on the left. If the palette is tall and narrow, put the indicator on top using GTPA_IndicatorHeight.

By default, the gadget's label will go above the palette gadget, unless GTPA_IndicatorWidth is specified, in which case the label will go on the left. In either case, the default may be overridden by setting the appropriate flag in the NewGadget's ng_Flags field.

The size specified for the palette gadget will determine how the area is subdivided to make the individual color squares. The actual size of the palette gadget will be no bigger than the size given, but it can be smaller in order to make the color squares all exactly the same size.

==== Text-Display and Numeric-Display Gadgets ====

Text-display (TEXT_KIND) and numeric-display (NUMBER_KIND) gadgets are read-only displays of information. They are useful for displaying information that is not editable or selectable, while allowing the application to use the GadTools formatting and visuals. Conveniently, the visuals are automatically refreshed through normal GadTools gadget processing. The values displayed may be modified by the program in the same way other GadTools gadgets may be updated.

Text-display and number-display gadgets consist of a fixed label (the one supplied as the NewGadget's ng_GadgetText), as well as a changeable string or number (GTTX_Text or GTNM_Number respectively). The fixed label is placed according to the PLACETEXT_ flag chosen in the NewGadget ng_Flags field. The variable part is aligned to the left-edge of the gadget.

Text-display gadgets recognize the following tags:

; GTTX_Text (STRPTR)
: Pointer to the string to be displayed or NULL for no string. The default is NULL. (Create and set.)

; GTTX_Border (BOOL)
: Set to TRUE to place a recessed border around the displayed string. The default is FALSE. (Create only.)

; GTTX_CopyText (BOOL)
: This flag instructs the text-display gadget to copy the supplied GTTX_Text string instead of using only a pointer to the string. This only works for the value of GTTX_Text set at CreateGadget() time. If GTTX_Text is changed, the new text will be referenced by pointer, not copied. Do not use this tag without a non-NULL GTTX_Text. (Create only.)

Number-display gadgets have the following tags:

; GTNM_Number (LONG)
: The number to be displayed. The default is zero. (Create or set.)

; GTNM_Border (BOOL)
: Set to TRUE to place a recessed border around the displayed number. The default is FALSE. (Create only.)

Since they are not selectable, text-display and numeric-display gadgets never cause IntuiMessages to be sent to the application.

==== Generic Gadgets ====

If the application requires a specialized gadget which does not fit into any of the defined GadTools kinds but would still like to use the GadTools gadget creation and deletion functions, it may create a GadTools generic gadget and use it any way it sees fit. In fact, all of the kinds of GadTools gadgets are created out of GadTools GENERIC_KIND gadgets.

The gadget that gets created will heed almost all the information contained in the NewGadget structure supplied.

If ng_GadgetText is supplied, the gadget's GadgetText will point to an IntuiText structure with the provided string and font. However, do not specify any of the PLACETEXT ng_Flags, as they are currently ignored by GENERIC_KIND gadgets. PLACETEXT flags may be supported by generic GadTools gadgets in the future.

It is up to the program to set the Flags, Activation, GadgetRender, SelectRender, MutualExclude and SpecialInfo fields of the Gadget structure.

The application must also set the GadgetType field, but be certain to preserve the bits set by CreateGadget().

For instance, to make a gadget boolean, use:

<pre>
gad->GadgetType |= GTYP_BOOLGADGET;
</pre>

and not

<pre>
gad->GadgetType = GTYP_BOOLGADGET;
</pre>

Using direct assignment, (the = operator), clears all other flags in the GadgetType field and the gadget may not be properly freed by FreeGadgets().

=== Functions for Setting up GadTools Menus and Gadgets ===

This section gives all the details on the functions used to set up GadTools menus and gadgets that were mentioned briefly earlier in this chapter.

==== GetVisualInfo() and FreeVisualInfo() ====

In order to ensure their best appearance, GadTools gadgets and menus need information about the screen on which they will appear. Before creating any GadTools gadgets or menus, the program must get this information using the GetVisualInfo() call.

<syntaxhighlight>
APTR GetVisualInfoA( struct Screen *screen, struct TagItem *taglist );
APTR GetVisualInfo( struct Screen *screen, Tag tag1, ... );
</syntaxhighlight>

Set the screen argument to a pointer to the screen you are using. The tag arguments, tag1 or taglist, are reserved for future extensions. Currently none are recognized, so only TAG_END should be used.

The function returns an abstract handle called the VisualInfo. For GadTools gadgets, the ng_VisualInfo field of the NewGadget structure must be set to this handle before the gadget can be added to the window. GadTools menu layout and creation functions also require the VisualInfo handle as an argument.

There are several ways to get the pointer to the screen on which the window will be opened. If the application has its own custom screen, this pointer is known from the call to OpenScreen() or OpenScreenTags(). If the application already has its window opened on the Workbench or some other public screen, the screen pointer can be found in Window.WScreen. Often the program will create its gadgets and menus before opening the window. In this case, use LockPubScreen() to get a pointer to the desired public screen, which also provides a lock on the screen to prevent it from closing. See [[Intuition_Screens|Intuition Screens]] and [[Intuition_Windows|Intuition Windows]] for more about public screens.

The VisualInfo data must be freed after all the gadgets and menus have been freed but before releasing the screen. Custom screens are released by calling CloseScreen(), public screens are released by calling CloseWindow() or UnlockPubScreen(), depending on the technique used. Use FreeVisualInfo() to free the visual info data.

<syntaxhighlight>
VOID FreeVisualInfo( APTR vi );
</syntaxhighlight>

This function takes just one argument, the VisualInfo handle as returned by GetVisualInfo(). The sequence of events for using the VisualInfo handle could look like this:

<syntaxhighlight>
void init()
{
myscreen = IIntuition->LockPubScreen(NULL);
if (!myscreen)
{
cleanup("Failed to lock default public screen");
}
vi = IGadTools->GetVisualInfo(myscreen);
if (!vi)
{
cleanup("Failed to GetVisualInfo");
}
/* Create gadgets here */
ng.ng_VisualInfo = vi;
...
}

void cleanup(STRPTR errorstr)
{
/* These functions may be safely called with a NULL parameter: */
IGadTools->FreeGadgets(glist);
IGadTools->FreeVisualInfo(vi);

if (myscreen)
IIntuition->UnlockPubScreen(NULL, myscreen);

IDOS->Printf(errorstr);
}
</syntaxhighlight>

==== CreateContext() ====

Use of GadTools gadgets requires some per-window context information. CreateContext() establishes a place for that information to go. This function must be called before any GadTools gadgets are created.

<syntaxhighlight>
struct Gadget *CreateContext( struct Gadget **glistptr );
</syntaxhighlight>

The glistptr argument is a double-pointer to a Gadget structure. More specifically, this is a pointer to a NULL-initialized pointer to a Gadget structure.

The return value of CreateContext() is a pointer to this gadget, which should be fed to the program's first call to CreateGadget(). This pointer to the Gadget structure returned by CreateContext(), may then serve as a handle to the list of gadgets as they are created. The code fragment listed in the next section shows how to use CreateContext() together with CreateGadget() to make a linked list of GadTools gadgets.

=== Creating Gadget Lists ===

In the discussion of CreateGadget() presented earlier, the examples showed only how to make a single gadget. For most applications that use GadTools, however, a whole list of gadgets will be needed. To do this, the application could use code such as this:

<pre>
struct NewGadget *newgad1, *newgad2, *newgad3;
struct Gadget *glist = NULL;
struct Gadget *pgad;

...
/* Initialize NewGadget structures */
...

/* Note that CreateContext() requires a POINTER to a NULL-initialized
* pointer to struct Gadget:
*/
pgad = CreateContext(&glist);

pgad = CreateGadget(BUTTON_KIND, pgad, newgad1, TAG_END);
pgad = CreateGadget(STRING_KIND, pgad, newgad2, TAG_END);
pgad = CreateGadget(MX_KIND, pgad, newgad3, TAG_END);

if (!pgad)
{
FreeGadgets(glist);
exit_error();
}
else
{
if ( mywin=OpenWindowTags(NULL,
WA_Gadgets, glist,
...
/* Other tags... */
...
TAG_END) )
{
/* Complete the rendering of the gadgets */
GT_RefreshWindow(win, NULL);
...
/* and continue on... */
...
CloseWindow(mywin);
}

FreeGadgets(glist);
}
</pre>

The pointer to the previous gadget, pgad in the code fragment above, is used for three purposes. First, when CreateGadget() is called multiple times, each new gadget is automatically linked to the previous gadget's NextGadget field, thus creating a gadget list. Second, if one of the gadget creations fails (usually due to low memory, but other causes are possible), then for the next call to CreateGadget(), pgad will be NULL and CreateGadget() will fail immediately. This means that the program can perform several successive calls to CreateGadget() and only have to check for failure at the end.

Finally, although this information is hidden in the implementation and not important to the application, certain calls to CreateGadget() actually cause several Intuition gadgets to be allocated and these are automatically linked together without program interaction, but only if a previous gadget pointer is supplied. If several gadgets are created by a single CreateGadget() call, they work together to provide the functionality of a single GadTools gadget. The application should always act as though the gadget pointer returned by CreateGadget() points to a single gadget instance. See "Documented Side-Effects" for a warning.

There is one exception to the fact that a program only has to check for failure after the last CreateGadget() call and that is when the application depends on the successful creation of a gadget and caches or immediately uses the gadget pointer returned by CreateGadget().

For instance, if the program wants to create a string gadget and save a pointer to the string buffer, it might do so as follows:

<pre>
gad = CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "Hello World",
TAG_END);
if (gad)
{
stringbuffer = ((struct StringInfo *)(gad->SpecialInfo))->Buffer;
}

/* Creation can continue here: */
gad = CreateGadget(..._KIND, gad, &ng2,
...
TAG_END);
</pre>

A major benefit of having a reusable NewGadget structure is that often many fields do not change and some fields change incrementally. For example, the application can set just the NewGadget's ng_VisualInfo and ng_TextAttr only once and never have to modify them again even if the structure is reused to create many gadgets. A set of similar gadgets may share size and some positional information so that code such as the following might be used:

<syntaxhighlight>
/* Assume that the NewGadget structure 'ng' is fully
* initialized here for a button labelled "OK"
*/
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng,
TAG_END);

/* Modify only those fields that need to change: */
ng.ng_GadgetID++;
ng.ng_LeftEdge += 80;
ng.ng_GadgetText = "Cancel";
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng,
TAG_END);
</syntaxhighlight>

{{Note|title=Warning|text=All gadgets created by GadTools currently have the GADTOOL_TYPE bit set in their GadgetType field. It is not correct to check for, set, clear or otherwise rely on this since it is subject to change.}}

=== Gadget Refresh Functions ===

Normally, GadTools gadgets are created and then attached to a window when the window is opened, either through the WA_FirstGadget tag or the NewWindow.FirstGadget field. Alternately, they may be added to a window after it is open by using the functions AddGList() and RefreshGList().

Regardless of which way gadgets are attached to a window, the program must then call the GT_RefreshWindow() function to complete the rendering of GadTools gadgets. This function takes two arguments.

<pre>
VOID GT_RefreshWindow( struct Window *win, struct Requester *req );
</pre>

This win argument is a pointer to the window that contains the GadTools gadgets. The req argument is currently unused and should be set to NULL. This function should only be called immediately after adding GadTools gadgets to a window. Subsequent changes to GadTools gadget imagery made through calls to GT_SetGadgetAttrs() will be automatically performed by GadTools when the changes are made. (There is no need to call GT_RefreshWindow() in that case.)

As mentioned earlier, applications must always ask for notification of window refresh events for any window that uses GadTools gadgets. When the application receives an IDCMP_REFRESHWINDOW message for a window, Intuition has already refreshed its gadgets. Normally, a program would then call Intuition's BeginRefresh(), perform its own custom rendering operations, and finally call EndRefresh(). But for a window that uses GadTools gadgets, the application must call GT_BeginRefresh() and GT_EndRefresh() in place of BeginRefresh() and EndRefresh(). This allows the the GadTools gadgets to be fully refreshed.

<pre>
VOID GT_BeginRefresh( struct Window *win );
VOID GT_EndRefresh ( struct Window *win, LONG complete );
</pre>

For both functions, the win argument is a pointer to the window to be refreshed. For GT_EndRefresh(), set the complete argument to TRUE if refreshing is complete, set it to FALSE otherwise. See the discussion of BeginRefresh() and EndRefresh() in [[Intuition_Windows|Intuition Windows]] for more about window refreshing.

When using GadTools gadgets, the program may not set the window's WFLG_NOCAREREFRESH flag. Even if there is no custom rendering to be performed, GadTools gadgets requires this minimum code to handle IDCMP_REFRESHWINDOW messages:

<pre>
case IDCMP_REFRESHWINDOW:
GT_BeginRefresh(win);
/* custom rendering, if any, goes here */
GT_EndRefresh(win, TRUE);
break;
</pre>

=== Other GadTools Functions ===

This section discusses some additional support functions in the GadTools library that serve special needs.

==== GT_FilterIMsg() and GT_PostFilterIMsg() ====

For most GadTools programs, GT_GetIMsg() and GT_ReplyIMsg() work perfectly well. In rare cases an application may find they pose a bit of a problem. A typical case is when all messages are supposed to go through a centralized ReplyMsg() that cannot be converted to a GT_ReplyIMsg(). Since calls to GT_GetIMsg() and GT_ReplyIMsg() must be paired, there would be a problem.

For such cases, the GT_FilterIMsg() and GT_PostFilterIMsg() functions are available. These functions allow GetMsg() and ReplyMsg() to be used in a way that is compatible with GadTools.

{{Note|title=Warning|text=These functions are for specialized use only and will not be used by the majority of applications. See GT_GetIMsg() and GT_ReplyIMsg() for standard message handling.}}

<syntaxhighlight>
struct IntuiMessage *GT_FilterIMsg( struct IntuiMessage *imsg );
struct IntuiMessage *GT_PostFilterIMsg( struct IntuiMessage *imsg );
</syntaxhighlight>

The GT_FilterIMsg() function should be called right after GetMsg(). It takes a pointer to the original IntuiMessage and, if the message applies to a GadTools gadget, returns either a modified IntuiMessage or a NULL. A NULL return signifies that the message was consumed by a GadTools gadget (and not needed by the application).

The GT_PostFilterIMsg() function should be called before replying to any message modified by GT_FilterIMsg(). It takes a pointer to the modified version of an IntuiMessage obtained with GT_FilterIMsg() and returns a pointer to the original IntuiMessage.

The typical calling sequence for a program that uses these functions, is to call GetMsg() to get the IntuiMessage. Then, if the message applies to a window which contains GadTools gadgets, call GT_FilterIMsg(). Any message returned by GT_FilterIMsg() should be used like a message returned from GT_GetIMsg().

When done with the message, the application must call GT_PostFilterIMsg() to perform any clean up necessitated by the previous call to GT_FilterIMsg(). In all cases, the application ''must'' then reply the original IntuiMessage using ReplyMsg(). This is true even for consumed messages as these are ''not'' replied by GadTools. For example, the application could use code such as this:

<syntaxhighlight>
/* port is a message port receiving different messages */
/* gtwindow is the window that contains GadTools gadgets */

imsg = IExec->GetMsg(port);

/* Is this the window with GadTools gadgets? */
if (imsg->IDCMPWindow == gtwindow)
{
/* Filter the message and see if action is needed */
if (gtimsg = IGadTools->GT_FilterIMsg(imsg))
{
switch (gtimsg->Class)
{
/* Act depending on the message */
...
}
/* Clean up the filtered message. The return value is not needed */
/* since we already have a pointer to the original message. */
IGadTools->GT_PostFilterIMsg(gtimsg);
}
}
/* other stuff can go here */
IExec->ReplyMsg(imsg);
</syntaxhighlight>

You should not make any assumptions about the contents of the unfiltered IntuiMessage (imsg in the above example). Only two things are guaranteed: the unfiltered IntuiMessage must be replied to and the unfiltered IntuiMessage (if it produces anything when passed through GT_FilterIMsg()) will produce a meaningful GadTools IntuiMessage like those described in the section on the different kinds of gadgets. The relationship between the unfiltered and filtered messages are expected to change in the future. See the section on documented side-effects for more information.

==== DrawBevelBox() ====

A key visual signature shared by most GadTools gadgets is the raised or recessed beveled box imagery. Since the program may wish to create its own boxes to match, GadTools provides the DrawBevelBox() and DrawBevelBoxA() functions.

<pre>
VOID DrawBevelBoxA( struct RastPort *rport, LONG left, LONG top, LONG width, LONG height,
struct TagItem *taglist );
VOID DrawBevelBox ( struct RastPort *rport, LONG left, LONG top, LONG width, LONG height,
Tag tag1, ... );
</pre>

The rport argument is a pointer to the RastPort into which the box is to be rendered. The left, top, width and height arguments specify the dimensions of the desired box.

The tag arguments, tag1 or taglist, may be set as follows:

; GT_VisualInfo (APTR)
: The VisualInfo handle as returned by a prior call to GetVisualInfo(). This value is required.

; GTBB_Recessed (BOOL)
: A beveled box may either appear to be raised to signify an area of the window that is selectable or recessed to signify an area of the window in which clicking will have no effect. Set this boolean tag to TRUE to get a recessed box. Omit this tag entirely to get a raised box.

DrawBevelBox() is a rendering operation, not a gadget. This means that the program must refresh any beveled boxes rendered through this function if the window gets damaged.

=== Gadget Keyboard Equivalents ===

Often, users find it convenient to control gadgets using the keyboard. The keyboard equivalent will be an underscored character in the gadget label, for easy identification. At the present time, however, the application is still responsible for implementing the reaction to each keypress.

==== Denoting a Gadget's Keyboard Equivalent ====

In order to denote the key equivalent, the application may add a marker-symbol to the gadget label. This is done by placing the marker-symbol immediately before the character to be underscored. This symbol can be any character that is not used in the label. The underscore character, "_" is the recommended marker-symbol. So, for example, to mark the letter "F" as the keyboard equivalent for a button labelled "Select Font ...", create the gadget text:

<pre>
ng.ng_GadgetText = "Select _Font ...";
</pre>

To inform GadTools of the underscore in the label, pass the GA_Underscore tag to CreateGadget() or CreateGadgetA(). The data-value associated with this tag is a character, not a string, which is the marker-symbol used in the gadget label:

<pre>
GA_Underscore, '_', /* Note '_', not "_" !!! */
</pre>

GadTools will create a gadget label which consists of the text supplied with the marker-symbol removed and the character following the marker-symbol underscored.

The gadget's label would look something like:

<pre>
Select Font ...
</pre>

==== Implementing a Gadget's Keyboard Equivalent Behavior ====

Currently, GadTools does not process keyboard equivalents for gadgets. It is up to the application writer to implement the correct behavior, normally by calling GT_SetGadgetAttrs() on the appropriate gadget. For some kinds of gadget, the behavior should be the same regardless of whether the keyboard equivalent was pressed with or without the shift key. For other gadgets, shifted and unshifted keystrokes will have different, usually opposite, effects.

Here is the correct behavior for keyboard equivalents for each kind of GadTools gadget:

; Button Gadgets
: The keyboard equivalent should invoke the same function that clicking on the gadget does. There is currently no way to highlight the button visuals programmatically when accessing the button through a keyboard equivalent.

; Text-Entry and Number-Entry Gadgets
: The keyboard equivalent should activate the gadget so the user may type into it. Use Intuition's ActivateGadget() call.

; Checkbox Gadgets
: The keyboard equivalent should toggle the state of the checkbox. Use GT_SetGadgetAttrs() and the GTCB_Checked tag.

; Mutually-Exclusive Gadgets
: The unshifted keystroke should activate the next choice, wrapping around from the last to the first. The shifted keystroke should activate the previous choice, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTMX_Active tag.

; Cycle Gadgets
: The unshifted keystroke should activate the next choice, wrapping around from the last to the first. The shifted keystroke should activate the previous choice, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTCY_Active tag.

; Slider Gadgets
: The unshifted keystroke should increase the slider's level by one, stopping at the maximum, while the shifted keystroke should decrease the level by one, stopping at the minimum. Use GT_SetGadgetAttrs() and the GTSL_Level tag.

; Scroller Gadgets
: The unshifted keystroke should increase the scroller's top by one, stopping at the maximum, while the shifted keystroke should decrease the scroller's top by one, stopping at the minimum. Use GT_SetGadgetAttrs() and the GTSC_Top tag.

; Listview Gadgets
: The unshifted keystroke should cause the next entry in the list to become the selected one, stopping at the last entry, while the shifted keystroke should cause the previous entry in the list to become the selected one, stopping at the first entry. Use GT_SetGadgetAttrs() and the GTLV_Top and GTLV_Selected tags.

; Palette Gadgets
: The unshifted keystroke should select the next color, wrapping around from the last to the first. The shifted keystroke should activate the previous color, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTPA_Color tag.

; Text-Display and Number-Display Gadgets
: These kinds of GadTools gadget have no keyboard equivalents since they are not selectable.

; Generic Gadgets
: Define appropriate keyboard functions based on the kinds of keyboard behavior defined for other GadTools kinds.

=== Complete GadTools Gadget Example ===

Here's a working example showing how to set up and use a linked list of GadTools gadgets complete with keyboard shortcuts.

<pre>
/* gadtoolsgadgets.c
** Simple example of using a number of gadtools gadgets.
**
** Compiled with SAS C v5.10a
** lc -b1 -cfistq -v -y gadtoolsgadgets
** blink FROM LIB:c.o gadtoolsgadgets.o TO gadtoolsgadgets LIB LIB:lc.lib LIB:amiga.lib
*/
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/gadgetclass.h>
#include <libraries/gadtools.h>

#include <clib/exec_protos.h>
#include <clib/graphics_protos.h>
#include <clib/intuition_protos.h>
#include <clib/gadtools_protos.h>

#include <stdio.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif

/* Gadget defines of our choosing, to be used as GadgetID's,
** also used as the index into the gadget array my_gads[].
*/
#define MYGAD_SLIDER (0)
#define MYGAD_STRING1 (1)
#define MYGAD_STRING2 (2)
#define MYGAD_STRING3 (3)
#define MYGAD_BUTTON (4)

/* Range for the slider: */
#define SLIDER_MIN (1)
#define SLIDER_MAX (20)

struct TextAttr Topaz80 = { "topaz.font", 8, 0, 0, };

struct Library *IntuitionBase;
struct Library *GfxBase;
struct Library *GadToolsBase;

/* Print any error message. We could do more fancy handling (like
** an EasyRequest()), but this is only a demo.
*/
void errorMessage(STRPTR error)
{
if (error)
printf("Error: %s\n", error);
}

/*
** Function to handle a GADGETUP or GADGETDOWN event. For GadTools gadgets,
** it is possible to use this function to handle MOUSEMOVEs as well, with
** little or no work.
*/
VOID handleGadgetEvent(struct Window *win, struct Gadget *gad, UWORD code,
WORD *slider_level, struct Gadget *my_gads[])
{
switch (gad->GadgetID)
{
case MYGAD_SLIDER:
/* Sliders report their level in the IntuiMessage Code field: */
printf("Slider at level %ld\n", code);
*slider_level = code;
break;
case MYGAD_STRING1:
/* String gadgets report GADGETUP's */
printf("String gadget 1: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_STRING2:
/* String gadgets report GADGETUP's */
printf("String gadget 2: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_STRING3:
/* String gadgets report GADGETUP's */
printf("String gadget 3: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_BUTTON:
/* Buttons report GADGETUP's (button resets slider to 10) */
printf("Button was pressed, slider reset to 10.\n");
*slider_level = 10;
GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
}
}

/*
** Function to handle vanilla keys.
*/
VOID handleVanillaKey(struct Window *win, UWORD code,
WORD *slider_level, struct Gadget *my_gads[])
{
switch (code)
{
case 'v':
/* increase slider level, but not past maximum */
if (++*slider_level > SLIDER_MAX)
*slider_level = SLIDER_MAX;
GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'V':
/* decrease slider level, but not past minimum */
if (--*slider_level < SLIDER_MIN)
*slider_level = SLIDER_MIN;
GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'c':
case 'C':
/* button resets slider to 10 */
*slider_level = 10;
GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'f':
case 'F':
ActivateGadget(my_gads[MYGAD_STRING1], win, NULL);
break;
case 's':
case 'S':
ActivateGadget(my_gads[MYGAD_STRING2], win, NULL);
break;
case 't':
case 'T':
ActivateGadget(my_gads[MYGAD_STRING3], win, NULL);
break;
}
}

/*
** Here is where all the initialization and creation of GadTools gadgets
** take place. This function requires a pointer to a NULL-initialized
** gadget list pointer. It returns a pointer to the last created gadget,
** which can be checked for success/failure.
*/
struct Gadget *createAllGadgets(struct Gadget **glistptr, void *vi,
UWORD topborder, WORD slider_level, struct Gadget *my_gads[])
{
struct NewGadget ng;
struct Gadget *gad;

/* All the gadget creation calls accept a pointer to the previous gadget, and
** link the new gadget to that gadget's NextGadget field. Also, they exit
** gracefully, returning NULL, if any previous gadget was NULL. This limits
** the amount of checking for failure that is needed. You only need to check
** before you tweak any gadget structure or use any of its fields, and finally
** once at the end, before you add the gadgets.
*/

/* The following operation is required of any program that uses GadTools.
** It gives the toolkit a place to stuff context data.
*/
gad = CreateContext(glistptr);

/* Since the NewGadget structure is unmodified by any of the CreateGadget()
** calls, we need only change those fields which are different.
*/
ng.ng_LeftEdge = 140;
ng.ng_TopEdge = 20+topborder;
ng.ng_Width = 200;
ng.ng_Height = 12;
ng.ng_GadgetText = "_Volume: ";
ng.ng_TextAttr = &Topaz80;
ng.ng_VisualInfo = vi;
ng.ng_GadgetID = MYGAD_SLIDER;
ng.ng_Flags = NG_HIGHLABEL;

my_gads[MYGAD_SLIDER] = gad = CreateGadget(SLIDER_KIND, gad, &ng,
GTSL_Min, SLIDER_MIN,
GTSL_Max, SLIDER_MAX,
GTSL_Level, slider_level,
GTSL_LevelFormat, "%2ld",
GTSL_MaxLevelLen, 2,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_Height = 14;
ng.ng_GadgetText = "_First:";
ng.ng_GadgetID = MYGAD_STRING1;
my_gads[MYGAD_STRING1] = gad = CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "Try pressing",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_GadgetText = "_Second:";
ng.ng_GadgetID = MYGAD_STRING2;
my_gads[MYGAD_STRING2] = gad = CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "TAB or Shift-TAB",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_GadgetText = "_Third:";
ng.ng_GadgetID = MYGAD_STRING3;
my_gads[MYGAD_STRING3] = gad = CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "To see what happens!",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_LeftEdge += 50;
ng.ng_TopEdge += 20;
ng.ng_Width = 100;
ng.ng_Height = 12;
ng.ng_GadgetText = "_Click Here";
ng.ng_GadgetID = MYGAD_BUTTON;
ng.ng_Flags = 0;
gad = CreateGadget(BUTTON_KIND, gad, &ng,
GT_Underscore, '_',
TAG_END);
return(gad);
}

/*
** Standard message handling loop with GadTools message handling functions
** used (GT_GetIMsg() and GT_ReplyIMsg()).
*/
VOID process_window_events(struct Window *mywin,
WORD *slider_level, struct Gadget *my_gads[])
{
struct IntuiMessage *imsg;
ULONG imsgClass;
UWORD imsgCode;
struct Gadget *gad;
BOOL terminated = FALSE;

while (!terminated)
{
Wait (1 << mywin->UserPort->mp_SigBit);

/* GT_GetIMsg() returns an IntuiMessage with more friendly information for
** complex gadget classes. Use it wherever you get IntuiMessages where
** using GadTools gadgets.
*/
while ((!terminated) &&
(imsg = GT_GetIMsg(mywin->UserPort)))
{
/* Presuming a gadget, of course, but no harm...
** Only dereference this value (gad) where the Class specifies
** that it is a gadget event.
*/
gad = (struct Gadget *)imsg->IAddress;

imsgClass = imsg->Class;
imsgCode = imsg->Code;

/* Use the toolkit message-replying function here... */
GT_ReplyIMsg(imsg);

switch (imsgClass)
{
/* --- WARNING --- WARNING --- WARNING --- WARNING --- WARNING ---
** GadTools puts the gadget address into IAddress of IDCMP_MOUSEMOVE
** messages. This is NOT true for standard Intuition messages,
** but is an added feature of GadTools.
*/
case IDCMP_GADGETDOWN:
case IDCMP_MOUSEMOVE:
case IDCMP_GADGETUP:
handleGadgetEvent(mywin, gad, imsgCode, slider_level, my_gads);
break;
case IDCMP_VANILLAKEY:
handleVanillaKey(mywin, imsgCode, slider_level, my_gads);
break;
case IDCMP_CLOSEWINDOW:
terminated = TRUE;
break;
case IDCMP_REFRESHWINDOW:
/* With GadTools, the application must use GT_BeginRefresh()
** where it would normally have used BeginRefresh()
*/
GT_BeginRefresh(mywin);
GT_EndRefresh(mywin, TRUE);
break;
}
}
}
}

/*
** Prepare for using GadTools, set up gadgets and open window.
** Clean up and when done or on error.
*/
VOID gadtoolsWindow(VOID)
{
struct TextFont *font;
struct Screen *mysc;
struct Window *mywin;
struct Gadget *glist, *my_gads[4];
void *vi;
WORD slider_level = 5;
UWORD topborder;

/* Open topaz 8 font, so we can be sure it's openable
** when we later set ng_TextAttr to &Topaz80:
*/
if (NULL == (font = OpenFont(&Topaz80)))
errorMessage( "Failed to open Topaz 80");
else
{
if (NULL == (mysc = LockPubScreen(NULL)))
errorMessage( "Couldn't lock default public screen");
else
{
if (NULL == (vi = GetVisualInfo(mysc, TAG_END)))
errorMessage( "GetVisualInfo() failed");
else
{
/* Here is how we can figure out ahead of time how tall the */
/* window's title bar will be: */
topborder = mysc->WBorTop + (mysc->Font->ta_YSize + 1);

if (NULL == createAllGadgets(&glist, vi, topborder,
slider_level, my_gads))
errorMessage( "createAllGadgets() failed");
else
{
if (NULL == (mywin = OpenWindowTags(NULL,
WA_Title, "GadTools Gadget Demo",
WA_Gadgets, glist, WA_AutoAdjust, TRUE,
WA_Width, 400, WA_MinWidth, 50,
WA_InnerHeight, 140, WA_MinHeight, 50,
WA_DragBar, TRUE, WA_DepthGadget, TRUE,
WA_Activate, TRUE, WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE, WA_SimpleRefresh, TRUE,
WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_REFRESHWINDOW |
IDCMP_VANILLAKEY | SLIDERIDCMP | STRINGIDCMP |
BUTTONIDCMP,
WA_PubScreen, mysc,
TAG_END)))
errorMessage( "OpenWindow() failed");
else
{
/* After window is open, gadgets must be refreshed with a
** call to the GadTools refresh window function.
*/
GT_RefreshWindow(mywin, NULL);

process_window_events(mywin, &slider_level, my_gads);

CloseWindow(mywin);
}
}
/* FreeGadgets() even if createAllGadgets() fails, as some
** of the gadgets may have been created...If glist is NULL
** then FreeGadgets() will do nothing.
*/
FreeGadgets(glist);
FreeVisualInfo(vi);
}
UnlockPubScreen(NULL, mysc);
}
CloseFont(font);
}
}

/*
** Open all libraries and run. Clean up when finished or on error..
*/
void main(void)
{
if (NULL == (IntuitionBase = OpenLibrary("intuition.library", 37)))
errorMessage( "Requires V37 intuition.library");
else
{
if (NULL == (GfxBase = OpenLibrary("graphics.library", 37)))
errorMessage( "Requires V37 graphics.library");
else
{
if (NULL == (GadToolsBase = OpenLibrary("gadtools.library", 37)))
errorMessage( "Requires V37 gadtools.library");
else
{
gadtoolsWindow();

CloseLibrary(GadToolsBase);
}
CloseLibrary(GfxBase);
}
CloseLibrary(IntuitionBase);
}
}
</pre>

=== Restrictions on GadTools Gadgets ===

There is a strict set of functions and operations that are permitted on GadTools gadgets. Even if a technique is discovered that works for a particular case, be warned that it cannot be guaranteed and should not be used. If the trick concocted only works most of the time, it may introduce subtle problems in the future.

Never selectively or forcibly refresh gadgets. The only gadget refresh that should ever be performed is the initial GT_RefreshWindow() after a window is opened with GadTools gadgets attached. It is also possible to add gadgets after the window is opened by calling AddGlist() and RefreshGlist() followed by GT_RefreshWindow(). These refresh functions should not be called at any other time.

GadTools gadgets may not overlap with each other, with other gadgets or with other imagery. Doing this to modify the gadget's appearance is not supported.

GadTools gadgets may not be selectively added or removed from a window. This has to do with the number of Intuition gadgets that each call to CreateGadget() produces and with refresh constraints.

Never use OnGadget() or OffGadget() or directly modify the GFLG_DISABLED Flags bit. The only approved way to disable or enable a gadget is to use GT_SetGadgetAttrs() and the GA_Disabled tag. Those kinds of GadTools gadgets that do not support GA_Disabled may not be disabled (for now).

The application should never write into any of the fields of the Gadget structure or any of the structures that hang off it, with the exception noted earlier for GENERIC_KIND gadgets. Avoid making assumptions about the contents of these fields unless they are explicitly programmer fields (GadgetID and UserData, for example) or if they are guaranteed meaningful (Left, Top, Width, Height, Flags). On occasion, the program is specifically invited to read a field, for example the StringInfo->Buffer field.

GadTools gadgets may not be made relative sized or relative positioned. This means that the gadget flags GFLG_RELWIDTH, GFLG_RELHEIGHT, GFLG_RELBOTTOM and GFLG_RELRIGHT may not be specified. The activation type of the gadget may not be modified (for example changing GACT_IMMEDIATE to GACT_RELVERIFY). The imagery or the highlighting method may not be changed.

These restrictions are not imposed without reason; subtle or blatant problems may arise now or in future versions of GadTools for programs that violate these guidelines.

=== Documented Side-Effects ===

There are certain aspects of the behavior of GadTools gadgets that should not be depended on. This will help current applications remain compatible with future releases of the GadTools library.

When using GT_FilterIMsg() and GT_PostFilterIMsg(), never make assumptions about the message before or after filtering. I.e., do not interpret the unfiltered message, assume that it will or will not result in certain kinds of filtered message or assume it will result in a consumed message (i.e., when GT_FilterIMsg() returns NULL).

IDCMP_INTUITICKS messages are consumed when a scroller's arrows are repeating. That is, IDCMP_INTUITICKS will not be received while the user is pressing a scroller arrows. Do not depend or rely on this side effect, though, it will not necessarily remain so in the future.

A single call to CreateGadget() may create one or more actual gadgets. These gadgets, along with the corresponding code in GadTools, define the behavior of the particular kind of GadTools gadget requested. Only the behavior of these gadgets is documented, the number or type of actual gadgets is subject to change. Always refer to the gadget pointer received from CreateGadget() when calling GT_SetGadgetAttrs(). Never refer to other gadgets created by GadTools, nor create code which depends on their number or form.

For text-display gadgets, the GTTX_CopyText tag does not cause the text to be copied when the text is later changed with GTTX_Text.

The PLACETEXT ng_Flags are currently ignored by GENERIC_KIND gadgets. However, this may not always be so.

All GadTools gadgets set GADTOOL_TYPE in the gadget's GadgetType field. Do not use this flag to identify GadTools gadgets, as this flag is not guaranteed to be set in the future.

The palette gadget subdivides its total area into the individual color squares. Do not assume that the subdivision algorithm won't change.

GUI Programming

2015-03-12T15:23:00Z

Rob Cranley: /* Choosing Toolkits */ Fixed typo

== Background ==

In AmigaOS, the face a program shows you – its [http://en.wikipedia.org/wiki/Graphical_user_interface graphical user interface] (GUI) – is created through a subsystem called [[Intuition_and_the_Amiga_Graphical_User_Interface|Intuition]]. Older literature sometimes used to refer to Intuition as “the Amiga user interface” but this is really not the case. Despite being responsible for much of what you can ''see'' in the OS (including its windowing desktop environment, the [[UserDoc:Workbench|Workbench]]), Intuition itself remains ''invisible'' to the user. It is merely a system component providing ready-made [[#GUI elements|elements]] to build GUIs from, and a set of functions through which these elements are manipulated. Intuition also interconnects GUIs with the operating system and handles various communications that underlie application usage and control.

Intuition’s functionality is further extended by a number of auxiliary system components, or [[#GUI toolkits|toolkits]]. Like most AmigaOS subsystems, Intuition and its extensions are implemented as libraries of functions that can be accessed from a higher-level programming language like C, C++, Modula-2 or AmigaE.

== GUI Elements ==

Amiga programs do not look or behave very differently from, say, Mac or Windows applications because their user interface is based on shared metaphors and familiar elements. There may be differences in naming conventions or programming techniques but the building blocks are similar. The following table summarizes the building blocks (GUI elements) that are provided by Intuition and its various extensions:

{| class="wikitable"
|-
! GUI element types
! Description
! System component or toolkit providing this functionality
|-
| [[Intuition_Screens|screens]] || Virtual desktops on which windows are opened. || Intuition Library
|-
| [[Intuition_Windows|windows]] || Rectangular areas containing an interface through which a program communicates with the user, and vice versa. || Intuition Library, ReAction, MUI
|-
| [[Intuition_Menus|menus]] || Programmable sets of commands displayed as a pull-down list of options. || Intuition Library, GadTools Library
|-
| [[Intuition_Gadgets|gadgets]] || Various-purpose GUI controls (buttons, toolbars, gauges, text fields...) with a standardized look and behaviour. Often called “widgets” in other operating systems. || Intuition Library, GadTools Library, ReAction, MUI
|-
| [[Intuition_Images,_Line_Drawing_and_Text#Creating_Images|images]] || Non-selectable elements showing graphics or text. || Intuition Library, ReAction, MUI
|-
| [[Intuition_Requesters_and_Alerts#Intuition_Requesters_and_Alerts|requesters]] || Means for displaying information and for requesting input from the user. They would be called “dialogs”, “dialog boxes” or “dialog windows” in other OSes. || Intuition Library, ASL Library, ReAction, MUI
|-
| [[Intuition_Requesters_and_Alerts#Alerts|alerts]] || A method of emergency communication (such as system errors). || Exec Library, Intuition Library
|-
| [[Application_Library#Pop-up_notifications_(Ringhio_messages)|pop-up notifications]] || Automatic messages informing the user when things happen. Unlike requesters, notifications are “unobtrusive” and do not require any input from the user. || [[Application Library]]
|-
| [[Intuition_Images,_Line_Drawing_and_Text#Creating_Text|IntuiText]] || Formatted text to be placed at a specific position inside an Intuition element (screen, window, menu, gadget or requester). || Intuition Library
|-
| [[Intuition_Images,_Line_Drawing_and_Text#Creating_Borders|borders]] || Graphical structures made of lines that connect a series of defined points.. || Intuition Library
|}

== The Two Frameworks ==

GUI programming in AmigaOS does not have to be done within a single framework or [http://en.wikipedia.org/wiki/Application_programming_interface API]. This fact can be confusing to newcomers. There are two frameworks in Intuition representing fundamentally different approaches to GUI programming:

# The '''data structure-oriented framework''' is the original Intuition API. Within this framework, if you want to create a GUI element, you have to provide dedicated data structures for it; if you want to manipulate the element, you have to use a function designed for the particular action and type of element.

# The '''object-oriented framework''' (called [[BOOPSI]]: Basic Object-Oriented Programming System for Intuition) is the extendable API. Within this framework, if you want to create a GUI element, you have to instantiate an ''object'' based upon a particular ''class''. Objects are manipulated through a small set of ''methods'' which are really just functions.

Modern AmigaOS programmers generally do not directly use either of these frameworks. Although it is still possible to do so it also requires a lot more code to achieve even a simple GUI.

Instead, programmers are encouraged to use one or more of the various toolkits provided.

== GUI toolkits ==

While the Intuition Library originally provided a datastructure-based set of basic GUI elements (screens, windows, menus, buttons & string gadgets, etc.) they have been supplanted by more modern tools for user interface programming. Most of the GUI-related functionality is now provided through various extensions to Intuition, or ''toolkits''. The following toolkits are installed by default in AmigaOS:

=== GadTools ===

[[GadTools_Library|GadTools]] is a datastructure-based toolkit. It is implemented as a single library and is not easily extensible. What is most useful about GadTools is the [[GadTools_Library#GadTools_Menus|menu building functionality]] (most of the other toolkits still use the menu build aspect of GadTools).

GadTools was introduced in AmigaOS 2.x as a ready-made toolkit for easier, faster and more consistent GUI design. GadTools extended the original Intuition set with fancy new controls such as the [[GadTools_Library#Cycle_Gadgets|cycle gadget]], the [[GadTools_Library#Mutually-Exclusive_Gadgets|radiobutton]], or the [[GadTools_Library#Listview_Gadgets|listview]]. The gadgets shared similar imagery, thus giving Amiga GUIs a more uniform, standardized look. Apart from improving the gadget set, GadTools also greatly simplified the creation of menus (GadTools uses standard Intuition menus but provides its own build and layout system for them). On the other hand, there is a very limited support for images in GadTools.

=== ASL ===

[[ASL_Library|ASL]] is a datastructure-based toolkit. It is implemented as a single library and is not extensible.

The Amiga Standard Library (ASL) is a toolkit designed to ease the programming of common requesters. There are currently three types of requester available: file requester, font requester and screenmode requester.

=== ReAction ===

[[ReAction]] is an object-oriented toolkit based on BOOPSI which is highly extensible.

ReAction is a more modern toolkit which hides much of the complexity. It covers all the functionality of GadTools and ASL and uses and extends the original BOOPSI class set built into Intuition Library. ReAction is considered to be the standard Amiga GUI toolkit. Over the years it has been integrated into the Intuition/BOOPSI framework, and is no longer considered a separate component.

=== MUI ===

[http://en.wikipedia.org/wiki/Magic_User_Interface Magic User Interface] is an object-oriented toolkit based on BOOPSI which is highly extensible.

MUI is a comprehensive third-party toolkit for application GUI design which can also incorporate GadTools menus and ASL. MUI is also available on older AmigaOS systems and various clone systems although the implementation differs so compatibility is not guaranteed.

=== Qt, REBOL/View and Others ===

Third party toolkits may also be used on AmigaOS just as well as the built-in toolkits listed above.

Such toolkits generally work by opening an Intuition Screen and then rendering directly into that screen to create the GUI environment. Toolkits may also incorporate Intuition Windows and use them as a basic element. Native Intuition Menus may or may not be used as well.

With the use of skinning, 3rd party GUIs can look and feel a lot like Amiga native GUIs. However, they can suffer from reduced speed due to the more intensive use of the CPU. Much of the speed problem can be alleviated through the use of hardware acceleration (e.g. compositing).

== Choosing Toolkits ==

* Choose the toolkit that works best for your application and your end customers.

* GadTools gadgets are incompatible with all others and have their own [[GadTools_Library#Function_Reference|set of functions]] to be used with. There is no automatic layout system: GadTools gadgets are not scalable and are at fixed positions and dimensions. Using GadTools for GUI programming is no longer recommended, with the exception of the menu build and layout system.

* The original BOOPSI set built in Intuition is usable but somewhat limited. Some BOOPSI objects are now actually wrappers for ReAction objects.

* If you require modern features like scalability, font sensitivity, automatic (re)layouting, or window iconification (the ability to collapse the program window into an icon on the Workbench screen), then use one of the object-oriented toolkits: ReAction or MUI.

* The ASL toolkit is utilized by ReAction and MUI through dedicated classes. There is little need to use ASL directly in object-oriented GUIs.

* Prefer not to mix datastructure-oriented and object-oriented GUI programming. Functions designed for Intuition windows, gadgets or images are not meant to be used on GUI objects created via ReAction. BOOPSI objects must solely be manipulated using [[BOOPSI_-_Object_Oriented_Intuition#Function_Reference|BOOPSI functions]] (methods).

* Many new programmers seem to be confused about window programming. It's fairly easy:
** ReAction elements (objects) must reside in a ''ReAction window'', that is, a window created through the Window Class, which is part of the toolkit. Such a window is manipulated as any other BOOPSI object.
** Intuition or GadTools elements must reside in an ''Intuition window'', that is, a window created through functions OpenWindow() or OpenWindowTags(), which are both part of the Intuition Library. Such windows are manipulated using dedicated functions.

* Despite both being based on BOOPSI, MUI and ReAction classes are not interchangeable. You cannot extend the functionality of ReAction with MUI classes and vice versa.

Using the keyboard to control Workbench

2014-12-18T15:35:39Z

Rob Cranley: /* Special Shell keys */ Removed extra backslash characters to leave single backslashes instead - were they escape codes?

[[Category:Workbench]][[Category:Keyboard]]
The following keystrokes are usable in the main Workbench screen.

Most of them will execute the corresponding action as found in the Workbench menu. Of course, the keystrokes are usable only if their menu counterpart is enabled (this depends on the context; e.g. actions on files are enabled only when file icons are selected).

= ''HELP'' Opens Workbench Help =

''Workbench menu'' (note that all menu shortcuts use the right Amiga key as qualifier)

''Amiga + B'' Switches on or off the [[Workbench Menu - Backdrop|backdrop]] feature of the Workbench root window.

''Amiga + E'' Allows you to [[Workbench Menu - Execute command|execute a command]].

''Amiga + ?'' Opens the [[Understanding_Workbench_requesters|About requester]] with version info etc.

''Amiga + Q'' [[Understanding_Workbench_requesters|Quits the Workbench]].

= Window menu =

''Amiga + N'' [[Window_Menu_-_New_Drawer|Creates a new drawer]] in the opened directory.

''Amiga + K'' [[Window_Menu_-_Close|Closes]] the selected drawer window.

''Amiga + A'' [[Window_Menu_-_Select_contents|Selects the contents]] in the selected window.

''Amiga + Z'' [[Window_Menu_-_Clear_selection|Clears]] the selection.

''Amiga + .'' [[Window_Menu_-_Clean_up_by|Cleans up]] the window contents by column.

''Amiga + 6'' [[Window_Menu_-_Clean_up_by|Cleans up]] the window contents by name.

''Amiga + 7'' [[Window_Menu_-_Clean_up_by|Cleans up]] the window contents by date.

''Amiga + 8'' [[Window_Menu_-_Clean_up_by|Cleans up]] the window contents by size.

''Amiga + 9'' [[Window_Menu_-_Clean_up_by|Cleans up]] the window contents by type.

''Amiga + -'' [[Window_Menu_-_Show...|Shows only]] files with an associated icon in the selected window's drawer.

''Amiga + +'' [[Window_Menu_-_Show...|Show All Files]] in the selected window's drawer (even files with no associated icon).

''Amiga + 1'' Displays files in [[Window_Menu_-_View_by|icon mode]] (the default).

''Amiga + 2'' Displays files by name, sorted in [[Window_Menu_-_View_by|alphabetical order]].

''Amiga + 3'' Displays files by name, sorted by [[Window_Menu_-_View_by|date]] (older to more recent).

''Amiga + 4'' Displays files by name, sorted by [[Window_Menu_-_View_by|size]] (smaller to bigger).

''Amiga + 5'' Displays files by name, sorted by [[Window_Menu_-_View_by|Type]] (directories first, then files).

''Amiga + F'' Runs the [[Window_Menu_-_Find|Find utility]] allowing you to search for files.

= Icons menu =

''Amiga + O'' [[Icon_Menu_-_Open|Opens]] the selected file(s).

''Amiga + C'' [[Icon_Menu_-_Copy|Clones]] the selected file(s).

''Amiga + R'' Allows you to [[Icon_Menu_-_Rename|rename]] the selected file(s).

''Amiga + I'' [[Icon_Menu_-_Information|Displays all information]] on the selected icon(s).

''Amiga + S'' [[Icon_Menu_-_Snapshot_and_UnSnapshot|Stores the position(s)]] of the selected icon(s).

''Amiga + U'' [[Icon_Menu_-_Snapshot_and_UnSnapshot|Clears the stored position(s)]] of the selected icon(s).

''Amiga + L'' [[Icon_Menu_-_Leave_Out_and_Put_Away|Moves the selected file(s)]] from its/their location(s) to the desktop.

''Amiga + P'' [[Icon_Menu_-_Leave_Out_and_Put_Away|Puts the selected left out file(s)]] back in its/their original place(s).

''Amiga + D'' [[Icon_Menu_-_Delete|Deletes]] the selected file(s) directly.

= Mouse Qualifiers =

''Right-Amiga + Open drawer''
Closes parent window while opening the drawer.

''Right-Amiga + Close gadget''
Closes all open drawer windows.

''Shift + Zoom gadget''
Maximizes a window to full screen without covering the Workbench titlebar.

''Shift + Drag window''
Forces window to stay within the WB screen (when "Off-screen windows dragging" is enabled in Prefs/GUI).

''Ctrl + Alt + Drag window frame''
Resizes a window from any edge or corner.

''Ctrl + Amiga + Drag window''
Moves a window by clicking it anywhere (except active text editors).

''Left-Amiga + Drag screen''
Moves or drags down a screen by clicking it anywhere. This can be redefined in Prefs/GUI, where you can also change other aspects of screen dragging.

= Mouse Substitution =

''Left-Amiga + M''
Flips through each open screen.

''Left-Amiga + N''
Flips to the Workbench screen.

''Left-Amiga + V''
Activates the leftmost button in a requester.

''Left-Amiga + B''
Activates the rightmost button in a requester with more than one button.

''Amiga + Arrows''
Moves the pointer.

''Amiga + Shift + Arrows''
Moves the pointer faster.

''Amiga + Right-Alt''
Performs a RMB click.

''Amiga + Left-Alt''
Performs a LMB click.

= Standard menu shortcuts in programs =

It may be useful to know that the official Amiga guidelines for user interface design contain a list of menu shortcut keys which should always be followed by conforming Amiga programs - where relevant, of course. And as many programs actually do follow this, it is worth learning the most important ones, so you e.g. always know how to print or how to quit a program. The list is as follows:

== Project menu ==

Amiga + N New

Amiga + O Open...

Amiga + S Save

Amiga + A Save As...

Amiga + P Print

Amiga + ? About... (not part of the official standard, but still almost always used)

Amiga + Q Quit

== Edit menu ==

Amiga + X Cut

Amiga + C Copy

Amiga + V Paste

Amiga + Z Undo

You might notice that some of these standard items are also present in the Workbench menus, and that those of course use the standard keys. Others (such as Paste) are not relevant in the Workbench, so therefore the corresponding shortcut keys (here Amiga + V) are not used at all.

= Standard keystrokes used elsewhere =

Although they are not strictly part of Workbench, some other standard keystrokes are worth a mention while we're at it.

= Boot modifier keys =

During bootup of your Amiga, it is possible to interrupt or influence the normal boot process in various ways using the keyboard and/or the mouse.

If you hold down the Help key (normally Scroll Lock on a PC keyboard) during bootup, you will enter the Early Startup Menu, where you can make various selections about which drive to boot from, and whether to boot without Startup-Sequence, among others. The same can be achieved by holding both (L+R) mouse buttons. Either way, you may have to experiment a bit with the timing; it has to happen during initialisation of the system, just after the Kickstart modules have been loaded, but before the initialisation has passed the point of the bootmenu.

You can also hold down the Ctrl key (either one on a PC keyboard) or the middle mouse button (if you have one); this will make the system boot without Startup-Sequence, just like it would do if you selected it from the Early Startup Menu. And if instead you hold down either one of the Shift or Alt keys (including Alt Gr on a PC keyboard), the system will boot without starting anything from the WBstartup drawer. Note that the system doesn't determine whether it should start with or without WBStartup until the Workbench is actually being loaded, which is not the very first thing that happens during startup. Therefore you have to keep the Alt or Shift key pressed until you actually see the Workbench screen appear for it to be detected.

= Special Shell keys =

In the AmigaShell window, there are also a couple of useful key combinations to note.

Ctrl-C, like in many other systems, is the regular break signal. It tells a Shell program to stop immediately. Note that this requires the program to actually be coded to "listen" for this signal, and to be able to receive it, i.e. not to be fully occupied with other matters. So it may not always seem to have any effect. Sometimes it just takes a little time, sometimes it doesn't work at all.

Ctrl-D works in a similar way, except that it breaks a running AmigaDOS script. Normally, a Ctrl-C will break the currently executing command, but if it is running as part of a script, this will just let the next command in the script run. With Ctrl-D you can avoid having the rest of the script run.

Finally, Ctrl-\ (Ctrl and backslash) can be used to exit the Shell. It does the same as hitting the close gadget (if found) or typing EndCLI as a command. Note that on a PC keyboard, the key to use together with Ctrl is not necessarily the backslash key, it differs between the various national keyboard types. It will normally have either a backslash or a vertical bar (|) as one of the characters printed on it. To find out for sure, you can start the program KeyShow in the Utilities drawer. Click on a Ctrl key on the display, and look for a key that shows '^\' (the caret '^' symbolizes the Ctrl code). There may be more than one key that shows this sequence, in which case both or all of them will work.

The KeyShow program is in general a great help if you are wondering how to type some rarely used character. It will always adapt to the keymap you have chosen in Prefs/Input (e.g. as done during installation) and show the characters produced by the various keys alone or together with whatever qualifier key you click on.

= More about the keyboard (and other subjects) =

You can find more information about the difference between using a classic Amiga keyboard and a PC keyboard, and lots of other keyboard-related things, in the file Keyboards.doc in the Documentation drawer, which can be found on your installation CD.

In general, the Documentation drawer is full of interesting and useful information about using your Amiga and AmigaOS 4.0. Please have a good look at it, and return to it whenever you search for answers in your future quest to master Workbench and AmigaOS. While it is not installed to your hard disk by default, it is highly recommended that you drag it over from the CD, so that you always have access to it while working with your system. It only takes up a couple of megabytes of disk space.

UserDoc:How AmigaOS Works

2014-12-02T15:51:55Z

Rob Cranley: /* Kickstart modules */ Small corrections.

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.
After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2014-12-02T15:40:26Z

Rob Cranley: /* In a shell */ Reworded sonce you do not need to use the List command to see if an object is a file or dir - the dir command will do this too.

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.
After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows to store data on partitions in SFS0 and SFS2
* JXFileSystem - allows to create partitions in JXFS
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

Wiki Author Credits

2014-06-10T14:18:01Z

Rob Cranley: Added my own name :)

The following is a list of known contributors to this wiki:
* Adam Levin
* Alexandre Balaban
* [http://amigaak.org.nz/ Amiga Auckland]
* Andy Finkel
* Bart Whitebook
* Bill Borsari
* Bill Koester
* Bob Burns
* Bob Pariseau
* Bruce Barrett
* Bryce Nesbitt
* Carl Sassenrath
* Carolyn Scheppner
* Chris Green
* Chris Ludwig
* Chris Raymond
* Dale Luck
* Dan Baker
* Daniel Jedlicka
* Darius Taghavy
* Darren Greenwald
* Dave Berezowski
* Dave Lucas
* David Junod
* David Miller
* Don Cox
* Eric Cotton
* Ewout Walraven
* Frank Bunton, for his [http://aminet.net/package/docs/help/adosbegin AmigaDOS guide]
* Hans-Joerg Frieden
* James Jacobs
* Jerry Hartzler
* Jez San
* Jim Mackraz
* Joe Katz
* John Orr
* John Wiederhirn
* Karl Churchill
* Ken Farinsky
* Kevin Klop
* Larry Hildenbrand
* Leo Schwab
* [https://sites.google.com/site/takeaprogrammertolunch/ Lyle Hazelwood]
* Mark Barton
* Mark Ricci
* [http://wandel.ca/ Markus Wandel]
* Martin Taillefer
* Michael Sinz
* Nancy Rains
* Neil Kafferkey
* Neil Katin
* Olaf Barthel
* Paul Higginbottom
* Paul Sadlik
* Peter Cherna
* Philippe Ferrucci
* R.J. Mical
* Randell Jesup
* Ray Brand
* Rob Cranley
* Rob Peck
* Rob Wyesham
* Roman Kargin
* Sam Dicker
* Simon Archer
* Spencer Shanson
* Stan Shepard
* Steve Beats
* [http://www.solie.ca Steven Solie]
* Stuart Ferguson
* Susan Deyl
* Thomas Frieden
* Tom Pohorsky
* Tom Rokicki

UserDoc:Introduction to AmigaOS

2014-06-05T14:50:55Z

Rob Cranley: /* Pop-Up Menus */ "till" -> until.

Like any modern personal computer system, AmigaOS presents a graphic interface and relies on common peripherals to let the user control their system.
Beyond most systems, AmigaOS provides more flexibility and options in how the user can approach, configure and use their Amiga computer.

In this page we will describe the details of AmigaOS graphic user interface (GUI) - how screens, windows and gadgets are presented and how you can use them.
We will also describe the various means by which the user can control and operate AmigaOS. In additional pages, you can read about [[UserDoc:How AmigaOS Works|how AmigaOS works]] and what its components are.

== AmigaOS Input - Point, Click and Type ==

There are two common ways you can use and control your AmigaOS system - by mouse and keyboard.

But AmigaOS also lets you control your system by other input devices (like touchscreens or voice recognition) depending on drivers and devices connected. Depending on software installed, AmigaOS can also be remotely controlled by networked protocols (like VNC and Synergy). Finally, AmigaOS can be controlled internal scripts set up by the User.

=== Using the mouse ===

[[File:Style2.5.png|frame|right]]

Typically in AmigaOS, you use a mouse to act on graphic elements (like "gadgets", "icons" or webpage "links"). By default, AmigaOS expects and supports mice or trackball pointing devices with at least two buttons. The left mouse button is used to "left-click" on graphic objects, to select them or operate them. The right mouse button is used to "right-click" and display the menus of the current application.

Optionally, one can use a mouse or trackball device with three (a "middle" button) and four buttons. With such devices, the functionality of the additional buttons can vary by application or environment. These functionalities can typically be configured by the user in specific applications or within AmigaOS (globally).

Furthermore, scroll wheels are supported by AmigaOS in a context-based fashion. If the current application's window is scrollable, the scrollwheel will act on that area. If the mouse pointer is positioned over a specifically scrollable gadget, the scrollwheel will affect that gadget.

In some applications and environments, you can also "double-click" (click twice, quickly) with the left button on an object to engage them. In the Workbench file manager, a single mouse click will only "select" an icon, whereas a double-click will open drawer/directory, run an application or open a file in an associated program.

Beside "clicking" - pressing down and releasing a mouse button at a specific location - you can also perform what is known as "dragging", which means clicking down and then moving the mouse around before releasing the mouse button. This is typically always done with the left mouse button and is done to select objects (draw a box around them), to adjust a control slider or to resize a window.

 

=== Using the keyboard ===

Of course the keyboard is used to enter text into text editing areas. But your keyboard can do so much more with its special "qualifier" keys and AmigaOS.

The most common example of a qualifier key is the "Shift" key which causes typed text to be made upper-case or capitalized. There are more qualifier keys on most keyboards, here is a list of all of them:
* '''the Shift keys''' - the common key that causes your text to be capitalized.
* '''The "Alternate" keys''' - the "Alt" keys typically to the bottom right and left of the keyboard.
* '''the "Control" keys''' - the "Ctrl" keys also to the bottom right and left of the keyboard.
* '''the "Amiga" keys''' - special "A" keys on the right and left side of the space bar. Besides being unique to AmigaOS, the right and left Amiga keys always mean different things (unlike the rest of the qualifier keys, most of the time). If you have a non-AmigaOS keyboard, the "Windows" or MacOS "Command" keys function as "Amiga" keys.
** '''the Right Amiga key''' - is used for "short cuts" within your current application.
** '''the Left Amiga key''' - is used for "short cuts" that are globally active anytime and anywhere in your AmigaOS system.
While all of these qualifier keys don't usually do anything on their own, when you press and hold one or more of these keys down while pressing regular keys, they can change what you type (capitalizing or making alternate characters) or become powerful "short-cuts" within your applications or throughout your entire AmigaOS system.

The most famous short-cuts are the '''copy''', '''cut''' and '''paste''' operations that you can perform on selected text:
* the '''Right-Amiga C''' short-cut copies any selected text or content to the Clipboard.
* the '''Right-Amiga X''' short-cut "cuts" any selected text or content to the Clipboard.
* the '''Right-Amiga V''' short-cut "pastes" any text or content from the Clipboard into your application (at the current cursor location).

== The AmigaOS GUI - Intuition ==

When AmigaOS has started, you will typically see the Workbench file manager. This is the start of your experience with the AmigaOS GUI and its most basic elements: a screen with menus and windows containing icons and "gagdets". These components are the basic building blocks of virtually all AmigaOS & application interfaces.

As with most things in AmigaOS, almost all of the following components can also be almost infinitely reconfigured, adjusted and graphically varied by the user. In the AmigaOS "Preferences" drawer, the "GUI", "ASL", "Locale", "Font", "Palette", "Poiner", "PopUpMenu", "Screens", "Workbench" and "WBPattern" preference editors easily allow a user to reconfigure the look and feel of their Amiga's GUI in dramatic ways.

AmigaOS also supports the use of alternate GUI systems in parallel with the default "Intuition" (aka "Reaction") GUI system. By default AmigaOS also comes with the "Magic User Interface" system ("MUI", a variant of the basic AmigaOS GUI system). Aside from Intuition, MUI can be reconfigured even more widely using its own MUI configuration app.

Additionally, AmigaOS can use a number of third-party "cross-platform" GUI systems: "AmiCygnix" GUI system - a native X11 GUI implementation for AmigaOS - and a native port of the "Qt" GUI system. With either of these systems, it is possible to run ported applications compiled for AmigaOS, but running with these cross-platform GUI systems.

To start with, we will explore the elements that make up the AmigaOS GUI system.

=== Screens ===

As start-up, the Workbench will be running on its "Workbench Screen". This will be the default location where most other application windows will also appear when started.

Typically an AmigaOS screen will have a "title bar" across the top with a graphical "depth gadget" at the right end. In the case of the Workbench screen, there will be an AmigaOS "boing ball" at the left end and the title bar will display certain system information (OS version, memory availability, etc.) Within the screen, the Workbench and any other applications can open windows, display icons and other GUI devices. If you right-click over the title bar, it becomes a "Menu Bar", showing you the control menus that are available for that application.

In many cases, other applications may open screens in addition to the Workbench screen. The "depth gadget" at the right end of each screen's title bar allows you to click from screen from screen. Besides clicking on the screen's depth gadet, AmigaOS also lets the user see other screens behind the front screen by "dragging" down on the screen title bar.

The characteristics of the Workbench screen such as resolution and color depth can be configured in the "Screenmode" preferences editor. Other screens can be either be configured in the "Screens" preferences editor or from within individual applications. Typically, AmigaOS applications also give the user the choice of whether application runs on their own screens or the "public" Workbench screen.

=== Windows ===
Windows are graphic containers that appear within AmigaOS screens. Windows can be created by any number of different applications - the Workbench, Shell sessions or applications. Outside of the Workbench file manager, each window usually reflects each individual running application. In some cases, one application may open multiple documents in separate windows or additional "requester" windows might appear for an application.

[[File:LibFig4-1.png]]

Almost all windows of AmigaOS will have these common elements:
* '''Borders''' - A border around the window's contents. Holding the Shift+Left-Amiga keys down while dragging any border will drag the window around.
* '''Title bar''' - A thicker top border that typically contains a name of the application or its contents. The area of the title bar acts as a "drag bar" which you can use to drag the window around the screen.
* '''Depth gadget''' - The right-most gadget in the top title bar that either pulls the window to front (if it isn't frontmost) or pushes it to the back (if it's in front). Holding down the Shift key while clicking this gagdet pushes the window to the back.

In AmigaOS, windows may also optionally have these additional features and elements:
* '''Close gadget''' - The left-most gadget in the title bar that closes the window.
* '''Scroll bar(s) and arrows''' - If the contents of the window can be scrolled in vertically and/or horizontally, there will be a scroll bar with arrow scroll buttons. These scroll bars can also be used if the mouse pointer is over a scroll bar and the mouse scroll wheel is used.
* '''Zoom gadget''' - the second gadget from the right-most of the title bar which switches the window between two sizes. Holding down the Shift key while clicking this gadget will make it fill the screen.
* '''Iconification gadget''' - left-most of the right-hand gadgets in the title bar which causes the window to disappear into an icon on the Workbench background - thus "Iconifying" the window or application.
* '''Sizing gadget''' - In the case of windows that can be resized, this is the gadget in the bottom right corner of the window that you can drag to resize the window.

Each AmigaOS application can use many different combinations of these features in the make up of their windows.

=== Menus ===

[[File:LibFig2-4.png|frame|right]]
Menus are lists of items that will allow you to see and use what commands are available in an application. The Workbench uses menus you can use to perform actions on the Workbench and its contents. Menus typically provide many more functions and commands than can be presented to the user than just graphic buttons, etc. within an application's window, as a result they are a primary way most applications are used.

In AmigaOS menus can always be found for the current application by moving the mouse to the top of the screen and holding down the right mouse button. The screen title bar will become a menu bar and will show the names of all the current application's menus.

By dragging with the right mouse button, each menu will display its "menu items". Each of those menu items corresponds to a command or setting, and can be selected by releasing the right mouse button while the desired menu item is highlighted. In some cases you will find a "check box" on a menu item which you can select to toggle a setting. In other cases, you will find that menu items have a little arrow head that indicates that item actually has a "sub-menu" - a menu within a menu. Menus ending with an ellipsis ("...") indicate that menu item will open a window that can be cancelled without committing any command. For those menu items that might be deactivated (they may not apply at the moment), they will be "greyed-out".

The labels of many menu items will also include a letter or two with an "A" at the right edge. This indicates what the keyboard Right-Amiga "short cut" is the equivalent of using that menu item within that application. In the above screen shot, you can see that pressing the two keys - "Right-Amiga" and "N" - would do the same as that menu item - to create a new drawer.
 

====Consistent Organization====
For the sake of consistency (when applicable), the first two AmigaOS menus of any application are typically organized with the following hierarchy and use these keyboard equivalents:

{| border="0"
|'''First Menu:'''
----
|| || Keyboard equivalent: || '''Second Menu:'''
----
|| || Keyboard equivalent:
|-
|'''PROJECT'''
----
|| || ||'''EDIT'''
----
||
|-
|'''New'''|| = Create new project in application.||Right-Amiga N||'''Cut'''|| = Cut the selected content into the Clipboard.||Right-Amiga X
|-
|'''Open...'''|| = Open the file containing a project.||Right-Amiga O||'''Copy'''|| = Copy the selected content into the Clipboard.||Right-Amiga C
|-
|'''Save'''|| = Save the project to it's current file name.||Right-Amiga S||'''Paste'''|| = Paste the Clipboard contents into the project (at the current location).||Right-Amiga V
|-
|'''Save As...'''|| = Save the project to a file of a new name.|| ||'''Undo'''|| = Undo the last change to current project.||Right-Amiga Z
|-
|'''Print'''|| = Print the current project.||Right-Amiga P||'''Redo'''|| = Restore the last change "undone" in the current project.||
|-
|'''Close'''|| = Close the project.|| || || ||
|-
|'''Quit'''|| = Quit the application.||Right-Amiga Q||
|}

====Menu Variations====
AmigaOS also includes some additional ways menus can be presented to the user:

=====Pop-Up Menus=====

[[File:OS4-WBPopUpMenu.jpg|frame|right]]
In the GUI preferences editor you can configure menus to "pop-up" under the mouse pointer whenever you right-click the mouse. This means you do not need to move the mouse to the top of the screen to use the menus. There are also options for making menus "sticky", meaning that you don't need to drag the mouse to navigate the menus, but rather just right click and the menus stay open until you make a selection or click away.
 

=====Context Menus=====

[[File:OS4-WBContextMenu.jpg|frame|right]]
The Workbench (with a utility added by default) and many applications provide "contextual menus". This means that you can put your mouse pointer over elements and right-click to pop-up a menu of things that are specific to the item you clicked over. In the case of the Workbench (with the Context Menus utility), right clicking on a file will pop-up a menu of things that could be done with that file, like deleting it.

All of these features provide both a simple means of using many functions within an application and at the same time allowing the user to configure a very efficient user interface that responds to nearly every whim.
 

=== Icons ===

==== Description ====
Icons are small images which can represent a disk, a directory, an application file or data file. Icons are primarilly used within the AmigaOS Workbench environment to represent all the file system objects the user can manipulate. With these icons it is possible to select files, open them, delete them or move them around within the Workbench. Applications may also make more limited use of icons to represent file system objects or may be used as imagery in an "icon bar" of buttons that can be clicked to perform various actions represented by icon imagery, like the Clock above.

{|style="text-align: center;"
|[[File:LibDiskIcon.png|frame|left|100px|Drive icon]] [[File:Icons.png|frame|right|Directory with sub-directory, data and application file icons]]
|}

AmigaOS also uses different icon imagery to indicate various types of icons - drives, directories, files and applications. Drive or partition icons look like little hard drives.
A directory icon will look like a cabinet & drawer whereas a file icon will be designed to give a clue about the file content.
Data files are normally shown with a "page" motif and some graphics or text to reflect the file type.
Application files typically have the most free-form graphics that reflect their purpose, name or developer.

The user can also edit the icon imagery using the icon editor, change how icons react to being double-clicked and adjust parameters stored within the icon file that affect how the represented file will be used.

Many applications and all AmigaOS file requesters allow Workbench icons to be "dragged and dropped" into the application or requester windows and the associated file will be recognized by the application, if possible.

==== Icon states ====

Icons can look different not only because of their image but also depending on their state.

As you can see in the directory example, the 2 top left icons appear semi-transparent. This subtle difference reflects whether the file or directory has an associated icon file with it. In AmigaOS, any directory or file can have such an icon file that stores a unique icon image, unique program settings or specific settings for that file or directory. That information can be adjusted within the Workbench and is automatically stored in a companion file with the same name, but with an added '''.info''' suffix.

While many files and directories and most applications have such ".info files" with them, they are not required and the Workbench can be set to show you "default icons" (based on the file types, etc.) so you can manipulate the corresponding objects. Of course, AmigaOS can also be configured on a directory-by-directory basis to only show files that have associated ".info" files.

In the same picture, the two top right directory icons also look slightly different. While the '''Utilities selected''' and the '''Utilities unselected''' are the same icon, their image is a bit different. The drawer of the first one is slightly opened and there is a "glow" effect arround the first icon. These two visual clues show you the first directory icon has been selected by the user whereas the second one is not.

==== App Icons ====

Many applications provide the option to be "iconified" either by clicking on an iconification gadget in their window title bars or by selecting a menu item. In those events, the application's window will disappear and an "app icon" will appear on the background of the Workbench screen. Double-clicking on the app icon will cause the icon to disappear and the application's window to reappear. Even while the application is iconified, it does continue to run and perform whatever the user may have it doing.

Some applications may also place an app icon on the Workbench background even while the application is open to allow the user to be able to drop other file icons on the app icon and have them be used by the application.

=== Graphic gadgets ===
Within AmigaOS and application windows, there can be any number of graphic devices meant to be operated by your mouse with clicks and drags - these are known as "gagdets". In most cases, the gagdets are simple analogs of real world objects - like buttons you press with your finger, forms you fill out with a pencil or tabs on folders.

[[File:LibFig5-1.png]]

==== Buttons ====

[[File:OS4-Buttons.jpg|frame|right]]
Buttons (or "Boolean gadgets") are some of the most common GUI objects. With a simple left-click of your mouse button, they are used to perform actions, set configurations or indicate choices.

In AmigaOS, clicking "down" on a button typically causes the button to be rendered differently, to reflect that it has been "pressed". Engaging the button is not actually recognized until you let go with the mouse button over the graphic gadget. This means that while the gadget has been clicked down, you always have the option of moving the mouse off the button gadget and then letting go and it will be as though the button had never been "pressed" or clicked on.
 
==== Text gadgets ====

[[File:OS4-StringGadgets.jpg|frame|right]]
A text gadget (or "String gadget") works like a space in a paper form to be filled out - left click in the gadget, you will see a cursor appear and you can type your answer.
Once you've finished typing your infrormation, you can either press the enter, carriage-return or tab keys for your entry to be recognized.

Text or string gadgets can also come in a number of variants for specific uses. Some can limit input to be numeric only (and may have adjacent buttons to increment or decrement the value). Some string gadgets may be specifically be meant for file or directory names and they have adjacent gagdets that will bring up a file requester to set the value. Many times a numeric gadget is paired with a slider gadget (as in the example above), where the value can either be set by typing in the gadget or by using the slider.
 
==== Sliders & Scroll Bars ====

[[File:OS4-SliderGadgets.jpg|frame|right]]
Slider gadgets work like controls many of have seen on their stereo systems - left-click and drag on the gadget "knob" to move it back and forth to set a value. A more sophisticated variant of the slider is the "scroll bar" that has a variably sized scroll bar contained in a scroll box that lets you see what proportion of the active range is visible or active.

With all slider and scroller gadgets AmigaOS also lets you click in the area to either side of the knob or slider to adjust the setting. In the case of sliders, the value will typically move by a fixed amount (+/- 1 or some suitable increment). In the case of scroll bars, clicking in the scroll box on either side of the scroll bar will cause the value to move in increments of the scroll bar size. Scroll bars also come with "scroll arrows" at the end of the scroll box that allow for finer movement of the scroll bar.
 
==== Cycle gadgets ====

[[File:OS4-CycleGadgets.jpg|frame|right]]
Cycle gagdets are a variant on buttons that let you select from a number of specific choices. You can either click on the majority of the gadget to pop-up a list of choices to select from or click on the circular arrow to cycle between the list of choices. Cycle gagdets rarely cause actions to occur, they just adjust some setting or configuration.
 
==== Check Box & Radio Button gadgets ====

[[File:OS4-CheckRadioGadgets.jpg|frame|right]]
Another variant of buttons, check boxes can be clicked to set on/off or yes/no conditions with a checkmark, just like a check box in a paper form. Radio buttons are another variant where two or more round buttons are presented in a set and only one of the set can be clicked and activated, like the buttons on a stereo system.
 
==== Tabs ====

[[File:OS4-Tabs.jpg|frame|right]]
Tabs are a graphical gadget that is used in combination with a "pages" or sets of gadgets and/or information, and you can click on the "tabs" to switch between the pages - like you might in a real notebook with tabbed pages. This provides a efficient way to present more information and settings in a compact interface.
 
====Requesters====

[[File:LibFig2-5.png|frame|right]]
As one uses AmigaOS and its applications, from time to time a "Requester" window may appear to ask the user a question - basically windows with gadgets in them. Such requesters can appear to confirm an action, obtain more information, make a selection or configuration. Typically a series of buttons across the bottom of the window will dispatch the requester, with the bottom-left button gadget indicating some affirmative choice and the bottom-right button gagdet cancelling the requester (performing no action or change).
 

====Keyboard Operation of Gadgets====
As with so many things, AmigaOS and its applications provide a secondary way to operate many of these gadgets - by keyboard. If a window contains text gadgets, pressing your keyboard's TAB key will activate the text gadgets in sequence (a cursor will appear in each so you can type & edit). Each press of the TAB key will cycle to the next gadget and pressing SHIFT + TAB will cycle through the gadgets in reverse order.

You may have noticed in many of the above sample images that many of the gagdets or their adjacent "label" texts contain a single underlined character. This is a sign that pressing that key on your keyboard will activate that gadget. Each gadget can then be operated by your keyboard - just like clicking on a button, clicking on a tab, setting a text or numeric value, etc. Of course, if you are in the midst of typing in a text gadget, then things you type will go into that gadget instead of operating other gagdets.

== Finding Files in AmigaOS ==

[[File:OS4-ASLReq.jpg|frame|right]]
AmigaOS provides a consistent method for navigating your file system and finding your files from within your apps - the "ASL file requester". It is used by everything in AmigaOS and most third party applications. It is the window (or "requester") that appears when you want to open or save files.

As you can see, the ASL file requester presents the files in a given location in your file systems (a directory or "drawer") and shows their size, date of creation or last modification and any comments attached to the file. The above example shows the same directory as appeared above in this page.

At the bottom corners of the window are buttons to accept the selection ("OK") or cancel the requester. Between those are buttons to view all the drives & partitions on your system ("Volumes") or to move to the "Parent" of the current directory.

Also at the bottom of the window you will see three text gadgets. The first of these is optional and allows you to filter what is shown in the file list - it is now shown filtering out any file with a ".info" suffix (those are AmigaOS icon files). The next two lines reflect the current directory path name and the currently selected file name (also selected in the file list above). In the case of saving files, you would type any name you wanted in the bottom text field to create a new file. Clicking on the titles of the file list will let you sort the file list.

Of course this being AmigaOS, the ASL requester has its own "preferences editor" that lets you set how the requester appears, is sorted by default and a number of mouse button short-cuts.
 

== Controlling AmigaOS - Which Way? ==

AmigaOS provides a number of parallel ways that the user can control and put their Amigas to use. The easiest and most common method is to use the AmigaOS graphic icons, windows and mouse interface - the "Workbench" - using all the GUI elements described above. But AmigaOS also provides a more traditional or "old fashioned" method called a command line interface (the "CLI" or "Shell"), where the user can type text commands and interact using a text interface. AmigaOS also provides a unique means of "interprocess communications" where user can have many applications and parts of the OS "talk" to each other.

=== The Workbench & Intuition ===

As we described above, AmigaOS provides the "Workbench", a straightforward, efficient and easy graphical means to start applications, manage your computer and all your files. Files and programs are represented with icons, generally known as "Projects" and "Tools". They can be stored in any arrangement of directories ("Drawers"). You double-click on a program icon and it will open in a Intuition GUI window on your Workbench screen.

Please see the section about the AmigaOS [http://wiki.amigaos.net/index.php/UserDoc:Workbench Workbench] to learn these concepts:

* What is the Workbench
* Workbench menus
* Keyboard control
* Workbench requesters
* Configuration
* Workbench help

=== The Shell & DOS Commands ===

[[File:OS4-Window-Shell.jpg|frame|right]]
The AmigaOS Shell can be opened by double-clicking the "Shell" icon in the AmigaOS "System" drawer. The Shell is a text based interface that allows you to perform most of the same operations as the Workbench - to run and interact with application programs, manage files and control your Amiga computer. AmigaOS also comes with dozens of standard "DOS commands" (programs purely meant for Shell usage). Simply enter the name of a program or command (like "dir") and press Enter, the command or program will run and it will print its results in the Shell window. While considered old fashioned, many users find the Shell to still be the most efficient way to perform many tasks on the Amigas.

Please see the section on the [[UserDoc:Shell|AmigaOS Shell]] to learn more.
 

=== Scripts & Messages ===

Scripts are simple text files that contain a list of commands written in a variety of languages: the AmigaDOS, Arexx and Python languages are provided with AmigaOS - there are many others. Each of these language has its strengths. You'll have to learn the one that suits what you want to do. You can create a script using a text editor. You can run such scripts from the Workbench or from the shell (or from any other script). By using ARexx ports provided by AmigaOS components (the Workbench or Multiview, for example) or third-party applications, scripts can be used to make your computer perform a wide variety of actions.

== AmigaOS System Tools ==
AmigaOS comes with a variety of programs to help in the preparation of your computer. These include tools for:

* Drive preparation (Media Toolbox, Format, Format DCRW & Mounter).
* Font Handling (TypeManager & FixFonts).
* Script Languages (RexxMast and Python).
* The Shell.
* Miscellaneous Utilities (Find, Help, Grim Reaper & Ringhio Server).

== AmigaOS Utilities ==
AmigaOS comes with a selection of utilities to assist the user, including:

* Commodities.
* Editors (Notepad, MEmacs, PrefsObjectEditor & IconEdit).
* Postscript oriented apps (AmiPDF, AmiGS & Ghostscript).
* Disk apps (PartitionWizard & RawDisk).
* Screenblankers.
* AmiDock and Dockies.
* The Unarc dearchiver.
* PlayCD.
* Several "sub-programs" that are used by other system utilities (blankers, dockies)
* Miscellaneous apps (Clock, printing apps, KeyShow, install apps, etc.).

Read [[Utilities|here]] to find all of them explained further.

== AmigaOS Preferences ==
AmigaOS comes with a number of small programs used for modifying the system's settings. These are stored in the [[Prefs]] drawer, and include programs for modifying the following settings:

* General appearance
* Screen resolution
* Desktop and window backgrounds
* Language settings
* Keyboard and mouse settings
* Printer settings
* Audio settings

Read [[Prefs|here]] for details and explanations of all the preference programs.

UserDoc:Introduction to AmigaOS

2014-06-05T14:49:57Z

Rob Cranley: /* The AmigaOS GUI - Intuition */ Various spelling and grammar corrections and some rewording. Clarified some aspects of menu operation.

Like any modern personal computer system, AmigaOS presents a graphic interface and relies on common peripherals to let the user control their system.
Beyond most systems, AmigaOS provides more flexibility and options in how the user can approach, configure and use their Amiga computer.

In this page we will describe the details of AmigaOS graphic user interface (GUI) - how screens, windows and gadgets are presented and how you can use them.
We will also describe the various means by which the user can control and operate AmigaOS. In additional pages, you can read about [[UserDoc:How AmigaOS Works|how AmigaOS works]] and what its components are.

== AmigaOS Input - Point, Click and Type ==

There are two common ways you can use and control your AmigaOS system - by mouse and keyboard.

But AmigaOS also lets you control your system by other input devices (like touchscreens or voice recognition) depending on drivers and devices connected. Depending on software installed, AmigaOS can also be remotely controlled by networked protocols (like VNC and Synergy). Finally, AmigaOS can be controlled internal scripts set up by the User.

=== Using the mouse ===

[[File:Style2.5.png|frame|right]]

Typically in AmigaOS, you use a mouse to act on graphic elements (like "gadgets", "icons" or webpage "links"). By default, AmigaOS expects and supports mice or trackball pointing devices with at least two buttons. The left mouse button is used to "left-click" on graphic objects, to select them or operate them. The right mouse button is used to "right-click" and display the menus of the current application.

Optionally, one can use a mouse or trackball device with three (a "middle" button) and four buttons. With such devices, the functionality of the additional buttons can vary by application or environment. These functionalities can typically be configured by the user in specific applications or within AmigaOS (globally).

Furthermore, scroll wheels are supported by AmigaOS in a context-based fashion. If the current application's window is scrollable, the scrollwheel will act on that area. If the mouse pointer is positioned over a specifically scrollable gadget, the scrollwheel will affect that gadget.

In some applications and environments, you can also "double-click" (click twice, quickly) with the left button on an object to engage them. In the Workbench file manager, a single mouse click will only "select" an icon, whereas a double-click will open drawer/directory, run an application or open a file in an associated program.

Beside "clicking" - pressing down and releasing a mouse button at a specific location - you can also perform what is known as "dragging", which means clicking down and then moving the mouse around before releasing the mouse button. This is typically always done with the left mouse button and is done to select objects (draw a box around them), to adjust a control slider or to resize a window.

 

=== Using the keyboard ===

Of course the keyboard is used to enter text into text editing areas. But your keyboard can do so much more with its special "qualifier" keys and AmigaOS.

The most common example of a qualifier key is the "Shift" key which causes typed text to be made upper-case or capitalized. There are more qualifier keys on most keyboards, here is a list of all of them:
* '''the Shift keys''' - the common key that causes your text to be capitalized.
* '''The "Alternate" keys''' - the "Alt" keys typically to the bottom right and left of the keyboard.
* '''the "Control" keys''' - the "Ctrl" keys also to the bottom right and left of the keyboard.
* '''the "Amiga" keys''' - special "A" keys on the right and left side of the space bar. Besides being unique to AmigaOS, the right and left Amiga keys always mean different things (unlike the rest of the qualifier keys, most of the time). If you have a non-AmigaOS keyboard, the "Windows" or MacOS "Command" keys function as "Amiga" keys.
** '''the Right Amiga key''' - is used for "short cuts" within your current application.
** '''the Left Amiga key''' - is used for "short cuts" that are globally active anytime and anywhere in your AmigaOS system.
While all of these qualifier keys don't usually do anything on their own, when you press and hold one or more of these keys down while pressing regular keys, they can change what you type (capitalizing or making alternate characters) or become powerful "short-cuts" within your applications or throughout your entire AmigaOS system.

The most famous short-cuts are the '''copy''', '''cut''' and '''paste''' operations that you can perform on selected text:
* the '''Right-Amiga C''' short-cut copies any selected text or content to the Clipboard.
* the '''Right-Amiga X''' short-cut "cuts" any selected text or content to the Clipboard.
* the '''Right-Amiga V''' short-cut "pastes" any text or content from the Clipboard into your application (at the current cursor location).

== The AmigaOS GUI - Intuition ==

When AmigaOS has started, you will typically see the Workbench file manager. This is the start of your experience with the AmigaOS GUI and its most basic elements: a screen with menus and windows containing icons and "gagdets". These components are the basic building blocks of virtually all AmigaOS & application interfaces.

As with most things in AmigaOS, almost all of the following components can also be almost infinitely reconfigured, adjusted and graphically varied by the user. In the AmigaOS "Preferences" drawer, the "GUI", "ASL", "Locale", "Font", "Palette", "Poiner", "PopUpMenu", "Screens", "Workbench" and "WBPattern" preference editors easily allow a user to reconfigure the look and feel of their Amiga's GUI in dramatic ways.

AmigaOS also supports the use of alternate GUI systems in parallel with the default "Intuition" (aka "Reaction") GUI system. By default AmigaOS also comes with the "Magic User Interface" system ("MUI", a variant of the basic AmigaOS GUI system). Aside from Intuition, MUI can be reconfigured even more widely using its own MUI configuration app.

Additionally, AmigaOS can use a number of third-party "cross-platform" GUI systems: "AmiCygnix" GUI system - a native X11 GUI implementation for AmigaOS - and a native port of the "Qt" GUI system. With either of these systems, it is possible to run ported applications compiled for AmigaOS, but running with these cross-platform GUI systems.

To start with, we will explore the elements that make up the AmigaOS GUI system.

=== Screens ===

As start-up, the Workbench will be running on its "Workbench Screen". This will be the default location where most other application windows will also appear when started.

Typically an AmigaOS screen will have a "title bar" across the top with a graphical "depth gadget" at the right end. In the case of the Workbench screen, there will be an AmigaOS "boing ball" at the left end and the title bar will display certain system information (OS version, memory availability, etc.) Within the screen, the Workbench and any other applications can open windows, display icons and other GUI devices. If you right-click over the title bar, it becomes a "Menu Bar", showing you the control menus that are available for that application.

In many cases, other applications may open screens in addition to the Workbench screen. The "depth gadget" at the right end of each screen's title bar allows you to click from screen from screen. Besides clicking on the screen's depth gadet, AmigaOS also lets the user see other screens behind the front screen by "dragging" down on the screen title bar.

The characteristics of the Workbench screen such as resolution and color depth can be configured in the "Screenmode" preferences editor. Other screens can be either be configured in the "Screens" preferences editor or from within individual applications. Typically, AmigaOS applications also give the user the choice of whether application runs on their own screens or the "public" Workbench screen.

=== Windows ===
Windows are graphic containers that appear within AmigaOS screens. Windows can be created by any number of different applications - the Workbench, Shell sessions or applications. Outside of the Workbench file manager, each window usually reflects each individual running application. In some cases, one application may open multiple documents in separate windows or additional "requester" windows might appear for an application.

[[File:LibFig4-1.png]]

Almost all windows of AmigaOS will have these common elements:
* '''Borders''' - A border around the window's contents. Holding the Shift+Left-Amiga keys down while dragging any border will drag the window around.
* '''Title bar''' - A thicker top border that typically contains a name of the application or its contents. The area of the title bar acts as a "drag bar" which you can use to drag the window around the screen.
* '''Depth gadget''' - The right-most gadget in the top title bar that either pulls the window to front (if it isn't frontmost) or pushes it to the back (if it's in front). Holding down the Shift key while clicking this gagdet pushes the window to the back.

In AmigaOS, windows may also optionally have these additional features and elements:
* '''Close gadget''' - The left-most gadget in the title bar that closes the window.
* '''Scroll bar(s) and arrows''' - If the contents of the window can be scrolled in vertically and/or horizontally, there will be a scroll bar with arrow scroll buttons. These scroll bars can also be used if the mouse pointer is over a scroll bar and the mouse scroll wheel is used.
* '''Zoom gadget''' - the second gadget from the right-most of the title bar which switches the window between two sizes. Holding down the Shift key while clicking this gadget will make it fill the screen.
* '''Iconification gadget''' - left-most of the right-hand gadgets in the title bar which causes the window to disappear into an icon on the Workbench background - thus "Iconifying" the window or application.
* '''Sizing gadget''' - In the case of windows that can be resized, this is the gadget in the bottom right corner of the window that you can drag to resize the window.

Each AmigaOS application can use many different combinations of these features in the make up of their windows.

=== Menus ===

[[File:LibFig2-4.png|frame|right]]
Menus are lists of items that will allow you to see and use what commands are available in an application. The Workbench uses menus you can use to perform actions on the Workbench and its contents. Menus typically provide many more functions and commands than can be presented to the user than just graphic buttons, etc. within an application's window, as a result they are a primary way most applications are used.

In AmigaOS menus can always be found for the current application by moving the mouse to the top of the screen and holding down the right mouse button. The screen title bar will become a menu bar and will show the names of all the current application's menus.

By dragging with the right mouse button, each menu will display its "menu items". Each of those menu items corresponds to a command or setting, and can be selected by releasing the right mouse button while the desired menu item is highlighted. In some cases you will find a "check box" on a menu item which you can select to toggle a setting. In other cases, you will find that menu items have a little arrow head that indicates that item actually has a "sub-menu" - a menu within a menu. Menus ending with an ellipsis ("...") indicate that menu item will open a window that can be cancelled without committing any command. For those menu items that might be deactivated (they may not apply at the moment), they will be "greyed-out".

The labels of many menu items will also include a letter or two with an "A" at the right edge. This indicates what the keyboard Right-Amiga "short cut" is the equivalent of using that menu item within that application. In the above screen shot, you can see that pressing the two keys - "Right-Amiga" and "N" - would do the same as that menu item - to create a new drawer.
 

====Consistent Organization====
For the sake of consistency (when applicable), the first two AmigaOS menus of any application are typically organized with the following hierarchy and use these keyboard equivalents:

{| border="0"
|'''First Menu:'''
----
|| || Keyboard equivalent: || '''Second Menu:'''
----
|| || Keyboard equivalent:
|-
|'''PROJECT'''
----
|| || ||'''EDIT'''
----
||
|-
|'''New'''|| = Create new project in application.||Right-Amiga N||'''Cut'''|| = Cut the selected content into the Clipboard.||Right-Amiga X
|-
|'''Open...'''|| = Open the file containing a project.||Right-Amiga O||'''Copy'''|| = Copy the selected content into the Clipboard.||Right-Amiga C
|-
|'''Save'''|| = Save the project to it's current file name.||Right-Amiga S||'''Paste'''|| = Paste the Clipboard contents into the project (at the current location).||Right-Amiga V
|-
|'''Save As...'''|| = Save the project to a file of a new name.|| ||'''Undo'''|| = Undo the last change to current project.||Right-Amiga Z
|-
|'''Print'''|| = Print the current project.||Right-Amiga P||'''Redo'''|| = Restore the last change "undone" in the current project.||
|-
|'''Close'''|| = Close the project.|| || || ||
|-
|'''Quit'''|| = Quit the application.||Right-Amiga Q||
|}

====Menu Variations====
AmigaOS also includes some additional ways menus can be presented to the user:

=====Pop-Up Menus=====

[[File:OS4-WBPopUpMenu.jpg|frame|right]]
In the GUI preferences editor you can configure menus to "pop-up" under the mouse pointer whenever you right-click the mouse. This means you do not need to move the mouse to the top of the screen to use the menus. There are also options for making menus "sticky", meaning that you don't need to drag the mouse to navigate the menus, but rather just right click and the menus stay open till you make a selection or click away.
 

=====Context Menus=====

[[File:OS4-WBContextMenu.jpg|frame|right]]
The Workbench (with a utility added by default) and many applications provide "contextual menus". This means that you can put your mouse pointer over elements and right-click to pop-up a menu of things that are specific to the item you clicked over. In the case of the Workbench (with the Context Menus utility), right clicking on a file will pop-up a menu of things that could be done with that file, like deleting it.

All of these features provide both a simple means of using many functions within an application and at the same time allowing the user to configure a very efficient user interface that responds to nearly every whim.
 

=== Icons ===

==== Description ====
Icons are small images which can represent a disk, a directory, an application file or data file. Icons are primarilly used within the AmigaOS Workbench environment to represent all the file system objects the user can manipulate. With these icons it is possible to select files, open them, delete them or move them around within the Workbench. Applications may also make more limited use of icons to represent file system objects or may be used as imagery in an "icon bar" of buttons that can be clicked to perform various actions represented by icon imagery, like the Clock above.

{|style="text-align: center;"
|[[File:LibDiskIcon.png|frame|left|100px|Drive icon]] [[File:Icons.png|frame|right|Directory with sub-directory, data and application file icons]]
|}

AmigaOS also uses different icon imagery to indicate various types of icons - drives, directories, files and applications. Drive or partition icons look like little hard drives.
A directory icon will look like a cabinet & drawer whereas a file icon will be designed to give a clue about the file content.
Data files are normally shown with a "page" motif and some graphics or text to reflect the file type.
Application files typically have the most free-form graphics that reflect their purpose, name or developer.

The user can also edit the icon imagery using the icon editor, change how icons react to being double-clicked and adjust parameters stored within the icon file that affect how the represented file will be used.

Many applications and all AmigaOS file requesters allow Workbench icons to be "dragged and dropped" into the application or requester windows and the associated file will be recognized by the application, if possible.

==== Icon states ====

Icons can look different not only because of their image but also depending on their state.

As you can see in the directory example, the 2 top left icons appear semi-transparent. This subtle difference reflects whether the file or directory has an associated icon file with it. In AmigaOS, any directory or file can have such an icon file that stores a unique icon image, unique program settings or specific settings for that file or directory. That information can be adjusted within the Workbench and is automatically stored in a companion file with the same name, but with an added '''.info''' suffix.

While many files and directories and most applications have such ".info files" with them, they are not required and the Workbench can be set to show you "default icons" (based on the file types, etc.) so you can manipulate the corresponding objects. Of course, AmigaOS can also be configured on a directory-by-directory basis to only show files that have associated ".info" files.

In the same picture, the two top right directory icons also look slightly different. While the '''Utilities selected''' and the '''Utilities unselected''' are the same icon, their image is a bit different. The drawer of the first one is slightly opened and there is a "glow" effect arround the first icon. These two visual clues show you the first directory icon has been selected by the user whereas the second one is not.

==== App Icons ====

Many applications provide the option to be "iconified" either by clicking on an iconification gadget in their window title bars or by selecting a menu item. In those events, the application's window will disappear and an "app icon" will appear on the background of the Workbench screen. Double-clicking on the app icon will cause the icon to disappear and the application's window to reappear. Even while the application is iconified, it does continue to run and perform whatever the user may have it doing.

Some applications may also place an app icon on the Workbench background even while the application is open to allow the user to be able to drop other file icons on the app icon and have them be used by the application.

=== Graphic gadgets ===
Within AmigaOS and application windows, there can be any number of graphic devices meant to be operated by your mouse with clicks and drags - these are known as "gagdets". In most cases, the gagdets are simple analogs of real world objects - like buttons you press with your finger, forms you fill out with a pencil or tabs on folders.

[[File:LibFig5-1.png]]

==== Buttons ====

[[File:OS4-Buttons.jpg|frame|right]]
Buttons (or "Boolean gadgets") are some of the most common GUI objects. With a simple left-click of your mouse button, they are used to perform actions, set configurations or indicate choices.

In AmigaOS, clicking "down" on a button typically causes the button to be rendered differently, to reflect that it has been "pressed". Engaging the button is not actually recognized until you let go with the mouse button over the graphic gadget. This means that while the gadget has been clicked down, you always have the option of moving the mouse off the button gadget and then letting go and it will be as though the button had never been "pressed" or clicked on.
 
==== Text gadgets ====

[[File:OS4-StringGadgets.jpg|frame|right]]
A text gadget (or "String gadget") works like a space in a paper form to be filled out - left click in the gadget, you will see a cursor appear and you can type your answer.
Once you've finished typing your infrormation, you can either press the enter, carriage-return or tab keys for your entry to be recognized.

Text or string gadgets can also come in a number of variants for specific uses. Some can limit input to be numeric only (and may have adjacent buttons to increment or decrement the value). Some string gadgets may be specifically be meant for file or directory names and they have adjacent gagdets that will bring up a file requester to set the value. Many times a numeric gadget is paired with a slider gadget (as in the example above), where the value can either be set by typing in the gadget or by using the slider.
 
==== Sliders & Scroll Bars ====

[[File:OS4-SliderGadgets.jpg|frame|right]]
Slider gadgets work like controls many of have seen on their stereo systems - left-click and drag on the gadget "knob" to move it back and forth to set a value. A more sophisticated variant of the slider is the "scroll bar" that has a variably sized scroll bar contained in a scroll box that lets you see what proportion of the active range is visible or active.

With all slider and scroller gadgets AmigaOS also lets you click in the area to either side of the knob or slider to adjust the setting. In the case of sliders, the value will typically move by a fixed amount (+/- 1 or some suitable increment). In the case of scroll bars, clicking in the scroll box on either side of the scroll bar will cause the value to move in increments of the scroll bar size. Scroll bars also come with "scroll arrows" at the end of the scroll box that allow for finer movement of the scroll bar.
 
==== Cycle gadgets ====

[[File:OS4-CycleGadgets.jpg|frame|right]]
Cycle gagdets are a variant on buttons that let you select from a number of specific choices. You can either click on the majority of the gadget to pop-up a list of choices to select from or click on the circular arrow to cycle between the list of choices. Cycle gagdets rarely cause actions to occur, they just adjust some setting or configuration.
 
==== Check Box & Radio Button gadgets ====

[[File:OS4-CheckRadioGadgets.jpg|frame|right]]
Another variant of buttons, check boxes can be clicked to set on/off or yes/no conditions with a checkmark, just like a check box in a paper form. Radio buttons are another variant where two or more round buttons are presented in a set and only one of the set can be clicked and activated, like the buttons on a stereo system.
 
==== Tabs ====

[[File:OS4-Tabs.jpg|frame|right]]
Tabs are a graphical gadget that is used in combination with a "pages" or sets of gadgets and/or information, and you can click on the "tabs" to switch between the pages - like you might in a real notebook with tabbed pages. This provides a efficient way to present more information and settings in a compact interface.
 
====Requesters====

[[File:LibFig2-5.png|frame|right]]
As one uses AmigaOS and its applications, from time to time a "Requester" window may appear to ask the user a question - basically windows with gadgets in them. Such requesters can appear to confirm an action, obtain more information, make a selection or configuration. Typically a series of buttons across the bottom of the window will dispatch the requester, with the bottom-left button gadget indicating some affirmative choice and the bottom-right button gagdet cancelling the requester (performing no action or change).
 

====Keyboard Operation of Gadgets====
As with so many things, AmigaOS and its applications provide a secondary way to operate many of these gadgets - by keyboard. If a window contains text gadgets, pressing your keyboard's TAB key will activate the text gadgets in sequence (a cursor will appear in each so you can type & edit). Each press of the TAB key will cycle to the next gadget and pressing SHIFT + TAB will cycle through the gadgets in reverse order.

You may have noticed in many of the above sample images that many of the gagdets or their adjacent "label" texts contain a single underlined character. This is a sign that pressing that key on your keyboard will activate that gadget. Each gadget can then be operated by your keyboard - just like clicking on a button, clicking on a tab, setting a text or numeric value, etc. Of course, if you are in the midst of typing in a text gadget, then things you type will go into that gadget instead of operating other gagdets.

== Finding Files in AmigaOS ==

[[File:OS4-ASLReq.jpg|frame|right]]
AmigaOS provides a consistent method for navigating your file system and finding your files from within your apps - the "ASL file requester". It is used by everything in AmigaOS and most third party applications. It is the window (or "requester") that appears when you want to open or save files.

As you can see, the ASL file requester presents the files in a given location in your file systems (a directory or "drawer") and shows their size, date of creation or last modification and any comments attached to the file. The above example shows the same directory as appeared above in this page.

At the bottom corners of the window are buttons to accept the selection ("OK") or cancel the requester. Between those are buttons to view all the drives & partitions on your system ("Volumes") or to move to the "Parent" of the current directory.

Also at the bottom of the window you will see three text gadgets. The first of these is optional and allows you to filter what is shown in the file list - it is now shown filtering out any file with a ".info" suffix (those are AmigaOS icon files). The next two lines reflect the current directory path name and the currently selected file name (also selected in the file list above). In the case of saving files, you would type any name you wanted in the bottom text field to create a new file. Clicking on the titles of the file list will let you sort the file list.

Of course this being AmigaOS, the ASL requester has its own "preferences editor" that lets you set how the requester appears, is sorted by default and a number of mouse button short-cuts.
 

== Controlling AmigaOS - Which Way? ==

AmigaOS provides a number of parallel ways that the user can control and put their Amigas to use. The easiest and most common method is to use the AmigaOS graphic icons, windows and mouse interface - the "Workbench" - using all the GUI elements described above. But AmigaOS also provides a more traditional or "old fashioned" method called a command line interface (the "CLI" or "Shell"), where the user can type text commands and interact using a text interface. AmigaOS also provides a unique means of "interprocess communications" where user can have many applications and parts of the OS "talk" to each other.

=== The Workbench & Intuition ===

As we described above, AmigaOS provides the "Workbench", a straightforward, efficient and easy graphical means to start applications, manage your computer and all your files. Files and programs are represented with icons, generally known as "Projects" and "Tools". They can be stored in any arrangement of directories ("Drawers"). You double-click on a program icon and it will open in a Intuition GUI window on your Workbench screen.

Please see the section about the AmigaOS [http://wiki.amigaos.net/index.php/UserDoc:Workbench Workbench] to learn these concepts:

* What is the Workbench
* Workbench menus
* Keyboard control
* Workbench requesters
* Configuration
* Workbench help

=== The Shell & DOS Commands ===

[[File:OS4-Window-Shell.jpg|frame|right]]
The AmigaOS Shell can be opened by double-clicking the "Shell" icon in the AmigaOS "System" drawer. The Shell is a text based interface that allows you to perform most of the same operations as the Workbench - to run and interact with application programs, manage files and control your Amiga computer. AmigaOS also comes with dozens of standard "DOS commands" (programs purely meant for Shell usage). Simply enter the name of a program or command (like "dir") and press Enter, the command or program will run and it will print its results in the Shell window. While considered old fashioned, many users find the Shell to still be the most efficient way to perform many tasks on the Amigas.

Please see the section on the [[UserDoc:Shell|AmigaOS Shell]] to learn more.
 

=== Scripts & Messages ===

Scripts are simple text files that contain a list of commands written in a variety of languages: the AmigaDOS, Arexx and Python languages are provided with AmigaOS - there are many others. Each of these language has its strengths. You'll have to learn the one that suits what you want to do. You can create a script using a text editor. You can run such scripts from the Workbench or from the shell (or from any other script). By using ARexx ports provided by AmigaOS components (the Workbench or Multiview, for example) or third-party applications, scripts can be used to make your computer perform a wide variety of actions.

== AmigaOS System Tools ==
AmigaOS comes with a variety of programs to help in the preparation of your computer. These include tools for:

* Drive preparation (Media Toolbox, Format, Format DCRW & Mounter).
* Font Handling (TypeManager & FixFonts).
* Script Languages (RexxMast and Python).
* The Shell.
* Miscellaneous Utilities (Find, Help, Grim Reaper & Ringhio Server).

== AmigaOS Utilities ==
AmigaOS comes with a selection of utilities to assist the user, including:

* Commodities.
* Editors (Notepad, MEmacs, PrefsObjectEditor & IconEdit).
* Postscript oriented apps (AmiPDF, AmiGS & Ghostscript).
* Disk apps (PartitionWizard & RawDisk).
* Screenblankers.
* AmiDock and Dockies.
* The Unarc dearchiver.
* PlayCD.
* Several "sub-programs" that are used by other system utilities (blankers, dockies)
* Miscellaneous apps (Clock, printing apps, KeyShow, install apps, etc.).

Read [[Utilities|here]] to find all of them explained further.

== AmigaOS Preferences ==
AmigaOS comes with a number of small programs used for modifying the system's settings. These are stored in the [[Prefs]] drawer, and include programs for modifying the following settings:

* General appearance
* Screen resolution
* Desktop and window backgrounds
* Language settings
* Keyboard and mouse settings
* Printer settings
* Audio settings

Read [[Prefs|here]] for details and explanations of all the preference programs.

UserDoc:Introduction to AmigaOS

2014-06-05T14:18:38Z

Rob Cranley: /* Requesters */ Grammar correction: removed unnecessary apostrophe. Also removed unnecessary double spacing.

Like any modern personal computer system, AmigaOS presents a graphic interface and relies on common peripherals to let the user control their system.
Beyond most systems, AmigaOS provides more flexibility and options in how the user can approach, configure and use their Amiga computer.

In this page we will describe the details of AmigaOS graphic user interface (GUI) - how screens, windows and gadgets are presented and how you can use them.
We will also describe the various means by which the user can control and operate AmigaOS. In additional pages, you can read about [[UserDoc:How AmigaOS Works|how AmigaOS works]] and what its components are.

== AmigaOS Input - Point, Click and Type ==

There are two common ways you can use and control your AmigaOS system - by mouse and keyboard.

But AmigaOS also lets you control your system by other input devices (like touchscreens or voice recognition) depending on drivers and devices connected. Depending on software installed, AmigaOS can also be remotely controlled by networked protocols (like VNC and Synergy). Finally, AmigaOS can be controlled internal scripts set up by the User.

=== Using the mouse ===

[[File:Style2.5.png|frame|right]]

Typically in AmigaOS, you use a mouse to act on graphic elements (like "gadgets", "icons" or webpage "links"). By default, AmigaOS expects and supports mice or trackball pointing devices with at least two buttons. The left mouse button is used to "left-click" on graphic objects, to select them or operate them. The right mouse button is used to "right-click" and display the menus of the current application.

Optionally, one can use a mouse or trackball device with three (a "middle" button) and four buttons. With such devices, the functionality of the additional buttons can vary by application or environment. These functionalities can typically be configured by the user in specific applications or within AmigaOS (globally).

Furthermore, scroll wheels are supported by AmigaOS in a context-based fashion. If the current application's window is scrollable, the scrollwheel will act on that area. If the mouse pointer is positioned over a specifically scrollable gadget, the scrollwheel will affect that gadget.

In some applications and environments, you can also "double-click" (click twice, quickly) with the left button on an object to engage them. In the Workbench file manager, a single mouse click will only "select" an icon, whereas a double-click will open drawer/directory, run an application or open a file in an associated program.

Beside "clicking" - pressing down and releasing a mouse button at a specific location - you can also perform what is known as "dragging", which means clicking down and then moving the mouse around before releasing the mouse button. This is typically always done with the left mouse button and is done to select objects (draw a box around them), to adjust a control slider or to resize a window.

 

=== Using the keyboard ===

Of course the keyboard is used to enter text into text editing areas. But your keyboard can do so much more with its special "qualifier" keys and AmigaOS.

The most common example of a qualifier key is the "Shift" key which causes typed text to be made upper-case or capitalized. There are more qualifier keys on most keyboards, here is a list of all of them:
* '''the Shift keys''' - the common key that causes your text to be capitalized.
* '''The "Alternate" keys''' - the "Alt" keys typically to the bottom right and left of the keyboard.
* '''the "Control" keys''' - the "Ctrl" keys also to the bottom right and left of the keyboard.
* '''the "Amiga" keys''' - special "A" keys on the right and left side of the space bar. Besides being unique to AmigaOS, the right and left Amiga keys always mean different things (unlike the rest of the qualifier keys, most of the time). If you have a non-AmigaOS keyboard, the "Windows" or MacOS "Command" keys function as "Amiga" keys.
** '''the Right Amiga key''' - is used for "short cuts" within your current application.
** '''the Left Amiga key''' - is used for "short cuts" that are globally active anytime and anywhere in your AmigaOS system.
While all of these qualifier keys don't usually do anything on their own, when you press and hold one or more of these keys down while pressing regular keys, they can change what you type (capitalizing or making alternate characters) or become powerful "short-cuts" within your applications or throughout your entire AmigaOS system.

The most famous short-cuts are the '''copy''', '''cut''' and '''paste''' operations that you can perform on selected text:
* the '''Right-Amiga C''' short-cut copies any selected text or content to the Clipboard.
* the '''Right-Amiga X''' short-cut "cuts" any selected text or content to the Clipboard.
* the '''Right-Amiga V''' short-cut "pastes" any text or content from the Clipboard into your application (at the current cursor location).

== The AmigaOS GUI - Intuition ==

When AmigaOS has started, you will typically see the Workbench file manager. This is the start of your experience with the AmigaOS GUI and it's most basic elements: a screen with menus and windows containing icons and "gagdets". These components are the basic building blocks of virtually all AmigaOS & application interfaces.

As with most things in AmigaOS, almost all of the following components can also be almost infinitely reconfigured, adjusted and graphically varied by the user. In the AmigaOS "Preferences" drawer, the "GUI", "ASL", "Locale", "Font", "Palette", "Poiner", "PopUpMenu", "Screens", "Workbench" and "WBPattern" preferences editors easily allow a user to reconfigure the GUI of their Amiga in drammatic ways.

AmigaOS also supports the use of alternate GUI systems in parallel with the default "Intuition" (aka "Reaction") GUI system. By default AmigaOS also comes with the "Magic User Interface system ("MUI", a variant of the basic AmigaOS GUI system. More than Intuition, MUI can be reconfigured even more widely using its own MUI configuration app.

Additionally, AmigaOS can use a number of third-party "cross-platform" GUI systems: "AmiCygnix" GUI system - a native X11 GUI implementation for AmigaOS - and a native port of the "Qt" GUI system. With either of these systems, it is possible to run ported applications compiled for AmigaOS, but running with these cross-platform GUI systems.

To start with, we will explore the elements that make up the AmigaOS GUI system.

=== Screens ===

As start-up, the Workbench will be running on its "Workbench Screen". This will be the default location where most other application windows will also appear when started.

Typically an AmigaOS screen will have a "title bar" across the top with a graphical "depth gadget" at the right end. In the case of the Workbench screen,
there will be an AmigaOS "boing ball" at the left end and the title bar will display certain system information (OS version, memory availability, etc.). Within the screen, the Workbench and any other applications can open windows, display icons and other GUI devices. If you right-click over the title bar, it becomes a "Menu Bar", showing you the control menus that are available for that application.

In many cases, other applications may open screens in addition to the Workbench screen. The "depth gadget" at the right end of each screen's title bar allows you to click from screen from screen. Besides clicking on the screen's depth gadet, AmigaOS also lets the user see other screens behind the front screen by "dragging' down on the screen title bar.

The characteristics of the Workbench screen such as resolution and color depth can be configured in the "Screenmode" preferences editor. Other screens can be either be configured in the "Screens" preferences editor or from within individual applications. Typically, AmigaOS applications also give the user the choice of whether application runs on their own screens or the "public" Workbench screen.

=== Windows ===
Windows are graphic containers that appear within AmigaOS screens. Windows can be created by any number of different applications - the Workbench, Shell sessions or applications. Outside of the Workbench file manager, each window usually reflects each individual running application. In some cases, one application may open multiple documents in separate windows or additional "requester" windows might appear for an application.

[[File:LibFig4-1.png]]

Almost all windows of AmigaOS will have these common elements:
* '''Borders''' - A border around the window's contents. Holding the Shift+Left-Amiga keys down while dragging any border will drag the window around.
* '''Title bar''' - A thicker top border that typically contains a name of the application or it's contents. The area of the title bar acts as a "drag bar" which you can use to drag the window around the screen.
* '''Depth gadget''' - The right-most gadget in the top title bar that either pulls the window to front (if it isn't frontmost) or pushes it to the back (if it's in front). Holding down the Shift key while clicking this gagdet pushes the window to the back.

In AmigaOS, windows may also optionally have these additional features and elements:
* '''Close gadget''' - The left-most gadget in the title bar that closes the window.
* '''Scroll bar(s) and arrows''' - If the contents of the window can be scrolled in vertically and/or horizontally, there will be a scroll bar with arrow scroll buttons. These scroll bars can also be used if the mouse pointer is over a scroll bar and the mouse scroll wheel is used.
* '''Zoom gadget''' - the second gadget from the right-most of the title bar which switches the window between two sizes. Holding down the Shift key while clicking this gadget will make it fill the screen.
* '''Iconification gadget''' - left-most of the right-hand gadgets in the title bar which causes the window to disappear into an icon on the Workbench background - thus "Iconifying" the window or application.
* '''Sizing gadget''' - In the case of windows that can be resized, this is the gadget in the bottom right corner of the window that you can drag to resize the window.

Each AmigaOS application can use almost infinite combinations of these features in the make up of their windows.

=== Menus ===

[[File:LibFig2-4.png|frame|right]]
Menus are lists of items that will allow you to see and use what commands are available in an application. The Workbench uses menus you can use to perform actions on the Workbench and its contents. Menus typically provide many more functions and commands than can be presented to the user than just graphic buttons, etc. within an application's window, as a result they are a primary way most applications are used.

In AmigaOS menus can always be found for the current application by moving the mouse to the top of the screen and right-clicking. The screen title bar will become a menu bar and will show the names of all the current application's menus.

By dragging with the right mouse button, each menu will display its "menu items". Each of those menu items corresponds to a command or setting. In some cases you will find a "check box" on a menu item which you can click on to toggle a setting. In other cases, you will find that menu items have a little arrow head that indicates that item actually has a "sub-menu" - a menu within a menu. Menus ending with ellipses ("...") indicate that menu item will open a window that can be cancelled without commiting any command. For those menu items that might be deactivated (they may not apply at the moment), they will be "greyed-out".

The labels of many menu items will also include a letter or two with an "A" at the right edge. This indicates what the keyboard Right-Amiga "short cut" is the equivalent of using that menu item within that application. In the above screen shot, you can see that pressing the two keys - "Right-Amiga" and "N" - would do the same as that menu item - to create a new drawer.
 

====Consistent Organization====
For the sake of consistency (when applicable), the first two AmigaOS menus of any application are typically organized with the following hierarchy and use these keyboard equivalents:

{| border="0"
|'''First Menu:'''
----
|| || Keyboard equivalent: || '''Second Menu:'''
----
|| || Keyboard equivalent:
|-
|'''PROJECT'''
----
|| || ||'''EDIT'''
----
||
|-
|'''New'''|| = Create new project in application.||Right-Amiga N||'''Cut'''|| = Cut the selected content into the Clipboard.||Right-Amiga X
|-
|'''Open...'''|| = Open the file containing a project.||Right-Amiga O||'''Copy'''|| = Copy the selected content into the Clipboard.||Right-Amiga C
|-
|'''Save'''|| = Save the project to it's current file name.||Right-Amiga S||'''Paste'''|| = Paste the Clipboard contents into the project (at the current location).||Right-Amiga V
|-
|'''Save As...'''|| = Save the project to a file of a new name.|| ||'''Undo'''|| = Undo the last change to current project.||Right-Amiga Z
|-
|'''Print'''|| = Print the current project.||Right-Amiga P||'''Redo'''|| = Restore the last change "undone" in the current project.||
|-
|'''Close'''|| = Close the project.|| || || ||
|-
|'''Quit'''|| = Quit the application.||Right-Amiga Q||
|}

====Menu Variations====
AmigaOS also includes a couple additional ways menus can be can serve the user:

=====Pop-Up Menus=====

[[File:OS4-WBPopUpMenu.jpg|frame|right]]
In the GUI preferences editor you can configure menus to "pop-up" under the mouse pointer whenever you right-click the mouse. This means you do not need to move the mouse to the top of the screen to use the menus. There are also options for making menus "sticky", meaning that you don't need to drag the mouse to navigate the menus, but rather just right click and the menus stay open till you make a selection or click away.
 

=====Context Menus=====

[[File:OS4-WBContextMenu.jpg|frame|right]]
The Workbench (with a utility added by default) and many applications provide "contextural menus". This means that you can put your mouse pointer over elements and right-click to pop-up a menu of things that are specific to the item you clicked over. In the case of the Workbench (with the Context Menus utility), right clicking on a file will pop-up a menu of things that could be done with that file, like deleting it.

All of these features provide both a simple means of using many functions within an application and at the same time allowing the user to configure a very efficient user interface that responds to nearly every whim.
 

=== Icons ===

==== Description ====
Icons are small images which can represent a disk, a directory, an application file or data file. Icons are primarilly used within the AmigaOS Workbench environment to represent all the file system objects the user can manipulate. With these icons it is possible to select files, open them, delete them or move them around within the Workbench. Applications may also make more limited use of icons to represent file system objects or may be used as imagery in an "icon bar" of buttons that can be clicked to perform various actions represented by icon imagery, like the Clock above.

{|style="text-align: center;"
|[[File:LibDiskIcon.png|frame|left|100px|Drive icon]] [[File:Icons.png|frame|right|Directory with sub-directory, data and application file icons]]
|}

AmigaOS also uses different icon imagery to indicate various types of icons - drives, directories, files and applications. Drive or partition icons look like little hard drives.
A directory icon will look like a cabinet & drawer whereas a file icon will be designed to give a clue about the file content.
Data files are normally shown with a "page" motif and some graphics or text to reflect the file type.
Application files typically have the most free-form graphics that reflect their purpose, name or developer.

The user can also edit the icon imagery using the icon editor, change how icons react to being double-clicked and adjust parameters stored within the icon file that affect how the represented file will be used.

Many applications and all AmigaOS file requesters allow Workbench icons to be "dragged and dropped" into the application or requester windows and the associated file will be recognized by the application, if possible.

==== Icon states ====

Icons can look different not only because of their image but also depending on their state.

As you can see in the directory example, the 2 top left icons appear semi-transparent. This subtle difference reflects whether the file or directory has an associated icon file with it. In AmigaOS, any directory or file can have such an icon file that stores a unique icon image, unique program settings or specific settings for that file or directory. That information can be adjusted within the Workbench and is automatically stored in a companion file with the same name, but with an added '''.info''' suffix.

While many files & directories and most applications have such ".info files" with them, they are not required and the Workbench can be set to show you "default icons" (based on the file types, etc.) so you can manipulate the corresponding objects. Of course, AmigaOS can also be configured on a directory-by-directory basis to only show files that have associated ".info" files.

In the same picture, the 2 top right directory icons also look slightly different. While the '''Utilities selected''' and the '''Utilities unselected''' are the same icon, their image is a bit different. The drawer of the first one is slightly opened and there is a "glow" effect arround the first icon. These two visual clues show you the first directory icon has been selected by the user whereas the second one is not.

==== App Icons ====

Many applications provide the option to be "iconified" either by clicking on an iconification gadget in their window title bars or by selecting a menu item. In those events, the application's window will disappear and an "app icon" will appear on the background of the Workbench screen. Double-clicking on the app icon will cause the icon to disappear and the application's window to reappear. Even while the application is iconified, it does continue to run and perform whatever the user may have it doing.

Some applications may also place an app icon on the Workbench background even while the application is open to allow the user to be able to drop other file icons on the app icon and have them be used by the application.

=== Graphic gadgets ===
Within AmigaOS and application windows, there can be any number of graphic devices meant to be operated by your mouse with clicks and drags - these are known as "gagdets". In most cases, the gagdets are simple analogs of real world objects - like buttons you press with your finger, forms you fill out with a pencil or tabs on folders.

[[File:LibFig5-1.png]]

==== Buttons ====

[[File:OS4-Buttons.jpg|frame|right]]
Buttons (or "Boolean gadgets") are some of the most common GUI objects. With a simple left-click of your mouse button, they are used to perform actions, set configurations or indicate choices.

In AmigaOS, clicking "down" on a button typically causes the button to be rendered differently, to reflect that it has been "pressed". Engaging the button is not actually recognized until you let go with the mouse button over the graphic gadget. This means that while the gadget has been clicked down, you always have the option of moving the mouse off the button gadget and then letting go and it will be as though the button had never been "pressed" or clicked on.
 
==== Text gadgets ====

[[File:OS4-StringGadgets.jpg|frame|right]]
A text gadget (or "String gadget") works like a space in a paper form to be filled out - left click in the gadget, you will see a cursor appear and you can type your answer.
Once you've finished typing your infrormation, you can either press the enter, carriage-return or tab keys for your entry to be recognized.

Text or string gadgets can also come in a number of variants for specific uses. Some can limit input to be numeric only (and may have adjacent buttons to increment or decrement the value). Some string gadgets may be specifically be meant for file or directory names and they have adjacent gagdets that will bring up a file requester to set the value. Many times a numeric gadget is paired with a slider gadget (as in the example above), where the value can either be set by typing in the gadget or by using the slider.
 
==== Sliders & Scroll Bars ====

[[File:OS4-SliderGadgets.jpg|frame|right]]
Slider gadgets work like controls many of have seen on their stereo systems - left-click and drag on the gadget "knob" to move it back and forth to set a value. A more sophisticated variant of the slider is the "scroll bar" that has a variably sized scroll bar contained in a scroll box that lets you see what proportion of the active range is visible or active.

With all slider and scroller gadgets AmigaOS also lets you click in the area to either side of the knob or slider to adjust the setting. In the case of sliders, the value will typically move by a fixed amount (+/- 1 or some suitable increment). In the case of scroll bars, clicking in the scroll box on either side of the scroll bar will cause the value to move in increments of the scroll bar size. Scroll bars also come with "scroll arrows" at the end of the scroll box that allow for finer movement of the scroll bar.
 
==== Cycle gadgets ====

[[File:OS4-CycleGadgets.jpg|frame|right]]
Cycle gagdets are a variant on buttons that let you select from a number of specific choices. You can either click on the majority of the gadget to pop-up a list of choices to select from or click on the circular arrow to cycle between the list of choices. Cycle gagdets rarely cause actions to occur, they just adjust some setting or configuration.
 
==== Check Box & Radio Button gadgets ====

[[File:OS4-CheckRadioGadgets.jpg|frame|right]]
Another variant of buttons, check boxes can be clicked to set on/off or yes/no conditions with a checkmark, just like a check box in a paper form. Radio buttons are another variant where two or more round buttons are presented in a set and only one of the set can be clicked and activated, like the buttons on a stereo system.
 
==== Tabs ====

[[File:OS4-Tabs.jpg|frame|right]]
Tabs are a graphical gadget that is used in combination with a "pages" or sets of gadgets and/or information, and you can click on the "tabs" to switch between the pages - like you might in a real notebook with tabbed pages. This provides a efficient way to present more information and settings in a compact interface.
 
====Requesters====

[[File:LibFig2-5.png|frame|right]]
As one uses AmigaOS and its applications, from time to time a "Requester" window may appear to ask the user a question - basically windows with gadgets in them. Such requesters can appear to confirm an action, obtain more information, make a selection or configuration. Typically a series of buttons across the bottom of the window will dispatch the requester, with the bottom-left button gadget indicating some affirmative choice and the bottom-right button gagdet cancelling the requester (performing no action or change).
 

====Keyboard Operation of Gadgets====
As with so many things, AmigaOS and its applications provide a secondary way to operate many of these gadgets - by keyboard. If a window contains text gadgets, pressing your keyboard's TAB key will activate the text gadgets in sequence (a cursor will appear in each so you can type & edit). Each press of the TAB key will cycle to the next gadget and pressing SHIFT + TAB will cycle through the gadgets in reverse order.

You may have noticed in many of the above sample images that many of the gagdets or their adjacent "label" texts contain a single underlined character. This is a sign that pressing that key on your keyboard will activate that gadget. Each gadget can then be operated by your keyboard - just like clicking on a button, clicking on a tab, setting a text or numeric value, etc. Of course, if you are in the midst of typing in a text gadget, then things you type will go into that gadget instead of operating other gagdets.

== Finding Files in AmigaOS ==

[[File:OS4-ASLReq.jpg|frame|right]]
AmigaOS provides a consistent method for navigating your file system and finding your files from within your apps - the "ASL file requester". It is used by everything in AmigaOS and most third party applications. It is the window (or "requester") that appears when you want to open or save files.

As you can see, the ASL file requester presents the files in a given location in your file systems (a directory or "drawer") and shows their size, date of creation or last modification and any comments attached to the file. The above example shows the same directory as appeared above in this page.

At the bottom corners of the window are buttons to accept the selection ("OK") or cancel the requester. Between those are buttons to view all the drives & partitions on your system ("Volumes") or to move to the "Parent" of the current directory.

Also at the bottom of the window you will see three text gadgets. The first of these is optional and allows you to filter what is shown in the file list - it is now shown filtering out any file with a ".info" suffix (those are AmigaOS icon files). The next two lines reflect the current directory path name and the currently selected file name (also selected in the file list above). In the case of saving files, you would type any name you wanted in the bottom text field to create a new file. Clicking on the titles of the file list will let you sort the file list.

Of course this being AmigaOS, the ASL requester has its own "preferences editor" that lets you set how the requester appears, is sorted by default and a number of mouse button short-cuts.
 

== Controlling AmigaOS - Which Way? ==

AmigaOS provides a number of parallel ways that the user can control and put their Amigas to use. The easiest and most common method is to use the AmigaOS graphic icons, windows and mouse interface - the "Workbench" - using all the GUI elements described above. But AmigaOS also provides a more traditional or "old fashioned" method called a command line interface (the "CLI" or "Shell"), where the user can type text commands and interact using a text interface. AmigaOS also provides a unique means of "interprocess communications" where user can have many applications and parts of the OS "talk" to each other.

=== The Workbench & Intuition ===

As we described above, AmigaOS provides the "Workbench", a straightforward, efficient and easy graphical means to start applications, manage your computer and all your files. Files and programs are represented with icons, generally known as "Projects" and "Tools". They can be stored in any arrangement of directories ("Drawers"). You double-click on a program icon and it will open in a Intuition GUI window on your Workbench screen.

Please see the section about the AmigaOS [http://wiki.amigaos.net/index.php/UserDoc:Workbench Workbench] to learn these concepts:

* What is the Workbench
* Workbench menus
* Keyboard control
* Workbench requesters
* Configuration
* Workbench help

=== The Shell & DOS Commands ===

[[File:OS4-Window-Shell.jpg|frame|right]]
The AmigaOS Shell can be opened by double-clicking the "Shell" icon in the AmigaOS "System" drawer. The Shell is a text based interface that allows you to perform most of the same operations as the Workbench - to run and interact with application programs, manage files and control your Amiga computer. AmigaOS also comes with dozens of standard "DOS commands" (programs purely meant for Shell usage). Simply enter the name of a program or command (like "dir") and press Enter, the command or program will run and it will print its results in the Shell window. While considered old fashioned, many users find the Shell to still be the most efficient way to perform many tasks on the Amigas.

Please see the section on the [[UserDoc:Shell|AmigaOS Shell]] to learn more.
 

=== Scripts & Messages ===

Scripts are simple text files that contain a list of commands written in a variety of languages: the AmigaDOS, Arexx and Python languages are provided with AmigaOS - there are many others. Each of these language has its strengths. You'll have to learn the one that suits what you want to do. You can create a script using a text editor. You can run such scripts from the Workbench or from the shell (or from any other script). By using ARexx ports provided by AmigaOS components (the Workbench or Multiview, for example) or third-party applications, scripts can be used to make your computer perform a wide variety of actions.

== AmigaOS System Tools ==
AmigaOS comes with a variety of programs to help in the preparation of your computer. These include tools for:

* Drive preparation (Media Toolbox, Format, Format DCRW & Mounter).
* Font Handling (TypeManager & FixFonts).
* Script Languages (RexxMast and Python).
* The Shell.
* Miscellaneous Utilities (Find, Help, Grim Reaper & Ringhio Server).

== AmigaOS Utilities ==
AmigaOS comes with a selection of utilities to assist the user, including:

* Commodities.
* Editors (Notepad, MEmacs, PrefsObjectEditor & IconEdit).
* Postscript oriented apps (AmiPDF, AmiGS & Ghostscript).
* Disk apps (PartitionWizard & RawDisk).
* Screenblankers.
* AmiDock and Dockies.
* The Unarc dearchiver.
* PlayCD.
* Several "sub-programs" that are used by other system utilities (blankers, dockies)
* Miscellaneous apps (Clock, printing apps, KeyShow, install apps, etc.).

Read [[Utilities|here]] to find all of them explained further.

== AmigaOS Preferences ==
AmigaOS comes with a number of small programs used for modifying the system's settings. These are stored in the [[Prefs]] drawer, and include programs for modifying the following settings:

* General appearance
* Screen resolution
* Desktop and window backgrounds
* Language settings
* Keyboard and mouse settings
* Printer settings
* Audio settings

Read [[Prefs|here]] for details and explanations of all the preference programs.

UserDoc talk:Main

2014-05-29T14:45:02Z

Rob Cranley: Created page with "Just a thought: Might it be a good idea to have a User Documentation navigation section to the left, similar to the current Developers section? I was thinking that a few links..."

Just a thought: Might it be a good idea to have a User Documentation navigation section to the left, similar to the current Developers section? I was thinking that a few links for reference for users might be a good thing, and much better than traversing through 2 or 3 pages to get to a reference section on Prefs programs or AmigaDOS commands or the likes? I'd add it myself but I'm not sure I'm able to...

UserDoc:Introduction to AmigaOS

2014-05-19T14:20:10Z

Rob Cranley: /* App Icons */ Grammar correction: "by menu item" -> "by selecting a menu item"

Like any modern personal computer system, AmigaOS presents a graphic interface and relies on common peripherals to let the user control their system.
Beyond most systems, AmigaOS provides more flexibility and options in how the user can approach, configure and use their Amiga computer.

In this page we will describe the details of AmigaOS graphic user interface (GUI) - how screens, windows and gadgets are presented and how you can use them.
We will also describe the various means by which the user can control and operate AmigaOS. In additional pages, you can read about [[UserDoc:How AmigaOS Works|how AmigaOS works]] and what its components are.

== AmigaOS Input - Point, Click and Type ==

There are two common ways you can use and control your AmigaOS system - by mouse and keyboard.

But AmigaOS also lets you control your system by other input devices (like touchscreens or voice recognition) depending on drivers and devices connected. Depending on software installed, AmigaOS can also be remotely controlled by networked protocols (like VNC and Synergy). Finally, AmigaOS can be controlled internal scripts set up by the User.

=== Using the mouse ===

[[File:Style2.5.png|frame|right]]

Typically in AmigaOS, you use a mouse to act on graphic elements (like "gadgets", "icons" or webpage "links"). By default, AmigaOS expects and supports mice or trackball pointing devices with at least two buttons. The left mouse button is used to "left-click" on graphic objects, to select them or operate them. The right mouse button is used to "right-click" and display the menus of the current application.

Optionally, one can use a mouse or trackball device with three (a "middle" button) and four buttons. With such devices, the functionality of the additional buttons can vary by application or environment. These functionalities can typically be configured by the user in specific applications or within AmigaOS (globally).

Furthermore, scroll wheels are supported by AmigaOS in a context-based fashion. If the current application's window is scrollable, the scrollwheel will act on that area. If the mouse pointer is positioned over a specifically scrollable gadget, the scrollwheel will affect that gadget.

In some applications and environments, you can also "double-click" (click twice, quickly) with the left button on an object to engage them. In the Workbench file manager, a single mouse click will only "select" an icon, whereas a double-click will open drawer/directory, run an application or open a file in an associated program.

Beside "clicking" - pressing down and releasing a mouse button at a specific location - you can also perform what is known as "dragging", which means clicking down and then moving the mouse around before releasing the mouse button. This is typically always done with the left mouse button and is done to select objects (draw a box around them), to adjust a control slider or to resize a window.

 

=== Using the keyboard ===

Of course the keyboard is used to enter text into text editing areas. But your keyboard can do so much more with its special "qualifier" keys and AmigaOS.

The most common example of a qualifier key is the "Shift" key which causes typed text to be made upper-case or capitalized. There are more qualifier keys on most keyboards, here is a list of all of them:
* '''the Shift keys''' - the common key that causes your text to be capitalized.
* '''The "Alternate" keys''' - the "Alt" keys typically to the bottom right and left of the keyboard.
* '''the "Control" keys''' - the "Ctrl" keys also to the bottom right and left of the keyboard.
* '''the "Amiga" keys''' - special "A" keys on the right and left side of the space bar. Besides being unique to AmigaOS, the right and left Amiga keys always mean different things (unlike the rest of the qualifier keys, most of the time). If you have a non-AmigaOS keyboard, the "Windows" or MacOS "Command" keys function as "Amiga" keys.
** '''the Right Amiga key''' - is used for "short cuts" within your current application.
** '''the Left Amiga key''' - is used for "short cuts" that are globally active anytime and anywhere in your AmigaOS system.
While all of these qualifier keys don't usually do anything on their own, when you press and hold one or more of these keys down while pressing regular keys, they can change what you type (capitalizing or making alternate characters) or become powerful "short-cuts" within your applications or throughout your entire AmigaOS system.

The most famous short-cuts are the '''copy''', '''cut''' and '''paste''' operations that you can perform on selected text:
* the '''Right-Amiga C''' short-cut copies any selected text or content to the Clipboard.
* the '''Right-Amiga X''' short-cut "cuts" any selected text or content to the Clipboard.
* the '''Right-Amiga V''' short-cut "pastes" any text or content from the Clipboard into your application (at the current cursor location).

== The AmigaOS GUI - Intuition ==

When AmigaOS has started, you will typically see the Workbench file manager. This is the start of your experience with the AmigaOS GUI and it's most basic elements: a screen with menus and windows containing icons and "gagdets". These components are the basic building blocks of virtually all AmigaOS & application interfaces.

As with most things in AmigaOS, almost all of the following components can also be almost infinitely reconfigured, adjusted and graphically varied by the user. In the AmigaOS "Preferences" drawer, the "GUI", "ASL", "Locale", "Font", "Palette", "Poiner", "PopUpMenu", "Screens", "Workbench" and "WBPattern" preferences editors easily allow a user to reconfigure the GUI of their Amiga in drammatic ways.

AmigaOS also supports the use of alternate GUI systems in parallel with the default "Intuition" (aka "Reaction") GUI system. By default AmigaOS also comes with the "Magic User Interface system ("MUI", a variant of the basic AmigaOS GUI system. More than Intuition, MUI can be reconfigured even more widely using its own MUI configuration app.

Additionally, AmigaOS can use a number of third-party "cross-platform" GUI systems: "AmiCygnix" GUI system - a native X11 GUI implementation for AmigaOS - and a native port of the "Qt" GUI system. With either of these systems, it is possible to run ported applications compiled for AmigaOS, but running with these cross-platform GUI systems.

To start with, we will explore the elements that make up the AmigaOS GUI system.

=== Screens ===

As start-up, the Workbench will be running on its "Workbench Screen". This will be the default location where most other application windows will also appear when started.

Typically an AmigaOS screen will have a "title bar" across the top with a graphical "depth gadget" at the right end. In the case of the Workbench screen,
there will be an AmigaOS "boing ball" at the left end and the title bar will display certain system information (OS version, memory availability, etc.). Within the screen, the Workbench and any other applications can open windows, display icons and other GUI devices. If you right-click over the title bar, it becomes a "Menu Bar", showing you the control menus that are available for that application.

In many cases, other applications may open screens in addition to the Workbench screen. The "depth gadget" at the right end of each screen's title bar allows you to click from screen from screen. Besides clicking on the screen's depth gadet, AmigaOS also lets the user see other screens behind the front screen by "dragging' down on the screen title bar.

The characteristics of the Workbench screen such as resolution and color depth can be configured in the "Screenmode" preferences editor. Other screens can be either be configured in the "Screens" preferences editor or from within individual applications. Typically, AmigaOS applications also give the user the choice of whether application runs on their own screens or the "public" Workbench screen.

=== Windows ===
Windows are graphic containers that appear within AmigaOS screens. Windows can be created by any number of different applications - the Workbench, Shell sessions or applications. Outside of the Workbench file manager, each window usually reflects each individual running application. In some cases, one application may open multiple documents in separate windows or additional "requester" windows might appear for an application.

[[File:LibFig4-1.png]]

Almost all windows of AmigaOS will have these common elements:
* '''Borders''' - A border around the window's contents. Holding the Shift+Left-Amiga keys down while dragging any border will drag the window around.
* '''Title bar''' - A thicker top border that typically contains a name of the application or it's contents. The area of the title bar acts as a "drag bar" which you can use to drag the window around the screen.
* '''Depth gadget''' - The right-most gadget in the top title bar that either pulls the window to front (if it isn't frontmost) or pushes it to the back (if it's in front). Holding down the Shift key while clicking this gagdet pushes the window to the back.

In AmigaOS, windows may also optionally have these additional features and elements:
* '''Close gadget''' - The left-most gadget in the title bar that closes the window.
* '''Scroll bar(s) and arrows''' - If the contents of the window can be scrolled in vertically and/or horizontally, there will be a scroll bar with arrow scroll buttons. These scroll bars can also be used if the mouse pointer is over a scroll bar and the mouse scroll wheel is used.
* '''Zoom gadget''' - the second gadget from the right-most of the title bar which switches the window between two sizes. Holding down the Shift key while clicking this gadget will make it fill the screen.
* '''Iconification gadget''' - left-most of the right-hand gadgets in the title bar which causes the window to disappear into an icon on the Workbench background - thus "Iconifying" the window or application.
* '''Sizing gadget''' - In the case of windows that can be resized, this is the gadget in the bottom right corner of the window that you can drag to resize the window.

Each AmigaOS application can use almost infinite combinations of these features in the make up of their windows.

=== Menus ===

[[File:LibFig2-4.png|frame|right]]
Menus are lists of items that will allow you to see and use what commands are available in an application. The Workbench uses menus you can use to perform actions on the Workbench and its contents. Menus typically provide many more functions and commands than can be presented to the user than just graphic buttons, etc. within an application's window, as a result they are a primary way most applications are used.

In AmigaOS menus can always be found for the current application by moving the mouse to the top of the screen and right-clicking. The screen title bar will become a menu bar and will show the names of all the current application's menus.

By dragging with the right mouse button, each menu will display its "menu items". Each of those menu items corresponds to a command or setting. In some cases you will find a "check box" on a menu item which you can click on to toggle a setting. In other cases, you will find that menu items have a little arrow head that indicates that item actually has a "sub-menu" - a menu within a menu. Menus ending with ellipses ("...") indicate that menu item will open a window that can be cancelled without commiting any command. For those menu items that might be deactivated (they may not apply at the moment), they will be "greyed-out".

The labels of many menu items will also include a letter or two with an "A" at the right edge. This indicates what the keyboard Right-Amiga "short cut" is the equivalent of using that menu item within that application. In the above screen shot, you can see that pressing the two keys - "Right-Amiga" and "N" - would do the same as that menu item - to create a new drawer.
 

====Consistent Organization====
For the sake of consistency (when applicable), the first two AmigaOS menus of any application are typically organized with the following hierarchy and use these keyboard equivalents:

{| border="0"
|'''First Menu:'''
----
|| || Keyboard equivalent: || '''Second Menu:'''
----
|| || Keyboard equivalent:
|-
|'''PROJECT'''
----
|| || ||'''EDIT'''
----
||
|-
|'''New'''|| = Create new project in application.||Right-Amiga N||'''Cut'''|| = Cut the selected content into the Clipboard.||Right-Amiga X
|-
|'''Open...'''|| = Open the file containing a project.||Right-Amiga O||'''Copy'''|| = Copy the selected content into the Clipboard.||Right-Amiga C
|-
|'''Save'''|| = Save the project to it's current file name.||Right-Amiga S||'''Paste'''|| = Paste the Clipboard contents into the project (at the current location).||Right-Amiga V
|-
|'''Save As...'''|| = Save the project to a file of a new name.|| ||'''Undo'''|| = Undo the last change to current project.||Right-Amiga Z
|-
|'''Print'''|| = Print the current project.||Right-Amiga P||'''Redo'''|| = Restore the last change "undone" in the current project.||
|-
|'''Close'''|| = Close the project.|| || || ||
|-
|'''Quit'''|| = Quit the application.||Right-Amiga Q||
|}

====Menu Variations====
AmigaOS also includes a couple additional ways menus can be can serve the user:

=====Pop-Up Menus=====

[[File:OS4-WBPopUpMenu.jpg|frame|right]]
In the GUI preferences editor you can configure menus to "pop-up" under the mouse pointer whenever you right-click the mouse. This means you do not need to move the mouse to the top of the screen to use the menus. There are also options for making menus "sticky", meaning that you don't need to drag the mouse to navigate the menus, but rather just right click and the menus stay open till you make a selection or click away.
 

=====Context Menus=====

[[File:OS4-WBContextMenu.jpg|frame|right]]
The Workbench (with a utility added by default) and many applications provide "contextural menus". This means that you can put your mouse pointer over elements and right-click to pop-up a menu of things that are specific to the item you clicked over. In the case of the Workbench (with the Context Menus utility), right clicking on a file will pop-up a menu of things that could be done with that file, like deleting it.

All of these features provide both a simple means of using many functions within an application and at the same time allowing the user to configure a very efficient user interface that responds to nearly every whim.
 

=== Icons ===

==== Description ====
Icons are small images which can represent a disk, a directory, an application file or data file. Icons are primarilly used within the AmigaOS Workbench environment to represent all the file system objects the user can manipulate. With these icons it is possible to select files, open them, delete them or move them around within the Workbench. Applications may also make more limited use of icons to represent file system objects or may be used as imagery in an "icon bar" of buttons that can be clicked to perform various actions represented by icon imagery, like the Clock above.

{|style="text-align: center;"
|[[File:LibDiskIcon.png|frame|left|100px|Drive icon]] [[File:Icons.png|frame|right|Directory with sub-directory, data and application file icons]]
|}

AmigaOS also uses different icon imagery to indicate various types of icons - drives, directories, files and applications. Drive or partition icons look like little hard drives.
A directory icon will look like a cabinet & drawer whereas a file icon will be designed to give a clue about the file content.
Data files are normally shown with a "page" motif and some graphics or text to reflect the file type.
Application files typically have the most free-form graphics that reflect their purpose, name or developer.

The user can also edit the icon imagery using the icon editor, change how icons react to being double-clicked and adjust parameters stored within the icon file that affect how the represented file will be used.

Many applications and all AmigaOS file requesters allow Workbench icons to be "dragged and dropped" into the application or requester windows and the associated file will be recognized by the application, if possible.

==== Icon states ====

Icons can look different not only because of their image but also depending on their state.

As you can see in the directory example, the 2 top left icons appear semi-transparent. This subtle difference reflects whether the file or directory has an associated icon file with it. In AmigaOS, any directory or file can have such an icon file that stores a unique icon image, unique program settings or specific settings for that file or directory. That information can be adjusted within the Workbench and is automatically stored in a companion file with the same name, but with an added '''.info''' suffix.

While many files & directories and most applications have such ".info files" with them, they are not required and the Workbench can be set to show you "default icons" (based on the file types, etc.) so you can manipulate the corresponding objects. Of course, AmigaOS can also be configured on a directory-by-directory basis to only show files that have associated ".info" files.

In the same picture, the 2 top right directory icons also look slightly different. While the '''Utilities selected''' and the '''Utilities unselected''' are the same icon, their image is a bit different. The drawer of the first one is slightly opened and there is a "glow" effect arround the first icon. These two visual clues show you the first directory icon has been selected by the user whereas the second one is not.

==== App Icons ====

Many applications provide the option to be "iconified" either by clicking on an iconification gadget in their window title bars or by selecting a menu item. In those events, the application's window will disappear and an "app icon" will appear on the background of the Workbench screen. Double-clicking on the app icon will cause the icon to disappear and the application's window to reappear. Even while the application is iconified, it does continue to run and perform whatever the user may have it doing.

Some applications may also place an app icon on the Workbench background even while the application is open to allow the user to be able to drop other file icons on the app icon and have them be used by the application.

=== Graphic gadgets ===
Within AmigaOS and application windows, there can be any number of graphic devices meant to be operated by your mouse with clicks and drags - these are known as "gagdets". In most cases, the gagdets are simple analogs of real world objects - like buttons you press with your finger, forms you fill out with a pencil or tabs on folders.

[[File:LibFig5-1.png]]

==== Buttons ====

[[File:OS4-Buttons.jpg|frame|right]]
Buttons (or "Boolean gadgets") are some of the most common GUI objects. With a simple left-click of your mouse button, they are used to perform actions, set configurations or indicate choices.

In AmigaOS, clicking "down" on a button typically causes the button to be rendered differently, to reflect that it has been "pressed". Engaging the button is not actually recognized until you let go with the mouse button over the graphic gadget. This means that while the gadget has been clicked down, you always have the option of moving the mouse off the button gadget and then letting go and it will be as though the button had never been "pressed" or clicked on.
 
==== Text gadgets ====

[[File:OS4-StringGadgets.jpg|frame|right]]
A text gadget (or "String gadget") works like a space in a paper form to be filled out - left click in the gadget, you will see a cursor appear and you can type your answer.
Once you've finished typing your infrormation, you can either press the enter, carriage-return or tab keys for your entry to be recognized.

Text or string gadgets can also come in a number of variants for specific uses. Some can limit input to be numeric only (and may have adjacent buttons to increment or decrement the value). Some string gadgets may be specifically be meant for file or directory names and they have adjacent gagdets that will bring up a file requester to set the value. Many times a numeric gadget is paired with a slider gadget (as in the example above), where the value can either be set by typing in the gadget or by using the slider.
 
==== Sliders & Scroll Bars ====

[[File:OS4-SliderGadgets.jpg|frame|right]]
Slider gadgets work like controls many of have seen on their stereo systems - left-click and drag on the gadget "knob" to move it back and forth to set a value. A more sophisticated variant of the slider is the "scroll bar" that has a variably sized scroll bar contained in a scroll box that lets you see what proportion of the active range is visible or active.

With all slider and scroller gadgets AmigaOS also lets you click in the area to either side of the knob or slider to adjust the setting. In the case of sliders, the value will typically move by a fixed amount (+/- 1 or some suitable increment). In the case of scroll bars, clicking in the scroll box on either side of the scroll bar will cause the value to move in increments of the scroll bar size. Scroll bars also come with "scroll arrows" at the end of the scroll box that allow for finer movement of the scroll bar.
 
==== Cycle gadgets ====

[[File:OS4-CycleGadgets.jpg|frame|right]]
Cycle gagdets are a variant on buttons that let you select from a number of specific choices. You can either click on the majority of the gadget to pop-up a list of choices to select from or click on the circular arrow to cycle between the list of choices. Cycle gagdets rarely cause actions to occur, they just adjust some setting or configuration.
 
==== Check Box & Radio Button gadgets ====

[[File:OS4-CheckRadioGadgets.jpg|frame|right]]
Another variant of buttons, check boxes can be clicked to set on/off or yes/no conditions with a checkmark, just like a check box in a paper form. Radio buttons are another variant where two or more round buttons are presented in a set and only one of the set can be clicked and activated, like the buttons on a stereo system.
 
==== Tabs ====

[[File:OS4-Tabs.jpg|frame|right]]
Tabs are a graphical gadget that is used in combination with a "pages" or sets of gadgets and/or information, and you can click on the "tabs" to switch between the pages - like you might in a real notebook with tabbed pages. This provides a efficient way to present more information and settings in a compact interface.
 
====Requesters====

[[File:LibFig2-5.png|frame|right]]
As one uses AmigaOS and it's applications, from time to time a "Requester" window may appear to ask the user a question - basically windows with gadgets in them. Such requesters can appear to confirm an action, obtain more information, make a selection or configuration. Typically a series of buttons across the bottom of the window will dispatch the requester, with the bottom-left button gadget indicating some affirmative choice and the bottom-right button gagdet cancelling the requester (performing no action or change).
 

====Keyboard Operation of Gadgets====
As with so many things, AmigaOS and its applications provide a secondary way to operate many of these gadgets - by keyboard. If a window contains text gadgets, pressing your keyboard's TAB key will activate the text gadgets in sequence (a cursor will appear in each so you can type & edit). Each press of the TAB key will cycle to the next gadget and pressing SHIFT + TAB will cycle through the gadgets in reverse order.

You may have noticed in many of the above sample images that many of the gagdets or their adjacent "label" texts contain a single underlined character. This is a sign that pressing that key on your keyboard will activate that gadget. Each gadget can then be operated by your keyboard - just like clicking on a button, clicking on a tab, setting a text or numeric value, etc. Of course, if you are in the midst of typing in a text gadget, then things you type will go into that gadget instead of operating other gagdets.

== Finding Files in AmigaOS ==

[[File:OS4-ASLReq.jpg|frame|right]]
AmigaOS provides a consistent method for navigating your file system and finding your files from within your apps - the "ASL file requester". It is used by everything in AmigaOS and most third party applications. It is the window (or "requester") that appears when you want to open or save files.

As you can see, the ASL file requester presents the files in a given location in your file systems (a directory or "drawer") and shows their size, date of creation or last modification and any comments attached to the file. The above example shows the same directory as appeared above in this page.

At the bottom corners of the window are buttons to accept the selection ("OK") or cancel the requester. Between those are buttons to view all the drives & partitions on your system ("Volumes") or to move to the "Parent" of the current directory.

Also at the bottom of the window you will see three text gadgets. The first of these is optional and allows you to filter what is shown in the file list - it is now shown filtering out any file with a ".info" suffix (those are AmigaOS icon files). The next two lines reflect the current directory path name and the currently selected file name (also selected in the file list above). In the case of saving files, you would type any name you wanted in the bottom text field to create a new file. Clicking on the titles of the file list will let you sort the file list.

Of course this being AmigaOS, the ASL requester has its own "preferences editor" that lets you set how the requester appears, is sorted by default and a number of mouse button short-cuts.
 

== Controlling AmigaOS - Which Way? ==

AmigaOS provides a number of parallel ways that the user can control and put their Amigas to use. The easiest and most common method is to use the AmigaOS graphic icons, windows and mouse interface - the "Workbench" - using all the GUI elements described above. But AmigaOS also provides a more traditional or "old fashioned" method called a command line interface (the "CLI" or "Shell"), where the user can type text commands and interact using a text interface. AmigaOS also provides a unique means of "interprocess communications" where user can have many applications and parts of the OS "talk" to each other.

=== The Workbench & Intuition ===

As we described above, AmigaOS provides the "Workbench", a straightforward, efficient and easy graphical means to start applications, manage your computer and all your files. Files and programs are represented with icons, generally known as "Projects" and "Tools". They can be stored in any arrangement of directories ("Drawers"). You double-click on a program icon and it will open in a Intuition GUI window on your Workbench screen.

Please see the section about the AmigaOS [http://wiki.amigaos.net/index.php/UserDoc:Workbench Workbench] to learn these concepts:

* What is the Workbench
* Workbench menus
* Keyboard control
* Workbench requesters
* Configuration
* Workbench help

=== The Shell & DOS Commands ===

[[File:OS4-Window-Shell.jpg|frame|right]]
The AmigaOS Shell can be opened by double-clicking the "Shell" icon in the AmigaOS "System" drawer. The Shell is a text based interface that allows you to perform most of the same operations as the Workbench - to run and interact with application programs, manage files and control your Amiga computer. AmigaOS also comes with dozens of standard "DOS commands" (programs purely meant for Shell usage). Simply enter the name of a program or command (like "dir") and press Enter, the command or program will run and it will print its results in the Shell window. While considered old fashioned, many users find the Shell to still be the most efficient way to perform many tasks on the Amigas.

Please see the section on the [[UserDoc:Shell|AmigaOS Shell]] to learn more.
 

=== Scripts & Messages ===

Scripts are simple text files that contain a list of commands written in a variety of languages: the AmigaDOS, Arexx and Python languages are provided with AmigaOS - there are many others. Each of these language has its strengths. You'll have to learn the one that suits what you want to do. You can create a script using a text editor. You can run such scripts from the Workbench or from the shell (or from any other script). By using ARexx ports provided by AmigaOS components (the Workbench or Multiview, for example) or third-party applications, scripts can be used to make your computer perform a wide variety of actions.

== AmigaOS System Tools ==
AmigaOS comes with a variety of programs to help in the preparation of your computer. These include tools for:

* Drive preparation (Media Toolbox, Format, Format DCRW & Mounter).
* Font Handling (TypeManager & FixFonts).
* Script Languages (RexxMast and Python).
* The Shell.
* Miscellaneous Utilities (Find, Help, Grim Reaper & Ringhio Server).

== AmigaOS Utilities ==
AmigaOS comes with a selection of utilities to assist the user, including:

* Commodities.
* Editors (Notepad, MEmacs, PrefsObjectEditor & IconEdit).
* Postscript oriented apps (AmiPDF, AmiGS & Ghostscript).
* Disk apps (PartitionWizard & RawDisk).
* Screenblankers.
* AmiDock and Dockies.
* The Unarc dearchiver.
* PlayCD.
* Several "sub-programs" that are used by other system utilities (blankers, dockies)
* Miscellaneous apps (Clock, printing apps, KeyShow, install apps, etc.).

Read [[Utilities|here]] to find all of them explained further.

== AmigaOS Preferences ==
AmigaOS comes with a number of small programs used for modifying the system's settings. These are stored in the [[Prefs]] drawer, and include programs for modifying the following settings:

* General appearance
* Screen resolution
* Desktop and window backgrounds
* Language settings
* Keyboard and mouse settings
* Printer settings
* Audio settings

Read [[Prefs|here]] for details and explanations of all the preference programs.

UserDoc:Introduction to AmigaOS

2014-05-19T14:16:03Z

Rob Cranley: /* Scripts & Messages */ Grammar correction: "such script" -> "such scripts"

Like any modern personal computer system, AmigaOS presents a graphic interface and relies on common peripherals to let the user control their system.
Beyond most systems, AmigaOS provides more flexibility and options in how the user can approach, configure and use their Amiga computer.

In this page we will describe the details of AmigaOS graphic user interface (GUI) - how screens, windows and gadgets are presented and how you can use them.
We will also describe the various means by which the user can control and operate AmigaOS. In additional pages, you can read about [[UserDoc:How AmigaOS Works|how AmigaOS works]] and what its components are.

== AmigaOS Input - Point, Click and Type ==

There are two common ways you can use and control your AmigaOS system - by mouse and keyboard.

But AmigaOS also lets you control your system by other input devices (like touchscreens or voice recognition) depending on drivers and devices connected. Depending on software installed, AmigaOS can also be remotely controlled by networked protocols (like VNC and Synergy). Finally, AmigaOS can be controlled internal scripts set up by the User.

=== Using the mouse ===

[[File:Style2.5.png|frame|right]]

Typically in AmigaOS, you use a mouse to act on graphic elements (like "gadgets", "icons" or webpage "links"). By default, AmigaOS expects and supports mice or trackball pointing devices with at least two buttons. The left mouse button is used to "left-click" on graphic objects, to select them or operate them. The right mouse button is used to "right-click" and display the menus of the current application.

Optionally, one can use a mouse or trackball device with three (a "middle" button) and four buttons. With such devices, the functionality of the additional buttons can vary by application or environment. These functionalities can typically be configured by the user in specific applications or within AmigaOS (globally).

Furthermore, scroll wheels are supported by AmigaOS in a context-based fashion. If the current application's window is scrollable, the scrollwheel will act on that area. If the mouse pointer is positioned over a specifically scrollable gadget, the scrollwheel will affect that gadget.

In some applications and environments, you can also "double-click" (click twice, quickly) with the left button on an object to engage them. In the Workbench file manager, a single mouse click will only "select" an icon, whereas a double-click will open drawer/directory, run an application or open a file in an associated program.

Beside "clicking" - pressing down and releasing a mouse button at a specific location - you can also perform what is known as "dragging", which means clicking down and then moving the mouse around before releasing the mouse button. This is typically always done with the left mouse button and is done to select objects (draw a box around them), to adjust a control slider or to resize a window.

 

=== Using the keyboard ===

Of course the keyboard is used to enter text into text editing areas. But your keyboard can do so much more with its special "qualifier" keys and AmigaOS.

The most common example of a qualifier key is the "Shift" key which causes typed text to be made upper-case or capitalized. There are more qualifier keys on most keyboards, here is a list of all of them:
* '''the Shift keys''' - the common key that causes your text to be capitalized.
* '''The "Alternate" keys''' - the "Alt" keys typically to the bottom right and left of the keyboard.
* '''the "Control" keys''' - the "Ctrl" keys also to the bottom right and left of the keyboard.
* '''the "Amiga" keys''' - special "A" keys on the right and left side of the space bar. Besides being unique to AmigaOS, the right and left Amiga keys always mean different things (unlike the rest of the qualifier keys, most of the time). If you have a non-AmigaOS keyboard, the "Windows" or MacOS "Command" keys function as "Amiga" keys.
** '''the Right Amiga key''' - is used for "short cuts" within your current application.
** '''the Left Amiga key''' - is used for "short cuts" that are globally active anytime and anywhere in your AmigaOS system.
While all of these qualifier keys don't usually do anything on their own, when you press and hold one or more of these keys down while pressing regular keys, they can change what you type (capitalizing or making alternate characters) or become powerful "short-cuts" within your applications or throughout your entire AmigaOS system.

The most famous short-cuts are the '''copy''', '''cut''' and '''paste''' operations that you can perform on selected text:
* the '''Right-Amiga C''' short-cut copies any selected text or content to the Clipboard.
* the '''Right-Amiga X''' short-cut "cuts" any selected text or content to the Clipboard.
* the '''Right-Amiga V''' short-cut "pastes" any text or content from the Clipboard into your application (at the current cursor location).

== The AmigaOS GUI - Intuition ==

When AmigaOS has started, you will typically see the Workbench file manager. This is the start of your experience with the AmigaOS GUI and it's most basic elements: a screen with menus and windows containing icons and "gagdets". These components are the basic building blocks of virtually all AmigaOS & application interfaces.

As with most things in AmigaOS, almost all of the following components can also be almost infinitely reconfigured, adjusted and graphically varied by the user. In the AmigaOS "Preferences" drawer, the "GUI", "ASL", "Locale", "Font", "Palette", "Poiner", "PopUpMenu", "Screens", "Workbench" and "WBPattern" preferences editors easily allow a user to reconfigure the GUI of their Amiga in drammatic ways.

AmigaOS also supports the use of alternate GUI systems in parallel with the default "Intuition" (aka "Reaction") GUI system. By default AmigaOS also comes with the "Magic User Interface system ("MUI", a variant of the basic AmigaOS GUI system. More than Intuition, MUI can be reconfigured even more widely using its own MUI configuration app.

Additionally, AmigaOS can use a number of third-party "cross-platform" GUI systems: "AmiCygnix" GUI system - a native X11 GUI implementation for AmigaOS - and a native port of the "Qt" GUI system. With either of these systems, it is possible to run ported applications compiled for AmigaOS, but running with these cross-platform GUI systems.

To start with, we will explore the elements that make up the AmigaOS GUI system.

=== Screens ===

As start-up, the Workbench will be running on its "Workbench Screen". This will be the default location where most other application windows will also appear when started.

Typically an AmigaOS screen will have a "title bar" across the top with a graphical "depth gadget" at the right end. In the case of the Workbench screen,
there will be an AmigaOS "boing ball" at the left end and the title bar will display certain system information (OS version, memory availability, etc.). Within the screen, the Workbench and any other applications can open windows, display icons and other GUI devices. If you right-click over the title bar, it becomes a "Menu Bar", showing you the control menus that are available for that application.

In many cases, other applications may open screens in addition to the Workbench screen. The "depth gadget" at the right end of each screen's title bar allows you to click from screen from screen. Besides clicking on the screen's depth gadet, AmigaOS also lets the user see other screens behind the front screen by "dragging' down on the screen title bar.

The characteristics of the Workbench screen such as resolution and color depth can be configured in the "Screenmode" preferences editor. Other screens can be either be configured in the "Screens" preferences editor or from within individual applications. Typically, AmigaOS applications also give the user the choice of whether application runs on their own screens or the "public" Workbench screen.

=== Windows ===
Windows are graphic containers that appear within AmigaOS screens. Windows can be created by any number of different applications - the Workbench, Shell sessions or applications. Outside of the Workbench file manager, each window usually reflects each individual running application. In some cases, one application may open multiple documents in separate windows or additional "requester" windows might appear for an application.

[[File:LibFig4-1.png]]

Almost all windows of AmigaOS will have these common elements:
* '''Borders''' - A border around the window's contents. Holding the Shift+Left-Amiga keys down while dragging any border will drag the window around.
* '''Title bar''' - A thicker top border that typically contains a name of the application or it's contents. The area of the title bar acts as a "drag bar" which you can use to drag the window around the screen.
* '''Depth gadget''' - The right-most gadget in the top title bar that either pulls the window to front (if it isn't frontmost) or pushes it to the back (if it's in front). Holding down the Shift key while clicking this gagdet pushes the window to the back.

In AmigaOS, windows may also optionally have these additional features and elements:
* '''Close gadget''' - The left-most gadget in the title bar that closes the window.
* '''Scroll bar(s) and arrows''' - If the contents of the window can be scrolled in vertically and/or horizontally, there will be a scroll bar with arrow scroll buttons. These scroll bars can also be used if the mouse pointer is over a scroll bar and the mouse scroll wheel is used.
* '''Zoom gadget''' - the second gadget from the right-most of the title bar which switches the window between two sizes. Holding down the Shift key while clicking this gadget will make it fill the screen.
* '''Iconification gadget''' - left-most of the right-hand gadgets in the title bar which causes the window to disappear into an icon on the Workbench background - thus "Iconifying" the window or application.
* '''Sizing gadget''' - In the case of windows that can be resized, this is the gadget in the bottom right corner of the window that you can drag to resize the window.

Each AmigaOS application can use almost infinite combinations of these features in the make up of their windows.

=== Menus ===

[[File:LibFig2-4.png|frame|right]]
Menus are lists of items that will allow you to see and use what commands are available in an application. The Workbench uses menus you can use to perform actions on the Workbench and its contents. Menus typically provide many more functions and commands than can be presented to the user than just graphic buttons, etc. within an application's window, as a result they are a primary way most applications are used.

In AmigaOS menus can always be found for the current application by moving the mouse to the top of the screen and right-clicking. The screen title bar will become a menu bar and will show the names of all the current application's menus.

By dragging with the right mouse button, each menu will display its "menu items". Each of those menu items corresponds to a command or setting. In some cases you will find a "check box" on a menu item which you can click on to toggle a setting. In other cases, you will find that menu items have a little arrow head that indicates that item actually has a "sub-menu" - a menu within a menu. Menus ending with ellipses ("...") indicate that menu item will open a window that can be cancelled without commiting any command. For those menu items that might be deactivated (they may not apply at the moment), they will be "greyed-out".

The labels of many menu items will also include a letter or two with an "A" at the right edge. This indicates what the keyboard Right-Amiga "short cut" is the equivalent of using that menu item within that application. In the above screen shot, you can see that pressing the two keys - "Right-Amiga" and "N" - would do the same as that menu item - to create a new drawer.
 

====Consistent Organization====
For the sake of consistency (when applicable), the first two AmigaOS menus of any application are typically organized with the following hierarchy and use these keyboard equivalents:

{| border="0"
|'''First Menu:'''
----
|| || Keyboard equivalent: || '''Second Menu:'''
----
|| || Keyboard equivalent:
|-
|'''PROJECT'''
----
|| || ||'''EDIT'''
----
||
|-
|'''New'''|| = Create new project in application.||Right-Amiga N||'''Cut'''|| = Cut the selected content into the Clipboard.||Right-Amiga X
|-
|'''Open...'''|| = Open the file containing a project.||Right-Amiga O||'''Copy'''|| = Copy the selected content into the Clipboard.||Right-Amiga C
|-
|'''Save'''|| = Save the project to it's current file name.||Right-Amiga S||'''Paste'''|| = Paste the Clipboard contents into the project (at the current location).||Right-Amiga V
|-
|'''Save As...'''|| = Save the project to a file of a new name.|| ||'''Undo'''|| = Undo the last change to current project.||Right-Amiga Z
|-
|'''Print'''|| = Print the current project.||Right-Amiga P||'''Redo'''|| = Restore the last change "undone" in the current project.||
|-
|'''Close'''|| = Close the project.|| || || ||
|-
|'''Quit'''|| = Quit the application.||Right-Amiga Q||
|}

====Menu Variations====
AmigaOS also includes a couple additional ways menus can be can serve the user:

=====Pop-Up Menus=====

[[File:OS4-WBPopUpMenu.jpg|frame|right]]
In the GUI preferences editor you can configure menus to "pop-up" under the mouse pointer whenever you right-click the mouse. This means you do not need to move the mouse to the top of the screen to use the menus. There are also options for making menus "sticky", meaning that you don't need to drag the mouse to navigate the menus, but rather just right click and the menus stay open till you make a selection or click away.
 

=====Context Menus=====

[[File:OS4-WBContextMenu.jpg|frame|right]]
The Workbench (with a utility added by default) and many applications provide "contextural menus". This means that you can put your mouse pointer over elements and right-click to pop-up a menu of things that are specific to the item you clicked over. In the case of the Workbench (with the Context Menus utility), right clicking on a file will pop-up a menu of things that could be done with that file, like deleting it.

All of these features provide both a simple means of using many functions within an application and at the same time allowing the user to configure a very efficient user interface that responds to nearly every whim.
 

=== Icons ===

==== Description ====
Icons are small images which can represent a disk, a directory, an application file or data file. Icons are primarilly used within the AmigaOS Workbench environment to represent all the file system objects the user can manipulate. With these icons it is possible to select files, open them, delete them or move them around within the Workbench. Applications may also make more limited use of icons to represent file system objects or may be used as imagery in an "icon bar" of buttons that can be clicked to perform various actions represented by icon imagery, like the Clock above.

{|style="text-align: center;"
|[[File:LibDiskIcon.png|frame|left|100px|Drive icon]] [[File:Icons.png|frame|right|Directory with sub-directory, data and application file icons]]
|}

AmigaOS also uses different icon imagery to indicate various types of icons - drives, directories, files and applications. Drive or partition icons look like little hard drives.
A directory icon will look like a cabinet & drawer whereas a file icon will be designed to give a clue about the file content.
Data files are normally shown with a "page" motif and some graphics or text to reflect the file type.
Application files typically have the most free-form graphics that reflect their purpose, name or developer.

The user can also edit the icon imagery using the icon editor, change how icons react to being double-clicked and adjust parameters stored within the icon file that affect how the represented file will be used.

Many applications and all AmigaOS file requesters allow Workbench icons to be "dragged and dropped" into the application or requester windows and the associated file will be recognized by the application, if possible.

==== Icon states ====

Icons can look different not only because of their image but also depending on their state.

As you can see in the directory example, the 2 top left icons appear semi-transparent. This subtle difference reflects whether the file or directory has an associated icon file with it. In AmigaOS, any directory or file can have such an icon file that stores a unique icon image, unique program settings or specific settings for that file or directory. That information can be adjusted within the Workbench and is automatically stored in a companion file with the same name, but with an added '''.info''' suffix.

While many files & directories and most applications have such ".info files" with them, they are not required and the Workbench can be set to show you "default icons" (based on the file types, etc.) so you can manipulate the corresponding objects. Of course, AmigaOS can also be configured on a directory-by-directory basis to only show files that have associated ".info" files.

In the same picture, the 2 top right directory icons also look slightly different. While the '''Utilities selected''' and the '''Utilities unselected''' are the same icon, their image is a bit different. The drawer of the first one is slightly opened and there is a "glow" effect arround the first icon. These two visual clues show you the first directory icon has been selected by the user whereas the second one is not.

==== App Icons ====

Many applications provide the option to be "iconified" either by clicking on an iconification gadget in their window title bars or by menu item. In those events, the application's window will disappear and an "app icon" will appear on the background of the Workbench screen. Double-clicking on the app icon will cause the icon to disappear and the application's window to reappear. Even while the application is iconified, it does continue to run and perform whatever the user may have it doing.

Some applications may also place an app icon on the Workbench background even while the application is open to allow the user to be able to drop other file icons on the app icon and have them be used by the application.

=== Graphic gadgets ===
Within AmigaOS and application windows, there can be any number of graphic devices meant to be operated by your mouse with clicks and drags - these are known as "gagdets". In most cases, the gagdets are simple analogs of real world objects - like buttons you press with your finger, forms you fill out with a pencil or tabs on folders.

[[File:LibFig5-1.png]]

==== Buttons ====

[[File:OS4-Buttons.jpg|frame|right]]
Buttons (or "Boolean gadgets") are some of the most common GUI objects. With a simple left-click of your mouse button, they are used to perform actions, set configurations or indicate choices.

In AmigaOS, clicking "down" on a button typically causes the button to be rendered differently, to reflect that it has been "pressed". Engaging the button is not actually recognized until you let go with the mouse button over the graphic gadget. This means that while the gadget has been clicked down, you always have the option of moving the mouse off the button gadget and then letting go and it will be as though the button had never been "pressed" or clicked on.
 
==== Text gadgets ====

[[File:OS4-StringGadgets.jpg|frame|right]]
A text gadget (or "String gadget") works like a space in a paper form to be filled out - left click in the gadget, you will see a cursor appear and you can type your answer.
Once you've finished typing your infrormation, you can either press the enter, carriage-return or tab keys for your entry to be recognized.

Text or string gadgets can also come in a number of variants for specific uses. Some can limit input to be numeric only (and may have adjacent buttons to increment or decrement the value). Some string gadgets may be specifically be meant for file or directory names and they have adjacent gagdets that will bring up a file requester to set the value. Many times a numeric gadget is paired with a slider gadget (as in the example above), where the value can either be set by typing in the gadget or by using the slider.
 
==== Sliders & Scroll Bars ====

[[File:OS4-SliderGadgets.jpg|frame|right]]
Slider gadgets work like controls many of have seen on their stereo systems - left-click and drag on the gadget "knob" to move it back and forth to set a value. A more sophisticated variant of the slider is the "scroll bar" that has a variably sized scroll bar contained in a scroll box that lets you see what proportion of the active range is visible or active.

With all slider and scroller gadgets AmigaOS also lets you click in the area to either side of the knob or slider to adjust the setting. In the case of sliders, the value will typically move by a fixed amount (+/- 1 or some suitable increment). In the case of scroll bars, clicking in the scroll box on either side of the scroll bar will cause the value to move in increments of the scroll bar size. Scroll bars also come with "scroll arrows" at the end of the scroll box that allow for finer movement of the scroll bar.
 
==== Cycle gadgets ====

[[File:OS4-CycleGadgets.jpg|frame|right]]
Cycle gagdets are a variant on buttons that let you select from a number of specific choices. You can either click on the majority of the gadget to pop-up a list of choices to select from or click on the circular arrow to cycle between the list of choices. Cycle gagdets rarely cause actions to occur, they just adjust some setting or configuration.
 
==== Check Box & Radio Button gadgets ====

[[File:OS4-CheckRadioGadgets.jpg|frame|right]]
Another variant of buttons, check boxes can be clicked to set on/off or yes/no conditions with a checkmark, just like a check box in a paper form. Radio buttons are another variant where two or more round buttons are presented in a set and only one of the set can be clicked and activated, like the buttons on a stereo system.
 
==== Tabs ====

[[File:OS4-Tabs.jpg|frame|right]]
Tabs are a graphical gadget that is used in combination with a "pages" or sets of gadgets and/or information, and you can click on the "tabs" to switch between the pages - like you might in a real notebook with tabbed pages. This provides a efficient way to present more information and settings in a compact interface.
 
====Requesters====

[[File:LibFig2-5.png|frame|right]]
As one uses AmigaOS and it's applications, from time to time a "Requester" window may appear to ask the user a question - basically windows with gadgets in them. Such requesters can appear to confirm an action, obtain more information, make a selection or configuration. Typically a series of buttons across the bottom of the window will dispatch the requester, with the bottom-left button gadget indicating some affirmative choice and the bottom-right button gagdet cancelling the requester (performing no action or change).
 

====Keyboard Operation of Gadgets====
As with so many things, AmigaOS and its applications provide a secondary way to operate many of these gadgets - by keyboard. If a window contains text gadgets, pressing your keyboard's TAB key will activate the text gadgets in sequence (a cursor will appear in each so you can type & edit). Each press of the TAB key will cycle to the next gadget and pressing SHIFT + TAB will cycle through the gadgets in reverse order.

You may have noticed in many of the above sample images that many of the gagdets or their adjacent "label" texts contain a single underlined character. This is a sign that pressing that key on your keyboard will activate that gadget. Each gadget can then be operated by your keyboard - just like clicking on a button, clicking on a tab, setting a text or numeric value, etc. Of course, if you are in the midst of typing in a text gadget, then things you type will go into that gadget instead of operating other gagdets.

== Finding Files in AmigaOS ==

[[File:OS4-ASLReq.jpg|frame|right]]
AmigaOS provides a consistent method for navigating your file system and finding your files from within your apps - the "ASL file requester". It is used by everything in AmigaOS and most third party applications. It is the window (or "requester") that appears when you want to open or save files.

As you can see, the ASL file requester presents the files in a given location in your file systems (a directory or "drawer") and shows their size, date of creation or last modification and any comments attached to the file. The above example shows the same directory as appeared above in this page.

At the bottom corners of the window are buttons to accept the selection ("OK") or cancel the requester. Between those are buttons to view all the drives & partitions on your system ("Volumes") or to move to the "Parent" of the current directory.

Also at the bottom of the window you will see three text gadgets. The first of these is optional and allows you to filter what is shown in the file list - it is now shown filtering out any file with a ".info" suffix (those are AmigaOS icon files). The next two lines reflect the current directory path name and the currently selected file name (also selected in the file list above). In the case of saving files, you would type any name you wanted in the bottom text field to create a new file. Clicking on the titles of the file list will let you sort the file list.

Of course this being AmigaOS, the ASL requester has its own "preferences editor" that lets you set how the requester appears, is sorted by default and a number of mouse button short-cuts.
 

== Controlling AmigaOS - Which Way? ==

AmigaOS provides a number of parallel ways that the user can control and put their Amigas to use. The easiest and most common method is to use the AmigaOS graphic icons, windows and mouse interface - the "Workbench" - using all the GUI elements described above. But AmigaOS also provides a more traditional or "old fashioned" method called a command line interface (the "CLI" or "Shell"), where the user can type text commands and interact using a text interface. AmigaOS also provides a unique means of "interprocess communications" where user can have many applications and parts of the OS "talk" to each other.

=== The Workbench & Intuition ===

As we described above, AmigaOS provides the "Workbench", a straightforward, efficient and easy graphical means to start applications, manage your computer and all your files. Files and programs are represented with icons, generally known as "Projects" and "Tools". They can be stored in any arrangement of directories ("Drawers"). You double-click on a program icon and it will open in a Intuition GUI window on your Workbench screen.

Please see the section about the AmigaOS [http://wiki.amigaos.net/index.php/UserDoc:Workbench Workbench] to learn these concepts:

* What is the Workbench
* Workbench menus
* Keyboard control
* Workbench requesters
* Configuration
* Workbench help

=== The Shell & DOS Commands ===

[[File:OS4-Window-Shell.jpg|frame|right]]
The AmigaOS Shell can be opened by double-clicking the "Shell" icon in the AmigaOS "System" drawer. The Shell is a text based interface that allows you to perform most of the same operations as the Workbench - to run and interact with application programs, manage files and control your Amiga computer. AmigaOS also comes with dozens of standard "DOS commands" (programs purely meant for Shell usage). Simply enter the name of a program or command (like "dir") and press Enter, the command or program will run and it will print its results in the Shell window. While considered old fashioned, many users find the Shell to still be the most efficient way to perform many tasks on the Amigas.

Please see the section on the [[UserDoc:Shell|AmigaOS Shell]] to learn more.
 

=== Scripts & Messages ===

Scripts are simple text files that contain a list of commands written in a variety of languages: the AmigaDOS, Arexx and Python languages are provided with AmigaOS - there are many others. Each of these language has its strengths. You'll have to learn the one that suits what you want to do. You can create a script using a text editor. You can run such scripts from the Workbench or from the shell (or from any other script). By using ARexx ports provided by AmigaOS components (the Workbench or Multiview, for example) or third-party applications, scripts can be used to make your computer perform a wide variety of actions.

== AmigaOS System Tools ==
AmigaOS comes with a variety of programs to help in the preparation of your computer. These include tools for:

* Drive preparation (Media Toolbox, Format, Format DCRW & Mounter).
* Font Handling (TypeManager & FixFonts).
* Script Languages (RexxMast and Python).
* The Shell.
* Miscellaneous Utilities (Find, Help, Grim Reaper & Ringhio Server).

== AmigaOS Utilities ==
AmigaOS comes with a selection of utilities to assist the user, including:

* Commodities.
* Editors (Notepad, MEmacs, PrefsObjectEditor & IconEdit).
* Postscript oriented apps (AmiPDF, AmiGS & Ghostscript).
* Disk apps (PartitionWizard & RawDisk).
* Screenblankers.
* AmiDock and Dockies.
* The Unarc dearchiver.
* PlayCD.
* Several "sub-programs" that are used by other system utilities (blankers, dockies)
* Miscellaneous apps (Clock, printing apps, KeyShow, install apps, etc.).

Read [[Utilities|here]] to find all of them explained further.

== AmigaOS Preferences ==
AmigaOS comes with a number of small programs used for modifying the system's settings. These are stored in the [[Prefs]] drawer, and include programs for modifying the following settings:

* General appearance
* Screen resolution
* Desktop and window backgrounds
* Language settings
* Keyboard and mouse settings
* Printer settings
* Audio settings

Read [[Prefs|here]] for details and explanations of all the preference programs.

UserDoc:Introduction to AmigaOS

2014-05-19T14:14:08Z

Rob Cranley: Added brief overview of Prefs

Like any modern personal computer system, AmigaOS presents a graphic interface and relies on common peripherals to let the user control their system.
Beyond most systems, AmigaOS provides more flexibility and options in how the user can approach, configure and use their Amiga computer.

In this page we will describe the details of AmigaOS graphic user interface (GUI) - how screens, windows and gadgets are presented and how you can use them.
We will also describe the various means by which the user can control and operate AmigaOS. In additional pages, you can read about [[UserDoc:How AmigaOS Works|how AmigaOS works]] and what its components are.

== AmigaOS Input - Point, Click and Type ==

There are two common ways you can use and control your AmigaOS system - by mouse and keyboard.

But AmigaOS also lets you control your system by other input devices (like touchscreens or voice recognition) depending on drivers and devices connected. Depending on software installed, AmigaOS can also be remotely controlled by networked protocols (like VNC and Synergy). Finally, AmigaOS can be controlled internal scripts set up by the User.

=== Using the mouse ===

[[File:Style2.5.png|frame|right]]

Typically in AmigaOS, you use a mouse to act on graphic elements (like "gadgets", "icons" or webpage "links"). By default, AmigaOS expects and supports mice or trackball pointing devices with at least two buttons. The left mouse button is used to "left-click" on graphic objects, to select them or operate them. The right mouse button is used to "right-click" and display the menus of the current application.

Optionally, one can use a mouse or trackball device with three (a "middle" button) and four buttons. With such devices, the functionality of the additional buttons can vary by application or environment. These functionalities can typically be configured by the user in specific applications or within AmigaOS (globally).

Furthermore, scroll wheels are supported by AmigaOS in a context-based fashion. If the current application's window is scrollable, the scrollwheel will act on that area. If the mouse pointer is positioned over a specifically scrollable gadget, the scrollwheel will affect that gadget.

In some applications and environments, you can also "double-click" (click twice, quickly) with the left button on an object to engage them. In the Workbench file manager, a single mouse click will only "select" an icon, whereas a double-click will open drawer/directory, run an application or open a file in an associated program.

Beside "clicking" - pressing down and releasing a mouse button at a specific location - you can also perform what is known as "dragging", which means clicking down and then moving the mouse around before releasing the mouse button. This is typically always done with the left mouse button and is done to select objects (draw a box around them), to adjust a control slider or to resize a window.

 

=== Using the keyboard ===

Of course the keyboard is used to enter text into text editing areas. But your keyboard can do so much more with its special "qualifier" keys and AmigaOS.

The most common example of a qualifier key is the "Shift" key which causes typed text to be made upper-case or capitalized. There are more qualifier keys on most keyboards, here is a list of all of them:
* '''the Shift keys''' - the common key that causes your text to be capitalized.
* '''The "Alternate" keys''' - the "Alt" keys typically to the bottom right and left of the keyboard.
* '''the "Control" keys''' - the "Ctrl" keys also to the bottom right and left of the keyboard.
* '''the "Amiga" keys''' - special "A" keys on the right and left side of the space bar. Besides being unique to AmigaOS, the right and left Amiga keys always mean different things (unlike the rest of the qualifier keys, most of the time). If you have a non-AmigaOS keyboard, the "Windows" or MacOS "Command" keys function as "Amiga" keys.
** '''the Right Amiga key''' - is used for "short cuts" within your current application.
** '''the Left Amiga key''' - is used for "short cuts" that are globally active anytime and anywhere in your AmigaOS system.
While all of these qualifier keys don't usually do anything on their own, when you press and hold one or more of these keys down while pressing regular keys, they can change what you type (capitalizing or making alternate characters) or become powerful "short-cuts" within your applications or throughout your entire AmigaOS system.

The most famous short-cuts are the '''copy''', '''cut''' and '''paste''' operations that you can perform on selected text:
* the '''Right-Amiga C''' short-cut copies any selected text or content to the Clipboard.
* the '''Right-Amiga X''' short-cut "cuts" any selected text or content to the Clipboard.
* the '''Right-Amiga V''' short-cut "pastes" any text or content from the Clipboard into your application (at the current cursor location).

== The AmigaOS GUI - Intuition ==

When AmigaOS has started, you will typically see the Workbench file manager. This is the start of your experience with the AmigaOS GUI and it's most basic elements: a screen with menus and windows containing icons and "gagdets". These components are the basic building blocks of virtually all AmigaOS & application interfaces.

As with most things in AmigaOS, almost all of the following components can also be almost infinitely reconfigured, adjusted and graphically varied by the user. In the AmigaOS "Preferences" drawer, the "GUI", "ASL", "Locale", "Font", "Palette", "Poiner", "PopUpMenu", "Screens", "Workbench" and "WBPattern" preferences editors easily allow a user to reconfigure the GUI of their Amiga in drammatic ways.

AmigaOS also supports the use of alternate GUI systems in parallel with the default "Intuition" (aka "Reaction") GUI system. By default AmigaOS also comes with the "Magic User Interface system ("MUI", a variant of the basic AmigaOS GUI system. More than Intuition, MUI can be reconfigured even more widely using its own MUI configuration app.

Additionally, AmigaOS can use a number of third-party "cross-platform" GUI systems: "AmiCygnix" GUI system - a native X11 GUI implementation for AmigaOS - and a native port of the "Qt" GUI system. With either of these systems, it is possible to run ported applications compiled for AmigaOS, but running with these cross-platform GUI systems.

To start with, we will explore the elements that make up the AmigaOS GUI system.

=== Screens ===

As start-up, the Workbench will be running on its "Workbench Screen". This will be the default location where most other application windows will also appear when started.

Typically an AmigaOS screen will have a "title bar" across the top with a graphical "depth gadget" at the right end. In the case of the Workbench screen,
there will be an AmigaOS "boing ball" at the left end and the title bar will display certain system information (OS version, memory availability, etc.). Within the screen, the Workbench and any other applications can open windows, display icons and other GUI devices. If you right-click over the title bar, it becomes a "Menu Bar", showing you the control menus that are available for that application.

In many cases, other applications may open screens in addition to the Workbench screen. The "depth gadget" at the right end of each screen's title bar allows you to click from screen from screen. Besides clicking on the screen's depth gadet, AmigaOS also lets the user see other screens behind the front screen by "dragging' down on the screen title bar.

The characteristics of the Workbench screen such as resolution and color depth can be configured in the "Screenmode" preferences editor. Other screens can be either be configured in the "Screens" preferences editor or from within individual applications. Typically, AmigaOS applications also give the user the choice of whether application runs on their own screens or the "public" Workbench screen.

=== Windows ===
Windows are graphic containers that appear within AmigaOS screens. Windows can be created by any number of different applications - the Workbench, Shell sessions or applications. Outside of the Workbench file manager, each window usually reflects each individual running application. In some cases, one application may open multiple documents in separate windows or additional "requester" windows might appear for an application.

[[File:LibFig4-1.png]]

Almost all windows of AmigaOS will have these common elements:
* '''Borders''' - A border around the window's contents. Holding the Shift+Left-Amiga keys down while dragging any border will drag the window around.
* '''Title bar''' - A thicker top border that typically contains a name of the application or it's contents. The area of the title bar acts as a "drag bar" which you can use to drag the window around the screen.
* '''Depth gadget''' - The right-most gadget in the top title bar that either pulls the window to front (if it isn't frontmost) or pushes it to the back (if it's in front). Holding down the Shift key while clicking this gagdet pushes the window to the back.

In AmigaOS, windows may also optionally have these additional features and elements:
* '''Close gadget''' - The left-most gadget in the title bar that closes the window.
* '''Scroll bar(s) and arrows''' - If the contents of the window can be scrolled in vertically and/or horizontally, there will be a scroll bar with arrow scroll buttons. These scroll bars can also be used if the mouse pointer is over a scroll bar and the mouse scroll wheel is used.
* '''Zoom gadget''' - the second gadget from the right-most of the title bar which switches the window between two sizes. Holding down the Shift key while clicking this gadget will make it fill the screen.
* '''Iconification gadget''' - left-most of the right-hand gadgets in the title bar which causes the window to disappear into an icon on the Workbench background - thus "Iconifying" the window or application.
* '''Sizing gadget''' - In the case of windows that can be resized, this is the gadget in the bottom right corner of the window that you can drag to resize the window.

Each AmigaOS application can use almost infinite combinations of these features in the make up of their windows.

=== Menus ===

[[File:LibFig2-4.png|frame|right]]
Menus are lists of items that will allow you to see and use what commands are available in an application. The Workbench uses menus you can use to perform actions on the Workbench and its contents. Menus typically provide many more functions and commands than can be presented to the user than just graphic buttons, etc. within an application's window, as a result they are a primary way most applications are used.

In AmigaOS menus can always be found for the current application by moving the mouse to the top of the screen and right-clicking. The screen title bar will become a menu bar and will show the names of all the current application's menus.

By dragging with the right mouse button, each menu will display its "menu items". Each of those menu items corresponds to a command or setting. In some cases you will find a "check box" on a menu item which you can click on to toggle a setting. In other cases, you will find that menu items have a little arrow head that indicates that item actually has a "sub-menu" - a menu within a menu. Menus ending with ellipses ("...") indicate that menu item will open a window that can be cancelled without commiting any command. For those menu items that might be deactivated (they may not apply at the moment), they will be "greyed-out".

The labels of many menu items will also include a letter or two with an "A" at the right edge. This indicates what the keyboard Right-Amiga "short cut" is the equivalent of using that menu item within that application. In the above screen shot, you can see that pressing the two keys - "Right-Amiga" and "N" - would do the same as that menu item - to create a new drawer.
 

====Consistent Organization====
For the sake of consistency (when applicable), the first two AmigaOS menus of any application are typically organized with the following hierarchy and use these keyboard equivalents:

{| border="0"
|'''First Menu:'''
----
|| || Keyboard equivalent: || '''Second Menu:'''
----
|| || Keyboard equivalent:
|-
|'''PROJECT'''
----
|| || ||'''EDIT'''
----
||
|-
|'''New'''|| = Create new project in application.||Right-Amiga N||'''Cut'''|| = Cut the selected content into the Clipboard.||Right-Amiga X
|-
|'''Open...'''|| = Open the file containing a project.||Right-Amiga O||'''Copy'''|| = Copy the selected content into the Clipboard.||Right-Amiga C
|-
|'''Save'''|| = Save the project to it's current file name.||Right-Amiga S||'''Paste'''|| = Paste the Clipboard contents into the project (at the current location).||Right-Amiga V
|-
|'''Save As...'''|| = Save the project to a file of a new name.|| ||'''Undo'''|| = Undo the last change to current project.||Right-Amiga Z
|-
|'''Print'''|| = Print the current project.||Right-Amiga P||'''Redo'''|| = Restore the last change "undone" in the current project.||
|-
|'''Close'''|| = Close the project.|| || || ||
|-
|'''Quit'''|| = Quit the application.||Right-Amiga Q||
|}

====Menu Variations====
AmigaOS also includes a couple additional ways menus can be can serve the user:

=====Pop-Up Menus=====

[[File:OS4-WBPopUpMenu.jpg|frame|right]]
In the GUI preferences editor you can configure menus to "pop-up" under the mouse pointer whenever you right-click the mouse. This means you do not need to move the mouse to the top of the screen to use the menus. There are also options for making menus "sticky", meaning that you don't need to drag the mouse to navigate the menus, but rather just right click and the menus stay open till you make a selection or click away.
 

=====Context Menus=====

[[File:OS4-WBContextMenu.jpg|frame|right]]
The Workbench (with a utility added by default) and many applications provide "contextural menus". This means that you can put your mouse pointer over elements and right-click to pop-up a menu of things that are specific to the item you clicked over. In the case of the Workbench (with the Context Menus utility), right clicking on a file will pop-up a menu of things that could be done with that file, like deleting it.

All of these features provide both a simple means of using many functions within an application and at the same time allowing the user to configure a very efficient user interface that responds to nearly every whim.
 

=== Icons ===

==== Description ====
Icons are small images which can represent a disk, a directory, an application file or data file. Icons are primarilly used within the AmigaOS Workbench environment to represent all the file system objects the user can manipulate. With these icons it is possible to select files, open them, delete them or move them around within the Workbench. Applications may also make more limited use of icons to represent file system objects or may be used as imagery in an "icon bar" of buttons that can be clicked to perform various actions represented by icon imagery, like the Clock above.

{|style="text-align: center;"
|[[File:LibDiskIcon.png|frame|left|100px|Drive icon]] [[File:Icons.png|frame|right|Directory with sub-directory, data and application file icons]]
|}

AmigaOS also uses different icon imagery to indicate various types of icons - drives, directories, files and applications. Drive or partition icons look like little hard drives.
A directory icon will look like a cabinet & drawer whereas a file icon will be designed to give a clue about the file content.
Data files are normally shown with a "page" motif and some graphics or text to reflect the file type.
Application files typically have the most free-form graphics that reflect their purpose, name or developer.

The user can also edit the icon imagery using the icon editor, change how icons react to being double-clicked and adjust parameters stored within the icon file that affect how the represented file will be used.

Many applications and all AmigaOS file requesters allow Workbench icons to be "dragged and dropped" into the application or requester windows and the associated file will be recognized by the application, if possible.

==== Icon states ====

Icons can look different not only because of their image but also depending on their state.

As you can see in the directory example, the 2 top left icons appear semi-transparent. This subtle difference reflects whether the file or directory has an associated icon file with it. In AmigaOS, any directory or file can have such an icon file that stores a unique icon image, unique program settings or specific settings for that file or directory. That information can be adjusted within the Workbench and is automatically stored in a companion file with the same name, but with an added '''.info''' suffix.

While many files & directories and most applications have such ".info files" with them, they are not required and the Workbench can be set to show you "default icons" (based on the file types, etc.) so you can manipulate the corresponding objects. Of course, AmigaOS can also be configured on a directory-by-directory basis to only show files that have associated ".info" files.

In the same picture, the 2 top right directory icons also look slightly different. While the '''Utilities selected''' and the '''Utilities unselected''' are the same icon, their image is a bit different. The drawer of the first one is slightly opened and there is a "glow" effect arround the first icon. These two visual clues show you the first directory icon has been selected by the user whereas the second one is not.

==== App Icons ====

Many applications provide the option to be "iconified" either by clicking on an iconification gadget in their window title bars or by menu item. In those events, the application's window will disappear and an "app icon" will appear on the background of the Workbench screen. Double-clicking on the app icon will cause the icon to disappear and the application's window to reappear. Even while the application is iconified, it does continue to run and perform whatever the user may have it doing.

Some applications may also place an app icon on the Workbench background even while the application is open to allow the user to be able to drop other file icons on the app icon and have them be used by the application.

=== Graphic gadgets ===
Within AmigaOS and application windows, there can be any number of graphic devices meant to be operated by your mouse with clicks and drags - these are known as "gagdets". In most cases, the gagdets are simple analogs of real world objects - like buttons you press with your finger, forms you fill out with a pencil or tabs on folders.

[[File:LibFig5-1.png]]

==== Buttons ====

[[File:OS4-Buttons.jpg|frame|right]]
Buttons (or "Boolean gadgets") are some of the most common GUI objects. With a simple left-click of your mouse button, they are used to perform actions, set configurations or indicate choices.

In AmigaOS, clicking "down" on a button typically causes the button to be rendered differently, to reflect that it has been "pressed". Engaging the button is not actually recognized until you let go with the mouse button over the graphic gadget. This means that while the gadget has been clicked down, you always have the option of moving the mouse off the button gadget and then letting go and it will be as though the button had never been "pressed" or clicked on.
 
==== Text gadgets ====

[[File:OS4-StringGadgets.jpg|frame|right]]
A text gadget (or "String gadget") works like a space in a paper form to be filled out - left click in the gadget, you will see a cursor appear and you can type your answer.
Once you've finished typing your infrormation, you can either press the enter, carriage-return or tab keys for your entry to be recognized.

Text or string gadgets can also come in a number of variants for specific uses. Some can limit input to be numeric only (and may have adjacent buttons to increment or decrement the value). Some string gadgets may be specifically be meant for file or directory names and they have adjacent gagdets that will bring up a file requester to set the value. Many times a numeric gadget is paired with a slider gadget (as in the example above), where the value can either be set by typing in the gadget or by using the slider.
 
==== Sliders & Scroll Bars ====

[[File:OS4-SliderGadgets.jpg|frame|right]]
Slider gadgets work like controls many of have seen on their stereo systems - left-click and drag on the gadget "knob" to move it back and forth to set a value. A more sophisticated variant of the slider is the "scroll bar" that has a variably sized scroll bar contained in a scroll box that lets you see what proportion of the active range is visible or active.

With all slider and scroller gadgets AmigaOS also lets you click in the area to either side of the knob or slider to adjust the setting. In the case of sliders, the value will typically move by a fixed amount (+/- 1 or some suitable increment). In the case of scroll bars, clicking in the scroll box on either side of the scroll bar will cause the value to move in increments of the scroll bar size. Scroll bars also come with "scroll arrows" at the end of the scroll box that allow for finer movement of the scroll bar.
 
==== Cycle gadgets ====

[[File:OS4-CycleGadgets.jpg|frame|right]]
Cycle gagdets are a variant on buttons that let you select from a number of specific choices. You can either click on the majority of the gadget to pop-up a list of choices to select from or click on the circular arrow to cycle between the list of choices. Cycle gagdets rarely cause actions to occur, they just adjust some setting or configuration.
 
==== Check Box & Radio Button gadgets ====

[[File:OS4-CheckRadioGadgets.jpg|frame|right]]
Another variant of buttons, check boxes can be clicked to set on/off or yes/no conditions with a checkmark, just like a check box in a paper form. Radio buttons are another variant where two or more round buttons are presented in a set and only one of the set can be clicked and activated, like the buttons on a stereo system.
 
==== Tabs ====

[[File:OS4-Tabs.jpg|frame|right]]
Tabs are a graphical gadget that is used in combination with a "pages" or sets of gadgets and/or information, and you can click on the "tabs" to switch between the pages - like you might in a real notebook with tabbed pages. This provides a efficient way to present more information and settings in a compact interface.
 
====Requesters====

[[File:LibFig2-5.png|frame|right]]
As one uses AmigaOS and it's applications, from time to time a "Requester" window may appear to ask the user a question - basically windows with gadgets in them. Such requesters can appear to confirm an action, obtain more information, make a selection or configuration. Typically a series of buttons across the bottom of the window will dispatch the requester, with the bottom-left button gadget indicating some affirmative choice and the bottom-right button gagdet cancelling the requester (performing no action or change).
 

====Keyboard Operation of Gadgets====
As with so many things, AmigaOS and its applications provide a secondary way to operate many of these gadgets - by keyboard. If a window contains text gadgets, pressing your keyboard's TAB key will activate the text gadgets in sequence (a cursor will appear in each so you can type & edit). Each press of the TAB key will cycle to the next gadget and pressing SHIFT + TAB will cycle through the gadgets in reverse order.

You may have noticed in many of the above sample images that many of the gagdets or their adjacent "label" texts contain a single underlined character. This is a sign that pressing that key on your keyboard will activate that gadget. Each gadget can then be operated by your keyboard - just like clicking on a button, clicking on a tab, setting a text or numeric value, etc. Of course, if you are in the midst of typing in a text gadget, then things you type will go into that gadget instead of operating other gagdets.

== Finding Files in AmigaOS ==

[[File:OS4-ASLReq.jpg|frame|right]]
AmigaOS provides a consistent method for navigating your file system and finding your files from within your apps - the "ASL file requester". It is used by everything in AmigaOS and most third party applications. It is the window (or "requester") that appears when you want to open or save files.

As you can see, the ASL file requester presents the files in a given location in your file systems (a directory or "drawer") and shows their size, date of creation or last modification and any comments attached to the file. The above example shows the same directory as appeared above in this page.

At the bottom corners of the window are buttons to accept the selection ("OK") or cancel the requester. Between those are buttons to view all the drives & partitions on your system ("Volumes") or to move to the "Parent" of the current directory.

Also at the bottom of the window you will see three text gadgets. The first of these is optional and allows you to filter what is shown in the file list - it is now shown filtering out any file with a ".info" suffix (those are AmigaOS icon files). The next two lines reflect the current directory path name and the currently selected file name (also selected in the file list above). In the case of saving files, you would type any name you wanted in the bottom text field to create a new file. Clicking on the titles of the file list will let you sort the file list.

Of course this being AmigaOS, the ASL requester has its own "preferences editor" that lets you set how the requester appears, is sorted by default and a number of mouse button short-cuts.
 

== Controlling AmigaOS - Which Way? ==

AmigaOS provides a number of parallel ways that the user can control and put their Amigas to use. The easiest and most common method is to use the AmigaOS graphic icons, windows and mouse interface - the "Workbench" - using all the GUI elements described above. But AmigaOS also provides a more traditional or "old fashioned" method called a command line interface (the "CLI" or "Shell"), where the user can type text commands and interact using a text interface. AmigaOS also provides a unique means of "interprocess communications" where user can have many applications and parts of the OS "talk" to each other.

=== The Workbench & Intuition ===

As we described above, AmigaOS provides the "Workbench", a straightforward, efficient and easy graphical means to start applications, manage your computer and all your files. Files and programs are represented with icons, generally known as "Projects" and "Tools". They can be stored in any arrangement of directories ("Drawers"). You double-click on a program icon and it will open in a Intuition GUI window on your Workbench screen.

Please see the section about the AmigaOS [http://wiki.amigaos.net/index.php/UserDoc:Workbench Workbench] to learn these concepts:

* What is the Workbench
* Workbench menus
* Keyboard control
* Workbench requesters
* Configuration
* Workbench help

=== The Shell & DOS Commands ===

[[File:OS4-Window-Shell.jpg|frame|right]]
The AmigaOS Shell can be opened by double-clicking the "Shell" icon in the AmigaOS "System" drawer. The Shell is a text based interface that allows you to perform most of the same operations as the Workbench - to run and interact with application programs, manage files and control your Amiga computer. AmigaOS also comes with dozens of standard "DOS commands" (programs purely meant for Shell usage). Simply enter the name of a program or command (like "dir") and press Enter, the command or program will run and it will print its results in the Shell window. While considered old fashioned, many users find the Shell to still be the most efficient way to perform many tasks on the Amigas.

Please see the section on the [[UserDoc:Shell|AmigaOS Shell]] to learn more.
 

=== Scripts & Messages ===

Scripts are simple text files that contain a list of commands written in a variety of languages: the AmigaDOS, Arexx and Python languages are provided with AmigaOS - there are many others. Each of these language has its strengths. You'll have to learn the one that suits what you want to do. You can create a script using a text editor. You can run such script from the Workbench or from the shell (or from any other script). By using ARexx ports provided by AmigaOS components (the Workbench or Multiview, for example) or third-party applications, scripts can be used to make your computer perform a wide variety of actions.

== AmigaOS System Tools ==
AmigaOS comes with a variety of programs to help in the preparation of your computer. These include tools for:

* Drive preparation (Media Toolbox, Format, Format DCRW & Mounter).
* Font Handling (TypeManager & FixFonts).
* Script Languages (RexxMast and Python).
* The Shell.
* Miscellaneous Utilities (Find, Help, Grim Reaper & Ringhio Server).

== AmigaOS Utilities ==
AmigaOS comes with a selection of utilities to assist the user, including:

* Commodities.
* Editors (Notepad, MEmacs, PrefsObjectEditor & IconEdit).
* Postscript oriented apps (AmiPDF, AmiGS & Ghostscript).
* Disk apps (PartitionWizard & RawDisk).
* Screenblankers.
* AmiDock and Dockies.
* The Unarc dearchiver.
* PlayCD.
* Several "sub-programs" that are used by other system utilities (blankers, dockies)
* Miscellaneous apps (Clock, printing apps, KeyShow, install apps, etc.).

Read [[Utilities|here]] to find all of them explained further.

== AmigaOS Preferences ==
AmigaOS comes with a number of small programs used for modifying the system's settings. These are stored in the [[Prefs]] drawer, and include programs for modifying the following settings:

* General appearance
* Screen resolution
* Desktop and window backgrounds
* Language settings
* Keyboard and mouse settings
* Printer settings
* Audio settings

Read [[Prefs|here]] for details and explanations of all the preference programs.

Utilities

2014-05-19T12:38:39Z

Rob Cranley: /* Blankers (Dir) */ Added basic description

= Introduction =

Below is the list of what is included in a default AmigaOS installation. You can find either programs or a group of "sub-programs" that another program needs. For your convenience they are marked with a "(Dir)" if they represent a directory.

= AmigaOS SYS:Utilities =

== AmiGS (Dir) ==

== AmiPDF (Dir) ==

== Blankers (Dir) ==
The Blankers drawer contains individual modules which are used to blank the screen, usually replacing the screen's contents with moving patterns or images. Each module can provide a different effect, and it is these modules which are used by the ScreenBlanker commodity. Additional modules can be downloaded and added to this drawer. The modules used are selected using the [[Blanker preferences]] program.

== bru ==

== Calculator ==

== CatComp ==

== Clock ==

== Commodities (Dir) ==
The Commodities drawer contains small "[[commodity]]" programs - little applications which can add or modify features of AmigaOS in order to adjust its behaviour to your liking. Examples include [[Exchange]] for controlling all commodities, [[ClickToFront]] for changing how windows are moved to the front of the view on screen, and [[ScreenBlanker]] which shows a screen saver after a period of inactivity.

== Dockies (Dir) ==

== Ghostscript (Dir) ==

== GraphicDump ==

== HDBackup ==

Note: Not yet released as of May 2014.

== IconEdit ==

== InitPrinter ==

== Installation Utility ==

== Installer ==

== InstallExtras (Dir) ==

== KeyShow ==

== LogViewer ==

== MEmacs ==

== More ==

== [[MultiView]] ==

[[MultiView]] is a multipurpose viewer utility. It will display all files for which a datatype is installed. Multiview is capable of displaying different files such as text, pictures, sound and animations.
It can be controlled by a GUI, command line arguments and an AREXX interface.

== NotePad ==
Notepad is a utility for editing plain text files. It supports clipboard operation for copying and pasting text to and from other files and applications, and can be controlled using a simple GUI. For more advanced users, Notepad can be used for editing scripts, such as [[ARexx]] scripts or the [[S:User-Startup]] file.

== PartitionWizard ==

== PlayCD ==

== ppp_connector, ppp_dialer, ppp_sample ==

== PrefsObjectsEditor ==

== PrintFiles ==

== RawDisk ==

== SGrab (Dir) ==
The [[SGrab]] drawer contains the SGrab commodity and documentation. SGrab is used for taking screengrabs of AmigaOS screens and saving them in a location and format of your choosing. Many options are available, such as hotkey activation and adjustable image quality. See the enclosed documentation for more details.

== ShowConfig ==

== UnArc ==

== USBInspector ==

Utilities

2014-05-19T12:31:43Z

Rob Cranley: /* SGrab (Dir) */ Added basic description

= Introduction =

Below is the list of what is included in a default AmigaOS installation. You can find either programs or a group of "sub-programs" that another program needs. For your convenience they are marked with a "(Dir)" if they represent a directory.

= AmigaOS SYS:Utilities =

== AmiGS (Dir) ==

== AmiPDF (Dir) ==

== Blankers (Dir) ==

== bru ==

== Calculator ==

== CatComp ==

== Clock ==

== Commodities (Dir) ==
The Commodities drawer contains small "[[commodity]]" programs - little applications which can add or modify features of AmigaOS in order to adjust its behaviour to your liking. Examples include [[Exchange]] for controlling all commodities, [[ClickToFront]] for changing how windows are moved to the front of the view on screen, and [[ScreenBlanker]] which shows a screen saver after a period of inactivity.

== Dockies (Dir) ==

== Ghostscript (Dir) ==

== GraphicDump ==

== HDBackup ==

Note: Not yet released as of May 2014.

== IconEdit ==

== InitPrinter ==

== Installation Utility ==

== Installer ==

== InstallExtras (Dir) ==

== KeyShow ==

== LogViewer ==

== MEmacs ==

== More ==

== [[MultiView]] ==

[[MultiView]] is a multipurpose viewer utility. It will display all files for which a datatype is installed. Multiview is capable of displaying different files such as text, pictures, sound and animations.
It can be controlled by a GUI, command line arguments and an AREXX interface.

== NotePad ==
Notepad is a utility for editing plain text files. It supports clipboard operation for copying and pasting text to and from other files and applications, and can be controlled using a simple GUI. For more advanced users, Notepad can be used for editing scripts, such as [[ARexx]] scripts or the [[S:User-Startup]] file.

== PartitionWizard ==

== PlayCD ==

== ppp_connector, ppp_dialer, ppp_sample ==

== PrefsObjectsEditor ==

== PrintFiles ==

== RawDisk ==

== SGrab (Dir) ==
The [[SGrab]] drawer contains the SGrab commodity and documentation. SGrab is used for taking screengrabs of AmigaOS screens and saving them in a location and format of your choosing. Many options are available, such as hotkey activation and adjustable image quality. See the enclosed documentation for more details.

== ShowConfig ==

== UnArc ==

== USBInspector ==

Utilities

2014-05-19T12:28:56Z

Rob Cranley: /* Commodities (Dir) */ Added basic description

= Introduction =

Below is the list of what is included in a default AmigaOS installation. You can find either programs or a group of "sub-programs" that another program needs. For your convenience they are marked with a "(Dir)" if they represent a directory.

= AmigaOS SYS:Utilities =

== AmiGS (Dir) ==

== AmiPDF (Dir) ==

== Blankers (Dir) ==

== bru ==

== Calculator ==

== CatComp ==

== Clock ==

== Commodities (Dir) ==
The Commodities drawer contains small "[[commodity]]" programs - little applications which can add or modify features of AmigaOS in order to adjust its behaviour to your liking. Examples include [[Exchange]] for controlling all commodities, [[ClickToFront]] for changing how windows are moved to the front of the view on screen, and [[ScreenBlanker]] which shows a screen saver after a period of inactivity.

== Dockies (Dir) ==

== Ghostscript (Dir) ==

== GraphicDump ==

== HDBackup ==

Note: Not yet released as of May 2014.

== IconEdit ==

== InitPrinter ==

== Installation Utility ==

== Installer ==

== InstallExtras (Dir) ==

== KeyShow ==

== LogViewer ==

== MEmacs ==

== More ==

== [[MultiView]] ==

[[MultiView]] is a multipurpose viewer utility. It will display all files for which a datatype is installed. Multiview is capable of displaying different files such as text, pictures, sound and animations.
It can be controlled by a GUI, command line arguments and an AREXX interface.

== NotePad ==
Notepad is a utility for editing plain text files. It supports clipboard operation for copying and pasting text to and from other files and applications, and can be controlled using a simple GUI. For more advanced users, Notepad can be used for editing scripts, such as [[ARexx]] scripts or the [[S:User-Startup]] file.

== PartitionWizard ==

== PlayCD ==

== ppp_connector, ppp_dialer, ppp_sample ==

== PrefsObjectsEditor ==

== PrintFiles ==

== RawDisk ==

== SGrab (Dir) ==

== ShowConfig ==

== UnArc ==

== USBInspector ==

Utilities

2014-05-19T12:21:43Z

Rob Cranley: /* NotePad */

Utilities

2014-05-19T12:21:07Z

Rob Cranley: /* NotePad */ Added basic description

Configuring Workbench and AmigaOS

2014-01-31T17:03:17Z

Rob Cranley: /* Configuring through the User-startup */

[[Category:Workbench]][[Category:Preferences]]
AmigaOS and the Workbench comes with a suite of program preferences to adjust Sound, Graphics, Text, Display, Font settings and more.

== Configuring through the User-startup ==

The user-startup is a simple AmigaDOS script containing commands that will be executed everytime AmigaOS starts.
It is optional but it is always used by the user as it is an easy way to add custom settings to the system.

The [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] is so critical for the correct starting of the operating system that it is recommended to never modify it. Instead, users can edit the [[UserDoc:System_Scripts#user-startup|user-startup]] to start their own programs or set their own settings.

As an example, if you want to create an assign each time you boot AmigaOS, just add the following line to your user-startup:

''Assign myassign: Disk:mydirectory''

== Configuring through the Devs:... ==

== The Save/Use/Test concept==

[[File:Save-use-test-cancel.png|frame|Buttons at the bottom of the preferences programs]]
In AmigaOS you can modify some settings and test them '''without''' storing the modifications on disk. This is very handy because you can modify a lot of settings but you can always go back very easily to your saved configuration. You don't need to keep a list of all the changes you do and there is no fear you break something.
When you want to cancel all your tests, just restart the system and you automatically restore the previous (correct) settings.
This way it's up to the user to decide when the settings will be saved. The operating system will never store modifications by itself.

To reflect this mechanism all preferences programs have the following 4 buttons (if possible):

* Save
This will save on disk the current settings so they will become permanent. The preferences program will also close.

* Use
When you click this button, the current settings will be applied on the system but ''not saved'' on disk. The preferences program will also close.

* Test
This button will apply the current settings but the program will stay open. This way you can immediately see the result of your settings and you can modify them again and do another test.

* Cancel
This will cancel any modification you did since the program was opened. Changes will be reverted and the program will close.

== List of all the preferences programs you can use ==

[[Workbench/Prefs/AHI|AHI]] (Audio Hardware Interface) - Allows for control over the audio functions of your Amiga

[[Workbench/Prefs/amigainput|AmigaInput]] - Setup for gamepads and joysticks

[[Workbench/Prefs/asl|ASL]] - Allows for control over file requesters

[[Workbench/Prefs/compatibility|Compatibility]] - Manages the 68K Just-in-time compiler settings

[[Workbench/Prefs/console|Console]] - Controls the settings for the Amiga Shell

[[Workbench/Prefs/deficons|DefIcons]] - Interface to allow behaviour of default icons

[[Workbench/Prefs/dos|DOS]] - Manages DOS settings

[[Workbench/Prefs/font|Font]] - Controls Font selection for Workbench, Screens, and Windows

[[Workbench/Prefs/gui|GUI]] - Used to control the look and feel of various elements of the AmigaOS 4 interface

[[Workbench/Prefs/input|Input]] - Controls the settings for the keyboard and mouse

[[Workbench/Prefs/internet|Internet]] - Contains settings for the computer's network connections

[[Workbench/Prefs/locale|Locale]] - Sets the user's preferred languages

[[Workbench/Prefs/notifications|Notifications]] - Controls the behaviour of Ringhio, the AmigaOS 4.1 pop-up notification system

[[Workbench/Prefs/palette|Palette]] - Allows the user to adjust certain colours used for some on-screen elements

[[Workbench/Prefs/Picasso96Mode|Picasso96Mode]] - Advanced controls for creating and modifying graphics modes

[[Workbench/Prefs/pointer|Pointer]] - Allows editing of the mouse pointer's image

[[Workbench/Prefs/popupmenu|PopupMenu]] - Settings controlling the look and behaviour of the system's pop-up menus

[[Workbench/Prefs/printer|Printer]] -

[[Workbench/Prefs/printergfx|PrinterGfx]] -

[[Workbench/Prefs/printerps|PrinterPS]] -

[[Workbench/Prefs/screenblanker|ScreenBlanker]] - Preferences for the system's screen saver / screen blanker

[[Workbench/Prefs/ScreenMode|ScreenMode]] - Settings for screen resolution and colour depth

[[Workbench/Prefs/screens|Screens]] - Allows the setting up and control of custom screens for applications

[[Workbench/Prefs/serial|Serial]] - Sets the default settings for the serial port

[[Workbench/Prefs/time|Time]] - Allows the user to set the system's time and date

[[Workbench/Prefs/timezone|Timezone]] - Allows the user to set their current timezone and Daylight Saving Time preferences

[[Workbench/Prefs/uboot|UBoot]] - Advanced settings concerning the computer's initial booting system

[[Workbench/Prefs/usb|USB]] - Contains USB preferences and information

[[Workbench/Prefs/wbpattern|WBPattern]] - Settings for the background of the Workbench screen and directory windows

[[Workbench/Prefs/wbstartup|WBStartup]] - Controls which programs are launched when Workbench starts

[[Workbench/Prefs/workbench|Workbench]] - Settings which control certain aspects of the Workbench's behaviour

Using the Workbench

2012-07-24T12:27:44Z

Rob Cranley: More detail in closing drawers section.

[[Category:Workbench]]
There are two primary means of interacting with icons or files on the Workbench, those sat on the Workbench screen, also known as the Desktop, and those sat in Drawers.

'''Workbench Screen'''

The Workbench screen is the primary visual component of your system. Its main element is the Workbench root window; it can be either a normal window, or, more commonly used, a backdrop window, in which case the window frame vanishes, and its content is displayed directly on the Workbench background. Nevertheless, it is actually still technically a window. In either case, the role of the root window is the same: icons and other windows appear on it.

The Workbench screen itself is identified by the Amiga Workbench title bar located along the top border of the display. The title bar also displays the number of bytes of graphics memory and other memory currently available. You can change which pieces of information are displayed in the title bar; this is done in the Workbench preferences program in your Prefs drawer, where also other useful adjustments can be made to the way your Workbench operates.

When you boot your Amiga, the Workbench root window contains icons for any disks present in the system (including removable disks), the Ram Disk, and any other icons determined by your system configuration.

If you press the right mouse button, the title bar will show all available [[Using_the_Workbench_menus|menus]].

'''Drawers'''

A Drawer displays the content of a directory or folder stored on your computer.

By default, the files shown here all have an associated icon file. The icon is the little image you actually see. To open a file, double-click its icon. Files without an associated icon are normally hidden.

In order to display all files (i.e. even those without an icon), select [[Window_Menu_-_Show...|Show All Files]] in the Window menu.

To close the window, click on its close gadget (located in the top left corner of the window), select [[Window_Menu_-_Close|Close]] in the Window menu or press ''Right AMIGA+K'' (see [[Using_the_keyboard_to_control_Workbench|keystrokes]] for a list of useful keyboard shortcuts).

Using the Workbench

2012-07-24T11:53:26Z

Rob Cranley: Rearranged files in drawers description to improve grammar; added a little more detail.

[[Category:Workbench]]
There are two primary means of interacting with icons or files on the Workbench, those sat on the Workbench screen, also known as the Desktop, and those sat in Drawers.

'''Workbench Screen'''

The Workbench screen is the primary visual component of your system. Its main element is the Workbench root window; it can be either a normal window, or, more commonly used, a backdrop window, in which case the window frame vanishes, and its content is displayed directly on the Workbench background. Nevertheless, it is actually still technically a window. In either case, the role of the root window is the same: icons and other windows appear on it.

The Workbench screen itself is identified by the Amiga Workbench title bar located along the top border of the display. The title bar also displays the number of bytes of graphics memory and other memory currently available. You can change which pieces of information are displayed in the title bar; this is done in the Workbench preferences program in your Prefs drawer, where also other useful adjustments can be made to the way your Workbench operates.

When you boot your Amiga, the Workbench root window contains icons for any disks present in the system (including removable disks), the Ram Disk, and any other icons determined by your system configuration.

If you press the right mouse button, the title bar will show all available [[Using_the_Workbench_menus|menus]].

'''Drawers'''

A Drawer displays the content of a directory or folder stored on your computer.

By default, the files shown here all have an associated icon file. The icon is the little image you actually see. To open a file, double-click its icon. Files without an associated icon are normally hidden.

In order to display all files (i.e. even those without an icon), select [[Window_Menu_-_Show...|Show All Files]] in the Window menu.

To close the window, select [[Window_Menu_-_Close|Close]] in the Window menu or press '''AMIGA+K'' (see [[Using_the_keyboard_to_control_Workbench|keystrokes]] for a list of useful keyboard shortcuts).

Configuring Workbench and AmigaOS

2012-06-29T12:40:50Z

Rob Cranley:

[[Category:Workbench]][[Category:Preferences]]
AmigaOS and the Workbench comes with a suite of program preferences to adjust Sound, Graphics, Text, Display, Font settings and more.

Here are the preferences programs that are available in AmigaOS 4.x:

[[amigaos41ahi|AHI]] (Audio Hardware Interface) - Allows for control over the audio functions of your Amiga

[[amigaos41amigainput|AmigaInput]] - Setup for gamepads and joysticks

[[amigaos41asl|ASL]] - Allows for control over file requesters

[[amigaos41compatibility|Compatibility]] - Manages the 68K Just-in-time compiler settings

[[amigaos41console|Console]] - Controls the settings for the Amiga Shell

[[amigaos41deficons|DefIcons]] - Interface to allow behavour of default icons

[[amigaos41dos|DOS]] - Manages DOS settings

[[amigaos41font|Font]] - Controls Font selection for Workbench, Screens, and Windows

[[amigaos41gui|GUI]] - Used to control the look and feel of various elements of the AmigaOS 4 interface

[[amigaos41input|Input]] - Controls the settings for the keyboard and mouse

[[amigaos41internet|Internet]] - Contains settings for the computer's network connections

[[amigaos41locale|Locale]] - Sets the user's preferred languages

[[amigaos41notifications|Notifications]] - Controls the behaviour of Ringhio, the AmigaOS 4.1 pop-up notification system

[[amigaos41palette|Palette]] - Allows the user to adjust certain colours used for some on-screen elements

[[amigaos41Picasso96Mode|Picasso96Mode]] - Advanced controls for creating and modifying graphics modes

[[amigaos41pointer|Pointer]] - Allows editing of the mouse pointer's image

[[amigaos41popupmenu|PopupMenu]] - Settings controlling the look and behaviour of the system's pop-up menus

[[amigaos41printer|Printer]] -

[[amigaos41printergfx|PrinterGfx]] -

[[amigaos41printerps|PrinterPS]] -

[[amigaos41screenblanker|ScreenBlanker]] - Preferences for the system's screen saver / screen blanker

[[amigaos41screenmode|ScreenMode]] - Settings for screen resolution and colour depth

[[amigaos41screens|Screens]] - Allows the setting up and control of custom screens for applications

[[amigaos41serial|Serial]] - Sets the default settings for the serial port

[[amigaos41time|Time]] - Allows the user to set the system's time and date

[[amigaos41timezone|Timezone]] - Allows the user to set their current timezone and Daylight Saving Time preferences

[[amigaos41uboot|UBoot]] - Advanced settings concerning the computer's initial booting system

[[amigaos41usb|USB]] - Contains USB preferences and information

[[amigaos41wbpattern|WBPattern]] - Settings for the background of the Workbench screen and directory windows

[[amigaos41wbstartup|WBStartup]] - Controls which programs are launched when Workbench starts

[[amigaos41workbench|Workbench]] - Settings which control certain aspects of the Workbench's behaviour

Configuring Workbench and AmigaOS

2012-06-29T12:40:24Z

Rob Cranley:

[[Category:Workbench]][[Category:Preferences]]
AmigaOS and the Workbench comes with a suite of program preferences to adjust Sound, Graphics, Text, Display, Font settings and more.

Here are the preferences programs that are available in AmigaOS 4.x:

[[amigaos41ahi|AHI]] (Audio Hardware Interface) - Allows for control over the audio functions of your Amiga

[[amigaos41amigainput|AmigaInput]] - Setup for gamepads and joysticks

[[amigaos41asl|ASL]] - Allows for control over file requesters

[[amigaos41compatibility|Compatibility]] - Manages the 68K Just-in-time compiler settings

[[amigaos41console|Console]] - Controls the settings for the Amiga Shell

[[amigaos41deficons|DefIcons]] - Interface to allow behavour of default icons

[[amigaos41dos|DOS]] - Manages DOS settings

[[amigaos41font|Font]] - Controls Font selection for Workbench, Screens, and Windows

[[amigaos41gui|GUI]] - Used to control the look and feel of various elements of the AmigaOS 4 interface

[[amigaos41input|Input]] - Controls the settings for the keyboard and mouse

[[amigaos41internet|Internet]] - Contains settings for the computer's network connections

[[amigaos41locale|Locale]] - Sets the user's preferred languages

[[amigaos41notifications|Notifications]] - Controls the behaviour of Ringhio, the AmigaOS 4.1 pop-up notification system

[[amigaos41palette|Palette]] - Allows the user to adjust certain colours used for some on-screen elements

[[amigaos41Picasso96Mode|Picasso96Mode]] - Advanced controls for creating and modifying graphics modes

[[amigaos41pointer|Pointer]] - Allows editing of the mouse pointer's image

[[amigaos41popupmenu|PopupMenu]] - Settings controlling the look and behaviour of the system's pop-up menus

[[amigaos41printer|Printer]] -

[[amigaos41printergfx|PrinterGfx]] -

[[amigaos41printerps|PrinterPS]] -

[[amigaos41screenblanker|ScreenBlanker]] - Preferences for the system's screen saver / screen blanker

[[amigaos41screenmode|ScreenMode]] - Settings for screen resolution and colour depth

[[amigaos41screens|Screens]] - Allows the setting up and control of custom screens for applications

[[amigaos41serial|Serial]] - Sets the default settings for the serial port

[[amigaos41time|Time]] - Allows the user to set the system's time and date

[[amigaos41timezone|Timezone]] - Allows the user to set theyr current timezone and Daylight Saving Time preferences

[[amigaos41uboot|UBoot]] - Advanced settings concerning the computer's initial booting system

[[amigaos41usb|USB]] - Contains USB preferences and information

[[amigaos41wbpattern|WBPattern]] - Settings for the background of the Workbench screen and directory windows

[[amigaos41wbstartup|WBStartup]] - Controls which programs are launched when Workbench starts

[[amigaos41workbench|Workbench]] - Settings which control certain aspects of the Workbench's behaviour

Configuring Workbench and AmigaOS

2012-06-29T07:46:48Z

Rob Cranley:

[[Category:Workbench]][[Category:Preferences]]
AmigaOS and the Workbench comes with a suite of program preferences to adjust Sound, Graphics, Text, Display, Font settings and more.

Here are the preferences programs that are available in AmigaOS 4.x:

[[amigaos41ahi|AHI]] (Audio Hardware Interface) - Allows for control over the audio functions of your Amiga

[[amigaos41amigainput|AmigaInput]] - Setup for gamepads and joysticks

[[amigaos41asl|ASL]] - Allows for control over file requesters

[[amigaos41compatibility|Compatibility]] - Manages the 68K Just-in-time compiler settings

[[amigaos41console|Console]] - Controls the settings for the Amiga Shell

[[amigaos41deficons|DefIcons]] - Interface to allow behavor of default icon

[[amigaos41dos|DOS]] - Manages DOS settings

[[amigaos41font|Font]] - Controls Font selection for Workbench, Screens, and Windows

[[amigaos41gui|GUI]] -

[[amigaos41input|Input]] - Controls the settings for the keyboard and mouse

[[amigaos41internet|Internet]] -

[[amigaos41locale|Locale]] -

[[amigaos41notifications|Notifications]] - Controls the behaviour of Ringhio, the AmigaOS 4.1 pop-up notification system

[[amigaos41palette|Palette]] -

[[amigaos41Picasso96Mode|Picasso96Mode]] - Advanced controls for creating and modifying graphics modes

[[amigaos41pointer|Pointer]] - Allows editing of the mouse pointer's image

[[amigaos41popupmenu|PopupMenu]] -

[[amigaos41printer|Printer]] -

[[amigaos41printergfx|PrinterGfx]] -

[[amigaos41printerps|PrinterPS]] -

[[amigaos41screenblanker|ScreenBlanker]] -

[[amigaos41screenmode|ScreenMode]] - Settings for screen resolution and colour depth

[[amigaos41screens|Screens]] -

[[amigaos41serial|Serial]] -

[[amigaos41time|Time]] - Allows the user to set the system's time and date

[[amigaos41timezone|Timezone]] -

[[amigaos41uboot|UBoot]] -

[[amigaos41usb|USB]] -

[[amigaos41wbpattern|WBPattern]] - Settings for the background of the Workbench screen and directory windows

[[amigaos41wbstartup|WBStartup]] - Controls which programs are launched when Workbench starts

[[amigaos41workbench|Workbench]] - Settings which control certain aspects of the Workbench's behaviour

UserDoc:Workbench

2012-06-29T07:36:06Z

Rob Cranley:

AmigaOS has it's own desktop environment called [[Using_the_Workbench|Workbench]].

[[Using_the_Workbench|Workbench]] comes with a range of features to help users access and arrange their documents, photographs, music and video files in an intuitive manner. Naturally, users may also customise the look and feel of [[Using_the_Workbench|Workbench]] from the background desktop image through to the design of the interface and much more.

[[Using_the_Workbench|Understanding Workbench]]

[[Using the Workbench menus|Using the Workbench menus]]

[[Using the keyboard to control Workbench|Using the keyboard to control Workbench]]

[[Understanding Workbench requesters|Understanding Workbench requesters]]

[[Configuring Workbench and AmigaOS|Configuring Workbench and AmigaOS]]

[[AmigaOS_Updates|Updating to the latest version of AmigaOS]]

----

[[Glossary|Glossary]]

'''Workbench Help'''

By pressing the Help key on your keyboard (commonly found sharing the Scroll Lock key on a modern keyboard) you can open Workbench Help.
Workbench Help is context-sensitive, when you press the Help key it will open up directly into the section of Workbench Help most relevant. For instance, if the Workbench desktop is selected, pressing the Help key will open the guide on the page about the [[Using_the_Workbench|Workbench Screen]].