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.
  
  -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 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)
  
  -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,
  
  
____                                                         ____
  
  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)
  
  -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.  (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
  
  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 owner
     is returned.  (Input)
  
  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
  
  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.
  
  
  
  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_
  ____                                                         ____
  
  
  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.
  
  
  
  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)
  
  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.
  
  
  
  
  
  
____                                                         ____
  
  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)
  
  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.
  
  
  
  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
  
  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.
  
  
  
  
  
  
  
  
  
  
  
  
____                                                         ____
  
  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
  
  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.
  
  
____                                                         ____
  
  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)
  
  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.
  
  
  
  
  
____                                                         ____
  
  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)
  
  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.
  
  
  
  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:
  
     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);
  
  
  
  
  
  
  
  
  
  
  
____________                                         ____________
  
  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
  
  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.
  
               ________________________________________
  
  
  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:
  
     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);
  
  
  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.
  
     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_$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.
  
  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.
  
  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
  
  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_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)
  
  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)
  
  
               ________________________________________
  
  
  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
  _____________                                       _____________
  
  
     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);
  
  
  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.
  
  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   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)
  
  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   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)
  
  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)
  
  
  
  
_______________                          ________________________
  
  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.
  
  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)
  
  
  
  
  
  
________________________                           ______________
  
  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)
  
  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)
  
  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)
  
  
  
  
  
  
______________                                  _________________
  
  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_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_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)
  
  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   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)
  
  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)
  
  
  
  
  
  
______________                                     ______________
  
  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)
  
  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)
  
  
  
  
______________                                     ______________
  
  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_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_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
  _____________                                ____________________
  
  
  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   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_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_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)
  
  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   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)
  
  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   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)
  
  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   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_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_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)
  
  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   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)
  
  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   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)
  
  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   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_.
  
  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  "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)
  
  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  "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)
  
  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:
     error_table_$moderr
        incorrect access modes to perform the operation.
     error_table_$ai_restricted
        incorrect authorization to complete the operation.
  
  
  
  
  
______________________                              _____________
  
  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)
  
  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.
  
  
  
_____________                                     _______________
  
  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)
  
  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 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)
  
  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 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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  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.
  
  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 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.
  
  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 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_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)
  
  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  "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)
  
  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 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_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)
  
  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 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_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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  
  
_______________________________   _______________________________
  
  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)
  
  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.
  
  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.
  
  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.
  
  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)
  
  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.
  
  
  
  
________________________                            _____________
  
  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)
  
  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.
  
  
_____________                               _____________________
  
  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)
  
  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.
  
  
  
_____________________                 ___________________________
  
  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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  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:
  
  
  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);
  
  
  
  
___________________________               _______________________
  
  $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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  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:
  
  
  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.
  
  
  
  
_______________________                __________________________
  
  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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  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:
  
  
  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.
  
  
  
  
__________________________                    ___________________
  
  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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  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:
  
  
  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.
  
  
  
___________________                    __________________________
  
  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.
  
  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
  
  
__________________________            ___________________________
  
  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)
  
  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.
     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,
  
  
___________________________           ___________________________
  
  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);
  
  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.
  
  
  
  
  
___________________________           ___________________________
  
  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)
  
  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 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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  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
  
  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.
  
  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
  
  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
  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.   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_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)
  
        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  the  number  of
        characters placed in the user area).
  
  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)
  
        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  the  number  of
        characters placed in the user area).
  
  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)
  
        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)
  
  
  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)
  
        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.
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
____                                                         ____
  
  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)
  
        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
  
  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)
  
        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)
  
  
  
  
  
  
  
  
  
____                                                         ____
  
  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)
  
        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)
  
  
  
  
  
  
____                                                         ____
  
  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)
  
        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)
  
  
  
  
  
  
  
  
  
  
  
  
_________                                               _________
  
  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)
  
        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)
  
  
  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)
  
        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)
  
               ________________________________________
  
  
  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.
  
  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  "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.
  
  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  "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_$$$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.
  
  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
  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)
  
  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  "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)
  
  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  "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.
  
  
  
  
  
  
  
  
  
_____________________               _____________________________
  
  $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
  _____________________________      ______________________________
  
  
  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:
     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 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)
  
  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.
  
  
______________________________              _____________________
  
  message_segment_$compact_index              message_segment_$copy
  ______________________________              _____________________
  
  
  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 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
  _____________________                     _______________________
  
  
  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 "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)
  
  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.
  
  
_______________________              ____________________________
  
  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)
  
  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.
     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  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
  
  
____________________________        _____________________________
  
  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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  
  
  
_____________________________      ______________________________
  
  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.
  
  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.
  
  
  
______________________________    _______________________________
  
  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.
  
  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.
  
  
  
  
  
  
  
  
  
_______________________________           _______________________
  
  message_segment_$get_mode_index           $get_message_count_file
  _______________________________           _______________________
  
  
  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::: $$$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)
  
  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.
  
  
  
  
  
  
  
  
_______________________                  ________________________
  
  $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)
  
  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  "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.
  
  
  
________________________                   ______________________
  
  $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:
  
  
  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.
  
  
  
______________________                    _______________________
  
  $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
  
  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:
  
  
  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.
  
  
  
_______________________               ___________________________
  
  $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)
  
  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.
  
  
  
  
  
___________________________           ___________________________
  
  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:
  
     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))
       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.
  
  
  
  
  
___________________________        ______________________________
  
  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)
  
  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.
  
  
  
  
  
  
______________________________     ______________________________
  
  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_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
        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).
  
  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.
  
  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)
  
  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.
  
  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
  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)
  
  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  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)
  
  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)
  
  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:
  
  
  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.
  
  
  
__________________________            ___________________________
  
  $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)
  
  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)
  
  code
     is a  standard system status  code.  (Output) It  can have the
  
  
___________________________           ___________________________
  
  $own_incremental_read_index           $own_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
  
  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:
  
  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.
  
  
  
  
___________________________        ______________________________
  
  $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:
  
  
  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.
  
  
______________________________    _______________________________
  
  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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  
_______________________________   _______________________________
  
  message_segment_$own_read_index   message_segment_$own_read_index
  _______________________________   _______________________________
  
  
  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:
  
  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.
  
  
  
  
  
  
_______________________________                 _________________
  
  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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  
  
  
  
  
  
  
_________________                               _________________
  
  $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:
  
  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.
  
  
_________________                              __________________
  
  $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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  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
  
  
__________________                             __________________
  
  $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:
  
  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.
  
  
  
  
  
  
  
  
__________________                                     __________
  
  $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)
  
  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.
  
  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.
     error_table_$ai_restricted
        incorrect authorization to complete the operation.
     error_table_$no_message
        no message available with desired characteristics.
  
  
  
  
  
  
__________                                             __________
  
  $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:
  
  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.
  
  
  
  
  
  
  
__________                            ___________________________
  
  $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)
  
  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.
  
  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.
     error_table_$ai_restricted
        incorrect authorization to complete the operation.
     error_table_$no_message
        no message available with desired characteristics.
  
  
  
  
  
  
  
___________________________           ___________________________
  
  message_segment_$read_index           message_segment_$read_index
  ___________________________           ___________________________
  
  
  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:
  
  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.
  
  
  
  
  
  
  
___________________________                    __________________
  
  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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  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
  
  
__________________                             __________________
  
  $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:
  
  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);
  
  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.
  
  
  
__________________                             __________________
  
  $read_message_file                             $read_message_file
  __________________                             __________________
  
  
  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.
  
  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)
  
  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.
     error_table_$no_message
        no message available with desired characteristics.
  
  
___________________                           ___________________
  
  $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:
  
  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);
  
  
  
  
  
  
  
  
  
  
  
  
  
  
___________________                           ___________________
  
  $read_message_index                           $read_message_index
  ___________________                           ___________________
  
  
  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.
  
  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
  
  
___________________          ____________________________________
  
  $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)
  
  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
  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
  
  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::: 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
  
  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.
  
  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.
  
  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
        incorrect access on directory containing 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
  
  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_$$$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
  
  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_$$$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
  
  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 at  system_low and thus
  accessible to everyone.
  
               ________________________________________
  
  
  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.
  
  dcl    1  device_info based (device_info_ptr) aligned,
            2  version_num      fixed bin,
            2  usage_time       fixed bin,
            2  wait_time        fixed bin,
            2  system_flag      bit(1),
            2  device_name      char(8),
            2  model            fixed bin,
            2  qualifiers(4)    fixed bin(35);
  
  STRUCTURE ELEMENTS
  
  version_num
       is  the version  number of   this structure.   This will  be
       different for each resource type.  (Input)
  
  usage_time
       number  of minutes device  will/may be used.   (Reserved for
       future use.)
  
  wait_time
       number  of  minutes  user   will/must  wait  for  assignment
       completion.  (Reserved for future use.)
  
  
  
____                                                         ____
  
  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).
  
  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.   See  the   documentation  on  the  send_as_request_
  subroutine for more information about the calling sequence.
  
  
________________                                 ________________
  
  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.
  
  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.
  
  
  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
  
  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 asr_com_channel_info.incl.pl1.
  
  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.
  
  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.
  
  
  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
  
  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 asr_daemon_command.incl.pl1.
  
  
  
  
  
  
  
________________                                 ________________
  
  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.
  
  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.   See  the   documentation  on  the  send_as_request_
  subroutine for more information about the calling sequence.
  
  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.
  
  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.   See  the   documentation  on  the  send_as_request_
  subroutine for more information about the calling sequence.
  
  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,
  
  
________________                                 ________________
  
  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)
  
  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
     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.
  
  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.   See  the   documentation  on  the  send_as_request_
  subroutine for more information about the calling sequence.
  
  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.
  
  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.   See  the   documentation  on  the  send_as_request_
  subroutine for more information about the calling sequence.
  
  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.
  
  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.   See  the   documentation  on  the  send_as_request_
  subroutine for more information about the calling sequence.
  
  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.
  
  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.
  
  
  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  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
  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.
  
  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.
  
  
  
  
  
  
  
  
  
  
  
  
  

  ___________________                                 _____________
  
  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.