GBCH-JCHANGE(1)

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