1 08/28/86 forum_
2
3
4 The forum_ subroutine provides a subroutine interface to the Forum
5 interactive meeting system.
6
7
8 Entry points in forum_:
9 List is generated by the help command
10
11
12
13 :Entry: accept_notifications: 03/06/85 forum_$accept_notifications
14
15
16 Function: This entry turns on reception of forum notifications by the
17 calling process.
18
19
20 Syntax:
21 declare forum_$accept_notifications entry fixed bin35;
22 call forum_$accept_notifications status;
23
24
25 Arguments:
26 status
27 is a standard status code. Output It can have the following
28 value:
29 forum_error_table_$no_notify_seg
30 The notifications database could not be initiated.
31
32
33 :Entry: change_chairman: 03/06/85 forum_$change_chairman
34
35
36 Function: This entry is used to change the chairman of a Forum
37 meeting.
38
39
40 Syntax:
41 declare forum_$change_chairman entry char* char* char* fixed
42 bin35;
43 call forum_$change_chairman dirname entryname chairman status;
44
45
46 Arguments:
47 dirname
48 is the pathname of the directory containing the meeting. Input
49 entryname
50 is the name of the meeting. The ".forum" suffix is required.
51 Input
52 chairman
53 is the name of the new chairman of the meeting, in the form
54 Person.Project. The new chairman must already be a participant.
55 Input
56
57
58 status
59 is a standard status code. Output It can have one of the
60 following values:
61 forum_error_table_$chairman_only
62 The caller is not the current chairman.
63 forum_error_table_$no_such_user
64 The supplied new chairman is not a participant.
65
66
67 :Entry: change_chairman_idx: 03/06/85 forum_$change_chairman_idx
68
69
70 Function: This entry changes the chairman of a Forum meeting. It is
71 the same as the change_chairman entry point except that a forum_idx is
72 used to identify the meeting instead of a pathname.
73
74
75 Syntax:
76 declare forum_$change_chairman_idx entry fixed bin char*
77 fixed bin35;
78 call forum_$change_chairman_idx forum_idx chairman status;
79
80
81 Arguments:
82 forum_idx
83 identifies a meeting opened by forum_$open_forum. Input
84 chairman
85 is the name of the new chairman of the meeting, in the form
86 Person.Project. The new chairman must already be a participant.
87 Input
88 status
89 is a standard status code. Output It can have one of the
90 following values:
91 forum_error_table_$chairman_only
92 The caller is not the current chairman.
93 forum_error_table_$no_such_user
94 The supplied new chairman is not a participant.
95
96
97 :Entry: chname_forum: 03/06/85 forum_$chname_forum
98
99
100 Function: This entry is used to change the names of Forum meetings.
101
102
103 Syntax:
104 declare forum_$chname_forum entry char* char* char* char*
105 fixed bin35;
106 call forum_$chname_forum dirname entryname old_name new_name
107 status;
108
109
110 Arguments:
111 dirname
112 is the pathname of the directory containing the meeting. Input
113 entryname
114 is the name of the meeting. The ".forum" suffix is required.
115 Input
116 old_name
117 is a name to be removed from the meeting, or blank if no name is to
118 be removed. If non-blank, ".forum" suffix is required. Input
119 new_name
120 is a name to be added to the meeting, or blank if no name is to be
121 added. If non-blank, the ".forum" suffix is required. Input
122 status
123 is a standard status code. Output
124
125
126 :Entry: chname_forum_idx: 03/06/85 forum_$chname_forum_idx
127
128
129 Function: This entry is used to change the names of Forum meetings.
130 It is the same as the chname_forum entry point except that a forum_idx
131 is used to identify the meeting instead of a pathname.
132
133
134 Syntax:
135 declare forum_$chname_forum_idx entry fixed bin char* char*
136 fixed bin35;
137 call forum_$chname_forum_idx forum_idx old_name new_name status;
138
139
140 Arguments:
141 forum_idx
142 identifies a meeting opened by forum_$open_forum. Input
143 old_name
144 is a name to be removed from the meeting, or blank if no name is to
145 be removed. If non-blank, the ".forum" suffix is required. Input
146 new_name
147 is a name to be added to the meeting, or blank if no name is to be
148 added. If non-blank, the ".forum" suffix is required. Input
149 status
150 is a standard status code. Output
151
152
153 :Entry: create_forum: 03/06/85 forum_$create_forum
154
155
156 Function: Creates a Forum meeting with the user as chairman.
157
158
159 Syntax:
160 declare forum_$create_forum entry char* char* fixed bin35;
161 call forum_$create_forum dirname entryname status;
162
163
164 Arguments:
165 dirname
166 is the pathname of the directory containing the meeting. Input
167 entryname
168 is the name of the meeting. The ".forum" suffix is required.
169 Input
170 status
171 is a standard status code.
172
173
174 Access required:
175 The caller must have modify permission on the containing directory.
176
177
178 :Entry: set_v1_forum_acl: 03/06/85 forum_$set_v1_forum_acl
179
180
181 Function: This entry is valid only for meetings created with pre-MR11
182 software. This entry is used to add or change an ACL term. ACL terms
183 can only be specified for Person_id.* or *.Project_id, terms of the
184 form Person_id.Project_id are not allowed.
185
186
187 Syntax:
188 declare forum_$set_v1_forum_acl entry fixed bin char* bit1
189 aligned bit1 aligned bit1 aligned fixed bin35;
190 call forum_$set_v1_forum_acl forum_idx access_name user_sw set_sw
191 write_sw status;
192
193
194 Arguments:
195 forum_idx
196 identifies a meeting opened by forum_$open_forum. Input
197 access_name
198 The Person_id or Project_id whose ACL is to be added or deleted.
199 Access_name can not contain a ".". Input
200 user_sw
201 This switch should be on if access_name is a Person_id, and off if
202 it is a Project_id. Input
203
204
205 set_sw
206 This switch should on if access is to be added, and off if it is to
207 be deleted. Input
208 write_sw
209 This switch should on if write access is to be added, and off if
210 only read access is to be added. This switch is ignored if set_sw
211 is off. Input
212 status
213 is a standard status code. Output
214
215
216 Access required:
217 The caller must have modify permission on the containing directory.
218
219
220 :Entry: v1_expunge: 03/06/85 forum_$v1_expunge
221
222
223 Function: This entry is used to physically remove deleted participant
224 records and deleted transactions from a Forum meeting. This results in
225 reclaimed storage space.
226
227
228 Syntax:
229 declare forum_$v1_expunge entry fixed bin bit 36 aligned
230 fixed bin fixed bin fixed bin fixed bin fixed bin35;
231 call forum_$v1_expunge forum_idx switches users_deleted
232 trans_deleted users_damaged trans_damaged status;
233
234
235 Arguments:
236 forum_idx
237 identifies a meeting opened by forum_$open_forum. Input
238 switches
239 is a word of switches as follows: Input
240 transactions
241 if set, deleted transactions should be expunged.
242 users
243 if set, deleted participant records should be expunged.
244
245
246 users_deleted
247 is the number of participant records which were expunged. Output
248 trans_deleted
249 is the number of transactions which were expunged. Output
250 users_damaged
251 is the number of participant records which were expunged because
252 they were inconsistent. Output
253 trans_damaged
254 is the number of transactions which were expunged because they were
255 inconsistent. Output
256 status
257 is a standard status code. Output
258
259
260 :Entry: check_user: 03/06/85 forum_$check_user
261
262
263 Function: This entry is used to determine if a user is a participant
264 in a Forum meeting.
265
266
267 Syntax:
268 declare forum_$check_user entry fixed bin char* fixed bin fixed
269 bin35;
270 call forum_$check_user forum_idx user_name last_entered status;
271
272
273 Arguments:
274 forum_idx
275 identifies a meeting opened by forum_$open_forum. Input
276 user_name
277 The Person_id of the user to be checked. Input
278 last_entered
279 is the index of the most recent transaction entered by this user, or
280 0 if this user has never entered a transaction. Output
281 status
282 is a standard status code. Output
283
284
285 :Entry: close_forum: 03/06/85 forum_$close_forum
286
287
288 Function: This entry closes a meeting opened by forum_$open_forum.
289
290
291 Syntax:
292 declare forum_$close_forum entry fixed bin fixed bin35;
293 call forum_$close_forum forum_idx status;
294
295
296 Arguments:
297 forum_idx
298 identifies a meeting opened by forum_$open_forum. This argument
299 will be set to zero if the meeting is successfully closed.
300 Input/Output
301 status
302 is a standard status code. It can have the following value:
303 forum_error_table_$invalid_forum_idx
304 forum_idx does not identify an open meeting.
305
306
307 :Entry: convert: 03/06/85 forum_$convert
308
309
310 Function: This entry converts a meeting created with pre-MR11 software
311 into a current version meeting.
312
313
314 Syntax:
315 declare forum_$convert entry char * char * fixed bin 35;
316 call forum_$convert dirname entryname status;
317
318
319 Arguments:
320 dirname
321 is the name of the directory containing the meeting. Input
322 entryname
323 is the name of the meeting. Input The ".control" suffix is
324 required.
325 status
326 is a standard status code.
327
328
329 Access required:
330 The caller must have modify permission on the containing directory and
331 chairman access to the meeting.
332
333
334 :Entry: convert_attendee_idx: 03/06/85 forum_$convert_attendee_idx
335
336
337 Function: This entry is used to convert an attendee_idx into a user
338 name.
339
340
341 Syntax:
342 declare forum_$convert_attendee_idx entry fixed bin fixed bin
343 char* fixed bin35;
344 call forum_$convert_attendee_idx forum_idx attendee_idx user_name
345 status;
346
347
348 Arguments:
349 forum_idx
350 identifies a meeting opened by forum_$open_forum. Input
351 attendee_idx
352 is the index of a participant in a meeting, as placed in Forum
353 interprocess messages. Input
354 user_name
355 is the name of the user with the specified attendee_idx, in the form
356 Person_id.Project_id. Output
357 status
358 is a standard status code. Output It can have the following
359 value:
360 forum_error_table_$invalid_attendee_idx
361 The supplied attendee index does not correspond to a valid
362 participant record in this meeting.
363
364
365 :Entry: delete_forum: 03/06/85 forum_$delete_forum
366
367
368 Function: Deletes a Forum meeting.
369
370
371 Syntax:
372 declare forum_$delete_forum entry char* char* fixed bin35;
373 call forum_$delete_forum dirname entryname status;
374
375
376 Arguments:
377 dirname
378 is the pathname of the directory containing the meeting. Input
379 entryname
380 is the name of the meeting. The ".forum" suffix is required.
381 Input
382 status
383 is a standard status code. Output
384
385
386 Access required:
387 The user must have modify permission on the containing directory.
388
389
390 :Entry: delete_forum_acl: 08/28/86 forum_$delete_forum_acl
391
392
393 Function: This entry deletes specified entries from an access control
394 list ACL. This entry cannot be used on meetings created with
395 pre-MR11 software.
396
397
398 Syntax:
399 declare forum_$delete_forum_acl entry char* char* ptr fixed
400 bin fixed bin35;
401 call forum_$delete_forum_acl dirname entryname acl_ptr acl_count
402 code;
403
404
405 Arguments:
406 dirname
407 is the pathname of the directory containing the meeting. Input
408 entryname
409 is the name of the meeting. The ".forum" suffix is required.
410 Input
411 acl_ptr
412 points to a user-filled delete_acl structure. Input
413 acl_count
414 is the number of ACL entries in the delete_acl structure. Input
415 code
416 is a storage system status code. Output
417
418
419 :Entry: enter_trans: 03/06/85 forum_$enter_trans
420
421
422 Function: This entry is used to enter a transaction into a Forum
423 meeting.
424
425
426 Syntax:
427 declare forum_$enter_trans entry fixed bin char* fixed bin
428 char* bit1 aligned fixed bin fixed bin35;
429 call forum_$enter_trans forum_idx text previous_trans subject
430 filled_sw trans_idx status;
431
432
433 Arguments:
434 forum_idx
435 identifies a meeting opened by forum_$open_forum. Input
436 text
437 is the text of the transaction to be entered. Input
438 previous_trans
439 is the index of the transaction that this transaction is in reply
440 to, or 0 if it is the start of a new chain. Input
441 subject
442 is the subject of the transaction to be entered. Input
443
444
445 filled_sw
446 is set if the transaction should not be filled on output. Input
447 trans_idx
448 is the index of the transaction entered. Output
449 status
450 is a standard status code. Output It can have the following
451 value:
452 forum_error_table_$read_only
453 The caller does not have access to enter transactions in the
454 meeting.
455
456
457 :Entry: expunge: 03/06/85 forum_$expunge
458
459
460 Function: This entry is used to physically remove deleted participant
461 records and deleted transactions from a Forum meeting. This results in
462 reclaimed storage space.
463
464
465 Syntax:
466 declare forum_$expunge entry fixed bin bit 36 aligned fixed bin
467 fixed bin;
468 call forum_$expunge forum_idx switches users_deleted
469 trans_deleted;
470
471
472 Arguments:
473 forum_idx
474 identifies a meeting opened by forum_$open_forum. Input
475 switches
476 is a word of switches as follows: Input
477 transactions if set, deleted transactions should be expunged.
478 users if set, deleted participant records should be expunged.
479 users_deleted
480 is the number of participant records which were expunged. Output
481 trans_deleted
482 is the number of transactions which were expunged. Output
483 status
484 is a standard status code. Output
485
486
487 :Entry: forum_info: 08/28/86 forum_$forum_info
488
489
490 Function: This entry is used to obtain information about a Forum
491 meeting.
492
493
494 Syntax:
495 declare forum_$forum_info entry char* char* char*
496 fixed bin71 ptr fixed bin35;
497 call forum_$forum_info dirname entryname access_name access_time
498 forum_info_ptr status;
499
500
501 Arguments:
502 dirname
503 is the pathname of the directory containing the meeting. Input
504 entryname
505 is the name of the meeting. The ".forum" suffix is required.
506 Input
507 access_name
508 is the Person_id.Project_id.tag for which access is to be
509 calculated. If blank, the access_name of the caller is used. The
510 per-user information returned is for the Person_id portion of
511 access_name. Input
512
513
514 access_time
515 changed information is calculated from the specified date-time.
516 Usually, "clock " should be passed. Input
517 forum_info_ptr
518 is a pointer to a copy of the forum_info structure see the include
519 file forum_info.incl.pl1. Input
520 status
521 is a standard status code. Output It can have the following
522 value:
523 forum_error_table_$not_eligible
524 The user does not have access to obtain information about
525 transaction counts and changes, but the chairman name is still
526 valid in this case.
527
528
529 :Entry: forum_info_idx: 08/28/86 forum_$forum_info_idx
530
531
532 Function: This entry is used to obtain information about a Forum
533 meeting. It is the same as the forum_info entry point except that a
534 forum_idx is used to identify the meeting instead of a pathname.
535
536
537 Syntax:
538 declare forum_$forum_info_idx entry fixed bin char* fixed bin71
539 ptr fixed bin35;
540 call forum_$forum_info_idx forum_idx access_name access_time
541 forum_info_ptr status;
542
543
544 Arguments:
545 forum_idx
546 identifies a meeting opened by forum_$open_forum. Input
547 access_name
548 is the Person_id.Project_id.tag for which access is to be
549 calculated. If blank, the access_name of the caller is used. The
550 per-user information returned is for the Person_id portion of
551 access_name. Input
552 access_time
553 changed information is calculated from the specified date-time.
554 Usually, "clock " should be passed. Input
555 forum_info_ptr
556 is a pointer to a copy of the forum_info structure see the include
557 file forum_info.incl.pl1. Input
558
559
560 status
561 is a standard status code. Output It can have the following
562 value:
563 forum_error_table_$not_eligible
564 The user does not have access to obtain information about
565 transaction counts and changes, but the chairman name is still
566 valid in this case.
567
568
569 :Entry: forum_limits: 08/28/86 forum_$forum_limits
570
571
572 Function: This entry is used to obtain various pieces of information
573 about an open Forum meeting. This entry point is obsolete. The
574 forum_$real_forum_limits entry point should be used instead.
575
576
577 Syntax:
578 declare forum_$forum_limits entry fixed bin fixed bin fixed bin
579 fixed bin fixed bin bit36 aligned fixed bin35;
580 call forum_$forum_limits forum_idx last_seen first_trans
581 last_trans new_trans_count flags status;
582
583
584 Arguments:
585 forum_idx
586 identifies a meeting opened by forum_$open_forum. Input
587 last_seen
588 is the index of the most-recently entered transaction that the user
589 has seen, as set by forum_$set_last_seen_idx. Output
590 first_trans
591 is the index of the oldest transaction in the meeting. Output
592
593
594 last_trans
595 is the index of the most recent transaction in the meeting.
596 Output
597 new_trans_count
598 is the number of transactions entered since last_seen by users other
599 than the caller. Output
600 flags
601 is a collection of switches. Output
602 status
603 is a standard status code. Output
604
605
606 :Entry: get_forum_path: 03/06/85 forum_$get_forum_path
607
608
609 Function: This entry is used to determine the actual name of the
610 meeting instead of the name of the link used to access it.
611
612
613 Syntax:
614 declare forum_$get_forum_path entry char* char* char*
615 char* fixed bin35;
616 call forum_$get_forum_path dirname entryname forum_dirname
617 forum_entryname status;
618
619
620 Arguments:
621 dirname
622 is the pathname of the directory containing the meeting. Input
623 entryname
624 is the name of the meeting. The ".forum" suffix is required.
625 Input
626 forum_dirname
627 is the pathname of the directory where the meeting actually resides.
628 Output
629 forum_entryname
630 is the primary name of the meeting. Output
631 status
632 is a standard status code. Output
633
634
635 :Entry: get_forum_path_idx: 03/06/85 forum_$get_forum_path_idx
636
637
638 Function: This entry is used to determine the actual name of the
639 meeting instead of the name of the link used to access it. It is the
640 same as the get_forum_path entry point except that a forum_idx is used
641 to identify the meeting instead of a pathname.
642
643
644 Syntax:
645 declare forum_$get_forum_path_idx entry fixed bin char* char*
646 fixed bin35;
647 call forum_$get_forum_path_idx forum_idx forum_dirname
648 forum_entryname status;
649
650
651 Arguments:
652 forum_idx
653 identifies a meeting opened by forum_$open_forum. Input
654 forum_dirname
655 is the pathname of the directory where the meeting actually resides.
656 Output
657 forum_entryname
658 is the primary name of the meeting. Output
659 status
660 is a standard status code. Output
661
662
663 :Entry: get_message: 03/06/85 forum_$get_message
664
665
666 Function: This entry is used to read out the greeting message set by
667 the chairman using the forum_$set_message entry.
668
669
670 Syntax:
671 declare forum_$get_message entry fixed bin char* fixed bin35;
672 call forum_$get_message forum_idx message status;
673
674
675 Arguments:
676 forum_idx
677 identifies a meeting opened by forum_$open_forum. Input
678 message
679 is the text of the message, this can contain at most 256 characters.
680 Output
681 status
682 is a standard status code. Output It can have the following
683 value:
684 forum_error_table_$no_message
685 There is no chairman greeting message for this meeting.
686
687
688 :Entry: get_switch: 03/06/85 forum_$get_switch
689
690
691 Function: This entry is used to return the value of several switches
692 associated with a Forum meeting or its participants.
693
694
695 Syntax:
696 declare forum_$get_switch entry char * char * char * char
697 * bit 1 aligned fixed bin 35;
698 call forum_$get_switch dirname entryname person_id switch_name
699 switch_setting status;
700
701
702 Arguments:
703 dirname
704 is the name of the directory containing the meeting. Input
705 entryname
706 is the name of the meeting. The ".forum" suffix is required.
707 Input
708
709
710 person_id
711 the user name of the user whose per-user switch value is desired.
712 Input The project_id should not be given. Starnames are not
713 permitted. If this is blank, the current user is assumed.
714 switch_name
715 is the name of the switch to retrieve. Input See "List of
716 Switches" below.
717 switch_setting
718 is the returned switch setting. Output
719 status
720 is a standard status code. It may have the following value:
721
722 forum_error_table_$invalid_switch_name
723
724 the switch_name is not one of the valid switches.
725
726
727 List of switches:
728 adjourned, adj
729 prevents users from entering the meeting.
730 meeting_eligibility_messages, mtg_emsg
731 turns on printing of eligibility messages for this meeting.
732 notify, nt
733 turns on the notify switch for the meeting. This means that an
734 interactive message will be sent each time a transaction is entered
735 if the user is logged in and has issued the
736 forum_accept_notifications command.
737 participating, part
738 turns on the participation switch for the meeting.
739 safety
740 changes the storage system safety switch for the meeting. The
741 meeting cannot be deleted if this switch is on.
742
743
744 :Entry: get_transaction_map: 03/06/85 forum_$get_transaction_map
745
746
747 Function: This entry is used to retrieve a bit map representing the
748 transactions that a given participant has seen. This entrypoint cannot
749 be used with meetings created with pre-MR11 software.
750
751
752 Syntax:
753 declare forum_$get_transaction_map entry char * char * char *
754 bit * fixed bin 35;
755 call forum_$get_transaction_map dirname entryname person_id
756 seen_map status;
757
758
759 Arguments:
760 dirname
761 is the name of the directory containing the meeting. Input
762 entryname
763 is the name of the meeting. Input The ".forum" suffix is
764 required.
765
766
767 person_id
768 The username of the user whose transaction seen map is desired.
769 Input Starnames are not permitted. If this is blank, the current
770 user is assumed.
771 seen_map
772 is a bit map indicating which transactions the user has seen. If
773 the n'th bit in this map is a "1"b, then the user has seen
774 transaction "n". This variable must be large enough to hold one bit
775 for each transaction in the meeting.
776 status
777 is a standard status code.
778
779
780 :Entry: get_uid_file: 03/06/85 forum_$get_uid_file
781
782
783 Function: This entry returns the file system unique identifier of a
784 meeting.
785
786
787 Syntax:
788 declare forum_$get_uid_file entry char * char * bit 36
789 aligned fixed bin 35;
790 call forum_$get_uid_file dir_name entryname uid code;
791
792
793 Arguments:
794 dirname
795 is the pathname of the directory containing the meeting. Input
796 entryname
797 is the name of the meeting. Input The meeting suffix is required.
798 uid
799 is the unique identifier of the meeting. Output
800 code
801 is a standard status code.
802
803
804 :Entry: list_forum_acl: 08/28/86 forum_$list_forum_acl
805
806
807 Function: This entry is used either to list the entire access control
808 list ACL meeting or to return the access modes of specified ACL
809 entries. This entry cannot be used with meetings created with pre-MR11
810 software.
811
812
813 Syntax:
814 declare forum_$list_forum_acl entry char* char* ptr ptr ptr
815 fixed bin fixed bin35;
816 call forum_$list_forum_acl dir_name entryname area_ptr
817 area_ret_ptr acl_ptr acl_count code;
818
819
820 Arguments:
821 dirname
822 is the pathname of the directory containing the meeting. Input
823 entryname
824 is the name of the meeting. Input The ".forum" suffix is
825 required.
826 area_ptr
827 points to an area in which the list of ACL entries, which make up
828 the entire ACL of the segment, is allocated. Input If area_ptr is
829 null, then the user wants access modes for certain ACL entries;
830 these will be specified by the structure pointed to by acl_ptr.
831 area_ret_ptr
832 points to the start of the allocated list of ACL entries. Output
833
834
835 acl_ptr
836 if area_ptr is null, then acl_ptr points to an ACL structure,
837 segment_acl, into which mode information is placed for the access
838 names specified in that same structure see the include
839 file acl_structures.incl.pl1. Input
840 acl_count
841 is the number of entries in the ACL structure. Input or Output
842 Input is the number of entries in the ACL structure identified by
843 acl_ptr.
844 Output is the number of entries in the segment_acl structure
845 allocated in the area pointed to by area_ptr, if area_ptr is not
846 null.
847 code
848 is a storage system status code. Output
849
850
851 Notes: If acl_ptr is used to obtain modes for specified access names
852 rather than for all access names on a segment, then each ACL entry in
853 the segment_acl structure either has status_code set to 0 and contains
854 the segment's mode or has status_code set to
855 error_table_$user_not_found and contains a mode of 0.
856
857
858 :Entry: list_v1_forum_acl: 03/06/85 forum_$list_v1_forum_acl
859
860
861 Function: This entry is used to list the ACL of a Forum meeting.
862
863
864 Syntax:
865 declare forum_$list_v1_forum_acl entry char* char* ptr ptr
866 fixed bin fixed bin35;
867 call forum_$list_v1_forum_acl dirname pathname area_ptr acl_ptr
868 acl_count status;
869
870
871 Arguments:
872 dirname
873 is the pathname of the directory containing the meeting. Input
874 entryname
875 is the name of the meeting. The ".forum" suffix is required.
876 Input
877 area_ptr
878 points to an area where the segment_acl structure is to be
879 allocated. Input It can not be null.
880
881
882 acl_ptr
883 points to the allocated segment_acl structure. This structure is
884 described in the hcs_$add_acl_entries subroutine. Output
885 acl_count
886 is the number of ACL entries in the segment_acl structure. Output
887 status
888 is a standard status code. Output
889
890
891 :Entry: list_users: 08/28/86 forum_$list_users
892
893
894 Function: This entry is used to extract information about the
895 participants in a Forum meeting.
896
897
898 Syntax:
899 declare forum_$list_users entry char* char* ptr ptr
900 fixed bin35;
901 call forum_$list_users dirname entryname area_ptr user_list_ptr
902 status;
903
904
905 Arguments:
906 dirname
907 is the pathname of the directory containing the meeting. Input
908 entryname
909 is the name of the meeting. The ".forum" suffix is required.
910 Input
911 area_ptr
912 is a pointer to an area where the user_list structure is to be
913 allocated. Input It can not be null.
914 user_list_ptr
915 is a pointer to the user_list structure see the include file
916 forum_user_list.incl.pl1. Output
917 status
918 is a standard status code. Output
919
920
921 :Entry: list_users_idx: 08/28/86 forum_$list_users_idx
922
923
924 Function: This entry is used to extract information about the
925 participants in a Forum meeting. It is the same as the list_users
926 entry point except that a forum_idx is used to identify the meeting
927 instead of a pathname.
928
929
930 Syntax:
931 declare forum_$list_users_idx entry fixed bin ptr ptr
932 fixed bin35;
933 call forum_$list_users_idx forum_idx area_ptr user_list_ptr
934 status;
935
936
937 Arguments:
938 forum_idx
939 identifies a meeting opened by forum_$open_forum. Input
940 area_ptr
941 is a pointer to an area where the user_list structure is to be
942 allocated. Input It can not be null.
943 user_list_ptr
944 is a pointer to the user_list structure see the include file
945 forum_user_list.incl.pl1. Output.
946 status
947 is a standard status code. Output
948
949
950 :Entry: next_transaction: 12/04/85 forum_$next_transaction
951
952 Function: This entry returns the index of the next unexpunged
953 transaction relative to a supplied transaction index.
954
955
956 Syntax:
957 declare forum_$next_transaction entry fixed bin fixed bin
958 fixed bin fixed bin 35;
959 call forum_$next_transaction forum_idx trans_idx next_idx
960 status;
961
962
963 Arguments:
964 forum_idx
965 identifies a meeting opened by forum_$open_forum. Input
966 trans_idx
967 is the index of the transaction where the search is to start.
968 Input
969 next_idx
970 is the index of the unexpunged transaction entered most recently
971 after trans_idx. Output
972
973
974 status
975 is a standard status code. Output It can have the following
976 values:
977 forum_error_table_$invalid_trans_idx
978 There is no transaction corresponding to the supplied index.
979 forum_error_table_$no_transactions
980 There is no next unexpunged transaction.
981
982
983 :Entry: open_forum: 03/06/85 forum_$open_forum
984
985
986 Function: This entry opens a meeting and returns the forum_idx used in
987 many of the other calls to forum_.
988
989
990 Syntax:
991 declare forum_$open_forum entry char* char* fixed bin
992 fixed bin35;
993 call forum_$open_forum dirname entryname forum_idx status;
994
995
996 Arguments:
997 dirname
998 is the pathname of the directory containing the meeting. Input
999 entryname
1000 is the name of the meeting. The ".forum" suffix is required.
1001 Input
1002 forum_idx
1003 is the index number used in subsequent calls to forum_ that take a
1004 forum index. All coexistent openings of the same meeting in the
1005 same process will return the same number. Output
1006
1007
1008 status
1009 is a standard status code. If this is non-zero the meeting could
1010 not be opened. Output It can have one of the following values:
1011 forum_error_table_$meeting_adjourned
1012 The chairman has adjourned the meeting. Only the chairman can
1013 attend.
1014 forum_error_table_$no_such_forum
1015 The dirname-entryname pair does not exist.
1016 forum_error_table_$not_a_forum
1017 The segment named by dirname and entryname is not a Forum
1018 meeting.
1019 forum_error_table_$not_eligible
1020 The caller has insufficient access to participate in the meeting.
1021
1022
1023 :Entry: previous_transaction: 12/04/85 forum_$previous_transaction
1024
1025 Function: This entry returns the index of the previous unexpunged
1026 transaction relative to a supplied transaction index.
1027
1028
1029 Syntax:
1030 declare forum_$previous_transaction entry fixed bin fixed bin
1031 fixed bin fixed bin 35;
1032 call forum_$previous_transaction forum_idx trans_idx prev_idx
1033 status;
1034
1035
1036 Arguments:
1037 forum_idx
1038 identifies a meeting opened by forum_$open_forum. Input
1039 trans_idx
1040 is the index of the transaction where the search is to start.
1041 Input
1042 prev_idx
1043 is the index of the unexpunged transaction entered most recently
1044 before trans_idx. Output
1045
1046
1047 status
1048 is a standard status code. Output It can have the following
1049 values:
1050 forum_error_table_$invalid_trans_idx
1051 There is no transaction corresponding to the supplied index.
1052 forum_error_table_$no_transactions
1053 There is no previous unexpunged transaction.
1054
1055
1056 :Entry: read_trans: 08/28/86 forum_$read_trans
1057
1058 Function: This entry is used to read a transaction from a Forum
1059 meeting.
1060
1061
1062 Syntax:
1063 declare forum_$read_trans entry fixed bin fixed bin ptr ptr
1064 fixed bin35;
1065 call forum_$read_trans forum_idx trans_idx area_ptr
1066 forum_user_trans_ptr status;
1067
1068
1069 Arguments:
1070 forum_idx
1071 identifies a meeting opened by forum_$open_forum. Input
1072 trans_idx
1073 is the index of the transaction to be read. Input
1074 area_ptr
1075 is a pointer to an area where the forum_user_trans structure is to
1076 be allocated. Input
1077 forum_user_trans_ptr
1078 is a pointer to the forum_user_trans structure see the include file
1079 forum_user_trans.incl.pl1. Output
1080
1081
1082 status
1083 is a standard status code. Output It can have the following
1084 values:
1085 forum_error_table_$invalid_trans_idx
1086 There is no transaction corresponding to the supplied index.
1087 forum_error_table_$trans_deleted
1088 The deleted switch is set for this transaction and the caller is
1089 neither the chairman nor the author.
1090 forum_error_table_$trans_reaped
1091 The transaction has been physically removed from the meeting.
1092
1093
1094 :Entry: rechain: 12/27/85 forum_$rechain
1095
1096
1097 Function: This entry changes transaction chaining information, either
1098 removing a transaction from its current chain or moving it to a
1099 different chain. A transaction subject may be changed in either case.
1100
1101
1102 Syntax: declare forum_$rechain entry fixed bin fixed bin fixed bin
1103 char * fixed bin 35;
1104 call forum_$rechain forum_idx trans_idx pref new_subject status;
1105
1106
1107 Arguments:
1108 forum_idx
1109 identifies a meeting opened by forum_$open_forum. Input
1110 trans_idx
1111 is the index of the transaction to be rechained. Input
1112 pref
1113 is the index of any transaction in the chain to which the
1114 transaction named by trans_idx should be attached. If pref is
1115 zero, then the transaction is removed from its transaction chain.
1116 new_subject
1117 is the new subject for the transaction named by trans_idx. If
1118 new_subject is "", then the subject is not changed.
1119 status
1120 is a standard status code. Output
1121
1122
1123 Access required: The caller must have chairman access to the meeting.
1124
1125
1126 :Entry: refuse_notifications: 03/06/85 forum_$refuse_notifications
1127
1128
1129 Function: This entry turns off reception of forum notifications by the
1130 calling process.
1131
1132
1133 Syntax:
1134 declare forum_$refuse_notifications entry fixed bin35;
1135 call forum_$refuse_notifications status;
1136
1137
1138 Arguments:
1139 status
1140 is a standard status code. Output It can have the following
1141 value:
1142 forum_error_table_$no_notify_seg
1143 The notifications database could not be initiated.
1144
1145
1146 :Entry: replace_forum_acl: 08/28/86 forum_$replace_forum_acl
1147
1148
1149 Function: This entry replaces an entire access control list ACL for
1150 a meeting with a user-provided ACL, and can optionally add an entry for
1151 *.SysDaemon.* with mode rw to the new ACL. This entry cannot be used
1152 on meetings created with pre-MR11 software.
1153
1154
1155 Syntax:
1156 declare forum_$replace_forum_acl entry char* char* ptr fixed
1157 bin bit1 fixed bin35;
1158 call forum_$replace_forum_acl dirname entryname acl_ptr acl_count
1159 no_sysdaemon_sw code;
1160
1161
1162 Arguments:
1163 dirname
1164 is the pathname of the directory containing the meeting. Input
1165 entryname
1166 is the entryname of the meeting. Input The ".forum" suffix is
1167 required.
1168 acl_ptr
1169 points to the user supplied segment_acl structure that is to replace
1170 the current ACL see the include file acl_structures.incl.pl1.
1171 Input
1172
1173
1174 acl_count
1175 is the number of entries in the segment_acl structure. Input
1176 no_sysdaemon_sw
1177 is a switch that indicates whether an rw *.SysDaemon.* entry is to
1178 be put on the ACL of the meeting after the existing ACL has been
1179 deleted and before the user-supplied segment_acl entries are added.
1180
1181 Input
1182 "0"b adds rw *.SysDaemon.* entry
1183 "1"b replaces the existing ACL with only the user-supplied
1184 segment_acl
1185
1186 code
1187 is a storage system status code. Output
1188
1189
1190 Notes: If acl_count is zero, then the existing ACL is deleted and only
1191 the action indicated if any by the no_sysdaemon_sw switch is
1192 performed. If acl_count is greater than zero, processing of the
1193 segment_acl entries is performed top to bottom, allowing later entries
1194 to overwrite previous ones if the access_name in the segment_acl
1195 structure is identical.
1196
1197
1198 :Entry: set_delete_sw: 03/06/85 forum_$set_delete_sw
1199
1200
1201 Function: This entry is used to delete or retrieve a transaction.
1202
1203
1204 Syntax:
1205 declare forum_$set_delete_sw entry fixed bin fixed bin
1206 bit1 aligned fixed bin35;
1207 call forum_$set_delete_sw forum_idx trans_idx delete_sw status;
1208
1209
1210 Arguments:
1211 forum_idx
1212 identifies a meeting opened by forum_$open_forum. Input
1213 trans_idx
1214 is the index of the transaction whose delete switch is to be
1215 changed. Input
1216 delete_sw
1217 should be on to delete the transaction, or off to retrieve it.
1218
1219
1220 status
1221 is a standard status code. Output It can have one of the
1222 following values:
1223 forum_error_table_$chairman_only
1224 The caller is neither the author of the transaction nor the
1225 chairman of the meeting.
1226 forum_error_table_$invalid_trans_idx
1227 There is no transaction corresponding to the supplied index.
1228
1229
1230 :Entry: set_event_channel: 03/06/85 forum_$set_event_channel
1231
1232
1233 Function: This entry is used to set the event channel used to send
1234 wakeups when interesting forum events occur.
1235
1236
1237 Syntax:
1238 declare forum_$set_event_channel entry char* char*
1239 fixed bin71 fixed bin35;
1240 call forum_$set_event_channel entry dirname entryname event_channel
1241 status;
1242
1243
1244 Arguments:
1245 dirname
1246 is the pathname of the directory containing the meeting. Input
1247 entryname
1248 is the name of the meeting. The ".forum" suffix is required.
1249 Input
1250 event_channel
1251 is the event channel which should receive wakeups from other users
1252 attending the same meeting. Input
1253 status
1254 is a standard status code. Output
1255
1256
1257 Notes: Currently, the only wakeup sent by Forum occurs when a
1258 transaction is entered while you are attending the meeting.
1259
1260
1261 :Entry: set_event_channel_idx: 03/06/85 forum_$set_event_channel_idx
1262
1263
1264 Function: This entry is used to set the event channel used to send
1265 wakeups when interesting forum events occur.
1266
1267
1268 Syntax:
1269 declare forum_$set_event_channel_idx entry fixed bin fixed bin71
1270 fixed bin35;
1271 call forum_$set_event_channel_idx entry forum_idx event_channel
1272 status;
1273
1274
1275 Arguments:
1276 forum_idx
1277 identifies a meeting opened by forum_$open_forum. Input
1278 event_channel
1279 is the event channel which should receive wakeups from other users
1280 attending the same meeting. Input
1281 status
1282 is a standard status code. Output
1283
1284
1285 Notes: See the forum_$set_event_channel entry point for a description
1286 of interprocess messages used by Forum.
1287
1288
1289 :Entry: set_forum_acl: 08/28/86 forum_$set_forum_acl
1290
1291
1292 Function: This entry adds specified access modes to the access control
1293 list ACL of a meeting. If an access name already appears on the ACL
1294 of the segment, its mode is changed to the one specified by the call.
1295 This entry cannot be used on meetings created with pre-MR11 software.
1296
1297
1298 Syntax:
1299 declare forum_$set_forum_acl entry char * char * ptr fixed bin
1300 fixed bin 35;
1301 call forum_$set_forum_acl dirname entryname acl_ptr acl_count
1302 code;
1303
1304
1305 Arguments:
1306 dirname
1307 is the name of the directory containing the meeting. Input
1308 entryname
1309 is the name of the meeting. Input The meeting suffix is required.
1310 acl_ptr
1311 points to a user-filled segment_acl_array structure see the include
1312 file acl_structures.incl.pl1. Input
1313 acl_count
1314 contains the number of ACL entries in the segment_acl_array
1315 structure. Input
1316 code
1317 is a storage system status code. Output
1318
1319
1320 :Entry: set_message: 03/06/85 forum_$set_message
1321
1322
1323 Function: This entry is used to set a chairman's greeting message for
1324 a Forum meeting.
1325
1326
1327 Syntax:
1328 declare forum_$set_message entry fixed bin char* fixed bin35;
1329 call forum_$set_message forum_idx message status;
1330
1331
1332 Arguments:
1333 forum_idx
1334 identifies a meeting opened by forum_$open_forum. Input
1335 message
1336 is the text message, this can contain at most 256 characters.
1337 Input
1338 status
1339 is a standard status code. Output It can have one of the
1340 following values:
1341 forum_error_table_$chairman_only
1342 The caller is not the chairman of the meeting.
1343 forum_error_table_$message_too_long
1344 The message exceeds the 256 character limit.
1345
1346
1347 :Entry: set_seen_switch: 03/06/85 forum_$set_seen_switch
1348
1349
1350 Function: This entry marks a transaction as having been seen by a
1351 participant. This entry cannot be used on meetings created with
1352 pre-MR11 software.
1353
1354
1355 Syntax:
1356 declare forum_$set_seen_switch entry fixed bin char * fixed bin
1357 bit 1 aligned fixed bin 35;
1358 call forum_$set_seen_switch forum_idx person_id trans_idx value
1359 status;
1360
1361
1362 Arguments:
1363 forum_idx
1364 identifies a meeting opened by forum_$open_forum. Input
1365 person_id
1366 is the user name of the participant for whom the transaction is to
1367 be marked as seen. Input If this is blank, the person_id of the
1368 caller is assumed. Chairman access is required to change a seen
1369 switch for another participant.
1370 trans_idx
1371 is the number of the transaction to be marked. Input
1372 value
1373 is on if the transaction is to be marked as seen, and off otherwise.
1374 Input
1375 status
1376 is a standard status code. Output
1377
1378
1379 :Entry: set_switch: 03/06/85 forum_$set_switch
1380
1381
1382 Function: This entry is used to change several switches associated
1383 with a Forum meeting or its participants.
1384
1385
1386 Syntax:
1387 declare forum_$set_switch entry char* char* char* char*
1388 bit1 aligned fixed bin35;
1389 call forum_$set_switch dirname entryname person_id switch_name
1390 switch_setting status;
1391
1392
1393 Arguments:
1394 dirname
1395 is the pathname of the directory containing the meeting. Input
1396 entryname
1397 is the name of the meeting. The ".forum" suffix is required.
1398 Input
1399 person_id
1400 is the Person_id of the user on whose behalf you are setting the
1401 switch. The Project_id should not be given. Starnames are not
1402 permitted. If this is blank, the current user is assumed. Only the
1403 chairman of a forum can set switches for persons other than herself.
1404 Input
1405
1406
1407 switch_name
1408 is the name of the switch to set. See "List of Switches" below.
1409 Input
1410 switch_setting
1411 is the new switch setting. Input
1412 status
1413 is a standard status code. It can have one of the following values:
1414 forum_error_table_$chairman_only
1415 Person_id does not identify the caller and the caller is not the
1416 chairman.
1417 forum_error_table_$invalid_switch_name
1418 The switch_name is not one of the valid switches.
1419 forum_error_table_$switch_not_changed
1420 The old setting was the same as the new setting.
1421
1422
1423 List of switches:
1424 adjourned, adj
1425 Prevents users from entering the meeting. Only the chairman can set
1426 this switch.
1427 meeting_eligibility_messages, mtg_emsg
1428 Turns on printing of eligibilty messages for this meeting. This
1429 switch can only be set by the chairman.
1430
1431
1432 notify, nt
1433 Turns on the notify switch for the meeting. This means that an
1434 interactive message will be sent each time a transaction is entered
1435 if the user is logged in and has issued the
1436 forum_accept_notifications command.
1437 participating, part
1438 Turns on the participation switch for the meeting.
1439 safety
1440 Changes the storage system safety switch for the meeting. The
1441 meeting cannot be deleted if this switch is on.
1442
1443
1444 :Entry: set_switch_idx: 03/06/85 forum_$set_switch_idx
1445
1446
1447 Function: This entry is used to change several switches associated
1448 with a Forum meeting or its participants. It is the same as the
1449 set_switch entry point except that a forum_idx is used to identify the
1450 meeting instead of a pathname.
1451
1452
1453 Syntax:
1454 declare forum_$set_switch_idx entry fixed bin char* char*
1455 bit1 aligned fixed bin35;
1456 call forum_$set_switch_idx forum_idx person_id switch_name
1457 switch_setting status;
1458
1459
1460 Arguments:
1461 forum_idx
1462 identifies a meeting opened by forum_$open_forum. Input
1463 person_id
1464 is the Person_id of the user on whose behalf you are setting the
1465 switch. The Project_id should not be given. Starnames are not
1466 permitted. If this is blank, the current user is assumed. Only the
1467 chairman of a forum can set switches for persons other than herself.
1468 Input
1469
1470
1471 switch_name
1472 is the name of the switch to set. See "List of switches" below.
1473 Input
1474 switch_setting
1475 is the new switch setting. Input
1476 status
1477 is a standard status code. It can have one of the following values:
1478 forum_error_table_$chairman_only
1479 Person_id does not identify the caller and the caller is not the
1480 chairman.
1481 forum_error_table_$invalid_switch_name
1482 The switch_name is not one of the valid switches.
1483 forum_error_table_$switch_not_changed
1484 The old setting was the same as the new setting.
1485
1486
1487 List of switches:
1488 access_changed
1489 Specifies that the ACL on the meeting has changed. This switch is
1490 set by the forum_chairman_$set_forum_acl entry point, and should
1491 normally only be turned off by this subroutine.
1492 adjourned, adj
1493 Prevents users from entering the meeting. Only the chairman can set
1494 this switch.
1495 deleted
1496 Specifies that the attendee record for this user should be marked as
1497 deleted.
1498 meeting_eligibility_messages, mtg_emsg
1499 Turns on printing of eligibilty messages for this meeting. This
1500 switch can only be set by the chairman.
1501
1502
1503 message_seen
1504 Specifies that the chairman message on the meeting has changed.
1505 This switch is set by the forum_$set_message entry point, and should
1506 normally only be turned off by this subroutine.
1507 notify, nt
1508 Turns on the notify switch for the meeting. This means that an
1509 interactive message will be sent each time a transaction is entered
1510 if the user is logged in and has issued the
1511 forum_accept_notifications command.
1512 participating, part
1513 Turns on the participation switch for the meeting.
1514 safety
1515 Changes the storage system safety switch for the meeting. The
1516 meeting cannot be deleted if this switch is on.
1517
1518
1519 :Entry: trans_ref_info: 03/06/85 forum_$trans_ref_info
1520
1521
1522 Function: This entry is used to obtain information about an individual
1523 transaction. This entry is obsolete. The forum_$real_trans_ref_info
1524 entry should be used instead.
1525
1526
1527 Syntax:
1528 declare forum_$trans_ref_info entry fixed bin fixed bin fixed bin
1529 fixed bin bit1 aligned fixed bin35;
1530 call forum_$trans_ref_info forum_idx trans_idx prev_ref next_ref
1531 deleted_sw status;
1532
1533
1534 Arguments:
1535 forum_idx
1536 identifies a meeting opened by forum_$open_forum. Input
1537 trans_idx
1538 is the index of the transaction for which information is desired.
1539 Input
1540 prev_ref
1541 is the index of the preceding transaction in the same transaction
1542 chain. This is zero if the transaction is the first in a chain.
1543 Output
1544
1545
1546 next_ref
1547 is the index of the next transaction in the same transaction chain.
1548 This is zero if the transaction is the last in a chain. Output
1549 deleted_sw
1550 is set if the transaction has been marked as deleted. Output
1551 status
1552 is a standard status code. Output It can have one of the
1553 following values:
1554 forum_error_table_$invalid_trans_idx
1555 There is no transaction corresponding to the supplied index.
1556 forum_error_table_$trans_reaped
1557 The transaction has been physically removed from the meeting.
1558
1559
1560 :Entry: trans_time_info: 03/06/85 forum_$trans_time_info
1561
1562
1563 Function: This entry returns the indexes of transactions entered
1564 during a given time span.
1565
1566
1567 Syntax:
1568 declare forum_$trans_time_info entry fixed bin fixed bin71
1569 fixed bin71 fixed bin fixed bin fixed bin35;
1570 call forum_$trans_time_info forum_idx low_time high_time low_trans
1571 high_trans status;
1572
1573
1574 Arguments:
1575 forum_idx
1576 identifies a meeting opened by forum_$open_forum. Input
1577 low_time
1578 is the timestamp of the low end of the time span. Input
1579 high_time
1580 is the timestamp of the high end of the time span. Input
1581
1582
1583 low_trans
1584 is the index of the first transaction entered after low_time. If
1585 there are no transactions that new, than the index of the highest
1586 transaction in the meeting is returned. Output
1587 high_trans
1588 is the index of the transaction entered immediately before
1589 high_time. If no transactions were entered before then, zero is
1590 returned. Output
1591 status
1592 is a standard status code. Output.
1593
1594
1595 :Entry: validate_uid: 03/06/85 forum_$validate_uid
1596
1597
1598 Function: This entry is used to determine if a given meeting unique
1599 identifier uid corresponds to a given meeting.
1600
1601
1602 Syntax:
1603 declare forum_$validate_uid entry fixed bin bit36 aligned
1604 fixed bin35;
1605 call forum_$validate_uid forum_idx forum_uid status;
1606
1607
1608 Arguments:
1609 forum_idx
1610 identifies a meeting opened by forum_$open_forum. Input
1611 forum_uid
1612 is the uid of the meeting. Normally this is obtained from Forum
1613 interprocess messages. Input
1614 status
1615 is a standard status code. Output It can have the following
1616 value:
1617 forum_error_table_$incorrect_uid
1618 The supplied uid is not the unique identifier of the meeting
1619 identified by forum_idx.