HP 3000 Manuals

Micro Focus COBOL System Reference, Volume 1

Operation 

You must create an MCS initializationfile for each COBOL application
program.

Creating an Initialization File 

To create an initialization file enter:

cobrun comms

If, however, you want to use the comms module from statically
linkedprograms you must first pre-link the program which 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 Initialization screen shown
in Figure 8-1 is displayed: 


          Figure 8-1:  Creating an Initialization Screen 

The default is to create a file (C). You can enter a file-name in one of
the following formats:

   *   a file-name with an extension of your choice

   *   a file-name with no extension, in which case the file is given the
       default extension of .mcs

   *   do not enter a file-name at all, in which case the initialization
       file is stored in a file called INIT.mcs

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, which allows you to define one or more
consoles.

Defining a Console.   

You must define each console to which your program refers.  The Console
Definition screen shown in Figure 8-2 enables you to define each console
in turn:


          Figure 8-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 devicename 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 of 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.  Table 8-1:  Message Control System Default Control Keys 

-------------------------------------------------------
|                          |                          |
| Key                      | Function                 |
|                          |                          |
-------------------------------------------------------
|                          |                          |
| Return                   | End of message           |
|                          |                          |
-------------------------------------------------------
|                          |                          |
| <-                       | Rubout (erases last      |
|                          | character)               |
|                          |                          |
-------------------------------------------------------
|                          |                          |
| ^                        | End of Segment           |
|                          |                          |
-------------------------------------------------------
|                          |                          |
| ->                       | Purges message           |
|                          |                          |
-------------------------------------------------------
|                          |                          |
| v                        | 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.

Defining the Queue.   

You can define many queues and sub-queuesfor each console, and these
relate to the SYMBOLIC QUEUE and SYMBOLIC SUB-QUEUES defined in the
Communication Description.  The queue structure is shown in Figure 8-3.


          Figure 8-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 8-4.

To set up the queue structure shown in Figure 8-3 you must make these
replies to the queue prompt:

Queue - Name   MQ1            MQ1            MQ1            MQ1            MQ1
of Main Queue

Sub Queue 1    SQ13           SQ12           SQ11           SQ11           SQ11

Sub Queue 2                                  SQ16           SQ15           SQ14

Sub Queue 3                                                                SQ17


          Figure 8-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 8-5.


          Figure 8-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 within the same sub-queue.  Each path must be
unique.  Thus:


            

is allowed, but:


            

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 promptis 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 selectionhas the default N (no).  Auto-queue selection is
a facility in Micro Focus COBOL 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.

System Initialization.   

When you have defined all the consoles and queues, you are prompted to
enter the system-wide initialization data.  The screen shown in Figure
8-6 is displayed.


          Figure 8-6:  System Initialization Screen 

The inputand outputpasswords 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 will be 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 of 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 

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.

Using the Initialization File 

When you have created an initialization file, you can use this file to
define symbolic consoles and queuesto the MCS before the program is run.
The command to use an already 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.

Communicating with other Consoles 

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 for any reason 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 also
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.

Sending a Message.   

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 EMIor WITH EGI clause (see your Language Reference - Additional 
Topics).

ESIis 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.

EMIis 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.

EGIis 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.

Receiving a Message.   

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.

MPE/iX 5.0 Documentation