$Wait
$Wait suspends 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.
- The 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.
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.
- 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.
- 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 SOUL 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.
See also
The ECB-related $functions are: