$CommBg

From m204wiki
Revision as of 18:57, 29 October 2012 by JALWiccan (talk | contribs) (1 revision)
Jump to navigation Jump to search

Execute Model 204 commands on sdaemon

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 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 accepts five arguments and returns a number indicating the success of the function. It is also callable.

Syntax

<section begin="syntax" />%rc = $CommBg(inlist, file, descriptor, outlist, msgctl) <section end="syntax" />

%rc is set to 0 or an 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. Under Sirius Mods Version 6.2 and earlier, the output line width was always set to 255. Under Sirius Mods Version 6.3 and later, 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.

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

$CommBg return codes

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