11/28/86 ws_ The Work Station subroutine library provides the application programmer with a means of accessing the facilities provided by MOWSE, including facilities for: registering with MOWSE, obtaining information from MOWSE, and making requests of other applications which are registered with MOWSE. In most cases, equivalent functionality has been provided for both machines (the PC and Multics). Help is available (through Multics info segs) for both sides, and is accessed by entering the subroutine or entrypoint name following the help command. For more information on the use of the subroutine library, please consult the MOWSE Application Programmer's Manual. Entry points in ws_: (List is generated by the help command) :Entry: connect_request: 11/28/86 ws_$connect_request Function: Requests a connection to an application which has been loaded by sending a "REQUEST_CONNECT" minor capability to the requested application. Syntax: dcl ws_$connect_request entry (char (*), char (*), fixed bin, ptr, fixed bin (35)); call ws_$connect_request (capability_name, args, system, mcb_ptr, code); Arguments: capability_name (Input) The name of the major capability of the application to which the connect is requested. args (Input) Any command line arguments which may be necessary if the capability is to be started before the connection is made. system (Input) The system of the capability being connected to. mcb_ptr (Input) The pointer to the application's MOWSE Control Block assigned by a call to ws_$create_instance. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Examples: call ws_$connect_request ("bft", "load", REMOTE, mcb_ptr, code); :Entry: connect_response: 11/28/86 ws_$connect_response Function: Replies to an application's request for a connection. This allows the application of the ws_$connect_request call to be notified either of this application's acceptance of the connect request (by supplying the new major capability_number), or rejection of the request (by supplying an error code). The application which made the request for connection will receive the RESPONSE_CONNECT which will indicate the success or fail of the request. Syntax: dcl ws_$connect_response entry (fixed bin(17), fixed bin(17), ptr, fixed bin(35)); call ws_$connect_response (status, major_capability, mcb_ptr, code); Arguments: status (Input) The acceptance/rejectance of the connect request. Values ACCEPT REJECT major_capability (Input) The major capability number of the application to which the response is destined. mcb_ptr (Input) A pointer to the mcb which is associated with the connection. The mcb can be either the original mcb obtained by the application, or the address of a new mcb obtained by the application specifically for this connection. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Examples: call ws_$connect_response (ACCEPT, request_capability, mcb_ptr, code); call ws_$connect_response (REJECT, request_capability, mcb_ptr, code); :Entry: create_instance: 11/28/86 ws_$create_instance Function: Registers the calling routine with MOWSE by assigning it a major capability number and adding it to MOWSE's capability table. The calling routine must supply the name by which it is to be known to MOWSE, and the entry point describing where it is to be invoked by an execute capability. Syntax: dcl ws_$create_instance entry (char(*), char(*), fixed bin(17), fixed bin(17), ptr, ptr, fixed bin(35)) call ws_$create_instance (capability_name, entry_name, inbuff_length, outbuff_length, data_block_ptr, mcb_ptr, code) Arguments: capability_name (Input) The name by which the calling capability will be known to MOWSE. entry_name (Input) The entry point (by name) which will be invoked when MOWSE has a message destined for the application. inbuff_length (Input) The length (in characters) of the message buffer which receives argument data from incoming messages. The buffer will be allocated with the size specified or MINIMUM_BUFFER_SIZE, whichever is larger. outbuff_length (Input) The length (in characters) of the message buffer which will be used for outgoing messages. The buffer will be allocated with the size specified or MINIMUM_BUFFER_SIZE, whichever is larger. data_block_ptr (Input) A pointer to the application's local data which is to be preserved across calls to the capability through MOWSE. This provides an alternate method to static variables of preserving data across the starts and stops of the application's life in MOWSE thus providing reentrancy. mcb_ptr (Output) A pointer to the application's MOWSE Control Block which will be used by MOWSE to maintain information on the application. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: All applications which expect to receive messages must have registered with MOWSE (through create_instance) in order to receive messages. A message is provided to the application when the destination of the message specifies the major capability number of the application. The application will then be invoked at the entry name provided with the message (argument data), its length, and a pointer to the applications data_block as follows: dcl application_$entry_point entry (fixed bin, fixed bin, ptr, fixed bin, ptr, ptr); application_$entry_point (minor_capability, major_sender, arg_ptr, arg_length, mcb_ptr, data_block_ptr); The buffers inbuff and outbuff allow MOWSE to send and receive messages longer than one communications packet (defined by PACKET_SIZE) in a manner transparent to the capability. Examples: call ws_$create_instance ("bft", "bft_$process_event", 256, 256, data_ptr, mcb_ptr, code); :Entry: destroy_instance: 11/28/86 ws_$destroy_instance Function: Removes the reference to the application from MOWSE's capability table and deallocates the inbuff and outbuff message buffer space. Syntax: dcl ws_$destroy_instance entry (ptr, fixed bin(35)); call ws_$destroy_instance (mcb_ptr code); Arguments: mcb_ptr (Input) The pointer to the application's MOWSE Control Block assigned by a call to ws_$create_instance. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Examples: call ws_$destroy_instance (mcb_ptr, code); :Entry: disconnect_request: 11/28/86 ws_$disconnect_request Function: Requests that conversation to the specified application be terminated by sending a REQUEST_DISCONNECT to the specified capability. Syntax: dcl ws_$disconnect_request entry (fixed bin(17), ptr, fixed bin(35)); call ws_$disconnect_request (capability_number, mcb_ptr, code); Arguments: capability_number (Input) The major capability number of the application which is to be disconnected. mcb_ptr (Input) The pointer to the application's MOWSE Control Block assigned by a call to ws_$create_instance. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Examples: call ws_$disconnect_request (bft_major_cap, mcb_ptr, code); :Entry: disconnect_response: 11/28/86 ws_$disconnect_response Function: Notifies the application which requested a disconnect that the disconnect was accepted or rejected. A RESPONSE_DISCONNECT message will be sent to the application which made the disconnect request. Syntax: dcl ws_$disconnect_response (fixed bin(17), fixed bin(17), ptr, fixed bin(35)); call ws_$disconnect_response (status, major_capability, mcb_ptr, code); Arguments: status (Input) The acceptance/rejection of the disconnect request. Values ACCEPT REJECT major_capability (Input) The major capability number of the application to which the response is destined. mcb_ptr (Input) The pointer to the application's MOWSE control block assigned by a call to ws_$create_instance. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Examples: call ws_$disconnect_response (ACCEPT, request_capability, mcb_ptr, code); call ws_$disconnect_response (REJECT, request_capability, mcb_ptr, code); :Entry: execute_capability: 11/28/86 ws_$execute_capability Function: Executes the minor capability function of the specified major capability with the arguments provided. Syntax: dcl ws_$execute_capability entry (fixed bin(17), fixed bin(17), ptr, fixed bin(17), ptr, fixed bin(35)); call ws_$execute_capability (major_capability_number, minor_capability_number, arg_ptr, arg_length, mcb_ptr, code); Arguments: major_capability_number (Input) The identifier of the capability to be executed. minor_capability_number (Input) The identifier of a specific function to be performed by the specified major_capability. arg_ptr (Input) A pointer to the argument data to be supplied to the specified capability, NULL if there is no argument data. arg_length (Input) The length of the argument data in bytes, zero if there is no data. mcb_ptr (Input) The pointer to the application's MOWSE Control Block assigned by a call to ws_$create_instance. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: MOWSE assumes that the argument data has been converted to character string format by the calling application. If not, MOWSE will lose every 9th bit of the argument data as only 8 of the 9 bits per character are transferred to the remote capability. If MOWSE was incapable of starting execution of the specified application, the calling application will be notified through the predefined minor capability FAIL_CAPABILITY. Examples: call ws_$execute_capability (pc_foo_id, add_num_id, num_arg_ptr, num_arg_len, mcb_ptr, code); :Entry: execute_command: 11/28/86 ws_$execute_command Function: Sends a command string to the command processor on the specified system. Syntax: dcl ws_$execute_command entry (char(*), fixed bin(17), fixed bin(17), ptr, fixed bin(35)) call ws_$execute_command (command_string, system, command_id, mcb_ptr, code) Arguments: command_string (Input) The string of characters that is typed on the system to execute the command. system (Input) A constant specifying the system the command_string will be executed on. Values LOCAL_SYSTEM REMOTE_SYSTEM command_id (Output) The tag which will be associated with the command_string being executed and the resultant EXECUTE_COMMAND_REPY predefined minor capability. mcb_ptr (Input) The pointer to the application's MOWSE Control Block assigned by a call to ws_$create_instance. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: There are two ways in which information is returned to the calling application. One is the immediate return which provides the error information as specified in code. The second is through a delayed response message via the predefined minor capability EXECUTE_COMMAND_REPLY which provides the calling application with information at the completion of the command. Two types of information are provided. One is a success or failure of the command - this is important in the case of remote commands which caused the command processor on the remote system to fail. The second is to provide the handler with the major capability number of the application which may have been loaded by the command. Since execute_command calls the system's command processor with the command_string, an application may be called which loads itself into the MOWSE. Thus, an application may use execute_command to load another application. Output from a command executing on the PC (by the PC's command processor) appears on the terminal screen with total disregard to MOWSE. If a terminal emulator is executing and it calls a PC routine through execute_command - such as "dir" - the output appears on the screen without passing through the terminal emulator. Examples: call ws_$execute_command ("dir \user\smith\*.*", REMOTE_SYSTEM, com_id, mcb_ptr, code); call ws_$execute_command ("ls -d >udd>m>Smith", LOCAL_SYSTEM, com_id, mcb_ptr, code); call ws_$execute_command ("bft", REMOTE_SYSTEM, com_id, mcb_ptr, code); :Entry: find_capability_number: 11/28/86 ws_$find_capability_number Function: Finds the major capability number of an application given a capability name. Syntax: dcl ws_$find_capability_number entry (char(*), fixed bin(17), fixed bin(17), fixed bin(35)); call ws_$find_capability_number (capability_name, system_id, major_capability_number, code); Arguments: capability_name (Input) The capability name to be looked for. system_id (Input) The system which is to be looked at to find the capability name. Values LOCAL_SYSTEM major_capability_number (input/output) Indicates where MOWSE is to begin searching of the capability table for the name specified, 0 will find the first case, and returns the major capability number of the found name. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: MOWSE looks for the capability name in its capability table in the following fashion: 1) If the provided major capability number is invalid, MOWSE will begin searching from the top of the table specified by the system_id. 2) If the major capability number is valid, MOWSE will begin searching from the next entry on the same system of the major capability number. 3) If the system id is invalid, MOWSE will search from the first entry on the local CAT. Examples: call ws_$find_capability_number ("bft", major_capability_number, code); :Entry: find_capability_name: 11/28/86 ws_$find_capability_name Function: Finds the name of a capability given its major capability number. Syntax: dcl ws_$find_capability_name entry (fixed bin(17), char(*), fixed bin (35)); call ws_$find_capability_name (major_capability_number, capability_name, code); Arguments: major_capability_number (Input) The major capability number of the capability name to be found. capability_name (Output) The name of the capability. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Examples: ws_$find_capability_name (major_cap, cap_name, code); :Entry: get_status: 11/28/86 ws_$get_status Function: Requests status information from the specified application. Syntax: dcl ws_$get_status entry (fixed bin(17), char(*), char(*), fixed bin(35)); call ws_$get_status (major_number, status_request, status_result, code); Arguments: major_number (Input) The major capability number of the application for which status information is requested. status_request (Input) The argument data to be provided to the application to be called. status_result (Output) The resultant character status information. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: This entry must only be called by a foreground application as it will wait within the call until a response is received. The requested application is notified of the request via the predefined minor capability STATUS. Examples: call ws_$get_status (bft_major_cap, "pending", status, code); :Entry: put_background_message: 11/28/86 ws_$put_background_message Function: Provides a background application with the means of displaying one of two types of special messages to the foreground channel through a foreground application such as the terminal emulator. 1) Information messages which inform the user such as errors and status. 2) Query messages which ask the user for input, which is relayed back to the requesting application through the predefined minor capability "QUERY_REPLY". Syntax: dcl ws_$put_background_message entry options (variable); call ws_$put_background_message (mcb_ptr, code, caller, control_string, arg1, ..., argN); Arguments: mcb_ptr (Input) The pointer to the application's MOWSE Control Block assigned by a call to ws_$create_instance. code (Input) Determines the type of the message to be displayed. If code is 0, the message will consist only of the contents of the control string. If code is a standard Multics code, it will be expanded as in com_err_. If code is "SEND_QUERY", the control string will be used to prompt the user for a response. caller (Input) The name of the routine making the call to ws_$put_background_message. control_string (Input) An ioa_ subroutine control string. This argument is optional (see com_err_). argI (Input) ioa_ subroutine arguments to be substituted into the control_string argument. These arguments are optional. They can only be used however, if the control_string argument is given first. Notes: All arguments are exactly as under com_err_ with the exception of the contents of the code parameter (as discussed above) and the mcb_ptr. All messages are placed into MOWSE for future retrieval through a call to ws_$get_background_message. If there is no foreground application executing to retrieve these messages, they will go unnoticed. This is especially important in the case of query messages as no response will be returned until the message has been retrieved and processed by the foreground application. If the code is specified as SEND_QUERY, the user's response will be provided to the calling application through the predefined minor capability "QUERY_REPLY". Examples: call ws_$put_background_message (mcb_ptr, error_code, "bft", "retrieve error ^d", bft_$invalid_dir); call ws_$put_background_message (mcb_ptr, 0, "bft", "transfer of file ^a complete", trans.name); call ws_$put_background_message (mcb_ptr, SEND_QUERY, "bft", "File ^a exists overwrite?", trans.name); :Entry: put_status: 11/28/86 ws_$put_status Function: Sends a status string to the application which made a request for status information. Syntax: dcl ws_$put_status entry (fixed bin(17), char(*), ptr, fixed bin(35)); call ws_$put_status (destination_major, status, mcb_ptr, code); Arguments: destination_major (Input) The major capability number of the application to which the status information is to be sent. status (Input) Character string which comprises the status information up to a length PACKET_SIZE. mcb_ptr (Input) The pointer to the application's MOWSE Control Block assigned by a call to ws_$create_instance. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: The calling application must have been invoked with the predefined minor capability STATUS, as it is only then that the requesting application is awaiting status information. Examples: call ws_$put_status (major_cap, "status no pending requests", mcb_ptr, code); :Entry: reset_capability: 11/28/86 ws_$reset_capability Function: Tells MOWSE to reset the specified application. The application to be reset is notified via the predefined minor capability RESET_APPLICATION. Syntax: dcl ws_$reset_capability entry (fixed bin(17), ptr, fixed bin(35)); call ws_$reset_capability (major_number, mcb_ptr, code); Arguments: major_number (Input) The major capability number of the application to be reset. mcb_ptr (Input) A pointer to the mcb of the application executing the function. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: MOWSE notifies the application through the predefined minor capability RESET_APPLICATION and clears all of the flags associated with the application. All messages occurring between the request and the completion of the request will be discarded by MOWSE. Examples: call ws_$reset_capability (bft_major_cap, code); :Entry: resume_capability: 11/28/86 ws_$resume_capability Function: Tells MOWSE to resume the specified application. The application to be resumed is notified via the predefined minor capability RESUME_APPLICATION. Syntax: dcl ws_$resume_capability entry (fixed bin(17), ptr, fixed bin(35)); call ws_$resume_capability (major_number, mcb_ptr, code); Arguments: major_number (Input) The major capability number of the application to be resumed. mcb_ptr (Input) A pointer to the mcb of the application executing this function. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: If the specified capability is not in suspension, the request will be ignored. The capability to be resumed is informed via the predefined minor RESUME_APPLICATION. Examples: call ws_$resume_capability (bft_major_cap, code); :Entry: send_query_reply: 11/28/86 ws_$send_query_reply Function: Sends the user's response to a query message to the originator of the background query message (see ws_$get_background_message). Syntax: dcl ws_$send_query_reply entry (char(*), fixed bin(17), fixed bin(35)); call ws_$send_query_reply (reply_string, destination_major, code); Arguments: reply_string (Input) The user's response to the query message obtained through a call to ws_$get_background_message. destination_major (Input) The major capability number of the application which is to receive this response string (see ws_$get_background_message). code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: A call to this procedure must be performed whenever a QUERY_MESSAGE type is returned from ws_$get_background_message as the requesting application is waiting for the response. Currently, ws_$send_query_reply is a null routine, as only the terminal emulator is capable of such functions. Examples: call ws_$send_query_reply (user_response, sender_major, code); :Entry: sleep: 11/28/86 ws_$sleep Function: Forces the calling application to sleep (suspend execution) for the specified number of seconds. When an application is put to sleep, it cannot accept any messages except TERMINATE_CAPABILITY and RESET_CAPABILITY. The calling application will be notified through the predefined minor capability WAKE_UP. Syntax: dcl ws_$sleep entry (ptr, fixed bin(17) fixed bin(35)); call ws_$sleep (mcb_ptr, time, code); Arguments: mcb_ptr (Input) A pointer to the mcb of the application executing this function. time (Input) The number of seconds the application is to sleep. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: The application is notified to awaken via the predefined minor capability WAKE_UP. Examples: call ws_$sleep (mcb_ptr, 10); :Entry: suspend_capability: 11/28/86 ws_$suspend_capability Function: Tells MOWSE to suspend the specified application. The application to be suspended is notified via the predefined minor capability SUSPEND_APPLICATION. A suspended application is unable to send or receive messages. Syntax: dcl ws_$suspend_capability entry (fixed bin(17), ptr, fixed bin(35)); call ws_$suspend_capability (major_number, mcb_ptr, code); Arguments: major_number (Input) Capability number of the application to be suspended. mcb_ptr (Input) A pointer to the mcb of the application executing this library function. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: The specified application will be suspended - unable to send or receive messages - by MOWSE until a call to ws_$resume_capability has been called for that application. Examples: call ws_$suspend_capability (bft_major_cap, code); :Entry: terminate_capability: 11/28/86 ws_$terminate_capability Function: Tells MOWSE to terminate the specified application. The application to be terminated is notified via the predefined minor capability TERMINATE_APPLICATION. Syntax: dcl ws_$terminate_capability entry (fixed bin(17), ptr, fixed bin(35)); call ws_$terminate_capability (major_number, mcb_ptr, code); Arguments: major_number (Input) The major capability number of the application to be terminated. mcb_ptr (Input) A pointer to the mcb of the application executing this function. code (Output) The error code immediately returned from MOWSE. Values: 0 - no error Or a standard Multics system error code. Notes: MOWSE will remove the specified application from its capability table after the application has been notified. Examples: call ws_$terminate_capability (bft_major_cap, code); ----------------------------------------------------------- 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