PMDF System Manager's Guide

22.1.4 Command Completion Statuses

The command procedure or script specified in the conversions file entry should return one of the following completion statuses. On OpenVMS, this is accomplished by exiting from the command procedure with the desired status. On UNIX and Windows, this is accomplished by setting the STATUS option in the OUTPUT_OPTIONS file. The script itself should exit explicitly with a value of 0, otherwise the conversion channel will think that the running of the script failed. Note that you must specify OVERRIDE-OPTION-FILE=1 in the conversion entry to enable the OUTPUT_OPTIONS file.

Table 22-6 shows the list of completion statuses that can be specified. The values for these statuses are defined in pmdf_com:pmdf_err.h (OpenVMS), /pmdf/include/pmdf_err.h (UNIX), or C:\pmdf\include\pmdf_err.h (NT).

Table 22-6 Completion Statuses
Status Description

1 Success. Continues processing the message.

PMDF__FORCEBITBUCKET Sends the entire message to the bitbucket channel. Similar to PMDF__FORCEDISCARD, but always goes to the bitbucket channel and never to the filter_discard channel.

PMDF__FORCEDELETE Deletes the current message part.

PMDF__FORCEDISCARD Deletes the entire message. Either goes to the bitbucket channel or the filter_discard channel, depending on your configuration.

PMDF__FORCEHOLD Holds the message as a .HELD file.

PMDF__FORCERETURN Bounces the message.

PMDF__NOCHANGE Tells the conversion channel that there were no changes made to the current message part.

**Table 22-6 Completion Statuses**
	Status	Description
	1	Success. Continues processing the message.
	PMDF__FORCEBITBUCKET	Sends the entire message to the `bitbucket` channel. Similar to `PMDF__FORCEDISCARD`, but always goes to the `bitbucket` channel and never to the `filter_discard` channel.
	PMDF__FORCEDELETE	Deletes the current message part.
	PMDF__FORCEDISCARD	Deletes the entire message. Either goes to the `bitbucket` channel or the `filter_discard` channel, depending on your configuration.
	PMDF__FORCEHOLD	Holds the message as a `.HELD` file.
	PMDF__FORCERETURN	Bounces the message.
	PMDF__NOCHANGE	Tells the conversion channel that there were no changes made to the current message part.

These statuses can be used, for example, to discontinue processing the message when the command procedure or script determines that the message part contains objectionable content.

The following sections provide more details about each of these options.

22.1.4.1 Bouncing Messages

The conversion command procedure or script may tell PMDF to return the message to its sender, by using the PMDF__FORCERETURN completion status.

The command procedure or script may optionally use OUTPUT_DIAGNOSTIC to specify a text string to be included in the bounce message returned to the message sender.

On UNIX and NT, the script should write a line in the OUTPUT_OPTIONS file like:

OUTPUT_DIAGNOSTIC=text-string

On OpenVMS, the command procedure should define a logical name in the job logical name table like:

$ DEFINE/JOB OUTPUT_DIAGNOSTIC text-string

There are a couple of variations on the FORCERETURN behavior available.

A value of PMDF__FORCERETURN+1 causes PMDF to return not the original message text, but the final message text including any modifications done by the command procedure or script. The number of lines of the message returned is still controlled by the LINES_TO_RETURN option.

A value of PMDF__FORCERETURN-1 causes PMDF to return the entire message, including any modifications done by the command procedure or script.

22.1.4.2 Deleting Messages

The conversion command procedure or script may tell PMDF to delete the entire message, by using the PMDF__FORCEDISCARD or PMDF__FORCEBITBUCKET completion status.

The PMDF__FORCEDISCARD status causes PMDF to perform the same actions as for the Sieve discard command in mailbox filter files. For example, if the FILTER_DISCARD option is set to 2 or 3 in the PMDF option file, the message will be routed to the filter_discard channel (see Section 7.3.3), otherwise it will be routed to the bitbucket channel, where it will be immediately deleted.

The PMDF__FORCEBITBUCKET status causes PMDF to delete the message by always sending it to the bitbucket channel.

The command procedure or script may optionally use OUTPUT_DIAGNOSTIC to specify a text string to appear in the MAIL.LOG_CURRENT file.

22.1.4.3 Deleting Message Parts

The conversion command procedure or script may tell PMDF to delete the current message part, by using the PMDF__FORCEDELETE completion status.

This causes PMDF to perform the same action as for the DELETE=1 conversion parameter clause, however that clause deletes the part unconditionally.

22.1.4.4 Holding Messages

The conversion command procedure or script may tell PMDF to hold the message, by using the PMDF__FORCEHOLD completion status.

This causes PMDF to hold (sideline) the message as a .HELD file in the conversion channel queue.

22.1.4.5 No Changes

The command procedure or script may tell the conversion channel that it made no changes to the current message part by using the PMDF__NOCHANGE completion status. If all message parts get the PMDF__NOCHANGE status, then the conversion channel will forward the message on to the next channel unchanged (that is, the MIME boundaries and headers will remain unchanged, and any encoded message parts will be their original versions rather than the decoded and re-encoded versions). If any parts return anything other than PMDF__NOCHANGE, then the message is processed by the conversion channel as normal.

Contents

Index