$Command: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(32 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Execute Model 204 command on sdaemon, results to image</span>
<span class="pageSubtitle">Execute Model 204 command on sdaemon, results to image</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the <var>$Command</var> 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 $Command function is the <var>[[Run (Daemon function)|Run]]</var> 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>


This function allows a <var class="product">Model 204</var> command to be executed on an sdaemon with the results returned to an image. <var>$Command</var> performs the same function as <var>$CommndL</var> except that data is returned to an image rather than a $list. <var>$CommndL</var> and <var>$CommBg</var> are recommended over $Command, as they run with less overhead, are simpler to use, and return their output in a $list.  
This function allows a <var class="product">Model 204</var> command to be executed on an [[Sdaemons|sdaemon]] with the results returned to an [[Images|image]]. <var>$Command</var> performs the same function as <var>[[$CommndL|$CommndL]]</var> except that data is returned to an image rather than a $list. <var>$CommndL</var> and <var>[[$CommBg|$CommBg]]</var> are recommended over $Command, as they run with less overhead, are simpler to use, and return their output in a $list.
 
The <var>$Command</var> function accepts five arguments and returns a number indicating the success of the function. It is also [[Calling Sirius Mods $functions|callable]].


The <var>$Command</var> function accepts five arguments and returns a number indicating the success of the function. It is also callable .
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %rc = $Command(cmd, msgctl, image_name, file, width)
<p class="syntax"><span class="term">%rc</span> = <span class="literal">$Command</span>(<span class="term">cmd</span>, [<span class="term">msgctl</span>], [<span class="term">image_name</span>], [<span class="term">file</span>], [<span class="term">width</span>])
<section end="syntax" /></p>
<p class="caption">$Command Function
</p>
</p>
<p class="caption"> %rc is set to 0 or an error code.</p>
<p class="caption"> %rc is set to 0 or an error code.</p>


Line 18: Line 18:
<td>A string containing the <var class="product">Model 204</var> command to be executed. This is a required argument.</td></tr>
<td>A string containing the <var class="product">Model 204</var> command to be executed. This is a required argument.</td></tr>
<tr><th>msgctl</th>
<tr><th>msgctl</th>
<td>A number indicating the setting to be used for MSGCTL when issuing the command in the sdaemon. This is an optional parameter, and it defaults to the user's current MSGCTL setting.</td></tr>
<td>A number indicating the setting to be used for <var>[[MSGCTL_parameter|MSGCTL]]</var> when issuing the command in the sdaemon. This is an optional parameter, and it defaults to the user's current MSGCTL setting.</td></tr>
 
<tr><th>image_name</th>
<tr><th>image_name</th>
<td>The name of an image to receive the command output. This image should have the following format:
<td>The name of an image to receive the command output. This image should have the following format:
<p class="code"> IMAGE CMD_OUT ARRAY_SIZE IS BINARY LEN 4
<p class="code">  
DISC_NUM IS BINARY LEN 4
IMAGE CMD_OUT  
NEXT_OUT IS BINARY LEN 4
    ARRAY_SIZE IS BINARY LEN 4
LINES_OUT IS BINARY LEN 4 ARRAY OCCURS n
    DISC_NUM IS BINARY LEN 4
OUT_ARRAY IS STRING LEN x  
    NEXT_OUT IS BINARY LEN 4
END ARRAY  
    LINES_OUT IS BINARY LEN 4  
    ARRAY OCCURS n
      OUT_ARRAY IS STRING LEN x  
    END ARRAY  
  END IMAGE
  END IMAGE
</p>
</p>
Where:  
Where:
<ul>
<ul>
<li>ARRAY_SIZE is the number of entries in OUT_ARRAY.  
<li>ARRAY_SIZE is the number of entries in OUT_ARRAY.  
Line 40: Line 43:
</ul>
</ul>
This must be set prior to calling the function. lines to be discarded before capturing starts. number of lines captured. The length, '''x''', should be set to the value of the fifth parameter passed to the function as described below. indicates the number of lines of output expected. The '''image_name''' argument is optional. If it is omitted, command output is printed to the output stream of the current user (the user invoking $Command).</td></tr>
This must be set prior to calling the function. lines to be discarded before capturing starts. number of lines captured. The length, '''x''', should be set to the value of the fifth parameter passed to the function as described below. indicates the number of lines of output expected. The '''image_name''' argument is optional. If it is omitted, command output is printed to the output stream of the current user (the user invoking $Command).</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 '''cmd''' is executed. The 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 '''cmd''' is executed. The file is opened with the same access privileges the user currently has for the file. This is an optional parameter.</td></tr>
<tr><th>width</th>
<tr><th>width</th>
<td>A number indicating the line width to be used for output lines. This is an optional argument, and it defaults to 80. Under <var class="product">[[Sirius Mods]]</var> Version 6.2 and earlier: if this value is not in the range 1-256, the default is used. Under <var class="product">[[Sirius Mods]]</var> Version 6.3 and later: this value can be specified as any value between 1 and the minimum LOBUFF value for any sdaemon thread in the Online, and if the value is not a valid number or not in this range, the request is cancelled.
<td>A number indicating the line width to be used for output lines. This is an optional argument, and it defaults to 80. Under <var class="product">[[Sirius Mods]]</var> Version 6.2 and earlier: if this value is not in the range 1-256, the default is used. Under <var class="product">[[Sirius Mods]]</var> Version 6.3 and later: this value can be specified as any value between 1 and the minimum <var>[[LOBUFF_parameter|LOBUFF]]</var> value for any sdaemon thread in the Online, and if the value is not a valid number or not in this range, the request is cancelled.
</td></tr>
</td></tr>
</table>
</table>
Line 91: Line 96:
</p>
</p>
<p class="code">  
<p class="code">  
==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
</ul>


[[Category:$Functions|$Command]]
[[Category:$Functions|$Command]]

Latest revision as of 14:02, 14 November 2018

Execute Model 204 command on sdaemon, results to image

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Command function is the Run 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 a Model 204 command to be executed on an sdaemon with the results returned to an image. $Command performs the same function as $CommndL except that data is returned to an image rather than a $list. $CommndL and $CommBg are recommended over $Command, as they run with less overhead, are simpler to use, and return their output in a $list.

The $Command function accepts five arguments and returns a number indicating the success of the function. It is also callable.

Syntax

%rc = $Command(cmd, [msgctl], [image_name], [file], [width])

%rc is set to 0 or an error code.

cmd A string containing the Model 204 command to be executed. This is a required argument.
msgctl A number indicating the setting to be used for MSGCTL when issuing the command in the sdaemon. This is an optional parameter, and it defaults to the user's current MSGCTL setting.
image_name The name of an image to receive the command output. This image should have the following format:

IMAGE CMD_OUT ARRAY_SIZE IS BINARY LEN 4 DISC_NUM IS BINARY LEN 4 NEXT_OUT IS BINARY LEN 4 LINES_OUT IS BINARY LEN 4 ARRAY OCCURS n OUT_ARRAY IS STRING LEN x END ARRAY END IMAGE

Where:

  • ARRAY_SIZE is the number of entries in OUT_ARRAY.
  • DISC_NUM is the number of output
  • NEXT_OUT is the array item number of the next entry to be set.
  • LINES_OUT is a return parameter and is set to the
  • OUT_ARRAY is a string array that contains the captured data.
  • The value of n, in OCCURS n,
This must be set prior to calling the function. lines to be discarded before capturing starts. number of lines captured. The length, x, should be set to the value of the fifth parameter passed to the function as described below. indicates the number of lines of output expected. The image_name argument is optional. If it is omitted, command output is printed to the output stream of the current user (the user invoking $Command).
file A string indicating the name of a file that is to be automatically opened by the sdaemon and made the current file before cmd is executed. The file is opened with the same access privileges the user currently has for the file. This is an optional parameter.
width A number indicating the line width to be used for output lines. This is an optional argument, and it defaults to 80. Under Sirius Mods Version 6.2 and earlier: if this value is not in the range 1-256, the default is used. Under Sirius Mods Version 6.3 and later: this value can be specified as any value between 1 and the minimum LOBUFF value for any sdaemon thread in the Online, and if the value is not a valid number or not in this range, the request is cancelled.

0 - Command successfully executed 4 - Command processed, errors produced 8 - sdaemon restarted 12 - sdaemon required more input 16 - No sdaemons are running 20 - Out of storage 24 - Specified output image not found 28 - Image not active 32 - Image too short 36 - Image contains invalid data 40 - Invalid file identifier

$Command return codes

The following program issues a VIEW command and displays the result at the user's terminal.

B IMAGE CMD_OUT ARRAY_SIZE IS BINARY LEN 4 DISC_NUM IS BINARY LEN 4 NEXT_OUT IS BINARY LEN 4 LINES_OUT IS BINARY LEN 4 ARRAY OCCURS 10 OUT_ARRAY IS STRING LEN 80 END ARRAY END IMAGE %I IS FIXED DP 0 %RC IS FIXED DP 0 PREPARE IMAGE CMD_OUT %CMD_OUT:ARRAY_SIZE = 10 %RC = $Command('VIEW',,'CMD_OUT') FOR %I FROM 1 TO 10 PRINT %CMD_OUT:OUT_ARRAY(%I) END FOR PRINT '10 lines printed. RC= ' AND %RC END

Products authorizing $Command

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$Command&oldid=117014"