11/28/86  pc_mowse_


This is a collection of subroutines (found in pc_mowse_.archive)
which provide a subroutine interface for the applications writer
to PC MOWSE.


Entry points in pc_mowse_:
   (List is generated by the help command)


:Entry:  conrqst:  11/28/86  conrqst


Function:
Requests a connection to an application which has been
loaded by sending a "WSRQSTCN" minor capability to the requested
application.


Syntax:
int conrqst(cap_name,args,system,mcb_ptr);
    char *cap_name;
    char *args;
    int system;
    mcb *mcb_ptr;


Arguments:
cap_name (Input)
    The name of the capability to be connected.
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 cretinst.


Returns:
0        - no error
Or an error code defined in the appendix.


Examples:
ecode = conrqst ("bft", "load", WSREMOTE, mcb_ptr);


:Entry:  conresp:  11/28/86  conresp


Function:
Replies to an application's request for a connection.  This
allows the application of the conrqst 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 WSRESPCN which
will indicate the success or fail of the request.


Syntax:
int conresp (status,cap_num,mcb_ptr);
    int status,
        cap_num;
        mcb_ptr,


Arguments:
status  (Input)
    The acceptance/rejectance of the connect request.
    Values WSACCEPT
            WSREJECT
cap_num  (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.


Returns:
0        - no error
Or an error code defined in the appendix.


Examples:
ecode = conresp (WSACCEPT, request_capability, mcb_ptr,
                 new_mcb_ptr, code);
ecode = conresp (WSREJECT, request_capability, mcb_ptr,
                 NULL, code);


:Entry:  cretinst:  11/28/86  cretinst


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:
int cretinst (cap_name, entry, inbuff_len, outbuff_len,
              data_ptr, mcb_ptr);
  char cap_name[WSCAPLEN];
  int (*entry)();
  int inbuff_len;
  int outbuff_len;
  char *data_ptr;
  mcb **mcb_ptr;


Arguments:
cap_name  (Input)
    A null terminated string of characters specifying the name
    by which the calling capability will be known to MOWSE.
entry  (Input)
    A pointer to the function which will be invoked when MOWSE
    has a message destined for the application.
inbuff_len  (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 WSMINBUF,
    whichever is larger.


outbuff_len  (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 WSMINBUF, whichever
    is larger.
data_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)
    The address of the pointer to the application's MOWSE
    Control Block which will be used by MOWSE to maintain
    information on the application.


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
All applications which expect to receive messages must have
registered with MOWSE (through cretinst) 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:


  application_$entry_point (minor_cap, major_sender, arg_ptr,
          arg_length, data_block_ptr, mcb_ptr);


          char      minor_cap;
          int       major_sender;
          char      *arg_ptr;
          int       arg_length;
          char      *data_block_ptr


The buffers inbuff and outbuff allow MOWSE to send and receive
messages longer than one communications packet (defined by
WSPAKSIZ) in a manner transparent to the capability.


Examples:
ecode = cretinst ("bft", bft_process, 256, 256, data_ptr,
                  &mcb_ptr);


:Entry:  destinst:  11/28/86  destinst


Function:
Removes the reference to the application from MOWSE's
capability table and deallocates the inbuff and outbuff
message buffer space.


Syntax:
int destinst (mcb_ptr);
  mcb **mcb_ptr;


Arguments:
mcb_ptr  (Input)
    The address of the pointer to the application's MOWSE
    Control Block assigned by a call to "cretinst".


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
If this is the final instance and it is being destroyed, then
all memory occupied by the application is released including
memory occupied by its code.


Examples:
ecode = destinst (&mcb_ptr);


:Entry:  disrqst:  11/28/86  disrqst


Function:
Requests that conversation to the specified application be
terminated by sending a "WSRQSTDS" to the specified
capability.


Syntax:
int disrqst(cap_num,mcb_ptr);
    int cap_num;
    mcb *mcb_ptr;


Arguments:
cap_num  (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 cretinst.


Returns:
0        - no error
Or an error code defined in the appendix.


Examples:
ecode = disrqst (bft_major_cap, mcb_ptr);


:Entry:  disresp:  11/28/86  disresp


Function:
Notifies the application which requested a disconnect that the
disconnect was accepted or rejected.  A "WSRESPDS" message
will be sent to the application which made the disconnect
request.


Syntax:
int disresp(status,cap_num,mcb_ptr);
    int status,
        cap_num;
    mcb *mcb_ptr;


Arguments:
status  (Input)
    The acceptance/rejectance of the disconnect request.
    Values WSACCEPT
            WSREJECT
cap_num  (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 cretinst.


Returns:
0        - no error
Or an error code defined in the appendix.


Examples:
ecode = disresp (WSACCEPT, request_capability, mcb_ptr);
ecode = disresp (WSREJECT, request_capability, mcb_ptr);


:Entry:  execap:  11/28/86  execap


Function:
Executes the minor capability function of the specified major
capability with the arguments provided.


Syntax:
int execap (major_num, minor_num, arg_ptr, arg_len, mcb_ptr);
  int major_num;
  int minor_num;
  char *arg_ptr;
  int arg_len;
  mcb *mcb_ptr;


Arguments:
major_num  (Input)
    The identifier of the capability to be executed.
minor_num  (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_len  (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 "cretinst".


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
It is up to the calling application to convert the argument
data into character string format which can be interpreted by
the application being called as a character string of data.

If MOWSE was incapable of starting execution of the specified
application, the calling application will be notified through
the predefined minor capability WSFAILCP.


Examples:
ecode = execap (pcfooid, addnumid, numarg_ptr, numarg_len,
                mcb_ptr);


:Entry:  execom:  11/28/86  execom


Function:
Sends a command string to the command processor on the
specified system.


Syntax:
int execom (command_string, system, command_id, mcb_ptr);
  char *command_string;
  int system;
  int *command_id;
  mcb *mcb_ptr


Arguments:
command_string  (Input)
    A null terminated 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 WSLOCAL
           WSREMOTE


command_id  (Output)
    The tag which will be associated with the command_string
    being executed and the resultant WSCOMREP predefined minor
    capability.
mcb_ptr  (Input)
    The pointer to the application's MOWSE Control Block
    assigned by a call to "cretinst".


Returns:
0        - no error
Or an error code defined in the appendix.


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 WSCOMREP
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 EXECOM - such as "dir" - the
output appears on the screen without passing through the
terminal emulator.


Examples:
ecode = execom ("dir \user\smith\*.*", WSREMOTE, &com_id,
                mcb_ptr);
ecode = execom ("ls -d >udd>m>Smith",WSLOCAL, &com_id,
                mcb_ptr);
ecode = execom ("bft", WSREMOTE, &com_id, mcb_ptr);


:Entry:  findname:  11/28/86  findname


Function:
Finds the name of a capability given its major capability
number.


Syntax:
int findname (major_num, cap_name);
  int major_number;
  char cap_name[WSCAPLEN];


Arguments:
major_number  (Input)
    The major capability number of the capability name to be
    found.
cap_name  (Output)
    The name of the capability found, 0 length if not found.


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:


Examples:
ecode = findname (major_cap, cap_name);


:Entry:  findnumb:  11/28/86  findnumb


Function:
Finds the major capability number of an application given a
capability name.


Syntax:
int findnumb (cap_name, sys_id, major_num);
  char cap_name[WSCAPLEN];
  int sys_id;
  int *major_num;


Arguments:
cap_name  (Input)
    The capability name to be looked for.
sys_id  (Input)
    The system which is to be looked at to find the capability
    name.
    Values  WSLOCAL
             WSREMOTE
major_num  (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.


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
MOWSE looks for the capability name in its capability table in
the following fashion:


    1) If the provided major capability number is 0, MOWSE
    will begin searching from the top of the table specified
    by the sys_id.
    2) If the major capability number is valid, MOWSE will
    begin searching from the next entry.
    3) If the provided sys_id is invalid, MOWSE will search
    the local CAT table from its first entry.


Examples:
ecode = findnumb ("bft_", WSLOCAL, &major_num);
ecode = findnumb ("bft_", WSREMOTE, &major_num);


:Entry:  getbgmes:  11/28/86  getbgmes


Function:
Returns one of two types of background messages - placed there
by a call to "putbgmes".


    1) Info messages which are for display only.
    2) Query messages which are to be used to prompt the user
    to provide information which is to be returned to the
    requesting application through a call to "sendqrep".


Syntax:
int getbgmes (string, type, sender_major);
  char *string;
  int *type;
  int *sender_major;


Arguments:
string  (Output)
    The next background message available from MOWSE, placed
    there by a call to "putbgmes".  The string buffer into
    which the background message is placed must be at least
    one packetsize (WSPAKSIZ characters) long.
type  (Output)
    A specifier to the type of background message returned.
    Values WSQUERY
            WSINFO
sender_major  (Output)
    The major capability number of the application which
    stored the background message through a call to
    "putbgmes".


Returns:
0         - no error
Or an error code defined in the appendix.


Notes:
The application which makes this call must be a foreground
application which is responsible for all user I/O.


If the message type returned is WSQUERY, the application which
made this call must send a reply to the sender major as it is
stopped, expecting a reply.


Examples:
ecode = getbgmes (string, &type, &sender_major);


:Entry:  getstat:  11/28/86  getstat


Function:
Requests status information from the specified application.


Syntax:
int getstat (major_num, status_request, status_result);
  int major_num;
  char *status_request;
  char *status_result;


Arguments:
major_num  (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.


Returns:
0        - no error
Or an error code defined in the appendix.


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 WSSTATUS.


Examples:
ecode = getstat (bft_major_cap, "pending", status);


:Entry:  gettdata:  11/28/86  gettdata


Function:
Retrieves a string from the terminal buffer and a flag which
determines whether or not there are pending background messages
(see PUTBGMES and GETBGMES).  The string is destined to be
used as terminal data, ie.  it is expected to be displayed by
the retrieving application on the PC's CRT.
If there is no data in the terminal buffer, a zero length
string will be returned.


Syntax:
int gettdata (getdata_ptr)
  struct get_struc {
     char *local_buffer_pointer;
     int local_buffer_size;
     int minor_capability;
     int background_pending_flag;
  } *getdata;


Arguments:
string_length  (Output)
    The length of the terminal string that it pointed to in
    the structure below.  0 if the terminal buffer is empty.
getdata_ptr  (Input)
    The pointer to the calling routine's structure which is
    used for input and output arguments.
local_buffer_ptr  (Input)
    A pointer to a buffer into which the retrieved terminal
    data will be placed.


local_buffer_size  (Input)
    The size of the local buffer.  Determines the maximum
    number of characters that can be retrieved.
minor_capability  (Output)
    The entry point specified by the remote system for
    specialized handling of received terminal data.
background_pending_flag  (Output)
    Determines if there are background messages pending.  0 if
    none are pending, N for the number of messages pending.


Returns:
N - length of terminal data retrieved, 0 if none.


Notes:


:Entry:  putbgmes:  11/28/86  putbgmes


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 WSQRYREP.


Syntax:
int putbgmes (mcb_ptr, code, caller, control, arg1,...,argN);
  mcb *mcb_ptr;
  int code;
  char *caller;
  char *control;


Arguments:
mcb_ptr  (Input)
    The pointer to the application's MOWSE Control Block
    assigned by a call to "cretinst".
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 WSQUERY, the control string will be used to
    prompt the user for a response.


caller  (Input)
    The name of the routine making the call to "putbgmes".
control  (Input)
    A "printf" control string.
argI  (Input)
    printf control arguments to be substituted into the
    control argument.  These arguments are optional.  They can
    only be used however, if the control argument is given
    first.


Returns:
0        - always


Notes:
All messages are placed into MOWSE for future retrieval
through a call to "getbgmes".  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 WSQUERY, the user's response will
be provided to the calling application through the predefined
minor capability WSQRYREP.


Examples:
putbgmes (mcb_ptr, ecode, "bft", "retrieve error %d",
          BFTINVDIR);
putbgmes (mcb_ptr, 0, "bft", "transfer of file %s complete",
          trans.name);
putbgmes (mcb_ptr, WSQUERY, "bft",
          "File %s exists overwrite?", trans.name);


:Entry:  putstat:  11/28/86  putstat


Function:
Sends a status string to the foreground application which made
a request for status information.


Syntax:
int putstat (status, mcb_ptr);
  char *status;
  mcb *mcb_ptr;


Arguments:
status  (Input)
    A null terminated character string which comprises the
    status information up to a length WSPAKSIZ.
mcb_ptr  (Input)
    The pointer to the application's MOWSE Control Block
    assigned by a call to "cretinst".


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
The calling application must have been invoked with the
predefined minor capability WSSTATUS, as it is only then that
the requesting application is awaiting status information.


Examples:
ecode = putstat ("status no pending requests", mcb_ptr);


:Entry:  puttdata:  11/28/86  puttdata


Function:
Sends a data string to the Multics user i/o switch.


Syntax:
puttdata(minor_cap, string_ptr, string_len);
  int minor_cap;
  char *string_ptr;
  int string_len;


Arguments:
minor_cap  (Input)
    The destination minor capability number to receive the
    data.  This is to distinguish between control information
    and regular terminal data.  The minor capability number
    for regular terminal data is WSFGDATA.
string_ptr  (Input)
    A pointer to the character string to be sent.
string_len  (Input)
    The length of above character string.


Returns:
0        - no error.


Notes:


:Entry:  resetcap:  11/28/86  resetcap


Function:
Tells MOWSE to reset the specified application.  The
application to be reset is notified via the predefined minor
capability RESET.


Syntax:
int resetcap (major_number, mcb_ptr);
  int major_number;
  mcb *mcb_ptr;


Arguments:
major_number  (Input)
    The major capability number of the application to be
    reset.
mcb_ptr  (Input)
    The pointer to the caller's MOWSE Control Block.


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
MOWSE notifies the application through the predefined minor
capability WSRSTAPP 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:
ecode = resetcap (bft_major_cap, mcb_ptr);


:Entry:  resume:  11/28/86  resume


Function:
Tells MOWSE to resume the specified application.  The
application to be resumed is notified via the predefined minor
capability RESM.


Syntax:
int resume (major_number, mcb_ptr);
  int major_number;
  mcb *mcb_ptr;


Arguments:
major_number  (Input)
    The major capability number of the application to be
    resumed.
mcb_ptr  (Input)
    The pointer to the caller's The MOWSE Control Block.


Returns:
0        - no error
Or an error code defined in the appendix.


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 WSRSMAPP.


Examples:
ecode = resume (bft_major_cap, mcb_ptr);


:Entry:  sendqrep:  11/28/86  sendqrep


Function:
Sends the user's response to a query message to the originator
of the background query message (see "getbgmes").


Syntax:
int sendqrep (reply_string, destination_major);
  char *reply_string;
  int destination_major;


Arguments:
reply_string  (Input)
    The user's response to the query message obtained through
    a call to "getbgmes".
destination_major  (Input)
    The major capability number of the application which is to
    receive this response string (see "getbgmes").


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
A call to this procedure must be performed whenever a WSQUERY
type is returned from "getbgmes" as the requesting application
is waiting for the response.


Examples:
ecode = sendqrep (user_response, sender_major);


:Entry:  wssleep:  11/28/86  wssleep


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 TERM and
RESET.  The calling application will be notified through the
predefined minor capability WSWAKEUP when the specified time
has elapsed.


Syntax:
int wssleep (time, mcb_ptr);
  int time;
  mcb *mcb_ptr;


Arguments:
time  (Input)
    The number of seconds the application is to sleep.
mcb_ptr  (Input)
    The pointer to the application's MOWSE control block
    assigned by a call to "cretinst".


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
The application is notified to awaken via the predefined minor
capability WSWAKEUP.
It is important that MOWSE applications use THIS sleep
function, as opposed to the sleep routine provided by the
standard "C" library.  MOWSE cannot perform anything until
the application has returned to it, thus all further message
processing would be suspended until the call to the "C" sleep
has expired.


Examples:
wssleep (10);


:Entry:  stayres: 11/28/86  stayres


Function:
Terminates execution of a MOWSE capability at the end of its
initialization, and keeps its object code resident in the PC's
memory for later invocations through "execap" calls.


Syntax:
stayres (mcb_ptr);
  mcb *mcb_ptr;


Arguments:
mcb_ptr  (Input)
    The pointer to the application's MOWSE Control Block
    assigned by a call to "cretinst".


Returns:
A call to "stayres" will not return.


:Entry:  suspend:  11/28/86  suspend


Function:
Tells MOWSE to suspend the specified application.  The
application to be suspended is notified via the predefined
minor capability WSSUSAPP.  A suspended application is unable
to send or receive messages.


Syntax:
int suspend (major_number, mcb_ptr);
  int major_number;
  mcb *mcb_ptr;


Arguments:
major_number  (Input)
    Capability number of the application to be suspended.
mcb_ptr  (Input)
    The pointer to the caller's MOWSE Control Block.


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:
The specified application will be suspended - unable to send
or receive messages - by MOWSE until a call to "resume" has
been called for that application.


Examples:
ecode = suspend (bft_major_cap, mcb_ptr);


:Entry:  termcap:  11/28/86  termcap


Function:
Tells MOWSE to terminate the specified application.  The
application to be terminated is notified via the predefined
minor capability WSTRMAPP.


Syntax:
int termcap (major_number, mcb_ptr);
  int major_number;
  mcb *mcb_ptr;


Arguments:
major_number  (Input)
    The major capability number of the application to be
    terminated.
mcb_ptr  (Input)
    The MOWSE Control Block of the calling capability.


Returns:
0        - no error
Or an error code defined in the appendix.


Notes:


Examples:
ecode = termcap (bft_major_cap, mcb_ptr);


                                          -----------------------------------------------------------


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