PMDF Programmer's Reference Manual
Previous Next Contents Index

PMDFgetChannelName

Obtain the name of the channel to be processed.

PASCAL

status = PMDF_get_channel_name

(channel, channel_len, keywords1, reserved)

argument information
Argument Data type Access Mechanism
channel descriptor read/write reference
channel_len unsigned word write reference
keywords1 unsigned longword write reference
reserved unsigned longword write reference

C

status = PMDFgetChannelName

(channel, channel_len, keywords1, reserved)

argument information 


int PMDFgetChannelName(char         *channel, 
                       int          *channel_len, 
                       unsigned int *keywords1, 
                       unsigned int *reserved)

Arguments

channel

String to receive the channel name. Must be at least CHANLENGTH bytes in length for PMDF_get_channel_name or CHANLENGTH+1 bytes for PMDFgetChannelName.

channel_len

Length in bytes of the returned channel name. Callers using PMDFgetChannelName must, on input, supply the maximum length in bytes of channel.

keywords1

Unsigned longword of bit flags describing various channel options set with channel keywords. This argument can be omitted.

reserved

Unsigned longword argument reserved for future use. Not used at present. This argument can be omitted.

Description

Channel programs typically service one or more instances of a channel, each instance having a distinct name which is specified in the PMDF configuration file. For example, a master (outbound) PhoneNet over DECnet channel program services all channels with names of the form dn_x where x distinguishes between each instance of a master PhoneNet over DECnet channel (e.g., dn_node1, dn_node2, etc.). The routine PMDFgetChannelName can be used by channel programs to determine which instance of a channel they are servicing; i.e., to determine the name of the particular channel they are processing. Channel programs which enqueue mail or can return messages typically need to know the name of the particular channel they are processing. This channel name is then used when PMDFstartMessageEnvelope or PMDFreturnMessage is called. In some cases, it can be necessary to hard-code a channel name into a program or otherwise obtain the channel name by a means other than PMDFgetChannelName. For instance, the channel name for TCP/IP slave channels is specified at compile time, and PhoneNet slave channels prompt for the name of the channel they are to process. In such cases, PMDFgetChannelName should not be used. When specified, bits in the optional keywords1 argument will be set as follows:
Bits Usage
0, 1 These two bits specify whether or not the headerbottom, headerinc, or headeromit channel keywords have been specified:
  • Bit 0 = 0, bit 1 = 0. headeromit: discard the message's header.
  • Bit 0 = 1, bit 1 = 0. headerinc: preserve the message header and keep it at the top of the message. This is the default case when none of these three channel keywords have been applied to the channel.
  • Bit 0 = 0, bit 1 = 1. headerbottom: preserve the message header but place it at the bottom of the message.
2 When set, indicates that the master_debug keyword was specified for this channel.
3 When set, indicates that the slave_debug keyword was specified for this channel.
4, 5 These two bits specify whether or not the exquota, holdexquota, or noexquota channel keywords have been specified:
  • Bit 4 = 0, bit 5 = 0. noexquota: return the message as undeliverable if the recipient is over quota.
  • Bit 4 = 1, bit 5 = 0. holdexquota: defer delivery of the message if the recipient is over quota.
  • Bit 4 = 0, bit 5 = 1. exquota: deliver the message to the recipient even if they are over quota.
Bit 0 is the least significant bit.
Note that all other channel keywords which can be applied to the channel are automatically handled by PMDF. On OpenVMS systems, the actual name of the particular channel being processed is specified by the logical PMDF_CHANNEL. The translation value of this logical gives the name of the channel being processed. On UNIX and Windows systems, the PMDF_CHANNEL environment variable is instead used with the equivalence value of the variable being the name of the channel.

Return Values

PMDF__OK Normal, successful completion.
PMDF__FATERRLIB Call to LIB$SCOPY_R_DX failed owing to a fatal internal error in the OpenVMS Run Time Library. Channel name not returned.
PMDF__INSVIRMEM Insufficient virtual memory: call to LIB$GET_VM made by LIB$SCOPY_R_DX has failed. Channel name not returned.
PMDF__INVSTRDES Invalid string descriptor for channel: descriptor has an invalid value in its DSC$B_CLASS field. Channel name not returned.
PMDF__NOCHANNEL Either the channel name cannot be determined, or the channel cannot be located in the configuration file.
PMDF__STRTRU Supplied string was too long; value truncated to fit.

Previous Next Contents Index