Pipelines stage - SHELLEXECUTE

SHELLEXECUTE stage v1.2

Pipelines v2.0

Purpose, Operands, Input record format, Streams used, Usage notes, Examples, See also

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 STDERR 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’ STDERR 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 returncode. Zero is the default.

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

●

command

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

Streams used

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 notes

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 ** 01 Address Rxpipe 02 03 ‘pipe (endchar ?)’, 04 ‘literal /powershell ps/ ‘, 05 ‘\| shell’, 06 ‘\| a: drop 3’, 07 ‘\| locate anycase w-1 /svchost/’, 08 ‘\| b: faninany’, 09 ‘\| 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 commandline: mypipe.rex Top of file 01 Address Rxpipe 02 03 ‘pipe lit /powershell get-eventlog system/’, 04 ‘\| shell’, 05 ‘\| cons’ 06 07 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 returncode 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 returncode indicates the success of a process and any other returncode; 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 returncode 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 returncode 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

Using SHELLEXECUTE

See also

None.

History of change

Version	Action	Description

1.1	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.2	Added	The MAXRC synonym.