/sys$common/syshlp/helplib.hlb SET, ENTRY, Qualifiers, /RETAIN  *Conan The Librarian (sorry for the slow response - running on an old VAX)

       /RETAIN=option

    Specifies the circumstances under which you want your jobs to be
    retained in a queue. When a job is retained in the queue, you can
    issue the SHOW QUEUE command after the job completes to see the
    status of the job. Without job retention, no record of a job is
    left in a queue after a job completes.

    Use the following options to specify job retention:

    o  ALWAYS-Holds the job in the queue regardless of the job's
       completion status.

    o  DEFAULT-Holds the job in the queue as specified by the queue's
       retention policy.

    o  ERROR-Holds the job in the queue only if the job completes
       unsuccessfully.

    o  UNTIL=time-value--Holds the job in the queue for the specified
       length of time, regardless of the job's completion status.

                                   NOTE

       You cannot specify a /NORETAIN qualifier with the SET
       ENTRY command (as system managers can with the commands
       INITIALIZE/QUEUE, START/QUEUE, and SET QUEUE); however, you
       can specify /RETAIN=DEFAULT with the SET ENTRY command. The
       default option holds the job in the queue as specified by
       the queue's retention policy. If the system manager has not
       specified retention for the queue, the job is not retained.

    How Job Retention Is Determined

    Although you can specify job retention options for your own jobs,
    the job retention option you specify may be overridden by the job
    retention option of the queue on which your job executed. If you
    submit or print a job to a generic queue, the generic queue's job
    retention setting may also override the job retention option you
    specify. This section describes how job retention is determined.

    An execution queue's job retention setting takes precedence
    over a generic queue's job retention setting; however, if the
    job's completion status does not match the job retention setting
    (if any) on the execution queue, then the generic queue's job
    retention setting attempts to control job retention. If the job's
    completion status does not match the job retention setting (if
    any) on the generic queue, then the user-specified job retention
    setting is used. Jobs submitted directly to execution queues are
    not affected by job retention settings on generic queues.

    If the execution queue's retention setting applies, the job is
    retained on the execution queue. Likewise, if the generic queue's
    retention setting applies, the job is retained on the generic
    queue. If the user-specified setting applies, the job is retained
    in the queue to which it was submitted.

    The following example illustrates how the queue manager
    determines job retention:

    Suppose you submit a job to a generic queue and specify
    /RETAIN=ALWAYS, and the job completes successfully.

    First, the queue manager compares the job's completion status
    to the execution queue's retention setting. Suppose the queue
    is set with /RETAIN=ERROR (retains only jobs that complete
    unsuccessfully). The job is not retained in the execution queue
    because the error condition was not met.

    Second, the queue manager compares the job's completion status to
    the generic queue's retention setting. Suppose the generic queue
    has no retention setting. The queue manager's comparison again
    fails to retain the job.

    Finally, the queue manager compares the job's completion
    status to the retention setting you specified for the job. This
    comparison reveals that the job should be retained. Because the
    user-specified setting leads the queue manager to retain the job,
    the job is held in the queue to which the job was submitted-in
    this case, the generic queue.

    For more information on types of queues, see the INITIALIZE/QUEUE
    command. For more information on setting retention options for
    queues, see the INITIALIZE/QUEUE, START/QUEUE, or SET QUEUE
    command.

    Timed Retention

    Timed retention, which you specify using the UNTIL=time-value
    option, allows you to retain a job in the queue only as long as
    you need it. This eliminates the need to delete the job from the
    queue later.

    For example, the following command retains job 172 in the queue
    until 7:31 on April 19, when the job will automatically be
    deleted from the queue.

    $ SET ENTRY/RETAIN=UNTIL=19-APR-2001:07:31:0.0 172

    However, depending on the queue's job retention policy, the
    job might be retained indefinitely. The job retention policy
    set on the queue takes precedence over the user-specified job
    retention setting. Because system managers cannot specify timed
    job retention for a queue, any jobs retained as a result of a
    queue's setting are retained indefinitely.

    If you specify the /RETAIN=UNTIL=time-value option, you must
    supply a time value. The time value is first interpreted as
    a delta time, then as a combination time, and finally as
    absolute time. If you specify a delta time, the delta begins
    when the job completes. For example, if you specify SET
    ENTRY/RETAIN=UNTIL="+3:00", the job will be retained for three
    hours after the job completes. For information on specifying time
    values, refer to the OpenVMS User's Manual.