NAME

gbch-r - submit a job to batch scheduler

gbch-rr - submit a job to remote batch scheduler


SYNOPSIS

gbch-r [ -options ] [ files ]

gbch-rr [ -options ] [ files ]


DESCRIPTION

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.


OPTIONS

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. The bts command in GNUbatch2 (Xi-Batch Rel 7) introduces the new concept of templates carrying most of the information supplied as options to gbch-r.

-? or +explain

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

-2 time or +grace-time time

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.

-9 or +catch-up

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.

-. or +done

sets the job or jobs to ``done'' state (this is mainly intended for resubmitting jobs which have been ``unqueued'').

-A days or +avoiding-days days

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.

-a string or +argument string

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.

-B or +assignment-not-critical

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.

-b or +assignment-critical

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.

-C or +cancelled

Sets the job or jobs to be in ``cancelled'' state.

-c condition or +condition condition

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.

-D directory or +directory directory

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.

-d or +delete-at-end

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.

-E or +local-environment

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.

-e or +cancel-arguments

deletes any arguments set up by previous options.

-F or +export

marks the job or jobs to be visible throughout the network, but only available to run on the machine which they are queued on.

-f letters or +flags-for-set

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.

-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

set the group owner of the job or jobs to be group. The user must have write admin file permission to invoke this argument.

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

-I redirection or +input-output redirection

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.

-i name or +interpreter name

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.

-J or +no-advance-time-error

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.

-j or +advance-time-error

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.

-K or +condition-not-critical

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.

-k or +condition-critical

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.

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

-M modes or +mode modes

sets the permissions of the job or jobs to be modes.

-m or +mail-message

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

-N or +normal

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.

-n or +local-only

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.

-O or +remote-environment

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.

-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, which must be in the range given by the user's minimum and maximum priority.

-Q hostname or +host hostname

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

-q queuename or +job-queue queuename

sets a job queue name as specified on the job or jobs. This may be any sequence of printable characters.

-R or +reschedule-all

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.

-r repeat_spec or +repeat repeat_spec

sets the repeat option of the jobs as specified.

-S or +skip-if-held

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.

-s or +set

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.

-T time or +time time

sets the next run time or time and date 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 if this time has elapsed since it was queued or last ran. Set to zero to retain the job or jobs indefinitely.

-U or +no-time

cancels any time setting on the job or jobs set with -T, -r or -o options.

-u user or +set-owner user

set the owner of the job or jobs to be user. The user must have write admin file permission to invoke this argument.

-V or +no-verbose

cancel the effect of the -v option, so that a message is not output giving the job number of each batch job successfully created

-v or +verbose

output a message on standard error containing the job number of each batch job successfully created.

-W sig or +which-signal sig

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.

-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

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

-x or +no-message

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

-Y time or +run-time time

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.

-y or +cancel-condition

deletes any conditions set up by previous arguments.

-z or +cancel-set

deletes any assignments set up by previous arguments.

-Z or +cancel-io

deletes any redirections set up by previous arguments.

+freeze-current

Save all the current options in a .gnubatch file in the current directory with keyword BTR for gbch-r or RBTR for gbch-rr.

+freeze-home

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.

Redirection format

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.

n<file

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

n>file

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

n>>file

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.

n<>file

For example

        8<>Data
        <>Myfile

Connect the file descriptor (or file descriptor 0 if not specified) for input and output, read-write mode.

n<>>file

For example

        8<>>Data
        <>>Myfile

Select read-write mode, appending to existing data.

n<|program

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

n|program

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

n&n

Duplicate the second file descriptor as the first file descriptor

n&-

Close the given file descriptor.

Repeat periods

The repeat period names for the -r option are as follows:

Minutes

Period in minutes

Hours

Period in hours

Days

Period in days

Weeks

Period in weeks

Monthsb

Months relative to the beginning

Monthse

Months relative to the end of the month

Years

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.

Conditions

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'

Assignments

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:

S

Perform assignment on startup

N

Perform assignment on normal exit

E

Perform assignment on error exit

A

Perform assignment on abort

C

Perform assignment on cancellation

R

Reverse assignment for N, E, A, and C.

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.

STARHERE=

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.

=exitcode

Assign the exit code of the job to the given variable. Flags are ignored and the operation only occurs when the job exits.

=signal

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.

Mode arguments

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 user, group and other permissions are set to the same value.


FILES

~/.gnubatch configuration file (home directory)

.gnubatch configuration file (current directory)

btrest.help message file


ENVIRONMENT

GBCH_R

space-separated options to override defaults.

BTRESTCONF

location of alternative help file.


SEE ALSO

gbch-jchange(1), gbch-jlist(1), gbch-vlist(1), gbch-var(1), btsyntax(5), gnubatch.conf(5), gnubatch.hosts(5), xbnetserv(8).


DIAGNOSTICS

Various diagnostics are read and printed as required from the message file btrest.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.