Shellexecute

SHELLEXECUTE stage v1.3

Pipelines v2.1

Purpose, Operands, Input record format, Streams, Usage, Examples, Related

Needs more examples

Syntax

>>──SHELLexecute──┬───────┬──────────────────────────────────────────────────────────><

                  └─BATCH─┘

Input record format:

            ┌─WAIT─────────┐

   ┌─CMD─┐  ├─SYNCHronous──┤  ┌─MAXERROR─0────────────┐

├──┼─────┼──┼──────────────┼──┼───────────────────────┼──command──────────────────────┤

   ├─EXE─┤  ├─NOWAIT───────┤  ├─MAXERRor─┬─errorlevel─┘

   └─PRG─┘  └─ASYNCHronous─┘  └─MAXRC────┘

Purpose

Use the SHELLEXECUTE stage to execute the specified command.

SHELLEXECUTE launches the specified process and begins reading records from that process' STDOUT and STDERROR streams. Records which are read from that process' STDOUT stream are written to the primary output stream and records which are read from that process' STDERROR stream, are written to the secondary output stream, if it is connected.

The only operand that can be specified on the stage command is the BATCH operand. All other operands, including the command to execute must be specified in a primary input stream record. You may process a series of input records that define; system commands, Powershell commands and third-party processes which may be synchronous or asynchronous.

Operands

●

BATch

specifies that should an input record argument contain a syntax error or invalid data, or that the actual command fails to execute; SHELLEXECUTE will issue the appropriate error message, but it will continue to read, process and execute input record commands until it reaches end-of-file on its primary input stream.

Input record format

●

CMD

specifies that command is a DOS or system shell command. This is the default.

●

EXE

PRG

specifies that command is an executable program.

●

WAIT

SYNCHronous

specifies that SHELLEXECUTE will wait for the command process to terminate before reading the next record from its primary input stream. This is the default.

●

NOWAIT

ASYNCHronous

specifies that SHELLEXECUTE will not wait for the command process to terminate, SHELLEXECUTE will read the next record from its primary input stream immediately.

●

MAXERRor

MAXRC

specifies the maximum allowed process return code. Zero is the default.

●	errorlevel is an unsigned integer which specifies the highest acceptable return code which indicates that the process has completed successfully. A return code that is higher than this defined maximum; will cause the SHELLEXECUTE stage to terminate with an error return code.

●

command

specifies a DOS/system shell command or program to execute.

Streams

The following streams are used by the SHELLEXECUTE stage:

Stream	Action

Primary input stream	SHELLEXECUTE reads records from its primary input stream and uses each as the command line argument for the specified process.
Primary output stream	SHELLEXECUTE reads records from the process' STDOUT and STDERR output streams and writes them to its primary output stream and secondary output stream, if it is connected.

Usage

1.	SHELL does not delay the records.
2.	When the WAIT or SYNCHronous operand is specified; SHELLEXECUTE will wait for the command process to terminate before reading the next record from its primary input stream. This is the default
3.	If you have Powershell installed on your machine; you can execute Powershell commands and process their output from within an ooRexx program: Consider the following example; which selects only SVCHOST system process entries from the Powershell command output: ** Top of file ** 1 Address Rxpipe 2 3 'pipe (endchar ?)', 4 'literal /powershell ps/ ', 5 '\| shell', 6 '\| a: drop 3', 7 '\| locate anycase w-1 /svchost/', 8 '\| b: faninany', 9 '\| cons', 10 '?', 11 'a:', 12 '\| take ', 13 '\| b:' 14 15 Exit 0 * End of file The pipeline above produces the following output: Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 139 5 3280 4852 56 0.12 488 svchost 291 24 10032 9544 71 1.14 1648 svchost 120 5 1872 4312 40 0.14 2036 svchost And, consider this; another example; launched from the command line: mypipe.rex Top of file 1 Address Rxpipe 2 3 'pipe lit /powershell get-eventlog system/', 4 '\| shell', 5 '\| cons' 6 7 Exit 0 End of file Windows PowerShell Copyright (C) 2006 Microsoft Corporation. All rights reserved. PS C:\Users\TenFiftyTwo> mypipe.rex** Index Time Type Source EventID Message ----- ---- ---- ------ ------- ------- 76970 Sep 29 19:33 Info Microsoft-Windows... 1 The description for Event ID '1' in Source 'Microsoft-Windows... 76969 Sep 29 19:33 Info Service Control M... 7036 The description for Event ID '1073748860' in Source 'Service ... 76968 Sep 29 19:27 Info Microsoft-Windows... 42 The description for Event ID '42' in Source 'Microsoft-Window... 76967 Sep 29 19:27 Info Service Control M... 7036 The description for Event ID '1073748860' in Source 'Service ... ...
4.	SHELLEXECUTE cannot anticipate the value or meaning of the return code that is passed back by a third-party process and this includes DOS, system shell and Powershell commands. Pipelines operates' on the principle that a zero return code indicates the success of a process and any other return code; indicates failure. This assumption will of course cause problems for a pipeline which uses the SHELLEXECUTE stage command when calling a process which does not adhere to this standard. As such, and, as a rule; you should check the documentation of the target process to determine the highest acceptable return code which indicates that the process has completed successfully; so that you can be sure that the SHELLEXECUTE stage is safe to continue. The process may or may not provide (a correct or meaningful) message or description of why it failed on either of its output streams and as such; Pipelines only provides the terminating return code in its output messages. It is not possible to predict the order in which records are read from the target process' STDOUT and STDERR streams. Pipelines cannot anticipate the order in which records are produced by a third-party process and as such the SHELLEXECUTE stage command will only produce output records as and when they become available. SHELLEXECUTE reads records from the process' STDOUT stream and writes them to its primary output stream, whilst reading records from the process' STDERR stream and writes them to its secondary output stream, if it is connected.
5.	If the SHELLEXECUTE stage discovers that its primary input stream is not connected; the SHELLEXECUTE stage ends. If the SHELLEXECUTE stage discovers that its primary output stream is not connected; SHELLEXECUTE stops reading output records from the process' STDOUT stream. Similarly, if the SHELLEXECUTE stage discovers that its secondary output stream is not connected; SHELLEXECUTE stops reading output records from the process' STDERR stream.
6.	SHELLEXECUTE verifies that its secondary input stream is not connected and then begins execution.

Examples

1.	Delaying a command
2.	Using SHELLEXECUTE
3.
4.
5.
6.

Related

CALLPIPE

History

Version	Date	Action	Description	Pipelines
1.3	27.12.2021	changed	Application-wide rewrite.	2.1
1.2	23.05.2011	added	The MAXRC synonym.	1.9
1.1	02.09.2010	changed	The stage has been re-designed and the only operand that can be specified on the stage command is the BATCH operand. All other operands, including the command to execute must be specified in a primary input stream record. Should an input record argument contain a syntax error or invalid data, or that the actual command fails to execute; SHELLEXECUTE will issue the appropriate error message, but it will continue to read, process and execute input record commands until it reaches end-of-file on its primary input stream.	1.8
1.0	30.06.2009	created	First version.	1.6