Special attention must be given to programs which may run indefinitely. An example of such a program might be a server which continually listens for incoming mail connections and, upon establishing a connection, enqueues any received mail to PMDF. The following discussion is concerned with such programs. Programs which run and merely submit a few messages, loop over a queue of messages and then exit, or user interfaces should not take the steps described in this section.a
When PMDF_initialize is called, site-specific configuration information is loaded. Normally, the life-span of this information far exceeds the running time of a program which uses it. However, this is not the case for a program which may run for weeks or months. When PMDF configuration information is changed, such programs need to be made aware of the change so that they can reload this information. However, subsequent calls to PMDF_initialize or PMDF_done and PMDF_initialize will not, in general, accomplish this task: a program must exit and restart in order to ensure that all configuration information is reloaded.
Also, a program which enqueues or dequeues messages to or from PMDF
will open the queue cache database and possibly the PMDF log file,
mail.log_current. Care must be taken to ensure that these
files are not left open during periods of inactivity. Doing otherwise
might block activities which require exclusive access to those files.
Programs which run indefinitely enqueuing or dequeuing messages should,
before going idle, always call PMDF_close_queue_cache,
PMDF_close_log_file, and, if doing message dequeue activity,
PMDF_dequeue_end. The queue cache and log file will be automatically
reopened when needed. The queue cache should not be closed while in the
middle of dequeue processing; i.e., PMDF_close_queue_cache
should not be called while looping over messages in a message queue
with PMDF_get_message. PMDF_close_queue_cache should be called after
PMDF_get_message has returned a PMDF__EOF status and before again
calling PMDF_dequeue_initialize.
1.7.1 OpenVMS considerations
The PMDF RESTART command is used after a change to the PMDF
configuration to restart components of PMDF which run indefinitely. In
addition, the PMDF CACHE/CLOSE command is used to force components of
PMDF to close the queue cache database should they have it open. One
such component of PMDF is BN_SLAVE. This component is a slave channel
program which runs as a detached process. It starts running at system
startup and continues to run, processing incoming BITNET mail, until
Jnet or the system is shut down. When configuration changes are made or
the queue cache needs to be rebuilt, a PMDF RESTART command is issued
to inform BN_SLAVE of this fact. BN_SLAVE then either exits and
restarts or closes the queue cache database at its earliest convenience.
The routine PMDF_set_call_back provides a communication path whereby a running program can be notified when a PMDF RESTART, PMDF SHUTDOWN, or PMDF CACHE/CLOSE command has been issued. When a RESTART or SHUTDOWN command is issued, a running program should note this fact and, as soon as is convenient, exit and restart or simply exit. In response to a CACHE/CLOSE command, the queue cache should be closed as soon as it is convenient to do so. This is accomplished with the PMDF_close_queue_cache routine. The cache will be automatically reopened when it is again needed. This is generally done by PMDF_enqueue_message and PMDF_get_message. The queue cache should not be closed while in the middle of dequeue processing; i.e., it should not be called while looping over messages in a message queue. PMDF_close_queue_cache should be called after PMDF_get_message has returned a PMDF__EOF status and before again calling PMDF_dequeue_initialize.
On OpenVMS systems, the communication path established by PMDF_set_call_back is implemented using cluster-wide resource locks. Thus, PMDF RESTART and PMDF SHUTDOWN commands issued anywhere on an OpenVMS cluster will be seen by all users of PMDF_set_call_back throughout the cluster.
1.7.2 UNIX & NT considerations
On UNIX and NT systems, the PMDF_set_call_back facility is
non-functional. Calls to it will merely return PMDF:OK without doing
anything. Likewise for the PMDF_cancel_call_back routine.
Also on UNIX and NT systems, the PMDF RESTART and SHUTDOWN commands may not be used to restart or shutdown site-supplied API clients. Such clients must supply their own mechanism for being signalled to either restart or shutdown.