08/28/86 forum_ The forum_ subroutine provides a subroutine interface to the Forum interactive meeting system. Entry points in forum_: (List is generated by the help command) :Entry: accept_notifications: 03/06/85 forum_$accept_notifications Function: This entry turns on reception of forum notifications by the calling process. Syntax: declare forum_$accept_notifications entry (fixed bin(35)); call forum_$accept_notifications (status); Arguments: status is a standard status code. (Output) It can have the following value: forum_error_table_$no_notify_seg The notifications database could not be initiated. :Entry: change_chairman: 03/06/85 forum_$change_chairman Function: This entry is used to change the chairman of a Forum meeting. Syntax: declare forum_$change_chairman entry (char(*), char(*), char(*), fixed bin(35)); call forum_$change_chairman (dirname, entryname, chairman, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) chairman is the name of the new chairman of the meeting, in the form Person.Project. The new chairman must already be a participant. (Input) status is a standard status code. (Output) It can have one of the following values: forum_error_table_$chairman_only The caller is not the current chairman. forum_error_table_$no_such_user The supplied new chairman is not a participant. :Entry: change_chairman_idx: 03/06/85 forum_$change_chairman_idx Function: This entry changes the chairman of a Forum meeting. It is the same as the change_chairman entry point except that a forum_idx is used to identify the meeting instead of a pathname. Syntax: declare forum_$change_chairman_idx entry (fixed bin, char(*), fixed bin(35)); call forum_$change_chairman_idx (forum_idx, chairman, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) chairman is the name of the new chairman of the meeting, in the form Person.Project. The new chairman must already be a participant. (Input) status is a standard status code. (Output) It can have one of the following values: forum_error_table_$chairman_only The caller is not the current chairman. forum_error_table_$no_such_user The supplied new chairman is not a participant. :Entry: chname_forum: 03/06/85 forum_$chname_forum Function: This entry is used to change the names of Forum meetings. Syntax: declare forum_$chname_forum entry (char(*), char(*), char(*), char(*), fixed bin(35)); call forum_$chname_forum (dirname, entryname, old_name, new_name, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) old_name is a name to be removed from the meeting, or blank if no name is to be removed. If non-blank, ".forum" suffix is required. (Input) new_name is a name to be added to the meeting, or blank if no name is to be added. If non-blank, the ".forum" suffix is required. (Input) status is a standard status code. (Output) :Entry: chname_forum_idx: 03/06/85 forum_$chname_forum_idx Function: This entry is used to change the names of Forum meetings. It is the same as the chname_forum entry point except that a forum_idx is used to identify the meeting instead of a pathname. Syntax: declare forum_$chname_forum_idx entry (fixed bin, char(*), char(*), fixed bin(35)); call forum_$chname_forum_idx (forum_idx, old_name, new_name, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) old_name is a name to be removed from the meeting, or blank if no name is to be removed. If non-blank, the ".forum" suffix is required. (Input) new_name is a name to be added to the meeting, or blank if no name is to be added. If non-blank, the ".forum" suffix is required. (Input) status is a standard status code. (Output) :Entry: create_forum: 03/06/85 forum_$create_forum Function: Creates a Forum meeting with the user as chairman. Syntax: declare forum_$create_forum entry (char(*), char(*), fixed bin(35)); call forum_$create_forum (dirname, entryname, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) status is a standard status code. Access required: The caller must have modify permission on the containing directory. :Entry: set_v1_forum_acl: 03/06/85 forum_$set_v1_forum_acl Function: This entry is valid only for meetings created with pre-MR11 software. This entry is used to add or change an ACL term. ACL terms can only be specified for Person_id.* or *.Project_id, terms of the form Person_id.Project_id are not allowed. Syntax: declare forum_$set_v1_forum_acl entry (fixed bin, char(*), bit(1) aligned, bit(1) aligned, bit(1) aligned, fixed bin(35)); call forum_$set_v1_forum_acl (forum_idx, access_name, user_sw, set_sw, write_sw, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) access_name The Person_id or Project_id whose ACL is to be added or deleted. Access_name can not contain a ".". (Input) user_sw This switch should be on if access_name is a Person_id, and off if it is a Project_id. (Input) set_sw This switch should on if access is to be added, and off if it is to be deleted. (Input) write_sw This switch should on if write access is to be added, and off if only read access is to be added. This switch is ignored if set_sw is off. (Input) status is a standard status code. (Output) Access required: The caller must have modify permission on the containing directory. :Entry: v1_expunge: 03/06/85 forum_$v1_expunge Function: This entry is used to physically remove deleted participant records and deleted transactions from a Forum meeting. This results in reclaimed storage space. Syntax: declare forum_$v1_expunge entry (fixed bin, bit (36) aligned, fixed bin, fixed bin, fixed bin, fixed bin, fixed bin(35)); call forum_$v1_expunge (forum_idx, switches, users_deleted, trans_deleted, users_damaged, trans_damaged, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) switches is a word of switches as follows: (Input) transactions if set, deleted transactions should be expunged. users if set, deleted participant records should be expunged. users_deleted is the number of participant records which were expunged. (Output) trans_deleted is the number of transactions which were expunged. (Output) users_damaged is the number of participant records which were expunged because they were inconsistent. (Output) trans_damaged is the number of transactions which were expunged because they were inconsistent. (Output) status is a standard status code. (Output) :Entry: check_user: 03/06/85 forum_$check_user Function: This entry is used to determine if a user is a participant in a Forum meeting. Syntax: declare forum_$check_user entry (fixed bin, char(*), fixed bin, fixed bin(35)); call forum_$check_user (forum_idx, user_name, last_entered, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) user_name The Person_id of the user to be checked. (Input) last_entered is the index of the most recent transaction entered by this user, or 0 if this user has never entered a transaction. (Output) status is a standard status code. (Output) :Entry: close_forum: 03/06/85 forum_$close_forum Function: This entry closes a meeting opened by forum_$open_forum. Syntax: declare forum_$close_forum entry (fixed bin, fixed bin(35)); call forum_$close_forum (forum_idx, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. This argument will be set to zero if the meeting is successfully closed. (Input/Output) status is a standard status code. It can have the following value: forum_error_table_$invalid_forum_idx forum_idx does not identify an open meeting. :Entry: convert: 03/06/85 forum_$convert Function: This entry converts a meeting created with pre-MR11 software into a current version meeting. Syntax: declare forum_$convert entry (char (*), char (*), fixed bin (35)); call forum_$convert (dirname, entryname, status); Arguments: dirname is the name of the directory containing the meeting. (Input) entryname is the name of the meeting. (Input) The ".control" suffix is required. status is a standard status code. Access required: The caller must have modify permission on the containing directory and chairman access to the meeting. :Entry: convert_attendee_idx: 03/06/85 forum_$convert_attendee_idx Function: This entry is used to convert an attendee_idx into a user name. Syntax: declare forum_$convert_attendee_idx entry (fixed bin, fixed bin, char(*), fixed bin(35)); call forum_$convert_attendee_idx (forum_idx, attendee_idx, user_name, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) attendee_idx is the index of a participant in a meeting, as placed in Forum interprocess messages. (Input) user_name is the name of the user with the specified attendee_idx, in the form Person_id.Project_id. (Output) status is a standard status code. (Output) It can have the following value: forum_error_table_$invalid_attendee_idx The supplied attendee index does not correspond to a valid participant record in this meeting. :Entry: delete_forum: 03/06/85 forum_$delete_forum Function: Deletes a Forum meeting. Syntax: declare forum_$delete_forum entry (char(*), char(*), fixed bin(35)); call forum_$delete_forum (dirname, entryname, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) status is a standard status code. (Output) Access required: The user must have modify permission on the containing directory. :Entry: delete_forum_acl: 08/28/86 forum_$delete_forum_acl Function: This entry deletes specified entries from an access control list (ACL). This entry cannot be used on meetings created with pre-MR11 software. Syntax: declare forum_$delete_forum_acl entry (char(*), char(*), ptr, fixed bin, fixed bin(35)); call forum_$delete_forum_acl (dirname, entryname, acl_ptr, acl_count, code); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) acl_ptr points to a user-filled delete_acl structure. (Input) acl_count is the number of ACL entries in the delete_acl structure. (Input) code is a storage system status code. (Output) :Entry: enter_trans: 03/06/85 forum_$enter_trans Function: This entry is used to enter a transaction into a Forum meeting. Syntax: declare forum_$enter_trans entry (fixed bin, char(*), fixed bin, char(*), bit(1) aligned, fixed bin, fixed bin(35)); call forum_$enter_trans (forum_idx, text, previous_trans, subject, filled_sw, trans_idx, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) text is the text of the transaction to be entered. (Input) previous_trans is the index of the transaction that this transaction is in reply to, or 0 if it is the start of a new chain. (Input) subject is the subject of the transaction to be entered. (Input) filled_sw is set if the transaction should not be filled on output. (Input) trans_idx is the index of the transaction entered. (Output) status is a standard status code. (Output) It can have the following value: forum_error_table_$read_only The caller does not have access to enter transactions in the meeting. :Entry: expunge: 03/06/85 forum_$expunge Function: This entry is used to physically remove deleted participant records and deleted transactions from a Forum meeting. This results in reclaimed storage space. Syntax: declare forum_$expunge entry (fixed bin, bit (36) aligned, fixed bin, fixed bin); call forum_$expunge (forum_idx, switches, users_deleted, trans_deleted); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) switches is a word of switches as follows: (Input) transactions if set, deleted transactions should be expunged. users if set, deleted participant records should be expunged. users_deleted is the number of participant records which were expunged. (Output) trans_deleted is the number of transactions which were expunged. (Output) status is a standard status code. (Output) :Entry: forum_info: 08/28/86 forum_$forum_info Function: This entry is used to obtain information about a Forum meeting. Syntax: declare forum_$forum_info entry (char(*), char(*), char(*), fixed bin(71), ptr, fixed bin(35)); call forum_$forum_info (dirname, entryname, access_name, access_time, forum_info_ptr, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) access_name is the Person_id.Project_id.tag for which access is to be calculated. If blank, the access_name of the caller is used. The per-user information returned is for the Person_id portion of access_name. (Input) access_time changed information is calculated from the specified date-time. Usually, "clock ()" should be passed. (Input) forum_info_ptr is a pointer to a copy of the forum_info structure (see the include file forum_info.incl.pl1). (Input) status is a standard status code. (Output) It can have the following value: forum_error_table_$not_eligible The user does not have access to obtain information about transaction counts and changes, but the chairman name is still valid in this case. :Entry: forum_info_idx: 08/28/86 forum_$forum_info_idx Function: This entry is used to obtain information about a Forum meeting. It is the same as the forum_info entry point except that a forum_idx is used to identify the meeting instead of a pathname. Syntax: declare forum_$forum_info_idx entry (fixed bin, char(*), fixed bin(71), ptr, fixed bin(35)); call forum_$forum_info_idx (forum_idx, access_name, access_time, forum_info_ptr, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) access_name is the Person_id.Project_id.tag for which access is to be calculated. If blank, the access_name of the caller is used. The per-user information returned is for the Person_id portion of access_name. (Input) access_time changed information is calculated from the specified date-time. Usually, "clock ()" should be passed. (Input) forum_info_ptr is a pointer to a copy of the forum_info structure (see the include file forum_info.incl.pl1). (Input) status is a standard status code. (Output) It can have the following value: forum_error_table_$not_eligible The user does not have access to obtain information about transaction counts and changes, but the chairman name is still valid in this case. :Entry: forum_limits: 08/28/86 forum_$forum_limits Function: This entry is used to obtain various pieces of information about an open Forum meeting. This entry point is obsolete. The forum_$real_forum_limits entry point should be used instead. Syntax: declare forum_$forum_limits entry (fixed bin, fixed bin, fixed bin, fixed bin, fixed bin, bit(36) aligned, fixed bin(35)); call forum_$forum_limits (forum_idx, last_seen, first_trans, last_trans, new_trans_count, flags, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) last_seen is the index of the most-recently entered transaction that the user has seen, as set by forum_$set_last_seen_idx. (Output) first_trans is the index of the oldest transaction in the meeting. (Output) last_trans is the index of the most recent transaction in the meeting. (Output) new_trans_count is the number of transactions entered since last_seen by users other than the caller. (Output) flags is a collection of switches. (Output) status is a standard status code. (Output) :Entry: get_forum_path: 03/06/85 forum_$get_forum_path Function: This entry is used to determine the actual name of the meeting instead of the name of the link used to access it. Syntax: declare forum_$get_forum_path entry (char(*), char(*), char(*), char(*), fixed bin(35)); call forum_$get_forum_path (dirname, entryname, forum_dirname, forum_entryname, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) forum_dirname is the pathname of the directory where the meeting actually resides. (Output) forum_entryname is the primary name of the meeting. (Output) status is a standard status code. (Output) :Entry: get_forum_path_idx: 03/06/85 forum_$get_forum_path_idx Function: This entry is used to determine the actual name of the meeting instead of the name of the link used to access it. It is the same as the get_forum_path entry point except that a forum_idx is used to identify the meeting instead of a pathname. Syntax: declare forum_$get_forum_path_idx entry (fixed bin, char(*), char(*), fixed bin(35)); call forum_$get_forum_path_idx (forum_idx, forum_dirname, forum_entryname, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) forum_dirname is the pathname of the directory where the meeting actually resides. (Output) forum_entryname is the primary name of the meeting. (Output) status is a standard status code. (Output) :Entry: get_message: 03/06/85 forum_$get_message Function: This entry is used to read out the greeting message set by the chairman using the forum_$set_message entry. Syntax: declare forum_$get_message entry (fixed bin, char(*), fixed bin(35)); call forum_$get_message (forum_idx, message, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) message is the text of the message, this can contain at most 256 characters. (Output) status is a standard status code. (Output) It can have the following value: forum_error_table_$no_message There is no chairman greeting message for this meeting. :Entry: get_switch: 03/06/85 forum_$get_switch Function: This entry is used to return the value of several switches associated with a Forum meeting or its participants. Syntax: declare forum_$get_switch entry (char (*), char (*), char (*), char (*), bit (1) aligned, fixed bin (35)); call forum_$get_switch (dirname, entryname, person_id, switch_name, switch_setting, status); Arguments: dirname is the name of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) person_id the user name of the user whose per-user switch value is desired. (Input) The project_id should not be given. Starnames are not permitted. If this is blank, the current user is assumed. switch_name is the name of the switch to retrieve. (Input) See "List of Switches" below. switch_setting is the returned switch setting. (Output) status is a standard status code. It may have the following value: forum_error_table_$invalid_switch_name the switch_name is not one of the valid switches. List of switches: adjourned, adj prevents users from entering the meeting. meeting_eligibility_messages, mtg_emsg turns on printing of eligibility messages for this meeting. notify, nt turns on the notify switch for the meeting. This means that an interactive message will be sent each time a transaction is entered if the user is logged in and has issued the forum_accept_notifications command. participating, part turns on the participation switch for the meeting. safety changes the storage system safety switch for the meeting. The meeting cannot be deleted if this switch is on. :Entry: get_transaction_map: 03/06/85 forum_$get_transaction_map Function: This entry is used to retrieve a bit map representing the transactions that a given participant has seen. This entrypoint cannot be used with meetings created with pre-MR11 software. Syntax: declare forum_$get_transaction_map entry (char (*), char (*), char (*), bit (*), fixed bin (35)); call forum_$get_transaction_map (dirname, entryname, person_id, seen_map, status); Arguments: dirname is the name of the directory containing the meeting. (Input) entryname is the name of the meeting. (Input) The ".forum" suffix is required. person_id The username of the user whose transaction seen map is desired. (Input) Starnames are not permitted. If this is blank, the current user is assumed. seen_map is a bit map indicating which transactions the user has seen. If the n'th bit in this map is a "1"b, then the user has seen transaction "n". This variable must be large enough to hold one bit for each transaction in the meeting. status is a standard status code. :Entry: get_uid_file: 03/06/85 forum_$get_uid_file Function: This entry returns the file system unique identifier of a meeting. Syntax: declare forum_$get_uid_file entry (char (*), char (*), bit (36) aligned, fixed bin (35)); call forum_$get_uid_file (dir_name, entryname, uid, code); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. (Input) The meeting suffix is required. uid is the unique identifier of the meeting. (Output) code is a standard status code. :Entry: list_forum_acl: 08/28/86 forum_$list_forum_acl Function: This entry is used either to list the entire access control list (ACL) meeting or to return the access modes of specified ACL entries. This entry cannot be used with meetings created with pre-MR11 software. Syntax: declare forum_$list_forum_acl entry (char(*), char(*), ptr, ptr, ptr, fixed bin, fixed bin(35)); call forum_$list_forum_acl (dir_name, entryname, area_ptr, area_ret_ptr, acl_ptr, acl_count, code); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. (Input) The ".forum" suffix is required. area_ptr points to an area in which the list of ACL entries, which make up the entire ACL of the segment, is allocated. (Input) If area_ptr is null, then the user wants access modes for certain ACL entries; these will be specified by the structure pointed to by acl_ptr. area_ret_ptr points to the start of the allocated list of ACL entries. (Output) acl_ptr if area_ptr is null, then acl_ptr points to an ACL structure, segment_acl, into which mode information is placed for the access names specified in that same structure (see the include file acl_structures.incl.pl1). (Input) acl_count is the number of entries in the ACL structure. (Input or Output) Input is the number of entries in the ACL structure identified by acl_ptr. Output is the number of entries in the segment_acl structure allocated in the area pointed to by area_ptr, if area_ptr is not null. code is a storage system status code. (Output) Notes: If acl_ptr is used to obtain modes for specified access names (rather than for all access names on a segment), then each ACL entry in the segment_acl structure either has status_code set to 0 and contains the segment's mode or has status_code set to error_table_$user_not_found and contains a mode of 0. :Entry: list_v1_forum_acl: 03/06/85 forum_$list_v1_forum_acl Function: This entry is used to list the ACL of a Forum meeting. Syntax: declare forum_$list_v1_forum_acl entry (char(*), char(*), ptr, ptr, fixed bin, fixed bin(35)); call forum_$list_v1_forum_acl (dirname, pathname, area_ptr, acl_ptr, acl_count, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) area_ptr points to an area where the segment_acl structure is to be allocated. (Input) It can not be null. acl_ptr points to the allocated segment_acl structure. This structure is described in the hcs_$add_acl_entries subroutine. (Output) acl_count is the number of ACL entries in the segment_acl structure. (Output) status is a standard status code. (Output) :Entry: list_users: 08/28/86 forum_$list_users Function: This entry is used to extract information about the participants in a Forum meeting. Syntax: declare forum_$list_users entry (char(*), char(*), ptr, ptr, fixed bin(35)); call forum_$list_users (dirname, entryname, area_ptr, user_list_ptr, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) area_ptr is a pointer to an area where the user_list structure is to be allocated. (Input) It can not be null. user_list_ptr is a pointer to the user_list structure (see the include file forum_user_list.incl.pl1). (Output) status is a standard status code. (Output) :Entry: list_users_idx: 08/28/86 forum_$list_users_idx Function: This entry is used to extract information about the participants in a Forum meeting. It is the same as the list_users entry point except that a forum_idx is used to identify the meeting instead of a pathname. Syntax: declare forum_$list_users_idx entry (fixed bin, ptr, ptr, fixed bin(35)); call forum_$list_users_idx (forum_idx, area_ptr, user_list_ptr, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) area_ptr is a pointer to an area where the user_list structure is to be allocated. (Input) It can not be null. user_list_ptr is a pointer to the user_list structure (see the include file forum_user_list.incl.pl1). (Output). status is a standard status code. (Output) :Entry: next_transaction: 12/04/85 forum_$next_transaction Function: This entry returns the index of the next unexpunged transaction relative to a supplied transaction index. Syntax: declare forum_$next_transaction entry (fixed bin, fixed bin, fixed bin, fixed bin (35)); call forum_$next_transaction (forum_idx, trans_idx, next_idx, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) trans_idx is the index of the transaction where the search is to start. (Input) next_idx is the index of the unexpunged transaction entered most recently after trans_idx. (Output) status is a standard status code. (Output) It can have the following values: forum_error_table_$invalid_trans_idx There is no transaction corresponding to the supplied index. forum_error_table_$no_transactions There is no next unexpunged transaction. :Entry: open_forum: 03/06/85 forum_$open_forum Function: This entry opens a meeting and returns the forum_idx used in many of the other calls to forum_. Syntax: declare forum_$open_forum entry (char(*), char(*), fixed bin, fixed bin(35)); call forum_$open_forum (dirname, entryname, forum_idx, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) forum_idx is the index number used in subsequent calls to forum_ that take a forum index. All coexistent openings of the same meeting in the same process will return the same number. (Output) status is a standard status code. If this is non-zero the meeting could not be opened. (Output) It can have one of the following values: forum_error_table_$meeting_adjourned The chairman has adjourned the meeting. Only the chairman can attend. forum_error_table_$no_such_forum The dirname-entryname pair does not exist. forum_error_table_$not_a_forum The segment named by dirname and entryname is not a Forum meeting. forum_error_table_$not_eligible The caller has insufficient access to participate in the meeting. :Entry: previous_transaction: 12/04/85 forum_$previous_transaction Function: This entry returns the index of the previous unexpunged transaction relative to a supplied transaction index. Syntax: declare forum_$previous_transaction entry (fixed bin, fixed bin, fixed bin, fixed bin (35)); call forum_$previous_transaction (forum_idx, trans_idx, prev_idx, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) trans_idx is the index of the transaction where the search is to start. (Input) prev_idx is the index of the unexpunged transaction entered most recently before trans_idx. (Output) status is a standard status code. (Output) It can have the following values: forum_error_table_$invalid_trans_idx There is no transaction corresponding to the supplied index. forum_error_table_$no_transactions There is no previous unexpunged transaction. :Entry: read_trans: 08/28/86 forum_$read_trans Function: This entry is used to read a transaction from a Forum meeting. Syntax: declare forum_$read_trans entry (fixed bin, fixed bin, ptr, ptr, fixed bin(35)); call forum_$read_trans (forum_idx, trans_idx, area_ptr, forum_user_trans_ptr, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) trans_idx is the index of the transaction to be read. (Input) area_ptr is a pointer to an area where the forum_user_trans structure is to be allocated. (Input) forum_user_trans_ptr is a pointer to the forum_user_trans structure (see the include file forum_user_trans.incl.pl1). (Output) status is a standard status code. (Output) It can have the following values: forum_error_table_$invalid_trans_idx There is no transaction corresponding to the supplied index. forum_error_table_$trans_deleted The deleted switch is set for this transaction and the caller is neither the chairman nor the author. forum_error_table_$trans_reaped The transaction has been physically removed from the meeting. :Entry: rechain: 12/27/85 forum_$rechain Function: This entry changes transaction chaining information, either removing a transaction from its current chain or moving it to a different chain. A transaction subject may be changed in either case. Syntax: declare forum_$rechain entry (fixed bin, fixed bin, fixed bin, char (*), fixed bin, (35)); call forum_$rechain (forum_idx, trans_idx, pref, new_subject, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) trans_idx is the index of the transaction to be rechained. (Input) pref is the index of any transaction in the chain to which the transaction named by trans_idx should be attached. If pref is zero, then the transaction is removed from its transaction chain. new_subject is the new subject for the transaction named by trans_idx. If new_subject is "", then the subject is not changed. status is a standard status code. (Output) Access required: The caller must have chairman access to the meeting. :Entry: refuse_notifications: 03/06/85 forum_$refuse_notifications Function: This entry turns off reception of forum notifications by the calling process. Syntax: declare forum_$refuse_notifications entry (fixed bin(35)); call forum_$refuse_notifications (status); Arguments: status is a standard status code. (Output) It can have the following value: forum_error_table_$no_notify_seg The notifications database could not be initiated. :Entry: replace_forum_acl: 08/28/86 forum_$replace_forum_acl Function: This entry replaces an entire access control list (ACL) for a meeting with a user-provided ACL, and can optionally add an entry for *.SysDaemon.* with mode rw to the new ACL. This entry cannot be used on meetings created with pre-MR11 software. Syntax: declare forum_$replace_forum_acl entry (char(*), char(*), ptr, fixed bin, bit(1), fixed bin(35)); call forum_$replace_forum_acl (dirname, entryname, acl_ptr, acl_count, no_sysdaemon_sw, code); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the entryname of the meeting. (Input) The ".forum" suffix is required. acl_ptr points to the user supplied segment_acl structure that is to replace the current ACL (see the include file acl_structures.incl.pl1). (Input) acl_count is the number of entries in the segment_acl structure. (Input) no_sysdaemon_sw is a switch that indicates whether an rw *.SysDaemon.* entry is to be put on the ACL of the meeting after the existing ACL has been deleted and before the user-supplied segment_acl entries are added. (Input) "0"b adds rw *.SysDaemon.* entry "1"b replaces the existing ACL with only the user-supplied segment_acl code is a storage system status code. (Output) Notes: If acl_count is zero, then the existing ACL is deleted and only the action indicated (if any) by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, processing of the segment_acl entries is performed top to bottom, allowing later entries to overwrite previous ones if the access_name in the segment_acl structure is identical. :Entry: set_delete_sw: 03/06/85 forum_$set_delete_sw Function: This entry is used to delete or retrieve a transaction. Syntax: declare forum_$set_delete_sw entry (fixed bin, fixed bin, bit(1) aligned, fixed bin(35)); call forum_$set_delete_sw (forum_idx, trans_idx, delete_sw, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) trans_idx is the index of the transaction whose delete switch is to be changed. (Input) delete_sw should be on to delete the transaction, or off to retrieve it. status is a standard status code. (Output) It can have one of the following values: forum_error_table_$chairman_only The caller is neither the author of the transaction nor the chairman of the meeting. forum_error_table_$invalid_trans_idx There is no transaction corresponding to the supplied index. :Entry: set_event_channel: 03/06/85 forum_$set_event_channel Function: This entry is used to set the event channel used to send wakeups when interesting forum events occur. Syntax: declare forum_$set_event_channel entry (char(*), char(*), fixed bin(71), fixed bin(35)); call forum_$set_event_channel entry (dirname, entryname, event_channel, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) event_channel is the event channel which should receive wakeups from other users attending the same meeting. (Input) status is a standard status code. (Output) Notes: Currently, the only wakeup sent by Forum occurs when a transaction is entered while you are attending the meeting. :Entry: set_event_channel_idx: 03/06/85 forum_$set_event_channel_idx Function: This entry is used to set the event channel used to send wakeups when interesting forum events occur. Syntax: declare forum_$set_event_channel_idx entry (fixed bin, fixed bin(71), fixed bin(35)); call forum_$set_event_channel_idx entry (forum_idx, event_channel, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) event_channel is the event channel which should receive wakeups from other users attending the same meeting. (Input) status is a standard status code. (Output) Notes: See the forum_$set_event_channel entry point for a description of interprocess messages used by Forum. :Entry: set_forum_acl: 08/28/86 forum_$set_forum_acl Function: This entry adds specified access modes to the access control list (ACL) of a meeting. If an access name already appears on the ACL of the segment, its mode is changed to the one specified by the call. This entry cannot be used on meetings created with pre-MR11 software. Syntax: declare forum_$set_forum_acl entry (char (*), char (*), ptr, fixed bin, fixed bin (35)); call forum_$set_forum_acl (dirname, entryname, acl_ptr, acl_count, code); Arguments: dirname is the name of the directory containing the meeting. (Input) entryname is the name of the meeting. (Input) The meeting suffix is required. acl_ptr points to a user-filled segment_acl_array structure (see the include file acl_structures.incl.pl1). (Input) acl_count contains the number of ACL entries in the segment_acl_array structure. (Input) code is a storage system status code. (Output) :Entry: set_message: 03/06/85 forum_$set_message Function: This entry is used to set a chairman's greeting message for a Forum meeting. Syntax: declare forum_$set_message entry (fixed bin, char(*), fixed bin(35)); call forum_$set_message (forum_idx, message, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) message is the text message, this can contain at most 256 characters. (Input) status is a standard status code. (Output) It can have one of the following values: forum_error_table_$chairman_only The caller is not the chairman of the meeting. forum_error_table_$message_too_long The message exceeds the 256 character limit. :Entry: set_seen_switch: 03/06/85 forum_$set_seen_switch Function: This entry marks a transaction as having been seen by a participant. This entry cannot be used on meetings created with pre-MR11 software. Syntax: declare forum_$set_seen_switch entry (fixed bin, char (*), fixed bin, bit (1) aligned, fixed bin (35)); call forum_$set_seen_switch (forum_idx, person_id, trans_idx, value, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) person_id is the user name of the participant for whom the transaction is to be marked as seen. (Input) If this is blank, the person_id of the caller is assumed. Chairman access is required to change a seen switch for another participant. trans_idx is the number of the transaction to be marked. (Input) value is on if the transaction is to be marked as seen, and off otherwise. (Input) status is a standard status code. (Output) :Entry: set_switch: 03/06/85 forum_$set_switch Function: This entry is used to change several switches associated with a Forum meeting or its participants. Syntax: declare forum_$set_switch entry (char(*), char(*), char(*), char(*), bit(1) aligned, fixed bin(35)); call forum_$set_switch (dirname, entryname, person_id, switch_name, switch_setting, status); Arguments: dirname is the pathname of the directory containing the meeting. (Input) entryname is the name of the meeting. The ".forum" suffix is required. (Input) person_id is the Person_id of the user on whose behalf you are setting the switch. The Project_id should not be given. Starnames are not permitted. If this is blank, the current user is assumed. Only the chairman of a forum can set switches for persons other than herself. (Input) switch_name is the name of the switch to set. See "List of Switches" below. (Input) switch_setting is the new switch setting. (Input) status is a standard status code. It can have one of the following values: forum_error_table_$chairman_only Person_id does not identify the caller and the caller is not the chairman. forum_error_table_$invalid_switch_name The switch_name is not one of the valid switches. forum_error_table_$switch_not_changed The old setting was the same as the new setting. List of switches: adjourned, adj Prevents users from entering the meeting. Only the chairman can set this switch. meeting_eligibility_messages, mtg_emsg Turns on printing of eligibilty messages for this meeting. This switch can only be set by the chairman. notify, nt Turns on the notify switch for the meeting. This means that an interactive message will be sent each time a transaction is entered if the user is logged in and has issued the forum_accept_notifications command. participating, part Turns on the participation switch for the meeting. safety Changes the storage system safety switch for the meeting. The meeting cannot be deleted if this switch is on. :Entry: set_switch_idx: 03/06/85 forum_$set_switch_idx Function: This entry is used to change several switches associated with a Forum meeting or its participants. It is the same as the set_switch entry point except that a forum_idx is used to identify the meeting instead of a pathname. Syntax: declare forum_$set_switch_idx entry (fixed bin, char(*), char(*), bit(1) aligned, fixed bin(35)); call forum_$set_switch_idx (forum_idx, person_id, switch_name, switch_setting, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) person_id is the Person_id of the user on whose behalf you are setting the switch. The Project_id should not be given. Starnames are not permitted. If this is blank, the current user is assumed. Only the chairman of a forum can set switches for persons other than herself. (Input) switch_name is the name of the switch to set. See "List of switches" below. (Input) switch_setting is the new switch setting. (Input) status is a standard status code. It can have one of the following values: forum_error_table_$chairman_only Person_id does not identify the caller and the caller is not the chairman. forum_error_table_$invalid_switch_name The switch_name is not one of the valid switches. forum_error_table_$switch_not_changed The old setting was the same as the new setting. List of switches: access_changed Specifies that the ACL on the meeting has changed. This switch is set by the forum_chairman_$set_forum_acl entry point, and should normally only be turned off by this subroutine. adjourned, adj Prevents users from entering the meeting. Only the chairman can set this switch. deleted Specifies that the attendee record for this user should be marked as deleted. meeting_eligibility_messages, mtg_emsg Turns on printing of eligibilty messages for this meeting. This switch can only be set by the chairman. message_seen Specifies that the chairman message on the meeting has changed. This switch is set by the forum_$set_message entry point, and should normally only be turned off by this subroutine. notify, nt Turns on the notify switch for the meeting. This means that an interactive message will be sent each time a transaction is entered if the user is logged in and has issued the forum_accept_notifications command. participating, part Turns on the participation switch for the meeting. safety Changes the storage system safety switch for the meeting. The meeting cannot be deleted if this switch is on. :Entry: trans_ref_info: 03/06/85 forum_$trans_ref_info Function: This entry is used to obtain information about an individual transaction. This entry is obsolete. The forum_$real_trans_ref_info entry should be used instead. Syntax: declare forum_$trans_ref_info entry (fixed bin, fixed bin, fixed bin, fixed bin, bit(1) aligned, fixed bin(35)); call forum_$trans_ref_info (forum_idx, trans_idx, prev_ref, next_ref, deleted_sw, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) trans_idx is the index of the transaction for which information is desired. (Input) prev_ref is the index of the preceding transaction in the same transaction chain. This is zero if the transaction is the first in a chain. (Output) next_ref is the index of the next transaction in the same transaction chain. This is zero if the transaction is the last in a chain. (Output) deleted_sw is set if the transaction has been marked as deleted. (Output) status is a standard status code. (Output) It can have one of the following values: forum_error_table_$invalid_trans_idx There is no transaction corresponding to the supplied index. forum_error_table_$trans_reaped The transaction has been physically removed from the meeting. :Entry: trans_time_info: 03/06/85 forum_$trans_time_info Function: This entry returns the indexes of transactions entered during a given time span. Syntax: declare forum_$trans_time_info entry (fixed bin, fixed bin(71), fixed bin(71), fixed bin, fixed bin, fixed bin(35)); call forum_$trans_time_info (forum_idx, low_time, high_time, low_trans, high_trans, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) low_time is the timestamp of the low end of the time span. (Input) high_time is the timestamp of the high end of the time span. (Input) low_trans is the index of the first transaction entered after low_time. If there are no transactions that new, than the index of the highest transaction in the meeting is returned. (Output) high_trans is the index of the transaction entered immediately before high_time. If no transactions were entered before then, zero is returned. (Output) status is a standard status code. (Output). :Entry: validate_uid: 03/06/85 forum_$validate_uid Function: This entry is used to determine if a given meeting unique identifier (uid) corresponds to a given meeting. Syntax: declare forum_$validate_uid entry (fixed bin, bit(36) aligned, fixed bin(35)); call forum_$validate_uid (forum_idx, forum_uid, status); Arguments: forum_idx identifies a meeting opened by forum_$open_forum. (Input) forum_uid is the uid of the meeting. Normally this is obtained from Forum interprocess messages. (Input) status is a standard status code. (Output) It can have the following value: forum_error_table_$incorrect_uid The supplied uid is not the unique identifier of the meeting identified by forum_idx. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved