$Wait
Function
Suspend a user until an Event Control Block (ECB) is posted
Syntax
$WAIT(ECB-number [,'SWAP' | 'NOSWAP'] [,time-interval] | 'CPQZ' | 'QZSIG')
Where:
- ECB-number is a string with a numeric value from one to the NECBS parameter, which identifies the ECB upon which to wait. ECB-number can be expressed as a numeric, a literal, a %variable, or a field name. This is a user defined event. When these users are placed in a wait state, the wait type is 30.
- SWAP keyword specifies a swappable wait; this is the default. The NOSWAP keyword specifies a nonswappable wait. If you enter a keyword, enclose it in single quotation marks.
- time-interval specifies the maximum number of seconds to wait. A wait that is finished, because the time expired, is indicated by a return code 16.
- The CPQZ and QZSIG keywords are the named ECBs for extended quiesce, which are used by the NonStop/204 facility for independently run third-party backups. See the Rocket Model 204 System Manager's Guide for an explanation of the facility.
A time-interval may be from zero to 86400 and indicated as a number, %variable, or a string. A time-interval less than one is treated as no time-interval supplied with no time-out to happen.
If a time-interval is specified, the second argument, SWAP or NOSWAP, is activated. You can specify 'SWAP' or 'NOSWAP', or accept the default, SWAP, using the following syntax:
$WAIT(ECB-number,,time-interval)
The time-interval can be used as an argument to $WAIT to determine when an extended quiesce event starts; at that time the backup can be submitted. When these users are placed in a wait state, the wait type is 47.
CPQZ is posted internally at the beginning of each extended quiesce and unposted internally at the interval end.
QZSIG can be posted during the extended quiesce. It is unposted internally at the end of extended quiesce.
The $WAIT function applied to CPQZ and QZSIG are bumpable, swappable waits of type 47 for CPQZ and 48 for QZSIG. You cannot specify the SWAP or NOSWAP keywords or time-interval with the named ECBs.
Usage
You can use the $WAIT function to suspend a user, meaning: put that user into a wait state until the ECB is posted by another user with the $POST function. Users who have issued a $WAIT function call are bumpable and may be swappable depending on whether SWAP or NOSWAP was used in the $WAIT call.
Caution: Limit the use of the $WAIT function with the NOSWAP option to situations where only a small number of threads may use it. This will avoid having all servers occupied by users in a NOSWAP state and having no available server for a posting user to swap into.
Using the $WAIT function, you can put a User Language thread into a wait state. To perform third-party backups, the thread must wait for the extended quiesce of a checkpoint to start and then submit a backup job.
- For numbered ECBs, you can use the $POST, $UNPOST, and $WAIT functions to coordinate processing between threads.
- For the QZSIG ECB, you can use the $POST and $WAIT functions to signal and recognize the end of an extended quiesce for third-party backups.
- For the CPQZ ECB, you can use the $WAIT function to wait on the start of an extended quiesce.
The following return codes apply to the $WAIT function:
| Return code | Meaning |
|---|---|
| 0 | Success |
| 2 | Bad argument specified |
| 3 | NECBS parameter is not specified or is zero |
| 4 | The first argument is less than one or greater than the NECBS parameter |
| 5 | NUSERS = 1 |
| 6 | NOSWAP and NSERVS EQ 1 |
| 8 | No argument specified |
| 9 | Checkpointing inactive, if using extended quiesce ECBs, CPQZ or QZSIG |
| 11 | The CPQZ or QZSIG ECB is already posted |
| 12 | Invalid argument CPQZ or invalid argument following QZSIG |
| 13 | For QZSIG, the system is not in extended quiesce or already leaving extended quiesce |
| 15 | Time interval is not numeric or greater than 86,400 |
| 16 | $WAIT finished due to expired time interval |
| 17 | Second argument entered is not SWAP or NOSWAP |
When the ECB specified in the $WAIT call is posted, the waiting user will resume evaluation and may capture the post code with $STATUSD. See the following $WAIT example.
Example
The following code illustrates an interaction between User 1 and User 2. User 1 issues the following:
BEGIN %X=$ECBDSET(3,'THIS IS ECB 3') PAUSE 60 %X=$POST(3,5678) END
User 2 starting after the previous $ECBDSET, but before 60 seconds have elapsed:
BEGIN PRINT 'WAITING ON ECB 3' NP %X=$WAIT(3) PRINT 'ECB 3 HAS BEEN POSTED WITH POST CODE= ' WITH - $STATUSD END
User 2 will be suspended (WT=30) when the $WAIT call is evaluated and will resume processing when ECB number 3 is posted by User 1. $STATUSD will return the post code value = 5678.
If User 2 starts after 60 seconds have elapsed and the ECB number 3 has been posted, then User 2 will not wait, but will print the last post code for the ECB number 3.