Differences

This shows you the differences between two versions of the page.

--- transformations:runprogram [2018/06/27 14:47] – dmitry
+++ transformations:runprogram [2021/07/19 01:59] (current) – [Examples] craigt
@@ Line 1: / Line 1: @@
-===== Run program =====
+{{ transformations:RunProgramAction.png}}
+====== RUN PROGRAM ======
+Category: Workflow / External\\
-Run specified external application, and wait until it finishes.
+\\
+=====Description=====
+This action runs a specified external application and waits until it finishes.
 If no external application is provided the command line is executed by the Windows shell (cmd.exe).
-The transformation fails if the exеrnal application returns a non-zero exit code.
+The action fails if the extеrnal application returns a non-zero exit code.
-===Use cases===
+\\
+=====Use cases=====
   * Run external applications (e.g. after a file is generated by EasyMorph).
   * Execute Windows shell commands (copy, del, ren, etc.).
   * Run other EasyMorph projects in order to make them generate reports.
+\\
+=====Action settings=====
+^ Setting  ^ Description  ^
+|Application<sup>*</sup>|Enter or browse to the fully qualified path and filename of the program's executable file.  If this is left blank,\\ the command line is executed by the Windows shell (cmd.exe).|
+|Working directory (optional)<sup>*</sup>|Enter the folder containing any files required by the application.|
+|Arguments|Enter the values, filenames, commands, etc. passed to the application as either static text or a calculated\\ string.  Options:  //Text// or //Calculated//.  See the table below for details.|
+|Halt if exit code is not 0|When this is checked, the workflow will stop and display an error if the run program terminates with an error.|
+|Capture output|When checked, EasyMorph will capture any returned data in a dataset (e.g., to see errors).  See the\\ "Capturing output" section below under "Remarks" for more information.|
+<sup>*</sup> Setting can be specified using a [[:parameters|parameter]].\\
-===Capturing output===
+\\
-It is possible to capture STDOUT and STDERR of the executed external application or Windows shell command. For instance it is possible to run //dir// and capture its output as a table in EasyMorph, or forward output of an application into EasyMorph without creating a temporary intermediate CSV file. STDERR is captured in a separate column, which can later be used for error-handling routines. Since EasyMorph also outputs errors into STDERR this feature can be used for error handling of EasyMorph projects executed in the command line mode.
+====Argument options====
+^ Option  ^ Description  ^
+|Text|Enter static text arguments.|
+|Calculated|Enter an expression to calculate the argument string.|
+Incorporating parameters is supported in both options (e.g., {MyParam}).  See the "Parameter substitution" section below under "Remarks" for more information about using parameters in arguments.
-===Parameter substitution===
+\\
-The transformation allows defining its command line as a text or as a calculated expression. It is possible to insert [[:parameters]] into text. For instance:
+=====Remarks=====
+====Parameter substitution====
+The action allows defining its command line as static text or as a calculated expression. It is possible to insert [[:parameters]] into text. For instance:
   copy /Y {SourceFileName} {DestinationFileName}
-The command line above is equivalent to the calculated expression below, but is easier to use.
+The command line above is equivalent to the calculated expression below but is easier to use.
 	“copy /Y “ & {SourceFileName} & “ “ & {DestinationFileName}
@@ Line 26: / Line 47: @@
 //SourceFileName// and //DestinationFileName// are parameter names.
+\\
+====Capturing output====
+It is possible to capture STDOUT and STDERR of the executed external application or Windows shell command. For instance, it is possible to run //dir// and capture its output as a table in EasyMorph, or forward the output of an application into EasyMorph without creating a temporary intermediate CSV file.
+STDERR is captured in a separate column, which can later be used for error-handling routines. Since EasyMorph also outputs errors into STDERR this feature can be used for error handling of EasyMorph projects executed in the command line mode.
+\\
+=====Examples=====
+**Example 1:**  Running the external 7-Zip program to unzip a file or files.
+**Action parameters:**
+> Application "C:\Program Files (x86)\7-Zip\7z.exe" (the full path and name of program executable)
+> Working directory is "C:\Zipped files" (the folder the application will find the file(s) to be unzipped)
+> Calculated argument '' ' e "' & {File name} & '" -y -aoa' '' (the argument string required by 7-Zip to decompress the file(s); note {File name} is an EasyMorph parameter)
+> Halt if exit code is not 0 is checked (the workflow will stop with an error if 7-Zip does not complete correctly)
+{{  https://easymorph.com/images/learn/unzip-file.png  }}
+\\ \\
+**Example 2:** Run the Windows shell command to copy a file.
+**Action parameters:**
+> Application is left blank (the Windows shell will run the command below)
+> Calculated argument is the shell command:  '' 'copy /Y "' & {Old location} & '" "' & {New location} & '"' ''  (note {Old location} and {New location} are EasyMorph parameters)
+> Hard if exit code is not 0 is checked (the workflow will stop with an error if the copy command does not complete successfully)
+{{  https://easymorph.com/images/learn/file-copy.png  }}
+\\
+====Community examples====
+  * [[https://community.easymorph.com/t//1398/1|How to obtain a list of all files recursively]] ([[https://community.easymorph.com/uploads/short-url/p5eGkU5ftaJpBXTfGbLxLte2VPX.morph|Project]]; Module: //Main//; Group: //Tab 1//; Table: //Table 1//; Action position: //1//)
+  * [[https://community.easymorph.com/t//1755/9|EasyMorph 4.3 : Tableau Hyper Addon logs]] ([[https://community.easymorph.com/uploads/short-url/22W0a67rOyb81dAD8zNmISfuMDK.morph|Project]]; Module: //Main//; Group: //Tab 1//; Table: //Convert DSET file to Hyper file//;\\ Action position: //4//)
+  * [[https://community.easymorph.com/t//2653/1|Extracting all projects published in the Community and their actions]] ([[https://community.easymorph.com/uploads/short-url/mrnJQUJJL8Do1T8ioicyzE1VgmK.morph|Project]]; Module: //Main loop//; Group: //Group 1//; Table: //Actions//; Action position: //6//)
+\\
+=====See also=====
+  * [[transformations:iterateprogram|Iterate program]]
+  * [[https://easymorph.com/learn/external-programs.html|Tutorial:Executing external programs]]
-===See also===
-[[https://easymorph.com/learn/external-programs.html|Tutorial:Executing external programs]]