$CommBg: Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
No edit summary |
||
| (34 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:$CommBg}} | {{DISPLAYTITLE:$CommBg}} | ||
<span class="pageSubtitle">Execute | <span class="pageSubtitle">Execute Model 204 commands on sdaemon</span> | ||
<p class=" | <p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the <var>$CommBg</var> function is [[Run (Daemon function)|Run]]. The OO APIs emphasize the use of the [[List of Daemon methods|Daemon methods]]; users are strongly urged to use the new Daemon API instead of the old $functions.</p> | ||
This function allows one or more | This function allows one or more <var class="product">Model 204</var> commands to be executed on an [[Sdaemons|sdaemon]]. It has two basic modes of operation: | ||
<ul> | <ul> | ||
<li>"asynchronous" mode is used when the output from the | <li>"asynchronous" mode is used when the output from the <var class="product">Model 204</var> commands are not to be returned into a $list. This is indicated by the absence of the fourth parameter (the output $list identifier). When a request is initiated in "asynchronous" mode, <var>$CommBg</var> returns immediately, before the commands in the input $list are executed. </li> | ||
<li>"synchronous" mode is used when the output from the | |||
<li>"synchronous" mode is used when the output from the <var class="product">Model 204</var> commands are to be returned into a $list. When a request is initiated in "synchronous" mode, <var>$CommBg</var> does not return until all commands in the input $list have been executed. </li> | |||
</ul> | </ul> | ||
The $CommBg function | The <var>$CommBg</var> function is [[Calling Sirius Mods $functions|callable]]. | ||
==Syntax== | ==Syntax== | ||
<p class="syntax">< | <p class="syntax"><span class="term">%rc</span> = <span class="literal">$CommBg</span>(<span class="term">inlist</span>, [<span class="term">file</span>], [<span class="term">descriptor</span>], [<span class="term">outlist</span>], [<span class="term">msgctl</span>]) | ||
< | |||
< | |||
</p> | </p> | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%rc</th> | |||
<td>A numeric variable that is set to 0 or to a positive [[#Return codes|error code]].</td></tr> | |||
===Syntax terrms=== | |||
<tr><th>inlist</th> | <tr><th>inlist</th> | ||
<td>The identifier of a $list that contains the | <td>The identifier of a $list that contains the <var class="product">Model 204</var> commands to be executed in the sdaemon. If the request is an "asynchronous" request (<var class="term">outlist</var> argument missing), the contents of this $list are passed to the sdaemon, and they become no longer available to the invoking program. This is a required argument. After execution of <var>$CommBg</var>, this list is empty.</td></tr> | ||
<tr><th>file</th> | <tr><th>file</th> | ||
<td>A string indicating the name of a file that is to be automatically opened by the sdaemon and made the current file before commands in | <td>A string indicating the name of a file that is to be automatically opened by the sdaemon and made the current file before commands in <strong><i>inlist</i></strong> are executed. This file is opened with the same access privileges the user currently has for the file. This is an optional parameter.</td></tr> | ||
<tr><th>descriptor</th> | <tr><th>descriptor</th> | ||
<td>A string identifying the background task. This information used to be examined via the $BgQuery function which is now obsolete, so this parameter is also obsolete | <td>A string identifying the background task. This information used to be examined via the <var>$BgQuery</var> function which is now obsolete, so this parameter is also obsolete — and ignored. This is an optional argument.</td></tr> | ||
<tr><th>outlist</th> | <tr><th>outlist</th> | ||
<td>The identifier of a $list to receive the printed output from the | <td>The identifier of a $list to receive the printed output from the <var class="product">Model 204</var> commands in the input $list. If this optional argument is present, <var>$CommBg</var> works in "synchronous" mode: it does not return until all the <var class="product">Model 204</var>. commands in the input $list have been executed. If this argument is not present, <var>$CommBg</var> works in "asynchronous" mode: it returns before any of the <var class="product">Model 204</var> commands in the input $list are executed, and the output lines of the background task are placed on the audit trail as "AD" lines. The output line width is set to the minimum <var>[[LOBUFF parameter|LOBUFF]]</var> value for any sdaemon thread in the Online.</td></tr> | ||
<tr><th>msgctl</th> | <tr><th>msgctl</th> | ||
<td>A number indicating the setting to be used for MSGCTL when running the commands in the sdaemon. This is an optional parameter, and it defaults to the user's current MSGCTL setting. | <td>A number indicating the setting to be used for <var>[[MSGCTL parameter|MSGCTL]]</var> when running the commands in the sdaemon. This is an optional parameter, and it defaults to the user's current <var>MSGCTL</var> setting. </td></tr> | ||
</td></tr> | |||
</table> | </table> | ||
<p class="code"> | ===Return codes=== | ||
<p class="code"> 0 - Request successfully created | |||
4 - Counting errors in sdaemon (synchronous only) | |||
6 - Invalid $list identifier | |||
7 - Input $list is empty | |||
8 - sdaemon was restarted (synchronous only) | |||
12 - Insufficient input for sdaemon (synchronous only) | |||
16 - No sdaemons are running | |||
20 - Out of storage | |||
24 - Output $list or [[Using the system scratch file (CCATEMP)|CCATEMP]] full (synchronous only) | |||
40 - Invalid file identifier | |||
</p> | </p> | ||
The following program does a PAI dump of file COMPSON in an sdaemon | ==Example== | ||
<p class="code"> | The following program does a PAI dump of file <code>COMPSON</code> in an sdaemon: | ||
<p class="code">b | |||
%list = $ListNew | |||
%rc = $ListAdd(%list, 'USE OUTFILE') | |||
%rc = $ListAdd(%list, 'B') | |||
%rc = $ListAdd(%list, 'FOR EACH RECORD') | |||
%rc = $ListAdd(%list, ' PRINT ''*''') | |||
%rc = $ListAdd(%list, ' PAI') | |||
%rc = $ListAdd(%list, 'END FOR') | |||
%rc = $ListAdd(%list, 'END') | |||
%rc = $CommBg(%list, 'COMPSON', 'PAI UNLOAD') | |||
end | |||
</p> | </p> | ||
The following program creates a permanent group called SNOPES and then opens that group | The following program creates a permanent group called <code>SNOPES</code> and then opens that group: | ||
<p class="code"> | <p class="code">b | ||
%ilist = $ListNew | |||
%olist = $ListNew | |||
%rc = $ListAdd(%ilist, 'CREATE PERM GROUP SNOPES FROM FLEM,IKE') | |||
%rc = $ListAdd(%ilist, 'PARAMETER PROCFILE=*') | |||
%rc = $ListAdd(%ilist, 'END') | |||
%rc = $CommBg(%ilist, , ,%olist) | |||
OPEN PERM GROUP SNOPES | |||
end | |||
</p> | </p> | ||
< | |||
==Products authorizing {{PAGENAMEE}}== | |||
<ul class="smallAndTightList"> | |||
<li>[[Janus Sockets]]</li> | |||
<li>[[Janus Web Server]]</li> | |||
</ul> | |||
[[Category:$Functions|$CommBg]] | [[Category:$Functions|$CommBg]] | ||
Latest revision as of 15:03, 15 November 2018
Execute Model 204 commands on sdaemon
Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $CommBg function is Run. The OO APIs emphasize the use of the Daemon methods; users are strongly urged to use the new Daemon API instead of the old $functions.
This function allows one or more Model 204 commands to be executed on an sdaemon. It has two basic modes of operation:
- "asynchronous" mode is used when the output from the Model 204 commands are not to be returned into a $list. This is indicated by the absence of the fourth parameter (the output $list identifier). When a request is initiated in "asynchronous" mode, $CommBg returns immediately, before the commands in the input $list are executed.
- "synchronous" mode is used when the output from the Model 204 commands are to be returned into a $list. When a request is initiated in "synchronous" mode, $CommBg does not return until all commands in the input $list have been executed.
The $CommBg function is callable.
Syntax
%rc = $CommBg(inlist, [file], [descriptor], [outlist], [msgctl])
Syntax terrms
| %rc | A numeric variable that is set to 0 or to a positive error code. |
|---|---|
| inlist | The identifier of a $list that contains the Model 204 commands to be executed in the sdaemon. If the request is an "asynchronous" request (outlist argument missing), the contents of this $list are passed to the sdaemon, and they become no longer available to the invoking program. This is a required argument. After execution of $CommBg, this list is empty. |
| file | A string indicating the name of a file that is to be automatically opened by the sdaemon and made the current file before commands in inlist are executed. This file is opened with the same access privileges the user currently has for the file. This is an optional parameter. |
| descriptor | A string identifying the background task. This information used to be examined via the $BgQuery function which is now obsolete, so this parameter is also obsolete — and ignored. This is an optional argument. |
| outlist | The identifier of a $list to receive the printed output from the Model 204 commands in the input $list. If this optional argument is present, $CommBg works in "synchronous" mode: it does not return until all the Model 204. commands in the input $list have been executed. If this argument is not present, $CommBg works in "asynchronous" mode: it returns before any of the Model 204 commands in the input $list are executed, and the output lines of the background task are placed on the audit trail as "AD" lines. The output line width is set to the minimum LOBUFF value for any sdaemon thread in the Online. |
| msgctl | A number indicating the setting to be used for MSGCTL when running the commands in the sdaemon. This is an optional parameter, and it defaults to the user's current MSGCTL setting. |
Return codes
0 - Request successfully created 4 - Counting errors in sdaemon (synchronous only) 6 - Invalid $list identifier 7 - Input $list is empty 8 - sdaemon was restarted (synchronous only) 12 - Insufficient input for sdaemon (synchronous only) 16 - No sdaemons are running 20 - Out of storage 24 - Output $list or CCATEMP full (synchronous only) 40 - Invalid file identifier
Example
The following program does a PAI dump of file COMPSON in an sdaemon:
b %list = $ListNew %rc = $ListAdd(%list, 'USE OUTFILE') %rc = $ListAdd(%list, 'B') %rc = $ListAdd(%list, 'FOR EACH RECORD') %rc = $ListAdd(%list, ' PRINT ''*''') %rc = $ListAdd(%list, ' PAI') %rc = $ListAdd(%list, 'END FOR') %rc = $ListAdd(%list, 'END') %rc = $CommBg(%list, 'COMPSON', 'PAI UNLOAD') end
The following program creates a permanent group called SNOPES and then opens that group:
b %ilist = $ListNew %olist = $ListNew %rc = $ListAdd(%ilist, 'CREATE PERM GROUP SNOPES FROM FLEM,IKE') %rc = $ListAdd(%ilist, 'PARAMETER PROCFILE=*') %rc = $ListAdd(%ilist, 'END') %rc = $CommBg(%ilist, , ,%olist) OPEN PERM GROUP SNOPES end