NAME

     imctr_get, imctr_free, imctr_load  -  MTA  channel  counters
     utilities.


SYNOPSIS

     #include <imta.h>

     int imctr_load(imctr_t *ctr, char *channel);

     int imctr_get(imctr_t ctr, int index, imctr_type_t  counter,
     char **channel);

     void imctr_free(imctr_t ctr);


DESCRIPTION

     The SIMS IMTA accumulates in the form of counters or message
     traffic  statistics  for each of its channels. These statis-
     tics, referred to as "channel counters," correspond to those
     used  by  the  Mail  Monitoring  MIB (RFC 1566) with an IMTA
     channel representing a "group" as defined by RFC 1566.

     imctr_load() may be used to gather these counters for one or
     more  channels specified by channel.  To obtain counters for
     more than one channel at a time, use wild cards in the chan-
     nel  name.   The  only wild-card character available is "*".
     It stands for 0 or more characters.  For instance, to obtain
     counters for all TCP/IP channels use the name "tcp_*". Simi-
     larly, to obtain counters for all  channels,  use  the  name
     "*".  imctr_load()  returns  the number of channels matching
     channel for which counters were found.

     Once the counters have  been  gathered,  individual  channel
     counters  may  then be obtained by calling imctr_get().  ctr
     is the imctr_t handle on the counters  datastructures  gath-
     ered  with  a previous call.  If the channel argument passed
     to imctr_load() led to gathering counters for more than  one
     channel,  the  counters corresponding to each of these chan-
     nels can be retrieved  by  using  values  of  index  located
     between  0  and  the  value returned by imctr_load() less 1.
     each call places the name of the corresponding channel in  a
     buffer  referenced  by  channel.  counter must be set to the
     type of counter desired.  The available types are:

     IMCTR_RECEIVED_MSGS
                       cumulative count of messages  enqueued  to
                       the channel

     IMCTR_SUBMITTED_MSGS
                       cumulative count of messages  enqueued  by
                       the channel

     IMCTR_STORED_MSGS total number of messages currently  stored
                       for the channel

     IMCTR_DELIVERED_MSGS
                       cumulative count  of messages dequeued  by
                       the channel

     IMCTR_REJECTED_MSGS
                       cumulative count of messages  which,  upon
                       trying to be enqueued to the channel, were
                       rejected.

     IMCTR_FAILED_MSGS cumulative count of messages  enqueued  to
                       the  channel which, when processed, failed
                       to be delivered for one or more recipients
                       owing  to  permanent errors of some sort (
                       e.g., invalid recipient address).

     IMCTR_ATTEMPTED_MSGS
                       cumulative count of messages  enqueued  to
                       the   channel   whose  delivery  has  been
                       attempted.

     IMCTR_RECEIVED_VOLUME
                       cumulative volume of messages enqueued  to
                       the channel as measured in Kilobytes

     IMCTR_SUBMITTED_VOLUME
                       cumulative volume of messages enqueued  by
                       the channel as measured in Kilobytes

     IMCTR_STORED_VOLUME
                       volume of messages  currently  stored  for
                       the channel as measured in Kilobytes

     IMCTR_DELIVERED_VOLUME
                       cumulative volume of messages dequeued  by
                       the channel as measured in Kilobytes

     IMCTR_REJECTED_VOLUME
                       cumulative volume of messages which,  upon
                       trying to be enqueued to the channel, were
                       rejected.

     IMCTR_FAILED_VOLUME
                       cumulative volume of messages enqueued  to
                       the  channel which, when processed, failed
                       to be delivered for one or more recipients
                       owing  to  permanent errors of some sort (
                       e.g., invalid recipient address).

     IMCTR_ATTEMPTED_VOLUME
                       cumulative volume of messages enqueued  to
                       the   channel   whose  delivery  has  been
                       attempted.

     IMCTR_RECEIVED_RCPTS
                       total number of  recipients  specified  in
                       all messages enqueued to the channel

     IMCTR_SUBMITTED_RCPTS
                       total number of  recipients  specified  in
                       all messages enqueued by the channel

     IMCTR_STORED_RCPTS
                       total number of  recipients  specified  in
                       all  messages  currently  stored  for  the
                       channel

     IMCTR_DELIVERED_RCPTS
                       total number of  recipients  specified  in
                       all messages delivered by the channel

     IMCTR_REJECTED_RCPTS
                       cumulative count  of  recipient  addresses
                       which,  upon  trying to be enqueued to the
                       channel, were rejected.

     IMCTR_FAILED_RCPTS
                       cumulative count of recipients enqueued to
                       the  channel which, when processed, failed
                       to be delivered owing to permanent  errors
                       of  some  sort  (  e.g., invalid recipient
                       address).

     IMCTR_ATTEMPTED_RCPTS
                       cumulative count of recipients enqueued to
                       the   channel   whose  delivery  has  been
                       attempted.



     After the counters have been used, the memory  allocated  to
     store  the  counters  must  be freed with imctr_free().  The
     argument  ctr  points  to  the  channel  counters  structure
     returned by a previous call to imctr_get().


RETURN VALUES

     If successful, imctr_load returns  the  number  of  channels
     matching channel for which counters were found.

     If  successful,  imctr_get  returns  the  requested  counter
     value.


     Otherwise, these functions can fail for one of the following
     reasons:

     IMRC_INVALID_COUNTER_TYPE
                       The counter requested via  imctr_get()  is
                       unknown.

     IMRC_OUT_OF_MEMORY
                       The  system  is  out   for   memory,   and
                       imctr_load()  is  not able to allocate the
                       necessary values.

     IMRC_LOCK_ERROR   imctr_load() fails due to a contention  to
                       access counters information in the MTA.

     IMRC_CHANNEL_NAME_TOO_LONG
                       The  string  argument  channel  passed  to
                       imctr_load() is longer than IM_CHANNEL_LEN
                       bytes.


ATTRIBUTES

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


SEE ALSO

     imta.cnf(4).