NAME

     immd_defer - Defers a message for later processing.


SYNOPSIS

     #include <imta.h>

     int immd_defer(immd_t md, int  increment, char *reason);


DESCRIPTION

     immd_defer() provides a simple way to defer  a  message  for
     all recipients. The same behavior can be obtained by setting
     the disposition to IM_DISP_DEFERRED for all recipient  while
     calling                        immd_recipient_disposition().
     immd_recipient_disposition() must be used when deferrinfg  a
     message for only some of the recipients.

     The deferred message will be left in the message queues  for
     processing  by  a  subsequent processing job. If the message
     continues to remain in the message queues  long  enough,  it
     will  be  returned automatically. See the message return and
     bouncing discussions in the "SIMS Administrator's Guide" for
     further details on this subject.

     Typically message processing is deferred  when  a  temporary
     error (e.g., network link down, etc.) or an unexpected error
     affecting the message as a whole occurs. In the event  of  a
     permanent error, the disposition of each and every recipient
     should   be   set   to   an    appropriate    value    using
     immd_recipient_disposition().

     Each time a message is deferred, an explanation of  why  the
     message  is  being  deferred  may be placed in the message's
     "delivery failure log".  This failure log can be  read  with
     immd_read_failure_log() when the previously deferred message
     is again accessed.  Should the message  be  returned  as  an
     undeliverable  message by SIMS's MTA, a copy of the log will
     be included with the returned message. The log is only  gen-
     erated  if you specify the reason argument.  If this parame-
     ter is never used for a given  message,  then  that  message
     will  have  no  delivery  failure  log.  increment Specifies
     whether or not the message  retry  count  should  be  incre-
     mented.  When  reason is specified (not NULL), this argument
     is ignored and the message retry count incremented. No  firm
     guidelines exist to determine when the retry count should or
     should not be incremented. In general, however, it should be
     incremented.  This  helps postmasters to spot messages which
     have defied delivery.


RETURN VALUES

     immd_defer() return IMRC_OK when successful, and one of  the
     following error codes otherwise.

     IMRC_BAD_CONTEXT
                 The dequeue context md has not been  initialized
                 or  has  been  corrupted.  Make sure imme_init()
                 has been previously called.

     IMRC_TEXT_TRUNCATED
                 The reason string contained more than IM_LOG_LEN
                 characters, so it has been truncated to fit.


ATTRIBUTES

               _______________________________________
              |   Attribute Type   |  Attribute Value|
              |____________________|_________________|
              | Architecture       |  sparc, x86     |
              |____________________|_________________|
              | Availability       |  SUNWimsdk      |
              |____________________|_________________|
              | MT-Level           |  MT-Safe        |
              |____________________|_________________|
              | Interface Stability|  Stable         |
              |____________________|_________________|


SEE ALSO

     immd_init(3), immd_recipient_disposition(3),  imta_error(3),
     immd_read_failure_log(3)