 |
» |
|
|
|
|
|
|
|
|
Bruce Claremont, Senior Consultant
|
|
|
|
|
|
|
|
/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.
$ SUBMIT /NOPRINT /LOG=LOGS: DOWNLOADS:5_MINUTE_CHK.COM
$ PURGE /KEEP=12 LOGS:5_MINUTE_CHK.LOG
Figure 1: Retain the last 12 log files for the procedure 5_MINUTE_CHK.
$ SUBMIT /NOPRINT /LOG=PAYLOGS: PAYROLL:MONTH_END.COM
$ PURGE / BEFORE="TODAY-365-00" PAYLOGS:MONTH_END.LOG
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.
$ INITIALIZE /QUEUE /RETAIN=ERROR /BATCH PAYROLL_BATCH
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.
$ START /QUEUE /RETAIN=ERROR SYS$BATCH
Figure 4: Adding /RETAIN=ERROR on queue start up.
$ SET QUEUE /RETAIN=ERROR SYS$BATCH
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.
$ PRINT /RETAIN=ERROR /QUEUE=LASER_21 RPT:FS3302.LIS
Figure 6: Print job FS3302 is retained on queue LASER_21 if it fails to print.
$ SUBMIT /RETAIN=ERROR /LOG=LOGS: /KEEP INVENTORY:INV906.COM
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.
$ SHOW QUEUE /BY_JOB_STATUS=RETAIN SYS$BATCH
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.
|
|
|
