HP 3000 Manuals

Procedure Division in the Communication Module [ COBOL/HP-UX Language Reference for the Series 700 and 800 ] MPE/iX 5.0 Documentation

COBOL/HP-UX Language Reference for the Series 700 and 800

Procedure Division in the Communication Module

The ACCEPT MESSAGE COUNT Statement

Function

The ACCEPT MESSAGE COUNT statement
causes the number of messages in a queue to be made available.

General Format

ACCEPT cd-name MESSAGE COUNT

Syntax Rule

CD-name must reference an input CD.

General Rules

1. The ACCEPT MESSAGE COUNT statement causes the MESSAGE COUNT field
specified for cd-name to be updated to indicate the number of
messages that exist in a queue, sub-queue-1, ... .

2. Upon execution of the ACCEPT MESSAGE COUNT statement, the contents
of the area specified by a communication description entry must
contain at least the name of the symbolic queue to be tested.
Testing the condition causes the contents of the data items
referenced by data-name-10 (STATUS KEY) and data-name-1 (MESSAGE
COUNT) of the area associated with the communication entry to be
appropriately updated. (See "The Communication Description -
Complete Entry Skeleton" in this chapter.)

The DISABLE Statement

Function

The DISABLE statement
notifies the MCS to inhibit data transfer between specified output queues
and destinations for output or between specified sources and input queues
for input.
________________________________________________________________________
|(ANS85) |
|The KEY phrase of the DISABLE statement is classed as an obsolete |
|element in the ANSI'85 standard and is scheduled to be deleted from |
|the next full revision of the ANSI Standard. |
________________________________________________________________________

________________________________________________________________________
|(MF) |
|All dialects within this COBOL implementation fully support this |
|syntax. Refer to your COBOL System Reference for details on |
|using the FLAGSTD directive to detect all occurrences of this |
|syntax. |
________________________________________________________________________

General Format

Syntax Rules

1. Cd-name must reference an input CD when the INPUT phrase
is specified.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|2. Cd-name must reference an input-output CD when the I-O TERMINAL |
| phrase is specified. |
| |
________________________________________________________________________

3. Cd-name must reference an output CD when the OUTPUT phrase is
specified.

4. Literal-1 or the contents of the data item referenced by identifier-1
must be defined as alphanumeric.

General Rules

1. The DISABLE statement provides a logical disconnection between the
MCS and the specified sources or destinations. When this logical
disconnection is already in existence, or is to be handled by some
other means external to this program, the DISABLE statement is not
required in this program. The logical path for the transfer of
data between the COBOL programs and the MCS is not affected by the
DISABLE statement.

2. When the INPUT phrase with the optional word TERMINAL is
specified, the logical path between the source and all queues and
sub-queues is deactivated. Only the contents of the data item
referenced by data-name-7 (SYMBOLIC SOURCE) of the area referenced
by cd-name are meaningful.

3. When the INPUT phrase without the optional word TERMINAL is
specified, the logical paths for all of the sources associated
with the queues and sub-queues specified by the contents of
data-name-1 (SYMBOLIC QUEUE) through data-name-4 (SYMBOLIC
SUB-QUEUE-3) of the area referenced by cd-name are deactivated.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|4. When the I-O TERMINAL phrase is specified, the logical path |
| between the source (as defined by the content of the data item |
| referenced by data-name-3 (SYMBOLIC TERMINAL)) and the program is |
| deactivated. |
| |
________________________________________________________________________

5. When the OUTPUT phrase is specified, the logical path for
destination, or the logical paths for all destinations, specified by
the contents of the data item referenced by data-name-5 (SYMBOLIC
DESTINATION) of the area referenced by cd-name are deactivated.

6. Literal-1 or the contents of the data-name referenced by identifier-1
will be matched with a password built into the system. The DISABLE
statement will be honored only if literal-1 or the contents of the
data item referenced by identifier-1 match the system password. When
literal-1 or the contents of the data item referenced by identifier-1
do not match the system password, the value of the STATUS KEY item in
the area referenced by cd-name is updated.

The MCS must be capable of handling a password of from one to ten
characters inclusive.

7. The MCS will insure that the execution of a DISABLE statement will
cause the logical disconnection at the earliest time the source or
destination is inactive. The execution of the DISABLE statement will
never cause the remaining portion of the message to be terminated
during transmission to or from a terminal.

The ENABLE Statement

Function

The ENABLE statement
notifies the MCS to allow data transfer between specified output queues
and destinations for output or between specified sources and input queues
for input.
________________________________________________________________________
|(ANS85) |
|The KEY phrase of the ENABLE statement is classed as an obsolete |
|element in the ANSI'85 standard and is scheduled to be deleted from |
|the next full revision of the ANSI Standard. |
________________________________________________________________________

General Format

Syntax Rules

3. Cd-name must reference an output CD when the OUTPUT phrase is
specified.

4. Literal-1 or the contents of the data item referenced by identifier-1
must be defined as alphanumeric.

General Rules

1. The ENABLE statement provides a logical connection between the MCS
and the specified sources or destinations. When this logical
connection is already in existence, or is to be handled by some other
means external to this program, the ENABLE statement is not required
in this program. The logical path for the transfer of data between
the COBOL programs and the MCS is not affected by the ENABLE
statement.

2. When the INPUT phrase with the optional word TERMINAL is specified,
the logical path between the source and all associated queues and sub
queues which are already enabled is activated. Only the contents of
the data item referenced by data-name-7 (SYMBOLIC SOURCE) of the area
referenced by cd-name are meaningful to the MCS.

3. When the INPUT phrase without the optional word TERMINAL is
specified, the logical paths for all of the sources associated with
the queue and sub-queues specified by the contents of data-name-1
(SYMBOLIC QUEUE) through data-name-4 (SYMBOLIC SUB-QUEUE-3) of the
area referenced by cd-name are activated.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|4. When the I-O TERMINAL phrase is specified, the logical path |
| between the source (as defined by the content of the data item |
| referenced by data-name-3 (SYMBOLIC TERMINAL)) and the program is |
| activated. |
| |
________________________________________________________________________

6. Literal-1 or the contents of the data item referenced by identifier-1
will be matched with a password built into the system. The ENABLE
statement will be honored only if literal-1 or the contents of the
data item referenced by identifier-1 match the system password. When
literal-1 or the contents of the data item referenced by identifier-1
do not match the system password, the value of the STATUS KEY item in
the area referenced by cd-name is updated.

The MCS must be capable of handling a password of from one to ten
characters inclusive.
________________________________________________________________________
|The PURGE Statement |
| |
|(ANS85) |
| |
|Function |
| |
|The PURGE statement eliminates from the MCS a partial message which |
|has been released by one or more SEND statements. |
| |
|General Format |
| |
| PURGE cd-name |
| |
|Syntax Rule |
| |
|CD-name must reference an output CD or input-output CD. |
| |
|General Rules |
| |
| |
| 1. Execution of a PURGE statement causes the MCS to eliminate any |
| partial message awaiting transmission to the destinations |
| specified in the CD referenced by cd-name. |
| |
| 2. Any message that has associated with it an EMI or EGI is not |
| affected by the execution of a PURGE statement. |
| |
| 3. The content of the status key data item and the content of the |
| error key data item (if applicable) of the area referenced by |
| cd-name-1 are updated by the MCS. (See "The Communication |
| Description - Complete Entry Skeleton" earlier in this |
| chapter.) |
________________________________________________________________________

The RECEIVE Statement

Function

The RECEIVE statement
makes available to the COBOL program a message, message segment, or a
portion of a message or segment, and pertinent information about that
data from a queue maintained by the MCS. The RECEIVE statement allows for
a specific imperative statement when no data is available.

General Format

Syntax Rule

Cd-name must reference an input CD or input-output CD. (ANS85)

General Rules

1. If cd-name references an input CD, the contents of the data items
specified by data-name-1 (SYMBOLIC QUEUE) through data-name-4
(SYMBOLIC SUB-QUEUE-3) of the area referenced by cd-name designate
the queue structure containing the message. (See "The
Communication Description - Complete Entry Skeleton" in this
chapter.)
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|2. If cd-name references an input-ouput CD, the contents of the |
| data items specified by data-name-3 (SYMBOLIC TERMINAL) of |
| the area referenced by cd-name designate the source of the |
| message. |
| |
________________________________________________________________________

3. The message, message segment, or portion of a message or segment is
transferred to the receiving character positions of the area
referenced by identifier-1 aligned to the left without space fill.

4. When, during the execution of a RECEIVE statement, the MCS makes data
available in the data item referenced by identifier-1, the NO DATA
phrase, if specified, is ignored and control is transferred to the
end of the RECEIVE statement
________________________________________________________________________
|(ANS85) |
|or, if the WITH DATA phrase is specified, to imperative-statement-2. |
|If control is transferred to imperative-statement-2, execution |
|continues according to the rules for each statement specified in |
|imperative-statement-2. If a procedure branching or conditional |
|statement which causes explicit transfer of control is executed, |
|control is transferred in accordance with the rules for that |
|statement; otherwise, upon completion of the execution of |
|imperative-statement-2, control is transferred to the end of the |
|RECEIVE statement. |
________________________________________________________________________

5. When, during the execution of a RECEIVE statement, the MCS does not
make data available in the data item referenced by identifier-1, one
of the three actions listed below will occur. The conditions under
which data is not made available are defined by the implementor.

a. If the NO DATA phrase is specified in the RECEIVE statement,
the RECEIVE operation is terminated with the indication that
imperative-statement-1. Execution then continues
according to the rules for each statement specified in
imperative-statement-1. If a procedure branching or
conditional statement which causes explicit transfer of
control is executed, control is transferred in accordance
with the rules for that statement; otherwise, upon completion
of the execution of imperative- statement-1, control is
transferred to the end of the RECEIVE statement and the WITH
DATA phrase, if specified, is ignored.(ANS85)

b. If the NO DATA phrase is not specified in the RECEIVE
statement, execution of the object program is suspended until
data is made available in the data item referenced by
identifier-1.

c. If one or more queues or subqueues (ANS85) are unknown to the
MCS, the appropriate status key code is stored and control is
then transferred as if data had been made available.

6. The data items identified by cd-name are appropriately updated by
the MCS at each execution of a RECEIVE statement.

7. A single execution of a RECEIVE statement never returns to the data
item referenced by identifier-1 more than a single message (when the
MESSAGE phrase is used) or a single segment (when the SEGMENT phrase
is used). However,the MCS does not pass any portion of a message to
the object program until the entire message is available in the
input queue, even if the SEGMENT phrase of the RECEIVE statement is
specified.

8. When the MESSAGE phrase is used, end of segment indicators are
ignored, and the following rules apply to the data transfer:

a. If a message is the same size as the area referenced by
identifier-1, the message is stored in the area referenced by
identifier-1.

b. If a message size is less than the area referenced by
identifier-1, the message is aligned to the leftmost
character position of the area referenced by identifier-1
with no space fill.

c. If a message size is greater than the area referenced by
identifier-1, the message fills the area referenced by
identifier-1 left to right starting with the leftmost
character of the message. The remainder of the message can
be transferred to the area referenced by identifier-1 with
subsequent RECEIVE statements referring to the same queue,
sub-queue ... . The remainder of the message, for the
purposes of applying rules 8a, 8b, and 8c, is treated as a
new message.

9. When the SEGMENT phrase is used, the following rules apply:

a. If a segment is the same size as the area referenced by
identifier-1, the segment is stored in the area referenced by
identifier-1.

b. If the segment size is less than the area referenced by
identifier-1, the segment is aligned to the leftmost
character position of the area referenced by identifier-1
with no space fill.

c. If a segment size is greater than the area referenced by
identifier-1, the segment fills the area referenced by
identifier-1 left to right starting with the leftmost
character of the segment. The remainder of the segment can
be transferred to the area referenced by identifier-1 with
subsequent RECEIVE statements calling out the same queue,
sub-queue ... . The remainder of the segment, for the
purposes of applying rules 9a, 9b and 9c, is treated as a new
segment.

d. If the text to be accessed by the RECEIVE statement has
associated with it an end of message indicator or end of
group indicator, the existence of an end of segment indicator
associated with the text is implied and the text is treated
as a message segment.

10. Once the execution of a RECEIVE statement has returned a portion of
a message, only subsequent execution of RECEIVE statements in that
run unit can cause the remaining portion of the message to be
returned.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|11. The END-RECEIVE phrase delimits the scope of the RECEIVE |
| statement. See Delimited Scope Statements in the chapter COBOL |
| Concepts. |
| |
________________________________________________________________________

The SEND Statement

Function

The SEND statement
causes a message, a message segment, or a portion of a message or segment
to be released to one or more output queues maintained by the MCS.

General Formats

Format 1

SEND cd-name FROM identifier-1

Format 2

Syntax Rules

1. Cd-name must reference an output CD or an input-output CD. (ANS85)

2. Identifier-2 must reference a one character integer without an
operational sign.

3. When identifier-3 is used in the ADVANCING phrase, it must be the
name of an elementary integer item.

4. When the mnemonic-name phrase is used, the name is identified with
a particular feature specified. The mnemonic-name is defined in
the SPECIAL-NAMES paragraph of the Environment Division.

5. Integer or the value of the data item referenced by identifier-3
can be zero.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|6. If identifier-1 is a function-identifier, it must reference an |
| alphanumeric function. |
| |
________________________________________________________________________

General Rules

Both Formats

1. When a receiving communication device (printer, display screen,
card punch, and so on) is oriented to a fixed line size:

a. Each message or message segment will begin at the leftmost
character position of the physical line.

b. A message or message segment that is smaller than the
physical line size is released so as to appear space-filled
to the right.

c. Excess characters of a message or message segment will not
be truncated. Characters will be packed to a size equal to
that of the physical line and then transmitted to the
device. The process continues on the next line with the
excess characters.

2. When a receiving communication device (paper tape punch, another
computer, and so on) is oriented to handle variable length
messages, each message or message segment will begin on the next
available character position of the communications device.

3. As part of the execution of a SEND statement, the MCS will
interpret the contents of the data item referenced by data-name-2
(TEXT LENGTH) of the area referenced by cd-name to the user's
indication of the number of leftmost character positions of the
data item referenced by identifier-1 from which data is to be
transferred.

If the contents of the data item referenced by data-name-2 (TEXT
LENGTH) of the area referenced by cd-name are zero, no characters
of the data item referenced by identifier-1 are transferred.

If the contents of the data item referenced by data-name-2 (TEXT
LENGTH) of the area referenced by cd-name are outside the range of
zero through the size of the data item referenced by identifier-1
inclusive, an error is indicated by the value of the data item
referenced by data-name-3 (STATUS KEY) of the area referenced by
cd-name, and no data is transferred. (See Table 9-1 for Status.)

4. As part of the execution of a SEND statement, the contents of the
data item referenced by data-name-3 (STATUS KEY) of the area
referenced by cd-name is updated by the MCS. (See the section "The
Communication Description - Complete Entry Skeleton" earlier
in this chapter.)

5. The effect of having special control characters within the
contents of the data item referenced by identifier-1 is undefined.

6. A single execution of a SEND statement for Format 1 releases only
a single portion of a message or of a message segment to the MCS.

A single execution of a SEND statement of Format 2 never releases
to the MCS more than a single message or a single message segment
as indicated by the contents of the data item referenced by
identifier-2 or by the specified indicator ESI, EMI or EGI.

However, the MCS will not transmit any portion of a message to a
communications device until the entire message is placed in the
output queue.

7. During the execution of the run unit, the disposition of a portion
of a message not terminated by an EMI or EGI or which has not been
eliminated by the execution of a PURGE statement (ANS85) is
undefined. However, the message does not logically exist for the
MCS and hence cannot be sent to a destination.

8. Once the execution of a SEND statement has released a portion of a
message to the MCS, only subsequent execution of SEND statements
in the same run unit can cause the remaining portion of the
message to be released.

Format 2

9. The contents of the data item referenced by identifier-2 indicate
that the contents of the data item referenced by identifier-1 are
to have associated with it an end of segment indicator, an end of
message indicator or an end of transmission indicator according to
the following schedule:

----------------------------------------------------------------------------------------------
| | | |
| If the contents of the data | then the contents of data | which means: |
| item referenced by | item referenced by | |
| identifier-2 associated with | identifier-1 have: | |
| it is: | | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| "0" | no indicator | no indicator |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| "1" | ESI | an end of segment indicator |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| "2" | EMI | an end of message indicator |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| "3" | EGI | an end of group indicator |
| | | |
----------------------------------------------------------------------------------------------
| |
| Any character other than "1",, "2" or "3" will be interpreted as "0" |
| |
----------------------------------------------------------------------------------------------
| |
| If the contents of the data item referenced by identifier-2 is other than "1" ,, "2" |
| or "3",, and identifier-1 is no specified,, then an error is indicated by the value |
| in the data item referenced by data-name-3 (STATUS KEY) or the area referenced by |
| cd-name,, and no data is transferred. |
| |
----------------------------------------------------------------------------------------------

10. The ESI
indicates to the MCS that the message segment is complete. The EMI
indicates to the MCS that the message is complete.

The EGI
indicates to the MCS that the group of messages is complete. The
Run-Time System specifies the interpretation that is given to the
EGI by the MCS.

The MCS will recognize these indications and establish whatever is
necessary to maintain group, message, and segment control.

11. The hierarchy of ending indicators is EGI, EMI,
ESI. An EGI need not be preceded by an ESI or EMI. An EMI need not
be preceded by an ESI.

12. The ADVANCING phrase allows control of the vertical positioning of
each message or message segment on a communication device where
vertical positioning is applicable. If vertical positioning is not
applicable on the device, the MCS will ignore the vertical
positioning specified or implied.

13. If identifier-2 is specified and the content of the data item
referenced by identifier-2 is zero, the ADVANCING phrase and the
REPLACING phrase (ANS85) if specified, are ignored by the MCS.

14. On a device where vertical positioning is applicable and the
ADVANCING phrase
is not specified, automatic advancing is provided to act as if the
user had specified AFTER ADVANCING 1 LINE.

15. If the ADVANCING phrase is implicitly or explicitly specified and
vertical positioning is applicable, the following rules apply:

a. If identifier-3 or integer is specified, characters
transmitted to the communication device will be repositioned
vertically downward the number of lines equal to the value
associated with the data item referenced by identifier-3 or
integer.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|b. If the value of the data item referenced by identifier-3 is |
| negative, the results are undefined. |
| |
________________________________________________________________________

c. If mnemonic-name is specified, characters transmitted to the
communication device will be positioned according to the rules
specified for that communication device.

d. If the BEFORE phrase
is used, the message or message segment is represented on the
communication device before vertical repositioning according to
general rules 15a. and 15b. (ANS85) above.

e. If the AFTER phrase
is used, the message or message segment is represented on the
communication device after vertical repositioning according to
general rules 15a. and 15b. (ANS85) above.

f. If PAGE is specified, characters transmitted to the
communication device will be represented on the device before or
after (depending upon the phrase used) the device is
repositioned to the next page. If PAGE is specified but page
has no meaning in conjunction with a specific device, then
advancing is provided to act as if the user had specified BEFORE
or AFTER (depending upon the phrase used) ADVANCING 1 LINE.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|16. On receiving character-imaging communication devices on which it |
| is possible to present two or more characters at the same |
| position, with the choice of superimposing second or subsequent |
| characters on characters already displayed at that position, |
| or displaying each character in the place of characters |
| previously transmitted to that line, the following rules |
| apply: |
| |
| |
| a. If the REPLACING phrase is specified, the characters |
| transmitted by the SEND statement replace all characters |
| which may have previously been transmitted to the same |
| line, beginning with the leftmost character position of |
| the line. |
| |
| b. If the REPLACING phrase is not specified, the characters |
| transmitted by the SEND statment, appear superimposed upon|
| the characters which may have previously been transmitted |
| to the same line, beginning with the leftmost character |
| position of the line. |
| |
|17. When a receiving communication device does not support the |
| replacement of characters, regardless of whether or not the |
| REPLACING phrase is specified, the characters transmitted by the |
| SEND statement appear superimposed upon the characters |
| which may have previously been transmitted to the same |
| line, beginning with the leftmost character position of the |
| line. |
| |
|18. When a receiving communication device does not support the |
| superimposing of two or more characters at athe same position, |
| regardless of whether or not the REPLACING phrase is specified, |
| the characters transmitted by the SEND statement replace all |
| characters which may have previously been transmitted to the same|
| line beginning with the leftmost character position of the |
| line. |
| |
________________________________________________________________________

MPE/iX 5.0 Documentation