The MCST software provides AS/400 applications with an easy-to-use, high level MCST API, which is based on the program call and the parameter list. One of the call parameters is used to define the operation requested from the MCST. These MCST operations are: Init, Send, Receive, Query, Close, and End.
The communications between the applications take place on client/server basis. This means that the other application (the one who establishes the connection) is the requester and the other is the server during the duration of the socket connection.
Notice, that the client/server roles of the applications (and the corresponding modes of MCST) cannot be changed during the socket connection. If the application calls MCST in the client mode in order to open the socket connection, it can only function as a client/requester during the socket connection. In the same way, the other application must call MCST to start it in the server mode, and this applications and MCST cannot change the role during the socket connection. The server application can send data to the client application only as a response to the service request.
If you need to transfer data messages two-way between the system, so that the messages are independent of each other, you need both the client and server applications (and the corresponding MCSTs) in both systems: the first client/server pair takes care of initiating the socket connection to another 'direction', and the other pair on the opposite direction. See the following figure.
If you are not familiar with the general principles of client/server communications, please, see the related chapter in the Manycom Socket Tools, Installation and User's Guide manual.
MCST does not add any control codes or characters in the data message, so the partner application can be any application - e.g. Windows, UNIX, LINUX or AS/400 - using the TCP/IP socket communication of that system. The OS/400 socket interface used by the MCST follows the widely accepted BSD 4.3 socket specification.
MCST includes modules for both the client and server functions. If the partner system is also an AS/400 system, the socket communication of both the client and server applications can be handled with MCST.
Otherwise, a separate software or programming must be used on the partner side.
Up to 32 kbytes of data can be sent or received with each send or receive request to MCST.
User-defined translation tables can be defined in one of the call parameters to set the ASCII/EBCDIC or other character conversion for the data. This can be done separately in each call, if needed.
Notice, that your application should always check the MCST return code after each MCST call operation to decide what to do if the requested operation was unsuccessful.
MCST is transparent to the data with the exception that the character conversion is performed by MCST if requested. The length, contents and format of each data message can be specified freely in the applications. The content and meaning of each message is usually coded as a 'transaction id' in the first characters of the message data. This way the client and server applications can be easily 'synchronised' and they can easily determine how to handle each received message.
If the server application has not initiated MCST to start listening the listen port, then the calls from the clients to this port will be unsuccessful. In this case, the client application usually gets an error code from it's socket interface. MCST client also returns the error code in this situation.
If the MCST server has already accepted a call request, and a new socket connection from another client is requested to the same IP listen port, the new connection will be accepted and the new client can send data to the listen port. However, the server application can serve the new connection (i.e. read the sent data) only after closing first the previous connection and after a new initialization (Init) function is performed. The maximum number of client calls in the queue is set to 512 in the MCST configuration by default.
Normally the client decides when to end the socket connection, but the server application can also end listening the IP port or end waiting for data from the established socket connection if the specified time interval expires. The time interval is set by the application when calling the MCST API program.
The base TCP/IP socket software of the OS/400 operating system takes care of the buffering of the received data until the receiving application or MCST reads the data from the socket. The buffer size (512 B...8 MB) can be set with the command CHGTCPA.
If the application works as a client application, it calls the MCST program 'SOCCL' with the specified parameter list. If the application works as a server application, it calls the MCST program 'SOCSE' with the corresponding parameter list.
A separate call is needed for each socket operation: Init, Send, Receive, Query, Close, and End. The MCST software always informs the applications whether the requested operation was successful by returning a MCST return code and, when necessary, the corresponding error message.
Notice, that the socket communications used by MCST is based on the so called stream socket technique. Your application can specify in the Receive data length parameter how many characters it wants to get from MCST. If the value is left blank, it will get an unexpected number of characters (the number MCST got with one read operation) regardless of the number of characters sent by the partner application.
For each receive operation, a wait time-out value can be set by the application to define the maximum time for MCST to wait for the data from the socket before MCST returns the control to the application. If the timer expires, the corresponding MCST 'time-out' return code and message together with the received data and data length are returned to the application, which can now decide what to do next.
The receiving application can select one of the following receive modes: 1) receive a specified number of characters, 2) receive a 'logical record' or a data message which ends with the specified character string, 3) receive the number of characters sent by the other application; the sending application must set the length of the sent data in binary mode in the first four bytes of the data. Notice also, that the wait-timer can, and usually should be set with all the three modes.
The program call parameter lists for the MCST client and server API interfaces are described in detail in the manual Manycom Socket Tools, Installation and User's Guide.
Model, test and simulation applications of MCST
In order to ease the learning and use of MCST, two model applications that use the MCST API interface are bundled with the MCST package. These applications provide the screens to start MCST in the client and server modes.
The other screen can be used as a 'client screen' to establish a socket connection to a specified IP address and IP port, key in and send data to the socket, show the received data, and close the connection. The other screen can be used as a 'server screen' to start listening the specified IP port, read and show the received data, send the response, etc.
Notice that the source codes of these applications and the DDS specifications for the screens are included in the package.
The applications can be put to use as examples in programming, but they can also be utilized in the simulation and testing of client/server applications that are under work or already finished.
The use of these model applications has been described in more detail in the separate document 'Manycom Socket Tools, Installation and User's Guide.