cfexecute

Description

Enables ColdFusion developers to execute a process on a server computer.

Syntax


<cfexecute name = " ApplicationName "

  arguments = "CommandLine Arguments"

  outputFile = "Output file name"

  timeout = "Timeout interval in seconds">

  ...

</cfexecute>

Attributes

Attribute

Description

name
Required. The full pathname of the application to execute.
Note: On Windows, you must specify the extension as part of the application's name. For example, myapp.exe,

arguments
Optional. Command-line arguments passed to the application.
If arguments is specified as a string, it is processed as follows:

On Windows, the entire string is passed to the Windows process control subsystem for parsing.

On UNIX, the string is tokenized into an array of arguments. The default token separator is a space; arguments with embedded spaces may be delimited by double quotes.

If arguments is passed as an array, it is processed as follows:

On Windows, the array elements are concatenated into a string of tokens, separated by spaces. The string is passed to the Windows process control subsystem for parsing.

On UNIX, the elements of the arguments array are copied into a corresponding array of exec() arguments.

outputFile
Optional. The file to which to direct the output of the program. If not specified, the output is displayed on the page from which it was called.

timeout
Optional. Indicates how long, in seconds, the ColdFusion executing thread waits for the spawned process. A timeout of 0 is equivalent to the non-blocking mode of executing. A very high timeout value is equivalent to a blocking mode of execution. The default is 0; therefore, the ColdFusion thread spawns a process and returns without waiting for the process to terminate.
If no output file is specified, and the timeout value is 0, the program output is discarded.

Attribute	Description
name	Required. The full pathname of the application to execute. Note: On Windows, you must specify the extension as part of the application's name. For example, myapp.exe,
arguments	Optional. Command-line arguments passed to the application. If `arguments` is specified as a string, it is processed as follows: On Windows, the entire string is passed to the Windows process control subsystem for parsing. On UNIX, the string is tokenized into an array of arguments. The default token separator is a space; arguments with embedded spaces may be delimited by double quotes. If `arguments` is passed as an array, it is processed as follows: On Windows, the array elements are concatenated into a string of tokens, separated by spaces. The string is passed to the Windows process control subsystem for parsing. On UNIX, the elements of the `arguments` array are copied into a corresponding array of exec() arguments.
outputFile	Optional. The file to which to direct the output of the program. If not specified, the output is displayed on the page from which it was called.
timeout	Optional. Indicates how long, in seconds, the ColdFusion executing thread waits for the spawned process. A timeout of 0 is equivalent to the non-blocking mode of executing. A very high timeout value is equivalent to a blocking mode of execution. The default is 0; therefore, the ColdFusion thread spawns a process and returns without waiting for the process to terminate. If no output file is specified, and the timeout value is 0, the program output is discarded.

Usage

cfexecute is available on Windows NT 4.0 and UNIX platforms. Do not put other ColdFusion tags or functions between the start and the end tags of cfexecute. The cfexecute tags cannot be nested.

Exception

cfexecute throws the following exceptions:

If the application name is not found: Application File Not Found exception
If the output file cannot be opened: Output File Cannot exception
If the effective user of the ColdFusion executing thread does not have permissions to execute the process, a security exception is thrown.
The time out values must be between 0 and the longest time out value supported by the operating system.

Example

<!---------------------------------------------------------------------

This example illustrates use of the cfexecute tag. 

---------------------------------------------------------------------->

<html>

<head>

<title>cfexecute</title>

</head>



<body>

<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>



</body>

</html>