MULTICS TECHNICAL BULLETIN MTB-659 To: MTB Distribution From: Jim Lippard Date: June 1, 1984 Subject: message facility This MTB describes plans for the reimplementation of the Multics message facility. This reimplementation is based around a message_facility_ subroutine which will allow programs such as emacs, xmail, and xservice to handle incoming interactive messages without stepping on each other. Comments and questions should be sent to the author: by Multics mail: Lippard.Multics on System M or MIT-Multics via forum: >site>forum>Message_Facility.forum (msgs) or by telephone: (602) 862-6641 or HVN 357-6641 _________________________________________________________________ Multics Project working documentation. Not to be reproduced or distributed outside the Multics project. CONTENTS Page Problems in the existing message facility . . . . . . . . . . . . . . 4 Proposed changes . . . . . . . . . . . 5 Changes to accept_messages . . . . . . 5 accept_messages . . . . . . . . . . 7 Changes to delete_message and print_messages . . . . . . . . . . . 11 delete_message . . . . . . . . . . 12 print_messages . . . . . . . . . . 14 Changes to send_message . . . . . . . 17 send_message . . . . . . . . . . . 18 New commands . . . . . . . . . . . . . 22 accepting . . . . . . . . . . . . . 23 message_status . . . . . . . . . . 24 Implementation of message_facility_ . 26 Alarm and wakeup handlers . . . . . 30 message_facility_ . . . . . . . . . 31 get_next_msgf_mbx_ptr . . . . . 31 get_msgf_mbx_ptr . . . . . . . . 31 free_msgf_mbx_ptr . . . . . . . 32 get_wakeup_state . . . . . . . . 32 set_wakeup_state . . . . . . . . 33 get_mbx_path . . . . . . . . . . 33 get_prefix . . . . . . . . . . . 34 set_prefix . . . . . . . . . . . 34 get_message_format . . . . . . . 35 set_message_format . . . . . . . 36 get_alarm_handler . . . . . . . 36 set_alarm_handler . . . . . . . 37 get_wakeup_handler . . . . . . . 37 set_wakeup_handler . . . . . . . 38 get_last_message_info . . . . . 39 get_current_message_info . . . . 40 get_msg_array_ptr . . . . . . . 41 read_message . . . . . . . . . . 42 set_seen_switch . . . . . . . . 43 send_message . . . . . . . . . . 43 send_message_access_class . . . 45 delete_message . . . . . . . . . 47 Changes needed in other parts of the system . . . . . . . . . . . . . . . 48 error_table_ . . . . . . . . . . . 48 Lippard i 06/01/84 MTB-659 CONTENTS (cont) Page ring 1 mailbox primitives . . . . . 48 mlsys_utils_ . . . . . . . . . . . 48 Lippard ii 06/01/84 MTB-659 The current message facility is sadly lacking in many areas, as well as being full of bugs. Most of the message facility commands are written into one large program, making it difficult to maintain. This MTB proposes that the Multics message facility be reimplemented around a central subroutine called message_facility_, with the current commands broken into separate modules for maintainability. The message_facility_ subroutine should also allow temporary interception of messages for such things as emacs, xmail, and xservice. Lippard 3 06/01/84 MTB-659 _P_R_O_B_L_E_M_S _I_N _T_H_E _E_X_I_S_T_I_N_G _M_E_S_S_A_G_E _F_A_C_I_L_I_T_Y The existing message facility is plagued by problems such as many obscure bugs and unmaintainability of the code. In addition, there is a need for a way for applications to determine on which mailboxes messages are being accepted, to intercept them temporarily, and reset things the way the were when it took over. The -call control argument to accept_messages is not sufficient because there is still no way for the procedure being called to know from which mailboxes to expect messages. Another problem with -call is that if the reminder feature is being used, the call string will be executed once for each undeleted message in the mailbox every time the alarm timer goes off. Lippard 4 06/01/84 MTB-659 _P_R_O_P_O_S_E_D _C_H_A_N_G_E_S Of primary importance in changing the message facility is fixing the bugs. Together with adding subroutine interfaces and adding new features, the best way to take care of this is to start over from scratch, building the message facility commands on top of a message_facility_ subroutine (described later in this document). Information such as on which mailboxes messages are being accepted must be maintained so that other applications can use this information to intercept messages. It is also desirable that all of the message facility commands understand mail table entries and control arguments accepted by the mail system. The send_message command should accept mail system addresses (with exceptions discussed later) and the other commands should accept mail system mailbox specifiers. _C_H_A_N_G_E_S _T_O _A_C_C_E_P_T__M_E_S_S_A_G_E_S The accept_messages command will now print old messages by default (-print). A -no_print (-npr) control argument will be added to override this behavior. This will prevent naive users from ignoring mail sent to them while they are not logged in. The -pathname (-pn) control argument will be made obsolete, retained but undocumented. If messages are accepted on a mailbox which does not exist (and it is not the user's default mailbox), the user will be queried as to whether or not it should be created. Currently the default mailbox is created, without comment. A comment about the mailbox creation should be given unless -brief (-bf) is given. Attempting to accept messages on a mailbox on which a process is already accepting messages will result in a warning messages and messages will not be accepted. This may be overridden using the -force (-fc) control argument. The short name -pfx is added to -prefix. The -short_prefix (-shpfx) and -no_short_prefix (-nshpfx) control arguments are added. -short_prefix gives the current behavior and is the default. -no_short_prefix causes the prefix to be printed only for messages which are not printed in short format (i.e., the previous message was from the same sender, with the same comment field, on the same date, within 5 minutes). Use of -no_short_prefix implies -short. Use of the -time control argument will assume -hold, since -time is useless without it. Lippard 5 06/01/84 MTB-659 Message numbers will be consecutive per-mailbox, instead of consecutive per-process. The text of mail notifications will be printed, rather than just printing "You have mail". This will allow send_mail to put mail subjects in the notifications, and allow for a way to distinguish computer-generated messages (such as answering service messages, IO Daemon notifications, etc.) from regular interactive messages. Messages with the notify flag on also will not change the information returned by last_message_time, last_message_sender, or last_message. If the user is accepting messages on a mailbox that is not the default, the entry name of the mailbox will be printed when messages are received to avoid confusion. Lippard 6 06/01/84 MTB-659 _______________ _______________ accept_messages accept_messages _______________ _______________ ACCEPT_MESSAGES SYNTAX AS A COMMAND am {mbx_specification} {-control_args} FUNCTION initializes or reinitializes the user's process for accepting both messages that are sent by the send_message command and notifications of the form "You have mail." that are sent by the send_mail command. ARGUMENTS mbx_specification | specifies the mailbox from which messages are to be deleted. | If not given, the user's default mailbox | (>udd>Project>Person>Person.mbx) is used. | LIST OF MAILBOX SPECIFICATIONS | -mailbox path, -mbx path | specifies the pathname of a mailbox. The suffix "mbx" is | added if necessary. | -user STR | specifies either a user's default mailbox or an entry in the | system mail table. See "Notes on mailbox selection by user" | below for more information. | -save path, -sv path | specifies the pathname of a savebox. The suffix ".sv.mbx" is | added if necessary. | -log | specifies the user's logbox and is equivalent to: | -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx | STR | is any non-control argument and is first interpreted as: | -mailbox STR | if no mailbox is found, this specification is then interpreted | as: | -save STR | if no savebox is found, this specification is then interpreted | as: | -user STR | Lippard 7 06/01/84 MTB-659 _______________ _______________ accept_messages accept_messages _______________ _______________ CONTROL ARGUMENTS -brief, -bf prevents accept_messages from informing the user that it is creating a mailbox, and prints messages in short format. -call {cmdline} when the message is received, instead of printing it in the default format, accept_messages calls the command processor with a string of the form: cmdline number sender time message {path} where: cmdline is any Multics command line; cmdline must be enclosed in quotation marks if it contains blanks or other command language characters. number is the sequence number of the message, assigned when the -hold control argument is used; otherwise, number is 0. sender is the User_id of the person who sent the message. time is the date-time the message was sent. message is the actual message sent. path is the pathname of the mailbox to which the message was sent. If the message was sent to the default mailbox, path is omitted. To reverse the effect of a previously specified -call control argument, the user can specify the -call control argument with | no cmdline argument. The maximum length of cmdline is 512 | characters. -flush DT discards messages sent before the specified date-time, where DT is a string acceptable to the convert_date_to_binary_ subroutine (described in the MPM Subroutines). This control argument is intended to be used by operators and consultants. Lippard 8 06/01/84 MTB-659 _______________ _______________ accept_messages accept_messages _______________ _______________ -force, -fc | causes messages to be accepted on the specified mailbox even | if another process is already accepting messages on it. | -hold, -hd holds messages until explicitly deleted by the delete_message command. Messages printed when the -hold control argument is in effect are preceded by an identifying number. -long, -lg precedes every message printed by the sender's Person_id and Project_id. This is the default. -no_hold, -nhd reverts the -hold control argument. -mail, -ml | causes notifications of the form "You have mail" to be printed | when mail is sent to the mailbox. (Default) | -no_mail, -nml | prevents mail notifications from being printed when mail is | received in the mailbox. | -prefix STR, -pfx STR | causes STR to be printed before printing a message from this mailbox. STR can be up to 12 characters long and can contain the ioa_ control strings ^/, ^| and ^- if desired. -short_prefix, -shpfx | specifies that the prefix is printed when messages are printed | in short format. (Default) | -no_short_prefix, -nshpfx | specifies that the prefix is not printed when messages are | printed in short format. | -print, -pr prints all messages that were received since the last time the user was accepting messages. (Default) | -no_print, -npr | suppresses printing of old messages. | -short, -sh precedes consecutive messages from the same sender by "=:" instead of the Person_id and Project_id. -time N, -tm N prints undeleted messages every N minutes, preceded by a Lippard 9 06/01/84 MTB-659 _______________ _______________ accept_messages accept_messages _______________ _______________ message of the form "You have X messages" where X is the number of undeleted messages. If N equals 0, time mode is | reset. Use of this control argument implies -hold. NOTES The user should not give conflicting control arguments in the same invocation of the command (i.e., -long and -short or -long and -brief). A default mailbox is created automatically the first time a user issues either print_mail, read_mail, accept_messages, or print_messages. The default mailbox is: >udd>Project_id>Person_id>Person_id.mbx Messages sent when the user is not logged in or when the user is deferring messages (see the defer_messages command) are saved in the mailbox and can be read later by invoking the print_messages command. The send_mail command stores mail in the same mailbox. It is not advisable for several users to share the same mailbox. At any time, only one process can be accepting messages from a | given mailbox. If a second process attempts to accept messages | on a mailbox, a warning message will be printed and messages will | continue to be routed to the first process. Use of the -force | (-fc) control argument will cause the second process to take over | the accept_messages function. The first process will receive no indication that messages are being routed to the second process. If the second process then logs out or is destroyed, the messages do not revert to an earlier process. Thus, a user who sends a message to that mailbox will be informed that the addressee is currently not accepting messages or is not logged in. | It is possible to accept messages on more than one mailbox at a | time, and to accept messages on a mailbox other than the default. | If a mailbox other than the default is to be used, and it does | not exist, then the accept_messages command queries the user as | to whether or not it should be created. When messages are | printed from a mailbox other than the default, the mailbox is | always identified. Lippard 10 06/01/84 MTB-659 _C_H_A_N_G_E_S _T_O _D_E_L_E_T_E__M_E_S_S_A_G_E _A_N_D _P_R_I_N_T__M_E_S_S_A_G_E_S The delete_message and print_messages commands will add the control arguments -match, -exclude, -comment (-com), -before, and -after to allow selection of messages to be processed. Both will also accept messages of ranges, and the keywords "all", "first", and "last". The -pathname (-pn) control argument is obsolete and will be retained but undocumented. The header printed by the print_messages command when reading a mailbox to which the user only has "o" permission will now say "You have N message(s) in PATH" (with "messages" properly plural or singular) instead of "Messages from yourself". The user's default mailbox will be created by print_messages if it does not already exist. An appropriate comment will be printed unless -brief is given. Message numbers will be assigned to messages read from mailboxes to which a user has "o" but not "d" extended access. These message numbers are understood by print_messages and delete_message. Currently, delete_message cannot be used on a mailbox unless the user has "d" extended access. The current behavior for mailboxes to which the user does have "d" extended access will remain the same: if the user is not holding messages on the mailbox, they will be deleted after being printed by print_messages, and no message numbers will be assigned. The print_messages command, when there are no messages in the mailbox, will print an appropriate error message instead of being silent. The -brief (-bf) control argument is added to suppress this message. The print_messages command, when used on a mailbox to which the user does not have "d" extended access, will no longer delete the user's own messages after printing them. Lippard 11 06/01/84 MTB-659 ______________ ______________ delete_message delete_message ______________ ______________ DELETE_MESSAGE SYNTAX AS A COMMAND | dlm {mbx_specification} msg_specs {-control_args} FUNCTION deletes a message sent by the send_message command and saved in a mailbox with the -hold control argument to the accept_messages command. (See the accept_messages command for more details.) ARGUMENTS | mbx_specification | specifies the mailbox from which messages are to be deleted. | If not given, the user's default mailbox | (>udd>Project>Person>Person.mbx) is used. | msg_specs | is one or more numbers or ranges. Numbers are as printed by | the print_message command when accept_messages -hold is in | effect. Ranges are of the form N:M, where Nudd>Project_id>Person_id>Person_id.sv.mbx | STR | is any non-control argument and is first interpreted as: | -mailbox STR | if no mailbox is found, this specification is then interpreted Lippard 12 06/01/84 MTB-659 ______________ ______________ delete_message delete_message ______________ ______________ as: | -save STR | if no savebox is found, this specification is then interpreted | as: | -user STR | CONTROL ARGUMENTS -all, -a deletes all messages from the mailbox. -after DATE_TIME | causes only messages sent after DATE_TIME to be deleted. | -before DATE_TIME | causes only messages sent before DATE_TIME to be deleted. | -comment STR, -com STR | causes only messages with comment fields containing STR to be | deleted. | -from STR, -fm STR | causes only messages sent from STR to be deleted. STR may be | of the form Person.Project, Person, or .Project. | -match STR | causes only messages containing STR to be deleted. | -exclude STR | causes only messages not containing STR to be deleted. | NOTES If no mailbox is specified, the user's default mailbox is assumed. For a description of the mailbox, refer to the accept_messages and print_mail commands. Lippard 13 06/01/84 MTB-659 ______________ ______________ print_messages print_messages ______________ ______________ PRINT_MESSAGES SYNTAX AS A COMMAND | pm {mbx_specification} {msg_specs} {-control_args} FUNCTION prints any interprocess messages that were received (and saved in the user's mailbox) while the user was not accepting messages, not logged in, or accept_messages -hold was in effect. ARGUMENTS | mbx_specification | specifies the mailbox from which messages are to be printed. | If not given, the user's default mailbox | (>udd>Project>Person>Person.mbx) is used. | msg_specs | is one or more numbers or ranges. Numbers are as printed by | the print_message command when accept_messages -hold is in | effect. Ranges are of the form N:M, where Nudd>Project_id>Person_id>Person_id.sv.mbx | STR | is any non-control argument and is first interpreted as: | -mailbox STR | if no mailbox is found, this specification is then interpreted Lippard 14 06/01/84 MTB-659 ______________ ______________ print_messages print_messages ______________ ______________ as: | -save STR | if no savebox is found, this specification is then interpreted | as: | -user STR | CONTROL ARGUMENTS -all, -a prints all messages, including those held by -hold mode (see accept_messages). This is the default. -after DATE_TIME | causes only messages sent after DATE_TIME to be printed. | -before DATE_TIME | causes only messages sent before DATE_TIME to be printed. | -brief, -bf | suppresses the message "You have no messages" when the mailbox | is empty. | -call cmdline for each message, instead of printing calls the command processor with the line: cmdline number sender time message {path} For more details, see the accept_messages command. -comment STR, -com STR | causes only messages with comment fields containing STR to be | printed. | -from STR, -fm STR | causes only messages sent from STR to be printed. STR may be | of the form Person.Project, Person, or .Project. | -last, -lt reprints only the latest message received. -long, -lg prints the sender and date-time of every message, even when the same for two consecutive messages. -match STR | causes only messages containing STR to be printed. | -exclude STR | causes only messages not containing STR to be printed. | Lippard 15 06/01/84 MTB-659 ______________ ______________ print_messages print_messages ______________ ______________ -new when accept_messages -hold mode is in effect, prints only those messages that have not been printed before. The default is to print all held messages. -short, -sh prints messages as with accept_messages -short, omitting redundant sender names in favor of the prefix "=:". This is the default. NOTES Messages are deleted after they are printed unless the -hold argument was given to the accept_messages command. The "last" message remains available for the life of the process or until redefined by a new message. If messages are deferred, it is a good practice to print out pending messages periodically. | A default mailbox is created automatically the first time a user | issues either print_mail, read_mail, accept_messages, or | print_messages. The default mailbox is: | >udd>Project_id>Person_id>Person_id.mbx For a description of the mailbox, refer to the accept_messages and print_mail commands. See also the active functions last_message, last_message_sender, and last_message_time. Lippard 16 06/01/84 MTB-659 _C_H_A_N_G_E_S _T_O _S_E_N_D__M_E_S_S_A_G_E The commands send_message_acknowledge, send_message_express, and send_message_silent will be obsoleted in favor of the new send_message. Control arguments will be added to send_message to duplicate behavior of the three obsolete commands, as well as allowing for previously impossible combinations. The comment field by default contains a string specified by the variable full_name._ in the user's value segment. The -pathname (-pn) control argument will be made obsolete, retained but undocumented. Lippard 17 06/01/84 MTB-659 ____________ ____________ send_message send_message ____________ ____________ SEND_MESSAGE SYNTAX AS A COMMAND | sm {-control_args} address {message} FUNCTION sends messages (one or more, always sent one at a time) to a given user on a given project or to a given mailbox. ARGUMENTS | address can be of the form Person_id.Project_id to specify a mailbox belonging to that person, a string containing at least one ">" | or "<" character to specify the pathname of a mailbox, a mail | table address, one of the arguments "-mailbox" ("-mbx"), | "-log", "-save" ("-sv"), or "-user" immediately followed by a | string giving the pathname of a mailbox, logbox, save box, or | user name respectively; or the argument "-last_destination" | ("-ld") if send_message has been used before in this process. | For more information type "help addresses.gi -section control | argument". All arguments following one of the above are | considered to be message text. message is anything that appears up to the end of the command. It may be one or more words. If message is missing from the command line, send_message enters an input loop, and a multi-line message may be sent. See below. CONTROL ARGUMENTS | -acknowledge, -ack | requests that the recipient's process return an | acknowledgement message when the message is read. It also | implies the -brief (-bf) control argument. See below. | -no_acknowledge, -nack | requests that the recipient's process not return an | acknowledgement message when the message is read. (Default) | -escape, -esc | turns on the ".." escape convention to execute Multics | commands from within input mode for the current message. | (Default) Lippard 18 06/01/84 MTB-659 ____________ ____________ send_message send_message ____________ ____________ -no_escape, -nesc | turns off the ".." escape convention. | -express, -xps | sends the message only if the recipient is likely to see it | immediately, that is, is currently accepting messages. | -no_express, -nxps | always sends the message. (Default) | -comment STR, -com STR | adds a comment of the form (STR) after the user's person and | in the message's header. The default behavior is to insert in | the comment field the value of the variable "full_name._" from | the user's value segment. | -no_comment, -ncom | suppresses insertion of any comment. | -brief, -bf | does not print an error message if the message cannot be sent | or if the recipient is not accepting messages. | -silent, -sil | suppresses all error messages. | -long, -lg | prints error messages. (Default) | -print, -pr | prints the destination the message is being sent to when | -last_destination (-ld) is used. | -no_print, -npr | does not print the destination the message is being sent to | when -last_destination (-ld) is used. (Default) | NOTES For a description of the mailbox, refer to the accept_messages and print_mail descriptions in this manual. All control arguments must precede the address or they will be | sent as message text. | If the message is to contain a parenthesis, bracket, or semi-colon character, that character must be enclosed in quotes. These characters are not treated specially by the send_message command. A single quote character may be typed as """". Lippard 19 06/01/84 MTB-659 ____________ ____________ send_message send_message ____________ ____________ EXAMPLES If WJones on the Alpha project sends the following to RTSmith on the Beta project by using the command line: ! sm RTSmith.Beta need access to your lsg command the message prints on RTSmith's terminal (if RTSmith is accepting messages) as follows: 1) WJones.Alpha 04/20/76 1200.6 mst Tue: need access to your lsg command Input Loop: When send_message enters the input loop it types "Input:" and accepts lines which are sent, one line at a time. Input loop is terminated by a line consisting solely of a period. When in input loop, Multics commands may be executed if typed on a line beginning with two periods. The user can receive messages while in the input loop, so this is a way to hold conversations. If the user is who the message(s) are being sent to changes how he is accepting messages (defers messages, accepts messages, logs out), send_message will print a message to that effect (unless -brief or -silent is specified). Acknowledgements: If an acknowledgement is requested the acknowledgement says: From