This document documents the examples provided in the Online Tutorial for EntireX Broker. The purpose of each example is outlined, the objective of the client and server parts of the example is explained, and the logical program flow is illustrated. This should help you implement similar functionality using any of the supported programming languages. The Online Tutorial contains Natural example code to demonstrate these examples.
This document covers the following topics:
This example shows a client sending simple messages that do not require
a reply from a server, for example feeding statistical performance data into a
network-wide performance monitor. Since no reply is expected, the client does
not have to wait for an answer and therefore issues a non-blocked SEND call to
the broker. The established communication is non-conversational.
Such a client could be used as a trigger for a net management server from all servers in the network.
The client issues simple messages to a server without expecting a
reply. Because no reply is required (the server will not return any response),
the client issues a SEND without wait
(W=NO). This type of call is called non-blocked, and control is
returned to the caller immediately. The client specifies non-conversational
communication using "NONE" in the
CONV-ID field of the ACI control block.
The server establishes a service which is able to collect simple
messages from clients that do not require a reply. A
REGISTER is necessary to inform the Broker of the
availability of the service. The DEREGISTER, issued
as the last action, informs the Broker of the unavailability of the service
served by this server.
The server wants to wait for a client message and therefore uses a
blocked RECEIVE - that is, a
RECEIVE with W=nS is issued to the
Broker.
Client LOGON ------> logon to Broker repeat SEND,W=NO,CID=NONE ------> forward message to server until ... LOGOFF -----> logoff from Broker _______________________________________________________ Server LOGON ------> logon to Broker REGISTER ------> offer service repeat RECEIVE,W=nS,CID=NEW ------> wait for message until ... DEREGISTER ------> deregister service LOGOFF ------> logoff from Broker
This example shows a client sending requests that require a reply from
a server, for example a database access. Traditional remote procedure calls
(RPCs) are also referred in this way. Since a reply is expected, the client
uses a blocked SEND to issue the request to the server and wait for the reply.
This is the equivalent of an implicit receive. The established communication is
non-conversational.
The client issues requests and expects a reply from the server.
Because a reply is required and no conversation is built, a blocked
SEND (W=nS) must be used. If the wait time elapses
before the reply is received, there is no chance (in non-conversational mode)
of getting the reply. However, you can retrieve the reply later in
conversational mode by issuing a subsequent
RECEIVE.
The server establishes a service that is able to receive requests and return a reply to the client. Although the communication is non-conversational, the server gets a conversation ID with the incoming request. This ID must be retrieved and used when sending back the reply to the client.
The server must issue the RECEIVE call with
CID=NEW in order to prevent unnecessary "Conversation ID
timeout" messages.
Client LOGON ------> logon to Broker repeat SEND,W=nS,CID=NONE ------> send and wait for reply until ... LOGOFF -----> logoff from Broker ______________________________________________________ Server LOGON ------> logon to Broker REGISTER ------> offer service repeat RECEIVE,W=nS,CID=NEW ------> wait for request SEND,W=NO,CID=1234 ------> reply to client until ... DEREGISTER ------> deregister service LOGOFF ------> logoff from Broker
This example shows a client dealing with a long-running service. The
server process is initiated with a non-blocked SEND
request. Later on, the client checks the processing status with a non-blocked
RECEIVE request. However, the client retains control
in all broker calls and is never blocked. The established communication
is conversational. This example applies to any background processing in which
the client should retain control.
The client issues a non-blocked SEND to initiate a conversation with
the desired service. With the subsequent non-blocked
RECEIVE requests, the process is checked to see if
it is still running or has finished.
The server provides a service which takes some time to finish. It
demonstrates a non-blocked client example. The long running processing is
simulated by a wait of 30 seconds done with a blocked
RECEIVE to a dummy WAIT service.
Client
LOGON ------> logon to Broker
repeat
SEND,W=NO,CID=NEW ------> initiate process/conversation
repeat
RECEIVE,W=NO,CID=1234 ------> check for process status
decide on ERROR-CLASS
VALUE 0 successful response - retrieve reply
VALUE 3 processing ended
VALUE 74 wait some time and retry
until ...
until ...
LOGOFF ----> logoff from Broker
____________________________________________________________
Server
LOGON ------> logon to Broker
REGISTER ------> offer service
repeat
RECEIVE,W=nS,CID=NEW ------> wait for new conversation
wait 30 seconds - simulate long running processing
SEND,OP=EOC,W=NO,CID=1234 -----> reply and EOC
until ...
DEREGISTER ------> deregister service
LOGOFF ------> logoff from Broker
This example shows a client retrieving a large amount of data from a
server within a conversation, for example a GET
<file> command of a file transfer system. The transfer of
messages/data to the client is done by the server with non-blocked
SENDs. This is important because the server can work
independently from the client, that is, forward the data/messages to the client
and is then quickly free to process the next conversation. The established
communication is conversational.
The client receives a large amount of data/messages from a server. The
SEND initiates a conversation with the desired
service. Following the RECEIVE, the client retrieves
data/messages from the connected server until the conversation is ended by the
server.
The server is able to send a large amount of data/messages to the
client. The data/messages are transferred with non-blocked (W=NO)
SENDs. The last transfer terminates the conversation
with a non-blocked SEND and option
EOC.
Client
LOGON ------> logon to Broker
repeat
SEND,W=nS,CID=NEW ------> initiate conversation
repeat
RECEIVE,W=nS,CID=1234 ------> receive data/message
decide on ERROR-CLASS
VALUE 0 successful response
VALUE 3 conversation ended
until ...
until ...
LOGOFF -----> logoff from Broker
_____________________________________________________________
Server
LOGON ------> logon to Broker
REGISTER ------> offer service
repeat
RECEIVE,W=nS,CID=NEW ------> wait for new conversation
SEND,W=NO,CID=1234 ------> acknowledge conversation
repeat
SEND,W=NO,CID=1234 ------> transfer data/message
until end of data
SEND,OP=EOC,W=NO,CID=1234 -----> last data/message and EOC
until ...
DEREGISTER ------> deregister service
LOGOFF ------> logoff from Broker
This example shows a client transferring a large amount of data to a
server using conversational communication, for example, a PUT
<file> command of a file transfer system. Once the
conversation is established, the server depends on the client's activity,
because the client always sends the messages/data and finishes the
conversation, thus tying the server to one conversation for a long time. This
might in some circumstances be unacceptable. The situation can be improved when
multiple servers for this service are started simultaneously.
The client transfers a large amount of data/messages to the server.
The first blocked SEND initiates a conversation with
the server. The server acknowledges the conversation with a reply. Subsequent
non-blocked SENDs then transfer the data/messages to the server. The last
transfer terminates the conversation with a non-blocked
SEND and option EOC.
The server retrieves a large amount of data from the client. The
server depends on the client at the second RECEIVE
for the data/messages, because the call is blocked.
Client
LOGON -----> logon to Broker
repeat
SEND,W=nS,CID=NEW ------> initiate conversation
repeat
SEND,W=NO,CID=1234 ------> transfer data/message
until ...
SEND,OP=EOC,W=NO,CID=1234 ------> last data/message and EOC
until ...
LOGOFF ----> logoff from Broker
______________________________________________________________
Server
LOGON ------> logon to Broker
REGISTER ------> offer service
repeat
RECEIVE,W=nS,CID=NEW ------> wait for new conversation
SEND,W=NO,CID=1234 ------> acknowledge conversation
repeat
RECEIVE,W=nS,CID=1234 ------> receive data/message
until ...
until ...
DEREGISTER ------> deregister service
LOGOFF ------> logoff from Broker
This example shows a server which is able to process multiple conversations in parallel. To build such a server, the states of active conversations must be maintained in order to know where processing continues when the next request/message for the conversation is retrieved. Be aware that this can lead to complicated programs (multiplexing servers in environments where it is not feasible to have one server process per client).
A simpler and more convenient way to build a server environment which is able to process multiple conversations is to start replicates of the server. However, multiplexing servers may be appropriate in environments with restricted resources (for example, limited number of tasks).
The established communication is conversational.
This client is used to demonstrate a server which is able to process
multiple conversations in parallel. The first blocked SEND initiates the
conversation. The server always acknowledges the conversation with a reply to
the client. With the subsequent calls, requests/replies are transferred within
the established conversation. The conversation is terminated by issuing an
EOC.
The server processes multiple conversations in parallel. At the
RECEIVE with CID=ANY, client requests
are retrieved, which belong either to existing or new conversations. All known
conversations are stored in an array. When conversations finish, these entries
are freed. When the last entry is used, CID=OLD is issued,
preventing the retrieval of new conversations.
Client
LOGON ------> logon to Broker
repeat
SEND,W=nS,CID=NEW ------> initiate conversation
repeat
SEND,W=nS,CID=1234 ------> ongoing conversation
until ...
EOC,CID=1234 ------> end of conversation
until ...
LOGOFF -----> logoff from Broker
_______________________________________________________________
Server
LOGON ------> logon to Broker
REGISTER ------> offer service
repeat
RECEIVE,W=nS,CID=ANY/OLD ------> OLD if max parallel reached
decide on ERROR-CLASS
VALUE 0 successful response
SEND,W=NO,CID=1234 ------> new or ongoing conversation
VALUE 3 conversation ended
until ...
DEREGISTER ------> deregister service
LOGOFF ------> logoff from Broker
This example demonstrates the HOLD
facility of EntireX Broker. Data/messages are set in hold by the
SEND with the option
HOLD. This prevents the partner from retrieving
the data/messages until a SEND without the HOLD option is issued. Held
data/messages are always under control of the sender until they are released.
With the function UNDO, the sender can remove held
data/messages.
The HOLD option is useful if a packet of
data has to be delivered that does not fit in one request. Either the whole
request packet has to be shipped, or nothing (minimum transaction support). The
established communication is conversational. To set data/messages in hold only
makes sense in conversational communications.
This client demonstrates the hold mechanism used by the server. The data/messages are set in hold by the server and released with the last data/message sent. The client does not recognize this.
The server sends data using the HOLD
facility. Data is set in hold with SEND and option
HOLD.
Client
LOGON ------> logon to Broker
repeat
SEND,W=nS,CID=NEW ------> initiate conversation
repeat
RECEIVE,W=nS,CID=1234 ------> receive data/messages
decide on ERROR-CLASS
VALUE 0 successful response
VALUE 3 conversation ended
until ...
until ...
LOGOFF ------> logoff from Broker
_________________________________________________________
Server
LOGON ------> logon to Broker
REGISTER ------> offer service
repeat
RECEIVE,W=nS,CID=NEW ------> wait for new conversation
SEND,W=NO,CID=1234 ------> acknowledge conversation
repeat
SEND,OP=HOLD,W=NO,CID=1234 ------> set data in hold
until ...
if error
UNDO ------> remove accumulated data
endif
SEND,OP=EOC,W=NO,CID=1234 -----> release data in hold
until ...
DEREGISTER ----> deregister service
LOGOFF ------> logoff from Broker
This example demonstrates a server that deregisters while conversations
still exist. The conversations continue. With the option
QUIESCE used on the
DEREGISTER function, servers are able to remove
their services in a smooth way. Established conversations are allowed to
continue until ended with EOC by any partner. This mechanism is
needed to shut down a server without aborting existing conversations.
New conversations are not accepted for servers that have removed their services and will be connected by the broker to other servers if available, or else rejected.
The established communication is conversational.
The client establishes a conversation with a blocked
SEND. After retrieving an acknowledgment from the
server, subsequent requests/replies are transferred within this conversation.
However, the service is deregistered while the conversation continues.
After a new conversation is retrieved, the server removes the service
in a smooth way by issuing a DEREGISTER with option
QUIESCE. The established conversation continues
until ended by the client.
Client
LOGON ------> logon to Broker
SEND,W=nS,CID=NEW ------> initiate conversation
repeat
SEND,W=nS,CID=1234 ---> ongoing after deregistration
until ...
EOC,CID=1234 -----------> end of conversation
LOGOFF -----> logoff from Broker
__________________________________________________________
Server
LOGON ------> logon to Broker
repeat
REGISTER ------> offer service
RECEIVE,W=nS,CID=NEW ------> wait for new conversation
DEREGISTER,OP=QUIESCE ------> deregister service
SEND,W=NO,CID=1234 ------> acknowledge new conversation
repeat
RECEIVE,W=nS,CID=1234 ------> ongoing conversation
SEND,W=NO,CID=1234 ------> reply to client
until 3 conversation ended
until ...
LOGOFF ------> logoff from Broker
This example demonstrates a server offering multiple services. It is
possible to issue a RECEIVE to the broker
and specify the service name with an asterisk(*) in any of the fields
SERVER-CLASS, SERVER-NAME and
SERVICE. This enables clients to wait for multiple
services with one RECEIVE. The services waited for
must all be previously registered. The asterisk(*) notation can also be used in
DEREGISTER calls.
This feature is useful for alias service names or multipurpose servers. For example, a server might be able to retrieve data from a database, to add data and to remove data. A way to implement this is to register three different services.
The established communication is non-conversational.
This client demonstrates a server which is able to offer multiple services. The name of the service
the message is routed to is alternately switched between Service 1 and Service 2.
The server demonstrates how to offer multiple services. With the
REGISTER call, two services are established. With
the RECEIVE call using the asterisk notation for the
service (SV=*), the server can process any request for any of the services it
has registered. The actual service name to which the request belongs is
returned in the SERVER-CLASS,
SERVER-NAME and SERVICE fields by
the Broker. This allows the server to offer multiple services with a single
RECEIVE call.
With the DEREGISTER call, all previously
registered services are removed using the asterisk notation for the service
name (SV=*).
Client LOGON ------> logon to Broker repeat SEND,SV=SV1,W=nS,CID=NONE ------> send to first service SEND,SV=SV2,W=nS,CID=NONE ------> send to second service until ... LOGOFF -----> logoff from Broker _______________________________________________________ Server LOGON ------> logon to Broker REGISTER,SV=SV1 ------> offer first service REGISTER,SV=SV2 ------> offer second service repeat RECEIVE,SV=*,W=nS,CID=NEW ------> wait for any service SEND,W=NO,CID=1234 ------> reply to client until ... DEREGISTER,SV=* ------> deregister all services LOGOFF -----> logoff from Broker
Example 11: Model to write Client/Server Programs API Version 1
Example 12: Model to write Client/Server programs API Version 2
This screen is an ACI test tool. An interface is provided which allows you to fill the broker ACI yourself and therefore issue all types of ACI requests in any sequence. You can use it
for test purposes of EntireX Broker;
for studying EntireX Broker functions and functionality;
as counterpart of any client or server written in any programming language.
This example shows a simple client/server communication. It implements Single requests with Reply (see also this example in the tutorial). The client issues a simple request and waits for a reply from the server.
The established communication is non-conversational.
The programs for this example do not need any other Natural object (maps, data areas etc.) for execution.
You can copy the programs to any Natural library and use them as models to write your own client/server programs.
This client issues requests and expects a reply from the server.
Because a reply is required and no conversation is built, a blocked
SEND (W=nS) must be used (see also the example
Single Requests with Reply in the tutorial).
You can copy this program to any Natural library and use it as model to write your own client programs.
This server establishes a service which is able to collect simple messages from clients that do not require a reply. Although the communication is non-conversational the server gets a conversation ID with the incoming request. This ID must be used when sending back the reply to the client (see also the example Single Requests with Reply in the tutorial). You can copy this program to any Natural library and use it as a model to write your own server programs.
Client repeat SEND,W=nS,CID=NONE ------> send and wait for reply until ... _____________________________________________________ Server REGISTER ------> offer service repeat RECEIVE,W=nS,CID=NEW ------> wait for request SEND,W=NO,CID=1234 ------> reply to client until ... DEREGISTER ------> deregister service
This example shows a simple client/server communication. It implements Single requests with Reply (see also this example in the tutorial). The client issues a simple request and waits for a reply from the server.
The established communication is non-conversational.
The programs for this example do not need any further Natural object (maps, data areas etc.) for execution.
You can copy the programs to any Natural library and use them as models to write your own client/server programs.
This client issues requests and expects a reply from the server.
Because a reply is required and no conversation is built, a blocked SEND (W=nS)
must be used (see also the example Single Requests with Reply in the
tutorial).
You can copy this program to any Natural library and use it as model to write your own client programs.
This server establishes a service which is able to collect simple messages from clients that do not require a reply. Although the communication is non-conversational the server gets a conversation ID with the incoming request. This ID must be used when sending back the reply to the client (see also the example Single Requests with Reply in the tutorial). You can copy this program to any Natural library and use it as a model to write your own server programs.
Client LOGON ------> logon to Broker repeat SEND,W=nS,CID=NONE ------> send and wait for reply until ... LOGOFF -----> logoff from Broker _________________________________________________ Server LOGON ---------> logon to Broker REGISTER ------> offer service repeat RECEIVE,W=nS,CID=NEW ------> wait for request SEND,W=NO,CID=1234 --------> reply to client until ... DEREGISTER ----> deregister service LOGOFF --------> logoff from Broker
An Attach Manager is a server that is able to start server. If no
server is found for a client request, the Broker informs the Attach Manager to
start the desired server. To be informed by the Broker, the Attach Manager must
previously register all servers for which it is responsible using the option
ATTACH.
LOGON ------> logon to Broker REGISTER -----------------------> Attach Manager main service REGISTER,OP=ATTACH,SV=SV1 ------> attachable service repeat RECEIVE,W=nS,CID=NEW ---------> wait for any service until ... DEREGISTER,SV=* ------> deregister all services LOGOFF -----> logoff from Broker
Demonstration of Attach Manager Interface:
This example shows a server collecting simple messages from clients
that do not require a reply. The server polls for a message at the
RECEIVE, i.e. the RECEIVE
is not blocked. This enables the server to do other work, even if no message is
available for processing. The client uses a non-blocked
SEND because no reply is expected from the server.
The communication is non-conversational.
A Server collecting cyclic statistical data from various input media, e.g. mainframe console, job management systems, databases and client messages from the broker.
This client issues simple messages to a server without expecting a
reply. Because no reply is required - the server will not return any response -
the client issues a SEND without wait
(W=NO). This type of call is called non-blocked because it is not
blocked and control is returned immediately to the caller. With a value of
"NONE" in the CONV-ID field
of the ACI control block the client specifies non-conversational
communication.
This example shows a server collecting simple messages from clients
that do not require a reply. The server polls for a message at the
RECEIVE, i.e. the RECEIVE
is not blocked. This enables the server to do other work, even if no message is
available for processing. The client uses a non-blocked
SEND since no reply is expected from the server. The
communication is non-conversational.
A Server collecting cyclic statistical data from various input media, e.g. mainframe console, job management systems, databases and client messages from the broker.
Client LOGON ------> logon to Broker repeat SEND,W=NO,CID=NONE ------> forward message to server until ... LOGOFF ----> logoff from Broker _________________________________________________________ Server LOGON ------> logon to Broker REGISTER ------> offer service repeat RECEIVE,W=NO,CID=NEW ------> poll for message decide on ERROR-CLASS VALUE 0 successfull response VALUE 74 no message available - so free for other work until ... DEREGISTER ------> deregister service LOGOFF ------> logoff from Broker
This example shows a client sending requests/messages and expecting a
reply from the server. The established communication is non-conversational.
Because a reply is expected, the client uses a blocked SEND call to the broker. The server polls for a request at the
RECEIVE, i.e. the RECEIVE
is non-blocked. This enables the server to do other work, even if no request is
available for processing.
This client issues requests/messages and expects a reply from the
server. Because a reply is required and no conversation is built, a blocked
SEND (W=nS) must be used. If the wait time elapses
before the reply is received, there is no chance in non-conversational mode of
getting the reply. However, you can do this in conversational mode by issuing a
subsequent RECEIVE.
This server establishes a service that is able to receive
requests/messages and return a reply to the client. The server works
non-blocked at the RECEIVE, that is, a
RECEIVE with W=NO is issued to the
Broker. Because of this non-blocked call, control is retained, allowing the
server to do other work.
Client
LOGON ------> logon to Broker
repeat
SEND,W=nS,CID=NONE ------> send and wait for reply
until ...
LOGOFF -----> logoff from Broker
____________________________________________________________
Server
LOGON ------> logon to Broker
REGISTER ------> offer service
repeat
RECEIVE,W=NO,CID=NEW ------> poll for request/message
decide on ERROR-CLASS
VALUE 0 successfull response
SEND,W=NO,CID=1234 ------> reply to client
VALUE 74 no message available - so free for other work
until ...
DEREGISTER ------> deregister service
LOGOFF ------> logoff from Broker