NAME WriteUMSMsg -- Write a universal message to the UMS-MB. SYNOPSIS msgNum = WriteUMSMsg( login, tags ) D0 D3 D3 LONG WriteUMSMsg( LONG, struct TagItem * ); msgNum = WriteUMSMsgTags( login, tag1, ... ) LONG WriteUMSMsgTags( LONG, ULONG, ... ); FUNCTION Writes a message to the UMS message-base. This may be either a new message to create or an already existing message to be changed. The MBP checks correctness of the message and the users write-access concerning this message before writing it. It also performs dupe-checking, tries to link to a tree of reply-chains, creates all desired indices and computes the other users' read-access to this message. All the components of the message as well as information on how to do it are supplied as AmigaDOS compatible TagItems. INPUTS The following tags are allowed: WMsgText, .. WMsgText + 127 : STRPTR specify a certain text-field. A text fields is always one null-terminated string. Read the separate documantation to see what fields and what formats of these fields are allowed. A certain text-field (identified by its tag) may only appear once in a message. If a field is specified more than once in the tag list, only the latest will be used. WTextFields : UMSMsgTextFields specify more than one text-field. This points to an array of 128 string-pointers. All fields you don't want to specify must be NULL in this array. WMsgNum : LONG when you want to change an old message, you must use this tag to specify the number of the message to change. Don't use this tag when you just want to create a new message. WMsgDate : LONG this has a very special meaning. Specifying an AmigaDOS compatible date (seconds since 1.1.1978) with this tag indicates that you want to restore an old message from a backup rather than writing a new one. All users will have the 'old' flag set and not get this message as a new one when this tag is used. WChainUp : LONG in some cases it might be unsure or impossible for the MBP to build the correct reply-chain for a message. Use this tag to specify the number of the old message that is referred to by the new one. WHardLink, WSoftLink : LONG Writing a message with a Message-ID that already exists in the MB usually will lead to the detection of a 'dupe'. Yet in some cases it is necessary for UMS to allow multiple messages with the same Message-ID. This is made possible by the concept of message-'links'. With this concept, multiple messages sharing the same Message-ID (and perhaps some more fields) are organized in a circular linked list. To create such a linked list, you just write its first message as usual and remember its number. Then you write the other messages using one of the above tags to specify the number of the original message (or any of the already linked messages). The MBP may optimize storage space for message links by only storing the fields that differ between the fields and the original message. Nevertheless you always have to specify the whole message to write a link and you will always get the complete message when reading a link. All links to a message must consist of the same fields as the original message, but the contents of the fields may differ. There are two sorts of message-links, hardlinks and softlinks. Softlinks describe messages that have some fields in common (at least the Message-ID), but are really treated as individual messages. E.g. different parts of a splitted large message. Hardlinks, on the other hand, are treated as one message wherever possible. I.e. if you read one hardlinked message, all the other links will be marked as old, too. RFC crosspostings, for instance, should be made hardlinks. WAutoBounce : LONG If the msg to be written is addressed to a local user that doesn't exist or to an address that no exporter can export, there are two possible behaviours possible for the MBP: a) reject the message using error-no "NoReader", expecting the client to care about the undeliverable message b) keep the message, forwarding it to the local sysop or some kind of 'bounce-daemon', so that the writing client needs not to care about the message any more. This tag allowes to specify the desired behaviour, data=0 forces a), data=1 forces b). If this tag is not specified, the MBP will choose the behaviour as it wishes, maybe depending on whether the writing user is an exporter or not. WHide : LONG In some cases it might be desirable to write a message that can only by read by exporters and not by simple users, or the other way round. For instance control-messages that are of no interest to users by must be distributed over the net. Setting data to 0 is the same as the default. data=1 means that only exporters may view and read the message, data=2 makes the message invisible to exporters and only accessible to simple users. WHdrFill, WTxtFill : LONG specify how many bytes to reserve for later changes in the header/text of the message. The MBP may not be able to change an existing message if the change would increase the overall size (maybe after compression) of the message. Since such changes are neccessary in some special cases, the MBP can be told to reserve some space when writing a message the first time. Reserving more than actually needed is not a good idea, since it decreases performance and wastes space. The writer of a message usually should know whether or not he will change the message later on and to what extend he will increase the size of the message. WNoUpdate : LONG when writing a message, the 'Old'-flag in your user-status for the new message will usually be set. If you don't want this, use this tag and set its data to 1. RESULT msgNum - Number of the written message or NULL on failure. NOTES Changing an old message: You must _always_ give a complete message to WriteUMSMsg(), even when changing an old one! The MBP needs this to detect all changes made to the old message, including changed, added or deleted fields. Thus you need to read a message prior to changing it. Use RTextFields and WTextField for ReadUMSMsg() and WriteUMSMsg() when changing an old message! Otherwise you will loose fields unknown to you allication that might be still important to other applications! You may not be allowed to change certain fields of an existing message. Most likely those fields that are used by the MBP to compute all the users access-rights will be prohibited to change. SEE ALSO utility/tagitem.h