NAME

gbch-jchange - change batch jobs


SYNOPSIS

gbch-jchange [ -options ] job number ...


DESCRIPTION

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.


OPTIONS

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.

-? or +explain

causes a summary of the other options to be displayed without taking further action.

-2 time or +grace-time time

change the secondary maximum run time to time seconds (time may be a number of seconds, or mm:ss for minutes and seconds).

-9 or +catch-up

change the "if not possible" action of the job or jobs to "catch up".

-A days or +avoiding-days days

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.

-a string or +argument string

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.

-B or +assignment-not-critical

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.

-b or +assignment-critical

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.

-C or +cancelled

Sets the job or jobs to "cancelled" state.

-c condition or +condition condition

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.

-D directory or +directory directory

Sets the working directory for the job or jobs.

-d or +delete-at-end

Cancels any repeat option of the job or jobs so that they will be deleted at the end of the next run.

-E or +reset-environment

Resets the environment for the job or jobs to be that of the environment of the gbch-jchange command.

-e or +cancel-arguments

Deletes any existing arguments for the job or jobs.

-F or +export

Marks the job or jobs to be visible throughout the network, but only liable to run on the machine which they are on.

-f flags or +flags-for-set flags

Sets the flags which determine when an assignment is performed for subsequent -s options. Will not affect any existing assigments.

-G or +full-export

Marks the job or jobs to be visible throughout the network and potentially available to run on any machine.

-g group or +set-group group

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.

-H or +hold-current

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.

-h title or +title title

Sets the title of the job or jobs to title. Note that this may be done whilst the job or jobs are running.

-I redirection or +input-output redirection

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.

-i name or +interpreter name

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.

-J or +no-advance-time-error

Sets the flag so that if the job or jobs exit with an error, the next time to run is not advanced.

-j or +advance-time-error

Sets the flag so that if the job or jobs exit with an error, the next time to run is still advanced if applicable.

-K or +condition-not-critical

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.

-k or +condition-critical

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.

-L value or +ulimit value

Sets the ulimit value of the job or jobs to the value given.

-l number or +loadlev number

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.

-M modes or +mode modes

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.

-m or +mail-message

Sets the flag whereby completion messages are mailed to the owner of the job or jobs.

-N or +normal

Sets the job or jobs to normal "ready to run" state.

-n or +local-only

Marks the job or jobs to be local only to the machines which they are on.

-o or +no-repeat

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.

-P value or +umask value

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.

-p number or +priority number

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.

-q queuename or +job-queue queuename

Sets a job queue name as specified on the job or jobs.

-R or +reschedule-all

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.

-r repeat option or +repeat repeat option

Sets the repeat option of the jobs as specified.

-S or +skip-if-held

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.

-s assignment or +set assignment

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.

-T time or +time time

Sets the next run time of the job or jobs as specified.

-t time or +delete-time time

Sets a delete time for the specified job or jobs as a time in hours after which it will be automatically deleted.

-U or +no-time

Cancels any time setting on the job or jobs.

-u user or +set-owner user

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.

-W sig or +which-signal sig

Sets the signal to kill the job or jobs after the maximum run time has been exceeded.

-w or +write-message

Sets the flag whereby completion messages are written to the owner's terminal if available.

-X range or +exit-code range

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
-x or +no-message

Resets both flags as set by -m and -w.

-Y time or +run-time time

Sets a maximum run time for the specified job or jobs. time is in seconds, which may be expressed as hh:mm:ss.

-y or +cancel-condition

Deletes any existing conditions in the job or jobs.

-Z or +cancel-io

Deletes any existing redirections in the job or jobs.

-z or +cancel-set

Deletes any existing assignments in the job or jobs.

+freeze-current

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.

+freeze-home

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.

Mode arguments

<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:

R

read permission

W

write permission

S

reveal permission

M

read mode

P

set mode

U

give away owner

V

assume owner

G

give away group

H

assume group

D

delete

K

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

Note on mode and owner changes

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.


FILES

~/.gnubatch configuration file (home directory)

.gnubatch configuration file (current directory)

btrest.help message file


ENVIRONMENT

GBCH_JCHANGE

space-separated options to override defaults.

BTRESTCONF

path name of alternative message file.


SEE ALSO

btsyntax(5), gnubatch.conf(5), gnubatch.hosts(5), gbch-r(1), gbch-jlist(1), gbch-jdel(1), gbch-user(1), gbch-rr(1).


DIAGNOSTICS

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

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.


AUTHOR

John M Collins, Xi Software Ltd.