PreviousReport Writer Debug ModuleNext"

Chapter 2: Communication

The Communication Module provides the ability to access, process, and create messages or portions thereof. It provides the ability to communicate through a Message Control System (MCS) with local and remote communication devices.

Support in this chapter that is marked as ANS85 is also sensitive to the COMS85 directive. See your COBOL system documentation for details of how or whether the Communication Module is supported at run time.

Although it is a part of the standard COBOL definition, this module is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

2.1 Data Division in the Communication Module

2.1.1 Communication Section

In a COBOL program the Communication Description entries (CD) represent the highest level of organization in the Communication Section. The COMMUNICATION SECTION header is followed by a CD entry consisting of a level indicator, a data-name and a series of independent clauses. These clauses indicate the queues and subqueues, the message date and time, the source, the text length, the status and end keys, and message count of input. They also specify the destination count, the text length, the status and error keys, and destinations for output.

For an input-output CD entry the clauses specify the message date, message time, symbolic terminal, text length, and key and status key.

The entry itself is terminated by a period. These record areas can be implicitly redefined by user-specified record description entries following the various CD clauses.

2.1.2 The Communication Description - Complete Entry Skeleton

The CD specifies the interface area between the MCS and a COBOL program.

General Formats

Format 1

Format 2

Format 3

Syntax Rules

All Formats
  1. A CD must appear only in the Communication Section .
Formats 1 and 3
  1. Within a single program, the INITIAL clause can be specified in only one CD. The INITIAL clause must not be used in a program that specifies the USING phrase of the PROCEDURE DIVISION Header. (See the section The PROCEDURE DIVISION Header in the chapter Program Definition in your Language Reference.)

  2. Except for the INITIAL clause, the optional clauses can be written in any order.

  3. If neither option in the format is specified, a level 01 data description entry must follow the CD entry. Either option can be followed by a level 01 data description entry.

  4. Record description entries following an input CD implicitly redefine this record and must describe a record of exactly 87 standard data format characters. Multiple redefinitions of this record are permitted; however, only the first redefinition can contain VALUE clauses. However, the MCS will always reference the record according to the data descriptions defined in General Rule 4.

  5. Data-name-1, data-name-2, ..., data-name-11 must be unique within the CD. Within this series, any data-name can be replaced by the reserved word FILLER.
Format 2
  1. The optional clauses can be written in any order.

  2. If none of the optional clauses of the CD is specified, a level 01 data description entry must follow the CD entry.

  3. Record descriptions following an output CD implicitly redefine this record. Multiple redefinitions of this record are permitted; however, only the first redefinition can contain VALUE clauses. The MCS will always reference the record according to the data descriptions defined in General Rule 18.

  4. Data-name-1, data-name-2, ..., data-name-5 must be unique in a CD.

  5. If the DESTINATION TABLE OCCURS clause is not specified, one ERROR KEY and one SYMBOLIC DESTINATION area is assumed. In this case, neither subscripting nor indexing is permitted when referencing these data items.

  6. If the DESTINATION TABLE OCCURS clause is specified, data-name-4 and data-name-5 can only be referred to by subscripting or indexing.

  7. The value of the data item referenced by data-name-1 and integer-2 is not restricted.
Format 3
  1. Record descriptions following an input-output CD implicitly redefine this record and must describe a record of exactly 33 standard data characters. Multiple redefinitions of this record are permitted; however, only the first redefinition may contain VALUE clauses. The MCS will always reference the record according to the data descriptions defined in General Rule 26.

General Rules

All Formats
  1. Table 2-1 indicates the possible contents of the data items referenced by data-name-10 for Format 1, data-name-3 for Format 2

    and by data-name-6 for Format 3

    at the completion of each statement shown. An " X" on a line in a statement column indicates that the associated code shown for that line is possible for that statement.

    Table 2-1: Communication Status Key Condition

    RECEIVE
      SEND
    input-output-cd
      SEND output-cd
      PURGE
      ACCEPT MESSAGE COUNT
      ENABLE INPUT
      ENABLE INPUT/I-O TERMINAL
      ENABLE OUTPUT
      DISABLE INPUT
      DISABLE INPUT/I-O TERMINAL
      DISABLE OUTPUT
      Status Key Value
    X X X X X X X X X X X 00 No error detected. Action completed.
        X X               10 One or more destinations are disabled. Action completed. (see General Rule 2.)
      X                   10 Destination disabled. No action taken.
              X X X X X X 15 Symbolic source, or one or more queues or destinations already disabled-enabled. (See General Rule 2.)
      X X X       X     X 20 One or more destinations unknown. Action completed for known destinations. (See General Rule 2).
    X       X X     X     20 One or more queues or subqueues unknown. No action taken.
    X           X     X   21 Symbolic source is unknown. No action taken.
        X X       X     X 30 Destination count invalid. No action taken.
              X X X X X X 40 Password invalid. No enabling/disabling action taken.
      X X                 50 Text length exceeds size of identifier-1.
      X X                 60 Portion requested to be sent has text length of zero or identifier-1 absent. No action taken.
        X                 65 Output queue capacity exceeded. (See General Rule 2.)
          X               70 One or more destinations do not have portions associated with them. Action completed for other destinations.
        X X   X   X X   X 80 A combination of at least two status key conditions 10, 15 and 20 have occurred. (See General Rule 2.)
                          9x Operating-System-defined status
Format 1
  1. The input CD information constitutes the communication between the MCS and the program as information about the message being handled. This information does not come from the terminal as part of the message.

  2. For each input CD, a record area of 87 contiguous standard data format characters is allocated. This record area is defined to the MCS as follows:
    1. The SYMBOLIC QUEUE clause defines data-name-1 as the name of an elementary alphanumeric data item of 12 characters occupying positions 1-12 in the record.

    2. The SYMBOLIC SUB-QUEUE-1 clause defines data-name-2 as the name of an elementary alphanumeric data item of 12 characters occupying positions 13-24 in the record.

    3. The SYMBOLIC SUB-QUEUE-2 clause defines data-name-3 as the name of an elementary alphanumeric data item of 12 characters occupying positions 25-36 in the record.

    4. The SYMBOLIC SUB-QUEUE-3 clause defines data-name-4 as the name of an elementary alphanumeric data item of 12 characters occupying positions 37-48 in the record.

    5. The MESSAGE DATE clause defines data-name-5 as the name of a data item whose implicit description is that of an integer of 6 digits without an operational sign occupying character positions 49-54 in the record.

    6. The MESSAGE TIME clause defines data-name-6 as the name of a data item whose implicit description is that of an integer of 8 digits without an operational sign occupying character positions 55-62 in the record.

    7. The SYMBOLIC SOURCE clause defines data-name-7 as the name of an elementary alphanumeric data item of 12 characters occupying positions 63-74 in the record.

    8. The TEXT LENGTH clause defines data-name-8 as the name of an elementary data item whose implicit description is that of an integer of 4 digits without an operational sign occupying character positions 75-78 in the record.

    9. The END KEY clause defines data-name-9 as the name of an elementary alphanumeric data item of 1 character occupying position 79 in the record.

    10. The STATUS KEY clause defines data-name-10 as the name of an elementary alphanumeric data item of 2 characters occupying positions 80-81 in the record.

    11. The MESSAGE COUNT clause defines data-name-11 as the name of an elementary data item whose implicit description is that of an integer of 6 digits without an operational sign occupying character positions 82-87 in the record.

    The second option can be used to replace the above clauses by a series of data-names which, taken in order, correspond to the data-names defined by these clauses.

    Use of either option results in a record whose implicit description is equivalent to the following: 

      Implicit Description                     Phrase

      01 data-name-0.
       02 data-name-1       PIC X(12).     SYMBOLIC QUEUE
       02 data-name-2       PIC X(12).     SYMBOLIC SUB-QUEUE-1
       02 data-name-3       PIC X(12).     SYMBOLIC SUB-QUEUE-2
       02 data-name-4       PIC X(12).     SYMBOLIC SUB-QUEUE-3
       02 data-name-5       PIC 9(06).     MESSAGE DATE
       02 data-name-6       PIC 9(08).     MESSAGE TIME
       02 data-name-7       PIC X(12).     SYMBOLIC SOURCE
       02 data-name-8       PIC 9(04).     TEXT LENGTH
       02 data-name-9       PIC X.         END KEY
       02 data-name-10      PIC XX.        STATUS KEY
       02 data-name-11      PIC 9(06).     MESSAGE COUNT

    In the above, the information under "Phrase" is for clarification and is not part of the description.

  3. The contents of the data items referenced by data-name-2, data-name-3, and data-name-4, when not being used must contain spaces.

  4. The data items referenced by data-name-1, data-name-2, data-name-3, and data-name-4 contain symbolic-names designating queues, sub-queues, ..., respectively. All symbolic-names must follow the rules for the formation of system-names, and must have been previously defined to the MCS.

  5. A RECEIVE statement causes the serial return of the "next" message or a portion of a message from the queue as specified by the entries in the CD.

    If during the execution of a RECEIVE statement, a message from a more specific source is needed, the contents of the data item referenced by data-name-1 can be made more specific by the use of the contents of the data items referenced by data-name-2, data-name-3, and in turn data-name-4. When a given level of the queue structure is specified, all higher levels must also be specified.

    If not all levels of the queue hierarchy are specified, the MCS determines the "next" message or portion of a message to be accessed.

    After the execution of a RECEIVE statement, the contents of the data items referenced by data-name-1 through data-name-4 will contain the symbolic-names of all the levels of the queue structure.

  6. Whenever a program is scheduled by the MCS to process a message, that program establishes a run unit and the symbolic-names of the queue structure that demanded this activity will be placed in the data items referenced by data-name-1 through data-name-4 of the CD associated with the INITIAL clause as applicable. In all other cases, the contents of the data items referenced by data-name-1 through data-name-4 of the CD associated with the INITIAL clause are initialized to spaces.

    The symbolic-names are inserted or the initialization to spaces is completed prior to the execution of the first Procedure Division statement.

    The execution of a subsequent RECEIVE statement naming the same contents of the data items referenced by data-name-1 through data-name-4 will return the actual message that caused the program to be scheduled. Only at that time will the remainder of the CD be updated.

  7. If the MCS attempts to schedule a program lacking an INITIAL clause, the results are undefined.

  8. Data-name-5 has the format "YYMMDD" (year, month, day). Its contents represent the date on which the MCS recognizes that the message is complete.

    The contents of the data item referenced by data-name-5 are only updated by the MCS as part of the execution of a RECEIVE statement.

  9. The contents of data-name-6 have the format "HHMMSSTT" (hours, minutes, seconds, hundredths of a second) and its contents represent the time at which the MCS recognizes that the message is complete.

    The contents of the data item referenced by data-name-6 are only updated by the MCS as part of the execution of the RECEIVE statement.

  10. During the execution of a RECEIVE statement, the MCS provides, in the data item referenced by data-name-7, the symbolic-name of the communications terminal that is the source of the message being transferred. This symbolic move must follow the rules for the formation of system names. However, if the symbolic-name of the communication terminal is not known to the MCS, the contents of the data item referenced by data-name-7 will contain spaces.

  11. The MCS indicates via the contents of the data item referenced by data-name-8 the number of character positions filled as a result of the execution of the RECEIVE statement. (See The RECEIVE Statement later in this chapter.)

  12. The contents of the data item referenced by data-name-9 are set only by the MCS as part of the execution of a RECEIVE statement according to the following rules:
    1. When the RECEIVE MESSAGE phrase is specified, then data-name-9 is set to one of the following:
      • If an end of group has been detected, the contents of the data item referenced by data-name-9 are set to 3;

      • If an end of message has been detected, the contents of the data item referenced by data-name-9 are set to 2;

      • If less than a message has been detected, the contents of the data item referenced by data-name-9 are set to 0.

    2. When the RECEIVE SEGMENT phrase is specified, data-name-9 is set to one of the following:
      • If an end of group has been detected, the contents of the data item referenced by data-name-9 are set to 3.

      • If an end of message has been detected, the contents of the data item referenced by data-name-9 are set to 2.

      • If an end of segment has been detected, the contents of the data item referenced by data-name-9 are set to 1.

      • If less than a message segment is transferred, the contents of the data item referenced by data-name-9 are set to 0.

    3. When more than one of the above conditions is satisfied simultaneously, the rule first satisfied in the order listed determines the contents of the data item referenced by data-name-9.

  13. The contents of the data item referenced by data-name-10 indicate the status condition of the previously executed RECEIVE, ACCEPT MESSAGE COUNT, ENABLE INPUT, or DISABLE INPUT statements.

    The actual association between the contents of the data item referenced by data-name-10 and the status condition itself is defined in Table 2-1.

  14. The contents of the data item referenced by data-name-11 indicate the number of messages that exist in a queue, sub-queue-1, ... . The MCS updates the contents of the data item referenced by data-name-11 only as part of the execution of an ACCEPT statement with the COUNT phrase .
Format 2
  1. The nature of the output CD information is such that it is not sent to the terminal, but constitutes the communication between the program and the MCS as information about the message being handled.

  2. For each output CD, a record area of contiguous standard data format characters is allocated according to the following formula: (10 plus 13 times integer-2).
    1. The DESTINATION COUNT clause defines data-name-1 as the name of a data item whose implicit description is that of an integer without an operational sign occupying character positions 1-4 in the record.

    2. The TEXT LENGTH clause defines data-name-2 as the name of an elementary data item whose implicit description is that of an integer of 4 digits without an operational sign occupying character positions 5-8 in the record.

    3. The STATUS KEY clause defines data-name-3 to be an elementary alphanumeric data item of 2 characters occupying positions 9-10 in the record.

    4. Character positions 11-23 and every set of 13 characters thereafter will form table items of the following description:

      • The ERROR KEY clause defines data-name-4 as the name of an elementary alphanumeric data item of 1 character.

      • The SYMBOLIC DESTINATION clause defines data-name-5 as the name of an elementary alphanumeric data item of 12 characters.

    Use of the above clauses results in a record whose implicit description is equivalent to the following: 

      Implicit Description                     Phrase

     01 data-name-0.
     02 data-name-1      PIC 9(04).        DESTINATION COUNT
     02 data-name-2      PIC 9(04).        TEXT LENGTH
     02 data-name-3      PIC XX.           STATUS KEY
     02 data-name OCCURS integer-2 TIMES.  DESTINATION TABLE
         03 data-name-4  PIC X.            ERROR KEY
         03 data-name-5  PIC X(12).        SYMBOLIC DESTINATION

    In the above, the information under "Phrase" is for clarification and is not part of the description.

  3. During the execution of a SEND, ENABLE OUTPUT, or DISABLE OUTPUT statement, the contents of the data item referenced by data-name-1 will indicate to the MCS the number of symbolic destinations that are to be used from the area referenced by data-name-5.

    The MCS finds the first symbolic destination in the first occurrence of the area referenced by data-name-5, the second symbolic destination in the second occurrence of the area referenced by data-name-5 ... , up to and including the occurrence of the area referenced by data-name-5 indicated by the contents of data-name-1.

    If during the execution of a SEND, ENABLE OUTPUT, or DISABLE OUTPUT statement the value of the data item referenced by data-name-1 is outside the range of 1 through integer-2, an error condition is indicated and the execution of the SEND, ENABLE OUTPUT, or DISABLE OUTPUT statement is terminated.

  4. It is the responsibility of the user to insure that the value of the data item referenced by data-name-1 is valid at the time of execution of the SEND, ENABLE OUTPUT, or DISABLE OUTPUT statement.

  5. As part of the execution of a SEND statement, the MCS will interpret the contents of the data item referenced by data-name-2 to be the user's indication of the number of leftmost character positions of the data item referenced by the associated SEND identifier from which data is to be transferred. (See The SEND Statement later in this chapter.)

  6. Each occurrence of the data item referenced by data-name-5 contains a symbolic destination previously known to the MCS. These symbolic destination-names must follow the rules for the formation of system-names.

  7. The contents of the data item referenced by data-name-3 indicate the status condition of the previously executed SEND, ENABLE OUTPUT or DISABLE OUTPUT statement.

    The actual association between the contents of the data item referenced by data-name-3 and the status condition itself is defined in Table 2-1.

  8. If, during the execution of a SEND, an ENABLE OUTPUT, or a DISABLE OUTPUT statement, the MCS determines that any specified destination is unknown, the contents of the data item referenced by data-name-3 and all occurrences of the data items referenced by data-name-4 are updated.

    The contents of the data item referenced by data-name-4 when equal to 1 indicate that the associated value in the area referenced by data-name-5 has not been previously defined to the MCS. Otherwise, the contents of the data item referenced by data-name-4 are set to zero.

Format 2
  1. Table 2-2 indicates the possible content of the data item referenced by data-name-4 at the completion of each statement shown. An "X" on a line in a statement column indicates that the associated error key value shown for that line is possible for that statement.

    Table 2-2: Error Key Values

    SEND
      PURGE
      ENABLE OUTPUT
      DISABLE OUTPUT
      Error Key Value
    X X X X 0 No error.
    X X X X 1 Symbolic destination unknown.
    X X     2 Symbolic destination disabled.
      X     4 No partial message with referenced symbolic destination.
        X X 5 Symbolic destination already enabled/disabled.
    X       6 Output queue capacity exceeded.
            7-9 Reserved for future use.
    A-Z Operating-System-defined condition.
Format 3

  1. The input-output CD information constitutes the communication between the MCS and the program about the message being handled. This information does not come from the terminal as part of the message.

  2. For each input-output CD, a record area of 33 contiguous character positions is allocated. This record area is defined to the MCS as follows:
    1. The MESSAGE DATE clause defines data-name-1 as the name of a data item whose implicit description is that of an integer of 6 digits, without an operational sign, occupying positions 1-6 in the record.

    2. The MESSAGE TIME clause defines data-name-2 as the name of a data item whose implicit description is that of an integer of 8 digits, without an operational sign, occupying positions 7-14 in the record.

    3. The SYMBOLIC TERMINAL clause defines data-name-3 as the name of an elementary alphanumeric data item of 12 characters occupying positions 15-26 in the record.

    4. The TEXT LENGTH clause defines data-name-4 as the name of an elementary data item whose implicit description is that of an integer of 4 digits, without an operational sign, occupying positions 27-30 in the record.

    5. The END KEY clause defines data-name-5 as the name of an elementary alphanumeric data item of 1 character occupying position 31 in the record.

    6. The STATUS KEY clause defines data-name-6 as the name of an elementary alphanumeric data item of 2 characters occupying positions 32 and 33 in the record.

    The second option may be used to replace the above clauses by a series of data-names which, taken in order, correspond to the data-names defined by these clauses.

    Use of either option results in a record whose implicit description is equivalent to the following: 

      Implicit Description                     Phrase

     01 data-name-0.
     02 data-name-1  PIC 9(6).             MESSAGE DATE
     02 data-name-2  PIC 9(8).             MESSAGE TIME
     02 data-name-3  PIC X(12).            SYMBOLIC TERMINAL
     02 data-name-4  PIC 9(4).             TEXT LENGTH
     02 data-name-5  PIC X.                END KEY
     02 data-name-6  PIC XX.               STATUS KEY

    Note that in the above, the information under `COMMENT' is for clarification and is not part of the data description.

  3. When a program is scheduled by the MCS to process a message, the first RECEIVE statement referencing the input-output CD with the INITIAL clause returns the actual message that caused the program to be scheduled.

  4. Data-name-1 has the format "YYMMDD" (year, month, day). Its content represents the date on which the MCS recognizes that the message is complete.

    The content of the data item referenced by data-name-1 is updated only by the MCS as part of the execution of a RECEIVE statement.

  5. Data-name-2 has the format "HHMMSSTT" (hours, minutes, seconds, hundredths of a second) and its content represents the time at which the MCS recognizes that the message is complete.

    The content of the data item referenced by data-name-2 is updated only by the MCS as part of the execution of the RECEIVE statement.

  6. Whenever a program is scheduled by the MCS to process a message, that program establishes a run unit, and the symbolic name of the communication terminal that is the source of the message that invoked this program, is placed in the data item referenced by data-name-3 of the input-output CD associated with the INITIAL clause as applicable. This symbolic name must follow the rules for the formation of system-names.

    In all other cases, the content of the data item referenced by data-name-3 of the input-output CD associated with the INITIAL clause is initialized to spaces.

    The symbolic name is inserted, or the initialization to spaces is completed, prior to the execution of the first Procedure Division statement.

  7. If the MCS attempts to schedule a program lacking an INI TIAL clause, the results are undefined.

  8. When the INITIAL clause is specified for an input-output CD and the program is scheduled by the MCS, the content of the data item referenced by data-name-3 must not be changed by the program. If this content is changed, the execution of any statement referencing cd-name-1 is unsuccessful, and the data item referenced by data-name-6 is set to indicate unknown source or destination, as applicable. (See General Rule 1.)

  9. For an input-output CD without the INITIAL clause, or for an input-output CD with the INITIAL clause when the program is not scheduled by the MCS, the program must specify the symbolic name of the source or destination in data-name-3 prior to the execution of the first statement referencing cd-name-1.

    After executing the first statement referencing cd-name-1, the content of the data item referenced by data-name-3 must not be changed by the program. If this content is changed, the execution of any statement referencing cd-name-1 is unsuccessful, and the data item referenced by data-name-6 is set to indicate unknown source or destination, as applicable. (See General Rule 1.)

  10. The MCS indicates, through the content of the data item referenced by data-name-4, the number of character positions filled as a result of the execution of the RECEIVE statement. See the section The RECEIVE Statement later in this chapter.

    As part of the execution of a SEND statement, the MCS interprets the content of the data item referenced by data-name-4 as an indication of the number of leftmost character positions of the data item referenced by the associated SEND identifier from which data is transferred. See the section The SEND Statement later in this chapter.

  11. The content of the data item referenced by data-name-5 is set only by the MCS as part of the execution of a RECEIVE statement according to the following rules:
    1. When the RECEIVE MESSAGE phrase is specified:

      • If an end of group has been detected, the content of the data item referenced by data-name-5 is set to 3.

      • If an end of message has been detected, the content of the data item referenced by data-name-5 is set to 2.

      • If less than a message is transferred, the content of the data item referenced by data-name-5 is set to 0.

    2. When the RECEIVE SEGMENT phrase is specified:

      • If an end of group has been detected, the content of the data item referenced by data-name-5 is set to 3.

      • If an end of message has been detected, the content of the data item referenced by data-name-5 is set to 2.

      • If an end of segment has been detected, the content of the data item referenced by data-name-5 is set to 1.

      • If less than a message segment is transferred, the content of the data item referenced by data-item-5 is set to 0.

    3. When more than one of the conditions is satisfied simultaneously, the rule first satisfied in the order listed determines the content of the data item ref erenced bydata-name-5.

  12. The content of the data item referenced by data-name-6 indicates the status condition of the previously executed DISABLE, ENABLE, PURGE, RECEIVE, or SEND statement.

    The actual association between the content of the data item referenced by data-name-6 and the status condition itself is defined in General Rule 1.

2.2 Procedure Division in the Communication Module

2.2.1 The ACCEPT MESSAGE COUNT Statement

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

General Format

Syntax Rules

  1. 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 section The Communication Description - Complete Entry Skeleton in this chapter.)

2.2.2 The DISABLE Statement

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.

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.

All dialects in this COBOL implementation fully support this syntax. The FLAGSTD directive can be used 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.

  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.

  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 between one and 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.

2.2.3 The ENABLE Statement

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.

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.

All dialects in this COBOL implementation fully support this syntax. The FLAGSTD directive can be used 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.

    Cd-name must reference an input-output CD when the I-O TERMINAL phrase is specified.

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

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

  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.

  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 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 between one and ten characters inclusive.

2.2.4 The PURGE Statement

The PURGE statement eliminates from the MCS a partial message which has been released by one or more SEND statements.

General Format

Syntax Rules

  1. 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 section The Communication Description - Complete Entry Skeleton earlier in this chapter.)

2.2.5 The RECEIVE Statement

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 Rules

  1. CD-name must reference an input CD

    or input-output CD.

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 section The Communication Description - Complete Entry Skeleton in this chapter.)

  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

    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.

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

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

    3. If one or more queues

      or subqueues

      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:

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

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

    3. 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:

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

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

    3. 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 General Rules 9a, 9b and 9c, is treated as a new segment.

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

  11. The END-RECEIVE phrase delimits the scope of the RECEIVE statement. See the section Delimited Scope Statements in the chapter Concepts of COBOL Program in your Language Reference.

2.2.6 The SEND Statement

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

Format 2

Syntax Rules

  1. Cd-name must reference an output CD

    or an input-output CD.

  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.

  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:

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

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

    3. 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 2-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 in 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

    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
  1. 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 item referenced by identifier-2 associated with it is: then the contents of data item referenced by identifier-1 have: which means:
    "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 617 , 627 or 637, and identifier-1 is not specified, 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.

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

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

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

  5. 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 if specified, are ignored by the MCS.

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

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

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

    2. If the value of the data item referenced by identifier-3 is negative, the results are undefined.

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

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

      above.

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

      above.

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

  8. 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:

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

    2. If the REPLACING phrase is not specified, the characters transmitted by the SEND statement, appear superimposed upon the characters whic h may have previously been transmitted to the same line, beginning with the leftmost character position of the line.

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

  10. When a receiving communication device does not support the superimposing of two or more characters at the 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.

Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousReport Writer Debug ModuleNext"