$Wait: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 1: Line 1:
<b>Function</b>
<var>$Wait</var> suspends a user until an Event Control Block (ECB) is posted.
<p>Suspend a user until an Event Control Block (ECB) is posted</p>
 
<b>Syntax</b>
==Syntax==
<p class="code">$Wait(ECB-number [,'SWAP' | 'NOSWAP']
<p class="code">$Wait(ECB-number [,'SWAP' | 'NOSWAP']
     [,time-interval] | 'CPQZ' | 'QZSIG')
     [,time-interval] | 'CPQZ' | 'QZSIG')
</p>
</p>
<p>Where:</p>
<p>
Where:</p>
<ul>
<ul>
<li>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.</li>
<li>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.</li>
</li>
 
<li>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.</li>
<li>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.</li>
</li>
 
<li>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.</li>
<li>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.
<p>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.</p>
<p>
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.</p>
<p>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:</p>
<p>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:</p>
<p class="code">$Wait(ECB-number,,time-interval)
<p class="code">$Wait(ECB-number,,time-interval)
Line 19: Line 20:
<p>The time-interval can be used as an argument to <var>$Wait</var> 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.</p>
<p>The time-interval can be used as an argument to <var>$Wait</var> 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.</p>
</li>
</li>
<li>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 <var class="product">Model&nbsp;204</var> System Manager's Guide for an explanation of the facility. </li>
 
</li>
<li>The CPQZ and QZSIG keywords are the named ECBs for extended quiesce, which are used by the [[System and media recovery#Media recovery NonStop/204|NonStop/204 facility]] for independently-run third-party backups.
<ul>
<li>CPQZ is posted internally at the beginning of each extended quiesce and unposted internally at the interval end.</li>
<li>QZSIG can be posted during the extended quiesce. It is unposted internally at the end of extended quiesce.</li>
<li>The <var>$Wait</var> 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.</li>
</ul></li>
</ul>
</ul>
<p>CPQZ is posted internally at the beginning of each extended quiesce and unposted internally at the interval end.</p>
 
<p>QZSIG can be posted during the extended quiesce. It is unposted internally at the end of extended quiesce.</p>
==Usage==
<p>The <var>$Wait</var> 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.</p>
<p>
<b>Usage</b>
You can use the <var>$Wait</var> function to suspend a user, meaning: put that user into a wait state until the ECB is posted by another user with the <var>$Post</var> function. Users who have issued a <var>$Wait</var> function call are bumpable and may be swappable depending on whether SWAP or NOSWAP was used in the <var>$Wait</var> call. </p>
<p>You can use the <var>$Wait</var> 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 <var>$Wait</var> function call are bumpable and may be swappable depending on whether SWAP or NOSWAP was used in the <var>$Wait</var> call. </p>
<p class="note"><b>Caution:</b> Limit the use of the <var>$Wait</var> 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.</p>
<p class="note"><b>Caution:</b> Limit the use of the <var>$Wait</var> 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.</p>
<p>Using the <var>$Wait</var> 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. </p>
<p>
Using the <var>$Wait</var> 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. </p>
<ul>
<ul>
<li>For numbered ECBs, you can use the $POST, $UNPOST, and <var>$Wait</var> functions to coordinate processing between threads.</li>
<li>For numbered ECBs, you can use the <var>$Post</var>, <var>$UnPost</var>, and <var>$Wait</var> functions to coordinate processing between threads.</li>
</li>
 
<li>For the QZSIG ECB, you can use the $POST and <var>$Wait</var> functions to signal and recognize the end of an extended quiesce for third-party backups.</li>
<li>For the QZSIG ECB, you can use the <var>$Post</var> and <var>$Wait</var> functions to signal and recognize the end of an extended quiesce for third-party backups.</li>
</li>
 
<li>For the CPQZ ECB, you can use the <var>$Wait</var> function to wait on the start of an extended quiesce.</li>
<li>For the CPQZ ECB, you can use the <var>$Wait</var> function to wait on the start of an extended quiesce.</li>
</li>
</ul>
</ul>
<p>The following return codes apply to the <var>$Wait</var> function:</p>
<p>
The following return codes apply to the <var>$Wait</var> function:</p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 43: Line 49:
<th>Meaning</th>
<th>Meaning</th>
</tr>
</tr>
<tr>
<tr>
<td align="right">0 </td>
<td align="right">0 </td>
<td>Success</td>
<td>Success</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">2 </td>
<td align="right">2 </td>
<td>Bad argument specified</td>
<td>Bad argument specified</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">3 </td>
<td align="right">3 </td>
<td>NECBS parameter is not specified or is zero</td>
<td>NECBS parameter is not specified or is zero</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">4 </td>
<td align="right">4 </td>
<td>The first argument is less than one or greater than the NECBS parameter</td>
<td>The first argument is less than one or greater than the NECBS parameter</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">5 </td>
<td align="right">5 </td>
<td>NUSERS = 1</td>
<td>NUSERS = 1</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">6 </td>
<td align="right">6 </td>
<td>NOSWAP and NSERVS EQ 1</td>
<td>NOSWAP and NSERVS EQ 1</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">8 </td>
<td align="right">8 </td>
<td>No argument specified</td>
<td>No argument specified</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">9</td>
<td align="right">9</td>
<td>Checkpointing inactive, if using extended quiesce ECBs, CPQZ or QZSIG</td>
<td>Checkpointing inactive, if using extended quiesce ECBs, CPQZ or QZSIG</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">11 </td>
<td align="right">11 </td>
<td>The CPQZ or QZSIG ECB is already posted</td>
<td>The CPQZ or QZSIG ECB is already posted</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">12</td>
<td align="right">12</td>
<td>Invalid argument CPQZ or invalid argument following QZSIG</td>
<td>Invalid argument CPQZ or invalid argument following QZSIG</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">13</td>
<td align="right">13</td>
<td>For QZSIG, the system is not in extended quiesce or already leaving extended quiesce</td>
<td>For QZSIG, the system is not in extended quiesce or already leaving extended quiesce</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">15</td>
<td align="right">15</td>
<td>Time interval is not numeric or greater than 86,400</td>
<td>Time interval is not numeric or greater than 86,400</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">16</td>
<td align="right">16</td>
<td><var>$Wait</var> finished due to expired time interval</td>
<td><var>$Wait</var> finished due to expired time interval</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">17</td>
<td align="right">17</td>
Line 100: Line 120:
</tr>
</tr>
</table>
</table>
<p>When the ECB specified in the <var>$Wait</var> call is posted, the waiting user will resume evaluation and may capture the post code with $STATUSD. See the following <var>$Wait</var> example. </p>
<p>
<b>Example</b>
When the ECB specified in the <var>$Wait</var> call is posted, the waiting user will resume evaluation and may capture the post code with <var>$StatusD</var>. See the following <var>$Wait</var> example. </p>
 
==Example==
<p>The following code illustrates an interaction between User 1 and User 2. User 1 issues the following:</p>
<p>The following code illustrates an interaction between User 1 and User 2. User 1 issues the following:</p>
<p class="code">BEGIN
<p class="code">BEGIN
Line 109: Line 131:
END
END
</p>
</p>
<p>User 2 starting after the previous $ECBDSET, but before 60 seconds have elapsed:</p>
<p>User 2 starting after the previous <var>$EcbDset</var>, but before 60 seconds have elapsed:</p>
<p class="code">BEGIN
<p class="code">BEGIN
PRINT 'WAITING ON ECB 3'
PRINT 'WAITING ON ECB 3'
NP
NP
%X=$WAIT(3)
%X=$WAIT(3)
PRINT 'ECB 3 HAS BEEN POSTED WITH POST CODE= ' WITH -
PRINT 'ECB 3 HAS BEEN POSTED WITH POST CODE= ' WITH $STATUSD
      $STATUSD
END
END
</p>
</p>
<p>User 2 will be suspended (WT=30) when the <var>$Wait</var> call is evaluated and will resume processing when ECB number 3 is posted by User 1. $STATUSD will return the post code value = 5678. </p>
<p>User 2 will be suspended (WT=30) when the <var>$Wait</var> call is evaluated and will resume processing when ECB number 3 is posted by User 1. <var>$StatusD</var> will return the post code value = 5678. </p>
<p>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.</p>
<p>
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.</p>
 
[[Category:SOUL $functions]]
[[Category:SOUL $functions]]

Revision as of 20:02, 8 September 2014

$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.
  • 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.