gbch-var - access batch variables from shell
gbch-var [ -options ] variable name
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''.
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
.
causes a summary of the other options to be displayed without taking further action.
Create the variable if it doesn't exist. An initial value should be supplied using the -s option.
Assign or update the given comment field of the variable to be string.
Delete the variable.
Mark the variable as ``exported'', i.e. visible to other hosts.
Change the group ownership of the variable to group.
Set the ``clustered'' marker on the variable. When used in conditions or assignments, the local version is used.
Reset the ``clustered'' marker on the variable.
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.
Set the mode (permissions) on the variable.
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.
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.
Force all set values to string even if they appear numeric.
Assign the given value to the variable.
Change the ownership of the variable to user.
In the test operations, if the variable does not exist, treat it as if it did exist and had the given value.
cancel options -S, -C, -D, -s and -u.
Save the current options in a .gnubatch file in the current
directory with keyword BTVAR
. Comparison options are not included.
Save all the current options in a .gnubatch file in the user's home
directory with keyword BTVAR
. Comparison options are not included.
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.
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.
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.
~/.gnubatch configuration file (home directory)
.gnubatch configuration file (current directory)
btrest.help message file
space-separated options to override defaults.
location of alternative help file.
gbch-q(1), gbch-vlist(1), btsyntax(5), gbch-cvlist(8).
Various diagnostics are read and printed as required from the message file btrest.help.
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.
John M Collins, Xi Software Ltd.