PMDF Programmer's Reference Manual


Previous Next Contents Index


PMDFgetChannelCounters

Obtain accumulated counters for one or more channels.

PASCAL

status = PMDF_get_channel_counters

(channel, counters, count)

argument information
Argument Data type Access Mechanism
channel descriptor read reference
timeout signed longword read value
counters counters pointer write reference
count signed longword write reference

C

status = PMDFgetChannelCounters

(channel, channel_len, timeout, counters, count)

argument information


int PMDFgetChannelCounters(char                   *channel, 
                           int                 channel_len, 
                           int                     timeout, 
                           PMDF_channel_counters **counters, 
                           int                    *count) 


Arguments

channel

String containing the name of the channel to retrieve counters for. The name can contain wild card characters. Length of the string, in bytes, can not exceed CHANLENGTH.

channel_len

Length in bytes of the channel name.

timeout

Maximum time, in seconds, to wait for counters to be synchronized.

counters

Pointer to list of channel counters. The format of each entry in the list is described in the Description section below.

count

Count of the number of channels for which counters have been returned.

Description

PMDF accumulates in the form of counters message traffic statistics for each of its channels. These statistics, referred to as "channel counters", correspond to those used by the Mail Monitoring MIB (RFC 1566) with a PMDF channel representing a "group" as defined by RFC 1566. The PMDFgetChannelCounters routine can be used to read these counters for one or more channels. To obtain counters for more than one channel at a time, use wild cards in the channel name. For instance, to obtain counters for all TCP/IP channels use the name *tcp*. Similarly, to obtain counters for all channels, use the name *. The counters are returned as a list pointed at by the counters argument. The list should be disposed of with the PMDFdisposeChannelCounters routine. Each entry in the list has the structure


#define CHANLENGTH 32 
typedef struct PMDF_channel_counters_s { 
  char                            channel_name[CHANLENGTH+1]; 
  int                             received_messages; 
  int                             submitted_messages; 
  int                             stored_messages; 
  int                             delivered_messages; 
  int                             received_volume; 
  int                             submitted_volume;                            
  int                             stored_volume; 
  int                             delivered_volume; 
  int                             received_recipients; 
  int                             submitted_recipients; 
  int                             stored_recipients; 
  int                             delivered_recipients; 
  struct PMDF_channel_counters_s *next; 
  int                             rejected_messages; 
  int                             failed_messages; 
  int                             attempted_messages; 
  int                             rejected_volume; 
  int                             failed_volume; 
  int                             attempted_volume; 
  int                             rejected_recipients; 
  int                             failed_recipients; 
  int                             attempted_recipients; 
  int                             delivered_first_messages; 
  int                             delivered_first_queue_count; 
  int                             delivered_first_queue_time; 
  int                             delivered_queue_count; 
  int                             delivered_queue_time; 
} PMDF_channel_counters; 
This structure is predeclared as PMDF_channel_stats in the C apidef.h header and Pascal apidef.pen environment files. With the exception of the channel_name and next fields, each field is a long, signed integer value. The channel_name field is CHANLENGTH+1 bytes long and gives the name of the channel corresponding to the counters in the entry. The next field is a pointer to another list entry. The end of the list is signified by a next field with a zero (nil) value. The interpretation of each field is given in the Table 1-5.

Table 1-5 Channel Counters List Entry
Field name Type Description
channel_name string The name of the channel stored in a CHANLENGTH+1 byte long string; PMDFgetChannelCounters will zero terminate the string.
received_messages signed longword The cumulative count of messages enqueued to the channel.
submitted_messages signed longword The cumulative count of messages enqueued by the channel.
stored_messages signed longword The current count of messages stored for the channel
delivered_messages signed longword The cumulative count of messages dequeued by the channel.
received_volume signed longword The cumulative volume of messages enqueued to the channel.
submitted_volume signed longword The cumulative volume of messages enqueued by the channel.
stored_volume signed longword The current volume of messages stored for the channel.
delivered_volume signed longword The cumulative volume of messages dequeued by the channel.
received_recipients signed longword The cumulative count of recipients specified in all messages enqueued to the channel.
submitted_recipients signed longword The cumulative count of recipients specified in all messages enqueued by the channel.
stored_recipients signed longword The current count of recipients specified in all messages currently stored for the channel.
delivered_recipients signed longword The cumulative count of recipients specified in all messages dequeued by the channel.
next pointer Pointer to the next list entry of channel counters.
rejected_messages signed longword The cumulative count of messages which, upon trying to be enqueued to the channel, were rejected.
failed_messages signed longword The 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).
attempted_messages signed longword The cumulative count of messages enqueued to the channel whose delivery has been attempted.
rejected_volume signed longword The cumulative volume of messages which, upon trying to be enqueued to the channel, were rejected.
failed_volume signed longword The 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).
attempted_volume signed longword The cumulative volume of messages enqueued to the channel whose delivery has been attempted.
rejected_recipients signed longword The cumulative count of recipient addresses which, upon trying to be enqueued to the channel, were rejected.
failed_recipients signed longword The 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).
attempted_recipients signed longword The cumulative count of recipients enqueued to the channel whose delivery has been attempted.
delivered_first_messages signed longword The cumulative count of messages enqueued to the channel which were successfully delivered (or returned as undeliverable) on their first processing attempt.
delivered_first_queue_count signed longword Cumulative count of first message delivery attempts made by the channel. When this value is less then received_messages, it means that delivery has not yet been attempted for all received messages. This is not unusual: this value is expected to lag behind received_messages.
delivered_first_queue_time signed longword Cumulative count of elapsed seconds between when a message is enqueued and when processing of its first delivery attempt completes. The result of dividing delivered_first_queue_time by delivered_first_queue_count gives the average amount of time in seconds spent by a message in the processing queues as it awaits its initial delivery attempt.
delivered_queue_count signed longword Cumulative count of message delivery attempts made by the channel.
delivered_queue_time signed longword Cumulative count of elapsed seconds between when a message is enqueued and when it is finally removed from the channel queue. The result of dividing delivered_queue_time by delivered_queue_count gives the average amount of time in seconds spent by a message in the processing queues.


Note: All volumes are measured in units of PMDF blocks. A PMDF block is, by default, 1024 bytes. However, this size can vary from system to system. The size of a PMDF block is controlled with the BLOCK _SIZE PMDF option. The PMDFgetBlockSize routine can be used to determine the current size of a PMDF block; i.e., the setting of the BLOCK _SIZE option.
The timeout argument specifies the maximum time, in seconds, to wait for node-specific caches of counters to be synchronized with the cluster-wide database of counters. If the time limit is exceeded, then the cluster-wide counters will be returned as is, not necessarily up-to-date. Specify a value of zero to avoid waiting at all or a value of -1 to wait without a timeout. The timeout argument has no effect on UNIX and Windows systems at present.

Return Values

PMDF__OK Normal, successful completion.
PMDF__INVSTRDES Invalid string descriptor for channel: descriptor has an invalid value in its DSC$B_CLASS field. No counters returned.
PMDF__NO Cannot access the counters; an interlock could not be obtained after ten attempts. No counters returned.
PMDF__STRTRUERR Supplied channel name was too long; no counters returned.


Previous Next Contents Index