RECEIVE Statement

The RECEIVE statement retrieves messages sent by other threads.

General Format

RECEIVE dest-item FROM { THREAD thread-1 }
                       { LAST THREAD     }
                       { ANY THREAD      }

Remaining phrases are optional, can appear in any order. 

{ BEFORE TIME timeout }
{ WITH NO WAIT        }

THREAD IN thread-2

SIZE   IN size-item

STATUS IN status-item

[ ON EXCEPTION statement-1 ]

[ NOT ON EXCEPTION statement-2 ]

[ END-RECEIVE ]

Syntax Rules

  1. dest-item is any data item.
  2. thread-1 and thread-2 are usage HANDLE or HANDLE OF THREAD data items. thread-2 may not be indexed or reference modified.
  3. timeout is a numeric literal or data item.
  4. size-item is a numeric data item. It may not be indexed or reference modified.
  5. status-item is a two-character group item, PIC XX, or PIC 99 data item. It may not be indexed or reference modified.
  6. statement-1 and statement-2 are any imperative statements.

General Rules

  1. The RECEIVE statement returns the next available message into dest-item. Only messages from the proper source are allowed as follows:
    1. FROM THREAD thread-1 specifies that only messages from the thread identified by thread-1 are allowed.
    2. FROM LAST THREAD specifies that only messages from the last thread are allowed. See Thread Fundamentals for more information.
    3. FROM ANY THREAD specifies that all messages are allowed.
  2. Messages are received in the order sent. If a message is available when the RECEIVE statement executes, the RECEIVE statement finishes immediately. Otherwise, the RECEIVE statement waits for a message to become available. This provides an efficient method for threads to synchronize with each other.
  3. When BEFORE TIME is specified, the RECEIVE statement will time out after the specified (timeout) number of hundredths of seconds. If the RECEIVE statement times out before receiving a message, it terminates with an exception condition and does not modify dest-item, thread-2, or size-item. If timeout is zero, then the RECEIVE statement times out immediately if a message is not available. Specifying NO WAIT is equivalent to specifying a timeout value of zero.
  4. If no message is available and the sending thread (as specified by rule1 above) does not exist or terminates before sending a message, the RECEIVE statement terminates with an exception condition and does not modify dest-item or size-item. This condition is reflected in the status placed in status-item. Note that the test occurs before the time-out test in the case that timeout is zero or NO WAIT is specified.
  5. The RECEIVE statement places the thread ID of the sending thread in thread-2.
  6. The size of the message sent is placed in size-item. The size is expressed in standard character positions (bytes). If the message is longer than dest-item, it is truncated. If the message is shorter than dest-item, it is padded on the right with spaces.
  7. The status of the RECEIVE statement is placed in status-item. The following values are possible (these approximate the standard file status codes):
    "00" Success - message received
    "04" Success - message received, but it was truncated
    "10" Exception - sending thread does not exist or terminated
    "99" Exception - timed out
  8. If the RECEIVE statement is successful (as indicated in rule 7 above), statement-2 executes. If an exception condition is returned, statement-1 executes.
Parent topic: Procedure Division Statements