Changes between Initial Version and Version 1 of Documentation/ARexxAPI


Ignore:
Timestamp:
Sep 22, 2013 8:15:24 PM (11 months ago)
Author:
AmigaPhil
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/ARexxAPI

    v1 v1  
     1== Reference - ARexx interface 
     2 
     3 
     4With the help of ARexx scripts, you can add new functions to YAM or 
     5let it do things automatically.  YAM offers a set of commands (listed 
     6in this documentation both [[rexx| by name ]] and [[rexl| by function ]]) which can be called 
     7through the '''YAM''' ARexx port.  They are explained along the following 
     8subchapters using the following format: 
     9 
     10 
     11'''NAME''' 
     12     The name of the command, a short description of what it does and 
     13     the YAM version where the command was implemented. 
     14 
     15'''TEMPLATE''' 
     16     Arguments and options accepted by the command.  The template uses 
     17     special characters that indicate the particular type of argument 
     18     expected, following the AmigaDOS template style: 
     19 
     20          /A   The parameter is compulsory\\ 
     21          /K   The parameter must be preceeded by the keyword\\ 
     22          /N   Numerical argument or result\\ 
     23          /M   Argument or result is a list of zero or more elements\\ 
     24          /S   The parameter works as a switch; the switch is in use when the parameter is given\\ 
     25 
     26'''FUNCTION''' 
     27     Describes what the command will do. 
     28 
     29'''INPUTS''' 
     30     Describes in detail the parameters accepted by the command. 
     31     Be careful when passing arguments containing spaces; for instance, 
     32 
     33          sub = 'Hello World'\\ 
     34          'WRITESUBJECT' sub 
     35 
     36     won't work!  It must be written as 
     37 
     38          'WRITESUBJECT "'sub'"' 
     39 
     40     or 
     41 
     42          'WRITESUBJECT "Hello World"' 
     43 
     44 
     45     Please note that because of the internal use of the ReadArgs() function, 
     46     the ARexx Host requires to escape certain special characters like a newline 
     47     (0x0a) or escape character (0x1b) if you want to have it included in your 
     48     final string or otherwise it is stripped by the ReadArgs() function. 
     49 
     50     This means that you have to use the following escape sequences in your 
     51     provided strings: 
     52 
     53      *N substitutes to 0x0a\\ 
     54      *E substitutes to 0x1b\\ 
     55      !** substitutes to *\\ 
     56      *" substitutes to "\\ 
     57 
     58     For example the following command would write a string to a texteditor 
     59     containing a newline: 
     60 
     61     'WRITEEDITOR "TEXT Hello Joe,*N I would like to meet you."' 
     62 
     63'''RETURNS''' 
     64     Returned info to be expected from the command.  Commands may return 
     65     results in three different kinds; let's look at these examples which 
     66     use the FOLDERINFO command: 
     67 
     68 
     69          FOLDERINFO 
     70            -> RESULT = "0 Incoming incoming 10 2 4 23030 1" 
     71 
     72          FOLDERINFO VAR fi 
     73            -> fi = "0 Incoming incoming 10 2 4 23030 1" 
     74 
     75          FOLDERINFO STEM fi. 
     76            -> fi.number = 0\\ 
     77                fi.name = "Incoming"\\ 
     78                fi.path = "incoming"\\ 
     79                fi.total = 10\\ 
     80                fi.new = 2\\ 
     81                fi.unread = 4\\ 
     82                fi.size = 23030\\ 
     83                fi.type = 1\\ 
     84 
     85     Another example which returns a result of type /M: 
     86 
     87          ADDRFIND STEM found. "Marcel Beck" NAMEONLY 
     88            -> found.alias.count = 2\\ 
     89                found.alias.0 = "Mars"\\ 
     90                found.alias.1 = "mbe"\\ 
     91 
     92'''WARNING''' 
     93     Any sort of vital information you should be aware of when using 
     94     this command. 
     95 
     96'''NOTES''' 
     97     Various notes about the command. 
     98 
     99'''EXAMPLE''' 
     100     A fragment of ARexx code to illustrate the usage of the command. 
     101 
     102'''BUGS''' 
     103     Problems that are known or have already been fixed with this command. 
     104 
     105'''SEE ALSO''' 
     106     Links to other related commands.