MULTICS TECHNICAL BULLETIN                                MTB-736

To:       MTB Distribution

From:     Kevin P. Fleming

Date:     January 29, 1986

Subject:  Additional Subroutine Documentation

Abstract:

This MTB  contains documentation for various  external subroutine
interfaces that are not currently  documented in AG93-05.  An MCR
will follow to include this  documentation in the MR 12.0 release
of AG93.

Comments should sent to the author:

via Multics Mail:
    KFleming on System-M or CISL-SERVICE-MULTICS

via Telephone:
    (602) 249-6771 or HVN 249-6771

_________________________________________________________________

Multics  Project  internal  working  documentation.   Not  to  be
reproduced or distributed outside the Multics Project.


MTB-736                       Additional Subroutine Documentation

                             CONTENTS

                                                         Page

       hcs_$get_access_info . . . . . . . . . . . . . .   1
       hcs_$get_access_info_seg . . . . . . . . . . . .   3
       hcs_$get_initial_ring  . . . . . . . . . . . . .   5
       hcs_$get_ring_brackets . . . . . . . . . . . . .   6
       hcs_$high_low_seg_count  . . . . . . . . . . . .   6
       hcs_$lv_attached . . . . . . . . . . . . . . . .   7
       hcs_$set_dnzp_sw . . . . . . . . . . . . . . . .   8
       hcs_$set_dnzp_sw_seg . . . . . . . . . . . . . .   9
       mdc_$check_mounted . . . . . . . . . . . . . . .   10
       mdc_$get_lv_access . . . . . . . . . . . . . . .   10
       rcp_ . . . . . . . . . . . . . . . . . . . . . .   11
       rcp_$attach  . . . . . . . . . . . . . . . . . .   14
       rcp_$check_attach  . . . . . . . . . . . . . . .   17
       rcp_$detach  . . . . . . . . . . . . . . . . . .   18
       rcp_$get_status  . . . . . . . . . . . . . . . .   19
       rcp_$list_resources  . . . . . . . . . . . . . .   21

____________________                         ____________________

hcs_$get_access_info                         hcs_$get_access_info
____________________                         ____________________

NAME: HCS_$GET_ACCESS_INFO

hcs_$get_access_info  returns all of  the access attributes  of a
storage system object, given its pathname.

USAGE

declare hcs_$get_access_info entry (char(*), char(*), fixed
     bin(1), ptr, fixed bin(35));

call hcs_$get_access_info (dir_name, entryname, chase,
     entry_access_info_ptr, code);

ARGUMENTS

dir_name
   the directory containing the object about which information is
   to be returned.  (Input)

entryname
   the entryname of the object.  (Input)

chase
   indicates the action hcs_$get_access_info is to perform if the
   object is a link.  (Input) Its possible values are:
     0 - do not chase the link
     1 - chase the link.

entry_access_info_ptr
   points  to a structure  containing all the  access information
   for the object.  (Input)

code
   is  a  standard  system  status  code.   (Output) Its possible
   values are:

   error_table_$link
      if chase was not specified, then the pathname supplied is a
      link.  Otherwise,  the pathname supplied  eventually points
      to a null link.

   error_table_$null_info_ptr
      the entry_access_info_ptr supplied was null.

   error_table_$unimplemented_version
      the   requested  version    of  entry_access_info   is  not
      supported.

____________________                         ____________________

hcs_$get_access_info                         hcs_$get_access_info
____________________                         ____________________

NOTES

The following structure,  declared in entry_access_info.incl.pl1,
is pointed to by entry_access_info_ptr:

dcl 1 entry_access_info aligned based (entry_access_info_ptr),
    2 version                 char (8),
    2 type                    fixed bin,
    2 dir_name                char (168) unaligned,
    2 entryname               char (32) unaligned,
    2 uid                     bit (36) aligned,
    2 ring_brackets           (3) fixed bin (3),
    2 extended_ring_brackets  (3) fixed bin (3),
    2 effective_access_modes  bit (36) aligned,
    2 extended_access_modes   bit (36) aligned,
    2 access_class            bit (72) aligned,
    2 parent_access_class     bit (72) aligned,
    2 multiclass              bit (1) aligned;

STRUCTURE ELEMENTS

version
   must be set to ENTRY_ACCESS_INFO_VERSION_1.

type
   specifies the type of the object.  Its possible values are:
     0 link
     1 segment
     2 directory

dir_name
   the pathname of the entry's parent.

entryname
   primary name of the entry

uid
   the entry's unique identifer

ring_brackets
   the entry's ring  brackets.  For directories, ring_brackets(3)
   is not used.

extended_ring_brackets
   this has not been implemented.

effective_access_modes
   the user's effective access to this entry, taking into account
   ACLs, ring brackets, and AIM authorization.

____________________                     ________________________

hcs_$get_access_info                     hcs_$get_access_info_seg
____________________                     ________________________

extended_access_modes
   the user's extended access modes to this entry.

access_class
   the access class of the object.  If it is a multiclass object,
   the  maximum  access  class  from  which  the  object  can  be
   referenced.

parent_access_class
   the  access class  of the  object's parent.   For a multiclass
   object, the minimum access class  from which the object can be
   referenced.

multiclass
   is "1"b if the object is multiclass

ACCESS REQUIRED

This entrypoint requires s access  to the containing directory of
the object, or non-null access to the object itself.

             ________________________________________

NAME: HCS_$GET_ACCESS_INFO_SEG

hcs_$get_access_info_seg returns all of  the access attributes of
a storage system object, given a pointer to the segment.

USAGE

declare hcs_$get_access_info_seg entry (ptr, ptr, fixed bin(35));

call hcs_$get_access_info_seg (seg_ptr, entry_access_info_ptr,
     code);

ARGUMENTS

seg_ptr
   is a pointer  to the segment about which information  is to be
   returned.

entry_access_info_ptr
   points  to a structure  containing all the  access information
   for the object.  (Input)

code
   is  a  standard  system  status  code.   (Output) Its possible
   values are:

________________________                 ________________________

hcs_$get_access_info_seg                 hcs_$get_access_info_seg
________________________                 ________________________

   error_table_$null_info_ptr
      the entry_access_info_ptr supplied was null.

   error_table_$unimplemented_version
      the   requested  version    of  entry_access_info   is  not
      supported.

NOTES

The following structure,  declared in entry_access_info.incl.pl1,
is pointed to by entry_access_info_ptr:

dcl 1 entry_access_info aligned based (entry_access_info_ptr),
    2 version                 char (8),
    2 type                    fixed bin,
    2 dir_name                char (168) unaligned,
    2 entryname               char (32) unaligned,
    2 uid                     bit (36) aligned,
    2 ring_brackets           (3) fixed bin (3),
    2 extended_ring_brackets  (3) fixed bin (3),
    2 effective_access_modes  bit (36) aligned,
    2 extended_access_modes   bit (36) aligned,
    2 access_class            bit (72) aligned,
    2 parent_access_class     bit (72) aligned,
    2 multiclass              bit (1) aligned;

STRUCTURE ELEMENTS

version
   must be set to ENTRY_ACCESS_INFO_VERSION_1.

type
   specifies the type of the object.  Its possible values are:
     1 segment
     2 directory

dir_name
   the pathname of the entry's parent.

entryname
   primary name of the entry

uid
   the entry's unique identifer

ring_brackets
   the entry's ring  brackets.  For directories, ring_brackets(3)
   is not used.

________________________                    _____________________

hcs_$get_access_info_seg                    hcs_$get_initial_ring
________________________                    _____________________

extended_ring_brackets
   this has not been implemented.

effective_access_modes
   the user's effective access to this entry, taking into account
   ACLs, ring brackets, and AIM authorization.

extended_access_modes
   the user's effective extended access mode to this entry.

access_class
   the access class of the object.  If it is a multiclass object,
   the  maximum  access  class  from  which  the  object  can  be
   referenced.

parent_access_class
   the  access class  of the  object's parent.   For a multiclass
   object, the minimum access class  from which the object can be
   referenced.

multiclass
   is "1"b if the object is multiclass

ACCESS REQUIRED

This entrypoint requires s access  to the containing directory of
the object, or non-null access to the object itself.

             ________________________________________

NAME: HCS_$GET_INITIAL_RING

hcs_$get_initial_ring returns  the ring at which  the process was
logged in.

USAGE

declare hcs_$get_initial_ring entry (fixed bin);

call hcs_$get_initial_ring (initial_ring);

ARGUMENTS

initial_ring
   the  ring  number  at   which  the  process  began  execution.
   (Output)

_____________________                     _______________________

hcs_$get_initial_ring                     hcs_$high_low_seg_count
_____________________                     _______________________

ACCESS REQUIRED

No access is required.

             ________________________________________

NAME: HCS_$GET_RING_BRACKETS

hcs_$get_ring_brackets, given a pointer to a segment, will return
the ring brackets of the segment.

USAGE

declare hcs_$get_ring_brackets entry (ptr, (3) fixed bin(3),
     fixed bin(35));

call hcs_$get_ring_brackets (seg_ptr, brackets, code);

ARGUMENTS

seg_ptr
   is a pointer to the segment in question.  (Input)

brackets
   is  a three-element  array  that  contains the  segment's ring
   brackets.   (Output) Ring  brackets and  validation levels are
   discussed in "Intraprocess Access Control" in the Programmer's
   Reference Manual.

code
   is a storage system status code.  (Output)

ACCESS REQUIRED

The user must have status permission on the directory or non-null
access to the object.

             ________________________________________

NAME: HCS_$HIGH_LOW_SEG_COUNT

hcs_$high_low_seg_count returns information  about the lowest and
highest segment  numbers used in the  process, excluding hardcore
segments.

_______________________                          ________________

hcs_$high_low_seg_count                          hcs_$lv_attached
_______________________                          ________________

USAGE

declare hcs_$high_low_seg_count entry (fixed bin, fixed bin);

call hcs_$high_low_seg_count (nonhardcore_seg_count,
     lowest_nonhardcore_segno);

ARGUMENTS

nonhardcore_seg_count
   the  number   of  nonhardcore  segment  numbers   being  used.
   (Output)

lowest_nonhardcore_segno
   is the lowest nonhardcore segment number.  (Output)

ACCESS REQUIRED

No access is required.

             ________________________________________

NAME: HCS_$LV_ATTACHED

hcs_$lv_attached checks  to see if  a logical volume  is attached
and available for use in this process.

USAGE

dcl hcs_$lv_attached entry (bit(36) aligned) returns (fixed
     bin(35));

code = hcs_$lv_attached (lvid);

ARGUMENTS

lvid
   is the logical volume id.  (Input)

code
   is  a  standard  system  status  code.   (Output) Its possible
   values are:

   0
      the volume is attached and available for use.

   error_table_$logical_volume_not_connected
      the  volume is private  and has not  been attached in  this
      process

________________                                 ________________

hcs_$lv_attached                                 hcs_$set_dnzp_sw
________________                                 ________________

   error_table_$logical_volume_not_defined
      the volume specified by lvid is not known to the system

ACCESS REQUIRED

No access is required.

             ________________________________________

NAME: HCS_$SET_DNZP_SW

hcs_$set_dnzp_sw  allows  the  dnzp  switch  associated  with the
specified  segment to  be changed.   The "don't  null zero pages"
(dnzp) switch indicates  how zero pages of a  segment are written
to disk.

USAGE

declare hcs_$set_dnzp_sw entry (char(*), char(*), bit(1), fixed
     bin(35));

call hcs_$set_dnzp_sw (dir_name, entryname, dnzp_sw, code);

ARGUMENTS

dir_name
   is  the  pathname  of  the  directory  containing the segment.
   (Input)

entryname
   is the entryname of the segment.  (Input)

dnzp_sw
   is  the new value  of the dnzp  switch.  (Input) Its  possible
   values are:
   "0"b  - zero  pages are  nulled  and  not written  to disk  or
      charged against quota
   "1"b  - zero  pages are  written to  disk and  charged against
      quota

code
   is  a  standard  system  status  code.   (Output) Its possible
   values are:

   error_table_$bad_ring_brackets
      the  ring  brackets  of  the  segment  are  less  than  the
      validation level of the user.

________________                             ____________________

hcs_$set_dnzp_sw                             hcs_$set_dnzp_sw_seg
________________                             ____________________

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory and w effective access to the segment.

             ________________________________________

NAME: HCS_$SET_DNZP_SW_SEG

hcs_$set_dnzp_sw_seg allows  the dnzp switch associated  with the
specified  segment to  be changed.   The "don't  null zero pages"
(dnzp) switch indicates  how zero pages of a  segment are written
to disk.

USAGE

declare hcs_$set_dnzp_sw_seg entry (ptr, bit(1), fixed bin(35));

call hcs_$set_dnzp_sw_seg (seg_ptr, dnzp_sw, code);

ARGUMENTS

seg_ptr
   is  a  pointer  to  the  segment  whose  dnzp  switch is to be
   modified.  (Input)

dnzp_sw
   is  the new value  of the dnzp  switch.  (Input) Its  possible
   values are:
   "0"b  - zero  pages are  nulled  and  not written  to disk  or
      charged against quota
   "1"b  - zero  pages are  written to  disk and  charged against
      quota

code
   is  a  standard  system  status  code.   (Output) Its possible
   values are:

   error_table_$bad_ring_brackets
      the  ring  brackets  of  the  segment  are  less  than  the
      validation level of the user.

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory and w effective access to the segment.

____________________                           __________________

hcs_$set_dnzp_sw_seg                           mdc_$get_lv_access
____________________                           __________________

NAME: MDC_$CHECK_MOUNTED

mdc_$check_mounted determines whether a logical volume is mounted
and available for use.

USAGE

declare mdc_$check_mounted entry (char(*), fixed bin(35));

call mdc_$check_mounted (lv_name, code);

ARGUMENTS

lv_name
   is the name of the logical volume.  (Input)

code
   is  a  standard  system  status  code.   (Output) Its possible
   values are:

   0
      the  volume is mounted  and ready for  use.  This does  not
      mean  it is  attached to  the calling  process (see  Notes,
      below.)

   error_table_$mount_not_ready
      the volume is not mounted.

NOTES

Use  hcs_$lv_attached to  determine if  a logical  volume is both
mounted and attached to the calling process.

ACCESS REQUIRED

No special access is required.

             ________________________________________

NAME: MDC_$GET_LV_ACCESS

mdc_$get_lv_access gets the calling  process' effective access to
manipulate a logical volume.

USAGE

declare mdc_$get_lv_access entry (char(*), fixed bin(3), fixed
     bin(5), bit (1) aligned, fixed bin (35));

__________________                                           ____

mdc_$get_lv_access                                           rcp_
__________________                                           ____

call mdc_$get_lv_access (lv_name, ring, mode, public, code);

ARGUMENTS

lv_name
   is the logical volume name.  (Input)

ring
   is the validation level for  which access is to be calculated.
   (Input)

mode
   is either REW_ACCESS_BIN for a volume executive, RW_ACCESS_BIN
   for a user with access to  use the volume, or N_ACCESS_BIN for
   a user  with no access  to the volume.   (Output) These values
   are declared in access_mode_values.incl.pl1.

public
   is "1"b if the volume is public.

code
   is a standard system status code.  (Output)

ACCESS REQUIRED

No special access is required.

             ________________________________________

NAME: RCP_

The  rcp_ subroutine is  used to manage  resources in the  user's
process.  There are entrypoints to  attach, detach, list, and get
the status of resources owned by this process or by the system.

Attaching a resource is a two  step process, consisting of a call
to rcp_$attach,  and 1 or  more calls to  rcp_$check_attach.  The
example which  follows will demonstrate this process,  as well as
showing how to release the resource back to the system.

____                                                         ____

rcp_                                                         rcp_
____                                                         ____

/**** This example will show how to attach a tape drive to this process,
handling any errors that rcp_ may return.  The procedure calling rcp_ should
use the following include files: rcp_resource_types.incl.pl1,
rcp_device_info_structs.incl.pl1, event_wait_channel.incl.pl1, and
event_wait_info.incl.pl1. */

/* We are going to attach a tape drive, requesting to have a specific volume
mounted on it. */

     rcp_id = "0"b;
     event_channel = 0;
     tape_info_ptr = null ();
     on cleanup call CLEANUP_ATTACH();

     allocate tape_info set (tape_info_ptr);       /* allocate device_info */
     tape_info.version_num = tape_info_version_3;  /* fill in structure */
     tape_info.system_flag = "0"b;                 /* not a system process */
     tape_info.device_name = "";         /* not asking for specific device */
     tape_info.model = 0;                          /* same */
     tape_info.write_flag = "1"b;                  /* we are going to write */
     tape_info.speed = 125;                        /* speed of drive */
     tape_info.density = "00001"b;                 /* 6250 bpi */
     tape_info.volume_name = "tape01";             /* the tape we want */
/* Now we need an event channel for rcp_ to tell us when the attachment has
been completed. */
     call ipc_$create_ev_chn (event_channel, code);
     if code ^= 0 then goto ERROR;

/* Now that we have the structure initialized, begin the attachment. */

     call rcp_$attach (DEVICE_TYPE (TAPE_DRIVE_TYPEX), tape_info_ptr,
                       event_channel, "", rcp_id, code);
     if code ^= 0 then goto ERROR;

/* Now we have to wait for the drive to be allocated to us, and the tape to be
mounted. */

     event_wait_channel.channel_id (1) = event_channel;

ATTACH_LOOP:
     rcp_comment = "";
     call rcp_$check_attach (rcp_id, tape_info_ptr, rcp_comment, ioi_id,
                             ws_max, to_max, rcp_state, code);
     if rcp_comment ^= "" then
       {rcp_comment should be printed on the user's terminal.};
     goto ATTACH_STATE (rcp_state);

/**** The attachment has been completed. */
ATTACH_STATE (0):
     goto ATTACH_COMPLETE;

____                                                  ___________

rcp_                                                  rcp_$attach
____                                                  ___________

/**** The resource has been attached, but we cannot use it yet. This can happen
      in the case of a tape or disk volume having to be mounted, etc. In this
      case, we block on an event channel and rcp_ will tell us when the
      resource is ready for use. */
ATTACH_STATE (1):
     call ipc_$block (addr (event_wait_channel), addr (event_wait_info), code);
     if code ^= 0 then goto ERROR;
     else goto ATTACH_LOOP;

/**** There is no appropriate resource available. */
ATTACH_STATE (2):
     code = error_table_$resource_unavailable;
     goto ERROR;

/**** An error has been encountered while processing the attachment. */
ATTACH_STATE (3):
     goto ERROR;

ERROR:
     call CLEANUP_ATTACH();
     {the appropriate message should be printed based upon the value of code,
      and this procedure should return.}

ATTACH_COMPLETE:

/* At this point, we can begin using the device through ioi_. */
     ...
     ...
/* Now that we have finished using the device, we must detach it. */

     call rcp_$detach (rcp_id, "0"b, error_count, "", code);
     if code ^= 0 then goto ERROR;
     free tape_info;
     call ipc_$delete_ev_chn (event_channel, code);
     return;

CLEANUP_ATTACH: procedure;

     if rcp_id ^= ""b then call rcp_$detach (rcp_id, "0"b, (0), "", (0));
     if tape_info_ptr ^= null () then free tape_info;
     if event_channel ^= 0 then call ipc_$delete_ev_chn (event_channel, (0));

end CLEANUP_ATTACH;

___________                                           ___________

rcp_$attach                                           rcp_$attach
___________                                           ___________

             ________________________________________

NAME: RCP_$ATTACH

rcp_$attach  initiates the  attachment of  a device.   The device
that RCP  will attempt to attach  depends on the values  found in
the user  supplied device_info structure.  RCP will  first see if
an appropriate device  is assigned to this process.   If there is
an  appropriate assigned,  unattached device,  then RCP  will use
that  device for  this attachment.    If there  is not,  RCP will
attempt to assign an appropriate, available and accessible device
to  the process and  use that device  for the attachment.   If no
device  can  be  found  that  meets  the  requirements,  then the
attachment  is  aborted.   For  tape  and  disk  drives,  if  the
specified volume is not mounted, RCP will mount the volume on the
device.

The  rcp_$attach entry  point functions  in cooperation  with the
rcp_$check_attach entry  point.  A call to  rcp_$attach initiates
the attachment but does not complete it.  The caller still cannot
successfully  call  IOI  to  perform  I/O  on  the  device  being
attached.  The  attachment will not  be completed and  the caller
will not know the characteristics of the device that was attached
until  this data  is returned  from rcp_$check_attach.   For more
detailed information, see the example above.

USAGE

declare rcp_$attach entry (char(*), ptr, fixed bin(71), char(*),
     bit(36) aligned, fixed bin(35));

call rcp_$attach (device_type, device_info_ptr, event_id,
     comment, rcp_id, code);

ARGUMENTS

device_type
   is a string that identifies the  type of device to attach.  It
   must    be     one    of    the    constants     defined    in
   rcp_resource_types.incl.pl1.  (Input)

device_info_ptr
   points  to  a  structure  supplied  by  the  caller containing
   information about  the device to be attached.   (See below for
   information about the device_info structure.)  (Input)

event_id

___________                                           ___________

rcp_$attach                                           rcp_$attach
___________                                           ___________

   is an event  channel ID supplied by the  caller.  This channel
   will be used by RCP to notify  the user of the progress of the
   attachment  in  some  cases.   For  more  information, see the
   example above.  (Input)

comment
   is a message  to be displayed to the  operator upon completion
   of device assignment and prior to any volume mounting that may
   be required.  (Input)

rcp_id
   is an internally generated unique  id for this rcp attachment.
   (Output)  It   is  passed  to  other   rcp_  entrypoints  that
   manipulate the attachment.

error_code
   is  a standard  system status  code.  (Output)  Possible codes
   returned are:

   error_table_$bad_volid
      for a tape  or disk device, a volume must  be specified and
      it was not.

   error_table_$resource_attached
      the requested device is  already attached to the requesting
      process.

   error_table_$no_operation
      this  is a  T&D operation  and the  privileged attach entry
      point rcp_priv_$attach must be used instead.

   error_table_$resource_unknown
      the requested device is not known to the system.

   error_table_$resource_unavailable
      the requested device was accessible but not available.

   error_table_$resource_bad_access
      the requested device was unaccessible.

ACCESS REQUIRED

RW access to the Access Control Segment (ACS) associated with the
resource is required  in order to attach the  resource.  If RCPRM
is not enabled at your site, then the only resource controlled by
RCP is the device,and access control is not provided for tape and
disk volumes.  The ACS is located in >sc1>rcp>RESOURCE_NAME.acs.

___________                                           ___________

rcp_$attach                                           rcp_$attach
___________                                           ___________

If RCPRM is  enabled, then access to both devices  and volumes is
controlled by  ACS segments.  For  reading, the user  must have R
effective  access, and  for writing,  RW effective  access.  This
access  may be derived  from an ACS  segment associated with  the
resource, or based on the owner of the resource, as determined by
RCPRM.  Refer to the Reference Manual for further details.

NOTES

The device_info  structure is a general  purpose header structure
used for  the various of types  of resources.  It is  declared is
rcp_device_info_structs.incl.pl1,  along with the  structures for
tapes, disks,  and printers.  Each structure  uses device_info as
its header.   The include file  decribes the structures  for each
resource in more detail.

dcl    1  device_info based (device_info_ptr) aligned,
          2  version_num      fixed bin,
          2  usage_time       fixed bin,
          2  wait_time        fixed bin,
          2  system_flag      bit(1),
          2  device_name      char(8),
          2  model            fixed bin,
          2  qualifiers(4)    fixed bin(35);

STRUCTURE ELEMENTS

version_num
   is  the  version  number  of  this  structure.   This  will be
   different for each resource type.  (Input)

usage_time
   number  of minutes  device  will/may  be used.   (Reserved for
   future use.)

wait_time
   number   of  minutes   user  will/must   wait  for  assignment
   completion.  (Reserved for future use.)

system_flag
   if  this is  "1"b, the  user wants  to be  considered a system
   process for this assignment.  (Input)

device_name
   the  name of  the device.   (Input to  rcp_$attach/Output from
   rcp_$check_attach)

model
   the    model   number    of   the    device.    (Output   from
   rcp_$check_attach)

___________                                     _________________

rcp_$attach                                     rcp_$check_attach
___________                                     _________________

qualifiers
   this  element  will  contain  different  information  for each
   resource    type.    (Input    to   rcp_$attach/Output    from
   rcp_$check_attach)

             ________________________________________

NAME: RCP_$CHECK_ATTACH

rcp_$check_attach  establishes completion  of the  attach process
begun  by the  rcp_$attach entry   point, causes  IOI to  set the
workspace and timeout limits for  the device, promotes the device
to the caller's validation level,  and returns info needed by the
user to perform  I/O on this device.  It should  be noted that an
attachment is not complete until this entry point is called.

USAGE

declare rcp_$check_attach entry (bit(36) aligned, ptr, char(*),
     fixed bin, fixed bin(19), fixed bin(71), fixed bin, fixed
     bin(35));

call rcp_$check_attach (rcp_id, device_info_ptr, comment,
     ioi_index, workspace_max, timeout_max, statex, code);

ARGUMENTS

rcp_id
   is  the  unique  identified  for  this  attachment returned by
   rcp_$attach.  (Input)

device_info_ptr
   is a pointer to the device_info structure that was supplied to
   rcp_$attach  when  this  attachment  was  begun.  (Input) This
   entrypoint  will update the  information in this  structure to
   reflect  the characteristics  of  the  actual device  that was
   acquired.

comment
   the comment associated with this attachment.  This argument is
   always a null string.  (Output)

ioi_index
   is an index used for communication with IOI.  (Output)

workspace_max
   is the size of IOI workspace in words.  (Output)

_________________                                     ___________

rcp_$check_attach                                     rcp_$detach
_________________                                     ___________

timeout_max
   is the amount  of time IOI will wait for  another operation to
   begin, after an operation completes, before it unwires the IOI
   workspace.  If the next operation begins before this time out,
   then the workspace remains  wired.  Otherwise, it gets unwired
   automatically  and the  next  operation  is delayed  while IOI
   rewires the workspace pages into memory.

statex
   is the current state of the attachment.  (Output) Its possible
   values are:
      0 - the attachment is complete
      1 - the attachment is nearly complete
      2 - the resource is unavailable
      3 - an error occurred while attaching the resource
   See the example above for more information.

code
   is a standard system  status code.  (Output) Possible returned
   codes are:

   error_table_$bad_arg
      the rcp_id supplied is invalid.

   error_table_$invalid_state
      the attachment of  this device is in the wrong  state to be
      completed now.

ACCESS REQUIRED

Only the  process that began the attachment  with rcp_$attach can
complete it with rcp_$check_attach, but no access is required for
this  entrypoint,   as  all  access  checking   is  performed  by
rcp_$attach.

             ________________________________________

NAME: RCP_$DETACH

rcp_$detach detaches an IOI  device attachment.  Depending on the
disposition, the device will also be unassigned.

USAGE

declare rcp_$detach entry (bit(36) aligned, bit(*), fixed bin,
     char(*), fixed bin(35));

call rcp_$detach (rcp_id, disposition, error_count, comment,
     code);

___________                                       _______________

rcp_$detach                                       rcp_$get_status
___________                                       _______________

ARGUMENTS

rcp_id
   unique   rcp  identification    number  that   identifies  the
   attachment of the device.  (Input)

disposition
   specifies  whether the  device  should  be unassigned  or not.
   (Input)  Any  volume  associated  with  the  device  is always
   unassigned.  This argument's possible values are:
   "1"b - leave the device assigned to this process

   "0"b  - if  the device  was assigned  to this  process by  the
      rcp_$attach  call  that  initiated  this  attachment,  then
      unassign  the device; otherwise  leave it assigned  to this
      process.

error_count
   user ring error count for the attachment indicating the number
   of errors during the attachment.   This count is logged in the
   system log message for this detachment.  (Input)

comment
   a comment to  be displayed to the operator  upon detachment of
   the device.  (Input)

code
   is  a storage  system  status  code.  (Output)  Possible codes
   returned are:

   error_table_$bad_arg
      indicates a possible invalid or incorrect rcp_id.

   error_table_$bad_processid
      the device was  not attached to this process  or the rcp_id
      (which reflects  the process id which  made the attachment)
      is invalid or incorrect.

ACCESS REQUIRED

Only the  process which attached  the device can  detach it using
this entry point.

_______________                                   _______________

rcp_$get_status                                   rcp_$get_status
_______________                                   _______________

             ________________________________________

NAME: RCP_$GET_STATUS

rcp_$get_status will find  a resource given its name  or UID, and
return  all the  information about   it depending  on the  user's
access to the resource.

USAGE

declare rcp_$get_status entry (ptr, char (*), fixed bin (35));

call rcp_$get_status (resource_desc_ptr, registry_dir, code);

ARGUMENTS

resource_desc_ptr
   is a pointer to  the resource_descriptions structure.  See the
   definition under the rcp_$acquire entry point.  (Input)

registry_dir
   the  absolute pathname  of  the  directory containing  the RCP
   registries.  (Input) This is usually >system_control_1>rcp.

code
   is  a standard  system status  code.  (Output)  Possible codes
   returned are:

   error_table_$action_not_performed
      the  action was not  performed and the  user does not  have
      enough access to find out why.

   error_table_$bad_resource_spec
      there  was  erroneous  data  in  the  resource_descriptions
      structure supplied.

   error_table_$resource_awaiting_clear
      the  resource  is  awaiting  clear  and  is unavailable for
      status.

   error_table_$not_abs_path
      the registry directory pathname supplied is not an absolute
      pathname.

   error_table_$resource_locked
      the resource is locked and unavailable.

   error_table_$resource_unknown
      the requested resource is unknown to the system.

_______________                               ___________________

rcp_$get_status                               rcp_$list_resources
_______________                               ___________________

   error_table_$unimplemented_version
      the version of the resource_descriptions structure supplied
      is not supported.

   error_table_$resource_bad_access
      the  user does  not have  enough access  to get  resource's
      status.

ACCESS REQUIRED

Read  effective access is  required to get  the status of  an RCP
object.

NOTES

This entrypoint is only useful when the site has RCPRM enabled.

             ________________________________________

NAME: RCP_$LIST_RESOURCES

rcp_$list_resources  returns  a  list  of  resources  owned  by a
specific  user,  by  the   system,  or  unowned  resources.   The
selection  of information  to be  returned is  determined by  the
userid argument.

USAGE

declare rcp_$list_resources entry (char (*), char (*), char (*),
     ptr, fixed bin (35), ptr, fixed bin (35));

call rcp_$list_resources (resource_type, registry_dir, userid,
     user_area_ptr, n_resources, return_ptr, code);

ARGUMENTS

resource_type
   the resource type, i.e., "tape_vol".  (Input)

registry_dir
   the  absolute   pathname  of  the  directory   where  the  RCP
   registries   are    located.    (Input)   This    is   usually
   >system_control_1>rcp.

userid
   contains  the   selection  criteria  for  information   to  be
   returned.  (Input) Its possible values are:

___________________                           ___________________

rcp_$list_resources                           rcp_$list_resources
___________________                           ___________________

   Person.Project
      return  information  about  the   resources  owned  by  the
      specified user.

   system
      return information about the resources owned by the system.

   free
      return information about the resources in the free pool.

user_area_ptr
   pointer to  the area where the  resource_list structure should
   be  allocated.   See  "Notes"  below  for  description  of the
   resource_list structure.  (Input).

n_resources
   number of resources in the resource_list structure returned to
   the user.  (Output)

return_ptr
   is a  pointer to the allocated structure  in the user-supplied
   area.  (Output)

code
   is  a standard  system status  code.  (Output)  Possible codes
   returned are:

   error_table_$insufficient_access
      the  user  does  not  have  enough  access  to find out the
      desired information.  See "Access Required" below.

   error_table_$bad_name
      the userid supplied was Person.* and this is not allowed.

   error_table_$smallarg
      the user-supplied area is too  small for the information to
      be returned.

ACCESS REQUIRED

R  effective  access  is  required  to  list  the  existence of a
resource.  This computation takes into account ONLY the AIM range
of the  resource since R  raw mode is  not necessary to  list the
existence of a resource, but read_allowed_ is required.

NOTES

This entrypoint is only useful when the site has RCPRM enabled.

___________________                           ___________________

rcp_$list_resources                           rcp_$list_resources
___________________                           ___________________

NOTES

The resource_list structure  is defined in resource_list.incl.pl1
and is declared as follows:

dcl    1  resource_list aligned based (resource_list_ptr),
       2  forward_ptr pointer initial (null),
       2  max_entries fixed bin,
       2  n_resources fixed bin initial (0),
       2  resource_name
          (Max_entries refer (resource_list.max_entries)) char (32);

STRUCTURE ELEMENTS

forward_ptr
   points to the next block, null if there is no next block.

max_entries
   number of elements in the resource_name array.

n_resources
   number of valid resource names in this block.

resource_names
   array of resource names that meet the specified criteria.