test

Common Desktop Environment: Help System Author's and Programmer's Guide

Execution Link Control

Most hyperlinks display a related help topic, but hyperlinks can also execute shell commands and scripts. Links of this type are called execution links. Because execution links interact with a user's system, the Help System provides an execution policy to control how execution links are handled.

The Help System uses resources to define the behavior of execution links. The DtNexecutionPolicy resource is set in an application's application defaults file to modify how execution links are handled by the Help System. In addition the Help System uses a set of resources called execution aliases. An execution alias is a resource that assigns a name (or label) to the command string or script that an execution link executes.

Execution Policy Default Behavior

When an execution link is selected, if the link has an execution alias, the Help System retrieves the value of the alias and executes the command. If an execution alias has not been defined, the Help System displays a confirmation dialog box that shows the command to be executed and asks the user whether to execute the command or to cancel the operation.

Execution Aliases

When using execution links in a help volume, it is recommended to create execution aliases. That is, in the application's application defaults file you define an alias (a name) that represents the actual command to be executed. One advantage of this method is that it isolates the actual commands from the help volume source files. This makes it possible to edit the commands in the application defaults file without changing the hyperlinks in the help volume. Each hyperlink references an alias name, which remains unchanged even though its content may have been edited. For instance, a tutorial help volume that uses scripts could be easily customized to accommodate a particular shell environment by modifying the shell script commands in the application defaults file.

To Create an Execution Alias

To create an execution alias in an application's application defaults file, use this resource specification syntax:

application_name.executionAlias.alias_name: command

Where:

application_name

Name or class name of the application that owns the help volume

executionAlias

Keyword that identifies the resource is an alias

alias_name

Name assigned to the command

command

Shell command or script to be executed for this link

There is no restriction on the length of the command string. To enter commands with multiple lines, end each line (except the last) with a \ (backslash).

Examples

This resource entry creates an execution alias named, StartDtterm, which starts a terminal emulator. The & (ampersand) starts the command in the background.

Dtterm.executionAlias.StartDtterm: dtterm &

This entry creates an alias named, xclockAlias, that executes the xclock application in an application named NightAlert.

NightAlert.executionAlias.xclockAlias: xclock &

Using Execution Aliases in Hyperlinks

An execution alias can be referenced using the <link> element or used in conjunction with elements that have a hyperlink parameter, such as <p> or <figure>.

To Create an Execution Link Using an Execution Alias

    Use the <link> element as shown: 

<link "DtHelpExecAlias alias_name [default_command]" Execute >text<\link>

Where:

DtHelpExecAlias

Keyword that identifies this link has an execution alias

alias_name

Name defined as an alias in the execution alias resource specification

default_command Optional.

If provided, this command is executed when an execution alias has not been loaded from an application's application defaults file. For example, application resources are not loaded when a help volume is displayed from an information viewer, such as Help View.

text

The portion of your help text that you want to designate as the hyperlink text (underlined)

Note -

If the command you are executing doesn't finish immediately, run it in the background by appending an &(ampersand) to the command. If you don't, the help window will not operate until the command finishes.

Examples

This hyperlink references the execution alias named, xclockAlias. The resource definition for the alias is shown in the section "Execution Aliases".

The link starts the xclock program running in the background. The phrase "Start the Clock" becomes the hyperlink. Clicking the hyperlink runs the xclock program in a separate window. To end the program, close the window.

<link "DtHelpExecAlias xclockAlias" Execute>Start the Clock<\link>

Here is the same hyperlink including an optional default command.

<link "DtHelpExecAlias xclockAlias xclock &" Execute>Start the Clock<\link>

DtNexecutionPolicy Resource

The DtNexecutionPolicy resource enables a system administrator or user to select an appropriate level of security for a given application.

The resource values that can be set are:

help_execute_query_all

Query all execution links.

help_execute_query_unaliased

Query only link commands that do not have execution aliases defined.

help_execute_none

Do not execute any execution links.

help_execute_all

Execute all execution links.

The default value is help_execute_query_unaliased. Any execution links defined as execution aliases will be automatically executed, whereas the Help System will display a confirmation dialog box for any other execution links.

It is not recommended for the application developer to set the DtNexecutionPolicy because this prevents a system administrator or user from altering the value.

See Also