HP OpenVMS Systems Documentation

This chapter provides information about the following topics:

• Three levels of desktop integration, defined by the CDE documentation:
  • Minimal ( Section 4.1)
  • Recommended ( Section 4.2)
  • Optional ( Section 4.3)
• Creating new application groups ( Section 4.4)
• Registering a third-party application ( Section 4.5)
• Porting UNIX reference pages (manpages) to the New Desktop ( Section 4.6)
• CDE documentation for integrating applications ( Section 4.7)

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 WINDOW_TYPE NO_STDIO 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.

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:

  CDE$USER_DEFAULTS:[BIN]
  CDE$SYSTEM_DEFAULTS:[BIN]

  
  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:

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.

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.

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

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

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

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.

GENCAT msgfile [,...] catfile

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,
      disk$:[user.DT.TYPES]CALCULATOR.DT
   
   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
   disk$:[user.DT.APPMANAGER.MY_TOOLS].
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