$Post: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Admin moved page $POST to $Post without leaving a redirect: caps in title)
m (add italics)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<b>Function</b>
<var>$Post</var> indicates that some event has occurred. The thread(s) waiting on the Event Control Block (ECB) can resume processing.
<p>Indicates that some event has occurred. The thread(s) waiting on the Event Control Block (ECB) can resume processing.</p>
 
<b>Syntax</b>
==Syntax==
<p class="code">$POST({ECB-number[,post-code][,string] | 'QZSIG'})
<p class="code">$Post({<span class="term">ECB-number</span>[,<span class="term">post-code</span>][,<span class="term">string</span>] | '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 that identifies the ECB to be posted. The ECB-number can be expressed as a numeric literal, a %variable, or a field name.</li>
<li><var class="term">ECB-number</var> is a string with a numeric value from one to the value of the <var>[[NECBS parameter|NECBS]]</var> parameter that identifies the ECB to be posted. The ECB-number can be expressed as a numeric literal, a %variable, or a field name. </li>
</li>
 
<li>post-code is a numeric value between zero and 16,777,215. You can use this optional argument for whatever you wish. If omitted, a default post code of zero is used.</li>
<li><var class="term">post-code</var> is a numeric value between zero and 16,777,215. You can use this optional argument for whatever you wish. If omitted, a default post code of zero is used.
<p>The post code is accessible using the $ECBTEST function followed by the $STATUSD function for the specified posted ECB.</p>
<p>The post code is accessible using the <var>$EcbTest</var> function followed by the <var>$StatusD</var> function for the specified posted ECB.</p>
<p>Once set, unless explicitly reset to zero, post codes persist whether or not the ECB is posted.</p>
<p>Once set, unless explicitly reset to zero, post codes persist whether or not the ECB is posted.</p>
</li>
</li>
<li>string can be up to 255 bytes long. It can be a numeric, a literal enclosed in quotation marks, a %variable, or a field name. </li>
 
<p>String data is accessible using the $ECBDGET function for the specified ECB.</p>
<li><var class="term">string</var> can be up to 255 bytes long. It can be a numeric, a literal enclosed in quotation marks, a %variable, or a field name.  
<p>Once set, unless explicitly reset to null, data strings persist whether or not the ECB is posted. Depending on the sequence, data strings can be changed by either the $POST or $ECBDSET functions.</p>
<p>String data is accessible using the <var>$EcbDGet</var> function for the specified ECB.</p>
</li>
<p>Once set, unless explicitly reset to null, data strings persist whether or not the ECB is posted. Depending on the sequence, data strings can be changed by either the <var>$Post</var> or <var>$EcbDSet</var> functions.</p></li>
 
<li>QZSIG is an extended quiesce named ECB. To use it, you need not set the NECBS parameter. QZSIG can be expressed as a literal, a %variable, or a field name. Although QZSIG can be posted, it cannot be unposted. Unposting is handled internally at the end of the extended quiesce. You cannot specify a post code or a string for QZSIG.</li>
<li>QZSIG is an extended quiesce named ECB. To use it, you need not set the NECBS parameter. QZSIG can be expressed as a literal, a %variable, or a field name. Although QZSIG can be posted, it cannot be unposted. Unposting is handled internally at the end of the extended quiesce. You cannot specify a post code or a string for QZSIG.</li>
</li>
</ul>
</ul>
<b>Usage</b>
 
<p>The $POST function posts a specified ECB with an optional post code and an optional associated string. Only an unposted ECB may be posted. If an ECB is already posted, the posted state is indicated by return code 14. The ECB contents and associated string do not change. Any other thread waiting ($WAIT) on the specified ECB becomes eligible to resume processing.</p>
==Usage==
<p>Use the $POST, $UNPOST, and $WAIT functions to coordinate processing between threads. </p>
<p>
<p>The following return codes apply to the $POST function</p>
The <var>$Post</var> function posts a specified ECB with an optional post code and an optional associated string. Only an unposted ECB may be posted. If an ECB is already posted, the posted state is indicated by return code 14. The ECB contents and associated string do not change. Any other thread waiting (<var>[[$Wait]]</var>) on the specified ECB becomes eligible to resume processing.</p>
<p>
Use the <var>$Post</var>, <var>[[$UnPost]]</var>, and <var>$Wait</var> functions to coordinate processing between threads. </p>
<p>
The following return codes apply to the <var>$Post</var> function</p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 28: Line 32:
<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><var>[[NECBS and NOECBS parameters|NECBS]]</var> 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 <var>NECBS</var> parameter</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">5 </td>
<td align="right">5 </td>
<td>NUSERS = 1</td>
<td><var>[[NUSERS parameter|NUSERS]]</var> is 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</td>
<td>Checkpointing inactive</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">10 </td>
<td align="right">10 </td>
<td>Post code out of range, 0 to 16,777,215</td>
<td>Post code out of range, 0 to 16,777,215</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">11</td>
<td align="right">11</td>
<td>The QZSIG ECB is already posted</td>
<td>The QZSIG ECB is already posted</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">12</td>
<td align="right">12</td>
<td>Invalid argument CPQZ specified or invalid argument following QZSIG</td>
<td>Invalid argument CPQZ specified or invalid argument following QZSIG</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">13</td>
<td align="right">13</td>
<td>Cannot be issued outside of extended quiesce</td>
<td>Cannot be issued outside of extended quiesce</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">14</td>
<td align="right">14</td>
Line 77: Line 93:
</tr>
</tr>
</table>
</table>
<b>Example</b>
 
==Example==
<p>On Thread A</p>
<p>On Thread A</p>
<p class="code">BEGIN
<p class="code">BEGIN
Line 90: Line 107:
END
END
</p>
</p>
<p>In the previous code, the $UNPOST function on Thread A marks the ECB specified as unposted. Then, Thread A waits at the $WAIT(1) until another thread issues a $POST(1,nnnn). Thread B posts the ECB number one with $POST(1,32), at which point Thread A resumes evaluation with PRINT $STATUSD and prints the post code of 32.</p>
<p>
In the previous code, the <var>$UnPost</var> function on Thread A marks the ECB specified as unposted. Then, Thread A waits at the <code>$WAIT(1)</code> until another thread issues a <code>$Post(1,nnnn)</code>. Thread B posts the ECB number one with <code>$Post(1,32)</code>, at which point Thread A resumes evaluation with <code>PRINT $STATUSD</code> and prints the post code of 32.</p>
 
==See also==
The ECB-related $functions are:
<ul>
<li><var>[[$EcbDGet]]</var>
<li><var>[[$EcbDSet]]</var>
<li><var>[[$EcbTest|$EcbTest]]</var>
<li><var>[[$Post]]</var>
<li><var>[[$UnPost]]</var>
<li><var>[[$Wait]]</var>
</ul>
 
[[Category:SOUL $functions]]
[[Category:SOUL $functions]]

Latest revision as of 17:21, 2 January 2018

$Post indicates that some event has occurred. The thread(s) waiting on the Event Control Block (ECB) can resume processing.

Syntax

$Post({ECB-number[,post-code][,string] | 'QZSIG'})

Where:

  • ECB-number is a string with a numeric value from one to the value of the NECBS parameter that identifies the ECB to be posted. The ECB-number can be expressed as a numeric literal, a %variable, or a field name.
  • post-code is a numeric value between zero and 16,777,215. You can use this optional argument for whatever you wish. If omitted, a default post code of zero is used.

    The post code is accessible using the $EcbTest function followed by the $StatusD function for the specified posted ECB.

    Once set, unless explicitly reset to zero, post codes persist whether or not the ECB is posted.

  • string can be up to 255 bytes long. It can be a numeric, a literal enclosed in quotation marks, a %variable, or a field name.

    String data is accessible using the $EcbDGet function for the specified ECB.

    Once set, unless explicitly reset to null, data strings persist whether or not the ECB is posted. Depending on the sequence, data strings can be changed by either the $Post or $EcbDSet functions.

  • QZSIG is an extended quiesce named ECB. To use it, you need not set the NECBS parameter. QZSIG can be expressed as a literal, a %variable, or a field name. Although QZSIG can be posted, it cannot be unposted. Unposting is handled internally at the end of the extended quiesce. You cannot specify a post code or a string for QZSIG.

Usage

The $Post function posts a specified ECB with an optional post code and an optional associated string. Only an unposted ECB may be posted. If an ECB is already posted, the posted state is indicated by return code 14. The ECB contents and associated string do not change. Any other thread waiting ($Wait) on the specified ECB becomes eligible to resume processing.

Use the $Post, $UnPost, and $Wait functions to coordinate processing between threads.

The following return codes apply to the $Post 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 is 1
8 No argument specified
9 Checkpointing inactive
10 Post code out of range, 0 to 16,777,215
11 The QZSIG ECB is already posted
12 Invalid argument CPQZ specified or invalid argument following QZSIG
13 Cannot be issued outside of extended quiesce
14 An attempt to post an already posted ECB

Example

On Thread A

BEGIN PRINT $UNPOST(1) PRINT $WAIT(1) PRINT $STATUSD END

On Thread B

BEGIN PRINT $POST(1,32) END

In the previous code, the $UnPost function on Thread A marks the ECB specified as unposted. Then, Thread A waits at the $WAIT(1) until another thread issues a $Post(1,nnnn). Thread B posts the ECB number one with $Post(1,32), at which point Thread A resumes evaluation with PRINT $STATUSD and prints the post code of 32.

See also

The ECB-related $functions are: