NERSCPowering Scientific Discovery Since 1974

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)