cfexecute

Description

Executes a ColdFusion developer-specified process on a server computer.

Category

Syntax

<cfexecute 
    name = "application name"
    arguments = "command line arguments"
    outputFile = "output filename"
    timeout = "timeout interval"
    variable = "variable name">
    ...
</cfexecute>

Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

History

ColdFusion MX 6.1:

Added the variable attribute.
Changed filepath behavior for the outputFile attribute: if you do not specify an absolute filepath in the outputFile attribute, the path is relative to the ColdFusion temporary directory.

Attributes

Attribute	Req/Opt	Default	Description
name	Required		Absolute path of the application to execute. On Windows, you must specify an extension, for example, C:\myapp.exe.
arguments	Optional		Command-line variables passed to application. If specified as string, it is processed as follows: Windows: passed to process control subsystem for parsing. UNIX: tokenized into an array of arguments. The default token separator is a space; you can delimit arguments that have embedded spaces with double-quotation marks. If passed as array, it is processed as follows: Windows: elements are concatenated into a string of tokens, separated by spaces. Passed to process control subsystem for parsing. UNIX: elements are copied into an array of exec() arguments.
outputFile	Optional		File to which to direct program output. If no `outputfile` or `variable` attribute is specified, output is displayed on the page from which it was called. If not an absolute path (starting a with a drive letter and a colon, or a forward or backward slash), it is relative to the ColdFusion temporary directory, which is returned by the `GetTempDirectory` function.
timeout	Optional	0	Length of time, in seconds, that ColdFusion waits for output from the spawned program. 0: equivalent to nonblocking mode. A very high value: equivalent to blocking mode. If the value is 0: ColdFusion starts a process and returns immediately. ColdFusion may return control to the calling page before any program output displays. To ensure that program output displays, set the value to 2 or higher. If the `outputFile` attribute is not specified, any program output is discarded
variable	Optional		Variable in which to put program output. If no `outputfile` or `variable` `attribute` is specified, output is displayed on page from which it was called.

Usage

Do not put other ColdFusion tags or functions between the start and end tags of cfexecute. You cannot nest cfexecute tags.

Exceptions

Throws the following exceptions:

If the application name is not found: java.io.IOException
If the effective user of the ColdFusion executing thread does not have permissions to execute the process: a security exception

The time-out values must be between zero and the longest time-out value supported by the operating system.

Example

<h3>cfexecute</h3>
<p>This example executes the Windows NT version of the netstat network monitoring program, and places its output in a file.

<cfexecute name = "C:\WinNT\System32\netstat.exe"
    arguments = "-e" 
    outputFile = "C:\Temp\output.txt"
    timeout = "1">
</cfexecute>

Comments

-==cfSearching==- said on Jan 7, 2008 at 1:24 AM :

It has been suggested that cfexecute captures only stdout and not stderr, and that failure to capture stderr may cause problems. Is this correct and if so is there a fix?

halL said on Jan 7, 2008 at 7:22 AM :

-==cfSearching==- is correct. Here is what Ben Forta said about it in his blog:

The <cfexecute> tag captures output (which can be returned, or saved to a variable or file). But only stdout output is captured, not stderr, and so if the command you are executing generates error messages to stderr you'll not see those in the captured output. The solution is to redirect stderr to stdout, if you are using Windows you can do this by adding the following to the end of the command to be executed: 2>&1

-==cfSearching==- said on Jan 8, 2008 at 12:11 AM :

Thank you for the additional information. A few other observations:

1. Another windows tip from Ben Forta's blog mentions using the /c flag to tell "the command interpreter to run and terminate upon completion ..". The example below obtains the java version. It is for demonstration purposes only. A better option is to use java.lang.System properties.

<cftry>

<cfexecute name="c:\winnt\system32\cmd.exe"
arguments="/c java.exe -version"
variable="results"
timeout="6" />

<cfdump var="#results#">
<cfcatch>
<cfdump var="#cfcatch#">
</cfcatch>
</cftry>

2. In my testing, some programs appear to require both /c AND the redirect 2>&1 or they do not exit properly. If either option is omitted, CF does return a response, when the allotted time had elapsed, but it may leave processes running in the Task Manager until the CF Server is restarted. With these programs I have observed the following:

a) If you use a redirect, but omit the /c flag, an instance of CMD.EXE
remains running in the Task Manager until the CF Server is restarted

b) If you use the /c flag, but omit the redirect, both CMD.EXE and
the process may remain running in the Task Manager until the CF
Server is restarted

These processes will execute and terminate normally only when both options are used.

3. If cfexecute does not complete in the allotted "timeout", CF will return a timeout message, but it does not appear to kill the running process. The process continues running until completion.

This behavior makes sense when using timeout="0" (ie Do not wait. Return immediately ). But it would be nice if there were a killOnTimeout option. I was able to achieve this using Runtime.exec and cfthread, but a built in option for cfexecute might be a nice feature.

DCwebGuy said on Jul 17, 2008 at 8:03 PM :

errorVariable parameter, which is new for 8.1, needs to be documented here.

rspitzmd said on Aug 14, 2008 at 1:53 PM :

Hello Adobe Team,

can the LiveDocs be updated to include the new attributes "errorFile" and "errorVariable", introduced with Coldfusion 8.0.1, which serve exactly the purpose of catching stderr?

I expected the "Live"Docs to be more up to date than the printed documentation, but apparently they aren't.

halL said on Aug 18, 2008 at 12:47 PM :

We hope to get the Livedocs updated some time soon with the 8.0.1 changes.

In the interim, here is the information from the Release Notes.
------------------------------------------

The cfexecute tag has two new attributes for accessing the error stream of the executed
process. You can use either of the following attributes, but you cannot use both in the same
tag.
• errorVariable The name of a variable in which to save the error stream output.
• errorFile The pathname of a file in which to save the error stream output. If not an
absolute path (starting a with a drive letter and a colon, or a forward or backward slash), it is
relative to the ColdFusion temporary directory, which is returned by the GetTempDirectory
function.

Adobe ColdFusion 8

cfexecute

Comments