Legend:

With the help of ARexx scripts, you can add new functions to YAM or let it do things automatically.\\

8

7

YAM offers a set of commands (listed in this documentation both [[ARexx API/List by Name| by name ]] and [[ARexx API/List by Function| by function ]]) which can be called through the '''YAM''' ARexx port. They are explained along the following

9

8

subchapters using the following format:

10

9

10

NAME::

11

The name of the command, a short description of what it does and the YAM version where the command was implemented.

11

12

12

'''NAME'''

13

The name of the command, a short description of what it does and the YAM version where the command was implemented.

13

TEMPLATE::

14

Arguments and options accepted by the command. The template uses special characters that indicate the particular type of argument expected, following the AmigaDOS template style:

14

15

15

'''TEMPLATE'''

16

Arguments and options accepted by the command. The template uses special characters that indicate the particular type of argument expected, following the AmigaDOS template style:

16

`/A` The parameter is compulsory\\

17

`/K` The parameter must be preceeded by the keyword\\

18

`/N` Numerical argument or result\\

19

`/M` Argument or result is a list of zero or more elements\\

20

`/S` The parameter works as a switch; the switch is in use when the parameter is given\\

17

21

18

/A The parameter is compulsory\\

19

/K The parameter must be preceeded by the keyword\\

20

/N Numerical argument or result\\

21

/M Argument or result is a list of zero or more elements\\

22

/S The parameter works as a switch; the switch is in use when the parameter is given\\

22

FUNCTION::

23

Describes what the command will do.

23

24

24

'''FUNCTION'''

25

Describes what the command will do.

25

INPUTS::

26

Describes in detail the parameters accepted by the command.

27

Be careful when passing arguments containing spaces; for instance,

26

28

27

'''INPUTS'''

28

Describes in detail the parameters accepted by the command.

29

Be careful when passing arguments containing spaces; for instance,

29

{{{#!urbiscript

30

sub = 'Hello World'

31

'WRITESUBJECT' sub

32

}}}

33

34

won't work. It must be written as

30

35

31

sub = 'Hello World'\\

32

'WRITESUBJECT' sub

36

{{{#!urbiscript

37

'WRITESUBJECT "'sub'"'

38

}}}

33

39

34

won't work. It must be written as

40

or

35

41

36

'WRITESUBJECT "'sub'"'

42

{{{#!urbiscript

43

'WRITESUBJECT "Hello World"'

44

}}}

37

45

38

or

46

Please note that because of the internal use of the ReadArgs() function, the ARexx Host requires to escape certain special characters like a newline (0x0a) or escape character (0x1b) if you want to have it included in your final string or otherwise it is stripped by the ReadArgs() function.

39

47

40

'WRITESUBJECT "Hello World"'

48

This means that you have to use the following escape sequences in your provided strings:

41

49

50

`*N` substitutes to 0x0a (newline \n) \\

51

`*E` substitutes to 0x1b (escape)\\

52

`!**` substitutes to *\\

53

`*` substitutes to "\\

42

54

43

Please note that because of the internal use of the ReadArgs() function, the ARexx Host requires to escape certain special characters like a newline (0x0a) or escape character (0x1b) if you want to have it included in your final string or otherwise it is stripped by the ReadArgs() function.

55

For example the following command would write a string to a texteditor containing a newline:

44

56

45

This means that you have to use the following escape sequences in your provided strings:

57

{{{#!urbiscript

58

'WRITEEDITOR "TEXT Hello Joe,*N I would like to meet you."'

59

}}}

46

60

47

*N substitutes to 0x0a\\

48

*E substitutes to 0x1b\\

49

!** substitutes to *\\

50

*" substitutes to "\\

61

If a parameter represents a file name you should keep in mind that file names on AmigaOS might contain spaces or other special characters which will cause ARexx to treat the name as multiple words instead of a single word. Hence a file name should '''always''' be surrounded by quotes, no matter if it contains spaces or not. Scripts can very easily be tested for this case by letting them handle a file in the Amiga RAM disk, i.e. "RAM Disk:/foo/bar".

51

62

52

For example the following command would write a string to a texteditor containing a newline:

63

RETURNS::

64

Returned info to be expected from the command. Commands may return results in three different kinds; let's look at these examples which use the FOLDERINFO command:

53

65

54

'WRITEEDITOR "TEXT Hello Joe,*N I would like to meet you."'

66

{{{#!urbiscript

67

FOLDERINFO

68

-> RESULT = "0 Incoming incoming 10 2 4 23030 1"

69

}}}

55

70

56

If a parameter represents a file name you should keep in mind that file names on AmigaOS might contain spaces or other special characters which will cause ARexx to treat the name as multiple words instead of a single word. Hence a file name should '''always''' be surrounded by quotes, no matter if it contains spaces or not. Scripts can very easily be tested for this case by letting them handle a file in the Amiga RAM disk, i.e. "RAM Disk:/foo/bar".

71

{{{#!urbiscript

72

FOLDERINFO VAR fi

73

-> fi = "0 Incoming incoming 10 2 4 23030 1"

74

}}}

57

75

58

'''RETURNS'''

59

Returned info to be expected from the command. Commands may return results in three different kinds; let's look at these examples which use the FOLDERINFO command:

76

{{{#!urbiscript

77

FOLDERINFO STEM fi.

78

-> fi.number = 0

79

fi.name = "Incoming"

80

fi.path = "incoming"

81

fi.total = 10

82

fi.new = 2

83

fi.unread = 4

84

fi.size = 23030

85

fi.type = 1

86

}}}

60

87

88

Another example which returns a result of type `/M`:

61

89

62

FOLDERINFO

63

-> RESULT = "0 Incoming incoming 10 2 4 23030 1"

90

{{{#!urbiscript

91

ADDRFIND STEM found. "Marcel Beck" NAMEONLY

92

-> found.alias.count = 2

93

found.alias.0 = "Mars"

94

found.alias.1 = "mbe"

95

}}}

64

96

65

FOLDERINFO VAR fi

66

-> fi = "0 Incoming incoming 10 2 4 23030 1"

67

68

FOLDERINFO STEM fi.

69

-> fi.number = 0\\

70

fi.name = "Incoming"\\

71

fi.path = "incoming"\\

72

fi.total = 10\\

73

fi.new = 2\\

74

fi.unread = 4\\

75

fi.size = 23030\\

76

fi.type = 1\\

77

78

Another example which returns a result of type /M:

79

80

ADDRFIND STEM found. "Marcel Beck" NAMEONLY

81

-> found.alias.count = 2\\

82

found.alias.0 = "Mars"\\

83

found.alias.1 = "mbe"\\

84

85

'''WARNING'''

97

WARNING::

86

98

Any sort of vital information you should be aware of when using this command.