getnim - NIM's Command Line Interface
This page describes the inquiry-only command called getnim that users can use interactively and in scripts to get their account balances.
GETNIM(l) NERSC GETNIM(l)
NAME
getnim - query the NERSC banking database for remaining allocation,
resources and repository information
SYNOPSIS
getnim [ options ] -Rrname
or
getnim [ options ] -Rrname { -uuid | -Uuname }
or
getnim [ options ][ -D ] { -uuid | -Uuname }
or
getnim [ options ] -Rrname { -l | -L }
or
getnim [ options ] -Fbatchname
PARAMETERS
-R<rname> to specify the repository name
-U<uname> to specify the user name
-u<uid> or specify the user uid
-l | -L give the charge info for each user in the reposi-
tory where the user is identified by uid|uname
respectively.
-Fbatchname returns the resource, machine and charge factors
for the given batchname or returns -1 if not found,
or use these factors to weight the given threshold
value.
OPTIONS
-h some helpful usage info only
-q quiet output. Only shell output if requested.
-S be forgiving of Client/Server errors by setting the
exit value to zero for these type errors. Error
messages still go to stderr though. Usage errors
and insufficient allocation still result in non-
zero exit values.
-tthreshold getnim will return a zero exit status if the
remaining balance is equal to or greater than the
threshold value (in decimal hours) else non-zero.
If the -F option is given then the threshold is
weighted by the machine and resource charge fac-
tors. The default threshold value is zero, if this
option is not given.
-Hhostname use this NERSC hostname instead of the value in the
NERSC_HOST environment variable.
-c return C-shell environment variables
-s return Bourne shell environment variables
-p return Perl variables.
-D only consider the user's default repository with -U
or -u for the given host.
DESCRIPTION
The getnim command queries the NERSC account database and
returns the amount of resource time remaining in the alloca-
tion, either at a repository level or at the user level.
The numbers returned are all in decimal hours with at most two
decimal digits of precision. A value less than or equal to the
threshold value indicates that there is insufficient time
within the given allocation for further execution. If no
threshold value is given then the threshold is assumed to be
zero.
The getnim tool can return information regarding the resource
charge factors also (machine and resource priority charge fac-
tors).
For more detailed accounting information use the NERSC web
interface at http://nim.nersc.gov .
The first and second forms given above:
getnim [ -tthreshold ][ -Fbatchname ] -Rrname
and
getnim [ -tthreshold ][ -Fbatchname ] -Rrname { -uuid | -Uuname}
returns a single value representing the decimal hours left in
the given repository as a whole or for the given user taking
into account the user's percentage of the repository they are
allowed to use.
The third form:
getnim [ -tthreshold ][ -D ][ -Fbatchname ] { -uuid | -Uuname }
will return a list of repositories, one per line, followed by a
tab character and the user's remaining balance within the
repository accounting for the percentage the user is allowed to
use of the repository. The repositories are arranged with the
default repo first.
However, if the -D option is given then only the default repo
is shown and the threshold is only considered against this
repository. If shell variables are requested then DEFAULT_REPO
is defined in either case.
The fourth form:
getnim -Rrname { -l | -L }
will return a list of users for the given repository, one per
line, followed by a tab character and the amount the user has
charged to the repository.
Finally:
getnim -Fbatchname
will return the resource for the given queue batchname, as well
as the machine and resource priority charge factor. For exam-
ple, typically the premium batch queue will be the HIGH
resource with a priority charge factor of 2.0 or twice the nor-
mal rate. The machine factor reflects the relative speed of
the machine compared to the NERSC base machine unit.
SHELL VARIABLES
If either the -c, -s, or -p shell options are given then the
repository or user information will go to stderr, and some
variables can be defined via eval. See the examples below.
Some or all of the following variables will be defined:
GETNIM_EXIT Exit return value.
GETNIM_ERROR Explanation if the exit return value is
non-zero.
NERSC_CHARGE_FACTOR Charge factor for the given resource.
NERSC_MACHINE_FACTOR
The relative weight for the given machine
relative to the base NERSC machine.
NERSC_RESOURCE The resource for the given batch.
NERSC_HOST The NERSC host used for determining the
various factors.
DEFAULT_REPO The user's default repository.
EXIT STATUS
The getnim command will have an exit status of 0 if the
returned remaining allocation value is greater than the thresh-
old and there is no error; else it will return an exit status
of 1 if the returned allocation is less than or equal to the
threshold.
However, if the batchname is scavenger or the like the sense of
the exit status is reversed. Only users in repos with no allo-
cation left can submit to or run in the scavenger queues. The
threshold is not used in this determination at all.
A return status of 2 or more indicate that there was an error
of some type.
For the third form, which returns a list of repositories and
values. The return status is 0 if any of the allocation values
are greater than or equal to the threshold. The return status
is 1 if all are less.
Exit Value Explanation
0 Successful completion and remaining alloca-
tion exceeds the threshold.
1 Successful completion but remaining alloca-
tion insufficient for the threshold, or may
not have access to premium resources.
2 No valid arguments given.
3 Can not have both -u and -U options.
4 Need to give an integer to use -u.
7 Need to give a decimal to use -t.
8 Invalid input, probably due to non-existent
repo or user name or uid.
18 XML packet parsing error - this is a server
error.
21 Invalid server status - this is a server
error.
25 timeout - this is a server or network
error.
27 bad server status - this is an unspecified
server error.
89 Can not connect to the server - this is a
server or network error.
99 this is a client logic error.
All exit values greater than 10 represent some type of
client/server/network error and you may need to notify NERSC
user services of the problem.
EXAMPLES
To find out which repositories you have access to and how much
allocation time you have left in each of these repositories,
perform the following command with your own username:
getnim -Umyname
Which will return something like this:
abc 9999.84
mpabc 99999.99
mpabc1 2000
Where the first repo is the default one for the system. How-
ever, some of the repositories may not apply or be enabled for
the machine you are on currently. To show only the default
repository then add the -D option.
Look at the total resource time left for a given repository
with:
getnim -Rabc
Returning:
199948.12
Note, this value is the remaining resource time for the given
repository, not your allocation of the repository resources
(which is determined by the repository manager).
To specifically view your allocation from the repository:
getnim -Rabc -Umyname
Returning:
9999.84
To look at the repository charges by the repository members:
getnim -L -Rabc
Returning something similar to:
lniawng 1204.13
lsum 0
lumzoro 0.03
majid 4920.32
minel 0
meulerl 0
The threshold value can be useful for batch scripts. Suppose
you want to have your batch script to run only if there is
enough resources left. The following C-shell code snippet
demonstrates a conditional based on the threshold value. In
this case, run if there are at least 20 resource hours,
weighted by the machine and priority factors for the reg_big
batch class, left in the abc repository for you:
set hours=`getnim -t 20 -F reg_big -U myname -R abc`
if ( $status == 0 ) then
... OK to run ...
else
... Not enough time left ...
... Or an error occurred ...
echo "There was only $hours allocation hours left"
endif
Here is the equivalent Bourne shell code snippet:
if hours=`getnim -t20 -Freg_big -Umyname -Rabc`
then
... OK to run ...
else
... Not enough time left ...
... Or an error occurred ...
echo "There was only $hours allocation hours left"
fi
FURTHER SHELL EXAMPLES
Use the shell options above, to get more detailed information
from getnim. The remaining hours left is generally not impor-
tant for script handling and can be elided with the -q option.
The environment variables defined will give the specific exit
return value as well as any error message if non-zero, along
with the factors and resource designation used, and perhaps the
default repository for the given user.
The following example shows the C-shell usage:
eval `getnim -q -c -Umyuser -F premium -Rabc -t1000`
Or the Bourne shell version, where the default repository will
be used:
eval `getnim -q -s -Umyuser -F premium -D -t1000`
The default repository name will be in the DEFAULT_REPO envi-
ronment variable. In either case the GETNIM_EXIT environment
variable should be examined and if non-zero then the explana-
tion for the non-zero value will be in the GETNIM_ERROR envi-
ronment variable. If the GETNIM_EXIT value is 1, then either
'insufficient allocation' or 'no access to premium queues'
caused the exit value. For values greater than 1 and less than
10 these are typically usage errors, and values greater than 10
are network/client/server errors.
Perl variables can be defined also, but special care must be
taken if "use strict" is enabled. In that case the following
code fragment should work:
use strict;
use warnings;
our ($NERSC_CHARGE_FACTOR, $NERSC_MACHINE_FACTOR);
our ($NERSC_RESOURCE, $NERSC_HOST);
our ($GETNIM_EXIT, $GETNIM_ERROR, $DEFAULT_REPO);
eval `getnim -q -p -H hopper -F debug -U myuser -t 9999 -D`;
WARNING
The repository and user allocation values are rolled-up on a
nightly basis and will not reflect any current charges.
DIAGNOSTICS
Error messages should be self-explanatory.
SEE ALSO
http://nim.nersc.gov
http://www.nersc.gov/nusers/accounts/nim/
AUTHOR
R.K.Owen,Ph.D. NERSC
NERSC Accounting Tools - 21 Oct 2011 GETNIM(l)
