home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / comm / Mail+News / UMS11 / Doc / english / export.man < prev    next >
Text File  |  1995-04-23  |  8KB  |  206 lines
  1.  
  2.                 EXPORT (V2.7)
  3.                 ~~~~~~
  4.  
  5. Format:   EXPORT <name> <password> [SERVER <server>] [<file>]
  6. ~~~~~~~   [PRESERVE] [SUBSCRIBED <list>] [UPDATE <updateflag>]
  7.           [FILTER <filterflag>] [VERBOSITY <level>] [LOCALREFER]
  8.  
  9. Template: USER/A,PASSWORD/A,SERVER/K,FILE,PRESERVE/S,SUBSCRIBED/K,
  10. ~~~~~~~~~ UPDATE/K/N,FILTER/K/N,V=VERBOSITY/K/N,LOCALREFER/S
  11.  
  12. Purpose:  Export messages from a UMS message-base, either to backup
  13. ~~~~~~~~  or to transfer them to another UMS message-base.
  14.  
  15. Specification:
  16. ~~~~~~~~~~~~~~
  17.  
  18. EXPORT  reads  messages  from  a UMS message-base and stores them in a
  19. file.  It  uses its own format, which stores the complete UMS message,
  20. has very little overhead, is "almost plaintext" and can be efficiently
  21. read by a tool called IMPORT.
  22.  
  23.   It may be used for different purposes:
  24.  
  25.  * for making backups of a message-base.
  26.  
  27.   Advantages  of  using  EXPORT  instead of a filesystem based backups
  28.   are:
  29.  
  30.     + incremental backups are supported.
  31.     + selective backups are possible. I.e. you can make a backup of
  32. only the more important messages.
  33.     + the backup is more space efficient, it uses less overhead.
  34.     + devices like tape-streamers may easily and efficiently be used.
  35.  
  36. However there is an important disadvantage:
  37.  
  38.     - the status of messages is not saved. After a backup&restore
  39. operation with EXPORT/IMPORT all information on what user has already
  40. read or exported what message is completely lost!
  41.  
  42.  
  43.  * for transfering messages from one message-base to another.
  44.  
  45.   Let's say you want to create a new message-base on your system, e.g.
  46.   to  test  a  new  configuration  or some beta-tools. In order not to
  47.   start with a completely empty message-base you might want to fill it
  48.   with  some  old  "news"  from  your  other message-base. This can be
  49.   easily and efficiently done with EXPORT and IMPORT. All data will be
  50.   preserved in the proper format and no garbage data will be added.
  51.  
  52.  
  53.  * to exchange messages with another node that also uses UMS.
  54.  
  55.   Given  you  are  a  node  system  which has to feed some "points" or
  56.   "leaf-nodes"  that  also  use  UMS. You might want to use EXPORT and
  57.   IMPORT  for  exchanging  messages  with  them,  since these tool are
  58.   completely  capabale of doing this and are more efficient using less
  59.   overhead than any other know protocol.
  60.  
  61.     You  can  even build a complete complex network of UMS-using nodes
  62.   with EXPORT/IMPORT, if you and the other nodes agree on that format.
  63.  
  64.  
  65. Invocation:
  66. ~~~~~~~~~~~
  67. you  must  specify a username and password to log into the (optionally
  68. specified) UMS server that the messages are read from.
  69.  
  70.   If  you  specify  the filename <file>, this will be the file that is
  71. written to. Otherwise output will be written to stdout.
  72.  
  73. HINT:  output  buffering  is  handled differently for both cases. When
  74. writing  to  a  file, EXPORT uses a 32KB write-buffer. When writing to
  75. stdout, it reduces buffering and flushes after each exported message.
  76.  
  77.   Specifying  the PRESERVE keyword means your user-flag "old" must not
  78. be  changed.  Otherwise messages written to the file will me marked as
  79. old and, if the used UMS account has "EXPORT" privileges, as exported.
  80. You  will want to use the PRESERVE keyword when making backups or just
  81. playing  around.  You  should NOT use it when exchanging messages with
  82. other nodes.
  83.  
  84.   The SUBSCRIBED keyword makes EXPORT only export messages with groups
  85. matching  at  least  one of the patterns given in the <list> var (see:
  86. Configuration).  You  may want to use this option when exchanging news
  87. with  another  node  that not neccessarily always wants to receive all
  88. readable messages.
  89.  
  90.   As  the  default,  EXPORT exports "new" message, with the "old" flag
  91. unset.  If  you  want to want to export other messages, you can select
  92. them  with  any  suitable  tool  (e.g.  CleanEx)  and tell EXPORT what
  93. user-flag has been set on these messages. This is done with the FILTER
  94. option.  With  this option, EXPORT exports all messages with this flag
  95. set, no matter whether they are new or not.
  96.  
  97.   EXPORT can use another user-flag, indicated by UPDATE, to mark which
  98. messages  have  been  exported  to only export each message once. This
  99. flag  is  used  analogously  to  the  "old" flag. Useful for archiving
  100. messages without having to dedicate an extra UMS user-account for this
  101. purpose.  ONLY  use  this feature, if you EXACTLY know which flags you
  102. may use!!!
  103.  
  104.   The VERBOSITY option allows you to control the verbosity of console-
  105. output (stderr) given by EXPORT. The <level> must be in the range of 0
  106. to  9.  Otherwise  it will be set to the default of 6, which gives you
  107. some 'graphical' progress-report. Set it to 5 to suppress the progress
  108. report  and  only see a short statistical summary. Set it to 4 to only
  109. get  stderr-output in case of errors. Set it to 0 to ignore all errors
  110. except  of gurus (which cannot be ignored). Set it to 9 to get as much
  111. output as possible.
  112.  
  113.   In  some  cases  message-IDs  of  locally  written  messages  may be
  114. different  from  some  network  (e.g.  MausNet).  Follow-ups  to these
  115. messages  then  have  a  different ID. The relevant importer still can
  116. manage  to create the correct chaining, but a general importer cannot.
  117. By using the LOCALREFER option EXPORT exports the follow-up with local
  118. ReferID,  allowing  IMPORT  to  re-import  all  messages  with  proper
  119. chaining.
  120.  
  121.  
  122. Configuration:
  123. ~~~~~~~~~~~~~~
  124.  
  125. EXPORT uses the following variables in the UMS configuration:
  126.  
  127.   export.nodename
  128.   export.usernodename -- addresses used for the local system.
  129.  
  130.   For  messages that are written or received by local users UMS stores
  131. no  "address".  Each  exporter must know what it's system's name is in
  132. the  destination  network.  EXPORT uses these config vars to determine
  133. this  address. 'export.usernodename' is local to each user. It will be
  134. used  as  FromAddr  when  a  message  writen by that user is exported.
  135. 'export.nodename'   is  global.  It's  only  used  when  there  is  no
  136. 'export.usernodename' for a user.
  137.  
  138.   Sometimes  it  is  sufficient  to  only  have 'export.nodename'. But
  139. sometimes  you  also  need  to  have an 'export.usernodename' for each
  140. user.  E.g.  if  you  want  to use Usenet-addresses you need to set up
  141. 'export.usernodename's,  since  Usenet-addresses  always depend on the
  142. username. ("foo@any.com" for user "Foo Bar").
  143.  
  144.  
  145.   <list> -- subscribed groups.
  146.  
  147.   The  SUBSCRIBED  option  lets  you  specify  the  name  of  a config
  148. variable.  This  variable contains a new-style patternlist. If this is
  149. used, only groups matching that patternlist are exported.
  150.  
  151.   For  each  group  the patternlist is processed line-by-line form the
  152. beginnig  to  the  end.  Each line contains one AmigaDOS style pattern
  153. with  an optional exclamation mark ("!") at the beginning. If there is
  154. no  exclamation  mark  at  the  beginning  and  the  group matches the
  155. pattern,  the  group  will be enabled. If there is an exclamation mark
  156. and the group matches, it will be disabled.
  157.  
  158.   Example: consider the following patternlist
  159.  
  160.     !#?
  161.     comp.sys.amiga.#?
  162.     !comp.sys.amiga.advocacy
  163.  
  164.   the  group  "comp.sys.amiga.hardware" would be exported, but not the
  165. groups "comp.sys.amiga.advocacy" or "alt.sys.amiga".
  166.  
  167.   Please note that private messages have an "empty" group. If you want
  168. to export private messages and use the subscribe-feature, you must use
  169. a  suitable  pattern.  For example "()" is a pattern that only matches
  170. private messages.
  171.  
  172.  
  173. Examples:
  174. ~~~~~~~~~
  175.  
  176. 1)
  177. Make a complete backup of the MB to a file on volume "Spool":
  178.  
  179.   1> export sysop password Spool:backup.export preserve filter 10
  180.  
  181. Using  flag  10  as  a  filter exports all messages, since this is the
  182. "ReadAccess" flag which is set for all messages the user can read.
  183.  
  184. Restore the backup:
  185.  
  186.   1> import sysop password Spool:backup.export restore
  187.  
  188.  
  189. 2)
  190. Transfer all new messages for user "mh" from machine "a500" to the
  191. local machine, using a temporary file on volume "Spool":
  192.  
  193.   1> export mh   password server default@a500 spool:a500.export subscribed
  194.   1> import a500 password server default      spool:a500.export
  195.  
  196.  
  197. 3)
  198. Archive all messages for user "mh" that have not yet been archived to
  199. a tape streamer:
  200.  
  201.   1> export mh password btntape:app preserve update 14 filter 10
  202.  
  203.  
  204. See also: IMPORT, UMSDOCTOR
  205. ~~~~~~~~~
  206.