Document revision date: 19 July 1999

By default, the log file has the same name as the first command procedure in the batch job and has the file type .LOG. The system writes output from a batch job to a log file once each minute. To specify a different time interval, include the SET OUTPUT_RATE command in your command procedure.

If you attempt to use the EDT editor to read the log file while the system is writing to it, you receive a message indicating that the file is locked by another user. Wait a few seconds and try again. The EVE editor, however, allows you to read the batch job's log file. By specifying EDIT/TPU/READ_ONLY and the name of the log file, you can use EVE commands to move around the log file and to ensure that any changes you make to the file are not saved. If you omit the /READ_ONLY qualifier and modify the log file in any way, the batch job terminates.

Because your batch job is a process that logs in under your user name and executes your login command procedure, the output from a batch job includes the contents of your login command procedure. The output also includes everything written to the batch job log file (command procedure output, error messages, and so on) and the full logout message. To prevent your login command procedure from being written to the batch log file, add the following command to the beginning of your login command procedure:

$ IF F$MODE() .EQS. "BATCH" THEN SET NOVERIFY

By default, the log file name is the name under which you submitted the job. Also by default, the log file has the file type .LOG and assumes the device and directory specified by your login defaults. To specify a different log file name when you submit the job, use the /LOG_NAME qualifier to the SUBMIT command.

The batch job log file includes all output to SYS$OUTPUT and SYS$ERROR. It also includes, by default, all command lines executed in the command procedure. To prevent the command lines from being printed, use either the SET NOVERIFY command or the F$VERIFY lexical function in your command procedure. When the job completes, the system writes job termination information (using the long form of the system logout message) to the log file.

If the SET VERIFY command is in effect, you can also learn the exact time when each command is executed by using the SET PREFIX command to time-stamp each command line.

When a batch job fails to complete successfully, you can examine the log file to determine the point at which the command procedure failed and the error status that caused the failure.

Saving Log Files

To save log files, use either the /KEEP or the /NOPRINTER qualifier. The /KEEP qualifier saves the log file after it is printed. The /NOPRINTER qualifier saves the log without printing it. If you specify neither of these qualifiers, the default action occurs; the log file is queued to the default print queue SYS$PRINT and is deleted after it prints. The /KEEP and /NOPRINTER qualifiers save the log file in your default login directory. The log file has the same name as the first command procedure in the batch job and the file type .LOG. To specify an alternate file name or directory name, or both, use the /LOG_FILE qualifier. To rename and save the log file, you must use /LOG_FILE and either /KEEP or /NOPRINTER.

In the following example, the log file is saved to a file named DISK2:[JONES.RESULTS]UPDATE.LOG:

$ SUBMIT/LOG_FILE=DISK2:[JONES.RESULTS]/NOPRINTER - _$ DISK2:[JONES.RESULTS]UPDATE

Reading the Log File

You can use the TYPE command to read the log file to determine how much of the batch job has completed. However, if you attempt to display the log file while the system is writing to it, you receive a message indicating that the file is locked by another user. If this occurs, wait a few seconds and try again.

Including Command Output in the Batch Job Log

Typically, a batch job command procedure that compiles, links, and executes a program creates additional printed output such as a compiler listing or a linker map. To produce printed copies of these files, a batch job command procedure can contain the PRINT commands necessary to print them.

If you want a batch job log to contain all output from the command procedure, including printed listings of compiler or linker output files, you can do either of the following:

• Use the TYPE command instead of the PRINT command in the command procedure. The TYPE command writes to SYS$OUTPUT. In a batch job, SYS$OUTPUT is equated to the batch job log file.
• Use qualifiers on appropriate commands to direct the output to SYS$OUTPUT.
  Note that if you use this technique, the output files are not saved on disk unless you save the log file.

When the command procedure shown in the following example completes processing, there are three separate output listings: the batch job log, the compiler listing, and the linker map:

$ FORTRAN/LIST BIGCOMP $ PRINT BIGCOMP.LIS $ LINK/MAP/FULL BIGCOMP $ PRINT BIGCOMP.MAP

The following example shows how to use qualifiers to direct the output to SYS$OUTPUT:

$ FORTRAN/LIST=SYS$OUTPUT BIGCOMP $ LINK/MAP=SYS$OUTPUT/FULL BIGCOMP

When these commands are executed in a batch job, the output files from the compiler and the linker are written directly to the log file.

18.5.4 Changing Batch Job Characteristics

After a job has been submitted to the queue but before the job starts to execute, you can use the SET ENTRY or the SET QUEUE/ENTRY command with the appropriate qualifiers to change characteristics associated with the job.

The following example shows two methods you can use to change the name of a batch job while it is pending in a batch queue:

$ SET QUEUE/ENTRY=209/NAME=NEW_NAME SYS$BATCH

$ SET ENTRY 209 /NAME=NEW_NAME

Both of these commands change the name of job number 209 to NEW_NAME.

The following list contains some of the changes you can make with the SET ENTRY or SET QUEUE/ENTRY commands. For a complete list of qualifiers, see the OpenVMS DCL Dictionary. Note that most of the qualifiers allowed with the SUBMIT command can also be used with SET ENTRY and the SET QUEUE/ENTRY commands.

You can make the following changes:

• Delay processing of a job.
  Use the /AFTER qualifier to specify a time after which the job can be executed. Use the /HOLD qualifier to hold a job until you explicitly release it.
• Release a job.
  Use the /NOHOLD or /RELEASE qualifier to release a job that was submitted with the /HOLD or /AFTER qualifiers.
• Send a job to a different queue.
  Use the /REQUEUE qualifier to change the queue on which the job will execute.
• Change execution characteristics.
  Change execution characteristics such as working set default, working set extent, working set size, job scheduling priority, and CPU time limit.
• Change the parameters to be passed to a job.
  Use the /PARAMETERS qualifier to change the parameters.

Following are the qualifiers you can specify with the SUBMIT command to control batch job characteristics. Note that you can also specify execution characteristics such as working set default, working set extent, working set size, job scheduling priority, and CPU time limit.

• /AFTER
  Specifies a time after which the batch job can execute. The job remains in the batch queue until the specified time. To hold a job in the queue until you explicitly release it, use the /HOLD qualifier. (To release a job that is being held, use the SET ENTRY/RELEASE command.)
• /NAME
  Specifies a name for the batch job. Otherwise, the job name defaults to the file name of the first (or only) command procedure in the job.
• /NOTE
  Specifies a message string to appear as part of the display for a SHOW QUEUE/FULL command. Allows you to convey information about the job to the operator or system manager.
• /NOTIFY
  Requests notification of job completion. The system sends a message to your terminal when the batch job finishes executing.
• /PARAMETERS
  Passes parameters to a batch job.
• /NOPRINTER or /KEEP
  Saves a batch job log file.
• /QUEUE
  Sends a batch job to a queue other than SYS$BATCH. To execute a command procedure that is located on a remote node, use the /REMOTE qualifier. This sends the job to SYS$BATCH at the remote node.
• /RESTART
  Enables you to restart the job if the system fails while the job is executing.
• /RETAIN
  Keeps a batch job in a queue after it completes. You can use the SHOW QUEUE or SHOW ENTRY commands to see the job's completion status.

Once a job has been entered in a batch job queue, you can monitor its status with the SHOW ENTRY command or the SHOW QUEUE command. If you have no jobs in the queue, the system displays the following message:

$ SHOW QUEUE BOSTON_BATCH Batch queue BOSTON_BATCH, on BOSTON::

To see complete information on your jobs, use the /FULL qualifier with the SHOW ENTRY or SHOW QUEUE command. To see the status of other jobs in the queue, use the SHOW QUEUE/ALL command.

In the following example, entry number 999 is displayed:

$ SUBMIT EXCHAN.DAT Job EXCHAN (queue SYS$BATCH entry 999) started on SYS$BATCH $ SHOW ENTRY 999 Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 999 EXCHAN BLASS 3 Executing On batch queue SYS$BATCH

$ SUBMIT/NOPRINTER/PARAMETER=STATS.DAT UPDATE Job UPDATE (queue SYS$BATCH entry 1080) started on BOSTON_BATCH $ SHOW QUEUE BOSTON_BATCH Batch queue BOSTON_BATCH on BOSTON:: Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 1080 UPDATE ODONNELL 36 Executing

In the next example, the /FULL qualifier displays statistics about BOSTON_BATCH and characteristics associated with job number 999:

$ SHOW ENTRY/FULL 999 Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 999 EXCHAN BLASS 3 Executing On batch queue BOSTON_BATCH Submitted 11-DEC-1996 13:12 /PRIORITY=100 WRKD:[BLASS]EXCHAN.DAT;3

$ SHOW QUEUE/FULL BOSTON_BATCH Batch queue BOSTON_BATCH, on BOSTON:: /BASE_PRIORITY=3 /JOB_LIMIT=5 /OWNER=[EXEC] /PROTECTION=(S:E,O:D,G:R,W:W) Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 1080 UPDATE ODONNELL 36 Executing Submitted 11-DEC-1996 10:46 /KEEP /PARAM=("STATS.DAT") /NOPRINTER /PRIO=4 _BOSTON$DQA2:[ODONNELL]TEMP.COM;1 (executing)

In the following example, the SHOW QUEUE/ALL command is used to display all jobs in the BOSTON_BATCH queue:

$ SHOW QUEUE/ALL BOSTON_BATCH Batch queue BOSTON_BATCH on BOSTON:: Entry Jobname Username Status ----- ------- -------- ------ 923 no privilege Executing 939 no privilege Holding until 11-DEC-1996 19:00 1080 UPDATE ODONNELL Executing

Note that, unless you are a privileged user, your information is limited to jobs submitted under your account.

18.5.7 Deleting and Stopping Batch Jobs

You can delete batch jobs before or during execution. To delete an entry that is pending or already executing in a batch queue, use the DELETE/ENTRY command. You need special privileges to delete a job that you did not submit. When a job terminates as a result of a DELETE/ENTRY command, the log file is neither printed nor deleted from your directory.

When you terminate a job using the DELETE/ENTRY command, it is handled as an abnormal termination because the operating system's normal job termination activity is preempted. As a result, the batch job log does not, for example, contain the standard logout message that summarizes job time and accounting information. Termination that results either from an explicit EXIT command or STOP command or the implicit execution of either of these commands (as the result of the current ON condition), however, is considered normal termination. The operating system performs proper rundown and accounting procedures after a normal termination.

The following command deletes the job entry 210 in SYS$BATCH:

$ DELETE/ENTRY=210 SYS$BATCH

18.5.8 Restarting Batch Jobs

If the system fails while your batch job is executing, your job does not complete. When the system recovers and the queue is restarted, your job is aborted and the next job in the queue is executed. However, by specifying the /RESTART qualifier when you submit a batch job, you indicate that the system should reexecute your job if the system fails before the job is finished.

By default, a batch job is reexecuted beginning with the first line. See Chapter 15 and Chapter 16 for more information about symbols you can add to your command procedures to specify a different restarting point.

In addition to restarting a job after a system failure, you can also restart a job after you explicitly stop the job. To stop a job and then restart it on the same or a different queue, use the STOP/QUEUE/REQUEUE/ENTRY command.

The command shown in this example stops job 212 on SYS$BATCH and requeues it on SYS$BATCH.

$ STOP/QUEUE/REQUEUE/ENTRY=212 SYS$BATCH

To enter this command, job 212 must have been submitted using the /RESTART qualifier to the SUBMIT command. When the batch job executes for the second time, the system uses the global symbol BATCH$RESTART to determine where to begin executing the job.

18.5.9 Synchronizing Batch Job Execution

You can use the SYNCHRONIZE and WAIT commands within a command procedure to place the procedure in a wait state. The SYNCHRONIZE command causes the procedure to wait for the completion of a specified job. The WAIT command causes the procedure to wait for a specified period of time to elapse.

If you specify a job name with the SYNCHRONIZE command, note that the jobs to be synchronized must be associated with your user name. (A job is associated with the user name of the process that submits it.) To synchronize jobs for different users, you must use the /ENTRY qualifier with the SYNCHRONIZE command to specify the job entry number.

In the following example, if two jobs are submitted concurrently to perform cooperative functions, one job can contain the following command:

$ SYNCHRONIZE BATCH25

After this command is executed, the command procedure cannot continue execution until the job identified by the job name BATCH25 completes execution.

This SYNCHRONIZE command places the current command procedure in a wait state until job 454 completes:

$ SYNCHRONIZE/ENTRY=454

Figure 18-1 is an example of command procedures that are submitted for concurrent execution but must be synchronized for proper execution. Each procedure compiles a large source program.

Figure 18-1 Synchronizing Batch Job Execution

As you examine the example, note the following:

1. Individual SUBMIT commands are required to submit two separate jobs. The first process is created.
2. After the FORTRAN command is executed, the SYNCHRONIZE command is executed. If job 315 is either current or pending, job 314 will not execute the next command.
3. If job 315 has completed execution, job 314 continues with the next command.

The WAIT command is useful for command procedures that must have access to a shared system resource such as a disk or tape drive.

The following example shows a procedure that requests the allocation of a tape drive:

$ TRY: $ ALLOCATE DM: RK: $ IF $STATUS THEN GOTO OKAY $ WAIT 00:05 $ GOTO TRY $ OKAY: $ REQUEST/REPLY/TO=DISKS - "Please mount BACK_UP_GMB on ''F$TRNLNM("RK")'" . . .

If the WAIT command does not complete successfully, the procedure places itself in a wait state. After a 5-minute interval, it retries the request.

The IF command following the ALLOCATE request checks the value of $STATUS. If the value of $STATUS indicates successful completion, the command procedure continues. Otherwise, the procedure executes the WAIT command; the WAIT command specifies a time interval of five minutes. After waiting five minutes, the next command, GOTO, is executed and the request is repeated. This procedure continues looping and attempting to allocate a device until it succeeds or until the batch job is deleted or stopped.

	privacy and legal statement
6489PRO_048.HTML