GBCH-RR(1)

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.

-? 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, the most important of which is %t, which inserts the job title. See the Reference manual.

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.