HP OpenVMS Systems

OpenVMS Technical Journal V12

HP OpenVMS Systems

OpenVMS information

» What's new on our site
» Upcoming events
» Configuration and buying assistance
» Send us your comments

HP OpenVMS systems

» OpenVMS software
» Supported Servers
» OpenVMS virtualization
» OpenVMS solutions and partners
» OpenVMS success stories
» OpenVMS service and support
» OpenVMS resources and information
» OpenVMS documentation
» Education and training

OpenVMS software

» Operating system
» OpenVMS clusters
» OpenVMS Galaxy
» e-Business products
» Opensource tools
» Networking
» System management
» Storage management
» Security products
» Application development and integration
» Software licensing
» SPD listings
» Whitepapers
» Ask the wizard
» Training
» OpenVMS books

Evolving business value

» Business Systems Evolution
» AlphaServer systems transition planning
» Alpha RetainTrust program

Related links

» HP Integrity servers
» HP Alpha systems
» HP storage
» HP software
» HP products and services
» HP solutions
» HP support
disaster proof
HP Integrity server animation
HP Integrity server animation
Content starts here

Utilizing /RETAIN=ERROR to make life easier

Bruce Claremont, Senior Consultant


The /RETAIN=ERROR qualifier is a useful tool to identify problem batch and print jobs. This paper discusses how to deploy the qualifier to your advantage as part of OpenVMS system maintenance and monitoring.

It is surprising how few OpenVMS sites implement /RETAIN=ERROR on their queues -particularly batch queues. At certain sites, a review of log files reveals that some jobs have not successfully run to completion for years. Since the logs aren't checked, no one is aware of the problem, which often leads to painful and expensive long-term data corruption.

One of the easiest ways to impress users is to contact them when a job goes bad - before they become aware of it. Proactive maintenance of this sort will help maintain a smooth-running system. The goal is less work for administrators, and /RETAIN=ERROR can help you achieve it.

How it Helps

/RETAIN=ERROR retains job information on a queue if the job ends abnormally. The primary cause of an abnormal termination for a batch job is an error within the job. Retaining the job information tells us what job failed and what parameters were used to invoke it. Reviewing the log file tells where the job failed, which helps identify the root cause of the problem.

For print jobs, retaining the job information when there is an error can help administrators identify an invalid PRINT statement, corrupted print file, or problem with the printer. As with batch jobs, knowing a problem exists is the first step towards eliminating the problem.

Retaining Log Files

Retaining batch job log files is strongly recommended. The /NOPRINT and /KEEP qualifiers ensure a log file is retained after a job completes. OpenVMS's default behavior is to delete a log file if a job completes successfully unless /KEEP or /NOPRINT are specified. It's good practice to retain several versions of a log file. Having a complete log file from a valid run to compare to a log file from a failed run is a useful troubleshooting tool. An appropriately tuned PURGE command following the SUBMIT command ensures log files do not pile up unnecessarily.


Figure 1: Retain the last 12 log files for the procedure 5_MINUTE_CHK.

Figure 2: Retain the last year's worth of Month End payroll logs. How does this retain 12 months of logs? Should AFTER include a parameter?

/RETAIN=ERROR set up for a queue

Configuring a queue to enable /RETAIN=ERROR is easy. Simply add the /RETAIN=ERROR qualifier to the INITIALIZE command when creating the queue.


Figure 3: Create a queue with /RETAIN=ERROR.
You can also add the /RETAIN=ERROR qualifier to an existing queue with the START or SET queue commands.


Figure 4: Adding /RETAIN=ERROR on queue start up.

Figure 5: Adding /RETAIN=ERROR to a running queue.

Using /RETAIN=ERROR at the queue level is a great way to monitor jobs. It allows you to know when any job fails so the root cause can be determined and the problem eliminated. However, /RETAIN=ERROR usage can be refined to the job level if so desired.

/RETAIN=ERROR set up for a job

/RETAIN=ERROR can be specified for individual jobs. However, remember that /RETAIN settings on generic and execution queues to which the job is submitted can override the local job setting. As OpenVMS Help says:

    "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."

Look at the SUBMIT command description in the HP OpenVMS DCL Dictionary for a comprehensive description of /RETAIN precedence rules.

Using /RETAIN=ERROR at the job level allows you to monitor specific jobs. If the queues upon which the jobs run do not have a conflicting /RETAIN policy, the job will be retained if it completes unsuccessfully.


Figure 6: Print job FS3302 is retained on queue LASER_21 if it fails to print.

Figure 7: Job INV906 will be retained on queue SYS$BATCH if it fails to complete successfully.

Checking Job Status

Presuming your user account has the correct privileges or access controls, checking for retained jobs is as easy as issuing a SHOW QUEUE statement. Use the /BY_JOB_STATUS=RETAIN qualifier to limit the display to retained jobs.


Figure 8: Display retained jobs on SYS$BATCH queue.
It makes sense to have OpenVMS check for retained jobs automatically and notify the administrator of any found. A DCL procedure called BATCHQ_CHECK.COM is included in the article Using OpenVMS to Meet a Sarbanes-Oxley Mandate Part 2: The DCL (.pdf) that accomplishes this task.


The /RETAIN=ERROR feature provides another simple method to proactively monitor an OpenVMS system while helping to provide end users and management with a smooth-running system. Start using it today to identify and correct problem jobs on your OpenVMS system.

About the author:

Mr. Bruce Claremont has been working with OpenVMS since 1983. Mr. Claremont has extensive programming, project management, and system management experience. He founded Migration Specialties in 1992 and continues to deliver OpenVMS and application migration services along with hardware emulation solutions. More information about Migration Specialties products and services can be found at www.MigrationSpecialties.com.

For more information

More on DCL development: