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 IDdestination-id─┬────────────────────────────────────────► ├─ USER IDuser-id────────┤ └─ LTERM IDlterm-id──────┘ ►─── FROMmessage-location─┬─ TOend-message-location─┬─ . ────────────────►◄ └─ LENGTHmessage-length───┘
Parameters
- ONLYSends 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.
- ALWAYSSends 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 IDdestination-idSpecifies 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 IDuser-idSpecifies the user that receives the message.User-idis 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 IDlterm-idSpecifies 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.
- FROMmessage-locationSpecifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the message text to send. Specify the symbolic name of a user-defined field.
- TOend-message-locationSpecifies 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.
- LENGTHmessage-lengthDefines 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 1The 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 2The 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 3The 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. |