.!
.!  File:	BAT.RNH
.!
.!  Author:	Hunter Goatley
.!
.!  Date:	May 20, 1991
.!
.!  Description:
.!
.!	RUNOFF source file for BAT on-line help.
.!
.!	To build:	$ RUNOFF BAT.RNH
.!			$ LIBR/HELP/INSERT libr BAT
.!
.!  Modification history:
.!
.!	01-004		Hunter Goatley		15-JUL-1992 15:34
.!		Updated info on /NAME.
.!
.!	01-003		Hunter Goatley		29-FEB-1992 21:18
.!		Added /PREFIX.
.!
.!	01-002		Hunter Goatley		21-JUN-1991 08:03
.!		Added /KEEP, /LOG_FILE, /PRINTER, /RESTART.
.!
.!	01-001		Hunter Goatley		20-MAY-1991 15:59
.!		Genesis.
.!
.noflags
.lm3 .rm70
.indent -3
1 BAT
.br
BAT will submit a series of commands to a batch queue, eliminating the need
for the user to manually create a command procedure to perform the tasks.
.sk
Commands to be executed in batch may be specified on the command line;
multiple commands can be separated by "|".  If commands are not given
on the command line, BAT will prompt for commands until a null line or CTRL-Z
is entered.
.sk
The temporary command procedure that is created contains commands to set
VERIFY and to change the default directory for the batch job to the current
default directory of the process running BAT.
.sk
Format:
.sk;.lm+4
$ BAT [/qualifiers] [command [|command...]]
.lm-4
.indent -3
2 Parameters
.sk;.indent -3
[/qualifiers]
.sk
All BAT qualifiers must immediately follow the BAT verb to be recognized as
BAT qualifiers.
.sk;.indent -3
[command [|command...]]
.sk
A command or list of commands that are to be executed in batch.  Multiple
commands separated by "|" (vertical bar) may be specified.
.sk
.indent -3
2 Qualifiers
.sk
.!------------------------------------------------------------------------------
.indent -3
/AFTER
.sk;.indent -1
/AFTER=time
.br;.indent -1
/NOAFTER
.sk
Requests that the job be held until after a specific time. If the specified time
has passed already, the job is processed immediately.
.sk
You can specify time as either an absolute time or as a combination of absolute
and delta times. For complete information on specifying time values, see the VMS
DCL Concepts Manual.
.sk
.!------------------------------------------------------------------------------
.indent -3
/CPUTIME
.sk;.indent -1
/CPUTIME=time
.sk
Defines a CPU time limit for the batch job. You can specify time
as delta time, 0, INFINITE, or NONE. If the queue on which the
job executes has a defined CPUMAXIMUM value, the smaller of the
SUBMIT command and queue values is used. If the queue on which
the job executes does not have a specified maximum CPU time limit,
the smaller of the SUBMIT command and user authorization file
UAF) values is used. If the queue on which the job executes
does not have a specified maximum CPU time limit and the UAF has
a specified CPU time limit of NONE, either the value 0 or the
keyword INFINITE allows unlimited CPU time. If you specify the
keyword NONE, the specified queue or UAF value is used. CPU time
values must be greater than or equal to the number specified by
the SYSGEN parameter PQL_MCPULM.
.sk
Unlike many DCL commands, if days are specified, the delta time must be
enclosed in quotes.
.sk
.!------------------------------------------------------------------------------
.indent -3
/HOLD
.sk;.indent -1
/HOLD
.br;.indent -1
/NOHOLD (default)
.sk
Controls whether the job is made available for immediate
processing. The /HOLD qualifier holds the job until it is released
by the SET ENTRY/RELEASE or the SET ENTRY/NOHOLD command.
.sk
.!------------------------------------------------------------------------------
.indent -3
/LOG_FILE
.sk;.indent -1
/LOG_FILE[=filespec] (default)
.br;.indent -1
/NOLOG_FILE
.sk
Names the log file. No wildcards (* and %)  are allowed in the
file specification.
.sk
When you use the /LOG_FILE qualifier, the system writes the batch
job's output to the file you specify. If you use the /NOLOG_FILE
qualifier, no log file is created. By default, a log file
is created, using SYS$LOGIN:name.LOG as the default file name, where
"name" is the name of the batch job.
.sk
.!------------------------------------------------------------------------------
.indent -3
/KEEP
.sk;.indent -1
/KEEP
.br;.indent -1
/NOKEEP (default)
.sk
Controls whether or not the temporary command file is deleted.  Note: BAT
does not use /KEEP in the same that SUBMIT uses /KEEP.
.sk
.!------------------------------------------------------------------------------
.indent -3
/NAME
.sk;.indent -1
/NAME=job-name
.sk
Names the job, the temporary command procedure, and the batch log file
(unless /NOLOG is given).  The job name must specify a valid file name
of up to 39 characters.  The default job name is BATCHTMP_xxxxxxxx, where
"xxxxxxxx" is the PID of the current process.
.sk
.!------------------------------------------------------------------------------
.indent -3
/NOTIFY
.sk;.indent -1
/NOTIFY (default)
.br;.indent -1
/NONOTIFY
.sk
Controls whether a message is broadcast to your terminal session
when the job is completed or aborted.
.sk
.!------------------------------------------------------------------------------
.indent -3
/PREFIX
.sk;.indent -1
/PREFIX="Prefix" (defaults to /PREFIX="(!8%T) ")
.br;.indent -1
/NOPREFIX
.sk
Specifies the argument to the DCL command SET PREFIX, which is included at
the beginning of the BAT temporary command procedure.  The prefix string
should be surrounded by quotes and can contain some FAO directives, including
"!%T" and "!%D".  For more information, consult the on-line help for SET PREFIX.
.sk
Because the SET PREFIX command was introduced with VMS v5.5,
this qualifier should only be specified on VMS v5.5 and higher.  On other
versions of VMS, a non-fatal error will occur for each batch job.
.sk
.!------------------------------------------------------------------------------
.indent -3
/PRINTER
.sk;.indent -1
/PRINTER=[queue-name]
.br;.indent -1
/NOPRINTER (default)
.sk
Queues the job log file for printing when your job is completed.
The /PRINTER qualifier allows you to specify a particular print
queue; the default print queue is SYS$PRINT.
.sk
.!------------------------------------------------------------------------------
.indent -3
/PRIORITY
.sk;.indent -1
/PRIORITY=n
.sk
Requires OPER (operator) or ALTPRI (alter privilege) privilege to
specify a priority greater than the value of the SYSGEN parameter
MAXQUEPRI.
.sk
Specifies the job-scheduling priority for the batch job with
respect to other jobs in the same queue. The value of n is an
integer in the range of 0 to 255, where 0 is the lowest priority
and 255 is the highest.
.sk
The default value is the value of the SYSGEN parameter DEFQUEPRI.
No privilege is needed to set the priority lower than the
MAXQUEPRI value.
.sk
The /PRIORITY qualifier has no effect on the job's process
execution priority. The job's process execution priority is
determined by the base priority attribute of the INITIALIZE/QUEUE
/BASE_PRIORITY command.
.sk
.!------------------------------------------------------------------------------
.indent -3
/QUEUE
.sk;.indent -1
/QUEUE=queue-name[:]
.sk
Identifies the batch queue on which the job is entered. The
default queue is SYS$BATCH.
.sk
.!------------------------------------------------------------------------------
.indent -3
/RESTART
.sk;.indent -1
/RESTART
.br;.indent -1
/NORESTART (default)
.sk
Indicates whether the job restarts after a system failure or after
a STOP/QUEUE/REQUEUE command.
.sk
.!------------------------------------------------------------------------------
.indent -3
/USER
.sk;.indent -1
/USER=username
.sk
Requires CMKRNL (change mode to kernel) privilege and read (R)
and write (W)  access to the user authorization file (UAF).
.sk
Allows you to submit a job on behalf of another user. The job
runs exactly as if that user had submitted it. The job runs
under that user's user name and user identification code (UIC),
and accounting information is logged to that user's account.
By default, the user identification comes from the requesting
process. The username qualifier value can be any user name that is
validated on your system. The name must be 1 to 12 alphanumeric
characters.
.sk
.!------------------------------------------------------------------------------
.indent -3
/WSDEFAULT
.sk;.indent -1
/WSDEFAULT=n
.sk
Defines for a batch job a working set default, the default number
of physical pages that the job can use. If the queue on which the
job executes has a nonzero default working set, the smaller of
the specified job and queue values is used. If the queue on which
the job executes has a working set default of 0, the smaller of
the specified job and UAF values (value established in the user
authorization file) is used. If you specify the value 0 or NONE,
the specified queue or UAF value is used. Working set default
values must range between the numbers specified by the SYSGEN
parameters PQL_MWSDEFAULT and WSMAX.
.sk
.!------------------------------------------------------------------------------
.indent -3
/WSEXTENT
.sk;.indent -1
/WSEXTENT=n
.sk
Defines for the batch job a working set extent, the maximum
amount of physical memory that the job can use. The job uses
the maximum amount of physical memory only when the system has
excess free pages. If the queue on which the job executes has a
nonzero working set extent, the smaller of the specified job and
queue values is used. If the queue on which the job executes has a
working set extent of 0, the smaller of the specified job and the
value established in the user authorization file (UAF) is used. If
you specify the value 0 or NONE, the specified queue or UAF value
is used. Working set extent values must range between the numbers
specified by the SYSGEN parameters PQL_MWSEXTENT and WSMAX.
.sk
.!------------------------------------------------------------------------------
.indent -3
/WSQUOTA
.sk;.indent -1
/WSQUOTA=n
.sk
Defines for the batch job a working set quota, the amount of
physical memory that the job is guaranteed. If the queue on which
the job executes has a nonzero working set quota, the smaller of
the specified job and queue values is used. If the queue on which
the job executes has a working set quota of 0, the smaller of the
specified job or the value established in the user authorization
file (UAF) is used. If you specify the value 0 or NONE, the
specified queue or UAF value is used. Working set quota values
must range between the numbers specified by the SYSGEN parameters
PQL_MWSQUOTA and WSMAX.
.!------------------------------------------------------------------------------
.sk;.indent -3
2 Reading_From_SYS$INPUT
.br;
In a batch job, SYS$INPUT is defined as the command procedure itself.  BAT
treats all input lines as implicit DCL commands; in order to specify data
to be read by a program, the DECK and EOD (end of deck) keywords should
be used.  See subtopic Examples for an example of the use of DECK and EOD.
.!------------------------------------------------------------------------------
.sk;.indent -3
2 Examples
.br;
.literal
1.  $ BAT SHOW USER|SHOW SYSTEM|SHOW TIME
    Job BATCHTMP ... started on ...
.end literal
.sk
In this example, 3 commands have been entered on the command line.  The
three commands will all be executed by a single batch job.
.sk
.literal
2.  $ BAT
    _Command: SHOW USER
    _Command: SHOW SYSTEM
    _Command: SHOW TIME|SHOW QUOTA
    _Command:
    Job BATCHTMP ... started on ...
    $
.end literal
.sk
In this example, no commands were given on the command line, so BAT prompts
for individual commands.
.sk
.literal
3.  $ BAT
    _Command: MAIL
    _Command: DECK
    _Deck: PURGE/RECLAIM
    _Deck: COMPRESS
    _Deck: EOD
    _Command:
    Job BATCHTMP ... started on ...
    $
.end literal
.sk
In this example, the DECK and EOD keywords are used to allow program
input from SYS$INPUT.
.sk