| Client/Server Binding | Communications Module (MCS) for UNIX | |
This chapter describes the Message Control System (MCS) and explains how to use the Mcsetup utility to create an initialization file which enables your COBOL programs to communicate across a network.
The Message Control System (MCS) enables COBOL programs to communicate with each other via network sessions using COBOL SEND and RECEIVE statements.
Communications syntax is described in the Language Reference - Additional Topics. Before you begin this chapter, you should read the chapter Communication in the Language Reference - Additional Topics.
The MCS performs the following tasks:
Before you can use the communications facilities provided by MCS, you must use the Mcsetup utility ( mcsetup.exe ) to create an MCS initialization file for each COBOL program. The initialization file contains the structures, formats and symbolic names of the terminals and queues that your COBOL program will use.
Before you create the initialization file, you must specify the symbolic terminals and queues in the Communication Description (CD) of your program. See the chapter Communication in the Language Reference - Additional Topics for details of the CD entry.
To use the MCS, you must link mcs.obj to your communications application before you can run it.
To link your program, enter:
link program-name+mcs.obj;
The Mcsetup utility creates an initialization file with a .mcs extension. The initialization file:
An MCS initialization file must be created for each COBOL application program using the Mcsetup utility.
The command line syntax for invoking Mcsetup is:
mcsetup program-name
where program-name is the name of your COBOL
application program.
If you specify the program name on the command line, the Symbolic Device Definition screen appears, enabling you to define each symbolic terminal.
If you do not specify the name of your COBOL program on the command line, Mcsetup prompts you for the name of the program as follows:
MCS: initialization file create/update Application file-name [.EXE]:
When you enter the program name, the Symbolic Device Definition screen appears.
If you specify an application program name for which an initialization
file already exists, Mcsetup makes a backup file called program-name.tmp.
The values held in the .mcs file
are then displayed on your screen, enabling you to update the file.
In the following sections the two programs shown below are used to illustrate features of the Mcsetup utility.
Program 1 - cmsend.cbl:
cd cm-outque-1 for output
. . .
status key is out-status-key.
symbolic destination is sym-dest.
procedure division.
. . .
move "consol1" to sym-dest.
. . .
enable output cm-outque-2 with key "spocode02".
send cm-outque-1 from identifier-1.
Program 2 - cmrec.cbl:
cd cm-inque-1 for input
symbolic queue is main-queue
symbolic sub-queue-1 is sub-one.
. . .
status key is in-status-key.
procedure division.
. . .
move "iqname01" to main-queue.
move "sqname02" to sub-one.
enable input cm-inque-1 with key "spicode01".
receive cm-inque-1 message into identifier-2.
The Symbolic Device Definition screen enables you to define each symbolic terminal:
Symbolic Device Definition
Symbolic Terminal Name [ ] Physical Device [ ] Message Dispatch Rate [4] Enabled for Input?(Y/N) [Y] Start Session?(Y/N) [ ]
On the Symbolic Device Definition screen you define a connection between a Symbolic Terminal Name (from your program I/O) and the physical device name that identifies your program on the PC Network.
For example, the program cmsend.cbl has an OUTPUT CD with a Symbolic Destination of SYM-DEST and the value "CONSOL1". Using this screen you can define SYM-DEST (CONSOL1) to be another COBOL program, cmrec.cbl. Therefore, a SEND to SYM-DEST would result in cmrec.cbl receiving a message.
Using an initialization file enables you to change the names of network devices with which you want to communicate without having to recompile and relink your application programs.
The Physical Device is the network device name which is to behave as the symbolic source or the symbolic destination. This should not be the same as your program but should be the program with which you wish to communicate. The device name must not include a device or a path name. The MCS tries to establish a network session with all of the devices that you name in the Physical Device field of the Symbolic Device Definition screens.
The communications program at each end must add this physical device name to the network before the MCS can establish the network session. The logical and physical names can be the same, provided that they are not longer than 12 characters in length.
The Message Dispatch Rate specifies the rate at which messages are output to the symbolic terminal from your program. The rate is in the range 0 to 9, where 0 is the fastest. The default rate is 4.
The Enabled for Input field has a default of "yes" (Y). When a symbolic terminal is enabled for input, any messages sent to or from this terminal are stored in the MCS for processing until a RECEIVE statement is executed in your program.
If your program performs an ENABLE, type N (No) in this field because you cannot ENABLE an already enabled symbolic terminal.
The Start Session ? (Y/N) field determines whether the MCS calls the other program, or waits to be called by the other program. The default is Y. The MCS calls the other program to start the sessions. When any two programs are communicating, one program must call, and the other program must be called.
Each side of the communication session must have an initialization file. The value in the Start Session ? (Y/N) field is different in both MCS files. One should have a Y and the other file should have the value N.
For example, the Symbolic Device Definition screen for cmsend.cbl would be:
Symbolic Device Definition
Symbolic Terminal Name [CONSOL1 ] Physical Device [CMREC ] Message Dispatch Rate [4] Enabled for Input?(Y/N) [Y] Start Session?(Y/N) [Y]
Press Enter to move to the next screen.
You can define queues and subqueues for each symbolic terminal, and these correspond to the symbolic queue and symbolic subqueues defined in the INPUT CD of your application program.
After you enter a name in the Symbolic Terminal Name field and press Enter, the Queue Definition screen appears as follows:
Queue for Terminal name
Queue - name of Main Queue [ ] Sub Queue 1 [ ] Sub Queue 2 [ ] Sub Queue 3 [ ] Enabled for input (y/n) [N] Auto-Queue Selection Enabled? [N]
The name field is the symbolic terminal specified on the previous screen. Therefore, if you named your first symbolic terminal CONSOLE1, for example, then the header reads:
Queue for Terminal CONSOLE1
With the Queue for Terminal screen you define the queues and subqueues associated with the symbolic terminal(s) for INPUT CDs in your program.
If your program does not use INPUT CDs, then you can ignore this screen, because OUTPUT CDs do not have named queues associated with them.
You can define as many main queues as you want. You can define up to three subqueues for each main queue, and like the symbolic terminal, the main queue and its associated subqueues can be initially disabled or enabled.
Type the names of the symbolic Subqueues that you named in the INPUT CD of your program. You can define up to three subqueues for each main queue. These Subqueue fields apply only to one INPUT CD.
The Enabled for Input (Y/N) field determines whether the main queue and its subqueues are enabled for input. The default is N. When a queue is enabled for input, any messages sent to this queue are stored in the MCS for processing until your program executes a RECEIVE statement. If the queue is not enabled for input, any messages sent to the MCS for processing are rejected. By using an ENABLE INPUT in your program, you can enable a queue that is initially disabled.
Type Y for this prompt only if your program does not use ENABLE INPUT for the INPUT CD. Your program gives you an error if you enable an already enabled queue or disable an already disabled queue.
The Auto-Queue Selection Enabled field has a default of N. Auto-queue selection directs a message to a particular queue or subqueue depending on the first few characters of the message. You specify the queue before the message when you are sending information.
Incoming messages are initially passed 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 2 and 3 are also compared, and if a match is found, the message is directed to the matching queue. If no match is found, the message is directed to the main queue having the highest priority.
For example, the Queue for Terminal CONSOL1 for cmrec.cbl would be:
Queue for Terminal name
Queue - name of Main Queue [IQNAME01] Sub Queue 1 [SQNAME02] Sub Queue 2 [ ] Sub Queue 3 [ ] Enabled for input (y/n) [N] Auto-Queue Selection Enabled? [N]
Press Enter after completing all information for the first queue.
The Symbolic Device Definition screen then reappears, enabling you to define further symbolic terminals, queues and subqueues. This loop continues through the Symbolic Device Definition screen, then down through the Queue Definition screen until you leave spaces in the Symbolic Terminal Name field on the Symbolic Device Definition screen.
Press Enter. This displays the System Initialization screen for
program-name.
When you have defined all the symbolic terminals, queues, and subqueues, you are prompted to enter the system-wide initialization data. The following screen appears:
System Initialization
Application Program [progname ] Input Password [ ] Output Password [ ] Is this a Message Server [N]
The Application Program field contains the name you typed on the Mcsetup command line or the name specified on the application name prompt.
The Input Password and Output Password fields contain passwords associated with your program. The password is the identifier or literal associated with the KEY clause in the ENABLE/DISABLE statement. If no passwords are specified, the MCS takes these defaults:
| input password | SPICODE01 | |
| output password | SPOCODE01 |
The default to the message server prompt is N, but you must specify Y if your application contains an INITIAL CD. A message server is run each time a message is received and is continually rerun until a message beginning with ###### is received by the MCS.
For example, system initialization for cmsend.cbl would be:
System Initialization
Application Program [CMSEND ] Input Password [SPICODE01 ] Output Password [SPOCODE01 ] Is this a Message Server [N]
When you have entered all the data on this screen, press Enter. The Mcsetup program creates an initialization file for your application program.
You are then returned to the DOS prompt. The MCS reads this initialization file when you run your communications application.
To update an existing .mcs file , enter the name of the file on the Mcsetup command line. The Mcsetup program makes a backup copy of the file, using the application name with a .tmp extension, and loads the existing .mcs file.
Mcsetup then displays the definition of each symbolic terminal and its queues, with the data that you have previously 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 subqueues are deleted. The related subqueue screens are also deleted.
When you have reviewed all the existing data in the definition, new symbolic terminals and associated queues can be entered as described in the previous sections. As you did when creating an initialization file, enter spaces into the main queue name and symbolic terminal name field when all of the values have been entered.
When you run a communications program, 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. This message is then put into one or more destination queues defined by the communication description entries (CDs) in the COBOL program before being sent to the program with which you wish to communicate.
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 RECEIVE messages, but only when it has been ENABLED for input (sent) or output (received).
The MCS takes the symbolic terminal names specified in your application program and matches them to the network device names in the initialization file which you created for that application.
If for any reason the MCS cannot handle the message, a status code is returned in the STATUS KEY data item. The Language Reference explains how to use the STATUS KEY clause, and also lists the possible codes that can be returned. A status of 00 is returned on successful handling of the message.
You can send whole messages, parts of messages (called segments), or groups of messages by using the SEND statement with the WITH ESI, WITH EMI, or WITH EGI clauses.
ESI is the end of a segment. The segments are passed to the MCS, but nothing is actually sent to the session until the entire message is passed.
EMI is the end of the message. EMI can be sent after a simple message or after a series of segments. The MCS sends the message to the other program with a carriage return character indicating EMI.
EGI is the end of the group. You may want to send an end-of-group to show that the preceding messages are related. The MCS sends the message with a BEL character (ASCII value equal to 07) to indicate the end of the group.
In the same way as you can send whole messages, groups of messages, or parts of messages, you can receive whole messages, groups of messages, or parts of messages by using the RECEIVE....MESSAGE INTO and RECEIVE.... SEGMENT INTO statements. Refer to the Language Reference for more information.
The MCS needs the PC Network to be started in a RECEIVER or REDIRECTOR configuration. If the network program is not started when you run your program, the MCS stops your program with an error message.
When the MCS is attempting to start a session with the programs which are to act as SYMBOLIC SOURCE or SYMBOLIC DESTINATION terminals, it will wait indefinitely for the session to be established.
If one of the programs cannot send or receive messages, the MCS aborts the attempt to establish a network session and issues an error message.
When you run an application program that uses the communications facilities, the MCS creates one network session between your program and each symbolic terminal defined in its initialization file. If the MCS cannot create a session between your application and a symbolic terminal, the MCS stops and issues an error message.
The MCS creates all sessions when the first COBOL communications verb is executed. To start the session, the MCS adds the name of your application program to the local network card and issues a CALL/LISTEN to the remote application name.
The MCS issues a CALL if you answered Y (yes) in the Start Session? (Y/N) field during Mcsetup initialization file creation. The MCS issues a LISTEN if you answered N (no) to this question.
Normally, the session remains active until a STOP RUN ends your program. At that time, the MCS hangs up each active session and deletes your program's network name from the local network card.
The MCS processes two types of network messages: data messages and acknowledgments. Data messages can contain embedded ASCII carriage control characters that correspond to the BEFORE/AFTER ADVANCING phrases in the SEND statement of your program.
Acknowledgments are two bytes long. The first byte indicates whether the network message is a data message or an acknowledgment. In a data message, the second byte contains the END-INDICATOR given in the SEND statement of your program. In an acknowledgment, the second byte contains the acknowledge value that indicates how the MCS handled the last message sent.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Client/Server Binding | Communications Module (MCS) for UNIX | |