MESSAGE PORTS FOR BEGINNERS
IDENTIFY YOURSELF
Message ports work on the assumption that they can uniquely identify the program that wants to communicate with others. In reality, it is not so much the program that wants to communicate but the user of the program. For this very reason, the first operation to be performed is precisely that of "logging in". The syntax is very simple:
= LOGIN( username, password )Note that on DOJO servers there is no different process between registration and access to the systems: this is because, in fact, it is unlikely that the user's situation has persisted on the retrocomputers. It follows that, at the first attempt to access, there will also be contextual registration of the user; after the first access, each subsequent access must have the same credentials, and there is no way to change them, at least with this version of the DOJO protocol.
The
LOGIN function return a sessionId, To
be used on other commands / functions. To verify that the operation has taken place, the SUCCESS()
function must be used. If SUCCESS(...) returns a TRUE
result, then the login process was successful; if it returns a FALSE result,
then the process must be considered failed for some reason (the username may
have already been used, or the credentials are incorrect, and so on).
OPEN (AT LEAST) ONE (RECEIVING) PORT
A message port can be thought of as a mailbox. When someone (a program or a user that uses a program) sends a message to a port, it is as if we were asking a postal system to deliver a letter to the mailbox (of another program). The postal service guarantees that the message will be delivered, but of course it cannot guarantee when this will happen. Therefore, the order in which messages arrive may not be the same as the order in which they are sent.
To create a message port where receive messages, simply use the
CREATE PORT(...) function, whose
syntax is as follows:= CREATE PORT( sessionId, application )The
sessionId parameter is the same one that returned the call to
LOGIN(...), and identifies the working session at that moment.
The application parameter represents, instead, the name of the
application or functionality to which you want to associate this message port.
The message port (mailbox) is owned by the user but also by each individual application or application functionality. Therefore, it is possible to define more than one mailbox (i.e., a port) for a single user, as long as each of them is identified by a different application code.
FIND OUT THE (SENDING) PORT
To send a message, we need to know the address of that message port. In DOJO protocol jargon, a message box is identified by a unique identifier, called "port id". So the first useful operation is to find out the port id to use to send the message. This is exactly the purpose of
= FIND PORT(...) function.The syntax follows:
port = FIND PORT( sessionId, username, application )So basically three pieces of information are needed to identify that mailbox. First of all, you need an identifier that allows the user (sender) to be recognized by the DOJO server (
sessionId). To get it, you need to identify
yourself, and you can do that with the procedure explained in the previous
chapter. Secondly, you need to know the identifier of the user who
owns that mailbox (username). Finally, it is essential to know
the name of the application on whose behalf we are looking for the mailbox
(application).
As we mentioned before, it is possible to have multiple ports assigned to a user. However, it is also true that each port is marked with an
application identifier
(or, if we want, an application functionality identifier). The consequence is that the
DOJO protocol indirectly creates communication networks whose nodes belong to the same
application. This is the basis for sharing servers by programs that are also very different
from each other.
PUT A MESSAGE TO A PORT
To put a message we can use the PUT MESSAGE statement, with the
following syntax:
PUT MESSAGE portId, message
This is a statement, not a function. It follows
that we cannot know if the statement was successful. This does not really represent
a limitation, for the simple fact that the statement will always be successful: if
the program on the other side of the port is not available, for some reason, the
message will be preserved by the DOJO server, and it will be delivered at the
first available moment.
WAIT FOR A MESSAGE
Once you have created a port and sent a message, you may wait for a
message to arrive to you. As explained in the previous chapters,
the port is accessible to anyone who knows its identifier (perhaps
because they have searched for it). Therefore, many messages may
arrive or none at all. The program that wants to wait for the
arrival can use the PEEK MESSAGE command. The syntax is as follows:
= PEEK MESSAGE( portId )
If it returns FALSE, it means that the message port is empty; on
the contrary, if it returns TRUE, it is possible to fetch the message
using the GET MESSAGE command. The syntax is:
= GET MESSAGE( portId )
Note that the message port behaves like a queue, that is, the first message that is inserted is the first that is retrieved. Therefore, if a program sends three messages in a row to the attention of the port of another, the receiving program will receive the three messages in the same order.
Obviously, if several programs do the same thing, the messages will be interspersed but, in the end, they will be in the same order.
