home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 28 / amigaformatcd28.iso / -seriously_amiga- / comms / other / aemail151 / files.lha / ARexx.lha / AEMail-ARexx.doc < prev    next >
Text File  |  1998-03-09  |  67KB  |  1,724 lines
  1.                           AEMAIL AREXX INTERFACE
  2.                           ======================
  3.  
  4.                                Introduction
  5.                                ------------
  6.  
  7. AEMail has a very powerful set of ARexx commands that can be used to
  8. control AEMail from external ARexx scripts.  You can also execute ARexx
  9. scripts and AmigaDOS scripts from within AEMail with the use of the "Send
  10. AREXX/DOS Command" and the "Send Last Command" items in the Project Menu
  11. (see VII.  AEMAIL MENUS).
  12.  
  13. When you want to send commands from an ARexx script to AEMail, you must
  14. tell ARexx how to locate the AEMail ARexx message port.  The AEMail ARexx
  15. Port Name is normally "AEMAIL1".  You can change this port name with the
  16. use of the "AREXXPORT=" tool type (See TOOL TYPES under Section IV.
  17. CONFIGURATION).  The current Arexx Port Name is shown in the About message
  18. obtained with the "About" item under the Project Menu.
  19.  
  20. You tell ARexx what the message port name for AEMail is by using the ARexx
  21. ADDRESS commmand in an ARexx script like this:
  22.  
  23.     ADDRESS AEMAIL1
  24.  
  25. If you call an ARexx script from AEMail, the ADDRESS command is
  26. automatically set to the AEMail ARexx message port.
  27.  
  28. After each command directed at AEMail from an ARexx script is executed,
  29. the standard ARexx result variable, RC, will report the success or failure
  30. of the command.  A 0 in RC indicates that the command was understood and
  31. executed successfully.  An RC value other than 0 indicates an error
  32. severity indicator.  The exact error text is reported in the Arexx
  33. AEMAIL.LASTERROR variable.
  34.  
  35. All of the AEMail ARexx commands also report back information if they
  36. were executed successfully (RC = 0).  This information is reported in the
  37. ARexx variable RESULT.  To receive this information you must supply the
  38. following ARexx command at the beginning of the ARexx script:
  39.  
  40.     OPTIONS RESULTS
  41.  
  42. You will notice that some commands have possible negative numbers for
  43. RESULT values.  The RESULT variable usually returns either a numeric value
  44. or a string.  If a numeric value is returned and if it is positive and
  45. above zero, the expected result was achieved.  If the value was 0 or
  46. negative, the expected result was not achieved.  Some commands that
  47. normally return strings in the RESULT variable may also return a NULL
  48. string or a negative numeric value.  The negative numeric value is used to
  49. denote various reasons the string value was not returned.  If there is
  50. only one reason, the command will normally return a "0" or a NULL value;
  51. but if there is more than one reason, the additional reasons will be
  52. indicated with a negative number.  An example would be a command that is
  53. expected to return the Subject:  from the current message.  A result of
  54. NULL or blank indicates that there was no Subject:  header and a result of
  55. "-1" indicates that there is no current message.  These two conditions
  56. need to be distinguished.
  57.  
  58. Below is a both a list of the currently available AEMail ARexx commands
  59. and a section which describes each command in detail.  Many of the
  60. commands are available to registered users only.  These will be so noted
  61. in the command list.
  62.  
  63. Some of the commands are composed of multiple words.  To avoid confusion
  64. these multiple words are sometimes separated by an underline character
  65. ("_").  As an example "ADDRESS_BOOK" separates ADDRESS and BOOK with the
  66. underline.  This is to avoid confusion with "ADDRESS" which is a standard
  67. ARexx command.  If an underline is required, it will be shown in the
  68. command syntax.
  69.  
  70. QUOTING:  Some command have parameters with embedded ARexx command
  71. characters such as +, -, |, etc.  To avoid the possibilty of ARexx
  72. interpreting these as ARexx operations, the parameter should be surrounded
  73. by quotes (either single or double quotes).  An example of where this is
  74. very important is the first parameter of the OKAY2 command.  Each of the
  75. possible responses in the OKAY2 command is separated by a vertical bar
  76. ("|") such as "OK|CANCEL".  The entire response parameter needs to be
  77. surrounded in quotes as shown or otherwise the vertical bar will be
  78. intrepreted by ARexx as an "inclusive or" operation.
  79.  
  80. Another condition requiring quoting is passing strings with embedded
  81. spaces.  This usually requires a bit of "creative" quoting because ARexx
  82. always strips at least one set of quotation marks from all strings.
  83. Fortunately ARexx considers both the double quote (") and the single quote
  84. (') as quotes.  To provide for the proper treatment of strings with
  85. embedded spaces (such as some file and path names or title strings), you
  86. have to use a double grouping of quotes.
  87.  
  88. For example:
  89.  
  90.     GETFILENAME '"The Title String"' '"A file name path"'
  91.  
  92. will send "The Title String" and "A file name path" to AEMail which will
  93. recognize these strings as two quoted operands.
  94.  
  95. ARexx variables which might have embedded spaces in their contents must
  96. also be quoted as above.  You can do this as follows:
  97.  
  98.     filename = "A file name path"
  99.     title = "The Title String"
  100.     GETFILENAME '"'title'"' '"'filename'"'
  101.  
  102. This ensures that ARexx, when it strips off a set of quotation marks and
  103. replaces the variables with their contents, will also pass a set of
  104. quotation marks around the resulting strings.  AEMail will then recognize
  105. the passed strings as two string operands rather than many unconnected
  106. words.
  107.                         Synopsis of ARexx Commands
  108.                         --------------------------
  109.  
  110. The following is a list of the currently available AEMail ARexx commands.
  111. This list also indicates which commands are only available to registered
  112. users with an (R) following the command.
  113.  
  114. A complete description of all of the commands and the command variations
  115. follows this list.
  116.  
  117. ADDRESS_BOOK (R)    Manipulates the AEMail Address Book
  118. BCC (R)             Returns the BCC header in a message
  119. CC (R)              Returns the CC header in a message
  120. COMPOSE             Composes a message
  121. CURRENT IS SELECTED Makes the selected message current
  122. DATE (R)            Returns the DATE header in a message
  123. EXTRACT (R)         Parses a name string to real name or email address
  124. FIRST (R)           Selects first message in folder or name in name string
  125. FLAGS (R)           Returns the flags in a message
  126. FOLDER (R)          Returns information on folders
  127. FROM (R)            Returns the FROM header in a message
  128. GETCLIP (R)         Get a clip from the clipboard
  129. GETFILENAME         Brings up the AEMail file requester
  130. GETNUMBER           Brings up the AEMail numeric requester
  131. GETSIZE (R)         Returns the size of a message or message body
  132. GETSTRING           Brings up the AEMail string requester
  133. LAST (R)            Selects last message in a folder
  134. MESSAGE (R)         Sets various flags in a message
  135. NEXT (R)            Selects next message in folder or name in name string
  136. OKAY1               Brings up AEMail notification requester
  137. OKAY2               Brings up AEMail notification requester with responses
  138. PREVIOUS (R)        Selects the previous message in a folder
  139. QUEUE               Queues a passed message
  140. REPLYTO (R)         Returns the REPLY-TO header in a message
  141. SAVE (R)            Saves a message or message text
  142. SCREENTOBACK        Brings a screen to the back of the display
  143. SCREENTOFRONT       Brings a screen to the front of the display
  144. SUBJECT (R)         Returns the SUBJECT header in a message
  145. TO (R)              Returns the TO header in a message
  146.  
  147.  
  148.                               ARexx Commands
  149.                               --------------
  150.  
  151. The following is a description of all of the currently available AEMail
  152. ARexx commands in alphabetical order.  Shown with each of the commands is
  153. what you can expect to have returned in the RESULT variable.  Please note
  154. the use of the OKAY1 and OKAY2 commands.  You can use these to report back
  155. information to the AEMail user.  These commands put up a requester with
  156. the information you provide.
  157.  
  158. You will also notice in the command descriptions the use of the term
  159. "current message".  This applies to ARexx commands only and is not the
  160. "selected message" that is indicated by an asterick (*) in the displayed
  161. message list; although, you can make the most recent (current) "selected
  162. message" the "current message" (see the CURRENT IS SELECTED command below)
  163. and you can "select" a current message (the MESSAGE SELECT command).
  164. Initially "current message" is un-defined, but once it is defined it will
  165. remain defined through multiple calls from ARexx scripts until AEMail
  166. terminates or the "current message" is changed through the use of another
  167. ARexx command.
  168.  
  169.  
  170.  
  171.                                ADDRESS_BOOK
  172.  
  173. This command is used to manipulate the AEMail Address Book.  There are a
  174. number of variations of the ADDRESS_BOOK command.  They are listed below.
  175. If the correct command keyword ("LIST", "FIND", "ADD", etc.) is not
  176. present, an RC code of severity level 5 will be returned and
  177. AEMAIL.LASTERROR will contain "101:  Syntax Error".
  178.  
  179. Note the use of the parameter called "userid".  This can be either an
  180. email address or a referenced nickname pointing to another individual or
  181. group entry.  When a userid is returned, you can test if it is a nickname
  182. by using the ADDRESS_BOOK GET nickname TYPE command.
  183.  
  184. ***
  185.  
  186. Syntax: ADDRESS_BOOK LIST ALL [pad]
  187.         ADDRESS_BOOK LIST GROUP [pad]
  188.         ADDRESS_BOOK LIST INDIVIDUAL [pad]
  189.  
  190. This command will list the nicknames in your address book.  The operand
  191. "ALL" will list all of the nicknames, the operand "GROUP" will list just
  192. the group nicknames, and "INDIVIDUAL" will list just the individual
  193. nicknames.
  194.  
  195. Normally each nickname is separated by a space.  However, this can be
  196. changed by a specifying a pad string at the end of the command.  You can
  197. use the LF keyword to specify a line feed or use some other character
  198. sequence for the pad string.  As an example:  ", " will insert a comma
  199. followed by a space between each nickname in the list.
  200.  
  201. RESULT: The list of nicknames separated by the pad character.
  202.  
  203. ***
  204.  
  205. Syntax: ADDRESS_BOOK FIND nickname [userid]
  206.  
  207. This command is used to find out if a particular userid (email address or
  208. referenced nickname) is contained in a group entry in the Address Book.
  209. You can explicity give the userid or the email address can be obtained
  210. from the current message.  If the userid is not specified, both the From:
  211. and Reply-To:  addresses from the current message will be used to check if
  212. the email address is in the group entry specified by nickname.  The
  213. nickname operand is required and must be a group nickname.
  214.  
  215. RESULT: -3          No current message if userid not given
  216.         -2          The nickname is not for a group entry in the Address
  217.                     Book
  218.         -1          The nickname given is not in the Address Book.
  219.         0           The userid was not found
  220.         1           The userid found.  If not supplied, the userid that
  221.                     was found was an email address from the From: address
  222.                     in the current message.
  223.         2           The Reply-To: address in the current message was found
  224.                     in the group.
  225.         3           Both the Reply-To: and From: addresses were found.
  226.                     Note: these addresses may actually be the same.
  227.  
  228. ***
  229.  
  230. Syntax: ADDRESS_BOOK CREATE GROUP nickname ["SEND-HEADER-ONLY"|SHO],
  231.             FROM|REPLYTO|userid description
  232.  
  233. This entry creates a new group entry in the Address Book.  When you create
  234. a group entry you must have one userid (email address or referenced
  235. nickname) entry to place in the group.  You are not allowed to have a
  236. group without any entries.
  237.  
  238. The nickname for the new group must be supplied and it must not be greater
  239. than 9 characters.  It can not, of course, match any existing nickname.
  240.  
  241. "SEND-HEADER-ONLY" is an optional keyword operand which sets the "Send
  242. Header Only" flag in the group entry and must be quoted.  You can use the
  243. shorthand abreviation "SHO" instead of the full "SEND-HEADER-ONLY" string.
  244.  
  245. The userid which is added can be explicity specified or it can be the
  246. email address taken from either the From:  or Reply-To:  address in the
  247. current message.  Use the keyword operands "FROM" or "REPLYTO" to specify
  248. which header field in the current message is to be used.  If you specify
  249. "REPLYTO" and that header is missing, an error condition will be returned
  250. (see below).
  251.  
  252. There is no validation performed on the user_id.  If it is an email
  253. address it should be one word without any intervening spaces.  It should
  254. be within a quoted string to avoid confusion with ARexx special symbols.
  255. If it is a nickname with embedded spaces it must be double quoted (two
  256. pairs of quote marks - ie, '"........"'.
  257.  
  258. The description operand is placed in the "Real Name" field in the Address
  259. Book entry and must be given.  It may have embedded spaces and should be
  260. quoted.  If you want quotes to appear in the group description you should
  261. use the ARexx method for including embedded quotes (i.e.,
  262. '"....string...."' or '"'variable'"'.
  263.  
  264.  
  265. RESULT: -4          The REPLYTO operand was specified and there is no
  266.                     Reply-To: header in the current message.
  267.         -3          No current message if userid not given
  268.         -1          The nickname given is greater than 9 characters.
  269.         0           The nickname given was already defined in the Address
  270.                     Book.
  271.         1           The group entry was successfully created.
  272.  
  273. ***
  274.  
  275. Syntax: ADDRESS_BOOK ADD TO GROUP nickname FROM
  276.         ADDRESS_BOOK ADD TO GROUP nickname REPLYTO
  277.         ADDRESS_BOOK ADD TO GROUP nickname userid
  278.  
  279. This command adds an userid (email address or referenced nickname) to an
  280. existing group in the Address Book.  The nickname operand specifies the
  281. group the userid is to be added to and is a required parameter.
  282.  
  283. The userid which is added can be explicity specified or it can be the
  284. email address taken from either the From:  or Reply-To:  address in the
  285. current message.  Use the keyword operands "FROM" or "REPLYTO" to specify
  286. which header field in the current message is to be used.  If you specify
  287. "REPLYTO" and that header is missing, an error condition will be returned
  288. (see below).
  289.  
  290. There is no validation performed on the user_id.  If it is an email
  291. address it should be one word without any intervening spaces.  It should
  292. be within a quoted string to avoid confusion with ARexx special symbols.
  293. If it is a nickname with embedded spaces it must be double quoted (two
  294. pairs of quote marks - ie, '"........"'.
  295.  
  296.  
  297. RESULT: -4          The REPLYTO operand was specified and there is no
  298.                     Reply-To: header in the current message.
  299.         -3          No current message if userid not specified.
  300.         -2          The nickname is not for a group entry in the Address
  301.                     Book
  302.         -1          The nickname given was not found.
  303.         0           The userid given was already defined in the group.
  304.         1           The userid was successfully added to the group.
  305.  
  306.  
  307. ***
  308.  
  309. Syntax: ADDRESS_BOOK ADD INDIVIDUAL nickname FROM [real-name]
  310.         ADDRESS_BOOK ADD INDIVIDUAL nickname REPLYTO [real-name]
  311.         ADDRESS_BOOK ADD INDIVIDUAL nickname userid [real-name]
  312.  
  313. This command adds a new individual nickname to the Address Book.  The
  314. nickname for the new group must be supplied and it must not be greater
  315. than 9 characters.  It can not, of course, match any existing nickname.
  316.  
  317. The userid which is assign to the new nickname is required and can be
  318. explicity specified or it can be the email address taken from either the
  319. From:  or Reply-To:  header in the current message.  Use the keyword
  320. operands "FROM" or "REPLYTO" to specify which header field in the current
  321. message is to be used.  If you specify "REPLYTO" and that header is
  322. missing, an error condition will be returned (see below).
  323.  
  324. There is no validation performed on the user_id.  If it is an email
  325. address it should be one word without any intervening spaces.  It should
  326. be within a quoted string to avoid confusion with ARexx special symbols.
  327. If it is a nickname with embedded spaces it must be double quoted (two
  328. pairs of quote marks - ie, '"........"'.
  329.  
  330. The real-name operand is placed in the "Real Name" field in the Address
  331. Book entry.  It is an optional entry.  It may have intervening spaces.  It
  332. should be quoted.  If you want quotes to appear in the group description
  333. you should use the ARexx method for including embedded quotes (i.e.,
  334. '"....string...."' or '"'variable'"'.
  335.  
  336. If a current message is used to obtain the userid (either the "FROM" or
  337. "REPLYTO" keyword operands) any real name supplied with the header will
  338. take precedence over the real-name operand if it is present.
  339.  
  340. RESULT: -4          The REPLYTO operand was specified and there is no
  341.                     Reply-To: header in the current message.
  342.         -3          No current message if userid not specified.
  343.         -1          The nickname given is greater than 9 characters.
  344.         0           The nickname given was already defined.
  345.         1           The nickname and userid was successfully added to the
  346.                     Address Book.
  347.  
  348. ***
  349.  
  350. Syntax: ADDRESS_BOOK DELETE FROM GROUP nickname FROM
  351.         ADDRESS_BOOK DELETE FROM GROUP nickname REPLYTO
  352.         ADDRESS_BOOK DELETE FROM GROUP nickname userid
  353.  
  354. This command deletes a userid from the group indicated by nickname.
  355.  
  356. The userid which is to be deleted is required and can be explicity
  357. specified or it can be the email address taken from either the From:  or
  358. Reply-To:  address in the current message.  Use the keyword operands
  359. "FROM" or "REPLYTO" to specify which header field in the current message
  360. is to be used.  If you specify "REPLYTO" and that header is missing, an
  361. error condition will be returned (see below).
  362.  
  363. There is no validation performed on the user_id.  If it is an email
  364. address it should be one word without any intervening spaces.  It should
  365. be within a quoted string to avoid confusion with ARexx special symbols.
  366. If it is a nickname with embedded spaces it must be double quoted (two
  367. pairs of quote marks - ie, '"........"'.
  368.  
  369. If the userid is the only userid in the group, it will not be deleted.
  370. No group can exist without at lease one userid.  In this special case a
  371. RESULT code of -5 will be returned.  To delete the one remaining userid
  372. you must delete the entire group (see "ADDRESS-BOOK DELETE GROUP" below.
  373.  
  374. RESULT: -5          The userid specified was the only userid in the
  375.                     group and WAS NOT DELETED.  Use the "ADDRESS_BOOK
  376.                     DELETE GROUP" command to delete entire group.
  377.         -4          The REPLYTO operand was specified and there is no
  378.                     Reply-To: header in the current message.
  379.         -3          No current message if userid not specified.
  380.         -2          The nickname is not for a group entry in the Address
  381.                     Book
  382.         -1          The nickname given was not found.
  383.         0           The userid was not present in the group.
  384.         1           The userid was deleted from the group.
  385.  
  386. ***
  387.  
  388. Syntax: ADDRESS_BOOK DELETE GROUP nickname
  389.  
  390. This command deletes the entire group specified by nickname and all of
  391. it's associated userids.
  392.  
  393. RESULT: -2          The nickname given is not for a group entry in the
  394.                     Address Book
  395.         -1          The nickname given was not found.
  396.  
  397.         1           The group was successfully deleted.
  398.  
  399. ***
  400.  
  401. Syntax: ADDRESS_BOOK DELETE INDIVIDUAL nickname
  402.  
  403. This command deletes the nickname provided.  It must be the nickname for
  404. an individual.
  405.  
  406. RESULT: -2          The nickname given is for a group entry in the
  407.                     Address Book.  No deletion was performed.
  408.         0           The individual's nickname was not present.
  409.         1           The individual's nickname was successfully deleted.
  410.  
  411. ***
  412.  
  413. Syntax: ADDRESS_BOOK GET nickname TYPE
  414.  
  415. This command obtains the type, group or individual, for the Address Book
  416. entry specified by "nickname".
  417.  
  418. RESULT: -1          The nickname given does not exist.
  419.          0          Nickname was for an individual entry.
  420.          1          Nickname was for a group entry.
  421.  
  422. ***
  423.  
  424. Syntax: ADDRESS_BOOK GET nickname REALNAME
  425.  
  426. This command obtains the "Real Name" or Group Description for the Address
  427. Book entry specified by "nickname".
  428.  
  429. RESULT: -1              The nickname given does not exist.
  430.          NULL or blank  No real name was present.
  431.          "Real Name" or group description string
  432.  
  433. ***
  434.  
  435. Syntax: ADDRESS_BOOK GET nickname USERID
  436.  
  437. This command obtains the userid for the Address Book entry specified by
  438. "nickname".  This command can only be used with Individual nicknames.
  439.  
  440. RESULT: -2          The nickname given is not for an individual entry.
  441.         -1          The nickname given does not exist.
  442.          "userid"  This may be either an email address or a referenced
  443.                     nickname.  Use the ADDRESS_BOOK GET nickname TYPE
  444.                     command to determine if it is a nickname rather than
  445.                     an email address.
  446.  
  447. ***
  448.  
  449. Syntax: ADDRESS_BOOK GET nickname "SEND-HEADER-ONLY-FLAG"|"SHO-FLAG"
  450.  
  451. This command obtains the state of the "Send Header Only" flag for the
  452. group entry specified by "nickname".  The operand can be specified as
  453. either "SEND-HEADER-ONLY-FLAG" or "SHO-FLAG" and must be quoted.  This
  454. command can only be used with Group nicknames.
  455.  
  456. RESULT: -2          The nickname given was not for a group entry.
  457.         -1          The nickname given does not exist.
  458.          0          The "Send Header Only" Flag was OFF.
  459.          1          The "Send Header Only" Flag was ON.
  460.  
  461. ***
  462.  
  463. Syntax: ADDRESS_BOOK GET nickname COUNT
  464.  
  465. This command obtains the count of userid entries in the group entry
  466. specified by "nickname".  This command is can only be used with Group
  467. nicknames.
  468.  
  469. RESULT: -2          The nickname given was not for a group entry.
  470.         -1          The nickname given does not exist.
  471.  
  472.          n          The count of userids in the group entry.
  473.  
  474.  
  475.                                    BCC
  476.  
  477. Syntax: BCC
  478.  
  479. This command returns the bcc:  header of the current message without the
  480. bcc:.  It has no operands.
  481.  
  482. RESULT: -1              No current message
  483.         NULL or blanks  No bcc: header
  484.         bcc: header
  485.  
  486.  
  487.                                     CC
  488.  
  489.  
  490. Syntax: CC
  491.  
  492. This command returns the cc:  header of the current message without the
  493. cc:.  It has no operands.
  494.  
  495. RESULT: -1              No current message
  496.         NULL or blanks  No cc: header
  497.         cc: header
  498.  
  499.  
  500.                                  COMPOSE
  501.  
  502. All of the variations of the COMPOSE command bring up the AEMail compose
  503. window for further action.  If for any reason the Compose window returns
  504. any error such as the failure to open the Compose window or an out of
  505. memory condition, the error will be returned in AEMAIL.LASTERROR with the
  506. RC set to a severity level of 20.  This error will not have an error
  507. number associated with it.
  508.  
  509. The syntax of the various variations of the COMPOSE command are as
  510. follows:
  511.  
  512. ***
  513.  
  514. Syntax: COMPOSE
  515.  
  516. The COMPOSE command without any operands brings up the Compose window to
  517. compose a new message.
  518.  
  519. RESULT: 0:          User canceled message compose.  No message composed.
  520.         1:          Message composed and placed in PENDING folder.
  521.         2:          Message composed and placed in QUEUED folder.
  522.         3:          Message composed and sent.
  523.  
  524. ***
  525.  
  526. Syntax: COMPOSE NEW MESSAGE
  527.  
  528. The Compose window will be brought up to compose a new message.
  529.  
  530. RESULT: 0:          User canceled message compose.  No message composed.
  531.         1:          Message composed and placed in PENDING folder.
  532.         2:          Message composed and placed in QUEUED folder.
  533.         3:          Message composed and sent.
  534.  
  535. ***
  536.  
  537. Syntax: COMPOSE REPLY
  538.  
  539. The Compose window will be brought up to compose a reply to the current
  540. message using the Reply-To: address as the recipient.  If the Reply-To:
  541. address is not available, the From:  address will be used.
  542.  
  543. RESULT: -1:         There is no current message defined.
  544.          0:         The user cancelled the operation.  No message was
  545.                     composed.
  546.          1:         Message composed and placed in PENDING folder.
  547.          2:         Message composed and placed in QUEUED folder.
  548.          3:         Message composed and sent.
  549. ***
  550.  
  551. Syntax: COMPOSE REPLY FROM
  552.  
  553. The Compose window will be brought up to compose a reply to the current
  554. message using the From: address as the recipient.
  555.  
  556. RESULT: -1:         There is no current message defined.
  557.          0:         The user cancelled the operation.  No message was
  558.                     composed.
  559.          1:         Message composed and placed in PENDING folder.
  560.          2:         Message composed and placed in QUEUED folder.
  561.          3:         Message composed and sent.
  562.  
  563. ***
  564.  
  565. Syntax: COMPOSE FORWARD [userid]
  566.  
  567. The Compose window will be brought up to forward the current message.  If
  568. the userid (email address or referenced Address Book nickname) is
  569. provided, this will be used as the recipient (To:  address) of the
  570. forwarded message; otherwise, the To:  address will be blank and user will
  571. have to provide it.
  572.  
  573. RESULT: -1:         There is no current message defined.
  574.          0:         The user cancelled the operation.  No message was
  575.                     composed.
  576.          1:         Message composed and placed in PENDING folder.
  577.          2:         Message composed and placed in QUEUED folder.
  578.          3:         Message composed and sent.
  579. ***
  580.  
  581. Syntax: COMPOSE MAILTO userid
  582.  
  583. The Compose window will be brought up to compose a new message to be
  584. mailed to the recipient indicated by the userid.  The userid can be either
  585. an Address Book nickname or a full email-address and must be given.
  586.  
  587. No validation is made on the userid.  If it is invalid, either the user
  588. will receive an error when the message is sent or a message will be
  589. received indicating "Returned mail:  User unknown".
  590.  
  591. RESULT: 0:          The user cancelled the operation.  No message was
  592.                     composed.
  593.         1:          Message composed and placed in the PENDING folder.
  594.         2:          Message composed and placed in the QUEUED folder.
  595.         3:          Message composed and sent.
  596.  
  597. ***
  598.  
  599. Syntax: COMPOSE "message-file-name"
  600.  
  601. The Compose window will be brought up and the message file indicated by
  602. "message-file-name" will be read into the system and used as the message
  603. to edit.  This message must have correctly formatted headers.  Only the
  604. To:, From:, Reply-To:, Subject:, cc:, and bcc: headers will be recognized.
  605. A blank line must separate the headers from the body of the message.
  606.  
  607. The "message-file-name" should be the full path name of the message file
  608. and it should be quoted since the path will contain characters that ARexx
  609. will attempt to interpret as operators or possibly embedded spaces.
  610.  
  611. Any address provided with the To: header can be either an Address Book
  612. nickname or a full email address.  Multiple To: addresses can be provided
  613. as well as multiple cc: or bcc: addresses.
  614.  
  615. No headers have to be provided with the message.  The headers can be
  616. provided on the Compose window.  However, if this is done, a blank line
  617. MUST precede the message body in the message file.
  618.  
  619. Additional RC type errors can be received by this command if the
  620. message-file-name is invalid or an error occurred reading in the message
  621. file.  Each of these errors have a severity level of 5 with one of the
  622. following messages placed in the AEMAIL.LASTERROR variable:
  623.  
  624.     105: Error Opening Passed Message
  625.     106: Error retrieving passed message
  626.  
  627. If you would like to use the File Requester to obtain the file name before
  628. passing it to this command, you can use the GETFILENAME command to obtain
  629. the full path name of the message.
  630.  
  631. No validation is made on the To:  address in the message.  If it is
  632. invalid, either the user will receive an error when the message is sent or
  633. a message will be received indicating "Returned mail:  User unknown".
  634.  
  635. RESULT: 0:          The user cancelled the operation.  No message was
  636.                     composed.
  637.         1:          Message composed and placed in PENDING folder.
  638.         2:          Message composed and placed in QUEUED folder.
  639.         3:          Message composed and sent.
  640.  
  641.  
  642.  
  643.                            CURRENT IS SELECTED
  644.  
  645. Syntax: CURRENT IS SELECTED
  646.  
  647. This command makes the currently selected message the current message.
  648. The currently selected message is the message that is highlighted in the
  649. message list or the message that is currently being displayed.  The
  650. message may or may not have a selection asterick.
  651.  
  652. RESULT: 0           There was no selected message.
  653.         1           Current message is now the selected message.
  654.  
  655.  
  656.  
  657.                                    DATE
  658.  
  659. Syntax: DATE
  660.         DATE MDY
  661.         DATE DMY
  662.         DATE YMD
  663.  
  664. This command returns the Date:  header of the current message header
  665. without the "Date:".
  666.  
  667. Without an operand, this command returns the date as it was received in
  668. the Date:  header of the message.  With the operand "MDY" it returns the
  669. date as mm/dd/yy.  The operand "DMY" returns the date as dd/mm/yy and
  670. "YMD" returns yy/mm/dd.  All of the fields are two digits which means that
  671. yy will be the last 2 digits of the year.
  672.  
  673. The alternate formats are provided so that the date field can be stored in
  674. a data base such as one created with "Final Data".
  675.  
  676. RESULT: -1              No current message
  677.         NULL or blanks  No Date: header
  678.         Date: field
  679.  
  680.                                  EXTRACT
  681.  
  682. Syntax: EXTRACT REALNAME name-string
  683.         EXTRACT USERID name-string
  684.  
  685. This command extracts either the REALNAME or the USERID (email address
  686. or address book nickname) from a name string that is usually the result of
  687. the FIRST TONAME, FIRST CCNAME, FIRST BCCNAME or NEXT NAME commands
  688. (see below).  Because of the various formats of a name string; ie,
  689.  
  690.         email-address (Full Name)
  691.         Full Name <email-address>
  692.         email-address
  693.         addressbook-nickname
  694.  
  695. it is easier to use this command rather then to use standard ARexx
  696. commands to parse the name string.
  697.  
  698. If you use the ADDRESS_BOOK GET nickname TYPE command you can determine if
  699. a userid that is returned is a nickname or email address.
  700.  
  701. The name-string variable should be quoted since it will contain blanks and
  702. other characters ARexx may not like including double quote marks.  As an
  703. example:
  704.  
  705.     OPTION RESULTS
  706.     FIRST TONAME
  707.     name=RESULT
  708.     if name = "" THEN EXIT
  709.     EXTRACT USERID '"'name'"'
  710.     emailaddr=RESULT
  711.     ADDRESS_BOOK GET '"'emailaddr'"' TYPE
  712.     if RESULT = 0 THEN OKAY1 emailaddr" is an individual nickname."
  713.     ELSE if RESULT = 1 THEN OKAY1 emailaddr" is a group nickname."
  714.  
  715. RESULT: NULL or blank   No real name if REAL-NAME operand used.
  716.         Either the real name or userid string.
  717.                                   FIRST
  718.  
  719. This command is used to select the first message in the current folder or
  720. to select the first name string from the list of To:  or cc:  recipients.
  721.  
  722. ***
  723.  
  724. Syntax: FIRST
  725.         FIRST NEW
  726.         FIRST SELECTED
  727.         FIRST DELETED
  728.  
  729. Without an Operand this command selects the first message in the current
  730. selected folder as the current message.
  731.  
  732. With the NEW operand, this command selects the first un-read (new) message
  733. in the current selected folder as the current message.
  734.  
  735. If a message is unread but deleted, it will NOT be considered an un-read
  736. message.
  737.  
  738. With the SELECTED operand, this command selects the first selected
  739. (message marked with an asterick) message in the current selected folder
  740. as the current message.
  741.  
  742. With the DELETED operand, this command selects the first message marked as
  743. deleted in the current selected folder as the current message.
  744.  
  745. NOTE: The order of the messages in the folder is the un-sorted order.
  746. This generally means that the first message is the oldest message in the
  747. folder.
  748.  
  749. RESULT: 0       No messages of the particular type in the folder
  750.         1       First message is now the current message.
  751.  
  752. ***
  753.  
  754. Syntax: FIRST TONAME
  755.         FIRST CCNAME
  756.         FIRST BCCNAME
  757.  
  758. This command returns the first name from the appropriate header field
  759. (To:, cc:, or bcc:) in the current message.  The name can be in one of the
  760. following formats:
  761.  
  762.         email-address (Full Name)
  763.         Full Name <email-address>
  764.         email-address
  765.         addressbook-nickname
  766.  
  767. Names in the header recipient lists are separated by commas; however, a
  768. comma may be embedded within a real name if the real name is surrounded by
  769. quotes.
  770.  
  771. If you wish to extract either the Full Name, email-address, or the
  772. addressbook-nickname from the RESULT you can set the RESULT to a variable
  773. and then use the EXTRACT command with that variable as the argument.
  774.  
  775. RESULT: -1              There is no current message
  776.          NULL or blank  There are no names in this field.
  777.          The first name in the appropriate header.
  778.  
  779.  
  780.                                   FLAGS
  781.  
  782. Syntax: FLAGS
  783.  
  784. This command returns the flags for the current message.  The flags are
  785. returned in the RESULT field as indicated below.  A message can have
  786. multiple flags which means that a value will be returned with the two or
  787. more values for the flags added together.  As an example, a message that
  788. is unread and new with attachments will return a value of 11.  You will
  789. need to use the ARexx operator for logical AND to isolate the flag you
  790. want.
  791.  
  792. Here is a piece of ARexx code to isolate a message that is unread:
  793.  
  794.     OPTION RESULTS
  795.  
  796.     FLAGS
  797.  
  798.     IF RESULT = -1 THEN OKAY1 "There is no current message"
  799.     ELSE DO
  800.  
  801.         IF RESULT & 2 THEN OKAY1 "This message is unread"
  802.         ELSE OKAY1 "This message has been read"
  803.  
  804.         END
  805.  
  806. Note the distinction between flag values 1 (for New) and 2 (for Unread).
  807. Generally, when a message is first read into the system both flags are
  808. set.  If the message is read, both flags are turned off.  However, if the
  809. message should be deleted without being read, the Unread flag will be
  810. turned off but the New flag will remain on.  If that message then becomes
  811. un-deleted and the New flag is still on, the Unread flag will be turned
  812. back on.
  813.  
  814. RESULT: -1          No current message
  815.         0           There is a current message but no flags are set
  816.         1           Message is New and unread (can be deleted)
  817.         2           Message is unread but not deleted
  818.         4           Message is a reply
  819.         8           Message has attachments
  820.         16          Message has been forwarded
  821.         32          Message is deleted
  822.         64          Message is selected
  823.  
  824.  
  825.                                   FOLDER
  826.  
  827. There are a number of variations of the FOLDER command.  They are listed
  828. below:
  829.  
  830. ***
  831.  
  832. Syntax: FOLDER
  833.  
  834. The FOLDER command with no operands is used to return the current selected
  835. folder name.
  836.  
  837. RESULT: 0           No folder currently selected
  838.         The folder Name (i.e., "INBOX", "QUEUED", etc.)
  839.  
  840. ***
  841.  
  842. Syntax: FOLDER LIST_FOLDERS [pad]
  843.  
  844. This command will list all of the folders in your system.  Normally each
  845. folder is separated by a space.  However, this can be changed by
  846. specifying a pad string at the end of the command.  You can use the LF
  847. keyword to specify a line feed or use some other character sequence for
  848. the pad string.  As an example:  ", " will insert a comma followed by a
  849. space between each folder name in the list.
  850.  
  851. Notice that the keyword here is LIST_FOLDERS with an underline between
  852. LIST and FOLDERS.  If the keyword was simply LIST it might be
  853. mis-interpreted as a folder named LIST.
  854.  
  855. RESULT: The list of folders separated by the pad character.
  856.  
  857. ***
  858.  
  859. Syntax: FOLDER folder-name
  860.  
  861. This command selects the the folder indicated by folder-name.
  862.  
  863. RESULT: -1: folder-name is invalid.  Could be the result of a misspelling
  864.             of one of the operands used with the FOLDER commands so that
  865.             the operand is mis-interpreted as a folder-name.
  866.          0: The folder folder-name could not be selected.
  867.          1: The folder folder-name was selected.
  868.  
  869. ***
  870.  
  871. Syntax: FOLDER DESCRIPTION
  872.         FOLDER folder-name DESCRIPTION
  873.         FOLDER folder-name SELECT DESCRIPTION
  874.  
  875. This command returns the description of either the selected folder or, if
  876. present, the folder indicated by folder name.  If the folder name is
  877. present, it will not become the new selected unless the SELECT keyword
  878. immediately follows it.  This allows you to obtain the description of a
  879. folder without selecting it.
  880.  
  881. NOTE:  If the folder-name is left off the command and any of the
  882. parameters is misspelled, it could result in the misspelled parameter
  883. being mis-interpreted as a folder-name.
  884.  
  885. RESULT: -1: folder-name is invalid.  Could be the result of a misspelling
  886.             of one of the operands used with the following FOLDER commands
  887.             so that the operand is mis-interpreted as a folder-name.
  888.  
  889.          The description of either the folder specified with folder-name
  890.             or the selected folder.
  891.  
  892. ***
  893.  
  894. Syntax: FOLDER NUMBER_MESSAGES
  895.         FOLDER folder-name NUMBER_MESSAGES
  896.         FOLDER folder-name SELECT NUMBER_MESSAGES
  897.  
  898. This command returns the number of messages contained in either the
  899. selected folder or, if present, the folder indicated by folder name.  If
  900. the folder name is present, it will not become the new selected folder
  901. unless the SELECT keyword immediately follows it.  This allows you to
  902. obtain the number of messages from a folder without selecting it.
  903.  
  904. Please note the spelling of the operand NUMBER_MESSAGES with the underline
  905. between NUMBER and MESSAGES.  This makes the operand string longer than a
  906. folder-name so that it does not interfer with any existing folder-name.
  907.  
  908. NOTE:  If the folder-name is left off the command and any of the
  909. parameters is misspelled, it could result in the misspelled parameter
  910. being mis-interpreted as a folder-name.
  911.  
  912. RESULT: -1: folder-name is invalid.  Could be the result of a misspelling
  913.             of one of the operands used with the following FOLDER commands
  914.             so that the operand is mis-interpreted as a folder-name.
  915.  
  916.          n: The total number of messages in the folder including ones that
  917.             are unread or deleted.
  918.  
  919. ***
  920.  
  921. Syntax: FOLDER NEW_MESSAGES
  922.         FOLDER folder-name NEW_MESSAGES
  923.         FOLDER folder-name SELECT NEW_MESSAGES
  924.  
  925. This command returns the number of new (unread) messages contained in
  926. either the selected folder or, if present, the folder indicated by folder
  927. name.  If the folder name is present, it will not become the new selected
  928. folder unless the SELECT keyword immediately follows it.  This allows you
  929. to obtain the number of new messages from a folder without selecting it.
  930.  
  931. If a message is unread but deleted, it will not be included in the count
  932. of new messages.
  933.  
  934. Please note the spelling of the operand NEW_MESSAGES with the underline
  935. between NEW and MESSAGES.  This makes the operand string longer than a
  936. folder-name so that it does not interfer with any existing folder-name.
  937.  
  938. NOTE:  If the folder-name is left off the command and any of the
  939. parameters is misspelled, it could result in the misspelled parameter
  940. being mis-interpreted as a folder-name.
  941.  
  942. RESULT: -1: folder-name is invalid.  Could be the result of a misspelling
  943.             of one of the operands used with the following FOLDER commands
  944.             so that the operand is mis-interpreted as a folder-name.
  945.  
  946.          n: The number of new or unread messages in the folder.
  947.  
  948. ***
  949.  
  950. Syntax: FOLDER DELETED_MESSAGES
  951.         FOLDER folder-name DELETED_MESSAGES
  952.         FOLDER folder-name SELECT DELETED_MESSAGES
  953.  
  954. This command returns the number of deleted messages contained in either
  955. the selected folder or, if present, the folder indicated by folder name.
  956. If the folder name is present, it will not become the new selected folder
  957. unless the SELECT keyword immediately follows it.  This allows you to
  958. obtain the number of deleted messages from a folder without selecting it.
  959.  
  960. Please note the spelling of the operand DELETED_MESSAGES with the
  961. underline between DELETED and MESSAGES.  This makes the operand string
  962. longer than a folder-name so that it does not interfer with any existing
  963. folder-name.
  964.  
  965. NOTE:  If the folder-name is left off the command and any of the
  966. parameters is misspelled, it could result in the misspelled parameter
  967. being mis-interpreted as a folder-name.
  968.  
  969. RESULT: -1: folder-name is invalid.  Could be the result of a misspelling
  970.             of one of the operands used with the following FOLDER commands
  971.             so that the operand is mis-interpreted as a folder-name.
  972.  
  973.          n: The number of deleted messages in the folder.
  974.  
  975. ***
  976.  
  977.                                    FROM
  978.  
  979. Syntax: FROM
  980.  
  981. This command returns the From:  header of the current message without the
  982. "From:  ".  It has no operands.
  983.  
  984. RESULT: -1              No current message
  985.         NULL or blanks  No From: header
  986.         From: header
  987.  
  988.                                  GETCLIP
  989.  
  990. Syntax: GETCLIP
  991.         GETCLIP n
  992.         GETCLIP UNIT n
  993.  
  994. This command will return the current contents of the clipboard in the
  995. result variable.  If "UNIT n" or "n" is not specified, it will be from the
  996. current active clipboard.  If "UNIT n" or "n" (without UNIT) is specified
  997. it will be from the clipboard unit specified by n.
  998.  
  999. If the clipboard unit is specified, the current active clipboard will be
  1000. changed to that unit UNLESS the clipboard unit was non-existant.
  1001.  
  1002. RESULT: NULL or blank   This clipboard unit is empty or non-existant.
  1003.         Data from the clipboard unit.
  1004.  
  1005. ***
  1006.  
  1007. Syntax: GETCLIP UNIT
  1008.  
  1009. This command will return the current active clipboard unit number.  Notice
  1010. that is similar to the previous command WITHOUT the clipboard unit number
  1011. (n).
  1012.  
  1013. RESULT: n       This current active clipboard unit number.
  1014.  
  1015.  
  1016.                                GETFILENAME
  1017.  
  1018. Syntax: GETFILENAME
  1019.         GETFILENAME title
  1020.         GETFILENAME title defaultpath
  1021.  
  1022. This command brings up the AEMail file requester so you can solicit file
  1023. names that can be used with commands that require file names.
  1024.  
  1025. If no operands are provided with this command, the file requester will
  1026. have "ARexx File Request" as the default title in the requester and a
  1027. default path of PROGDIR: (the directory from which AEMail was called).
  1028.  
  1029. The second form of this command allows you to provide your own title in
  1030. the file requester which may be more descriptive of what kind of file you
  1031. want.
  1032.  
  1033. The third form gives the user the ability to provide both a title and a
  1034. default file path and (if wanted) filename.  This is particularly useful
  1035. if you want to reference a different directory than your program
  1036. directory.  A default filename can be part of this path.
  1037.  
  1038. NOTE: If you supply a default path without a filename (directory only) you
  1039. must end the string with ":" or "/" to indicate that it is a directory and
  1040. not a filename path.
  1041.  
  1042. Be very careful in using this command since this is one that will require
  1043. "creative" quoting to insure that you have no more than two operand
  1044. strings.  As an example you should use something like this:
  1045.  
  1046.     GETFILENAME '"The Title String"' '"A file name path"'
  1047.  
  1048. This will send "The Title String" and "A file name path" to AEMail which
  1049. will recognize these strings as two quoted operands.
  1050.  
  1051. RESULT:  NULL or blank if the no filename was entered or the requester was
  1052.             cancelled.
  1053.          The full path and filename of the file that was selected.
  1054.                                 GETNUMBER
  1055.  
  1056. Syntax: GETNUMBER
  1057.         GETNUMBER title
  1058.         GETNUMBER title default
  1059.         GETNUMBER title default min
  1060.         GETNUMBER title default min max
  1061.  
  1062. This command brings up the AEMail numeric requester so you can solicit a
  1063. numeric value.
  1064.  
  1065. If no operands are provided with this command, the numeric requester will
  1066. have "ARexx Enter Number" as the default title in the requester and a
  1067. default value of 0.
  1068.  
  1069. The second form of this command allows you to provide your own title in
  1070. the numeric requester which may be more descriptive of what purpose you
  1071. want the number for.
  1072.  
  1073. The third form gives the user the ability to provide both a title and a
  1074. default numeric value.
  1075.  
  1076. The fourth form gives you the ability to provide a minimum value that can
  1077. be entered, and the fifth for allows both a minimum or maximum value.   f
  1078. a value outside this range is entered, the screen will flash.  Also, the
  1079. minimum and maximum limits are given in a text string below the numeric
  1080. entry gadget.
  1081.  
  1082. Be very careful in using this command since this is one that will require
  1083. "creative" quoting for the title to insure that strings between embedded
  1084. spaces are not interpreted as part of the numeric values.  As an example
  1085. you should use something like this:
  1086.  
  1087.     GETNUMBER '"Enter a number between 3 & 7"' 5 3 7
  1088.  
  1089. This will place "Enter a number between 3 & 7" in the title bar of the
  1090. requester, use 5 as the default value in the numeric entry gadget, and set
  1091. the minimum and maximum possibilities to 3 and 7 respectively.  This will
  1092. also recognize the full title string as a proper quoted operand.
  1093.  
  1094. RESULT:  NULL or blank if the the requester was cancelled.
  1095.           n     The numeric value entered in the requester.
  1096.  
  1097.                                  GETSIZE
  1098.  
  1099. Syntax: GETSIZE MESSAGE
  1100.         GETSIZE TEXT
  1101.  
  1102. This command will get the size of the Current Message.  If the operand
  1103. "MESSAGE" is given, it will be the size of the complete message.  If the
  1104. operand "TEXT" is given, it will be only the size of the text portion of
  1105. the message (Message size less the header size and any attachment size).
  1106.  
  1107. RESULT: 0       No Current Message
  1108.         The size of the Current Message or just the text size.
  1109.  
  1110.                                 GETSTRING
  1111.  
  1112. Syntax: GETSTRING
  1113.         GETSTRING title
  1114.         GETSTRING title defaultstring
  1115.  
  1116. This command brings up the AEMail string requester so you can solicit a
  1117. string from the user.
  1118.  
  1119. If no operands are provided with this command, the string requester will
  1120. have "ARexx Enter String" as the default title in the requester with no
  1121. default string.
  1122.  
  1123. The second form of this command allows you to provide your own title in
  1124. the string requester which may be more descriptive of what purpose you
  1125. want the string for.
  1126.  
  1127. The third form gives the user the ability to provide both a title and a
  1128. default string that will appear in the requester when it is first brought
  1129. up.
  1130.  
  1131. Be very careful in using this command since this is one that will require
  1132. "creative" quoting to insure that you have no more than two operand
  1133. strings.  As an example you should use something like this:
  1134.  
  1135.     GETFILENAME '"Enter a Folder Name"' '"INBOX"'
  1136.  
  1137. This will send "Enter a Folder Name" and "INBOX" to AEMail which will
  1138. recognize these strings as two separate quoted operands.  Since INBOX is
  1139. one word, it does not have to have the special quoting on it but can be
  1140. simply 'INBOX'.
  1141.  
  1142. RESULTS:  NULL or blank if the no string was entered or the requester was
  1143.             cancelled.
  1144.           The string that was entered in the requester.
  1145.                                    LAST
  1146.  
  1147. Syntax: LAST
  1148.         LAST NEW
  1149.         LAST SELECTED
  1150.         LAST DELETED
  1151.  
  1152. Without an Operand this command selects the last message in the current
  1153. selected folder as the current message.
  1154.  
  1155. With the NEW operand, this command selects the last un-read (new) message
  1156. in the current selected folder as the current message.
  1157.  
  1158. If a message is unread but deleted, it will NOT be considered an un-read
  1159. message.
  1160.  
  1161. With the SELECTED operand, this command selects the last selected
  1162. (message marked with an asterick) message in the current selected folder
  1163. as the current message.
  1164.  
  1165. With the DELETED operand, this command selects the last message marked as
  1166. deleted in the current selected folder as the current message.
  1167.  
  1168. NOTE: The order of the messages in the folder is the un-sorted order.
  1169. This generally means that the last message is the newest message in the
  1170. folder.
  1171.  
  1172. RESULT: 0       No messages of the particular type in the folder
  1173.         1       Last message is now the current message.
  1174.  
  1175.  
  1176.                                  MESSAGE
  1177.  
  1178. This command is used to set various flags on the Current Message.  After
  1179. the execution of this command, the message list, if it is currently being
  1180. displayed, will be re-displayed with the changed status.  The forms of
  1181. this command are as follows:
  1182.  
  1183. Syntax: MESSAGE SELECT
  1184.  
  1185. This command marks the Current Message as selected.
  1186.  
  1187. RESULT: -1  There is no Current Message.
  1188.          0  The Current Message is already marked as selected.
  1189.          1  The Current Message is now marked as selected.
  1190.  
  1191. ***
  1192.  
  1193. Syntax: MESSAGE UNSELECT
  1194.  
  1195. This command marks the Current Message as un-selected.
  1196.  
  1197. RESULT: -1  There is no Current Message.
  1198.          0  The Current Message is not marked as selected.
  1199.          1  The Current Message is now marked as un-selected.
  1200.  
  1201. ***
  1202.  
  1203. Syntax: MESSAGE DELETE
  1204.  
  1205. This command marks the Current Message as deleted.
  1206.  
  1207. RESULT: -1  There is no Current Message.
  1208.          0  The Current Message is already marked as deleted.
  1209.          1  The Current Message is now marked as deleted.
  1210.  
  1211. ***
  1212.  
  1213. Syntax: MESSAGE UNDELETE
  1214.  
  1215. This command marks the Current Message as not deleted.
  1216.  
  1217. RESULT: -1  There is no Current Message.
  1218.          0  The Current Message is not currently marked as deleted.
  1219.          1  The Current Message is now no longer marked as deleted.
  1220.  
  1221. ***
  1222.  
  1223. Syntax: MESSAGE READ
  1224.  
  1225. This command marks the Current Message as being read.
  1226.  
  1227. RESULT: -1  There is no Current Message.
  1228.          0  The Current Message is already marked as being read.
  1229.          1  The Current Message is now marked as being read.
  1230.  
  1231. ***
  1232.  
  1233. Syntax: MESSAGE MAKE NEW
  1234.  
  1235. This command marks the Current Message as unread or new.
  1236.  
  1237. NOTE: If the message was marked as deleted, only the "new" flag is set;
  1238. otherwise, both the "new" and "unread" flags are set.
  1239.  
  1240. RESULT: -1  There is no Current Message.
  1241.          0  The Current Message is already marked as unread (new).
  1242.          1  The Current Message is now marked as unread.
  1243.  
  1244. ***
  1245.  
  1246. Syntax: MESSAGE SELECT ALL
  1247.  
  1248. All messages in the current selected folder are marked as selected.  This
  1249. command does not change the Current Message status.
  1250.  
  1251. RESULT:  0  There are no messages in the selected folder.
  1252.          1  All of the messages in the selected folder are marked as
  1253.             selected.
  1254.  
  1255. ***
  1256.  
  1257. Syntax: MESSAGE SELECT NONE
  1258.         MESSAGE UNSELECT ALL
  1259.  
  1260. This command can be expressed in either form above.
  1261.  
  1262. All messages in the current selected folder are marked as un-selected.
  1263. This command does not change the Current Message status.
  1264.  
  1265. RESULT:  0  There are no messages in the selected folder.
  1266.          1  All of the messages in the selected folder are now marked as
  1267.             un-selected.
  1268.  
  1269.                                    NEXT
  1270.  
  1271. This command is used to select the next message in the current folder or
  1272. to select the next name string from the list of To:  or cc:  recipients.
  1273.  
  1274. ***
  1275.  
  1276. Syntax: NEXT
  1277.         NEXT NEW
  1278.         NEXT SELECTED
  1279.         NEXT DELETED
  1280.  
  1281. Without an operand this command selects the next message, regardless of
  1282. it's status, in the current selected folder as the current message.
  1283.  
  1284. With the NEW operand, this command selects the next un-read (new) message
  1285. in the current selected folder as the current message.
  1286.  
  1287. If a message is unread but deleted, it will NOT be considered an un-read
  1288. message.
  1289.  
  1290. With the SELECTED operand, this command selects the next selected (message
  1291. marked with an asterick) message in the current selected folder as the
  1292. current message.
  1293.  
  1294. With the DELETED operand, this command selects the next message marked as
  1295. deleted in the current selected folder as the current message.
  1296.  
  1297. NOTE:  The order of the messages in the folder is the un-sorted order.
  1298. This generally means that the order of the messages in the folder is that
  1299. older messages are before newer messages.
  1300.  
  1301. RESULT: 0       No more messages of the particular type are in the folder.
  1302.                 At the end of the message list.
  1303.         1       The next message is now the current message.
  1304.  
  1305. ***
  1306.  
  1307. Syntax: NEXT NAME
  1308.  
  1309. This command returns the next name from the header field that was
  1310. referenced by the last FIRST command.  A FIRST TONAME, FIRST CCNAME, or
  1311. FIRST BCCNAME command must have been issued prior to issuing the first
  1312. NEXT NAME command.  Each NEXT NAME command that is issued retrieves the
  1313. next name in that header field.  Once the end of the name list is reached,
  1314. another FIRST command must be issued before another NEXT NAME command is
  1315. issued.  The name can be in one of the following formats:
  1316.  
  1317.         email-address (Full Name)
  1318.         Full Name <email-address>
  1319.         email-address
  1320.         addressbook-nickname
  1321.  
  1322. Names in the header recipient lists are separated by commas; however, a
  1323. comma may be embedded within a real name if the real name is surrounded by
  1324. quotes.
  1325.  
  1326. If you wish to extract either the Full Name, email-address, or the
  1327. addressbook-nickname from the RESULT you can set the RESULT to a variable
  1328. and then use the EXTRACT command with that variable as the arguement.
  1329.  
  1330. RESULT: -2              The name string has not been started with the
  1331.                         FIRST command.
  1332.          NULL or blank  You are at the end of the list.  There are no 
  1333.                         more names in the current header field.
  1334.          The next name in the appropriate header.
  1335.  
  1336.                                   OKAY1
  1337.  
  1338. Syntax: OKAY1 text
  1339.  
  1340. This commands presents the AEMail notification requester containing the
  1341. supplied text.  If there are any ARexx specific command operators within
  1342. the text stream, the stream should be surrounded in quotes.
  1343.  
  1344. The notification requester has one button marked "Continue".  Clicking on
  1345. this button will terminate the requester and the OKAY1 command.
  1346.  
  1347. Warning: Be careful of the size of the text string that you pass to this
  1348. command.  If the string is too long without intervening line feeds, the
  1349. "Continue" button could be positioned off the screen and you will have no
  1350. way to terminate the requester.  This can be particularly true of returned
  1351. strings that are being displayed.  It is best to use the ARexx LEFT()
  1352. function to insure you have a short enough string.
  1353.  
  1354. RESULT: 1           Always returned
  1355.  
  1356.  
  1357.                                   OKAY2
  1358.  
  1359. Syntax: OKAY1 responses text
  1360.  
  1361. This commands presents the AEMail notification requester containing the
  1362. supplied text.  If there are any ARexx specific command operators within
  1363. the text stream, the stream should be surrounded in quotes.
  1364.  
  1365. "responses" provides a list of possible responses to the requester.  Any
  1366. number of responses can be provided.  Each response must be separated by
  1367. the vertical bar ("|").  The entire response string must be surrounded by
  1368. quote marks.
  1369.  
  1370. The notification requester has as many buttons as they are responses.  The
  1371. wording in these buttons is controlled by the response string.  Clicking
  1372. on any of these buttons will terminate the requester and the OKAY2
  1373. command.
  1374.  
  1375. RESULT: 0           The last response in the response string was selected.
  1376.         1           The first response was selected.
  1377.         n           The second through nth (last - 1) response was selected.
  1378.  
  1379.  
  1380.                                  PREVIOUS
  1381. Syntax: PREVIOUS
  1382.         PREVIOUS NEW
  1383.         PREVIOUS SELECTED
  1384.         PREVIOUS DELETED
  1385.  
  1386. Without an operand this command selects the previous message, regardless
  1387. of it's status, in the current selected folder as the current message.
  1388.  
  1389. With the NEW operand, this command selects the previous un-read (new)
  1390. message in the current selected folder as the current message.
  1391.  
  1392. If a message is unread but deleted, it will NOT be considered an un-read
  1393. message.
  1394.  
  1395. With the SELECTED operand, this command selects the previous selected
  1396. (message marked with an asterick) message in the current selected folder
  1397. as the current message.
  1398.  
  1399. With the DELETED operand, this command selects the previous message marked
  1400. as deleted in the current selected folder as the current message.
  1401.  
  1402. NOTE:  The order of the messages in the folder is the un-sorted order.
  1403. This generally means that the order of the messages in the folder is that
  1404. older messages are before newer messages.
  1405.  
  1406. RESULT: 0       No more messages of the particular type are in the folder.
  1407.                 At the beginning of the message list.
  1408.         1       The next previous is now the current message.
  1409.  
  1410.  
  1411.  
  1412.                                   QUEUE
  1413.  
  1414. Syntax: QUEUE "message-file-name" [MAILTO userid]
  1415.  
  1416. The message file indicated by "message-file-name" will be read into the
  1417. system and will be placed in the QUEUED folder.  This message must have
  1418. correctly formatted headers.  A blank line must separate the headers from
  1419. the body of the message.
  1420.  
  1421. The "message-file-name" should be the full path name of the message file
  1422. and it should be quoted since the path will contain characters that ARexx
  1423. will attempt to interpret as operators.  It may also contain embedded
  1424. spaces.  If it does contain embedded spaces, double quote pairs must be
  1425. used, ie. '"filename string"' or '"'variable'"'.
  1426.  
  1427. Any address provided with the To: header can be either an Address Book
  1428. nickname or a full email address.  Multiple To: addresses can be provided
  1429. as well as multiple cc: or bcc: addresses.
  1430.  
  1431. Instead of a To: address provided in the message the optional MAILTO
  1432. keyword can be used to provide a userid which can be an Address Book
  1433. nickname or an email address.  The MAILTO address will be added to any
  1434. addresses provide with a To: header.
  1435.  
  1436. If the From: or Reply-To: addresses are not given, these addresses will be
  1437. taken from the default From: and Reply-To addresses.
  1438.  
  1439. Any Date: header is ignored since the Date: header will be constructed
  1440. when the message is sent.
  1441.  
  1442. Any other non-standard headers can be supplied in the message file and
  1443. they will be included with the message.
  1444.  
  1445. Only the To:  header has to be provided unless the MAILTO parameter is
  1446. given.  If the MAILTO parameter is used, no headers have to be provided
  1447. with the message.  However, if this is done, a blank line MUST be the
  1448. first line in the message file.
  1449.  
  1450. Additional RC type errors can be received by this command if the
  1451. message-file-name is invalid or an error occurred reading in the message
  1452. file.  Each of these errors have a severity level of 5 with one of the
  1453. following messages placed in the AEMAIL.LASTERROR variable:
  1454.  
  1455.     105: Error Opening Passed Message
  1456.     106: Error retrieving passed message
  1457.  
  1458. No validation is made on the To:  address in the message.  If it is
  1459. invalid, either the user will receive an error when the message is sent or
  1460. a message will be received indicating "Returned mail:  User unknown".
  1461.  
  1462. RESULT: 1:          Message was placed in the QUEUED folder.
  1463.  
  1464.  
  1465.  
  1466.                                  REPLYTO
  1467.  
  1468. Syntax: REPLYTO
  1469.  
  1470. This command returns the Reply-To:  header of the current message without
  1471. the "Reply-To:  ".  It has no operands.
  1472.  
  1473. RESULT: -1              No current message
  1474.         NULL or blanks  No Reply-To: header
  1475.         Reply-To: header
  1476.                                    SAVE
  1477.  
  1478. This command can save the current message or selected messages or the text
  1479. portion of a message to a file.  The current message or current message
  1480. text can also be directly returned in the RESULT variable.  The Current
  1481. Message text can also be saved to the clipboard.
  1482.  
  1483. The various forms of this command are given below:
  1484.  
  1485. Syntax: SAVE MESSAGE
  1486.  
  1487. This command will return the Current Message in the RESULT variable. This
  1488. will be the complete message including all headers, message body, and all
  1489. attachments.
  1490.  
  1491. WARNING: This will return only the first 4092 characters of the current
  1492. message.  Line Feed characters will be included at the end of each line in
  1493. the message.
  1494.  
  1495. You can use the GETSIZE MESSAGE command to obtain the size of the message
  1496. to see if it will fit.
  1497.  
  1498. RESULT: NULL or blank       There is no Current Message
  1499.         The message (up to 4092 characters)
  1500.  
  1501. ***
  1502.  
  1503. Syntax: SAVE MESSAGE [TO] filename
  1504.  
  1505. This command will save the Current Message to the file whose complete path
  1506. and file name is filename.  This should be a quoted variable.  You can
  1507. solicit a filename by using the GETFILENAME command before issuing this
  1508. command.
  1509.  
  1510. The keyword TO is optional.
  1511.  
  1512. The message saved is the complete message including all headers, message
  1513. body, and all attachments.  Except for available disk space, there is no
  1514. limit on the size of the message.  Line Feed characters will be included
  1515. at the end of each line in the message.
  1516.  
  1517. RESULT:  0      There is no current message
  1518.          1      The current message has been saved.
  1519.  
  1520. ***
  1521.  
  1522. Syntax: SAVE SELECTED MESSAGES [TO] filename
  1523.  
  1524. This command will save all of the selected messages in the current
  1525. selected folder to the file whose complete path and file name is filename.
  1526. This should be a quoted variable.  You can solicit a filename by using the
  1527. GETFILENAME command before issuing this command.
  1528.  
  1529. All of the messages will be saved in the single file specified as a block
  1530. of messages.
  1531.  
  1532. The keyword TO is optional.
  1533.  
  1534. The messages saved include the complete message including all headers,
  1535. message body, and all attachments.  Except for available disk space, there
  1536. is no limit on the size of the message.  Line Feed characters will be
  1537. included at the end of each line in the message.
  1538.  
  1539. RESULT:  0      There is no messages selected
  1540.          1      The current message has been saved.
  1541.  
  1542. ***
  1543.  
  1544. Syntax: SAVE TEXT
  1545.         SAVE TEXT NOLF
  1546.  
  1547. This command will return the text body of the Current Message in the
  1548. RESULT variable.  This will be only the body text without headers or
  1549. attachments.
  1550.  
  1551. Normally the text is returned with a line feed separating each line.  If
  1552. you use the "NOLF" operand, this line feed will be left off.  This means
  1553. that the body lines will be one continuous string of data.  This can be
  1554. very helpful if you have a short message generated by a forms command sent
  1555. by email in a web page.
  1556.  
  1557. WARNING:  This will return only the first 4092 characters of the current
  1558. message body text.  Line Feed characters will be included at the end of
  1559. each line in the message unless NOLF is specified.
  1560.  
  1561. You can use the GETSIZE TEXT command to obtain the size of the message
  1562. body to see if it will fit.
  1563.  
  1564. RESULT: NULL or blank       There is no Current Message
  1565.         The message text (up to 4092 characters)
  1566.  
  1567. ***
  1568.  
  1569. Syntax: SAVE TEXT [TO] filename
  1570.  
  1571. This command will save the text body of the Current Message to the file
  1572. whose complete path and file name is filename.  This should be a quoted
  1573. variable.  You can solicit a filename by using the GETFILENAME command
  1574. before issuing this command.
  1575.  
  1576. The keyword TO is optional.
  1577.  
  1578. The text saved is only the body text without headers or attachments.
  1579. Except for available disk space, there is no limit on the size of the
  1580. message text.  Line Feed characters will be included at the end of each
  1581. line in the message.
  1582.  
  1583. RESULT:  0      There is no current message
  1584.          1      The current message text has been saved.
  1585.  
  1586. ***
  1587.  
  1588. Syntax: SAVE TEXT [TO] CLIPBOARD
  1589.         SAVE TEXT [TO] CLIPBOARD n
  1590.  
  1591. The first form of this command will save the text body of the Current
  1592. Message to the clipboard unit that is currently active.  The second form
  1593. will allow you to save the text to the clipboard unit specified by n.
  1594.  
  1595. You can determine which clipboard is currently active by using the GETCLIP
  1596. UNIT command.
  1597.  
  1598. If you use the "n" parameter, the currently active clipboard unit will be
  1599. changed to n after the command is successfully executed (RESULT of 1).
  1600. The keyword TO is optional.
  1601.  
  1602. The text saved is only the body text without headers or attachments.
  1603. Except for available RAM space, there is no limit on the size of the
  1604. message text.  Line Feed characters will be included at the end of each
  1605. line in the message.
  1606.  
  1607. RESULT:  0      There is no current message
  1608.          1      The current message text has been saved to the clipboard.
  1609.  
  1610. ***
  1611.  
  1612. Syntax: SAVE "string of text" [TO] CLIPBOARD
  1613.         SAVE "string of text" [TO] CLIPBOARD n
  1614.  
  1615. The first form of this command will save the string of text passed as a
  1616. quoted string to the clipboard unit that is currently active.  The second
  1617. form will allow you to save the string to the clipboard unit specified by
  1618. n.
  1619.  
  1620. You can determine which clipboard is currently active by using the GETCLIP
  1621. UNIT command.
  1622.  
  1623. If you use the "n" parameter, the currently active clipboard unit will be
  1624. changed to n after the command is successfully executed (RESULT of 1).
  1625. The keyword TO is optional.
  1626.  
  1627. The keyword TO is optional.
  1628.  
  1629. The string saved must be quoted to allow for embedded spaces and special
  1630. characters.  As an example:
  1631.  
  1632.     SAVE '"This is a string of characters"' TO CLIPBOARD 3
  1633.  
  1634. will save the string "This is a string of characters" to clipboard number
  1635. 3.
  1636.  
  1637. The string is limited to 119 characters. If a larger string is given it
  1638. will be truncated at 119 characters.
  1639.  
  1640. RESULT:  1      The string has been saved to the clipboard.
  1641.  
  1642.                                SCREENTOBACK
  1643.  
  1644. Syntax: SCREENTOBACK AEMAIL
  1645.         SCREENTOBACK WORKBENCH
  1646.         SCREENTOBACK public-screen-name
  1647.  
  1648. This command brings either the AEMail screen, the Workbench screen or
  1649. the named public-screen-name to the back of the display.
  1650.  
  1651. RESULT: 0   The public-screen-name is invalid or no longer open
  1652.         1   The specified screen has been moved to the back.
  1653.  
  1654.  
  1655.                               SCREENTOFRONT
  1656.  
  1657. Syntax: SCREENTOFRONT AEMAIL
  1658.         SCREENTOFRONT WORKBENCH
  1659.         SCREENTOFRONT public-screen-name
  1660.  
  1661. This command brings either the AEMail screen, the Workbench screen or
  1662. the named public-screen-name to the front of the display.
  1663.  
  1664. RESULT: 0   The public-screen-name is invalid or no longer open
  1665.         1   The specified screen is now the front most screen.
  1666.  
  1667.  
  1668.                                  SUBJECT
  1669.  
  1670. Syntax: SUBJECT
  1671.  
  1672. This command returns the Subject:  header of the current message without
  1673. "Subject: ".  It has no operands.
  1674.  
  1675. Also, the RE: and (fwd), if present, is stripped from the header string.
  1676. You can use the FLAGS command to determine if the current message is a
  1677. reply or forwarded message.
  1678.  
  1679. RESULT: -1              No current message
  1680.         NULL or blanks  No Subject: header
  1681.         Subject: header
  1682.  
  1683.  
  1684.                                     TO
  1685.  
  1686. Syntax: TO
  1687.  
  1688. This command returns the To:  header of the current message without the
  1689. "To: ".  It has no operands.
  1690.  
  1691. RESULT: -1              No current message
  1692.         NULL or blanks  No To: header
  1693.         To: header
  1694.  
  1695.                               Error Messages
  1696.                               --------------
  1697.  
  1698. When a command returns an RC value other than 0 the RC code represents a
  1699. severity code.  Severity codes are usually 5 or 20.  A string error
  1700. message will also appear in the AEMAIL.LASTERROR variable.  These errors
  1701. can be interrogated and displayed.
  1702.  
  1703. The errors that you can expect from AEMail are as follows:
  1704.  
  1705.         "100: Unknown command"
  1706.         "101: Syntax Error"
  1707.         "102: No Operand Required"
  1708.         "103: Missing Operand"
  1709.         "104: Too Many Operands"
  1710.         "105: Error Opening Passed Message"
  1711.         "106: Error retrieving passed message"
  1712.         "110: Out of Memory"
  1713.  
  1714. Additional errors which will not have a error message number associated
  1715. with them are:
  1716.  
  1717.         "Unable to open input mail file"
  1718.         "Error reading input mail file"
  1719.         "Unable to open output file"
  1720.         "Error writing to output file"
  1721.  
  1722.  
  1723.  
  1724.