Run (Daemon function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 1: Line 1:
{{Template:Daemon:Run subtitle}}
{{Template:Daemon:Run subtitle}}
 
Run is a member of the [[Daemon class]]
Run is a member of the [[Daemon class]]
   
   
 
  This callable method 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).
   
<pre>
This callable method 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).
[%strL =] %daem:Run(command, [%inputObj], [%outputObj], -
<p class="code"><nowiki>[%strL =] %daem:Run(command, [%inputObj], [%outputObj], -
[Info=%infoObj])
[Info=%infoObj])
</pre>
</nowiki></p>
 
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
Line 22: Line 21:
<td>The object passed to the daemon method object. This optional argument is passed by deep copy and not by reference, so '''%inputObj''' must be deep copyable, as described in :hdref refid=copying.. The passed object can be retrieved by the daemon thread using <var>[[GetInputObject (Daemon subroutine)|GetInputObject]]</var>. </td></tr>
<td>The object passed to the daemon method object. This optional argument is passed by deep copy and not by reference, so '''%inputObj''' must be deep copyable, as described in :hdref refid=copying.. The passed object can be retrieved by the daemon thread using <var>[[GetInputObject (Daemon subroutine)|GetInputObject]]</var>. </td></tr>
<tr><th>%outputObj</th>
<tr><th>%outputObj</th>
<td>The object returned from the daemon method object. This optional argument is passed by deep copy and not by reference, so '''%outputObj''' must be deep copyable, as described in :hdref refid=copying.. The object set to %outputObj is the object passed by the daemon thread using the ReturnObject method (:hdref refid=retnobj.).  
<td>The object returned from the daemon method object. This optional argument is passed by deep copy and not by reference, so '''%outputObj''' must be deep copyable, as described in :hdref refid=copying.. The object set to %outputObj is the object passed by the daemon thread using the ReturnObject method (:hdref refid=retnobj.).
  Because '''%outputObj''' is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. </td></tr>
<p>Because '''%outputObj''' 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>Info=%infoObj</th>
<tr><th>Info=%infoObj</th>
<td>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 '''%infoObj''' must be deep copyable, as described in :hdref refid=copying.. The object set to %infoObj is the object passed by the daemon thread using the ReturnInfoObject method (:hdref refid=retnobj.).  
<td>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 '''%infoObj''' must be deep copyable, as described in :hdref refid=copying.. The object set to %infoObj is the object passed by the daemon thread using the ReturnInfoObject method (:hdref refid=retnobj.).
  Because '''%infoObj''' is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. This parameter is only available in ''[[Sirius Mods]]'' Version 6.8 and later.  
<p>Because '''%infoObj''' is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. This parameter is only available in ''[[Sirius Mods]]'' Version 6.8 and later.</p>
  For an example of how to use this parameter, see the bottom of the "Usage Notes," below.</td></tr>
<p>For an example of how to use this parameter, see the bottom of the "Usage Notes," below.</p></td></tr>
</table>
</table>
 
==Exceptions==
==Exceptions==
   
   
 
This function can throw the following exceptions:
This function can throw the following exceptions:<dl>
<dl>
<dt>DaemonLost
<dd>If the daemon object is lost (probably restarted), a DaemonLost exception is thrown. This exception will only be thrown in ''[[Sirius Mods]]'' Version 7.2 and later. See (:hdref refid=daemlse.).</dl>
   
   
<dt>DaemonLost
<dd>If the daemon object is lost (probably restarted), a DaemonLost exception is thrown. This exception will only be thrown in ''[[Sirius Mods]]'' Version 7.2 and later. See (:hdref refid=daemlse.).</dl>
==Usage notes==
==Usage notes==
<ul>
<ul>
   
   
<li>These are example Run calls:
<li>These are example Run calls:
<pre>
<p class="code"><nowiki>%strlist = %daem:run('V UTABLE')
%strlist = %daem:run('V UTABLE')
 
%strlist = %daem:run(%list2, %x, %x)
%strlist = %daem:run(%list2, %x, %x)
</pre>
</nowiki></p>
<li>The Run method sets the output object to Null if the daemon command contains no ReturnObject (:hdref refid=retnobj.) invocation. Subsequent master thread references to that object, for example to print it, 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.
An example of a category of object that may '''not''' be passed to a daemon is a ''[[Janus Sockets]]'' Socket object.
<li>If a file you want to open on the daemon is already open on the master thread, the Open method (:hdref refid=opndaem.) lets you open the file with the same privileges it had on the master thread.
<li>As described in :hdref refid=workdae., Run's Stringlist argument can pass multiple commands to the daemon.
   
   
<li>The Run method sets the output object to Null if the daemon command contains no ReturnObject (:hdref refid=retnobj.) invocation. Subsequent master thread references to that object, for example to print it, 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.
An example of a category of object that may '''not''' be passed to a daemon is a ''[[Janus Sockets]]'' Socket object.
<li>If a file you want to open on the daemon is already open on the master thread, the Open method (:hdref refid=opndaem.) lets you open the file with the same privileges it had on the master thread.
<li>As described in :hdref refid=workdae., Run's Stringlist 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:
  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:
<pre>
<p class="code"><nowiki>class Multivar
class Multivar
public
public
variable a is object a
variable a is object a
Line 79: Line 75:
...
...
%daem:run('I MYPROC', %Multi)
%daem:run('I MYPROC', %Multi)
</pre>
</nowiki></p>
   
   
  To make use of the variables passed in the <tt>%Multi</tt> input parameter above:<ul>
  To make use of the variables passed in the <tt>%Multi</tt> input parameter above:<ul>
   
   
<li>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 the Open method (:hdref refid=opndaem.).  
<li>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 the Open method (:hdref refid=opndaem.).
<li>The MYPROC procedure must contain an invocation of the GetInputObject method (:hdref refid=getinp.).</ul>
<li>The MYPROC procedure must contain an invocation of the GetInputObject method (:hdref refid=getinp.).</ul>
   
   
 
  To return updated values to the master thread above, MYPROC must contain an invocation of ReturnObject (:hdref refid=retnobj.), and the Run method invocation requires an additional argument (represented in the Run method syntax by '''%inputObject'''), compatible with the ReturnObject argument. :hdref refid=quickeg. shows the passing of input and output objects between a master and daemon.  
  To return updated values to the master thread above, MYPROC must contain an invocation of ReturnObject (:hdref refid=retnobj.), and the Run method invocation requires an additional argument (represented in the Run method syntax by '''%inputObject'''), compatible with the ReturnObject argument. :hdref refid=quickeg. shows the passing of input and output objects between a master and daemon.
<li>While the optional <tt>Info</tt> object can be used for any kind of output object, its intent is to separate the "true&amp;CQ. output of a daemon request from informational output (return codes, error messages, diagnostics, etc.).  
<li>While the optional <tt>Info</tt> object can be used for any kind of output object, its intent is to separate the "true&amp;CQ. 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:
  In the following example, a Stringlist object (presumably containing error messages) is used as the Info output:
<pre>
<p class="code"><nowiki>%errors is object stringList
%errors is object stringList
%result is object myClass
%result is object myClass
%daem is object daemon
%daem is object daemon
...
...
%daem:run('MYSUBSYS', , %result, info=%errors)
%daem:run('MYSUBSYS', , %result, info=%errors)
</pre>
</nowiki></p>
   
   
  The daemon thread running the request returns the Info object using the ReturnInfoObject method (:hdref reftxt=ReturnInfoObject refid=retnobj.):
  The daemon thread running the request returns the Info object using the ReturnInfoObject method (:hdref reftxt=ReturnInfoObject refid=retnobj.):
<pre>
<p class="code"><nowiki>%errors is object stringList
%errors is object stringList
...
...
%(daemon):returnInfoObject(%errors)
%(daemon):returnInfoObject(%errors)
</pre>
</nowiki></p>
</ul>
</ul>
 
==Example==
==Example==
   
   
 
  In the following example, a daemon sorts found records, then returns in an object the sorted set of records:
  In the following example, a daemon sorts found records, then returns in an object the sorted set of records:
<pre>
<p class="code"><nowiki>Begin
Begin
%FindCriteria is string len 255
%FindCriteria is string len 255
%Pazuzu is object Daemon
%Pazuzu is object Daemon
Line 122: Line 115:
%SubList is object stringList
%SubList is object stringList
%FindCriteria = 'NICKNAME IS LIKE ''SI*'' '
%FindCriteria = 'NICKNAME IS LIKE ''SI*'' '
 
%SubList = new
%SubList = new
Text to %SubList
Text to %SubList
Line 136: Line 129:
End
End
End Text
End Text
 
%Pazuzu = New
%Pazuzu = New
%Pazuzu:run('*LOWER')
%Pazuzu:run('*LOWER')
%Pazuzu:open('MYFILE')
%Pazuzu:open('MYFILE')
%Pazuzu:run(%SubList,,%Sorted)
%Pazuzu:run(%SubList,,%Sorted)
 
For each record in %Sorted
For each record in %Sorted
Print '*'
Print '*'
Line 147: Line 140:
End For
End For
End
End
</pre>
</nowiki></p>
 
 
==See also==
==See also==
{{Template:Daemon:Run footer}}
{{Template:Daemon:Run footer}}

Revision as of 17:33, 28 February 2011

Run a set of commands on the Daemon thread (Daemon class)


Run is a member of the Daemon class


This callable method 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).

[%strL =] %daem:Run(command, [%inputObj], [%outputObj], - [Info=%infoObj])

Syntax terms

%strL If specified, a Stringlist object that contains the terminal output from the command or commands run on the daemon thread.
%daem A previously defined Daemon object.
command A string or Stringlist that is the required command or the set of commands executed by the daemon.
%inputObj The object passed to the daemon method object. This optional argument is passed by deep copy and not by reference, so %inputObj must be deep copyable, as described in :hdref refid=copying.. The passed object can be retrieved by the daemon thread using GetInputObject.
%outputObj The object returned from the daemon method object. This optional argument is passed by deep copy and not by reference, so %outputObj must be deep copyable, as described in :hdref refid=copying.. The object set to %outputObj is the object passed by the daemon thread using the ReturnObject method (:hdref refid=retnobj.).

Because %outputObj is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable.

Info=%infoObj 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 %infoObj must be deep copyable, as described in :hdref refid=copying.. The object set to %infoObj is the object passed by the daemon thread using the ReturnInfoObject method (:hdref refid=retnobj.).

Because %infoObj is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. This parameter is only available in Sirius Mods Version 6.8 and later.

For an example of how to use this parameter, see the bottom of the "Usage Notes," below.

Exceptions

This function can throw the following exceptions:

DaemonLost
If the daemon object is lost (probably restarted), a DaemonLost exception is thrown. This exception will only be thrown in Sirius Mods Version 7.2 and later. See (:hdref refid=daemlse.).

Usage notes

  • These are example Run calls:

    %strlist = %daem:run('V UTABLE') %strlist = %daem:run(%list2, %x, %x)

  • The Run method sets the output object to Null if the daemon command contains no ReturnObject (:hdref refid=retnobj.) invocation. Subsequent master thread references to that object, for example to print it, 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 (:hdref refid=opndaem.) lets you open the file with the same privileges it had on the master thread.
  • As described in :hdref refid=workdae., Run's Stringlist 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 the Open method (:hdref refid=opndaem.).
    • The MYPROC procedure must contain an invocation of the GetInputObject method (:hdref refid=getinp.).


    To return updated values to the master thread above, MYPROC must contain an invocation of ReturnObject (:hdref refid=retnobj.), and the Run method invocation requires an additional argument (represented in the Run method syntax by %inputObject), compatible with the ReturnObject argument. :hdref refid=quickeg. shows the passing of input and output objects between a master and daemon.
    
  • While the optional Info object can be used for any kind of output object, its intent is to separate the "true&CQ. 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 the ReturnInfoObject method (:hdref reftxt=ReturnInfoObject refid=retnobj.):
    

    %errors is object stringList ... %(daemon):returnInfoObject(%errors)

Example

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 %Sorted 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,,%Sorted) For each record in %Sorted Print '*' pai End For End


See also