1 04/24/86  acquire_resource, aqr
  2 
  3 Syntax as a command:  aqr type STR1 {...STRN} {-control_args}
  4                  or:  aqr type -number N {-control_args}
  5 
  6 
  7 Function: selects a resource of a given type from a free pool of all
  8 such resources and makes you the accounting owner of the resource.  You
  9 are given full control over the access rights for all users of the
 10 resource, as well as control over many parameters of the resource.
 11 Ownership of the resource is terminated via the release_resource
 12 command.
 13 
 14 
 15 Arguments:
 16 type
 17    is a resource type defined in the resource type description table
 18    (RTDT).
 19 STRi
 20    is the unique identifying name of the particular resource being
 21    acquired.  If STR looks like a control argument, precede it by -name
 22    (-nm).  If you give no -name, a resource is chosen to satisfy the
 23    constraints imposed by the control arguments given (if any).
 24 
 25 
 26 Control arguments:
 27 -access_class accr, -acc accr
 28    sets the initial AIM access class parameters, where accr is an
 29    access class range.  Users at any authorization within the access
 30    class range inclusive are allowed to read and write to the resource
 31    (provided they also meet other access requirements).  This control
 32    argument requires that you also provide -priv.
 33 -acs_path path
 34    specifies the pathname of the access control segment (ACS) for this
 35    resource.  You must create the ACS and set the desired access
 36    control list.  If the ACS doesn't exist or you don't specify it, the
 37    default access is rew to the accounting owner and null to all
 38    others.  If path is a null string, the existing ACS, if any, is
 39    disassociated from the resource.
 40 
 41 
 42 -alloc STR
 43    sets the allocation state of the resource to free or allocated,
 44    where STR must be either "on" or "off": on sets the allocation
 45    state to allocated; off, to free.  If you supply no -alloc, the
 46    allocation state is free.  (The allocation state flag is a
 47    convenience to you and is largely ignored by resource management.)
 48 -attributes STR, -attr STR
 49    searches for resources possessing the attributes specified in STR.
 50    If you give -attributes in conjunction with -name, then the resource
 51    specified by the explicit name is searched for, and, when found, its
 52    attributes are set to those specified with -attr.
 53 -comment STR, -com STR
 54    specifies the desired value of the comment string for this resource,
 55    where STR can be an arbitrary comment string with a maximum length
 56    of 168 characters.
 57 
 58 
 59 -lock STR
 60    locks or unlocks the resource, preventing or allowing use of that
 61    resource, where STR must be either "on" or "off": on prevents any
 62    of the resource; off allows use of the resource.  (Default: off)
 63 -number N, -nb N
 64    specifies that the number of such resources to be acquired is N.  If
 65    you select no -number, 1 is assumed.  You can choose -number only if
 66    you don't provide a name.
 67 
 68 
 69 -owner STR, -ow STR
 70    specifies that this is an acquisition on behalf of the user
 71    specified by STR.  If STR is given as "system", then the resource is
 72    assigned to the system pool; if given as "free", then the resource
 73    is acquired to the free pool (effectively the same as no -owner).
 74    If STR is of the form Person_id.Project_id (where neither Person_id
 75    nor Project_id can be a star), the user specified has all the rights
 76    of ownership to the resource, as if he had acquired it personally
 77    except that if you give "-release_lock on", the owner can't release
 78    (give up ownership of) the resource voluntarily.  This control
 79    argument requires that you also specify -priv.
 80 -priv
 81    specifies that a privileged call is to be made to obtain the status
 82    of this resource (see "Access Required" below).
 83 
 84 
 85 -release_lock STR, -rll STR
 86    specifies whether this resource can be released by the owner or only
 87    by a privileged process (see "Access Required" below), where STR
 88    must be either "on" or "off".  If you provide no -release_lock, the
 89    resource can be released by the owner.  This control argument
 90    requires that you use -priv.
 91 
 92 
 93 Access required: You need execute access to the rcp_admin_ gate to use
 94 -access_class, -owner, or -release_lock.
 95 
 96 
 97 Notes: This command acquires a resource for either you (requestor) or
 98 the user specified by -owner.  If you are registered on more than one
 99 project and need corresponding access or other users (on any project)
100 need access to acquire a resource, you must create or modify the ACS.
101 You must then specify the new/modified ACS by issuing this command
102 using -acs_path.  The User_id, a Person_id.Project_id pair, specifies
103 the user to be added to or deleted from the ACS.