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.