Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide

Building the Execution String for a COMMAND Action

The minimum requirements for a COMMAND action are two fields—ACTION and EXEC_STRING.

ACTION action_name
 {
     EXEC_STRING execution_string
 }

The execution string is the most important part of a COMMAND action definition. It uses syntax similar to the command line you would execute in a Terminal window but includes additional syntax for handling file and string arguments.

General Features of Execution Strings

Execution strings may include:

File and non-file arguments
Shell syntax
Absolute paths or names of executables

Action Arguments

An argument is information required by a command or application for it to run properly. For example, consider the command line you could use to open a file in Text Editor:

dtpad filename

In this command, filename is a file argument of the dtpad command.

Actions, like applications and commands, can have arguments. There are two types of data that a COMMAND action can use:

Files
String data

Using Shells in Execution Strings

The execution string is executed directly, rather than through a shell. However, you can explicitly invoke a shell in the execution string.

For example:

EXEC_STRING				\
 		/bin/sh -c \
 		'tar -tvf %(File)Arg_1% 2>&1 | \${PAGER:-more};\
 		echo "\\n*** Select Close from the Window menu to close ***"'

Name or Absolute Path of the Executable

If your application is located in a directory listed in the PATH variable, you can use the simple executable name. If the application is elsewhere, you must use the absolute path to the executable file.

Creating an Action that Uses No Arguments

Use the same syntax for the EXEC_STRING that you would use to start the application from a command line.

Examples

This execution string is part of an action that starts the X client xcutsel.
```
EXEC_STRING xcutsel
```

This execution string starts the client xclock with a digital clock. The command line includes a command-line option but requires no arguments.
```
EXEC_STRING xclock -digital
```

Creating an Action that Accepts a Dropped File

Use this syntax for the file argument:

%Arg_n%

%(File)Arg_n%

(File) is optional, since arguments supplied to Arg_n are assumed (by default) to be files. (See Interpreting a File Argument as a String for use of the %(String)Arg_n% syntax.)

This syntax lets the user drop a data file object on the action icon to start the action with that file argument. It substitutes the nth argument into the command line. The file can be a local or remote file.

Examples

This execution string executes wc -w using a dropped file as the -load parameter.
```
	EXEC_STRING wc -w %Arg_1%
```

This example shows a portion of a definition for an action that works only with directory arguments. When a directory is dropped on the action icon, the action displays a list of all the files in the directory with read-write permission.
```
	ACTION  List_Writable_Files
 	{
 	    ARG_TYPE     FOLDER
 	    EXEC_STRING /bin/sh -c 's -l %Arg_1% | grep rw-'
 	    …
 	}
```

Creating an Action that Prompts for a File Argument

Use this syntax for the file argument:

%(File)"prompt"%

This syntax creates an action that displays a prompt for a file name when the user double-clicks the action icon.

For example, this execution string displays a dialog box that prompts for the file argument of the wc -w command:

EXEC_STRING wc -w %(File)"Count words in file:"%

Creating an Action that Accepts a Dropped File or Prompts for One

Use this syntax for the file argument:

%Arg_n"prompt"%

%(File)Arg_n"prompt"%

This syntax produces an action that:

Accepts a dropped file as the file argument.

Displays a dialog box that prompts for a file name when the user double-clicks the action icon.

For example, this execution string performs lp -oraw on a dropped file. If the action is started by double-clicking the icon, a dialog box appears prompting for the file name.
```
EXEC_STRING lp -oraw %Arg_1"File to print:"%
```

Creating an Action that Prompts for a Non-File Argument

Use this syntax for the non-file parameter:

%"prompt"%

%(String)"prompt"%

(String) is optional, since quoted text is interpreted, by default, as string data. This syntax displays a dialog box that prompts for non-file data; do not use this syntax when prompting for a file name.

For example, this execution string runs the xwd command and prompts for a value to be added to each pixel:

EXEC_STRING xwd -add %"Add value:"% -out %Arg_1"Filename:"%

Interpreting a File Argument as a String

Use this syntax for the argument:

%(String)Arg_n%

For example, this execution string prints a file with a banner containing the file name, using the command lp -tbanner filename.

EXEC_STRING lp -t%(String)Arg_1% %(File)Arg_1"File to print:"%

Providing Shell Capabilities in an Action

Specify the shell in the execution string:

/bin/sh -c 'command'
/bin/ksh -c 'command'
/bin/csh -c 'command'

Examples

This execution string illustrates an action that uses shell piping.
```
	EXEC_STRING /bin/sh -c 'ps | lp'
```

This is a more complex execution string that requires shell processing and accepts a file argument.
```
	EXEC_STRING /bin/sh -c 'tbl %Arg_1"Man Page:"% | troff -man'
```

This execution string requires that the argument be a compressed file. The action uncompresses the file and prints it using lp -oraw.
```
	EXEC_STRING				/bin/sh -c 'cat %Arg_1 "File to print:"% | \
 					uncompress | lp -oraw'
```

This execution string starts a shell script.
```
	EXEC_STRING /usr/local/bin/StartGnuClient
```

Creating COMMAND Actions for Multiple File Arguments

There are three ways for actions to handle multiple file arguments:

The action can be run repeatedly, once for each argument. When an EXEC_STRING contains a single file argument and multiple file arguments are provided by dropping multiple files on the action icon, the action is run separately for each file argument.

For example if multiple file arguments are supplied to the following action definition:
```
	ACTION DisplayScreenImage
	{ 	
			EXEC_STRING					xwud -in %Arg_1%
 		…
 	}
```
the DisplayScreenImage action is run repeatedly.

The action can use two or more non-interchangeable file arguments. For example:
```
	xsetroot -cursor cursorfile maskfile  
```
requires two unique files in a particular order.

The action can perform the same command sequentially on each file argument. For example:
```
	pr file [file …]  
```
will print one or many files in one print job.

Creating an Action for Non-Interchangeable Arguments

Use one of the following syntax conventions:

If you want the action to prompt for the file names, use this syntax for each file argument:
```
	%(File)"prompt"%
```
Use a different prompt string for each argument.

For example, this execution string prompts for two files.
```
	EXEC_STRING				xsetroot -cursor %(File)"Cursor bitmap:"% \
 								%(File)"Mask bitmap:"%
```

To accept dropped files, use this syntax for each file argument:
```
	 %Arg_n%
```
using different values of n for each argument. For example:
```
	EXEC_STRING				diff %Arg_1% %Arg_2%
```

Creating an Action with Interchangeable File Arguments

Use one of the following syntax conventions:

To create an action that accepts dropped files and issues a command in the form command file 1 file 2 …, use this syntax for the file arguments:
```
	%Args%
```

To create an action that accepts multiple dropped files, or displays a prompt for a single file when double-clicked, use this syntax for the file arguments:
```
	%Arg_1"prompt"% %Args%
```
The action will issue the command in the form: command file 1 file 2 ….

Examples

This execution string creates an action that executes:
```
	pr file 1 file 2
```
with multiple file arguments.
```
	EXEC_STRING pr %Args%
```

This execution string creates an action similar to the previous example, except that the action displays a prompt when double-clicked (no file arguments).
```
	EXEC_STRING  pr %Arg_1"File(s) to print:"% %Args%
```

Creating an Action for Multiple Dropped Files

To accept multiple dropped file arguments and execute a command line in the form:

command file 1 file 2 …

use the syntax:

%Args%

Examples

This execution string executes a script named Checkout for multiple files:

	EXEC_STRING				/usr/local/bin/Checkout \
 								%Arg_1"Check out what file?"% %Args%

This execution string executes lp -oraw with multiple files:
```
	EXEC_STRING				lp -oraw %Arg_1"File to print:"% %Args%
```