HP OpenVMS Systems Documentation

Content starts here Getting Started With the New Desktop

Getting Started With the New Desktop

Previous Contents Index

Chapter 4
Integrating Applications Into the New Desktop

This chapter provides information about the following topics:


The integration of applications is not required. You can run any existing DECwindows application from the New Desktop without making any changes to it.

4.1 Minimal Integration

Minimal integration enables an application to be launched from the CDE desktop with one or more associated actions. To enable this to happen, certain application configuration files are required. You can achieve minimal integration for most applications by using the Create Action application to create the following configuration files for each application:

  • Icon file
  • Action and data type definition file
  • Action (stub) file

For some applications, you cannot complete minimal integration with Create Action. For example, you cannot use Create Action to create the action for an application if the command line requires a nonfile argument, such as a parameter. Nor can you use Create Action for an application if the data type must have actions associated with it other than Open and Print. In general, you can use Create Action to create the files you need for minimal integration and then edit the files to supply additional information that you cannot supply with Create Action. In some cases, you must create new files with your editor.

4.1.1 CDE Action Terminology

To understand the process of creating configuration files for integrating applications, it is important to understand how the following terms are used in the CDE interface and documentation:

  • Action
    Action refers to what happens to an application when you double click on its icon in Application Manager or File Manager. The association of the application's configuration files with the application files enables this action to happen. The Action Name field of Create Action is the name that will appear on the icon you select for the application.
  • Action definition file
    This file contains the definitions of actions and, optionally, definitions of any data types that you want to associate with an application. When this file contains data type definitions, it is sometimes referred to as an action and data type definition file.
    The action definition file for the Man Page Viewer, DTMANPAGEVIEW.DT, follows:

    ACTION dtmanpageview
    LABEL           Man Page Viewer
    ARG_COUNT       0
    ICON            Dthover
    TYPE            COMMAND
    EXEC_STRING     cde$system_defaults:[bin]dthelpview -man \
                    -xrm "Dthelpview*manBox*columns: 100"
    DESCRIPTION     The Man Page Viewer (Dtmanpageview) action \
                    displays a man page in a Quick Help viewer window.
  • Action (stub) file
    An action (stub) file is a file that the CDE software requires for every action definition file. An action file associates an action definition file with its icon file, making it possible for the icon to be visible within File Manager and Application Manager. An action file has the same name as the action definition file but lacks the DT extension. For example, DTMANPAGEVIEW. is the action file for DTMANPAGEVIEW.DT.

4.1.2 Creating Action Definition Files on OpenVMS Alpha

When creating action definition files for integrating an application, either with the Create Action application or directly with an editor, you must observe the following requirements on OpenVMS Alpha:

  • Icon names
    If the action specified for your application will be displayed as an icon in an Application Manager group, the action name must contain only valid OpenVMS file name characters and must be all lowercase. Create Action automatically lowercases the action name for you.
  • Command line for running an application
    The Command When Action Is Opened field of the Create Action application produces the EXEC_STRING in the action definition file. This field must contain a valid OpenVMS command line. If the command line begins with $, RUN, or MCR followed by a space, or if it begins with @, the command is processed as a DCL command without interpretation. If the command line begins with a valid OpenVMS or UNIX file specification, a foreign command is automatically generated. In addition, all of the command line options are implicitly quoted in order to preserve their case.
    If the command line begins with only a file name (no device or directory), then the following default execution directories are assumed:

    The logical name CDE$PATH is defined as a search list that points to these directories. If the file does not exist, the command is processed as an uninterpreted DCL command.
  • Arguments in the command line
    File arguments in the command line can be specified with Create Action. When you enter arguments using Create Action, you specify with the syntax $n, with $1 representing argument 1, $2 representing argument 2, and so forth in the Command When Action is Opened field. You represent all remaining arguments with $*. (For more information about specifying arguments, see Chapters 9 and 10 in the Common Desktop Environment: Advanced User's and System Administrator's Guide.)

Create Action has the following limitations with regard to specifying arguments:

  • It does not support prompt strings without an associated argument.
  • It provides a way to enter a prompt string for only the first argument using the Advanced option When Action Opens, Ask User For field.
  • It does not provide a way to specify the data type for an argument.
  • You cannot include the CWD keyword in your action to set a default directory.

When you specify arguments, you must be sure to use the correct argument type. By default, prompted arguments (syntax: %"prompt string"%) are of type String, and explicit arguments (syntax: %Arg_n["optional prompt string"]%) are of type File. If you do not want the default argument type, you can specify a different type by using either of the following expressions:

%(File)"prompt string"%

The %Args% keyword is similar to the %Arg_n% keyword except that the former is replaced with a list of arguments, separated by spaces, that is passed to the action. Whether or not this is appropriate depends on the specific DCL command.

4.1.3 Create Action Overview

As described in Chapter 9 of the Common Desktop Environment: Advanced User's and System Administrator's Guide, Create Action does the following:

  • Creates an action definition that runs a command.
  • Creates a file disk$:([user.DT.TYPES]action-name.DT. This file stores the action and data type definitions created for the application.
  • Creates an action file in the user's home directory. The action file is an executable file with the same name as the action.
    The action file's representation in File Manager is called an application icon. Double clicking on the application icon starts the application.
    When you create the action, you can make the action icon a drop zone by specifying data types that you can drop on the icon (optional).
  • Creates one or more data types for the application's data files (optional).
  • Creates an Open action for each data type.
  • Creates a Print action for each data type (optional).
  • Reloads the database of actions and data types. This makes the actions and data types take effect immediately.

4.1.4 Integrating Applications Using Create Action

You can access the Create Action application from the Desktop Tools application group in Application Manager. Figure 4-1 shows the main window of the Create Action application.

Figure 4-1 Create Action Main Window

Additional fields are displayed if you select the Advanced option, which is located in the lower left corner of the Create Action main window. These additional fields are shown in Figure 4-2. Table 4-1 describes each field in the Create Action main window and in the expanded (Advanced option) window.

Table 4-1 Create Action Fields
Field Name Purpose
Initial Fields
Action Name (Icon Label): This label is displayed next to the icon for the application.
Action icon: This icon represents the application. With Find Set..., you can select an icon from the collection that is included with the New Desktop. With Edit Icon..., you can modify an existing icon or create a new one.
Command When Action Is Opened (Double-clicked): The name of the application you want to access. This name can specify one or more file arguments as operands. The arguments must be specified in the format $ filename . For example: DIFF $1 $2 .
Help Text for Action Icon: This help becomes the On Item help for the Action Icon. The text automatically wraps in the text field. You can explicitly add a continuation line by ending a line with a space, a backslash (\), and Return. If the backslash is not present, subsequent lines will not be displayed.
Window Type: Select the windowing support option required by the application. You have a choice of three types of windows or no window.
Advanced Select this field if your application uses data files and you want to create one or more data types for them. The Create Action window expands to display additional, advanced fields.
Advanced Option Fields
When Action Opens, Ask Users for: Supply a prompt if the application's command line has a required or optional file argument. Otherwise, leave it blank.
Datatypes That Use This Action: If the action can accept any data type, select All Datatypes. If you want to modify any existing data types or create new ones, select Only Above List and then select Add. (Initially, the Datatypes That Use This Action list is empty.) When you select Add, a dialog box called Add Datatypes is displayed.

Figure 4-2 Create Action Main Window With Advanced Option Fields

4.1.5 Creating or Modifying Data Types Using Create Action

The Create Action application provides the Add Datatype dialog box for modifying an existing data type or creating a new one. The Add Datatype dialog box is shown in Figure 4-3, and the fields are described in Table 4-2.

Figure 4-3 Add Datatype Dialog Box

Table 4-2 Create Action: Add Datatype Dialog Box
Field Purpose
Name of Datatype Family: If you want to modify an existing data type and retain the same name, leave this field blank. If you want to create a new data type, supply a name. (The name cannot include spaces. The name is not visible to application users; it is used in the actions/data types database to identify the data type definition.)
Identifying Characteristics: To display the Identifying Characteristics dialog box, click on the Edit button.
Help Text for this Datatype Icon: This help becomes the On Item help for the Action Icon.
Datatype Icons: With Find Set..., you can select an icon from the collection that is included with the New Desktop. With Edit Icon..., you can create a new icon or modify an existing one.
Command to Open this Datatype: This command is the same that you supplied for Command When Action is Opened (Double-clicked): and will appear in this field.
Command to Print this Datatype: Enter the Print Dialog command line to suit the application data type.

After you respond to the second prompt, Identifying Characteristics, by clicking on the Edit... button, the Identifying Characteristics dialog box is displayed, as shown in Figure 4-4. The fields of this dialog box are described in Table 4-3.

The characteristics are displayed in the Identifying Characteristics field of the Add Datatype dialog box, using the following codes:

  • d --- A directory.
  • r --- The file has read permission.
  • w --- The file has write permission.
  • ! --- Logical operator NOT.
  • & --- Logical operator AND.

Figure 4-4 Identifying Characteristics Dialog Box

Table 4-3 Create Action: Identifying Characteristics Dialog Box
Field Purpose
Files, Folders The data type applies only to files or only to folders.
Name Pattern: Data typing based on the file name.
Permissions Pattern: Read, write, execute, or delete permission. The Either option for these permissions means that the permission does not matter. The permissions testing does not recognize OpenVMS access control lists (ACLs).
Contents: A pattern to search for, the type of contents, and an optional starting point in the file. Note that this feature can carry a substantial performance penalty when changing or updating views.

4.1.6 Editing Icons From the Create Action Application

If you invoke the Icon Editor from the Create Action application and edit an icon file, the edits that you make are not automatically shown in the displayed icon when you exit from Icon Editor. After exiting from Icon Editor, you must choose Find Set... and select the newly edited icon to change the display and associate the edited icon with the action.

If you want to edit more than one size of the icon, make all the edits before you select Find Set. If you do not have a complete set of edited icons when you select Find Set..., the missing icons will not be displayed and you will not be able to create them from within the Create Action application.

4.2 Recommended Integration

Recommended integration means that an application is integrated with other CDE components, making it more consistent with the CDE desktop. Recommended integration includes making the following enhancements to your application:

  • Providing convenience functions in an application, such as the drag-and-drop function and the save/restore function (see Chapter 5)
  • Providing for the internationalization of an application
  • Displaying CDE style error messages
  • Using the fonts provided with CDE (see Chapter 5)
  • Incorporating CDE style help (see Chapter 5)

Recommended integration will likely require code changes. This section briefly describes the resources for providing user interfaces in different languages and CDE style error messages. Chapter 5 describes the programming resources for providing the other enhancements.

4.2.1 Internationalization

The New Desktop provides user interfaces in different languages. The language and other culture-specific attributes, such as the symbols and rules for formatting monetary numeric information and dates, are defined in a file called a locale. Each locale is supported by a message catalog, which contains all the text an application will output for a particular language, and by resource files. The DEC C XPG4 localization utilities, briefly described in Table 4-4, are used to create locale files and message catalogs.

Users can specify the language of the user interface when they log in. From the login display, select Options, then select Language. The languages installed on your system, as defined in the locale files, are displayed. You can then select the language for the user interface on your system.


The default locale is the C locale. The notation .lang is used in file specifications in this manual to indicate the locale variable. In the CDE documentation, %L and <lang> are used to indicate the locale variable.

Table 4-4 DEC C XPG4 Localization Utilities
Utility Purpose
GENCAT Merges one or more message-text source files into a message catalog file. The message-text source files use a default file type of .MSG. The message catalog file uses a default file type of .CAT. The GENCAT syntax is:
GENCAT msgfile [,...] catfile

ICONV Depending on the option that you specify, ICONV either compiles conversion table files (ICONV COMPILE) or converts characters from one codeset to another (ICONV CONVERT). A conversion table file defines how characters in one codeset are converted to characters in another codeset.
LOCALE Depends on the option that you specify:
  • LOCALE COMPILE compiles a binary locale file.
  • LOCALE LOAD loads a locale name into system memory as shared, read-only global data.
  • LOCALE SHOW displays details of locales on your system.
  • LOCALE UNLOAD unloads a locale name from system memory.

The locale files are in the directory defined by the logical name SYS$I18N_LOCALE. For more information about the DEC C XPG4 localization utilities, see the OpenVMS Version 6.2 New Features Manual or the OpenVMS Version 7.0 New Features Manual.

4.2.2 Displaying Error Messages From Applications

New Desktop applications follow a common model for presenting error messages and warnings. Users expect messages to be displayed in message footers, error dialog boxes, or warning dialog boxes, with further explanations in online help, when appropriate. For details about displaying error messages in applications and linking message dialogs to online help, see the Common Desktop Environment: Programmer's Guide.

4.3 Optional Integration

Optional integration enables you to leverage CDE services to perform specialized tasks, such as providing certain graphical user interface functions and managing multiple workspaces. Custom widgets provide the specialized graphical user interface functions. The Workspace Manager API provides the functions for managing multiple workspaces. For more information about these CDE services, see Chapter 5 and Appendix B of this guide, the Common Desktop Environment: Programmer's Overview, and the Common Desktop Environment: Programmer's Guide.

4.4 Creating New Application Groups

The New Desktop includes four application groups: DECwindows Apps, DECwindows Utilities, Desktop Apps, and Desktop Tools, as shown in Figure 4-5. Desktop Apps refers to the CDE applications and Desktop Tools refers to the CDE tools.

Figure 4-5 Application Manager

An application group is simply a directory containing action (stub) files. For Application Manager to recognize that a directory is an application group, the directory must reside in one of the application group root directories defined by the logical name DTAPPSEARCHPATH. The directory disk$:[user.DT.APPMANAGER] is one of the application group root directories.

You can create additional application groups to be managed by Application Manager in the following way:

  1. Create a directory with the name of a new application group, for example, disk$:[user.DT.APPMANAGER.MY_TOOLS].
  2. The new application group will initially appear using the folder icon and the default name (in lowercase, with the underscore), as shown in Figure 4-6. To change the folder icon and the default name, copy the file NEWGROUP.DT_TEMPLATE from CDE$SYSTEM_DEFAULTS:[APPCONFIG.TYPES.C] to disk$:[user.DT.TYPES]newgroup.DT, if one doesn't exist already. Modify this file following the instructions contained within the file.
  3. Run the Create Action application located in the Desktop Apps group to create:
    1. Action (stub) file, for example, SYS$LOGIN:CALCULATOR
    2. Action and data type definition file, for example,

    You must fill in a minimum of two fields: Action Name (Icon Label) and Command When Action Is Opened (Double-clicked). For this example, the action name is CALCULATOR.DT and the command when action is opened is RUN SYS$SYSTEM:DECW$CALCULATOR.
  4. Provide an icon for your application in one of the following ways:
    • Accept the default icon (the runner) by not selecting either Find Set... or Edit Icon....
    • Select an icon that is included with the New Desktop by choosing Find Set... and responding to the prompts.
    • Revise an existing icon or create a new one by choosing Edit Icon... and responding to the prompts.

    For this example, the default icon is used.
  5. Move the action (stub) file from SYS$LOGIN to
  6. Enable the new application group within Create Action with the Save option on the File pull-down menu. Alternatively, you can exit from Create Action and enable the new application group with Reload Actions. From Application Manager, select the Desktop Tools group, then double click on Reload Actions.
  7. Select Application Manager.
    You will see a new file folder icon labeled my_tools, as shown in Figure 4-6. Double click on this icon and you will see the action icon (a runner) with the name Calculator. Double click to start Calculator.
  8. Repeat steps 3 through 6 for every application you want to add to a group.

Every time you use this procedure, a new .DT file is added to your disk$:[user.DT.TYPES] directory. You might want to create one file, such as MY_TOOLS.DT, and merge all the actions into this file. A single file can simplify the management of an application group.

Figure 4-6 Application Manager With a New Application Group

Previous Next Contents Index