Changes between Version 11 and Version 27 of Documentation/ARexxAPI


Ignore:
Timestamp:
(multiple changes)
Author:
(multiple changes)
Comment:
(multiple changes)

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/ARexxAPI

    v11 v27  
    1 [[TranslatedPages]]\\ 
    2 [[TOC(titleindex, heading=ARexx API, notitle, depth=1, Documentation/ARexx API/*)]] 
    3  
    4 == Reference - ARexx interface 
     1[[TranslatedPages]] 
     2[[TOC(depth=1)]] 
     3[[TOC(sectionindex, heading=ARexx Function List, notitle, depth=1, Documentation/ARexxAPI/)]] 
     4= Reference - ARexx interface 
    55 
    66With the help of ARexx scripts, you can add new functions to YAM or let it do things automatically.\\ 
    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 
     7YAM offers a set of commands (listed in this documentation both [[#FixListByName|by name]] and [[#FixListByFunction|by function]]) which can be called through the '''YAM''' ARexx port.  They are explained along the following 
    88subchapters using the following format: 
    99 
     
    2727   Be careful when passing arguments containing spaces; for instance, 
    2828 
    29    {{{#!urbiscript 
     29   {{{#!arexx 
    3030   sub = 'Hello World' 
    3131   'WRITESUBJECT' sub 
     
    3434   won't work. It must be written as 
    3535 
    36    {{{#!urbiscript 
     36   {{{#!arexx 
    3737   'WRITESUBJECT "'sub'"' 
    3838   }}} 
     
    4040   or 
    4141 
    42    {{{#!urbiscript 
     42   {{{#!arexx 
    4343   'WRITESUBJECT "Hello World"' 
    4444   }}} 
     
    5050   `*N` substitutes to 0x0a (newline \n) \\ 
    5151   `*E` substitutes to 0x1b (escape)\\ 
    52    `!**` substitutes to *\\ 
    53    `*` substitutes to "\\ 
     52   `**` substitutes to *\\ 
     53   `*"` substitutes to "\\ 
    5454 
    5555   For example the following command would write a string to a texteditor containing a newline: 
    5656 
    57    {{{#!urbiscript 
     57   {{{#!arexx 
    5858    'WRITEEDITOR "TEXT Hello Joe,*N I would like to meet you."' 
    5959   }}} 
     
    6464   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: 
    6565 
    66    {{{#!urbiscript 
     66   {{{#!arexx 
    6767   FOLDERINFO 
    6868   -> RESULT = "0 Incoming incoming 10 2 4 23030 1" 
    6969   }}} 
    7070 
    71    {{{#!urbiscript 
     71   {{{#!arexx 
    7272   FOLDERINFO VAR fi 
    7373   -> fi = "0 Incoming incoming 10 2 4 23030 1" 
    7474   }}} 
    7575 
    76    {{{#!urbiscript 
     76   {{{#!arexx 
    7777   FOLDERINFO STEM fi. 
    7878   -> 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 
     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 
    8686   }}} 
    8787 
    8888   Another example which returns a result of type `/M`: 
    8989 
    90    {{{#!urbiscript 
     90   {{{#!arexx 
    9191   ADDRFIND STEM found. "Marcel Beck" NAMEONLY 
    92     -> found.alias.count = 2 
    93          found.alias.0 = "Mars" 
    94          found.alias.1 = "mbe" 
     92   -> found.alias.count = 2 
     93      found.alias.0 = "Mars" 
     94      found.alias.1 = "mbe" 
    9595    }}} 
     96 
     97   '''IMPORTANT NOTE:''' Always check the RC return code after the command execution before examining any further returned variables (e.g. as part of a STEM variable). Additional variables will only be set for successfully executed commands which return zero (0) in RC. A failed command execution (`RC != 0`) will leave these variables in an uninitialized state which could potentially lead to undesired results. 
    9698 
    9799 WARNING:: 
     
    110112     Links to other related commands. 
    111113 
    112 ---- 
    113  * [[ARexx API/List by Name|Alphabetical list of all ARexx commands]] 
    114  * [[ARexx API/List by Function|List of all the ARexx commands sorted by function]] 
     114[[=#FixListByFunction]] 
     115== Grouped Function List 
     116 
     117=== Commands supplied by MUI 
     118 [[ARexxAPI/HELP|HELP]] - Return a list of all the supported ARexx commands\\ 
     119 [[ARexxAPI/HIDE|HIDE]]  - Iconify YAM\\ 
     120 [[ARexxAPI/INFO| INFO]]  - Return information about the program\\ 
     121 [[ARexxAPI/QUIT| QUIT]]  - Terminate YAM\\ 
     122 [[ARexxAPI/SCREENTOBACK| SCREENTOBACK]]  - Bring the YAM screen to the background\\ 
     123 [[ARexxAPI/SCREENTOFRONT| SCREENTOFRONT]]  - Bring the YAM screen to the foreground\\ 
     124 [[ARexxAPI/SHOW| SHOW]]  - Uniconify YAM\\ 
     125 
     126=== Address book handling 
     127 [[ARexxAPI/ADDRDELETE| ADDRDELETE]]  - Remove an entry from the address book\\ 
     128 [[ARexxAPI/ADDREDIT|ADDREDIT]]  - Fill the fields of the current address book entry\\ 
     129 [[ARexxAPI/ADDRFIND|ADDRFIND]]  - Search the address book for one or more entries\\ 
     130 [[ARexxAPI/ADDRGOTO|ADDRGOTO]]  - Select an address book entry by alias\\ 
     131 [[ARexxAPI/ADDRINFO|ADDRINFO]]  - Return information about an entry referred by alias\\ 
     132 [[ARexxAPI/ADDRLOAD|ADDRLOAD]]  - Load an address book by filename\\ 
     133 [[ARexxAPI/ADDRNEW|ADDRNEW]]  - Create a new entry in the address book\\ 
     134 [[ARexxAPI/ADDRRESOLVE|ADDRRESOLVE]]  - Resolve an alias or name\\ 
     135 [[ARexxAPI/ADDRSAVE|ADDRSAVE]]  - Save the address book under a given filename\\ 
     136 
     137=== Folder wide operations 
     138 [[ARexxAPI/FLUSHINDEXES|FLUSHINDEXES]]  - Flush the index of all folders\\ 
     139 [[ARexxAPI/FOLDERINFO|FOLDERINFO]]  - Return information about a given folder\\ 
     140 [[ARexxAPI/GETFOLDERINFO|GETFOLDERINFO]]  - Return information about the current folder\\ 
     141 [[ARexxAPI/MAILFILTER|MAILFILTER]]  - Filter messages in the current folder\\ 
     142 [[ARexxAPI/MAILUPDATE|MAILUPDATE]]  - Update the index of the current folder\\ 
     143 [[ARexxAPI/NEWMAILFILE|NEWMAILFILE]]  - Return a free message slot for a given folder\\ 
     144 
     145=== GUI handling 
     146 [[ARexxAPI/APPBUSY|APPBUSY]]  - Switch YAM to busy mode\\ 
     147 [[ARexxAPI/APPNOBUSY|APPNOBUSY]]  - Bring YAM out of busy mode\\ 
     148 [[ARexxAPI/LISTFREEZE|LISTFREEZE]]  - Forbid graphical updates to a list\\ 
     149 [[ARexxAPI/LISTUNFREEZE|LISTUNFREEZE]]  - Permit graphical updates to a list\\ 
     150 [[ARexxAPI/READCLOSE|READCLOSE]]  - Close the active Read window\\ 
     151 [[ARexxAPI/RESTART|RESTART]]  - Restart YAM\\ 
     152 
     153=== Message/Folder selection 
     154 [[ARexxAPI/FINDMAIL|FINDMAIL]] - Find a mail in all folders given a MessageID\\ 
     155 [[ARexxAPI/GETSELECTED|GETSELECTED]]  - Get the position of the messages selected in the current folder\\ 
     156 [[ARexxAPI/LISTSELECT|LISTSELECT]]  - Select messages in the current folder\\ 
     157 [[ARexxAPI/SETFOLDER|SETFOLDER]]  - Select the current folder\\ 
     158 [[ARexxAPI/SETMAIL|SETMAIL]]  - Select the current message in the current folder by number\\ 
     159 [[ARexxAPI/SETMAILFILE|SETMAILFILE]]  - Select the current message in the current folder by filename\\ 
     160 
     161=== Message manipulation 
     162 [[ARexxAPI/GETMAILINFO|GETMAILINFO]]  - Return information about the active message\\ 
     163 [[ARexxAPI/MAILARCHIVE|MAILARCHIVE]]  - Move the selected messages to another folder\\ 
     164 [[ARexxAPI/MAILBOUNCE|MAILBOUNCE]]  - Bounce the current message\\ 
     165 [[ARexxAPI/MAILCHANGESUBJECT|MAILCHANGESUBJECT]]  - Change the subject of the selected message(s)\\ 
     166 [[ARexxAPI/MAILCOPY|MAILCOPY]]  - Duplicate the selected message(s)\\ 
     167 [[ARexxAPI/MAILDELETE|MAILDELETE]]  - Delete the selected message(s)\\ 
     168 [[ARexxAPI/MAILEDIT|MAILEDIT]]  - Edit the current message\\ 
     169 [[ARexxAPI/MAILEXPORT|MAILEXPORT]]  - Export the selected message(s) into a file\\ 
     170 [[ARexxAPI/MAILIMPORT|MAILIMPORT]]  - Import messages from a file into the current folder\\ 
     171 [[ARexxAPI/MAILINFO|MAILINFO]]  - Return information about a given message\\ 
     172 [[ARexxAPI/MAILMOVE|MAILMOVE]]  - Move the selected messages to another folder\\ 
     173 [[ARexxAPI/MAILREAD|MAILREAD]]  - Read the current message\\ 
     174 [[ARexxAPI/MAILREPLY|MAILREPLY]]  - Reply the currently selected messages\\ 
     175 [[ARexxAPI/MAILSTATUS|MAILSTATUS]]  - Change the status of the selected message(s)\\ 
     176 [[ARexxAPI/READINFO|READINFO]]  - Get info about the attachments in the message being read\\ 
     177 [[ARexxAPI/READPRINT|READPRINT]]  - Print an attachment\\ 
     178 [[ARexxAPI/READSAVE|READSAVE]]  - Save an attachment\\ 
     179 [[ARexxAPI/SETFLAG|SETFLAG]]  - Set the PERmanent or VOLatile flag of a message\\ 
     180 
     181=== Network related 
     182 [[ARexxAPI/GETURL|GETURL]]  - Download a file from the WWW based on a given URL\\ 
     183 [[ARexxAPI/ISONLINE|ISONLINE]]  - Detect whether YAM is currently transfering email\\ 
     184 [[ARexxAPI/MAILCHECK|MAILCHECK]]  - Download new email\\ 
     185 [[ARexxAPI/MAILSEND|MAILSEND]]  - Send the messages in the '''Outgoing''' folder\\ 
     186 [[ARexxAPI/MAILSENDALL|MAILSENDALL]]  - Send all the messages in the '''Outgoing''' folder\\ 
     187 
     188=== Request info from user 
     189 [[ARexxAPI/GETCONFIGINFO|GETCONFIGINFO]]  - Return information about the current user\\ 
     190 [[ARexxAPI/REQUEST|REQUEST]]  - Request a choice from the user\\ 
     191 [[ARexxAPI/REQUESTFILE|REQUESTFILE]]  - Request the user to select a file\\ 
     192 [[ARexxAPI/REQUESTFOLDER|REQUESTFOLDER]]  - Request the user to select a folder\\ 
     193 [[ARexxAPI/REQUESTSTRING|REQUESTSTRING]]  - Request the user for a string\\ 
     194 [[ARexxAPI/USERINFO|USERINFO]]  - Return information about the current user\\ 
     195 
     196=== Writing new email 
     197 [[ARexxAPI/MAILFORWARD| MAILFORWARD]]  - Forward the selected messages\\ 
     198 [[ARexxAPI/MAILWRITE|MAILWRITE]]  - Open a new Write window to compose a new mail\\ 
     199 [[ARexxAPI/WRITEATTACH|WRITEATTACH]]  - Attach a file to a new message\\ 
     200 [[ARexxAPI/WRITEBCC|WRITEBCC]]  - Fill the BCC: header of a new message\\ 
     201 [[ARexxAPI/WRITECC|WRITECC]]  - Fill the CC: header of a new message\\ 
     202 [[ARexxAPI/WRITEEDITOR|WRITEEDITOR]]  - Pass an ARexx command to the internal editor\\ 
     203 [[ARexxAPI/WRITEFROM|WRITEFROM]]  - Fill the FROM: header of a new message\\ 
     204 [[ARexxAPI/WRITEIDENTITY|WRITEIDENTITY]] - Choose the user identity to be used when composing a new mail\\ 
     205 [[ARexxAPI/WRITELETTER|WRITELETTER]]  - Load a file into the internal text editor\\ 
     206 [[ARexxAPI/WRITEMAILTO|WRITEMAILTO]]  - Fill the TO: header of a new message\\ 
     207 [[ARexxAPI/WRITEOPTIONS|WRITEOPTIONS]]  - Set the options of a new message\\ 
     208 [[ARexxAPI/WRITEQUEUE|WRITEQUEUE]]  - Move a new message to the '''Outgoing''' queue\\ 
     209 [[ARexxAPI/WRITEREPLYTO|WRITEREPLYTO]]  - Fill the REPLY-TO: header of a new message\\ 
     210 [[ARexxAPI/WRITESEND|WRITESEND]]  - Send a new message\\ 
     211 [[ARexxAPI/WRITESUBJECT|WRITESUBJECT]]  - Fill the SUBJECT: header of a new message\\ 
     212 [[ARexxAPI/WRITETO|WRITETO]]  - Fill the TO: header of a new message\\ 
     213 
     214[[=#FixListByName]] 
     215== Alphabetical Function List 
     216 [[ARexxAPI/ADDRDELETE|ADDRDELETE]]  - Remove an entry from the address book\\ 
     217 [[ARexxAPI/ADDREDIT|ADDREDIT]]  - Fill the fields of the current address book entry\\ 
     218 [[ARexxAPI/ADDRFIND|ADDRFIND]]  - Search the address book for one or more entries\\ 
     219 [[ARexxAPI/ADDRGOTO|ADDRGOTO]]  - Select an address book entry by alias\\ 
     220 [[ARexxAPI/ADDRINFO|ADDRINFO]]  - Return information about an entry referred by alias\\ 
     221 [[ARexxAPI/ADDRLOAD|ADDRLOAD]]  - Load an address book by filename\\ 
     222 [[ARexxAPI/ADDRNEW|ADDRNEW]]  - Create a new entry in the address book\\ 
     223 [[ARexxAPI/ADDRRESOLVE|ADDRRESOLVE]]  - Resolve an alias or name\\ 
     224 [[ARexxAPI/ADDRSAVE|ADDRSAVE]]  - Save the address book under a given filename\\ 
     225 [[ARexxAPI/APPBUSY|APPBUSY]]  - Switch YAM to busy mode\\ 
     226 [[ARexxAPI/APPNOBUSY|APPNOBUSY]]  - Bring YAM out of busy mode\\ 
     227 [[ARexxAPI/FINDMAIL|FINDMAIL]] -  Find a mail in all folders given a MessageID\\ 
     228 [[ARexxAPI/FLUSHINDEXES|FLUSHINDEXES]]  - Flush the index of all folders\\ 
     229 [[ARexxAPI/FOLDERINFO|FOLDERINFO]]  - Return information about a given folder\\ 
     230 [[ARexxAPI/GETCONFIGINFO|GETCONFIGINFO]]  - Return information about the current user\\ 
     231 [[ARexxAPI/GETFOLDERINFO|GETFOLDERINFO]]  - Return information about the current folder\\ 
     232 [[ARexxAPI/GETMAILINFO|GETMAILINFO]]  - Return information about the active message\\ 
     233 [[ARexxAPI/GETSELECTED|GETSELECTED]]  - Get the position of the messages selected in the current folder\\ 
     234 [[ARexxAPI/GETURL|GETURL]]  - Download a file from the WWW based on a given URL\\ 
     235 [[ARexxAPI/HELP|HELP]]  - Return a list of all the supported ARexx commands\\ 
     236 [[ARexxAPI/HIDE|HIDE]]  - Iconify YAM\\ 
     237 [[ARexxAPI/INFO|INFO]]  - Return information about the program\\ 
     238 [[ARexxAPI/ISONLINE|ISONLINE]]  - Detect whether YAM is currently transfering email\\ 
     239 [[ARexxAPI/LISTFREEZE|LISTFREEZE]]  - Forbid graphical updates to a list\\ 
     240 [[ARexxAPI/LISTSELECT|LISTSELECT]]  - Select messages in the current folder\\ 
     241 [[ARexxAPI/LISTUNFREEZE|LISTUNFREEZE]]  - Permit graphical updates to a list\\ 
     242 [[ARexxAPI/MAILARCHIVE|MAILARCHIVE]]  - Move the selected messages to another folder\\ 
     243 [[ARexxAPI/MAILBOUNCE|MAILBOUNCE]]  - Bounce the current message\\ 
     244 [[ARexxAPI/MAILCHANGESUBJECT|MAILCHANGESUBJECT]]  - Change the subject of the selected message(s)\\ 
     245 [[ARexxAPI/MAILCHECK|MAILCHECK]]  - Download new email\\ 
     246 [[ARexxAPI/MAILCOPY|MAILCOPY]]  - Duplicate the selected message(s)\\ 
     247 [[ARexxAPI/MAILDELETE|MAILDELETE]]  - Delete the selected message(s)\\ 
     248 [[ARexxAPI/MAILEDIT|MAILEDIT]]  - Edit the current message\\ 
     249 [[ARexxAPI/MAILEXPORT|MAILEXPORT]]  - Export the selected message(s) into a file\\ 
     250 [[ARexxAPI/MAILFILTER|MAILFILTER]]  - Filter messages in the current folder\\ 
     251 [[ARexxAPI/MAILFORWARD|MAILFORWARD]]  - Forward the selected messages\\ 
     252 [[ARexxAPI/MAILIMPORT|MAILIMPORT]]  - Import messages from a file into the current folder\\ 
     253 [[ARexxAPI/MAILINFO|MAILINFO]]  - Return information about a given message\\ 
     254 [[ARexxAPI/MAILMOVE|MAILMOVE]]  - Move the selected messages to another folder\\ 
     255 [[ARexxAPI/MAILREAD|MAILREAD]]  - Read the current message\\ 
     256 [[ARexxAPI/MAILREPLY|MAILREPLY]]  - Reply the currently selected messages\\ 
     257 [[ARexxAPI/MAILSEND|MAILSEND]]  - Send the messages in the '''Outgoing''' folder\\ 
     258 [[ARexxAPI/MAILSENDALL|MAILSENDALL]]  - Send all the messages in the '''Outgoing''' folder\\ 
     259 [[ARexxAPI/MAILSTATUS|MAILSTATUS]]  - Change the status of the selected message(s)\\ 
     260 [[ARexxAPI/MAILUPDATE|MAILUPDATE]]  - Update the index of the current folder\\ 
     261 [[ARexxAPI/MAILWRITE|MAILWRITE]]  - Open a new Write window to compose a new mail\\ 
     262 [[ARexxAPI/NEWMAILFILE|NEWMAILFILE]]  - Return a free message slot for a given folder\\ 
     263 [[ARexxAPI/QUIT|QUIT]]  - Terminate YAM\\ 
     264 [[ARexxAPI/READCLOSE|READCLOSE]]  - Close the active Read window\\ 
     265 [[ARexxAPI/READINFO|READINFO]] - Get info about the attachments in the message being read\\ 
     266 [[ARexxAPI/READPRINT|READPRINT]]  - Print an attachment\\ 
     267 [[ARexxAPI/READSAVE|READSAVE]]  - Save an attachment\\ 
     268 [[ARexxAPI/REQUEST|REQUEST]]  - Request a choice from the user\\ 
     269 [[ARexxAPI/REQUESTFILE|REQUESTFILE]]  - Request the user to select a file\\ 
     270 [[ARexxAPI/REQUESTFOLDER|REQUESTFOLDER]]  - Request the user to select a folder\\ 
     271 [[ARexxAPI/REQUESTSTRING|REQUESTSTRING]]  - Request the user for a string\\ 
     272 [[ARexxAPI/RESTART|RESTART]]  - Restart YAM\\ 
     273 [[ARexxAPI/SCREENTOBACK|SCREENTOBACK]]  - Bring the YAM screen to the background\\ 
     274 [[ARexxAPI/SCREENTOFRONT|SCREENTOFRONT]]  - Bring the YAM screen to the foreground\\ 
     275 [[ARexxAPI/SETFLAG|SETFLAG]]  - Set the PERmanent or VOLatile flag of a message\\ 
     276 [[ARexxAPI/SETFOLDER|SETFOLDER]]  - Select the current folder\\ 
     277 [[ARexxAPI/SETMAIL|SETMAIL]]  - Select the current message in the current folder by number\\ 
     278 [[ARexxAPI/SETMAILFILE|SETMAILFILE]]  - Select the current message in the current folder by filename\\ 
     279 [[ARexxAPI/SHOW|SHOW]]  - Uniconify YAM\\ 
     280 [[ARexxAPI/USERINFO|USERINFO]]  - Return information about the current user\\ 
     281 [[ARexxAPI/WRITEATTACH|WRITEATTACH]]  - Attach a file to a new message\\ 
     282 [[ARexxAPI/WRITEBCC|WRITEBCC]]  - Fill the BCC: header of a new message\\ 
     283 [[ARexxAPI/WRITECC|WRITECC]]  - Fill the CC: header of a new message\\ 
     284 [[ARexxAPI/WRITEEDITOR|WRITEEDITOR]]  - Pass an ARexx command to the internal editor\\ 
     285 [[ARexxAPI/WRITEFROM|WRITEFROM]]  - Fill the FROM: header of a new message\\ 
     286 [[ARexxAPI/WRITEIDENTITY|WRITEIDENTITY]] - Choose the user identity to be used when composing a new mail \\ 
     287 [[ARexxAPI/WRITELETTER|WRITELETTER]]  - Load a file into the internal text editor\\ 
     288 [[ARexxAPI/WRITEMAILTO|WRITEMAILTO]] - Fill the TO: header of a new message\\ 
     289 [[ARexxAPI/WRITEOPTIONS|WRITEOPTIONS]]  - Set the options of a new message\\ 
     290 [[ARexxAPI/WRITEQUEUE|WRITEQUEUE]]  - Move a new message to the '''Outgoing''' queue\\ 
     291 [[ARexxAPI/WRITEREPLYTO|WRITEREPLYTO]]  - Fill the REPLY-TO: header of a new message\\ 
     292 [[ARexxAPI/WRITESEND|WRITESEND]]  - Send a new message\\ 
     293 [[ARexxAPI/WRITESUBJECT|WRITESUBJECT]]  - Fill the SUBJECT: header of a new message\\ 
     294 [[ARexxAPI/WRITETO|WRITETO]]  - Fill the TO: header of a new message\\