EXPORT (V2.7) ~~~~~~ Format: EXPORT [SERVER ] [] ~~~~~~~ [PRESERVE] [SUBSCRIBED ] [UPDATE ] [FILTER ] [VERBOSITY ] [LOCALREFER] Template: USER/A,PASSWORD/A,SERVER/K,FILE,PRESERVE/S,SUBSCRIBED/K, ~~~~~~~~~ UPDATE/K/N,FILTER/K/N,V=VERBOSITY/K/N,LOCALREFER/S Purpose: Export messages from a UMS message-base, either to backup ~~~~~~~~ or to transfer them to another UMS message-base. Specification: ~~~~~~~~~~~~~~ EXPORT reads messages from a UMS message-base and stores them in a file. It uses its own format, which stores the complete UMS message, has very little overhead, is "almost plaintext" and can be efficiently read by a tool called IMPORT. It may be used for different purposes: * for making backups of a message-base. Advantages of using EXPORT instead of a filesystem based backups are: + incremental backups are supported. + selective backups are possible. I.e. you can make a backup of only the more important messages. + the backup is more space efficient, it uses less overhead. + devices like tape-streamers may easily and efficiently be used. However there is an important disadvantage: - the status of messages is not saved. After a backup&restore operation with EXPORT/IMPORT all information on what user has already read or exported what message is completely lost! * for transfering messages from one message-base to another. Let's say you want to create a new message-base on your system, e.g. to test a new configuration or some beta-tools. In order not to start with a completely empty message-base you might want to fill it with some old "news" from your other message-base. This can be easily and efficiently done with EXPORT and IMPORT. All data will be preserved in the proper format and no garbage data will be added. * to exchange messages with another node that also uses UMS. Given you are a node system which has to feed some "points" or "leaf-nodes" that also use UMS. You might want to use EXPORT and IMPORT for exchanging messages with them, since these tool are completely capabale of doing this and are more efficient using less overhead than any other know protocol. You can even build a complete complex network of UMS-using nodes with EXPORT/IMPORT, if you and the other nodes agree on that format. Invocation: ~~~~~~~~~~~ you must specify a username and password to log into the (optionally specified) UMS server that the messages are read from. If you specify the filename , this will be the file that is written to. Otherwise output will be written to stdout. HINT: output buffering is handled differently for both cases. When writing to a file, EXPORT uses a 32KB write-buffer. When writing to stdout, it reduces buffering and flushes after each exported message. Specifying the PRESERVE keyword means your user-flag "old" must not be changed. Otherwise messages written to the file will me marked as old and, if the used UMS account has "EXPORT" privileges, as exported. You will want to use the PRESERVE keyword when making backups or just playing around. You should NOT use it when exchanging messages with other nodes. The SUBSCRIBED keyword makes EXPORT only export messages with groups matching at least one of the patterns given in the var (see: Configuration). You may want to use this option when exchanging news with another node that not neccessarily always wants to receive all readable messages. As the default, EXPORT exports "new" message, with the "old" flag unset. If you want to want to export other messages, you can select them with any suitable tool (e.g. CleanEx) and tell EXPORT what user-flag has been set on these messages. This is done with the FILTER option. With this option, EXPORT exports all messages with this flag set, no matter whether they are new or not. EXPORT can use another user-flag, indicated by UPDATE, to mark which messages have been exported to only export each message once. This flag is used analogously to the "old" flag. Useful for archiving messages without having to dedicate an extra UMS user-account for this purpose. ONLY use this feature, if you EXACTLY know which flags you may use!!! The VERBOSITY option allows you to control the verbosity of console- output (stderr) given by EXPORT. The must be in the range of 0 to 9. Otherwise it will be set to the default of 6, which gives you some 'graphical' progress-report. Set it to 5 to suppress the progress report and only see a short statistical summary. Set it to 4 to only get stderr-output in case of errors. Set it to 0 to ignore all errors except of gurus (which cannot be ignored). Set it to 9 to get as much output as possible. In some cases message-IDs of locally written messages may be different from some network (e.g. MausNet). Follow-ups to these messages then have a different ID. The relevant importer still can manage to create the correct chaining, but a general importer cannot. By using the LOCALREFER option EXPORT exports the follow-up with local ReferID, allowing IMPORT to re-import all messages with proper chaining. Configuration: ~~~~~~~~~~~~~~ EXPORT uses the following variables in the UMS configuration: export.nodename export.usernodename -- addresses used for the local system. For messages that are written or received by local users UMS stores no "address". Each exporter must know what it's system's name is in the destination network. EXPORT uses these config vars to determine this address. 'export.usernodename' is local to each user. It will be used as FromAddr when a message writen by that user is exported. 'export.nodename' is global. It's only used when there is no 'export.usernodename' for a user. Sometimes it is sufficient to only have 'export.nodename'. But sometimes you also need to have an 'export.usernodename' for each user. E.g. if you want to use Usenet-addresses you need to set up 'export.usernodename's, since Usenet-addresses always depend on the username. ("foo@any.com" for user "Foo Bar"). -- subscribed groups. The SUBSCRIBED option lets you specify the name of a config variable. This variable contains a new-style patternlist. If this is used, only groups matching that patternlist are exported. For each group the patternlist is processed line-by-line form the beginnig to the end. Each line contains one AmigaDOS style pattern with an optional exclamation mark ("!") at the beginning. If there is no exclamation mark at the beginning and the group matches the pattern, the group will be enabled. If there is an exclamation mark and the group matches, it will be disabled. Example: consider the following patternlist !#? comp.sys.amiga.#? !comp.sys.amiga.advocacy the group "comp.sys.amiga.hardware" would be exported, but not the groups "comp.sys.amiga.advocacy" or "alt.sys.amiga". Please note that private messages have an "empty" group. If you want to export private messages and use the subscribe-feature, you must use a suitable pattern. For example "()" is a pattern that only matches private messages. Examples: ~~~~~~~~~ 1) Make a complete backup of the MB to a file on volume "Spool": 1> export sysop password Spool:backup.export preserve filter 10 Using flag 10 as a filter exports all messages, since this is the "ReadAccess" flag which is set for all messages the user can read. Restore the backup: 1> import sysop password Spool:backup.export restore 2) Transfer all new messages for user "mh" from machine "a500" to the local machine, using a temporary file on volume "Spool": 1> export mh password server default@a500 spool:a500.export subscribed 1> import a500 password server default spool:a500.export 3) Archive all messages for user "mh" that have not yet been archived to a tape streamer: 1> export mh password btntape:app preserve update 14 filter 10 See also: IMPORT, UMSDOCTOR ~~~~~~~~~