hp DECwindows Motif for hp OpenVMS Alpha

hp DECwindows Motif
for hp OpenVMS Alpha

New Features

Order Number: AA--RT2CA--TE

February 2003

This manual describes new features and enhancements that pertain to the HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 software.

Revision/Update Information: This is a new manual.

Operating System: HP OpenVMS Alpha Version 7.3--1

Software Version: HP DECwindows Motif for
HP OpenVMS Alpha Version 1.3

Hewlett-Packard Company
Palo Alto, California

Motif, OSF/1, UNIX, and the "X" device are registered trademarks and The Open Group is a trademark of The Open Group in the U.S. and other countries.

Confidential computer software. Valid license from HP and/or its subsidiaries required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Neither HP nor any of its subsidiaries shall be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6663

The HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

This document describes the new features introduced with the HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 (DECwindows Motif) software. For information about how these features might affect your system, read the release notes before you install, upgrade, or use the DECwindows Motif Version 1.3 software.

The features in this manual are cumulative from DECwindows Motif Version 1.0 and indicate any undocumented items that still pertain to the software. For previous features, a label within the description indicates when the feature was introduced.

Intended Audience

This manual is intended for system managers, users, and programmers who work with the DECwindows Motif software.

Document Structure

This manual is structured as follows:

Part I, Features of This Release
- Chapter 1 describes new features of interest to general users of the DECwindows Motif software.
- Chapter 2 describes new features related to system and network management.
- Chapter 3 describes new features that support application and system programmers.
Part II, Features of Previous Releases
- Chapter 4 describes previous features of interest to general users of the DECwindows Motif software.
- Chapter 5 describes previous features related to system and network management.
- Chapter 6 describes previous features that support application and system programmers.

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet openvmsdoc@hp.com

Mail Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.compaq.com/doc/

Conventions

In this manual, references to OpenVMS are synonymous with the HP OpenVMS Alpha Operating System.

Unless otherwise specified, references to OpenVMS Clusters, VMSclusters, or clusters in this document are synonymous with HP OpenVMS Clusters.

All uses of DECwindows and DECwindows Motif refer to the HP DECwindows Motif for HP OpenVMS Alpha software; and all uses of X server and X display server refer to the DECwindows X11 Display Server. Additionally, all uses of DECwindows XUI (X User Interface) refer to the DECwindows product prior to DECwindows Motif Version 1.0.

The following conventions are also used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as brackets, rather than a box.

... Horizontal ellipsis points in examples indicate one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that you must enclose the choices in parentheses if you choose more than one.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.

{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.

text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
In the HTML version of this document, this convention appears as italic text.

italic text Italic text emphasizes important information and indicates complete titles of manuals and variables. Variables include information that varies in system messages (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace type

Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Part 1
Features of This Release

The following chapters describe the general user, programming, and system management features available with DECwindows Motif Version 1.3.

Chapter 1
General User Features

This chapter provides information about new features that pertain to all users of DECwindows Motif.

1.1 Enhanced DECwindows Motif Display Device Capabilities

To support the new X display server access control and proxy features available as part of the X11R6.6 upgrade, many SET DISPLAY and SHOW DISPLAY command qualifiers have been either added or modified for use on OpenVMS Alpha Version 7.3--1 systems.

Table 1-1 lists these new and changed qualifiers that provide the following added functionality for DECwindows Motif display devices:

Ability to define and view a set of named properties associated with a particular display device and assign their values. Named properties are intended to store such information as the network address or transport for the display device. Once defined, you can use these properties as the basis for subsequent DCL global symbol definitions.
Access to a subset of commands from the X Authority utility (xauth). This utility enables you to manage the contents of one or more X authority files, which are used by the MIT-KERBEROS-5 and MIT-MAGIC-COOKIE-1 protocols to control access to an X server. Use the new qualifiers to create and use an alternate X authority file, manually generate or revoke authorization keys, or extract entries from the X authority file.
Access to the proxy manager and Low-Bandwidth X (LBX) proxy server. The proxy manager and LBX proxy server assist in managing connections over low-bandwidth networks, such as the Internet. Use the new qualifiers to specify a standalone proxy server or to specify a proxy manager (and the manager's port and transport information). You can also enable authentication on proxy server connections and specify data values, such as a magic cookie, to be passed to the authentication protocol.

Table 1-1 New and Changed DCL SET DISPLAY and SHOW DISPLAY Command Qualifiers
Command Qualifier Description

SET DISPLAY /GENERATE Connects to the X server and generates a new authorization key.

/LBXAUTHENTICATE
/NOLBXAUTHENTICATE Specifies the authentication protocol used to grant the proxy server access to the X server.

/LBXDATA Specifies a data value to be processed by the authentication protocol.

/PMPORT Indicates the port number for the proxy manager.

/PMTRANSPORT Specifies the network transport used by a display device to connect to the proxy manager.

/PROXY Specifies that a proxy manager be used to assign an LBX proxy server to act as an intermediary between the client and the X server specified in the command.

/QUOTA Modifies the value of the name count or data space quota for the display device.

/REVOKE Revokes the authorization key for the display device produced by the /GENERATE qualifier.

/SERVER Specifies the server number. This qualifier takes on the additional meaning of specifying a standalone LBX proxy server.

/TRANSPORT Specifies the network transport used to connect to the X server. When using the proxy manager, selects transport used between the selected proxy server and the X server. When using a standalone proxy server, selects the transport between the client and the proxy server. This qualifier also provides a default value for the /PMTRANSPORT qualifier.

/VALUE Sets, deletes, or modifies a named property value.

/XAUTHORITY
/NOXAUTHORITY Specifies the location for an alternate X authority file. The /NOXAUTHORITY qualifier clears this setting.

SHOW DISPLAY /ALL Displays all named properties associated with the display device and their current values.

/EXTRACT Obtains the authorization data from the current X authority file and writes it to SYS$OUTPUT.

/QUOTA Displays the name count and data space quota values associated with the display device.

/SYMBOLS Defines a DCL symbol for each named property.

/VALUES Displays the set of values associated with the specified named properties.

**Table 1-1 New and Changed DCL SET DISPLAY and SHOW DISPLAY Command Qualifiers**
Command	Qualifier	Description
SET DISPLAY	/GENERATE	Connects to the X server and generates a new authorization key.
	/LBXAUTHENTICATE /NOLBXAUTHENTICATE	Specifies the authentication protocol used to grant the proxy server access to the X server.
	/LBXDATA	Specifies a data value to be processed by the authentication protocol.
	/PMPORT	Indicates the port number for the proxy manager.
	/PMTRANSPORT	Specifies the network transport used by a display device to connect to the proxy manager.
	/PROXY	Specifies that a proxy manager be used to assign an LBX proxy server to act as an intermediary between the client and the X server specified in the command.
	/QUOTA	Modifies the value of the name count or data space quota for the display device.
	/REVOKE	Revokes the authorization key for the display device produced by the /GENERATE qualifier.
	/SERVER	Specifies the server number. This qualifier takes on the additional meaning of specifying a standalone LBX proxy server.
	/TRANSPORT	Specifies the network transport used to connect to the X server. When using the proxy manager, selects transport used between the selected proxy server and the X server. When using a standalone proxy server, selects the transport between the client and the proxy server. This qualifier also provides a default value for the /PMTRANSPORT qualifier.
	/VALUE	Sets, deletes, or modifies a named property value.
	/XAUTHORITY /NOXAUTHORITY	Specifies the location for an alternate X authority file. The /NOXAUTHORITY qualifier clears this setting.

SHOW DISPLAY	/ALL	Displays all named properties associated with the display device and their current values.
	/EXTRACT	Obtains the authorization data from the current X authority file and writes it to SYS$OUTPUT.
	/QUOTA	Displays the name count and data space quota values associated with the display device.
	/SYMBOLS	Defines a DCL symbol for each named property.
	/VALUES	Displays the set of values associated with the specified named properties.

See Chapter 2 for details of the X server access control features available with HP DECwindows Motif for HP OpenVMS Alpha Version 1.3.

The following sections describe these qualifiers in further detail.

1.1.1 New SET DISPLAY Qualifiers

/GENERATE[=(keyword[=value][,...])

Requires a trusted network connection and that the SECURITY extension to the X server be enabled.

Instructs the display device to connect to the X server and generate a new authorization key (consisting of the security protocol name and a token). This authorization key is then stored in the X authority file currently in use. If you do not want to overwrite any previously existing keys for this display device, use the /XAUTHORITY qualifier to write the generated key to an alternate X authority file.

Each generated key follows the default settings unless otherwise specified. This means that, by default, each generated authorization key:

Follows the MIT-MAGIC-COOKIE-1 protocol
Grants an untrusted connection to the X server
Is not associated with a particular application group
Maintains a timeout period of 60 seconds before which it must be used (otherwise, it is automatically revoked)

Possible keyword values are as follows:

Value Description

TRUSTED Specifies that the key grant unrestricted access to the X server. This keyword permits a client application to perform all actions.

UNTRUSTED Specifies that the key grant restricted access to the X server. This keyword restricts client applications to a subset of X server extensions and prevents access to windows other than those created by the requesting application.

TIMEOUT=seconds Specifies the number of seconds after which the key is revoked automatically if not in use. The timeout period begins immediately, and refreshes once all connections using this key have closed.

NOTIMEOUT Specifies that the key has no expiration and must be explicitly revoked.

GROUP=groupid Specifies that the key is associated with a particular application group and is to be revoked if that group is deleted. Although the use of application groups is supported by DECwindows Motif via the XC-APPGROUP extension, DECwindows Motif does not currently supply any utilities or desktop applications to create these groups. To create an application group, you must use an X Window System application or utility external to DECwindows Motif.

PROTOCOL=name Specifies the protocol to be used to authenticate the key. Valid values for the name parameter are MIT-MAGIC-COOKIE-1 and MIT-KERBEROS-5.

Value	Description
TRUSTED	Specifies that the key grant unrestricted access to the X server. This keyword permits a client application to perform all actions.
UNTRUSTED	Specifies that the key grant restricted access to the X server. This keyword restricts client applications to a subset of X server extensions and prevents access to windows other than those created by the requesting application.
TIMEOUT=seconds	Specifies the number of seconds after which the key is revoked automatically if not in use. The timeout period begins immediately, and refreshes once all connections using this key have closed.
NOTIMEOUT	Specifies that the key has no expiration and must be explicitly revoked.
GROUP=groupid	Specifies that the key is associated with a particular application group and is to be revoked if that group is deleted. Although the use of application groups is supported by DECwindows Motif via the XC-APPGROUP extension, DECwindows Motif does not currently supply any utilities or desktop applications to create these groups. To create an application group, you must use an X Window System application or utility external to DECwindows Motif.
PROTOCOL=name	Specifies the protocol to be used to authenticate the key. Valid values for the name parameter are MIT-MAGIC-COOKIE-1 and MIT-KERBEROS-5.

The keyword sets TRUSTED/UNTRUSTED and TIMEOUT/NOTIMEOUT are mutually exclusive. Do not enter both values on the same command line.

/LBXAUTHENTICATE=protocol-name
/NOLBXAUTHENTICATE

Specifies the authentication protocol used to grant the LBX proxy server access to the X display server. This qualifier is used with the /PROXY and /CREATE qualifiers when creating an initial LBX proxy server connection. If a proxy server connection already exists, these qualifiers are ignored. If you do not specify /LBXAUTHENTICATE, the authentication protocol is obtained from the current X authority file. If you specify /NOLBXAUTHENTICATE, the proxy server defaults to the X authority file of the user who started the proxy server.

Valid values for the protocol-name parameter are MIT-MAGIC-COOKIE-1 and MIT-KERBEROS-5. If you supply a protocol-name value of MIT-MAGIC-COOKIE-1, you must also specify the value of the magic cookie using the /LBXDATA qualifier.

/LBXDATA=value

Specifies a data value for the authentication protocol used between the LBX proxy server and the X display server. This qualifier must be used with the /LBXAUTHENTICATE, /PROXY, and /CREATE qualifiers.

When you issue a SET DISPLAY/CREATE/PROXY/LBXAUTHENTICATE=MIT-MAGIC-COOKIE-1 command, use this qualifier to provide a hexadecimal magic cookie value to the MIT-MAGIC-COOKIE-1 protocol.

/PMPORT=[port-number]

Specifies the port number on which the proxy manager is listening. This qualifier is used with the /PROXY and /CREATE qualifiers. The default port is 6500.

/PMTRANSPORT=transport-name

Specifies the network transport used to connect to the proxy manager. This qualifier is used with the /PROXY and /CREATE qualifiers.

Valid values for the transport-name parameter are LOCAL, DECNET, and TCPIP. If you do not specify a transport, then the network transport specified by the /TRANSPORT qualifier is used.

/PROXY[=node]

Specifies that a proxy manager should be used to locate an LBX proxy server, which serves as an intermediary for processing client and server connections for a display device. Use an LBX proxy server when connecting to a remote node located over a low-bandwidth network connection, such as the Internet. The proxy manager should run on the local network.

When you create a display device using the SET DISPLAY/CREATE/PROXY command, you can use that device to connect to an X display server exactly the same as you would with any other display device. The client connects to the LBX proxy server returned by the proxy manager, which in turn connects to the X display server.

The value of the /PROXY qualifier specifies the node on which the proxy manager is running. The proxy manager is responsible for starting or locating a proxy server to provide access to the X server specified by the transport, node, and server values. The proxy manager returns the transport, node, and server values for the selected proxy server to the display device. If you do not specify a value for the node parameter, the default location is the current node.

The /PMPORT and /PMTRANSPORT qualifiers can be used to further specify the proxy manager's location.

/QUOTA=(quota-name=value[,...])

Requires SYSPRV (system privilege) privilege or the DECW$WS_QUOTA rights identifier. If using an executive mode device, SYSNAM (system name) privilege is also required.

Modifies the value of the name count or data space quota associated with the display device. These quotas influence the amount of non-paged pool available for storing named properties.

Possible values for the quota-name parameter are as follows:

NAME_COUNT -- The name count quota restricts the total number of named properties associated with the device. The default name count quota is the value of the DECW$WS_DEFAULT_NAME_COUNT logical, or 12 if the logical is not defined.
DATA_SPACE -- The data space quota restricts the total amount of space available (in bytes) for storing property values. Note that this space includes some data overhead and may not total the exact length of the values. The default data space quota is the value of the DECW$WS_DEFAULT_DATA_SPACE logical, or 10752 if the logical is not defined.

/REVOKE

Requires a trusted network connection and that the SECURITY extension to the X server be enabled.

Revokes an authorization key created with the /GENERATE qualifier.

If you specify the /REVOKE qualifier, the revoke operation is performed before the other actions on the SET DISPLAY command. For example, you can use both the /REVOKE and /GENERATE qualifiers on the same command line, in any order, to revoke one authorization key and generate another.

Do not use with the /CREATE qualifier.

/SERVER

Specifies either an X server or a standalone LBX proxy server. Standalone LBX proxy servers are not managed by the proxy manager and are manually assigned a server number on startup.

/TRANSPORT

When using a proxy manager, specifies the transport that the selected LBX proxy server should use to connect to the X server.

When using a standalone proxy server (specified by the /SERVER qualifier), specifies the transport that the client should use to connect to the proxy server. The value specified for this qualifier acts as a default value for the /PMTRANSPORT qualifier.

/VALUE=(NAME=property-name,action[=data])

Sets, deletes, or modifies a property value associated with the display device. These property values are intended to store configuration information associated with the display device, such as the network address or transport.

Use the following options to specify the type of action to perform:

DELETE -- Deletes the specified property value.
SET=data -- Sets the specified property to the supplied value.
APPEND=data -- If the property exists, adds the supplied value to the end of list of values associated with the property. If the property does not exist, it is created and set to the supplied value.

Use the SHOW DISPLAY/VALUES command to display all existing named properties and their current values. Property names are restricted to 31 characters. Names that include a dollar sign ($) are reserved by HP for use with OpenVMS products and facilities. For example, names starting with the string DECW$ are reserved for DECwindows Motif.

/XAUTHORITY=[filespec]
/NOXAUTHORITY

Specifies the file specification for an alternate X authority file. The X authority file contains data that grants or restricts access to the X display server depending on the authentication protocol in use. If a file specification is not entered with this qualifier, a default of SYS$LOGIN:DECW$XAUTHORITY.DECW$XAUTH is used.

Note that with this qualifier, all X authority file specifications resolve to a physical device (versus logical device) in order to remain available to other detached processes. If you specify a search list, and the file is not found, the X authority file specification resolves to the first directory in the search list.

Use /NOXAUTHORITY to clear the setting and return to the file referenced by the DECW$XAUTHORITY logical or the default file if the logical is not defined.

See Section 2.6 for information on the available authentication protocols and the content of X authority files.

Contents

Index

Internet	openvmsdoc@hp.com
Mail	Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	Horizontal ellipsis points in examples indicate one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose the choices in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[\|]	In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ }	In command format descriptions, braces indicate required elements; you must choose one of the options listed.
text style	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. In the HTML version of this document, this convention appears as italic text.
italic text	Italic text emphasizes important information and indicates complete titles of manuals and variables. Variables include information that varies in system messages (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace type	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.