WAIT Statement

The WAIT statement synchronizes operations between threads.

General Format

WAIT FOR { THREAD thread-ID         }
         { LAST THREAD              }
         { ANY THREAD               }

Remaining phrases are optional, can appear in any order.

{ BEFORE TIME timeout }
{ TEST ONLY }

THREAD IN thread-2

SIZE IN size-item

STATUS IN status-item
[ ON EXCEPTION statement-1 ]

[ NOT ON EXCEPTION statement-2 ]

[ END-WAIT ]

Syntax Rules

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

General Rules

  1. The WAIT statement waits for a thread to terminate or send a message. The thread waited on is determined as follows:
    1. FOR THREAD thread-ID specifies the thread identified by thread-ID.
    2. FOR LAST THREAD specifies the last thread. See Thread Fundamentals in the ACUCOBOL-GT User's Guide for a discussion of the last thread.
    3. FOR ANY THREAD specifies all threads. The first one to terminate or send a message satisfies the WAIT statement.
  2. If a message is available when the WAIT statement executes, then WAIT statement finishes immediately.
  3. When BEFORE TIME is specified, the WAIT statement will time-out after the specified (timeout) number of hundredths of seconds. If the WAIT statement times out before receiving a message, it terminates with an exception condition and it does not modify thread-2 or size-item. If timeout is zero, then the WAIT statement times-out immediately if a message is not available. Specifying TEST ONLY is equivalent to specifying a timeout value of zero.
  4. If the thread waited for does not exist or terminates before sending a message, then the WAIT statement terminates with an exception condition and does not modify size-item. Such a condition is reflected in the status code placed in status-item. Note that the test occurs before the time-out test in the case that timeout is zero or TEST ONLY is specified.
  5. The WAIT statement places the thread ID of the sending or terminating 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).
  7. The status of the WAIT statement is placed in status-item. The following values are possible (these approximate the standard file status codes):
    "00" Success - message received
    "10" Exception - thread does not exist or terminated
    "99" Exception - timed-out
  8. If the WAIT statement is successful (as indicated in rule 7), it executes statement-1. If an exception condition exists, it executes statement-2 instead.