gbch-jchange - change batch jobs
gbch-jchange [ -options ] job number ...
gbch-jchange is a program to modify details of a job or jobs from a shell script or another program. Jobs are specified by using the job number, as displayed by gbch-r(1) with the -v (verbose) option, or as in the output of the first column of the gbch-jlist(1) command with default format.
Remote jobs should be specified by prefixing the job numbers with the host name thus:
host:1234
It is not necessary to specify any leading zeros.
Several jobs may be specified at once to apply the same set of changes to all of them at once.
As supplied, the options to gbch-jchange are more or less identical to those for gbch-r, except that existing jobs have their parameters changed from whatever they are to the specified parameters, and there is no "default", in that mentioning an option means that the user requires an existing parameter for the job or jobs changed. For details of the syntax and much of the meaning of the options, please see the documentation of gbch-r(1) at the corresponding option.
It is a mistake not to specify any options at all.
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_JCHANGE
and the
environment variable to specify the help file is BTRESTCONF
.
causes a summary of the other options to be displayed without taking further action.
change the secondary maximum run time to time seconds (time may be a number of seconds, or mm:ss for minutes and seconds).
change the "if not possible" action of the job or jobs to "catch up".
signifies days to avoid when the job or jobs are repeated. The
interpretation of the option syntax, and default days is just the same
as for gbch-r(1), but the existing "days to avoid" in each job is
replaced completely with the result. For example, the default days are
Sat
and Sun
, so
-A ,Wed
Will incorporate the default days to avoid taken from the help file, adding Wednesday and change the days to avoid in the job or jobs to Saturday, Sunday and Wednesday.
Specify an argument for the job or jobs. The argument will be added to the end of the arguments already in the job or jobs or added by previous -a arguments to gbch-jchange unless the -e option is used, which will discard any pre-existing arguments in the job or jobs as well as any previously-specified -a arguments.
Marks subsequently specified assignments as "not critical", i.e. an assignment of a variable on an inaccessible remote host will be ignored. Existing assignments are not affected.
Marks subsequent assignments as "critical", i.e. an assignment of a variable on an inaccessible remote host will cause the job to be held up. Existing assignments are not affected.
Sets the job or jobs to "cancelled" state.
Sets a condition on the job or jobs. This will add an extra condition to existing conditions in the job or jobs or preceding -c unless the -y option is given to discard any previously-specified conditions.
Sets the working directory for the job or jobs.
Cancels any repeat option of the job or jobs so that they will be deleted at the end of the next run.
Resets the environment for the job or jobs to be that of the environment of the gbch-jchange command.
Deletes any existing arguments for the job or jobs.
Marks the job or jobs to be visible throughout the network, but only liable to run on the machine which they are on.
Sets the flags which determine when an assignment is performed for subsequent -s options. Will not affect any existing assigments.
Marks the job or jobs to be visible throughout the network and potentially available to run on any machine.
Resets the group owner of the job or jobs to group.
Note that the setting of the group is done as a separate operation from any other changes. Depending upon whether the pre-existing and new modes and ownership permit the various operations, this may need to be done before, after or interleaved with other changes for it to succeed.
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. Note that this may be done whilst the job or jobs are running.
Sets a redirection for the job or jobs. This will add the redirection to any existing redirections for the job or jobs unless they are all reset first using the -Z option.
Sets the command interpreter for the job or jobs to be name. This will also reset the load level of the job or jobs to be that of the command interpreter. If the load level is to be different from this value, use the -l option after this option.
Sets the flag so that if the job or jobs exit with an error, the next time to run is not advanced.
Sets the flag so that if the job or jobs exit with an error, the next time to run is still advanced if applicable.
Marks subsequent conditions as "not critical", i.e. a condition dependent on a variable on an inaccessible remote host will be ignored. Does not affect any conditions already defined.
Marks subsequent conditions as "critical", i.e. a condition dependent on a variable on an inaccessible remote host will cause the job to be held up. Does not affect any conditions already defined.
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.
Sets the permissions of the job or jobs to be modes. The format of the modes argument is defined in more detail below.
Note that the setting of the mode is done as a separate operation from any other changes. Depending upon whether the pre-existing and new modes and ownership permit the various operations, this may need to be done before, after or interleaved with other changes to succeed.
Sets the flag whereby completion messages are mailed to the owner of the job or jobs.
Sets the job or jobs to normal "ready to run" state.
Marks the job or jobs to be local only to the machines which they are on.
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. Note that the specified priority must be in the range given by the user's minimum and maximum priority.
Sets a job queue name as specified on the job or jobs.
Sets the "if not possible" action of the job or jobs to reschedule all - the run is done when it is possible and subsequent runs are rescheduled.
Sets the repeat option of the jobs as specified.
Sets the "if 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. The assignment will be added to those already defined unless the existing assignments are cleared first with the -z option.
Sets the next run time 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.
Cancels any time setting on the job or jobs.
Resets the owner of the job or jobs to user.
Note that the setting of the user is done as a separate operation from any other changes. Depending upon whether the pre-existing and new modes and ownership permit the various operations, this may need to be done before, after or interleaved with other changes to succeed.
Sets the signal 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 for example
-X N0:9
Resets both flags as set by -m and -w.
Sets a maximum run time for the specified job or jobs. time is in seconds, which may be expressed as hh:mm:ss.
Deletes any existing conditions in the job or jobs.
Deletes any existing redirections in the job or jobs.
Deletes any existing assignments in the job or jobs.
Save all the current options in a .gnubatch file in the current directory. If no jobs are specified, this will not be treated as an error and the program will exit after saving the options.
Save all the current options in a .gnubatch file in the user's home directory. If no jobs are specified, this will not be treated as an error and the program will exit after saving the options.
<a name="Change_mode_argument"></a> 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 job, group and other permissions are set to the same value.
An alternative format allows permissions to be added to the existing permissions, thus
-M U:+WD,G:+D
will add the relevant permissions to whatever is currently set.
Similarly permissions may be cancelled individually by constructs of the form:
-M G:-W,O:-RS
If the same operation is to be done with two or more of U
, G
or
O
, the letters may be run together, for example
-M GO:+W
Changing various parameters, the mode (permissions), the owner and the group are done as separate operations.
In some cases changing the mode may prevent the next operation from taking place. In other cases it may need to be done first.
Similar considerations apply to changes of the owner and the group.
Btjchange does not attempt to work out the appropriate order to perform the operations, the user should execute separate gbch-jchange commands in sequence to achieve the desired effect.
~/.gnubatch configuration file (home directory)
.gnubatch configuration file (current directory)
btrest.help message file
space-separated options to override defaults.
path name of alternative message file.
btsyntax(5)
,
gnubatch.conf(5),
gnubatch.hosts(5),
gbch-r(1),
gbch-jlist(1),
gbch-jdel(1),
gbch-user(1),
gbch-rr(1).
Various diagnostics may be issued if the user attempts operations which are not permitted to him or her, or if various errors are detected. The diagnostics are read as required from the message file rest.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.