Multics

MULTICS TECHNICAL BULLETIN MTB760

To: MTB Distribution

From: Mary Crawford

Date: 08/06/87

Subject: Privileged Commands and Subroutines

-----------------------------------

This MTB describes the internal and/or privileged Commands and
Subroutines for the Multics System.

-----------------------------------

Comments on this MTB should be placed in forum on System M:

>udd>m>mtgs>Multics_Issues (Multics)

or directed by Multics mail to:

System M: GDixon.Multics

or by phone to:

Gary Dixon
HVN: 862-3593
DDD: 602-862-3593

_________________________________________________________________

Multics project internal documentation; not to be reproduced or
distributed outside the Multics project without permission of the
Director of MDC.

CONTENTS

Page

PRIVILEGED COMMANDS . . . . . . . . . 1-1
cpmc . . . . . . . . . . . . . . . 1-2
cl_intermediary . . . . . . . . 1-2
create cr . . . . . . . . . . . 1-3
destroy . . . . . . . . . . . . 1-5
enable invoke . . . . . . . . . 1-5
enabled, invoked . . . . . . . . 1-6
generate_call, gc . . . . . . . 1-6
id . . . . . . . . . . . . . . . 1-7
list, ls . . . . . . . . . . . . 1-7
pop_preferred . . . . . . . . . 1-8
preferred . . . . . . . . . . . 1-9
probe, pb . . . . . . . . . . . 1-9
program_interrupt, pi . . . . . 1-10
push_preferred . . . . . . . . . 1-10
run . . . . . . . . . . . . . . 1-11
scheduler . . . . . . . . . . . 1-13
select, sl . . . . . . . . . . . 1-13
set_cl_intermediary . . . . . . 1-14
set_preferred . . . . . . . . . 1-14
start, sr . . . . . . . . . . . 1-15
stop . . . . . . . . . . . . . . 1-15
wakeup . . . . . . . . . . . . . 1-15
PRIVILEGED SUBROUTINES . . . . . . . . 2-1
connection_list_manager_ . . . . . 2-2
add . . . . . . . . . . . . . . 2-2
priv_change_user . . . . . . . . 2-4
priv_delete_name . . . . . . . . 2-5
hpriv_delete_name . . . . . . . 2-5
priv_delete_offset . . . . . . . 2-6
hpriv_delete_offset . . . . . . 2-6
priv_delete_all_for_user . . . . 2-6
priv_get_name . . . . . . . . . 2-7
hpriv_get_name . . . . . . . . . 2-10
priv_get_next_owner . . . . . . 2-11
hpriv_get_next_owner . . . . . . 2-11
hpriv_get_next . . . . . . . . . 2-12
priv_remove_user . . . . . . . . 2-13
init . . . . . . . . . . . . . . 2-13
cpm_ . . . . . . . . . . . . . . . 2-14
block . . . . . . . . . . . . . 2-14

CONTENTS (cont)

Page

create . . . . . . . . . . . . . 2-14
destroy . . . . . . . . . . . . 2-17
generate_call . . . . . . . . . 2-18
generate_call_preferred . . . . 2-19
generate_call_when_ready . . . . 2-20
get_control_point_meters . . . . 2-20
get_preferred_control_point . . 2-22
get_scheduler_meters . . . . . . 2-23
get_user_cl_intermediary . . . . 2-24
pop_preferred_control_point . . 2-25
push_preferred_control_point . . 2-25
scheduler . . . . . . . . . . . 2-26
set_preferred_control_point . . 2-27
set_user_cl_intermediary . . . . 2-27
start . . . . . . . . . . . . . 2-28
stop . . . . . . . . . . . . . . 2-29
wakeup . . . . . . . . . . . . . 2-30
cpm_data_ . . . . . . . . . . . . . 2-31
n_control_points . . . . . . . . 2-31
dm_hcs_$allocate_journal . . . . . 2-31
dm_hcs_$free_journal . . . . . . . 2-32
dm_hcs_$get_journal_stamp . . . . . 2-33
dm_hcs_$get_max_held_per_journal . 2-33
dm_hcs_$get_n_journals . . . . . . 2-34
dm_hcs_$guaranteed_eligibility_off 2-34
dm_hcs_$guaranteed_eligibility_on . 2-35
dm_hcs_$set_force_write_limit . . . 2-35
dm_hcs_$set_journal_stamp . . . . . 2-36
dm_hcs_$validate_bj_uid . . . . . . 2-37
dsa_tty_ . . . . . . . . . . . . . 2-38
abort . . . . . . . . . . . . . 2-38
attach . . . . . . . . . . . . . 2-39
connect . . . . . . . . . . . . 2-39
detach . . . . . . . . . . . . . 2-41
event . . . . . . . . . . . . . 2-42
index . . . . . . . . . . . . . 2-42
order . . . . . . . . . . . . . 2-43
read . . . . . . . . . . . . . . 2-45
read_echoed . . . . . . . . . . 2-46
read_with_mark . . . . . . . . . 2-47
write . . . . . . . . . . . . . 2-48
write_whole_string . . . . . . . 2-48
get_control_point_id_ . . . . . . . 2-50
hcs_$acl_add1 . . . . . . . . . . . 2-50
hcs_$acl_add . . . . . . . . . . . 2-52
hcs_$acl_delete . . . . . . . . . . 2-55
hcs_$acl_list . . . . . . . . . . . 2-56
hcs_$acl_replace . . . . . . . . . 2-58

CONTENTS (cont)

Page

hcs_$assign_channel . . . . . . . . 2-61
hcs_$assign_linkage . . . . . . . . 2-61
hcs_$block . . . . . . . . . . . . 2-62
hcs_$chname . . . . . . . . . . . . 2-62
hcs_$combine_linkage . . . . . . . 2-64
hcs_$delete_channel . . . . . . . . 2-65
hcs_$dir_quota_move . . . . . . . . 2-65
hcs_$dir_quota_read . . . . . . . . 2-66
hcs_$echo_negotiate_get_chars . . . 2-68
hcs_$fblock . . . . . . . . . . . . 2-69
hcs_$flush_consecutive_pages . . . 2-70
hcs_$flush_pages . . . . . . . . . 2-71
hcs_$fs_get_brackets . . . . . . . 2-72
hcs_$fs_get_dir_name . . . . . . . 2-73
hcs_$fs_search_get_wdir . . . . . . 2-74
hcs_$fs_search_set_wdir . . . . . . 2-75
hcs_$get_alarm_timer . . . . . . . 2-76
hcs_$get_authorization . . . . . . 2-76
hcs_$get_dates . . . . . . . . . . 2-77
hcs_$get_dates_ptr . . . . . . . . 2-78
hcs_$get_defname_ . . . . . . . . . 2-78
hcs_$get_hex_exponent_control . . . 2-80
hcs_$get_ipc_operands . . . . . . . 2-81
hcs_$get_lp . . . . . . . . . . . . 2-82
hcs_$get_page_trace_signal . . . . 2-82
hcs_$get_segment_ptr_path . . . . . 2-83
hcs_$get_user_raw_mode . . . . . . 2-84
hcs_$get_volume_dump_switches . . . 2-84
hcs_$grow_lot . . . . . . . . . . . 2-85
hcs_$initiate_search_rules . . . . 2-86
hcs_$level_get . . . . . . . . . . 2-88
hcs_$level_set . . . . . . . . . . 2-88
hcs_$link_force . . . . . . . . . . 2-89
hcs_$list_acl . . . . . . . . . . . 2-90
hcs_$list_dir . . . . . . . . . . . 2-91
hcs_$set_copysw . . . . . . . . . . 2-98
hcs_$set_cpu_timer . . . . . . . . 2-99
hcs_$set_damaged_sw . . . . . . . . 2-100
hcs_$set_damaged_sw_seg . . . . . . 2-101
hcs_$set_hex_exponent_control . . . 2-102
hcs_$set_hexfp_control . . . . . . 2-103
hcs_$set_page_trace_signal . . . . 2-104
hcs_$set_pl1_machine_mode . . . . . 2-105
hcs_$set_stack_ptr . . . . . . . . 2-105
hcs_$set_synchronized_sw . . . . . 2-106
hcs_$set_timer . . . . . . . . . . 2-107
hcs_$set_volume_dump_switches . . . 2-107
hcs_$status_for_backup . . . . . . 2-108

CONTENTS (cont)

Page

hcs_$stop_process . . . . . . . . . 2-109
hcs_$trace_marker . . . . . . . . . 2-109
hcs_$try_to_unlock_lock . . . . . . 2-110
hcs_$tty_abort . . . . . . . . . . 2-111
hcs_$tty_attach . . . . . . . . . . 2-112
hcs_$tty_detach . . . . . . . . . . 2-113
hcs_$tty_detach_new_proc . . . . . 2-114
hcs_$tty_event . . . . . . . . . . 2-115
hcs_$tty_get_line . . . . . . . . . 2-116
hcs_$tty_get_name . . . . . . . . . 2-117
hcs_$tty_index . . . . . . . . . . 2-118
hcs_$tty_order . . . . . . . . . . 2-119
hcs_$tty_read . . . . . . . . . . . 2-137
hcs_$tty_read_echoed . . . . . . . 2-138
hcs_$tty_read_with_mark . . . . . . 2-139
hcs_$tty_state . . . . . . . . . . 2-141
hcs_$tty_write . . . . . . . . . . 2-141
hcs_$tty_write_set_mark . . . . . . 2-143
hcs_$tty_write_whole_string . . . . 2-144
hcs_$unmask_ips . . . . . . . . . . 2-145
hcs_$usage_values . . . . . . . . . 2-146
hpriv_connection_list_ . . . . . . 2-146
installation_gate_ . . . . . . . . 2-147
install_ttt . . . . . . . . . . 2-147
ioi_ . . . . . . . . . . . . . . . 2-148
connect . . . . . . . . . . . . 2-148
connect_pcw . . . . . . . . . . 2-149
get_detailed_status . . . . . . 2-149
get_special_status . . . . . . . 2-150
release_devices . . . . . . . . 2-151
set_channel_required . . . . . . 2-151
set_event . . . . . . . . . . . 2-152
set_status . . . . . . . . . . . 2-152
suspend_devices . . . . . . . . 2-153
timeout . . . . . . . . . . . . 2-154
workspace . . . . . . . . . . . 2-154
ipc_ . . . . . . . . . . . . . . . 2-155
reassign_call_channels . . . . . 2-155
wait_for_an_event . . . . . . . 2-156
list_init_ . . . . . . . . . . . . 2-160
variable_already_zero . . . . . 2-161
login_server_overseer_$test . . . . 2-164
mailbox_$accept_wakeups_index . . . 2-165
mailbox_$add_index . . . . . . . . 2-166
mailbox_$chname_file . . . . . . . 2-167
mailbox_$check_salv_bit_index . . . 2-168
mailbox_$close . . . . . . . . . . 2-169
mailbox_$compact_file . . . . . . . 2-170

CONTENTS (cont)

Page

mailbox_$compact_index . . . . . . 2-171
mailbox_$copy . . . . . . . . . . . 2-172
mailbox_$create . . . . . . . . . . 2-173
mailbox_$delete . . . . . . . . . . 2-174
mailbox_$delete_index . . . . . . . 2-175
mailbox_$get_mode_file . . . . . . 2-176
mailbox_$get_mode_index . . . . . . 2-177
mailbox_$get_message_count_index . 2-178
mailbox_$get_uid_file . . . . . . . 2-179
mailbox_$get_uid_index . . . . . . 2-180
mailbox_$incremental_read_index . . 2-181
mailbox_$mbx_acl_add . . . . . . . 2-183
mailbox_$mbx_acl_delete . . . . . . 2-185
mailbox_$mbx_acl_list . . . . . . . 2-186
mailbox_$mbx_acl_replace . . . . . 2-188
mailbox_$open . . . . . . . . . . . 2-189
mailbox_$open_if_full . . . . . . . 2-190
$own_incremental_read_index . . . . 2-191
mailbox_$own_read_index . . . . . . 2-193
mailbox_$read_delete_index . . . . 2-195
mailbox_$read_index . . . . . . . . 2-197
mailbox_$read_message_file . . . . 2-199
mailbox_$read_message_index . . . . 2-202
mailbox_$set_max_length_file . . . 2-206
mailbox_$set_safety_switch . . . . 2-207
mailbox_$update_message_index . . . 2-208
mailbox_$validate . . . . . . . . . 2-209
mailbox_$wakeup_add_index . . . . . 2-210
mailbox_$wakeup_aim_add_index . . . 2-212
mca_ . . . . . . . . . . . . . . . 2-214
area . . . . . . . . . . . . . . 2-214
attach_ipc . . . . . . . . . . . 2-215
attach_mca . . . . . . . . . . . 2-216
config . . . . . . . . . . . . . 2-216
config_file . . . . . . . . . . 2-217
detach_ipc . . . . . . . . . . . 2-221
detach_mca . . . . . . . . . . . 2-221
diskette . . . . . . . . . . . . 2-222
diskette_read . . . . . . . . . 2-223
display . . . . . . . . . . . . 2-225
load_ipc . . . . . . . . . . . . 2-225
process_io_event . . . . . . . . 2-226
read_data . . . . . . . . . . . 2-227
reset . . . . . . . . . . . . . 2-228
reset_ipc . . . . . . . . . . . 2-228
return_status . . . . . . . . . 2-230
tandd_read_data . . . . . . . . 2-231
tandd_write_data . . . . . . . . 2-232

CONTENTS (cont)

Page

tandd_write_text . . . . . . . . 2-233
work_space . . . . . . . . . . . 2-234
mca_priv_ . . . . . . . . . . . . . 2-239
force_reset . . . . . . . . . . 2-239
force_unlock . . . . . . . . . . 2-239
mca_priv_load_ipcs . . . . . . . 2-240
reset_ipcs . . . . . . . . . . . 2-241
trace . . . . . . . . . . . . . 2-241
mdc_ . . . . . . . . . . . . . . . 2-242
create_dir . . . . . . . . . . . 2-242
create_dirx . . . . . . . . . . 2-243
create_dirx_acct . . . . . . . . 2-244
delete_dir . . . . . . . . . . . 2-245
delete_volume_quota . . . . . . 2-246
find_lvid . . . . . . . . . . . 2-246
find_lvname . . . . . . . . . . 2-247
find_volname . . . . . . . . . . 2-247
get_lv_access . . . . . . . . . 2-248
lvname_info . . . . . . . . . . 2-249
pvname_info . . . . . . . . . . 2-250
read_disk_tabel . . . . . . . . 2-251
set_account_restrict_path . . . 2-251
set_mdir_account . . . . . . . . 2-252
set_mdir_owner . . . . . . . . . 2-253
set_mdir_quota . . . . . . . . . 2-253
set_volume_quota . . . . . . . . 2-254
status . . . . . . . . . . . . . 2-255
mhcs_ . . . . . . . . . . . . . . . 2-260
get_seg_usage . . . . . . . . . 2-260
get_seg_usage_ptr . . . . . . . 2-261
mseg_ . . . . . . . . . . . . . . . 2-262
find_hdr_msg . . . . . . . . . . 2-262
find_msg . . . . . . . . . . . . 2-263
message_segment_$add_file . . . . . 2-263
message_segment_$add_index . . . . 2-264
message_segment_$chname_file . . . 2-265
message_segment_$check_salv_bit_file 2-267
$check_salv_bit_index . . . . . . . 2-268
message_segment_$close . . . . . . 2-269
message_segment_$compact_file . . . 2-269
message_segment_$compact_index . . 2-270
message_segment_$copy . . . . . . . 2-271
message_segment_$create . . . . . . 2-272
message_segment_$delete . . . . . . 2-273
message_segment_$delete_file . . . 2-274
message_segment_$delete_index . . . 2-275
message_segment_$get_mode_file . . 2-276
message_segment_$get_mode_index . . 2-277

CONTENTS (cont)

Page

$get_message_count_file . . . . . . 2-278
$get_message_count_index . . . . . 2-279
$incremental_read_file . . . . . . 2-280
$incremental_read_index . . . . . . 2-282
message_segment_$ms_acl_add . . . . 2-284
message_segment_$ms_acl_delete . . 2-286
message_segment_$ms_acl_list . . . 2-288
message_segment_$ms_acl_replace . . 2-289
message_segment_$open . . . . . . . 2-291
$own_incremental_read_file . . . . 2-292
$own_incremental_read_index . . . . 2-294
message_segment_$own_read_file . . 2-296
message_segment_$own_read_index . . 2-298
$read_delete_file . . . . . . . . . 2-300
$read_delete_index . . . . . . . . 2-302
$read_file . . . . . . . . . . . . 2-304
message_segment_$read_index . . . . 2-306
$read_message_file . . . . . . . . 2-308
$read_message_index . . . . . . . . 2-311
message_segment_$set_max_length_file 2-314
$set_safety_switch . . . . . . . . 2-315
message_segment_$update_message_file 2-316
$update_message_index . . . . . . . 2-317
message_segment_$validate . . . . . 2-318
pnt_fs_gate_ . . . . . . . . . . . 2-319
add_acl_entries . . . . . . . . 2-319
chname_file . . . . . . . . . . 2-321
delete_acl_entries . . . . . . . 2-322
list_acl . . . . . . . . . . . . 2-324
replace_acl . . . . . . . . . . 2-325
validate . . . . . . . . . . . . 2-326
priv_connection_list_ . . . . . . . 2-327
rcp_ . . . . . . . . . . . . . . . 2-328
acquire . . . . . . . . . . . . 2-328
assign_device . . . . . . . . . 2-332
attach . . . . . . . . . . . . . 2-334
attach_lv . . . . . . . . . . . 2-337
cancel_id_string . . . . . . . . 2-338
check_assign . . . . . . . . . . 2-339
check_attach . . . . . . . . . . 2-340
check_attach_lv . . . . . . . . 2-342
copy_list . . . . . . . . . . . 2-343
detach . . . . . . . . . . . . . 2-345
detach_lv . . . . . . . . . . . 2-346
get_status . . . . . . . . . . . 2-347
list_resources . . . . . . . . . 2-348
promote . . . . . . . . . . . . 2-350
release . . . . . . . . . . . . 2-351

CONTENTS (cont)

Page

set_status . . . . . . . . . . . 2-355
unassign . . . . . . . . . . . . 2-357
unassign_device . . . . . . . . 2-358
run_test_as . . . . . . . . . . . . 2-359
restart_fault . . . . . . . . . . . 2-360
cleanup_entry . . . . . . . . . 2-360
restart_entry . . . . . . . . . 2-361
send_as_request_ . . . . . . . . . 2-362
block . . . . . . . . . . . . . 2-362
no_block . . . . . . . . . . . . 2-384
send_system_message_ . . . . . . . 2-387
send_system_message_ . . . . . . 2-387
set_ext_variable_ . . . . . . . . . 2-389
for_linker . . . . . . . . . . . 2-389
sys_log_ . . . . . . . . . . . . . 2-393
system_message_handler_ . . . . . . 2-404
test_system_control . . . . . . . . 2-405
user_message_ . . . . . . . . . . . 2-408
user_message_admin_ . . . . . . . . 2-411
read_message . . . . . . . . . . 2-412
user_message_priv_ . . . . . . . . 2-414
add_message . . . . . . . . . . 2-414
delete_message_id . . . . . . . 2-416
delete_process_messages . . . . 2-417
system_init . . . . . . . . . . 2-417
ws_tty_ . . . . . . . . . . . . . . 2-418
abort . . . . . . . . . . . . . 2-418
attach . . . . . . . . . . . . . 2-418
detach . . . . . . . . . . . . . 2-419
event . . . . . . . . . . . . . 2-420
order . . . . . . . . . . . . . 2-421
read . . . . . . . . . . . . . . 2-422
read_echoed . . . . . . . . . . 2-423
read_with_mark . . . . . . . . . 2-424
write . . . . . . . . . . . . . 2-425
write_whole_string . . . . . . . 2-426

SECTION 1

Privileged Commands

This section provides documentation for Multics Privileged and
Internal Commands.

Name: cpmc

This command is the command level interface to the control point
management facility.

SYNTAX AS A COMMAND

cpmc operation {arguments} {-control_args}

SYNTAX AS AN ACTIVE FUNCTION

[cpmc operation {arguments}]

ARGUMENTS

operation
identifies the operation to be performed by this invocation of
control_point_manager_call. Detailed descriptions of the
supported operations follow.

CONTROL ARGUMENTS

-control_args
are specific to the requested operation and are described
below.

NOTES

Many of the operations described below act on an arbitrary
control point as opposed to the current control point. The
desired control point is selected by supplying the operation with
the control point's unique ID. A control point's unique ID is a
12 digit octal value which is displayed by this command's list
operation. In addition, the list operation also displays a 6
digit short form of the ID which may also be used to select the
control point. When using either form of the control point's
unique ID, leading zeroes may be omitted

Operation: cl_intermediary

This operation returns or displays the identity of the user
supplied command level intermediary for the specified control
point.

SYNTAX AS AN ACTIVE FUNCTION

[cpmc cl_intermediary ID]

____ ____

cpmc cpmc
____ ____

SYNTAX AS A COMMAND

cpmc cl_intermediary ID

ARGUMENTS

ID
is the unique ID of the desired control point.

NOTES

When used as an active function, this operation returns the
identity of the command level intermediary in a form suitable for
use with the set_cl_intermediary operation described below.

Operation: create cr

This operation creates a new control point.

SYNTAX

cpmc cr ENTRY {INFO_PTR} {-control_args}"

ARGUMENTS

entry
is the initial procedure to be run in the new control point.
ENTRY is a virtual entrypoint as accepted by the cv_entry_
subroutine.

info_ptr
is a pointer which is passed as the single argument to the new
control point's initial procedure. INFO_PTR is a virtual
pointer as accepted by the cv_ptr_ subroutine. If no INFO_PTR
is specified, a null pointer is passed to the initial
procedure.

CONTROL ARGUMENTS

-brief, -bf
does not display the message described above.

-cl_intermediary ENTRY
specifies the entrypoint to be used as the command level
intermediary for the new control point. ENTRY is a virtual
entrypoint as accepted by the cv_entry_ subroutine.

____ ____

cpmc cpmc
____ ____

-comment STR, -com STR
specifies a description of the new control point which will be
displayed by the list operation The default description is the
name of the control point's initial procedure.

-default_cl_intermediary
specifies that the new control point is to used the standard
command level intermediary provided by the control point
manager. (Default)

-dependent
specifies that the new control point will be a child of the
current control point.

-independent
specifies that the new control point will be independent of
all other control points in the process. At present, the
independence of a control point only affects when the storage
it has used will be released after it is destroyed. (Default)

-long, -lg
displays a message giving the ID of the newly created control
point. (Default)

-no_start, -nsr
does not mark the new control point as ready for execution.
(Default)

-not_preferred
does not make the new control point the preferred control
point. (Default)

-preferred
makes the new control point the preferred control point. This
control argument may not be specified unless "-start" is also
specified.

-priority N
sets the scheduling priority of the new control point to N
which must be an integer. A ready control point whose
priority is 1 is always scheduled before any ready control
point whose priority is 2, etc. The default priority is 1.

-separate_io_switches {STR}, -sepios {STR}
specifies that the new control point is to have its own set of
standard I/O switches (i.e., user_i/o, user_input,
user_output, and error_output). If STR is supplied, it is the
attach description for the new control point's user_i/o
switch. If STR is not supplied, its user_i/o will be attached

____ ____

cpmc cpmc
____ ____

via the syn_ I/O module to the current control point's
user_i/o. In either case, the actual attachment of the I/O
switches will be performed in the new control point before its
initial procedure is invoked.

-shared_io_switches, -shios
specifies that the new control point is to use the same set of
standard I/O switches as the current control point (Default)

-start, -sr
marks the new control point as ready for execution. Actual
execution of the control point will begin when all higher
priority control points in the process are blocked waiting for
an IPC wakeup.

NOTES

The run operation, described below, is the preferred method to
execute a command line in a control point.

Operation: destroy

This operation destroys the specified control point.

SYNTAX

cpmc destroy ID

ARGUMENTS

ID
is the unique ID of the control point to be destroyed.

NOTES

When a control point is destroyed, the cleanup handlers of all
entrypoints still active in the control point are run, the
control point's standard I/O switches are detached, and the
storage used by its stack is released.

Operation: enable invoke

This operation enables control point management.

SYNTAX

cpmc enabled

____ ____

cpmc cpmc
____ ____

NOTES

Control point management is enabled automatically by the first
use of this command's create or run operations or by the first
call to the cpm_$create entrypoint.

Operation enabled, invoked

This operation returns "true" if control point management is
already enabled in the process and "false" otherwise.

SYNTAX AS AN ACTIVE FUNCTION

[cpmc enabled]

SYNTAX AS A COMMAND

cpmc enabled

Operation: generate_call, gc

This operation queues a call to an arbitrary entrypoint in a
specific control point and, optionally, forces the immediate
execution of said call.

SYNTAX

cpmc gc ID ENTRY {INFO_PTR} {-control_args}

ARGUMENTS

ENTRY
identifies the entrypoint to be run. ENTRY is a virtual
entrypoint as accepted by the cv_entry_ subroutine.

ID
is the unique ID of the control point in which the entrypoint
is to be run.

INFO_PTR
is a pointer which is passed as the single argument to the
above entrypoint. INFO_PTR is a virtual pointer as accepted
by the cv_ptr_ subroutine. If no INFO_PTR is specified, a
null pointer is passed to the entrypoint.

____ ____

cpmc cpmc
____ ____

CONTROL ARGUMENTS

-defer_until_ready, -dur
specifies that execution of the entrypoint is not to occur
until the control point is next ready for execution and is
subsequently selected for execution by the control point
scheduler. If the control point is already ready for
execution, execution of the entrypoint will still be delayed
until said control is next scheduled.

-immediate, -im
specifies that execution of the entrypoint is to take place
immediately. (Default)

-not_preferred
specifies that the target control point will not be made the
preferred control point during the entrypoint's execution.
(Default)

-preferred
specifies that the target control point is to be temporarily
made the preferred control point while execution of the
entrypoint takes place. This control argument is incompatible
with the "-defer_until_ready" control argument.

NOTES

This operation enables an entry point to be executed as if it
were executed by the control point itself.

Operation: id

This operation returns the unique ID of the current control
point.

SYNTAX AS AN ACTIVE FUNCTION

[cpmc id]

SYNTAX AS A COMMAND

cpmc id

Operation: list ls

This operation lists the status of some or all control points
active in the process.

____ ____

cpmc cpmc
____ ____

SYNTAX

cpmc ls {IDs} {-control_args}

ARGUMENTS

IDs
are the unique IDs of individual control points whose status
is to be displayed.

CONTROL ARGUMENTS

-all, -a
specifies that the status of all active control points is to
be displayed.

-meters
specifies that the usage meters of the control points listed
are also to be displayed. A control point's usage meters
includes its CPU usage, segment and page faults counts, and
VTOC I/O counts.

-no_meters
specifies that no usage meters are to be displayed. (Default)

NOTES

At least one control point ID or the "-all" control argument must
be specified for this operation. Use of both control point IDs
and the "-all" control argument is not permitted.

The information always displayed for a control point is its
unique ID in both long and short forms, its state (e.g., ready,
blocked), and its description as supplied in the call to
cpm_$create or the use of this command's create or run
operations.

If the status of more than one control point is requested and
usage meters are also requested via the "-meters" control
argument, this operation will also display the usage meters of
the control point scheduler.

Operation: pop_preferred

This operation resets the preferred control point to the one in
force before the last use of the push_preferred operation. See
the push_preferred operation below for more information.

____ ____

cpmc cpmc
____ ____

SYNTAX

cpmc pop_preferred FLAG

ARGUMENTS

FLAG
is either "true" or "false" and should be the value returned
by the last use of the push_preferred operation.

Operation: preferred

This entrypoint returns the ID of the preferred control point, if
any.

SYNTAX AS AN ACTIVE FUNCTION

[cpmc preferred]

SYNTAX AS A COMMAND

cpmc preferred

NOTES

The preferred control point is always given priority for
execution over all other control points whenever it is ready.
The effect of this treatment is to cause the preferred control
point to have control over the user's terminal, if it uses the
terminal, as it will receive all IPC wakeups generated by the
terminal. When control point management is first enabled, the
root control point is made the preferred control point.

Operation: probe, pb

This operation invokes the probe debugger in the specified
control point.

SYNTAX

cpmc pb ID

ARGUMENTS

ID
is the unique ID of the control point in which probe is to be
run.

____ ____

cpmc cpmc
____ ____

NOTES

This operation will make the specified control point the
preferred control point while probe is executing in order to
insure that probe can communicate with the user's terminal.

Operation: program_interrupt, pi

This operation signals the program_interrupt condition on the
stack of the specified control point.

SYNTAX

cpmc pi ID {-control_args}

ARGUMENTS

ID
is the unique ID of the control point in which
program_interrupt is to be signalled.

CONTROL ARGUMENTS

-not_preferred
specifies that the control point will not be made the
preferred control point.

-preferred
specifies that the control point will be made the preferred
control point before program_interrupt is signalled.
(Default)

Operation: push_preferred

This operation makes the specified control point the preferred
control point on a temporary basis.

SYNTAX AS AN ACTIVE FUNCTION

[cpmc push_preferred ID]

SYNTAX AS A COMMAND

cpmc push_preferred ID

____ ____

cpmc cpmc
____ ____

ARGUMENTS

ID
is the unique ID of the control point which is to be made the
preferred control point.

NOTES

This operation returns "true" if it was able to make the
specified control point the preferred control point. The result
of this operation should be used as input to the pop_preferred
operation described above to restore the previous preferred
control point when the actions requiring the new control point to
be preferred are completed.

The following version 2 exec_com fragment demonstrates the proper
use of the push_preferred and pop_preferred operations.

&set pushed false
&on cleanup &begin
cpmc pop_preferred &(pushed)
&end
&set pushed [cpmc push_preferred &1]
...
cpmc pop_preferred &(pushed)

Operation: run

This operation creates a new control point to execute the
supplied command line. The control point is destroyed when the
command line completes.

SYNTAX

cpmc run {-control_args} COMMAND_LINE

ARGUMENTS

COMMAND_LINE
is the command line to be executed. The command line starts
with the first non-control argument supplied to the run
operation. If the command line is to start with a hyphen (-),
the "-string" control argument should be used to signify the
start of the command line.

CONTROL ARGUMENTS

-brief, -bf
does not display the message described above.

____ ____

cpmc cpmc
____ ____

-cl_intermediary ENTRY
specifies the entrypoint to be used as the command level
intermediary for the new control point. ENTRY is a virtual
entrypoint as accepted by the cv_entry_ subroutine.

-comment STR, -com STR
specifies a description of the new control point which will be
displayed by the list operation The default description is the
command line which it will execute.

-default_cl_intermediary
specifies that the new control point is to used the standard
command level intermediary provided by the control point
manager. (Default)

-dependent
specifies that the new control point will be a child of the
current control point.

-long, -lg
displays a message giving the ID of the newly created control
point. (Default)

-no_start, -nsr
does not make the new control point as ready for execution.

-not_preferred
does not make the new control point the preferred control
point.

-preferred
makes the new control point the preferred control point. This
control argument is incompatible with the "-no_start" control
argument. (Default)

-separate_io_switches {STR}, -sepios {STR}
specifies that the new control point is to have its own set of
standard I/O switches (i.e., user_i/o, user_input,

____ ____

cpmc cpmc
____ ____

user_output, and error_output). If STR is supplied, it is the
attach description for the new control point's user_i/o
switch. If STR is not supplied, its user_i/o will be attached
via the syn_ I/O module to the current control point's
user_i/o. In either case, the actual attachment of the I/O
switches will be performed in the new control point before its
initial procedure is invoked.

-shared_io_switches, -shios
specifies that the new control point is to use the same set of
standard I/O switches as the current control point (Default)

-string COMMAND_LINE, -str COMMAND_LINE
specifies that the command line to be executed starts with the
next argument to the run operation.

Operation: scheduler

This operation blocks the current control point and invokes the
scheduler to run the appropriate ready control point.

SYNTAX

cpmc scheduler

NOTES

It is not usually necessary to use this operation to schedule
control points, because ipc_ calls the control point scheduler
when a wakeup is sent to a control point.

Operation: select, sl

This operation marks the specified control point as ready for
execution and makes it the preferred control point.

SYNTAX

cpmc sl ID

____ ____

cpmc cpmc
____ ____

ARGUMENTS

ID
is the unique ID of the control point to be selected.

Operation: set_cl_intermediary

This operation sets the command level intermediary for the
specified control point.

SYNTAX

cpmc set_cl_intermediary ID {ENTRY} {-control_args}

ARGUMENTS

ENTRY
is the new command level intermediary for the entrypoint.
ENTRY is a virtual entrypoint as accepted by the cv_entry_
subroutine.

ID
is the unique ID of the control point whose command level
intermediary is to be set.

ARGUMENTS

-default, -dft
specifies that the command level intermediary for the control
point is to be restored to the default supplied by the control
point manager.

NOTES

Either an entrypoint must be supplied or the "-default" control
argument must be used. Both an entrypoint and "-default" may not
be used in a single invocation of this command.

Operation: set_preferred

This entrypoint makes the specified control point the preferred
control.

SYNTAX

cpmc set_preferred ID

____ ____

cpmc cpmc
____ ____

ARGUMENTS

control_point_id (Input)
is the unique ID of the control point which will become the
preferred control point.

Operation: start, sr

This entrypoint marks the specified control point as ready for
execution.

SYNTAX

cpmc sr ID

ARGUMENTS

ID
is the unique ID of the control point which is to be marked
ready.

Operation: stop

This entrypoint marks the specified control point as not ready
for execution. The control point will not run until it is again
made ready by this command's select or start operations or by a
call to the cpm_$start entrypoint.

SYNTAX

cpmc stop ID

ARGUMENTS

ID
is the unique ID of the control point which is to be stopped.

Operation: wakeup

This operation sends a generic wakeup to the specified control
point.

SYNTAX

cpmc wakeup ID

____ ____

cpmc cpmc
____ ____

ID
is the unique ID of the control point which is to be awakened.

NOTES

It is not usually necessary to use this operation to wakeup
blocked control points, because ipc_ calls the control point
scheduler when a wakeup is sent to a control point.

SECTION 2

Privileged Subroutines

This section provides documentation for Multics Privileged and
Internal Subroutines.

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

Name: connection_list_manager_

The connection_list_manager_ module maintains the inner-ring list
of active connections. The entries in this module are used to
add, delete, update, and obtain information about entries in the
active connection list. Most of these entries (apart from the
"get_*" entries) are usually called in the inner ring by
network-specific modules, but all are available through one of
the gates priv_connection_list_ or hpriv_connection_list_. The
gate entries and their associated target entries are listed at
the end of this module description.

These entries may be viewed as being divided into two classes:
privileged and highly privileged. Privileged entries are
available through priv_connection_list_, and can be used on
connections of which the calling process is the owner. Highly
privileged entries are available through hpriv_connection_list_,
and allow the caller to operate on any connection entry. In
general, the presence of the string "hpriv_", or "priv_" at the
beginning of the name of an entry indicates the level of
privilege associated with it.

Entry: connection_list_manager_$add

This entry adds a connection to the list. The connection will be
assigned to the calling process as the "owner", and to the
specified user process as the "user". This entry is privileged.

USAGE

dcl connection_list_manager_$add entry (char (*), fixed bin (35),
char (*), char (*), char (*), fixed bin, bit (18), fixed bin
(35))

call connection_list_manager_$add (connection_name,
connection_handle, network_service_type,
force_disconnect_entry, force_accounting_flush_entry,
usage_type, connection_offset, code)

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

ARGUMENTS

connection_name
is the name of the connection, as returned by
login_service_entries.listen. (Input)

connection_handle
is the unique identifier of the connection, as returned by
login_service_entries.listen. (Input)

network_service_type
is the name of the service provided by the top-level
networking entity for the connection. (Input)

force_disconnect_entry
is the name of the force_disconnect entrypoint returned by
net_info_$get_service_entries. Note that this must be a name
and not an entry variable because it may have to be used by a
process other than the caller. (Input)
force_accounting_flush_entry is the name of the entrypoint
which can be used to force accounting for the particular
process to be made. Note that this must be a name and not an
entry variable because it may have to be used by a process
other than the caller. (Input)

usage_type
is an indicator of the way in which the connection is going to
be used, as described for
login_service_entries.assign_connection (above). (Input)

connection_offset
is the offset in the connection list at which the specified
connection has been added. This can be used by other entries
to find and/or delete the specific connection with comparative
efficiency. (Output)

code
is a standard system status code. (Output)

NOTES

The force_disconnect_entry and force_accounting_flush_entry
fields are character strings defining an entrypoint to do the
assigned task. The target entrypoint is expected to be declared
as

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

USAGE

dcl module$entrypoint entry (char (*), fixed bin (35))

call module$entrypoint (connection_name, code)

ARGUMENTS

connection_name
is the name of the connection to pass to the entry. (Input)

code
is a standard system status code. (Output)

Entry: connection_list_manager_$priv_change_user

This entry is used to change the user process in the table entry.
The calling process must be the owner.

USAGE

dcl connection_list_manager_$priv_change_user entry (bit (18),
bit (36) aligned, char (*), fixed bin, fixed bin (71), bit
(72) aligned, fixed bin (35)))

call connection_list_manager_$priv_change_user
(connection_offset, user_process_id, user_group_id,
usage_type, terminate_event_channel, initializer_handle,
code)

ARGUMENTS

connection_offset
is the offset of the connection in the list, as returned by
the add entry, above. (Input)

user_process_id
is the process ID of the user process to which the connection
is assigned. (Input)

user_group_id
is the process group ID (person.project.tag) of the user
process to which the connection is assigned. (Input)

terminate_event_channel
is the name of an event channel over which a wakeup can be
sent to the owner process if the user process terminates.
(Input)

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

initializer_handle
is the handle used in requests from the login server to the
Initializer concerning this connection. (Input)

usage_type
indicates the way the connection is to be used by the process,
i.e., login, dial, etc. Its possible values are declared in
ls_usage_types.incl.pl1; see the description of
login_service_entries.assign_connection for the possible
values. (Input)

code
is a standard system status code. (Output)

Entry: connection_list_manager_$priv_delete_name

This entry deletes the connection with the specified name from
the active connection list. The calling process must be the
owner of the connection.

USAGE

dcl connection_list_manager_$priv_delete_name entry (char (*),
fixed bin (35))

call connection_list_manager_$priv_delete_name (connection_name,
code)

ARGUMENTS

connection_name
is the name of the connection, as above. (Input)

code
is a standard system status code. (Output)

This entry deletes the connection with the specified name from
the active connection list, no matter what process is the owner.
The calling sequence is the same as for the priv_delete_name
entry, above.

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

Entry: connection_list_manager_$priv_delete_offset

This entry deletes the connection with the specified offset from
the active connection list. The calling process must be the
owner of the connection.

USAGE

dcl connection_list_manager_$priv_delete_offset entry (bit (18),
fixed bin (35))

call connection_list_manager_$priv_delete_offset
(connection_offset, code)

ARGUMENTS

connection_offset
is the connection offset as returned by the add entry, above.
(Input)

code
is a standard system status code. (Output)

Entry: connection_list_manager_$priv_delete_all_for_user

This entry deletes the connection with the specified offset from
the active connection list, no matter what process is the owner.
The calling sequence is the same as for the priv_delete_offset
entry, above.

Entry: connection_list_manager_$priv_delete_offset

This entry deletes all the connections for a specified user
process for which the calling process is the owner.

USAGE

dcl connection_list_manager_$priv_delete_all_for_user entry (bit
(36) aligned, fixed bin (35))

call connection_list_manager_$priv_delete_all_for_user
(user_process_id, code)

ARGUMENTS

user_process_id
is the process ID of the user process whose connections are to
be deleted. (Input)

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

code
is a standard system status code. (Output)

This entry deletes all the connections for a specified user
process, no matter what process is the owner. It has the same
calling sequence as priv_delete_all_for_user (above).

Entry: connection_list_manager_$priv_get_name

This entry returns information about the connection with the
specified name; the calling process must be the owner of the
connection.

USAGE

dcl connection_list_manager_$priv_get_name entry (char (*), ptr,
fixed bin (35))

call connection_list_manager_$priv_get_name (connection_name,
connection_info_ptr, code)

ARGUMENTS

connection_name
is the name of the connection about which information is to be
returned. (Input)

connection_info_ptr
is a pointer to the active_connection_info structure described
in "Notes", below. (Input)

code
is a standard system status code. (Output)

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

NOTES

The connection_info_ptr points to the following structure
(declared in active_connection_info.incl.pl1):
dcl 1 active_connection_info aligned based,
2 version char (8),
2 connection_name char (32),
2 network_service_type char (32),
2 user_process_id bit (36),
2 user_group_id char (32),
2 owner_process_id bit (36),
2 owners_group_id char (32),
2 terminate_event_channel fixed bin (71),
2 owner_initializer_handle bit (72),
2 force_disconnect_entry char (64),
2 force_accounting_flush_entry char (64),
2 connection_handle fixed bin (35),
2 usage_type fixed bin,
2 flags,
3 delegated bit (1) unaligned,
3 mbz_bits bit (35) unaligned,
2 offset bit (18);

STRUCTURE ELEMENTS

ARGUMENTS

version
is the version of the structure. It must be filled in by the
caller with the value ACT_INFO_VERSION_1.

connection_name
is the name of the connection.

network_service_type
is the name of the service provided by the top-level
networking entity for the connection.

user_process_id
is the process ID of the user process to which the connection
is assigned.

user_group_id
is the process group ID (person.project.tag) of the user
process.

owner_process_id
is the process ID of the owning process.

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

owner_group_id
is the process group ID (person.project.tag) of the "owning"
process.

terminate_event_channel
is the event channel over which the owner may be sent a wakeup
if the user process is terminated.

owner_initializer_handle
is the handle used by the owner to communicate with the
Initializer about the connection. It is used to notify the
Initializer if the connection is terminated and the owner
process no longer exists.

force_disconnect_entry
is the name of the entrypoint to be called to force
termination of the connection. It is used during login server
initialization if neither the user process nor the owner
process exists.

force_accounting_flush_entry
is the name of the entrypoint to be called to force all
current accounting data for the connection to be added to the
network accounting table. It is used during during process
termination to make sure the latest accounting data is
available for the connection.

connection_handle
is the unique identifier of the connection, as described under
connection_list_manager_$add, above.

usage_type
specifies way in which the connection is used by the process,
as described under connection_list_manager_$add, above.

delegated
indicates that the connection has been assigned to a user
other than the owner.

offset
is the offset of the connection in the list.

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

connection_list_manager_$hpriv_get_name

This entry returns information about the connection with the
specified name, no matter what process is the owner. The calling
sequence is the same as for the priv_get_name entry, above.

Entry: connection_list_manager_$priv_get_next_user entry

This entry returns information about the next connection after
the one at a specified offset assigned to the specified user
process, for which the calling process is the owner.

USAGE

dcl connection_list_manager_$priv_get_next_user entry (bit (36)
aligned, bit (18), ptr, fixed bin (35))

call connection_list_manager_$priv_get_next_user
(user_process_id, connection_offset, connection_info_ptr,
code)

ARGUMENTS

user_process_id
is the process ID of the user process. (Input)

connection_offset
is the offset in the list of the connection relative to which
the next connection is to be found. If it is "0"b,
information about the first connection for the specified user
is returned. (Input)

connection_info_ptr
is a pointer to the active_connection_info structure, as
above. (Input)

code
is a standard system status code. (Output)

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

Entry: connection_list_manager_$priv_get_next_user

This entry returns information about the next connection after
the one at a specified offset assigned to the specified user
process, no matter what process is the owner. The calling
sequence is the same as for the priv_get_next_user entry, above.

Entry: connection_list_manager_$priv_get_next_owner entry

This entry returns information about the next connection after
the one at a specified offset for which the calling process is
the owner.

USAGE

dcl connection_list_manager_$priv_get_next_owner entry (bit (18),
ptr, fixed bin (35))

call connection_list_manager_$priv_get_next_owner
(connection_offset, connection_info_ptr, code)

ARGUMENTS

connection_offset
is the offset in the list of the connection relative to which
the next connection is to be found. If it is "0"b,
information about the first connection for which the calling
process is the owner is returned. (Input)

connection_info_ptr
is a pointer to the active_connection_info structure, as
above. (Input)

code
is a standard system status code. (Output)

Entry: connection_list_manager_$hpriv_get_next_owner entry

This entry returns information about the next connection after
the one at a specified offset for which a specified process is
the owner.

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

USAGE

dcl connection_list_manager_$hpriv_get_next_owner entry (bit
(18), bit (36), ptr, fixed bin (35))

call connection_list_manager_$hpriv_get_next_owner
(connection_offset, owner_process_id, connection_info_ptr,
code)

ARGUMENTS

owner_process_id
is the process ID of the process for which connections are to
be found. (Input)

connection_info_ptr
is a pointer to the active_connection_info structure, as
above. (Input)

code
is a standard system status code. (Output)

Entry: connection_list_manager_$hpriv_get_next entry

This entry returns information about the next connection after
the one at a specified offset.

USAGE

dcl connection_list_manager_$hpriv_get_next entry (bit (18), ptr,
fixed bin (35))

call connection_list_manager_$hpriv_get_next (connection_offset,
connection_info_ptr, code)

ARGUMENTS

connection_offset
is the offset in the list of the connection relative to which
the next connection is to be found. If it is "0"b,
information about the first connection in the list is
returned. (Input)

________________________ ________________________

connection_list_manager_ connection_list_manager_
________________________ ________________________

connection_info_ptr
is a pointer to the active_connection_info structure, as
above. (Input)

code
is a standard system status code. (Output)

Entry: connection_list_manager_$priv_remove_user

This entry is called to make the specified process cease to be
the user of the specified connection. No new user process is
assigned by this entry. The calling process must be the owner of
the connection.

USAGE

dcl connection_list_manager_$priv_remove_user entry (bit (18),
bit (36), fixed bin (35))

call connection_list_manager_$priv_remove_user
(connection_offset, user_process_id, code)

ARGUMENTS

connection_offset
is the offset of the connection in the list. (Input)

user_process_id
is the process ID of the expected current user of the
connection. If the user process ID in the connection entry
does not match this argument, no action is taken, and a
nonzero status code is returned. (Input)

code
is a standard system status code. (Output)

Entry: connection_list_manager_$init

This entry initializes the active connection list segment. It is
called once per bootload. It will create the segment if it does
not already exist.

USAGE

dcl connection_list_manager_$init entry (fixed bin (35))

call connection_list_manager_$init (code)

________________________ ____

connection_list_manager_ cpm_
________________________ ____

code
is a standard system status code. (Output)

________________________________________

Name: cpm_

Entry: cpm_$block

This entrypoint places the current control point in the blocked
state.

USAGE

dcl cpm_$block entry ();

call cpm_$block ();

NOTES

Once a control point is in the blocked state, it will not become
eligible for execution until a subsequent call to cpm_$wakeup or
cpm_$generate_call. Therefore, this entrypoint should be used
with caution. The primary caller of this entrypoint is intended
to be ipc_.

Entry: cpm_$create

This entrypoint creates a new control point.

USAGE

dcl cpm_$create entry (pointer, bit (36) aligned, fixed binary
(35));

call cpm_$create (ccpi_ptr, control_point_id, code);

____ ____

cpm_ cpm_
____ ____

ARGUMENTS

ccpi_ptr
is a pointer to the create_control_point_info structure which
describes the control point to be created (see "Entry
Information" below). (Input)

control_point_id
is set to the unique ID of the newly created control point.
(Output)

code
is a standard system status code. (Output) Amongst the
possible returned codes, the following codes have special
significance to this entry:
error_table_$unimplemented_version
The version of the create_control_point_info structure
supplied by the caller is not supported by this
entrypoint.

ENTRY INFORMATION

This structure is declared in the cpm_create_ctrl_pt_info include
file as follows:

dcl 1 create_control_point_info
aligned based (ccpi_ptr),
2 header,
3 version character (8) unaligned,
3 comment character (64) unaligned,
3 initproc,
4 entry entry (pointer) variable,
4 info_ptr
pointer,
3 user_cl_intermediary
entry (bit (1) aligned)
variable,
3 priority fixed binary,
3 flags,
4 independent
bit (1) unaligned,
4 separate_standard_iocbs
bit (1) unaligned,
4 user_io_attach_desc_given
bit (1) unaligned,
4 user_cl_intermediary_given
bit (1) unaligned,
4 pad bit (32) unaligned,
3 pad bit (36) aligned,
3 user_io_attach_desc_length

____ ____

cpm_ cpm_
____ ____

fixed binary (21),
2 user_io_attach_desc
character
(ccpi_user_io_attach_desc_length
refer (create_control_point_info .
user_io_attach_desc_length)) unaligned;

STRUCTURE ELEMENTS

version
is the current version of this structure. The version of this
structure described here is given by the value of the named
constant CREATE_CONTROL_POINT_INFO_VERSION_1 which is defined
in the cpm_create_ctrl_pt_info include file.

comment
is the description of the new control point which will be
displayed by the list operation of the
control_point_manager_call command.

initproc.entry
is the initial procedure of the new control point.

initproc.info_ptr
is the pointer which will be passed as the argument to the
above initial procedure.

user_cl_intermediary
is the command level intermediary for the new control point if
flags.user_cl_intermediary_given is "1"b; otherwise, this
element of the structure is ignored.

priority
is the scheduling priority for the new control. A ready
control point whose priority is 1 is always scheduled before
any ready control point whose priority is 2, etc.

flags.independent
if "1"b, the new control point will be independent of all
other control points in the process; if "0"b, the new control
point will be a child of the current control point. At
present, the independence of a control point only controls
when its storage will be released after it is destroyed.

flags.separate_standard_iocbs
if "1"b, the new control point will be given its own set of
standard I/O switches (i.e., user_i/o, user_input,

____ ____

cpm_ cpm_
____ ____

user_output, and error_output); if "0"b, the new control point
will share the standard switches of the root control point if
it is independent or the current control point if it is
dependent.

flags.user_io_attach_desc_given
is only valid when flags.separate_standard_iocbs is to "1"b.
If "1"b, an attach description for the new control point's
user_i/o switch is supplied in the user_io_attach_desc element
of this structure; if "0"b, the new control point's user_i/o
switch will be attached via the syn_ I/O module to its
parent's user_i/o switch.

flags.user_cl_intermediary_given
if "1"b, the user_cl_intermediary element above contains the
command level intermediary for the new control point; if "0"b,
the new control point will use the standard command level
intermediary supplied by the control point manager.

user_io_attach_desc_length
is the length of the user_io_attach_desc element of this
structure.

user_io_attach_desc
is the attach description for the new control point's user_i/o
switch if flags.user_io_attach_desc_given is "1"b; otherwise,
this element of the structure is ignored.

NOTES

The control is created in the stopped state. It will not be
scheduled for execution until after a call to cpm_$start.

If the new control point is to have separate standard I/O
switches, they are created and attached in the new control point
before the initial procedure is invoked.

Entry: cpm_$destroy

This entrypoint destroys the specified control point.

USAGE

dcl cpm_$destroy entry (bit (36) aligned, fixed binary (35));

call cpm_$destroy (control_point_id, code);

____ ____

cpm_ cpm_
____ ____

control_point_id
is the unique ID of the control point to be destroyed.
(Input)

code
is a standard system status code. (Output) Amongst the
possible returned codes, the following codes have special
significance to this entry:
cpm_et_$cant_destroy_root
The ID supplied above is that of the root control point
which can never be destroyed.
cpm_et_$control_point_not_found
The ID supplied above does not identify an active
control point.

NOTES

Entry: cpm_$generate_call

This entrypoint runs the specified entrypoint immediately in the
requested control point.

USAGE

dcl cpm_$generate_call entry (bit (36) aligned, entry pointer,
fixed binary (35));

call cpm_$generate_call (control_point_id, userproc,
userproc_info_ptr, code);

ARGUMENTS

control_point_id
is the unique ID of the control point in which the entrypoint
is to be run. (Input)

userproc
is the entrypoint to be run. (Input)

userproc_info_ptr
is a pointer which is supplied as the argument to the above
entrypoint. (Input)

____ ____

cpm_ cpm_
____ ____

Entry: cpm_$generate_call_preferred

This entrypoint runs the specified entrypoint immediately in the
requested control point. In addition, this entrypoint makes the
specified control point the preferred control point while the
requested entrypoint is being executed.

USAGE

dcl cpm_$generate_call_preferred entry (bit (36) aligned,
entry (pointer), pointer, fixed binary (35));

call cpm_$generate_call_preferred (control_point_id, userproc,
userproc_info_ptr, code);

ARGUMENTS

control_point_id
is the unique ID of the control point in which the entrypoint
is to be run. (Input)

userproc
is the entrypoint to be run. (Input)

userproc_info_ptr
is a pointer which is passed as the argument to the above
entrypoint. (Input)

____ ____

cpm_ cpm_
____ ____

Entry: cpm_$generate_call_when_ready

This entrypoint queues a call to the specified entrypoint in the
requested control point which will be executed when the scheduler
next runs said control point.

USAGE

dcl cpm_$generate_call_when_ready entry (bit (36) aligned,
entry (pointer), pointer, fixed binary (35)

call cpm_$generate_call_when_ready (control_point_id, userproc,
userproc_info_ptr, code)

ARGUMENTS

control_point_id
is the unique ID of the control point in which the entrypoint
is to be run. (Input)

userproc
is the entrypoint to be run. (Input)

userproc_info_ptr
is a pointer which is passed as the argument to the above
entrypoint. (Input)

Entry: cpm_$get_control_point_meters

This entrypoint returns the usage meters for the specified
entrypoint.

USAGE

dcl cpm_$get_control_point_meters entry (bit (36) aligned,
pointer, fixed binary (35);

call cpm_$get_control_point_meters (control_point_id, cpma_ptr,
code);

____ ____

cpm_ cpm_
____ ____

control_point_id
is the unique ID of the control point whose meters are to be
returned. (Input)

cpma_ptr
is a pointer to the control_point_meters_argument structure
into which this entrypoint will place the usage meters (see
"Entry Information" below). (Input)

code
is a standard system status code. Amongst the possible
returned codes, the following codes have special significance
to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an active
control point.
error_table_$unimplemented_version
The version of the control_point_meters_argument
requested by the caller is not supported by this
entrypoint.

ENTRY INFORMATION

The control_point_meters_argument structure is declared in the
cpm_ctrl_pt_meters include file as follows.

dcl 1 control_point_meters_argument
aligned based (cpma_ptr),
2 version character (8) unaligned,
2 meters,
3 n_schedules
fixed binary,
3 pad fixed binary,
3 real_time fixed binary (71),
3 usage like process_usage;
STRUCTURE ELEMENTS

version
is the current version of this structure. (Input) The version
of this structure described here is given by the value of the
named constant CONTROL_POINT_METERS_ARGUMENT_VERSION_1 which
is declared in the cpm_ctrl_pt_meters include file.

meters.n_schedules
is set to the number of times that the requested control point
has actually been run by the control point scheduler.
(Output)

____ ____

cpm_ cpm_
____ ____

meters.real_time
is set to the number of microseconds of wall clock time that
this control point has been running. (Output)

meters.usage
is set to the actual usage meters for this control point.
(Output) See the writeup of the hcs_$get_process_usage
entrypoint for a detailed explanation of the elements of this
structure.

Entry: cpm_$get_preferred_control_point

This entrypoint returns the unique ID of the preferred control
point.

USAGE

dcl cpm_$get_preferred_control_point entry (bit (36) aligned;

call cpm_$get_preferred_control_point (control_point_id);

ARGUMENTS

control_point_id
is set to the unique ID of the preferred control point or to
"0"b if there is presently no preferred control point in the
process. (Output)

NOTES

____ ____

cpm_ cpm_
____ ____

Entry: cpm_$get_scheduler_meters

This entrypoint returns the usage meters of the control point
scheduler.

USAGE

dcl cpm_$get_scheduler_meters entry (pointer,
fixed binary (35));

call cpm_$get_scheduler_meters (cpma_ptr, code);

ARGUMENTS

cpma_ptr
is a pointer to the control_point_meters_argument structure
into which this entrypoint will place the usage meters (see
"Entry Information" below). (Input)

code
is a standard system status code. Amongst the possible
returned codes, the following codes have special significance
to this entry:

error_table_$unimplemented_version
The version of the control_point_meters_argument
requested by the caller is not supported by this
entrypoint.

ENTRY INFORMATION

The control_point_meters_argument structure is declared in the
cpm_ctrl_pt_meters include file as follows.

dcl 1 control_point_meters_argument
aligned based (cpma_ptr),
2 version character (8) unaligned,
2 meters,
3 n_schedules fixed binary,
3 pad fixed binary,
3 real_time fixed binary (71),
3 usage like process_usage;

STRUCTURE ELEMENTS

____ ____

cpm_ cpm_
____ ____

meters.n_schedules
is set to the number of times that the scheduler has been
invoked. (Output)

meters.real_time
is set to the number of microseconds of wall clock time that
the scheduler has been in control of the process. (Output)
This time includes the time spent blocked waiting for IPC
wakeups from devices or other processes.

meters.usage
is set to the actual usage meters for the scheduler. (Output)
See the writeup of the hcs_$get_process_usage entrypoint for a
detailed explanation of the elements of this structure.

Entry: cpm_$get_user_cl_intermediary

This entrypoint returns the command level intermediary in use by
the specified control point.

USAGE

dcl cpm_$get_user_cl_intermediary entry bit (36) aligned,
entry (bit (1) aligned), (fixed binary (35));

call cpm_$get_user_cl_intermediary (control_point_id,
user_cl_intermediary, code);

ARGUMENTS

control_point_id
is the unique ID of the control point whose intermediary is
desired. (Input)

user_cl_intermediary
is set to the entrypoint which is the command level
intermediary for the specified control point. (Output)

____ ____

cpm_ cpm_
____ ____

Entry: cpm_$pop_preferred_control_point

This entrypoint restores the preferred control point to the one
in force before the last call to
cpm_$push_preferred_control_point.

USAGE

dcl cpm_$pop_preferred_control_point entry (bit (1) aligned);

call cpm_$pop_preferred_control_point
(pushed_preferred_control_point);

ARGUMENTS

pushed_preferred_control_point
is the value returned by the last call to
cpm_$push_preferred_control_point. (Input/Output) This
entrypoint will always set this argument to "0"b before
returning to its caller.

EEEnnntttrrryyy::: cccpppmmm_$$$pppuuussshhh_ppprrreeefffeeerrrrrreeeddd_cccooonnntttrrrooolll_pppoooiiinnnttt

This entrypoint makes the specified control point the preferred
control point if possible while saving the identity of the prior
preferred control point in a stack for later restoration by the
cpm_$pop_preferred_control_point entrypoint.

USAGE

dcl cpm_$push_preferred_control_point entry (bit (36) aligned,
bit (1) aligned, fixed binary (35));

call cpm_$push_preferred_control_point (control_point_id,
pushed_preferred_control_point, code);

ARGUMENTS

control_point_id
is the unique ID of the control point which is to be made the
preferred control point. (Input)

pushed_preferred_control_point
is set to "1"b if the requested control point is successfully
made the preferred control point; otherwise, this argument is
set to "0"b. (Output)

____ ____

cpm_ cpm_
____ ____

code
is a standard system status code. (Output) Amongst the
possible returned codes, the following codes have special
significance to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an active
control point.
cpm_et_$preferred_cant_be_stopped
The ID supplied above identifies a control point in the
stopped state. A control point in the stopped state may
not be made the preferred control point.
cpm_et_$preferred_stack_overflow
The stack of preferred control points if full.

NOTES

The setting of pushed_preferred_control_point is made indivisibly
with making the specified control point the preferred control
point.

EEEnnntttrrryyy::: cccpppmmm_$$$sssccchhheeeddduuullleeerrr

This entrypoint invokes the control point scheduler to run an
appropriate ready control point.

USAGE

dcl cpm_$scheduler entry ();

call cpm_$scheduler ();

NOTES

The primary caller of this entrypoint is intended to be ipc_ when
another control point is to be scheduled to run.

____ ____

cpm_ cpm_
____ ____

EEEnnntttrrryyy::: cccpppmmm_$$$ssseeettt_ppprrreeefffeeerrrrrreeeddd_cccooonnntttrrrooolll_pppoooiiinnnttt

This entrypoint makes the specified control point the preferred
control point.

USAGE

dcl cpm_$set_preferred_control_point entry (bit (36) aligned,
fixed binary (35));

call cpm_$set_preferred_control_point (control_point_id, code);

ARGUMENTS

control_point_id
is the unique ID of the control point which is to be made the
preferred control point. (Input)

EEEnnntttrrryyy::: cccpppmmm_$$$ssseeettt_uuussseeerrr_ccclll_iiinnnttteeerrrmmmeeedddiiiaaarrryyy

This entrypoint sets the command level intermediary for the
specified control point.

USAGE

dcl cpm_$set_user_cl_intermediary entry (bit (36) aligned,
entry (bit (1) aligned), fixed binary (35));

call cpm_$set_user_cl_intermediary (control_point_id,
user_cl_intermediary, code);

ARGUMENTS

control_point_id
is the unique ID of the control point whose command level
intermediary is to be set. (Input)

____ ____

cpm_ cpm_
____ ____

user_cl_intermediary
is the entrypoint which is to be the new intermediary for the
above control point. (Input) This entry is declared as
dcl user_cl_intermediary entry (bit (1) aligned);
call user_cl_intermediary (return_from_intermediary);

Arguments

return_from_intermediary
is "1"b if cpm_overseer_$cl_intermediary is to
return as if "start" had been typed, without getting
a new command level or stopping the current control
point. (Input)

code
is a standard system status code. (Output) Amongst the
possible returned codes, the following codes have special
significance to this entry:

cpm_et_$control_point_not_found
The ID supplied above does not identify an active
control point.

NOTES

The cl_intermediary is always set to be
cpm_overseer_$cl_intermediary, which creates a new listener level
if the root control point is running, and otherwise stops the
current control point and calls the cpm_$scheduler. The
user_cl_intermediary, if given, is called by
cpm_overseer_$cl_intermediary.

EEEnnntttrrryyy::: cccpppmmm_$$$ssstttaaarrrttt

This entrypoint marks a control point as ready for execution.

USAGE

dcl cpm_$start entry (bit (36) aligned, fixed binary (35));

call cpm_$start (control_point_id, code);

ARGUMENTS

control_point_id
is the unique ID of the control point to be started. (Input)

____ ____

cpm_ cpm_
____ ____

code
is a standard system status code. (Output) Amongst the
possible returned codes, the following codes have special
significance to this entry:
cpm_et_$already_started
The ID supplied above identifies a control point which
is already started. Such a control point is in either
the ready or blocked state.
cpm_et_$control_point_not_found
The ID supplied above does not identify an active
control point.

EEEnnntttrrryyy::: cccpppmmm_$$$ssstttoooppp

This entrypoint places a control point in the stopped state.
Once in the stopped state, the scheduler will not run the control
point until after a subsequent call to cpm_$start.

USAGE

dcl cpm_$stop entry (bit (36) aligned, fixed binary (35));

call cpm_$stop (control_point_id, code);

ARGUMENTS

control_point_id
is the unique ID of the control point to be stopped. (Input)

code
is a standard system status code. (Output) Amongst the
possible returned codes, the following codes have special
significance to this entry:
cpm_et_$already_stopped
The ID supplied above identifies a control point which
is already in the stopped state.
cpm_et_$cant_stop_root
The ID supplied above is that of the root control point
which can never be stopped.
cpm_et_$control_point_not_found
The ID supplied above does not identify an active
control point.

____ ____

cpm_ cpm_
____ ____

EEEnnntttrrryyy::: cccpppmmm_$$$wwwaaakkkeeeuuuppp

This entrypoint sends a generic wakeup to the specified control
point. The wakeup changes the control point's state from blocked
to ready and informs the scheduler that it is again eligible for
execution.

USAGE

dcl cpm_$wakeup entry (bit (36) aligned, fixed binary (35));

call cpm_$wakeup (control_point_id, code);

ARGUMENTS

control_point_id
is the unique ID of the control point to be awakened. (Input)

code
is a standard system status code. (Output) Amongst the
possible returned codes, the following codes have special
significance to this entry:
cpm_et_$cant_wakeup_when_stopped
The ID supplied above identifies a control point in the
stopped state. Wakeups can only be sent to control
points which are in the blocked state.
cpm_et_$control_point_not_found
The ID supplied above does not identify an active
control point.
cpm_et_$wakeup_ignored
The ID supplied above identifies a control point which
is already in the ready state.

NOTES

The primary caller of cpm_$wakeup is intended to be ipc_. This
entry sets the state of the control point to ready and puts the
control point into the control point ready queue.

____ ________________________

cpm_ dm_hcs_$allocate_journal
____ ________________________

NNNaaammmeee::: cccpppmmm_dddaaatttaaa_

EEEnnntttrrryyy::: cccpppmmm_dddaaatttaaa_$$$nnn_cccooonnntttrrrooolll_pppoooiiinnntttsss

This datum is the number of active control points in the process.

USAGE

dcl cpm_data_$n_control_points fixed binary external;

________________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$aaallllllooocccaaattteee_jjjooouuurrrnnnaaalll

This entry point gets ring-2 Data Management (DM) an unused
journal index into the ring-0 dm_journal_seg_ for a new before
journal. The dm_journal_seg_ is a segment that keeps track of up
to 64 before journals.

USAGE

declare dm_hcs_$allocate_journal entry (bit(36) aligned, fixed
bin, fixed bin(35));

call dm_hcs_$allocate_journal (uid, journal_idx, code);

ARGUMENTS

uid
is the ring-2 unique ID for the new before journal. (Input)

journal_idx
is the index into the ring-0 dm_journal_seg_ for the new
before journal. (Output)

code
is a storage system status code. (Output) It can have the
values:

error_table_$dm_not_enabled
the Data Management system has not been brought up.
error_table_$bad_arg
the uid argument is null. The unique ID cannot be null.
error_table_$no_journals_free
there is no unused index available in the dm_journal_seg_.

________________________ ____________________

dm_hcs_$allocate_journal dm_hcs_$free_journal
________________________ ____________________

ACCESS REQUIRED

This gate can only be called from ring-2. The access
authorization of the owner is recorded in the dm_per_journal
structure so that the index cannot be freed unless the requester
is at the same authorization as the original owner.

________________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$fffrrreeeeee_jjjooouuurrrnnnaaalll

This entry point allows ring-2 Data Management (DM) to free a
previously allocated journal index in the ring-0 dm_journal_seg_.

USAGE

declare dm_hcs_$free_journal entry (fixed bin, fixed bin(35));

call dm_hcs_$free_journal (journal_idx, code);

ARGUMENTS

journal_idx
is the journal index that was previously allocated. (Input)

code
is a storage system status code. (Output) It can have the
possible value:

error_table_$invalid_dm_journal_index
the index is not a valid index or the user is attempting to
free a journal index when the authorization is not the same
as the authorization of the original owner.
error_table_$dm_not_enabled
the Data Management system has not been brought up.
error_table_$dm_journal_pages_held a journal index cannot
be freed when pages are held in memory.

ACCESS REQUIRED

This gate can only be called from ring-2. The user must be at
the same access authorization as the owner who originally
allocated the journal index.

____________________ ________________________________

dm_hcs_$free_journal dm_hcs_$get_max_held_per_journal
____________________ ________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$gggeeettt_jjjooouuurrrnnnaaalll_ssstttaaammmppp

This function returns to ring-2 Data Management (DM) the value of
the journal time stamp for a given ring-0 dm_journal_seg_ index.
The time stamp tells Page Control when the before journal was
last written to disk so all pages dependent on that before
journal, modified before this time, can be written to disk.

USAGE

declare dm_hcs_$get_journal_stamp entry (fixed bin) returns(fixed
bin(71));

call dm_hcs_$get_journal_stamp (journal_idx, time_stamp);

ARGUMENTS

journal_idx
is the index into the dm_journal_seg_ for the before journal.
(Input)

time_stamp
is the date and time the before journal was last written to
disk. (Output) This value will be zero if the Data Management
system has not been brought up, the given index is not valid,
or the user does not have the correct access.

ACCESS REQUIRED

This gate can only be called from ring-2. The user must have
read access to objects created at the authorization of the
creator.

________________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$gggeeettt_mmmaaaxxx_hhheeelllddd_pppeeerrr_jjjooouuurrrnnnaaalll

This function returns to ring-2 Data Management (DM) the value of
the maximum number of pages per journal that will be held in
memory until a before journal is written out. This value is from
the ring-0 dm_journal_seg_.

USAGE

declare dm_hcs_$get_max_held_per_journal entry () returns (fixed
bin);

max_pages = dm_hcs_$get_max_held_per_journal ();

_________________________________________________________________

dm_hcs_$get_max_held_per_journaldm_hcs_$guaranteed_eligibility_off
_________________________________________________________________

max_pages
contains the maximum number of pages held in memory per
journal. (Output) This value will be zero if the Data
Management system has not been brought up.

ACCESS REQUIRED

This gate can only be called from ring-2.

________________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$gggeeettt_nnn_jjjooouuurrrnnnaaalllsss

This function returns to ring-2 Data Management (DM) the value of
the number of before journal entries allocated in the ring-0
dm_journal_seg_.

USAGE

declare dm_hcs_$get_n_journals entry () returns (fixed bin);

n_journals = dm_hcs_$get_n_journals ();

ARGUMENTS

n_journals
contains the number of before journal entries that have been
allocated. (Output) This value will be zero if the Data
Management system has not been brought up.

ACCESS REQUIRED

This gate can only be called from ring-2.

________________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$ggguuuaaarrraaannnttteeeeeeddd_eeellliiigggiiibbbiiillliiitttyyy_oooffffff

This entry point allows Data Management (DM) to turn off the
guaranteed eligible state within process scheduling granted by
guaranteed_eligibility_on.

USAGE

declare dm_hcs_$guaranteed_eligibility_off ();

call dm_hcs_$guaranteed_eligibility_off ();

__________________________________ _____________________________

dm_hcs_$guaranteed_eligibility_off dm_hcs_$set_force_write_limit
__________________________________ _____________________________

ACCESS REQUIRED

This gate can only be called from ring-2.

________________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$ggguuuaaarrraaannnttteeeeeeddd_eeellliiigggiiibbbiiillliiitttyyy_ooonnn

This entry point allows Data Management (DM) to guarantee that a
process will remain in the eligible state within process
scheduling and be able to run. This guaranteed eligible state is
in effect until turned off.

USAGE

declare dm_hcs_$guaranteed_eligibility_on ();

call dm_hcs_$guaranteed_eligibility_on ();

ACCESS REQUIRED

This gate can only be called from ring-2.

________________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$ssseeettt_fffooorrrccceee_wwwrrriiittteee_llliiimmmiiittt

This entry point allows ring-2 Data Management (DM) to set the
write limit of the user's validation level. The write limit is
the maximum number of pages that can be written to disk during a
force write.

USAGE

declare dm_hcs_$set_force_write_limit entry (fixed bin, fixed
bin(35));

call dm_hcs_$set_force_write_limit (write_limit, code);

ARGUMENTS

write_limit
is the new maximum number of pages, between 1 and 256, that
can be written to disk during a force write. (Input)

code
is a storage system status code. (Output) It can have the
value:

_____________________________ _________________________

dm_hcs_$set_force_write_limit dm_hcs_$set_journal_stamp
_____________________________ _________________________

error_table_$argerr
the limit is less than 1 or greater than 256.

ACCESS REQUIRED

This gate can only be called from ring-2.

________________________________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$ssseeettt_jjjooouuurrrnnnaaalll_ssstttaaammmppp

This entry point allows ring-2 Data Management (DM) to set the
time stamp for a specified journal in the ring-0 dm_journal_seg_.
The time stamp tells Page Control when the before journal was
last written to disk so all pages dependent on that before
journal, modified before this time, can be written to disk.

USAGE

declare dm_hcs_$set_journal_stamp entry (fixed bin, fixed
bin(71), fixed bin(35));

call dm_hcs_$set_journal_stamp (journal_idx, time_stamp, code);

ARGUMENTS

journal_idx
is the index into the dm_journal_seg_ of the before journal to
be changed. (Input)

time_stamp
is the new date and time the before journal was written to
disk. (Input)

code
is a storage system status code. (Output) It can have values
of:

error_table_$invalid_dm_journal_index
the index is not a valid index or the user does not have
the correct access.
error_table_$dm_not_enabled
the Data Management system has not been brought up.

ACCESS REQUIRED

This gate can only be called from ring-2. The user must have
write access to objects created at the authorization of the
creator.

_________________________ _______________________

dm_hcs_$set_journal_stamp dm_hcs_$validate_bj_uid
_________________________ _______________________

NNNaaammmeee::: dddmmm_hhhcccsss_$$$vvvaaallliiidddaaattteee_bbbjjj_uuuiiiddd

This function, given a valid ring-0 dm_journal_seg_ index and
before journal unique ID, returns true if the supplied uid
matches the uid indexed in the dm_journal_seg_ and the caller has
authorization to read the information.

USAGE

declare dm_hcs_$validate_bj_uid entry (bit(36) aligned, fixed
bin) returns(bit(1) aligned);

call dm_hcs_$validate_bj_uid (uid, journal_idx, validated);

ARGUMENTS

uid
is the unique ID for the before journal. (Input)

journal_idx
is the index into the dm_journal_seg_ for the before journal.
(Input)

validated
is a bit (1) return value. (Output)

1 the specified uid is a valid unique ID for the indexed
before journal.
0 the specified uid is not valid, the specified index is not
valid, the Data Management system has not been brought up,
or the user does not have the correct access.

ACCESS REQUIRED

This gate can only be called from ring-2. The user must have
read access to objects created at the authorization of the
creator.

_______________________ ________

dm_hcs_$validate_bj_uid dsa_tty_
_______________________ ________

NNNaaammmeee::: dddsssaaa_ttttttyyy_

This subroutine provides the interface between the video system
and the DSA session control and terminal manager programs.

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$aaabbbooorrrttt

This entry resets the read and/or write buffers for a given
channel.

USAGE

dcl dsa_tty_$abort entry (fixed bin(35), fixed bin, fixed bin,
fixed bin(35));

call dsa_tty_$abort (tty_dsa_id, reset_switch, state, code);

ARGUMENTS

tty_dsa_id
is tty_'s DSA session identifier for the channel, returned by
dsa_tty_$attach. (Input)

reset_switch
indicates whether read or write are to be reset. (Input)
1 reset read
2 reset write
3 reset both

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

________ ________

dsa_tty_ dsa_tty_
________ ________

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$aaattttttaaaccchhh

This entry attaches an existing DSA session to the process, given
its channel name. It returns tty_'s DSA session identifier
associated with the channel. This session ID is used in future
dsa_tty_ calls to identify the channel.

USAGE

dcl dsa_tty_$attach entry (char(*), fixed bin(71), fixed bin(35),
fixed bin, fixed bin(35));

call dsa_tty_$attach (channel_name, event, tty_dsa_id, state,
code);

ARGUMENTS

channel_name
is the channel name of the DSA channel to be attached.
(Input)

event
is the event channel over which the caller of dsa_tty_ events
are to be reported to the caller. (Input)

tty_dsa_id
is tty_'s DSA session identifier which dsa_tty_$attach assigns
to the channel. (Output)

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$cccooonnnnnneeecccttt

This entrypoint creates a new DSA session. It is used by tc_io_
to create an outbound, dial-out connection through DSA.

USAGE

dcl dsa_tty_$connect entry (char(*), ptr, fixed bin(71), char(*)
var, ptr, char(*), fixed bin(35), ptr, fixed bin(21),
char(*) var, (2) bit(72), fixed bin(35));

________ ________

dsa_tty_ dsa_tty_
________ ________

call dsa_tty_$connect (correspondent, area_ptr, event_channel,
network_address, user_id_ptr, channel_name, session_handle,
dsa_connection_info_ptr, dsa_connection_info_len,
attach_description, access_class_range, code);

ARGUMENTS

correspondent
is the name of an application which must be defined in a
correspondent entry in the Network Information Table (NIT).
This NIT entry describes how to access the application (eg,
name of the network used to access the application, system on
which the application exists, name of the endpoint which
handles requests to use the application, etc). (Input)

area_ptr
is a pointer to an area in which dsa_connection_info can be
allocated. (Input)

event_channel
is an event channel dsa_tty_ uses to signal events associated
with this channel. If 0, then events are not signalled.
(Input)

network_address
is the network address to use when making the dial-out
connection. (Input)

user_id_ptr
is a pointer to a user identification structure. Currently,
this is used only to dial_out from Multics to an application
running on the DN8 (eg, edit or debug). Thus, information in
the structure defines person_id, project_id, billing_id and
password of a user application on the DN8. The submitter_id
structure is declared in dsa_scu_sec_info.incl.pl1. For
caller not connecting to a DN8 application, this can be a null
pointer. (Input)

channel_name
is the name of the actual DSA channel to be used for the
dial-out connection. (Output)

session_handle
is a handle used for communications between session control
and the Login_Server. (Output)

dsa_connection_info_ptr
is a pointer to information about the DSA connection. This
information is allocated in the area pointed to by area_ptr.
This information currently isn't used. (Output)

________ ________

dsa_tty_ dsa_tty_
________ ________

dsa_connection_info_len
is the length in words of the DSA connection information.
(Output)

attach_description
is an attach description that can be used to attach the tty_
I/O module to the dial-out channel. (Output)

access_class_range
is the access class of the dial-out channel. (Output)

code
is a standard status code. (Output)

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$dddeeetttaaaccchhh

This entry detaches a DSA session from the process. The session
may optionally be disconnected at the same time.

USAGE

dcl dsa_tty_$detach entry (fixed bin(35), fixed bin, fixed bin,
fixed bin(35));

call dsa_tty_$detach (tty_dsa_id, dflag, state, code);

ARGUMENTS

tty_dsa_id
is tty's DSA session identifier for the channel. (Input)

dflag
is the disconnection flag. (Input)
1 disconnect (destroy) the session.
0 just detach the session from the process.

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

________ ________

dsa_tty_ dsa_tty_
________ ________

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$eeevvveeennnttt

This entry sets the event channel associated with the connection.

USAGE

dcl dsa_tty_$event entry (fixed bin(35), fixed bin(71), fixed
bin, fixed bin(35));

call dsa_tty_$event (tty_dsa_id, event_channel, state, code);

ARGUMENTS

tty_dsa_id
is tty_'s DSA session identifier for the channel. (Input)

event_channel
identifies the event channel to be used. (Input)

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$iiinnndddeeexxx

This entry returns tty_'s DSA session identifier for a channel,
given its channel name.

USAGE

dcl dsa_tty_$index entry (char(*), fixed bin(35), fixed bin,
fixed bin(35));

call dsa_tty_$index (channel_name, tty_dsa_id, state, code);

ARGUMENTS

channel_name
is the channel name. (Input)

tty_dsa_id
is tty's DSA session identifier for the channel. (Output)

________ ________

dsa_tty_ dsa_tty_
________ ________

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$ooorrrdddeeerrr

This entry performs the specified control order on the i/o
switch.

USAGE

dcl dsa_tty_$order entry (fixed bin(35), char(*), ptr, fixed bin,
fixed bin(35));

call dsa_tty_$order (tty_dsa_id, order, info_ptr, state, code);

ARGUMENTS

tty_dsa_id
is tty's DSA session identifier for the channel. (Input)

order
is the name of the control order. (Input)

info_ptr
is null or points to the data whose form depends on the
control order. (Input)

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

NOTES

The following list of tty_ control requests are also supported by
dsa_tty_. Requests followed by an asterisk (*) are used
explicitly by tc_io_ in managing the screen. Others are
available to the user from command level and from applications.
get_echo_break_table quit_enable
get_editing_chars read_status

________ ________

dsa_tty_ dsa_tty_
________ ________

get_event_channel resetread
get_input_conversion resetwrite
get_input_translation set_echo_break_table *
get_line_status_enabled set_editing_chars
get_meters set_input_conversion
get_output_conversion set_input_translation
get_output_translation set_line_status_enabled
get_special set_output_conversion
hangup set_output_translation
interrupt set_prompt
line_length set_special
line_status set_terminal_data *
modes * start *
printer_off * store_id
printer_on terminal_info *
quit_disable write_status

The following tty_ control requests are supported in dsa_tty_ by
ignoring the request and returning a code of 0. None are used by
the video system.

accept_printer_off reset_more
input_flow_control_chars set_delay
output_flow_control_chars set_framing_chars
refuse_printer_off

The following control requests are implemented especially for DSA
connections. None are used by the video system, therefore they
are not documented in this MTB.

attention1 get_line_indicator
attention2 get_modes
attention3 get_network_type
attention4 get_page_indicator
attention5 get_switch_logical_device
attention6 get_tabulation
attention7 get_terminal_characteristics
attention8 request_device_status
attention9 select_output_device
begin_ack_unit set_attention_fcn
conceal_input set_delimiter_fcn
conceal_next_line set_editing_fcn
demand_turn set_event_info
disable_input_device set_line_indicator
enable_input_device set_modes
end_ack_unit set_page_indicator
get_attention_fcn set_switch_logical_device
get_delimiter_fcn set_tabulation
get_editing_fcn set_terminal_characteristics
get_event_info

________ ________

dsa_tty_ dsa_tty_
________ ________

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$rrreeeaaaddd

This entry reads unechoed characters from the terminal.

USAGE

dcl dsa_tty_$read entry (fixed bin(35), ptr, fixed bin(21), fixed
bin(21), fixed bin(21), fixed bin, fixed bin(35));

call dsa_tty_$read (tty_dsa_id, buffer_ptr, offset,
n_chars_to_read, n_chars_read, state, code);

ARGUMENTS

tty_dsa_id
is tty's DSA session identifier for the channel. (Input)

buffer_ptr
pointer to buffer in which characters read from terminal are
placed. (Input)

offset
is the offset in buffer at which first input character is
placed. (Input)

n_chars_to_read
is the maximum number of characters to return. (Input)

n_chars_read
is the actual number of characters returned. (Output)

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

________ ________

dsa_tty_ dsa_tty_
________ ________

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$rrreeeaaaddd_eeeccchhhoooeeeddd

This entry reads echoed characters from the terminal.
Echo-negotiated input starts when this entrypoint is called and
no unechoed characters exist in the input already read.
Negotiated echoing continues until a break character is reached,
or the remaining space in the current window line is filled with
echoed characters. Type ahead entered before echo negotiation
begins or after it stops is not echoed by the terminal.

USAGE

dcl dsa_tty_$read_echoed entry (fixed bin(35), ptr, fixed
bin(21), fixed bin(21), fixed bin(21), fixed bin(21), fixed
bin, fixed bin, fixed bin(35));

call dsa_tty_$read_echoed (tty_dsa_id, buffer_ptr, offset,
n_chars_to_read, n_chars_read, echoed, screen_left, state,
code);

ARGUMENTS

tty_dsa_id
is tty's DSA session identifier for the channel. (Input)

buffer_ptr
pointer to buffer in which characters read from terminal are
placed. (Input)

offset
offset in buffer at which first character is to be placed.
(Input)

n_chars_to_read
is the maximum number of characters to return. (Input)

n_chars_read
is the actual number of characters returned. (Output)

echoed
is the number of characters echoed during echo negotiated
input. (Output)

screen_left
is the space left on current line of current window. (Input)

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

________ ________

dsa_tty_ dsa_tty_
________ ________

code
is a standard status code. (Output)

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$rrreeeaaaddd_wwwiiittthhh_mmmaaarrrkkk

This entry is like read, but an additional argument indicates the
number of input characters read prior to the mark set in the
input by dsa_tty_$write_whole_string.

USAGE

dcl dsa_tty_$read_with_mark entry (fixed bin(35), char(*), fixed
bin(21), fixed bin(21), fixed bin, fixed bin(35));

call dsa_tty_$read_with_mark (tty_dsa_id, buffer, n_chars_read,
mark_index, state, code);

ARGUMENTS

tty_dsa_id
is tty's DSA session identifier for the channel. (Input)

buffer
buffer in which characters read from terminal are placed.
(Input)

n_chars_read
is the actual number of characters returned. (Output)

mark_index
is the number of input characters read prior to setting of the
mark (by dsa_tty_$write_whole_string) in the input. (Output)

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

________ ________

dsa_tty_ dsa_tty_
________ ________

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$wwwrrriiittteee

This entry writes text to the terminal screen.

USAGE

dcl dsa_tty_$write entry (fixed bin(35), ptr, fixed bin(21),
fixed bin(21), fixed bin(21), fixed bin, fixed bin(35));

call dsa_tty_$write (tty_dsa_id, buffer_ptr, offset,
n_chars_to_write, n_chars_written, state, code);

ARGUMENTS

tty_dsa_id
is tty's DSA session identifier for the channel. (Input)

buffer_ptr
pointer to buffer holding data to be written. (Input)

offset
offset in buffer of first character to be written. (Input)

n_chars_to_write
is the number of characters supplied. (Input)

n_chars_written
is the actual number of characters written. (Output)

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$wwwrrriiittteee_wwwhhhooollleee_ssstttrrriiinnnggg

This entry is the same as $write, except that it guarantees to
send the entire buffer to the terminal as a single unit, rather
than sending a partial buffer. This ensures that terminal escape
sequences get sent to the terminal as a single unit, rather than
possibly being split across several transmissions to the
terminal.

________ ________

dsa_tty_ dsa_tty_
________ ________

USAGE

dcl dsa_tty_$write_whole_string entry (fixed bin(35), char(*),
bit(1), fixed bin(21), fixed bin, fixed bin(35));

call dsa_tty_$write_whole_string (tty_dsa_id, string, mark_flag,
n_chars_written, state, code);

ARGUMENTS

tty_dsa_id
is tty's DSA session identifier for the channel. (Input)

string
is the character string to write. The buffer can be at most
512 characters long. This is the size of the video system
output holding buffer. (Input)

mark_flag
indicates whether to set a mark in the input stream to
separate input typed prior to printing string on the terminal
from characters typed after string is printed. This mark
allows type-ahead input to be separated from MORE responses.
(Input)
"0"b do not set mark
"1"b set mark

n_chars_written
is the actual number of characters written. This should equal
the length of string, if writing was successful, or 0 if the
string could not be written as a single unit. It may also be
some intermediate value if an unexpected error occurs.
(Output)

state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)

code
is a standard status code. (Output)

_____________________ _____________

get_control_point_id_ hcs_$acl_add1
_____________________ _____________

NNNaaammmeee::: gggeeettt_cccooonnntttrrrooolll_pppoooiiinnnttt_iiiddd_

This subroutine returns the unique ID of the current control
point.

USAGE

dcl get_control_point_id_ entry ()
returns (bit (36) aligned);

control_point_id = get_control_point_id_ ();

ARGUMENTS

control_point_id (Output)
is set to the unique ID of the current control point.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$aaaccclll_aaadddddd111

This entry point adds one name to the access control list (ACL)
of the specified entry (segment or directory). If the name
already appears on the ACL of the entry, its mode is changed to
the one specified by the call. This entry also sets the ring
brackets for segments.

USAGE

declare hcs_$acl_add1 entry (char(*), char(*), char(*),
fixed bin(5), (3) fixed bin(6), fixed bin(35));

call hcs_$acl_add1 (dir_name, entryname, userid, mode, rb, code);

ARGUMENTS

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

entryname
is the entryname of the segment or directory. (Input)

_____________ _____________

hcs_$acl_add1 hcs_$acl_add1
_____________ _____________

userid
is the userid (in the form Person_id.Project_id.tag) that
identifies the processes to which this ACL name applies.
(Input)

mode
contains the modes for this userid. (Input) The include file
access_mode_values.incl.pl1 defines the mnemonics for these
values:

dcl (N_ACCESS_BIN init (00000b),
R_ACCESS_BIN init (01000b),
E_ACCESS_BIN init (00100b),
W_ACCESS_BIN init (00010b),
RW_ACCESS_BIN init (01010b),
RE_ACCESS_BIN init (01100b),
REW_ACCESS_BIN init (01110b),
S_ACCESS_BIN init (01000b),
M_ACCESS_BIN init (00010b),
A_ACCESS_BIN init (00001b),
SA_ACCESS_BIN init (01001b),
SM_ACCESS_BIN init (01010b),
SMA_ACCESS_BIN init (01011b))
fixed bin (5) internal static options (constant);

rb
is a three-element array that contains the ring brackets.
(Input) The ring bracket variables become the ring brackets of
the entry, if and only if, the entry is a segment. Ring
brackets must be in the allowable range 0 through 7 and must
have the ordering:

rb1 <= rb2 <= rb3

code
is a storage system status code. (Output)

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory.

_____________ ____________

hcs_$acl_add1 hcs_$acl_add
_____________ ____________

NOTES

If the segment is a gate and if the validation level is greater
than ring 1, then access is given only to a name that contains
the same project as the user or to the SysDaemon project. If the
ACL to be added is in error, no processing is performed and the
subroutine returns the code
error_table_$invalid_project_for_gate.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$aaaccclll_aaadddddd

This entry point adds up to 100 names to the access control list
(ACL) of the specified entry (segment or directory). If any name
already appears on the ACL of the entry, its mode is changed to
the one specified by the call. It also sets the ring brackets of
the entry if it is a segment.

USAGE

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

call hcs_$acl_add (dir_name, entryname, acl_ptr, acl_count,
code);

ARGUMENTS

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

entryname
is the entryname of the segment or directory. (Input)

acl_ptr
is a pointer to a user-filled acl_array structure. (Input)
The structure of this array is defined in "ACL Array".

acl_count
is a count of the number of names in the array. (Input)

code
is a storage system status code. (Output)

____________ ____________

hcs_$acl_add hcs_$acl_add
____________ ____________

ACL ARRAY

The acl_array structure should be declared in the following way:

dcl 1 acl_array (acl_count) aligned like input_acl;

The input_acl structure is as follows:

dcl 1 input_acl aligned based,
2 userid char (32) aligned,
2 mode bit (5) unaligned,
2 reterr bit (13) unaligned,
2 (rb1, rb2, rb3) bit (6) unaligned;

STRUCTURE ELEMENTS

userid
is the userid (in the form Person_id.Project_id.tag) that
identifies the processes to which this ACL name applies.

mode
contains the modes for this userid. The include file
access_mode_values.incl.pl1 defines the mnemonics for these
values:

____________ ____________

hcs_$acl_add hcs_$acl_add
____________ ____________

reterr
is a 13 bit error code for this ACL name only.

rb1
is ring bracket 1 for this ACL name.

The ring bracket variables of the last ACL name in the array
become the ring brackets of the entry, if and only if, the
entry is a segment. Ring brackets must be in the allowable
range 0 through 7 and must have the ordering:

rb1 <= rb2 <= rb3

rb2
is ring bracket 2 for this ACL name.

rb3
is ring bracket 3 for this ACL name.

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory.

NOTES

This entrypoint will attempt to process all names in the data
array and set acl_array(i).reterr to nonzero for any name that
has an error, as well as returning an error code in the system
status code.

If the segment is a gate and if the validation level is greater
than ring 1, then access is given only to names that contain the
same project as the user or to the SysDaemon project. If the ACL
to be added is in error, no processing is performed and the
subroutine returns the code
error_table_$invalid_project_for_gate.

____________ _______________

hcs_$acl_add hcs_$acl_delete
____________ _______________

NNNaaammmeee::: hhhcccsss_$$$aaaccclll_dddeeellleeettteee

This entry point deletes up to 100 names from the access control
list (ACL) of the specified entry (segment or directory). If the
count of names in the array is -1, the entire ACL is deleted. If
the count is zero, no deletions take place.

USAGE

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

call hcs_$acl_delete (dir_name, entryname, acl_ptr, acl_count,
code);

ARGUMENTS

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

entryname
is the entryname of the segment or directory. (Input)

acl_ptr
is a pointer to a user-filled acl_array structure. (Input)
The structure of this array is defined in "ACL Array".

acl_count
is a count of the number of names in the array. (Input)

code
is a storage system status code. (Output)

ACL ARRAY

The acl_array structure should be declared in the following way:

dcl 1 acl_array (acl_count) aligned like input_acl;

The input_acl structure is as follows:

dcl 1 input_acl aligned based,
2 userid char (32) aligned,
2 mode bit (5) unaligned,
2 reterr bit (13) unaligned,
2 (rb1, rb2, rb3) bit (6) unaligned;

_______________ _____________

hcs_$acl_delete hcs_$acl_list
_______________ _____________

STRUCTURE ELEMENTS

userid
is the userid (in the form Person_id.Project_id.tag) that
identifies the ACL name to be deleted.

mode
is ignored for delete.

reterr
is a 13 bit error code for this ACL name only.

rb1
is ignored for delete.

rb2
is ignored for delete.

rb3
is ignored for delete.

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory.

NOTES

________________________________________

NNNaaammmeee::: hhhcccsss_$$$aaaccclll_llliiisssttt

This entry point is used either to list the entire access control
list of the specified segment or to return the access modes for
specified ACL entries. The segment_acl_array structure used by
this entry point is described in the hcs_$add_acl_entries entry
point.

USAGE

dcl hcs_$acl_list entry (char(*), char(*), ptr, fixed bin, ptr,
fixed bin(35));

_____________ _____________

hcs_$acl_list hcs_$acl_list
_____________ _____________

call hcs_$acl_list (dir_name, entry_name, acl_ptr, acl_count,
area_ptr, code);

ARGUMENTS

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

entryname
is the entryname of the directory. (Input)

acl_ptr
if area_ptr is null, then acl_ptr points to an ACL structure,
segment_acl_array, into which mode information is to be placed
for the access names specified in that same structure. If
area_ptr is not null, then acl_ptr is set to point to an
allocated segment_acl_array structure which is filled in with
the entire ACL of the segment. (Input or Output)

acl_count
is the number of entries in the segment_acl_array structure
pointed to by acl_ptr. (If area_ptr is null, this is Input,
otherwise it is Output)

area_ptr
is a pointer to an area in which the segment_acl_array
structure should be allocated. If this is null then only
selected ACL entries are being listed, as specified by acl_ptr
and acl_count.

code
is a storage system error code. (Output)
The possible security-related codes returned are:

error_table_$incorrect_access
Either the caller has non-null access to the segment and no
status access to the containing directory, or the caller's
authorization does not dominate the containing directory's
access class.
error_table_$no_info
The caller has null access to the parent directory and
either null access to the segment or the segment does not
exist.

_____________ ________________

hcs_$acl_list hcs_$acl_replace
_____________ ________________

NOTES

If acl_ptr is used to obtain modes for specified access names
(rather than obtaining modes for all access names on the initial
ACL), then each initial ACL entry in the segment_acl_array
structure either has status_code set to 0 and contains the
segment's mode or has status_code set to
error_table_$user_not_found and contains a mode of 0.

ACCESS REQUIRED

The caller must have status effective access on the containing
directory.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$aaaccclll_rrreeeppplllaaaccceee

This entry point deletes all the names on the access control list
(ACL) of the specified entry (segment or directory), and then
adds up to 100 new names from a user-filled array. If the count
of names in the array is zero, the entire ACL is deleted and no
additions take place. If the entry is a segment, the ring
brackets are set.

USAGE

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

call hcs_$acl_replace (dir_name, entryname, acl_ptr, acl_count,
code);

ARGUMENTS

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

entryname
is the entryname of the segment or directory. (Input)

acl_ptr
is a pointer to a user-filled acl_array structure. (Input)
The structure of this array is defined in "ACL Array".

acl_count
is a count of the number of names in the array. (Input)

________________ ________________

hcs_$acl_replace hcs_$acl_replace
________________ ________________

code
is a storage system status code. (Output)

ACL ARRAY

The acl_array structure should be declared in the following way:

dcl 1 acl_array (acl_count) aligned like input_acl;

The input_acl structure is as follows:

dcl 1 input_acl aligned based,
2 userid char (32) aligned,
2 mode bit (5) unaligned,
2 reterr bit (13) unaligned,
2 (rb1, rb2, rb3) bit (6) unaligned;

STRUCTURE ELEMENTS

userid
is the userid (in the form Person_id.Project_id.tag) that
identifies the processes to which this ACL name applies.

mode
contains the modes for this userid. The include file
access_mode_values.incl.pl1 defines the mnemonics for these
values:

reterr
is a 13 bit error code for this ACL name only.

________________ ________________

hcs_$acl_replace hcs_$acl_replace
________________ ________________

rb1
is ring bracket 1 for this ACL name.

rb1 <= rb2 <= rb3

rb2
is ring bracket 2 for this ACL name.

rb3
is ring bracket 3 for this ACL name.

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory.

NOTES

___________________ ___________________

hcs_$assign_channel hcs_$assign_linkage
___________________ ___________________

NNNaaammmeee::: hhhcccsss_$$$aaassssssiiigggnnn_ccchhhaaannnnnneeelll

Requests the assignment of a special event channel (also called
fast channels) to the process. The special channel, if
available, is assigned to the ring corresponding to the current
validation level.

USAGE

declare hcs_$assign_channel entry (fixed bin(71), fixed bin(35));

call hcs_$assign_channel (event_channel_name, code);

ARGUMENTS

event_channel_name
is the name of the event channel assigned. (Output)

code
is a standard system status code (Output). The status code
error_table_$special_channels_full is returned if there are no
more available special event channels.

ACCESS REQUIRED

There are no access requirements for this entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$aaassssssiiigggnnn_llliiinnnkkkaaagggeee

This entry point allocates a specified amount of space in the
ring's original user free area.

USAGE

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

call hcs_$assign_linkage (amount, rp, code);

ARGUMENTS

amount
is the number of words to be allocated. (Input)

rp
points to the allocated space. (Output)

___________________ ___________

hcs_$assign_linkage hcs_$chname
___________________ ___________

code
is a standard storage system status code. (Output)
The possible code returned is:

error_table_$noalloc
The requested space could not be allocated.

ACCESS REQUIRED

No access required.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$bbbllloooccckkk

Causes the calling process to enter the blocked state until a
wakeup or IPS signal is received. If a wakeup is pending, the
call returns immediately. There are no arguments.

USAGE

declare hcs_$block ();

call hcs_$block ();

ACCESS REQUIRED

There are no access requirements for this gate entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ccchhhnnnaaammmeee

This entry point changes the entry name on a specified storage
system entry. If an already existing name (an old name) is
specified, it is deleted from the entry; if a new name is
specified, it is added. Thus, if only an old name is specified,
the effect is to delete a name; if only a new name is specified,
the effect is to add a name; and if both are specified, the
effect is to rename the entry.

USAGE

declare hcs_$chname entry (char(*), char(*), char(*), char(*),
fixed bin(35));

call hcs_$chname (dir_name, entryname, oldname, newname, code);

___________ ___________

hcs_$chname hcs_$chname
___________ ___________

ARGUMENTS

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

entryname
is the entry name of the segment, directory, multisegment
file, or link. (Input)

oldname
is the name to be deleted from the entry. (Input) It can be a
null character string ("") in which case no name is deleted.
If oldname is null, then newname must not be null.

newname
is the name to be added to the entry. (Input) It must not
already exist in the directory on this or another entry. It
can be a null character string ("") in which case no name is
added. If it is null, then oldname must not be the only name
on the entry.

code
is a storage system status code. (Output) It can have the
values:
error_table_$nonamerr
attempting to delete the only name of a directory entry.
error_table_$namedup
attempting to add a name that exists on another entry.
error_table_$segnamedup
attempting to add a name that already exists on this entry.
error_table_$incorrect_access
The caller's access class isn't equal to that of the entry.

ACCESS REQUIRED

The user must have modify permission on the directory containing
the entry whose name is to be changed. The process'
authorization must be equal to the entry's access class.

NOTES

The hcs_$chname_seg entry point performs a similar function using
a pointer to a segment instead of its pathname.

____________________ ____________________

hcs_$combine_linkage hcs_$combine_linkage
____________________ ____________________

NNNaaammmeee::: hhhcccsss_$$$cccooommmbbbiiinnneee_llliiinnnkkkaaagggeee

This entry point combines a segment's linkage section in the ring
of the validation level.

USAGE

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

call hcs_$combine_linkage (segment_ptr, ring, code);

ARGUMENTS

segment_ptr
points to the segment whose linkage is to be combined.
(Input)

ring
is the ring in which to combine; it must be the current
validation level. (Input)

code
is a standard storage system status code. (Output)
The possible security-related codes returned are:

error_table_$bad_ring_brackets
The caller has non-null access and the caller's ring is not
in the segment's read bracket but is in the parent's read
bracket.
error_table_$no_info
Either the caller has null access to both segment and
parent or the caller's ring is in the read bracket of
neither segment nor parent.

NOTES

A seg_fault_error condition is raised if the caller has null
access to the segment, non-null access to the parent, and the
caller's ring is within the segment's read bracket.

ACCESS REQUIRED

The access required is R access on the segment in the ring of the
validation level.

___________________ ___________________

hcs_$delete_channel hcs_$dir_quota_move
___________________ ___________________

NNNaaammmeee::: hhhcccsss_$$$dddeeellleeettteee_ccchhhaaannnnnneeelll

Causes the specified special event channel (also called a fast
channel) to be unassigned from the process.

USAGE

declare hcs_$delete_channel entry (fixed bin(71), fixed bin(35));

call hcs_$delete_channel (event_channel_name, code);

ARGUMENTS

event_channel_name
is the name of a fast event channel. (Input)

code
is a standard system status code. (Output). This code is
error_table_$invalid_channel if the specified channel is
invalid (not a valid special channel). It is
error_table_$wrong_channel_ring if the ring number associated
with the special channel is not equal to the caller's current
validation level.

ACCESS REQUIRED

There are no access requirements for this gate entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$dddiiirrr_qqquuuoootttaaa_mmmooovvveee

moves all or part of a directory quota between two directories,
one of which is immediately inferior to the other.

USAGE

declare hcs_$dir_quota_move entry (char(*), char(*), fixed bin,
fixed bin(35));

call hcs_$dir_quota_move (dir_name, entryname, quota_change,
code);

ARGUMENTS

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

___________________ ___________________

hcs_$dir_quota_move hcs_$dir_quota_read
___________________ ___________________

entryname
is the entryname of the directory. (Input)

quota_change
is the number of records of directory quota to be moved
between the superior directory and the inferior directory.
(Input) (See "Notes" below.)

code
is a storage system status code. (Output)

NOTES

Notes: After the directory quota change, the remaining directory
quota in each directory must be greater than the number of
records used by directories in that directory.

The quota_change argument can be either a positive or negative
number. If it is positive, the quota is moved from dir_name to
entryname. If it is negative, the move is from entryname to
dir_name. If the change results in zero quota left on entryname,
that directory is assumed to no longer contain a terminal quota
and all of its used records are reflected up to the used records
on dir_name. It is a restriction that no quota in any of the
directories superior to entryname can be modified from a nonzero
value to a zero value by this subroutine.

It is allowed to move directory quota from a master directory to
and from its parent, since master directory status applies only
to the quota used by segments.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$dddiiirrr_qqquuuoootttaaa_rrreeeaaaddd

returns the directory record quota and accounting information for
a directory.

USAGE

declare hcs_$dir_quota_read entry (char(*), fixed bin(18), fixed
bin(71), bit(36) aligned, bit(36), fixed bin(1), fixed bin,
fixed bin(35));

call hcs_$dir_quota_read (dir_name, quota, trp, tup, sons_lvid,
tacc_sw, used, code);

___________________ ___________________

hcs_$dir_quota_read hcs_$dir_quota_read
___________________ ___________________

ARGUMENTS

dir_name
is the pathname of the directory for which directory quota
information is desired. (Input)

quota
is the directory record quota in the directory. (Output)

trp
is the directory time-record product (trp) charged to the
directory. (Output) This double-precision number is in units
of record-seconds.

tup
is the time, expressed in storage system time format (the
high-order 36 bits of the 52-bit time returned by the clock_
subroutine) that the directory trp was last updated. (Output)

sons_lvid
is the logical volume ID for segments contained in this
directory. (Output)

tacc_sw
is the terminal directory account switch. (Output) The
setting of this switch determines how charges are made.
1 directory records are charged against the directory quota in
this directory
0 directory records are charged against the directory quota in
the first superior directory with a terminal directory account

used
is the number of records used by directories in this directory
and by directories in nonterminal inferior directories.
(Output)

code
is a storage system status code. (Output)

NOTES

If the directory contains a nonterminal account, the quota, trp,
and tup are all zero. The variable specified by used, however,
is kept up-to-date and represents the number of directory records
in this directory and inferior, nonterminal directories.

___________________ _____________________________

hcs_$dir_quota_read hcs_$echo_negotiate_get_chars
___________________ _____________________________

NNNaaammmeee::: hhhcccsss_$$$eeeccchhhooo_nnneeegggoootttiiiaaattteee_gggeeettt_ccchhhaaarrrsss

This entrypoint reads characters from a communications channel,
echoing some or all of them under program control. Echoing is
controlled by the parameters of the call as well as by a
break_table supplied via a control order. This entrypoint is
obsolete, replaced by hcs_$tty_read_echoed.

USAGE

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

call hcs_$echo_negotiate_get_chars (device_index,
buffer_word_ptr, buffer_word_offset, buffer_length, n_trans,
n_echoed, screen_left, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

buffer_word_ptr
is a pointer to to beginning of the word containing the first
character of the data buffer. If the buffer is not on an even
work boundary, the buffer_word_offset is used to specify the
character position within the word. (input)

buffer_word_offset
is the character index (0, 1, 2, or 3) of the first character
of the buffer within the first word of the buffer. (input)

buffer_length
is the length of the data buffer in characters. (input)

n_trans
is the number of characters transferred by this call.
(output)

n_echoed
is the number of the returned characters that were echoed by
the system. (output)

screen_left
is the number of character positions left on the screen. This
is the maximum number of characters that will be echoed if no
break characters are typed. (input)

_____________________________ ___________

hcs_$echo_negotiate_get_chars hcs_$fblock
_____________________________ ___________

state
is the state of the communications channel. The possible
values returned are declared in the include file
tty_states.incl.pl1. The only value that can be returned to
processes other than the initializer is TTY_STATE_DIALED_UP.
If the channel is in any other state, the status code will be
error_table_$io_no_permission and the state will be undefined.
In the initializer process, any of the states declared in the
initializer may be returned. (output)

code
is the state of the communications channel. The possible
values returned are declared in the include file
tty_states.incl.pl1. The only value that can be returned to
processes other than the initializer is TTY_STATE_DIALED_UP.
If the channel is in any other state, the status code will be
error_table_$io_no_permission and the state will be undefined.
In the initializer process, any of the states declared in the
initializer may be returned. (output)

NOTES

There is a complex protocol that is used to synchronize the
application using echoed input and the system. This protocol is
not described here; see the source in tty_read.pl1.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$fffbbbllloooccckkk

Returns only when a wakeup is received, either for a fast channel
or for a regular channel. It returns information about which
fast channel received a wakeup and whether any messages were
emptied from the Interprocess Transmission Table (ITT) into the
process' Event Channel Table (ECT).

USAGE

declare hcs_$fblock entry (bit (36) aligned, bit (1) aligned);

call hcs_$fblock (fast_channel_events,
messages_allocated_in_ect);

___________ ____________________________

hcs_$fblock hcs_$flush_consecutive_pages
___________ ____________________________

ARGUMENTS

fast_channel_events
indicates on which fast channels wakeups are pending.
(Input/Output) Each bit corresponds to a fast channel. The
other bits in the string are untouched.

messages_allocated_in_ect
is set to "1"b if any messages were allocated in the ECT for
the validation ring. (Output)

ACCESS REQUIRED

There are no access requirements for this gate entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$fffllluuussshhh_cccooonnnssseeecccuuutttiiivvveee_pppaaagggeeesss

forces the supervisor to write the modified pages from a
specified set of consecutive pages in each of a set of specified
segments within the process' address space out to disk.

USAGE

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

call hcs_$flush_consecutive_pages (flush_consecp, code);

ARGUMENTS

flush_consecp
is a pointer to a flush_consec structure as described in
flush_structures.incl.pl1. (Input) See "Notes" below.

code
is a standard status code. (Output) See "Notes" below.

NOTES

The flush_consec structure referred to by flush_consecp provides
a list of segments, and for each, a range of pages within each
segment to be flushed.

Use of this entry point may introduce substantial real time delay
into execution, since the caller must wait for the movement of
the disk; other usage of the system, meanwhile, may cause further
delay.

____________________________ ________________

hcs_$flush_consecutive_pages hcs_$flush_pages
____________________________ ________________

This entry point protects data against an unrecoverable main
memory crash. This entry point returns the following non-zero
status codes. If the segment is an inner ring segment,
error_table_$bad_ring_brackets is returned. If the user does not
have write access to the segment, error_table_$moderr is
returned. If the segment is not known, or a hardcore segment,
then error_table_$invalidsegno is returned.

The pages are written one segment at a time. Any error
encountered will abort the list.

ACCESS REQUIRED

None.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$fffllluuussshhh_pppaaagggeeesss

forces the supervisor to write selected non-hardcore,
non-directory pages to disk. The pages are in the process'
address space and are written only if they have been modified.

USAGE

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

call hcs_$flush_pages (flushp, code);

ARGUMENTS

flushp
is a pointer to a flush structure as described in
flush_structures.incl.pl1. (Input) See "Notes" below.

code
is a standard status code. (Output)

error_table_$argerr
a page number is less than 0 or greater than 255
error_table_$dirseg
the segment is a directory
error_table_$invalidsegno
the segment is not known, or is a hardcore segment.
error_table_$unimplemented_version

________________ ____________________

hcs_$flush_pages hcs_$fs_get_brackets
________________ ____________________

NOTES

The flush structure referred to by flushp provides a list of
selected pages within selected segments to be flushed.

This entry point protects data against an unrecoverable main
memory crash. The pages are written one segment at a time. Any
error encountered will abort the list.

ACCESS REQUIRED

None.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$fffsss_gggeeettt_bbbrrraaaccckkkeeetttsss

hcs_$fs_get_brackets returns the access mode of the user on a
specified segment at the current validation level, and the ring
brackets of the segment. For a discussion of access modes, see
"Access Control" in the Programmer's Reference Manual. This
entrypoint is obsolete.

USAGE

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

call hcs_$fs_get_brackets (seg_ptr, mode, ring_brackets, code);

ARGUMENTS

seg_ptr
is a pointer to the segment whose access mode is to be
returned. (Input)

mode
is the access mode returned. See the description of the
hcs_$append_branchx entry point for the possible values of the
mode argument. (Output)

ring_brackets
are the ring brackets of the segment.

____________________ ____________________

hcs_$fs_get_brackets hcs_$fs_get_dir_name
____________________ ____________________

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

error_table_$no_info
the user does not have enough access to get any
information.

NOTES

The mode and ring brackets for the segment in the user's address
space are used in combination with the user's current validation
level to determine the mode the user would have if the user
accessed this segment. For a discussion of ring brackets and
validation level, see "Intraprocess Access Control" in the
Programmer's Reference Manual.

ACCESS REQUIRED

This entry point requires s access to the parent of the object,
or non-null access to the object itself.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$fffsss_gggeeettt_dddiiirrr_nnnaaammmeee

This entry point returns a name of the directory containing the
specified segment.

USAGE

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

call hcs_$fs_get_dir_name (segment_ptr, dirname, dirname_length,
code);

ARGUMENTS

segment_ptr
is a pointer to a segment. (Input)

dirname
is the directory name of the segment. (Output)

dirname_length
is the length in words of the directory name. (Output)

____________________ _______________________

hcs_$fs_get_dir_name hcs_$fs_search_get_wdir
____________________ _______________________

code
is a standard storage system status code. (Output)
The possible security-related codes returned are:

error_table_$incorrect_access
The caller's access class is either insufficient or
inconsistent with that of the directory.
error_table_$no_info
The caller does not have the necessary access modes.

ACCESS REQUIRED

The access required is non-null on the entry and S on the parent
directory.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$fffsss_ssseeeaaarrrccchhh_gggeeettt_wwwdddiiirrr

This entry point returns the pathname of the working directory.

USAGE

declare hcs_$fs_search_get_wdir entry (ptr, fixed bin);

call hcs_$fs_search_get_wdir (pathname_ptr, pathname_length);

ARGUMENTS

pathname_ptr
is a pointer to the char (168) aligned string which is to
contain the pathname. (Input)

pathname_length
is the length in characters of the working directory pathname.
(Output)

ACCESS REQUIRED

The access required is S on the working directory and/or S on the
parent directory.

_______________________ _______________________

hcs_$fs_search_set_wdir hcs_$fs_search_set_wdir
_______________________ _______________________

NNNaaammmeee::: hhhcccsss_$$$fffsss_ssseeeaaarrrccchhh_ssseeettt_wwwdddiiirrr

This entry point makes the specified directory the working
directory in the ring of the validation level.

USAGE

declare hcs_$fs_search_set_wdir entry (char(*), fixed bin(35));

call hcs_$fs_search_set_wdir (wdir_name, code);

ARGUMENTS

wdir_name
is the pathname of the new working directory. (Input)

code
is a standard storage system status code. (Output)
The possible security-related codes returned are:

error_table_$incorrect_access
The specified directory's access class is either higher
than or inconsistent with the caller's access class.
error_table_$no_dir
Some directory in the path specified does not exist and the
caller has access to search the "parent" of the nonexistent
directory.
error_table_$no_info
The caller has insufficient access to both the specified
directory and its parent, where insufficient access can
mean either NULL access on the directory or that the
caller's ring is not in the directory's ring bracket.

ACCESS REQUIRED

The access required is S access on the directory to be set and/or
S access on its parent directory.

_______________________ ______________________

hcs_$fs_search_set_wdir hcs_$get_authorization
_______________________ ______________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_aaalllaaarrrmmm_tttiiimmmeeerrr

returns the current value of the pending timer and associated
event channel.

USAGE

declare hcs_$get_alarm_timer entry (fixed bin(71), fixed
bin(71));

call hcs_$get_alarm_timer (timer_value, event_channel);

ARGUMENTS

timer_value
time of alarm. Zero means no timer active. (Output)

event_channel
event channel for wakeup. (Output)

ACCESS REQUIRED

None.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_aaauuuttthhhooorrriiizzzaaatttiiiooonnn

This entry point returns the access authorization and the maximum
attainable access authorization values for the process.

USAGE

declare hcs_$get_authorization entry (bit(72) aligned, bit(72)
aligned);

call hcs_$get_authorization (authorization, max_authorization);

ARGUMENTS

authorization
is the access authorization for the process. (Output)

max_authorization
is the maximum access authorization the user can attain.
(Output)

______________________ ______________

hcs_$get_authorization hcs_$get_dates
______________________ ______________

ACCESS REQUIRED

No access is required. This entry has per-process effects only,
and may be called from any ring.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_dddaaattteeesss

Returns the date/time used, date/time modified, date/time entry
modified, date/time dumped and the date/time volume dumped for a
segment. Status permission on the directory or nonnull access on
the entry is required to use this entry point.

USAGE

declare hcs_$get_dates entry (char(*), char(*), (*) bit(36),
fixed bin(35));

call hcs_$get_dates (dir_name, entryname, dates, code);

ARGUMENTS

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

entryname
is the entryname of the segment or directory. (Input)

dates
is an array of dates in file system format (the high order 36
bits of the value returned by the clock_ subroutine). The
dates are returned in the order: date/time used, date/time
modified, date/time entry modified, date/time dumped,
date/time volume dumped. Only as many values are returned as
are implied by the dimension of this argument.

code
is a storage system status code. (Output)

__________________ _________________

hcs_$get_dates_ptr hcs_$get_defname_
__________________ _________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_dddaaattteeesss_ppptttrrr

USAGE

declare hcs_$get_dates_ptr entry (ptr, (*) bit(36), fixed
bin(35));

call hcs_$get_dates_ptr (seg_ptr, dates, code);

ARGUMENTS

seg_ptr
is a pointer to the segment. (Input)

code
is a storage system status code. (Output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_dddeeefffnnnaaammmeee_

Returns the entry name corresponding to a given entry offset for
a segment or gate.

USAGE

declare hcs_$get_defname_ entry (ptr, ptr, bit(18) aligned, fixed
bin, char(*), fixed bin(35));

call hcs_$get_defname_ (linkptr, defptr, offset, section,
entry_name, code);

_________________ _________________

hcs_$get_defname_ hcs_$get_defname_
_________________ _________________

ARGUMENTS

linkptr
a pointer to the active linkage section for the entry.
(Input) This value must be supplied only if defptr is null.

defptr
a pointer to the definitions section or to the segment if the
segment is a gate. (Input) If this value is null, the
definitions will be found via the linkage section indicated by
linkptr.

offset
the offset of the entry. (Input)

section
the object section to which the offset is relative. (Input) A
value of -1 indicates that any definition class is acceptable.

entry_name
the entry name from the definitions. (Output)

code
a storage system status code. (Output)
The possible codes returned are:

error_table_$defs_loop
The object segment's definitions are not threaded properly
or there are too many of them.
error_table_$no_ext_sym
A definition corresponding to the given offset was not
found.

NOTES

This primitive searches the definitions section for the given
object segment looking for a definition for an entry offset equal
to the supplied offset and whose class (section of the object
segment) matches the supplied section. It is used by process
debugging tools to determine the entrypoint called from
information in the stack frame for a procedure.

The user must have "e" effective access to the segment in the
calling ring and have "r" effective access in the ring of
execution for the segment.

_________________ _____________________________

hcs_$get_defname_ hcs_$get_hex_exponent_control
_________________ _____________________________

In some situations conditions are raised that are not caught and
transformed into error codes. seg_fault_error is raised if the
caller has null access to the object segment.
not_in_read_bracket is raised if the caller's ring is not in the
object segment's read bracket, although the entry will handle
gates if the linkptr argument is used.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_hhheeexxx_eeexxxpppooonnneeennnttt_cccooonnntttrrrooolll

Returns the state of automatic hexadecimal mode floating point
under flow and over flow restart.

USAGE

declare hcs_$get_hex_exponent_control entry (bit (1) aligned, bit
(1) aligned, bit (72) aligned);

call hcs_$get_hex_exponent_control (restart_underflow,
restart_overflow, max_value);

ARGUMENTS

restart_underflow
is a flag. If "1"b, floating overflows in hex mode will be
automatically restarted with a result value specified by the
parameter "max_value." (Output)

restart_overflow
is a flag. if "1"b, floating underflows in hex mode will be
automatically restarted with a result value of zero. (Output)

max_value
is the value to be used when automatically restarting floating
overflows. (Output)

ACCESS REQUIRED

None.

_____________________________ _____________________

hcs_$get_hex_exponent_control hcs_$get_ipc_operands
_____________________________ _____________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_iiipppccc_ooopppeeerrraaannndddsss

Returns the two constants used to construct event channel names
for the calling process.

USAGE

declare hcs_$get_ipc_operands entry (fixed bin (18), fixed bin
(35));

call hcs_$get_ipc_operands (r_offset, r_factor);

ARGUMENTS

r_offset
This is a number determined at process creation time that is
used to construct event channel names. (Output) See "Notes"
for more information.

r_factor
This is a number determined at process creation time that is
used to construct event channel names. (Output) See "Notes"
for more information.

NOTES

These two constants are determined randomly (from the clock) at
process creation time. Event channel names are constructed by
using these numbers in a one-way algorithm. See
ipc_validate_.pl1 for more information on this. These quantities
should never be stored in storage readable by other processes.

ACCESS REQUIRED

None.

___________ __________________________

hcs_$get_lp hcs_$get_page_trace_signal
___________ __________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_lllppp

This entry point returns a pointer to the specified segment's
combined linkage section in the ring of the validation level.
The LOT in the ring's initial stack is used.

USAGE

declare hcs_$get_lp entry (ptr, ptr);

call hcs_$get_lp (segment_ptr, linkage_ptr);

ARGUMENTS

segment_ptr
is a pointer to the segment whose linkage section is desired.
(Input)

linkage_ptr
is a pointer to the segment's combined linkage section in the
ring of the validation level. (Output)

ACCESS REQUIRED

No access required.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_pppaaagggeee_tttrrraaaccceee_sssiiigggnnnaaalll

returns information about the signalling of the pgt_ IPS signal
when the per-process event trace buffer is full.

USAGE

declare hcs_$get_page_trace_signal entry (bit (1) aligned, fixed
bin);

call hcs_$get_page_trace_signal (signal_sw, threshold);

ARGUMENTS

signal_sw
is a flag. (Output) It will be "1"b if signalling of the pgt_
condition is enabled when the trace buffer is full, and "0"b
if signalling is disabled.

__________________________ _________________________

hcs_$get_page_trace_signal hcs_$get_segment_ptr_path
__________________________ _________________________

threshold
is the fullness threshold, expressed as a number between 0 and
100. (Output) The pgt_ condition will be signalled when the
trace buffer is that percent full.

ACCESS REQUIRED

None.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_ssseeegggmmmeeennnttt_ppptttrrr_pppaaattthhh

Returns the segment number and UID of a segment already known to
the calling process.

USAGE

declare hcs_$get_segment_ptr_path entry (char(*), char(*), ptr,
bit(36), fixed bin(35));

call hcs_$get_segment_ptr_path (dir_name, entryname, seg_ptr,
uid, code);

ARGUMENTS

dir_name
is the directory name of the segment. (Input)

entryname
is the entryname of the segment. (Input)

seg_ptr
is a pointer to the segment. If the segment is not already
known to the calling process (via initiation) then this will
be null on return. (Output)

uid
is the unique ID of the segment. (output)

code
is a standard system status code. (Output)

______________________ _____________________________

hcs_$get_user_raw_mode hcs_$get_volume_dump_switches
______________________ _____________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_uuussseeerrr_rrraaawww_mmmooodddeee

returns a user's access modes to a segment or directory without
regard for ring brackets.

USAGE

declare hcs_$get_user_raw_mode entry (char(*), char(*), char(*),
bit(36) aligned, fixed bin(35));

call hcs_$get_user_raw_mode (dir_name, entryname, user_name,
modes, code);

ARGUMENTS

dir_name
is the directory name of the segment or directory. (Input)

entryname
is the entryname of the segment or directory. (Input)

user_name
is the name of the user whose modes are to be returned. If
this is "", the caller's modes are returned.

modes
are the access modes of the user on the specified object.
(Output)

code
is a standard system status code.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$gggeeettt_vvvooollluuummmeee_ddduuummmppp_ssswwwiiitttccchhheeesss

returns the value of the incremental and complete volume dump
switches for a segment. The process must have status permission
on the directory containing the segment or non-null access on the
segment.

USAGE

declare hcs_$get_volume_dump_switches entry (char(*), char(*),
fixed bin, fixed bin, fixed bin(35));

call hcs_$get_volume_dump_switches (dir_name, entryname,
incremental_sw, complete_sw, code);

_____________________________ _____________

hcs_$get_volume_dump_switches hcs_$grow_lot
_____________________________ _____________

ARGUMENTS

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

entryname
is the entryname of the segment. (Input)

incremental_sw
is the value of the incremental volume dump switch. A value
of 1 means that the incremental volume dumper is prevented
from dumping this segment. A value of -1 means that dumping
of this segment is allowed.

complete_sw
is the value of the complete volume dump switch. A value of 1
means that the complete volume dumper is prevented from
dumping this segment. A value of -1 means that dumping of
this segment is allowed.

code
is a storage system status code. (Output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$gggrrrooowww_lllooottt

This entry point increases the LOT in the specified ring to its
maximum size by reallocating and copying it. The lot_ptr in the
ring's initial stack is used.

USAGE

declare hcs_$grow_lot entry (fixed bin(3));

call hcs_$grow_lot (ring);

ARGUMENTS

ring
is the ring number; it must be the same as the validation
level. (Input)

ACCESS REQUIRED

No access required.

_____________ __________________________

hcs_$grow_lot hcs_$initiate_search_rules
_____________ __________________________

NNNaaammmeee::: hhhcccsss_$$$iiinnniiitttiiiaaattteee_ssseeeaaarrrccchhh_rrruuullleeesss

This entry point provides the user with a subroutine interface
for specifying the search rules that he wants to use in his
process.

USAGE

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

call hcs_$initiate_search_rules (search_rules_ptr, code);

ARGUMENTS

search_rules_ptr
is a pointer to a structure containing the new search rules.
See "Information Structure" below. (Input)

code
is a storage system status code. (Output)
error_table_$bad_string
not a pathname or keyword
error_table_$notadir
error_table_$too_many_sr

INFORMATION STRUCTURE

The structure pointed to by search_rules_ptr is declared as
follows:

dcl 1 search_rules aligned,
2 number fixed bin,
2 names (21) char(168) aligned;

STRUCTURE ELEMENTS

number
is the number of search rules contained in the array. The
current maximum number of search rules the user can define is
21.

names
are the names of the search rules. Two types of search rules
are permitted: absolute pathnames of directories to be
searched or keywords.

__________________________ __________________________

hcs_$initiate_search_rules hcs_$initiate_search_rules
__________________________ __________________________

LIST OF KEYWORDS

initiated_segments
search for the already initiated segments.

referencing_dir
search the containing directory of the segment making the
reference.

working_dir
search the working directory.

process_dir
search the process directory.

home_dir
search the home directory.

set_search_directories
insert the directories following this keyword into the default
search rules after working_dir, and make the result the
current search rules.

site-defined keywords
may also be specified. These keywords may expand into one or
more directory pathnames. The keyword, default, is always
defined to be the site's default search rules.

NOTES

The set_search_directories keyword, when used, must be the first
search rule specified and the only keyword used. If this keyword
is used, hcs_$initiate_search_rules sets the default search
rules, and then inserts the specified directories in the search
rules after the working directory.

Some of the keywords, such as set_search_directories, are
expanded into more than one search rule. The limit of 21 search
rules applies to the final number of search rules to be used by
the process as well as to the number of rules contained in the
array.

The search rules remain in effect until this entry point is
called with a different set of rules or the process is
terminated. Codes that can be returned from this entry point
are:

__________________________ ______________

hcs_$initiate_search_rules hcs_$level_set
__________________________ ______________

error_table_$bad_string (not a pathname or keyword)
error_table_$notadir
error_table_$too_many_sr

Additional codes can be returned from other procedures that are
called by hcs_$initiate_search_rules.

For the values of the site-defined keywords, the user may call
the hcs_$get_system_search_rules entry point.

ACCESS REQUIRED

None.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$llleeevvveeelll_gggeeettt

returns the current validation level.

USAGE

declare hcs_$level_get entry fixed bin (3);

call hcs_$level_get (level);

ARGUMENTS

level
the current validation level. (Output)

ACCESS REQUIRED

None.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$llleeevvveeelll_ssseeettt

Establish a new validation level for the process.

USAGE

declare hcs_$level_set entry fixed bin(3);

call hcs_$level_set (level);

______________ _______________

hcs_$level_set hcs_$link_force
______________ _______________

level
the validation level to be made current. (Input)

NOTES

The level cannot be set to a value lower than the current ring of
execution.

ACCESS REQUIRED

None.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$llliiinnnkkk_fffooorrrccceee

This entry point snaps a link that was not faulted on.

USAGE

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

call hcs_$link_force (link_pair_ptr, ignore, code);

ARGUMENTS

link_pair_ptr
is a pointer to the link to be snapped. (Input)

ignore
is not used.

code
is a standard storage system status code. (Output)
The possible security-related codes returned are:

error_table_$moderr
Either the caller had NULL access to the target and S
access to the parent, or the caller's ring was not in the
target's call bracket.
error_table_$seg_not_found
The target was not found. The caller may have had NULL
access to both the intended target and its parent.

NOTES

A no_read_permission condition is raised if the caller's access
in the call bracket is non-NULL but does not include R access.

_______________ _____________

hcs_$link_force hcs_$list_acl
_______________ _____________

ACCESS REQUIRED

The access required on the target is R access in the call
bracket.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$llliiisssttt_aaaccclll

This entry point is used either to list the entire access control
list (ACL) of a segment or to return the access modes of
specified ACL entries. The segment_acl_array structure used by
this entry point is discussed in the description of
hcs_$add_acl_entries.

USAGE

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

call hcs_$list_acl (dir_name, entryname, area_ptr, area_ret_ptr,
acl_ptr, acl_count, code);

ARGUMENTS

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

entryname
is the entryname of the segment. (Input)

area_ptr
points to an area in which the list of ACL entries, which make
up the entire ACL of the segment, is allocated. (Input) If
area_ptr is null, then the user wants access modes for certain
ACL entries; these will be specified by the structure pointed
to by acl_ptr (see below).

area_ret_ptr
points to the start of the allocated list of ACL entries.
(Output)

acl_ptr
if area_ptr is null, then acl_ptr points to an ACL structure,
segment_acl_array, into which mode information is placed for
the access names specified in that same structure. (Input)

acl_count
is the number of entries in the ACL structure. (Input or

_____________ _____________

hcs_$list_acl hcs_$list_dir
_____________ _____________

Output)
Input
is the number of entries in the ACL structure identified by
acl_ptr.
Output
is the number of entries in the segment_acl_array structure
allocated in the area pointed to by area_ptr, if area_ptr
is not null.

code
is a storage system status code. (Output)

NOTES

If acl_ptr is used to obtain modes for specified access names
(rather than for all access names on a segment), then each ACL
entry in the segment_acl_array structure either has status_code
set to 0 and contains the segment's mode or has status_code set
to error_table_$user_not_found and contains a mode of 0.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$llliiisssttt_dddiiirrr

This entry point returns information about all the entries in the
specified directory, plus a count of the number of branches
(segments and directories) and the number of links. The
information is returned in the user-defined area. If user-area
is null, dc_n_branches and dc_n_links are set to the total number
of respective entries. This entry point will try to return
information kept in the volume table of contents (VTOC) if it is
mounted, and it can be time consuming to access the VTOC entries
for all branches in a large directory.

USAGE

declare hcs_$list_dir entry (char(*), area(1024), ptr, fixed bin,
ptr, fixed bin, fixed bin(35));

call hcs_$list_dir (dir_name, user_area, dc_branch_arrayp,
dc_n_branches, dc_link_arrayp, dc_n_links, code);

_____________ _____________

hcs_$list_dir hcs_$list_dir
_____________ _____________

ARGUMENTS

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

user_area
is the user-defined area where the structures will be
allocated. (Input)

dc_branch_arrayp
is a pointer to the allocated array structure in which
information on each branch is returned. (Output) This array
structure is defined in "Branch Array Structure".

dc_n_branches
is a count of the number of branches in the directory.
(Output)

dc_link_arrayp
is a pointer to the allocated array structure in which
information on each link is returned. (Output) This array
structure is defined in "Link Array Structure".

dc_n_links
is a count of the number of links in the directory. (Output)

code
is a storage system status code. (Output)

BRANCH ARRAY STRUCTURE

The branch array structure will be allocated as follows:

dcl 1 dcpack_branch_array (dc_n_branches)
like dcpack_branch based (dc_branch_arrayp) aligned;

The branch structure, defined as dcpack_branch in the include
file dcpack_info.incl.pl1, is as follows:

dcl 1 dcpack_branch based (dc_branchp) aligned;
2 vtoc_error bit (1) unal,
2 pad1 bit (1) unal,
2 uid bit (70) unal,
2 pad2 bit (20) unal,
2 dtu bit (52) unal,
2 pad3 bit (20) unal,
2 dtm bit (52) unal,
2 pad4 bit (20) unal,

_____________ _____________

hcs_$list_dir hcs_$list_dir
_____________ _____________

2 dtd bit (52) unal,
2 pad5 bit (20) unal,
2 dtem bit (52) unal,
2 pad6 bit (20) unal,
2 rd bit (52) unal,
2 dirsw bit (1) unal,
2 optsw bit (2) unal,
2 bc bit (24) unal,
2 consistsw bit (2) unal,
2 mode bit (5) unal,
2 usage bit (2) unal,
2 usagect bit (17) unal,
2 nomore bit (1) unal,
2 cl bit (9) unal,
2 ml bit (9) unal,
2 acct bit (36),
2 hlim bit (17) unal,
2 llim bit (17) unal,
2 pad7 bit (2) unal,
2 rb1 bit (6) unal,
2 rb2 bit (6) unal,
2 rb3 bit (6) unal,
2 pad8 bit (18) unal,
2 pad9 bit (18) unal,
2 namerp bit (18) unal,
2 nnames fixed bin,

_____________ _____________

hcs_$list_dir hcs_$list_dir
_____________ _____________

STRUCTURE ELEMENTS

vtoc_error
the VTOCE of this entry could not be read, thus the VTOCE
fields are invalid.

uid
is the 36 bit segment UID at the front of 70 bits.

dtu
is the date and time the branch was last used. This VTOCE
field is invalid if vtoc_error is "1"b.

dtm
is the date and time the contents of the branch was last
modified. This VTOCE field is invalid if vtoc_error is "1"b.

dtd
is the date and time the branch was last dumped (hierarchy).

dtem
is the date and time the branch was last modified.

rd
is an unused field.

dirsw
specifies whether entry is a directory.

optsw
specifies whether the copy switch is on.

bc
is the bit count of the segment or directory.

consistsw
is an unused field.

mode
is the current user's access mode for this segment or
directory. The values of these bits are the same as for the
fixed bin (5) mode, defined in the include file
access_mode_values.incl.pl1, as follows:

_____________ _____________

hcs_$list_dir hcs_$list_dir
_____________ _____________

usage
is an unused field.

usagect
is an unused field.

nomore
is an unused field.

cl
is the current length of the segment or directory in units of
1024-word records. This VTOCE field is invalid if vtoc_error
is "1"b.

ml
is the maximum length of the segment or directory in units of
1024-word records. This VTOCE field is invalid if vtoc_error
is "1"b.

acct
is an unused field.

hlim
is an unused field.

llim
is an unused field.

rb1
is ring bracket 1 for a segment or dir ring bracket for a
directory.

_____________ _____________

hcs_$list_dir hcs_$list_dir
_____________ _____________

rb2
is ring bracket 2 for a segment or dir ring bracket for a
directory.

rb3
is ring bracket 3 for a segment or dir ring bracket for a
directory.

namerp
is a relative pointer into area of names array structure for
this entry. This structure is defined in "Names Array
Structure".

nnames
is the number of addnames on this segment or directory.

LINK ARRAY STRUCTURE

The link array structure will be allocated as follows:

dcl 1 dcpack_link_array (dc_n_links)
like dcpack_link based (dc_link_arrayp) aligned;

The link structure, defined as dcpack_link in the include file
dcpack_info.incl.pl1, is as follows:

dcl 1 dcpack_link based (dc_linkp) aligned,
2 pad1 bit (2) unal,
2 uid bit (70) unal,
2 pad2 bit (20) unal,
2 dtu bit (52) unal,
2 pad3 bit (20) unal,
2 dtem bit (52) unal,
2 pad4 bit (20) unal,
2 dtd bit (52) unal,
2 pathnamerp bit (18) unal,
2 namerp bit (18) unal,
2 nnames fixed bin;

STRUCTURE ELEMENTS

uid
is the 36 bit segment UID at the front of 70 bits.

dtu
is the date and time the link was last used.

_____________ _____________

hcs_$list_dir hcs_$list_dir
_____________ _____________

dtd
is the date and time the link was last dumped (hierarchy).

dtem
is the date and time the link was last modified.

pathnamep
is a relative pointer into area of link pathname. This
structure is defined in "Link Pathname Structure".

namep
is a relative pointer into area of names array structure for
this link. This structure is defined in "Names Array
Structure".

nnames
is the number of addnames on this link.

NAME ARRAY STRUCTURE

The name array structure will be allocated as follows:

dcl 1 dcpack_name_array (dc_n_names) aligned like dcpack_ename based (dc_name_arrayp);

dcl 1 dcpack_ename based (dc_namep) aligned,
2 size fixed bin (16) unal,
2 pad bit (19) unal,
2 name char (32) unaligned;

STRUCTURE ELEMENTS

size
is the length of added name.

name
is the name for compatability with old status command.

LINK PATHNAME STRUCTURE

The link pathname structure, defined as dcpack_path in the
include file dcpack_info.incl.pl1, is as follows:

_____________ _______________

hcs_$list_dir hcs_$set_copysw
_____________ _______________

dcl 1 dcpack_path based (dc_pnp) aligned,
2 size fixed bin (16) unal,
2 pad bit (19) unal,
2 author char (32) unaligned,
2 name char (168) unaligned;

STRUCTURE ELEMENTS

size
is the length of link pathname in chars.

author
is the author.

name
is the link pathname.

ACCESS REQUIRED

Status permission is required on the containing directory.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_cccooopppyyyssswww

This entry point allows the copy switch associated with the
specified entry (segment or directory) to be changed. The copy
switch is used to determine whether the segment itself or a copy
of the segment is made available to a process, it has no meaning
for a directory.

USAGE

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

call hcs_$set_copysw (dir_name, entryname, copy_sw, code);

ARGUMENTS

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

entryname
is the entryname of the segment or directory. (Input)

_______________ __________________

hcs_$set_copysw hcs_$set_cpu_timer
_______________ __________________

copy_sw
is the new value of the copy switch. (Input)

1 a copy of the segment will be made whenever it is initiated
0 a copy of the segment will not be made when it is initiated

code
is a storage system status code. (Output) It can have the
value:

error_table_$bad_ring_brackets
attempting to change the copy switch when the ring brackets
are less than the validation level of the user.

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory. Also, the user's validation level must be within the
first ring bracket of the entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_cccpppuuu_tttiiimmmeeerrr

Establishes a CPU timer for the process which will cause a IPC
wakeup or IPS signal to be sent when the specified CPU time
passes.

USAGE

declare hcs_$set_cpu_timer entry (fixed bin (71), fixed bin,
fixed bin (71));

call hcs_$set_cpu_timer (alarm_time, abs_rel_sw,
event_channel_nane);

ARGUMENTS

alarm_time
is the time, either absolute or relative, at which an IPC
wakeup or IPS signal is to be sent to the process. (Input)

abs_rel_sw
is either 1 for relative time, or 2 for absolute time.
(Input)

__________________ ___________________

hcs_$set_cpu_timer hcs_$set_damaged_sw
__________________ ___________________

event_channel_nane
is the name of the event channel over which the IPC wakeup is
to be sent. If its value is 0, then an IPS cput signal is
sent in lieu of a wakeup. (Input)

ACCESS REQUIRED

There are no access requirements for this gate entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_dddaaammmaaagggeeeddd_ssswww

This entry point allows the damaged switch associated with the
specified entry (segment or directory) to be changed in the
volume table of contents (VTOC), if it is mounted. The damaged
switch indicates a segment has been damaged by a device error or
system crash, it has no meaning for a directory.

USAGE

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

call hcs_$set_damaged_sw (dir_name, entryname, damaged_sw, code);

ARGUMENTS

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

entryname
is the entryname of the segment or directory. (Input)

damaged_sw
is the new value of the damaged switch. (Input)

1 any attempt to reference this segment will result in a
segment fault with error code error_table_$segbusted
0 the segment is usable

code
is a storage system status code. (Output) It can have the
value:

error_table_$bad_ring_brackets
attempting to change the damaged switch when the ring
brackets are less than the validation level of the user.

___________________ _______________________

hcs_$set_damaged_sw hcs_$set_damaged_sw_seg
___________________ _______________________

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory or write permission on the entry. Also, the user's
validation level must be within the first ring bracket of the
entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_dddaaammmaaagggeeeddd_ssswww_ssseeeggg

This entry point, given a pointer to a segment, allows the
damaged switch associated with the specified segment to be
changed in the volume table of contents (VTOC), if it is mounted.
The damaged switch indicates a segment has been damaged by a
device error or system crash.

USAGE

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

call hcs_$set_damaged_sw_seg (seg_ptr, damaged_sw, code);

ARGUMENTS

seg_ptr
is the pointer to the segment. (Input)

damaged_sw
is the new value of the damaged switch. (Input)

1 any attempt to reference this segment will result in a
segment fault with error code error_table_$segbusted
0 the segment is usable

code
is a storage system status code. (Output) It can have the
value:

error_table_$bad_ring_brackets
attempting to change the damaged switch when the ring
brackets are less than the validation level of the user.

_______________________ _____________________________

hcs_$set_damaged_sw_seg hcs_$set_hex_exponent_control
_______________________ _____________________________

ACCESS REQUIRED

The user must have status and modify permission on the containing
directory or write permission on the segment. Also, the user's
validation level must be within the first ring bracket of the
segment.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_hhheeexxx_eeexxxpppooonnneeennnttt_cccooonnntttrrrooolll

specifies the bahavior of the process on floating underflow or
overflow in hex mode.

USAGE

declare hcs_$set_hex_exponent_control entry (bit(1) aligned,
bit(1) aligned, bit(72) aligned, fixed bin(35));

call hcs_$set_hex_exponent_control (restart_underflow,
restart_overflow, max_value, code);

ARGUMENTS

restart_underflow
is a flag. If "1"b, then floating underflow faults will be
automatically restarted with a result value of zero. (Input)

restart_overflow
is a flag. If "1"b, then floating overflow faults in hex mode
will be restarted with a result value of max_value. (Input)

max_value
is the value to be used as the result when a floating overflow
is restarted in hex mode. (Input)

code
is a standard system status code. It will be nonzero if the
caller validation level is greater than the process' initial
ring. (Output)

ACCESS REQUIRED

None.

______________________ ______________________

hcs_$set_hexfp_control hcs_$set_hexfp_control
______________________ ______________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_hhheeexxxfffppp_cccooonnntttrrrooolll

This program controls the access to hex floating point mechanism
of the 8/70 processors via the access control segment
>sc1>admin_acs>Fortran_hfp.acs. If the user has sufficient
access (see notes), pds_$hfp_exponent_enabled may be set or reset
by using this program.

USAGE

declare hcs_$set_hexfp_control entry (bit(2) aligned, bit(2)
aligned, fixed bin(35));

call hcs_$set_hexfp_control (new_hfp_sw, old_hfp_sw, code);

ARGUMENTS

new_hfp_sw
is the desired state of the hfp switch. (Output) Must be "1"b
to enable use of hex floating point and "0"b to disable it.

old_hfp_sw
is the current state of the hfp switch. (Output)

code
is a standard system status code. (Output) The value will be
either 0 or et_$action_not_performed.

ACCESS REQUIRED

The user must have access to set_proc_required command to select
an 8/70M processor, or depend on luck to be dealt one -- since we
do not support hybrid systems, this really is not a problem.
Site approval of use of hex floating point is also required,
i.e., sys_info$hfp_exponent_available must be set to "1"b. If
the acs segment >sc1>admin_acs>Fortran_hfp.acs exists, RW access
to it is required; otherwise, no other restrictions apply.

______________________ __________________________

hcs_$set_hexfp_control hcs_$set_page_trace_signal
______________________ __________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_pppaaagggeee_tttrrraaaccceee_sssiiigggnnnaaalll

Sets the parameters that control the signalling of the pgt_ IPS
signal (and corresponding condition).

USAGE

declare hcs_$set_page_trace_signal entry (bit(1) aligned, fixed
bin, bit(1) aligned, bit(1) aligned, fixed bin, fixed
bin(35));

call hcs_$set_page_trace_signal (new_signal_sw, new_threshold,
values_changed, old_signal_sw, old_threshold, code);

ARGUMENTS

new_signal_sw
is a flag. if it is "1"b, then the pgt_ condition will be
signalled whenever the trace buffer reaches the specified
percentage of fullness. (Input)

new_threshold
is a percent between 0 and 100. When the new_signal_sw is
"1"b, this determines the point at which a pgt_ condition is
signalled. When the per-process buffer of events reaches this
percentage of full, the condition is signalled. (Input)

values_changed
is a flag. it is set to "1"b on output if the new_signal_sw
and the new_threshold changed the existing parameters in
place. (Output)

old_signal_sw
is the old value of the signal_sw. (Output)

old_threshold
is the old value of the threshold. (Output)

code
is a standard system status code. (Output)

ACCESS REQUIRED

None.

__________________________ __________________

hcs_$set_page_trace_signal hcs_$set_stack_ptr
__________________________ __________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_ppplll111_mmmaaaccchhhiiinnneee_mmmooodddeee

This entrypoint changes the manner in which the user's process
handles stringsize conditions.

USAGE

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

call hcs_$set_pl1_machine_mode (new_mode, old_mode);

ARGUMENTS

new_mode
is the value to set for the mode. Non-zero means that the
machine conditions should be made restartable, zero means that
the machine conditions are to be unmodified when the condition
is signalled. (Input)

old_mode
is the value of the mode before changing, for those
applications who wish to restore the process state. (Input)

ACCESS REQUIRED

None. This entry simply changes the behavior of the user's
process.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_ssstttaaaccckkk_ppptttrrr

specifies the stack to be used for the current validation level.
Until reset, the supervisor will perform all signalling and user
ring stack manipulation in the specified segment. The new stack
must have been properly initialized or the process will fail very
soon. No checks are made with the pointer given, but if there is
not effective REW access the process will die. This routine is
called by cpm_.

USAGE

declare hcs_$set_stack_ptr entry (ptr);

call hcs_$set_stack_ptr (stk_ptr);

__________________ ________________________

hcs_$set_stack_ptr hcs_$set_synchronized_sw
__________________ ________________________

ARGUMENTS

stk_ptr
points to the location to begin a new stack. (Input)

ACCESS REQUIRED

None.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_sssyyynnnccchhhrrrooonnniiizzzeeeddd_ssswww

sets the synchronized switch for a segment. This is allowed only
for segments whose write bracket is less than or equal to the
data management ring number. Modify permission is required on
the directory containing the segment.

USAGE

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

call hcs_$set_synchronized_sw (dir_name, entryname, switch,
code);

ARGUMENTS

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

entryname
is the entryname of the segment. (Input)

switch
is the value to be set for the synchronized switch. (Input)

code
is a storage system status code. (Output)

______________ _____________________________

hcs_$set_timer hcs_$set_volume_dump_switches
______________ _____________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_tttiiimmmeeerrr

Sets the per-process cpu timer. An IPC wakeup or an IPS signal
will be sent to the process when the specified amount of CPU time
has passed.

USAGE

declare hcs_$set_timer entry (fixed bin (71), fixed bin (71));

call hcs_$set_timer (cpu_time, event_channel_name);

ARGUMENTS

cpu_time
is the absolute number of CPU microseconds which may pass
before an IPC wakeup or IPS signal is to be sent to the
process. (Input)

event_channel_name
is the name of the event channel over which the IPC wakeup is
to be sent. If its value is 0, then an IPS cput signal is
sent in lieu of a wakeup. (Input)

ACCESS REQUIRED

There are no access requirements for this gate entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssseeettt_vvvooollluuummmeee_ddduuummmppp_ssswwwiiitttccchhheeesss

modifies the incremental and complete volume dump switches for a
segment. Modify permission is required on the directory
containing the segment.

USAGE

declare hcs_$set_volume_dump_switches entry (char(*), char(*),
fixed bin, fixed bin, fixed bin(35));

call hcs_$set_volume_dump_switches (dir_name, entryname,
incremental_sw, complete_sw, code);

ARGUMENTS

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

_____________________________ ______________________

hcs_$set_volume_dump_switches hcs_$status_for_backup
_____________________________ ______________________

entryname
is the entryname of the segment. (Input)

incremental_sw
specifies how the incremental volume dump switch is to be
modified. A positive value for incremental_sw sets the switch
(thereby preventing the incremental volume dumper from dumping
this segment). A negative value for incremental_sw resets it
(thereby allowing the dumping of this segment). A zero value
for incremental_sw leaves the switch as is.

complete_sw
specifies how the complete volume dump switch is to be
modified. A positive value for complete_sw sets the switch
(thereby preventing the complete volume dumper from dumping
this segment). A negative value for complete_sw resets it
(thereby allowing the dumping of this segment). A zero value
for complete_sw leaves the switch as is.

code
is a storage system status code. (Output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssstttaaatttuuusss_fffooorrr_bbbaaaccckkkuuuppp

Returns a large amount of information for an entry. Status
permission on the directory or nonnull access on the entry is
required to use this entry point.

USAGE

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

call hcs_$status_for_backup (dir_name, entryname, info_ptr,
code);

ARGUMENTS

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

entryname
is the entryname of the segment or directory. (Input)

______________________ _________________

hcs_$status_for_backup hcs_$trace_marker
______________________ _________________

info_ptr
is a pointer to a structure described by
status_for_backup.incl.pl1. (Input)

code
is a storage system status code. (Output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ssstttoooppp_ppprrroooccceeessssss

This entry causes the calling process to be placed in the
"stopped" state. The system will no longer schedule the calling
process.

USAGE

declare hcs_$stop_process entry (bit(36) aligned);

call hcs_$stop_process (process_id);

ARGUMENTS

process_id
is the process id of the calling process. It is supplied only
as a means of verifying that the calling process really
desires to be stopped. (Input)

ACCESS REQUIRED

There are no access requirements for this gate entry.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$tttrrraaaccceee_mmmaaarrrkkkeeerrr

Adds a marker to the per-process trace of hardcore events. This
allows a process calling hcs_$get_page_trace to mark the trace at
the beginning of some set of operations, perform the operations,
and then read out the trace. The trace elements that were caused
by the operation can then be determined by searching for the
marker.

USAGE

declare hcs_$trace_marker entry (char (4));

_________________ _______________________

hcs_$trace_marker hcs_$try_to_unlock_lock
_________________ _______________________

call hcs_$trace_marker (mark);

ARGUMENTS

mark
is a 4 character marker to identify a place in the trace.

ACCESS REQUIRED

None

________________________________________

NNNaaammmeee::: hhhcccsss_$$$tttrrryyy_tttooo_uuunnnllloooccckkk_llloooccckkk

Allows non-hardcore programs to unlock a lock if it was
originally locked by a process which no longer exists. If the
process associated with the lock id in the lock no longer exists,
then the lock is set to the lock id of the calling process.

USAGE

declare hcs_$try_to_unlock_lock entry (ptr, fixed bin);

call hcs_$try_to_unlock_lock (lock_ptr, code);

ARGUMENTS

lock_ptr
is a pointer to a standard lock word. (Input) The value
pointed to by this pointer is assumed to be either a lock id
or 0.

code
is an status code. (Output) It is a non-standard status code
which takes on the following values:

1 - the lock is locked by a currently valid process.
2 - the lock was not locked.
3 - the lock id was bad is now set to the caller's lock id.

ACCESS REQUIRED

The caller must have write effective access to the segment
pointed to by the supplied pointer. If the ring mechanism
prevents writing to the segment, the not_in_write_bracket
condition will be signalled. If discretionary or mandatory
access control prevent writing to the segment, the
no_write_permission condition will be signalled.

______________ ______________

hcs_$tty_abort hcs_$tty_abort
______________ ______________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_aaabbbooorrrttt

This entrypoint implements "resetread" and "resetwrite", i.e.,
discarding pending input and/or output.

USAGE

declare hcs_$tty_abort entry (fixed bin, fixed bin (2), fixed
bin, fixed bin (35));

call hcs_$tty_abort (device_index, resetsw, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

resetsw
Specifies whether to reset input, output, or both. The value
is constructed as follows: a value of 2 indicates resetwrite,
and a value of 1 is resetread. A value of 3 is both.

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

_______________ _______________

hcs_$tty_attach hcs_$tty_attach
_______________ _______________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_aaattttttaaaccchhh

Attaches a communications channel to the calling process, given
the channel name. The channel must have been previously assigned
to the process via dial_manager_, unless the calling process is
the initializer.

USAGE

declare hcs_$tty_attach entry (char(*), fixed bin(71), fixed bin,
fixed bin, fixed bin(35));

call hcs_$tty_attach (channel_name, event_channel, device_index,
state, code);

ARGUMENTS

channel_name
Is the name of the communications channel to be attached.

event_channel
is an IPC event channel over which the system will send a
wakeup when input arrives or when output space is available.
In the initializer process, wakeups are also sent when the
channel dials up or hangs up. Note that input and output
wakeups are only sent if the process' most recent read or
write (respectively) failed due to lack or input or space.
(input)

device_index
Is the device index identifying the channel to the system.
This can be passed to the other hcs_$tty_* entrypoints.
(output)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

_______________ _______________

hcs_$tty_attach hcs_$tty_detach
_______________ _______________

NOTES

Note that hcs_$tty_attach, unlike hcs_$tty_index, will return an
error if it is called twice for the same channel.

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_dddeeetttaaaccchhh

Detaches a communications channel from the calling process. The
channel remains assigned for re-attachment.

USAGE

declare hcs_$tty_detach entry (fixed bin, fixed bin, fixed bin,
fixed bin(35));

call hcs_$tty_detach (device_index, detach_flag, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

detach_flag
This flag is only respected if the calling process is the
initializer. If it is set to 1, then the channel is hung up
and must be listened to again (with a "listen" control order)
before it may be used. If the flag is zero then the channel
remains in the same state. This flag is primarily of
historical interest, dating to the time when non-initializer
processes could serve as the hardcore owner (hproc) for
communications channels. Setting the flag to 1 allowed a new
process to become the channel owner. (input)

_______________ ________________________

hcs_$tty_detach hcs_$tty_detach_new_proc
_______________ ________________________

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_dddeeetttaaaccchhh_nnneeewww_ppprrroooccc

This entrypoint detaches a communications channel from the
calling process. If the calling process is the initializer, then
the channel becomes available for attachment by a specified user
process.

USAGE

declare hcs_$tty_detach_new_proc entry (fixed bin, bit(36), fixed
bin, fixed bin(35));

call hcs_$tty_detach_new_proc (device_index, user_process_id,
state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

user_process_id
is the process id of the user process which is being given the
right to use this channel. This process may now attach the
channel via hcs_$tty_attach or hcs_$tty_index. This argument
is ignored if the caller is not the initializer.

________________________ ______________

hcs_$tty_detach_new_proc hcs_$tty_event
________________________ ______________

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_eeevvveeennnttt

This entrypoint supplies a new event channel for an attached
communications channel.

USAGE

declare hcs_$tty_event entry (fixed bin, fixed bin(71), fixed
bin, fixed bin(35));

call hcs_$tty_event (device_index, event_channel, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

______________ _________________

hcs_$tty_event hcs_$tty_get_line
______________ _________________

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_gggeeettt_llliiinnneee

This entrypoint reads data from a communications channel. If
there is a line mark available in the data stream, then it will
return no data past the line mark.

USAGE

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

call hcs_$tty_get_line (device_index, buffer_word_ptr,
buffer_char_offset, buffer_length, n_trans, nl_found, state,
code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

buffer_char_offset
is the character index (0, 1, 2, or 3) of the first character
of the buffer within the first word of the buffer. (input)

buffer_length
is the length of the data buffer in characters. (input)

n_trans
is the number of characters transferred by this call.
(output)

_________________ _________________

hcs_$tty_get_line hcs_$tty_get_name
_________________ _________________

nl_found
will be "1"b if the last character is a new line character
(linemark), and "0"b if no new line character was available
within buffer_length characters. (input)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_gggeeettt_nnnaaammmeee

This entrypoint returns the name of a communications channel
given the device_index.

USAGE

declare hcs_$tty_get_name entry (fixed bin, char(*), fixed bin,
fixed bin(35));

call hcs_$tty_get_name (device_index, channel_name, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

channel_name
is the name of the communications channel. (output)

state
is the state of the communications channel. The possible
values returned are declared in the include file
tty_states.incl.pl1. The only value that can be returned to

_________________ ______________

hcs_$tty_get_name hcs_$tty_index
_________________ ______________

processes other than the initializer is TTY_STATE_DIALED_UP.
If the channel is in any other state, the status code will be
error_table_$io_no_permission and the state will be undefined.
In the initializer process, any of the states declared in the
initializer may be returned. (output)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_iiinnndddeeexxx

This entrypoint attaches a communications channel to the calling
process. If the channel is already attached, it returns the
device index.

USAGE

declare hcs_$tty_index entry (char(*), fixed bin, fixed bin,
fixed bin(35));

call hcs_$tty_index (channel_name, device_index, state, code);

ARGUMENTS

channel_name
is the name of the channel to be attached. (input)

device_index
is the device index identifying the channel to the system.
(output)

______________ ______________

hcs_$tty_index hcs_$tty_order
______________ ______________

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_ooorrrdddeeerrr

This entrypoint performs a control order on a communications
channel. The specific order is selected by character string
name.

USAGE

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

call hcs_$tty_order (device_index, order_name, order_info_ptr,
state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

order_name
is the name of the control order to be performed. There are
many different control orders, some of which are only
permitted to the initializer process. (see the doc now in the
tty_ doc). (input)

order_info_ptr
is a pointer to the info structure associated with the control
order, if any. (input)

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

CONTROL OPERATION

The following orders are supported when the I/O switch is open.
Except as noted, the info_ptr should be null. The orders are
divided into categories. Local orders perform a specific
function one time only, global orders change the way the system
interfaces with the terminal, and other orders fit in neither
category. Control orders are performed through the iox_$control
entry.

LIST OF LOCAL ORDERS

interrupt
sends an out-of-band interrupt signal (quit signal) to the
terminal.

listen
sends a wakeup to the process once the line associated with
this device identifier is dialed up.

printer_off
causes the printer mechanism of the terminal to be temporarily
disabled if it is physically possible for the terminal to do
so; if it is not, the status code
error_table_$action_not_performed is returned (see "Notes"
below).

printer_on
causes the printer mechanism of the terminal to be re-enabled
(see "Notes" below).

start_xmit_hd
causes the channel to remain in a transmitting state at the
completion of the next block of output, rather than starting
to accept input. The line then remains in a transmitting
state until the stop_xmit_hd control operation is issued.
This operation is valid only for terminals with line type
LINE_ARDS.

stop_xmit_hd
causes the channel to resume accepting input from the terminal
(after the completion of current output, if any). This
operation is only valid for ARDS-like terminals and is used
only to counteract a preceding start_xmit_hd operation.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

wru
initiates the transmission of the answerback of the device, if
it is so equipped. This operation is allowed only for the
process that originally attached the device (generally the
initializer process). The answerback can subsequently be read
by means of the get_chars input/output operation.

LIST OF GLOBAL CONTROL ORDERS

accept_printer_off
causes subsequent printer_off and printer_on orders to be
accepted if possible.

get_delay
is used to find out what delay values are currently in effect.
The info_ptr points to the structure described for set_delay
(below), which is filled in as a result of the call (except
for the version number, which must be supplied by the caller).

get_editing_chars
is used to find out what input editing characters are in
effect. The info_ptr points to the structure described below
for set_editing_chars, which is filled in as a result of the
call (except for the version number, which must be supplied by
the caller).

get_framing_chars
causes the framing characters currently in use to be returned
(see the set_framing_chars order below). If no framing
characters have been supplied, NUL characters are returned.
The info_ptr must point to a structure like the one described
for the set_framing_chars order; this structure is filled in
as a result of the call.

get_ifc_info
causes the characters currently in use for input flow control
to be returned (see the input_flow_control_chars order below).
The info_ptr must point to a structure like the one described
for the input_flow_control_chars order, which is filled in as
a result of the call. If no characters are currently set, the
count fields are set to 0.

get_input_translation
get_output_translation
get_input_conversion
get_output_conversion
these orders are used to obtain the current contents of the
specified table. The info_ptr points to a structure like the
one described for the corresponding "set" order below, which
is filled in as a result of the call (except for the version

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

number, which must be supplied by the caller). If the
specified table does not exist (no translation or conversion
is required), the status code error_table_$no_table is
returned.

get_ofc_info
causes the characters and protocol currently in use for output
flow control to be returned (see the output_flow_control_chars
order below). The info_ptr must point to a structure like the
one described for the output_flow_control_chars order, which
is filled in as a result of the call. If no output flow
control protocol is currently in use, the count fields are set
to 0, and both suspend_resume and block_acknowledge are set to
"0"b.

get_special
is used to obtain the contents of the special_chars table
currently in use. The info_ptr points to the following
structure (defined in tty_convert.incl.pl1):

dcl 1 get_special_info_struc aligned,
2 area_ptr ptr,
2 table_ptr ptr;

where:

area_ptr
points to an area in which a copy of the current
special_chars table is returned. (Input)

table_ptr
is set to the address of the returned copy of the table.
(Output)

input_flow_control_chars
specifies the character(s) to be used for input flow control
for terminals with line speed input capability. The terminal
must be in iflow mode for the feature to take effect. The
info_ptr must point to the following structure (declared in
flow_control_info.incl.pl1):

dcl 1 input_flow_control_info aligned,
2 suspend_seq unaligned,
3 count fixed bin(9) unsigned,
3 chars char(3),
2 resume_seq unaligned,
3 count fixed bin(9) unsigned,
3 chars char(3),
2 timeout bit(1);

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

where:

suspend_seq
is the character sequence that the system sends to tell the
terminal to stop sending input, or that the terminal sends
to inform the host that it is suspending input. count is
an integer from 0 to 3 that specifies the number of
characters in the sequence. chars are the characters
themselves. At present, only sequences of length 0 or 1
are supported.

resume_seq
is the character sequence to be sent by the system to the
terminal to tell it to resume transmission of input. count
is an integer from 0 to 3 that specifies the number of
characters in the sequence. chars are the characters
themselves.

timeout
is "1"b if the resume character is to be sent to the
terminal after input has ceased for one second, whether or
not a suspend character has been received.

output_flow_control_chars
enables either of two output flow control protocols and
specifies the characters to be used for output flow control.
The terminal must be in oflow mode for the feature to take
effect. The info_ptr must point to the following structure
(declared in flow_control_info.incl.pl1):

dcl 1 output_flow_control_info aligned,
2 flags unaligned,
3 suspend_resume bit(1),
3 block_acknowledge bit(1),
3 mbz bit(16),
2 buffer_size fixed bin(18) unsigned unaligned,
2 suspend_or_etb_seq unaligned,
3 count fixed bin(9) unsigned,
3 chars char(3),
2 resume_or_ack_seq unaligned,
3 count fixed bin(9) unsigned,
3 chars char(3);

where:

suspend_resume
is "1"b to specify a suspend/resume protocol.

block_acknowledge
is "1"b to specify a block acknowledgement protocol.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

buffer_size
is the number of characters in the terminal's buffer if
block_acknowledge is "1"b; otherwise, it is ignored.

suspend_or_etb_seq
is the character sequence sent by the terminal to tell the
system to suspend output if suspend_resume is "1"b, or the
end_of_block character sequence if block_acknowledge is
"1"b. count is an integer from 0 to 3 that specifies the
number of characters in the sequence. chars are the
characters themselves.

resume_or_ack_seq
is the character sequence sent by the terminal to indicate
that output can be resumed if suspend_resume is "1"b, or
the character sequence sent by the terminal to acknowledge
completion of a block if block_acknowledge is "1"b. count
is an integer from 0 to 3 that specifies the number of
characters in the sequence. chars are the characters
themselves.

refuse_printer_off
causes subsequent printer_off and printer_on orders to be
rejected, except when in echoplex mode.

set_delay
sets the number of delay characters associated with the output
of carriage-motion characters. The info_ptr points to the
following structure (defined in tty_convert.incl.pl1):

dcl 1 delay_struc based aligned,
2 version fixed bin,
2 default fixed bin,
2 delay,
3 vert_nl fixed bin,
3 horz_nl float bin,
3 const_tab fixed bin,
3 var_tab float bin,
3 backspace fixed bin,
3 vt_ff fixed bin;

where:

version
is the version number of the structure. It must be 1.

default
indicates, if nonzero, that the default values for the
current terminal type and baud rate are to be used and that
the remainder of the structure is to be ignored.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

vert_nl
is the number of delay characters to be output for all
newlines to allow for the linefeed
(-127 <= vert_nl <= 127). If it is negative, its absolute
value is the minimum number of characters that must be
transmitted between two linefeeds (for a device such as a
TermiNet 1200).

horz_nl
is a number to be multiplied by the column position to
obtain the number of delays to be added for the carriage
return portion of a newline (0 <= horz_nl <= 1). The
formula for calculating the number of delay characters to
be output following a newline is:

ndelays = vert_nl + fixed (horz_nl*column)

const_tab
is the constant portion of the number of delays associated
with any horizontal tab character (0 <= const_tab <= 127).

var_tab
is the number of additional delays associated with a
horizontal tab for each column traversed
(0 <= var_tab <= 1). The formula for calculating the
number of delays to be output following a horizontal tab
is:

ndelays = const_tab + fixed (var_tab*n_columns)

backspace
is the number of delays to be output following a backspace
character (-127 <= backspace <= 127). If it is negative,
its absolute value is the number of delays to be output
with the first backspace of a series only (or a single
backspace). This is for terminals such as the TermiNet 300
that need delays to allow for hammer recovery in case of
overstrikes, but do not require delays for the carriage
motion associated with the backspace itself.

vt_ff
is the number of delays to be output following a vertical
tab or formfeed (0 <=vt_ff <= 511).

set_editing_chars
changes the characters used for editing input. The info_ptr
points to the following structure (declared in
tty_editing_chars.incl.pl1):

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

dcl 1 editing_chars aligned,
2 version fixed bin,
2 erase char(1) unaligned,
2 kill char(1) unaligned;

where:

version
is the version number of this structure. It must be 2.

erase
is the erase character.

kill
is the kill character.

The following rules apply to editing characters:

1. The two editing characters cannot be the same.

2. No carriage-movement character (carriage return, newline,
horizontal tab, backspace, vertical tab, or formfeed) can
be used for either of the editing functions.

3. NUL and space cannot be used for either editing function.

4. If the editing character is an ASCII control character, it
will not have the desired effect unless ctl_char mode is on
(see "Modes Operation" below).

set_framing_chars
specifies the pair of characters that the terminal generates
surrounding input transmitted as a block or "frame." These
characters must be specified in the character code used by the
terminal. This order must be used for blk_xfer mode (see
below) to be effective. The info_ptr must point to a
structure with the following format:

dcl 1 framing_chars aligned,
2 frame_begin char(1) unaligned,
2 frame_end char(1) unaligned;

set_input_conversion
provides a table to be used in converting input to identify
escape sequences and certain special characters. The info_ptr
points to a structure of the following form (defined in
tty_convert.incl.pl1):

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

dcl 1 cv_trans_struc aligned,
2 version fixed bin,
2 default fixed bin,
2 cv_trans aligned,
3 value (0 : 255) fixed bin(8) unaligned;

where:

version
is the version number of the structure. It must be 1.

default
indicates, if nonzero, that the default table for the
current terminal type is to be used, and the remainder of
the structure is ignored.

values
are the elements of the table. This table is indexed by
the value of a typed input character, and the corresponding
entry contains the ASCII character resulting from the
translation. If the info_ptr is null, no translation is to
be done.

NOTE: In the case of a terminal that inputs 6-bit
characters and case-shift characters, the first 64
characters of the table correspond to characters in
lower shift, and the next 64 correspond to characters in
upper shift.

The table is indexed by the ASCII value of each input
character (after translation, if any), and the corresponding
entry contains one of the following values (mnemonic names for
these values are defined in tty_convert.incl.pl1):

0 ordinary character
1 break character
2 escape character
3 character to be thrown away
4 formfeed character (to be thrown away if page length is nonzero)
5 this character and immediately following character to be thrown
away

set_input_translation
provides a table to be used for translation of terminal input
to ASCII. The info_ptr points to a structure of the following
form (declared in tty_convert.incl.pl1):

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

dcl 1 cv_trans_struc aligned,
2 version fixed bin,
2 default fixed bin,
2 cv_trans aligned,
3 value (0 : 255) char(1) unaligned;

where version, default, and value are as described in the
cv_trans_struc structure used with the set_input_conversion
order above.

set_line_type
sets the line type associated with the terminal to the value
supplied. The info_ptr should point to a fixed binary
variable containing the new line type. Line types can be any
of the following named constants defined in the include file
line_types.incl.pl1:

LINE_ASCII
device similar to 7-bit ASCII using Bell 103-type modem
protocol.

LINE_1050
device similar to IBM Model 1050.

LINE_2741
device similar to IBM Model 2741, with or without auto EOT
inhibit.

LINE_ARDS
device similar to Adage, Inc. Advanced Remote Display
Station (ARDS) protocol using Bell 202C6-type modem.

LINE_SYNC
synchronous connections, no protocol.

LINE_G115
ASCII synchronous connection, Model G-115 remote computer
protocol.

LINE_BSC
binary synchronous protocol.

LINE_ETX
device similar to TermiNet 1200 protocol using Bell
202C5-type modem.

LINE_VIP
device similar to Honeywell Model 7700 Visual Information
Projection (VIP) stand-alone terminal.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

LINE_ASYNC1
LINE_ASYNC2
LINE_ASYNC3
site-supplied asynchronous protocols.

LINE_SYNC1
LINE_SYNC2
LINE_SYNC3
site-supplied synchronous protocols.

LINE_POLLED_VIP
device similar to Honeywell Model 7700 Visual Projection
System (VIP) polled terminal concentrator subsystem.

LINE_X25LAP
X.25 network connection using the link access protocol
(LAP).

LINE_COLTS
special software channel used for Communications Online
Test and Diagnostics System.

This operation is not permitted while the terminal is in use.

set_output_conversion
provides a table to be used in formatting output to identify
certain kinds of special characters. The info_ptr points to a
structure like that described for set_input_conversion
(above). The table is indexed by each ASCII output character
(before translation, if any), and the corresponding entry
contains one of the following values (mnemonic names for these
values are defined in tty_convert.incl.pl1):

0 ordinary character.
1 newline.
2 carriage return.
3 horizontal tab.
4 backspace.
5 vertical tab.
6 formfeed.
7 character requiring octal escape.
8 red ribbon shift.
9 black ribbon shift.
10 character does not change the column position.
11 this character together with the following one do not change
the column position (used for hardware escape sequences).
12 character is not to be sent to the terminal.
17 or greater a character requiring a special escape sequence.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

The indicator value is the index into the escape table of
the sequence to be used, plus 16. The escape table is
part of the special characters table; see the set_special
order below.

set_output_translation
provides a table to be used for translating ASCII characters
to the code to be sent to the terminal. The info_ptr points
to a structure like that described for set_input_translation.
The table is indexed by the value of each ASCII character, and
the corresponding entry contains the character to be output.
If the info_ptr is null, no translation is to be done.

NOTE: For a terminal that expects 6-bit characters and
case-shift characters, the 400(8) bit must be turned on
in each entry in the table for a character that requires
upper shift, and the 200(8) bit must be on in each entry
for a character that requires lower shift.

set_special
provides a table that specifies sequences to be substituted
for certain output characters, and characters that are to be
interpreted as parts of escape sequences on input. Output
sequences are of the following form (defined in
tty_convert.incl.pl1):

dcl 1 c_chars based aligned,
2 count fixed bin(8) unaligned,
2 chars(3) char(1) unaligned;

where:

count
is the actual length of the sequence in characters
(0 <= count <= 3). If count is zero, there is no sequence.

chars
are the characters that make up the sequence.
The info_ptr points to a structure of the following form
(defined in tty_convert_incl.pl1):

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

dcl 1 special_chars_struc aligned based,
2 version fixed bin,
2 default fixed bin,
2 special_chars
3 nl_seq aligned like c_chars,
3 cr_seq aligned like c_chars,
3 bs_seq aligned like c_chars,
3 tab_seq aligned like c_chars,
3 vt_seq aligned like c_chars,
3 ff_seq aligned like c_chars,
3 printer_on aligned like c_chars,
3 printer_off aligned like c_chars,
3 red_ribbon_shift aligned like c_chars,
3 black_ribbon_shift aligned like c_chars,
3 end_of_page aligned like c_chars,
3 escape_length fixed bin,
3 not_edited_escapes (sc_escape_len refer
(special_chars.escape_length))
like c_chars,
3 edited_escapes (sc_escape_len refer
(special_chars.escape_length))
like c_chars,
3 input_escapes aligned,
4 len fixed bin(8) unaligned,
4 str char (sc_input_escape_len refer
(special_chars.input_escapes.len))
unaligned,
3 input_results aligned,
4 pad bit(9) unaligned,
4 str char (sc_input_escape_len refer
(special_chars.input_escapes.len))
unaligned;

where:

version
is the version number of this structure. It must be 1.

default
indicates, if nonzero, that the default values for the
current terminal type and baud rate are to be used and that
the remainder of the structure is to be ignored.

nl_seq
is the output character sequence to be substituted for a
newline character. The nl_seq.count generally should be
nonzero.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

cr_seq
is the output character sequence to be substituted for a
carriage-return character. If count is zero, the
appropriate number of backspaces is substituted. However,
either cr_seq.count or bs_seq.count should be nonzero
(i.e., both should not be zero).

bs_seq
is the output character sequence to be substituted for a
backspace character. If count is zero, a carriage return
and the appropriate number of spaces are substituted.
However, either bs_seq.count or cr_seq.count, should be
nonzero (i.e., both should not be zero).

tab_seq
is the output character sequence to be substituted for a
horizontal tab. If count is zero, the appropriate number
of spaces is substituted.

vt_seq
is the output character sequence to be substituted for a
vertical tab. If count is zero, no characters are
substituted.

ff_seq
is the output character sequence to be substituted for a
formfeed. If count is zero, no characters are substituted.

printer_on
is the character sequence to be used to implement the
printer_on control operation. If count is zero, the
function is not performed.

printer_off
is the character sequence to be used to implement the
printer_off control operation. If count is zero, the
function is not performed.

red_ribbon_shift
is the character sequence to be substituted for a
red-ribbon-shift character. If count is zero, no
characters are substituted.

black_ribbon_shift
is the character sequence to be substituted for a
black-ribbon-shift character. If count is zero, no
characters are substituted.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

end_of_page
is the character sequence to be printed to indicate that a
page of output is full. If count is zero, no additional
characters are printed, and the cursor is left at the end
of the last line.

escape_length
is the number of output escape sequences in each of the two
escape arrays.

not_edited_escapes
is an array of escape sequences to be substituted for
particular characters if the terminal is in "^edited" mode.
This array is indexed according to the indicator found in
the corresponding output conversion table (see the
description of the set_output_conversion order above).

edited_escapes
is an array of escape sequences to be used in edited mode.
It is indexed in the same fashion as not_edited_escapes.

input_escapes
is a string of characters each of which forms an escape
sequence when preceded by an escape character.

input_results
is a string of characters each of which is to replace the
escape sequence consisting of an escape character and the
character occupying the corresponding position in
input_escapes.

set_wakeup_table
specifies a wakeup table, i.e., a set of wakeup characters
that controls the dispatching of input wakeups. The wakeup
table operates in conjunction with wake_tbl mode. The wakeup
table has no effect until wake_tbl mode is enabled. Once
enabled, the standard method of generating input wakeups
(normally one wakeup for each line) is suspended. Thereafter,
wakeups are only generated when wakeup characters are received
or when the buffer gets too full. The wakeup table cannot be
changed while wake_tbl mode is enabled. The info_ptr should
point to the following structure (declared in
set_wakeup_table_info.incl.pl1):

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

dcl swt_infop ptr;
dcl swt_info_version_1 fixed bin static options (constant) init (1);

dcl 1 swt_info aligned based (swt_infop),
2 version fixed bin,
2 new_table like wakeup_table,
2 old_table like wakeup_table;

dcl wakeup_tablep ptr;

dcl 1 wakeup_table aligned based (wakeup_tablep),
2 wake_map (0:127) bit (1) unal,
2 mbz bit (16) unal;

where:

version
is the version number of this structure. (Input). It must
be 1.

new_table
is the wakeup table to set. (Input)

old_table
is set to the value of the current wakeup table that is
being replaced. (Output). If no current wakeup table
exists, all entries are set to "0"b.

wake_map
is an array having one entry for each character in the
ASCII character set. (Input). A value of "1"b defines a
wakeup character. All other entries must be "0"b. If all
entries are "0"b, the current wakeup table, if any, is
deleted.

mbz
must be "0"b. (Input)

The primary application for the wakeup table mechanism is to
reduce overhead incurred by text editors, such as qedx, while
in input mode. While in input mode, a user process must wake
up for each line of input even though no processing is
immediately required. In wake_tbl mode, a process is only
awakened when input mode is exited or a large amount of input
has been accumulated. However, since wake_tbl mode causes
more input to be buffered in ring 0 than before, a quit signal
is likely to discard more input than before. If a user does
not wish to lose input, he simply should avoid quitting while
in input mode.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

If a user does quit out of input mode, he does not remain in
wake_tbl mode (under normal circumstances). The default modes
established by the standard quit handler include ^wake_tbl. A
start command restores wake_tbl mode.

LIST OF MISCELLANEOUS CONTROL ORDERS

copy_meters
causes the current cumulative meters associated with the
channel to be copied to unwired storage, so that the
statistics for the channel can be determined both for the life
of the system and for the current dialup. This order can only
be issued by the "owning" process (normally the initializer).
The info_ptr should be null.

quit_disable
causes quit signal processing to be disabled for this device.

quit_enable
causes quit signal processing to be enabled for this device.
(Quit signal processing is initially disabled.)

read_status
tells whether or not there is any type-ahead input waiting for
a process to read. The info_ptr should point to the following
structure (defined in tty_read_status_info.incl.pl1), which is
filled in by the call:

dcl 1 tty_read_status_info aligned based,
2 event_channel fixed bin (71),
2 input_available bit (1);

where:

event_channel
is the event channel used to signal the arrival of input.

input_available
indicates whether input is available.
"0"b no input
"1"b input

start
causes a wakeup to be signalled on the event channel
associated with this device. This request is used to restart
processing on a device whose wakeups may have been lost or
discarded.

______________ ______________

hcs_$tty_order hcs_$tty_order
______________ ______________

store_id
stores the answerback identifier of the terminal for later use
by the process. The info_ptr should point to a char(4)
variable that contains the new identifier.

terminal_info
returns information about the terminal. The info_ptr should
point to the following structure (declared in
terminal_info.incl.pl1):

dcl 1 terminal_info aligned,
2 version fixed bin,
2 id char(4) unaligned,
2 term_type char(32) unaligned,
2 line_type fixed bin,
2 baud_rate fixed bin,
2 reserved (4) fixed bin;

where:

version
is the version number of the above structure. (Input). It
must be 1.

id
is the terminal identifier derived from the answerback.
(Output)

term_type
is the terminal type name. (Output)

line_type
is the line type number. (Output)

baud_rate
is the baud rate at which the terminal is running.
(Output)

reserved
is reserved for future use.

write_status
tells whether or not there is any write-behind output that has
not been sent to the terminal. The info_ptr should point to
the following structure, which is filled in by the call:

dcl 1 info_structure aligned,
2 ev_chan fixed bin(71),
2 output_pending bit(1);

______________ _____________

hcs_$tty_order hcs_$tty_read
______________ _____________

where:

ev_chan
is the event channel used to signal the completion of
output.

output_pending
indicates whether output is pending.
"0"b no output
"1"b output

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_rrreeeaaaddd

This entrypoint reads characters from a communications channel.

USAGE

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

call hcs_$tty_read (device_index, buffer_word_ptr,
buffer_char_offset, buffer_length, n_trans, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

buffer_char_offset
is the character index (0, 1, 2, or 3) of the first character
of the buffer within the first word of the buffer. (input)

buffer_length
is the length of the data buffer in characters. (input)

n_trans
is the number of characters transferred by this call.
(output)

_____________ ____________________

hcs_$tty_read hcs_$tty_read_echoed
_____________ ____________________

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_rrreeeaaaddd_eeeccchhhoooeeeddd

This entrypoint reads characters from a communications channel,
echoing some or all of them under the control of a count and a
break_table.

USAGE

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

call hcs_$tty_read_echoed (device_index, buffer_word_ptr,
buffer_char_offset, buffer_length, n_trans, n_echoed,
max_to_read, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

buffer_char_offset
is the character index (0, 1, 2, or 3) of the first character
of the buffer within the first word of the buffer. (input)

____________________ _______________________

hcs_$tty_read_echoed hcs_$tty_read_with_mark
____________________ _______________________

buffer_length
is the length of the data buffer in characters. (input)

n_trans
is the number of characters transferred by this call.
(output)

n_echoed
is the number of the returned characters that were echoed.
(output)

max_to_read
is the maximum number of characters to echo. This is normally
set to the number of character positions available on the line
of the video screen. (input)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_rrreeeaaaddd_wwwiiittthhh_mmmaaarrrkkk

This entrypoint reads characters a communications channel,
returning the position of the input/output synchronization mark.

USAGE

declare hcs_$tty_read_with_mark entry (fixed bin, char(*), fixed
bin(24), fixed bin(21), fixed bin, fixed bin(35));

call hcs_$tty_read_with_mark (device_index, read_buffer, n_trans,
mark_index, state, code);

_______________________ _______________________

hcs_$tty_read_with_mark hcs_$tty_read_with_mark
_______________________ _______________________

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

read_buffer
is a buffer into which the data will be read. (output)

n_trans
is the number of characters transferred by this call.
(output)

mark_index
is the position of the last character read in this buffer
before the input/output synchronization mark was seen. This
mark is seen when the last character specified before a mark
with the tty_write_with_mark or tty_write_whole_string is
transmitted. After that character is transmitted, the mark is
entered into the logical stream of input to indicate that
input following the mark was received after the marked output
was transmitted. This is zero if the mark has not yet been
returned. (output)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

______________ ______________

hcs_$tty_state hcs_$tty_write
______________ ______________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_ssstttaaattteee

This entrypoint returns the state of a communications channel
attached to the calling process.

USAGE

declare hcs_$tty_state entry (fixed bin, fixed bin, fixed
bin(35));

call hcs_$tty_state (device_index, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

________________________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_wwwrrriiittteee

This entrypoint writes characters to a communications channel.

USAGE

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

call hcs_$tty_write (device_index, buffer_word_ptr,
buffer_char_offset, buffer_length, n_trans, state, code);

______________ ______________

hcs_$tty_write hcs_$tty_write
______________ ______________

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

buffer_char_offset
is the character index (0, 1, 2, or 3) of the first character
of the buffer within the first word of the buffer. (input)

buffer_length
is the length of the data buffer in characters. (input)

n_trans
is the number of characters transferred by this call.
(output)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

_______________________ _______________________

hcs_$tty_write_set_mark hcs_$tty_write_set_mark
_______________________ _______________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_wwwrrriiittteee_ssseeettt_mmmaaarrrkkk

This entrypoint writes characters to a communications channel.
Input/output synchronization is requested after the last
character written. After that character is transmitted, a mark
will be inserted in the input stream that may be retrieved with
hcs_$tty_read_with_mark.

USAGE

declare hcs_$tty_write_set_mark entry (fixed bin, char(*), fixed
bin(21), fixed bin, fixed bin(35));

call hcs_$tty_write_set_mark (device_index, data_to_write,
n_trans, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

data_to_write
is a string of characters to be written to the channel.
(input)

n_trans
is the number of characters transferred by this call.
(output)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

___________________________ ___________________________

hcs_$tty_write_whole_string hcs_$tty_write_whole_string
___________________________ ___________________________

NNNaaammmeee::: hhhcccsss_$$$ttttttyyy_wwwrrriiittteee_wwwhhhooollleee_ssstttrrriiinnnggg

This entrypoint writes a string of characters to a communications
channel. If there is insufficient buffer space to accept the
entire string, then none of it is written.

USAGE

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

call hcs_$tty_write_whole_string (device_index, chars_to_write,
mark_flag, n_trans, state, code);

ARGUMENTS

device_index
is the device index identifying the channel to the system.
The device index is obtained via a call to hcs_$tty_index or
hcs_$tty_attach. (input)

chars_to_write
is the string of characters to be transmitted to the channel.

mark_flag
is a flag. if "1"b, the synchronization mark is inserted into
the output string after this string of characters. (input)

n_trans
is the number of characters transferred by this call.
(output)

code
is a standard system status code. It will be
error_table_$io_no_permission if the channel has hung up.
(output)

___________________________ _______________

hcs_$tty_write_whole_string hcs_$unmask_ips
___________________________ _______________

NNNaaammmeee::: hhhcccsss_$$$uuunnnmmmaaassskkk_iiipppsss

This entry point masks off, or disables, the specified ips
interrupts. Note the nonstandard use of the word "unmask" to
mean the disabling of an interrupt, rather than the enabling of
it; this is done for historical reasons. This entry point can be
used at the beginning of a critical section of code, to disable
one or more ips interrupts, and turn on the control bit as an
indication that some interrupts are disabled. See "Notes" in the
description of the hcs_$mask_ips entry point for a discussion of
the control bit.

USAGE

declare hcs_$unmask_ips entry (bit(36) aligned, bit(36) aligned);

call hcs_$unmask_ips (mask, old_mask)

ARGUMENTS

mask
is a word containing a "1"b for each ips interrupt that is to
be disabled. (Input) See "Notes".

old_mask
is the former value of the ips mask, with a control bit of
"1"b. (Output)

NOTES

The create_ips_mask_ subroutine can be used to create a mask,
given a set of ips names.

This entry point can be used at the end of a critical section of
code, to undo the mask changes made by this entry point.

ACCESS REQUIRED

None.

_________________ ______________________

hcs_$usage_values hpriv_connection_list_
_________________ ______________________

NNNaaammmeee::: hhhcccsss_$$$uuusssaaagggeee_vvvaaallluuueeesss

Returns the total number of page faults for this process as well
as the total cpu time this process has been charged with.

USAGE

declare hcs_$usage_values entry (fixed bin (71), fixed bin (71));

call hcs_$usage_values (page_faults, virtual_cpu_time);

ARGUMENTS

page_faults
the number of page faults taken by this process. (Output)

virtual_cpu_time
the virtual cpu time charged to this process. (Output)

ACCESS REQUIRED

There are no access requirements for this gate entry.

________________________________________

NNNaaammmeee::: hhhppprrriiivvv_cccooonnnnnneeeccctttiiiooonnn_llliiisssttt_

This gate contains highly privileged entries to
connection_list_manager_. They can be used only by highly
privileged processes (such as the Initializer), to manipulate any
connection entry. The entries contained in
hpriv_connection_list_ are listed below, along with their target
entries in connection_list_manager_.

Gate entry Target

delete_name hpriv_delete_name
delete_offset hpriv_delete_offset
delete_all_for_user hpriv_delete_all_for_user
get_name hpriv_get_name
get_next hpriv_get_next
get_next_owner hpriv_get_next_owner
get_next_user hpriv_get_next_user
init init

______________________ __________________

hpriv_connection_list_ installation_gate_
______________________ __________________

NNNaaammmeee::: iiinnnssstttaaallllllaaatttiiiooonnn_gggaaattteee_

EEEnnntttrrryyy::: iiinnnssstttaaallllllaaatttiiiooonnn_gggaaattteee_$$$iiinnnssstttaaallllll_ttttttttt

This entrypoint installs a new version of the system terminal
type table (TTT).

USAGE

declare installation_gate_$install_ttt entry (ptr, fixed bin (18)
uns, char(*), fixed bin(35));

call installation_gate_$install_ttt (ttt_ptr, word_count,
complaint, code);

ARGUMENTS

ttt_ptr
is a pointer to the binary TTT data. (Input)

word_count
is the number of words in the TTT to be installed. (Input)

complaint
is a string providing a more detailed description of a
failure. (Output)

code
is a standard system status code. (Output)

ACCESS REQUIRED
RW to the system TTT (>sc1>ttt) is required. Normally, only system
administrators and maintainers have this access.

CODES RETURNED
error_table_$smallarg - input TTT length is too small to be a valid TTT.
error_table_$invalid_ascii - a field in the TTT expected to be printable
ascii characters contained other character values
error_table_$unimplemented_version - input TTT data has wrong version
error_table_$improper_data_format - data in the TTT not in the proper format

____ ____

ioi_ ioi_
____ ____

NNNaaammmeee::: iiioooiii_

EEEnnntttrrryyy::: iiioooiii_$$$cccooonnnnnneeecccttt

The connect entry is called to start an I/O operation to a
device. The IOI will construct a PCW in ring 0 which will be
used to connect to the channel. This PCW will contain a reset
status command, and the continue bit will be set. The caller's
workspace will be wired-down in memory to prevent it from being
paged out to disk while the I/O operation is in progress, and the
channel will be connected to the DCW list which starts at a
caller-supplied offset in the workspace.

USAGE

declare ioi_$connect (fixed bin, fixed bin (18), fixed bin (35));

call ioi_$connect (devx, offset, code);

ARGUMENTS

devx
is the IOI specified device index.

offset
is the offset in the user's workspace at which the DCW list
starts. An offset of 0 implies that the DCW list is at the
very beginning of the workspace.

code
is a standard system status code.

NOTES

The termination of the I/O operation will be signalled on the
event channel specified in the call to rcp_$attach or
ioi_$set_event. xxxxx

____ ____

ioi_ ioi_
____ ____

EEEnnntttrrryyy::: iiioooiii_$$$cccooonnnnnneeecccttt_pppcccwww

This entry is identical to the connect entry except that the
caller provides the first word of the PCW to be used when
connecting the channel. This PCW is copied into ring 0 and
validated before it is used. If an invalid field is found in the
PCW, the connect does not take place.

USAGE

declare ioi_$connect_pcw entry (fixed bin, fixed bin(18), bit(36)
aligned, fixed bin(35));

call ioi_$connect_pcw (devx, offset, pcw, code);

ARGUMENTS

devx
is as given for ioi_$connect.

offset
is as given for ioi_$connect.

pcw
is the first word of the Peripheral Control Word (PCW) to be
used to connect to the device. The format of a PCW is given
in the include file iom_pcw.incl.pl1.

code
is as given for ioi_$connect.

NOTES

See the note under ioi_$connect.

EEEnnntttrrryyy::: iiioooiii_$$$gggeeettt_dddeeetttaaaiiillleeeddd_ssstttaaatttuuusss

This entry is used to return the detailed status available after
an I/O error. The format of detailed status is different for
each device, and its interpretation is up to the caller. If
there is no detailed status available for this device, this fact
is reflected to the caller. Detailed status is only saved after
an I/O operation terminated in error.

USAGE

declare ioi_$get_detailed_status entry (fixed bin, bit(1)
aligned, bit(216), fixed bin(35));

____ ____

ioi_ ioi_
____ ____

call ioi_$get_detailed_status (devx, valid_flag, detailed_status,
code);

ARGUMENTS

devx
is the IOI supplied device index.

valid_flag
is set to "1"b if there is detailed status available, is set
to "0"b otherwise.

detailed_status
is the detailed status from the last I/O operation.

code
is a standard system status code.

EEEnnntttrrryyy::: iiioooiii_$$$gggeeettt_ssspppeeeccciiiaaalll_ssstttaaatttuuusss

This entry is called to check for the existence of special status
for a device. Special status is set by the occurence of a
special interrupt from a device (such as a disk drive coming on
line, or a tape rewind completing). If the device in question is
connected to a PSIA channel, the special status reported at
special interrupt time is returned to the caller.

USAGE

declare ioi_$get_special_status entry (fixed bin, bit(1) aligned,
bit(36) aligned, fixed bin(35));

call ioi_$get_special_status (devx, valid_flag, special_status,
code);

ARGUMENTS

devx
is the IOI supplied device index.

valid_flag
is set to "1"b if there is special status available, is set to
"0"b otherwise.

special_status
is the special status from the last special interrupt.

code
is a standard system status code.

____ ____

ioi_ ioi_
____ ____

EEEnnntttrrryyy::: iiioooiii_$$$rrreeellleeeaaassseee_dddeeevvviiiccceeesss

This entry undoes the effects of a ioi_$suspend_devices call.
Any devices which were suspended will again be available for I/O.

USAGE

declare ioi_$release_devices entry (fixed bin, fixed bin(35));

call ioi_$release_devices (devx, code);

ARGUMENTS

devx
is the IOI supplied device index.

code
is a standard system status code.

EEEnnntttrrryyy::: iiioooiii_$$$ssseeettt_ccchhhaaannnnnneeelll_rrreeeqqquuuiiirrreeeddd

This privileged entry is called to set a required channel and IOM
number for a device which could possibly otherwise be run by more
than one channel. It is primarily intended for use by the Test
and Diagnostic software.

USAGE

declare ioi_$set_channel_required entry (fixed bin, fixed bin(3),
fixed bin(7), fixed bin(35));

call ioi_$set_channel_required (devx, iom, channel, code);

ARGUMENTS

devx
is the IOI supplied device index.

iom
is the IOM number of the required channel.

channel
is the channel number of the required channel.

code
is a standard system status code.

____ ____

ioi_ ioi_
____ ____

NOTES

After calling this entry, any subsequent calls to ioi_$connect
during this attachment will use the specified channel. This does
not preclude this channels use by other attachments. To undo the
effects of this call, another call using with both iom and
channel set to zero may be used.

To make a call to ioi_, this must be a privileged attachment.
Access to rcp_priv_ is necessary to obtain a privileged
attachment.

EEEnnntttrrryyy::: iiioooiii_$$$ssseeettt_eeevvveeennnttt

This entry is called to change the event channel over which
status events are signalled for a device. This event channel is
initially set by calling rcp_$attach, but may be changed.

USAGE

declare ioi_$set_event entry (fixed bin, fixed bin(71), fixed
bin(35));

call ioi_$set_event (devx, event_channel, code);

ARGUMENTS

devx
is the IOI supplied device index.

event_channel
is the new event channel to be used when signalling status
events.

code
is a standard system status code.

EEEnnntttrrryyy::: iiioooiii_$$$ssseeettt_ssstttaaatttuuusss

The ioi_ entry is used to specify the address and length of a
circular queue to be used for reporting status. This queue is
allocated in the workspace segment. Each time status is to be
reported, the next entry in the queue is used. If the previous
status report used the last entry in the queue, the first entry
in the queue is used for this status report. It is up to the
user to keep track of where status is to be reported next.

____ ____

ioi_ ioi_
____ ____

USAGE

declare ioi_$set_status entry (fixed bin, fixed bin(18), fixed
bin, fixed bin(35));

call ioi_$set_status (devx, offset, count, code);

ARGUMENTS

devx
is the IOI supplied device index.

offset
is the word offset into the workspace segment at which the
status queue is to begin.

count
is the number of elements in the status queue. Each element
in the status queue is 8 words long. The format of each entry
in this queue is defined in the include file
ioi_stat.incl.pl1.

code
is a standard system status code.

EEEnnntttrrryyy::: iiioooiii_$$$sssuuussspppeeennnddd_dddeeevvviiiccceeesss

This entry is used to suspend all activity on a device controller
except for that directed at a specified device. It is meant for
use by the Test and Diagnostic software.

USAGE

declare ioi_$suspend_devices entry (fixed bin, fixed bin(35));

call ioi_$suspend_devices (devx, code);

ARGUMENTS

devx
is the IOI supplied device index. All activity on the
controller to which this device is connected will be delayed
until an ioi_$release_devices call. Any activity currently in
progress will be allowed to finish. If the specified device
is connected to more than one controller, an
ioi_$set_channel_required call must have been made to select
one of them.

____ ____

ioi_ ioi_
____ ____

code
is a standard system status code.

EEEnnntttrrryyy::: iiioooiii_$$$tttiiimmmeeeooouuuttt

This entry establishes a time-out interval for a device. The
clock is read each time the device is connected. If a terminate
interrupt does not occur within the time-out interval,
termination will be forced and the user notified. The ioi_ entry
may be called as many times as desired for a device. If it is
never called, a default value of 30 seconds will be used.

USAGE

declare ioi_$timeout entry (fixed bin, fixed bin(71), fixed
bin(35));

call ioi_$timeout (devx, time, code);

ARGUMENTS

devx
is the IOI supplied device index.

time
is the time (in microseconds) to be given to allow a device to
terminate after a connect. If time is zero, no timeout value
is set and an I/O operation may take as long as necessary.

code
is a standard system status code.

EEEnnntttrrryyy::: iiioooiii_$$$wwwooorrrkkkssspppaaaccceee

The ioi_ entry is called to provide a workspace for DCW lists and
data buffers. If this is the first call to this entry, a segment
of the specified size is created in the caller's process
directory; otherwise the maximum length of the previously created
segment is changed to reflect the new value.

Since the entire workspace must be in memory while I/O is in
progress to the device, performance problems could result if an
excessively large workspace is requested. Users should ensure
that the workspace size correctly reflects their need for DCW
lists, buffers, and the status queue.

This entry may not be called while I/O is in progress to the
device.

____ ____

ioi_ ipc_
____ ____

The management of this segment is completely up to the caller;
the IOI makes no assumptions about its contents. Various ioi_
entries take offsets into this workspace as arguments.

USAGE

declare ioi_$workspace entry (fixed bin, ptr, fixed bin(19),
fixed bin(35));

call ioi_$workspace (devx, workspace_ptr, workspace_length,
code);

ARGUMENTS

devx
is the IOI supplied device index.

workspace_ptr
is a pointer to the workspace segment to be used to contain
DCW lists and data.

workspace_length
is the desired length of the wordspace segment in words.

code
is a standard system status code.

________________________________________

NNNaaammmeee::: iiipppccc_

Most ipc_ entrypoints are described in Multics Subroutines. The
following are internal entrypoints used by cpm_.

EEEnnntttrrryyy::: iiipppccc_$$$rrreeeaaassssssiiigggnnn_cccaaallllll_ccchhhaaannnnnneeelllsss

This entrypoint reassigns call channels from one control point to
another one whenever a control point is destroyed.

USAGE

dcl ipc_$reassign_call_channels entry (bit (36) aligned,
bit (36) aligned);

call ipc_$reassign_call_channels (old_control_point_id,
new_control_point_id);

____ ____

ipc_ ipc_
____ ____

old_control_point_id Input
is the unique ID of the control point to be destroyed.

new_control_point_id
is the unique ID of the control point to be assigned the event
call channel.

EEEnnntttrrryyy::: iiipppccc_$$$wwwaaaiiittt_fffooorrr_aaannn_eeevvveeennnttt

Wait for an ipc_ event when there are no control points in the
ready states.

USAGE

dcl ipc_$wait_for_an_event entry ();

call ipc_$wait_for_an_event ();

NOTES

The arrival of an event will cause the control point waiting for
that event to be put into the ready state.

Changes to Existing Structures

Changes to ect_structures.incl.pl1

dcl 1 waiting_control_point
aligned based (wcpp),
2 word_0,
3 block_count
fixed bin (17) unal,
3 type fixed bin (17) unal,
2 control_point_id
bit (36) aligned,
2 chain,
3 next_wcpp pointer,
3 prev_wcpp pointer,

ARGUMENTS

block_count
is the number of ipc_$block calls made by the control point

type
is the type of waiting control point (currently not used).

____ ____

ipc_ ipc_
____ ____

control_point_id
is the id of the waiting control point

next_wcpp
is a pointer to the next waiting control point.

prev_wcpp
is a pointer to the previous waiting control point.

o The structure wait_channel has the following added:

dcl 1 wait_channel aligned based (ectep),
2 word_0,
3 unused1 fixed bin (17) unal,
3 type fixed bin (17) unal,
2 next_chanp ptr unal,
2 prev_chanp ptr unal,
2 word_3,
3 fast_channel
bit (1) unal,
3 inhibit_count
fixed bin (16) unal,"
3 wakeup_control_points
bit (1) unal,
3 wakeup_count
fixed bin (17) unal unsigned,
2 name bit (72),
2 first_ev_msgp
ptr unal,
2 last_ev_msgp
ptr unal,
2 first_wcpp ptr unal,
2 last_wcpp ptr unal,
2 fast_channel_id fixed binary,
2 unused2 fixed bin;

wakeup_control_points
indicates the control point waiting on this channel should be
awakened.

first_wcpp
is the pointer to the first control point waiting on this
channel. See the description of the waiting_control_point
structure above.

last_wcpp
is the pointer to the last control point waiting on this
channel. See the description of the waiting_control_point
structure above.

____ ____

ipc_ ipc_
____ ____

o The structure call_channel has the following added:

dcl 1 call_channel aligned based (ectep),
2 word_0,
3 priority fixed bin (17) unal,
3 type fixed bin (17) unal,
2 next_chanp ptr unal,
2 prev_chanp ptr unal,
2 word_3,
3 call_inhibit bit (1) unal,
3 inhibit_count fixed bin (16) unal,
3 wakeup_control_points bit (1) unal,
3 wakeup_count fixed bin (18) unal unsigned,
2 name bit (72),
2 first_ev_msgp ptr unal,
2 last_ev_msgp ptr unal,
2 data_ptr ptr unal,
2 procedure_value,
3 procedure_ptr ptr unal,
3 environment_ptr ptr,
2 control_point_id bit (36) al;

wakeup_control_points
indicates the control point waiting on this channel should be
awakened.

control_point_id
is the control point which owns this channel

o The following was added to the stack_header:
dcl 1 stack_header based (sb) aligned,
2 pad1 (4) fixed bin,
2 old_lot_ptr ptr,
2 combined_stat_ptr
ptr,
2 clr_ptr ptr,
2 max_lot_size fixed bin (17) unal,
2 main_proc_invoked
fixed bin (11) unal,
2 have_static_vlas
bit (1) unal,
2 pad4 bit (2) unal,
2 run_unit_depth
fixed bin (2) unal,
2 cur_lot_size fixed bin (17) unal,
2 pad2 bit (18) unal,
2 system_free_ptr
ptr,
2 user_free_ptr
ptr,

____ ____

ipc_ ipc_
____ ____

2 null_ptr ptr,
2 stack_begin_ptr
ptr,
2 stack_end_ptr
ptr,
2 lot_ptr
ptr,
2 signal_ptr ptr,
2 bar_mode_sp ptr,
2 pl1_operators_ptr
ptr,
2 call_op_ptr ptr,
2 push_op_ptr ptr,
2 return_op_ptr ptr,
2 return_no_pop_op_ptr
ptr,
2 entry_op_ptr ptr,
2 trans_op_tv_ptr ptr,
2 isot_ptr ptr,
2 sct_ptr ptr,
2 unwinder_ptr ptr,
2 sys_link_info_ptr
ptr,
2 rnt_ptr ptr,
2 ect_ptr ptr,
2 assign_linkage_ptr
ptr,
2 cpd_ptr ptr unaligned,
2 cpm_enabled bit (36),
2 trace,
3 frames,
4 count, fixed bin,
4 top_ptr ptr unal,
3 in_trace bit (36) aligned,
2 pad3 (3) bit (36) aligned;

cpd_ptr
is a pointer to the control_point_data structure for the
control point which owns this stack if control point
management is enabled.

cpm_enabled
is set to control_point_data.id of the control point for which
this is a stack if control point management is enabled, and is
"0" otherwise.

____ __________

ipc_ list_init_
____ __________

NNNaaammmeee::: llliiisssttt_iiinnniiittt_

Allows the caller to intitialize a variable using an encoding
scheme that allows data compression. This encoding can specify
the skipping of bits or the repeating of bits. It can also
specify the area is to be zeroed.

USAGE

declare list_init_ entry
(ptr, ptr, fixed bin (35), ptr, ptr, fixed bin (35));

call list_init_ (variable_ptr, template_ptr, var_size,
stack_base_ptr, seg_ptr, code);

ARGUMENTS

variable_ptr
is a pointer to the variable to be initialized (Input)

template_ptr
is a pointer to the list_template_entry structure defining the
initialization to be performed. The list_template_entry
structure is declared in system_link_init_info.incl.pl1 and
has the structure defined in the following "Notes on
list_template_entry Structure" section. If this is null it
implies that the target should be zeroed. (Input)

var_size
is the size of the variable in words. (Input)

sb_ptr
is a pointer to the base of the stack in the ring where the
variable is active. (Input)

seg_ptr
is a pointer to the segment containing the declaration of the
variable to be initialized. (Input)

code
is a standard system error code. (Output)

__________ __________

list_init_ list_init_
__________ __________

EEEnnntttrrryyy::: llliiisssttt_iiinnniiittt_$$$vvvaaarrriiiaaabbbllleee_aaalllrrreeeaaadddyyy_zzzeeerrrooo

Allows the caller to intialize a variable using an encoding
scheme that allows data compression. This encoding can specify
the skipping of bits or the repeating of bits. This entry point
takes for granted that the variable has been previously zeroed.

USAGE

declare list_init_$variable_already_zero entry
(ptr, ptr, fixed bin (35), ptr, ptr, fixed bin (35));

call list_init_$variable_already_zero (variable_ptr,
template_ptr,
var_size, stack_base_ptr, seg_ptr, code);

ARGUMENTS

variable_ptr
is a pointer to the variable to be initialized (Input)

template_ptr
is a pointe to the list_template_entry structure defining the
initialization to be performed. The list_template_entry
structure is declared in system_link_init_init_info.incl.pl1
and has the structure defined in the following "Notes on
list_template_entry Structure" section. If this is null it
implies that the target should be zeroed. (Input)

var_size
is the size of the variable in words. (Input)

sb_ptr
is a pointe to the base of the stack in the ring where the
variable is active. (Input)

seg_ptr
is a pointer to the segment containing the declaration of the
variable to initialized. (Input)

code
is a standard system error code. (Output)

NOTES

The list_template_entry has the following definition as found in
system_link_init_info.incl.pl1:

__________ __________

list_init_ list_init_
__________ __________

dcl 1 list_template_entry aligned based,
2 n_bits fixed bin (35) aligned,
2 mbz bit (3) unaligned,
2 init_type fixed bin (3)
unsigned unaligned,
2 repeat fixed bin (30)
unsigned unaligned,
2 datum bit
(init_n_bits_in_datum
refer
(list_template_entry.n.bits));

Structure elements:

ARGUMENTS

nbits
is the number of bits of initialization specified by the datum.
If zero this specifies that this is the last template in the
initialization. If skipping is implied
via the repeat field then this specifies the number
of bits to be skipped. If positive it implies a forward skip.
If negative it implies a backward skip.
mbz is a zeroed pad field and must be zero.

init_type
specifies what type of initialization is to be performed with the
following named constants found in system_link_init_info.incl.pl1.

NORMAL_INIT (=0)
ITS PTR_INIT (=1)
PACKED_PTR_INIT (=2)

init_type
specifies how many times the datum is to be repeated in the
variable. If zero this specifies a skipping of n_bits bits in
the variable.

init_type
this is the data to be copied out to the variable repeat
times. If zero it implies that the variable will be zeroed.
For NORMAL_INIT the datum is copied out directly to the
variable. For ITS_PTR_INIT and PACKED_PTR_INIT the datum
specifies encoded information that will allow external
pointers to be initialized to nonconstant values. The n_bits
field in this case is always 72. The encoding is in the form
of the structure pointe_init_template defined in
system_link_init_info.incl.pl1 as follows:

__________ __________

list_init_ list_init_
__________ __________

dcl 1 pointer_init_template based,
2 ptr_type fixed bin (18)
unsigned aligned,
2 section_offset fixed bin (18)
unsigned unaligned,
2 word_offset fixed bin (18)
unsigned unaligned,
2 mbz bit (12) unaligned,
2 bit_offset fixed bin (6)
unsigned unaligned;
Structure elements:

ARGUMENTS

ptr_type
specifies where the target area is located. The following
named constants are declared in link_init_info.incl.pl1.

PTR_INIT_TEXT (= 0) text section reference
PTR_INIT_LOT (= 1) link section reference
PTR_INIT_ISOT (= 2) static section reference

section_offset
the word offset of the target within the specified section.

word_offset
is the offset in words from the address within the section to
the target. If the location specified by the section_offset
and the ptr_type is a link this value will be applied to the
target address obtained by referencing through the link.

bit_offset
is the offset in bits from the address specified by
word_offset above to the target. If the location specified by
the section_offset and the ptr_type is a link this value will
be applied to the target address obtained by referencing
through the link.

NOTES

The ptr_type and section_offset fields specify a pointer to a
word within the object segment. In the case of a pointer to the
linkage section this location may be a link. If this is the
case, then the reference, references indirectly through the link,
snapping it via hcs_$link_force if necessary. Then the
word_offset and bit_offset values are applied. Thus an arbitrary
word and bit offset may be specified to be added to any pointer
for which a standard link may be created.

__________ ___________________________

list_init_ login_server_overseer_$test
__________ ___________________________

In the case of nonlink references, if either the word_offset or
the section_offset are nonzero then the offsets will be applied
as word offsets to the section pointe identified by the ptr_type
field. If the bit offset is nonzero it will be applied as a bit
offset from the resulting address generated by applying the
section_offset and word_offset. If this reference is not to a
constant structure the results are undefined. This allows
pointes to be created to any arbitrary point within the object
segment.

Recursive references to external variables with pointer
initialization will be handled due to the allocation of the
variable taking place prior to the initialization of the
variable. This implies that a recursive reference will
eventually find the allocated variable in the external name list
and its value will be the address of the allocated variable.

________________________________________

NNNaaammmeee::: lllooogggiiinnn_ssseeerrrvvveeerrr_ooovvveeerrrssseeeeeerrr_$$$ttteeesssttt

SYNTAX AS A COMMAND

login_server_overseer_$test {test_sc1_dir {test_info_dir}} {-pb}

FUNCTION

This command establishes a test version of the login server
environment in the caller's process. In this environment, the
standard login server requests are available. In addition,
normal Multics commands can be issued by preceding them with ..
to escape from the login server ssu_ environment. This feature
can be used to issue cpm_call commands to manipulate the control
points listening on endpoints or managing connections.

ARGUMENTS

test_sc1_dir
pathname of the directory containing test versions of
answering service databases to be used by the login server.
Login server requests are sent to the login_server_requests.ms
queue in this directory.

test_info_dir
pathname of the directory containing the three Login Server
subsystem info directories, which contain info segments
describing the subsystem requests. Three subdirectories must

___________________________ _____________________________

login_server_overseer_$test mailbox_$accept_wakeups_index
___________________________ _____________________________

reside in test_info_dir:
login_server_info
login_info
login_connect_info

-probe, -pb
when control points report an error, calls probe after
reporting the error to allow a chance for further debugging.
By default, execution continues within the control point after
the error is reported.

ACCESS REQUIRED

To use this command, access is required to the
network_accounting_gate_, user_message_priv_ gate, and
login_server_requests.ms queue.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$aaacccccceeepppttt_wwwaaakkkeeeuuupppsss_iiinnndddeeexxx

The accept_wakeups_index entrypoint enables a process to accept
IPC wakeups by posting its event channel and process ID in a
mailbox.

USAGE

declare mailbox_$accept_wakeups_index entry (fixed bin, fixed
bin(71), bit(36), fixed bin(35));

call mailbox_$accept_wakeups_index (mseg_index, event_channel,
wakeup_switches, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox through which wakeups are to be
accepted. (Input)

event_channel
is the value returned from a call to ipc_$create_ev_chn,
providing an IPC channel over which wakeups can be sent.
(Input)

wakeup_switches
is a bit string identifying the type of wakeups that the
process will accept. (Input) When turned on, the high order

_____________________________ __________________

mailbox_$accept_wakeups_index mailbox_$add_index
_____________________________ __________________

bit signifies that the process will accept normal wakeups.
When turned on, the second highest order bit signifies that
the process will accept urgent wakeups. The remaining
thirty-four bits are ignored.

code
is a standard system status code. (Output) It can have the
following values:
error_table_$moderr
incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.

ACCESS REQUIRED

The calling process must have "d" extended access to the mailbox
to accept wakeups. The authorization of the calling process must
dominate the access class of the parent of the mailbox. The
authorization of the calling process must dominate the
authorization of any live process already accepting wakeups
through the mailbox. The authorization of the calling process
must be dominated by the access class of the mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$aaadddddd_iiinnndddeeexxx

The add_index entrypoint places an arbitrary message in a
mailbox.

USAGE

declare mailbox_$add_index entry (fixed bin, ptr, fixed bin(24),
bit(72) aligned, fixed bin(35));

call mailbox_$add_index (mseg_index, message_ptr, message_len,
message_id, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox into which the message is to be
placed. (Input)

message_ptr
is a pointer to an arbitrary bit string, which is the text of
the message. (Input)

__________________ ____________________

mailbox_$add_index mailbox_$chname_file
__________________ ____________________

message_len
is the length of the message in bits. (Input)

message_id
is a value identifying the message in the mailbox, which can
be used to reference the message in subsequent calls to
mailbox_.

ACCESS REQUIRED

The calling process must have "a" extended access to the mailbox
to add a message. The authorization of the calling process must
dominate the access class of the parent of the mailbox. The
authorization of the calling process must be dominated by the
access class of the mailbox segment.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$ccchhhnnnaaammmeee_fffiiillleee

The chname_file entrypoint changes the entry name on a specified
mailbox. If an already existing name (an old name) is specified,
it is deleted from the entry; if a new name is specified, it is
added. Thus, if only an old name is specified, the effect is to
delete a name; if only a new name is specified, the effect is to
add a name; and if both are specified, the effect is to rename
the entry.

USAGE

declare mailbox_$chname_file entry (char(*), char(*), char(*),
char(*), fixed bin(35));

call mailbox_$chname_file (dir_name, entry_name, old_entry_name,
new_entry_name, code);

ARGUMENTS

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

____________________ _____________________________

mailbox_$chname_file mailbox_$check_salv_bit_index
____________________ _____________________________

entry_name
is the name of the mailbox. (Input)

old_entry_name
is the name to be deleted from the mailbox. (Input) It can be
a null character string ("") in which case no name is deleted.
If oldname is null, then newname must not be null.

new_entry_name
is the name to be added to the entry. (Input) It must not
already exist in the directory on this or another entry. It
can be a null character string ("") in which case no name is
added. If it is null, then oldname must not be the only name
on the entry.

code
is a storage system status code. (Output) It can have the
values:
error_table_$moderr
incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$nonamerr
attempting to delete the only name of a directory entry.
error_table_$namedup
attempting to add a name that exists on another entry.
error_table_$segnamedup
attempting to add a name that already exists on this entry.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
mailbox. The authorization of the calling process must equal the
access class of the parent of the mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$ccchhheeeccckkk_sssaaalllvvv_bbbiiittt_iiinnndddeeexxx

The check_salv_bit_index entrypoint returns the value of the
salvaged bit of a mailbox; in addition, it can be used to turn
the bit off if found on.

USAGE

declare mailbox_$check_salv_bit_index entry (fixed bin, bit(1)
aligned, bit(1) aligned, fixed bin(35));

_____________________________ ______________

mailbox_$check_salv_bit_index mailbox_$close
_____________________________ ______________

call mailbox_$check_salv_bit_index (mseg_index, turn_off,
salv_bit, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox from which the salvaged bit is to be
obtained and possibly turned off. (Input)

turn_off
is a flag which, if set to true, turns of the salvaged bit if
it is on. (Input)

salv_bit
is the value of the salvaged bit prior to the call. (Output)

ACCESS REQUIRED

The calling process must have "s" extended access to the mailbox
to obtain the value of the salvaged bit. It must have "d"
extended access to turn the salvaged bit off. The authorization
of the process must dominate the access class of the parent of
the mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$ccclllooossseee

The close entrypoint terminates the relationship between a
message segment index and a mailbox.

USAGE

declare mailbox_$close entry (fixed bin, fixed bin(35));

call mailbox_$close (mseg_index, code);

______________ _____________________

mailbox_$close mailbox_$compact_file
______________ _____________________

ARGUMENTS

mseg_index
is the value returned froma call to mailbox_$open, used to
identify a specific mailbox. (Input)

code
is a standard system status code. (Output)

ACCESS REQUIRED

No explicit access is required to sucessfully execute this
entrypoint.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$cccooommmpppaaacccttt_fffiiillleee

The compact_file entrypoint eliminates unused space in a mailbox,
compressing its size to reflect storage actually filled with
messages.

USAGE

declare mailbox_$compact_file entry (char(*), char(*), float
bin(27), fixed bin(35));

call mailbox_$compact_file (dir_name, entry_name,
compaction_ratio, code);

ARGUMENTS

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

entry_name
is the name of the mailbox. (Input)

compaction_ratio
is a value used to determine whether or not to perform the
compaction. (Input) If the ratio of unused space to used
space exceeds the argument value, the segment is compacted.
If the compaction ratio is negative, the compaction always
performed.

code
is a standard system status code. (Output) It can have the
following values:

_____________________ ______________________

mailbox_$compact_file mailbox_$compact_index
_____________________ ______________________

error_table_$moderr
incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.

ACCESS REQUIRED

The calling process must have "d" extended access to the mailbox.
The authorization of the calling process must be equal to the
access class of the parent of the mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$cccooommmpppaaacccttt_iiinnndddeeexxx

The compact_index entrypoint eliminates unused space in a
mailbox, compressing its size to reflect storage actually filled
with messages.

USAGE

declare mailbox_$compact_index entry (fixed bin, float bin(27),
fixed bin(35));

call mailbox_$compact_index (mseg_index, compaction_ratio, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox to be compacted. (Input)

______________________ _____________

mailbox_$compact_index mailbox_$copy
______________________ _____________

ACCESS REQUIRED

The calling process must have "d" extended access to the mailbox.
The authorization of the calling process must be equal to the
access class of the parent of the mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$cccooopppyyy

The copy entrypoint copies the contents of an existing mailbox
into a new mailbox.

USAGE

declare mailbox_$copy entry (char (*), char (*), char (*), char
(*), bit (1) aligned, fixed bin (35));

call mailbox_$copy (source_dir_name, source_entry_name,
target_dir_name, target_entry_name, error_on_target, code);

ARGUMENTS

source_dir_name
is the pathname of the directory that contains the mailbox to
be copied. (Input)

source_entry_name
is the name of the mailbox to be copied. (Input)

target_dir_name
is the pathname of the directory that is to contain a copy of
the source mailbox. (Input)

target_entry_name
is the name of the new mailbox. (Input)

error_on_target
is a flag indicating that the difficulties in copying the
mailbox were due to the target mailbox. (Output)

_____________ _______________

mailbox_$copy mailbox_$create
_____________ _______________

ACCESS REQUIRED

The calling process must have "r" extended access to the source
mailbox, and "ma" access to the target directory. The
authorization of the calling process must equal the access class
of BOTH the source and target directories. The maximum
authorization of the process must dominate the access class of
the source mailbox.

NOTES

The target mailbox must not exist before this entrypoint is
called.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$cccrrreeeaaattteee

The create entrypoint creates a mailbox in a given directory.

USAGE

declare mailbox_$create entry (char(*), char(*), fixed bin(35));

call mailbox_$create (dir_name, entry_name, code);

ARGUMENTS

dir_name
is the pathname of the directory which is to contain the
mailbox. (Input)

entry_name
is the name of the mailbox to be created. (Input)

ACCESS REQUIRED

The calling process must have append and modify access to the
directory which is to contain the mailbox. The authorization of
the calling process must equal the access class of the directory
which is to contain the mailbox.

_______________ _______________

mailbox_$create mailbox_$delete
_______________ _______________

NOTES

The mailbox is created with default extended modes of "adrosw"
for the caller's person ID and "aow" for both "*.SysDaemon.*" and
"*.*.*". The access class range of the mailbox is defined at the
lower bound by the access class of the parent directory and at
the upper bound by the maximum authorization of the calling
process.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$dddeeellleeettteee

The delete entrypoint deletes a mailbox from hierarchy.

USAGE

declare mailbox_$delete entry (char(*), char(*), fixed bin(35));

call mailbox_$delete (dir_name, entry_name, code);

ARGUMENTS

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

entry_name
is the name of the mailbox to be deleted. (Input)

ACCESS REQUIRED

The calling process must have modify access to the parent of the
mailbox. The authorization of the calling process must be equal
to the access class of the parent of the mailbox.

_______________ _____________________

mailbox_$delete mailbox_$delete_index
_______________ _____________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$dddeeellleeettteee_iiinnndddeeexxx

The delete_index entrypoint deletes a specified message in a
mailbox.

USAGE

declare mailbox_$delete_index entry (fixed bin, bit(72) aligned,
fixed bin(35));

call mailbox_$delete_index (mseg_index, message_id, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox which contains the message to be
deleted. (Input)

message_id
is the identifier of the message to be deleted. (Input)

ACCESS REQUIRED

The calling process must have "d" extended access to the mailbox
to delete an arbitrary message; alternatively, "o" extended
access will permit the process to delete a message that was added
by the user. The authorization of the calling process must equal
the access class of the message to be deleted. The authorization
of the calling process must dominate the parent of the mailbox
that contains the message. The authorization of the calling
process must be dominated by the access class of the mailbox.

_____________________ ______________________

mailbox_$delete_index mailbox_$get_mode_file
_____________________ ______________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$gggeeettt_mmmooodddeee_fffiiillleee

The get_mode_file entrypoint returns the effective extended
access the caller has to a mailbox.

USAGE

declare mailbox_$get_mode_file entry (char(*), char(*), bit(36)
aligned, fixed bin(35));

call mailbox_$get_mode_file (dir_name, entry_name, modes, code);

ARGUMENTS

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

entry_name
is the name of the mailbox. (Input)

modes
is a bit string describing the effective extended access the
process has to the mailbox. (Output) The bit string is
described in the include file
mseg_access_mode_values.incl.pl1.

ACCESS REQUIRED

The calling process must have either a minimum of status access
to the parent of the mailbox or non-null extended access to the
mailbox itself. The authorization of the calling process must
dominate the access class of the parent of the mailbox.

______________________ _______________________

mailbox_$get_mode_file mailbox_$get_mode_index
______________________ _______________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$gggeeettt_mmmooodddeee_iiinnndddeeexxx

The get_mode_index entrypoint returns the effective extended
access the caller has to a mailbox.

USAGE

declare mailbox_$get_mode_index entry (fixed bin, bit(36)
aligned, fixed bin(35));

call mailbox_$get_mode_index (mseg_index, modes, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox for which modes are to be obtained.
(Input)

modes
is a bit string describing the effective extended access the
process has to the mailbox. (Output) The bit string is
described in the include file
mseg_access_mode_values.incl.pl1.

ACCESS REQUIRED

_______________________ ________________________________

mailbox_$get_mode_index mailbox_$get_message_count_index
_______________________ ________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$gggeeettt_mmmeeessssssaaagggeee_cccooouuunnnttt_iiinnndddeeexxx

The get_message_count_index entrypoint returns the number of
messages present in a mailbox that are accessible to the calling
process.

USAGE

declare mailbox_$get_message_count_index entry (fixed bin, fixed
bin, fixed bin(35));

call mailbox_$get_message_count_index (mseg_index, message_count,
code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox from which the count is to be
obtained. (Input)

message_count
is the number of messages accessible to the calling process.
(Output)

ACCESS REQUIRED

The calling process must have "s" extended access to the mailbox
in order to obtain its message count. The authorization of the
calling process must dominate the access class of the parent of
the mailbox.

________________________________ _____________________

mailbox_$get_message_count_index mailbox_$get_uid_file
________________________________ _____________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$gggeeettt_uuuiiiddd_fffiiillleee

The get_uid_file entrypoint returns the file system unique
identifier for the mailbox.

USAGE

declare mailbox_$get_uid_file entry (char(*), char(*), bit(36)
aligned, fixed bin(35));

call mailbox_$get_uid_file (dir_name, entry_name, uid, code);

ARGUMENTS

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

entry_name
is the name of the mailbox. (Input)

uid
is the file system unique identifier for the mailbox.
(Output)

ACCESS REQUIRED

_____________________ ______________________

mailbox_$get_uid_file mailbox_$get_uid_index
_____________________ ______________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$gggeeettt_uuuiiiddd_iiinnndddeeexxx

The get_uid_index entrypoint returns the file system unique
identifier for the mailbox.

USAGE

declare mailbox_$get_uid_index entry (fixed bin, bit(36) aligned,
fixed bin(35));

call mailbox_$get_uid_index (mseg_index, uid, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox for which the unique identifier is to
be obtained. (Input)

uid
is the file system unique identifier for the mailbox.
(Output)

ACCESS REQUIRED

______________________ _______________________________

mailbox_$get_uid_index mailbox_$incremental_read_index
______________________ _______________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$iiinnncccrrreeemmmeeennntttaaalll_rrreeeaaaddd_iiinnndddeeexxx

The incremental_read_index entrypoint obtains a message from a
mailbox relative to the message specified in its argument list.

USAGE

declare mailbox_$incremental_read_index entry (fixed bin, ptr,
bit(2) aligned, bit(72) aligned, ptr, fixed bin(35));

call mailbox_$incremental_read_index (mseg_index, area_ptr,
direction, message_id, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox from which the message is to be
obtained. (Input)

area_ptr
is a pointer to an area where mailbox_ can allocate the
message. (Input)

direction
is a bit string specifying the message to be returned,
relative to that specified by the message identifier. (Input)
A value of "00"b selects the specified message. A value of
"10"b selects the message before the specified one. A value
of "01"b selects the message after the specified one.

message_id
is the identifier of the message that serves as a reference
point for the selection. (Input)

ms_arg_ptr
is a pointer to the structure mseg_return_args, which will be
filled in with information about the selected message.
(Input)

_______________________________ _______________________________

mailbox_$incremental_read_index mailbox_$incremental_read_index
_______________________________ _______________________________

ACCESS REQUIRED

The caller must have "r" extended access to the mailbox to read a
message from it. The authorization of the caller must both
dominate the access class of the parent of the mailbox and
dominate the access class of the message for the message to be
returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

dcl ms_arg_ptr pointer;
dcl 1 mseg_return_args aligned
based (ms_arg_ptr),
2 ms_ptr pointer,
2 ms_len fixed bin (24),
2 sender_id char (32) unaligned,
2 level fixed bin,
2 ms_id bit (72),
2 sender_authorization bit (72),
2 access_class bit (72);

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

_______________________________ ____________________

mailbox_$incremental_read_index mailbox_$mbx_acl_add
_______________________________ ____________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$mmmbbbxxx_aaaccclll_aaadddddd

This entry point adds specified access modes to the access
control list (ACL) of the specified mailbox. If an access name
already appears on the ACL of the mailbox, its mode is changed to
the one specified by the call.

USAGE

declare mailbox_$mbx_acl_add entry (char(*), char(*), ptr, fixed
bin, fixed bin(35));

call mailbox_$mbx_acl_add (dir_name, entry_name, acl_ptr,
acl_count, code);

ARGUMENTS

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

entry_name
is the entry name of the mailbox. (Input)

acl_ptr
points to a user-filled segment_acl_array structure (see
"Entry Information" below). (Input)

acl_count
contains the number of ACL entries in the segment_acl_array
structure (see "Entry Information" below). (Input)

ENTRY INFORMATION

The segment_acl_array structure should be declared in the
following way:

dcl 1 segment_acl_array (acl_count) aligned like
segment_acl_entry;

The segment_acl_entry structure (declared in the include file
acl_structures.incl.pl1) is as follows:

____________________ ____________________

mailbox_$mbx_acl_add mailbox_$mbx_acl_add
____________________ ____________________

dcl 1 segment_acl_entry aligned based,
2 access_name char(32) unaligned,
2 mode bit(36) aligned,
2 extended_mode bit(36) aligned,
2 status_code fixed bin(35);

STRUCTURE ELEMENTS

access_name
is the access name (in the form Person_id.Project_id.tag) that
identifies the processes to which this ACL entry applies.

mode
should contain the value "0"b.

extended_mode
contains the extended modes for this access name. The include
file mseg_access_mode_values.incl.pl1 defines mnemonics for
these values:

dcl (MSEG_A_ACCESS initial ("400000000000"b3),
MSEG_D_ACCESS initial ("200000000000"b3),
MSEG_R_ACCESS initial ("100000000000"b3),
MSEG_O_ACCESS initial ("040000000000"b3),
MSEG_S_ACCESS initial ("020000000000"b3),
MSEG_W_ACCESS initial ("010000000000"b3),
MSEG_U_ACCESS initial ("004000000000"b3))
bit (36) aligned static options (constant);

status_code
is a standard system status code for this ACL entry only.

NOTES

If code is returned as error_table_$argerr, then the erroneous
ACL entries in the segment_acl structure have status_code set to
an appropriate error code. No processing is performed.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
mailbox. The authorization of the calling process must be equal
to the access class of the parent of the mailbox.

____________________ _______________________

mailbox_$mbx_acl_add mailbox_$mbx_acl_delete
____________________ _______________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$mmmbbbxxx_aaaccclll_dddeeellleeettteee

This entry point deletes specified entries from an access control
list (ACL) for a mailbox.

USAGE

declare mailbox_$mbx_acl_delete entry (char(*), char(*), ptr,
fixed bin, fixed bin(35));

call mailbox_$mbx_acl_delete (dir_name, entryname, acl_ptr,
acl_count, code);

ARGUMENTS

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

entryname
is the entryname of the mailbox. (Input)

acl_ptr
points to a user-filled delete_acl_array structure (see "Entry
Information" below). (Input)

acl_count
is the number of ACL entries in the delete_acl_array structure
(see "Entry Information" below). (Input)

code
is a storage system status code. (Output) It can have the
following values:
error_table_$moderr
incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.

ENTRY INFORMATION

The delete_acl_array structure should be declared in the
following way:

dcl 1 delete_acl_array (acl_count) aligned like delete_acl_entry;

The delete_acl_entry structure (declared in the include file
acl_structures.incl.pl1) is as follows:

dcl 1 delete_acl_entry aligned based,
2 access_name char(32) unaligned,
2 status_code fixed bin(35);

_______________________ _____________________

mailbox_$mbx_acl_delete mailbox_$mbx_acl_list
_______________________ _____________________

STRUCTURE ELEMENTS

access_name
is the access name (in the form of Person_id.Project_id.tag)
that identifies the ACL entry to be deleted.

status_code
is a storage system status code for this ACL entry only.

NOTES

If code is returned as error_table_$argerr, then the erroneous
ACL entries in the delete_acl_array structure have status_code
set to an appropriate error code. No processing is performed.

If an access name cannot be matched to a name already on the ACL
of the mailbox, then the status_code for that ACL entry in the
delete_acl_array structure is set to error_table_$user_not_found.
Processing continues to the end of the delete_acl_array structure
and code is returned as 0.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
mailbox. The authorization of the calling process must equal the
access class of the parent of the mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$mmmbbbxxx_aaaccclll_llliiisssttt

This entry point is used either to list the entire access control
list (ACL) of a mailbox or to return the access modes of
specified ACL entries. The segment_acl_array structure used by
this entry point is discussed in the description of
mailbox_$mbx_acl_add.

USAGE

declare mailbox_$mbx_acl_list entry (char(*), char(*), ptr, fixed
bin, ptr, fixed bin(35));

call mailbox_$mbx_acl_list (dir_name, entryname, user_acl_ptr,
user_acl_count, area_ptr, code);

ARGUMENTS

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

_____________________ _____________________

mailbox_$mbx_acl_list mailbox_$mbx_acl_list
_____________________ _____________________

entryname
is the entryname of the mailbox. (Input)

user_acl_ptr
points to an ACL structure, segment_acl_array, which contains
mode information. (Input or Output)
Input (area_ptr is null)
points to a structure supplied by the caller, containing
access names about which information is to be returned in
that same structure.
Output (area_ptr is not null)
points to a structure allocated in the area pointed to by
area_ptr into which mode information for all access names
is placed.

user_acl_count
is the number of entries in the ACL structure. (Input or
Output)
Input
is the number of entries in the ACL structure identified by
user_acl_ptr.
Output
is the number of entries in the segment_acl_array structure
allocated in the area pointed to by area_ptr, if area_ptr
is not null.

area_ptr
points to an area in which the list of ACL entries, which make
up the entire ACL of the mailbox, is allocated. (Input) If
area_ptr is null, then the user wants access modes for certain
ACL entries; these will be specified by the structure pointed
to by user_acl_ptr.

NOTES

If user_acl_ptr is used to obtain modes for specified access
names (rather than for all access names on a mailbox), then each
ACL entry in the segment_acl_array structure either has
status_code set to 0 and contains the mailbox's mode or has
status_code set to error_table_$user_not_found and contains a
mode of 0.

_____________________ ________________________

mailbox_$mbx_acl_list mailbox_$mbx_acl_replace
_____________________ ________________________

ACCESS REQUIRED

The calling process must have modify access to the parent of the
mailbox. The authorization of the calling process must dominate
the access class of the parent of the mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$mmmbbbxxx_aaaccclll_rrreeeppplllaaaccceee

This entry point replaces an entire access control list (ACL) for
a mailbox with a user-provided ACL, and can optionally add an
entry for *.SysDaemon.* with mode rw to the new ACL. The
segment_acl_array structure described in mailbox_$mbx_acl_add is
used by this entry point.

USAGE

declare mailbox_$mbx_acl_replace entry (char(*), char(*), ptr,
fixed bin, fixed bin(35));

call mailbox_$mbx_acl_replace (dir_name, entryname, acl_ptr,
acl_count, code);

ARGUMENTS

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

entryname
is the entryname of the mailbox. (Input)

acl_ptr
points to the user supplied segment_acl_array structure that
is to replace the current ACL. (Input)

acl_count
is the number of entries in the segment_acl_array structure.
(Input)

________________________ _____________

mailbox_$mbx_acl_replace mailbox_$open
________________________ _____________

NOTES

If acl_count is zero, then the existing ACL is deleted. If
acl_count is greater than zero, processing of the
segment_acl_array entries is performed top to bottom, allowing
later entries to overwrite previous ones if the access_name in
the segment_acl_array structure is identical.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
mailbox. The authorization of the calling process must be equal
to the access class of the parent of the mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$ooopppeeennn

The open entrypoint associates a specified mailbox with a message
segment index, allowing for more efficient processing of mailbox
functions during subsequent calls to mailbox_.

USAGE

declare mailbox_$open entry (char (*), char (*), fixed bin, fixed
bin (35));

call mailbox_$open (dir_name, entry_name, mseg_index, code);

ARGUMENTS

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

entry_name
is the name of the mailbox. (Input)

mseg_index
is a value which will identify the mailbox until a call to
mailbox_$close is performed. (Output)

_____________ _____________________

mailbox_$open mailbox_$open_if_full
_____________ _____________________

ACCESS REQUIRED

The calling process must have non-null extended access to the
mailbox. The authorization of the calling process must dominate
the access class of the parent directory. The authorization of
the calling process must be dominated by the access class of the
mailbox.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$ooopppeeennn_iiifff_fffuuullllll

This entrypoint opens a mailbox for use by the caller if there is
at least one accessible message in the mailbox.

USAGE

declare mailbox_$open_if_full entry (char(*), char(*), bit(1)
aligned, fixed bin, fixed bin, fixed bin(35));

call mailbox_$open_if_full (dir_name, entry_name, salv_bit,
message_count, mseg_index, code);

ARGUMENTS

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

entry_name
is the name of the mailbox. (Input)

salv_bit
is the value of the salvaged bit for the mailbox. (Output)

message_count
is the number of messages accessible to the calling process.
(Output)

mseg_index
is the index. (Output)

_____________________ ___________________________

mailbox_$open_if_full $own_incremental_read_index
_____________________ ___________________________

ACCESS REQUIRED

The calling process must have "s" extended access to the mailbox
in order to open it and obtain the values of the salvaged bit and
message count; otherwise, the calling process must have non-null
extended access to the mailbox to simply open it. The
authorization of the calling process must dominate the access
class of the parent of the mailbox. The authorization of the
calling process must be dominated by the access class of the
mailbox.

NOTES

A code of error_table_$moderr will be returned and the mailbox
will be opened if the user has non-null extended access but lacks
"S" access.

________________________________________

NNNaaammmeee::: $$$ooowwwnnn_iiinnncccrrreeemmmeeennntttaaalll_rrreeeaaaddd_iiinnndddeeexxx

The own_incremental_read_index entrypoint obtains a message
originally added to a mailbox by the user, relative to the
message specified in the argument list.

USAGE

declare mailbox_$own_incremental_read_index entry (fixed bin,
ptr, bit(2) aligned, bit(72) aligned, ptr, fixed bin(35));

call mailbox_$own_incremental_read_index (mseg_index, area_ptr,
direction, message_id, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox from which the message is to be
obtained. (Input)

area_ptr
is a pointer to an area where mailbox_ can allocate the
message. (Input)

direction
is a bit string specifying the message to be returned,

___________________________ ___________________________

$own_incremental_read_index $own_incremental_read_index
___________________________ ___________________________

relative to that specified by the message identifier. (Input)
A value of "00"b selects the specified message. A value of
"10"b selects the message before the specified one. A value
of "01"b selects the message after the specified one.

message_id
is the identifier of the message that serves as a reference
point for the selection. (Input)

ms_arg_ptr
is a pointer to the structure mseg_return_args, which will be
filled in with information about the selected message.
(Input)

ACCESS REQUIRED

The caller must have either "r" or "o" extended access to the
mailbox to read a message from it. The authorization of the
caller must both dominate the access class of the parent of the
mailbox and dominate the access class of the message for the
message to be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

___________________________ _______________________

$own_incremental_read_index mailbox_$own_read_index
___________________________ _______________________

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$ooowwwnnn_rrreeeaaaddd_iiinnndddeeexxx

The own_read_index entrypoint returns a message originally added
by the user from a mailbox.

USAGE

declare mailbox_$own_read_index entry (fixed bin, ptr, bit(1)
aligned, ptr, fixed bin(35));

call mailbox_$own_read_index (mseg_index, area_ptr,
message_wanted, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from mailbox_$open, identifying the
mailbox from which the message is to be obtained. (Input)

area_ptr
is a pointer to an area where mailbox_ can allocate the
message. (Input)

_______________________ _______________________

mailbox_$own_read_index mailbox_$own_read_index
_______________________ _______________________

message_wanted
is a flag indicating which message is wanted. (Input) If
"0"b, the first message found is returned; if "1"b, the last
is returned.

ms_arg_ptr
is a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

ACCESS REQUIRED

The caller must have either "r" or "o" extended access to the
mailbox to read its own message. The authorization of the caller
must both dominate the access class of the parent of the mailbox
and dominate the access class of the message to be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

_______________________ __________________________

mailbox_$own_read_index mailbox_$read_delete_index
_______________________ __________________________

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$rrreeeaaaddd_dddeeellleeettteee_iiinnndddeeexxx

The read_delete_index entrypoint returns a message from a mailbox
and deletes it from the mailbox.

USAGE

declare mailbox_$read_delete_index entry (fixed bin, ptr, bit(1)
aligned, ptr, fixed bin(35));

call mailbox_$read_delete_index (mseg_index, area_ptr,
message_wanted, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from mailbox_$open, identifying the
mailbox from which the message is to be obtained and
subsequently deleted. (Input)

area_ptr
is a pointer to an area where mailbox_ can allocate the
message. (Input)

message_wanted
is a flag indicating which message is wanted. (Input) If
"0"b, the first message found is returned; if "1"b, the last
is returned.

__________________________ __________________________

mailbox_$read_delete_index mailbox_$read_delete_index
__________________________ __________________________

ms_arg_ptr
os a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

ACCESS REQUIRED

The calling process must have both "r" and "d" extended access to
the mailbox in order to read and delete a message. The
authorization of the process must dominate the access class of
the parent of the mailbox and must be dominated by the access
class of the mailbox. In addition, the authorization of the
calling process must be equal to the access class of the message
to be read and deleted. If the process authorization dominates
the message access class, then the code
error_table_$ai_restricted will be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

__________________________ ___________________

mailbox_$read_delete_index mailbox_$read_index
__________________________ ___________________

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$rrreeeaaaddd_iiinnndddeeexxx

The read_index entrypoint returns a message from a mailbox.

USAGE

declare mailbox_$read_index entry (fixed bin, ptr, bit(1)
aligned, ptr, fixed bin(35));

call mailbox_$read_index (mseg_index, area_ptr, message_wanted,
ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox from which a message is to be
obtained. (Input)

area_ptr
is a pointer to an area where mailbox_ can allocate the
message. (Input)

message_wanted
is a flag indicating which message is wanted. (Input) If
"0"b, the first message found is returned; if "1"b, the last
is returned. is a flag indicating which message is wanted.
(Input) If "0"b, the first message found is returned; if "1"b,
the last is returned.

___________________ ___________________

mailbox_$read_index mailbox_$read_index
___________________ ___________________

ms_arg_ptr
is a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

ACCESS REQUIRED

The caller must have "r" extended access to the mailbox to read a
message. The authorization of the caller must both dominate the
access class of the parent of the mailbox and dominate the access
class of the message to be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

___________________ __________________________

mailbox_$read_index mailbox_$read_message_file
___________________ __________________________

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$rrreeeaaaddd_mmmeeessssssaaagggeee_fffiiillleee

The read_message_file entrypoint allows the caller to read a
message from a mailbox, optionally reading its own messages
and/or deleting the message just read. The behavior of this
entrypoint is controlled by an input structure.

USAGE

declare mailbox_$read_message_file entry (char (*), char (*),
ptr, ptr, fixed bin(35));

call mailbox_$read_message_file (dir_name, entry_name, area_ptr,
mseg_message_info_ptr, code);

ARGUMENTS

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

entry_name
is the name of the mailbox. (Input)

area_ptr
is a pointer to an area where mailbox_ can allocate the
message text. (Input)

mseg_message_info_ptr
is a pointer to the structure "mseg_message_info", described
below. (Input)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$moderr

__________________________ __________________________

mailbox_$read_message_file mailbox_$read_message_file
__________________________ __________________________

incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$no_message
no message available with desired characteristics.

ACCESS REQUIRED

The calling process must have the following effective extended
access to the mailbox: "r" to read an arbitrary message; "o" or
"r" to read its own message; "d" to delete an arbitrary message;
"o" or "d" to delete its own message. The authorization of the
calling process must dominate the access class of the parent of
the mailbox. To delete a message, the authorization of the
process must be dominated by the access class of the mailbox. In
addition, the authorization of the process must dominate the
access class of the message to be read, and be equal to the
access class of the message to be deleted.

NOTES

The structure "mseg_message_info" is declared in the include file
mseg_message_info.incl.pl1, and defined as follows:

dcl mseg_message_info_ptr pointer;
dcl 1 mseg_message_info based
(mseg_message_info_ptr) aligned,
2 version char (8) aligned,
2 message_code fixed bin,
2 control_flags unaligned,
3 own bit (1),
3 delete bit (1),
3 pad bit (34),
2 ms_ptr ptr,
2 ms_len fixed bin (24),
2 ms_id bit (72),
2 ms_access_class bit (72),
2 sender_id char (32) unaligned,
2 sender_process_id bit (36) aligned,
2 sender_level fixed bin,
2 sender_authorization bit (72),
2 sender_max_authorization bit (72),
2 sender_audit bit (36);

__________________________ __________________________

mailbox_$read_message_file mailbox_$read_message_file
__________________________ __________________________

declare MSEG_MESSAGE_INFO_V1
char (8) aligned init ("msegmi01")
int static options (constant);
declare (
MSEG_READ_FIRST init (1),
MSEG_READ_LAST init (2),
MSEG_READ_SPECIFIED init (3),
MSEG_READ_BEFORE_SPECIFIED init (4),
MSEG_READ_AFTER_SPECIFIED init (5))
fixed bin int static options (constant);
declare (
MSEG_READ_OWN init ("1"b),
MSEG_READ_DELETE init ("01"b)
) bit (36)
aligned internal static options (constant);
Where:

version Is the version of this structure. The caller must set
this to MSEG_MESSAGE_INFO_v1.

message_code specifies which message is to be read from the
message segment. This value must be set by the caller
to one of the following named constants:
MSEG_READ_FIRST to read the first message.
MSEG_READ_LAST to read the last message.
MSEG_READ_SPECIFIED to read the message specified by
mseg_message_info.ms_id.
MSEG_READ_BEFORE_SPECIFIED to read the message previous
to the message specified by mseg_message_info.ms_id.
MSEG_READ_AFTER_SPECIFIED to read the next message
after the message specified by mseg_message_info.ms_id.

own is a flag. If set to "1"b, only messages added to the
segment by the calling user will be returned. This
must be set by the caller.

delete is a flag. If set to "1"b, the message will be deleted
after it is read out. This must be set by the caller.

ms_ptr is a pointer to the message read from the message segment.
This pointer is meaningful if and only if code is
returned 0. The message always begins on a double-word
boundary.

ms_len is the length of the message, in bits.

__________________________ ___________________________

mailbox_$read_message_file mailbox_$read_message_index
__________________________ ___________________________

access. If the message_code is
MSEG_READ_BEFORE_SPECIFIED or
MSEG_READ_AFTER_SPECIFIED, the "ms_id" is used for
comparison only and need not identify any message. On
output, it is the message id of the returned message.

ms_access_class is the access class of the message returned.

sender_id is the process group id of the process that added the
message to the segment.

sender_process_id is the process id of the process that added the
message to the segment. It may be zero to indicate
that no process id is available.

sender_level is the validation level of the process that added
the message to the segment.

sender_authorization is the authorization, including privileges,
of the process that added the message to the message
segment.

sender_max_authorization is the max authorization of the process
that added the message to the message segment.

sender_audit are the audit flags for the process sending the
message.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$rrreeeaaaddd_mmmeeessssssaaagggeee_iiinnndddeeexxx

The read_message_index entrypoint allows the caller to read a
message from a mailbox, optionally reading its own messages
and/or deleting the message just read. The behavior of this
entrypoint is controlled by an input structure.

USAGE

declare mailbox_$read_message_index entry (fixed bin, ptr, ptr,
fixed bin(35));

call mailbox_$read_message_index (mseg_index, area_ptr,
mseg_message_info_ptr, code);

___________________________ ___________________________

mailbox_$read_message_index mailbox_$read_message_index
___________________________ ___________________________

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox from which the message is to be read.
(Input)

area_ptr
is a pointer to an area where mailbox_ can allocate the
message text. (Input)

mseg_message_info_ptr
is a pointer to the structure "mseg_message_info", described
below. (Input)

ACCESS REQUIRED

NOTES

The structure "mseg_message_info" is declared in the include file
mseg_message_info.incl.pl1, and defined as follows:

dcl mseg_message_info_ptr pointer;
dcl 1 mseg_message_info based
(mseg_message_info_ptr) aligned,
2 version char (8) aligned,
2 message_code fixed bin,
2 control_flags unaligned,

___________________________ ___________________________

mailbox_$read_message_index mailbox_$read_message_index
___________________________ ___________________________

3 own bit (1),
3 delete bit (1),
3 pad bit (34),
2 ms_ptr ptr,
2 ms_len fixed bin (24),
2 ms_id bit (72),
2 ms_access_class bit (72),
2 sender_id char (32) unaligned,
2 sender_process_id bit (36) aligned,
2 sender_level fixed bin,
2 sender_authorization bit (72),
2 sender_max_authorization bit (72),
2 sender_audit bit (36);

version
Is the version of this structure. The caller must set this to
MSEG_MESSAGE_INFO_v1.

message_code
specifies which message is to be read from the message
segment. This value must be set by the caller to one of the
following named constants: MSEG_READ_FIRST to read the first
message.
MSEG_READ_LAST to read the last message.
MSEG_READ_SPECIFIED to read the message specified by
mseg_message_info.ms_id.
MSEG_READ_BEFORE_SPECIFIED to read the message previous to the
message specified by mseg_message_info.ms_id.
MSEG_READ_AFTER_SPECIFIED to read the next message after the
message specified by mseg_message_info.ms_id.

___________________________ ___________________________

mailbox_$read_message_index mailbox_$read_message_index
___________________________ ___________________________

own
is a flag. If set to "1"b, only messages added to the segment
by the calling user will be returned. This must be set by the
caller.

delete
is a flag. If set to "1"b, the message will be deleted after
it is read out. This must be set by the caller.

ms_ptr
is a pointer to the message read from the message segment.
This pointer is meaningful if and only if code is returned 0.
The message always begins on a double-word boundary.

ms_len
is the length of the message, in bits.

ms_id
is a message segment/mailbox message id. If the message_code
is MSEG_READ_SPECIFIED, this is interpreted on input, and must
be the message id of a message in the message segment to which
the caller has access. If the message_code is
MSEG_READ_BEFORE_SPECIFIED or MSEG_READ_AFTER_SPECIFIED, it is
used for comparison only and need not identify any message.
On output, it is the message id of the returned message.

ms_access_class
is the access class of the message returned.

sender_id
is the process group id of the process that added the message
to the segment.

sender_process_id
is the process id of the process that added the message to the
segment. It may be zero to indicate that no process id is
available.

sender_level
is the validation level of the process that added the message
to the segment.

sender_authorization
is the authorization, including privileges, of the process
that added the message to the message segment.

sender_max_authorization
is the max authorization of the process that added the message
to the message segment.

___________________________ ____________________________

mailbox_$read_message_index mailbox_$set_max_length_file
___________________________ ____________________________

sender_audit
are the audit flags for the process sending the message.

________________________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$ssseeettt_mmmaaaxxx_llleeennngggttthhh_fffiiillleee

The set_max_length_file entrypoint sets the maximum length of a
mailbox.

USAGE

declare mailbox_$set_max_length_file entry (char(*), char(*),
fixed bin(19), fixed bin(35));

call mailbox_$set_max_length_file (dir_name, entry_name,
max_length, code);

ARGUMENTS

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

entry_name
is the name of the mailbox. (Input)

max_length
is the new maximum length of the mailbox. (Input)

code
is a standard system standard code. (Output) It can have the
following values:
error_table_$moderr
incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
mailbox. The authorization of the calling process must be equal
to the access class of the parent of the mailbox.

____________________________ __________________________

mailbox_$set_max_length_file mailbox_$set_safety_switch
____________________________ __________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$ssseeettt_sssaaafffeeetttyyy_ssswwwiiitttccchhh

The set_safety_switch entrypoint changes the value of the safety
switch for a mailbox.

USAGE

declare mailbox_$set_safety_switch entry (char(*), char(*),
bit(1) aligned, fixed bin(35));

call mailbox_$set_safety_switch (dir_name, entry_name,
safety_switch, code);

ARGUMENTS

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

entry_name
is the name of the mailbox. (Input)

safety_switch
is the new value of the safety switch. (Input)

ACCESS REQUIRED

The calling process must have modify access to the parent of the
mailbox. The authorization of the calling process must equal the
access class of the parent of the mailbox.

__________________________ _____________________________

mailbox_$set_safety_switch mailbox_$update_message_index
__________________________ _____________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$uuupppdddaaattteee_mmmeeessssssaaagggeee_iiinnndddeeexxx

The update_message_index entrypoint changes the contents of a
message in a mailbox.

USAGE

declare mailbox_$update_message_index entry (fixed bin, fixed
bin(24), bit(72) aligned, ptr, fixed bin(35));

call mailbox_$update_message_index (mseg_index, message_len,
message_id, message_ptr, code);

ARGUMENTS

mseg_index
is the value returned from a call to mailbox_$open,
identifying the mailbox which is to have one if its messages
updated. (Input)

message_len
is the name of the mailbox. (Input)

message_id
is the identifier of the message to be modified. (Input)

message_ptr
is a pointer to the new message. (Input)

ACCESS REQUIRED

The calling process must have "d" extended access to the mailbox
to update a message. The authorization of the calling process
must dominate the parent of the mailbox that contains the message
and must be equal to the access class of the message to be
updated.

_____________________________ _________________

mailbox_$update_message_index mailbox_$validate
_____________________________ _________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$vvvaaallliiidddaaattteee

The validate entrypoint determines whether or not a given entry
is a mailbox.

USAGE

declare mailbox_$validate entry (char(*), char(*), fixed
bin(35));

call mailbox_$validate (dir_name, entry_name, code);

ARGUMENTS

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

entry_name
is the name of the potential mailbox. (Input)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$not_seg_type
the entry is not a mailbox.
error_table_$no_info
no information on the entry is available.

ACCESS REQUIRED

NOTES

For an entry to be considered a mailbox, it must have the "mbx"
suffix and have ring brackets of (1, 1, 1).

_________________ _________________________

mailbox_$validate mailbox_$wakeup_add_index
_________________ _________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$wwwaaakkkeeeuuuppp_aaadddddd_iiinnndddeeexxx

The wakeup_add_index entrypoint adds a message to a mailbox and
sends the process receiving messages through the mailbox a
wakeup.

USAGE

declare mailbox_$wakeup_add_index entry (fixed bin, ptr, fixed
bin(24), bit(36), bit(72) aligned, fixed bin(35));

call mailbox_$wakeup_add_index (mseg_index, message_ptr,
message_len, wakeup_switches, message_id, code);

ARGUMENTS

mseg_index
is the value returned froma call to mailbox_$open, identifying
the mailbox into which the message is to be placed. (Input)

message_ptr
is a pointer to an arbitrary bit string, which is the text of
the message. (Input)

message_len
is the length of the message in bits. (Input)

wakeup_switches
is an array of switches specifying the disposition of the
wakeup and message. (Input) See "Notes" below.

message_id
is a value identifying the message in the mailbox, which can
be used to reference the message in subsequent calls to
mailbox_. (Output)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$no_append
lack of "a" extended access prevents performing the
operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$wakeup_denied
insufficient access to send a wakeup.
error_table_$no_info
no information can be returned because of authorization of
recipient.

_________________________ _________________________

mailbox_$wakeup_add_index mailbox_$wakeup_add_index
_________________________ _________________________

ACCESS REQUIRED

NOTES

The wakeup_switches structure is defined as follows:

declare 1 wakeup_switches aligned
2 normal_wakeup bit (1) unaligned,
2 urgent_wakeup bit (1) unaligned,
2 always_add bit (1) unaligned,
2 never_add bit (1) unaligned,
2 pad bit (1) unaligned;

where:

normal_wakeup indicates that the caller wants to send a
normal wakeup.

urgent_wakeup indicates that the caller wants to send an
urgent wakeup if
sending a normal one is not possible.

always_add indicates that the message is to be added to the
mailbox
regardless of the ability to send a wakeup.

never_add indicates that the message is not to be added, even
if all
access checks pass.

_________________________ _____________________________

mailbox_$wakeup_add_index mailbox_$wakeup_aim_add_index
_________________________ _____________________________

NNNaaammmeee::: mmmaaaiiilllbbboooxxx_$$$wwwaaakkkeeeuuuppp_aaaiiimmm_aaadddddd_iiinnndddeeexxx

The wakeup_aim_add_index entrypoint adds a message to a mailbox
and sends the process receiving messages through the mailbox a
wakeup.

USAGE

declare mailbox_$wakeup_aim_add_index entry (fixed bin, ptr,
fixed bin(24), bit(36), bit (72) aligned, bit(72) aligned,
fixed bin(35));

call mailbox_$wakeup_aim_add_index (mseg_index, message_ptr,
message_len, wakeup_switches, message_access_class,
message_id, code);

ARGUMENTS

mseg_index
is the value returned froma call to mailbox_$open, identifying
the mailbox into which the message is to be placed. (Input)

message_ptr
is a pointer to an arbitrary bit string, which is the text of
the message. (Input)

message_len
is the length of the message in bits. (Input)

wakeup_switches
is an array of switches specifying the disposition of the
wakeup and message. (Input) See the wakeup_add_index
entrypoint for a discussion of these switches.

message_access_class
is the access class that the message shall assume. (Input)

message_id
is a value identifying the message in the mailbox, which can
be used to reference the message in subsequent calls to
mailbox_. (Output)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$no_append
lack of "a" extended access prevents performing the
operation.

_____________________________ _____________________________

mailbox_$wakeup_aim_add_index mailbox_$wakeup_aim_add_index
_____________________________ _____________________________

error_table_$wakeup_denied
insufficient access to send a wakeup.
error_table_$no_info
no information can be returned because of authorization of
recipient.

ACCESS REQUIRED

The calling process must have "a" extended access to the mailbox
to add a message and must have "w" or "u" extended access to the
mailbox to send a normal or urgent wakeup, respectively. The
access class of the message must dominate the access class of the
parent of the mailbox. The access class of the message must be
dominated by the access class of the mailbox segment. The
authorization of the calling process must dominate the access
class of the parent of the mailbox. The authorization of the
calling process must be dominated by the access class of the
mailbox. The authorization of the process must be dominated by
the access class of the message. The maximum authorization of
the calling process must dominate the access class of the
message. The authorization of the caller must be dominated by
the access class of the receiver if and only if a wakeup is to be
sent (i.e., if either normal_wakeup or urgent_wakeup is set in
wakeup_switches).

NOTES

The wakeup_switches structure is defined as follows:

declare 1 wakeup_switches aligned
2 normal_wakeup bit (1) unaligned,
2 urgent_wakeup bit (1) unaligned,
2 always_add bit (1) unaligned,
2 never_add bit (1) unaligned,
2 pad bit (1) unaligned;

where:

normal_wakeup indicates that the caller wants to send a
normal wakeup.

urgent_wakeup indicates that the caller wants to send an
urgent wakeup if sending a normal one is not possible.

always_add indicates that the message is to be added to the
mailbox regardless of the ability to send a wakeup.

never_add indicates that the message is not to be added, even
if all access checks pass.

_____________________________ ____

mailbox_$wakeup_aim_add_index mca_
_____________________________ ____

NNNaaammmeee::: mmmcccaaa_

EEEnnntttrrryyy::: mmmcccaaa_$$$aaarrreeeaaa

MCA Area Structure:

The mca_area_ptr points to a structure which defines the format
of the data filled in by the mca_ module when I/O between the
attached MCA and Multics has completed. This area is only used
when the user has specified an event channel to be notified
through. The structure is declared in mca_area.incl.pl1.

dcl 1 mca_area aligned based (mca_area_ptr),
2 version char (8),
2 io_outstanding bit (1) aligned,
2 mca_attach_state fixed bin (17),
2 mca_status bit (72),
2 ret_len fixed bin (21);

dcl mca_area_ptr ptr;

dcl MCA_area_version_1 char (8) int static options
(constant) init ("MCA00001");

STRUCTURE ELEMENTS

version
Is the version number of the structure. The current version
is MCA00001.

io_outstanding
This will indicate the status of the maintenance session.
Will be false if the requested task has been completed. If
true, the task is not complete and the user will be required
to call this entry again upon completion of the next I/O.

mca_attach_state
This will contain the current attachment state. 1 =
"Attaching", which means that the mca modules are still in the
process of attaching the mca (doing the reset & read-config
IO). 2 = "Attached", which means that the mca is now fully
attached.

mca_status
Is the status returned by the MCA upon completion of the
request.

____ ____

mca_ mca_
____ ____

ret_len
Is the number of characters placed in the user area.

EEEnnntttrrryyy::: mmmcccaaa_$$$aaattttttaaaccchhh_iiipppccc

This entry will be used to attach a selected IPC to a user
process. The user must have previously attached the MCA, that
will communicate with the IPC.

USAGE

dcl mca_$attach_ipc entry (char (*), fixed bin, fixed bin,
fixed bin (35));

call mca_$attach_ipc (ipc_id, mca_ioi_idx, ipc_num, code);

ARGUMENTS

ipc_id
IPC name to be attached. The name must be either the form
"ipcN", where N would be the IPC number 0 through 15, or
"ICC", where "I" would be the tag of the MCA (i.e. A, B, C or
D) and CC would be a channel number that is assigned to the
IPC. (Input)

mca_ioi_idx
IOI index value that was returned when MCA was attached.
(Input)

ipc_num
The real IPC number (0 - 15) that was attached. This is the
number to be used with the load and reset entries. (Output)

code
Will be zero if attachment was successful, else a standard
system status code will be returned. (Output)

NOTES

When an IPC is attached, it is sometimes necessary to suspend all
system I/O through all the logical channels. If required, this
entry will attempt to perform this task. If it is not possible
to suspend the I/O, the IPC will NOT be attached and an error
code returned.

____ ____

mca_ mca_
____ ____

EEEnnntttrrryyy::: mmmcccaaa_$$$aaattttttaaaccchhh_mmmcccaaa

This entry will be used to attach a selected MCA to a user
process.

USAGE

dcl mca_$attach_mca entry (char (*), fixed bin (71), fixed bin,
fixed bin (35));

call mca_$attach_mca (mca_id, mca_ev_chn, mca_ioi_idx, code);

ARGUMENTS

mca_id
MCA name to be attached. The name must be in the form "mcaX",
where X will be equal to the letter of the IMU the MCA is in
(a, b, c, or d). (Input)

mca_ev_chn
Event channel that will be used to signal completion of MCA
I/O. If it is a value other than 0 or 1, then completion of
the I/O for this MCA will be handled using the event method
and it will be required for the user to call
mca_$process_io_event for each I/O completion, until the task
is complete including the attachment task. Otherwise all
entries that perform I/O will use ipc_$block to wait for the
I/O to complete before returning from the call. The process
will go blocked in ring_1 for this case. (Input)

mca_ioi_idx
IOI index value that will be returned when the MCA is
successfully attached. (Output)

code
Will be a standard system status code. (Output)

EEEnnntttrrryyy::: mmmcccaaa_$$$cccooonnnfffiiiggg

This entry will return the contents of the IMU configuration data
currently residing in the MCA's RAM. The user will need to
provide sufficient space, defined by ret_ptr, to hold the the
information. The configuration data will be defined in a system
include file.

USAGE

dcl mca_$config entry (fixed bin, ptr, fixed bin (21),
fixed bin (21) bit (36), fixed bin (35));

____ ____

mca_ mca_
____ ____

call mca_$config (mca_ioi_idx, ret_ptr, ret_size, ret_len
mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

ret_ptr
User area to return configuration data. (Input)

ret_size
Maximum size of user area in characters. (Input)

ret_len
Actual number characters placed in the users area. (Output)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).

code
Will be a standard system status code. (Output)

NOTES

The entry mca_$read_data must also be called after receiving the
requested data to terminate the "session". Refer to section 4
(Miscellaneous MCA Operations) for details.

EEEnnntttrrryyy::: mmmcccaaa_$$$cccooonnnfffiiiggg_fffiiillleee

The following structure was built based on data obtained from the
EPS-1 "Dipper Firmware Loading" Rev B section 3.5.1 starting on
sheet 25. The structure is declared in mca_config_file.incl.pl1.

dcl mca_config_file_ptr ptr;

dcl 1 mca_config_file based (mca_config_file_ptr),
2 diskette_data,
/* total of 20 chars (bytes) */
3 unique_id char (8),
/* User ID assiged to diskette from which FW was loaded */
3 date_created char (6),

____ ____

mca_ mca_
____ ____

/* MMDDYY */
3 date_late_changed char (6),
/* MMDDYY */
2 iioc_data,
/* total of 31 chars (bytes) */
3 iioc_config char (8),
/* mca path_name of file used to load from */
3 iioc_state_control,
4 will_be_zero_1 bit (1),
/* zero because of 8 bit-byte to 9 bit-byte */
4 state_counter fixed bin (5) unsigned unal,
/* values are not defined */
4 RFU_1 bit (1),
4 RFU_2 bit (1),
4 write_protect_ptw_sw bit (1),
3 operating_system fixed bin (9) unal unsigned,
/* better be a value equal to Multics */
3 iioc_num fixed bin (9) unal unsigned,
/* the number of the imu */
3 iioc_disk_tab fixed bin (9) unal unsigned,
/* The value of the TAB number of the Diskette_Product_Set
containing the proper revision of diagnostics for IMU */
3 p_s_disk_tab fixed bin (9) unal unsigned,
/* same as iioc_disk_tab only for the Port Select */
3 port_select_state fixed bin (9) unal unsigned,
/* State counter values will exists which uniquely define:
o P. S. not loaded
o Single port
o Load failed
o Read failed
o Verify failed
o P. S. loaded */
3 config_valid char (1),
/* ascii number of drive this config was read from.
if value = "000"b3 drive door has been opened. */
3 iioc_rfu char (2),
2 bootstrap_data,
/* total of 15 chars (bytes) */
3 control fixed bin (9) unal unsigned,
/* 0 = bootstrap not configured
1 = bootstrap allowed
2 = auto boot at power up */
3 imu_port_at_scu fixed bin (9) unal unsigned,
/* port number for bootstrap (0 to 7) */
3 chan_num fixed bin (9) unal unsigned,
/* bootstrap channel number (8 to 63) */
3 dev_num fixed bin (9) unal unsigned,
/* bootstrap device number (1 to 63) */
3 int_base char (4),
3 mb_base char (4),

____ ____

mca_ mca_
____ ____

3 boot_src fixed bin (9) unal unsigned,
/* bootstrap source 1=card, 2=tape, 3=disk */
3 unatt_op fixed bin (9) unal unsigned,
/* 1 = unattended operation */
3 boot_rfu bit (9),
2 port_data (0:3),
/* total 28 chars (bytes) */
3 enable fixed bin (9) unal unsigned,
/* 1 = port enable */
3 init fixed bin (9) unal unsigned,
/* 1 = init allowed */
3 ilace char (1),
/* no interlace = "000"b3,
A,B,C,D = the other port for interlace */
3 port_size,
4 msb_ign1 bit (1),
4 msb bit (8),
4 lsb_ign1 bit (1),
4 lsb bit (8),
3 disk_tab fixed bin (9) unal unsigned,
/* value of TAB number of the D_P_S containing the proper
revision of diagnostics for port adapter. */
3 assignment fixed bin (9) unal unsigned,
/* (0 - 3) */
2 channel_data (0:15),
/* total of 160 bytes */
3 lvl_1_state fixed bin (9) unal unsigned,
/* State counter values define:
= No config present
= Not configured
= Physically not present
= Basic ROM test failed (mico IPCs only)
= Jam test failed (mico IPCs only)
= Self test failed (mico IPCs only)
= HW ID does not match config ID
= Console set up failed (console only)
= RSO failed (PSIA only)
= FW not found on diskette (FW loadable IPCS only)
= Alter file not found
= Alter load failed
= FW execute failed (FW loadable IPCS only)
= Operational
= Stop On condition occured */
3 lvl_1_ctl_att,
4 ctl_ign1 bit (1),
4 ctl1 bit (1),
/* if master console true = rmt_maint
else true = RSO required at init */
4 ctl2 bit (1),
/* if master console true = master

____ ____

mca_ mca_
____ ____

else reserved of future use */
4 ctl3 bit (1),
/* if master console true = active/slave
else true = 18X */
4 ctl_p2 bit (5),
3 disk_tab fixed bin (9) unal unsigned,
/* Tab number of the D_P_S containing the proper
revision of diagnostics for this adapter */
3 fw_id_ign1 bit (1),
3 fw_id bit (8),
3 lvl_1_id_ign1 bit (1),
3 no_lev_2 bit (1),
/* true = Do not ask for lvl-2 info. */
3 micro_ctl bit (1),
/* true = micro-procesor controled */
3 fbus_latch bit (1),
/* true = F-Bus Disable Latch is true */
3 lvl_1_id_type fixed bin (5) unsigned unal,
/* unique Lvl-1 type */
3 fw_rev char (1),
3 prim_ch_num fixed bin (9) unal unsigned,
/* primary channel number (8 to 63) */
3 num_of_log_ch fixed bin (9) unal unsigned,
/* number of logical channels */
3 num_of_busses fixed bin (9) unal unsigned,
/* number of data busses */
3 cont_byte_ign1 bit (1),
3 cont_byte_rfu bit (5),
3 cont_byte_soc bit (1),
/* true = Stop-On-Condition present */
3 cont_byte_mpfp bit (1),
/* true = maint. panel function present */
3 cont_byte_mc bit (1),
/* true = has been set to Master Console */
2 adapter_data (0:15, 0:7),
3 lvl_2_state fixed bin (9) unal unsigned,
3 lvl_2_clt_att fixed bin (9) unal unsigned,
3 disk_tab fixed bin (9) unal unsigned,
3 fw_idfixed bin (9) unal unsigned,
3 lvl_2_id fixed bin (9) unal unsigned,
3 fw_rev_ign1 bit (1),
3 fw_rev bit (8),
3 rfu bit (1),
2 uses_less_data char (200);

____ ____

mca_ mca_
____ ____

EEEnnntttrrryyy::: mmmcccaaa_$$$dddeeetttaaaccchhh_iiipppccc

This entry will be used to detach a IPC that is currently
attached to a user process.

USAGE

dcl mca_$detach_ipc entry (char (*), fixed bin, bit (1),
fixed bin (35));

call mca_$detach_ipc (ipc_id, mca_ioi_idx, ipc_operational,
code);

ARGUMENTS

ipc_id
IPC name to be detached. The name must be either the form
"ipcN", where N would be the IPC number 0 through 15, or
"ICC", where "I" would be the tag of the MCA (i.e. A, B, C or
D) and CC would be a channel number that is part of the IPC.
(Input)

mca_ioi_idx
IOI index value that was returned when MCA was attached.
(Input)

ipc_operational
This bit controls the release of I/O that has been suspended
through the IPC. If the bit is true, then then IPC is
considered operational and the I/O will be released (if it had
been suspended). Otherwise the I/O will remain suspended and
the operator will be notified that the I/O was not released.
(Input)

code
Will be a standard system status code. (Output)

EEEnnntttrrryyy::: mmmcccaaa_$$$dddeeetttaaaccchhh_mmmcccaaa

This entry will be used to detach the currently attached MCA from
a user process.

USAGE

dcl mca_$detach_mca entry (fixed bin, fixed bin (35));

call mca_$detach_mca (mca_ioi_idx, code);

____ ____

mca_ mca_
____ ____

mca_ioi_idx
IOI index value that was returned when MCA was attached.
(Input)

code
Will be a standard system status code. (Output)

NOTES

If any IPCs on the MCA are attached they will be detached before
the MCA is detached.

EEEnnntttrrryyy::: mmmcccaaa_$$$dddiiissskkkeeetttttteee

This is the definition of the data returned by the MCA when
either reading the diskette header, directory or files. The
structure is declared in mca_diskette.incl.pl1.
dcl header_ptr ptr;

dcl 1 header based (header_ptr),
2 copyright char (55),
2 title char (8),
2 unique_id char (8),
2 date_created char (6),
2 date_changed char (6),
2 space_adr bit (18) unal,
2 space_x bit (18) unal,
2 space_size bit (18) unal,
2 dir_adr bit (18) unal,
2 dir_x bit (18) unal,
2 dir_size like two_byte,
2 config_name char (8),
2 config_count fixed bin (9) unal unsigned,
2 disk_type fixed bin (9) unal unsigned,
2 val fixed bin (9) unal unsigned,
2 equip_type char (4),
2 ipi_num char (12),
2 disk_dwg_num char (12),
2 prod_num_tab char (3),
2 x_of_n bit (18) unal;

dcl dir_ptr ptr;
dcl dire_ptr ptr;
dcl dir_number fixed bin;

dcl 1 directory based (dir_ptr),
2 array (dir_number) like dire;

____ ____

mca_ mca_
____ ____

dcl two_byte_ptr ptr;

dcl 1 two_byte based (two_byte_ptr) unal,
2 pad1 bit (1) unal,
2 lsb bit (8) unal,
2 pad2 bit (1) unal,
2 msb bit (8) unal;

dcl 1 dire based (dire_ptr),
2 path_name char (8),
2 sector_address like two_byte,
2 file_size like two_byte,
2 rfu like two_byte,
2 attributes bit (8) unal,
2 deleted bit (1) unal,
2 rfu1 char (1);

dcl file_ptr ptr;
dcl file_size fixed bin (21);
dcl 1 hex_file based (file_ptr),
2 hex_data (file_size) like two_byte;

EEEnnntttrrryyy::: mmmcccaaa_$$$dddiiissskkkeeetttttteee_rrreeeaaaddd

This entry will allow selected information from one of the two
diskette devices to be returned to the caller.

USAGE

dcl mca_$diskette_read entry (fixed bin, char (*), fixed bin,
ptr, fixed bin (21), fixed bin (21), bit (36),
fixed bin (35));

call mca_$diskette_read (mca_ioi_idx, read_type, disk_num,
ret_ptr, ret_size, ret_len, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

read_type
Defines what information is to be returned. The input will be
passed to the MCA without alteration.(Input)
Valid inputs are:

"DIRECTORY" This will return the directory contents from
the selected diskette.

____ ____

mca_ mca_
____ ____

"HDR" This will return the contents of the
diskette header.

P=file_name This will return the contents of the
requested file_name.

VID/file_name The MCA will return file_name data, only if
a diskette labeled VID is mounted in either
of the 2 diskette devices. The disk_num
argument will not be used.

disk_num
This will define which diskette device to read the selected
data from. Valid values are 0 and 1. (Input)

ret_ptr
User area to return data. (Input)

ret_size
Maximum size of user area in characters. (Input)

ret_len
Actual number characters placed in the users area. (Output)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O.

code
Will be a standard system status code. (Output)

NOTES

The entry mca_$read_data must also be called after receiving the
requested data to terminate the "session". Refer to section 4
(Miscellaneous MCA Operations) for details.

____ ____

mca_ mca_
____ ____

EEEnnntttrrryyy::: mmmcccaaa_$$$dddiiisssppplllaaayyy

This entry will allow a user to extract the contents of the
ring-1 control segment, mca_data_seg, for examination.

USAGE

dcl mca_$display entry (ptr, fixed bin (21), fixed bin (21),
fixed bin (35));

call mca_$display (ret_ptr, ret_size, ret_len, code);

ARGUMENTS

ret_ptr
User area to return data. (Input)

ret_size
Maximum size of user area in characters. If this is less than
the size of the mca data, then only ret_size characters will
be returned. (Input)

ret_len
Actual number characters placed in the users area. (Output)

code
Will be a standard system status code. (Output)

EEEnnntttrrryyy::: mmmcccaaa_$$$llloooaaaddd_iiipppccc

This entry will allow the requested IPC to have its internal
firmware reloaded from the MCA diskette and reset to a
initialized state.

USAGE

dcl mca_$load_ipc (fixed bin, fixed bin, bit (36),
fixed bin (35));

call mca_$load_ipc (mca_ioi_idx, ipc_number, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

ipc_number
The IPC number to be acted on (returned by mca_$attach_ipc).
(Input)

____ ____

mca_ mca_
____ ____

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

This will only be valid when the MCA is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).

code
Will be a standard system status code. (Output)

NOTES

It will be necessary to attach an IPC, using the mca_$attach_ipc,
before invoking this entry. Otherwise an error code will be
returned.

EEEnnntttrrryyy::: mmmcccaaa_$$$ppprrroooccceeessssss_iiiooo_eeevvveeennnttt

Used to notify ring 1 of the completion of an asynchronous I/O
event. It may be necessary to call this entry several times
before a task is complete. This entry must only be used when a
event channel was passed to mca_$attach_mca entry point when the
MCA was attached.

USAGE

dcl mca_$process_io_event entry (fixed bin, ptr, ptr,
fixed bin (35));

call mca_$attach_mca (mca_ioi_idx, event_call_info_ptr,
mca_area_ptr, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

event_call_info_ptr
Pointer to the event_call_info structure returned when the
event was signalled. (Input)

mca_area_ptr
Pointer to the user supplied area for placing I/O completion
information. (Input)

code
Will be a standard system status code. (Output)

____ ____

mca_ mca_
____ ____

EEEnnntttrrryyy::: mmmcccaaa_$$$rrreeeaaaddd_dddaaatttaaa

This entry must be used in cases, such as diskette read, where
the data to be sent by the MCA is larger that the size of the
user buffer. This is indicated by the status returned for that
call. This entry reads the remaining data from the MCA and
places it in the user buffer for this call. The status returned
must be checked to see if there is more data to read. Repeated
calls to this entry must be used to read the data.

USAGE

dcl mca_$read_data entry (fixed bin, ptr, fixed bin (21),
fixed bin (21), bit (36), fixed bin (35));

call mca_$read_data (mca_ioi_idx, ret_ptr, ret_size, ret_len,
mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

ret_ptr
User area to return data. (Input)

ret_size
Maximum size of user area in characters. (Input)

ret_len
Actual number characters placed in the users area. (Output)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O.

code
Will be a standard system status code. (Output)

____ ____

mca_ mca_
____ ____

NOTES

This entry must also be used to terminate a "session", when
entries like config and diskette_read have been used. Refer to
section 4 (Miscellaneous MCA Operations) for details.

EEEnnntttrrryyy::: mmmcccaaa_$$$rrreeessseeettt

This entry will allow the user to reset the MCA to Multics
communication dialogue. This entry issues a reset_status opcode
("40"b3) to the MCA.

USAGE

dcl mca_$reset (fixed bin, bit (36), fixed bin (35));

call mca_$reset (mca_ioi_idx, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

EEEnnntttrrryyy::: mmmcccaaa_$$$rrreeessseeettt_iiipppccc

This entry will allow the requested IPC to be reset to an
initialized state.

USAGE

dcl mca_$reset_ipc (fixed bin, fixed bin, bit (36),
fixed bin (35));

call mca_$reset_ipc (mca_ioi_idx, ipc_number, mca_status, code);

____ ____

mca_ mca_
____ ____

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

ipc_number
The IPC number to be acted on (returned by mca_$attach_ipc).
(Input)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

NOTES

It will be necessary to attach an IPC, using the mca_$attach_ipc,
before invoking this entry. Otherwise an error code will be
returned.

____ ____

mca_ mca_
____ ____

EEEnnntttrrryyy::: mmmcccaaa_$$$rrreeetttuuurrrnnn_ssstttaaatttuuusss

Status Major Substatus Octal

Channel Ready 0000
Normal Termination x00000 4000 or 4040
Adapter Failure x00001 4001 or 4041
Maint. Session Normal Term. x00010 4002 or 4042
Maint. Session Abnormal Term. x00011 4003 or 4043
Response Data Present 1xxxxx *

Attention (Diskette) 0010
Write Inhibit x00001 4201 or 4241
Seek Incomplete x00010 4202 or 4242
Device Not Present x00100 4204 or 4244
Device Inoperable x01000 4210 or 4250
Device in Standby (door open) x10000 4220 or 4260

Data Alert 0011
Transmission Parity Alert x00010 4302 or 4342
Check Character Alert x10000 4320 or 4360

Command Reject 0101
Invalid Operation Code x00001 4501 or 4541

Attention (MCA) 1010
MCA Executive F/W Error x00001 5201 or 5241
MCA Overlay F/W Error x00010 5202 or 5242
Connect Time Out x10000 5220 or 5260

Data Alert (MCA) 1011
Data Overflow on Load x00110 5306 or 5346
Data Underflow on Load x00111 5307 or 5347

Command Reject (MCA) 1101
Invalid Sequence x00001 5501 or 5541
Invalid PATH_NAME x00010 5502 or 5542
Invalid Request Format x00011 5503 or 5543
Continue Bit Error x00100 5504 or 5544
Invalid Block Header x00101 5505 or 5545

* The Response Data Present bit is applicable to ALL status returns.

____ ____

mca_ mca_
____ ____

EEEnnntttrrryyy::: mmmcccaaa_$$$tttaaannndddddd_rrreeeaaaddd_dddaaatttaaa

This entry will allow the tolts subsystem to send previously
prepared IO blocks to the MCA. This entry must be used by tolts
to perform a read only operation from the MCA. This is the case
when the previous command status return indicates that the MCA
has more data to send than the tolts subsystem had reserved space
for. The IDCW and DCW will be supplied by the gated code. When
the MCA returns response data, it will be copied from the wired
block into the user area and the MCA status returned to the
caller.

USAGE

dcl mca_$tandd_read_data (fixed bin, ptr, fixed bin, bit (36),
fixed bin (35));

call mca_$tandd_read_data (mca_ioi_idx, io_block_ptr,
io_block_len, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

io_block_ptr
Tolts area that contains the IO block to be sent. (Input)
Note: The data_header_2 area will be nulled as well as data_2
the size will be set to 0. The data returned will be defined
by data_header_1 and the data returned in the data_1 area.

io_block_len
Size of tolts area in words. (Input)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

NOTES

This entry must also be used to terminate a "maintenance
session". Refer to mca_$read_data for details.

____ ____

mca_ mca_
____ ____

EEEnnntttrrryyy::: mmmcccaaa_$$$tttaaannndddddd_wwwrrriiittteee_dddaaatttaaa

This entry will allow the tolts subsystem to send previously
prepared IO blocks to the MCA. This entry will be used by tolts
to perform early communication with the MCA, prior to initiating
a test request, and to send TEST OVERLAY data to the MCA and to
maintain a response area for the MCA while a given test is being
executed. This entry will also move the IO block to a wired
area, replacing the IDCWs (15, 03) and DCWs with known good ones.
When the MCA returns response data, it will be copied from the
wired block into the user area and the MCA status returned to the
caller.

USAGE

dcl mca_$tandd_write_data (fixed bin, ptr, fixed bin, bit (36),
fixed bin (35));

call mca_$tandd_write_data (mca_ioi_idx, io_block_ptr,
io_block_len, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

io_block_ptr
Tolts area that contains the IO block to be sent. (Input)

io_block_len
Size of tolts area in words. (Input)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

____ ____

mca_ mca_
____ ____

EEEnnntttrrryyy::: mmmcccaaa_$$$tttaaannndddddd_wwwrrriiittteee_ttteeexxxttt

This entry will allow the tolts subsystem to send previously
prepared IO blocks to the MCA. This entry must be used by tolts
to initiate a IO activity with the MCA, for a given IPC. This
entry will verify that the text portion of the block only
contains the valid commands READ, RESET, LOAD or TEST and that
the IPC attached is the only adapter specified after the command
text. This entry will also move the IO block to a wired area,
replacing the IDCWs (13, 03) and DCWs with known good ones. When
the MCA returns response data, it will be copied from the wired
block into the user area and the MCA status returned to the
caller.

USAGE

dcl mca_$tandd_write_text (fixed bin, ptr, fixed bin, bit (36),
fixed bin (35));

call mca_$tandd_write_text (mca_ioi_idx, io_block_ptr,
io_block_len, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when the selected MCA was attached.
(Input)

io_block_ptr
Tolts area that contains the text IO block to be sent.
(Input)

io_block_len
Size of tolts area in words. (Input)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

____ ____

mca_ mca_
____ ____

NOTES

If the text of the I/O block specifies an IPC adapter, the
adapter must be attached to the user process. If the adapter is
not attached no I/O will be performed and an error code will be
returned.

EEEnnntttrrryyy::: mmmcccaaa_$$$wwwooorrrkkk_ssspppaaaccceee

This is the definition of the workspace used by the mca ring-1
modules when communicating with the MCA through IOI. The
structure is declared in mca_data_area.incl.pl1.

dcl data_header_ptr ptr;

dcl (data_size_1, data_size_2) fixed bin (21) init (0);

dcl io_param_blk_ptr ptr;

dcl mca_dcw_list_ptr ptr;

dcl mca_work_space_ptr ptr;

dcl 1 mca_work_space based (mca_work_space_ptr),
2 list_of_dcw like mca_dcw_list,
/* the list of idcws and dcws */
2 status_area like istat,
/* the ioi status return area */
2 data_header_1 aligned like data_header,
/* the structure that defines the HOST to MCA data */
2 data_1 char (data_size_1),
/* the text of the data to be sent to the MCA */
2 data_header_2 aligned like data_header,
/* the structure that defines the MCA to HOST data */
2 data_2 char (data_size_2);
/* the text of the data returned by the MCA */

NOTES

data_header_1 and data_1 areas are reserved for data TO the
MCA. The data_header_2 and data_2 areas are reserved for data
FROM the MCA. However if the "mca_$tandd_read_data" entry is
call the data will be returned in data_1 and defined in the
data_header_1 area. The data_header_2 values should be nulled.

____ ____

mca_ mca_
____ ____

dcl 1 data_header based (data_header_ptr) aligned,
2 type bit (9) unal,
/* must be equal to "000"b3 (MBZ) */
2 definer fixed bin (9) unal unsigned,
/* defines type of info in header */
2 ctl_sw bit (18) unal,
/* "currently undefined" mbz = "000000"b3 */
2 host_sts_ign1 bit (1) unal,
2 host_sts_msb bit (8) unal,
2 host_sts_ign2 bit (1) unal,
2 host_sts_lsb bit (8) unal,
2 rd_flpy fixed bin (9) unal unsigned,
/* 0 = data files from host */
/* 1 = data files from flopy */
2 io_param_blk like io_parameter_block unal;

____ ____

mca_ mca_
____ ____

dcl 1 io_parameter_block based (io_param_blk_ptr) unal,
2 open fixed bin (9) unal unsigned,
2 cmd bit (18),
2 sts_ptr bit (18),
/* Unused */
2 file_name char (8),
/* file name for this request */
2 options bit (18),
/* Unused */
2 source_ptr bit (18),
/* Unused */
2 source_len,
/* data_size =
source_len_msb||source_len_lsb MCA to HOST */
3 source_len_ign1 bit (1),
3 source_len_msb bit (8),
3 source_len_ign2 bit (1),
3 source_len_lsb bit (8),
2 dest_ptr bit (18),
/* Unused */
2 blk_ct,
/* if MCA to HOST blk_ct_msb||blk_ct_lsb =
MAX number of 256 byte BLOCKS */
/* else not used */
3 blk_ct_ign1 bit (1),
3 blk_ct_msb bit (8),
3 blk_ct_ign2 bit (1),
3 blk_ct_lsb bit (8),
2 dest_len,
/* supplied by host as the number of bytes
in data_field max value is 16128 */
/* dest_len_msb = substr(unspec(data_size),21,8) */
/* dest_len_lsb = substr(unspec(data_size),29,8) */
3 dest_len_ign1 bit (1),
3 dest_len_msb bit (8),
3 dest_len_ign2 bit (1),
3 dest_len_lsb bit (8);

/* Constants used for data_header.definer */

____ ____

mca_ mca_
____ ____

dcl DATA_FROM_HOST
fixed bin (9) unsigned init (0) static options (constant);
dcl WRITE_CONSOLE
fixed bin (9) unsigned init (1) static options (constant);
dcl WRITE_READ_CONSOLE
fixed bin (9) unsigned init (2) static options (constant);
dcl DATA_FROM_MCA
fixed bin (9) unsigned init (3) static options (constant);
dcl REQ_DATA_FROM_HOST
fixed bin (9) unsigned init (4) static options (constant);
dcl STATUS_FROM_MCA
fixed bin (9) unsigned init (5) static options (constant);
dcl SEEK
fixed bin (9) unsigned init (6) static options (constant);
dcl CON_DATA_FROM_HOST
fixed bin (9) unsigned init (7) static options (constant);
dcl BIN_DATA_FROM_HOST
fixed bin (9) unsigned init (8) static options (constant);
dcl ABORT_SES_FROM_HOST
fixed bin (9) unsigned init (9) static options (constant);

dcl 1 mca_dcw_list based (mca_dcw_list_ptr),
2 idcw1 like idcw,
2 dcw1 like dcw,
2 idcw2 like idcw,
2 dcw2 like dcw;

dcl 1 dcw based (dcwp) aligned,
/* Data Control Word */
(2 address bit (18),
/* address for data transfer */
2 char_pos bit (3),
/* character position */
2 m64 bit (1),
/* non-zero for mod 64 address */
2 type bit (2),
/* DCW type */
2 tally bit (12)) unal;
/* tally for data transfer */

____ ____

mca_ mca_
____ ____

dcl 1 idcw based aligned,
/* Instruction DCW */
(2 command bit (6),
/* device command */
2 device bit (6),
/* device code */
2 ext bit (6),
/* address extension */
2 code bit (3),
/* should be "111"b for PCW */
2 ext_ctl bit (1),
/* "1"b if address extension to be used */
2 control bit (2),
/* terminate/proceed and marker control bits */
2 chan_cmd bit (6),
/* type of I/O operation */
2 count bit (6)) unal
/* record count or control character */;

dcl 1 istat based aligned,
/* I/O Interfacer status structure */
2 completion,
/* completion flags */
(3 st bit (1),
/* "1"b if status returned */
3 er bit (1),
/* "1"b if status indicates error condition */
3 run bit (1),
/* "1"b if channel still running */
3 time_out bit (1)) unal,
/* "1"b if time-out occurred */
2 level fixed bin (3),
/* IOM interrupt level */
2 offset fixed bin (18),
/* DCW list offset */
2 absaddr fixed bin (24),
/* absolute address of workspace */
2 iom_stat bit (72),
/* IOM status */
2 lpw bit (72)
/* LPW residue */;

_________ _________

mca_priv_ mca_priv_
_________ _________

NNNaaammmeee::: mmmcccaaa_ppprrriiivvv_

EEEnnntttrrryyy::: mmmcccaaa_ppprrriiivvv_$$$fffooorrrccceee_rrreeessseeettt

This entry will allow the user to reinitialize the MCA. This
entry issues a reset_mask PCW to the MCA. Executing this entry
has the same effect as pushing the "MCA Reset" button located in
the IMU cabinet.

USAGE

dcl mca_priv_$force_reset (char (*), bit (36), fixed bin (35));

call mca_priv_$force_reset (mca_id, mca_status, code);

ARGUMENTS

mca_id
MCA name to be reset. The name must be in the form "mcaX",
where X will be equal to the letter of the IMU the MCA is in
(a, b, c, or d). (Input)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

NOTES

The MCA must be in the FREE state for this entry to operate
properly. The entry will attach the MCA, do the reset and detach
the MCA when complete.

EEEnnntttrrryyy::: mmmcccaaa_ppprrriiivvv_$$$fffooorrrccceee_uuunnnllloooccckkk

This entry will allow the per MCA lock in the ring-1 mca_data_seg
to be force unlocked.

USAGE

dcl mca_priv_$force_unlock (char (*), fixed bin (35));

call mca_priv_$force_unlock (mca_id, code);

_________ _________

mca_priv_ mca_priv_
_________ _________

mca_id
MCA name to be unlocked. The name must be in the form "mcaX",
where X will be equal to the letter of the IMU the MCA is in
(a, b, c, or d). (Input)

code
Will be a standard system status code. (Output)

EEEnnntttrrryyy::: mmmcccaaa_ppprrriiivvv_$$$mmmcccaaa_ppprrriiivvv_llloooaaaddd_iiipppcccsss

This entry will allow all of the currently defined IPCs of the
selected IMU to have their internal firmware reloaded from the
MCA diskette and reset to a initialized state. This requires all
the IPCs of the IMU be attached to this process before this
command can be executed.

USAGE

dcl mca_priv_$load_ipcs entry (fixed bin, bit (36),
fixed bin (35));

call mca_priv_$load_ipcs (mca_ioi_idx, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

_________ _________

mca_priv_ mca_priv_
_________ _________

EEEnnntttrrryyy::: mmmcccaaa_ppprrriiivvv_$$$rrreeessseeettt_iiipppcccsss

This entry will allow all of the currently defined IPCs of the
selected IMU to be reset to a initialized state. This requires
all the IPCs of the IMU be attached to this process before this
command can be executed.

USAGE

dcl mca_priv_$reset_ipcs entry (fixed bin, bit (36),
fixed bin (35));

call mca_priv_$reset_ipcs (mca_ioi_idx, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

EEEnnntttrrryyy::: mmmcccaaa_ppprrriiivvv_$$$tttrrraaaccceee

This entry will allow the turning ON or OFF of the MCA console
messages (i.e. TRACING) displayed on the IPC-CONS adapter that
currently has the multidrop (MD) interface enabled.

USAGE

dcl mca_priv_$trace entry (fixed bin, bit (3), bit (1),
char (40), bit (36), fixed bin (35));

call mca_priv_$trace (mca_ioi_idx, mca_option, on_off_bit,
trace_state, mca_status, code);

ARGUMENTS

mca_ioi_idx
IOI index value returned when MCA was attached. (Input)

_________ ____

mca_priv_ mdc_
_________ ____

mca_option
A three bit field that will define what MCA tracing types will
be affected by the call. The three types in order will be
FAULT, BOOT and DEBUG. (Input)
The values are: "100"b -> FAULT, "010"b -> BOOT, or "001"b ->
DEBUG. These values may be or'ed together.

on_off_bit
A one bit field that will define whether to turn the above
MCA_OPTIONS ON or OFF. "1"b = turn on tracing. "0"b turn off
tracing. (Input)

trace_state
This is the ascii data returned by the MCA to indicate the
state of tracing. (Output)

mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)

code
Will be a standard system status code. (Output)

________________________________________

NNNaaammmeee::: mmmdddccc_

The mdc_ subroutine (actually a ring 1 gate) provides a series of
entry points for manipulation of master directories.

EEEnnntttrrryyy::: mmmdddccc_$$$cccrrreeeaaattteee_dddiiirrr

This entry point is used to create a new master directory. Its
arguments are roughly analogous to the hcs_$append_branchx entry
point.

USAGE

declare mdc_$create_dir entry (char(*), char(*), char(*), bit(36)
aligned, (3) fixed bin(3), char(*), fixed bin,
fixed bin(35));

____ ____

mdc_ mdc_
____ ____

call mdc_$create_dir (dir_name, entryname, volume, mode, rings,
user_id, quota, code);

ARGUMENTS

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

entryname
is the entryname of the subdirectory. (Input)

volume
is the name of the logical volume that is to contain segments
created in the new directory. (Input)

mode
is the user's access mode. (Input)

rings
are the ring brackets of the directory. (Input) Only the
first values are used.

user_id
is an access control name. (Input)

quota
is the quota to be placed on the new directory. (Input)

code
is a standard status code. (Output)

EEEnnntttrrryyy::: mmmdddccc_$$$cccrrreeeaaattteee_dddiiirrrxxx

This entry point is an extension of the mdc_$create_dir entry
point, which is similar to hcs_$create_branch_ entry point.

USAGE

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

call mdc_$create_dirx (dir_name, entryname, volume, info_ptr,
code);

ARGUMENTS

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

____ ____

mdc_ mdc_
____ ____

entryname
is the entryname of the subdirectory. (Input)

volume
is the name of the logical volume that is to contain segments
created in the new directory. (Input)

info_ptr
is a pointer to the create_branch_info structure as described
under the hcs_$create_branch_ entry point. (Input)

EEEnnntttrrryyy::: mmmdddccc_$$$cccrrreeeaaattteee_dddiiirrrxxx_aaaccccccttt

This entry point is an extension of the mdc_$create_dir entry
point, which is similar to the hcs_$create_branch_ entry point.

USAGE

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

call mdc_$create_dirx_acct (dir_name, entryname, volume,
info_ptr, account, owner, code);

ARGUMENTS

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

entryname
is the entryname of the subdirectory. (Input)

volume
is the name of the logical volume that is to contain segments
created in the new directory. (Input)

info_ptr
is a pointer to the create_branch_info structure as described
under the hcs_$create_branch_ entry point. (Input)

account
is the quota account from which this directory should draw
quota. (Input)

owner
is the user_id which should be listed as the owner of the
directory. (Input)

____ ____

mdc_ mdc_
____ ____

ACCESS REQUIRED

The user must have executive "E" access to the volume if the
account and/or owner are specified non-null. The quota account
must exist.

When the account and owner are null strings, a quota account
matching the user's person.project must exist.

SYSTEM STATUS CODES

argerr - create_branch_info has wrong version

mdc_exec_access - account and/or owner specified but user lacks
executive permission to volume

mdc_illegal_owner - the owner specified is in an illegal format

mdc_no_quota_account - the specified quota account does not exist

mdc_bad_quota - invalid quota in the account

mdc_no_quota - insufficient quota in the account

EEEnnntttrrryyy::: mmmdddccc_$$$dddeeellleeettteee_dddiiirrr

This entry point is used to delete a master directory.

USAGE

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

call mdc_$delete_dir (dir_name, entryname, code);

ARGUMENTS

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

entryname
is the entryname of the subdirectory. (Input)

code
is a standard status code. (Output)

____ ____

mdc_ mdc_
____ ____

EEEnnntttrrryyy::: mmmdddccc_$$$dddeeellleeettteee_vvvooollluuummmeee_qqquuuoootttaaa

This entry point is used to delete a logical volume quota
account.

USAGE

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

call mdc_$delete_volume_quota (volume, account, code);

ARGUMENTS

volume
is the logical volume to be manipulated.

account
is the name of the account (of the form person.project) to be
deleted.

code
is a standard system status code. (Output)

ACCESS REQUIRED

Executive access is required to the logical volume.

EEEnnntttrrryyy::: mmmdddccc_$$$fffiiinnnddd_lllvvviiiddd

This entry point translates a logical volume id (lvid) to a
logical volume name.

USAGE

declare mdc_$find_lvid entry (bit(36) aligned, char(x), fixed bin
(35));

call mdc_$find_lvid (lvid, lv_name, code);

ARGUMENTS

lvid
is a logical volume id. (Input)

lvname
is the corresponding lv name. (Output)

____ ____

mdc_ mdc_
____ ____

code
is a standard system status code. (Output)

EEEnnntttrrryyy::: mmmdddccc_$$$fffiiinnnddd_lllvvvnnnaaammmeee

This entry point translates a logical volume id (lvid) to a
logical volume name.

USAGE

declare mdc_$find_lvid entry (bit(36) aligned, char(x), fixed bin
(35));

call mdc_$find_lvid (lvid, lv_name, code);

ARGUMENTS

lvid
is a logical volume id. (Input)

lvname
is the corresponding lv name. (Output)

code
is a standard system status code. (Output)

EEEnnntttrrryyy::: mmmdddccc_$$$fffiiinnnddd_vvvooolllnnnaaammmeee

This entry point translates a physical volume id (pvid) into a
physical volume name and logical volume name.

USAGE

declare mdc_$find_volname entry (bit(36), aligned, char(*),
char(*1), fixed bin (30));

call mdc_$find_volname (pvid, pv_name, lv_name, code);

ARGUMENTS

pvid
is the physical volume id. (Input)

pv_name
is the physical volume name. (Output)

lv_name
is the logical volume name. (Output)

____ ____

mdc_ mdc_
____ ____

code
is a standard system status code. (Output)

EEEnnntttrrryyy::: mmmdddccc_$$$gggeeettt_lllvvv_aaacccccceeessssss

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));

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.

____ ____

mdc_ mdc_
____ ____

EEEnnntttrrryyy::: mmmdddccc_$$$lllvvvnnnaaammmeee_iiinnnfffooo

This entry point returns information about a logical volume.
-WARNING- Internal interface subject to change.

USAGE

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

call mdc_$lvname_info (lv_name, info_ptr, n_physical_volumes,
code);

ARGUMENTS

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

info_ptr
is a pointer to the pv_info structure. See Notes below.

n_physical_volumes
is the number of physical volumes in this logical volume.
(Output)

code
is a standard status code. (Output)

NOTES

The following structure describe all of the physical volumes in
the logical volume.

dcl 1 pv_info (100) aligned based (info_ptr),
2 pvname char(32),
2 device_type fixed bin,
2 pvid bit(36) aligned,

STRUCTURE ELEMENTS

pvname
is the name of this physical volume. (Output)

device_type
is the model number of the volume from fs_dev_types.incl.pl1.

pvid
is the unique id of the physical volume. (Output)

____ ____

mdc_ mdc_
____ ____

EEEnnntttrrryyy::: mmmdddccc_$$$pppvvvnnnaaammmeee_iiinnnfffooo

This entry point gets various kinds of information about a
specified storage-system physical volume.

USAGE

declare mdc_$pvname_info entry (char (*), bit (36) aligned, char
(*), bit (36) aligned, fixed bin, fixed bin (35));

call mdc_$pvname_info (pvname, pvid, lvname, lvid, device_type,
code);

ARGUMENTS

pvname
is the name of the physical volume about which information is
to be returned. (Input)

pvid
is the physical volume id of the specified volume. It can be
used as a parameter to ring-zero volume and partition
interfaces. (Output)

lvname
is the name of the logical volume to which the physical volume
belongs. (Output)

lvid
is the logical volume id of the logical volume to which the
physical volume belongs. (Output)

device_type
is a number indicating what type of device the specified
physical volume is mounted on. The names and characteristics
of these devices are listed in various arrays declared in the
include file fs_dev_types.incl.pl1. (Output)

code
is a standard system-status code. It is nonzero if the
information about the volume cannot be obtained or if the
volume does not exist. (Output)

____ ____

mdc_ mdc_
____ ____

EEEnnntttrrryyy::: mmmdddccc_$$$rrreeeaaaddd_dddiiissskkk_tttaaabbbllleee

This entry point copies out the system's database of disk drives
and their use into the user's storage. -WARNING- this is an
internal, unsupported interface, subject to change.

USAGE

declare mdc_$read_disk_table entry (pointer, fixed bin (35));

call mdc_$read_disk_table (temp_seg_ptr, code);

ARGUMENTS

temp_set_ptr
is a pointer to a segment that will be over-written with a
copy of the disk table.

code
is a standard system status code. (Output)

ACCESS REQUIRED

r access in ring 1 to >disk_table is required.

NOTES

disk_table.incl.pl1 describes the disk table.

EEEnnntttrrryyy::: mmmdddccc_$$$ssseeettt_aaaccccccooouuunnnttt_rrreeessstttrrriiicccttt_pppaaattthhh

This entry point manipulates a list of directories into which
master directories may be put. System and volume administrators
may set specific directories into which master directories may be
created by users with quota accounts.

USAGE

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

call mdc_$set_account_restrict_path (volume, account, dirs,
codes, type, code);

ARGUMENTS

volume
is the logical volume name. (Input)

____ ____

mdc_ mdc_
____ ____

account
is the person.project account name. (Input)

dirs
is an array of directory pathnames. (Input)

codes
is an array of status codes, one per entry in dirs. (Output)

type
(Input)
0 to replace the path list.
1 to add to the path list.
2 to delete from the path list.

code
is nonzero if any error is encounted. (Output)

NOTES

The restrict list specifies those directories with which master
directories may be appended on this volume by this account.

ACCESS REQUIRED

Volume access is required.

EEEnnntttrrryyy::: mmmdddccc_$$$ssseeettt_mmmdddiiirrr_aaaccccccooouuunnnttt

This entry point is used to set the quota account of a master
directory.

USAGE

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

call mdc_$set_mdir_account (dir_name, entryname, account, code);

ARGUMENTS

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

entryname
is the entryname of the subdirectory. (Input)

____ ____

mdc_ mdc_
____ ____

account
is the name of the new quota account. The directory quota is
returned to the old account and redrawn from this new account.

code
is a standard system status code. (Output)

EEEnnntttrrryyy::: mmmdddccc_$$$ssseeettt_mmmdddiiirrr_ooowwwnnneeerrr

This entry point is used to set the owner name of a master
directory.

USAGE

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

call mdc_$set_mdir_owner (dir_name, entryname, owner, code);

ARGUMENTS

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

entryname
is the entryname of the subdirectory. (Input)

owner
is the new owner name of the master directory, in the form
Person_id.Project_id.tag. (Input)

code
is a standard system status code. (Output)

EEEnnntttrrryyy::: mmmdddccc_$$$ssseeettt_mmmdddiiirrr_qqquuuoootttaaa

This entry point is used to set the quota on a master directory.

USAGE

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

call mdc_$set_mdir_quota (dir_name, entryname, sw, quota, code);

____ ____

mdc_ mdc_
____ ____

ARGUMENTS

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

entryname
is the entryname of the subdirectory. (Input)

sw
is a switch indicating the kind of quota change. (Input)
"0"b sets the directory quota to the quota parameter.
"1"b algebraically adds the quota parameter to the current
directory quota.

quota
is the quota to be placed on the new directory. (Input)

code
is a standard system status code. (Output)

EEEnnntttrrryyy::: mmmdddccc_$$$ssseeettt_vvvooollluuummmeee_qqquuuoootttaaa

This entry point is used to set the volume quota for a quota
account on a logical volume.

USAGE

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

call mdc_$set_volume_quota (volume, account, sw, quota, code);

ARGUMENTS

volume
is the name of the logical volume that is to contain segments
created in the new directory. (Input)

account
is the name of the quota account in the form
Person_id.Project_id.tag. The quota account name may contain
stars. (Input)

sw
is a switch indicating the kind of quota change. (Input)
"0"b sets the directory quota to the quota parameter.
"1"b algebraically adds the quota parameter to the current
directory quota.

____ ____

mdc_ mdc_
____ ____

quota
is the quota to be placed on the new directory. (Input)

code
is a standard system status code. (Output)

EEEnnntttrrryyy::: mmmdddccc_$$$ssstttaaatttuuusss

This entry point returns information about logical volumes and
master directories.

USAGE

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

call mdc_$status (volume_name, arg, return_info_ptr, code);

ARGUMENTS

volume_name
is the name of a logical volume about which information will
be returned. (Input)

arg
is a pointer to the args structure described in
mdc_status_args.incl.pl1.

return_info_ptr
is a pointer to the volume_data structure declared
mdc_status_info.incl.pl1.

code
is a standard system status code.

ACCESS REQUIRED

Executive access (rew) is required to the volume to set the
executive flag, user access (rw) is used otherwise.

____ ____

mdc_ mdc_
____ ____

NOTES

The structure that argp ptr point to is declared in the include
file mdc_status_args.incl.pl1.

dcl 1 msargs aligned based (argp),
2 version fixed bin,
2 output_size fixed bin(19),
2 flags
3 exec bit(1) unaligned,
3 dirs bit(1) unaligned,
3 account bit(1) unaligned,
3 owner bit(1) unaligned,
3 backup bit(1) unaligned,
3 restrict bit(1) unaligned,
3 accounting bit(1) unaligned,
3 bill bit(1) unaligned,
2 nnames fixed bin,
2 namesp ptr,
2 output_ptr ptr;

STRUCTURE ELEMENTS

version
must be 1.

output_size
is the number of words in output space.

flags.exec
is set if user wants to exercise exec access.

flags.dirs
is set if user wants info about master directories returned.

flags.account
is set if user has passed a list of accounts (exec only).
Only one of flags.account or flags.owner can be set.

flags.owner
is set if user has passed a list of owners (exec only). Only
one of flags.account or flags.owner can be set.

flags.backup
is set if backup data wanted (exec only). Must be zero.

flags.restrict
is set if caller wants restriction paths returned.

____ ____

mdc_ mdc_
____ ____

flags.accounting
is set if caller wants accounting data.

nnames
is the number of names passed (if account or owner set).

namesp
is a pointer to the ms_names structure described below.

output_ptr
is a pointer for unformatted space into which the results will
be placed. The volume_data structure described below
describes this storage.

NAMESP_PTR

The structure pointed to by namesp_ptr is declared as follows:

dcl 1 ms_names (msargs.nnames) (msargs.namesp) aligned based
2 person char(22) unaligned;
2 project char(9) unaligned;

VOLUME_DATAP PTR

The structure pointed to by volume_datap is declared as follows:

dcl 1 volume_data alligned based (volume datap),
2 version fixed bin,
2 accountp ptr,
2 ownerp ptr,
2 restrictp ptr,
2 defaultp ptr,
2 backup (3) fixed bin(35);

STRUCTURE ELEMENTS

version
must be 1. (Input)

accountp
pointer to first account_data entry returned.

ownerp
pointer to list of owner_data entries.

restrictp
pointer to list of path restrictions.

____ ____

mdc_ mdc_
____ ____

defaultp
pointer to list of path defaults.

backup
data for backup accounting. Not used, always zero.

ACCOUNT_DATAP PTR

The structure pointed to by account_datap is declared as follows:

dcl 1 account_data aligned based (account_datap),
2 next ptr,
2 name,
3 person char(22) unaligned,
3 project char(9) unaligned,
2 quota fixed bin(18),
2 quota_used fixed bin(18),
2 trp fixed bin(71),
2 backup (31) fixed bin(35),
2 dirp ptr,
2 restrictp ptr;

STRUCTURE ELEMENTS

account_data
structure returned for each quota account.

next
is the pointer to next one.

quota
is the total quota available to account.

quota_used
is the total used currently.

trp
is the time_record prodecut of deleted directories.

backup
is the backup account data. Not used.

dirp
is the pointer to first directory charged against account.

restrictp
is the pointer to pathname restriction list.

____ ____

mdc_ mdc_
____ ____

DIR_DATAP_PTR

The structure pointed to by dir_datap is declared as follows:

dcl 1 dir_data aligned based (dir_datap),
2 next ptr,
2 pathp ptr,
2 name,
3 person char(22) unaligned,
3 project char(9) unaligned,
2 quota fixed bin,
2 backup (3) fixed bin(35);

STRUCTURE ELEMENTS

dir_data
is the structure allocated for each master directory.

next
is the pointer to next one.

pathp
is the pointer to pathname entry.

quota
is the quota allocated to directory.

backup
is the backup account data.

OWNER_DATAP_PTR

The structure pointed to by owner_datap_ptr is declared as
follows:

dcl 1 owner_data aligned based (owner_datap),
2 next ptr,
2 name,
3 person char(22) unaligned,
3 project char(9) unaligned,
2 dirp ptr;

STRUCTURE ELEMENTS

owner_data
is the structure allocated for each master directory owner.

name
is the owner name.

____ _____

mdc_ mhcs_
____ _____

dirp
is the pointer to list of owners directories.

PATH_DATAP_PTR

The structure pointed to be path_datap_ptr is declared as
follows:

dcl 1 path_data aligned based (path_datap),
2 next ptr,
2 code fixed bin(35),
2 dir char(168) unaligned,
2 ename char(32) unaligned;

STRUCTURE ELEMENTS

path_data
one of these is allocated for each pathname.

code
is the status code from decoding the pathname.

________________________________________

NNNaaammmeee::: mmmhhhcccsss_

EEEnnntttrrryyy::: mmmhhhcccsss_$$$gggeeettt_ssseeeggg_uuusssaaagggeee

This entry point returns the number of page faults taken on a
segment since its creation.

USAGE

declare mhcs_$get_seg_usage entry (char(*), char(*),
fixed bin(35), fixed bin(35));

call mhcs_$get_seg_usage (dir_name, entryname, use, code);

_____ _____

mhcs_ mhcs_
_____ _____

ARGUMENTS

dir_name
is the directory containing the segment. (Input)

entryname
is the entry name of the segment. (Input)

use
is the page fault count. (Output)

code
is a standard status code. (Output)

NOTES

This entry point works for segments only and cannot be used to
determine the page faults on a directory.

EEEnnntttrrryyy::: mmmhhhcccsss_$$$gggeeettt_ssseeeggg_uuusssaaagggeee_ppptttrrr

This entry point works the same as mhcs_$get_seg_usage except
that it takes a pointer to the segment.

USAGE

declare mhcs_$get_seg_usage_ptr entry (ptr, fixed bin(35),
fixed bin(35));

call mhcs_$get_seg_usage_ptr (s_ptr, use, code);

ARGUMENTS

s_ptr
is a pointer to the segment. (Input)

use
is the page fault count. (Output)

code
is a standard status code. (Output)

_____ _____

mhcs_ mseg_
_____ _____

NNNaaammmeee::: mmmssseeeggg_

EEEnnntttrrryyy::: mmmssseeeggg_$$$fffiiinnnddd_hhhdddrrr_mmmsssggg

This entry, callable only from the ring of the segment, returns a
pointer to the header message.

USAGE

declare mseg_$find_hdr_msg entry (ptr, ptr, fixed bin (18), bit
(72) aligned, fixed bin (35));

call mseg_$find_hdr_msg (mseg_ptr, hdr_msg_ptr, hdr_msg_length,
hdr_msg_access_class, code);

ARGUMENTS

mseg_ptr
is a pointer to an mseg_ managed segment. (Input)

hdr_msg_ptr
is a pointer to the header message of segment, if any.
(Output)

hdr_msg_length
is the length, in words, of the data in the header message.
(Output)

hdr_msg_access_class
is the access class of the information stored in the header
message. It is the callers responsibility to check this
against the process authorization before returning this
information out of ring 1. (Output)

code
will be zero if there was a header message defined, and
error_table_$no_message otherwise. (Output)

_____ _________________________

mseg_ message_segment_$add_file
_____ _________________________

EEEnnntttrrryyy::: mmmssseeeggg_$$$fffiiinnnddd_mmmsssggg

This entry is similar to mseg_$priv_read. No area pointer is
supplied, because no data is copied. It is the callers
responsibility to make all access control checks.

USAGE

declare mseg_$find_msg entry (ptr, ptr, fixed bin (35));

call mseg_$find_msg (mseg_ptr, mseg_message_info_ptr, code);

ARGUMENTS

mseg_ptr
is a pointer to a mseg_ managed segment. (Input)

mseg_message_info_ptr
is a pointer to a standard mseg_message_info structure, as
declared in mseg_message_info.incl.pl1. On output, the fields
ms_ptr and ms_len are set to the actual location and length of
the message text in the segment. The other output fields are
set as usual. (Input, but fields output)

code
is a standard system status code. It will be
error_table_$no_message if the requested message could not be
located. (Output)

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$aaadddddd_fffiiillleee

The add_file entrypoint places an arbitrary message in a message
segment.

USAGE

declare message_segment_$add_file entry (char (*), char (*), ptr,
fixed bin(24), bit(72) aligned, fixed bin(35));

call message_segment_$add_file (dir_name, entry_name,
message_ptr, message_len, message_id, code);

ARGUMENTS

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

_________________________ __________________________

message_segment_$add_file message_segment_$add_index
_________________________ __________________________

entry_name
is the name of the message segment (Input).

message_ptr
is a pointer to an arbitrary bit string, which is the text of
the message. (Input)

message_len
is the length of the message in bits. (Input)

message_id
is a value identifying the message in the message segment,
which can be used to reference the message in subsequent calls
to message segment.

ACCESS REQUIRED

The calling process must have "a" extended access to the message
segment to add a message. The authorization of the calling
process must dominate the access class of the parent of the
message segment. The authorization of the calling process must
be dominated by the access class of the message segment segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$aaadddddd_iiinnndddeeexxx

The add_index entrypoint places an arbitrary message in a message
segment.

USAGE

declare message_segment_$add_index entry (fixed bin, ptr, fixed
bin(24), bit(72) aligned, fixed bin(35));

call message_segment_$add_index (mseg_index, message_ptr,
message_len, message_id, code);

__________________________ ____________________________

message_segment_$add_index message_segment_$chname_file
__________________________ ____________________________

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment into which a message is to be
added.

message_ptr
is a pointer to an arbitrary bit string, which is the text of
the message. (Input)

message_len
is the length of the message in bits. (Input)

message_id
is a value identifying the message in the message segment,
which can be used to reference the message in subsequent calls
to message segment.

ACCESS REQUIRED

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$ccchhhnnnaaammmeee_fffiiillleee

The chname_file entrypoint changes the entry name on a specified
message segment. If an already existing name (an old name) is
specified, it is deleted from the entry; if a new name is
specified, it is added. Thus, if only an old name is specified,
the effect is to delete a name; if only a new name is specified,
the effect is to add a name; and if both are specified, the
effect is to rename the entry.

____________________________ ____________________________

message_segment_$chname_file message_segment_$chname_file
____________________________ ____________________________

USAGE

declare message_segment_$chname_file entry (char(*), char(*),
char(*), char(*), fixed bin(35));

call message_segment_$chname_file (dir_name, entry_name,
old_entry_name, new_entry_name, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

old_entry_name
is the name to be deleted from the message segment. (Input)
It can be a null character string ("") in which case no name
is deleted. If oldname is null, then newname must not be
null.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
message segment. The authorization of the calling process must
equal the access class of the parent of the message segment.

____________________________ ____________________________________

message_segment_$chname_file message_segment_$check_salv_bit_file
____________________________ ____________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$ccchhheeeccckkk_sssaaalllvvv_bbbiiittt_fffiiillleee

The check_salv_bit_file entrypoint returns the value of the
salvaged bit of a message segment; in addition, it can be used to
turn the bit off if found on.

USAGE

declare message_segment_$check_salv_bit_file entry (char (*),
char (*), bit(1) aligned, bit(1) aligned, fixed bin(35));

call message_segment_$check_salv_bit_file (dir_name, entry_name,
turn_off, salv_bit, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

turn_off
is a flag which, if set to true, turns off the salvaged bit if
it is on. (Input)

salv_bit
is the value of the salvaged bit prior to the call. (Output)

ACCESS REQUIRED

The calling process must have "s" extended access to the message
segment to obtain the value of the salvaged bit. It must have
"d" extended access to turn the salvaged bit off. The
authorization of the process must dominate the access class of
the parent of the message segment.

____________________________________ _____________________

message_segment_$check_salv_bit_file $check_salv_bit_index
____________________________________ _____________________

NNNaaammmeee::: $$$ccchhheeeccckkk_sssaaalllvvv_bbbiiittt_iiinnndddeeexxx

The check_salv_bit_index entrypoint returns the value of the
salvaged bit of a message segment; in addition, it can be used to
turn the bit off if found on.

USAGE

declare message_segment_$check_salv_bit_index entry (fixed bin,
bit(1) aligned, bit(1) aligned, fixed bin(35));

call message_segment_$check_salv_bit_index (mseg_index, turn_off,
salv_bit, code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment from which the salvaged bit is
to be obtained and possibly turned off. (Input)

turn_off
is a flag which, if set to true, turns of the salvaged bit if
it is on. (Input)

salv_bit
is the value of the salvaged bit prior to the call. (Output)

ACCESS REQUIRED

_____________________ _____________________________

$check_salv_bit_index message_segment_$compact_file
_____________________ _____________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$ccclllooossseee

The close entrypoint terminates the relationship between a
message segment index and a message segment.

USAGE

declare message_segment_$close entry (fixed bin, fixed bin(35));

call message_segment_$close (mseg_index, code);

ARGUMENTS

mseg_index
is the value returned froma call to message_segment_$open,
used to identify a specific message segment. (Input)

code
is a standard system status code. (Output)

ACCESS REQUIRED

No explicit access is required to sucessfully execute this
entrypoint.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$cccooommmpppaaacccttt_fffiiillleee

The compact_file entrypoint eliminates unused space in a message
segment, compressing its size to reflect storage actually filled
with messages.

USAGE

declare message_segment_$compact_file entry (char(*), char(*),
float bin(27), fixed bin(35));

call message_segment_$compact_file (dir_name, entry_name,
compaction_ratio, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

_____________________________ ______________________________

message_segment_$compact_file message_segment_$compact_index
_____________________________ ______________________________

ACCESS REQUIRED

The calling process must have "d" extended access to the message
segment. The authorization of the calling process must be equal
to the access class of the parent of the message segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$cccooommmpppaaacccttt_iiinnndddeeexxx

The compact_index entrypoint eliminates unused space in a message
segment, compressing its size to reflect storage actually filled
with messages.

USAGE

declare message_segment_$compact_index entry (fixed bin, float
bin(27), fixed bin(35));

call message_segment_$compact_index (mseg_index,
compaction_ratio, code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment to be compacted. (Input)

______________________________ _____________________

message_segment_$compact_index message_segment_$copy
______________________________ _____________________

ACCESS REQUIRED

The calling process must have "d" extended access to the message
segment. The authorization of the calling process must be equal
to the access class of the parent of the message segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$cccooopppyyy

The copy entrypoint copies the contents of an existing message
segment into a new message segment.

USAGE

declare message_segment_$copy entry (char (*), char (*), char
(*), char (*), bit (1) aligned, fixed bin (35));

call message_segment_$copy (source_dir_name, source_entry_name,
target_dir_name, target_entry_name, error_on_target, code);

ARGUMENTS

source_dir_name
is the pathname of the directory that contains the message
segment to be copied. (Input)

source_entry_name
is the name of the message segment to be copied. (Input)

target_dir_name
is the pathname of the directory that is to contain a copy of
the source message segment. (Input)

target_entry_name
is the name of the new message segment. (Input)

error_on_target
is a flag indicating that the difficulties in copying the
message segment were due to the target message segment.
(Output)

_____________________ _______________________

message_segment_$copy message_segment_$create
_____________________ _______________________

ACCESS REQUIRED

The calling process must have "r" extended access to the source
message segment, and "ma" access to the target directory. The
authorization of the calling process must equal the access class
of BOTH the source and target directories. The maximum
authorization of the calling process must dominate the access
class of the source message segment.

NOTES

The target message segment must not exist before this entrypoint
is called.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$cccrrreeeaaattteee

The create entrypoint creates a message segment in a given
directory.

USAGE

declare message_segment_$create entry (char(*), char(*), fixed
bin(35));

call message_segment_$create (dir_name, entry_name, code);

ARGUMENTS

dir_name
is the pathname of the directory which is to contain the
message segment. (Input)

entry_name
is the name of the message segment to be created. (Input)

code
is a standard system status code. (Output) It can have the
following values:

_______________________ _______________________

message_segment_$create message_segment_$delete
_______________________ _______________________

error_table_$moderr
incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.

ACCESS REQUIRED

The calling process must have append and modify access to the
directory which is to contain the message segment. The
authorization of the calling process must equal the access class
of the directory which is to contain the message segment.

NOTES

The message segment is created with default extended modes of
"adros" for the caller's person ID and "ao" for "*.SysDaemon.*".
The access class range of the message segment is defined at the
lower bound by the access class of the parent directory and at
the upper bound by the maximum authorization of the calling
process.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$dddeeellleeettteee

The delete entrypoint deletes a message segment from hierarchy.

USAGE

declare message_segment_$delete entry (char(*), char(*), fixed
bin(35));

call message_segment_$delete (dir_name, entry_name, code);

ARGUMENTS

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

entry_name
is the name of the message segment to be deleted. (Input)

_______________________ ____________________________

message_segment_$delete message_segment_$delete_file
_______________________ ____________________________

ACCESS REQUIRED

The calling process must have modify access to the parent of the
message segment. The authorization of the calling process must
be equal to the access class of the parent of the message
segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$dddeeellleeettteee_fffiiillleee

The delete_file entrypoint deletes a specified message in a
message segment.

USAGE

declare message_segment_$delete_file entry (char (*), char (*),
bit(72) aligned, fixed bin(35));

call message_segment_$delete_file (dir_name, entry_name,
message_id, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

message_id
is the identifier of the message to be deleted. (Input)

ACCESS REQUIRED

____________________________ _____________________________

message_segment_$delete_file message_segment_$delete_index
____________________________ _____________________________

must equal the access class of the message to be deleted. The
authorization of the calling process must dominate the parent of
the message segment that contains the message. The calling
process must have "d" extended access to the message segment to
delete an arbitrary message; alternatively, "o" extended access
will permit the process to delete a message that was added by the
user. The authorization of the calling process must equal the
access class of the message to be deleted. The authorization of
the calling process must dominate the parent of the message
segment that contains the message. The authorization of the
calling process must be dominated bythe access class of the
message segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$dddeeellleeettteee_iiinnndddeeexxx

The delete_index entrypoint deletes a specified message in a
message segment.

USAGE

declare message_segment_$delete_index entry (fixed bin, bit(72)
aligned, fixed bin(35));

call message_segment_$delete_index (mseg_index, message_id,
code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment which contains the message to
be deleted. (Input)

message_id
is the identifier of the message to be deleted. (Input)

_____________________________ ______________________________

message_segment_$delete_index message_segment_$get_mode_file
_____________________________ ______________________________

ACCESS REQUIRED

The calling process must have "d" extended access to the message
segment to delete an arbitrary message; alternatively, "o"
extended access will permit the process to delete a message that
was added by the user. The authorization of the calling process
must equal the access class of the message to be deleted. The
authorization of the calling process must dominate the parent of
the message segment that contains the message. The authorization
of the calling process must be dominated bythe access class of
the message segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$gggeeettt_mmmooodddeee_fffiiillleee

The get_mode_file entrypoint returns the effective extended
access the caller has to a message segment.

USAGE

declare message_segment_$get_mode_file entry (char(*), char(*),
bit(36) aligned, fixed bin(35));

call message_segment_$get_mode_file (dir_name, entry_name, modes,
code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

modes
is a bit string describing the effective extended access the
process has to the message segment. (Output) The bit string
is described in the include file
mseg_access_mode_values.incl.pl1.

______________________________ _______________________________

message_segment_$get_mode_file message_segment_$get_mode_index
______________________________ _______________________________

ACCESS REQUIRED

The calling process must have either a minimum of status access
to the parent of the message segment or non-null extended access
to the message segment itself. The authorization of the calling
process must dominate the access class of the parent of the
message segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$gggeeettt_mmmooodddeee_iiinnndddeeexxx

The get_mode_index entrypoint returns the effective extended
access the caller has to a message segment.

USAGE

declare message_segment_$get_mode_index entry (fixed bin, bit(36)
aligned, fixed bin(35));

call message_segment_$get_mode_index (mseg_index, modes, code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment for which modes are to be
obtained. (Input)

modes
is a bit string describing the effective extended access the
process has to the message segment. (Output) The bit string
is described in the include file
mseg_access_mode_values.incl.pl1.

_______________________________ _______________________

message_segment_$get_mode_index $get_message_count_file
_______________________________ _______________________

ACCESS REQUIRED

________________________________________

NNNaaammmeee::: $$$gggeeettt_mmmeeessssssaaagggeee_cccooouuunnnttt_fffiiillleee

The get_message_count_file entrypoint returns the number of
messages present in a message segment that are accessible to the
calling process.

USAGE

declare message_segment_$get_message_count_file entry (char (*),
char (*), fixed bin, fixed bin(35));

call message_segment_$get_message_count_file (dir_name,
entry_name, message_count, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

message_count
is the number of messages accessible to the calling process.
(Output)

_______________________ ________________________

$get_message_count_file $get_message_count_index
_______________________ ________________________

ACCESS REQUIRED

The calling process must have "s" extended access to the message
segment in order to obtain its message count. The authorization
of the calling process must dominate the access class of the
parent of the message segment.

________________________________________

NNNaaammmeee::: $$$gggeeettt_mmmeeessssssaaagggeee_cccooouuunnnttt_iiinnndddeeexxx

The get_message_count_index entrypoint returns the number of
messages present in a message segment that are accessible to the
calling process.

USAGE

declare message_segment_$get_message_count_index entry (fixed
bin, fixed bin, fixed bin(35));

call message_segment_$get_message_count_index (mseg_index,
message_count, code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment from which the count is to be
obtained. (Input)

message_count
is the number of messages accessible to the calling process.
(Output)

ACCESS REQUIRED

________________________ ______________________

$get_message_count_index $incremental_read_file
________________________ ______________________

NNNaaammmeee::: $$$iiinnncccrrreeemmmeeennntttaaalll_rrreeeaaaddd_fffiiillleee

The incremental_read_file entrypoint obtains a message from a
message segment relative to the message specified in its argument
list.

USAGE

declare message_segment_$incremental_read_file entry (char (*),
char (*), ptr, bit(2) aligned, bit(72) aligned, ptr, fixed
bin(35));

call message_segment_$incremental_read_file (dir_name,
entry_name, area_ptr, direction, message_id, ms_arg_ptr,
code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

direction
is a bit string specifying the message to be returned,
relative to that specified by the message identifier. (Input)
A value of "00"b selects the specified message. A value of
"10"b selectes the message before the specified one. A value
of "01"b selects the message after the specified one.

message_id
is the identifier of the message that serves as a reference
point for the selection. (Input)

ms_arg_ptr
is a pointer to the structure mseg_return_args, which will be
filled in with information about the selected message.
(Input)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$moderr
incorrect access modes to perform the operation.

______________________ ______________________

$incremental_read_file $incremental_read_file
______________________ ______________________

error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$no_message
no message available with desired characteristics.

ACCESS REQUIRED

The caller must have "r" extended access to the message segment
to read a message from it. The authorization of the caller must
both dominate the access class of the parent of the message
segment and dominate the access class of the message for the
message to be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

______________________ _______________________

$incremental_read_file $incremental_read_index
______________________ _______________________

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: $$$iiinnncccrrreeemmmeeennntttaaalll_rrreeeaaaddd_iiinnndddeeexxx

The incremental_read_index entrypoint obtains a message from a
message segment relative to the message specified in its argument
list.

USAGE

declare message_segment_$incremental_read_index entry (fixed bin,
ptr, bit(2) aligned, bit(72) aligned, ptr, fixed bin(35));

call message_segment_$incremental_read_index (mseg_index,
area_ptr, direction, message_id, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment from which the message is to
be obtained. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

direction
is a bit string specifying the message to be returned,
relative to that specified by the message identifier. (Input)
A value of "00"b selects the specified message. A value of
"10"b selectes the message before the specified one. A value
of "01"b selects the message after the specified one.

message_id
is the identifier of the message that serves as a reference
point for the selection. (Input)

ms_arg_ptr
is a pointer to the structure mseg_return_args, which will be
filled in with information about the selected message.
(Input)

code
is a standard system status code. (Output) It can have the

_______________________ _______________________

$incremental_read_index $incremental_read_index
_______________________ _______________________

following values:
error_table_$moderr
incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$no_message
no message available with desired characteristics.

ACCESS REQUIRED

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

_______________________ ___________________________

$incremental_read_index message_segment_$ms_acl_add
_______________________ ___________________________

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$mmmsss_aaaccclll_aaadddddd

This entry point adds specified access modes to the access
control list (ACL) of the specified message segment. If an
access name already appears on the ACL of the message segment,
its mode is changed to the one specified by the call.

USAGE

declare message_segment_$ms_acl_add entry (char(*), char(*), ptr,
fixed bin, fixed bin(35));

call message_segment_$ms_acl_add (dir_name, entry_name, acl_ptr,
acl_count, code);

ARGUMENTS

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

entry_name
is the entry name of the message segment. (Input)

acl_ptr
points to a user-filled segment_acl_array structure (see
"Entry Information" below). (Input)

acl_count
contains the number of ACL entries in the segment_acl_array
structure (see "Entry Information" below). (Input)

___________________________ ___________________________

message_segment_$ms_acl_add message_segment_$ms_acl_add
___________________________ ___________________________

ENTRY INFORMATION

The segment_acl_array structure should be declared in the
following way:

dcl 1 segment_acl_array (acl_count) aligned like
segment_acl_entry;

The segment_acl_entry structure (declared in the include file
acl_structures.incl.pl1) is as follows:

dcl 1 segment_acl_entry aligned based,
2 access_name char(32) unaligned,
2 mode bit(36) aligned,
2 extended_mode bit(36) aligned,
2 status_code fixed bin(35);

STRUCTURE ELEMENTS

access_name
is the access name (in the form Person_id.Project_id.tag) that
identifies the processes to which this ACL entry applies.

mode
should contain the value "0"b.

extended_mode
contains the extended modes for this access name. The include
file mseg_access_mode_values.incl.pl1 defines mnemonics for
these values:

status_code
is a standard system status code for this ACL entry only.

NOTES

If code is returned as error_table_$argerr, then the erroneous
ACL entries in the segment_acl structure have status_code set to
an appropriate error code. No processing is performed.

___________________________ ______________________________

message_segment_$ms_acl_add message_segment_$ms_acl_delete
___________________________ ______________________________

ACCESS REQUIRED

The calling process must have modify access to the parent of the
message segment. The authorization of the calling process must
be equal to the access class of the parent of the message
segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$mmmsss_aaaccclll_dddeeellleeettteee

This entry point deletes specified entries from an access control
list (ACL) for a message segment.

USAGE

declare message_segment_$ms_acl_delete entry (char(*), char(*),
ptr, fixed bin, fixed bin(35));

call message_segment_$ms_acl_delete (dir_name, entryname,
acl_ptr, acl_count, code);

ARGUMENTS

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

entryname
is the entryname of the message segment. (Input)

acl_ptr
points to a user-filled delete_acl_array structure (see "Entry
Information" below). (Input)

acl_count
is the number of ACL entries in the delete_acl_array structure
(see "Entry Information" below). (Input)

______________________________ ______________________________

message_segment_$ms_acl_delete message_segment_$ms_acl_delete
______________________________ ______________________________

ENTRY INFORMATION

The delete_acl_array structure should be declared in the
following way:

dcl 1 delete_acl_array (acl_count) aligned like delete_acl_entry;

The delete_acl_entry structure (declared in the include file
acl_structures.incl.pl1) is as follows:

dcl 1 delete_acl_entry aligned based,
2 access_name char(32) unaligned,
2 status_code fixed bin(35);

STRUCTURE ELEMENTS

access_name
is the access name (in the form of Person_id.Project_id.tag)
that identifies the ACL entry to be deleted.

status_code
is a storage system status code for this ACL entry only.

NOTES

If code is returned as error_table_$argerr, then the erroneous
ACL entries in the delete_acl_array structure have status_code
set to an appropriate error code. No processing is performed.

If an access name cannot be matched to a name already on the ACL
of the message segment, then the status_code for that ACL entry
in the delete_acl_array structure is set to
error_table_$user_not_found. Processing continues to the end of
the delete_acl_array structure and code is returned as 0.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
message segment. The authorization of the calling process must
equal the access class of the parent of the message segment.

______________________________ ____________________________

message_segment_$ms_acl_delete message_segment_$ms_acl_list
______________________________ ____________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$mmmsss_aaaccclll_llliiisssttt

This entry point is used either to list the entire access control
list (ACL) of a message segment or to return the access modes of
specified ACL entries. The segment_acl_array structure used by
this entry point is discussed in the description of
message_segment_$ms_acl_add.

USAGE

declare message_segment_$ms_acl_list entry (char(*), char(*),
ptr, fixed bin, ptr, fixed bin(35));

call message_segment_$ms_acl_list (dir_name, entryname,
user_acl_ptr, user_acl_count, area_ptr, code);

ARGUMENTS

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

entryname
is the entryname of the message segment. (Input)

user_acl_count
is the number of entries in the ACL structure. (Input or
Output)
Input
is the number of entries in the ACL structure identified by
acl_ptr.
Output
is the number of entries in the segment_acl_array structure
allocated in the area pointed to by area_ptr, if area_ptr
is not null.

area_ptr
points to an area in which the list of ACL entries, which make

____________________________ _______________________________

message_segment_$ms_acl_list message_segment_$ms_acl_replace
____________________________ _______________________________

up the entire ACL of the message segment, is allocated.
(Input) If area_ptr is null, then the user wants access modes
for certain ACL entries; these will be specified by the
structure pointed to by user_acl_ptr (see below).

NOTES

If user_acl_ptr is used to obtain modes for specified access
names (rather than for all access names on a message segment),
then each ACL entry in the segment_acl_array structure either has
status_code set to 0 and contains the message segment's mode or
has status_code set to error_table_$user_not_found and contains a
mode of 0.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
message segment. The authorization of the calling process must
dominate the access class of the parent of the message segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$mmmsss_aaaccclll_rrreeeppplllaaaccceee

This entry point replaces an entire access control list (ACL) for
a message segment with a user-provided ACL, and can optionally
add an entry for *.SysDaemon.* with mode rw to the new ACL. The
segment_acl_array structure described in
message_segment_$ms_acl_add is used by this entry point.

USAGE

declare message_segment_$ms_acl_replace entry (char(*), char(*),
ptr, fixed bin, fixed bin(35));

call message_segment_$ms_acl_replace (dir_name, entryname,
acl_ptr, acl_count, code);

_______________________________ _______________________________

message_segment_$ms_acl_replace message_segment_$ms_acl_replace
_______________________________ _______________________________

ARGUMENTS

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

entryname
is the entryname of the message segment. (Input)

acl_ptr
points to the user supplied segment_acl_array structure that
is to replace the current ACL. (Input)

acl_count
is the number of entries in the segment_acl_array structure.
(Input)

NOTES

ACCESS REQUIRED

The calling process must have modify access to the parent of the
message segment. The authorization of the calling process must
be equal to the access class of the parent of the message
segment.

_______________________________ _____________________

message_segment_$ms_acl_replace message_segment_$open
_______________________________ _____________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$ooopppeeennn

The open entrypoint associates a specified message segment with a
message segment index, allowing for more efficient processing of
message segment functions during subsequent calls to message
segment.

USAGE

declare message_segment_$open entry (char (*), char (*), fixed
bin, fixed bin (35));

call message_segment_$open (dir_name, entry_name, mseg_index,
code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

mseg_index
is a value which will identify the message segment until a
call to message_segment_$close is performed. (Output)

ACCESS REQUIRED

The calling process must have non-null extended access to the
message segment. The authorization of the calling process must
dominate the access class of the parent directory. The
authorization of the calling process must be dominated by the
access class of the mailbox.

_____________________ __________________________

message_segment_$open $own_incremental_read_file
_____________________ __________________________

NNNaaammmeee::: $$$ooowwwnnn_iiinnncccrrreeemmmeeennntttaaalll_rrreeeaaaddd_fffiiillleee

The own_incremental_read_file entrypoint obtains a message
originally added to a message segment by the user, relative to
the message specified in the argument list.

USAGE

declare message_segment_$own_incremental_read_file entry (char
(*), char (*), ptr, bit(2) aligned, bit(72) aligned, ptr,
fixed bin(35));

call message_segment_$own_incremental_read_file (dir_name,
entry_name, area_ptr, direction, message_id, ms_arg_ptr,
code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

message_id
is the identifier of the message that serves as a reference
point for the selection. (Input)

ms_arg_ptr
is a pointer to the structure mseg_return_args, which will be
filled in with information about the selected message.
(Input)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$moderr
incorrect access modes to perform the operation.

__________________________ __________________________

$own_incremental_read_file $own_incremental_read_file
__________________________ __________________________

error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$no_message
no message available with desired characteristics.

ACCESS REQUIRED

The caller must have either "r" or "o" extended access to the
message segment to read a message from it. The authorization of
the caller must both dominate the access class of the parent of
the message segment and dominate the access class of the message
for the message to be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

__________________________ ___________________________

$own_incremental_read_file $own_incremental_read_index
__________________________ ___________________________

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: $$$ooowwwnnn_iiinnncccrrreeemmmeeennntttaaalll_rrreeeaaaddd_iiinnndddeeexxx

The own_incremental_read_index entrypoint obtains a message
originally added to a message segment by the user, relative to
the message specified in the argument list.

USAGE

declare message_segment_$own_incremental_read_index entry (fixed
bin, ptr, bit(2) aligned, bit(72) aligned, ptr, fixed
bin(35));

call message_segment_$own_incremental_read_index (mseg_index,
area_ptr, direction, message_id, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment from which the message is to
be obtained. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

message_id
is the identifier of the message that serves as a reference
point for the selection. (Input)

ms_arg_ptr
is a pointer to the structure mseg_return_args, which will be
filled in with information about the selected message.
(Input)

code
is a standard system status code. (Output) It can have the

___________________________ ___________________________

$own_incremental_read_index $own_incremental_read_index
___________________________ ___________________________

ACCESS REQUIRED

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

___________________________ ______________________________

$own_incremental_read_index message_segment_$own_read_file
___________________________ ______________________________

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$ooowwwnnn_rrreeeaaaddd_fffiiillleee

The own_read_file entrypoint returns a message originally added
by the user from a message segment.

USAGE

declare message_segment_$own_read_file entry (char (*), char (*),
ptr, bit(1) aligned, ptr, fixed bin(35));

call message_segment_$own_read_file (dir_name, entry_name,
area_ptr, message_wanted, ms_arg_ptr, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

message_wanted
is a flag indicating which message is wanted. (Input) If
"0"b, the first message found is returned; if "1"b, the last
is returned.

ms_arg_ptr
is a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$moderr
incorrect access modes to perform the operation.

______________________________ ______________________________

message_segment_$own_read_file message_segment_$own_read_file
______________________________ ______________________________

error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$no_message
no message available with desired characteristics.

ACCESS REQUIRED

The caller must have either "r" or "o" extended access to the
message segment to read its own message. The authorization of
the caller must both dominate the access class of the parent of
the message segment and dominate the access class of the message
to be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

______________________________ _______________________________

message_segment_$own_read_file message_segment_$own_read_index
______________________________ _______________________________

access_class
is the access class of the message.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$ooowwwnnn_rrreeeaaaddd_iiinnndddeeexxx

The own_read_index entrypoint returns a message originally added
by the user from a message segment.

USAGE

declare message_segment_$own_read_index entry (fixed bin, ptr,
bit(1) aligned, ptr, fixed bin(35));

call message_segment_$own_read_index (mseg_index, area_ptr,
message_wanted, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from message_segment_$open, identifying
the message segment from which the message is to be obtained.
(Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

message_wanted
is a flag indicating which message is wanted. (Input) If
"0"b, the first message found is returned; if "1"b, the last
is returned.

ms_arg_ptr
is a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

_______________________________ _______________________________

message_segment_$own_read_index message_segment_$own_read_index
_______________________________ _______________________________

ACCESS REQUIRED

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

_______________________________ _________________

message_segment_$own_read_index $read_delete_file
_______________________________ _________________

NNNaaammmeee::: $$$rrreeeaaaddd_dddeeellleeettteee_fffiiillleee

The read_delete_file entrypoint returns a message from a message
segment and deletes it from the message segment.

USAGE

declare message_segment_$read_delete_file entry (char (*), char
(*), ptr, bit(1) aligned, ptr, fixed bin(35));

call message_segment_$read_delete_file (dir_name, entry_name,
area_ptr, message_wanted, ms_arg_ptr, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

message_wanted
is a flag indicating which message is wanted. (Input) If
"0"b, the first message found is returned; if "1"b, the last
is returned.

ms_arg_ptr
os a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

_________________ _________________

$read_delete_file $read_delete_file
_________________ _________________

ACCESS REQUIRED

The calling process must have both "r" and "d" extended access to
the message segment in order to read and delete a message. The
authorization of the process must dominate the access class of
the parent of the message segment and must be dominated by the
access class of the message segment. In addition, the
authorization of the calling process must be equal to the access
class of the message to be read and deleted. If the process
authorization dominates the message access class, then the code
error_table_$ai_restricted will be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

_________________ __________________

$read_delete_file $read_delete_index
_________________ __________________

NNNaaammmeee::: $$$rrreeeaaaddd_dddeeellleeettteee_iiinnndddeeexxx

The read_delete_index entrypoint returns a message from a message
segment and deletes it from the message segment.

USAGE

declare message_segment_$read_delete_index entry (fixed bin, ptr,
bit(1) aligned, ptr, fixed bin(35));

call message_segment_$read_delete_index (mseg_index, area_ptr,
message_wanted, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from message_segment_$open, identifying
the message segment from which the message is to be obtained
and subsequently deleted. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

message_wanted
is a flag indicating which message is wanted. (Input) If
"0"b, the first message found is returned; if "1"b, the last
is returned.

ms_arg_ptr
os a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

ACCESS REQUIRED

__________________ __________________

$read_delete_index $read_delete_index
__________________ __________________

access class of the message segment. In addition, the
authorization of the calling process must be equal to the access
class of the message to be read and deleted. If the process
authorization dominates the message access class, then the code
error_table_$ai_restricted will be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

__________________ __________

$read_delete_index $read_file
__________________ __________

NNNaaammmeee::: $$$rrreeeaaaddd_fffiiillleee

The read_file entrypoint returns a message from a message
segment.

USAGE

declare message_segment_$read_file entry (char (*), char (*),
ptr, bit(1) aligned, ptr, fixed bin(35));

call message_segment_$read_file (dir_name, entry_name, area_ptr,
message_wanted, ms_arg_ptr, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

ms_arg_ptr
is a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

__________ __________

$read_file $read_file
__________ __________

ACCESS REQUIRED

The caller must have "r" extended access to the message segment
to read a message. The authorization of the caller must both
dominate the access class of the parent of the message segment
and dominate the access class of the message to be returned.

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

__________ ___________________________

$read_file message_segment_$read_index
__________ ___________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$rrreeeaaaddd_iiinnndddeeexxx

The read_index entrypoint returns a message from a message
segment.

USAGE

declare message_segment_$read_index entry (fixed bin, ptr, bit(1)
aligned, ptr, fixed bin(35));

call message_segment_$read_index (mseg_index, area_ptr,
message_wanted, ms_arg_ptr, code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment from which a message is to be
obtained. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message. (Input)

ms_arg_ptr
is a pointer to the structure "mseg_return_args", which will
be filled in with information about the selected message.
(Input)

___________________________ ___________________________

message_segment_$read_index message_segment_$read_index
___________________________ ___________________________

ACCESS REQUIRED

NOTES

The structure "mseg_return_args" is declared in the include file
mseg_return_args.incl.pl1, and is defined as follows:

Where:

ms_ptr
is a pointer to the message.

ms_len
is the length of the message in bits.

sender_id
is the process group ID of the sending process.

level
is the validation level of the sending process.

ms_id
is the unique ID of the message.

sender_authorization
is the access authorization of the sending process.

access_class
is the access class of the message.

___________________________ __________________

message_segment_$read_index $read_message_file
___________________________ __________________

NNNaaammmeee::: $$$rrreeeaaaddd_mmmeeessssssaaagggeee_fffiiillleee

The read_message_file entrypoint allows the caller to read a
message from a message segment, optionally reading its own
messages and/or deleting the message just read. The behavior of
this entrypoint is controlled by an input structure.

USAGE

declare message_segment_$read_message_file entry (char (*), char
(*), ptr, ptr, fixed bin(35));

call message_segment_$read_message_file (dir_name, entry_name,
area_ptr, mseg_message_info_ptr, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message text. (Input)

mseg_message_info_ptr
is a pointer to the structure "mseg_message_info", described
below. (Input)

ACCESS REQUIRED

__________________ __________________

$read_message_file $read_message_file
__________________ __________________

class of the message segment. In addition, the authorization of
the process must dominate the access class of the message to be
read, and be equal to the access class of the message to be
deleted.

NOTES

The structure "mseg_message_info" is declared in the include file
mseg_message_info.incl.pl1, and defined as follows:

version Is the version of this structure. The caller must set
this to MSEG_MESSAGE_INFO_v1.

__________________ __________________

$read_message_file $read_message_file
__________________ __________________

own is a flag. If set to "1"b, only messages added to the
segment by the calling user will be returned. This
must be set by the caller.

delete is a flag. If set to "1"b, the message will be deleted
after it is read out. This must be set by the caller.

ms_ptr is a pointer to the message read from the message segment.
This pointer is meaningful if and only if code is
returned 0. The message always begins on a double-word
boundary.

ms_len is the length of the message, in bits.

ms_id is a message segment/message segment message id. If the
message_code is MSEG_READ_SPECIFIED, this is
interpreted on input, and must be the message id of a
message in the message segment to which the caller has
access. If the message_code is
MSEG_READ_BEFORE_SPECIFIED or
MSEG_READ_AFTER_SPECIFIED, this is used for comparison
only and need not identify any message. On output, it
is the message id of the returned message.

ms_access_class is the access class of the message returned.

sender_id is the process group id of the process that added the
message to the segment.

sender_process_id is the process id of the process that added the
message to the segment. It may be zero to indicate
that no process id is available.

sender_level is the validation level of the process that added
the message to the segment.

sender_authorization is the authorization, including privileges,
of the process that added the message to the message

__________________ ___________________

$read_message_file $read_message_index
__________________ ___________________

segment.

sender_max_authorization is the max authorization of the process
that added the message to the message segment.

sender_audit are the audit flags for the process sending the
message.

________________________________________

NNNaaammmeee::: $$$rrreeeaaaddd_mmmeeessssssaaagggeee_iiinnndddeeexxx

The read_message_index entrypoint allows the caller to read a
message from a message segment, optionally reading its own
messages and/or deleting the message just read. The behavior of
this entrypoint is controlled by an input structure.

USAGE

declare message_segment_$read_message_index entry (fixed bin,
ptr, ptr, fixed bin(35));

call message_segment_$read_message_index (mseg_index, area_ptr,
mseg_message_info_ptr, code);

ARGUMENTS

mseg_index
is the value returned from a call to message_segment_$open,
identifying the message segment from which the message is to
be read. (Input)

area_ptr
is a pointer to an area where message segment can allocate the
message text. (Input)

mseg_message_info_ptr
is a pointer to the structure "mseg_message_info", described
below. (Input)

___________________ ___________________

$read_message_index $read_message_index
___________________ ___________________

ACCESS REQUIRED

The calling process must have the following effective extended
access to the message segment: "r" to read an arbitrary message;
"o" or "r" to read its own message; "d" to delete an arbitrary
message; "o" or "d" to delete its own message. The authorization
of the calling process must dominate the access class of the
parent of the message segment. To delete a message, the
authorization of the process must be dominated by the access
class of the message segment. In addition, the authorization of
the process must dominate the access class of the message to be
read, and be equal to the access class of the message to be
deleted.

NOTES

The structure "mseg_message_info" is declared in the include file
mseg_message_info.incl.pl1, and defined as follows:

___________________ ___________________

$read_message_index $read_message_index
___________________ ___________________

version Is the version of this structure. The caller must set
this to MSEG_MESSAGE_INFO_v1.

own is a flag. If set to "1"b, only messages added to the
segment by the calling user will be returned. This
must be set by the caller.

delete is a flag. If set to "1"b, the message will be deleted
after it is read out. This must be set by the caller.

ms_ptr is a pointer to the message read from the message segment.
This pointer is meaningful if and only if code is
returned 0. The message always begins on a double-word
boundary.

ms_len is the length of the message, in bits.

___________________ ____________________________________

$read_message_index message_segment_$set_max_length_file
___________________ ____________________________________

access. If the message code is
MSEG_READ_BEFORE_SPECIFIED or
MSEG_READ_AFTER_SPECIFIED, this is used for comparison
only and need not identify any message. On output, it
is the message id of the returned message.

ms_access_class is the access class of the message returned.

sender_id is the process group id of the process that added the
message to the segment.

sender_process_id is the process id of the process that added the
message to the segment. It may be zero to indicate
that no process id is available.

sender_level is the validation level of the process that added
the message to the segment.

sender_authorization is the authorization, including privileges,
of the process that added the message to the message
segment.

sender_max_authorization is the max authorization of the process
that added the message to the message segment.

sender_audit are the audit flags for the process sending the
message.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$ssseeettt_mmmaaaxxx_llleeennngggttthhh_fffiiillleee

The set_max_length_file entrypoint sets the maximum length of a
message segment.

USAGE

declare message_segment_$set_max_length_file entry (char(*),
char(*), fixed bin(19), fixed bin(35));

call message_segment_$set_max_length_file (dir_name, entry_name,
max_length, code);

ARGUMENTS

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

____________________________________ __________________

message_segment_$set_max_length_file $set_safety_switch
____________________________________ __________________

entry_name
is the name of the message segment. (Input)

max_length
is the new maximum length of the message segment. (Input)

ACCESS REQUIRED

The calling process must have modify access to the parent of the
message segment. The authorization of the calling process must
be equal to the access class of the parent of the message
segment.

________________________________________

NNNaaammmeee::: $$$ssseeettt_sssaaafffeeetttyyy_ssswwwiiitttccchhh

The set_safety_switch entrypoint changes the value of the safety
switch for a message segment.

USAGE

declare message_segment_$set_safety_switch entry (char(*),
char(*), bit(1) aligned, fixed bin(35));

call message_segment_$set_safety_switch (dir_name, entry_name,
safety_switch, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

safety_switch
is the new value of the safety switch. (Input)

code
is a standard system status code. (Output) It can have the

__________________ ____________________________________

$set_safety_switch message_segment_$update_message_file
__________________ ____________________________________

following values:
error_table_$moderr
incorrect access modes to perform the operation.
error_table_$ai_restricted
incorrect authorization to complete the operation.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
message segment. The authorization of the calling process must
equal the access class of the parent of the message segment.

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$uuupppdddaaattteee_mmmeeessssssaaagggeee_fffiiillleee

The update_message_file entrypoint changes the contents of a
message in a message segment.

USAGE

declare message_segment_$update_message_file entry (char (*),char
(*), fixed bin(24), bit(72) aligned, ptr, fixed bin(35));

call message_segment_$update_message_file (dir_name, entry_name,
message_len, message_id, message_ptr, code);

ARGUMENTS

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

entry_name
is the name of the message segment. (Input)

message_len
is the name of the message segment. (Input)

message_id
is the identifier of the message to be modified. (Input)

message_ptr
is a pointer to the new message. (Input)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$moderr
incorrect access modes to perform the operation.

____________________________________ _____________________

message_segment_$update_message_file $update_message_index
____________________________________ _____________________

error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$no_message
no message available with desired characteristics.

ACCESS REQUIRED

The calling process must have "d" extended access to the message
segment to update a message. The authorization of the calling
process must dominate the parent of the message segment that
contains the message and must be equal to the access class of the
message to be updated.

________________________________________

NNNaaammmeee::: $$$uuupppdddaaattteee_mmmeeessssssaaagggeee_iiinnndddeeexxx

The update_message_index entrypoint changes the contents of a
message in a message segment.

USAGE

declare message_segment_$update_message_index entry (fixed bin,
fixed bin(24), bit(72) aligned, ptr, fixed bin(35));

call message_segment_$update_message_index (mseg_index,
message_len, message_id, message_ptr, code);

ARGUMENTS

mseg_index
is the valued returned from a call to message_segment_$open,
identifying the message segment which is to have one of its
messages updated. (Input)

message_len
is the name of the message segment. (Input)

message_id
is the identifier of the message to be modified. (Input)

message_ptr
is a pointer to the new message. (Input)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$moderr
incorrect access modes to perform the operation.

_____________________ _________________________

$update_message_index message_segment_$validate
_____________________ _________________________

error_table_$ai_restricted
incorrect authorization to complete the operation.
error_table_$no_message
no message available with desired characteristics.

ACCESS REQUIRED

________________________________________

NNNaaammmeee::: mmmeeessssssaaagggeee_ssseeegggmmmeeennnttt_$$$vvvaaallliiidddaaattteee

The validate entrypoint determines whether or not a given entry
is a message segment.

USAGE

declare message_segment_$validate entry (char(*), char(*), fixed
bin(35));

call message_segment_$validate (dir_name, entry_name, code);

ARGUMENTS

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

entry_name
is the name of the potential message segment. (Input)

code
is a standard system status code. (Output) It can have the
following values:
error_table_$not_seg_type
the entry is not a message segment.
error_table_$no_info
no information on the entry is available.

_________________________ ____________

message_segment_$validate pnt_fs_gate_
_________________________ ____________

ACCESS REQUIRED

NOTES

For an entry to be considered a message segment, it must have the
"ms" suffix and have ring brackets of (1, 1, 1).

________________________________________

NNNaaammmeee::: pppnnnttt_fffsss_gggaaattteee_

EEEnnntttrrryyy::: pppnnnttt_fffsss_gggaaattteee_$$$aaadddddd_aaaccclll_eeennntttrrriiieeesss

This entry point adds specified access modes to the access
control list (ACL) of the specified PNT. If an access name
already appears on the ACL of the PNT, its mode is changed to the
one specified by the call.

USAGE

declare pnt_fs_gate_$add_acl_entries entry (char(*), char(*),
ptr, fixed bin(35));

call pnt_fs_gate_$add_acl_entries (dir_name, entry_name, acl_ptr,
code);

ARGUMENTS

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

entry_name
is the entry name of the PNT. (Input)

acl_ptr
points to a user-filled general_acl structure (see "Entry
Information" below). (Input)

____________ ____________

pnt_fs_gate_ pnt_fs_gate_
____________ ____________

code
is a storage system status code. (Output) Its value may be:
error_table_$moderr
incorrect access on entry. (See Access Required Section).

ENTRY INFORMATION

The general_acl structure should be declared in the following
way:

dcl 1 general_acl aligned based (acl_ptr),
2 version char (8) aligned,
2 count fixed bin,
2 entries (acl_count refer (general_acl.count)) aligned
like general_acl_entry;

STRUCTURE ELEMENTS

version
is the version of the structure and must be set to
GENERAL_ACL_VERSION_1.

count
must be set to the number of acl entries after the structure
has been allocated.

The general_acl_entry structure (declared in the include file
acl_structures.incl.pl1) is as follows:

dcl 1 general_acl_entry aligned based,
2 access_name char(32) unaligned,
2 mode bit(36) aligned,
2 status_code fixed bin(35);

STRUCTURE ELEMENTS

access_name
is the access name (in the form Person_id.Project_id.tag) that
identifies the processes to which this ACL entry applies.

mode
contains the modes for this access name. The first three bits
correspond to the modes read, execute, and write. The
remaining bits must be zeros. For example, rw access is
expressed as "101"b. The execute mode does not apply to MSF's
and thus to PNT's.

status_code
is a standard system status code for this ACL entry only.

____________ ____________

pnt_fs_gate_ pnt_fs_gate_
____________ ____________

NOTES

If code is returned as error_table_$argerr, then the erroneous
ACL entries in the general_acl structure have status_code set to
an appropriate error code. No processing is performed.

ACCESS REQUIRED

Because PNT's are implemented using MSF's, RW access on the PNT
itself (which translates to SMA to the directory portion) is
required to modify the PNT's access. Authorization of the
calling process must be equal to the access class of the parent
of the PNT. The system PNT is at system_low.

EEEnnntttrrryyy::: pppnnnttt_fffsss_gggaaattteee_$$$ccchhhnnnaaammmeee_fffiiillleee

The chname_file entrypoint changes the entry name on a specified
PNT. If an already existing name (an old name) is specified, it
is deleted from the entry; if a new name is specified, it is
added. Thus, if only an old name is specified, the effect is to
delete a name; if only a new name is specified, the effect is to
add a name; and if both are specified, the effect is to rename
the entry.

USAGE

declare pnt_fs_gate_$chname_file entry (char(*), char(*),
char(*), char(*), fixed bin(35));

call pnt_fs_gate_$chname_file (dir_name, entry_name,
old_entry_name, new_entry_name, code);

ARGUMENTS

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

entry_name
is the name of the PNT. (Input)

old_entry_name
is the name to be deleted from the PNT. (Input) It can be a
null character string ("") in which case no name is deleted.
If oldname is null, then newname must not be null.

new_entry_name
is the name to be added to the entry. (Input) It must not

____________ ____________

pnt_fs_gate_ pnt_fs_gate_
____________ ____________

already exist in the directory on this or another entry. It
can be a null character string ("") in which case no name is
added. If it is null, then oldname must not be the only name
on the entry.

ACCESS REQUIRED

The calling process must have modify access to the parent of the
PNT. The authorization of the calling process must equal the
access class of the parent of the PNT.

EEEnnntttrrryyy::: pppnnnttt_fffsss_gggaaattteee_$$$dddeeellleeettteee_aaaccclll_eeennntttrrriiieeesss

This entry point deletes specified entries from an access control
list (ACL) for a PNT.

USAGE

declare pnt_fs_gate_$delete_acl_entries entry (char(*), char(*),
ptr, fixed bin35));

call pnt_fs_gate_$delete_acl_entries (dir_name, entryname,
acl_ptr, code);

ARGUMENTS

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

entryname
is the entryname of the PNT. (Input)

acl_ptr
points to a user-filled general_delete_acl structure (see
"Entry Information" below). (Input)

____________ ____________

pnt_fs_gate_ pnt_fs_gate_
____________ ____________

code
is a storage system status code. (Output) Its value may be:
error_table_$moderr
incorrect access on entry (See Access Required Section).

ENTRY INFORMATION

The general_delete_acl structure should be declared in the
following way:

dcl 1 general_delete_acl aligned based (acl_ptr),
2 version char (8) aligned,
2 count fixed bin,
2 entries (acl_count refer (general_delete_acl.count))
aligned like general_delete_acl_entry;

STRUCTURE ELEMENTS

version
is the version of the structure and must be set to
GENERAL_DELETE_ACL_VERSION_1.

count
must be set to the number of acl entries after the structure
has been allocated.

The general_delete_acl_entry structure (declared in the
include file acl_structures.incl.pl1) is as follows:

dcl 1 general_delete_acl_entry aligned based,
2 access_name char (32) unaligned,
2 status_code fixed bin (35);

STRUCTURE ELEMENTS

access_name
is the access name (in the form of Person_id.Project_id.tag)
that identifies the ACL entry to be deleted.

status_code
is a storage system status code for this ACL entry only.

NOTES

If code is returned as error_table_$argerr, then the erroneous
ACL entries in the delete_acl_array structure have status_code
set to an appropriate error code. No processing is performed.

____________ ____________

pnt_fs_gate_ pnt_fs_gate_
____________ ____________

If an access name cannot be matched to a name already on the ACL
of the PNT, then the status_code for that ACL entry in the
delete_acl_array structure is set to error_table_$user_not_found.
Processing continues for the rest of the general_delete_acl
entries and code is returned as 0.

ACCESS REQUIRED

EEEnnntttrrryyy::: pppnnnttt_fffsss_gggaaattteee_$$$llliiisssttt_aaaccclll

This entry point is used either to list the entire access control
list (ACL) of a PNT or to return the access modes of specified
ACL entries. The general_acl structure used by this entry point
is discussed in the description of pnt_fs_gate_$add_acl_entries.

USAGE

declare pnt_fs_gate_$list_acl entry (char(*), char(*), ptr, ptr,
fixed bin(35));

call pnt_fs_gate_$list_acl (dir_name, entryname, area_ptr,
acl_ptr, code);

ARGUMENTS

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

entryname
is the entryname of the PNT. (Input)

area_ptr
points to an area in which the list of ACL entries, which make
up the entire ACL of the PNT, is allocated. (Input) If
area_ptr is not null, then the user wants access modes for
certain ACL entries; these will be specified by the structure
pointed to by acl_ptr (see below). Otherwise, the entire ACL
is to be returned.

____________ ____________

pnt_fs_gate_ pnt_fs_gate_
____________ ____________

acl_ptr
points to an ACL structure, general_acl, into which the ACL
information is placed. If area ptr is not null the structure
contains the access names for which the modes are requested.
(Input)

code
is a storage system status code. (Output) It will generally
be 0 (see Access Required Section).

NOTES

If acl_ptr is used to obtain modes for specified access names
(rather than for all access names on a PNT), then each ACL entry
in the segment_acl_array structure either has status_code set to
0 and contains the PNT's mode or has status_code set to
error_table_$user_not_found and contains a mode of 0.

ACCESS REQUIRED

MSF's must have S permission on the directory portion to *.*.*,
which is all the access required by this gate. The authorization
of the calling process must dominate the access class of the
parent of the PNT. The system PNT is is at system_low and thus
accessible to everyone.

EEEnnntttrrryyy::: pppnnnttt_fffsss_gggaaattteee_$$$rrreeeppplllaaaccceee_aaaccclll

This entry point replaces an entire access control list (ACL) for
a PNT with a user-provided ACL, and can optionally add an entry
for *.SysDaemon.* with mode rw to the new ACL. The general_acl
structure described in pnt_fs_gate_$add_acl_entries is used by
this entry point.

USAGE

declare pnt_fs_gate_$replace_acl entry (char(*), char(*), ptr,
bit(1), fixed bin(35));

call pnt_fs_gate_$replace_acl (dir_name, entryname, acl_ptr,
no_sysdaemon_sw, code);

ARGUMENTS

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

entryname
is the entryname of the PNT. (Input)

____________ ____________

pnt_fs_gate_ pnt_fs_gate_
____________ ____________

acl_ptr
points to the user supplied general_acl structure that is to
replace the current ACL. (Input)

no_sysdaemon_sw
is a switch that indicates whether an rw *.SysDaemon.* entry
is to be put on the ACL of the PNT after the existing ACL has
been deleted and before the user-supplied segment_acl_array
entries are added. (Input)
"0"b adds rw *.SysDaemon.* to ACL.
"1"b replaces the existing ACL with only the user-supplied
segment_acl_array.

code
is a storage system status code. (Output) error_table_$moderr
is returned if the user does not have RW permission to the PNT
(see Access Required section).

NOTES

If general_acl.count is zero, then the existing ACL is deleted
and only the action indicated (if any) by the no_sysdaemon_sw
switch is performed. If general_acl.count is greater than zero,
processing of the general_acl entries is performed top to bottom,
allowing later entries to overwrite previous ones if the
access_name in the general_acl structure is identical.

ACCESS REQUIRED

EEEnnntttrrryyy::: pppnnnttt_fffsss_gggaaattteee_$$$vvvaaallliiidddaaattteee

The validate entrypoint determines whether or not a given entry
is a PNT.

USAGE

declare pnt_fs_gate_$validate entry (char(*), char(*), fixed
bin(35));

call pnt_fs_gate_$validate (dir_name, entry_name, code);

____________ _____________________

pnt_fs_gate_ priv_connection_list_
____________ _____________________

ARGUMENTS

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

entry_name
is the name of the potential PNT. (Input)

code
is a standard system status code. (Output) It may have the
values:
error_table_$not_seg_type
entry is not of the given type (if the gate is called on a
directory or non-PNT MSF)
error_table_$not_a_dir
entry is not a directory (if the gate is called on a
segment).

NOTES

For an entry to be considered a PNT, it must be an MSF with the
"pnt" suffix and have ring brackets of (1, 1, 1).

ACCESS REQUIRED

________________________________________

NNNaaammmeee::: ppprrriiivvv_cccooonnnnnneeeccctttiiiooonnn_llliiisssttt_

This gate contains privileged entries to
connection_list_manager_. In general, they can be used only by
login server processes, and only to manipulate entries for
connections of which the calling process is the owner. The
entries contained in priv_connection_list_ are listed below,
along with their target entries in connection_list_manager_.

Gate entry Target

add add
change_user priv_change_user
delete_name priv_delete_name
delete_offset priv_delete_offset
delete_all_for_user priv_delete_all_for_user

_____________________ ____

priv_connection_list_ rcp_
_____________________ ____

get_name priv_get_name
get_next_user priv_get_next_user
get_next_owner priv_get_next_owner
remove_user priv_remove_user

________________________________________

NNNaaammmeee::: rrrcccppp_

EEEnnntttrrryyy::: rrrcccppp_$$$aaacccqqquuuiiirrreee

This entrypoint finds a free resource that meets or exceeds the
user-given criteria, and makes the user the owner of the
resource, having control of the resource and having resource
executive (E access) to the resource.

USAGE

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

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

ARGUMENTS

resource_desc_ptr
pointer to a resource description structure. See "Notes"
below for structure definition. (Input)

registry_dir
the absolute pathname of the registry directory. (Input)

code
is a storage 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
acquisition.

____ ____

rcp_ rcp_
____ ____

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

error_table_$rcp_bad_attributes
the attributes specified by the user are invalid.

error_table_$resource_locked
the resource is locked and unavailable.

error_table_$resource_not_free
the requested resource is not in the free state and
cannot be acquired.

error_table_$resource_unavailable
the requested resource is unavailable.

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

error_table_$unimplemented_version
the version supplied in the resource descriptions
structure is invalid.

ACCESS REQUIRED

Anyone can acquire a free resource. Resources in the free pool
have REW access to *.*.

NOTES

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

____ ____

rcp_ rcp_
____ ____

dcl 1 resource_descriptions based (resource_desc_ptr) aligned,
2 version_no fixed bin,
2 n_items fixed bin,
2 item (Resource_count refer (resource_descriptions.n_items)) aligned,
3 type char (32),
3 name char (32),
3 uid bit (36),
3 potential_attributes bit (72),
3 attributes (2) bit (72),
3 desired_attributes (4) bit (72),
3 potential_aim_range (2) bit (72),
3 aim_range (2) bit (72),
3 owner char (32),
3 acs_path char (168),
3 location char (168),
3 comment char (168),
3 charge_type char (32),
3 rew bit (3) unaligned,
3 (usage_lock,
release_lock,
awaiting_clear,
user_alloc) bit (1) unaligned,
3 pad2 bit (29) unaligned,
3 given aligned,
(4 (name,
uid,
potential_attributes,
desired_attributes,
potential_aim_range,
aim_range,
owner,
acs_path,
location,
comment,
charge_type,
usage_lock,
release_lock,
user_alloc) bit (1),
4 pad1 bit (22)) unaligned,
3 state bit (36) aligned,
3 status_code fixed bin (35);

version_no
version number of the resource_descriptions structure.

n_items
number of items to be acquired.

____ ____

rcp_ rcp_
____ ____

type
resource type being acquired.

resource_name
name of resource to be acquired.

uid
resource identifying number not used for acquires.

potential_attributes
not used for acquires.

attributes
attributes of the resource; density, model, etc.

desired_attributes
a resource can be acquired by attribute selection.

aim_range
actual aim_range of an acquired resource.

potential_aim_range
range of aim classes for a free resource.

owner
defines the resource owner after an acquisition.

acs_path
specifies the absolute pathname of the ACS segment for the
resource.

location
not used for acquisitions.

comment
a comment string for the resource, i.e. "dump tape".

charge_type
not used for acquisitions.

rew
defines the user's access to the resource.

usage_lock, release_lock, awaiting_clear
not used for acquisitions.

____ ____

rcp_ rcp_
____ ____

EEEnnntttrrryyy::: rrrcccppp_$$$aaassssssiiigggnnn_dddeeevvviiiccceee

This entry point attempts to assign one device class resource to
the calling process. Specifications regarding the device to be
assigned are supplied by the caller using the appropriate
structure defined in rcp_device_info_structs.incl.pl1 to which
this routine is passed a pointer. Internally an entry is
completed and entered in rcp_com_seg which contains information
about the assignment. The actual assignment is not complete
until it is checked by rcp_$check_assign.

USAGE

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

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

ARGUMENTS

device_type
describes the type of device requested. This value must be
one of the following: tape_drive, disk_drive, console,
printer, punch, reader, special. (Input)

device_info_ptr
is a pointer to the structure rcp_device_info found in
rcp_device_info_structs.incl.pl1, which contains information
about the device to be assigned. See "Notes" below for
structure definition. (Input)

event_id
is an event channel id supplied by the caller but is no longer
used. (Input)

comment
is a message to be displayed to the operator upon completion
of the assignment. (Input)

rcp_id
Internally generated unique id for this rcp assignment.
(Output)

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

____ ____

rcp_ rcp_
____ ____

error_table_$resource_assigned
indicates the specified resource is already assigned.
error_table_$resource_bad_access
not enough access to assign the desired resource.
error_table_$resource_unavailable
no resource available to meet the request.
error_table_$resource_unknown
requested resource unknown to the system.

ACCESS REQUIRED

RW is required to assign a device. The ACS must exist for
devices and is usually located in >sc1>rcp>DEVICE_NAME.acs. If
the ACS does not exist, the error code,
error_table_$insufficient_access or
error_table_$resource_bad_access is returned.

NOTES

The device_info structure is defined in
rcp_device_info_structs.incl.pl1 and overlays the appropriate
structure for the device type. For example, for tapes, the
structure tape_info, also declared in
rcp_device_info_structs.incl.pl1, should be used; a pointer to it
passed to this entry point. The overlay structure pointed to by
device_info_ptr is declared as follows (For details of
type-specific structures see the include file):

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);

version_num
version number of this structure.

usage_time
number of minutes device will/may be used.

wait_time
number of minutes user will/must wait for assignment
completion.

system_flag
"1"b user wants to be a system process for this assignment.

____ ____

rcp_ rcp_
____ ____

device_name
device name.

model
model number of the device.

qualifiers
qualifying characteristics such as tape_drive speed, density,
etc.

EEEnnntttrrryyy::: rrrcccppp_$$$aaattttttaaaccchhh

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)

____ ____

rcp_ rcp_
____ ____

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
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 inaccessible.

____ ____

rcp_ rcp_
____ ____

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.

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 describes the structures for each
resource in more detail.

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.)

____ ____

rcp_ rcp_
____ ____

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)

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

EEEnnntttrrryyy::: rrrcccppp_$$$aaattttttaaaccchhh_lllvvv

Performs an IOI attachment for one logical volume. The logical
volume name supplied must have been previously registered. This
routine can only be used for removable-media devices.

USAGE

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

call rcp_$attach_lv (volume_info_ptr, event_chan, rcp_id, code);

ARGUMENTS

volume_info_ptr
pointer to logical volume info structure as defined in
rcp_lv_info.incl.pl1 (see below). (Input)

event_chan
an event channel supplied by the caller. (Input)

rcp_id
rcp unique identification number for this logical volume
attachment. (Output)

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

error_table_$resource_bad_access
not enough access to attach the desired logical volume.

____ ____

rcp_ rcp_
____ ____

error_table_$unimplemented_version
incorrect version supplied by lv_info structure.

error_table_$unregistered_volume
logical volume requested is not registered.

ACCESS REQUIRED

Everyone has RW access to public volumes. If the volume is
private, access is determined by the volume_name.ACS. If the ACS
does not exist for a private logical volume, only the logical
volume owner (Person_id.SysAdmin) has access.

NOTES

The data structure pointed to volume_info_ptr is defined in
rcp_lv_info.incl.pl1 as follows:

dcl 1 lv_info_based (lv_info_ptr) aligned,
2 version_num fixed bin,
2 usage_time fixed bin,
2 wait_time fixed bin,
2 system_flag bit(1),
2 volume_name char(32);

version_num
version number of structure.

usage_time
number of minutes device will/may be used.

volume_name
name of registered logical volume.

EEEnnntttrrryyy::: rrrcccppp_$$$cccaaannnccceeelll_iiiddd_ssstttrrriiinnnggg

Implements reservation cancelling given a reservation id.

USAGE

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

call rcp_$cancel_id_string (res_id, code);

____ ____

rcp_ rcp_
____ ____

ARGUMENTS

res_id
is the rcp generated reservation id for the resource
reservation being cancelled. (Input)

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

error_table_$noentry
no volume or device was found in rcp_data which
corresponded to the volume or device in the reservation.

error_table_$request_id_ambiguous
the reservation id supplied is invalid.

error_table_$invalid_resource_state
the volume or device is not reserved.

ACCESS REQUIRED

The only requirement to cancel resource reservations is that the
process be the same process that made the reservation. All
resource reservations are automatically cancelled when the
process terminates.

EEEnnntttrrryyy::: rrrcccppp_$$$ccchhheeeccckkk_aaassssssiiigggnnn

This routine checks the assignment made by rcp_$assign_device.
An assignment is not complete until this entry point has been
called. In particular, the state of rcp_device_info and the
rcp_com_seg entry for this assignment is examined for
correctness.

USAGE

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

call rcp_$check_assign (rcp_id, device_info_ptr, comment, statex,
code);

ARGUMENTS

rcp_id
Unique id for this rcp assignment generated by
rcp_$assign_device. (Input)

____ ____

rcp_ rcp_
____ ____

device_info_ptr
is a pointer to the structure rcp_device_info.incl.pl1, which
contains information about the device to be assigned. See the
description of rcp_device.info.incl.pl1 in the
rcp_$assign_device entry point. (Input)

comment
is a message to be displayed to the operator upon completion
of the assignment. (Input)

statex
state of this assignment. (Output) Can be one of the
following values:.

statex = 0
indicates to caller that everything was OK.
statex = 3
indicates to caller that there was an error returned in
code.

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

error_table_$bad_arg
indicates a bad argument passed to rcp_$check_assign.
error_table_$invalid_state
the rcp_com_seg entry for this assignment is not in the
assignment state.

EEEnnntttrrryyy::: rrrcccppp_$$$ccchhheeeccckkk_aaattttttaaaccchhh

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);

____ ____

rcp_ rcp_
____ ____

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)

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.

____ ____

rcp_ rcp_
____ ____

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.

EEEnnntttrrryyy::: rrrcccppp_$$$ccchhheeeccckkk_aaattttttaaaccchhh_lllvvv

This entry point must be called after a call to rcp_$attach_lv.
It checks that the rcp_id supplied is for a valid logical volume
attachment and if so returns the logical volume id and the
state_index. This routine is basically a no op.

USAGE

declare rcp_$check_attach_lv entry (bit (36) aligned, ptr, fixed
bin, fixed bin (35));

call rcp_$check_attach_lv (rcp_id, volume_info_ptr, state_index,
code);

ARGUMENTS

rcp_id
is the unique rcp identifying number for the logical volume
attachment. (Input)

volume_info_ptr
not used.

state_index
a zero state_index indicates everything is OK; when the
state_index returned is a three then an error has occured.
(Output)

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

error_table_$bad_index
indicates RCP cannot find the index of the logical volume
from the given rcp_id. A possibly erroneous rcp_id was
supplied.

____ ____

rcp_ rcp_
____ ____

ACCESS REQUIRED

There are no access requirements for rcp_$check_attach_lv. It
must be called, however, after a call to rcp_$check_attach_lv.

EEEnnntttrrryyy::: rrrcccppp_$$$cccooopppyyy_llliiisssttt

This entry is called to return rcp_com_seg (RCS) information
about all attachments and assignments of the calling process.

USAGE

declare rcp_$copy_list entry (ptr, fixed bin(19), fixed bin(35));

call rcp_$copy_list (to_ptr, copy_size, code);

ARGUMENTS

to_ptr
pointer to caller's work segment where information should be
placed. See "Notes" below for structure definition. (Input)

copy_size
size of caller's work segment. (Input)

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

error_table_$bad_arg
the size of the user's work segment is larger than the
maximum allowed.

error_table_$unimplemented_version
the version number in the rcp_list structure defined
below, is incorrect.

error_table_$item_too_big
the resulting information is too large to fit in the user
supplied work segment.

ACCESS REQUIRED

There are no access requirements since the user can only obtain
information about the current process assignments and
attachments.

____ ____

rcp_ rcp_
____ ____

NOTES

The rli structure pointed to by the to_ptr is defined in
rcp_list.incl.pl1 and is declared as follows:

dcl 1 rli based (rli_ptr) aligned,
2 head like rli_header,
2 dassigns (0 refer (rli.head.num_dassign)) like dassign,
2 attaches (0 refer (rli.head.num_attach)) like attach,
2 lvs (0 refer (rli.head.num_lv)) like lv,
2 device_resvs (0 refer (rli.head.num_device_resv))
like device_resv,
2 vol_resvs (0 refer (rli.head.num_vol_resv)) like vol_resv,
2 end bit (36);

head
contains header information: version number, number of
logical volumes attached, number of device assignment entries,
number of attachments, number of devices reserved, and number
of volumes reserved.

dassigns
array of device assignment entries with the following
information about each assignment for this process: device
name, device type index, device model, device qualifiers, time
device was put into assignment state, current validation
level, disposition, flag indicating whether device is also
attached, rcp_id for the assignment, number of minutes device
may be assigned, number of minutes user waited for the
assignment.

attaches
array of resources attached containing the following
information for each attachment: device and volume names,
device type index, current state of the attachment, current
validation level, flags indicating a privileged attach and an
attach for reading or writing, rcp_id for the attachment,
maximum size of the IOI workspace for the attachment, maximum
IOI time-out interval, index used to communicate with IOI,
number of minutes device may be attached, number of minutes
user waited for the attachment.

lvs
an array of logical volume attachment entries with the
following information for each attachment: logical volume
name, time logical volume attached, rcp_id for the logical
volume attachment.

____ ____

rcp_ rcp_
____ ____

device_resvs
an array of device reservation entries with the following
information for each device reserved: reservation id, who it
was reserved by, device type index, device name.

vol_resvs
an array of volume reservation entries with the following
information for each volume reserved: reservation id, who it
was reserved by, volume type index, volume name.

EEEnnntttrrryyy::: rrrcccppp_$$$dddeeetttaaaccchhh

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);

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)

____ ____

rcp_ rcp_
____ ____

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.

EEEnnntttrrryyy::: rrrcccppp_$$$dddeeetttaaaccchhh_lllvvv

detaches one logical volume from the list of logical volumes
attached for this process.

USAGE

declare rcp_$detach_lv entry (bit(36) aligned, fixed bin(35));

call rcp_$detach_lv (rcp_id, code);

ARGUMENTS

rcp_id
is the rcp unique identifying number for the logical volume
attachment. (Input).

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

error_table_$bad_index
the rcp_id supplied indicates an invalid offset into
rcp_com_seg.

ACCESS REQUIRED

The only requirement to detach a logical volume using
rcp_$detach_lv is that the caller process be the process that
attached the logical volume.

____ ____

rcp_ rcp_
____ ____

EEEnnntttrrryyy::: rrrcccppp_$$$gggeeettt_ssstttaaatttuuusss

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_ rcp_
____ ____

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.

EEEnnntttrrryyy::: rrrcccppp_$$$llliiisssttt_rrreeesssooouuurrrccceeesss

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_ rcp_
____ ____

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.

____ ____

rcp_ rcp_
____ ____

NOTES

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

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.

EEEnnntttrrryyy::: rrrcccppp_$$$ppprrrooommmooottteee

This procedure is called to change (promote or demote) the
caller's validation level for the specified rcp_com_seg entry
(RCSE). This validation level defines the highest ring from
which calls can be made to RCP (and also IOI) that involve this
RCSE. If there is an entry associated with this one then it too
will be promoted or demoted. If an attachment kind of RCSE is
found then IOI will be called to promote or demote the associated
device once the attachment completes.

USAGE

declare rcp_$promote entry (bit(36) aligned, fixed bin, fixed
bin(35));

call rcp_$promote (rcp_id, new_level, code);

____ ____

rcp_ rcp_
____ ____

ARGUMENTS

rcp_id
internally generated unique identifying number for the
assignment or attachment which indicates the entry in
rcp_com_seg which is to be promoted or demoted.

new_level
new level for the associated RCSE for this caller.

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

error_table_$bad_index
the rcp_id indicates an invalid offset into rcp_com_seg
(not a valid RCSE).

error_table_$invalid_state
the RCSE indicated by the rcp_id is in an invalid state.

ACCESS REQUIRED

To promote an attachment RCSE, the caller must have E access to
admin_gate_$ioi_promote.

EEEnnntttrrryyy::: rrrcccppp_$$$rrreeellleeeaaassseee

This entry point relinquishes the resource back to the free pool.
It has the effect of changing the accounting owner back to "free"
and it then becomes available for all to acquire.

USAGE

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

call rcp_$release (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 registry directory. (Input)

____ ____

rcp_ rcp_
____ ____

code
is a storage 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_$not_abs_path
the registry directory pathname is not an absolute
pathname.

error_table_$resource_locked
the resource is locked and unavailable for release.

error_table_$resource_free
the requested resource is already in the free state.

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

error_table_$unimplemented_version
the version supplied in the resource descriptions
structure is invalid.

error_table_$bad_access
the user does not have enough access to release the
resource.

ACCESS REQUIRED

The user must be the resource owner and have REW access. By
default, if there is no acs_path for this resource, the owner
will have REW access. However, in the case that an acs_path is
specified and the user does not have REW effective access, the
release will be denied. In this way, users can protect
themselves from erroneously releasing volumes.

____ ____

rcp_ rcp_
____ ____

EEEnnntttrrryyy::: rrrcccppp_$$$rrreeessseeerrrvvveee

This entry point is called to reserve devices and volumes.
Multiple devices and volumes can be reserved at a time, however,
if the reservation for any one in a set fails the entire
reservation fails. This entry point is primarily used by the
absentee facility to insure that resources required for an
absentee job are available prior to run time. Reservation of the
resources guarantees their exclusive use by the process until
explicit channel of the reservation or process termination. In
this way, an absentee job will not fail during execution due to
the unavailability of resources.

USAGE

declare rcp_$reserve entry (ptr, ptr, fixed bin (35));

call rcp_$reserve (resource_desc_ptr, resource_res_ptr, code);

ARGUMENTS

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

resource_res_ptr
is a pointer to the reservation_description structure. See
"Notes" below for a description of this structure. (Input)

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

error_table_$bad_conversion
the attributes supplied in the reservation_descriptions
structure are invalid.

error_table_$badcall
the number of items requested in the
reservation_descriptions structure does not match the
number of items in the resource_descriptions structure.

error_table_$resource_unknown
resource not know to the system.

error_table_$unimplemented_version
the version number supplied in the resource_descriptions
structure or the reservation_descrption structure is
incorrect.

____ ____

rcp_ rcp_
____ ____

error_table_$device_limit_exceeded
the user already has the maximum number of devices
assigned and cannot reserve any devices.

error_table_$reservation_failed
indicates there are no volumes or devices appropriate,
available, or accessible to meet the requirements of the
reservation specification.

ACCESS REQUIRED

R access is required to reserve a volume; RW access is required
to reserve a device.

NOTES

The reservation_description structure is declared in
resource_control_desc.incl.pl1 and is declared as follows:

dcl 1 reservation_description based (resource_res_ptr) aligned,
2 version_no fixed bin,
2 reserved_for char (32),
2 reserved_by char (32),
2 reservation_id fixed bin (71),
2 group_starting_time fixed bin (71),
2 asap_duration fixed bin (71),
2 flags aligned,
(3 auto_expire bit (1),
3 asap bit (1),
3 rel bit (1),
3 sec bit (1)) unaligned,
2 n_items fixed bin,
2 reservation_group
(Resource_count refer (reservation_description.n_items)),
3 starting_time fixed bin (71),
3 duration fixed bin (71);

version_no
the version number of this structure.
reserved_for
group id of the process who this reservation is for.
reserved_by
group_id of the process performing the reservation.
reservation_id
internally generated reservation id number for this
reservation group.

____ ____

rcp_ rcp_
____ ____

group_starting_time
starting time for the reservation.
asap_duration
after this time the reservation is no longer desired.
auto_expire
"1"b indicates reservation should expire when the process
terminates. (Default).
asap
"1"b indicates make this reservation within the
asap_duration time.
rel
"1"b indicates that times are relative to the current clock
time, otherwise they are absolute times.
sec
"1"b indicates times are in seconds; otherwise they are in
microseconds.
n_items
the number of items being reserved. Must be equal to
n_items in the associated resource_descriptions structure.
starting_time
time the reservation begins. All values in this array will
be equal.
duration
length of time the reservation is good. All values in the
array will be equal.

EEEnnntttrrryyy::: rrrcccppp_$$$ssseeettt_ssstttaaatttuuusss

The set entrypoint will find a resource given its name or UID,
and replace various properties of it (depending on your privilege
and access).

USAGE

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

call rcp_$set_status (resource_desc_ptr, registr_dir, code);

ARGUMENTS

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

registr_dir
the absolute pathname of the registry directory. (Input)

____ ____

rcp_ rcp_
____ ____

code
is a storage 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
use.

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

error_table_$rcp_bad_attributes
the attributes specified by the user are invalid.

error_table_$resource_locked
the resource is locked and unavailable.

error_table_$resource_free
cannot set properties on a free resource.

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

error_table_$unimplemented_version
the version supplied in the resource descriptions
structure is invalid.

error_table_$resource_bad_access
the user does not have enough access to set the desired
properties.

ACCESS REQUIRED

There are two types of set_status. The first type is a
set_access which sets an access property - acs_path. The subject
must be the resource owner and have REW access if the ACS exists.
If the ACS does not exist, the owner by default has REW and is
the only one that can set the acs_path. The second type of
set_status is setting of regular resource properties. These fall
into two categories: those that require REW access (comment,
location, lock, release_lock and charge_type) to prevent a covert

____ ____

rcp_ rcp_
____ ____

channel, and those that require RW access (user_alloc and
attributes). In the first category, only the comment can be set
by a non_privileged user with REW access. All others require the
call to be made through a privileged gate.

EEEnnntttrrryyy::: rrrcccppp_$$$uuunnnaaassssssiiigggnnn

Unassign a resource given its rcp_id.

USAGE

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

call rcp_$unassign (rcp_id, disposition, comment, code);

ARGUMENTS

rcp_id
is the unique id that was generated for the assignment.
(Input)

disposition
unused. (Input)

comment
is a message to be displayed to the operator upon completion
of the unassignment. (Input)

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

error_table_$bad_arg
indicates an erroneous rcp_id was generated and RCP
cannot find the resource entry in rcp_com_seg to which it
refers.

error_table_$resource_unassigned
indicates the resource specified is not assigned to this
process.

ACCESS REQUIRED

The only requirement to unassign a resource using rcp_$unassign
is that process be the same process that made the assignment.
All resources are automatically unassigned when the process
terminates.

____ ____

rcp_ rcp_
____ ____

EEEnnntttrrryyy::: rrrcccppp_$$$uuunnnaaassssssiiigggnnn_dddeeevvviiiccceee

Unassign a device given its name.

USAGE

declare rcp_$unassign_device entry (char(*), bit(*), char(*),
fixed bin(35));

call rcp_$unassign_device (device_name, disposition, comment,
code);

ARGUMENTS

device_name
is the name of the device to be unassigned. (Input)

disposition
unused. (Input)

comment
is a message to be displayed to the operator upon completion
of the unassignment. (Input)

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

error_table_$resource_unassigned
indicates the resource specified is not assigned to this
process.

ACCESS REQUIRED

The only requirement to unassign a resource using rcp_$unassign
is that process be the same process that made the assignment.
All resources are automatically unassigned when the process
terminates.

____ ___________

rcp_ run_test_as
____ ___________

NNNaaammmeee::: rrruuunnn_ttteeesssttt_aaasss

SYNTAX AS A COMMAND

run_test_as test_sc1_dir

FUNCTION

This command establishes a test version of the Initializer's user
control environment in the caller's process. In this
environment, the standard operator requests are available to
manipulate user processes created by the test environment.
Process can be created for Multics Networking Architecture (MNA)
interactive user, absentee users and daemon users.

ARGUMENTS

test_sc1_dir
is the pathname of the user directory to be used as the system
control directory. You must specify a directory other than
>sc1 to avoid interfering with the real user control running
in the Initializer process.

ACCESS REQUIRED

This command requires access to a variety of privileged gates
needed to initialize the System Control and User Control
environments. These include hpriv_connection_list_ and
network_accounting_gate_.

NOTES

The pathname of a test >sc1 directory must be given as an
argument to this command. Do not use the real >sc1 directory, or
you will interfere with operation of the real system control
environment in the Initializer process.

The test >sc1 directory should already contain all segments
needed to run the system control and user control environments.
If segments are missing or incorrectly formatted, error messages
will result and the environment initialization will fail. The
user control environment is not highly robust, so fatal process
errors (although not common) may occur if things are improperly
setup.

___________ _____________

run_test_as restart_fault
___________ _____________

The best way to setup the directory is to refer to the
acct_start_up.ec to see what needs to be in the test >sc1
directory. After the test directory is built, invoke this
command and fix all errors which result. Another (more
frustrating) approach is to invoke this command with an empty
directory and fix the errors, reinvoke and fix the new errors,
etc.

WARNING: The system control environment plays with the I/O
switches. Do not expect it to work in anything but a virgin
environment (no auditing, no video). And don't be surprised if
your favorite commands (emacs) won't work once you've started the
test environment. After exiting the test environment, a new_proc
is recommended to cleanse the user process.

________________________________________

NNNaaammmeee::: rrreeessstttaaarrrttt_fffaaauuulllttt

EEEnnntttrrryyy::: rrreeessstttaaarrrttt_fffaaauuulllttt$$$cccllleeeaaannnuuuppp_eeennntttrrryyy

this gate is called to indicate that the process is unwinding
past a signaller fault frame. It instructs ring zero to discard
the saved copy of the machine conditions.

USAGE

declare restart_fault$cleanup_entry entry;

call restart_fault$cleanup_entry ();

NOTES

1) This gate is not available in the user ring address space. An
entry pointer to this gate is left in the signaller stack frame
by signaller.alm as the handler of the condition "cleanup".

When a condition is signalled by ring 0, the program
signaller.alm builds a stack frame on the user ring stack that
includes a copy of the machine conditions for the condition. It
then arranges for the entry signal_ to be called in the outer
ring.

2) This entry is called as follows: when control is unwound
(non-local go-to'ed) past the frame built by signaller, the
cleanup handler is executed. This gate is the cleanup handler.
It ignores its parameters, but uses the display pointer in its

_____________ _____________

restart_fault restart_fault
_____________ _____________

argument list to find the stack frame just before its caller's on
the stack. Since its caller is signal_, the previous frame is
the signaller frame. Interpreting the previous frame as a
signaller frame, it extracts the saved machine condition index
from mc.fim_temp, and frees those machine conditions from the
ring 0 stack of saved machine conditions. If the argument list
lacks a display pointer, or if the previous frame is not marked
as a signaller frame, or if the machine condition index is
invalid, then nothing is done.

See restart_fault$restart_entry for more information.

EEEnnntttrrryyy::: rrreeessstttaaarrrttt_fffaaauuulllttt$$$rrreeessstttaaarrrttt_eeennntttrrryyy

This gate is called to restart execution of a set of machine
conditions that resulted from a fault or IPS signal.

USAGE

declare restart_fault$restart_entry entry;

call restart_fault$restart_entry ();

NOTES

This gate is not available in the user address space. It is
called as follows:

When a user process takes a fault, or an IPS signal is to be
signalled, control is transferred to the ring zero program
signaller.alm. This program saves a copy of the machine
conditions in the ring zero machine conditions save area
(pds$mc_save_area points to it). This save area is organized as
a stack of machine conditions, the most recent set stored on the
top of the stack. (Since the stack is unwound on exit from an
inner ring, there can be no interference between machine
conditions for different rings.) In addition, the machine
conditions are copied into the signaller stack frame on the outer
ring stack, where they are accessible to the user. The user
process is permitted to make some limited modifications to the
machine conditions, such as setting the result value for a
floating point underflow. See restart_fault.alm for details.

The return pointer in the signaller stack frame is
restart_fault|0 (restart_fault$restart_entry). When control
arrives here, the machine conditions from the signaller stack
frame (as potentially modified by the user) are copied into the

_____________ ________________

restart_fault send_as_request_
_____________ ________________

pds. They are then checked against the saved machine conditions
in the save area to insure that no invalid modifications have
been made. If there were invalid modifications, the
illegal_return condition is signalled.

Otherwise, the saved machine conditions are popped off of the
stack, and the processor resumes execution be restoring the
machine conditions.

________________________________________

NNNaaammmeee::: ssseeennnddd_aaasss_rrreeeqqquuueeesssttt_

The send_as_request_ subroutine contains entry points that send
messages to the system Answer Service Request server. It is not
recommended that any application code send as_requests.
Subroutine interfaces are available for all the supported
as_request facilities.

EEEnnntttrrryyy::: ssseeennnddd_aaasss_rrreeeqqquuueeesssttt_$$$bbbllloooccckkk

sends an as_request, and blocks to await the system's reply.

USAGE

declare send_as_request_$block entry (ptr, fixed bin,
bit(72)!aligned, bit(72) aligned, fixed bin(35));

call send_as_request_$block (as_request_ptr, as_request_len,
as_request_id, as_request_reply, code);

ARGUMENTS

as_request_ptr
is a pointer to standard as_request structure. (Input)
as_request_structures begin with a header declared in
as_request_header.incl.pl1. (See "Notes" below).

as_request_len
is the length of the standard as_request structure, in words.
(Input)

as_request_id
is the unique identifier assigned to the request. (Output)

as_request_reply
is the event message returned by the system in reply to the
request. (Output)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

code
is a standard system status code. (Output)

NOTES

The send_as_request_$block entrypoint each takes a request
pointer defining an operation. The allowed requests for this
entrypoint are described below.

Operation: admin_command

This answering service request executes a specified command line
in the system control process (Initializer.SysDaemon.z). It
optionally sends the user a wakeup at the start or completion of
command execution and returns information to the caller about
errors which occurred while executing the command line. It
optionally sends the user mail containing the output produced by
executing the command line.

This is an answering service request, and as such, is not called
directly as a subroutine. A structure containing the relevant
information, described below, is filled in by the caller and a
pointer to this structure, as well as the length of the
structure, is passed to the send_as_request_ subroutine for
processing.

ADMIN COMMAND INFO STRUCTURE

Following is a definition of the structure which is passed as
input to the send_as_request_ subroutine. It is declared in
as_requests.incl.pl1.

dcl 1 asr_admin_command_info aligned,
2 header aligned like as_request_header,
2 version char (8),
2 flags aligned,
3 send_start_wakeup bit (1) unaligned,
3 send_completion_wakeup bit (1) unaligned,
3 send_completion_message bit (1) unaligned,
3 send_completion_mail bit (1) unaligned,
3 dialog bit (1) unaligned,
3 pad bit (31) unaligned,
2 dialog_info aligned,
3 event_channel fixed bin (71),
3 output_message_segment_pathname char (200) unaligned,
3 input_message_segment_pathname char (200) unaligned,

________________ ________________

send_as_request_ send_as_request_
________________ ________________

2 mail_destination char (200) unaligned,
2 command_length fixed bin (21),
2 command char (asr_ac_length refer
(asr_admin_command_info.command_length)) unaligned;

STRUCTURE ELEMENTS

header
is the as_request_header structure, described below and
defined in the include file as_request_header.incl.pl1.
(Input)

version
is the version number of the asr_admin_command_info structure.
This version number is currently equal to the constant
ASR_AC_VERSION_1, defined in the include file
as_requests.incl.pl1. (Input)

send_start_wakeup
is a flag indicating whether the user is to be sent a wakeup
over the event channel specified in the header at the start of
command execution. (Input)

send_completion_wakeup
is a flag indicating whether the user is to be sent a wakeup
over the event channel specified in the header at the
completion of command execution. (Input)

send_completion_message
is a flag indicating whether the user is to be notified by
interactive message of the completion of command execution.
The message includes an indication of whether the command was
executed with or without errors. (Input)

send_completion_mail
is a flag indicating whether the user is to be notified by
mail of the completion of command execution. The mail
includes a transcription of the output generated during
execution of the command line. (Input)

dialog
is currently unused and is ignored.

dialog_info
is currently unused and is ignored.

mail_destination
is the mail system destination, e.g. mail table entry, where
the completion mail is to be sent if the send_completion_mail
flag is on. (Input)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

command_length
is the length, in characters, of the command line to be
executed. (Input)

command
is the actual command line to be executed. (Input)

ADMIN COMMAND REPLY STRUCTURE

Following is a definition of the structure which overlays the
reply argument to the send_as_request_ subroutine. It contains
information about the status of the answering service request
execution. It is declared in as_requests.incl.pl1.

dcl 1 asr_reply_admin_command aligned,
2 code fixed bin (35),
2 flags aligned,
3 command_refused bit (1) unaligned,
3 command_started bit (1) unaligned,
3 command_completed bit (1) unaligned,
3 command_aborted bit (1) unaligned,
3 command_had_errors bit (1) unaligned,
3 pad bit (31) unaligned;

STRUCTURE ELEMENTS

code
is a standard system status code. (Output)

command_refused
is a flag indicating whether execution of the command was
refused. If this flag is on, then code, above, indicates the
reason why. (Output)

command_started
is a flag indicating whether the command has started
execution. (Output)

command_completed
is a flag indicating whether the command has completed
execution. (Output)

command_aborted
is a flag indicating whether the command was aborted.
(Output)

command_had_errors
is a flag indicating whether the command encountered an error
(wrote a message over the error_output switch) during
execution. (Output)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

AS REQUEST HEADER INFO STRUCTURE

Following is a definition of the as_request_header structure used
above and defined in the include file as_request_header.incl.pl1.
It provides general information to the answering service request
server.

dcl 1 as_request_header based aligned,
2 version fixed bin,
2 type fixed bin,
2 reply_channel fixed bin (71);

STRUCTURE ELEMENTS

version
is the version number of the as_request_header structure.
Currently this must be equal to the constant
as_request_version_1 declared in the include file
as_request_header.incl.pl1. (Input)

type
is the type of answering service request. For the
admin_command request, this must be equal to the constant
ASR_ADMIN_COMMAND, declared in the include file
as_request_header.incl.pl1. (Input)

reply_channel
is the IPC event channel over which the answering service
request server will send status wakeups. (Input)

ACCESS REQUIRED

The user must have RW effective access to the ACS segment
>sc1>admin_acs>send_admin_command.acs in order to issue this
answering service request.

Operation: bump_user

This answering service request causes a specified user process to
be bumped (forcibly logged out).

________________ ________________

send_as_request_ send_as_request_
________________ ________________

BUMP USER INFO STRUCTURE

Following is a definition of the structure which is passed as
input to the send_as_request_ subroutine.

dcl 1 asr_bump_user_info aligned,
2 header aligned like as_request_header,
2 version char (8),
2 process_id bit (36),
2 message char (100) unaligned,
2 grace_time_in_seconds fixed bin,
2 reply_reference_id bit (36);

STRUCTURE ELEMENTS

header
is the as_request_header structure, described above and
defined in the include file as_request_header.incl.pl1.
(Input)

version
is the version number of the asr_bump_user structure. This
version number is currently equal to the constant
asr_bump_user_info_version_1, declared in the include file
as_requests.incl.pl1. (Input)

process_id
is the process id of the process to be bumped. (Input)

message
is the message to be displayed on the user's terminal when the
bump begins, that is, when the user's grace period begins. If
this argument is the null string, no message is sent to the
user's terminal. (Input)

grace_time_in_seconds
is the amount of time, in seconds, the user is given before
the process is actually terminated. (Input)

reply_reference_id
is a reference_id returned in the asr_reply_bump_user
structure. An IPC reply channel must be specified in the
reply_channel variable of the header of this structure in
order for the reply reference id to be returned. (Input)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

BUMP USER REPLY STRUCTURE

Following is a definition of the structure which overlays the
reply argument to the send_as_request_ subroutine. It contains
information about the status of the answering service request
execution.

dcl 1 asr_reply_bump_user aligned based (asr_replyp),
2 code fixed bin (35),
2 reference_id bit (36);

STRUCTURE ELEMENTS

code
is a standard system status code. (Output)

reference_id
is the same reference id supplied in the reference_id variable
in the input structure. It is used to synchronize requests
and replies. (Output)

ACCESS REQUIRED

The user must have RW effective access to the ACS segment
>sc1>admin_acs>bump_user.acs in order to issue this answering
service request.

Operation: com_channel_info

This answering service request returns to the user information
about a communications channel attached to his process.

COM CHANNEL INFO STRUCTURE

Following is a definition of the structure which is passed as
input to the send_as_request_ subroutine. It is declared in
asr_com_channel_info.incl.pl1.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

dcl 1 asr_com_channel_info aligned,
2 header aligned like as_request_header,
2 version char (8),
2 channel_name char (32) unaligned,
2 reply_version_requested char (8),
2 reply_message_handle bit (72) aligned;

STRUCTURE ELEMENTS

header
is the as_request_header structure, described above and
defined in the include file as_request_header.incl.pl1.
(Input)

version
is the version number of the asr_com_channel_info structure.
This version number is currently equal to the constant
ASR_CCI_VERSION_1, declared in the include file
asr_com_channel_info.incl.pl1. (Input)

channel_name
is the name of the communications channel for which
information is to be returned.

reply_version_requested
is the version of the as_com_channel_info structure (not to be
confused with the asr_com_channel_info structure) requested.
This structure will be filled in by the answering service and
sent to the user via the user message facility. It is the
user process' responsibility to read this message with the
user_message_$read_message subroutine. (Input)

reply_message_handle
is the handle to be used in sending the user message. This
value is used by the user when calling
user_message_$read_message to read the message from the user
message facility. (Input)

COM CHANNEL INFO REPLY STRUCTURE

dcl 1 asr_reply_com_channel_info aligned,
2 code fixed bin (35),
2 pad bit (36) aligned;

________________ ________________

send_as_request_ send_as_request_
________________ ________________

STRUCTURE ELEMENTS

code
is a standard system status code. (Output)

ACCESS REQUIRED

In order to receive information about a communications channel,
the user must either have the communications channel attached as
the primary login channel, or as a secondary autocall or slave
channel.

Operation: daemon_command

This answering service request allows a user to login or logout
system daemon processes, send command lines to be executed in
daemon processes, and send QUIT IPS signals to deamon processes.

DAEMON COMMAND INFO STRUCTURE

Following is a definition of the structure which is passed as
input to the send_as_request_ subroutine. It is declared in
asr_daemon_command.incl.pl1.

dcl 1 asr_daemon_command_info aligned,
2 header aligned like as_request_header,
2 version char (8),
2 action_code fixed bin,
2 user_name char (32) unaligned,
2 project_name char (32) unaligned,
2 source_name char (32) unaligned,
2 pad (10) bit (36) aligned,
2 command_length fixed bin (21),
2 command char (asr_dc_length refer
(asr_daemon_command_info.command_length)) unaligned;

________________ ________________

send_as_request_ send_as_request_
________________ ________________

STRUCTURE ELEMENTS

header
is the as_request_header structure, described above and
defined in the include file as_request_header.incl.pl1.
(Input)

version
is the version number of the asr_daemon_command_info
structure. This version number is currently equal to the
constant ASR_DC_INFO_VERSION_1, declared in the include file
asr_daemon_command.incl.pl1. (Input)

action_code
is the desired action (login, logout, reply, quit) to be
performed. The include file asr_daemon_command.incl.pl1
defines constants to be used in setting this action code.
(Input)

user_name
is the user name for the "login" subrequest. (Input)

project_name
is the project name for the "login" subrequest. (Input)

source_name
is the message coordinator source name used to identify the
daemon process for the "reply", "quit", and "logout"
subrequests, and over which the daemon is to be logged in for
the "login" subrequest. (Input)

command_length
is the length of the command line supplied below. (Input)

command
is the command line to be sent to the daemon process for the
"reply" subrequest and are the optional login arguments to be
supplied for the "login" subrequest. (Input)

DAEMON COMMAND REPLY STRUCTURE

________________ ________________

send_as_request_ send_as_request_
________________ ________________

dcl 1 asr_reply_daemon_command aligned,
2 code fixed bin (35),
2 flags aligned,
3 command_refused bit (1) unaligned,
3 no_such_daemon bit (1) unaligned,
3 no_access_to_daemon bit (1) unaligned,
3 pad bit (33) unaligned;

STRUCTURE ELEMENTS

code
is a standard system status code. (Output)

command_refused
is a flag indicating that the daemon_command request has been
refused. The variable code indicates the reason for the
refusal. (Output)

no_such_daemon
is a flag indicating that the daemon specified by the
source_name variable in the input structure does not exist.
(Output)

no_access_to_daemon
is a flag indicating that the user did not have the required
access to manipulate the daemon. (Output)

ACCESS REQUIRED

If the installation parameter validate_daemon_commands is
disabled, RW effective access is required to the ACS segment
>sc1>admin_acs>send_daemon_command.acs. If, however, the
validate_daemon_commands installation parameter is enabled, then
the user must have the appropriate access to the MCACS segment
located in >sc1>mc_acs>SOURCE_NAME.mcacs, where SOURCE_NAME is
the same as that specified in the input structure, above. The
MCACS segment is an extended entry, with extended ACLs. In order
to login or logout a daemon process, the user must have "c"
access to the MCACS segment. In order to reply to a daemon
process, the user must have "r" access. In order to send a QUIT
IPS signal, the user must have "q" access. Additionally, for the
login subrequest, the process being logged in over the specified
message coordinator SOURCE_NAME must have "d" access to the MCACS
segment.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

Operation: dial_out

This answering service request allows the user to "dial out" an
autocall service communications channel to a specified
destination.

DIAL SERVER REQUEST INFO STRUCTURE

Following is a definition of the structure which is passed as
input to the send_as_request_ subroutine.

dcl 1 dial_server_request aligned based (request_ptr),
2 header like as_request_header,
2 version fixed bin,
2 dial_control_channel fixed bin (71),
2 dial_qualifier char (22),
2 channel_name char (32),
2 dial_out_destination char (32),
2 baud_rate fixed bin,
2 line_type fixed bin,
2 server_type char (32),
2 flags aligned,
3 start bit (1) unaligned,
3 stop bit (1) unaligned,
3 privileged_attach bit (1) unaligned,
3 release_channel bit (1) unaligned,
3 registered_server bit (1) unaligned,
3 no_hangup bit (1) unaligned,
3 release_dial_id bit (1) unaligned,
3 tandd_attach bit (1) unaligned,
3 no_listen bit (1) unaligned,
3 access_class_specified bit (1) unaligned,
3 privileged_server bit (1) unaligned,
3 pad bit (25) unaligned,
2 access_class bit (72);

________________ ________________

send_as_request_ send_as_request_
________________ ________________

STRUCTURE ELEMENTS

header
is the as_request_header structure, described above and
defined in the include file as_request_header.incl.pl1.
(Input)

version
is the version number of the dial_server_request structure.
This version number is currently equal to the constant
dial_server_request_version_4 declared in the include file
dial_server_request.incl.pl1. (Input)

dial_control_channel
is an IPC event channel over which the answering service will
send status wakeups. The event messages received over this
event channel should be interpreted with the
convert_dial_message_ subroutine. (Input)

dial_qualifier
is not used for the dial_out answering service request.

channel_name
is the channel name over which the user wishes to dial out.
This channel name may be specified using the star convention
in which case any available autocall channel which matches the
star name will be used. A generic destination, as defined in
the Channel Definition Table (CDT) may be specified in lieu of
a specific channel name or star name. (Input)

dial_out_destination
is a character string representation of the dial out
destination. This may be a phone number for an Auto Call Unit
(ACU) or any other destination recognized by the device or
multiplexer connected to the communications channel being
dialed out on. (Input)

baud_rate
is the desired baud rate of the autocall channel. This may be
-1 if the user doesn't care to specify the baud rate. (Input)

line_type
is the desired line type of the autocall channel. See the
include file line_types.incl.pl1 for a list of the recognized
line types. The value of "lbound (line_types, 1)" should be
used if the user does not care what line type is chosen.
(Input)

server_type
is not used for the dial_out answering service request.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

start
is not used for the dial_out answering service request.

stop
is not used for the dial_out answering service request.

privileged_attach
is not used for the dial_out answering service request.

release_channel
is not used for the dial_out answering service request.

registered_server
is not used for the dial_out answering service request.

no_hangup
is not used for the dial_out answering service request.

release_dial_id
is not used for the dial_out answering service request.

tandd_attach
is not used for the dial_out answering service request.

no_listen
is not used for the dial_out answering service request.

access_class_specified
is a flag indicating whether the user wishes to specify the
access class of the autocall connection. (Input)

privileged_server
is not used by the dial_out answering service request.

access_class
is the access class of the autocall connection desired by the
user. This access class must equal the user's process
authorization unless the comm privilege is enabled. If the
privilege is enabled, the specified access class must be
between the user's current and maximum authorization. If the
access_class_specified flag is not enabled, this argument is
ignored. (Input)

DIAL OUT REPLY

The dial out request replies via the event message, as do other
AS requests. But the structure of this reply must be interpreted
by the convert_dial_message_ subroutine described in the Multics
Subroutines manual.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

ACCESS REQUIRED

In order to use the dial_out answering service request, the user
must have the dialok attribute enabled. In addition, if the
system administrator has enabled the "dial_out" check_acs flag
for the specified channel in the CDT, the user must have RW
effective access to the ACS segment >sc1>rcp>CHANNEL_NAME.acs
where CHANNEL_NAME is the channel name specified (or implied) by
channel_name, above. If the system administrator has not enabled
the "dial_out" check_acs flag for the channel, then no other
access is required to initiate a dial out.

Operation: dial_server

This answering service request allows the user to start, stop,
and shutoff dial-id service, or to attach a communications
channel for normal or Test and Diagnostics (T&D) use.

DIAL SERVER REQUEST INFO STRUCTURE

Following is a definition of the structure which is passed as
input to the send_as_request_ subroutine.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

3 release_dial_id bit (1) unaligned,
3 tandd_attach bit (1) unaligned,
3 no_listen bit (1) unaligned,
3 access_class_specified bit (1) unaligned,
3 privileged_server bit (1) unaligned,
3 pad bit (25) unaligned,
2 access_class bit (72);

STRUCTURE ELEMENTS

header
is the as_request_header structure, described above and
defined in the include file as_request_header.incl.pl1.
(Input)

dial_qualifier
for the start_dial_id, stop_dial_id, and shutoff_dial_id
subrequests, this specifies the name of the dial_id to
manipulate. (Input)

channel_name
for the priv_attach, tandd_attach, and release_channel
subrequests, specifies the name of the channel the user wishes
to manipulate. This channel name may be specified via the
star convention, or a generic channel name may be used.
Generic names are defined by the system administrator in the
Channel Definition Table (CDT). (Input)

dial_out_destination
is not used for the dial_server answering service request.

baud_rate
for the priv_attach, tandd_attach, and release_channel
subrequests, is the desired baud rate of the channel. This
may be -1 if the user doesn't care to specify the baud rate.
(Input)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

line_type
for the priv_attach, tandd_attach, and release_channel
subrequests, is the desired line type of the channel. See the
include file line_types.incl.pl1 for a list of the recognized
line types. The value of "lbound (line_types, 1)" should be
used if the user does not care what line type is chosen.
(Input)

server_type
is currently not used.

start
specifies that the user wishes to start a dial_id service.
(Input)

stop
specifies that the user wishes to stop a dial_id service.
(Input)

privileged_attach
specifies that the user wishes to attach a communications
channel. The channel must be a slave service type channel at
the time of the request unless the tandd_attach flag is on.
(Input)

release_channel
specifies that the user wishes to release a channel previously
attached with the privileged_attach subrequest. (Input)

registered_server
for the start_dial_id subrequest, specifies that the user
wishes to use a registered dial id. A dial_id is registered
by a system administrator. (Input)

no_hangup
is only valid for the release_channel requests, and requests
that the channel be left dialed, rather than hung up, which is
the default. (Input)

release_dial_id
specifies that the user wishes to shutoff dial service and
hang up any communications channels already attached to the
process. (Input)

tandd_attach
is only valid for the privileged_attach subrequest, and
specifies that a T&D attachment is to be used. (Input)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

no_listen
is only valid for the release_channel subrequest, and
specifies that the answering service is not to listen for
dialups on this channel after it is released. (Input)

access_class_specified
is not used by the dial_server answering service request.

privileged_server
this field is only valid for the start_dial_id subrequest and
specifies that the process may accept dials from users dialing
in at any authorization up to the maximum authorization of the
server process (the process issuing the request). (Input)

access_class
is not used by the dial_server answering service request.

DIAL SERVER REPLY

The dial server request replies via the event message, as do
other AS requests. But the structure of this reply must be
interpreted by the convert_dial_message_ subroutine described in
the Multics Subroutines manual.

ACCESS REQUIRED

In order to use the dial_server answering service request, the
user must have the dialok attribute enabled. In addition, for
the priv_attach subrequest, if the system administrator has
enabled the "priv_attach" check_acs flag for the specified
channel in the CDT, the user must have RW effective access to the
ACS segment >sc1>rcp>CHANNEL_NAME.acs where CHANNEL_NAME is the
channel name specified (or implied) by channel_name, above. If
the system administrator has not enabled the "priv_attach"
check_acs flag for the channel, then no other access is required
to attach a channel.

In order to become a registered dial server, the user must have
RW effective access to the ACS segment
>sc1>rcp>dial.DIAL_QUALIFIER.acs where DIAL_QUALIFIER is the name
specified as dial_qualifier, above.

In order to become a privileged server, the user must have the
comm privilege enabled, or have its validation level set to
Ring-1.

In order to make a T&D attachment (that is, specifying the
tandd_attach flag for the priv_attach subrequest), the user must
have RW effective access to the ACS segment
>sc1>admin_acs>tandd.acs.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

Operation: fpe_causes_logout

This answering service request indicates that the answering
service should log out the process if it takes a fatal process
error.

FPE CAUSES LOGOUT STRUCTURE

For fpe_causes_logout, simply pass the as_request_header
structure as input to send_as_request_. It is declared in the
include file as_request_header.incl.pl1. It provides general
information to the answering service request server.

dcl 1 as_request_header based aligned,
2 version fixed bin,
2 type fixed bin,
2 reply_channel fixed bin (71);

STRUCTURE ELEMENTS

version
is the version number of the as_request_header structure.
Currently this must be equal to the constant
as_request_version_1 declared in the include file
as_request_header.incl.pl1. (Input)

type
is the type of answering service request. For the
fpe_causes_logout request, this must be equal to the constant
ASR_FPE_CAUSES_LOGOUT, declared in the include file
as_request_header.incl.pl1. (Input)

reply_channel
is the IPC event channel over which the answering service
request server will the reply message. (Input)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

FPE CAUSES LOGOUT REPLY STRUCTURE

Following is a definition of the structure which overlays the
reply argument to the send_as_request_ subroutine. It contains
information about the status of the answering service request
execution.

dcl 1 asr_reply aligned,
2 code fixed bin (35),
2 data bit (36);

STRUCTURE ELEMENTS

code
is a standard system status code. (Output)

data
is always equal to "1"b. (Output)

ACCESS REQUIRED

There are no access requirements for this answering service
request.

Operation: fpe_causes_new_proc

This answering service request indicates that the answering
service should create a new process if it takes a fatal process
error.

FPE CAUSES NEW_PROC STRUCTURE

For fpe_causes_new_proc, simply pass the as_request_header
structure as input to send_as_request_. It is declared in the
include file as_request_header.incl.pl1. It provides general
information to the answering service request server.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

dcl 1 as_request_header based aligned,
2 version fixed bin,
2 type fixed bin,
2 reply_channel fixed bin (71);

STRUCTURE ELEMENTS

version
is the version number of the as_request_header structure.
Currently this must be equal to the constant
as_request_version_1 declared in the include file
as_request_header.incl.pl1. (Input)

type
is the type of answering service request. For the
fpe_causes_logout request, this must be equal to the constant
ASR_FPE_CAUSES_NEW_PROC, declared in the include file
as_request_header.incl.pl1. (Input)

reply_channel
is the IPC event channel over which the answering service
request server will the reply message. (Input)

FPE CAUSES NEW_PROC REPLY STRUCTURE

Following is a definition of the structure which overlays the
reply argument to the send_as_request_ subroutine. It contains
information about the status of the answering service request
execution.

dcl 1 asr_reply aligned,
2 code fixed bin (35),
2 data bit (36);

STRUCTURE ELEMENTS

code
is a standard system status code. (Output)

data
is always equal to "0"b. (Output)

ACCESS REQUIRED

There are no access requirements for this answering service
request.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

Operation: process_termination_monitor

This answering service request specifies that the answering
service should notify this process of any process terminations.

PROCESS TERMINATION MONITOR INFO STRUCTURE

Following is a definition of the structure which is passed as
input to the send_as_request_ subroutine.

dcl 1 asr_buzzard_info aligned,
2 header aligned like as_request_header,
2 version char (8),
2 info_channel fixed bin (71),
2 my_reference_id bit (36);

STRUCTURE ELEMENTS

header
is the as_request_header structure, described above and
defined in the include file as_request_header.incl.pl1.
(Input)

version
is the version number of the asr_buzzard_info structure. This
version number is currently equal to the constant
asr_buzzard_info_version_1, declared in the include file
as_requests.incl.pl1. (Input)

info_channel
is the IPC event channel over which the answering service is
to send notifications of process terminations. (Input)

my_reference_id
is a reference id which is returned in the process termination
notification messages. (Input)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

PROCESS TERMINATION MONITOR REPLY STRUCTURE

Following is a definition of the structure which overlays the
reply argument to the send_as_request_ subroutine. It contains
information about the status of the answering service request
execution.

dcl 1 asr_reply aligned,
2 code fixed bin (35),
2 data bit (36);

STRUCTURE ELEMENTS

code
is a standard system status code. (Output)

data
is "1"b if the user was already a process termination monitor
and "0"b if it wasn't. (Output)

ACCESS REQUIRED

The user must have RW effective access to the ACS segment
>sc1>admin_acs>process_termination_monitor.acs in order to issue
this answering service request.

EEEnnntttrrryyy::: ssseeennnddd_aaasss_rrreeeqqquuueeesssttt_$$$nnnooo_bbbllloooccckkk

This entry point sends an as request message to the system as
request server, and does not block to await a reply.

USAGE

declare send_as_request_$no_block entry (ptr, fixed bin, bit(72)
aligned, fixed bin(35));

call send_as_request_$no_block (as_request_ptr, as_request_len,
as_request_id, code);

ARGUMENTS

as_request_ptr
is a pointer to standard as_request structure. (Input)
as_request_structures begin with a header declared in
as_request_header.incl.pl1. See notes below.

as_request_len
is the length of the standard as_request structure, in words.
(Input)

________________ ________________

send_as_request_ send_as_request_
________________ ________________

as_request_id
is the unique identifier assigned to the request. (Output)

code
is a standard system status code. (Output)

NOTES

The send_as_request_$no_block entrypoint takes a request pointer
defining an operation. The allowed requests for this entrypoint
are described below.

Operation: abs_command

Provides the capability to log in and cancel absentee jobs.
Following is the definition of the structure which is passed as
input to the send_as_request_ in order to execute an abs_command
AS request.

dcl 1 asr_abs_command_info aligned based (asr_abs_command_info_ptr),
2 header aligned like as_request_header,
2 version char (8),
2 action_code fixed bin,
2 request_id fixed bin (71);

STRUCTURE ELEMENTS

header
is the as_request_header

version
the version of the structure, must be ASR_AC_INFO_VERSION_1

action_code
may be either ASR_AC_LOGIN, to login an absentee job, or
ASR_AC_CANCEL, to cancel an absentee job.

request_id
is the request ID of the absentee job to be logged in or
cancelled

Operation: admin_command

See description of admin_command under $block.

________________ ________________

send_as_request_ send_as_request_
________________ ________________

Operation: note_pnt_change

This answering service request notifies the answering service of
a change in the security attributes of a registered user.

NOTE PNT CHANGE INFO STRUCTURE

Following is a definition of the structure which is passed as
input to the send_as_request_ subroutine. It is declared in
as_request.incl.pl1.

dcl 1 asr_note_pnt_change_info aligned,
2 header aligned like as_request_header,
2 version char (8),
2 person_id char (32);

STRUCTURE ELEMENTS

header
is the as_request_header structure, described above and
defined in the include file as_request_header.incl.pl1.
(Input)

version
is the version number of the asr_note_pnt_change_info
structure. This version number is currently equal to the
constant ASR_NPC_INFO_VERSION_1, declared in the include file
as_requests.incl.pl1. (Input)

person_id
is the person_id of the user whose security attributes have
changed. The answering service will examine the PNT entry of
this person_id and update the information about this user in
the answering service tables, if the user is logged in. It
may cause the user to be bumped if the new security attributes
are incompatible with those of the logged in user.

________________ ____________________

send_as_request_ send_system_message_
________________ ____________________

ACCESS REQUIRED

In order for this request to be granted, the user must have his
validation level set to Ring-1. That is, the process must be
running in the administrative ring.

________________________________________

NNNaaammmeee::: ssseeennnddd_sssyyysssttteeemmm_mmmeeessssssaaagggeee_

EEEnnntttrrryyy::: ssseeennnddd_sssyyysssttteeemmm_mmmeeessssssaaagggeee_$$$ssseeennnddd_sssyyysssttteeemmm_mmmeeessssssaaagggeee_

This entry point, which requires access to hphcs_, sends a
message to a specified process accompanied by the system_message_
IPS signal. Processes have a static handler for system_message_
that invokes system_message_handler_.

USAGE

dcl send_system_message_ entry (bit (36) aligned, fixed bin, ptr,
fixed bin (35));

call send_system_message_ (recipient_process_id,
recipient_initial_ring, message_ptr, code);

ARGUMENTS

recipient_process_id
is the process id of the recipient. (Input)

recipient_initial_ring
is the initial (login) ring number of the recipient process.
(Input)

message_ptr
is a pointer to an allocated copy of one of the structures
warn_system_message, inactivity_system_message or
dm_shut_system_message, declared in the include file
system_message.incl.pl1. Operator warn messages use
warn_system_message and set the type field equal to
SYSTEM_MESSAGE_TYPE_AS_WARN. Inactivity messages use
inactivity_system_message and set the type field equal to
SYSTEM_MESSAGE_TYPE_AS_INACTIVITY. The other structure is
available for future use by Data Management. (Input)

____________________ ____________________

send_system_message_ send_system_message_
____________________ ____________________

NOTES

The structures for warn messages are as follows:

dcl 1 system_message_header aligned based,
2 version char (8),
2 type fixed bin,
2 type_version char (8);

dcl 1 warn_system_message aligned based,
2 header aligned like system_message_header,
2 caller char (64),
2 text_len fixed bin (21),
2 text char (system_message_text_len
refer (warn_system_message.text_len));

dcl 1 inactivy_system_message aligned based,
2 header aligned like system_message_header,
2 caller char (64),
2 text_len fixed bin (21),
2 text char (system_message_text_len
refer (inactivy_system_message.text_len));

STRUCTURE ELEMENTS

version
is equal to SYSTEM_MESSAGE_VERSION_1.

type
is equal to SYSTEM_MESSAGE_TYPE_AS_WARN for the
warn_system_message and SYSTEM_MESSAGE_TYPE_AS_INACTIVITY for
the inactivity_system_message.

type_version
is equal to SYSTEM_MESSAGE_AS_WARN_V1 for the
warn_system_message and SYSTEM_MESSAGE_AS_INACTIVITY_V1 for
the inactivity_system_message.

caller
is the name of the caller, to be prefixed to the message text:

CALLER: TEXT

If caller is "", only the text is printed. This is common to
all system messages.

text_len
is the number of characters in the message text. This is
common to all system messages.

____________________ _________________

send_system_message_ set_ext_variable_
____________________ _________________

text
is the text of the message. This is common to all system
messages.

The inactivity message is merely another type of warn message.
It is defined as a unique type so that the message handler can
accurately determine that special action is required in
response to it.

________________________________________

NNNaaammmeee::: ssseeettt_eeexxxttt_vvvaaarrriiiaaabbbllleee_

Most set_ext_variable_ entrypoints are documented in Multics
Subroutines. The following is an internal entrypoint.

EEEnnntttrrryyy::: ssseeettt_eeexxxttt_vvvaaarrriiiaaabbbllleee_$$$fffooorrr_llliiinnnkkkeeerrr

This entry point is called by link_snap to allocate or find an
external variable. It should only be called in ring 0. If the
size of the variable is greater than sys_info_$max_seg_size this
entry traps to the referencing ring to perform the allocation and
snap the link.

USAGE

dcl set_ext_variable_$for_linker entry (char (*), ptr, ptr, fixed
bin (35), ptr, ptr, ptr, ptr);

call set_ext_variable_$for_linker (ext_name, init_info_ptr, sb,
seg_ptr, found_sw, node_ptr, code, mc_ptr, def_ptr,
type_ptr, link_ptr);

ARGUMENTS

ext_name
is the name of the external variable. (Input)

init_info_ptr
is a pointer to the initialization info. For a complete
description of the initialization structure. (Input)

sb_ptr
is a pointe to the base of the stack of the caller. (Input)

_________________ _________________

set_ext_variable_ set_ext_variable_
_________________ _________________

seg_ptr
is a pointe to the segment containing the object to be
initialized. (Input).

found_sw
is set to indicate whether the variable was found or not.
(Output)

node_ptr
is a pointe to the extenal variable node. For a complete
description of the node structure (see "Notes on variable_node
Structure"). (Output)

code
is an error code. (Output)

mc_ptr
is a pointer to the machine conditions for the linkage fault.
(Input)

def_ptr
is a pointer to the base of the definition section of the
segment that contains the link to the variable. (Input)

type_ptr
is a pointer to the type pair of the link to the variable.
(Input)

link_ptr
is a pointer to the (unsnapped) link to the variable. (Input)

Notes on init_info Structure:
When a new external variable is allocated (not found), it must be
initialized. The following structure, described in
system_link_init_info.incl.pl1, is pointed to by init_info_ptr:

dcl 1 init_info aligned based,
2 size fixed bin (19),
2 type fixed bin,
2 init_template
(init_size refer
(init_info.size)) fixed bin (35);

Structure elements:
size
is the initialization template size, in words.
type
is the type of initialization to be performed.

_________________ _________________

set_ext_variable_ set_ext_variable_
_________________ _________________

0 no init
1 invalid
2 invalid
3 init from template
4 init area to empty ()
5 list_template initialization (see "Notes on list_template
Initialization Structure")
init_template
is the initialization template to be used when type = 3.

Notes on list_template Initialization Structure:
When the initialization type is 5 or a list_template
initialization is being performed the init_info structure is not
used. The structure used is the list_init_info structure which
has the following definition in system_link_init_info.incl.pl1:

dcl 1 list_init_info aligned based,
2 size fixed bin (35),
2 type fixed bin,
2 pad bit (18) unaligned,
2 list_size fixed bin (18)
unsigned unaligned,
2 template (0 refer
(list_init_info.list_size))
bit (36);

Structure Elements:

size
is the size of the variable in words.

type
is the type of initialization to be performed. 5
list_template

list_size
is the number of list_template_entries that make up the
template.

template
takes the form of a list_template_entry structure as defined
in system_link_init_info.incl.pl1. This structure is passed
on to list_init_ and decoded into data which is copied to the
variable. See the definition of list_init_ for a more
complete description.

_________________ _________________

set_ext_variable_ set_ext_variable_
_________________ _________________

Notes on variable_node Structure:
Great care should be taken when using the node_ptr. The
variable_node structure should never be modified. Modifications
to the variable_node will have unpredictable results.

A pointer to the following structure is returned by the entry
points in this subroutine. It is declared in
system_link_names.incl.pl1

dcl 1 variable_node aligned based,
2 forward_thread ptr unaligned,
2 vbl_size fixed bin (23) unaligned,
2 init_type fixed bin (11) unaligned,
2 time_allocated fixed bin (71),
2 vbl_ptr ptr,
2 init_ptr ptr,
2 name_size fixed bin (21) aligned,
2 name char (nchars refer
(variable_node.name_size)),
2 seg_ptr ptr;

Structure elements:

forward_thread
is used by the linker to thread this variable to the next.

vbl_size
is the size, in words, of this variable.

init_type
is the type of initialization that is performed:
0 none
1 invalid
2 invalid
3 initialize from template
4 initialize to an empty area
5 initialize using a list template (see "Notes on list_template
Initialization Structure").

time_allocated
is the clock reading at the time this variable was allocated.

vbl_ptr
is a pointer to the variable's storage.

init_ptr
is a pointer to the intialization template.

_________________ ________

set_ext_variable_ sys_log_
_________________ ________

name_size
is the number of characters in the variable name.

name
is the name of the variable.

seg_ptr
is a pointer to the segment containing the variables
initialization information.

________________________________________

NNNaaammmeee::: sssyyysss_llloooggg_

The sys_log_ subroutine provides an error message handling
facility to programs that run in the Initializer process. The
subroutine has two modes of operation.

Command mode is used by operator commands to report errors to the
operator in a manner similar to com_err_. The error messages are
printed on the operator terminal that issued the command. They
are also written into the admin log, which can be printed via
"print_sys_log -admin".

Answer Service (AS) mode is used by noncommand programs running
in the Initializer to report errors in a manner similar to the
hardcore syserr_ mechanism. The error messages are printed on
one of three Answering Service I/O switches (severity1, severity2
or severity3). They are also written into the Answering Service
log, which can be printed via "print_sys_log -as".

ARGUMENTS
The following argument is used by all sys_log_ entrypoints.

severity
defines the severity of the error. Allowed values are defined
by named constants in sys_log_constants.incl.pl1.

SL_LOG_SILENT (= 0)
Only log the message, do not print it.

SL_LOG (= 1)
Log the message and print it. When called in AS mode,
print the message on the severity1 I/O switch. When
called in command mode, print the message on the
operator's console.

________ ________

sys_log_ sys_log_
________ ________

SL_LOG_BEEP (= 2)
Log the message and print it preceeded by a line of
asterisks and followed by a BELL character which turns
on the audible alarm. When called in AS mode, print
the message on the severity2 I/O switch. When called
in command mode, print the message on the operator's
console.

SL_LOG_CRASH (= 3)
Log the message, print it preceeded by a line of
asterisks and followed by a BELL character, and crash
the system. When called in AS mode, print the message
on the severity3 I/O switch. When called in command
mode, print the message on the operator's console.

EEEnnntttrrryyy::: sssyyysss_llloooggg_$$$eeerrrrrrooorrr_llloooggg

This entrypoint logs/prints an error table code and message in AS
mode. The message format is:

caller: error_code_text ioa_message

USAGE

declare sys_log_$error_log entry options(variable);

call sys_log_$error_log (severity, code, caller, ioa_ctl, args);

ARGUMENTS

severity
is a fixed bin(17) argument which defines the severity, as
described above. (Input)

code
is a fixed bin(35) error table code whose expanded text is
placed in the message. If code is zero, then no error message
text is placed in the message. (Input)

caller
is a char(*) name of the calling program. This is placed in
the message to identify where the message is coming from.
(Input)

ioa_ctl
is a char(*) or char(*) varying ioa_ control string describing
the message format. (Input)

________ ________

sys_log_ sys_log_
________ ________

args
are arguments to be substituted into the ioa_ control string.
(Input)

EEEnnntttrrryyy::: sssyyysss_llloooggg_$$$sssyyysss_llloooggg_

This entrypoint logs/prints a message in AS mode. The ioa_ctl
string should include the caller's name to identify where the
message is coming from.

USAGE

declare sys_log_ entry options(variable);

call sys_log_ (severity, ioa_ctl, args);

ARGUMENTS

severity
is a fixed bin(17) argument which defines the severity, as
described above. (Input)

ioa_ctl
is a char(*) or char(*) varying ioa_ control string describing
the message format. (Input)

args
are arguments to be substituted into the ioa_ control string.
(Input)

EEEnnntttrrryyy::: sssyyysss_llloooggg_$$$bbbiiinnnaaarrryyy

This entrypoint logs/prints a message in AS mode. The logged
message includes binary data which further describes the
circumstances of the error.

USAGE

declare sys_log_$binary entry options(variable);

call sys_log_$binary (severity, data_ptr, data_lth, data_class,
ioa_ctl, args);

________ ________

sys_log_ sys_log_
________ ________

ARGUMENTS

severity
is a fixed bin(17) argument which defines the severity, as
described above. (Input)

data_ptr
is an aligned pointer to the binary data. (Input)

data_lth
is a fixed bin(17) length of the binary data, in words.
(Input)

data_class
is a char(10) varying parameter defining the class of binary
data. This is used by print_sys_log to find a routine to
expand and print the binary data. For example, if the
data_class were CLASS, then print_sys_log would use a routine
called expand_CLASS_msg_ to expand and print the binary data.
(Input)

ioa_ctl
is a char(*) or char(*) varying ioa_ control string describing
the message format. (Input)

args
are arguments to be substituted into the ioa_ control string.
(Input)

EEEnnntttrrryyy::: sssyyysss_llloooggg_$$$cccooommmmmmaaannnddd

This entrypoint logs/prints a message in command mode. The
ioa_ctl string should include the caller's name to identify where
the message is coming from.

USAGE

declare sys_log_$command entry options(variable);

call sys_log_$command (severity, ioa_ctl, args);

ARGUMENTS

severity
is a fixed bin(17) argument which defines the severity, as
described above. (Input)

________ ________

sys_log_ sys_log_
________ ________

ioa_ctl
is a char(*) or char(*) varying ioa_ control string describing
the message format. (Input)

args
are arguments to be substituted into the ioa_ control string.
(Input)

EEEnnntttrrryyy::: sssyyysss_llloooggg_$$$cccooommmmmmaaannnddd_eeerrrrrrooorrr

This entrypoint logs/prints an error table code and message in
command mode. The message format is:

caller: error_code_text ioa_message

USAGE

declare sys_log_$command_error entry options(variable);

call sys_log_$command_error (severity, code, caller, ioa_ctl,
args);

ARGUMENTS

severity
is a fixed bin(17) argument which defines the severity, as
described above. (Input)

code
is a fixed bin(35) error table code whose expanded text is
placed in the message. If code is zero, then no error message
text is placed in the message. (Input)

caller
is a char(*) name of the calling program. This is placed in
the message to identify where the message is coming from.
(Input)

ioa_ctl
is a char(*) or char(*) varying ioa_ control string describing
the message format. (Input)

args
are arguments to be substituted into the ioa_ control string.
(Input)

________ ________

sys_log_ sys_log_
________ ________

EEEnnntttrrryyy::: sssyyysss_llloooggg_$$$gggeeennneeerrraaalll

This entrypoint logs/print an error message in either AS or
command modes. It allows the caller to specify which items are
placed in the message, and whether these items are to come from
the input structure or from an associated argument list. This
entrypoint should be used in preference to those above, because
calling programs can be written in a more readable fashion.
Refer to the Notes below for an example.

USAGE

declare sys_log_$general (pointer);

call sys_log_$general (sl_info_ptr);

ARGUMENTS

sl_info_ptr
points to the sl_info structure described below. (Input)

INFO STRUCTURE

The sys_log_$general entrypoint uses information provided by the
following structure to determine which items to place in the
message, and where to obtain those items. This structure is
declared in sys_log_constants.incl.pl1.

________ ________

sys_log_ sys_log_
________ ________

dcl 1 sl_info aligned automatic,
2 version char(8),
2 arg_list_ptr ptr,
2 loc,
3 (mode,
severity,
code,
caller,
data,
class,
ioa_msg) fixed bin,
2 flags,
3 ioa_msg_is_error_code bit(1) unal,
3 flags_pad bit(35) unal,
2 mode fixed bin,
2 severity fixed bin,
2 code fixed bin(35),
2 caller char(65) varying,
2 data,
3 data_ptr ptr,
3 data_lth fixed bin(21),
2 class char(10) varying,
2 ioa_msg char(500) varying;

STRUCTURE ELEMENTS

version
is the version number of this structure. It should be set to
the named constant SL_INFO_version_1. (Input)

arg_list_ptr
is a pointer to an argument list. Various error message items
can be extracted from this argument list, under control of
sl_info.loc. (Input)

loc
is the location of information needed to process the error
message. The information can be given in the sl_info
structure, can come from the argument list, or certain items
can be omitted completely. (Input) All sl_info.loc elements
can have one of the following values:

SL_INFO_arg_given_in_structure (= -1)
the information is located in the correspondingly named,
level 2 structure element.

SL_INFO_arg_not_given (= 0)
the information is not given.

________ ________

sys_log_ sys_log_
________ ________

+N
a positive integer giving the argument number in the
argument list which contains the information.

loc.mode
is the location of the mode.

loc.severity
is the location of the severity.

loc.code
is the location of the error code.

loc.caller
is the location of the caller name.

loc.data
is the location of the binary data pointer and length. If a
positive integer N is given, then the pointer is the Nth
argument in the argument list, and the argument length is
argument N+1.

loc.class
is the location of the binary data class.

loc.ioa_msg
is the location of the ioa_ control string. If a positive
integer N is given, then then ioa_ control string is the Nth
argument in the argument list, and remaining arguments are
substituted into the control string. If
SL_INFO_arg_given_in_structure is given, then ioa_msg is
treated as a character string message text rather than an ioa_
control string; no argument substitution is performed.

flags.ioa_msg_is_error_code
is "1"b if loc.ioa_msg is a positive integer N, and the Nth
argument in the argument list is an error code whose expanded
text is the ioa_ control structure. If this flag is "0"b and
loc.ioa_msg is positive, then the Nth argument in the argument
list is a char(*) or char(*) varying ioa_ control string. If
loc.ioa_msg is nonpositive, this flag is ignored. (Input)

mode
is a fixed bin(17) operating mode for sys_log_. If the mode
is located in the argument list or not given as input, then
the value actually used is returned in sl_info.mode.
(Input/Output) It can be one of the following values:

________ ________

sys_log_ sys_log_
________ ________

SL_INFO_as_mode (= 1)
operate in AS mode. This is the default if loc.mode is
SL_INFO_arg_not_given.

SL_INFO_command_mode (= 2)
operate in command mode.

severity
is a fixed bin(17) argument which defines the severity, as
described above. If the severity is located in the argument
list or not given as input, then the value actually used is
returned in sl_info.severity. (Input/Output) If loc.severity
is SL_INFO_arg_not_given, then SL_LOG is the default value for
mode.

code
is a fixed bin(35) error table code whose expanded text is
placed in the message. If code is -1 or loc.code is
SL_INFO_arg_not_given, then no error table text is placed in
the message. If a zero code is given, it means that no error
really occurred; therefore printing/logging of the sys_log_
message is aborted. Otherwise, code is treated as a standard
error table code whose text is obtained by calling
convert_status_code_ and placed in the message. If code is
located in the argument list, then the value is returned in
sl_info.code. (Input/Output)

caller
is a char(*) name of the program reporting the error. A
caller name should always be given. If the caller is located
in the argument list, then the name is returned in
sl_info.caller. (Input/Output)

data
is a pointer to and fixed bin(17) length of the binary data to
be associated with the logged message. If the data_ptr and
data_lth are located in the argument list, then these values
are returned in sl_info.data_ptr and sl_info.data_lth.
(Input/Output)

class
is a char(*) binary data class name. It is required if binary
data is given. If the class is located in the argument list,
then the data class is returned in sl_info.class.
(Input/Output)

________ ________

sys_log_ sys_log_
________ ________

ioa_msg
is a char(*) or char(*) varying ioa_ control string, or an
error table code whose text is the ioa_ control string (see
sl_info.ioa_msg_is_error_code above). The text expansion
after argument substitution is returned. (Input/Output)

NOTES

The calling program should use an error diagnostic internal
procedure to report its errors. This internal procedure fills in
the sl_info structure and calls sys_log_$general, passing its
argument list as the location for various message items.

The sys_log_constants.incl.pl1 file declares several constant
versions of the sl_info structure to simplify structure
assignment. These are summarized below. Refer to the include
file for details.

sl_info_sev_code_msg
sl_info settings for an SL_INFO_as_mode operation to be used
with an Error internal procedure whose calling sequence is:

call Error (severity, code, ioa_ctl, args);

The Error internal procedure must set sl_info.arg_list_ptr
and sl_info.caller. It may optionally set sl_info.data and
sl_info.class.

sl_info_sev_msg
an SL_INFO_as_mode operation with Error calling sequence:

call Error (severity, ioa_ctl, args);

sl_info_sev_coded_msg
an SL_INFO_as_mode operation with Error calling sequence:

call Error (severity, ioa_ctl_as_error_code, args);

sl_info_sev_code_label_msg
an SL_INFO_as_mode operation with Error calling sequence:

call Error (severity, code, return_label, ioa_ctl, args);

sl_info_code_msg
an SL_INFO_as_mode operation with Error calling sequence:

call Error (code, ioa_ctl, args);

________ ________

sys_log_ sys_log_
________ ________

sl_info_msg
an SL_INFO_as_mode operation with Error calling sequence:

call Error (ioa_ctl, args);

These structure templates can be used in conjunction with an
internal procedure to report errors, as shown in the example
below.

as_proc_: procedure (P_code);

dcl P_code fixed bin(35) parameter;
.
.
dcl MY_NAME char(8) initial ("as_proc_") internal static
options(constant);
.
.
call xxx_ (path, modes, code);
if code ^= 0 then
call Error (SL_LOG_BEEP, code, ABORT_LABEL,
"Calling xxx_ subroutine for ^a.", path);
.
.
ABORT_LABEL:
P_code = code;
return;
.
.
Error: procedure options(variable);

dcl return_label label based(return_label_ptr),
return_label_ptr pointer;

sl_info = sl_info_sev_code_label_msg;
sl_info.arg_list_ptr = cu_$arg_list_ptr();
sl_info.caller = MY_NAME;
call sys_log_$general (addr(sl_info));
if sl_info.code ^= 0 then do;
call cu_$arg_ptr (3, return_label_ptr, 0, 0);
go to return_label;
end;
else return;

end Error;
end as_proc_;

________ _______________________

sys_log_ system_message_handler_
________ _______________________

If sys_log_$general is called with an invalid sl_info structure,
then it reports this error by signalling the sys_log_error_
condition, passing the following condition information structure
which is declared in sys_log_error_info.incl.pl1:

dcl 1 sys_log_error_info aligned automatic,
2 header like condition_info_header,
2 sl_info_ptr ptr;

STRUCTURE ELEMENTS

header.version
is the version number of this structure. It is set to the
named constant SYS_LOG_ERROR_INFO_version_1.

header.action_flags.cant_restart
is "1"b, indicating that restarting with an invalid sl_info
structure is impossible.

header.status_code
is an error table code indicating how the sl_info structure is
invalid.

sl_info_ptr
is a pointer to the invalid sl_info structure.

________________________________________

NNNaaammmeee::: sssyyysssttteeemmm_mmmeeessssssaaagggeee_hhhaaannndddllleeerrr_

EEEnnntttrrryyy::: sssyyysssttteeemmm_mmmeeessssssaaagggeee_hhhaaannndddllleeerrr_$$$sssyyysssttteeemmm_mmmeeessssssaaagggeee_hhhaaannndddllleeerrr_

This subroutine handles the system_message_ condition by
outputting any previously unprocessed messages which have been
sent to the user by send_system_message_. Processes will have a
static handler that calls this subroutine.

USAGE

dcl system_message_handler_ entry ();
dcl sct_manager_$set entry (fixed bin, entry, fixed bin (35));

%include static_handlers;

_______________________ ___________________

system_message_handler_ test_system_control
_______________________ ___________________

call sct_manager_$set (system_message_sct_index,
system_message_handler_, code);

NOTES

The system_message_handler_ will output the message to the
user outputting the text portion of each message to the
users terminal directly through the user_i/o switch.

The handler will special case any inactivity_system_messages
by sending an "inacrcvd" event message back to the
Initializer, using the process' termination event channel
stored in the PIT, to let the Initializer know that the user
has received all system messages.

________________________________________

NNNaaammmeee::: ttteeesssttt_sssyyysssttteeemmm_cccooonnntttrrrooolll

SYNTAX AS A COMMAND

test_system_control test_sc1_dir

FUNCTION

This command establishes a test version of the system control
environment in the user's process. In this environment, the
standard operator requests are available to start user control
functions for the Multics Networking Architecture (MNA), absentee
processing, the message coordinator environment, daemon
processes, etc.

ARGUMENTS

test_sc1_dir
is the pathname of the user directory to be used as the system
control directory. You must specify a directory other than
>sc1 to avoid interfering with the real system control running
in the Initializer process.

ACCESS REQUIRED

This command requires access to a variety of privileged gates
needed to initialize the System Control and User Control
environments. These include hpriv_connection_list_ and
network_accounting_gate_.

___________________ ___________________

test_system_control test_system_control
___________________ ___________________

NOTES

The test >sc1 directory should already contain all segments
needed to run the system control and user control environments.
If segments are missing or incorrectly formatted, error messages
will result and the environment initialization will fail. The
system control environment is not highly robust, so fatal process
errors (although not common) may occur if things are improperly
setup.

The best way to setup the directory is to refer to the
acct_start_up.ec to see what needs to be in the test >sc1
directory. After the test directory is built, invoke
test_system_control and fix all errors which result. Another
(more frustrating) approach is to invoke test_system_control with
an empty directory and fix the errors, reinvoke and fix the new
errors, etc.

___________________ ___________________

test_system_control test_system_control
___________________ ___________________

Minimum contents of a test >sc1 subtree is shown below.

>UDD>DSA>AS>test_sc1
seg admin.ec
seg cdt
seg sat
seg sat.ht
seg sat.install.acs
seg ssu.ec
link mgt >sc1>mgt
link installation_parms >sc1>installation_parms
rate_structure_0
link rtdt >sc1>rtdt
link syserr_log >sc1>syserr_log
msf PNT.pnt
seg 0
seg 1
dir as_logs
seg admin_log
seg log
dir pdt
seg SysAdmin.pdt
seg SysMaint.pdt
seg SysDaemon.pdt
seg Operator.pdt
seg Multics.pdt
dir update
Empty

Other segments will be created when starting up the test system
control and user control environments and their subsystems.

___________________ _____________

test_system_control user_message_
___________________ _____________

NNNaaammmeee::: uuussseeerrr_mmmeeessssssaaagggeee_

This gate allows a user process to read the messages sent to it
by trusted processes.

EEEnnntttrrryyy::: uuussseeerrr_mmmeeessssssaaagggeee_$$$rrreeeaaaddd_mmmeeessssssaaagggeee

This entry is used to read a message from the user message
database.

USAGE

declare user_message_$read_message entry (ptr, ptr, fixed bin
(35));

call user_message_$read_message (area_ptr,
as_user_message_info_ptr, code);

ARGUMENTS

area_ptr
is a pointer to an area in which the returned message will be
allocated. (Input)

as_user_message_info_ptr
is a pointer to the as_user_message_info structure.

code
is a standard system status code.

_____________ _____________

user_message_ user_message_
_____________ _____________

AS_USER_MESSAGE_INFO

declare as_user_message_info_ptr pointer;
declare 1 as_user_message_info aligned
based (as_user_message_info_ptr),
2 version char (8) aligned,
2 flags aligned,
3 read_message_id bit (1) unaligned,
3 read_after_message_id bit (1) unaligned,
3 no_handle_given bit (1) unaligned,
3 ring_given bit (1) unaligned,
3 dont_delete bit (1) unaligned,
3 pad bit (31) unaligned,
2 message_info aligned,
3 message_ptr pointer,
3 message_length fixed bin (18),
3 message_id bit (72) aligned,
3 message_access_class bit (72) aligned,
3 message_handle bit (72) aligned,
3 message_ring fixed bin (3),
2 sender_info aligned,
3 group_id char (32) unaligned,
3 process_id bit (36) aligned,
2 destination_info aligned,
3 group_id char (32) unal,
3 process_id bit (36) aligned,
3 ring fixed bin (3) aligned;

declare AS_USER_MESSAGE_INFO_VERSION_1 char (8)
aligned init ("asum0001") int static options (constant);

STRUCTURE ELEMENTS

version
must be equal to AS_USER_MESSAGE_INFO_VERSION_1. (Input)

read_message_id
is a flag. If "1"b, then the field "message_id" is
interpreted as an input argument. The message whose id is
"message_id" is returned if it exists. The message_handle
field is not respected on input. This flag may not be on if
read_after_message_id is on. (Input)

_____________ _____________

user_message_ user_message_
_____________ _____________

read_after_message_id
is a flag. If "1"b, then the field "message_id" is
interpreted as an input argument. The first message after
message_id for the handle message_handle is returned. This
flag may not be on if read_message_id is on. (Input)

no_handle_given
is a flag. If "1"b, then a message is returned subject to the
read_message_id or read_after_message_id flags without regard
to the handle of the message. If "0"b, then the field
message_handle specifies the handle of the message to be
returned. (Input)

ring_given
is a flag. If "1"b, then the field message_ring is respected
on input, and specified the destination ring of the message to
be read. If "0"b, then messages destined for the current
validation level are returned. (Input)

dont_delete
is a flag. If "1"b, then the message is not deleted from the
user message database even if it is marked for deletion by its
recipient. If "0"b, the message is deleted if it is marked
for deletion. (Input)

message_ptr
is a pointer to the allocated copy of the message. (Output)

message_length
is the length of the allocated message in words. (Output)

message_access_class
is the access class of the message. (Output)

message_handle
if the handle within the process to which the message was
sent. If the flag no_handle_given is "1"b, then this is
(Output). Otherwise it is (Input).

message_ring
is the ring to which the message was sent. This field is only
respected of the flag ring_given is "1"b. (Input)

sender_info
is a substructure describing the process who sent the message.

group_id
is the User.Project.* user name of the sender. (Output)

_____________ ___________________

user_message_ user_message_admin_
_____________ ___________________

process_id
is the process id of the sender. (Output)

ring
is the validation level of the sender at the time that the
sender sent the message. (Output)

destination_info
is a substructure describing how the message was addressed.

group_id
is the starname that specified the user name of the
recipient(s). (Output)

process_id
is the process id, if any, specified for the recipient. If no
process id was specified then this will contain all ones.
(Output)

ring
is the ring specified for the recipient. (Output)

NOTES

Normally, a caller should fill this structure up as follows: set
read_message_id to 1 if the message if is known, zero otherwise.
Set read_after_message_id, no_handle_given, ring_given, and
dont_delete to 0. They are only used for tools that display the
messages pending for the process. Set the message_handle to the
handle for which the message is to be read.

________________________________________

NNNaaammmeee::: uuussseeerrr_mmmeeessssssaaagggeee_aaadddmmmiiinnn_

This gate contains entries callable by system maintainers and
administrators. They permit an administrator to examine the
messages in the user message database.

___________________ ___________________

user_message_admin_ user_message_admin_
___________________ ___________________

EEEnnntttrrryyy::: uuussseeerrr_mmmeeessssssaaagggeee_aaadddmmmiiinnn_$$$rrreeeaaaddd_mmmeeessssssaaagggeee

This entrypoint permits a process to read any message in the user
message database, subject to AIM restrictions. ring1 privilege
is required to read messages whose access classes are not less
than or equal to the caller's authorization.

USAGE

declare user_message_admin_$read_message entry (ptr, ptr, fixed
bin (35));

call user_message_admin_$read_message
(as_user_message_admin_read_info_ptr,
as_user_message_info_ptr, area_ptr, code);

ARGUMENTS

as_user_message_admin_read_info_ptr
is a pointer to the as_user_message_admin_read_info structure.

as_user_message_info_ptr
is a pointer to the as_user_message_info structure described
below under the "user_message_$read" entrypoint. All input
fields in the structure except the version are ignored, since
the message is completely specified by the
user_message_admin_read_info structure. (Input)

area_ptr
is a pointer to an area. The message returned will be copied
into storage allocated in this area. (Input)

code
is a standard system status code.

AS_USER_MESSAGE_ADMIN_READ_INFO

declare as_user_message_admin_read_info_ptr pointer;
declare 1 as_user_message_admin_read_info aligned
based (as_user_message_admin_read_info_ptr),
2 version char (8) aligned,
2 source_group_id char (32) unal,
2 source_process_id bit (36) aligned,
2 target_group_id char (32) unal,
2 target_process_id bit (36) aligned,
2 target_handle bit (72) aligned,
2 after_message_id bit (72) aligned;

___________________ ___________________

user_message_admin_ user_message_admin_
___________________ ___________________

declare AS_USER_MESSAGE_ADMIN_READ_INFO_VERSION_1
char (8) init ("aumar001") int static options (constant);

STRUCTURE ELEMENTS

version
must be AS_USER_MESSAGE_ADMIN_READ_INFO_VERSION_1. (Input)

source_group_id
is a starname specifying the sender of the message to be
read. "" is equivalent to *.*.*. (Input)

source_process_id
is the process id of the source process. If zero, the
source process id is not specified. (Input)

target_group_id
is a starname specifying the recipient(s) of the message to
be read. This starname must be character identical to the
starname specified by the message sender for a message to
match. That is, if a message is sent to "*.*.a", then this
value must be "*.*.a" to read it out. If this value is
equal to "", messages are read regardless of their group id.
(Note that if a message is sent to all users it is stored
with a destination of "*.*.*", not "".) (Input)

target_process_id
is the process id of the recipient of the message. If zero,
then the recipient process id is not specified. (Input)

target_handle
is the target handle of the message to be read. If zero,
then the handle is not specified. (Input)

after_message_id
is a message id of a message previously read. The message
returned will be one entered after the message identified by
this message_id. If any of the target_ fields are
specified, then it will be the next message that matches
those fields. If no target fields are specified, then it
will be the very next message. If this message_id refers to
a message whose access class is not less than or equal to
that of the process, and the caller lacks ring1 privilege,
this argument is ignored. (Input)

___________________ __________________

user_message_admin_ user_message_priv_
___________________ __________________

NNNaaammmeee::: uuussseeerrr_mmmeeessssssaaagggeee_ppprrriiivvv_

This gate contains entries used by trusted processes to send
messages to user processes using the user_message facility. In
this context, a "trusted process" is a process trusted not to
mis-use this facility (e.g., by sending infinite quantities of
messages or disrupting another process's use). Access to this
gate does not permit a process to write messages down to lower
authorizations without the ring1 system privilege.

EEEnnntttrrryyy::: uuussseeerrr_mmmeeessssssaaagggeee_ppprrriiivvv_$$$aaadddddd_mmmeeessssssaaagggeee

This entry is called to queue a message for delivery to a
process.

USAGE

declare user_message_priv_$add_message entry (ptr, fixed bin
(35));

call user_message_priv_$add_message
(as_user_add_message_info_ptr, code);

ARGUMENTS

as_user_message_add_ptr
is a pointer to the as_user_message_add structure, as declared
in as_user_message_add.incl.pl1 and described below. (Input)

code
is a standard system status code. It will be nonzero only if
the message could not be added.

AS_USER_MESSAGE_ADD_INFO

declare as_user_message_add_info_ptr pointer;
declare 1 as_user_message_add_info aligned
based (as_user_message_add_info),
2 version char (8) aligned,
2 message_info aligned,
3 message_ptr pointer,
3 message_length fixed bin (18),
3 message_access_class bit (72) aligned,
3 message_id bit (72) aligned,
2 destination_info aligned,

__________________ __________________

user_message_priv_ user_message_priv_
__________________ __________________

3 group_id char (32) unal,
3 process_id bit (36) aligned,
3 handle bit (72) aligned,
3 reader_deletes bit (1) aligned;

declare AS_USER_MESSAGE_ADD_INFO_VERSION_1
char (8) init ("auma0001") int static options (constant);

STRUCTURE ELEMENTS

version
is the version of this structure, and must be set to
AS_USER_MESSAGE_ADD_INFO_VERSION_1. (Input)

message_ptr
is a pointer to the text of the message to be added.
(Input)

message_length
is the length, in words, of the message to be added.
(Input)

message_access_class
is the access class marking for the message. Unless the
caller has the ring1 system privilege set, this must be
equal to the calling process authorization.

message_id
is the unique id assigned to the message when it is stored.
(Output)

group_id
is the target group_id of the message. If process_id is not
all ones, then this should be set to "" as it is not used.
This may be a starname. If this is not "" and process_id is
not all ones, the call is invalid and an error code is
returned.

process_id
is the process id of the process to which the message will
be delivered. If the message is to be delivered to more
than one process, (or the target process id is unknown) then
this must be set to all ones.

handle
is the protocol handle within the target processes to which

__________________ __________________

user_message_priv_ user_message_priv_
__________________ __________________

the message will be delivered. This may not be zero.
Handles with the first bit equal to 1 are reserved for
global system protocols.

reader_deletes
specifies whether the recipient the message should delete
it. If this is set to 1, then any recipient may delete the
message. If this is set to 0, then only the sender may
delete the message.

NOTES

The system automatically deletes all messages destined for a
specific process id when the process terminates. Thus a sender
may set reader_deletes to 0 and specify a process id, and the
message will be readable until the process terminates.

EEEnnntttrrryyy::: uuussseeerrr_mmmeeessssssaaagggeee_ppprrriiivvv_$$$dddeeellleeettteee_mmmeeessssssaaagggeee_iiiddd

This entry is used by a sender to delete a message. The message
must be specified by message_id. The message access class must
be equal to the caller authorization unless the caller has ring1
privilege.

USAGE

declare user_message_priv_$delete_message_id entry (bit (72)
aligned, fixed bin (35));

call user_message_priv_$delete_message_id (message_id, code);

ARGUMENTS

message_id
is the message id returned by add_message when the message was
added.

code
is a standard system status code.

__________________ __________________

user_message_priv_ user_message_priv_
__________________ __________________

EEEnnntttrrryyy::: uuussseeerrr_mmmeeessssssaaagggeee_ppprrriiivvv_$$$dddeeellleeettteee_ppprrroooccceeessssss_mmmeeessssssaaagggeeesss

This entrypoint deletes all the messages whose destination is a
specific process as specified by process_id. Only those messages
whose access classes are equal to the caller's authorization are
deleted unless the caller has ring1 privilege.

USAGE

declare user_message_priv_$delete_process_messages entry (bit
(36) aligned, fixed bin (35));

call user_message_priv_$delete_process_messages (pid, code);

ARGUMENTS

pid
is the process id of the process whose messages are to be
deleted. All messages whose destination is this process id
specifically are deleted.

code
is a standard system status code.

EEEnnntttrrryyy::: uuussseeerrr_mmmeeessssssaaagggeee_ppprrriiivvv_$$$sssyyysssttteeemmm_iiinnniiittt

This entrypoint is called by the Initializer as part of Answering
Service initialization. It deletes any information left from a
previous bootload and creates a new user_message database. This
entrypoint uses the syserr log to report details of problems on
the bootload console.

USAGE

declare user_message_priv_$system_init entry (fixed bin (35));

call user_message_priv_$system_init (code);

ARGUMENTS

code
is a standard system status code. It will be nonzero if and
only if it was impossible to set up a functional user_message
facility.

__________________ _______

user_message_priv_ ws_tty_
__________________ _______

NNNaaammmeee::: wwwsss_ttttttyyy_

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$aaabbbooorrrttt

This entry aborts current i/o and resets the read or write
buffers and stops echo negotiated input.

USAGE

dcl ws_tty_$abort entry (ptr, fixed bin, fixed bin, fixed
bin(35));

call ws_tty_$abort (iocb_ptr, reset_switch, state, code);

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

reset_switch
indicates whether read or write are to be reset. (Input)
1 reset read
2 reset write
3 reset both

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$aaattttttaaaccchhh

This entry "attaches" video mode to WSTERM by informing the
workstation software that synchronous mode is required to support
video and sends WSTERM a list of the break characters.

USAGE

dcl ws_tty_$attach entry (ptr, char(*), fixed bin(71), fixed bin,
fixed bin(35));

_______ _______

ws_tty_ ws_tty_
_______ _______

call ws_tty_$attach (iocb_ptr, name, event, state, code);

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

name
is the channel name and must be "mowse.". (Input)

event
is not used. (Input)

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$dddeeetttaaaccchhh

This entry "detaches" video mode from WSTERM by informing the
workstation software that synchronous communication is no longer
required. Asynchronous communication is established for
non-video mode.

USAGE

dcl ws_tty_$detach entry (ptr, fixed bin, fixed bin, fixed
bin(35));

call ws_tty_$detach (iocb_ptr, dflag, state, code);

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

dflag
is not used. (Input)

_______ _______

ws_tty_ ws_tty_
_______ _______

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$eeevvveeennnttt

This entry simply sets the tty state and returns.

USAGE

dcl ws_tty_$event entry (ptr, fixed bin(71), fixed bin, fixed
bin(35));

call ws_tty_$event (iocb_ptr, event, state, code);

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

event
is the event channel name. (Input)

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

NOTES

This entry is not believed to be needed but is retained in case
the event should need to be passed to hcs_$tty_event. There is
only one known video call to this entry and it appears redundant.

_______ _______

ws_tty_ ws_tty_
_______ _______

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$ooorrrdddeeerrr

This entry performs the specified control order on the i/o
switch.

USAGE

dcl ws_tty_$order entry (ptr, char(*), ptr, fixed bin, fixed
bin(35));

call ws_tty_$order (iocb_ptr, order, info_ptr, state, code);

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

order
is the name of the control order. (Input)

info_ptr
is null or points to the data whose form depends on the
control order. (Input)

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

NOTES

The following list of control orders are supported. With two
exceptions, these orders are passed to mowse_io_ for processing.
The first exception is that control orders which involve a
structure containing a version indicator are checked for the
current version. In the second exception, the modes order passes
the new modes to mowse_io_ via iox_$modes after changing the data
from a structure to a character string.

abort
debug_on
debug_off
get_editing_chars

_______ _______

ws_tty_ ws_tty_
_______ _______

get_event_channel
get_foreign_terminal_data
get_input_conversion
get_input_translation
get_mowse_info
get_output_conversion
get_output_translation
get_special
get_terminal_emulator_state
line_length
modes
printer_off
printer_on
put_to_sleep
quit_disable
quit_enable
read_status
resetread
resetwrite
send_local_message
send_message
set_echo_break_table
set_editing_chars
set_input_conversion
set_input_translation
set_output_conversion
set_output_translation
set_special
set_terminal_data
set_term_type
start
store_id
store_mowse_info
terminal_info
trace_on
trace_off
write_status

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$rrreeeaaaddd

This entry reads unechoed characters from the workstation.

USAGE

dcl ws_tty_$read entry (ptr, ptr, fixed bin(21), fixed bin(21),
fixed bin(21), fixed bin, fixed bin(35));

_______ _______

ws_tty_ ws_tty_
_______ _______

call ws_tty_$read (iocb_ptr, buffer_ptr, offset, n_chars_to_read,
n_chars_read, state, code);

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

buffer_ptr
points to caller's buffer. (Input)

offset
is the offset in caller's buffer to start at. (Input)

n_chars_to_read
is the maximum number of characters to return. (Input)

n_chars_read
is the actual number of characters returned. (Output)

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$rrreeeaaaddd_eeeccchhhoooeeeddd

This entry reads echoed characters from the workstation. Echoing
stops on a break character and type ahead is not echoed by the
workstation.

USAGE

dcl ws_tty_$read_echoed entry (ptr, ptr, fixed bin(21), fixed
bin(21), fixed bin(21), fixed bin(21), fixed bin, fixed bin,
fixed bin(35));

call ws_tty_$read_echoed (iocb_ptr, buffer_ptr, offset,
n_chars_to_read, n_chars_read, echoed, screen_left, state,
code);

_______ _______

ws_tty_ ws_tty_
_______ _______

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

buffer_ptr
points to caller's buffer. (Input)

offset
is the offset in caller's buffer to start at. (Input)

n_chars_to_read
is the maximum number of characters to return. (Input)

n_chars_read
is the actual number of characters returned. (Output)

echoed
is the number of characters echoed by interrupt side?
(Output)

screen_left
is the space left on line, negotiate entry? (Input)

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$rrreeeaaaddd_wwwiiittthhh_mmmaaarrrkkk

This entry is like read but a mark is set to indicate the end of
input.

USAGE

dcl ws_tty_$read_with_mark entry (ptr, char(*), fixed bin(21),
fixed bin(21), fixed bin, fixed bin(35));

call ws_tty_$read_with_mark (iocb_ptr, buffer, n_chars_read,
mark_index, state, code);

_______ _______

ws_tty_ ws_tty_
_______ _______

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

buffer
is the caller's buffer. (Input)

n_chars_read
is the actual number of characters returned. (Output)

mark_index
is an index in the returned string. (Output)

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$wwwrrriiittteee

This entry displays the caller's text by sending it to the
workstation.

USAGE

dcl ws_tty_$write entry (ptr, ptr, fixed bin(21), fixed bin(21),
fixed bin(21), fixed bin, fixed bin(35));

call ws_tty_$write (iocb_ptr, buffer_ptr, offset,
n_chars_to_write, n_chars_written, state, code);

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

buffer_ptr
pointer to caller's buffer. (Input)

offset
is the offset in caller's buffer to start at. (Input)

n_chars_to_write
is the maximum number of characters supplied. (Input)

_______ _______

ws_tty_ ws_tty_
_______ _______

n_chars_written
is the actual number of characters written. (Output)

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

code
is a standard status code. (Output)

EEEnnntttrrryyy::: wwwsss_ttttttyyy_$$$wwwrrriiittteee_wwwhhhooollleee_ssstttrrriiinnnggg

This entry is the same as write. It displays the caller's text
by sending it to the workstation.

USAGE

dcl ws_tty_$write_whole_string entry (ptr, char(*), bit(1), fixed
bin(21), fixed bin, fixed bin(35));

call ws_tty_$write_whole_string (iocb_ptr, string, mark_flag,
n_chars_written, state, code);

ARGUMENTS

iocb_ptr
points to the I/O control block of mowse_terminal_. (Input)

string
is the caller's character string to write. (Input)

mark_flag
indicates whether to set a mark. (Input)
"0"b don't set mark
"1"b set mark

n_chars_written
is the actual number of characters written. (Output)

state
indicates the tty state. (Output)
1 ignored
2 listening
5 dialed

_______ _______

ws_tty_ ws_tty_
_______ _______

code
is a standard status code. (Output)

Workstation Interfaces

The ws_tty_ modules communicate with the workstation software
(WSTERM) via calls to iox_. Actually these calls to iox_ are
calls to mowse_io_ which itself uses iox_ to exchange messages
with the MOWSE software on the workstation which in turn talks
to WSTERM.

There are two basic means by which ws_tty_ and WSTERM exchange
data. The most common method is via specific control
messages. These control messages are sent to WSTERM with an
iox_ "send_message" control order and fetched from WSTERM with
an iox_$get_chars call. Control messages are for exchanging
control data concerning the workstation environment and also
for reading user entered text.

The second method of communication is for writing text to the
workstation screen. This is done by ws_tty_ with calls to
iox_$put_chars. Using this method of writing text to the
workstation guarantees that plain text written to the screen
will not be misinterpreted as a control message. Control
messages and written text are identified by WSTERM by their
different min-cap ids.

Control message example

Suppose we want ws_tty_ to send the control message to WSTERM
to exit sync mode. The control message text is "XSM000000".
To send this we first append the foreground control message
min-cap id to the front of the message.

control_message = FG_CONTROL_MESSAGE || "XSM000000"

Then using

call iox_$control(iocb_ptr, "send_message", mowse_io_message_ptr, code);

where mowse_io_message_ptr ->
mowse_io_message.version = mowse_io_info_version_1;
mowse_io_message.channel = FG;
mowse_io_message.io_message_ptr = addr(control_message);
mowse_io_message.io_message_len = 10;

_______ _______

ws_tty_ ws_tty_
_______ _______

will send the message to WSTERM. (The constants and
structures are defined in the mowse include files.) Then when
WSTERM does a getdata it will find the text "XSM000000" with
the minor capability field set to FG_CONTROL_MESSAGE.

Sending Text Example

But if we want ws_tty_ to send the plain text "hello world",
this is the procedure when we set

term_message = "hello world";

call iox_$put_chars (iocb_ptr, addr(term_message), 11, code);

Then WSTERM will see the text "hello world" with the min cap
of FG_TERMINAL_DATA.

Likewise, ws_tty_ reads data from WSTERM with a call to
iox_$get_chars.

Control Message Format

The following description of the control messages does not
include the FG_CONTROL_MESSAGE byte appended to the front of
messages sent from ws_tty_ to WSTERM.

byte: 1 2 3 4 5 6..size+5
--------------------------------------------
| message id | size | data ... |
--------------------------------------------

message id
is a 3 character field identifying the message type and is
defined below.

size
is the number of bytes of data and is zero if there is no
data. This is a two byte (16 bit) unsigned binary number.
The largest data size is therefore 2**16-1 or 65535 bytes.

data
may or may not be present depending on the type and is
defined below.

_______ _______

ws_tty_ ws_tty_
_______ _______

Control Message Types

The functionality of the following controls is detailed in MTB741
section 6 and MTB708. These message ids are defined in
ws_control_ids.incl.pl1.
message type message direction data
id ws_tty_:WSTERM
---------------------------- ---- -------------- ---------------
Abort ABT -> -
Enter Sync Mode ESM -> break table
Sync Mode Entered SME <- -
Exit Sync Mode XSM -> -
Sync Mode Exited SMX <- -
End Echoed Input EEI <- text
End Non-echoed Input ENI <- text
Read with No Echo RNE -> count
Read With Echo RWE -> count
Set Break Table SBT -> break table
Set TTY Modes STM -> tty modes
Echoed Input Chars EIC <- text
Unechoed Input Chars UIC <- text
Printer On PON -> -
Printer Off POF -> -
Order ORD -> control order
-----------------------------------------------------------------

Break table

The break table format is simply the list of printing ASCII
characters that are to be interpreted as causing break on input.
The nonprinting control characters (octal 000 to 037 and 177) are
always break characters. If the break table is null, that is the
size is zero, there are no break characters. If the break table
size is -1 break-all mode is indicated and no break table data is
present.

TTY modes

The TTY modes data is a six byte field which contains the
following values:

_______ _______

ws_tty_ ws_tty_
_______ _______

data byte contents
----- ----------
1 mode switches, to be further defined as needed
2 kill character (default is @)
3 erase character (default is #)
4 literal next character (default is )
5 maximum column or line length (default is 80)
6 max lines or page length (default is 23)

Control order

The data field of the Order control message is the ascii text of
the order as passed to ws_tty_ plus any relevant data specific to
the control order. No control orders are currently required to
be passed to WSTERM, but this mechanism will allow for the
possibility in the future.

Read count

The count in RNE and RWE is a two byte or 16 bit field containing
an integer of the number of characters to read. In the unlikely
event that the read count exceeds this 64K field, ws_tty_ will
make repeated reads until the count is satisfied.

Text

Text data is simply a string of ASCII characters, one per byte.
The number of characters is given by the message size.