PMDF Programmer's Reference Manual


Previous Next Contents Index

2.7 PMDF_send Routine Description

In the following description, the string lengths CHANLENGTH and ALFA_SIZE are mentioned. These values are defined in the API include files and listed in Table 1-2.


PMDF_send

Send a message.

Format

status = PMDF_send (item_list)

argument information
Argument Data type Access Mechanism
item_list item list read reference

Arguments

item_list

Item list specifying actions to be taken by PMDF_send. The item_list argument is the address of a list of item descriptors, each of which specifies an action and provides the information needed to perform that action. The list of item descriptors is terminated with an entry with the PMDF_END_LIST item code.4 Each item descriptor has the following C-style structure declaration:


struct { 
  int   item_code; 
  void *item_address; 
  int   reserved; 
  int   item_length; 
} PMDF_item_list; 

PMDF_send Item Descriptor Fields

item_code

A longword (4 bytes) containing a user-supplied symbolic code specifying an action to be taken by PMDF_send. The include files described in Section 1.11 defines these codes. A description of each item code follows this list of item descriptor fields.

item_address

A longword (4 bytes) containing the user-supplied address of a character string to be used in conjunction with the action specified by the item_code field. Not all actions require that an item_address be specified.

item_length

A longword (4 bytes) containing the user-supplied length of the character string pointed at by item_address. Not all actions require that an item_address be specified.

PMDF_send Item Codes

PMDF_ADDRESS_STATUS

Return status messages for each To:, Cc:, and Bcc: address specified with the PMDF_*TO, PMDF_*CC, and PMDF_*BCC item codes. When this item code is specified, all address strings specified with PMDF_*TO, PMDF_*CC, and PMDF_*BCC must have a maximum length of at least ALFA_SIZE bytes. On input to PMDF_send the string contains an address whose length is given by the associated item_length field. On output, PMDF_send will write the status of that address back to the address string overwriting the address stored in that string. (The original address will be given in the text of the status message.) Also on output, the magnitude of the value contained in the item_length field will contain the length of the status message. If the value contained in the item_length field is positive, then the address was legal; if the value is negative then the address was illegal. See Section 2.5.3 for example programs which use this feature. For each address built with PMDF_FAX_TO, PMDF_FAX_CC, PMDF_FAX_BCC, PMDF_PRT_TO, PMDF_PRT_CC, PMDF_PRT_BCC the address of a string of length at least ALFA_SIZE bytes must be specified in the item_address field. On output, the success or error message associated with the address will be returned in this string. The value in the item_length field will give the length of the status message as well as indicate if the address was legal or illegal. The output strings will not be zero terminated. The item_address and item_length fields are ignored by this action.

PMDF_BCC

PMDF_ENV_BCC

PMDF_HDR_BCC

Specify a Bcc: address. The item_address and item_length fields specify the address and length of a string containing a Bcc: address. The length of the address can not exceed ALFA_SIZE bytes. PMDF_BCC is used to specify a blind carbon copy (Bcc:) address which should appear in both the message's header and envelope. PMDF_ENV_BCC is used to specify an envelope-only Bcc: address (i.e., an active recipient) which should not appear in the message's header. PMDF_HDR_BCC is used to specify a header-only Bcc: address (i.e., an inactive recipient) which should only appear in the message's header. If PMDF_ADDRESS_STATUS is specified, then this string must have a maximum size of at least ALFA_SIZE bytes.

PMDF_BLANK

When processing multiple input sources, insert a blank line between the input from each source. Ordinarily, the input files are appended one after the other with no delimiters or separators. This is the action selected with the PMDF_NOBLANK item code. By specifying the PMDF_BLANK action, PMDF_send will insert a blank line between each input file. This is especially useful when the first input file is to be treated as a source of header information and the second as the message body or part thereof. This then produces the requisite blank line between the message header and body. The item_address and item_length fields are ignored by this action.

PMDF_CC

PMDF_ENV_CC

PMDF_HDR_CC

Specify a Cc: address. The item_address and item_length fields specify the address and length of a string containing a Cc: address. The length of the address can not exceed ALFA_SIZE bytes. PMDF_CC is used to specify a carbon copy (Cc:) address which should appear in both the message's header and envelope. PMDF_ENV_CC is used to specify an envelope-only Cc: address (i.e., an active recipient) which should not appear in the message's header. PMDF_HDR_CC is used to specify a header-only Cc: address (i.e., an inactive recipient) which should only appear in the message's header. If PMDF_ADDRESS_STATUS is specified, then this string must have a maximum size of at least ALFA_SIZE bytes.

PMDF_CHAIN

PMDF_send immediately begins processing the list of item descriptors pointed at by item_address. This new list will be used immediately; any remaining items in the current list will be ignored. The item_length field should contain the value 4, the length of a longword in bytes.

PMDF_CHANNEL

Specify the channel to act as when enqueuing the message. If not specified, then mail will be enqueued as though sent from the local, l, channel. The item_address and item_length fields specify the address and length of a text string containing the name of the channel to act as. The length of the string can not exceed CHANLENGTH bytes.

PMDF_COMMENTS

Specify the body of a Comments: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Comments: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Comments: body can be specified. Additional Comments: header lines can be created with PMDF_EXTRA_HEADER.

PMDF_CONTENT_FILENAME

PMDF_NOCONTENT_FILENAME

When PMDF_CONTENT_FILENAME is specified, the name of the message input file will be included as a parameter in the MIME Content-type: header line. This action, when specified, will hold for all subsequent input files until a PMDF_NOCONTENT_FILENAME action is seen in the same item list. PMDF_NOCONTENT_FILENAME is the default. The item_address and item_length fields can be used to specify the file name, overriding the name of the input file.

PMDF_CONTENT_TYPE

Specify the body of a Content-type: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Content-type: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Content-type: body can be specified.

PMDF_DELIVERY_RECEIPT_TO

Specify the body of a Delivery-receipt-to: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Delivery-receipt-to: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Delivery-receipt-to: body can be specified.

PMDF_ENC_BASE64

PMDF_ENC_COMPRESSED_BASE64

Encode data from all subsequent input sources using MIME's BASE64 encoding. In the case of PMDF_ENC_COMPRESSED_BASE64, the data is first compressed using GNU zip. This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_BASE85

Encode data from all subsequent input sources using Adobe's ASCII85 encoding (BASE85). This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_BINHEX

Encode data from all subsequent input sources using the BINHEX encoding. This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_BTOA

Encode data from all subsequent input sources using the UNIX btoa encoding. This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_COMPRESSED_BINARY

Compress the data with GNU zip. No other encoding of the data will be done. This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_COMPRESSED_UUENCODE

PMDF_ENC_UUENCODE

Encode data from all subsequent input sources using UUENCODE. In the case of PMDF_ENC_COMPRESSED_UUENCODE, the data is first compressed using GNU zip. This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_HEXADECIMAL

Encode data from all subsequent input sources using a hexadecimal encoding. This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_NONE

Data from all subsequent input sources is left unencoded (i.e., not encoded). This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_QUOTED_PRINTABLE

Encode data from all subsequent input sources using MIME's quoted printable encoding. This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_ENC_UNKNOWN

Data from all subsequent input sources is left unencoded (i.e., not encoded). This setting can be changed with any of the other PMDF_ENC_ item codes. The default encoding is PMDF_ENC_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_END_LIST

Terminate an item list. This item code, when encountered, signals the end of the item list. The item_address and item_length fields are ignored by this action.

PMDF_ENV_FROM

Specify the envelope From: address to associate with a message. The item_address and item_length fields specify the address and length of a text string containing the envelope From: address to use for the message submission. The length of the string can not exceed ALFA_SIZE bytes. Only one envelope From: address can be specified. The PMDF_ENV_FROM action should be used when the envelope From: address is not a local address. When the address is a local address, then merely the user name should be specified using the PMDF_USER action. If this action and the PMDF_USER actions are not specified, then the user name associated with the current process will be used. Can not be used in conjunction with the PMDF_USER or PMDF_SUB_USER item codes.

PMDF_ERRORS_TO

Specify the body of an Errors-to: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of an Errors-to: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Errors-to: body can be specified.

PMDF_EXTRA_HEADER

Specify an additional header line to include in the message header. The item_address and item_length fields specify the address and length of the header line (field name and body) to place in the message header. The length of the string can not exceed ALFA_SIZE bytes. Any number of header lines can be added; use one item list entry per header line. PMDF_EXTRA_HEADER is intended to be used to add header lines not supported by other item codes (e.g., PMDF_SUBJECT, PMDF_KEYWORDS, etc., or to specify additional instances of header lines which can multiple times (e.g., Comments: header lines).

PMDF_FAX_AFTER

Specify the value to use with an AFTER attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_AT

Specify the value to use with an AT attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_AUTH

Specify the value to use with an AUTH attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_BCC

PMDF_FAX_CC

PMDF_FAX_TO

Begin the specification of a FAX To:, Cc:, or Bcc: address. FAX addresses can be composed, one attribute at a time, using the PMDF_FAX_ item codes. The attribute-value pair list is automatically assembled from the specified attribute-value pairs, properly quoted, and the domain specification appended. The actual assembly of the address is initiated when either the item list is terminated or when another PMDF_*TO, PMDF_*CC, or PMDF_*BCC action is encountered. The FAX address to be built will be treated as a To: address when PMDF_FAX_TO is specified, as a Cc: address when PMDF_FAX_CC is specified, and as a Bcc: address when PMDF_FAX_BCC is specified. The PMDF_FAX_DOMAIN and PMDF_FAX_FN actions must be specified for each FAX address to be assembled. The item_address and item_length fields are ignored by this action unless PMDF_ADDRESS_STATUS is specified in which case then the address of a string of length at least ALFA_SIZE bytes must be given in the item_address field.

PMDF_FAX_DOMAIN

Specify the domain name to associate with a FAX address which is being built up (e.g., text-fax.example.com). The item_address and item_length fields specify the address and length of a text string containing the domain name. The length of the string can not exceed ALFA_SIZE bytes. This action must be taken when composing a FAX address with the PMDF_FAX_ item codes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_FN

Specify the value to use with an FN attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. This action must be taken when composing a FAX address with the PMDF_FAX_ item codes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_FSI

Specify the value to use with an FSI attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_O

Specify the value to use with an O attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_OU

Specify the value to use with an OU attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_SETUP

Specify the value to use with a SETUP attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_SFN

Specify the value to use with a SFN attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_STN

Specify the value to use with a STN attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_TN

Specify the value to use with a TN attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FAX_TTI

Specify the value to use with a TTI attribute in a FAX address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_FAX_TO, PMDF_FAX_CC, or PMDF_FAX_BCC action must have appeared prior to using this action.

PMDF_FROM

Specify the address to use in the message header's From: header line. item_address and item_length fields specify the address and length of a text string containing the From: address. The length of the string can not exceed ALFA_SIZE bytes. Only one From: address can be specified. If this action is not used, then the From: header line will be derived from the envelope From: address.

PMDF_FRUIT_OF_THE_DAY

Specify the body of a Fruit-of-the-day: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Fruit-of-the-day: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Fruit-of-the-day: body can be specified.

PMDF_HDR_ADDRS

PMDF_HDR_NOADDRS

By default, PMDF_HDR_NOADDRS, recipient addresses must be explicitly specified and any addresses in a input header file will be ignored (but will still appear in the message header). Specify PMDF_HDR_ADDRS to request that the message also be sent to recipient addresses found in any input header files. The item_address and item_length fields are ignored by this action.

PMDF_HDR_FILE

Specify the name of an input file containing message header lines. The first input file can be a file containing a message header. In this case, it should be specified using this item code rather than PMDF_MSG_FILE. This will ensure that the input file receives the proper processing (e.g., is not encoded, accessed using text mode access, etc.). PMDF_send will use the header lines from the input file to form an initial message header. This initial header is then modified as necessary. This functionality is useful when forwarding mail. Note that any recipient addresses in the header file will be ignored unless PMDF_HDR_ADDRS is also specified. The item_address and item_length fields specify the address and length of a text string containing the input file's name. The length of the string can not exceed ALFA_SIZE bytes.

PMDF_HDR_RESENT

PMDF_HDR_NORESENT

The PMDF_HDR_RESENT action selects the default behavior whereby Resent- header lines are added as necessary to the message header when the associated header line appears in any input header files. For instance, a Resent-to: header line will be added if a To: header line already appears. Specify PMDF_HDR_NORESENT to cause additional addresses to be added to existing header lines rather than through the introduction of Resent- header lines. The item_address and item_length fields are ignored by this action.

PMDF_HDR_PROC

Specify the address of a procedure which will return, one line at a time, header lines for the message header. The item_address field specifies the address of the procedure to invoke. item_length must be set to 4, the length in bytes of a longword. The calling format which must be used by the procedure is given in Section 2.1.3.

PMDF_HDRMSG_FILE

Specify the name of an input file containing both the message header and message body. The content of the file represents an RFC 822 formatted message with at least one blank line separating the RFC 822 header from the message body. PMDF_send will use the header lines from the input file to form an initial message header. This initial header is then modified as necessary. The item_address and item_length fields specify the address and length of a text string containing the input file's name. The length of the string can not exceed ALFA_SIZE bytes.

PMDF_HDRMSG_PROC

Specify the address of a procedure which will return, one line at a time, each line of an RFC 822 formatted message. The RFC 822 header must come first, followed by at least one blank line, followed by the message body. The item_address field specifies the address of the procedure to invoke. item_length must be set to 4, the length in bytes of a longword. The calling format which must be used by the procedure is given in Section 2.1.3.

PMDF_IGNORE_ERRORS

Send the message as long as at least one To: address was okay and at least one input source was okay. By default, the message will not be sent if any of the To: addresses are illegal (e.g., bad syntax, restricted, unknown host, etc.) or if any of the input sources proved to be bad (e.g., could not open an input file). The item_address and item_length fields are ignored by this action.

PMDF_IMPORTANCE

Specify the body of an Importance: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of an Importance: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Importance: body can be specified.

PMDF_IS_CHANNEL

Ignore user-to-channel access checks when enqueuing mail. This should, in general, be used only by programs which do not enqueue mail in behalf of a user. The item_address and item_length fields are ignored by this action.

PMDF_IS_NOT_CHANNEL

Do not ignore user-to-channel access checks when enqueuing mail. This should, in general, be used by programs such as user agents which enqueue mail for users. The item_address and item_length fields are ignored by this action.

PMDF_KEYWORDS

Specify the body of a Keywords: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Keywords: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Keywords: body can be specified.

PMDF_MAX_BLOCKS

Specify the maximum number of blocks per message. If, when the message is enqueued, the message size exceeds this limit, then the message will be fragmented into smaller messages, each fragment no larger than the specified block size. The individual fragments are MIME compliant messages which use MIME's message/partial content type. MIME compliant mailers or user agents which receive the fragments can automatically re-assemble the fragmented message. (PMDF channels must be marked with the defragment keyword in order for automatic message re-assembly to occur.) The size of a block can vary from site to site --- sites can change this value from its default value of 1,024 bytes. Use the PMDF API routine PMDF_get_block_size to determine the size in bytes of a block. Or, alternatively, use the PMDF_MAX_BYTES item code instead. The item_address field specifies the address of a longword integer whose value is the maximum block size per message or message fragment. item_length must be set to 4, the length in bytes of a longword integer. By default, no limit is imposed. This default can be re-instated by specifying a value of -1. This limit can be simultaneously imposed with other limits.

PMDF_MAX_BYTES

Specify the maximum number of bytes per message. If, when the message is enqueued, the message size exceeds this limit, then the message will be fragmented into smaller messages, each fragment no larger than the specified byte size. The individual fragments are MIME compliant messages which use MIME's message/partial content type. MIME compliant mailers or user agents which receive the fragments can automatically re-assemble the fragmented message. (PMDF channels must be marked with the defragment keyword in order for automatic message re-assembly to occur.) The item_address field specifies the address of a longword integer whose value is the maximum bytes per message or message fragment. item_length must be set to 4, the length in bytes of a longword integer. By default, no limit is imposed. This default can be re-instated by using a value of -1. This limit can be simultaneously imposed with other limits.

PMDF_MAX_LINES

Specify the maximum number of message lines per message. If, when the message is enqueued, the number of message lines exceeds this limit, then the message will be fragmented into smaller messages, each fragment with no more than the specified number of lines. The individual fragments are MIME compliant messages which use MIME's message/partial content type. MIME compliant mailers or user agents which receive the fragments can automatically re-assemble the fragmented message. (PMDF channels must be marked with the defragment keyword in order for automatic message re-assembly to occur.) The item_address field specifies the address of a longword integer whose value is the maximum number of message lines per message or message fragment. item_length must be set to 4, the length in bytes of a longword integer. By default, no limit is imposed. This default can be re-instated by using a value of -1. This limit can be simultaneously imposed with other limits.

PMDF_MAX_TO

Specify the maximum number of envelope To: addresses per message copy. If, when the message is enqueued, the number of envelope To: addresses for the message exceeds this limit, then the message will be broken into multiple copies, each copy with no more than the specified number of envelope To: addresses. The item_address field specifies the address of a longword integer whose value is the maximum number of envelope To: addresses per message copy. item_length must be set to 4, the length in bytes of a longword integer. By default, no limit is imposed. This default can be re-instated by using a value of -1. This limit can be simultaneously imposed with other limits.

PMDF_MODE_BLOCK

Access subsequent input files using block mode I/O. This setting can be changed with any of the other PMDF_MODE_ item codes. The default access mode is that selected with PMDF_MODE_UNKNOWN. This access mode will not be applied to input procedures. On OpenVMS systems, this setting should be used for binary files. The item_address and item_length fields are ignored by this action.

PMDF_MODE_RECORD

Access subsequent input sources using record mode I/O. This setting can be changed with any of the other PMDF_MODE_ item codes. The default access mode is that selected with PMDF_MODE_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_MODE_RECORD_CRATTRIBUTE

Access subsequent input sources using record mode I/O preserving carriage return record terminators. This setting can be changed with any of the other PMDF_MODE_ item codes. The default access mode is that selected with PMDF_MODE_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_MODE_RECORD_CRLFATTRIBUTE

Access subsequent input sources using record mode I/O preserving carriage return, line feed record terminators. This setting can be changed with any of the other PMDF_MODE_ item codes. The default access mode is that selected with PMDF_MODE_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_MODE_RECORD_LFATTRIBUTE

Access subsequent input sources using record mode I/O preserving line feed record terminators. This setting can be changed with any of the other PMDF_MODE_ item codes. The default access mode is that selected with PMDF_MODE_UNKNOWN. The item_address and item_length fields are ignored by this action.

PMDF_MODE_TEXT

Access subsequent input sources using text mode I/O. This setting can be changed with any of the other PMDF_MODE_ item codes. The default access mode is that selected with PMDF_MODE_UNKNOWN. This setting or that selected with PMDF_MODE_UNKNOWN must be use for input files containing message header information and should be used for ordinary text files. The item_address and item_length fields are ignored by this action.

PMDF_MODE_UNKNOWN

Access subsequent input sources using text mode I/O. This setting can be changed with any of the other PMDF_MODE_ item codes. The default access mode is that selected with PMDF_MODE_UNKNOWN. This setting or that selected with PMDF_MODE_TEXT must be use for input sources containing message header information and should be used for ordinary text files. The item_address and item_length fields are ignored by this action.

PMDF_MSG_FILE

Specify an input file to read and include in the message body. The file will be read using the current access mode and encoded using the current encoding as specified by PMDF_MODE_ and PMDF_ENC_ item codes. The item_address and item_length fields specify the address and length of a text string containing the name of the input file. The length of the string can not exceed ALFA_SIZE bytes.

PMDF_MSG_PROC

Specify the address of a procedure which will return, one line at a time, data for the message body. Each line of input obtained from the procedure will be treated using the current access mode and encoded using the current encoding as specified by PMDF_MODE_ and PMDF_ENC_ item codes. Note, however, that the block access mode will not be applied to input procedures. The item_address field specifies the address of the procedure to invoke. item_length must be set to 4, the length in bytes of a longword integer. The calling format which must be used by the procedure is given in Section 2.1.3.

PMDF_NOADDRESS_ERRORS

Do not return status messages for To:, Cc:, and Bcc: addresses. This is the default setting. The strings containing To:, Cc:, and Bcc: addresses specified with PMDF_TO, PMDF_CC, PMDF_BCC, PMDF_ENV_TO, PMDF_ENV_CC, PMDF_ENV_BCC, PMDF_HDR_TO, PMDF_HDR_CC, and PMDF_HDR_BCC need only be long enough to contain the actual addresses. The item_address and item_length fields are ignored by this action.

PMDF_NOBLANK

When processing multiple input source, do not insert insert a blank line between the input from one source and the next. This is the default behavior: the input from each input source is appended one after the other with no delimiters or separators marking the transition between sources. The item_address and item_length fields are ignored by this action.

PMDF_NOIGNORE_ERRORS

Send the message only if all To: addresses are okay and all input sources are okay. This is the default. The item_address and item_length fields are ignored by this action.

PMDF_ORGANIZATION

Specify the body of an Organization: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of an Organization: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Organization: body can be specified.

PMDF_PRIORITY

Specify the body of a Priority: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Priority: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Priority: body can be specified.

PMDF_PRIV_DISABLE_PROC

The address of a procedure to invoke immediately after enqueuing a message so as to disable process privileges. See the description of the PMDF_PRIV_ENABLE_PROC item code for details on the use of this item code. This item code must be used in conjunction with the PMDF_PRIV_ENABLE_PROC item code. The item_length field is ignored by this action.

PMDF_PRIV_ENABLE_PROC

The address of a procedure to invoke immediately before enqueuing a message so as to enable process privileges. Privileges are required to enqueue messages. It is possible to provide PMDF_send with the address of two procedures to call. One procedure is called immediately prior to enqueuing a message thereby allowing process privileges to be enabled. The second procedure is then called immediately after the message has been enqueued thereby allowing process privileges to be disabled. See Section 2.3 for further details on the use of this item code. This item code must be used in conjunction with the PMDF_PRIV_DISABLE_PROC item code. The item_length field is ignored by this action.

PMDF_PRT_AT

Specify the value to use with an AT attribute in a printer To: address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_PRT_TO, PMDF_PRT_CC, or PMDF_PRT_BCC action must have appeared prior to using this action.

PMDF_PRT_BCC

PMDF_PRT_CC

PMDF_PRT_CC

Begin the specification of a printer To:, Cc:, or Bcc: address. Printer addresses can be composed, one attribute at a time, using the PMDF_PRT_ item codes. The attribute-value pair list is automatically assembled from the specified attribute-value pairs, properly quoted, and the domain specification appended. The actual assembly of the address is initiated when either the item list is terminated or when another PMDF_*TO, PMDF_*CC, or PMDF_*BCC action is encountered. The printer address to be built will be treated as a To: address when PMDF_PRT_TO is specified, as a Cc: address when PMDF_PRT_CC is specified, and as a Bcc: address when PMDF_PRT_BCC is specified. The PMDF_PRT_DOMAIN action must be specified for each printer address to be assembled. The item_address and item_length fields are ignored by this action unless PMDF_ADDRESS_STATUS is specified in which case then the address of a string of length at least ALFA_SIZE bytes must be given in the item_address field.

PMDF_PRT_DOMAIN

Specify the domain name to associate with a printer address which is being built up (e.g., printer.example.com). The item_address and item_length fields specify the address and length of a text string containing the domain name. The length of the string can not exceed ALFA_SIZE bytes. This action must be taken when composing a printer address with the PMDF_PRT_ item codes. A PMDF_PRT_TO, PMDF_PRT_CC, or PMDF_PRT_BCC action must have appeared prior to using this action.

PMDF_PRT_MS

Specify the value to use with an MS attribute in a printer To: address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_PRT_TO, PMDF_PRT_CC, or PMDF_PRT_BCC action must have appeared prior to using this action.

PMDF_PRT_O

Specify the value to use with an O attribute in a printer To: address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_PRT_TO, PMDF_PRT_CC, or PMDF_PRT_BCC action must have appeared prior to using this action.

PMDF_PRT_OU

Specify the value to use with an OU attribute in a printer To: address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_PRT_TO, PMDF_PRT_CC, or PMDF_PRT_BCC action must have appeared prior to using this action.

PMDF_PRT_P1

...

PMDF_PRT_P8

Specify the value to use with a P1, P2, P3, P4, P5, P6, P7, or P8 attribute in a printer To: address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_PRT_TO, PMDF_PRT_CC, or PMDF_PRT_BCC action must have appeared prior to using this action.

PMDF_PRT_TN

Specify the value to use with a TN attribute in a printer To: address which is being built up. The item_address and item_length fields specify the address and length of a text string containing the value to use. The length of the string can not exceed ALFA_SIZE bytes. A PMDF_PRT_TO, PMDF_PRT_CC, or PMDF_PRT_BCC action must have appeared prior to using this action.

PMDF_READ_RECEIPT_TO

Specify the body of a Read-receipt-to: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Read-receipt-to: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Read-receipt-to: body can be specified.

PMDF_REFERENCES

Specify the body of a References: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a References: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one References: body can be specified.

PMDF_REPLY_TO

Specify the body of a Reply-to: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Reply-to: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Reply-to: body can be specified.

PMDF_RESENT_FROM

Specify the body of a Resent-From: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Reply-to: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Reply-to: body can be specified.

PMDF_RESENT_REPLY_TO

Specify the body of a Resent-reply-to: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Resent-reply-to: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Resent-reply-to: body can be specified.

PMDF_SENSITIVITY

Specify the body of a Sensitivity: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Sensitivity: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Sensitivity: body can be specified.

PMDF_SUBADDRESS

Specify a subaddress to use when generating a return address from a user name specified with the PMDF_USER item code. The item_address and item_length fields specify the address and length of a text string containing the subaddress. The length of the string can not exceed ALFA_SIZE bytes. Only one subaddress can be specified per message. The PMDF_USER action must be used in conjunction with this item code.

PMDF_SUBJECT

Specify the body of a Subject: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Subject: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Subject: body can be specified.

PMDF_TO

PMDF_ENV_TO

PMDF_HDR_TO

Specify a To: address. The item_address and item_length fields specify the address and length of a string containing a To: address. The length of the address can not exceed ALFA_SIZE bytes. PMDF_TO is used to specify a To: address which should appear in both the message's header and envelope. PMDF_ENV_TO is used to specify an envelope-only To: address (i.e., an active recipient) which should not appear in the message's header. PMDF_HDR_TO is used to specify a header-only address To: (i.e., an inactive recipient) which should only appear in the message's header. If PMDF_ADDRESS_STATUS is specified, then this string must have a maximum size of at least ALFA_SIZE bytes.

PMDF_USER

Specify the user name to use for the envelope From: and header line From: addresses. The item_address and item_length fields specify the address and length of a text string containing the user name. The PMDF_ENV_FROM action should be used when the envelope From: address is not a local address. When the address is a local address, then merely the user name should be specified using the PMDF_USER action. If this action and the PMDF_ENV_FROM actions are not specified, then the user name associated with the current process will be used. Under OpenVMS, WORLD privilege --- as a default privilege --- is required to use this action when the specified From: address does not agree with the user name of the process enqueuing the message. On UNIX, the process must have the same (real) UID as the root or pmdf account. If the process lacks sufficient privileges, the SS$_NOWORLD (OpenVMS) or PMDF__INSUFPRIV (UNIX) error will be returned. On NT systems, the process must be a privileged process such as Administrator. Can not be used in conjunction with the PMDF_ENV_FROM item code.

PMDF_WARNINGS_TO

Specify the body of a Warnings-to: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Warnings-to: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one Warnings-to: body can be specified.

PMDF_X_ORGANIZATION

Specify the body of a X-Organization: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a X-Organization: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one X-Organization: body can be specified.

PMDF_X_PS_QUALIFIERS

Specify the body of a X-PS-Qualifiers: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a X-PS-Qualifiers: header line. The length of the string can not exceed ALFA_SIZE bytes. Only one X-PS-Qualifiers: body can be specified.

Description

Send a message. The processing carried out to address the message, generate the message's header and body, and enqueue the message is specified through the item_list argument. Refer to Section 2.1 for details on how to use PMDF_send. In the event of an error (an even return value), no message will be sent.

Return Values

PMDF__OK Normal, successful completion.
PMDF__ADDRERRS One or more illegal envelope To: addresses prevented the message from being sent.
PMDF__ALLADDRBAD Message contained no legal envelope To: addresses; no message sent.
PMDF__BADITEMADDR item_address associated with an item list entry is illegal.
PMDF__BADITEMCODE Unrecognized item_code specified in an item list entry.
PMDF__BADITEMSIZE item_length associated with an item list entry is incorrect.
PMDF__ERRFDLPROC An error occurred while attempting to process an OpenVMS file descriptor for an input file.
PMDF__ERROPENINP An error occurred while attempting to open an input file.
PMDF__ERRPROCINP An error occurred while processing an input source.
PMDF__FCRT File create error. The message could not be placed in the PMDF message queues. This is typically due to insufficient privileges although other possibilities exist such as insufficient disk space. Message not enqueued.
PMDF__FILOPNERRS An error occurred while processing an input source.
PMDF__FOPN Initialization failed. One or more PMDF configuration files could not be accessed. PMDF configuration files are incorrectly protected.
PMDF__HOST Illegal address specified ( e.g., bad syntax, illegal mail box name, corresponds to a restricted mailing list, etc.).
PMDF__INCOMPITMS Incompatible item codes specified.
PMDF__INSUFPRIV Process must have the same (real) UID as either the root or pmdf account in order to specify with the PMDF_USER item code a user name different than that of the current process. This error code is only returned on UNIX.
PMDF__MISGNSTART A PMDF_FAX_* or PMDF_PRT_* item code was used without first specifying a PMDF_FAX_TO, PMDF_FAX_CC, PMDF_FAX_BCC, PMDF_PRT_TO, PMDF_PRT_CC, or PMDF_PRT_BCC item code.
PMDF__NO Initialization failed owing to a version mismatch between the current version of PMDF and the site's compiled configuration. Either the PMDF configuration needs to be recompiled or the character set tables need to be recompiled.
PMDF__NOADDRESSES No To:, Cc:, or Bcc: addresses specified.
PMDF__NOOP Message had no envelope To: addresses; its delivery was effected by simply deleting it.
PMDF__STRTRUERR A string specified in one of the item list entries exceeds, in length, the maximum size allowed for the associated item code.
SS$_NOWORLD OpenVMS WORLD default privilege is required to specify with the PMDF_USER item code a user name different than that of the current process. This error code is only returned on OpenVMS.
On OpenVMS Systems Any error returned by the $GETJPI System Service or the STR$TRIM or STR$UPCASE OpenVMS Run Time Library routines.

Note

4 A single longword value of zero can instead be used.


Previous Next Contents Index