PMDF System Manager's Guide
PMDF-REF-6.0

A periodic job is one which reschedules itself for execution each time it runs. This section will discuss the second of PMDF's two main periodic jobs, the periodic return job. This job is embodied on OpenVMS by the command procedure PMDF_COM:return.com, which runs once a day at 0:30:00 by default, or is embodied on UNIX by the shell script /pmdf/bin/return.sh, which the cron daemon is normally scheduled to run once a day at 30 minutes after midnight, or is embodied on NT by the program return_job.exe in the PMDF binary image directory (usually C:\pmdf\bin\ which the at command normally schedules to run once a day at 30 minutes after midnight under the Scheduler. This job is primarily used to return (bounce) old, undeliverable messages which have sat around in the message queues for too long. The frequency with which the PMDF return job runs can be altered, if desired; see Section 1.4.4.1 below.

The return job (after first, on OpenVMS, resubmitting itself to run again, at its next scheduled time, in the queue in which it is presently running) by default scans the channels listed in the configuration file each time it runs, checking the values established with the notices keyword. Or if any of the urgentnotices, normalnotices, and nonurgentnotices channel keywords have been used to set more specific timeouts for certain priorities of messages, the return job checks those values. The messages queued to each channel are then checked. A warning message is sent for every message whose age in days matches any of the values specified with the notices keyword on the associated channel -- or in the case of the *notices keywords, any message whose priority matches or exceeds that specified by the keyword and whose age in days matches any of the keyword's values. The default ages if no notices keyword is specified are 3, 6, 9, and 12 days. If the message is as old or older than the final notices value, the entire message is returned and the original message is deleted from the channel queue; no further attempts to deliver the message will be made. The frequency with which the periodic return job attempts to perform this task of returning old messages may be controlled via the PMDF_RETURN_PERIOD logical (OpenVMS) or PMDF tailor file option (UNIX) or NT Registry entry.

Note:

On OpenVMS, the PMDF_RETURN_PERIOD logical should not be used if MAIL$BATCH runs on more than one node in a cluster, as this may lead to unpredictable results.

The text of the warning and failure notices issued by the message return system is contained in the return_*.txt files located in the PMDF language-specific directory.⁷ These files can be edited to provide different notification text if desired.⁸

PMDF maintains a history of delivery attempts for each message, which sometimes will include information about failed delivery attempts. This information is included in returned messages if RETURN_DELIVERY_HISTORY is set to 1 in the PMDF option file (this is the default). A value of 0 disables the inclusion of this information.

Finally, the message return subsystem normally performs some clean up tasks in addition to returning old messages; these additional functions are described below in Section 1.4.4.2 .

1.4.4.1 Adjusting return job frequency

On NT systems, the frequency of the PMDF return job is controlled via the at command which sets an entry for running return_job.exe under the Scheduler. If the return job is scheduled to run more frequently than once a day, as for instance on an hourly basis, then RETURN_UNITS=1 should be set in the PMDF option file, so that notices values will be interpreted in hours, rather than in days as is the default.

If the PMDF return job is running once an hour, then the default will be to issue warning notices for messages which have remained undeliverable for 3, 6, or 9 hours. Messages which have remained undeliverable for 12 or more hours are returned in their entirety to their sender and no further delivery attempts are made. Note: When RETURN_UNITS=1, these defaults will result in mail being bounced much too soon; therefore, sites are strongly encouraged to use the notices channel keyword to set "bounce" ages in excess of twelve hours.

As the PMDF return job also performs various PMDF periodic cleanup tasks, tuned on the assumption that the return job will only be running once a day, when the PMDF return job is run more frequently, various PMDF parameters should be adjusted accordingly. In particular, the PMDF_RETURN_SYNCH_PERIOD, PMDF_RETURN_SPLIT_PERIOD, and PMDF_RETURN_CHECK_PERIOD logicals (OpenVMS) or PMDF_RETURN_SYNCH_PERIOD and PMDF_RETURN_SPLIT_PERIOD PMDF tailor file options (UNIX) or PMDF_RETURN_SYNCH_PERIOD and PMDF_RETURN_SPLIT_PERIOD Registry entries (NT) should generally be adjusted so that these tasks are still performed only once a day; see Section 1.4.4.2 .

1.4.4.2 Clean up tasks performed by the return job

By default, the periodic return job checks each time it runs for any mail.log* or connection.log* files in the PMDF log area. It appends any existing mail.log_yesterday file to the cumulative log file, mail.log, renames the current mail.log_current file to mail.log_yesterday, and then begins a new mail.log_current file. The return job also performs the analogous operations for connection.log* files. The frequency at which the periodic job performs these log file roll overs may be controlled via the PMDF_RETURN_SPLIT_PERIOD logical (OpenVMS) or PMDF tailor file option (UNIX) or Registry entry (NT).

The return job by default also re-synchronizes the PMDF queue cache database each time it runs, scanning all the messages in the queues and entering any missing messages into the PMDF queue cache. The frequency with which the return job performs queue cache database re-synchronization may be controlled via the PMDF_RETURN_SYNCH_PERIOD logical (OpenVMS) or PMDF tailor file option (UNIX) or Registry entry (NT).
On OpenVMS, the queue cache is also periodically subjected to either a CONVERT operation, or to a CONVERT/RECLAIM operation to reclaim any unused space.

On OpenVMS, the PMDF return job also resets the version numbers of all log files in the PMDF log directory, PMDF_LOG: on OpenVMS. Unfortunately, the version numbers on open files cannot always be changed. Therefore, if, after resetting the version numbers, any log files have a version number exceeding the warning level, 25,000, set in the command procedure PMDF_COM:pmdf_check_logs.com, then a mail message will be sent to the Postmaster. When such a message is received the Postmaster must manually delete or reset the version numbers on the log files. Failure to do so will cause the associated channel to stop working should the version number of one of its log files attain 32,767. The frequency at which the periodic return job checks log file versions may be controlled via the PMDF_RETURN_CHECK_PERIOD logical; the default, if the logical is not defined, is to check each time the return job runs.

The logical names (OpenVMS) or PMDF tailor file options (UNIX) or Registry entries (NT) described above for controlling the frequency of return job tasks are not defined by default. To use such a logical name or tailor file option, define the logical or set the tailor file option or Registry entry to an integer value N; that will cause the associated action to only be performed every N times the periodic return job runs.

Note:

On OpenVMS, the PMDF_RETURN_SYNCH_PERIOD, PMDF_RETURN_SPLIT_PERIOD, and PMDF_RETURN_CHECK_PERIOD logicals should not be used if MAIL$BATCH runs on more than one node in a cluster, as this may lead to unpredictable results.

The periodic return job also includes a hook for executing a site-supplied clean up procedure. OpenVMS sites may provide their own PMDF_COM:daily_cleanup.com DCL procecure; UNIX sites may provide their own /pmdf/bin/daily_cleanup shell procedure; NT sites may provide their own daily_cleanup command script in the PMDF binary image directory (usually C:\pmdf\bin\. The periodic return job will automatically execute such a procedure, if it exists.

Note

⁷ On UNIX systems, this is the directory specified by the PMDF_LANG setting in the /etc/pmdf_tailor file; on NT systems, this is the directory specified by the PMDF_LANG entry in the PMDF tailor Registry; on OpenVMS systems, this is the directory specified by the PMDF_LANG logical. Usually the PMDF language-specific directory is simply a synonym for the PMDF table directory.

⁸ As the text of such a file is copied into messages, certain substitutions are made. A %C expands into the number of days the message has been queued; %L expands into the number of days the message has left in the queue before it is returned; %F expands into the number of days a message is allowed to stay in the queue; %S [%s] expands into an S [s] if the previously expanded numeric value was not equal to one; %U [%u] expands into the units, Hour [hour] or Day [day], in use; %R expands into the list of the message's recipients; %H expands into the message's headers.