PMDF System Manager's Guide

24.2.5 Command Completion Statuses

The command procedure or script specified in the script channel option file COMMAND option 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 NT, 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 script channel will think that the running of the script failed.

Table 24-10 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 24-10 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__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 script channel that there were no changes made to the message.

**Table 24-10 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__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 script channel that there were no changes made to the message.

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

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

24.2.5.1 Bouncing Messages

The script channel 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

Note that using the base PMDF__FORCERETURN status value, only a sample of the original message is included in the bounce message. The amount is controlled by the LINES_TO_RETURN PMDF option (see Section 7.3.4). However, 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.

24.2.5.2 Deleting Messages

The script channel command procedure or script may tell PMDF to delete the 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.

24.2.5.3 Holding Messages

The script channel 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 script channel queue.

24.2.5.4 No Changes

If the command procedure or script returns PMDF__NOCHANGE, this lets the script channel know that the command procedure made no changes to the message. The script channel will forward the message on to the next channel completely unchanged.

Contents

Index