SEND MESSAGE (COBOL)

The SEND MESSAGE statement sends a message to another terminal or user, or to a group of terminals or users that is defined as a destination, during system generation. The SEND MESSAGE function does not employ the data dictionary message area. Instead, each message is placed in a queue, and sent to the appropriate terminal only when it is possible to do so without disrupting executing tasks. Typically, queued messages are sent to a terminal the next time the ENTER NEXT TASK CODE message is displayed.
idmscu
The SEND MESSAGE statement sends a message to another terminal or user, or to a group of terminals or users that is defined as a 
destination
, during system generation. The SEND MESSAGE function does not employ the data dictionary message area. Instead, each message is placed in a queue, and sent to the appropriate terminal only when it is possible to do so without disrupting executing tasks. Typically, queued messages are sent to a terminal the next time the ENTER NEXT TASK CODE message is displayed.
Syntax
►►─── SEND MESSAGE ─┬──────────┬──────────────────────────────────────────────►                     ├─ ONLY ◄ ─┤                     └─ ALWAYS ─┘  ►─── TO ─┬─ DEST ID 
destination-id
 ─┬────────────────────────────────────────►           ├─ USER ID 
user-id
 ────────┤           └─ LTERM ID 
lterm-id 
──────┘  ►─── FROM 
message-location 
─┬─ TO 
end-message-location
 ─┬─ . ────────────────►◄                              └─ LENGTH 
message-length 
───┘
Parameters
  • ONLY
    Sends the message immediately when the destination, user, or terminal is available, and does not queue the message for subsequent transmission when the destination, user, or terminal is not available. This value is the default. 
    If ONLY is specified with the DEST ID option and some, but not all, of a group of users or terminals in the destination are available, the message is sent to the available ones. The sender is not aware of any unsuccessful transmissions.
  • ALWAYS
    Sends the message immediately when the destination, user, or terminal is available, and queues the message for later transmission when the destination, user, or terminal is not available.
  • TO DEST ID 
    destination-id
    Specifies the destination ID of the message recipient. Specify the symbolic name of a user-defined field that contains the destination ID, or the ID itself enclosed in quotation marks. The destination must have been defined during system generation.
  • TO USER ID 
    user-id
     
    Specifies the user that receives the message.
    User-id
     is the symbolic name of a 32-byte user-defined field that contains the user ID. The specified user can be signed on to any terminal.
  • TO LTERM ID 
    lterm-id
    Specifies the logical terminal that receives the message. Specify the symbolic name of a user-defined field that contains the terminal ID, or the ID itself enclosed in quotation marks.
  • FROM 
    message-location
    Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the message text to send. Specify the symbolic name of a user-defined field.
  • TO 
    end-message-location
    Specifies the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the message text. Specify the symbolic name of a user-defined dummy byte field or a field containing a data item that is not associated with the message text.
  • LENGTH 
    message-length
    Defines the length of the message text in bytes. Specify the symbolic name of a user-defined field that contains the length, or the length itself expressed as a numeric constant.
Examples
The following examples illustrate the use of the SEND MESSAGE statement.
  • Example 1
    The following statement sends the message in the TERM-MESS field to the logical terminal KENNEDYA:
    SEND MESSAGE ALWAYS   TO LTERM ID 'KENNEDYA'   FROM TERM-MESS TO END-TERM-MESS.
  • Example 2
    The following statement sends the message in the TERM-MESS field to the user field:
    MOVE 'KYJOE2' to USER32.    SEND MESSAGE     TO USER ID USER32     FROM TERM-MESS TO END-TERM-MESS.
  • Example 3
    The following statement sends the message in the TERM-MESS field to the destination ALL:
    SEND MESSAGE   TO DEST ID 'ALL'   FROM TERM-MESS TO END-TERM-MESS.
Status Codes
After completion of the SEND MESSAGE function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome:
Status code
Meaning
0000
The request has been serviced successfully.
4907
An I/O error has occurred during processing.
4921
The specified message recipient has not been defined.
4931
The parameter list is invalid.
4932
The derived length of the specified message data area is zero or negative.
4934
The specified variable storage area that contains the message text is in the LINKAGE SECTION but is not an 01-level entry.
4938
The specified WORKING-STORAGE SECTION or LINKAGE SECTION entry has not been allocated. A GET STORAGE request must be issued.