Document revision date: 15 July 2002

If virtual terminals are enabled and a modem line connection is lost, a process remains active on the system as a disconnected virtual terminal process. You must reconnect to the process within the time period specified by the system manager (the default value is 900 seconds or 15 minutes). If you fail to reconnect to the process before this time expires, the system deletes the process.

A terminal can be disconnected in the following circumstances:

• You lose the modem signal between the host and the terminal.
• You press the BREAK key on a terminal with the TT2$M_SECURE characteristic set.
• You enter the DCL command DISCONNECT.
• You enter the DCL command CONNECT/CONTINUE.

If your process is disconnected, you have the option of reconnecting to the old process and returning to the state it was in before you were disconnected. When you log in, the system prompts you as follows:

You have the following disconnected process: Terminal Process name Image name VTA52: RWOODS (none) Connect to above listed process [YES]:

If you press the Return key or enter Yes, you are logged out of your current process as if automatic execution of the DCL command CONNECT/CONTINUE had been performed for you. If you enter No or if you delay too long in responding (so that a response period timeout occurs), you remain logged in to your new process. You lose the ability to connect to the old process.

When you have multiple disconnected sessions, you are prompted for the name of the virtual terminal to which you want to reconnect. If you do not want to connect to any of the displayed sessions, enter No.

16.4.2 Removing Disconnected Processes

The system automatically removes your disconnected processes after a certain interval. You can conserve system resources, however, if you directly log out of any disconnected processes, as follows:

Step	Task
1	Enter the DCL command SHOW USERS to determine if you have other disconnected jobs.
2	Enter the DCL command CONNECT/LOGOUT to log out of the current process. Connect back through each of the associated virtual terminals (as noted by the terminal prefix VTA) until you reach the last existing process.
3	Enter the DCL command LOGOUT.

16.4.3 Managing Disconnected Processes

Virtual terminals allow you to maintain more than one disconnected process at a time. You must keep in mind, however, that while you are logged in to a virtual terminal, the physical terminal is disconnected. Any I/O requests directed to a device other than the physical terminal associated with your current virtual terminal process will enter a waiting state. The pending process will terminate when the timeout period expires. If, however, you reconnect to the physical terminal that is to receive the I/O request, the process continues from the point at which it entered the waiting state. Naming each process with a name that relates to its context makes it easier to reconnect to the desired process.

For example, a user named SMITH running a process to edit a file might use the SET PROCESS/NAME command to name the process SMITH_EDIT. Later, to continue editing, SMITH can easily determine which process is appropriate.

A system manager can restrict the use of virtual terminals systemwide or on a per terminal basis.

16.5 Working with Batch Jobs

A batch job is a noninteractive process. Because a batch job executes in a process of its own, you can have two or more processes doing different things at the same time. For example, you can use batch jobs to:

• Perform a task interactively while the system executes a program or command procedure in batch mode.
• Run command procedures that take a long time to execute.
• Execute command procedures or programs after hours.
• Run certain programs at a reduced priority (for example, if the program uses a disproportionate amount of system resources).

When you submit a batch job, the system creates a detached process with your account and process characteristics. The system runs the job from that process and deletes the process when the job completes. The system also executes the system login command procedure (SYLOGIN.COM) and your login command procedure (LOGIN.COM) and then executes the command procedures in the batch job. As these procedures execute, output is written to a log file. When the batch job completes, you can print the log file or save it in one of your directories.

To run a job in batch mode, submit your job to a batch queue (a list of batch jobs waiting to execute) by entering the DCL command SUBMIT. When you submit a job, it is directed to the default batch queue SYS$BATCH where it is added to the end of the queue of jobs waiting to be executed. When the jobs preceding yours are completed, your job is executed. On an OpenVMS system, the number of batch jobs that can execute simultaneously is specified when the batch queue is created by the system manager. By default, the SUBMIT command uses a file type .COM.

In the following example, the command enters JOB1.COM into SYS$BATCH:

$ SUBMIT JOB1 Job JOB1 (queue SYS$BATCH, entry 651, started on SYS$BATCH)

The system displays the name of the job, the queue containing the job, and the entry number assigned to the job. You receive the DCL prompt after your job is submitted to the batch queue. If you need to reference your batch job in any DCL commands (DELETE/ENTRY, for example), do so by using the job entry number. (You can obtain the job entry number by using the SHOW ENTRY command.) Note that if multiple procedures are submitted in a batch job, the batch job terminates when any procedure exits with an error or fatal (severe) system message.

Your batch job does not necessarily have to start running at the time you submit it to the batch queue. To specify a different time, enter the SUBMIT/AFTER command. In the following example, the job is submitted after 11:30 P.M.:

$ SUBMIT/AFTER=23:30 JOB1.COM

When you submit a command procedure for batch execution, the system saves the complete file specification for the command procedure, including the version number. If you update a command procedure after you submit it, the batch job executes the version of the command procedure that you submitted rather than the new version.

Because your login defaults are not usually the defaults needed to access the files mentioned in your command procedures, use one of the following methods to ensure that the correct files are accessed:

• Use complete file specifications --- When referring to a file in a command procedure or when passing a file to a command procedure, include the device and directory names as part of the file specification.
• Use the SET DEFAULT command --- Before referring to a file in a command procedure, use the SET DEFAULT command at the beginning of the command procedure to specify the proper device and directory.

As a batch job executes, it writes output to a log file. By default, the log file has the same name as the command procedure you submit with the file type .LOG. When the job is finished, the system prints the log file and deletes it from your directory. See Section 16.5.3 for information on saving log files.

Checking for Batch Jobs in Your Login Command Procedure

Each time you submit a batch job, the system executes your login command procedure. You can cause sections of your login command procedure to be included or omitted when you execute batch jobs by using the F$MODE lexical function to test for batch jobs.

In the following example, the login command procedure includes commands, logical names, and symbols that are used exclusively for batch jobs. The section is labeled BATCH_COMMANDS, and the following command is included at the beginning of the login command procedure:

IF F$MODE() .EQS. "BATCH" THEN GOTO BATCH_COMMANDS . . .

To prevent the system from executing any commands in your login command procedure when you submit a batch job, place the following command at the beginning of the procedure:

IF F$MODE() .NES. "INTERACTIVE" THEN EXIT

You can place this command anywhere in your login command procedure. When you submit a batch job, the system executes your login command procedure only to the point at which the preceding command is placed.

Submitting Multiple Command Procedures

When you enter the SUBMIT command, you can specify several command procedures to be executed in one job. Unless you specify a name with the /NAME qualifier, the SUBMIT command uses the name of the first command procedure as the job name. Note that if an error causes any command procedure in a job to exit, the entire job terminates.

When a batch job executes, the operating context of the first procedure (UPDATE.COM) is not preserved for the second procedure (SORT.COM). The system deletes local symbols created by UPDATE.COM before SORT.COM executes. Global symbols, however, are preserved.

You cannot specify different parameters for individual command procedures within a single job.

In the following example, the SUBMIT command creates a batch job that executes UPDATE.COM then SORT.COM:

$ SUBMIT UPDATE,SORT Job UPDATE (queue SYS$BATCH, entry 207) started on SYS$BATCH

The following example passes the same two parameters to UPDATE.COM and to SORT.COM:

$ SUBMIT UPDATE, SORT/PARAMETERS = - _$ (DISK1:[ACCOUNT.BILLS]DATA.DAT, DISK2:[ACCOUNT]NAME.DAT) $ Job UPDATE (queue SYS$BATCH, ENTRY 208) started on SYS$BATCH

16.5.2 Passing Data to Batch Jobs

The default input stream (SYS$INPUT) for a batch job is the command procedure that is being executed. Because a detached process is executing the batch job, you cannot redefine SYS$INPUT to the terminal (as you can with command procedures that you execute interactively.) To pass input to a batch job, use one of the following techniques:

• Include the data in the command procedure itself.
  To include data in a command procedure, place the data on the lines after the command or image.
• Temporarily define SYS$INPUT as a file.
  To define SYS$INPUT temporarily as a file, use the DEFINE/USER_MODE command.
• Pass parameters to the command procedure when you submit it for execution.
  To pass parameters to a command procedure, use the /PARAMETERS qualifier when you submit the batch job.

Note that you cannot specify different parameters for individual command procedures within a single job. Use separate SUBMIT commands if you need to pass different groups of parameters.

In the following example, data lines are passed to the image AVERAGE.EXE:

$! Execute AVERAGE.EXE $ RUN AVERAGE 647 899 532 401 $ EXIT

In the following example, SYS$INPUT is temporarily defined as a file:

$ DEFINE/USER_MODE SYS$INPUT STATS.DAT $ RUN AVERAGE $ EXIT

In the following example, the parameters in the file EMPLOYEES.DAT are passed to the command procedure CHECKS.DAT:

$ SUBMIT/PARAMETERS=(DISK1:[PAYROLL]EMPLOYEES.DAT) CHECKS Job CHECKS (queue SYS$BATCH, entry 209) started on SYS$BATCH

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.

16.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, refer to 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.

	privacy and legal statement
6489PRO_045.HTML