home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / comm / Mail+News / UMS11 / Doc / english / RexxUMS.doc < prev    next >
Text File  |  1995-05-13  |  12KB  |  269 lines
  1.                  ///////////////////////////////////////////
  2.                 ///    UMS - Universal Message System   ///
  3.                /// Documentation of the ARexx Inteface ///
  4.               ///////////////////////////////////////////
  5.  
  6. ums.library is a ARexx function library.  The query function is at
  7. offset -210.  Use addlib() or RXLIB to install it in the global library
  8. list of ARexx.
  9.  
  10. Please refer the autodoc of ums.library and the supplied sample scrips
  11. ("ReadMessage.rexx", "WriteMessage.rexx", "GroupContents.rexx" and
  12. "ShowGroups.rexx") to get a general understanding of the functions.
  13. Most functions have slightly other parameters than their counterparts in
  14. ums.library. These changes were necessary in order to get a useful
  15. interface. They should be easy to understand.
  16.  
  17. Unfortunately the API changed with the different versions of ums.library.
  18. See changes at the end of the file.
  19.  
  20.  
  21. Datatypes:
  22. ==========
  23.  
  24.   string   - a string (e.g. "Hello!")
  25.   account  - abstract handle returned by Login()
  26.   number   - a cardinal number
  27.   boolean  - "0" (FALSE) or "1" (TRUE)
  28.   flags    - a bitfield (e.g. '00110111 10101001 10100110 10100101'b)
  29.   stem     - a stem variable used to hold all fields of a message
  30.   kind     - kind of ums flags ("User"="U" / "Global"="G" / "Local"="L")
  31.   userkind - kind of user to be crated ("User" = "U" / "Sysop" = "S" /
  32.                                         "Exporter" = "E")
  33.   action   - Action for ServerControl (CLEANUP/FLUSH/QUIT/QUITFORCE/
  34.                                       PING/LOCKCFG/UNLOCKCFG)
  35.  
  36.  
  37. Special STEM compounds for UMSReadMsgInfo():
  38. ============================================
  39.  
  40.   HDRLEN, TXTLEN, DATE, UP, DN, LT, RT, GLOBALSTAT, USERSTAT, LOGINSTAT,
  41.   SOFTLINK, HARDLINK
  42.  
  43.  
  44. Special STEM compounds for UMSWriteMsg():
  45. =========================================
  46.  
  47.   MSGNUM, HARDLINK, SOFTLINK, CHAINUP, MSGDATE, HDRFILL, TXTFILL,
  48.   AUTOBOUNCE, NOUPDATE, HIDE
  49.  
  50.  
  51. Functions:
  52. ==========
  53.  
  54. These three functions are used to login and logout.
  55.   account = UMSLogin(user: string; password: string; [server: string])
  56.   account = UMSDupAccount(account: account)
  57.   UMSLogout(account: account)
  58.  
  59. This function is used to control server activities:
  60.   number = UMSServerControl(action: action; [server: string])
  61.  
  62. Use these functions to find out if an error and it's reason:
  63.   number = UMSErrNum(account: account)
  64.   string = UMSErrTxt(account: account)
  65.   string = UMSErrTxtFromNum(error: number)
  66.  
  67. Writes a log message to ums' logfile:
  68.   UMSLog(account: account; level: number; text: string)
  69.  
  70. This one writes a new message to the message base. The field of the message
  71. must be in the stem. The meaning of the fields numbered from 0 to 127 is
  72. defined by the constants (UMSCODE_MsgText etc.) preset by InitUMSContst().
  73. Look at the description of the msg-format in ums.doc. Instead of reading 
  74. a field from an ARexx string this function will read from a file if
  75. specifieng the filename in the stem by setting UMSCODE_MsgText_FILE etc.
  76. There are some additional special fields, too: MSGNUM, HARDLINK, SOFTLINK,
  77. CHAINUP, MSGDATE, HDRFILL, TXTFILL, AUTOBOUNCE, NOUPDATE, HIDE. Please take
  78. a look at ums.doc to find out their meaning:
  79.   number = UMSWriteMsg(account: account; fields: stem)
  80.  
  81. These are used by exportes to indicate the success of exporting a message
  82. (see ums.doc):
  83.   UMSExportedMsg (account: account; message: number)
  84.   UMSCannotExport(account: account; message: number; error: string)
  85.  
  86. Deleting a message:
  87.   boolean = UMSDeleteMsg(account: account; message: number)
  88.  
  89. These functions read a message from the message base and put it's fields
  90. into the stem. The first function reads all fields, the second just header
  91. fields and the last only one field. _IMPORTANT_NOTE_: These functions do
  92. not drop empty fields. Please ensure that you drop the stem before calling
  93. one of those funktions! If you set stem copounds like UMSCODE_MsgText_FILE
  94. to a filename the funktions will not create and store the corresponding ARexx
  95. string but will write the field to the file. This is useful to circumvent
  96. the limitation of ARexx string which have a maximum length of 68kB which
  97. may result in "errTooBig" for some messages:
  98.   booelan = UMSReadMsgAll   (account: account; message: number;
  99.                              fields: stem; [noupdate: boolean])
  100.   booelan = UMSReadMsgHeader(account: account; message: number;
  101.                              fields: stem; [noupdate: boolean])
  102.   booelan = UMSReadMsgField (account: account; message: number;
  103.                              fields: stem; field: number;
  104.                              [noupdate: boolean])
  105.  
  106. These reads the binary data associated with a message. It is put into the
  107. following fields of the stem: HDRLEN, TXTLEN, DATE, UP, DN, LT, RT,
  108. GLOBALSTAT, USERSTAT, LOGINSTAT, SOFTLINK, HARDLINK:
  109.   booelan = UMSReadMsgInfo  (account: account; message: number; info: stem)
  110.  
  111. Sets all "set" flags and clears all "clear" flags for all messages between
  112. "start" and "stop" which fulfill bitand(status,"mask")="match". You can
  113. examine the flags of the parent message by setting "parent" to TRUE.
  114. Selects and reads the flags of "user". Selects a maximum of "maxcount"
  115. messages with a maximal added size of "maxsize":
  116.   number = UMSSelectFlags(account: account;
  117.                           [kind: kind]; [set: flags]; [unset: flags];
  118.                           [start: nuber]; [stop: number];
  119.                           [kind: kind]; [mask: flags]; [match: flags]
  120.                           [parent: boolean];
  121.                           [maxcount: number]; [maxsize: number];
  122.                           [user: string])
  123.  
  124. Selects the message(s) if a certain field has a certain value. "quick"
  125. enables CRC checking which is fast:
  126.   number = UMSSelectField(account: account;
  127.                           [kind: kind]; [set: flags]; [unset: flags];
  128.                           [start: nuber]; [stop: number];
  129.                           field: number; string: string;
  130.                           [quick: BOOLEAN])
  131.  
  132. Selects one message by number:
  133.   number = UMSSelectMsg  (account: account;
  134.                           [kind: kind]; [set: flags]; [unset: flags];
  135.                           [start: nuber]; [stop: number];
  136.                           message: number)
  137.  
  138. All messages in the reply tree will be selected:
  139.   number = UMSSelectTree (account: account;
  140.                           [kind: kind]; [set: flags]; [unset: flags];
  141.                           [start: nuber]; [stop: number];
  142.                           message: number;
  143.                           [quick: BOOLEAN]; [sub: BOOLEAN])
  144.  
  145. Selects Messages younger than "receivedate":
  146.   number = UMSSelectDate (account: account;
  147.                           [kind: kind]; [set: flags]; [unset: flags];
  148.                           [start: nuber]; [stop: number];
  149.                           receivedate: number)
  150.  
  151. Selects Messages younger than "creationdate":
  152.   number = UMSSelectCDate (account: account;
  153.                            [kind: kind]; [set: flags]; [unset: flags];
  154.                            [start: nuber]; [stop: number];
  155.                            creationdate: number)
  156.  
  157. Selects Messages larger than "size":
  158.   number = UMSSelectSize (account: account;
  159.                           [kind: kind]; [set: flags]; [unset: flags];
  160.                           [start: nuber]; [stop: number];
  161.                           size: number)
  162.  
  163. Finds the next message starting with "last" with fullfills
  164. bitand(status,"mask")="match" (for "user"):
  165.   number = UMSSearchFlags(account: account;
  166.                           [kind: kind]; [mask: flags]; [match: flags];
  167.                           last: number; [user: string])
  168.  
  169. Search for the next message (for "user") fith a certain field:
  170.   number = UMSSearchField  (account: account; field: number;
  171.                             string: string; last: number;
  172.                             [direction: number]; [quick: boolean];
  173.                             [user: string])
  174.   number = UMSSearchPattern(account: account; field: number;
  175.                             pattern: string; last: number;
  176.                             [direction: number]; [user: string])
  177.  
  178. These are used to get configuration variables from ums.config.
  179.   string = UMSReadConfig(account: account; name: string; [user: string];
  180.                          [globalonly: boolean])
  181.   string = UMSReadConfigUserName(account: account; alias: string)
  182.   string = UMSNextVar(account: account; last: string; user: string;
  183.                       [globalonly: boolean])
  184.   boolean = UMSMatchConfig(account: account; name: string; string: string;
  185.                            [default: string]; [user: string];
  186.                            [globalonly: boolean])
  187.   string = UMSNextAlias(account: account; name: string; [alias: string])
  188.   string = UMSNextUser(account: account; [user: string])
  189.   string = UMSNextExporter(account: account; [exporter: string])
  190.   string = UMSNextNetGroup(account: account; [netgroup: string])
  191.   string = UMSNextNetGroupMember(account: account; [netgroupmember: string])
  192.  
  193. Write a variable to ums.config. In order do delete the Variable just pass
  194. no "data":
  195.   boolean = UMSWriteConfig(account: account; name: string; [data: string];
  196.                            [user: string]; [global: boolean])
  197.  
  198. Change ums.config:
  199.   boolean = UMSCreateUser(account: account; user: string; [kind: userkind])
  200.   boolean = UMSDeleteUser(account: account; user: string)
  201.   boolean = UMSCreateAlias(account: account; user: string; alias: string)
  202.   boolean = UMSDeleteAlias(account: account; alias: string)
  203.   boolean = UMSAddNetGroup(account: account; netgroup: string; newnetgroup: string)
  204.   boolean = UMSDeleteNetGroup(account: account; netgroup: string)
  205.  
  206. In order to create bitfields for flags use this funktion:
  207.   flags = UMSMakeFlags([flag: number; ...])
  208.  
  209. In order to preset variables like UMSCODE_MsgText with useful values call:
  210.   boolean = UMSInitConsts()
  211.  
  212.  
  213. Changes:
  214. ========
  215.  
  216. The ARexx API of UMS v8 and v9 were not commonly used. UMS v10 introduced a
  217. powerful API which is used by a lot of scripts.
  218.  
  219. UMS v11 introduces a new API for ARexx. It is not backward compatible.
  220. You'll have to change all old ARexx scripts in order to work with v11. If
  221. the scripts are changed they won't work with v10 any more. I'm sorry for
  222. that. Here's a list of what's to do:
  223.  
  224. - New functions:
  225.   UMSDupAccount, UMSServerControl, UMSErrTxtFromNum, UMSMatchConfig,
  226.   UMSInitConsts, UMSSelectCDate, UMSSelectSize, UMSNextAlias,
  227.   UMSNextUser, UMSNextExporter, UMSNextNetGroup, UMSNextNetGroupMember,
  228.   UMSCreateUser, UMSDeleteUser, UMSCreateAlias, UMSDeleteAlias,
  229.   UMSAddNetGroup, UMSDeleteNetGroup
  230.  
  231.   UMSDupAccount() is extremely useful for ARexx scripts launchend from a
  232.   program which is already logged in.
  233.  
  234.   UMSServerControl() replaces a lot of old functions (see below)
  235.  
  236.   UMSInitConsts() removes the need for an UMS include file. It predefines a
  237.   lot of useful constants formerly defined in UMSConsts.rexx
  238.  
  239.   The new select functions were introduced with UMS 11 Server Beta 23
  240.   Library Beta 13.
  241.  
  242.   The new configuration funktions, new parameters for UMSSelect(), the
  243.   "user" parameter for UMSSearch() and file support for UMSWriteMsg() and
  244.   UMSReadMsg() were introduced with UMS 11 Library Beta 17.
  245.  
  246. - Removed functions:
  247.   CleanUMS, FlushUMS, QuitUMS, LockUMSConfig, UnlockUMSConfig,
  248.   DumpUMSConfig
  249.  
  250.   DumpConfig() is not useful. You can substitute all other functions by
  251.   UMSServerControl()
  252.  
  253. - Renamed funtions:
  254.   LogUMS()                -> UMSLog()
  255.   WriteUMSMsg()           -> UMSWriteMsg()
  256.   ExportedUMSMsg()        -> UMSExportedMsg()
  257.   DeleteUMSMsg()          -> UMSDeleteMsg()
  258.   ReadUMSMsgAll()         -> UMSReadMsgAll()
  259.   ReadUMSMsgHeader()      -> UMSReadMsgHeader()
  260.   ReadUMSMsgField()       -> UMSReadMsgField()
  261.   ReadUMSMsgInfo()        -> UMSReadMsgInfo()
  262.   ReadUMSConfig()         -> UMSReadConfig()
  263.   ReadUMSConfigUserName() -> UMSReadConfigUserName()
  264.   NextUMSVar()            -> UMSNextVar()
  265.   WriteUMSConfig()        -> UMSWriteConfig()
  266.  
  267. - other changes:
  268.   UMSSelectTree()'s parameters changed.
  269.