$CommBg: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
No edit summary
 
(21 intermediate revisions by 4 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Execute Model 204 commands on sdaemon</span>
<span class="pageSubtitle">Execute Model 204 commands on sdaemon</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $CommBg function is [[Run (Daemon function)]].  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>
<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 <var class="product">Model 204</var> commands to be executed on an sdaemon. It has two basic modes of operation:
This function allows one or more <var class="product">Model&nbsp;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 <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>"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 <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>"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 <var>$CommBg</var> function accepts five arguments and returns a number indicating the success of the function. It is also callable .
The <var>$CommBg</var> function is [[Calling Sirius Mods $functions|callable]].
 
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" />%rc = $CommBg(inlist, file, descriptor, outlist, msgctl)
<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>])
<section end="syntax" /></p>
<p class="caption">$CommBg Function
</p>
</p>
<p class="caption"> %rc is set to 0 or an error code.</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 <var class="product">Model 204</var> 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.</td></tr>
<td>The identifier of a $list that contains the <var class="product">Model&nbsp;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 '''inlist''' 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>
<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 <var>$BgQuery</var> function which is now obsolete, so this parameter is also obsolete -- and ignored. This is an optional argument.</td></tr>
<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 &mdash; 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 <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. Under <var class="product">[[Sirius Mods]]</var> Version 6.2 and earlier, the output line width was always set to 255. Under <var class="product">[[Sirius Mods]]</var> Version 6.3 and later, the output line width is set to the minimum LOBUFF value for any sdaemon thread in the Online.</td></tr>
<td>The identifier of a $list to receive the printed output from the <var class="product">Model&nbsp;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&nbsp;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===
  0 - Request successfully created
<p class="code"> 0 - Request successfully created
  4 - Counting errors in sdaemon (synchronous only)
4 - Counting errors in sdaemon (synchronous only)
  6 - Invalid $list identifier
6 - Invalid $list identifier
  7 - Input $list is empty
7 - Input $list is empty
  8 - sdaemon was restarted (synchronous only)
8 - sdaemon was restarted (synchronous only)
12 - Insufficient input for sdaemon (synchronous only)
12 - Insufficient input for sdaemon (synchronous only)
16 - No sdaemons are running
16 - No sdaemons are running
20 - Out of storage
20 - Out of storage
24 - Output $list or CCATEMP full (synchronous only)
24 - Output $list or [[Using the system scratch file (CCATEMP)|CCATEMP]] full (synchronous only)
40 - Invalid file identifier
40 - Invalid file identifier
</p>
<p class="caption">$CommBg return codes
</p>
</p>


The following program does a PAI dump of file COMPSON in an sdaemon.
==Example==
<p class="code"> B
The following program does a PAI dump of file <code>COMPSON</code> in an sdaemon:
%LIST = $ListNew
<p class="code">b
%RC = $ListAdd(%LIST, 'USE OUTFILE')
%list = $ListNew
%RC = $ListAdd(%LIST, 'B')
%rc = $ListAdd(%list, 'USE OUTFILE')
%RC = $ListAdd(%LIST, 'FOR EACH RECORD')
%rc = $ListAdd(%list, 'B')
%RC = $ListAdd(%LIST, ' PRINT ''*''')
%rc = $ListAdd(%list, 'FOR EACH RECORD')
%RC = $ListAdd(%LIST, ' PAI')
%rc = $ListAdd(%list, ' PRINT &apos;'*&apos;&apos;')
%RC = $ListAdd(%LIST, 'END FOR')
%rc = $ListAdd(%list, ' PAI')
%RC = $ListAdd(%LIST, 'END')
%rc = $ListAdd(%list, 'END FOR')
%rc = $ListAdd(%list, 'END')
   
   
%RC = $CommBg(%LIST, 'COMPSON', 'PAI UNLOAD')
%rc = $CommBg(%list, 'COMPSON', 'PAI UNLOAD')
END
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"> B
<p class="code">b
%ILIST = $ListNew
%ilist = $ListNew
%OLIST = $ListNew
%olist = $ListNew
%RC = $ListAdd(%ILIST, -
%rc = $ListAdd(%ilist, 'CREATE PERM GROUP SNOPES FROM FLEM,IKE')
'CREATE PERM GROUP SNOPES FROM FLEM,IKE')
%rc = $ListAdd(%ilist, 'PARAMETER PROCFILE=*')
%RC = $ListAdd(%ILIST, 'PARAMETER PROCFILE=*')
%rc = $ListAdd(%ilist, 'END')
%RC = $ListAdd(%ILIST, 'END')
%rc = $CommBg(%ilist, , ,%olist)
%RC = $CommBg(%ILIST, , ,%OLIST)
OPEN PERM GROUP SNOPES
OPEN PERM GROUP SNOPES
end
END
</p>
</p>
<p class="code">  
 
==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

Products authorizing $CommBg