Obtain accumulated counters for one or more channels.

PASCAL

status = PMDF_get_channel_counters

(channel, counters, count)

C

status = PMDFgetChannelCounters

(channel, channel_len, timeout, counters, count)

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.

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.