SHELLEXECUTE stage v1.2

Pipelines v1.9

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

Home

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 from within a pipeline script and directly from the command line. Consider the following example; which selects only SVCHOST system process entries from the Powershell command output: pipe (endchar ?) literal /powershell ps/ | shell | a: drop 3 | locate anycase w-1 /svchost/ | b: faninany | cons ? a: | take * | b: The pipeline above produces the following output: 06/07/2009 21:09:42 begin.. 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 06/07/2009 21:09:43 end..(rc:0) Press ENTER to close... And, consider this example of a Powershell command issued from the command line: Windows PowerShell Copyright (C) 2006 Microsoft Corporation. All rights reserved. PS C:\Users\TenFiftyTwo> pipe "lit /powershell get-eventlog system/ | shell | cons" 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 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.