Run (Daemon function): Difference between revisions
m (→Syntax terms) |
|||
(15 intermediate revisions by 5 users not shown) | |||
Line 4: | Line 4: | ||
==Syntax== | ==Syntax== | ||
{{Template:Daemon:Run syntax}} | {{Template:Daemon:Run syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%sl</th> | <tr><th>%sl</th> | ||
<td>If specified, a <var>[[Stringlist class|Stringlist]]</var> object to contain the terminal output from the command, or commands, run on the daemon thread. </td></tr> | <td>If specified, a <var>[[Stringlist class|Stringlist]]</var> object to contain the terminal output from the command, or commands, run on the daemon thread. </td></tr> | ||
<tr><th>daemon</th> | <tr><th>daemon</th> | ||
<td>A <var> | <td>A <var>Daemon</var> object expression. </td></tr> | ||
<tr><th>commands</th> | <tr><th>commands</th> | ||
<td>A string or <var>Stringlist</var> that is the command, or the set of commands, to be executed by the daemon. </td></tr> | <td>A string or <var>Stringlist</var> that is the command, or the set of commands, to be executed by the daemon. </td></tr> | ||
<tr><th> | |||
<td>The input object passed to the daemon method object. This optional argument is passed by deep copy and not by reference, so <var class="term"> | <tr><th><var>Input</var></th> | ||
<tr><th> | <td>The input object passed to the daemon method object. This optional, [[Methods#Named parameters|name allowed]], argument is passed by deep copy and not by reference, so <var class="term">object</var> must be deep copyable, as described in: [[Copying objects]]. The passed object can be retrieved by the daemon thread using <var>[[GetInputObject (Daemon subroutine)|GetInputObject]]</var>.</td></tr> | ||
<td>The output object returned from the daemon method object. This optional argument is passed by deep copy and not by reference, so <var class="term"> | |||
<p>Because <var class="term"> | <tr><th><var>Output</var></th> | ||
<td>The output object returned from the daemon method object. This optional, name allowed, argument is passed by deep copy and not by reference, so <var class="term">object</var> must be deep copyable. The object set to <var class="term">object</var> is the object passed by the daemon thread using <var>[[ReturnObject (Daemon subroutine)|ReturnObject]]</var>. | |||
<p>Because <var class="term">object</var> is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. </p></td></tr> | |||
<tr><th><var>Info</var></th> | <tr><th><var>Info</var></th> | ||
<td>An optional, | <td>An optional, [[Methods#Named parameters|name required]], parameter that indicates a second output object returned from the daemon method object. This optional argument is passed by deep copy and not by reference, so <var>Info</var> must be deep copyable. The object set to <var>Info</var> is the object passed by the daemon thread using <var>[[ReturnInfoObject (Daemon subroutine)|ReturnInfoObject]]</var>. | ||
<p>Because <var | <p>Because <var>Info</var> is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. </p> | ||
<p>For an example of how to use this parameter, see the bottom of | <p>For an example of how to use this parameter, see the bottom of [[Run (Daemon function)#Usage notes|Usage Notes]], below.</p></td></tr> | ||
</table> | </table> | ||
==Exceptions== | ==Exceptions== | ||
This function can throw the following | This function can throw the following exception: | ||
< | <table class="syntaxTable"> | ||
< | <tr><th><var>[[DaemonLost class|DaemonLost]]</var></th> | ||
< | <td>If the daemon object is lost (probably restarted), a <var>DaemonLost</var> exception is thrown. </td></tr> | ||
</table> | |||
==Usage notes== | ==Usage notes== | ||
<ul><li><var>Run</var> sets the output object to Null if the daemon command contains no <var>[[ReturnObject (Daemon subroutine)|ReturnObject]]</var> invocation. Any subsequent master thread references to that object, for example to print it, will cancel the request. | <ul> | ||
<li><var>Run</var> sets the output object to Null if the daemon command contains no <var>[[ReturnObject (Daemon subroutine)|ReturnObject]]</var> invocation. Any subsequent master thread references to that object, for example to print it, will cancel the request. | |||
<li>As any Run method input-object argument, an input "parameter object" is passed by deep copy: the parameter object, all objects contained in that object, all objects contained in those objects, and so on are copied and passed to the sdaemon thread. | <li>As any Run method input-object argument, an input "parameter object" is passed by deep copy: the parameter object, all objects contained in that object, all objects contained in those objects, and so on are copied and passed to the sdaemon thread. | ||
<p>An example of a category of object that may <b><i>not</i></b> be passed to a daemon is a <var>[[Janus Sockets]]</var> Socket object.</p> | <p>An example of a category of object that may <b><i>not</i></b> be passed to a daemon is a <var class="product">[[Janus Sockets]]</var> <var>[[Socket class|Socket]]</var> object.</p> | ||
<li>If a file you want to open on the daemon is already open on the master thread, the <var>[[Open (Daemon subroutine)|Open]]</var> method lets you open the file with the same privileges it had on the master thread. | <li>If a file you want to open on the daemon is already open on the master thread, the <var>[[Open (Daemon subroutine)|Open]]</var> method lets you open the file with the same privileges it had on the master thread. | ||
<li>As described in | |||
<li>As described in [[Daemon class#Working with Daemonobjects|Working with Daemon objects]], <var>Run's</var> <var class="term">commands</var> argument can pass multiple commands to the daemon. | |||
<p>For example, to pass objects of three different classes, as well as float and longstring values to a daemon request, you can create a user class that contains such objects and the appropriate float and longstring values, then pass a "parameter object" of that class, as follows:</p> | <p>For example, to pass objects of three different classes, as well as float and longstring values to a daemon request, you can create a user class that contains such objects and the appropriate float and longstring values, then pass a "parameter object" of that class, as follows:</p> | ||
<p class="code">class Multivar | <p class="code">class Multivar | ||
Line 59: | Line 70: | ||
</p> | </p> | ||
<p>To make use of the variables passed in the <code>%multi</code> input parameter above:</p> | <p>To make use of the variables passed in the <code>%multi</code> input parameter above:</p> | ||
<ul><li>The file containing MYPROC must be open on the daemon from an invocation of <var>Run</var> with a <var class="product">Model 204</var> OPEN command argument or from an invocation of <var>[[Open (Daemon subroutine)|Open]]</var> | <ul> | ||
<li>The MYPROC procedure must contain an invocation of <var>[[GetInputObject_(Daemon_subroutine)|GetInputObject]]</var>.</ul> | |||
<p>To return updated values to the master thread above, MYPROC must contain an invocation of <var>[[ReturnObject (Daemon subroutine)|ReturnObject]]</var>, and <var>Run</var> invocation requires an additional argument (represented in the <var>Run</var> method syntax by <var | <li>The file containing <code>MYPROC</code> must be open on the daemon from an invocation of <var>Run</var> with a <var class="product">Model 204</var> <var>OPEN</var> command argument or from an invocation of <var>[[Open (Daemon subroutine)|Open]]</var>. | ||
<li>The <code>MYPROC</code> procedure must contain an invocation of <var>[[GetInputObject_(Daemon_subroutine)|GetInputObject]]</var>. | |||
</ul> | |||
<p>To return updated values to the master thread above, <code>MYPROC</code> must contain an invocation of <var>[[ReturnObject (Daemon subroutine)|ReturnObject]]</var>, and the <var>Run</var> invocation requires an additional argument (represented in the <var>Run</var> method syntax by the <var>Output</var> argument), compatible with the <var>ReturnObject</var> argument. [[Daemon_class#A_Daemon_example|A Daemon example]] shows the passing of input and output objects between a master and daemon.</p> | |||
</ul> | </ul> | ||
== | ==Examples== | ||
<ol><li>These are simple examples of <var>Run</var> calls: | <ol><li>These are simple examples of <var>Run</var> calls: | ||
<p class="code">%strlist = %daem:run('V UTABLE') | <p class="code">%strlist = %daem:run('V UTABLE') | ||
%strlist = %daem:run(%list2, %x, %x) | %strlist = %daem:run(%list2, %x, %x) | ||
</p> | </p> | ||
Line 75: | Line 90: | ||
%sSorted is object sortedRecordset in file MYFILE | %sSorted is object sortedRecordset in file MYFILE | ||
%subList is object stringList | %subList is object stringList | ||
%findCriteria = 'NICKNAME IS LIKE | %findCriteria = 'NICKNAME IS LIKE ''SI*'' ' | ||
%subList = new | %subList = new | ||
Line 94: | Line 109: | ||
%pazuzu:run('*LOWER') | %pazuzu:run('*LOWER') | ||
%pazuzu:open('MYFILE') | %pazuzu:open('MYFILE') | ||
%pazuzu:run(%subList,,% | %pazuzu:run(%subList,,%sSorted) | ||
for each record in % | for each record in %sSorted | ||
print '*' | print '*' | ||
pai | pai | ||
Line 102: | Line 117: | ||
end | end | ||
</p> | </p> | ||
<li>While the optional <var | <li>While the optional <var>Info</var> object can be used for any kind of output object, its intent is to separate the "true" output of a daemon request from informational output (return codes, error messages, diagnostics, etc.). In the following example, a <var>Stringlist</var> object (presumably containing error messages) is used as the <var>Info</var> output: | ||
<p class="code">%errors is object stringList | <p class="code">%errors is object stringList | ||
%result is object myClass | %result is object myClass | ||
Line 109: | Line 124: | ||
%daem:run('MYSUBSYS', , %result, info=%errors) | %daem:run('MYSUBSYS', , %result, info=%errors) | ||
</p> | </p> | ||
The daemon thread running the request returns the <var | The daemon thread running the request returns the <var>Info</var> object using <var>[[ReturnInfoObject (Daemon subroutine)|ReturnInfoObject]]</var>: | ||
<p class="code">%errors is object stringList | <p class="code">%errors is object stringList | ||
... | ... |
Latest revision as of 10:08, 16 September 2020
Run a set of commands on the Daemon thread (Daemon class)
Run runs on the daemon thread the command, or set of commands, specified by its first argument, and it returns the terminal output from the command(s).
Syntax
[%sl =] daemon:Run( commands, [[Input=] object], [[Output=] object], - [Info= object]) Throws DaemonLost, IncorrectDaemonState
Syntax terms
%sl | If specified, a Stringlist object to contain the terminal output from the command, or commands, run on the daemon thread. |
---|---|
daemon | A Daemon object expression. |
commands | A string or Stringlist that is the command, or the set of commands, to be executed by the daemon. |
Input | The input object passed to the daemon method object. This optional, name allowed, argument is passed by deep copy and not by reference, so object must be deep copyable, as described in: Copying objects. The passed object can be retrieved by the daemon thread using GetInputObject. |
Output | The output object returned from the daemon method object. This optional, name allowed, argument is passed by deep copy and not by reference, so object must be deep copyable. The object set to object is the object passed by the daemon thread using ReturnObject.
Because object is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. |
Info | An optional, name required, parameter that indicates a second output object returned from the daemon method object. This optional argument is passed by deep copy and not by reference, so Info must be deep copyable. The object set to Info is the object passed by the daemon thread using ReturnInfoObject.
Because Info is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. For an example of how to use this parameter, see the bottom of Usage Notes, below. |
Exceptions
This function can throw the following exception:
DaemonLost | If the daemon object is lost (probably restarted), a DaemonLost exception is thrown. |
---|
Usage notes
- Run sets the output object to Null if the daemon command contains no ReturnObject invocation. Any subsequent master thread references to that object, for example to print it, will cancel the request.
- As any Run method input-object argument, an input "parameter object" is passed by deep copy: the parameter object, all objects contained in that object, all objects contained in those objects, and so on are copied and passed to the sdaemon thread.
An example of a category of object that may not be passed to a daemon is a Janus Sockets Socket object.
- If a file you want to open on the daemon is already open on the master thread, the Open method lets you open the file with the same privileges it had on the master thread.
- As described in Working with Daemon objects, Run's commands argument can pass multiple commands to the daemon.
For example, to pass objects of three different classes, as well as float and longstring values to a daemon request, you can create a user class that contains such objects and the appropriate float and longstring values, then pass a "parameter object" of that class, as follows:
class Multivar public variable a is object a variable b is object b variable c is object c variable y is float variable z is longstring end public end class ... %multi is object Multivar %daem is object daemon ... %multi = new %multi:a = %objectA %multi:b = %objectB %multi:c = %objectC %multi:y = 3.1415929 %multi:z = %lstrZ ... %daem:run('I MYPROC', %Multi)
To make use of the variables passed in the
%multi
input parameter above:- The file containing
MYPROC
must be open on the daemon from an invocation of Run with a Model 204 OPEN command argument or from an invocation of Open. - The
MYPROC
procedure must contain an invocation of GetInputObject.
To return updated values to the master thread above,
MYPROC
must contain an invocation of ReturnObject, and the Run invocation requires an additional argument (represented in the Run method syntax by the Output argument), compatible with the ReturnObject argument. A Daemon example shows the passing of input and output objects between a master and daemon. - The file containing
Examples
- These are simple examples of Run calls:
%strlist = %daem:run('V UTABLE') %strlist = %daem:run(%list2, %x, %x)
- In the following example, a daemon sorts found records, then returns in an object the sorted set of records:
begin %findCriteria is string len 255 %pazuzu is object daemon %sSorted is object sortedRecordset in file MYFILE %subList is object stringList %findCriteria = 'NICKNAME IS LIKE ''SI*'' ' %subList = new text to %subList begin %basicSet is object recordSet in file MYFILE %sorted is object sortedRecordSet in file MYFILE %basicSet = New find records to %basicSet {%FindCriteria} end find sort records in %basicSet to %sorted by NICKNAME %(daemon):returnObject(%Sorted) end end text %pazuzu = New %pazuzu:run('*LOWER') %pazuzu:open('MYFILE') %pazuzu:run(%subList,,%sSorted) for each record in %sSorted print '*' pai end for end
- While the optional Info object can be used for any kind of output object, its intent is to separate the "true" output of a daemon request from informational output (return codes, error messages, diagnostics, etc.). In the following example, a Stringlist object (presumably containing error messages) is used as the Info output:
%errors is object stringList %result is object myClass %daem is object daemon ... %daem:run('MYSUBSYS', , %result, info=%errors)
The daemon thread running the request returns the Info object using ReturnInfoObject:
%errors is object stringList ... %(daemon):returnInfoObject(%errors)