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.