PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Obtain accumulated counters for one or more channels.

VMS FORMAT

status = PMDF_get_channel_counters

(channel, counters, count)

C FORMAT

status = PMDFgetChannelCounters

(channel, channel_len, timeout, counters, count)

int PMDFgetChannelCounters (channel, channel_len, timeout, 
                            counters, count) 
         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 may contain wild card characters. Length of the string, in bytes, may 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 PMDF_get_channel_counters routine may 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 PMDF_dispose_channel_counters 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 may vary from system to system. The size of a PMDF block is controlled with the BLOCK _SIZE PMDF option. The PMDF _get _block _size routine may 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 NT systems at present.