tellxdt3(XC)

tellxdt3 -- Desktop to UNIX shell communications utility

Syntax

tellxdt3 [options] [script]

Description

You can communicate with the Desktop from other applications or shell scripts using the program tellxdt3, located in /usr/bin/X11. You specify a Deskshell script to perform, and tellxdt3 will return any results from that script.

Options

The options you can set fall into two groups: those that specify which Desktop should run the script, and those that process the results. There are also some special options.

The option -- indicates the end of the options. Normally the end is indicated by an argument which is not the parameter of another option and does not begin with a dash.

Special options

If you specify any of these options, no other options are allowed and there must be no script.

-version: print the version number of tellxdt3, and exit
-verboseVersion: print a verbose form of the version, and exit
-usage or -help: print a usage message, and exit

Which Desktop to connect to

The following options control the connection to the Desktop:

-display display: connect to a Desktop running on the specified display. If this is not specified, the value of the environment variable DISPLAY is used.
-list: List the name of every Desktop running on the display, one per line, on standard output. You may specify the -display option with -list to list every Desktop running on that display.
-name name: connect to the Desktop with the specified name. The name of an instance of the Desktop is returned by the -list option, and is also stored in the Deskshell variable :Xdesktop_name.
-all: connect to all Desktops on this display, or on the display given by the -display option. It is not defined in which order the connections take place. The output from each Desktop, in sequence, will form the output from the complete command. The status will be the status from the last Desktop involved.
-wait: if the Desktop is not running, wait for it to start. By default, an error is returned in this case.
-secure code: use the primary security code code when connecting. If the *xqpSecurityEnabled resource is set to ``TRUE'', connections will fail if code does not match the primary security code for the specified instance of the Desktop.

If neither -name nor -all is specified, tellxdt3 will connect to a Desktop at random.

Processing the results

A Deskshell script returns a list of strings and a status. These strings are written to standard output; each string is surrounded by a prefix string and a suffix string, and separated by a delimiter string. Options allow the number of strings to be written to standard output, and the status to be written to standard output or standard error.

-prefix prefix: use prefix as the prefix string (default is none)
-suffix suffix: use suffix as the suffix string (default is none)
-delim delim: use delim as the delimiter string (default is a single newline)
-delimZero: use a zero byte as the delimiter string
-printCount: print the number of strings output (followed by a newline) to standard output, before the first string
-printStatus: print the status then possibly a text description (followed by a newline) to standard output, before both the first string and the output from -printCount, if specified
-reportStatus or -printReturn: as -printStatus, except that the line is written to standard error

Exit codes

The exit code is based on the status of the last (or only) script executed.

Returned status Exit code

0 0

1 to 255 1

256 to 511 2

512 to 767 3

768 to 1023 4

Other error 127

Returned status	Exit code
0	0
1 to 255	1
256 to 511	2
512 to 767	3
768 to 1023	4
Other error	127

Example

In the following example, the Bourne shell script uses tellxdt3 to trigger an icon:

#!/bin/sh # Send a trigger to the Desktop

if [ $# -ne 2 ] then echo "Usage: $0 triggername pathname" else tellxdt3 "actions_of $1 $2" fi

To use it, you would enter a command such as:

trigger activate $HOME

at a terminal prompt, assuming the script was named trigger.

Note that this example requires the tellxdt3 program to be on your PATH.