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