| Communications Module (MCS) for DOS |
This chapter describes how you set up the Message Control System. For a description of the basic concepts of the communications facility and the statements by which a program sends and receives messages, see your Language Reference - Additional Topics.
The Message Control System (MCS) enables up to 10 consoles to be connected to a single COBOL process for sending and receiving messages. Communication between the COBOL process and the consoles is controlled by the Message Control System (MCS).
The MCS is the logical interface between a COBOL program and the consoles it controls. The MCS uses some facilities of the Run-time system (RTS) and the operating system. It is the MCS that checks whether there are any messages to be sent or to be received. The MCS also handles system-specific tasks, allowing you to create programs that are independent of any system.
Before you can use the communications facilities provided by the MCS, you must specify the structures, formats and symbolic names of the queues in which the MCS buffers messages waiting to be sent to the program or consoles. You can also specify symbolic names for the consoles. To specify these symbolic names you must set up an initialization file by using the comms program (see the section Creating an Initialization File). The names you specify in the Communication Description (CD) of your COBOL program (see your Language Reference - Additional Topics) must match the names already defined to the MCS in the initialization file.
You must create an MCS initialization file for each COBOL application program.
To create an initialization file enter:
cobrun comms
If, however, you want to use the comms module from statically linked programs you must first pre-link the program that is to use comms and then execute the comms module from it.
For example:
cob -x CM101.cbl -e ""
creates a new RTS 'CM101' with CM101 linked into it as a callable module.
CM101 comms
executes the comms module from CM101.
Once you have invoked the comms module, the screen shown in Figure 9-1 is displayed:
Figure 9-1: Creating an Initialization Screen
The default is to create a file (C). You can enter a filename in one of the following formats:
You can abandon the comms process at this point, if you want, by entering a space instead of C or U.
Once you have specified the file-name, press Enter. The Console Definition screen is displayed, that allows you to define one or more consoles.
You must define each console to which your program refers. The Console Definition screen shown in Figure 9-2 enables you to define each console in turn:
Figure 9-2: Console Definition Screen
Enter 0 as the main Console Number and an optional
symbolic name in the Console Name field. The symbolic name
of the console is the one that you use in your COBOL program if you want
to SEND messages to this particular console. The physical device name is
/dev/ttynn (where nn
is the physical device number of the console); this must not be a login
port. Also, you should not enter a physical device
name for the system console. The Console Delay field
specifies the rate at which messages are output to the screen. The rate is
from 0 to 9, where 0 is the fastest and 9 the slowest. The default is 4.
The Enabled for Input? field has a default of yes (Y).
This means that a character entered at the console is automatically sent
to the MCS for processing. If no (N) is specified, you must specifically
enable the console for input from within the COBOL program, using the
ENABLE statement.
If you do not do this, characters cannot be accepted and are
rejected with an audible warning. When a console is disabled in this way,
the MCS still polls the console for input, although no characters can be
entered.
The seven fields at the bottom of the screen are used to specify the control characters that are received from or sent to the console being defined.
If you want to specify control characters for a particular console, you must specify all the control characters, entering at least one hexadecimal character for each field. As control keys are defined only for the main console, you must define the control characters for all other consoles. Table 8-1 describes the default mapping between control keys and communications functions.
Table 8-1 : Message Control System Default Control Keys
| Key | Function |
|---|---|
| Return | End of message |
| <left-arrow> | Rubout (erases last character) |
| <up-arrow> | End of Segment |
| <right-arrow> | Purges message |
| <down-arrow> | End of group |
| Home | Reset |
See the section Sending a Message later in this chapter for more
information on messages, segments and groups.
The clear screen function is the only output control sequence requested by the initialization phase. The MCS sends this control sequence to all consoles identified to it. If the sequence is not specified for a secondary console, the screen of the secondary console is not cleared before being used by the COBOL program. The clear screen control sequence is sent to a secondary console each time a SEND... BEFORE PAGE or SEND... AFTER PAGE is executed in the COBOL program. If the sequence is not specified, these statements behave in the same way as SEND... BEFORE LINE and SEND... AFTER LINE.
When you have entered all the information, press Enter, and the next screen is displayed. The next screen enables you to define the console's associated queues.
You can define many queues and sub-queues for each console, and these relate to the SYMBOLIC QUEUE and SYMBOLIC SUB-QUEUES defined in the Communication Description of your program. The queue structure is shown in Figure 9-3.
Figure 9-3: Queue Structure
You must declare queues in order of increasing priority, so the last queue defined has the highest priority.
The screen that prompts you to define the queues is shown in Figure 9-4.
To set up the queue structure shown in Figure 9-3 you must make these replies to the queue prompt:
| Queue - Name of Main Queue | MQ1 | MQ1 | MQ1 | MQ1 | MQ1 |
| Sub Queue 1 | SQ13 | SQ12 | SQ11 | SQ11 | SQ11 |
| Sub Queue 2 | SQ16 | SQ15 | SQ14 | ||
| Sub Queue 3 | SQ17 |
Figure 9-4: Queue for Console Screen
The last queue to be entered has the highest priority. You can define as many sub-queues at the same level as you want, but only three levels. So for example, you can define a queue with a structure similar to that shown in Figure 9-5.
Figure 9-5: More Complex Queue Structure
The definitions for such a structure are basically the same as for less complex structures. You start the definitions with the lowest priority queue and enter each path (for example MQ2, SQE, SQE; MQ2, SQE, SQD; and so on).
Notice that the same name can appear more than once, so long as the same name does not appear twice in the same sub-queue. Each path must be unique. Thus, the following is allowed:
but the next structure is not allowed because the MCS cannot distinguish between the two queues called Q1, SQA, SQA.
When you have entered all the information, press Enter and the queue prompt is displayed again. You can define several queues and sub-queues for one console in this way. When you have defined all the queues, leave spaces in the main queue name field and press Enter.
The console definition prompt is displayed again, so you can define another console and its associated queues. When all the consoles have been displayed, leave a space in the console number field and press Enter.
The auto-queue selection has the default N (no). Auto-queue selection is a facility that directs a message to a particular queue or sub-queue depending on the first few characters of the message. You specify the path before the actual message.
The auto-queue passes incoming messages initially to the MCS. When the MCS receives a message, characters from the front of the message are examined and compared with main queue names known to the MCS. If a match is found, more characters are examined and compared with subqueue names of the matching queue. Subqueues two and three are also compared, and if a match is found, the message is directed to the matching queue. The message is directed to whichever queue matches. If no match is found at all, the message is directed to the main queue with the highest priority.
When you have defined all the consoles and queues, you are prompted to enter the system-wide initialization data. The screen shown in Figure 9-6 is displayed.
Figure 9-6: System Initialization Screen
The input and output passwords are associated with your program. The password is the identifier or literal associated with the KEY clause in the ENABLE/DISABLE statement (see your Language Reference - Additional Topics). If no passwords are specified, the MCS takes these defaults:
| input password | SPICODE01 | |
| output password | SPOCODE01 |
The user program name is the name of the program that uses the MCS with the definitions you have just set up.
The default to the message server prompt is N (no), but you must specify Y (yes) if a Communication Description in your program contains the INITIAL phrase. A message server is run each time a message is received and is continually re-run until a message beginning "######" is entered. A run unit (default no) runs only when it is specifically enabled.
When you have entered all of the data, press Enter. A summary is displayed, showing which consoles are attached. All of the attached consoles receive a summary message to say they are attached. All the consoles and queues you have entered are now defined to the MCS. Control is then automatically transferred to the user program.
Updating an initialization file is similar to creating such a file. When you enter:
cobrun comms
at the first prompt you must enter U to show you want to update a file, and the name of the file to be updated. The screen then displays the definition of each console and its queues, with the data that has previously been entered. To enter new data or to overwrite existing data just move the cursor to the required field and enter the new value. If a main queue field is overwritten with spaces, this queue and all its sub-queues are removed. The subsequent sub-queue screens are also removed.
When you have reviewed all the existing data in the definition, you can enter new consoles and associated queues as described in the previous section. As when creating an initialization file, enter spaces into the main queue name and console number fields when all of the new values have been entered.
When you have created an initialization file, you can use this file to define symbolic consoles and queues to the MCS before the program is run. The command to use an existing file is:
cobrun comms file-name
where file-name is the name of the initialization
file. You may want to use an existing file rather than creating a new file
(if the user program is being copied onto another computer, for example).
The symbolic-names must be defined to the computer's MCS.
When you run a program to communicate with other consoles, the program uses the MCS to send and receive messages and to check whether there are any messages in the queues. The COBOL program passes a message to the MCS with the SEND statement, and this message is then put into one or more destination queues defined by the COBOL program's CD, before being output to the console. The RECEIVE statement causes outstanding messages in the input queues to be passed to the COBOL program. You can check the number of complete messages in a queue with the ACCEPT ... MESSAGE COUNT statement. Any console can send and receive messages, but only when it has been ENABLED for INPUT (SEND) or OUTPUT (RECEIVE). See your Language Reference - Additional Topics for more information on these statements.
The MCS takes the symbolic names specified in your COBOL program and matches them to the actual consoles from the definitions you initialize. If the MCS cannot handle the message, a status code is returned in the STATUS KEY data item. Your Language Reference - Additional Topics explains how to use the STATUS KEY clause, and lists the possible codes that can be returned. A status code of 00 is returned on successful handling of the message. It is the programmer's responsibility to ensure that the program checks for errors and handles them.
You can send whole messages, parts of messages called segments and groups of messages. You do this using the SEND statement with the WITH ESI, WITH EMI or WITH EGI clause (see your Language Reference - Additional Topics).
ESI is the end of a segment, and the character specified in the initialization file is the one you enter to signal the end of a segment. The segments are passed to the MCS, but nothing is actually sent until the entire message is passed.
EMI is the end of the message, and the character specified in the initialization file is the one you enter to signal the end of a message. EMI can be sent after a simple message or after a series of segments.
EGI is the end of group, and the character specified in the initialization file is the one you enter to signal the end of a group. You may want to send an end-of-group to show that the preceding messages are related.
In the same way that you can send whole messages or parts of messages, you can receive messages or part-messages, using the statement:
See your Language Reference - Additional Topics for more information.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Communications Module (MCS) for DOS |