The getnim command

This page describes the inquiry-only command called getnim that users can use interactively and in scripts to get their account balances.

The command getnim replaces the setcub command for use in user scripts to query the NIM database to find out how much allocation is remaining and available to the user.

     NAME
	  getnim - query the NERSC banking database for	remaining
	  allocation

     SYNOPSIS
	  getnim [ -tthreshold ] -Rrname
	  or
	  getnim [ -tthreshold ] { -uuid | -Uuname }
	  or
	  getnim [ -tthreshold ] -Rrname { -uuid | -Uuname }
	  or
	  getnim [ -tthreshold ] -Rrname { -l |	-L }


     DESCRIPTION
	  The getnim command queries the NERSC account database	and returns
	  the amount of	resource time remaining	in the allocation, 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 zero or negative value indicates
	  that there is	no more	time within the	given allocation for
	  further execution.

	  For more detailed accounting information use the NERSC web
	  interface at http://hpcf.nersc.gov/accounts/nim/

	  The first and	third forms given above
	  getnim [ -tthreshold ] -Rrname
	  and
	  getnim [ -tthreshold ] -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 second form
	  getnim [ -tthreshold ] { -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 fourth form
	  getnim [ -tthreshold ] -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.

     OPTIONS
	  The following	options	have the interpretation:

	  -tthreshold	      getnim will return a zero	exit status if
			      the remaining balance is equal to	or
			      less than	the threshold value (specified
			      in decimal hours)	else non-zero.

	  -Rrname	      to specify the repository	name.

	  -uuid		      to specify the user id number.

	  -Uuname	      to specify the user name.

	  -l|-L		      give the charge info for each user in
			      the repository where the user is
			      identified by uid|uname.


     EXIT STATUS
	  The getnim command will have an exit status of 0 if the
	  returned remaining allocation	value is greater than the
	  threshold 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.  A return status of	2 or more indicate
	  that there was an error of some type.

	  For the second 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.

	  For the fourth form, which returns a list of users in	a
	  repository and charges.  The return status is	0 if any of
	  the user repository charge values are	greater	than or	equal
	  to the threshold.  The return	status is 1 if all are less.


     EXAMPLES
	  To find out which repositories you have access to and	how
	  much 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     999.84
	       mpabc   9999.99
	       mpabc1  200

	  However, some	of the repositories may	not apply to the
	  machine you are on currently (e.g. PVP repositories can not
	  be used on MPPs, etc.).

	  Look at the total resource time left for a given repository
	  with:

	       getnim -Rabc

	  Returning:

	       19948.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:

	       999.83


	  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	left in	the abc	repository for you:

	       set rv=`getnim -t 20 -U myname -R abc`
	       if ( $status == 0 ) then
		    ...	OK to run ...
	       else
		    ...	Not enough time	left ...
		    ...	Or an error occurred ...
		    echo "There	was only $rv hours left"
	       endif

	  Here is the equivalent Bourne	shell code snippet:

	       if rv=`getnim -t20 -Umyname -Rabc`
	       then
		    ...	OK to run ...
	       else
		    ...	Not enough time	left ...
		    ...	Or an error occurred ...
		    echo "There	was only $rv hours left"
	       fi


     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.