AppendCPCommandOutput (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
No edit summary |
||
| (7 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:AppendCPCommandOutput subtitle}} | {{Template:Stringlist:AppendCPCommandOutput subtitle}} | ||
This [[Notation conventions for methods#Callable functions|callable]] method invokes a CP command in the Online's virtual machine and adds the output from that command to a <var>Stringlist</var>. The <var>AppendCPCommand</var> method accepts one or more arguments and returns a numeric result. Since CP commands are only available in a CMS environment, this method is useless when running under z/OS (MVS) or VSE and will result in request cancellation if invoked under those operating systems. | |||
==Syntax== | ==Syntax== | ||
{{Template:Stringlist:AppendCPCommandOutput syntax}} | {{Template:Stringlist:AppendCPCommandOutput syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%rc</th><td> | <tr><th>%rc</th><td>The return code from the issued CP command.</td></tr> | ||
<tr><th>sl</th> | <tr><th>sl</th> | ||
<td>Stringlist | <td>The <var>Stringlist</var> to receive output from the CP command.</td></tr> | ||
<tr><th>command</th> | <tr><th>command</th> | ||
<td> | <td>The CP command to be issued.</td></tr> | ||
<tr><th><var>BufferSize</var></th> | <tr><th><var>BufferSize</var></th> | ||
<td> | <td>The size of the virtual storage buffer to hold the result of the CP command. <var>AppendCpCommandOutput</var> uses Diagnose X'08' to issue the CP command, and Diagnose X'08' requires that the output from the command go to a single contiguous buffer in virtual storage. This buffer is only used as a staging area to hold the command output until it is moved to the output <var>Stringlist</var>. | ||
<p> | |||
<var>BufferSize</var> can be set to any value between 256 and 16M-1 (16777215). The default BufferSize, 64K (65536), is probably more than enough for almost all commands. There is probably little benefit to making the buffer smaller, as it is only allocated for a fleeting instant. </p></td></tr> | |||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul><li>Since a CP command can do nasty things to an Online (like set storage, or re-IPL the virtual machine), it is restricted to users with system manager privileges. An attempt to use it on a non-system manager account results in request cancellation.</li> | |||
<li>If the CP command output will not fit into the output buffer, the request is cancelled.</li> | |||
<li>Multiple CP commands can be issued in a single <var>AppendCpCommandoutput</var> invocation by separating them with an EBCDIC newline character (X'15'), as in <code>%sl:AppendCpCommandOutput('Q SET' '15':x 'IND').</code></li> | |||
</ul> | |||
==Examples== | ==Examples== | ||
The following program issues a CP <code>QUERY NAMES</code> command and displays the output on the user's terminal: | |||
<p class="output">b | |||
%sl is object stringlist auto new | |||
%sl:appendCpCommandOutput('Q NAMES') | |||
%sl:print | |||
end | |||
</p> | |||
==See also== | ==See also== | ||
{{Template:Stringlist:AppendCPCommandOutput footer}} | {{Template:Stringlist:AppendCPCommandOutput footer}} | ||
Latest revision as of 22:23, 2 September 2015
Add output from CP command to Stringlist (Stringlist class)
[Introduced in Sirius Mods 7.9]
This callable method invokes a CP command in the Online's virtual machine and adds the output from that command to a Stringlist. The AppendCPCommand method accepts one or more arguments and returns a numeric result. Since CP commands are only available in a CMS environment, this method is useless when running under z/OS (MVS) or VSE and will result in request cancellation if invoked under those operating systems.
Syntax
[%rc =] sl:AppendCPCommandOutput( command, [BufferSize= number])
Syntax terms
| %rc | The return code from the issued CP command. |
|---|---|
| sl | The Stringlist to receive output from the CP command. |
| command | The CP command to be issued. |
| BufferSize | The size of the virtual storage buffer to hold the result of the CP command. AppendCpCommandOutput uses Diagnose X'08' to issue the CP command, and Diagnose X'08' requires that the output from the command go to a single contiguous buffer in virtual storage. This buffer is only used as a staging area to hold the command output until it is moved to the output Stringlist.
BufferSize can be set to any value between 256 and 16M-1 (16777215). The default BufferSize, 64K (65536), is probably more than enough for almost all commands. There is probably little benefit to making the buffer smaller, as it is only allocated for a fleeting instant. |
Usage notes
- Since a CP command can do nasty things to an Online (like set storage, or re-IPL the virtual machine), it is restricted to users with system manager privileges. An attempt to use it on a non-system manager account results in request cancellation.
- If the CP command output will not fit into the output buffer, the request is cancelled.
- Multiple CP commands can be issued in a single AppendCpCommandoutput invocation by separating them with an EBCDIC newline character (X'15'), as in
%sl:AppendCpCommandOutput('Q SET' '15':x 'IND').
Examples
The following program issues a CP QUERY NAMES command and displays the output on the user's terminal:
b %sl is object stringlist auto new %sl:appendCpCommandOutput('Q NAMES') %sl:print end