MBX_$INTRO Domain/OS MBX_$INTRO
NAME
intro - using mailboxes
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/mbx.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/mbx.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/mbx.ins.ftn'
DESCRIPTION
The mailbox calls facilitate the creation of first-in/first-out data con-
nections between processes using a client/server protocol.
The following is a list of the mbx_$ calls.
mbx_$client_window return client buffer size
mbx_$close close a channel or mailbox
mbx_$cond_get_rec_chan read a channel without waiting
mbx_$cond_get_rec_chan_set read a set of channels without waiting
mbx_$create_server create a mailbox
mbx_$deallocate deallocate a channel
mbx_$get_conditional read a message without waiting
mbx_$get_ec get a pointer to a mailbox eventcount
mbx_$get_rec get a message from a mailbox
mbx_$get_rec_chan read a mailbox channel
mbx_$get_rec_chan_set read a set of channels
mbx_$open open a client channel in a mailbox
mbx_$put_chr send a partial message
mbx_$put_chr_cond send a partial message without waiting
mbx_$put_rec send a message
mbx_$put_rec_cond send a message without waiting
mbx_$server_window return server buffer size
mbx_$start_helper start a mailbox helper
mbx_$timed_open open a client channel with a timeout
A mailbox is a file through which processes can pass data to each other.
Every mailbox is managed by a "server" process that receives and
dispatches messages to one or more "client" processes. All mailbox mes-
sages travel via the mailbox from client to server, or from server to
client. A mailbox circuit from one client to another must be mediated by
the server for the mailbox. Mailbox clients cannot communicate directly.
The mailbox is a file that buffers the messages passed between clients
and the server. Each client communicates with the server over a mailbox
channel consisting of two buffers: a client buffer that contains mes-
sages from the client to the server, and a server buffer that contains
messages from the server to the client. These channels and buffers are
created when the server creates the mailbox.
The server must create enough channels to service its clients. It then
waits on the client buffers for messages, and services them as they
arrive, dispatching messages to its clients as necessary. Clients open
channels in an existing mailbox and use them to exchange messages with
the server.
A mailbox server and its clients need not run on the same node, but if
all processes using a mailbox are not running on the same node, all the
nodes using the mailbox must be running the mailbox helper. The mailbox
helper is a program, usually named /sys/mbx/mbx_helper, that routes mail-
box messages between nodes. In addition to routing messages to remote
nodes via the mailbox helper, Domain/OS manages the allocation of mailbox
channels to clients and provides eventcounts to synchronize processes
using a mailbox.
Constants
mbx_$chn_max
The maximum number of channels that a mailbox can contain.
mbx_$fil_max
The maximum size of a mailbox.
mbx_$min_chn_size
The minimum size of a channel buffer.
mbx_$msg_max
A mailbox message that is 1024 bytes long.
mbx_$msg_tn
For use when declaring a zero-based array that is mbx_$msg_max bytes
long.
mbx_$msg_wmax
A mailbox message that is 512 words long.
mbx_$msg_wtn
For use when declaring a zero-based array that is mbx_$msg_wmax
words long.
mbx_$rec_data_max
The maximum length of the data portion of a mailbox message.
mbx_$rec_msg_max
The maximum length of a server message, including the header and
data portions.
mbx_$serv_msg_hdr_len
Length of the mailbox header for a server message.
mbx_$serv_msg_max
A server message that contains 1024 bytes of data plus a 6-byte
header.
mbx_$version
Current version of MBX.
Data Types
mbx_$chan_num_t
A channel number. Possible values are integers from 0 through
mbx_$chn_max.
mbx_$chan_set_t
A set of channel numbers of type mbx_$chan_num_t.
mbx_$ec_key_t
A mailbox eventcount. One of the following predefined values:
mbx_$getrec_ec_key
An eventcount that advances when a new message enters a chan-
nel.
mbx_$putrec_ec_key
An eventcount that advances whenever a message leaves a
channel.
mbx_$mtype_t
A message type. One of the following predefined values:
mbx_$accept_open_mt
A response from a server to accept a client's open request.
mbx_$channel_open_mt
A request from a client to open a channel to a mailbox.
mbx_$data_mt
A data transmission.
mbx_$data_partial_mt
A partial data transmission.
mbx_$eof_mt
An end of transmission notice.
mbx_$reject_open_mt
A response from a server to reject a client's open request.
mbx_$msg_hdr_t
A mailbox message header. The diagram below illustrates the
mbx_$msg_hdr_t data type:
31 16
______________________________________________________________
| cnt |
|_____________________________________________________________|
| mt |
|_____________________________________________________________|
| chan |
______________________________________________________________
15 0
cnt The total number of bytes in the message, including the header.
mt A value of type mbx_$mtype_t representing a message type.
chan The channel of the client that sent the message, or that should
receive the message.
mbx_$server_msg_t
A server message of the maximum default size. The following diagram
illustrates the mbx_$server_msg_t data type:
31 16
______________________________________________________________
| cnt |
|_____________________________________________________________|
| mt |
|_____________________________________________________________|
| chan |
|_____________________________________________________________|
| data | ... |
______________________________________________________________
15 8 7 0
cnt The total number of bytes in the message, including the header.
mt A value of type mbx_$mtype_t representing a message type.
chan The channel of the client that sent the message, or that should
receive the message.
data The data portion of the message. This field can contain up to
1024 bytes.
Errors
mbx_$bad_key
Bad key.
mbx_$buffer_too_small
A server requested a message using a buffer smaller than six bytes.
There must be enough room for the message header in all server mes-
sage requests.
mbx_$channel_empty
There are no messages waiting in the channel. Received in response
to an mbx_$get_cond or mbx_$cond_get_chan request.
mbx_$channel_not_open
For a server, the channel number given referred to a channel that is
not presently open; for a client, the server has deallocated the
client's channel.
mbx_$client_no_rights
The client can't access the system mailbox maintained by the local
mailbox helper.
mbx_$client_server_deadlock
A server tried to open a channel to itself, which is illegal.
mbx_$eof
The client has sent a message of type mbx_$eof_mt. Received in
response to an mbx_$get_rec or mbx_$get_cond request.
mbx_$file_in_use
Attempted to create a mailbox file where a file exists and is
currently in use.
mbx_$handle_not_valid
The handle given does not point to a mailbox.
mbx_$helper_no_rights
The mailbox helper on the server's node can't access the server's
mailbox.
mbx_$ill_handle
The handle given is not a legal handle.
mbx_$msg_too_big_for_channel
An mbx_$put_conditional or mbx_$put_rec request tried to send a mes-
sage bigger than the maximum specified when the server created the
mailbox.
mbx_$no_more_channels
An mbx_$open was made to a mailbox with no free channels.
mbx_$no_more_resources
An mbx_$create_server or mbx_$open request was made, and the process
has insufficient resources left to open the mailbox or the channel.
mbx_$no_room_in_channel
There is not enough room in the channel for the message. Received
in response to an mbx_$put_conditional request.
mbx_$no_servers
An mbx_$open was made to a mailbox without an active server.
mbx_$open_rejected
The server rejected an mbx_$open request.
mbx_$open_timed_out
The server did not respond within the specified period of time.
mbx_$partial_record
Returned data does not contain a complete record.
mbx_$record_length_mismatch
A server used a put call and the value in the third argument did not
match the value in the length field of the message header.
mbx_$rem_rcv_timout
A remote operation was attempted, and the network has failed.
mbx_$rem_send_failed
A remote operation was attempted, and the network has failed.
mbx_$rem_service_unavailable
An mbx_$open open request was made from a remote node when the mail-
box helper was not running on that node or the server's node.
mbx_$remote_service_denied
An mbx_$open request was made from a remote node, and there are not
enough network services free to handle the request.
mbx_$sequenced_send_failed
An internal error occurred while sending a message that is larger
than 1158 bytes.
mbx_$size_too_large
An mbx_$create_server request asked for a mailbox larger than the
maximum.
mbx_$size_too_small
An mbx_$create_server request was made with a buffer size smaller
than the minimum.
mbx_$too_many_channels
Attempted to create a mailbox with too many channels.
mbx_$unexpected_cntl_msg
Received by a client when the last message the server sent on that
channel had a message type of mbx_$accept_open_mt,
mbx_$reject_open_mt, or mbx_$channel_open_mt when such a message
type was inappropriate. (Mbx_$channel_open_mt should never be used.
The other two message types are only used in response to a message
of type mbx_$channel_open_mt.) Received in response to an
mbx_$get_rec or mbx_$get_cond request.
mbx_$unknown_rqst
The client and server are using different versions of the mailbox
manager (although the two versions have the same version number),
and one of them made a request not recognized by the other manager.
mbx_$wrong_version_number
An mbx_$open request was made using a mailbox manager with a dif-
ferent version number than the one used to create the mailbox.