1 :Info: hcs_: 2022-08-26 hcs_
2
3
4 To obtain information on a particular entry point use the "ep" request
5
6
7 :Entry: add_acl_entries: 1982-05-12 hcs_$add_acl_entries
8
9
10 Function: adds specified access modes to the access control list ACL
11 of the specified segment. If an access name already appears on the
12 ACL of the segment, its mode is changed to the one specified by the
13 call.
14
15
16 Syntax:
17 declare hcs_$add_acl_entries entry char* char* ptr fixed bin
18 fixed bin35;
19 call hcs_$add_acl_entries dir_name entryname acl_ptr acl_count
20 code;
21
22
23 Arguments:
24 dir_name
25 is the pathname of the containing directory. Input
26 entryname
27 is the entryname of the segment. Input
28 acl_ptr
29 points to a user-filled segment_acl_array structure see "Notes"
30 below. Input
31 acl_count
32 contains the number of ACL entries in the segment_acl_array
33 structure see "Notes" below. Input
34 code
35 is a storage system status code. Output
36
37
38 Notes: The segment_acl_array structure should be declared as follows.
39
40 dcl segment_acl_array acl_count aligned like segment_acl_entry;
41
42 The segment_acl_entry structure is declared in the include file
43 acl_structures.incl.pl1.
44
45
46 :Entry: add_dir_acl_entries: 1982-05-12 hcs_$add_dir_acl_entries
47
48
49 Function: adds specified directory access modes to the access control
50 list ACL of the specified directory. If an access name already
51 appears on the ACL of the directory, its mode is changed to the one
52 specified by the call.
53
54
55 Syntax:
56 declare hcs_$add_dir_acl_entries entry char* char* ptr
57 fixed bin fixed bin35;
58 call hcs_$add_dir_acl_entries dir_name entryname acl_ptr acl_count
59 code;
60
61
62 Arguments:
63 dir_name
64 is the pathname of the containing directory. Input
65 entryname
66 is the entryname of the directory. Input
67 acl_ptr
68 points to a user-filled dir_acl_array structure see "Notes" below.
69 Input
70 acl_count
71 contains the number of ACL entries in the dir_acl_array structure
72 see "Notes" below. Input
73 code
74 is a storage system status code. Output
75
76
77 Notes: The dir_acl_array structure should be declared as follows.
78
79 dcl dir_acl_array acl_count aligned like dir_acl_entry;
80
81 The dir_acl_entry structure is declared in the include file
82 acl_structures.incl.pl1.
83
84
85 :Entry: add_dir_inacl_entries: 1982-03-08 hcs_$add_dir_inacl_entries
86
87
88 Function: adds specified directory access modes to the initial access
89 control list initial ACL for new directories created for the
90 specified ring within the specified directory. If an access name
91 already appears on the initial ACL of the directory, its mode is
92 changed to the one specified by the call.
93
94
95 Syntax:
96 declare hcs_$add_dir_inacl_entries entry char* char* ptr
97 fixed bin fixed bin3 fixed bin35;
98 call hcs_$add_dir_inacl_entries dir_name entryname acl_ptr
99 acl_count ring code;
100
101
102 Arguments:
103 dir_name
104 is the pathname of the containing directory. Input
105 entryname
106 is the entryname of the directory. Input
107 acl_ptr
108 points to a user-filled dir_acl structure described in the
109 hcs_$add_dir_acl_entries entry point. Input
110 acl_count
111 contains the number of initial ACL entries in the dir_acl structure.
112 Input
113 ring
114 is the ring number of the initial ACL. Input
115 code
116 is a storage system status code. Output
117
118
119 :Entry: add_inacl_entries: 1982-03-08 hcs_$add_inacl_entries
120
121
122 Function: adds specified access modes to the initial access control
123 list initial ACL for new segments created for the specified ring
124 within the specified directory. If an access name already appears on
125 the initial ACL of the segment, its mode is changed to the one
126 specified by the call.
127
128
129 Syntax:
130 declare hcs_$add_inacl_entries entry char* char* ptr fixed bin
131 fixed bin3 fixed bin35;
132 call hcs_$add_inacl_entries dir_name entryname acl_ptr acl_count
133 ring code;
134
135
136 Arguments:
137 dir_name
138 is the pathname of the containing directory. Input
139 entryname
140 is the entryname of the directory. Input
141 acl_ptr
142 points to a user-filled segment_acl structure described in the
143 hcs_$add_acl_entries entry point. Input
144 acl_count
145 contains the number of initial ACL entries in the segment_acl
146 structure. Input
147 ring
148 is the ring number of the initial ACL. Input
149 code
150 is a storage system status code. Output
151
152
153 Notes: If code is returned as error_table_$argerr, then the erroneous
154 initial ACL entries in segment_acl have status_code set to an
155 appropriate error code. No processing is performed in this instance.
156
157
158 :Entry: append_branch: 1982-03-08 hcs_$append_branch
159
160
161 Function: creates a segment in the specified directory, initializes
162 the access control list ACL of the segment by adding *.SysDaemon.*
163 with a mode of rw and adding the initial ACL for segments found in the
164 containing directory, and adds the user to the ACL of the segment with
165 the mode specified. ACLs and initial ACLs are described under "Access
166 Control" in the Reference Manual.
167
168
169 Syntax:
170 declare hcs_$append_branch entry char* char* fixed bin5
171 fixed bin35;
172 call hcs_$append_branch dir_name entryname mode code;
173
174
175 Arguments:
176 dir_name
177 is the pathname of the containing directory. Input
178 entryname
179 is the entryname of the segment. Input
180 mode
181 is the user's access mode. See the hcs_$append_branchx entry point
182 for values of the access mode argument. Input
183 code
184 is a storage system status code. Output
185
186
187 Access required:
188 Append permission on the containing directory is required to add a
189 segment to that directory.
190
191
192 Notes: A number of attributes of the segment are set to default
193 values as follows:
194 1. Ring brackets are set to the user's current validation level.
195 2. The User_id of the ACL entry specifying the given mode is set
196 to the Person_id and Project_id of the user, with the
197 instance tag set to an asterisk *.
198 3. The copy switch in the branch is set to 0.
199 4. The bit count is set to 0.
200
201 The hcs_$append_branchx entry point creates a
202 storage system entry with values other than the defaults listed above.
203
204
205 :Entry: append_branchx: 1982-05-12 hcs_$append_branchx
206
207
208 Function: creates either a subdirectory or a segment in a specified
209 directory. If a subdirectory is created, then the access control list
210 ACL of the subdirectory is initialized by adding *.SysDaemon.* with
211 a mode of sma and adding the initial ACL for directories that is
212 stored in the containing directory; otherwise the ACL of the segment
213 is initialized by adding *.SysDaemon.* with a mode of rw and adding
214 the initial ACL for segments. The input User_id and mode are then
215 merged to form an ACL entry that is added to the ACL of the
216 subdirectory or segment.
217
218
219 Syntax:
220 declare hcs_$append_branchx entry char* char* fixed bin5
221 3 fixed bin3 char* fixed bin1 fixed bin1
222 fixed bin24 fixed bin35;
223 call hcs_$append_branchx dir_name entryname mode rings user_id
224 dir_sw copy_sw bit_count code;
225
226
227 Arguments:
228 dir_name
229 is the pathname of the containing directory. Input
230 entryname
231 is the entryname of the segment or subdirectory. Input
232 mode
233 is the user's access mode see "Notes" below. Input
234 rings
235 is a three-element array that specifies the ring brackets of the new
236 segment or subdirectory. Input If a subdirectory is to be
237 created, the third element is ignored. See "Intraprocess Access
238 Control" in the Reference Manual.
239 user_id
240 is an access control name of the form Person_id.Project_id.tag.
241 Input
242
243
244 dir_sw
245 is the branch's directory switch. Input
246 1 if a directory is being created
247 0 if a segment is being created
248 copy_sw
249 is the value of the copy switch to be placed in the branch. Input
250 See "Entry Attributes" in the Reference Manual for an explanation of
251 the copy switch.
252 bit_count
253 is the segment length in bits. Input
254 code
255 is a storage system status code. Output
256
257
258 Access required:
259 Append permission is required on the containing directory to add an
260 entry to that directory.
261
262
263 Notes: The mode argument is a fixed binary number where the desired
264 mode is encoded with one access mode specified by each bit. For
265 segments the modes are:
266 read the 8-bit is 1 i.e. 01000b
267 execute the 4-bit is 1 i.e. 00100b
268 write the 2-bit is 1 i.e. 00010b
269 For directories, the modes are:
270 status the 8-bit is 1 i.e. 01000b
271 modify the 2-bit is 1 i.e. 00010b
272 append the 1-bit is 1 i.e. 00001b
273
274
275 If modify permission is given for a directory, then status must also be
276 given; i.e., 01010b.
277
278 The unused bits are reserved for unimplemented attributes and must be
279 zero. For example, rw access is 01010b in binary form.
280
281
282 :Entry: append_link: 1982-03-08 hcs_$append_link
283
284
285 Function: is provided to create a link in the storage system directory
286 hierarchy to some other directory entry in the hierarchy. For a
287 definition of links see "Glossary of Multics Terms" in the Reference
288 Manual.
289
290
291 Syntax:
292 declare hcs_$append_link entry char* char* char* fixed
293 bin35;
294 call hcs_$append_link dir_name entryname path code;
295
296
297 Arguments:
298 dir_name
299 is the pathname of the containing directory. Input
300 entryname
301 is the entryname of the link. Input
302 path
303 is the pathname of the directory entry to which the entryname
304 argument points. Input The pathname may be a maximum of 168
305 characters.
306 code
307 is a storage system status code. Output
308
309
310 Access required:
311 Append permission is required in the directory in which the link is
312 being created.
313
314
315 Notes: The entry pointed to by the link need not exist at the time the
316 link is created.
317
318 The hcs_$append_branch and hcs_$append_branchx entry points can be used
319 to create a segment or directory entry in the storage system hierarchy.
320
321
322 :Entry: change_bc: 1983-04-05 hcs_$change_bc
323
324
325 Function: provides an indivisible method of changing the
326 bitcount of a segment. It is an indivisible operation in that only one
327 process can perform it at a time; thus, if several processes try to
328 change the bitcount, each one will get a different output. This can be
329 used when several processes must write into a segment; if they use the
330 change_bc entrypoint to determine where to write, they will never
331 overwrite each others data, and they will also never have to explicitly
332 manipulate locks.
333
334
335 Syntax:
336 declare hcs_$change_bc entry char* char* fixed bin 24 fixed
337 bin24 fixed bin24 fixed bin 35;
338 call hcs_$change_bc dir_name entryname change old_bc new_bc
339 code;
340
341
342 Arguments:
343 dir_name
344 is the pathname of the directory containing the segment. Input
345 entryname
346 is the entryname of the segment. Input
347 change
348 is the amount by which the bitcount will be changed. Input
349 old_bc
350 is the bitcount before the change was applied. Output
351 new_bc
352 is the bitcount after the change was applied. Output
353 code
354 is a storage system status code. Output
355
356
357 Notes:
358 The user must have write access to the segment, but need not have
359 modify permission on the containing directory.
360
361 The hcs_$change_bc_seg entrypoint performs the same function, but it
362 takes a pointer to the segment rather than the pathname.
363
364
365 :Entry: change_bc_seg: 1983-04-05 hcs_$change_bc_seg
366
367
368 Function: provides an indivisible method of changing the
369 bitcount of a segment. It is an indivisible operation in that only one
370 process can perform it at a time; thus,, if several processes try to
371 change the bitcount, each one will get a different output. This can be
372 used when several processes must write into a segment; if they use the
373 change_bc_seg entrypoint to determine where to write, they will never
374 overwrite each others data, and they will also never have to explicitly
375 manipulate locks.
376
377
378 Syntax:
379 declare hcs_$change_bc_seg entry pointer fixed bin24
380 fixed bin24 fixed bin24 fixed bin 35;
381 call hcs_$change_bc_seg seg_ptr change old_bc new_bc code;
382
383
384 Arguments:
385 seg_ptr
386 is a pointer to the segment whose bitcount is to be changed.
387 Input
388 change
389 is the amount by which the bitcount will be changed. Input
390 old_bc
391 is the bitcount before the change was applied. Output
392 new_bc
393 is the bitcount after the change was applied. Output
394 code
395 is a storage system status code. Output
396
397
398 Notes:
399 The user must have write access to the segment, but need not have
400 modify permission on the containing directory.
401
402 The hcs_$change_bc entrypoint performs the same function, but it takes
403 the pathname of the segment rather than a pointer to it.
404
405
406 :Entry: chname_file: 1982-03-08 hcs_$chname_file
407
408
409 Function: changes the entryname on a specified storage system entry.
410 If an already existing name an old name is specified, it is deleted
411 from the entry; if a new name is specified, it is added. Thus, if
412 only an old name is specified, the effect is to delete a name; if only
413 a new name is specified, the effect is to add a name; and if both are
414 specified, the effect is to rename the entry.
415
416
417 Syntax:
418 declare hcs_$chname_file entry char* char* char* char*
419 fixed bin35;
420 call hcs_$chname_file dir_name entryname oldname newname code;
421
422
423 Arguments:
424 dir_name
425 is the pathname of the containing directory. Input
426 entryname
427 is the entryname of the segment, directory, multisegment file, or
428 link. Input
429 oldname
430 is the name to be deleted from the entry. Input It can be a null
431 character string "" in which case no name is deleted. If oldname
432 is null, then newname must not be null.
433 newname
434 is the name to be added to the entry. Input It must not already
435 exist in the directory on this or another entry. It can be a null
436 character string "" in which case no name is added. If it is
437 null, then oldname must not be the only name on the entry.
438
439
440 code
441 is a storage system status code. Output It can have the values:
442 error_table_$nonamerr
443 attempting to delete the only name of a directory entry
444 error_table_$namedup
445 attempting to add a name that exists on another entry
446 error_table_$segnamedup
447 attempting to add a name that already exists on this entry
448
449
450 Access required:
451 The user must have modify permission on the directory containing the
452 entry whose name is to be changed.
453
454
455 Notes: The hcs_$chname_seg entry point performs a similar function
456 using a pointer to a segment instead of its pathname.
457
458
459 :Entry: chname_seg: 1982-03-08 hcs_$chname_seg
460
461
462 Function: changes an entryname on a segment, if a pointer to the
463 segment is given. If an already existing name an old name is
464 specified, it is deleted from the entry; if a new name is specified,
465 it is added. Thus, if only an old name is specified, the effect is to
466 delete a name; if only a new name is specified, the effect is to add a
467 name; and if both are specified, the effect is to rename the entry.
468
469
470 Syntax:
471 declare hcs_$chname_seg entry ptr char* char* fixed bin35;
472 call hcs_$chname_seg seg_ptr oldname newname code;
473
474
475 Arguments:
476 seg_ptr
477 is a pointer to the segment whose name is to be changed. Input
478 oldname
479 is the name to be deleted from the entry. Input It can be a null
480 character string "" in which case no name is to be deleted. If
481 oldname is null, then newname must not be null.
482 newname
483 is the name to be added to the entry. Input It must not already
484 exist in the directory on this or another entry. It can be a null
485 character string "" in which case no name is added. If it is
486 null, then oldname must not be the only name on the entry.
487
488
489 code
490 is a storage system status code. Output It can have the values:
491 error_table_$nonamerr
492 attempting to delete the only name of a directory entry
493 error_table_$namedup
494 attempting to add a name that exists on another entry
495 error_table_$segnamedup
496 attempting to add a name that already exists on this entry
497
498
499 Access required:
500 The user must have modify permission on the directory containing the
501 segment whose name is to be changed.
502
503
504 Notes: The hcs_$chname_file entry point performs the same function if
505 the pathname of the segment is given instead of a pointer.
506
507
508 :Entry: create_branch_: 1985-03-06 hcs_$create_branch_
509
510
511 Function:
512 This entry point creates either a subdirectory or a segment in the
513 specified directory. This entry point is an extended and more general
514 form of the hcs_$append_branchx entry point. If a subdirectory is
515 created, then the access control list ACL of the subdirectory is
516 initiated by copying the initial ACL for directories that is stored in
517 the specified directory; otherwise, the ACL of the segment is initiated
518 by copying the initial ACL for segments. The access_name and mode
519 items from the create_branch_info structure see "Notes" below are
520 then added to the ACL of the created subdirectory or segment.
521
522
523 Syntax:
524 declare hcs_$create_branch_ entry char* char* ptr
525 fixed bin35;
526 call hcs_$create_branch_ dir_name entryname info_ptr code;
527
528
529 Arguments:
530 dir_name
531 is the pathname of the containing directory. Input
532 entryname
533 is the entryname of the segment or subdirectory to be created.
534 Input
535 info_ptr
536 is a pointer to the information structure described below. Input
537 code
538 is a storage system status code. Output
539
540
541 Notes: The user must have append permission on the containing
542 directory to add an entry to that directory.
543
544 The info_ptr pointer points to the create_branch_info structure
545 found in the include file create_branch_info.incl.pl1.
546
547
548 :Entry: del_dir_tree: 1982-03-08 hcs_$del_dir_tree
549
550
551 Function: given the pathname of a containing directory and the
552 entryname of a subdirectory, deletes the contents of the subdirectory
553 from the storage system hierarchy. All segments, links, and
554 directories inferior to that subdirectory are deleted, including the
555 contents of any inferior directories. The subdirectory is not itself
556 deleted. For information on the deletion of directories, see the
557 description of the hcs_$delentry_file entry point.
558
559
560 Syntax:
561 declare hcs_$del_dir_tree entry char* char* fixed bin35;
562 call hcs_$del_dir_tree dir_name entryname code;
563
564
565 Arguments:
566 dir_name
567 is the pathname of the containing directory. Input
568 entryname
569 is the entryname of the directory. Input
570 code
571 is a storage system status code. Output
572
573
574 Access required:
575 The user must have status and modify permission on the subdirectory
576 and the safety switch must be off in that directory. If the user does
577 not have status and modify permission on inferior directories, access
578 is automatically set and processing continues.
579
580
581 Notes: If an entry in an inferior directory gives the user access only
582 in a ring lower than his validation level, that entry is not deleted
583 and no further processing is done on the subtree. For information
584 about rings, see "Intraprocess Access Control" in the Reference Manual.
585
586
587 :Entry: delentry_file: 1982-03-08 hcs_$delentry_file
588
589
590 Function: given a directory name and an entryname, deletes the given
591 entry from its containing directory. This entry may be a segment, a
592 directory, or a link. If the entry is a segment, the contents of the
593 segment are truncated first. If the entry specifies a directory that
594 contains entries, the code error_table_$fulldir is returned and
595 hcs_$del_dir_tree must be called to remove the contents of the
596 directory. Generally, programmers should use the delete_ subroutine
597 rather than this entry point in order to ensure that their address
598 space is properly cleaned up.
599
600
601 Syntax:
602 declare hcs_$delentry_file entry char* char* fixed bin35;
603 call hcs_$delentry_file dir_name entryname code;
604
605
606 Arguments:
607 dir_name
608 is the pathname of the containing directory. Input
609 entryname
610 is the entryname of the segment, directory, or link. Input
611 code
612 is a storage system status code. Output
613
614
615 Access required:
616 The user must have modify permission on the containing directory. If
617 the entryname argument specifies a segment or directory but not a
618 link, the safety switch of the entry must be off.
619
620
621 Notes: The hcs_$delentry_seg entry point performs the same function on
622 a segment, given a pointer to the segment instead of the pathname.
623
624
625 :Entry: delentry_seg: 1982-03-08 hcs_$delentry_seg
626
627
628 Function: given a pointer to a segment, deletes the corresponding
629 entry from its containing directory. The contents of the segment are
630 truncated first. Generally, programmers should use the delete_
631 subroutine rather than this entry point in order to ensure that their
632 address space is properly cleaned up.
633
634
635 Syntax:
636 declare hcs_$delentry_seg entry ptr fixed bin35;
637 call hcs_$delentry_seg seg_ptr code;
638
639
640 Arguments:
641 seg_ptr
642 is the pointer to the segment to be deleted. Input
643 code
644 is a storage system status code. Output
645
646
647 Access required:
648 The user must have modify permission on the containing directory. The
649 safety switch of the segment must be off.
650
651
652 Notes: The hcs_$delentry_file entry point performs the same function,
653 given the pathname of the segment instead of the pointer.
654
655
656 :Entry: delete_acl_entries: 1982-03-08 hcs_$delete_acl_entries
657
658
659 Function: deletes specified entries from an access control list ACL
660 for a segment.
661
662
663 Syntax:
664 declare hcs_$delete_acl_entries entry char* char* ptr
665 fixed bin fixed bin35;
666 call hcs_$delete_acl_entries dir_name entryname acl_ptr acl_count
667 code;
668
669
670 Arguments:
671 dir_name
672 is the pathname of the containing directory. Input
673 entryname
674 is the entryname of the segment. Input
675 acl_ptr
676 points to a user-filled delete_acl structure see "Notes" below.
677 Input
678 acl_count
679 is the number of ACL entries in the delete_acl structure see
680 "Notes" below. Input
681 code
682 is a storage system status code. Output
683
684
685 Notes: The delete_acl structure is declared as follows.
686
687 dcl 1 delete_acl acl_count aligned based acl_ptr,
688 2 access_name char32,
689 2 status_code fixed bin35;
690
691 access_name
692 is the access name in the form of Person_id.Project_id.tag that
693 identifies the ACL entry to be deleted.
694 status_code
695 is a storage system status code for this ACL entry only.
696
697
698 If an access name cannot be matched to a name already on the ACL of the
699 segment, then the status_code for that ACL entry in the delete_acl
700 structure is set to error_table_$user_not_found. Processing continues
701 to the end of the delete_acl structure and code is returned as 0.
702
703
704 :Entry: delete_dir_acl_entries: 1982-03-08 hcs_$delete_dir_acl_entries
705
706
707 Function: is used to delete specified entries from an access control
708 list ACL for a directory.
709
710
711 Syntax:
712 declare hcs_$delete_dir_acl_entries entry char* char* ptr
713 fixed bin fixed bin35;
714 call hcs_$delete_dir_acl_entries dir_name entryname acl_ptr
715 acl_count code;
716
717
718 Arguments:
719 dir_name
720 is the pathname of the containing directory. Input
721 entryname
722 is the entryname of the directory. Input
723 acl_ptr
724 points to a user-filled delete_acl structure described in the
725 hcs_$delete_acl_entries entry point. Input
726 acl_count
727 is the number of ACL entries in the delete_acl structure. Input
728 code
729 is a storage system status code see "Notes" below. Output
730
731
732 Notes: If code is returned as error_table_$argerr, then the erroneous
733 ACL entries in the delete_acl structure have status_code set to an
734 appropriate error code. No processing is performed.
735
736 If an access name cannot be matched to a name already on the ACL of the
737 segment, then the status_code for that ACL entry in the delete_acl
738 structure is set to error_table_$user_not_found. Processing continues
739 to the end of the delete_acl structure and code is returned as 0.
740
741
742 :Entry: delete_dir_inacl_entries:
743 1982-03-08 hcs_$delete_dir_inacl_entries
744
745
746 Function: is used to delete specified entries from an initial access
747 control list initial ACL for new directories created for the
748 specified ring within the specified directory.
749
750
751 Syntax:
752 declare hcs_$delete_dir_inacl_entries entry char* char* ptr
753 fixed bin fixed bin3 fixed bin35;
754 call hcs_$delete_dir_inacl_entries dir_name entryname acl_ptr
755 acl_count ring code;
756
757
758 Arguments:
759 dir_name
760 is the pathname of the containing directory. Input
761 entryname
762 is the entryname of the directory. Input
763 acl_ptr
764 points to the user-filled delete_acl structure as described in the
765 hcs_$delete_acl_entries entry point. Input
766 acl_count
767 is the number of initial ACL entries in the delete_acl structure.
768 Input
769 ring
770 is the ring number of the initial ACL. Input
771 code
772 is a storage system status code. Output
773
774
775 Notes: If code is returned as error_table_$argerr, then the erroneous
776 initial ACL entries in the delete_acl structure have status_code set to
777 an appropriate error code. No processing is performed in this
778 instance.
779
780 If an access_name in the delete_acl structure cannot be matched to one
781 existing on the initial ACL, then the status_code of that initial ACL
782 entry in the delete_acl structure is set to
783 error_table_$user_not_found. Processing continues to the end of the
784 delete_acl structure and code is returned as 0.
785
786
787 :Entry: delete_inacl_entries: 1982-03-08 hcs_$delete_inacl_entries
788
789
790 Function: deletes specified entries from an initial access control
791 list initial ACL for new segments created for the specified ring
792 within the specified directory.
793
794
795 Syntax:
796 declare hcs_$delete_inacl_entries entry char* char* ptr
797 fixed bin fixed bin3 fixed bin35;
798 call hcs_$delete_inacl_entries dir_name entryname acl_ptr
799 acl_count ring code;
800
801
802 Arguments:
803 dir_name
804 is the pathname of the containing directory. Input
805 entryname
806 is the entryname of the directory. Input
807 acl_ptr
808 points to the user-filled delete_acl structure as described in the
809 hcs_$delete_acl_entries entry point. Input
810 acl_count
811 contains the number of initial ACL entries in the delete_acl
812 structure. Input
813 ring
814 is the ring number of the initial ACL. Input
815 code
816 is a storage system status code. Output
817
818
819 Notes: If code is returned as error_table_$argerr, then the erroneous
820 initial ACL entries in the delete_acl structure have status_code set
821 to an appropriate error code. No processing is performed in this
822 instance.
823
824 If an access_name in the delete_acl structure cannot be matched to one
825 existing on the initial ACL, then the status_code of that initial ACL
826 entry in the delete_acl structure is set to
827 error_table_$user_not_found. Processing continues to the end of the
828 delete_acl structure and code is returned as 0.
829
830
831 :Entry: force_write: 1982-03-08 hcs_$force_write
832
833
834 Function: causes the supervisor to force modified pages out of main
835 memory.
836
837
838 Syntax:
839 declare hcs_$force_write entry ptr bit36 fixed bin35;
840 call hcs_$force_write segp flags code;
841
842
843 Arguments:
844 segp
845 is a pointer to the segment whose modified pages are to be written.
846 Input
847 flags
848 specify a set of options. Input Currently only one option is
849 defined. The force_write_flags structure defined in
850 force_write_flags.incl.pl1 defines the options.
851 code
852 is a standard status code. Output See "Notes" below.
853
854
855 Notes: Use of this entry point may introduce substantial real time
856 delay into execution since the caller must wait for the movement of
857 the disk; other usage of the system meanwhile may cause further
858 delay.
859
860
861 This entry point protects data against an unrecoverable main memory
862 crash. On systems with bulk store paging devices this subroutine may
863 flush pages to the bulk store which is recoverable in case of main
864 memory crashes rather than to the disk. This entry point returns the
865 following non-zero status codes. If the segment is an inner ring
866 segment error_table_$bad_ring_brackets is returned. If the user does
867 not have write access to the segment error_table_$moderr is returned.
868 If the segment is not known not active or a hardcore segment then
869 error_table_$invalidsegno is returned. Because the user has no control
870 over whether or not the segment is active error_table_$invalidsegno
871 should not be treated as an error.
872
873
874 :Entry: fs_get_mode: 1982-03-08 hcs_$fs_get_mode
875
876
877 Function: returns the access mode of the user on a specified segment
878 at the current validation level. For a discussion of access modes
879 see "Access Control" in the Reference Manual.
880
881
882 Syntax:
883 declare hcs_$fs_get_mode entry ptr fixed bin5 fixed bin35;
884 call hcs_$fs_get_mode seg_ptr mode code;
885
886
887 Arguments:
888 seg_ptr
889 is a pointer to the segment whose access mode is to be returned.
890 Input
891 mode
892 is the access mode returned. See the description of the
893 hcs_$append_branchx entry point for the values of the mode
894 argument. Output
895 code
896 is a storage system status code. Output
897
898
899 Notes: The mode and ring brackets for the segment in the user's
900 address space are used in combination with the user's current
901 validation level to determine the mode the user would have if he
902 accessed this segment. For a discussion of ring brackets and
903 validation level see "Intraprocess Access Control" in the
904 Reference Manual.
905
906
907 :Entry: fs_get_access_modes: 1983-01-21 hcs_$fs_get_access_modes
908
909
910 Function: returns the access mode and the extended access mode of the
911 user on a specified segment at the current validation level. For a
912 discussion of access modes see "Access Control" in the Reference
913 Manual.
914
915
916 Syntax:
917 declare hcs_$fs_get_access_modes entry ptr bit 36 aligned
918 bit 36 aligned fixed bin 35;
919 call hcs_$fs_get_access_modes seg_ptr modes ex_modes code;
920
921
922 Arguments:
923 seg_ptr
924 is a pointer to the segment whose access mode is to be returned.
925 Input
926 modes
927 is the returned access mode. See the description of the
928 hcs_$append_branchx entry point for the values of the mode
929 argument. Output
930 ex_modes
931 is the returned extended access mode. Output
932 code
933 is a storage system status code. Output
934
935
936 Notes: The mode and ring brackets for the segment in the user's
937 address space are used in combination with the user's current
938 validation level to determine the mode the user would have if he
939 accessed this segment. For a discussion of ring brackets and
940 validation level see "Intraprocess Access Control" in the
941 Reference Manual.
942
943
944 :Entry: fs_get_path_name: 1982-03-08 hcs_$fs_get_path_name
945
946
947 Function: given a pointer to a segment returns a pathname for the
948 segment with the directory and entryname portions of the pathname
949 separated. The entryname returned is the primary name on the entry.
950
951
952 Syntax:
953 declare hcs_$fs_get_path_name entry ptr char* fixed bin char*
954 fixed bin35;
955 call hcs_$fs_get_path_name seg_ptr dir_name ldn entryname code;
956
957
958 Arguments:
959 seg_ptr
960 is a pointer to the segment. Input
961 dir_name
962 is the pathname of the containing directory. Output The
963 length of dir_name should be 168 characters.
964 ldn
965 is the number of nonblank characters in dir_name. Output
966 entryname
967 is the primary entryname of the segment. Output The length
968 of entryname should be 32 characters.
969 code
970 is a storage system status code. Output
971
972
973 :Entry: fs_get_ref_name: 1982-03-08 hcs_$fs_get_ref_name
974
975
976 Function: returns a specified i.e. first second etc. reference
977 name for a specified segment. See "Constructing and Interpreting
978 Names" in the Reference Manual.
979
980
981 Syntax:
982 declare hcs_$fs_get_ref_name entry ptr fixed bin char*
983 fixed bin35;
984 call hcs_$fs_get_ref_name seg_ptr count ref_name code;
985
986
987 Arguments:
988 seg_ptr
989 is a pointer to the segment whose reference name is sought. Input
990 count
991 specifies which reference name is to be returned where 1 is the
992 name by which the segment has most recently been made known 2 is
993 the next most recent name etc. Input
994 ref_name
995 is the desired reference name. Output
996 code
997 is a storage system status code. Output
998
999
1000 Notes: If the count argument is larger than the total number of names
1001 the name which the segment was originally made known is returned and
1002 code is set to error_table_$refname_count_too_big.
1003
1004
1005 :Entry: fs_get_seg_ptr: 1982-03-08 hcs_$fs_get_seg_ptr
1006
1007
1008 Function: given a reference name of a segment returns a pointer to
1009 the base of the segment. For a discussion of reference names see
1010 "Constructing and Interpreting Names" in the Reference Manual.
1011
1012
1013 Syntax:
1014 declare hcs_$fs_get_seg_ptr entry char* ptr fixed bin35;
1015 call hcs_$fs_get_seg_ptr ref_name seg_ptr code;
1016
1017
1018 Arguments:
1019 ref_name
1020 is the reference name of a segment for which a pointer is to be
1021 returned. Input
1022 seg_ptr
1023 is a pointer to the base of the segment. Output
1024 code
1025 is a storage system status code. Output
1026
1027
1028 Notes: If the reference name is accessible from the user's current
1029 validation level seg_ptr is returned pointing to the segment;
1030 otherwise it is null. For more information on rings and validation
1031 levels refer to "Intraprocess Access Control" in the Reference Manual.
1032
1033
1034 :Entry: fs_move_file: 1982-03-08 hcs_$fs_move_file
1035
1036
1037 Function: moves the data associated with one segment in the storage
1038 system hierarchy to another segment given the pathnames of the
1039 segments in question. The old segment remains but with a zero
1040 length.
1041
1042
1043 Syntax:
1044 declare hcs_$fs_move_file entry char* char* fixed bin2
1045 char* char* fixed bin35;
1046 call hcs_$fs_move_file from_dir from_entry at_sw to_dir to_entry
1047 code;
1048
1049
1050 Arguments:
1051 from_dir
1052 is the pathname of the directory in which from_entry resides.
1053 Input
1054 from_entry
1055 is the entryname of the segment from which data is to be moved.
1056 Input
1057
1058
1059 at_sw
1060 is a 2-bit append/truncate switch. Input
1061 append first bit:
1062 0 if to_entry does not exist the code error_table_$noentry is
1063 returned.
1064 1 if to_entry does not exist it is created.
1065 truncate second bit:
1066 0 if to_entry is not a zero-length segment the code
1067 error_table_$clnzero is returned.
1068 1 if to_entry is not a zero-length segment it is truncated
1069 before moving.
1070
1071
1072 to_dir
1073 is the pathname of the directory in which to_entry resides. Input
1074 to_entry
1075 is the entryname of the segment to which data is to be moved.
1076 Input
1077 code
1078 is a storage system status code. Output See "Notes" below.
1079
1080
1081 Notes: The hcs_$fs_move_seg entry point performs the same function
1082 given pointers to the segments in question instead of pathnames.
1083
1084 The code error_table_$no_move is returned if--
1085 1. Either to_entry or from_entry is not a segment.
1086 2. The user does not have rw access to to_entry.
1087 3. The user does not have read access to from_entry.
1088 4. The max_length of to_entry is less than the length of
1089 from_entry.
1090 5. There is not enough quota in to_dir to perform the move.
1091
1092
1093 :Entry: fs_move_seg: 1982-03-08 hcs_$fs_move_seg
1094
1095
1096 Function: moves the data associated with one segment in the hierarchy
1097 to another segment given pointers to the segments in question. The
1098 old segment remains but with a zero length.
1099
1100
1101 Syntax:
1102 declare hcs_$fs_move_seg entry ptr ptr fixed bin1 fixed bin35;
1103 call hcs_$fs_move_seg from_ptr to_ptr trun_sw code;
1104
1105
1106 Arguments:
1107 from_ptr
1108 is a pointer to the segment from which data is to be moved. Input
1109 to_ptr
1110 is a pointer to the target segment. Input
1111 trun_sw
1112 indicates whether the segment specified by to_ptr is to be truncated
1113 if it is not already zero length before performing the move.
1114 Input
1115 0 returns code error_table_$clnzero if the segment is not already
1116 zero length
1117 1 truncates the segment before moving
1118 code
1119 is a storage system status code. Output It can have the value
1120 error_table_$no_move or error_table_$clnzero.
1121
1122
1123 Notes: The hcs_$fs_move_file entry point performs the same function
1124 given the pathnames of the segments instead of the pointers.
1125
1126
1127 :Entry: get_access_class_seg: 1982-03-08 hcs_$get_access_class_seg
1128
1129
1130 Function: given a pointer returns the access class of that pointer's
1131 corresponding segment. For information on access classes see
1132 "Nondiscretionary Access Control" in the Reference Manual.
1133
1134
1135 Syntax:
1136 declare hcs_$get_access_class_seg entry ptr bit72 aligned
1137 fixed bin35;
1138 call hcs_$get_access_class_seg seg_ptr access_class code;
1139
1140
1141 Arguments:
1142 seg_ptr
1143 is the pointer to the segment. Input
1144 access_class
1145 is the access class of the segment. Output
1146 code
1147 is a storage system status code. Output
1148
1149
1150 :Entry: get_access_class: 1982-03-08 hcs_$get_access_class
1151
1152
1153 Function: returns the access class of a segment or directory in the
1154 storage hierarchy. For information on access classes see
1155 "Nondiscretionary Access Control" in the Reference Manual.
1156
1157
1158 Syntax:
1159 declare hcs_$get_access_class entry char* char* bit72 aligned
1160 fixed bin35;
1161 call hcs_$get_access_class dir_name entryname access_class code;
1162
1163
1164 Arguments:
1165 dir_name
1166 is the pathname of the containing directory. Input
1167 entryname
1168 is the entryname of the segment or directory. Input
1169 access_class
1170 is the access class of the segment or directory. Output
1171 code
1172 is a storage system status code. Output
1173
1174
1175 Access required:
1176 The user must have status permission on the directory the dir_name
1177 argument or nonnull access to the entry the entryname argument.
1178
1179
1180 Notes: If the value of entryname is null dir_name is assumed to be a
1181 full pathname.
1182
1183
1184 :Entry: get_author: 1982-03-08 hcs_$get_author
1185
1186
1187 Function: returns the author of a segment directory multisegment
1188 file or link.
1189
1190
1191 Syntax:
1192 declare hcs_$get_author entry char* char* fixed bin1 char*
1193 fixed bin35;
1194 call hcs_$get_author dir_name entryname chase author code;
1195
1196
1197 Arguments:
1198 dir_name
1199 is the pathname of the containing directory. Input
1200 entryname
1201 is the entryname of the segment directory multisegment file or
1202 link. Input
1203 chase
1204 if entryname refers to a link this flag indicates whether to return
1205 the author of the link or the author of the segment directory or
1206 multisegment file to which the link points. Input
1207 0 return link author
1208 1 return segment directory or multisegment file author
1209
1210
1211 author
1212 is the author of the segment directory multisegment file or link
1213 in the form of Person_id.Project_id.tag with a maximum length of 32
1214 characters. Output An error is not detected if the string
1215 author is too short to hold the author.
1216 code
1217 is a storage system status code. Output
1218
1219
1220 Access required:
1221 The user must have status permission on the containing directory.
1222
1223
1224 :Entry: get_bc_author: 1982-03-08 hcs_$get_bc_author
1225
1226
1227 Function: returns the bit count author of a segment or directory. The
1228 bit count author is the name of the user who last set the bit count of
1229 the segment or directory.
1230
1231
1232 Syntax:
1233 declare hcs_$get_bc_author entry char* char* char*
1234 fixed bin35;
1235 call hcs_$get_bc_author dir_name entryname bc_author code;
1236
1237
1238 Arguments:
1239 dir_name
1240 is the pathname of the containing directory. Input
1241 entryname
1242 is the entryname of the segment or directory. Input
1243 bc_author
1244 is the bit count author of the segment or directory in the form of
1245 Person_id.Project_id.tag with a maximum length of 32 characters.
1246 Output An error is not detected if the string bc_author is too
1247 short to hold the bit count author.
1248 code
1249 is a storage system status code. Output
1250
1251
1252 Access required:
1253 The user must have status permission on the containing directory.
1254
1255
1256 :Entry: get_dir_ring_brackets: 1982-03-08 hcs_$get_dir_ring_brackets
1257
1258
1259 Function: given the pathname of a containing directory and the
1260 entryname of a subdirectory returns the value of that subdirectory's
1261 ring brackets. Ring brackets are discussed in "Intraprocess Access
1262 Control" in the Reference Manual.
1263
1264
1265 Syntax:
1266 declare hcs_$get_dir_ring_brackets entry char* char*
1267 2 fixed bin3 fixed bin35;
1268 call hcs_$get_dir_ring_brackets dir_name entryname drb code;
1269
1270
1271 Arguments:
1272 dir_name
1273 is the pathname of the containing directory. Input
1274 entryname
1275 is the entryname of the subdirectory. Input
1276 drb
1277 is a two-element array that contains the directory's ring brackets.
1278 Output The first element contains the level required for modify
1279 and append permission; the second element contains the level
1280 required for status permission.
1281 code
1282 is a storage system status code. Output
1283
1284
1285 Access required:
1286 The user must have status permission on the containing directory.
1287
1288
1289 :Entry: get_exponent_control: 1982-03-08 hcs_$get_exponent_control
1290
1291
1292 Function: returns the current settings of the flags that control the
1293 system's handling of exponent overflow and underflow conditions. For
1294 more information on exponent control see the description of
1295 hcs_$set_exponent_control.
1296
1297
1298 Syntax:
1299 declare hcs_$get_exponent_control entry bit1 aligned bit1
1300 aligned float bin63;
1301 call hcs_$get_exponent_control restart_underflow restart_overflow
1302 overflow_value;
1303
1304
1305 Arguments:
1306 restart_underflow
1307 is "1"b if underflows are currently being automatically restarted
1308 and "0"b otherwise. Output
1309 restart_overflow
1310 is "1"b if overflows are currently being automatically restarted
1311 and "0"b otherwise. Output
1312 overflow_value
1313 is the value used for the result of the computation in the case of
1314 overflow. Output
1315
1316
1317 :Entry: get_ips_mask: 1982-03-08 hcs_$get_ips_mask
1318
1319
1320 Function: returns the value of the current ips mask.
1321
1322
1323 Syntax:
1324 declare hcs_$get_ips_mask entry bit36 aligned;
1325 call hcs_$get_ips_mask old_mask;
1326
1327
1328 Arguments:
1329 old_mask
1330 is the current value of the ips mask. Output
1331
1332
1333 Notes: A "1"b in any position in the mask means that the corresponding
1334 ips interrupt is enabled.
1335
1336 The thirty-sixth rightmost bit of old_mask does not correspond to an
1337 interrupt but is used as a control bit giving a positive indication
1338 that a particular masking or unmasking operation has taken place. No
1339 ips interrupts can occur in the time interval between the requested
1340 mask modification and the returning of the old_mask with the control
1341 bit set appropriately.
1342
1343
1344 Entry points used at the beginning of a critical section of code to
1345 disable some or all ips interrupts return a value of "1"b for the
1346 control bit while those that are used at the end of a critical section
1347 of code to re-enable those interrupts return a value of "0"b for the
1348 control bit. Thus a condition handler can interpret a value of "1"b
1349 in the control bit as meaning that execution was in a critical section
1350 of code and the ips mask has been modified. See "Notes" in the
1351 description of the hcs_$set_automatic_ips_mask entry point for
1352 information about the state of the ips mask immediately after an ips
1353 interrupt occurs.
1354
1355 The control bit in the mask returned by this entry point is always
1356 "0"b.
1357
1358
1359 :Entry: get_link_target: 1985-03-06 hcs_$get_link_target
1360
1361
1362 Function:
1363 This entry point returns the pathname of the ultimate target of a link
1364 if the ultimate target exists or what that pathname would be if the
1365 target did exist.
1366
1367
1368 Syntax:
1369 declare hcs_$get_link_target entry char* char* char* char*
1370 fixed bin35;
1371 call hcs_$get_link_target dir_name entryname link_dir_name
1372 link_entryname code;
1373
1374
1375 Arguments:
1376 dir_name
1377 is the directory name containing the link. Input
1378 entryname
1379 is the entryname of the link for which target information is
1380 desired. Input
1381 link_dir_name
1382 is the directory name of the link target with a maximum length of
1383 168 characters. Output
1384 link_entryname
1385 is the entryname of the link target with a maximum length of 32
1386 characters. Output
1387 code
1388 is a standard status code. Output
1389
1390
1391 Notes:
1392 This entry chases the link to its ultimate target. The
1393 ultimate target of a link must be a directory or segment which may or
1394 may not exist. If the immediate target of a link is another link the
1395 chasing of links continues toward the ultimate target directory or
1396 segment until it is encountered or found to be nonexistent. If the
1397 ultimate target of the link exists the user must either have nonnull
1398 permission on the directory containing the target or nonnull access to
1399 the target itself in order to determine its pathname. If appropriate
1400 access exists the code is zero and link_dir_name and link_entryname
1401 are set. If not an error code is returned and the link_dir_name and
1402 link_entryname are returned as blank.
1403
1404
1405 If the ultimate target does not exist the target pathname of the last
1406 link encountered while chasing links will be returned if the user has
1407 nonnull permission on the directory that would have contained that
1408 target pathname. In this case the returned code is
1409 error_table_$noentry and the link_dir_name and link_entryname are set.
1410
1411 In all other cases an error code is returned to indicate the lack of
1412 access and link_dir_name and link_entryname are returned as blanks.
1413
1414
1415 :Entry: get_max_length: 1982-03-08 hcs_$get_max_length
1416
1417
1418 Function: given a directory name and entryname returns the maximum
1419 length in words of the segment.
1420
1421
1422 Syntax:
1423 declare hcs_$get_max_length entry char* char* fixed bin19
1424 fixed bin35;
1425 call hcs_$get_max_length dir_name entryname max_length code;
1426
1427
1428 Arguments:
1429 dir_name
1430 is the pathname of the containing directory. Input
1431 entryname
1432 is the entryname of the segment. Input
1433 max_length
1434 is the maximum length of the segment in words. Output
1435 code
1436 is a storage system status code. Output
1437
1438
1439 Access required:
1440 The user must have status permission on the directory containing the
1441 segment or nonnull access to the segment.
1442
1443
1444 :Entry: get_max_length_seg: 1982-03-08 hcs_$get_max_length_seg
1445
1446
1447 Function: given a pointer to a segment returns the maximum length
1448 in words of the segment.
1449
1450
1451 Syntax:
1452 declare hcs_$get_max_length_seg entry ptr fixed bin19
1453 fixed bin35;
1454 call hcs_$get_max_length_seg seg_ptr max_length code;
1455
1456
1457 Arguments:
1458 seg_ptr
1459 is a pointer to the segment whose maximum length is to be returned.
1460 Input
1461 max_length
1462 is the maximum length of the segment in words. Output
1463 code
1464 is a storage system status code. Output
1465
1466
1467 Access required:
1468 The user must have status permission on the directory containing the
1469 segment or nonnull access to the segment.
1470
1471
1472 :Entry: get_page_trace: 1982-03-08 hcs_$get_page_trace
1473
1474
1475 Function: returns information about recent paging activity.
1476
1477
1478 Syntax:
1479 declare hcs_$get_page_trace entry ptr;
1480 call hcs_$get_page_trace data_ptr;
1481
1482
1483 Arguments:
1484 data_ptr
1485 is a pointer to a user data space where return information is
1486 stored. Input
1487
1488
1489 Notes: The format of the data structure returned by
1490 hcs_$get_page_trace is described below. The amount of data returned
1491 cannot be known in advance other than that there are less than 1024
1492 words returned.
1493
1494
1495 dcl 1 trace aligned basedtp
1496 2 next_available bit18 aligned
1497 2 size bit18 aligned
1498 2 time fixed bin71
1499 2 pad1 fixed bin35
1500 2 index bit17
1501 2 pad2 fixed bin71
1502 512 referdivide trace.size2170
1503 3 info bit36 aligned
1504 3 type bit6 unaligned
1505 3 pageno bit12 unaligned
1506 3 time_delta bit18 unaligned;
1507
1508
1509 Structure elements;
1510 next_available
1511 is a relative pointer relative to the first trace entry to the
1512 next entry to be used in the trace list.
1513 size
1514 is the number of words in the trace array and hence twice the
1515 number of entries in the array.
1516 time
1517 is the real-time clock reading at the time the last trace entry
1518 was entered in the list.
1519 pad1
1520 is unused.
1521
1522
1523 index
1524 is a relative pointer to the first trace entry entered in the
1525 last quantum. Thus all events traced in the last quantum can be
1526 determined by scanning from trace.index to trace.next_available
1527 minus 1 with the obvious check for wrap-around.
1528 pad2
1529 is unused.
1530 info
1531 is information about the particular trace entry.
1532
1533
1534 type
1535 specifies what kind of a trace entry it is. The following types
1536 are currently defined:
1537 0 page fault
1538 2 segment fault begin
1539 3 segment fault end
1540 4 linkage fault begin
1541 5 linkage fault end
1542 6 bound fault begin
1543 7 bound fault end
1544 8 signaller event
1545 9 restarted signal
1546 10 reschedule
1547 11 user marker
1548 12 interrupt
1549
1550
1551 pageno
1552 is the page number associated with the fault. Certain trace
1553 entries do not fill in this field.
1554 time_delta
1555 is the amount of real time elapsed between the time this entry
1556 was entered and the previous entry was entered. The time value
1557 is in units of 64 microseconds.
1558
1559
1560 :Entry: get_process_usage: 1982-03-08 hcs_$get_process_usage
1561
1562
1563 Function: returns information on system resource usage by the
1564 requesting process.
1565
1566
1567 Syntax:
1568 declare hcs_$get_process_usage entry ptr fixed bin 35;
1569 call hcs_$get_process_usage process_usage_pointer code;
1570
1571
1572 Arguments:
1573 process_usage_pointer
1574 is a pointer to the structure declared in
1575 process_usage.incl.pl1 Input
1576 code
1577 is a standard status code. Output
1578
1579
1580 :Entry: get_procs_required: 1987-08-10 hcs_$get_procs_required
1581
1582
1583 Function: returns the per-process CPUs required.
1584
1585
1586 Syntax:
1587 declare hcs_$get_procs_required entry bit 8 aligned
1588 bit 1 aligned fixed bin 35;
1589 call hcs_$get_procs_required procs_required default_sw code;
1590
1591
1592 Arguments:
1593 procs_required
1594 is the set of processors required. Output
1595 default_sw
1596 is "1"b if the set of processors required is the system default
1597 otherwise "0"b. Output
1598 code
1599 is a standard system error code. Output
1600
1601
1602 Access required:
1603 This operation requires rw permission on the access control segment:
1604 >sc1>admin_acs>set_proc_required.acs
1605
1606
1607 :Entry: get_ring_brackets: 1982-03-08 hcs_$get_ring_brackets
1608
1609
1610 Function: given the directory name and entryname of a segment
1611 returns the value of that segment's ring brackets.
1612
1613
1614 Syntax:
1615 declare hcs_$get_ring_brackets entry char* char* 3
1616 fixed bin3 fixed bin35;
1617 call hcs_$get_ring_brackets dir_name entryname rb code;
1618
1619
1620 Arguments:
1621 dir_name
1622 is the pathname of the containing directory. Input
1623 entryname
1624 is the entryname of the segment. Input
1625 rb
1626 is a three-element array that contains the segment's ring brackets.
1627 Output Ring brackets and validation levels are discussed in
1628 "Intraprocess Access Control" in the Reference Manual.
1629 code
1630 is a storage system status code. Output
1631
1632
1633 Access required:
1634 The user must have status permission on the containing directory.
1635
1636
1637 :Entry: get_safety_sw: 1982-03-08 hcs_$get_safety_sw
1638
1639
1640 Function: given a directory name and an entryname returns the value
1641 of the safety switch of a directory or a segment.
1642
1643
1644 Syntax:
1645 declare hcs_$get_safety_sw entry char* char* bit1 fixed
1646 bin35;
1647 call hcs_$get_safety_sw entry dir_name entryname safety_sw code;
1648
1649
1650 Arguments:
1651 dir_name
1652 is the pathname of the containing directory. Input
1653 entryname
1654 is the entryname of the directory or segment. Input
1655 safety_sw
1656 is the value of the safety switch. Output
1657 "0"b the segment or directory can be deleted
1658 "1"b the segment or directory cannot be deleted
1659 code
1660 is a storage system status code. Output
1661
1662
1663 Access required:
1664 The user must have status permission on the containing directory or
1665 nonnull access to the directory or segment.
1666
1667
1668 :Entry: get_safety_sw_seg: 1982-03-08 hcs_$get_safety_sw_seg
1669
1670
1671 Function: given a pointer to the segment returns the value of the
1672 safety switch of a segment.
1673
1674
1675 Syntax:
1676 declare hcs_$get_safety_sw_seg entry ptr bit1 fixed bin35;
1677 call hcs_$get_safety_sw_seg seg_ptr safety_sw code;
1678
1679
1680 Arguments:
1681 seg_ptr
1682 is a pointer to the segment whose safety switch is to be examined.
1683 Input
1684 safety_sw
1685 is the value of the segment safety switch. Output
1686 "0"b the segment can be deleted
1687 "1"b the segment cannot be deleted
1688 code
1689 is a storage system status code. Output
1690
1691
1692 Access required:
1693 The user must have status permission on the directory containing the
1694 segment or must have nonnull access to the segment.
1695
1696
1697 :Entry: get_search_rules: 1982-03-08 hcs_$get_search_rules
1698
1699
1700 Function: returns the search rules currently in use in the caller's
1701 process.
1702
1703
1704 Syntax:
1705 declare hcs_$get_search_rules entry ptr;
1706 call hcs_$get_search_rules search_rules_ptr;
1707
1708
1709 Arguments:
1710 search_rules_ptr
1711 is a pointer to a user-supplied search rules structure. Input
1712 See "Notes" below.
1713
1714
1715 Notes: The structure pointed to by search_rules_ptr is declared as
1716 follows:
1717
1718 dcl 1 search_rules aligned
1719 2 number fixed bin
1720 2 names 21 char168 aligned;
1721
1722 number
1723 is the number of search rules in the array.
1724 names
1725 are the names of the search rules. They can be absolute
1726 pathnames of directories or keywords. See the
1727 hcs_$initiate_search_rules entry point for a detailed description
1728 of the search rules.
1729
1730
1731 :Entry: get_system_search_rules:
1732 1982-03-08 hcs_$get_system_search_rules
1733
1734
1735 Function: provides the user with the values of the site-defined search
1736 rule keywords accepted by hcs_$initiate_search_rules.
1737
1738
1739 Syntax:
1740 declare hcs_$get_system_search_rules entry ptr fixed bin35;
1741 call hcs_$get_system_search_rules search_rules_ptr code;
1742
1743
1744 Arguments:
1745 search_rules_ptr
1746 is a pointer to the structure described in "Notes" below. Input
1747 code
1748 is a storage system status code. Output
1749
1750
1751 Notes: The structure pointed to by search_rules_ptr is declared as
1752 follows:
1753
1754 dcl 1 drules based aligned
1755 2 ntags fixed bin
1756 2 nrules fixed bin
1757 2 tags 10
1758 3 name char32
1759 3 flag bit36
1760 2 rules 50
1761 3 name char168
1762 3 flag bit36;
1763
1764
1765 Structure elements;
1766 ntags
1767 is the number of tags.
1768 nrules
1769 is the number of rules.
1770 tags
1771 is an array of keywords.
1772 tags.name
1773 is the keyword.
1774 tags.flag
1775 is a bit field with one bit on.
1776
1777
1778 rules
1779 is an array of directory names.
1780 rules.name
1781 is the absolute pathname of the directory.
1782 rules.flag
1783 is a bit field with bits on for every tag that selects this
1784 directory.
1785
1786
1787 :Entry: get_uid_file: 1983-03-31 hcs_$get_uid_file
1788
1789
1790 Function: returns the unique identifier of a storage system
1791 entry. If the input arguments refer to a link the uid of the target
1792 will be returned.
1793
1794
1795 Syntax:
1796 declare hcs_$get_uid_file entry char* char* bit36 aligned
1797 fixed bin35;
1798 call hcs_$get_uid_file dir_name entry_name uid code;
1799
1800
1801 Arguments:
1802 dir_name
1803 is the name of the directory containing the entry. Input
1804 entry_name
1805 is the name of the entry whose unique identifier is to be returned.
1806 Input
1807 uid
1808 is the unique identifier of the entry. Output
1809 code
1810 is a standard storage system status code. Output
1811
1812
1813 :Entry: get_uid_seg: 1982-05-17 hcs_$get_uid_seg
1814
1815 Function: Given a pointer to a segment returns the unique identifier
1816 associated with the segment.
1817
1818
1819 Syntax:
1820 declare hcs_$get_uid_seg entry ptr bit36 aligned fixed bin35;
1821 call hcs_$get_uid_seg seg_ptr unique_id code;
1822
1823
1824 Arguments:
1825 seg_ptr
1826 is a pointer to the segment whose unique identifier is to be
1827 determined. Input
1828 unique_id
1829 is the unique identifier associated with the segment. Output
1830 code
1831 is a standard storage system status code. Output
1832
1833
1834 :Entry: get_user_access_modes: 1983-01-21 hcs_$get_user_access_modes
1835
1836
1837 Function: returns the effective access mode and extended access mode of
1838 a user to a branch given the pathname of the branch the name of the
1839 user and the validation level ring number of the user. For a
1840 description of this mode see "Effective Access" in the Reference
1841 Manual.
1842
1843
1844 Syntax:
1845 declare hcs_$get_user_access_modes entry char* char* char*
1846 fixed bin bit 36 aligned bit 36 aligned fixed bin35;
1847 call hcs_$get_user_access_modes dir_name entryname user_id ring
1848 mode ex_mode code;
1849
1850
1851 Arguments:
1852 dir_name
1853 is the directory name of the branch. Input
1854 entryname
1855 is the entry name of the branch. Input
1856 user_id
1857 is the access name of the user in the form
1858 Person_id.Project_id_.tag. Input This is limited to 32
1859 characters. If null the access name of the calling process is
1860 used.
1861
1862
1863 ring
1864 is the validation level that is to be used in computing effective
1865 access. Input It must be a value between 0 and 7 inclusive or
1866 -1. If the ring value is -1 a default value of the validation
1867 level of the calling process is used. This default should be used
1868 in all cases except those in which a different ring's access is
1869 explicitly required.
1870 mode
1871 is the effective access mode of the user to the branch see "Notes"
1872 below. Output
1873 ex_mode
1874 is the extended access mode of the user to the branch. Output
1875 code
1876 is a standard status code. Output
1877
1878
1879 Access required:
1880 The user must have status permission on the containing directory
1881 unless the access name supplied is that of the calling process or
1882 null.
1883
1884
1885 Notes: The include file access_mode_values.incl.pl1 defines mnemonics
1886 for the different values of mode. Extended access modes are defined by
1887 the subsystem owning the branch.
1888
1889
1890 :Entry: get_user_access_modes: 1985-03-05 hcs_$get_user_access_modes
1891
1892
1893 Function:
1894 This entry point returns the effective access mode and extended access
1895 mode of a user to a segment given a pointer to the segment the name
1896 of the user and the validation level ring number of the user.
1897
1898
1899 Syntax:
1900 declare hcs_$get_user_access_modes entry pointer fixed bin
1901 bit 36 aligned bit 36 aligned fixed bin 35;
1902 call hcs_$get_user_access_modes segment_ptr user_id ring mode
1903 ex_mode code;
1904
1905
1906 Arguments:
1907 segment_ptr
1908 is a pointer to the segment for which access will be returned
1909 Input
1910 user_id
1911 is the access name fo the user in the form Person_id.Project_id.tag.
1912 Input This is limited to 32 characters. If null the access name
1913 of the calling process is used.
1914 ring
1915 is the validation level that is to be used in computing effective
1916 access. Input It must be a value between 0 and 7 inclusive or
1917 -1. If the ring value is -1 a default value of the validation
1918 level of the calling process is used. This default should be used
1919 in all cases except those in which a different ring's access is
1920 explicitly required.
1921
1922
1923 mode
1924 is the effective access mode of the user to the branch see "Notes"
1925 below. Output
1926 ex_mode
1927 is the extended access mode of the user to the branch. Output
1928 code
1929 is a standard status code. Output
1930
1931
1932 Access required:
1933 The user must have status permission on the containing directoy unless
1934 the access name supplied is that of the calling process or null.
1935
1936
1937 Notes: The include file access_mode_values.incl.pl1 defines mnemonics
1938 for the different values of mode. Extended access modes are defined by
1939 the subsystem owning the branch.
1940
1941
1942 :Entry: get_user_effmode: 1982-03-08 hcs_$get_user_effmode
1943
1944
1945 Function: returns the effective access mode of a user to a branch
1946 given the pathname of the branch the name of the user and the
1947 validation level ring number of the user. For a description of
1948 this mode see "Effective Access" in the Reference Manual.
1949
1950
1951 Syntax:
1952 declare hcs_$get_user_effmode entry char* char* char*
1953 fixed bin fixed bin5 fixed bin35;
1954 call hcs_$get_user_effmode dir_name entryname user_id ring mode
1955 code;
1956
1957
1958 Arguments:
1959 dir_name
1960 is the directory name of the branch. Input
1961 entryname
1962 is the entry name of the branch. Input
1963 user_id
1964 is the access name of the user in the form
1965 Person_id.Project_id_.tag. Input This is limited to 32
1966 characters. If null the access name of the calling process is
1967 used.
1968
1969
1970 ring
1971 is the validation level that is to be used in computing effective
1972 access. Input It must be a value between 0 and 7 inclusive or
1973 -1. If the ring value is -1 a default value of the validation
1974 level of the calling process is used. This default should be used
1975 in all cases except those in which a different ring's access is
1976 explicitly required.
1977 mode
1978 is the effective access mode of the user to the branch see "Notes"
1979 below. Output
1980 code
1981 is a standard status code. Output
1982
1983
1984 Access required:
1985 The user must have status permission on the containing directory
1986 unless the access name supplied is that of the calling process or
1987 null.
1988
1989
1990 Notes: The mode argument is a fixed binary number where the desired
1991 mode is encoded with one access mode specified by each bit. The modes
1992 for segments are:
1993 read the 8-bit is 1 i.e. 01000b
1994 execute the 4-bit is 1 i.e. 00100b
1995 write the 2-bit is 1 i.e. 00010b
1996 The modes for directories are:
1997 status the 8-bit is 1 i.e. 01000b
1998 modify the 2-bit is 1 i.e. 00010b
1999 append the 1-bit is 1 i.e. 00001b
2000
2001
2002 The unused bits are reserved for unimplemented attributes and must be
2003 0. For example rw access is 01010b in binary form and 10 in decimal
2004 form. The access_mode_values.incl.pl1 include file defines mnemonics
2005 for these values.
2006
2007
2008 :Entry: history_regs_get: 1982-03-08 hcs_$history_regs_get
2009
2010
2011 Function: returns the current state of the per-process history
2012 register switch pds$save_history_regs.
2013
2014
2015 Syntax:
2016 declare hcs_$history_regs_get entry bit 1 aligned;
2017 call hcs_$history_regs_get current_state;
2018
2019
2020 Arguments:
2021 current_state
2022 is the current state of the per-process switch. Output A "1"b
2023 equals on and a "0"b equals off.
2024
2025
2026 :Entry: history_regs_set: 1982-03-08 hcs_$history_regs_set
2027
2028
2029 Function: controls the state of the per-process switch
2030 pds$save_history_regs. If this per-process switch is set on "1"b
2031 then history registers of the processor that a process was executing
2032 on at the time of a signalable fault e.g. illegal_procedure are
2033 stored by the fault module fim and copied into the signallers stack
2034 frame return_to_ring_0_. If the per-process switch is set off and
2035 the per-system switch wired_hardcore_data$global_hregs is off then
2036 the history register block in the signaller stack frame is set to all
2037 zeros.
2038
2039
2040 Syntax:
2041 declare hcs_$history_regs_set entry bit 1 aligned;
2042 call hcs_$history_regs_set desired_state;
2043
2044
2045 Arguments:
2046 desired_state
2047 is the desired state of the per-process switch. Input A "1"b
2048 equals on and a "0"b equals off.
2049
2050
2051 :Entry: initiate: 1982-03-08 hcs_$initiate
2052
2053
2054 Function: given a pathname and a reference name makes known the
2055 segment defined by the pathname initiates the given reference name
2056 and increments the count of initiated reference names for the segment.
2057
2058
2059 Syntax:
2060 declare hcs_$initiate entry char* char* char* fixed bin1
2061 fixed bin2 ptr fixed bin35;
2062 call hcs_$initiate dir_name entryname ref_name seg_sw copy_ctl_sw
2063 seg_ptr code;
2064
2065
2066 Arguments:
2067 dir_name
2068 is the pathname of the containing directory. Input
2069 entryname
2070 is the entryname of the segment. Input
2071 ref_name
2072 is the reference name. Input If it is zero length the segment is
2073 initiated with a null reference name.
2074 seg_sw
2075 is the reserved segment switch. Input
2076 0 if no segment number has been reserved
2077 1 if a segment number was reserved
2078 copy_ctl_sw
2079 is obsolete and should be set to zero. Input
2080
2081
2082 seg_ptr
2083 is a pointer to the segment.
2084 1 if seg_sw is on Input
2085 0 if seg_sw is off Output
2086 code
2087 is a storage system status code. Output
2088
2089
2090 Access required:
2091 The user must have nonnull access on the segment the entryname
2092 argument in order to make it known.
2093
2094
2095 Notes: If a segment is concurrently initiated more than a
2096 system-defined number of times the usage count of the segment is said
2097 to be in an overflowed condition and further initiations do not
2098 affect the usage count. This affects the use of the
2099 hcs_$terminate_noname and hcs_$terminate_name entry points. If the
2100 reserved segment switch is on then the segment pointer is input and
2101 the segment is made known with that segment number. In this case the
2102 user supplies the initial segment number. If the reserved segment
2103 switch is off a segment number is assigned and returned as a pointer.
2104
2105
2106 If entryname cannot be made known a null pointer is returned for
2107 seg_ptr and the returned value of code indicates the reason for
2108 failure. Thus the usual way to test whether the call was successful
2109 is to check the pointer not the code since the code may be nonzero
2110 even if the segment was successfully initiated. If entryname is
2111 already known to the user's process code is returned as
2112 error_table_$segknown and the seg_ptr argument contains a nonnull
2113 pointer to entryname. If ref_name has already been initiated in the
2114 current ring the code is returned as error_table_$namedup. The
2115 seg_ptr argument contains a valid pointer to the segment being
2116 initiated. If entryname is not already known and no problems are
2117 encountered seg_ptr contains a valid pointer and code is 0.
2118
2119
2120 :Entry: initiate_count: 1982-03-08 hcs_$initiate_count
2121
2122
2123 Function: given a pathname and a reference name causes the segment
2124 defined by the pathname to be made known and the given reference name
2125 initiated. A segment number is assigned and returned as a pointer and
2126 the bit count of the segment is returned.
2127
2128
2129 Syntax:
2130 declare hcs_$initiate_count entry char* char* char*
2131 fixed bin24 fixed bin2 ptr fixed bin35;
2132 call hcs_$initiate_count dir_name entryname ref_name bit_count
2133 copy_ctl_sw seg_ptr code;
2134
2135
2136 Arguments:
2137 dir_name
2138 is the pathname of the containing directory. Input
2139 entryname
2140 is the entryname of the segment. Input
2141 ref_name
2142 is the reference name. Input If it is zero length the segment is
2143 initiated with a null reference name.
2144 bit_count
2145 is the bit count of the segment. Output
2146 copy_ctl_sw
2147 is obsolete and should be set to zero. Input
2148
2149
2150 seg_ptr
2151 is a pointer to the segment. Output
2152 code
2153 is a storage system status code. Output
2154
2155
2156 Notes: The user must have nonnull access on the segment the entryname
2157 argument in order to make it known.
2158
2159
2160 If entryname cannot be made known a null pointer is returned for
2161 seg_ptr and the returned value of code indicates the reason for
2162 failure. Thus the usual way to test whether the call was successful
2163 is to check the pointer not the code since the code may be nonzero
2164 even if the segment was successfully initiated. If entryname is
2165 already known to the user's process code is returned as
2166 error_table_$segknown and the seg_ptr argument contains a nonnull
2167 pointer to entryname. If entryname is not already known and no
2168 problems are encountered seg_ptr contains a valid pointer and code is
2169 0. If ref_name has already been initiated in the current ring the
2170 code is returned as error_table_$namedup. The seg_ptr argument
2171 contains a valid pointer to the segment being initiated. If the
2172 seg_ptr argument contains a nonnull pointer the bit_count argument is
2173 set to the bit count of the segment to which seg_ptr points.
2174
2175
2176 :Entry: initiate_search_rules: 1982-03-08 hcs_$initiate_search_rules
2177
2178
2179 Function: provides the user with a subroutine interface for specifying
2180 the search rules that he wants to use in his process. The search
2181 rules remain in effect until this entry point is called with a
2182 different set of rules or the process is terminated. For a
2183 description of the set_search_rules command type "help ssr".
2184
2185
2186 Syntax:
2187 declare hcs_$initiate_search_rules entry ptr fixed bin35;
2188 call hcs_$initiate_search_rules search_rules_ptr code;
2189
2190
2191 Arguments:
2192 search_rules_ptr
2193 is a pointer to a structure containing the new search rules.
2194 Input See "Notes" below.
2195 code
2196 is a storage system status code. Output It can be one of the
2197 following:
2198 error_table_$badstring not a pathname or keyword
2199 error_table_$notadir
2200 error_table_$too_many_sr
2201 Additional codes can be returned from other procedures that are
2202 called by hcs_$initiate_search_rules.
2203
2204
2205 Notes: The structure pointed to by search_rules_ptr is declared as
2206 follows:
2207
2208 dcl 1 search_rules aligned
2209 2 number fixed bin
2210 2 names 21 char168 aligned;
2211
2212 number
2213 is the number of search rules contained in the array. The
2214 current maximum number of search rules the user can define is 21.
2215 names
2216 are the names of the search rules. They can be absolute
2217 pathnames of directories or keywords. See "List of keywords"
2218 below.
2219
2220
2221 List of keywords:
2222 initiated_segments
2223 search for the already initiated segments.
2224 referencing_dir
2225 search the containing directory of the segment making the reference.
2226 working_dir
2227 search the working directory.
2228 process_dir
2229 search the process directory.
2230 home_dir
2231 search the home directory.
2232
2233
2234 set_search_directories
2235 insert the directories following this keyword into the default
2236 search rules after working_dir and make the result the current
2237 search rules. When used it must be the first search rule specified
2238 and the only keyword used.
2239 site-defined keywords
2240 may also be specified. These keywords may expand into one or more
2241 directory pathnames. The keyword default is always defined to be
2242 the site's default search rules. For the values of the site-defined
2243 keywords the user may call the hcs_$get_system_search_rules entry
2244 point.
2245
2246
2247 :Entry: list_acl: 1982-03-08 hcs_$list_acl
2248
2249
2250 Function: is used either to list the entire access control list ACL
2251 of a segment or to return the access modes of specified ACL entries.
2252
2253
2254 Syntax:
2255 declare hcs_$list_acl entry char* char* ptr ptr ptr
2256 fixed bin fixed bin35;
2257 call hcs_$list_acl dir_name entryname area_ptr area_ret_ptr
2258 acl_ptr acl_count code;
2259
2260
2261 Arguments:
2262 dir_name
2263 is the pathname of the containing directory. Input
2264 entryname
2265 is the entryname of the segment. Input
2266 area_ptr
2267 points to an area in which the list of ACL entries which make up
2268 the entire ACL of the segment is allocated. Input If area_ptr is
2269 null then the user wants access modes for certain ACL entries;
2270 these will be specified by the structure pointed to by acl_ptr.
2271 area_ret_ptr
2272 points to the start of the allocated list of ACL entries. Output
2273
2274
2275 acl_ptr
2276 if area_ptr is null then acl_ptr points to an ACL structure
2277 segment_acl into which mode information is placed for the access
2278 names specified in that same structure. Input The segment_acl
2279 structure is described in the hcs_$add_acl_entries entry point.
2280 acl_count
2281 is the number of entries in the ACL structure. Input or Output
2282 Input is the number of entries in the ACL structure identified by
2283 acl_ptr.
2284 Output is the number of entries in the segment_acl structure
2285 allocated in the area pointed to by area_ptr if area_ptr
2286 is not null.
2287 code
2288 is a storage system status code. Output
2289
2290
2291 Notes: If acl_ptr is used to obtain modes for specified access names
2292 rather than for all access names on a segment then each ACL entry in
2293 the segment_acl structure either has status_code set to 0 and contains
2294 the segment's mode or has status_code set to
2295 error_table_$user_not_found and contains a mode of 0.
2296
2297
2298 :Entry: list_dir_acl: 1982-03-08 hcs_$list_dir_acl
2299
2300
2301 Function: is used either to list the entire access control list ACL
2302 of a directory or to return the access modes for specified entries.
2303
2304
2305 Syntax:
2306 declare hcs_$list_dir_acl entry char* char* ptr ptr ptr
2307 fixed bin fixed bin35;
2308 call hcs_$list_dir_acl dir_name entryname area_ptr area_ret_ptr
2309 acl_ptr acl_count code;
2310
2311
2312 Arguments:
2313 dir_name
2314 is the pathname of the containing directory. Input
2315 entryname
2316 is the entryname of the directory. Input
2317 area_ptr
2318 points to an area in which the list of ACL entries which make up
2319 the entire ACL of the directory is allocated. Input If area_ptr
2320 is null then the user wants access modes for certain ACL entries;
2321 these will be specified by the structure pointed to by acl_ptr.
2322 area_ret_ptr
2323 points to the start of the allocated list of ACL entries. Output
2324
2325
2326 acl_ptr
2327 if area_ptr is null then acl_ptr points to an ACL structure
2328 dir_acl into which mode information is placed for the access names
2329 specified in that same structure. Input The dir_acl structure
2330 is described in the hcs_$add_dir_acl_entries entry point.
2331 acl_count
2332 is the number of entries in the ACL structure. Input or Output
2333 Input is the number of entries in the ACL structure identified by
2334 acl_ptr.
2335 Output is the number of entries in the dir_acl structure allocated
2336 in the area pointed to by area_ptr if area_ptr is not null.
2337 code
2338 is a storage system status code. Output
2339
2340
2341 Notes: If acl_ptr is used to obtain modes for specified access names
2342 rather than for all access names on a directory then each ACL entry
2343 in the dir_acl structure either has status_code set to 0 and contains
2344 the mode of the directory or has status_code set to
2345 error_table_$user_not_found and contains a mode of 0.
2346
2347
2348 :Entry: list_dir_inacl: 1986-09-26 hcs_$list_dir_inacl
2349
2350
2351 Function: is used either to list the entire initial access control
2352 list initial ACL for new directories created for the specified ring
2353 within the specified directory or to return the access modes for
2354 specified initial ACL entries.
2355
2356
2357 Syntax:
2358 declare hcs_$list_dir_inacl entry char* char* ptr ptr ptr
2359 fixed bin fixed bin3 fixed bin35;
2360 call hcs_$list_dir_inacl dir_name entryname area_ptr area_ret_ptr
2361 acl_ptr acl_count ring code;
2362
2363
2364 Arguments:
2365 dir_name
2366 is the pathname of the containing directory. Input
2367 entryname
2368 is the entryname of the directory. Input
2369 area_ptr
2370 points to an area into which the list of initial ACL entries which
2371 makes up the entire initial ACL of the directory is allocated.
2372 Input If area_ptr is null then the user wants access modes for
2373 certain initial ACL entries; these will be specified by the
2374 structure pointed to by acl_ptr.
2375 area_ret_ptr
2376 points to the start of the allocated list of initial ACL entries.
2377 Output
2378
2379
2380 acl_ptr
2381 if area_ptr is null then acl_ptr points to an initial ACL
2382 structure dir_acl into which mode information is placed for the
2383 access names specified in that same structure. Input
2384 The dir_acl structure is described in the hcs_$add_dir_inacl_entries
2385 entry point.
2386 acl_count
2387 Input is the number of entries in the initial ACL structure.
2388 Output is the number of entries in the dir_acl structure
2389 allocated in the area pointed to by area_ptr if area_ptr
2390 is not null.
2391 ring
2392 is the ring number of the initial ACL. Input
2393 code
2394 is a storage system status code. Output
2395
2396
2397 Notes: If acl_ptr is used to obtain modes for specified access names
2398 rather than obtaining modes for all access names on the initial ACL
2399 then each initial ACL entry in the dir_acl structure either has
2400 status_code set to 0 and contains the directory's mode or has
2401 status_code set to error_table_$user_not_found and contains a mode
2402 of 0.
2403
2404
2405 :Entry: list_inacl: 1986-09-26 hcs_$list_inacl
2406
2407
2408 Function: is used either to list the entire initial access control
2409 list initial ACL for new segments created for the specified ring
2410 within the specified directory or to return the access modes for
2411 specified initial ACL entries.
2412
2413
2414 Syntax:
2415 declare hcs_$list_inacl entry char* char* ptr ptr ptr
2416 fixed bin fixed bin3 fixed bin35;
2417 call hcs_$list_inacl dir_name entryname area_ptr area_ret_ptr
2418 acl_ptr acl_count ring code;
2419
2420
2421 Arguments:
2422 dir_name
2423 is the pathname of the containing directory. Input
2424 entryname
2425 is the entryname of the directory. Input
2426 area_ptr
2427 points to an area into which the list of initial ACL entries which
2428 makes up the entire initial ACL of the directory is allocated.
2429 Input If area_ptr is null then the user wants access modes for
2430 certain initial ACL entries; these will be specified by the
2431 structure pointed to by acl_ptr.
2432 area_ret_ptr
2433 points to the start of the allocated list of initial ACL entries.
2434 Output
2435
2436
2437 acl_ptr
2438 if area_ptr is null then acl_ptr points to an initial ACL
2439 structure segment_acl into which mode information is to be placed
2440 for the access names specified in that same structure. Input
2441 The segment_acl structure is described in the hcs_$add_inacl_entries
2442 entry point.
2443 acl_count
2444 Input is the number of entries in the initial ACL structure.
2445 Output is the number of entries in the segment_acl structure
2446 allocated in the area pointed to by area_ptr if area_ptr
2447 is not null.
2448 ring
2449 is the ring number of the initial ACL. Input
2450 code
2451 is a storage system status code. Output
2452
2453
2454 Notes: If acl_ptr is used to obtain modes for specified access names
2455 rather than obtaining modes for all access names on the initial ACL
2456 then each initial ACL entry in the segment_acl structure either has
2457 status_code set to 0 and contains the segment's mode or has status_code
2458 set to error_table_$user_not_found and contains a mode of 0.
2459
2460
2461 :Entry: make_entry: 1982-03-08 hcs_$make_entry
2462
2463
2464 Function: when given a reference name and an entry point name
2465 returns the value of a specified entry point. If the reference name
2466 has not yet been initiated the search rules are used to find a
2467 segment with a name the same as the reference name. The segment is
2468 made known and the reference name initiated. Use hcs_$make_ptr to
2469 have a pointer returned.
2470
2471
2472 Syntax:
2473 declare hcs_$make_entry entry ptr char* char* entry
2474 fixed bin35;
2475 call hcs_$make_entry ref_ptr entryname entry_point_name
2476 entry_point code;
2477
2478
2479 Arguments:
2480 ref_ptr
2481 is a pointer to the segment that is considered the referencing
2482 procedure see "Notes" below. Input
2483 entryname
2484 is the entryname or reference name of the segment. Input
2485 entry_point_name
2486 is the name of the entry point to be located. Input
2487 entry_point
2488 is the value of the segment entry point specified by entryname and
2489 entry_point_name. Output
2490 code
2491 is a storage system status code. Output
2492
2493
2494 Notes: The directory in which the segment pointed to by ref_ptr is
2495 located is used as the referencing directory for the standard search
2496 rules. If ref_ptr is null then the standard search rule specifying
2497 the referencing directory is skipped. See "Search Rules" in the
2498 Reference Manual. Normally ref_ptr is null.
2499
2500 The entryname and entry_point_name arguments are nonvarying character
2501 strings with a length of up to 32 characters. They need not be aligned
2502 and can be blank padded.
2503
2504
2505 If a null string is given for the entry_point_name argument then an
2506 entry value referring to the base of the segment is returned. In any
2507 case the segment identified by entryname is made known to the process
2508 with the entryname argument initiated as a reference name. If an error
2509 is encountered upon return the entry_point_ptr argument is null and an
2510 error code is given.
2511
2512
2513 :Entry: make_ptr: 1982-03-08 hcs_$make_ptr
2514
2515
2516 Function: when given a reference name and an entry point name
2517 returns a pointer to a specified entry point. If the reference name
2518 has not yet been initiated the search rules are used to find a
2519 segment with a name the same as the reference name. The segment is
2520 made known and the reference name initiated. Use hcs_$make_entry to
2521 have entry values returned.
2522
2523
2524 Syntax:
2525 declare hcs_$make_ptr entry ptr char* char* ptr fixed
2526 bin35;
2527 call hcs_$make_ptr ref_ptr entryname entry_point_name
2528 entry_point_ptr code;
2529
2530
2531 Arguments:
2532 ref_ptr
2533 is a pointer to the segment that is considered the referencing
2534 procedure. Input See "Notes" below.
2535 entryname
2536 is the entryname of the segment. Input
2537 entry_point_name
2538 is the name of the entry point to be located. Input
2539 entry_point_ptr
2540 is the pointer to the segment entry point specified by entryname and
2541 entry_point_name. Output
2542 code
2543 is a storage system status code. Output
2544
2545
2546 Notes: The directory in which the segment pointed to by ref_ptr is
2547 located is used as the referencing directory for the standard search
2548 rules. If ref_ptr is null then the standard search rule specifying
2549 the referencing directory is skipped. For a discussion of standard
2550 search rules refer to "Search Rules" in the Reference Manual.
2551 Normally ref_ptr is null.
2552
2553
2554 The entryname and entry_point_name arguments are nonvarying character
2555 strings with a length of up to 32 characters. They need not be aligned
2556 and can be blank padded. If a null string is given for the
2557 entry_point_name argument then a pointer to the base of the segment is
2558 returned. In any case the segment identified by entryname is made
2559 known to the process with the entryname argument initiated as a
2560 reference name. If an error is encountered upon return the
2561 entry_point_ptr argument is null and an error code is given.
2562
2563
2564 :Entry: make_seg: 1982-03-08 hcs_$make_seg
2565
2566
2567 Function: creates a segment with a specified entryname in a specified
2568 directory. Once the segment is created it is made known to the
2569 process and a pointer to the segment is returned to the caller. If
2570 the segment already exists or is already known a nonzero code is
2571 returned; however a pointer to the segment is still returned.
2572
2573
2574 Syntax:
2575 declare hcs_$make_seg entry char* char* char* fixed bin5
2576 ptr fixed bin35;
2577 call hcs_$make_seg dir_name entryname ref_name mode seg_ptr
2578 code;
2579
2580
2581 Arguments:
2582 dir_name
2583 is the pathname of the containing directory. Input
2584 entryname
2585 is the entryname of the segment. Input
2586 ref_name
2587 is the desired reference name or a null character string "".
2588 Input
2589 mode
2590 specifies the mode for this user. Input See "Notes" in the
2591 description of hcs_$append_branchx for more information on modes.
2592 seg_ptr
2593 is a pointer to the created segment. Output
2594
2595
2596 code
2597 is a storage system status code. Output It may be one of the
2598 following:
2599 error_table_$namedup
2600 if the specified segment already exists or the specified
2601 reference name has already been initiated
2602 error_table_$segknown
2603 if the specified segment is already known
2604
2605
2606 Notes: If dir_name is null the process directory is used. If the
2607 entryname is null a unique name is generated. The segment is made
2608 known and ref_name is initiated. See also "Constructing and
2609 Interpreting Names" in the Reference Manual.
2610
2611 If the segment cannot be created or made known a null pointer is
2612 returned for seg_ptr and the returned value of code indicates the
2613 reason for failure. Thus the usual way to test whether the call was
2614 successful is to check the pointer not the code since the code may be
2615 nonzero even if the segment was successfully initiated.
2616
2617
2618 :Entry: mask_ips: 1982-03-08 hcs_$mask_ips
2619
2620
2621 Function: masks on or enables the specified ips interrupts. This
2622 entry point can be used at the end of a critical section of code to
2623 re-enable specified ips interrupts and turn off the control bit see
2624 "Notes".
2625
2626
2627 Syntax:
2628 declare hcs_$mask_ips entry bit36 aligned bit36 aligned;
2629 call hcs_$mask_ips mask old_mask;
2630
2631
2632 Arguments:
2633 mask
2634 is a word containing a "1"b for each ips interrupt that is to be
2635 enabled. Input See "Notes".
2636 old_mask
2637 is the former value of the ips mask with a control bit of "0"b.
2638 Output
2639
2640
2641 Notes: The create_ips_mask_ subroutine can be used to create a mask
2642 given a set of ips names.
2643
2644 The thirty-sixth rightmost bit of old_mask does not correspond to an
2645 interrupt but is used as a control bit giving a positive indication
2646 that a particular masking or unmasking operation has taken place. No
2647 ips interrupts can occur in the time interval between the requested
2648 mask modification and the returning of the old_mask with the control
2649 bit set appropriately.
2650
2651
2652 Entry points used at the beginning of a critical section of code to
2653 disable some or all ips interrupts return a value of "1"b for the
2654 control bit while those that are used at the end of a critical section
2655 of code to re-enable those interrupts return a value of "0"b for the
2656 control bit. Thus a condition handler can interpret a value of "1"b
2657 in the control bit as meaning that execution was in a critical section
2658 of code and the ips mask has been modified. See "Notes" in the
2659 description of the hcs_$set_automatic_ips_mask entry point for
2660 information about the state of the ips mask immediately after an ips
2661 interrupt occurs.
2662
2663
2664 :Entry: quota_move: 1982-03-08 hcs_$quota_move
2665
2666
2667 Function: moves all or part of a quota between two directories one of
2668 which is immediately inferior to the other.
2669
2670
2671 Syntax:
2672 declare hcs_$quota_move entry char* char* fixed bin18
2673 fixed bin35;
2674 call hcs_$quota_move dir_name entryname quota_change code;
2675
2676
2677 Arguments:
2678 dir_name
2679 is the pathname of the containing directory. Input
2680 entryname
2681 is the entryname of the directory. Input
2682 quota_change
2683 is the number of records of secondary storage quota to be moved
2684 between the superior directory and the inferior directory. Input
2685 See "Notes" below.
2686 code
2687 is a storage system status code. Output
2688
2689
2690 Access required:
2691 The user must have modify permission on both directories.
2692
2693
2694 Notes: After the quota change the remaining quota in each directory
2695 must be greater than the number of records used in that directory.
2696
2697 The quota_change argument can be either a positive or negative number.
2698 If it is positive the quota is moved from dir_name to entryname. If
2699 it is negative the move is from entryname to dir_name. If the change
2700 results in zero quota left on entryname that directory is assumed to
2701 no longer contain a terminal quota and all of its used records are
2702 reflected up to the used records on dir_name. It is a restriction that
2703 no quota in any of the directories superior to entryname can be
2704 modified from a nonzero value to a zero value by this subroutine.
2705
2706
2707 :Entry: quota_read: 1982-03-08 hcs_$quota_read
2708
2709
2710 Function: returns the segment record quota and accounting information
2711 for a directory.
2712
2713
2714 Syntax:
2715 declare hcs_$quota_read entry char* fixed bin18 fixed bin71
2716 bit36 aligned bit36 fixed bin1 fixed bin18
2717 fixed bin35;
2718 call hcs_$quota_read dir_name quota trp tup sons_lvid tacc_sw
2719 used code;
2720
2721
2722 Arguments:
2723 dir_name
2724 is the pathname of the directory for which quota information is
2725 desired. Input
2726 quota
2727 is the segment record quota in the directory. Output
2728 trp
2729 is the time-record product trp charged to the directory. Output
2730 This double-precision number is in units of record-seconds.
2731 tup
2732 is the time expressed in storage system time format the high-order
2733 36 bits of the 52-bit time returned by the clock_ subroutine
2734 that the trp was last updated. Output
2735
2736
2737 sons_lvid
2738 is the logical volume ID for segments contained in this directory.
2739 Output
2740 tacc_sw
2741 is the terminal account switch. Output The setting of this switch
2742 determines how charges are made.
2743 1 records are charged against the quota in this directory
2744 0 records are charged against the quota in the first superior
2745 directory with a terminal account
2746 used
2747 is the number of records used by segments in this directory and by
2748 segments in nonterminal inferior directories. Output
2749 code
2750 is a storage system status code. Output
2751
2752
2753 Notes: If the directory contains a nonterminal account the quota
2754 trp and tup are all zero. The variable specified by used however is
2755 kept up-to-date and represents the number of records in this directory
2756 and inferior nonterminal directories.
2757
2758
2759 :Entry: release_segment_numbers: 1983-03-03 hcs_$release_segment_numbers
2760
2761 Function: releases reserved segment numbers which are not
2762 associated with segments.
2763
2764
2765 Syntax:
2766 declare hcs_$release_segment_numbers entry fixed bin fixed bin
2767 fixed bin35;
2768 call hcs_$release_segment_numbers first_segno block_size code;
2769
2770
2771 Arguments:
2772 first_segno
2773 is the first segment number of the reserved block. Input
2774 block_size
2775 is the number os segment numbers to be released. Input
2776 code
2777 is error_table_$invalidsegno if any portion of the segment number
2778 range is an invalid segment number. It is error_table_$segknown if
2779 any of the segment numbers is known. Output
2780
2781
2782 Notes: This entry should be used in the cleanup handler of programs
2783 which reserve segment number blocks using
2784 hcs_$reserve_segment_numbers. If code is non-zero no segment numbers
2785 were released. For example suppose that a program reserves a block
2786 of ten segment numbers and a cleanup condition occurs after only four
2787 of these segment numbers have been used in calls to hcs_$initiate.
2788 The cleanup handler should call hcs_$release_segment_numbers for the
2789 last six segments of the block and then individually terminate the
2790 first four segments.
2791
2792
2793 :Entry: replace_acl: 1982-03-08 hcs_$replace_acl
2794
2795
2796 Function: replaces an entire access control list ACL for a segment
2797 with a user-provided ACL and can optionally add an entry for
2798 *.SysDaemon.* with mode rw to the new ACL.
2799
2800
2801 Syntax:
2802 declare hcs_$replace_acl entry char* char* ptr fixed bin
2803 bit1 fixed bin35;
2804 call hcs_$replace_acl dir_name entryname acl_ptr acl_count
2805 no_sysdaemon_sw code;
2806
2807
2808 Arguments:
2809 dir_name
2810 is the pathname of the containing directory. Input
2811 entryname
2812 is the entryname of the segment. Input
2813 acl_ptr
2814 points to the user supplied segment_acl structure that is to replace
2815 the current ACL. Input The segment_acl structure is described in
2816 the hcs_$add_acl_entries entry point.
2817 acl_count
2818 is the number of entries in the segment_acl structure. Input
2819
2820
2821 no_sysdaemon_sw
2822 is a switch that indicates whether an rw *.SysDaemon.* entry is to
2823 be put on the ACL of the segment after the existing ACL has been
2824 deleted and before the user-supplied segment_acl entries are added.
2825 Input
2826 "0"b adds rw *.SysDaemon.* entry
2827 "1"b replaces the existing ACL with only the user-supplied
2828 segment_acl
2829 code
2830 is a storage system status code. Output
2831
2832
2833 Notes: If acl_count is zero then the existing ACL is deleted and only
2834 the action indicated if any by the no_sysdaemon_sw switch is
2835 performed. If acl_count is greater than zero processing of the
2836 segment_acl entries is performed top to bottom allowing later entries
2837 to overwrite previous ones if the access_name in the segment_acl
2838 structure is identical.
2839
2840 If the segment is a gate see "Intraprocess Access Control" in the
2841 Programmer's Reference Manual and if the validation level is greater
2842 than ring 1 access is restricted to the same project as that of the
2843 user or to the SysDaemon project. If the replacement ACL is in error
2844 then no processing is performed and the code
2845 error_table_$invalid_project_for_gate is returned.
2846
2847
2848 :Entry: replace_dir_acl: 1986-09-26 hcs_$replace_dir_acl
2849
2850
2851 Function: replaces an entire access control list ACL for a directory
2852 with a user-provided ACL and can optionally add an entry for
2853 *.SysDaemon.* with mode sma to the new ACL.
2854
2855
2856 Syntax:
2857 declare hcs_$replace_dir_acl entry char* char* ptr fixed bin
2858 bit1 fixed bin35;
2859 call hcs_$replace_dir_acl dir_name entryname acl_ptr acl_count
2860 no_sysdaemon_sw code;
2861
2862
2863 Arguments:
2864 dir_name
2865 is the pathname of the containing directory. Input
2866 entryname
2867 is the entryname of the directory. Input
2868 acl_ptr
2869 points to a user-supplied dir_acl structure that is to replace the
2870 current ACL. Input The dir_acl structure is described in the
2871 hcs_$add_dir_acl_entries entry point.
2872 acl_count
2873 contains the number of entries in the dir_acl structure. Input
2874
2875
2876 no_sysdaemon_sw
2877 is a switch that indicates whether the sma *.SysDaemon.* entry is
2878 put on the ACL of the directory after the existing ACL of the
2879 directory has been deleted and before the user-supplied dir_acl
2880 entries are added. Input
2881 "0"b adds sma *.SysDaemon.* entry
2882 "1"b replaces the existing ACL with only the user-supplied dir_acl
2883 code
2884 is a storage system status code. Output
2885
2886
2887 Notes: If acl_count is zero then the existing ACL is deleted and only
2888 the action indicated if any by the no_sysdaemon_sw switch is
2889 performed. If acl_count is greater than zero processing of the
2890 dir_acl entries is performed top to bottom allowing later entries to
2891 overwrite previous ones if the access_name in the dir_acl structure is
2892 identical.
2893
2894 If the replacement ACL is in error no processing is performed for that
2895 ACL entry in the dir_acl structure and the subroutine returns the code
2896 error_table_$nam_err or error_table_$invalid_ascii whichever is
2897 appropriate.
2898
2899
2900 :Entry: reserve_segment_numbers: 1983-03-03 hcs_$reserve_segment_numbers
2901
2902 Function: This entry point allows a user to reserve a block of
2903 contiguous segment numbers.
2904
2905
2906 Syntax:
2907 declare hcs_$reserve_segment_numbers entry fixed bin fixed bin
2908 fixed bin35;
2909 call hcs_$reserve_segment_numbers block_size first_segno code;
2910
2911
2912 Arguments:
2913 block_size
2914 is the number of segments in the segment number group. Input
2915 first_segno
2916 is the number of the first segment in the group assigned. Output
2917 code
2918 is 0 if the allocation succeeded. It is error_table_$nrmkst if
2919 there is no group of block_size contiguous segment numbers
2920 available. Output
2921
2922
2923 Notes: This entry removes the contiguous segment number group from the
2924 available free segment numbers. The assigned segment numbers are
2925 available only by using hcs_$initiate and specifying a reserved
2926 segment number. See also the description of
2927 hcs_$release_segment_numbers.
2928
2929
2930 :Entry: reset_ips_mask: 1982-03-08 hcs_$reset_ips_mask
2931
2932
2933 Function: replaces the entire ips mask with a specified mask and
2934 returns the previous value of the mask with a control bit of "0"b. It
2935 can be used at the end of a critical section of code to restore the
2936 mask to its former value. See "Notes" in the description of the
2937 hcs_$get_ips_mask entry point for a discussion of the control bit.
2938
2939
2940 Syntax:
2941 declare hcs_$reset_ips_mask entry bit36 aligned bit36 aligned;
2942 call hcs_$reset_ips_mask mask old_mask;
2943
2944
2945 Arguments:
2946 mask
2947 is the new ips mask to replace the current one. Input A "1" bit
2948 in a mask position enables the corresponding ips interrupt.
2949 old_mask
2950 is the former value of the ips mask with a control bit of "0"b.
2951 Output
2952
2953
2954 Notes: This entry point can be used at the end of a critical section
2955 of code to undo the mask changes made by the hcs_$set_ips_mask entry
2956 point. The old_mask returned by the latter entry point should be used
2957 as the value of the new mask set by this entry point.
2958
2959
2960 :Entry: replace_dir_inacl: 1986-09-26 hcs_$replace_dir_inacl
2961
2962
2963 Function:
2964 This entry point replaces an entire initial access control list
2965 initial ACL for new directories created for the specified ring within
2966 a specified directory with a user-provided initial ACL and can
2967 optionally add an entry for *.SysDaemon.* with mode sma to the new
2968 initial ACL.
2969
2970
2971 Syntax:
2972 declare hcs_$replace_dir_inacl entry char* char* ptr fixed bin
2973 bit1 fixed bin3 fixed bin35;
2974 call hcs_$replace_dir_inacl dir_name entryname acl_ptr acl_count
2975 no_sysdaemon_sw ring code;
2976
2977
2978 Arguments:
2979 dir_name
2980 is the pathname of the containing directory. Input
2981 entryname
2982 is the entryname of the directory. Input
2983 acl_ptr
2984 points to a user-supplied dir_acl_array structure that is to replace
2985 the current initial ACL. The dir_acl_array structure is discussed
2986 in the description of hcs_$add_dir_inacl_entries. Input
2987 acl_count
2988 contains the number of entries in the dir_acl_array structure.
2989 Input
2990
2991
2992 no_sysdaemon_sw
2993 is a switch that indicates whether the sma *.SysDaemon.* entry is
2994 put on the initial ACL after the existing initial ACL is deleted and
2995 before the user-supplied dir_acl_array entries are added. Input
2996 "0"b adds sma *.SysDaemon.* entry
2997 "1"b replaces the existing initial ACL with only the user-supplied
2998 dir_acl_array
2999 ring
3000 is the ring number of the initial ACL. Input
3001 code
3002 is a storage system status code. Output
3003
3004
3005 Notes: If acl_count is zero then the existing initial ACL is deleted
3006 and only the action indicated if any by the no_sysdaemon_sw switch is
3007 performed. If acl_count is greater than zero processing of the
3008 dir_acl_array entries is performed top to bottom allowing later
3009 entries to overwrite previous ones if the access_name in the
3010 dir_acl_array structure is identical.
3011
3012
3013 :Entry: replace_inacl: 1986-09-26 hcs_$replace_inacl
3014
3015
3016 Function: replaces an entire initial access control list initial ACL
3017 for new segments created for the specified ring within a specified
3018 directory with a user-provided initial ACL and can optionally add an
3019 entry for *.SysDaemon.* with mode rw to the new initial ACL.
3020
3021
3022 Syntax:
3023 declare hcs_$replace_inacl entry char* char* ptr fixed bin
3024 bit1 fixed bin3 fixed bin35;
3025 call hcs_$replace_inacl dir_name entryname acl_ptr acl_count
3026 no_sysdaemon_sw ring code;
3027
3028
3029 Arguments:
3030 dir_name
3031 is the pathname of the containing directory. Input
3032 entryname
3033 is the entryname of the directory. Input
3034 acl_ptr
3035 points to the user-supplied segment_acl structure that is to replace
3036 the current initial ACL. The segment_acl structure is described in
3037 the hcs_$add_inacl_entries entry point. Input
3038 acl_count
3039 contains the number of entries in the segment_acl structure.
3040 Input
3041
3042
3043 no_sysdaemon_sw
3044 is a switch that indicates whether the rw *.SysDaemon.* entry is to
3045 be put on the initial ACL after the existing initial ACL is deleted
3046 and before the user-supplied segment_acl entries are added. Input
3047 "0"b adds rw *.SysDaemon.* entry
3048 "1"b replaces the existing initial ACL with only the user-supplied
3049 segment_acl
3050 ring
3051 is the ring number of the initial ACL. Input
3052 code
3053 is a storage system status code. Output
3054
3055
3056 Notes: If acl_count is zero then the existing initial ACL is deleted
3057 and only the action indicated if any by the no_sysdaemon_sw switch is
3058 performed. If acl_count is greater than zero processing of the
3059 segment_acl entries is performed top to bottom allowing later entries
3060 to overwrite previous ones if the access_name in the segment_acl
3061 structure is identical.
3062
3063
3064 :Entry: set_256K_switch: 1983-03-03 hcs_$set_256K_switch
3065
3066 Function: This entry point sets the per-process switch which controls
3067 whether or not segments of maximum length 256K 262144 words can be
3068 used. The standard maximum length for a segment defined as
3069 sys_info$max_seg_size is 261120 words. The only supported use of
3070 256K segments is for Fortran Very Large Arrays.
3071
3072
3073 Syntax:
3074 declare hcs_$set_256K_switch entry bit2 aligned bit2 aligned
3075 fixed bin35;
3076 call hcs_$set_256K_switch new_switch old_switch code;
3077
3078
3079 Arguments:
3080 new_switch
3081 is the new control value. If it is "11"b the process may use 256K
3082 segments. If it is "10"b the process may not use such segments.
3083 Input
3084 old_switch
3085 is the previous value of the switch. Output
3086 code
3087 is 0 if the operation was performed. It is
3088 error_table_$action_not_performed if the caller's validation level
3089 is larger than the initial ring of the process or if new_switch is
3090 not "10"b or "11"b.
3091
3092
3093 Notes: If the switch has the value "10"b an attempt to connect to a
3094 segment having a maximum length greater than sys_info$max_seg_size
3095 words will cause a seg_fault_error with error code
3096 error_table_$big_seg. The error occurs when the process attempts to
3097 reference the contents of the segment not when the segment is made
3098 known using hcs_$initiate.
3099
3100
3101 :Entry: set_automatic_ips_mask: 1982-03-08 hcs_$set_automatic_ips_mask
3102
3103
3104 Function: replaces the entire automatic ips mask with a supplied
3105 value and returns the previous value of the automatic ips mask with a
3106 control bit of "1"b.
3107
3108
3109 Syntax:
3110 declare hcs_$set_automatic_ips_mask entry bit36 aligned
3111 bit36 aligned;
3112 call hcs_$set_automatic_ips_mask mask old_mask;
3113
3114
3115 Arguments:
3116 mask
3117 is the new value to replace the automatic ips mask. Input
3118 old_mask
3119 is the former value of the automatic ips mask with a control bit of
3120 "1"b. Output
3121
3122
3123 Notes: The create_ips_mask_ subroutine can be used to create a mask
3124 given a set of ips names.
3125
3126 The automatic ips mask controls the state of the ips mask at the time
3127 that an ips signal handler is called. The interpretation of the bits
3128 in the automatic ips mask is quite different from that of the bits in
3129 the ips mask. When an ips interrupt occurs if the bit corresponding
3130 to that interrupt is on in the automatic ips mask then automatic ips
3131 masking takes place -- i.e. all ips interrupts are temporarily masked
3132 off as described below. If the bit is off then the ips mask is not
3133 changed.
3134
3135
3136 If automatic ips masking is to take place for a given ips interrupt
3137 then the current value of the ips mask is saved in the machine
3138 conditions with its control bit on and the ips mask is set to all
3139 zero bits thus disabling all ips interrupts. This happens before the
3140 handler for the interrupt is called. When an ips interrupt handler
3141 returns if the control bit in the saved ips mask is on then the
3142 current ips mask is replaced by the saved one. It follows from this
3143 that the handler for an ips interrupt for which automatic ips masking
3144 is in effect can not make a permanent change to the ips mask unless it
3145 also modifies the machine conditions turning off the control bit in
3146 the saved ips mask.
3147
3148
3149 :Entry: set_bc: 1982-03-08 hcs_$set_bc
3150
3151
3152 Function: sets the bit count of a specified segment. It also sets the
3153 bit count author of that segment to be the user who called it.
3154
3155
3156 Syntax:
3157 declare hcs_$set_bc entry char* char* fixed bin24 fixed
3158 bin35;
3159 call hcs_$set_bc dir_name entryname bit_count code;
3160
3161
3162 Arguments:
3163 dir_name
3164 is the pathname of the containing directory. Input
3165 entryname
3166 is the entryname of the segment. Input
3167 bit_count
3168 is the new bit count of the segment. Input
3169 code
3170 is a storage system status code. Output
3171
3172
3173 Access required:
3174 The user must have write access on the segment but does not
3175 need modify permission on the containing directory.
3176
3177
3178 Notes: The hcs_$set_bc_seg entry point performs the same function
3179 when a pointer to the segment is provided instead of the pathname.
3180
3181
3182 :Entry: set_bc_seg: 1982-03-08 hcs_$set_bc_seg
3183
3184
3185 Function: given a pointer to the segment sets the bit count of a
3186 segment in the storage system. It also sets that bit count author of
3187 the segment to be the user who called it.
3188
3189
3190 Syntax:
3191 declare hcs_$set_bc_seg entry ptr fixed bin24 fixed bin35;
3192 call hcs_$set_bc_seg seg_ptr bit_count code;
3193
3194
3195 Arguments:
3196 seg_ptr
3197 is a pointer to the segment whose bit count is to be changed.
3198 Input
3199 bit_count
3200 is the new bit count of the segment. Input
3201 code
3202 is a storage system status code. Output
3203
3204
3205 Access required:
3206 The user must have write access on the segment but does not
3207 need modify permission on the containing directory.
3208
3209
3210 Notes: The hcs_$set_bc entry point performs the same function when
3211 provided with a pathname of a segment rather than a pointer.
3212
3213
3214 :Entry: set_dir_ring_brackets: 1982-03-08 hcs_$set_dir_ring_brackets
3215
3216
3217 Function: given the pathname of the containing directory and the
3218 entryname of the subdirectory sets the subdirectory's ring brackets.
3219
3220
3221 Syntax:
3222 declare hcs_$set_dir_ring_brackets entry char* char*
3223 2 fixed bin3 fixed bin35;
3224 call hcs_$set_dir_ring_brackets dir_name entryname drb code;
3225
3226
3227 Arguments:
3228 dir_name
3229 is the pathname of the containing directory. Input
3230 entryname
3231 is the entryname of the subdirectory. Input
3232 drb
3233 is a two-element array specifying the ring brackets of the
3234 directory. Input The first element contains the level required
3235 for modify and append permission; the second element contains the
3236 level required for status permission.
3237 code
3238 is a storage system status code. Output
3239
3240
3241 Access required:
3242 The user must have modify permission on the containing directory.
3243 Also the validation level must be less than or equal to both the
3244 present value of the first ring bracket and the new value of the first
3245 ring bracket that the user wishes set.
3246
3247 Ring brackets and validation levels are discussed in "Intraprocess
3248 Access Control" in the Reference Manual.
3249
3250
3251 :Entry: set_entry_bound: 1982-03-08 hcs_$set_entry_bound
3252
3253
3254 Function: given a directory name and an entryname sets the entry
3255 point bound of a segment.
3256
3257 The entry point bound attribute provides a way of limiting which
3258 locations of a segment may be targets of a call. This entry point
3259 allows the caller to enable or disable a hardware check of calls to a
3260 given segment from other segments. If the mechanism is enabled all
3261 calls to the segment must be made to an entry point whose offset is
3262 less than the entry point bound.
3263
3264 In practice this attribute is most effective when all of the entry
3265 points are located at the base of the segment. In this case the entry
3266 point bound is the number of callable words.
3267
3268
3269 Syntax:
3270 declare hcs_$set_entry_bound entry char* char* fixed bin14
3271 fixed bin35;
3272 call hcs_$set_entry_bound dir_name entryname entry_bound code;
3273
3274
3275 Arguments:
3276 dir_name
3277 is the pathname of the containing directory. Input
3278 entryname
3279 is the entryname of the segment. Input
3280 entry_bound
3281 is the new value in words for the entry point bound of the segment.
3282 Input If the value of entry_bound is 0 then the mechanism is
3283 disabled.
3284 code
3285 is a storage system status code. Output It can be:
3286 error_table_$argerr
3287 if an attempt is made to set the entry point bound of a segment
3288 greater than the system maximum of 16383.
3289
3290
3291 Access required:
3292 The user must have modify permission on the containing directory.
3293
3294
3295 Notes: A directory cannot have its entry point bound changed.
3296
3297 The hcs_$set_entry_bound_seg entry point can be used when a pointer to
3298 the segment is given rather than a pathname.
3299
3300
3301 :Entry: set_entry_bound_seg: 1982-03-08 hcs_$set_entry_bound_seg
3302
3303
3304 Function: given a pointer to a segment sets the entry point bound of
3305 the segment.
3306
3307 The entry point bound attribute provides a way of limiting which
3308 locations of a segment may be targets of a call. This entry point
3309 allows the caller to enable or disable a hardware check of calls to a
3310 given segment from other segments. If the mechanism is enabled all
3311 calls to the segment must be made to an entry point whose offset is
3312 less than the entry point bound.
3313
3314
3315 In practice this attribute is most effective when all of the entry
3316 points are located at the base of the segment. In this case the entry
3317 point bound is the number of callable words.
3318
3319
3320 Syntax:
3321 declare hcs_$set_entry_bound_seg entry ptr fixed bin14 fixed
3322 bin35;
3323 call hcs_$set_entry_bound_seg seg_ptr entry_bound code;
3324
3325
3326 Arguments:
3327 seg_ptr
3328 is a pointer to the segment whose entry point bound is to be
3329 changed. Input
3330 entry_bound
3331 is the new value in words for the entry point bound of the segment.
3332 Input If the value of entry_bound is 0 then the mechanism is
3333 disabled.
3334 code
3335 is a storage system status code. Output See "Notes" below.
3336
3337
3338 Notes: A directory cannot have its entry point bound changed.
3339
3340 The user must have modify permission on the containing directory.
3341
3342 If an attempt is made to set the entry point bound of a segment to
3343 greater than the system maximum of 16383 code is set to
3344 error_table_$argerr.
3345
3346 The hcs_$set_entry_bound entry point can be used when a pathname of the
3347 segment is given rather than a pointer.
3348
3349
3350 :Entry: set_exponent_control: 1982-03-08 hcs_$set_exponent_control
3351
3352
3353 Function: changes the current settings of the flags that control the
3354 system's handling of exponent overflow and underflow conditions.
3355
3356
3357 Syntax:
3358 declare hcs_$set_exponent_control entry bit1 aligned bit1
3359 aligned float bin63 fixed bin 35;
3360 call hcs_$set_exponent_control restart_underflow restart_overflow
3361 overflow_value code;
3362
3363
3364 Arguments:
3365 restart_underflow
3366 is "1"b if underflows should be automatically restarted and "0"b
3367 otherwise. Input
3368 restart_overflow
3369 is "1"b if overflows should be automatically restarted and "0"b
3370 otherwise. Input
3371 overflow_value
3372 is the value used for the result of the computation in the case of
3373 overflow. Input
3374 code
3375 is a standard status code. Output
3376
3377
3378 Notes: When either of the two flags are set to zero the corresponding
3379 error condition causes the appropriate fault condition to be signalled.
3380 If a flag is set to one then the computation resulting in the error is
3381 automatically restarted. In the case of underflow its result is set to
3382 zero. In the case of positive overflow its value is set to the value
3383 specified in overflow_value. In the case of negative overflow the
3384 negative of overflow_value is used. The default value is the largest
3385 representable positive number available as
3386 Default_exponent_control_overflow_value in the include file
3387 exponent_control.incl.pl1.
3388
3389
3390 This subroutine affects only the system's handling of exponent overflow
3391 and underflow when the overflow condition or the underflow condition is
3392 raised. In certain cases the error condition is raised instead; this
3393 subroutine does not affect the system's handling of such cases.
3394
3395 In programs not written in PL/I the exponent_control_ subroutine
3396 should be used in place of hcs_$set_exponent_control.
3397
3398
3399 :Entry: set_ips_mask: 1982-03-08 hcs_$set_ips_mask
3400
3401
3402 Function: replaces the entire ips mask with a supplied value and
3403 returns the previous value of the mask with a control bit of "1"b. It
3404 can be used at the beginning of a critical section of code to disable
3405 one or more ips interrupts and turn on the control bit to indicate
3406 that some interrupts are disabled. See "Notes" in the description of
3407 the hcs_$get_ips_mask entry point for a discussion of the control bit.
3408
3409
3410 Syntax:
3411 declare hcs_$set_ips_mask entry bit36 aligned bit36 aligned;
3412 call hcs_$set_ips_mask mask old_mask;
3413
3414
3415 Arguments:
3416 mask
3417 is the new value to replace the ips mask. Input A "1" bit in each
3418 mask position enables the corresponding ips interrupt.
3419 old_mask
3420 is the former value of the ips mask with a control bit of "1"b.
3421 Output
3422
3423
3424 Notes: The create_ips_mask_ subroutine can be used to create a mask
3425 given a set of ips names.
3426
3427 The hcs_$reset_ips_mask entry point can be used at the end of a
3428 critical section of code to undo the mask changes made by this entry
3429 point by setting the mask to the old_mask value returned by this
3430 entry point.
3431
3432
3433 :Entry: set_max_length: 1982-03-08 hcs_$set_max_length
3434
3435
3436 Function: given a directory name sets the maximum length in words
3437 of a segment.
3438
3439
3440 Syntax:
3441 declare hcs_$set_max_length entry char* char* fixed bin19
3442 fixed bin35;
3443 call hcs_$set_max_length dir_name entryname max_length code;
3444
3445
3446 Arguments:
3447 dir_name
3448 is the pathname of the containing directory. Input
3449 entryname
3450 is the entryname of the segment. Input
3451 max_length
3452 is the new value in words for the maximum length of the segment.
3453 Input
3454
3455
3456 code
3457 is a storage system status code. Output It can be:
3458 error_table_$argerr
3459 if an attempt is made to set the maximum length of a segment to
3460 greater than the system maximum sys_info$max_seg_size.
3461 error_table_$invalid_max_length
3462 if an attempt is made to set the maximum length of a segment to
3463 less than its current length.
3464
3465
3466 Access required:
3467 The user must have modify permission on the containing directory.
3468
3469
3470 Notes: A directory cannot have its maximum length changed.
3471
3472 The maximum length of a segment is accurate to units of 1024 words and
3473 if max_length is not a multiple of 1024 words it is set to the next
3474 multiple of 1024 words.
3475
3476 The hcs_$set_max_length_seg entry point can be used when the pointer to
3477 the segment is given rather than a pathname.
3478
3479
3480 :Entry: set_max_length_seg: 1982-03-08 hcs_$set_max_length_seg
3481
3482
3483 Function: given the pointer to the segment sets the maximum length
3484 in words of a segment.
3485
3486
3487 Syntax:
3488 declare hcs_$set_max_length_seg entry ptr fixed bin19 fixed
3489 bin35;
3490 call hcs_$set_max_length_seg seg_ptr max_length code;
3491
3492
3493 Arguments:
3494 seg_ptr
3495 is the pointer to the segment whose maximum length is to be changed.
3496 Input
3497 max_length
3498 is the new value in words for the maximum length of the segment.
3499 Input
3500 code
3501 is a storage system status code. Output It can be:
3502 error_table_$argerr
3503 if an attempt is made to set the maximum length of a segment to
3504 greater than the system maximum sys_info$max_seg_size.
3505 error_table_$invalid_max_length
3506 if an attempt is made to set the maximum length of a segment to
3507 less than its current length.
3508
3509
3510 Access required:
3511 The user must have modify permission on the containing directory.
3512
3513
3514 Notes: A directory cannot have its maximum length changed.
3515
3516 The maximum length of a segment is accurate to units of 1024 words and
3517 if max_length is not a multiple of 1024 words it is set to the next
3518 multiple of 1024 words.
3519
3520 The hcs_$set_max_length entry point can be used when a pathname of the
3521 segment is given rather than the pointer.
3522
3523
3524 :Entry: set_procs_required: 1987-01-16 hcs_$set_procs_required
3525
3526
3527 Function: sets the per-process CPUs required.
3528
3529
3530 Syntax:
3531 declare hcs_$set_procs_required entry bit 8 aligned
3532 fixed bin 35;
3533 call hcs_$set_procs_required procs_required code;
3534
3535
3536 Arguments:
3537 procs_required
3538 is the set of processors required. If "0"b the system default set
3539 of CPUs is assumed. Input
3540 code
3541 is a standard system error code. Output
3542
3543
3544 Access required:
3545 This operation requires rw permission on the access control segment:
3546 >sc1>admin_acs>set_proc_required.acs
3547
3548
3549 :Entry: set_ring_brackets: 1982-03-08 hcs_$set_ring_brackets
3550
3551
3552 Function: given the directory name and entryname of a nondirectory
3553 segment sets the segment's ring brackets.
3554
3555
3556 Syntax:
3557 declare hcs_$set_ring_brackets entry char* char* 3 fixed
3558 bin3 fixed bin35;
3559 call hcs_$set_ring_brackets dir_name entryname rb code;
3560
3561
3562 Arguments:
3563 dir_name
3564 is the pathname of the containing directory. Input
3565 entryname
3566 is the entryname of the segment. Input
3567 rb
3568 is a three-element array specifying the ring brackets of the
3569 segment; see "Notes" below. Input
3570 code
3571 is a storage system status code. Output
3572
3573
3574 Access required:
3575 The user must have modify permission on the containing directory.
3576 Also the validation level must be less than or equal to both the
3577 present value of the first ring bracket and the new value of the first
3578 ring bracket that the user wishes set.
3579
3580
3581 Notes: Ring brackets must be ordered as rb1 <= rb2 <= rb3
3582
3583 Ring brackets and validation levels are discussed in "Intraprocess
3584 Access Control" in the Reference Manual.
3585
3586
3587 :Entry: set_safety_sw: 1982-03-08 hcs_$set_safety_sw
3588
3589
3590 Function: allows the safety switch associated with a segment or
3591 directory to be changed. The segment is designated by a directory
3592 name and an entryname. See "Segment Directory and Link Attributes"
3593 in the Reference Manual for a description of the safety switch.
3594
3595
3596 Syntax:
3597 declare hcs_$set_safety_sw entry char* char* bit1
3598 fixed bin35;
3599 call hcs_$set_safety_sw dir_name entryname safety_sw code;
3600
3601
3602 Arguments:
3603 dir_name
3604 is the pathname of the containing directory. Input
3605 entryname
3606 is the entryname of the segment or directory. Input
3607 safety_sw
3608 is the new value of the safety switch. Input
3609 "0"b if the segment can be deleted
3610 "1"b if the segment cannot be deleted
3611 code
3612 is a storage system status code. Output
3613
3614
3615 Access required:
3616 The user must have modify permission on the containing directory.
3617
3618
3619 Notes: The hcs_$set_safety_sw_seg entry point can be used when the
3620 pointer to the segment is given rather than a pathname.
3621
3622
3623 :Entry: set_safety_sw_seg: 1982-03-08 hcs_$set_safety_sw_seg
3624
3625
3626 Function: given a pointer to a segment sets the safety switch of the
3627 segment. See "Segment Directory and Link Attributes" in the
3628 Reference Manual for a description of the safety switch.
3629
3630
3631 Syntax:
3632 declare hcs_$set_safety_sw_seg entry ptr bit1 fixed bin35;
3633 call hcs_$set_safety_sw_seg seg_ptr safety_sw code;
3634
3635
3636 Arguments:
3637 seg_ptr
3638 is the pointer to the segment. Input
3639 safety_sw
3640 is the new value of the safety switch. Input
3641 "0"b if the segment can be deleted
3642 "1"b if the segment cannot be deleted
3643 code
3644 is a storage system status code. Output
3645
3646
3647 Access required:
3648 The user must have modify permission on the containing directory.
3649
3650
3651 Notes: The hcs_$set_safety_sw entry point can be used when a pathname
3652 of the segment is given rather than the pointer.
3653
3654
3655 :Entry: star_: 1982-03-08 hcs_$star_
3656
3657
3658 Function: is the star convention handler for the storage system. See
3659 "Constructing and Interpreting Names" in the Reference Manual.
3660 It is called with a directory name and an entryname that is a
3661 star name contains asterisks or question marks. The directory is
3662 searched for all entries that match the given entryname. Information
3663 about these entries is returned in a structure. If the entryname is
3664 ** information on all entries in the directory is returned.
3665
3666 The hcs_$star_ entry point returns the storage system type and all
3667 names that match the given entryname.
3668
3669
3670 Syntax:
3671 declare hcs_$star_ entry char* char* fixed bin2 ptr
3672 fixed bin ptr ptr fixed bin35;
3673 call hcs_$star_ dir_name star_name star_select_sw area_ptr
3674 star_entry_count star_entry_ptr star_names_ptr code;
3675
3676
3677 Arguments:
3678 dir_name
3679 is the pathname of the containing directory. Input
3680 star_name
3681 is the entryname that can contain asterisks or question marks.
3682 Input
3683 star_select_sw
3684 indicates what information is to be returned. Input It can be:
3685 star_LINKS_ONLY =1
3686 information is returned about link entries only
3687 star_BRANCHES_ONLY =2
3688 information is returned about segment and directory entries only
3689 star_ALL_ENTRIES =3
3690 information is returned about segment directory and link
3691 entries.
3692
3693
3694 area_ptr
3695 is a pointer to the area in which information is to be returned.
3696 Input If the pointer is null star_entry_count is set to the total
3697 number of entries in the directory that match star_name.
3698 star_entry_count
3699 is a count of the number of entries that match the entryname.
3700 Output
3701 star_entry_ptr
3702 is a pointer to the allocated structure in which information on
3703 each entry is returned. Output See "Notes" below. This data
3704 structure is declared in star_structures.incl.pl1.
3705 star_names_ptr
3706 is a pointer to the allocated array of all the entrynames in this
3707 directory that match star_name. Output See "Notes" below.
3708
3709
3710 code
3711 is a storage system status code. Output It can be:
3712 error_table_$nomatch
3713 if no match with star_name was found in the directory.
3714 error_table_$badstar
3715 if star_name contained illegal syntax with respect to the star
3716 convention.
3717 error_table_$notalloc
3718 if the user did not provide enough space in the area to return
3719 all requested information. In this case the total number of
3720 entries will be returned to provide an estimate of space
3721 required.
3722
3723
3724 Access required:
3725 Status permission is required on the directory to be searched.
3726
3727
3728 Notes: If area_ptr is null star_entry_count is set to the total
3729 number of entries in the directory that match star_name. The setting
3730 of star_select_sw determines whether star_entry_count is the total
3731 number of link entries the total number of segment and directory
3732 entries or the total number of all entries.
3733
3734 If area_ptr is not null the entry information structure and the name
3735 array are allocated in the user-supplied area.
3736
3737
3738 A program using star_structures.incl.pl1 should declare addr binary
3739 and sum to be builtin. The arguments star_entry_count star_entry_ptr
3740 and star_names_ptr are declared in the include file along with named
3741 constants for the value of star_select_sw and the storage system type.
3742 One of the named constants for star_select_sw can be passed as an
3743 argument to hcs_$star_ along with star_entry_count star_entry_ptr and
3744 star_names_ptr.
3745
3746
3747 :Entry: star_list_: 1982-03-08 hcs_$star_list_
3748
3749
3750 Function: returns more information about the selected entries such as
3751 the mode and records used for segments and directories and link
3752 pathnames for links. This entry point obtains the records used and
3753 the date of last modification and last use from the VTOC and is
3754 therefore more expensive to use than the hcs_$star_dir_list_ entry
3755 point.
3756
3757
3758 Syntax:
3759 declare hcs_$star_list_ entry char* char* fixed bin3 ptr
3760 fixed bin fixed bin ptr ptr fixed bin35;
3761 call hcs_$star_list_ dir_name star_name star_select_sw area_ptr
3762 star_branch_count star_link_count star_list_branch__ptr
3763 star_list_names_ptr code;
3764
3765
3766 Arguments:
3767 dir_name
3768 is the pathname of the containing directory. Input
3769 star_name
3770 is the entryname that can contain asterisks or question marks.
3771 Input
3772
3773
3774 star_select_sw
3775 indicates what information is to be returned. Input All of the
3776 following are declared in star_structures.incl.pl1:
3777 star_LINKS_ONLY =1
3778 star_BRANCHES_ONLY =2
3779 star_ALL_ENTRIES =3
3780 star_LINKS_ONLY_WITH_LINK_PATHS =5
3781 star_ALL_ENTRIES_WITH_LINK_PATHS =7
3782
3783
3784 area_ptr
3785 is a pointer to the area in which information is to be
3786 returned. Input If the pointer is null star_branch_count
3787 and star_link_count are set to the total number of selected
3788 entries. See "Notes" below.
3789 star_branch_count
3790 is a count of the number of segments and directories that match
3791 star_name. Output
3792 star_link_count
3793 is a count of the number of links that match star_name.
3794 Output
3795
3796
3797 star_list_branch_ptr
3798 is a pointer to the allocated structure in which information on
3799 each entry is returned. Output The star_list_branch structure
3800 is used if the entry is a segment or a directory. The star_links
3801 structure is used if the entry is a link. Both are declared in
3802 star_structures.incl.pl1.
3803 star_list_names_ptr
3804 is a pointer to the allocated array in which selected entrynames
3805 and pathnames associated with link entries are stored. Output
3806 The star_list_names structure is the array of names. It is
3807 declared in star_structures.incl.pl1.
3808
3809
3810 code
3811 is a storage system status code. Output It can be:
3812 error_table_$nomatch
3813 if no match with star_name was found in the directory.
3814 error_table_$badstar
3815 if star_name contained illegal syntax with respect to the star
3816 convention.
3817 error_table_$notalloc
3818 if the user did not provide enough space in the area to return
3819 all requested information. In this case the total number of
3820 entries will be returned to provide an estimate of space
3821 required.
3822
3823
3824 Notes: If the system is unable to access the VTOC entry for a branch
3825 values of zero are returned for records used
3826 date_time_contents_modified and date_time_used and no error code is
3827 returned. Callers of this entry point should interpret zeros for all
3828 three of these values as an error indication rather than as valid
3829 data.
3830
3831
3832 A program using star_structures.incl.pl1 should declare addr binary
3833 and sum to be builtin. The star_branch_count star_entry_ptr
3834 star_link_count star_linkx star_list_names_ptr and star_select_sw
3835 variables are declared in the include file along with named constants
3836 for the value of star_select_sw and the storage system type.
3837
3838 To use the structures in the include file first assign to
3839 star_select_sw the proper named constant and then pass star_select_sw
3840 as an argument to hcs_$star_list_ along with star_branch_count
3841 star_link_count star_list_branch_ptr and star_list_names_ptr.
3842
3843
3844 The star_link_pathname based variable is used to get the pathname
3845 associated with link star_linkx in the star_links array. It is
3846 declared in star_structures.incl.pl1. To get the link pathname
3847 associated with a link assign to star_linkx the index of the link in
3848 star_links. Star_link_pathname will then be link pathname.
3849
3850
3851 :Entry: star_dir_list_: 1985-03-06 hcs_$star_dir_list_
3852
3853
3854 Function:
3855 This entry point returns information about the selected entries such
3856 as the mode and bit count for branches and link pathnames for links.
3857 It returns only information kept in directory branches and does not
3858 access the VTOC entries for branches. This entry point is more
3859 efficient than the hcs_$star_list_ entry point.
3860
3861
3862 Syntax:
3863 declare hcs_$star_dir_list_ entry char* char* fixed bin2 ptr
3864 fixed bin fixed bin ptr ptr fixed bin35;
3865 call hcs_$star_dir_list_ dir_name star_name star_select_sw
3866 area_ptr star_branch_count star_link_count
3867 star_list_branch_ptr star_list_names_ptr code;
3868
3869
3870 Arguments:
3871 dir_name
3872 is the pathname of the containing directory. Input
3873 star_name
3874 is the entryname that can contain asterisks or question marks.
3875 Input
3876 star_select_sw
3877 indicates what information is to be returned. Input It can be:
3878 star_LINKS_ONLY =1
3879 information is returned about link entries only.
3880 star_BRANCHES_ONLY =2
3881 information is returned about segment and directory entries only.
3882 star_ALL_ENTRIES =3
3883 information is returned about segment directory and link
3884 entries.
3885
3886
3887 star_LINKS_ONLY_WITH_LINK_PATHS =5
3888 information is returned about link entries only including the
3889 pathname associated with each link entry.
3890 star_ALL_ENTRIES_WITH_LINK_PATHS =7
3891 information is returned about segment directory and link
3892 entries including the pathname associated with each link entry.
3893 area_ptr
3894 is a pointer to the area in which information is to be returned. If
3895 the pointer is null star_branch_count and star_link_count are set
3896 to the total number of selected entries. See "Notes" below.
3897 Input
3898 star_branch_count
3899 is a count of the number of segments and directories that match the
3900 entryname. Output
3901
3902
3903 star_link_count
3904 is a count of the number of links that match the entryname.
3905 Output
3906 star_list_branch_ptr
3907 is a pointer to the allocated structure in which information on each
3908 entry is returned. Output
3909 star_list_names_ptr
3910 is a pointer to the allocated array in which selected entrynames and
3911 pathnames associated with link entries are stored. Output
3912 code
3913 is a storage system status code. See "Status Codes" above in the
3914 description of hcs_$star_ entry point. Output
3915
3916
3917 Notes: The names star_LINKS_ONLY through
3918 STAR_ALL_ENTRIES_WITH_LINK_PATHS are declared in
3919 star_structures.incl.pl1. The star_LINKS_ONLY star_BRANCHES_ONLY and
3920 star_ALL_ENTRIES are declared fixed bin 2 for compatability with
3921 hcs_$star and the star_LINKS_ONLY_WITH_LINK_PATHS and
3922 star_ALL_ENTRIES_WITH_LINK_PATHS are declared as fixed bin 3.
3923
3924 If area_ptr is null star_branch_count and star_link_count may be
3925 set. If information on segments and directories is requested
3926 star_branch_count is set to the total number of segments and
3927 directories that match star_name. If information on links is
3928 requested star_link_count is the total number of links that match
3929 star_name.
3930
3931
3932 If area_ptr is not null an array of entry information structures and
3933 the names array as described in the hcs_$star_ entry point above are
3934 allocated in the user-supplied area. Each element in the structure
3935 array may be either of the structures described below the star_links
3936 structure for links or the star_list_branch structure for segments and
3937 directories. The correct structure is indicated by the type item the
3938 first item in both structures.
3939
3940 If the system is unable to access the VTOC entry for a branch values
3941 of zero are returned for records used date_time_contents_modified and
3942 date_time_used and no error code is returned. Callers of this entry
3943 point should interpret zeros for all three of these values as an error
3944 indication rather than as valid data.
3945
3946
3947 The star_links structure described for hcs_$star_list is used
3948 if the entry is a link.
3949
3950
3951 :Entry: status_: 2022-08-26 hcs_$status_
3952
3953
3954 Function: returns the most often needed information about a specified
3955 directory entry. Other entry points hcs_$status_long
3956 hcs_$status_minf hcs_$status_mins return more or less detailed
3957 information and should be selected as the user requires.
3958
3959
3960 Syntax:
3961 declare hcs_$status_ entry char* char* fixed bin1 ptr ptr
3962 fixed bin35;
3963 call hcs_$status_ dir_name entryname chase_sw status_ptr
3964 status_area_ptr code;
3965
3966
3967 Arguments:
3968 dir_name
3969 is the pathname of the containing directory. Input
3970 entryname
3971 is the entryname of the segment directory or link. Input
3972 chase_sw
3973 indicates whether the information returned is about a link or about
3974 the entry to which the link points. Input
3975 0 returns link information
3976 1 returns information about the entry to which the link points
3977
3978
3979 status_ptr
3980 is a pointer to the structure in which information is returned.
3981 Input If the entry is a link it points to the status_link
3982 structure. If the entry is a segment directory or multisegment
3983 file it points to the status_branch structure. Both are defined
3984 in status_structures.incl.pl1.
3985 status_area_ptr
3986 is a pointer to the area in which names are returned. Input If
3987 the pointer is null no names are returned.
3988 code
3989 is a storage system status code. Output
3990
3991
3992 Access required:
3993 The user must have either status permission on the containing directory
3994 or nonnull access to the object to obtain complete information.
3995 Entrynames however are not returned unless the user has status
3996 permission on the containing directory.
3997
3998
3999 Notes: For compatability with older programs if entryname is given as
4000 a null string status is returned on the directory given as dir_name.
4001
4002
4003 :Entry: status_long: 2022-08-26 hcs_$status_long
4004
4005
4006 Function: returns most user-accessible information about a specified
4007 entry.
4008
4009
4010 Syntax:
4011 declare hcs_$status_long entry char* char* fixed bin1 ptr
4012 ptr fixed bin35;
4013 call hcs_$status_long dir_name entryname chase_sw status_ptr
4014 status_area_ptr code;
4015
4016
4017 Arguments:
4018 dir_name
4019 is the pathname of the containing directory. Input
4020 entryname
4021 is the entryname of the segment directory or link. Input
4022 chase_sw
4023 indicates whether the information returned is about a link or about
4024 the entry to which the link points. Input
4025 0 returns link information
4026 1 returns information about the entry to which the link points
4027
4028
4029 status_ptr
4030 is a pointer to the structure in which information is returned.
4031 Input If the entry is a link it points to the status_link
4032 structure. If the entry is a segment directory or multisegment
4033 file it points to the status_branch structure. Both are defined
4034 in status_structures.incl.pl1.
4035 status_area_ptr
4036 is a pointer to the area in which names are returned. Input If
4037 the pointer is null no names are returned.
4038 code
4039 is a storage system status code. Output
4040
4041
4042 Access required:
4043 The user must have either status permission on the containing directory
4044 or nonnull access to the object to obtain complete information.
4045 Entrynames however are not returned unless the user has status
4046 permission on the containing directory.
4047
4048
4049 Notes: For compatability with older programs if entryname is given as
4050 a null string status is returned on the directory given as dir_name.
4051
4052
4053 :Entry: status_minf: 1982-03-08 hcs_$status_minf
4054
4055
4056 Function: returns the bit count and entry type given the name of a
4057 directory and an entry. Status permission on the directory or nonnull
4058 access on the entry is required to use this entry point.
4059
4060
4061 Syntax:
4062 declare hcs_$status_minf entry char* char* fixed bin1
4063 fixed bin2 fixed bin24 fixed bin35;
4064 call hcs_$status_minf dir_name entryname chase_sw type bit_count
4065 code;
4066
4067
4068 Arguments:
4069 dir_name
4070 is the pathname of the containing directory. Input
4071 entryname
4072 is the entryname of the segment directory or link. Input
4073 chase_sw
4074 indicates whether the information returned is about a link or about
4075 the entry to which the link points. Input
4076 0 returns link information
4077 1 returns information about the entry to which the link points
4078
4079
4080 type
4081 specifies the type of entry. Output It can be:
4082 0 link
4083 1 segment
4084 2 directory
4085 bit_count
4086 is the bit count. Output
4087 code
4088 is a storage system status code. Output
4089
4090
4091 :Entry: status_mins: 1982-03-08 hcs_$status_mins
4092
4093
4094 Function: returns the bit count and entry type given a pointer to the
4095 segment. Status permission on the directory or nonnull access to the
4096 segment is required to use this entry point.
4097
4098
4099 Syntax:
4100 declare hcs_$status_mins entry ptr fixed bin2 fixed bin24
4101 fixed bin35;
4102 call hcs_$status_mins seg_ptr type bit_count code;
4103
4104
4105 Arguments:
4106 seg_ptr
4107 points to the segment about which information is desired. Input
4108 type
4109 specifies the type of entry. Output It can be:
4110 0 link
4111 1 segment
4112 2 directory
4113 bit_count
4114 is the bit count. Output
4115 code
4116 is a storage system status code. Output
4117
4118
4119 :Entry: terminate_noname: 1982-03-08 hcs_$terminate_noname
4120
4121
4122 Function: terminates a null reference name from the specified segment
4123 and decrements a count of initiated reference names for the segment.
4124
4125
4126 Syntax:
4127 declare hcs_$terminate_noname entry ptr fixed bin35;
4128 call hcs_$terminate_noname seg_ptr code;
4129
4130
4131 Arguments:
4132 seg_ptr
4133 is a pointer to the segment. Input/Output
4134 code
4135 is a storage system status code. Output
4136
4137
4138 Notes: If a segment is concurrently initiated more than a
4139 system-defined number of times the usage count of the segment is said
4140 to be in an overflowed condition. Under such circumstances the
4141 hcs_$terminate_noname entry point does not reduce the usage count but
4142 leaves the segment in the overflowed state. To terminate the segment
4143 hcs_$terminate_file or hcs_$terminate_seg should be used.
4144
4145
4146 If the hcs_$terminate_noname entry point reduces the count of initiated
4147 reference names of the segment to zero the segment is removed from the
4148 address space of the process made unknown. This entry point is used
4149 to clean up after making a segment known and initiating a single null
4150 reference name; see also the hcs_$initiate hcs_$initiate_count and
4151 hcs_$make_seg entry points. For a discussion of reference names see
4152 "Constructing and Interpreting Names" in the Reference Manual.
4153
4154
4155 The hcs_$terminate_name entry point terminates a specified nonnull
4156 reference name; hcs_$terminate_file and hcs_$terminate_seg entry points
4157 terminate all reference names of a segment and make the segment
4158 unknown given its pathname or segment number respectively.
4159
4160
4161 :Entry: terminate_file: 1982-03-08 hcs_$terminate_file
4162
4163
4164 Function: given the pathname of a segment terminates all the
4165 reference names of that segment and then removes the segment from the
4166 address space of the process makes the segment unknown. For a
4167 discussion of reference names see "Constructing and Interpreting
4168 Names" in the Reference Manual.
4169
4170
4171 Syntax:
4172 declare hcs_$terminate_file entry char* char* fixed bin1
4173 fixed bin35;
4174 call hcs_$terminate_file dir_name entryname seg_sw code;
4175
4176
4177 Arguments:
4178 dir_name
4179 is the pathname of the containing directory. Input
4180 entryname
4181 is the entryname of the segment. Input
4182 seg_sw
4183 is the reserved segment switch. Input
4184 1 saves segment number in the reserved segment list
4185 0 does not save segment number
4186 code
4187 is a storage system status code. Output
4188
4189
4190 Notes: The hcs_$terminate_seg entry point performs the same operation
4191 given a pointer to a segment instead of a pathname; the
4192 hcs_$terminate_name and hcs_$terminate_noname entry points terminate a
4193 single reference name.
4194
4195 The term_ subroutine performs the same operation as the
4196 hcs_$terminate_file entry point but in addition causes links to the
4197 entry's linkage section to be unsnapped. Use of the term_ subroutine
4198 is recommended.
4199
4200
4201 The reference names that are removed are those for which the ring level
4202 associated with the name is greater than or equal to the validation
4203 level of the process. If any reference names exist that are associated
4204 with a ring level less than the validation level of the process the
4205 segment is not made unknown and the code is returned as
4206 error_table_$bad_ring_brackets. For a discussion of rings refer to
4207 "Intraprocess Access Control" in the Reference Manual.
4208
4209
4210 :Entry: terminate_name: 1982-03-08 hcs_$terminate_name
4211
4212
4213 Function: terminates one reference name from a segment and decrements
4214 a count of initiated reference names for the segment.
4215
4216
4217 Syntax:
4218 declare hcs_$terminate_name entry char* fixed bin35;
4219 call hcs_$terminate_name ref_name code;
4220
4221
4222 Arguments:
4223 ref_name
4224 is the reference name to be terminated. Input
4225 code
4226 is a storage system status code. Output
4227
4228
4229 Notes: If a segment is concurrently initiated more than a
4230 system-defined number of times the usage count of the segment is said
4231 to be in an overflowed condition. Under such circumstances the
4232 hcs_$terminate_name entry point does not reduce the usage count but
4233 leaves the segment in the overflowed state. To terminate the segment
4234 hcs_$terminate_file or hcs_$terminate_seg should be used.
4235
4236
4237 If the hcs_$terminate_name entry point reduces the count of initiated
4238 reference names for that segment to zero the segment is removed from
4239 the address space of the process made unknown. For a discussion of
4240 reference names see "Constructing and Interpreting Names" in
4241 the Reference Manual.
4242
4243
4244 The hcs_$terminate_noname entry point terminates a null reference name
4245 from a specified segment; the hcs_$terminate_file and
4246 hcs_$terminate_seg entry points terminate all reference names of a
4247 segment and make the segment unknown given its pathname or segment
4248 number respectively.
4249
4250
4251 The term_$single_refname entry point see the description of the term_
4252 subroutine performs the same operation as the hcs_$terminate_name
4253 entry point unsnapping links as well. Use of the term_ subroutine is
4254 recommended.
4255
4256
4257 :Entry: terminate_seg: 1982-03-08 hcs_$terminate_seg
4258
4259
4260 Function: given a pointer to a segment in the current process
4261 terminates all the reference names of that segment and then removes
4262 the segment from the address space of the process makes it unknown.
4263 For a discussion of reference names see the "Constructing and
4264 Interpreting Names" in the Reference Manual.
4265
4266
4267 Syntax:
4268 declare hcs_$terminate_seg entry ptr fixed bin1 fixed bin35;
4269 call hcs_$terminate_seg seg_ptr seg_sw code;
4270
4271
4272 Arguments:
4273 seg_ptr
4274 is a pointer to the segment to be terminated. Input
4275 seg_sw
4276 is the reserved segment switch. Input
4277 1 saves segment number in reserved segment list
4278 0 does not save segment number
4279 code
4280 is a storage system status code. Output
4281
4282
4283 Notes: The hcs_$terminate_file entry point performs the same operation
4284 given the pathname of a segment instead of a pointer; the
4285 hcs_$terminate_name and hcs_$terminate_noname entry points terminate a
4286 single reference name.
4287
4288
4289 The term_$seg_ptr entry point see the term_ subroutine description
4290 performs the same operation as the hcs_$terminate_seg entry point
4291 unsnapping links as well. Use of the term_ subroutine is recommended.
4292
4293
4294 The only reference names that are removed are those for which the ring
4295 level associated with the name is greater than or equal to the
4296 validation level of the process. If any reference names exist that are
4297 associated with a ring level less than the validation level of the
4298 process the segment is not made unknown and the code is returned as
4299 error_table_$bad_ring_brackets. For a discussion of rings refer to
4300 "Intraprocess Access Control" in the Reference Manual.
4301
4302
4303 :Entry: truncate_file: 1982-03-08 hcs_$truncate_file
4304
4305
4306 Function: given a pathname truncates a segment to a specified
4307 length. If the segment is already shorter than the specified length
4308 no truncation is done. The effect of truncating a segment is to store
4309 zeros in the words beyond the specified length.
4310
4311
4312 Syntax:
4313 declare hcs_$truncate_file entry char* char* fixed bin19
4314 fixed bin35;
4315 call hcs_$truncate_file dir_name entryname length code;
4316
4317
4318 Arguments:
4319 dir_name
4320 is the pathname of the containing directory. Input
4321 entryname
4322 is the entryname of the segment. Input
4323 length
4324 is the new length of the segment in words. Input
4325 code
4326 is a storage system status code. Output
4327
4328
4329 Access required:
4330 The user must have write access on the segment in order to
4331 truncate it.
4332
4333
4334 Notes: A directory cannot be truncated. A segment is truncated as
4335 follows: all full pages after the page containing the last word of the
4336 new length segment as defined by the length argument are discarded.
4337 The remainder of the page containing the last word is converted to
4338 zeros.
4339
4340 Bit count is not automatically set by the hcs_$truncate_file entry
4341 point. If desired bit count may be set by using the hcs_$set_bc entry
4342 point.
4343
4344 The hcs_$truncate_seg entry point performs the same function when given
4345 a pointer to the segment instead of the pathname.
4346
4347
4348 :Entry: truncate_seg: 1982-03-08 hcs_$truncate_seg
4349
4350
4351 Function: given a pointer truncates a segment to a specified length.
4352 If the segment is already shorter than the specified length no
4353 truncation is done. The effect of truncating a segment is to store
4354 zeros in the words beyond the specified length.
4355
4356
4357 Syntax:
4358 declare hcs_$truncate_seg entry ptr fixed bin19 fixed bin35;
4359 call hcs_$truncate_seg seg_ptr length code;
4360
4361
4362 Arguments:
4363 seg_ptr
4364 is a pointer to the segment to be truncated. Input Only the
4365 segment number portion of the pointer is used.
4366 length
4367 is the new length of the segment in words. Input
4368 code
4369 is a storage system status code. Output
4370
4371
4372 Access required: The user must have write access on the segment in
4373 order to truncate it.
4374
4375
4376 Notes: A directory cannot be truncated. A segment is truncated as
4377 follows: all full pages after the page containing the last word of the
4378 new length as defined by the length argument segment are discarded.
4379 The remainder of the page containing the last word is converted to
4380 zeros.
4381
4382 Bit count is not automatically set by the hcs_$truncate_seg entry
4383 point. If desired bit count may be set by using the hcs_$set_bc_seg
4384 entry point.
4385
4386 The hcs_$truncate_file entry point performs the same function when
4387 given the pathname of the segment instead of the pointer.
4388
4389
4390 :Entry: validate_processid: 1985-03-05 hcs_$validate_processid
4391
4392
4393 Function:
4394 This entry determines whether a 36-bit quantity is the unique
4395 identifier of a process which is currently active on the system.
4396
4397
4398 Syntax:
4399 declare hcs_$validate_processid entry bit36 aligned fixed bin35;
4400 call hcs_$validate_processid processid code;
4401
4402
4403 Arguments:
4404 processid
4405 contains a quantity which may be the unique identifier of an active
4406 process. Input
4407 code
4408 is a standard status code. Output If processid is the unique
4409 identifier of an active process the value returned is zero.
4410 Otherwise the value is error_table_$process_unknown.
4411
4412
4413 :Entry: unmask_ips: 1982-03-08 hcs_$unmask_ips
4414
4415
4416 Function: masks off or disables the specified ips interrupts. This
4417 entry point can be used at the beginning of a critical section of
4418 code to disable one or more ips interrupts and turn on the control
4419 bit as an indication that some interrupts are disabled. See "Notes"
4420 in the description of the hcs_$mask_ips entry point for a discussion
4421 of the control bit.
4422
4423
4424 Syntax:
4425 declare hcs_$unmask_ips entry bit36 aligned bit36 aligned;
4426 call hcs_$unmask_ips mask old_mask
4427
4428
4429 Arguments:
4430 mask
4431 is a word containing a "1"b for each ips interrupt that is to be
4432 disabled. Input See "Notes".
4433 old_mask
4434 is the former value of the ips mask with a control bit of "1"b.
4435 Output
4436
4437
4438 Notes: The create_ips_mask_ subroutine can be used to create a mask
4439 given a set of ips names.
4440
4441 The hcs_$mask_ips entry point can be used at the end of a critical
4442 section of code to undo the mask changes made by this entry point.
4443
4444
4445 :Entry: wakeup: 1982-03-08 hcs_$wakeup
4446
4447
4448 Function: sends an interprocess communication wakeup signal to a
4449 specified process over a specified event channel. If that process has
4450 previously called the ipc_$block entry point it is awakened. See the
4451 ipc_ subroutine description.
4452
4453
4454 Syntax:
4455 declare hcs_$wakeup entry bit36 aligned fixed bin71
4456 fixed bin71 fixed bin35;
4457 call hcs_$wakeup process_id channel_id message code;
4458
4459
4460 Arguments:
4461 process_id
4462 is the process identifier of the target process. Input
4463 channel_id
4464 is the identifier of the event channel over which the wakeup is to
4465 be sent. Input
4466 message
4467 is the event message to be interpreted by the target process.
4468 Input
4469 code
4470 is a standard status code. Output
4471
4472
4473 :hcom:
4474 /****^ HISTORY COMMENTS:
4475 1 change2022-08-26GDixon approve2022-09-03MCR10121
4476 audit2022-09-03Swenson install2022-09-03MR12.8-1033:
4477 A Add documentation for hcs_$status_ omitted from earlier hcs_.info
4478 versions.
4479 B) Correct description of hcs_$status_long status_ptr argument.
4480 C) Correct errors found by verify_info command.
4481 END HISTORY COMMENTS */