NAME
          pshare - Displays resource allocation and usage information from  the
          Resource Allocation & Control data base within the DPCS system.

     SYNOPSIS
          pshare    [-b bank-list] [-u user-list] [-0|O] [-H] [-%]
               [-m hostname]
          pshare    -[t|T] bank [-l n] [-0|O] [-H] [-%] [-m hostname]
          pshare    -r bank [-0|O] [-H] [-%] [-m hostname]
          pshare    -h

     DESCRIPTION
          pshare reads the RAC data base file and writes ascii records from  it
          to  stdout.   Information written depends on options specified on the
          command line.

          If the -b option is used, information about banks is written.  If the
          -u option is used, information about user allocations is written.  If
          the -t or -T option is used, information about banks and (in the case
          of  the -t option) user allocations is written in such a manner as to
          show the tree structure of the data base.  If the -r option is  used,
          information  about  the specified bank and all its parents up through
          and including the root bank is written.  If none of the above options
          are  used,  then  information about the calling user's allocations is
          written.

          In addition to a Resource Quota  allocation  scheme,  the  DPCS  also
          implements  a  "Fair  Share" allocation scheme.  These two allocation
          schemes are independent from each other and work to  accomplish  dif-
          ferent  goals.  The fair share system attempts to regulate short term
          "rate-of-delivery" to help assure that users get good  response  time
          and turn-around to the extent that they have been allocated access to
          compute resources.  Users and groups of users (that  is,  within  the
          context  of banks) are granted shares that represent their "claim" on
          the resources of computers being managed by DPCS.

          Each machine within the DPCS domain is a member of one and  only  one
          resource partition.  That is, computers are partitioned into resource
          partitions.  A resource partition may have one member computer or  it
          may  have  many.  Shares are allocated to each user and bank for each
          resource partition.  A share represents a user's or a bank's claim on
          the  computational resources capable of being generated at a resource
          partition such as memory and cpu time.  A user or bank may apply  the
          shares  allocated  to it for a resource partition on any of the hosts
          in a resource partition.

          When a bank is created or a user is permitted to  use  the  resources
          granted to a bank, shares are allocated to that bank or user for each
          existing resource partition.  The shares a user  or  bank  has,  when
          divided  by the total number of shares allocated to all its siblings,
          represents the portion of the shares granted to the parent bank  that
          are claimed by the user or bank.

          The number of shares assigned by an administrator to a user  or  bank
          is  called  the  "raw  shares".   The  portion of a parent bank's raw
          shares that can be claimed by a user or bank is called the "effective
          share".   Raw  shares  are assigned but effective shares are computed
          from the assigned raw shares.  For instance, assume there is  a  bank
          named  TOP  that has been assigned some number of raw shares.  Assume
          further that TOP's effective share of its parent bank has been calcu-
          lated  to  be .3 (or 30%).  Now, assume that TOP has 2 subbanks and 1
          user allocation named RIGHT, LEFT and bob,  respectively.   If  RIGHT
          has  50 raw shares, LEFT has 20 raw shares and bob has 30 raw shares,
          then RIGHT would have a .5 effective share of TOP's share (or  a  .15
          effective share of TOP's parent's share), LEFT would have a .2 effec-
          tive share of TOP's share (or a .06 effective share of TOP's parent's
          share),  and  bob  would have a .3 effective share TOP's share.  Note
          that if RIGHT, LEFT and bob had  been  assigned  20,  8  and  12  raw
          shares,  respectively,  then  their effective shares would remain the
          same because the ratios of their raw shares would still be 5:2:3.

          Shares are "normalized" with respect to users who are requesting that
          resources  be  delivered  to  them.  (In other words, are logged onto
          some machine or have a batch job that can run.)  So,  even  though  a
          user may be granted only a 0.01% effective share; if that user is the
          only user requesting resources, then his/  her  normalized  effective
          share  of  the machine is 1.0.  If two users are requesting resources
          and one use has a global effective share of .03 and the other has  an
          global  effective share of .12, then their normalized shares are DPCS
          would try to deliver 20% of the machine's resources to the first user
          and 80% of the machine's resources to the other user.

          DPCS attempts to direct resource usage  by  measuring  actual  usage,
          comparing  the  results  against  the normalized shares and adjusting
          "nice" values of sessions and scheduling jobs so  as  to  make  usage
          patterns conform to normalized share values.

          Each user allocation and bank has associated with it a "usage" value.
          This  value, in the banks and user allocation which authorizes usage,
          is incremented whenever a user uses the resources of a computer.   It
          is  also "decayed" on a regular basis.  The decay algorithm is called
          a "half-life decay" algorithm.  The algorithm is written such that if
          a  usage  value is not incremented during the half-life decay period,
          its value will be cut in half in that period.

          The information written is displayed  in  multi-column  format.   The
          headings for the columns are as follows (depending on whether the -u,
          the -b or -r, or the -t or -T option is used, respectively):

          RESOURCE PARTITION:  partition_name
          USERNAME BANKNAME --------SHARES--------  ------USAGE------
                            ALLOCATED   NORMALIZED  NORMALIZED    RAW
          BANKNAME PARENT   --------SHARES--------  ------USAGE------
                            ALLOCATED   NORMALIZED  NORMALIZED    RAW
          U/B NAME B/P  NAME                    --------SHARES--------   ------

          USAGE------
                                              ALLOCATED    NORMALIZED   NORMAL-
          IZED    RAW

          The columns are relatively self-explanatory:

          SHARES ALLOCATED
                          the nominal share granted to the user or  bank  which
                          may be applied to the resource partition of which the
                          specified or implied  hostname  is  a  member.   This
                          value  must  be interpreted by dividing it by the sum
                          of all nominal shares allocated to sibling  banks  or
                          user  allocations.   If  you  use the -% option, this
                          calculation is done for you.


          SHARES NORMALIZED
                          the instantaneous share of the resource partition  of
                          which  the  specified or implied hostname is a member
                          which is being applied  for  the  user  or  the  bank
                          expressed  as a portion of the total shares which can
                          be applied to the resource partition.

          USAGE NORMALIZED
                          the half-life decayed usage value expressed as a por-
                          tion  of  the  total  usage on the resource partition
                          being reported.

          USAGE RAW       the half-life decayed raw usage value.  This value is
                          incremented  as  the user or bank uses resources on a
                          host in the resource partition.   It  is  decremented
                          periodically according to the function

     u(now) = u(last) / {2 ^ [{T(now) - T(last)} / decay_rate])


                          The decay rate is set by a pcs manager and 
                          represents the amount  of  time which if  a  bank  
                          or  user allocation is not used, it will decay to 
                          half its starting value.

     OPTIONS
          -%              Show allocated shares as a percentage of the parent's
                          shares.

          -0 or -O        Do not list records that have 0 raw usage.

          -H              The reports are issued without  a  header  line  that
                          explains  the  columns.  If not used, the header line
                          is written to standard output.

          -T bank         Records are written for the bank  specified  and,  if
                          the -l option is not specified or has a value greater
                          than 0, then all of the bank's sub-banks.   The  tree
                          is  traversed  as  far as specified by the -l option.
                          If the -l option is not  specified,  all  levels  are
                          written.   This  option  may not be used with the -b,
                          -r, -t or -u options.

          -b bank-list    Information about the banks in the list is displayed.
                          The  list  must  be comma separated.  This option may
                          not be used with the -T, -r or -t options.

          -h              A friendly usage message  is  displayed,  and  pshare
                          terminates.

          -l levels       The number of levels of a sub-tree to display if  the
                          -T or -t option is used.  This option may not be used
                          if neither the -t option nor the -T option  is  used.
                          The number of levels must be greater than or equal to
                          0.

          -m hostname     Will show allocation  information  for  the  resource
                          partition  of  which  hostname  is a member.  If this
                          option is not used, the value  for  hostname  is  the
                          host on which pshare is being executed.  To see allo-
                          cation information for all resource partitions in the
                          DPCS  domain,  use  an  escaped  asterisk (\*) as the
                          hostname.  (Beware of shell interpretation of  the  *
                          character.)

          -r bank         Records are written for the specified bank  and  each
                          of  its  parents  up  through  and including the root
                          bank.  This option may not be used with the  -T,  -b,
                          -t or -u options.

          -t bank         This option is identical  to  the  -T  option  except
                          that,  in  addition,  user  allocations to the listed
                          banks are also listed.  This option may not  be  used
                          with the -T, -b, -r or -u options.

          -u user-list    Information about the users in the list is displayed.
                          The  list  must  be comma separated.  This option may
                          not be used with the -T, -r or -t  options.

     EXAMPLES
          pshare
               report the status of the calling user's allocations  to  his/her
               current  bank  on  the  resource  partition of which the host on
               which pshare is being executed is a member.

          pshare -u joan,steve,mary
               report the status of users steve, joan and mary  access  to  all
               their banks

          pshare -b sab,fll
               report the status of the banks sab and fll.

          pshare -t fll -l 3
               report the status of all child nodes of fll down  three  genera-
               tion levels.

          pshare -l 3 -T root
               report the status of the top three levels of the rdb but  report
               only banks.  Do not report user allocations.

          pshare -t root -0
               report the status of all banks and user allocations  from  which
               some time has been used.

          pshare -T root -0
               report the status of all banks from which  some  time  has  been
               used.  Do not report user allocations.

          pshare -t root -0
               report the status of all banks and user allocations  from  which
               some time was used.

          pshare -r sab
               report the status of bank sab and all of its parents up  through
               the root bank.

          pshare -u joan -b sab
               report all allocations for user joan and report  the  status  of
               bank sab

     FILES
          /usr/local/adm/pcs/rdb     RAC data base

     EXIT CONDITIONS
          If there is an error, pshare returns an exit status of 1.

     AUTHOR
          Robert Wood, Lawrence Livermore National Laboratory,
               bwood@llnl.gov

     SEE ALSO
          bac, defbank, newbank, pquota, pcsmgr