gbch-var - access batch variables from shell

# NAME

gbch-var - access batch variables from shell

# SYNOPSIS

gbch-var [ -options ] variable name

# DESCRIPTION

gbch-var is a shell level tool to display, create, delete, modify or test the values of GNUbatch variables. Testing may be "atomic", in the sense that if two or more users attempt to assign new values to the same variable conditional on a test, only one will "win".

# OPTIONS

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

-C or +create

  Create the variable if it doesn't exist. An initial value should be supplied using the -s option.

-c string or +comment string

  Assign or update the given comment field of the variable to be string.

-D or +delete

  Delete the variable.

-E or +set-export

  Mark the variable as "exported", i.e. visible to other hosts.

-G group or +set-group group

  Change the group ownership of the variable to group.

-K or +cluster

  Set the "clustered" marker on the variable. When used in conditions or assignments, the local version is used.

-k or +no-cluster

  Reset the "clustered" marker on the variable.

-L or +set-local

  Mark the variable as local to the host only. This is the default for new variables, for existing variables it will turn off the export flag if it is specified. To leave existing variables unaffected, invoke the -N flag.

-M mode or +set-mode mode

  Set the mode (permissions) on the variable.

-N or +reset-export

  Reset the -L and -E options. For new variables this will restore to the default of local only. For existing variables this will mean that the export flag is left unchanged.

-o or +reset-cluster

  Reset the -k and -K options. For new variables this will restore to the default of not clustered. For existing variables this will mean that the cluster flag is left unchanged.

-S or +force-string

  Force all set values to string even if they appear numeric.

-s value or +set-value value

  Assign the given value to the variable.

-U user or +set-owner user

  Change the ownership of the variable to user.

-u value or +undefined-value value

  In the test operations, if the variable does not exist, treat it as if it did exist and had the given value.

-X or +cancel

  cancel options -S, -C, -D, -s and -u.

+freeze-current

  Save the current options in a .gnubatch file in the current directory with keyword `BTVAR`. Comparison options are not included.

+freeze-home

  Save all the current options in a .gnubatch file in the user's home directory with keyword `BTVAR`. Comparison options are not included.

# CONDITIONS

The six conditions `+eq`, `+ne`, `+gt`, `+ge`, `+lt` `+le` followed by a constant compare the variable value with the constant specified. The constant is assumed to be on the right of the comparison, for example:

            gbch-var +gt 4 myvar

Returns an exit code of zero ("true" to the shell) if `myvar` is greater than 4, or 1 ("false" to the shell) if it is less than or equal to 4. (Some other exit code would be returned if `myvar` did not exist.

This may be combined with other options, for example

            gbch-var -D +gt 100 myvar

Would delete `myvar` only if its value was greater than 100.

            gbch-var -s 1 +le 0 myvar

Would assign 1 to `myvar` only if its previous value was less than or equal to 0. Exit code 0 (shell "true") would be returned if the test succeeded and the other operation was completed successfully, exit code 1 (shell "false") would be returned if the test failed and nothing was done, or some other error if the variable did not exist or the operation was not permitted.

The test is "atomic" in the sense that a diagnostic will occur, and no assignment made, if some other process sets the value in between the test and the assignment (or other change).

The condition must follow all other options.

+eq, +ne, +lt and +gt may be represented as -e, -n, -l and -g but this is not particularly recommended, especially for the last two.

## Use of options

With no options, then the current value of the variable is printed, for example:

            gbch-var abc

prints out the value of variable `abc`.

To assign a value, the -s option should be used, thus

            gbch-var -s 29 abc

assigns the numeric value 29 to `abc`.

Remote variables are referred to as follows:

            gbch-var -s 32 host2:def

assigns 32 to variable `def` on `host2`.

The conditional options should be the last to be specified.

The -u option may be used to specify a value to substitute for a non-existent variable in a test rather than reporting an error, for example:

            gbch-var -u 10 -gt 5 myvar

will compare `myvar` with 5 if it exists. If it does not exist, then it will compare the given value, in this case 10, with 5, and in this case return "true". There should not be a diagnostic unless there is a completely different error.

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

Btvar does not attempt to work out the appropriate order to perform the operations, the user should execute separate gbch-var 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_VAR

  space-separated options to override defaults.

BTRESTCONF

  location of alternative help file.

# SEE ALSO

gbch-q(1), gbch-vlist(1), `btsyntax(5)`, gbch-cvlist(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.