NAME
       UMSSelect -- Select messages.

   SYNOPSIS
       count = UMSSelect( login, tags )
        D0                 D2     D3

       LONG UMSSelect( LONG, struct TagItem * );

       count = UMSSelectTags( login, tag1, ... )

       LONG UMSSelectTags( LONG, ULONG, ... );

   FUNCTION
         Select  messages  in  the  MB according to various criteria.  To
       'select'  here means to set or unset some flags, which then can be
       used by  UMSSearch(), stored or transferred to another user.

         UMSSelect()  can  only  do  one operation upon every invocation.
       An  operation  usually  looks  for  all messages that fullfill the
       specified criteria and then selects them in a specified way.

         When  you  want  to  select  messages  by  different,  logically
       combined criteria, you may need to call UMSSelect() more than once
       and  use  some  temporary  flags.  However, very few calls to this
       functions usually should suffice.

   INPUTS

         The  following  tags  control  the selection of messages.  Thus,
       they somehow specify the 'output' of the select operation.

         SelWriteGlobal        : (none)
               manipulate global flags on the selected messages.

         SelWriteLocal         : (none)
               manipulate your local login-flags.

         SelWriteUser          : STRPTR
               manipulate another user's user-flags. You must specify the
       users name (or alias).

         SelWriteGlobal,   SelWriteLocal   and  SelWriteUser  are  mutual
       exclusive  --  you can  manipulate  only one flag-table at a time.
       When  specifying  none  of  these  tags,  your  user-flags will be
       manipulated as default.

         SelSet,
         SelUnset              : LONGBITS
               on  each selected message the 'SelUnset' flags are cleared
       and then the 'SelSet' flags are set.
       ['status = (status & ~unset) | set;']
               When writing global- or user-flags, you are not allowed to
       manipulate all possible flags.  See <ums.h> for protected flags.


         The  following  tags control what and how messages are selected,
       the 'input' and 'modes' of the select operation.

         SelStart,
         SelStop               : LONG
               Limit  the number of messages to be processed.  The select
       operation  will start with the message indicated by 'SelStart' and
       stop  before  the  'SelStop'  message.   In  other words, start is
       included  and  stop  is  excluded.
               (0 < start <= messages to be processed < stop)
               This  was different and partly buggy in MBP versions prior
       to V10.16.
               If  no  'SelStart' is specified, the operation starts with
       the  first  message;  if  no 'SelStop' is specified, the operation
       stops at the last existing message.


         The following seven operations are mutually exclusive:

       1) select by status

         SelReadGlobal         : (none)
         SelReadLocal          : (none)
         SelReadUser           : STRPTR
               like   SelWriteGlobal,  SelWriteLocal,  SelWriteUser,  but
       specifys  which  flags to look at.  Again, your user-flags are the
       default.

         SelMask,
         SelMatch              : LONGBITS
               specify  a  mask and a match.  If (status & mask) == match
       [status * mask = match], the message will be selected.

         SelParent             : (node)
              with   this   tag   specified,   each   message's  'parent'
       (reference;  ->  reply-chaining)  will be inspected instead of its
       own status.

       2) select by date

         SelDate               : LONG
               the  messages'  dates  are compared with the supplied date
       (in  seconds  since  1.1.1978)  and  only the younger ones will be
       selected.

       4) select a tree

         SelTree               : LONG
               you  must specify  the number of a message here.  Then all
       messages being in the same reply-tree will be selected.

       5) select a sub-tree

         SelSubTree            : LONG
               like  SelTree,  but  only  the  subtree  (the one with the
       specified message as its root) is selected.

       6) select a single message

         SelMsg                : LONG
               select only the specified message.

       7) select by text

         WMsgText, ..
         WMsgText + 127        : STRPTR
               when  you  specify one of these tags, the function selects
       all  messages  which  have  the  supplied  string in the specified
       field.  The strings are compared case-INsensitive.

         SelQuick              : (none)
               when  this tag is specified, 'quick-search' is enabled for
       selecting  texts.  This means that only some CRCs on the texts are
       compared.   This  makes  it  possible  to  select  also some wrong
       messages.   Yet,  due to the usage of 32-bit CRCs, the probability
       of  selecting  wrong  messages  is  VERY low, you most likely will
       never experience this case.
               As  'quick-search'  does  not usually need to access mass-
       storage, it is VERY FAST.

   RESULT
       count - how many messages have been selected.  Zero, when no
               message has been selected or an error has occured.

   EXAMPLE
         See SelectMail.c for examples on how to use this function.

   NOTES
         Although  LONGBITS  are  used  in  the  definition,  the current
       implementation only uses/supports the lower 16 bits.

   SEE ALSO
        UMSSearch(), <usm.h>, </demo/SelectMail.c>