gbch-r - submit a job to batch scheduler
gbch-rr - submit a job to remote batch scheduler
gbch-r [ -options ] [ files ]
gbch-rr [ -options ] [ files ]
gbch-r creates a GNUbatch batch job from each of the supplied files or the standard input if no file names are given.
gbch-rr operates similarly, but creates the jobs on a remote host without the necessity of having to have GNUbatch running on the submitting host.
Except for the -Q option, which must be specified, and the options keyword used to pick up default arguments and to save with the +freeze-current and +freeze-home options, the (standard - it would be possible to make them different by editing the option definitions in btrest.help but this would not be sensible) options to gbch-rr are identical in effect to those for gbch-r.
Note that the order of treatment, letters and keywords described below
may be modified by editing the file btrest.help -
see btsyntax(5)
.
The environment variable on which options are supplied is GBCH_R
for
gbch-r, GBCH_RR
for gbch-rr and the environment variable to specify the
help file is BTRESTCONF
.
We regret having run out of single letters for options to gbch-r and gbch-rr and having had to resort in three cases to non-alphabetic options.
causes a summary of the other options to be displayed without taking further action.
Sets the second stage time of handling over-running jobs to time,
in seconds (the argument may be any number of seconds, or given as
mm:ss
for minutes and seconds).
This only applies if a maximum elapsed time for a job is set with the
-Y option. If a non-zero time is also given with this option, the
job is first killed with the signal number given by the -W option
and then, if it continues to run for the time given by this argument,
killed with SIGKILL
which cannot be caught or ignored.
sets the "if not possible" action of the job or jobs to catch up - one run of a series of missed runs is done when it is possible without affecting future runs.
sets the job or jobs to "done" state (this is mainly intended for resubmitting jobs which have been "unqueued").
signifies days to avoid when the job or jobs are to be repeated
automatically. The days to avoid option supersedes any preceding or
default option, unless a leading comma is given. Thus if the existing
days to avoid are Sat
and Sun
, the default when installed,
gbch-r -A Wed
will change the days to avoid to be Wednesday only, whereas
gbch-r -A ,Wed
will change the days to avoid to be Saturday, Sunday and Wednesday.
A single -
argument cancels the days to avoid parameter altogether,
thus -A-
.
Note that this parameter only affects automatic repetitions, so if the date given by the -T parameter falls on a day excluded by this argument, it will not be affected and the first run will be on the date specified.
Upon installation the default abbreviations for the days are Sun
,
Mon
, Tue
, Wed
, Thu
, Fri
, Sat
and Hday
, the last
refers to holidays as specified in the holiday file. The days are
interpreted case-insensitively, but on saving options with
+freeze-current or +freeze-home will save the names in the
initial capital format.
Provide an argument string to the command interpreter. Successive -a options are cumulative and append additional arguments to the list of arguments for the job or jobs. To clear previously-specified options (maybe set in .gnubatch files) and start afresh, use the -e option first.
Marks subsequently-specified assignments (with the -s option) as "not critical", meaning that the assignment will be ignored if it contains a reference to a variable on a remote host which is offline or inaccessible. This must precede the -s options to which it is to be applied.
Marks subsequently-specified assignments (with the -s option) as "critical", meaning that the job or jobs will not start if the assignment contains a reference to a variable on a remote host which is offline or inaccessible. This must precede the -s options to which is to be applied.
Sets the job or jobs to be in "cancelled" state.
Sets a condition to be satisfied before the job or jobs may run. Successive -c options cause further conditions to be appended to the list, up to a maximum of 10 conditions. To start from scratch, deleting any previously-specified conditions (in a .gnubatch file perhaps), use the -y option first.
Sets the working directory for the job or jobs. This may include
environment variable references preceded by $
to be expanded and
constructs such as ~user
to select the given user's home
directory. (Remember, if using the shell, and using these constructs,
to put quotes around the directory, otherwise the shell will expand
the constructs and not GNUbatch).
If omitted, then the current directory at the time of invoking gbch-r or gbch-rr is used.
cancels any repeat option of the jobs so that they will be deleted at the end of the run rather than repeated or kept. This is the default if no arguments are specified.
set the environment variables to be as per the local environment rather than the remote environment. This applies to gbch-rr only and is ignored in gbch-r.
deletes any arguments set up by previous options.
marks the job or jobs to be visible throughout the network, but only available to run on the machine which they are queued on.
Precede -s (set assignment) options with this and an argument
consisting of some or all of SNEACR
(for respectively Start, Normal
exit, Error exit, Abort, Cancel and Reverse) to set the flags which
determine when an assignment is performed.
marks the job or jobs to be visible throughout the network and potentially available to run on any machine.
set the group owner of the job or jobs to be group. The user must have write admin file permission to invoke this argument.
sets the "if not possible" action of the job or jobs to hold current - the run is done when it is possible without affecting subsequent runs.
sets the title of the job or jobs to title. In the absence of this argument the title will be that of the last part of the file name, if any. The title may be a string of any length containing any printable characters.
sets a redirection for the job or jobs. Successive -I options are cumulative and will append to the current list of redirections. To start the list of redirections from scratch, precede them with the -Z option.
sets the command interpreter for the job or jobs to be name. The load level is also set to that for the interpreter, so if a -l argument is to be specified, it should follow the -i argument.
The command interpreter will be rejected if its load level exceeds the maximum per job for a user.
sets the flag so that if the job exits with an error, the next time to run is not advanced according to the repeat specification.
sets the flag so that if the job exits with an error, the next time to run is still advanced if applicable. This is the default if no arguments are specified.
marks subsequently specified conditions set with the -c option as "not critical", i.e. a condition dependent on a variable on an offline or otherwise inaccessible remote host will be ignored in deciding whether a job may start. This is the default if no arguments are specified.
marks subsequently specified conditions set with the -c option as "critical", i.e. a condition dependent on a variable on an offline or otherwise inaccessible remote host will cause the job to be held up.
sets the ulimit value of the job or jobs to the value given.
sets the load level of the job or jobs to be number. The user must have special create permission for this to differ from that of the command interpreter and further the load level must be less than the maximum per job for a user. The load level is also reset by the -i (set command interpreter) option, so this must be used before the -l option.
sets the permissions of the job or jobs to be modes.
sets the flag whereby completion messages are mailed to the owner of the job. (They may anyway if the jobs output to standard output or standard error and these are not redirected).
sets the job or jobs to normal "ready to run" state, as opposed to "cancelled" as set by the -C option. This is the default if no arguments are specified.
marks the job or jobs to be local only to the machines which they are queued on. They will not be visible or runnable on remote hosts.
initialise the environment variables to be those from the remote environment. This applies to gbch-rr only and is ignored in gbch-r. This is the default if no arguments are specified.
cancels any repeat option of the job or jobs, so that the they will be
run and retained on the queue marked done
at the end.
sets the umask value of the job or jobs to the octal value given. The value should be up to 3 octal digits as per the shell.
sets the priority of the job or jobs to be number, which must be in the range given by the user's minimum and maximum priority.
send the job or jobs to the given hostname. Note that hostname must be in gnubatch.hosts on the submitting machine and the submitting machine's hostname must be in /etc/ on the receiving machine.
If specified with gbch-r, the effect is to invoke gbch-rr with the same command-line options as were given to gbch-r. Note that this does not include any options for gbch-r extracted from the environment or .gnubatch files.
This option is mandatory for gbch-rr and it will fail if it is not specified. gbch-r is not invoked as otherwise there might be an endless loop of calls (with -Q specified in a .gnubatch file for gbch-r but not for gbch-rr for example).
sets a job queue name as specified on the job or jobs. This may be any sequence of printable characters.
sets the "not possible" action of the job or jobs to reschedule all - the run is done when it is possible and subsequent runs are rescheduled by the amount delayed.
sets the repeat option of the jobs as specified.
sets the "not possible" action of the job or jobs to skip - the run is skipped if it could not be done at the specified time.
sets an assignment on the job or jobs to be performed at the start and/or finish of the job or jobs as selected by a previously-specified -f option. This option is cumulative, and will add to the list of assignments specified by previous -s options. To start from scratch, precede the assignments with the -z option.
sets the next run time or time and date of the job or jobs as specified.
sets a delete time for the specified job or jobs as a time in hours, after which it will be automatically deleted if this time has elapsed since it was queued or last ran. Set to zero to retain the job or jobs indefinitely.
cancels any time setting on the job or jobs set with -T, -r or -o options.
set the owner of the job or jobs to be user. The user must have write admin file permission to invoke this argument.
cancel the effect of the -v option, so that a message is not output giving the job number of each batch job successfully created
output a message on standard error containing the job number of each batch job successfully created.
used in conjunction with -Y and -2 options sets the signal number, e.g. 1, 2, 15 to kill the job or jobs after the maximum run time has been exceeded.
sets the flag whereby completion messages are written to the owner's terminal if available.
sets the normal or error exit code ranges for the job or jobs. The
format of the range argument is N or E followed by a range in
the form nn:nn
, thus
-X N0:9
and
-X E10:255
Note that an exit code which falls inside both ranges will be handled by the setting of the smaller range, so
-X N0:10 -X E1:255
will mean that exit codes 1 to 10 inclusive are treated as normal
as that is the smaller range. Unhandled exit codes are treated as
abort. The default is N0:0
and E1:255
.
resets both flags as set by -m and -w.
sets a maximum elapsed run time for the specified job or jobs. The
argument time is in seconds, which may be written as mm:ss or
hh:mm:ss. The job will be killed with SIGKILL
unless a different
signal is specified with the -W option and a further "grace time"
specified with the -2 option.
deletes any conditions set up by previous arguments.
deletes any assignments set up by previous arguments.
deletes any redirections set up by previous arguments.
Save all the current options in a .gnubatch file in the current
directory with keyword BTR
for gbch-r or RBTR
for gbch-rr.
Save all the current options in a .gnubatch file in the user's home
directory with keyword BTR
for gbch-r or RBTR
for gbch-rr.
The format of the argument to the -I option is similar to that for the shell with some extensions. The argument should always be enclosed in quotes to avoid the shell interpreting it rather than gbch-r or gbch-rr.
Environment variables and ~user
constructs are expanded at run time
in the strings.
Parameter substitutions, or "meta data" may be included in the argument strings for redirections, see meta data.
For example
3<myfile 7</tmp/data <input_file
Opens the specified file descriptor for input connected to the specified file. The file descriptor may be omitted in the common case of file descriptor 0 (standard input).
For example
4>outfile 12>/tmp/out 2>errors.%t >output_file
Opens the specified file descriptor for output, possibly creating the file, or truncating it to zero length first if it exists. The file descriptor may be be omitted in the common case of file descriptor 1 (standard output).
For example
5>>Log 7>>Log.%t >>output.%t
As with the shell, this likewise creates the output file if it does not exists but appends new data to any previous data if it exists, rather than truncating it.
For example
8<>Data <>Myfile
Connect the file descriptor (or file descriptor 0 if not specified) for input and output, read-write mode.
For example
8<>>Data <>>Myfile
Select read-write mode, appending to existing data.
For example
7<|uname
Run the specified program and take input from it on the given file descriptor (defaulting to standard input, file descriptor 0, if not specified).
For example
2|log_errors |log_output
Run the specified program and send output to it on the given file descriptor (defaulting to standard output, file descriptor 1, if not specified).
Duplicate the second file descriptor as the first file descriptor
Close the given file descriptor.
The repeat period names for the -r option are as follows:
Period in minutes
Period in hours
Period in days
Period in weeks
Months relative to the beginning
Months relative to the end of the month
Period in years
Each is followed by the number of the relevant periods after a colon. In the case of the month parameters, then this should be followed by a "target day" after a colon.
Examples:
-r Days:4 -r Monthsb:1:4 -r Monthse:1:31 -r Years:2
For Monthsb
the "target day" is the day of the month to aim for, in
this case the 4th of the month. If this would be a "day to avoid",
then the following day is tried and so on.
For Monthse
the "target day" is selected from the day of the month given
in the -T option. So if the month in the -T option has 31 days,
then
-r Monthse:1:31
will select the last day of each month and
-r Monthse:1;30
will select the second last, but if the month in the -T option has 30 days, the first will be invalid and the second will select the last day of the month.
If the selected day cannot be met for any reason, typically because it does not meet the "days to avoid" criteria, then the previous day is tried until an acceptable day is found. In this way you can select the "last working day of the month" or "next to last working day" etc.
A condition must be of the form
[machine:]<varname><condop><constant>.
where varname is the name of an existing variable for which the user has read permission.
condop is one of the following:
equal to
not equal
less than
less than or equal
greater than
greater than or equal
constant is either a string or a numeric value. If the string starts with a number then it should be preceded with a colon.
N.B. When invoked from a shell, quotation marks should surround the entire argument as shown above, otherwise the shell may attach its own interpretation on the various characters.
Examples of conditions:
-c 'Count>3' -c 'Lock=0' -c 'Remote:Lock!=0' -c 'Val=:3rd'
Each assignment should normally be preceded by a -f option to denote when the assignment is applied, apart from exit code and signal assignments.
The argument to the -f option is one or more of the following:
Perform assignment on startup
Perform assignment on normal exit
Perform assignment on error exit
Perform assignment on abort
Perform assignment on cancellation
The default if no -f options are specified is
-f SNEAR
but the default for this may be changed by editing the message file.
The format of the argument to the -s option is in the format
[machine:]<varname><operator><constant>.
varname is the name of a variable to which the user has read and write permission.
operator is one of the following:
Assign value which may be a string or numeric constant. To indicate that a string starting with a digit is intended to be a string, prefix it with a colon. Exceptionally, the variable assigned to may have write permission and not read permission for the user.
The effect of the "reverse" flag is to assign zero or the null string. Previous values are not recalled.
Increment variable by numeric constant. The effect of the "reverse" flag is to decrement the variable by that constant.
Arithmetic is as 32-bit signed integer.
Decrement variable by numeric constant. The effect of the "reverse" flag is to increment the variable by that constant.
Arithmetic is as 32-bit signed integer.
Multiply variable by numeric constant. The effect of the "reverse" flag is to divide the variable by that constant.
Arithmetic is as 32-bit signed integer and overflow is ignored.
Divide variable by numeric constant. The effect of the "reverse" flag is to multiply the variable by that constant.
Arithmetic is as 32-bit signed integer. Note that the remainder from division is ignored.
The handling of negative numbers may be dependent on the hardware and should probably not be relied upon.
Take the remainder (modulus) from division by the numeric constant. There is no "reverse" of the operation.
Arithmetic is as 32-bit signed integer. The handling of negative numbers may be dependent on the hardware and should probably not be relied upon.
Assign the exit code of the job to the given variable. Flags are ignored and the operation only occurs when the job exits.
Assign the signal number with which the job terminated to the given variable, or zero if the job did not exit with a signal. Flags are ignored and the operation only occurs when the job exits.
The following are examples of assignments:
-s 'myvar=7' -s 'host2:hisvar+=1' -s 'status=exitcode' -s 'val=:3rd'
Note the colon in the last assignment indicating that the value is a string, the colon is not included in the string.
The argument to the -M option provides for a wide variety of operations.
Each permission is represented by a letter, as follows:
read permission
write permission
reveal permission
read mode
set mode
give away owner
assume owner
give away group
assume group
delete
kill
Each section of the mode (user, group, others) is represented by the
prefixes U:
, G:
and O:
and separated by commas.
For example:
-M U:RWSMPDK,G:RWSDK,O:RS
would set the permissions for the user, group and others as given. If the prefixes are omitted, as in
-M RWSDK
then all of the user, group and other permissions are set to the same value.
~/.gnubatch configuration file (home directory)
.gnubatch configuration file (current directory)
btrest.help message file
space-separated options to override defaults.
location of alternative help file.
gbch-jchange(1),
gbch-jlist(1),
gbch-vlist(1),
gbch-var(1),
btsyntax(5)
,
gnubatch.conf(5),
gnubatch.hosts(5),
xbnetserv(8)
.
Various diagnostics are read and printed as required from the message file btrest.help.
Copyright (c) 2009 Free Software Foundation, Inc. This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.
John M Collins, Xi Software Ltd.