HELPLIB.HLB  —  SET  DISPLAY
    Directs the output of an OpenVMS DECwindows application.
    Output can be directed from any processor running a DECwindows
    application, including workstations, to any DECwindows
    workstation.

    Both source and destination nodes must be part of the same
    network.

    Format

      SET DISPLAY  [display-device]

1  –  Parameter

 display-device

    Specifies a logical name for the workstation display you are
    creating or modifying. If you are directing application output
    to multiple workstation displays, you can use different logical
    names to point to each display. If you do not specify a display-
    device parameter, the logical name DECW$DISPLAY is used. This
    means that, by default, application output will be displayed on
    the workstation display device referred to by DECW$DISPLAY.

    By entering the command SHOW DISPLAY, you can see the default
    workstation node where applications will be displayed, as well as
    related device, screen, and transport information.

    If you specified your own logical name in the SET DISPLAY/CREATE
    command, include that logical name in the SHOW DISPLAY command.

2  –  Qualifiers

2.1    /CREATE

    Creates the workstation display device (WSAn:) on which a
    DECwindows application is displayed. You must specify the /CREATE
    qualifier the first time you use the SET DISPLAY command, but
    you need not respecify it if you continue to redirect output from
    applications to other workstations with subsequent SET DISPLAY
    commands.

    When you specify the /CREATE qualifier without the /NODE
    qualifier, the workstation device defaults to the current node.
    Additionally, if you omit the /TRANSPORT qualifier, the transport
    defaults to either the value specified by the DECW$SETDISPLAY_
    DEFAULT_TRANSPORT logical, if defined, or to DECNET.

2.2    /DELETE

    Cancels the redirected display by deassigning the logical name
    DECW$DISPLAY and deleting the created display device. If you
    specified a logical name as the display-device parameter with
    the SET DISPLAY/CREATE command, entering the SET DISPLAY/DELETE
    display-device command cancels the redirected display by
    deassigning the logical name you specified and deleting the
    created display device.

    The DECwindows Session Manager defines DECW$DISPLAY in your job
    logical name table when you open a terminal (DECterm) window.
    When you redirect application output to another workstation
    with the SET DISPLAY/CREATE command, an additional DECW$DISPLAY
    logical name is defined in your process logical name table. This
    definition supersedes the definition in the job logical name
    table. Output from applications run from the process in which
    you executed the SET DISPLAY/CREATE command will be displayed on
    the workstation referred to by the definition of DECW$DISPLAY in
    the process logical name table. Enter the SHOW DISPLAY command
    to see where this application will be displayed. To see whether
    multiple definitions for DECW$DISPLAY exist, enter the command
    SHOW LOGICAL DECW$DISPLAY.

    If DECW$DISPLAY is still defined (for example, in the job
    logical name table) after you specify the /DELETE qualifier, any
    DECwindows applications run from this process will be displayed
    on the workstation device to which output is now directed. Enter
    the SHOW DISPLAY command if you are unsure of the node to which
    DECW$DISPLAY refers.

                                 CAUTION

       If you modify or delete the definition of DECW$DISPLAY from
       the job logical name table, you will be unable to start
       another session. Be careful not to specify the /DELETE
       qualifier without having first redirected the display with
       the SET DISPLAY/CREATE command.

    You cannot specify the /DELETE and /CREATE qualifiers on the same
    command line.

2.3    /EXECUTIVE_MODE

    Creates an executive-mode device and assigns the logical name
    DECW$DISPLAY to point to it. This qualifier must be used with
    the /CREATE qualifier. Devices created with the /EXECUTIVE_MODE
    qualifier are deleted only in the following situations:

    o  They are explicitly deleted with the /DELETE qualifier.

    o  The system is rebooted.

    To modify or delete executive-mode devices, you must have SYSNAM
    (system logical name) privilege.

2.4    /GENERATE

       /GENERATE[=(keyword[=value][,...]) (Alpha/Integrity servers
       only)

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

    Instructs the display device to connect to the X display
    server and generate a new authorization key (consisting of
    the authorization protocol name and a magic cookie). 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.

                                   NOTE

       The MIT-KERBEROS-5 protocol does not currently support key
       generation, as defined by the SECURITY extension. Do not
       use the /GENERATE qualifier when connected to an X display
       server protected by Kerberos access control.

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

    o  Follows the MIT-MAGIC-COOKIE-1 protocol

    o  Grants an untrusted connection to the X server

    o  Is not associated with a particular application group

    o  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 are server dependent. For
                    the DECwindows X display server, the only valid
                    value for the name parameter is MIT-MAGIC-COOKIE-
                    1. If you are connecting to a third-party X
                    server, the names of any additional authorization
                    protocols on that X server that support the
                    SECURITY extension and key generation are also
                    valid.

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

2.5    /LBXAUTHENTICATE

       /LBXAUTHENTICATE=protocol-name (Alpha/Integrity servers only)
       /NOLBXAUTHENTICATE (Alpha/Integrity servers only)

    Specifies the authorization 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 authorization 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 manager application.

    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.

2.6    /LBXDATA

       /LBXDATA=value (Alpha/Integrity servers only)

    Specifies a data value for the authorization 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.

2.7    /NODE

       /NODE=workstation_display

    Defines the workstation on which you want to display DECwindows
    applications. The node name you provide cannot be a cluster alias
    (a name that represents multiple nodes configured in an OpenVMS
    Cluster), but must instead identify an actual node.

    You must create a workstation display device with the
    /CREATE qualifier before you can redirect the output from
    applications to other workstations. Do not enter the SET
    DISPLAY/NODE=workstation_display command without having
    previously specified the /CREATE qualifier.

    When you specify the /CREATE qualifier without the /NODE
    qualifier, the workstation defaults to the current node.

    Make sure that you are authorized to display applications on
    the workstation you specify. For more information about using
    the DECwindows Session Manager to authorize yourself to display
    applications from other nodes, see the DECwindows documentation.

    Each node, both source and destination, must be defined in
    the other's network node database. For example, to display
    applications on node HUBBUB from ZEPHYR, HUBBUB must be entered
    in ZEPHYR's network node database, and ZEPHYR must be entered
    in HUBBUB's network node database. In addition, users on ZEPHYR
    must be authorized in the DECwindows Session Manager to display
    applications on HUBBUB. For information about entering nodes
    in a network node database, see the DECnet-Plus for OpenVMS
    documentation.

2.8    /PMPORT

       /PMPORT=[port-number] (Alpha/Integrity servers only)

    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.

2.9    /PMTRANSPORT

       /PMTRANSPORT=transport-name (Alpha/Integrity servers only)

    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 the same
    as those listed for the /TRANSPORT qualifier. If you do not
    specify a transport, then the network transport specified by
    the /TRANSPORT qualifier is used.

2.10    /PROXY

       /PROXY[=node] (Alpha/Integrity servers only)

    Specifies that a proxy manager application 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. This qualifier
    is used with the /CREATE qualifier.

    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 display 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.

2.11    /QUOTA

       /QUOTA=(quota-name=value[,...]) (Alpha/Integrity servers only)

    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:

    o  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.

    o  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.

2.12    /REVOKE

       /REVOKE (Alpha/Integrity servers only)

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

    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
    key and generate another.

    Do not use with the /CREATE qualifier.

2.13    /SCREEN

       /SCREEN=screen-number

    Defines the screen to be associated with this display device. In
    some hardware configurations, the system supports more than one
    screen. In such a configuration, you can specify the screen to
    which the application is directed.

2.14    /SERVER

       /SERVER=server-number

    Defines the server to be associated with the display device
    indicated by the display-device parameter to the SET DEVICE
    command. Using the transport mechanism, the server passes
    data between the user and the application. In some hardware
    configurations, the system supports more than one server. In
    such a configuration, you can specify the server to which the
    application is directed.

    On Alpha and Integrity server systems in LBX proxy server
    configurations, this qualifier specifies either an X display
    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.

    If you do not specify the display-device parameter, the SET
    DISPLAY/SERVER command associates the server with the display
    device indicated by the logical name DECW$DISPLAY.

2.15    /SUPERVISOR_MODE

       /SUPERVISOR_MODE (default)

    Creates a supervisor-mode device and assigns the logical name
    DECW$DISPLAY to point to it. This qualifier must be used with the
    /CREATE qualifier. When the user logs out, the device is deleted.

2.16    /TRANSPORT

       /TRANSPORT=transport-name

    Defines the transport mechanism, for example, DECnet or
    local, that passes information between the application and the
    workstation. The transport mechanism is used to send input from
    the user to the application and output from the application to
    the display device. In proxy manager configurations, the value
    specified for this qualifier also acts as a default value for the
    /PMTRANSPORT qualifier.

    The transport-name parameter can be one of the following values:

    o  TCPIP or DECNET

       Specifies the appropriate network transport for applications
       running and displaying on different nodes. You can specify
       the default transport value used with the SET DISPLAY/CREATE
       command by defining the DECW$SETDISPLAY_DEFAULT_TRANSPORT
       logical in the job, process, or system table. The value
       of this logical is then used each time you enter the SET
       DISPLAY/CREATE command without the /TRANSPORT qualifier. If
       you specify neither the qualifier nor the logical, the value
       of DECNET is used as default.

    o  LOCAL

       Optimizes the performance of applications running and
       displaying on the same node.

    On Alpha and Integrity server systems, the valid set of values
    for the transport-name parameter is further determined by the
    DECwindows logical DECW$IPV6_SUPPORT. This logical specifies
    which Internet Protocol version is supported: IPv4 or IPv6. See
    the DECwindows Motif documentation for more information about the
    DECW$IPV6_SUPPORT logical and support for the IPv6 protocol.

    When using a proxy manager on Alpha and Integrity server systems,
    this qualifier 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), this qualifier specifies the transport that the
    client should use to connect to the proxy server.

2.17    /USER_MODE

    Creates a user-mode display device and assigns the logical name
    DECW$DISPLAY to point to it. This qualifier must be used with
    the /CREATE qualifier. The lifetime of a user-mode device is
    one DECwindows image: when the next DECwindows image exits, the
    device is deleted.

2.18    /VALUE

       /VALUE=(NAME=property-name,action[=data]) (Alpha/Integrity
       servers only)

    Sets, deletes, or modifies a named property value associated with
    the display device. Named property values are intended to store
    configuration information associated with the display device,
    such as the network address of a session manager.

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

    o  DELETE - Deletes the specified property value.

    o  SET=data - Sets the specified property to the supplied value.

    o  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 VSI for use with OpenVMS products and facilities.
    For example, names starting with the string DECW$ are reserved
    for DECwindows Motif.

2.19    /XAUTHORITY

       /XAUTHORITY=[filespec] (Alpha/Integrity servers only)
       /NOXAUTHORITY (Alpha/Integrity servers only)

    Directs the display device to use a specific X authority file
    when connecting the X display server. The X authority file
    contains data that grants or restricts access to the X display
    server depending on the authorization protocol in use. If a file
    specification is not entered with this qualifier, the default
    of SYS$LOGIN:DECW$XAUTHORITY.DECW$XAUTH is used. If the file
    specification is entered and the file does not currently exist,
    it is created automatically when an entry is made into the file.

    Note that with this qualifier, all X authority file
    specifications resolve to a physical device (rather than a
    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.

3  –  Examples

    1.$ SHOW DISPLAY
        Device:     WSA1: [super]
        Node:       0
        Transport:  LOCAL
        Server:     0
        Screen:     0

      $ SET DISPLAY/CREATE/NODE=ZEPHYR/EXECUTIVE_MODE
      $ SHOW DISPLAY
        Device:     WSA2:  [exec]
        Node:       ZEPHYR
        Transport:  DECNET
        Server:     0
        Screen:     0
      $ SPAWN/NOWAIT/INPUT=NL: RUN SYS$SYSTEM:DECW$CLOCK

      $ SET DISPLAY/DELETE

      $ SHOW DISPLAY
        Device:     WSA1:  [super]
        Node:       0
        Transport:  LOCAL
        Server:     0
        Screen:     0

      In this example, you are logged in to your workstation (device
      WSA1:), here referred to as node 0. (0 is the standard
      shorthand notation for representing your node.) You want to
      run the DECwindows Clock on your workstation and display it on
      another workstation, ZEPHYR.

      Assuming you are authorized to display applications on ZEPHYR,
      you redirect the application's output to ZEPHYR with the SET
      DISPLAY command. The device created on ZEPHYR is an executive-
      mode device. You enter the SHOW DISPLAY command to verify the
      location of the redirected display. You then run Clock. When
      you finish running Clock, you disable the redirected display
      by entering the SET DISPLAY/DELETE command. Finally, you
      enter the SHOW DISPLAY command to verify that any applications
      subsequently run on your node will also be displayed there.

      Note that a new workstation display device, WSA2, is created
      when you enter the SET DISPLAY/CREATE command. When you cancel
      the redirected display with the SET DISPLAY/DELETE command,
      application output is once again displayed on the workstation
      display device referred to by WSA1.

    2.$ SET DISPLAY/CREATE/NODE=FLOPSY RABBIT
      $ SHOW DISPLAY RABBIT

       Device:    WSA2:  [super]
       Node:      FLOPSY
       Transport: DECNET
       Server:    0
       Screen:    0

      $ RUN/DETACHED/OUTPUT=WSA2: SYS$SYSTEM:DECW$CLOCK

      $ SET DISPLAY/CREATE/NODE=ZEPHYR ZNODE
      $ SHOW DISPLAY ZNODE

       Device:    WSA3:  [super]
       Node:      ZEPHYR
       Transport: DECNET
       Server:    0
       Screen:    0

      $ RUN/DETACHED/OUTPUT=WSA3: SYS$SYSTEM:DECW$CALENDAR

      $ RUN SYS$SYSTEM:DECW$BOOKREADER
      $ SHOW DISPLAY

       Device:    WSA1:  [super]
       Node:      0
       Transport: LOCAL
       Server:    0
       Screen:    0

      In this example, you are logged in to your node (device WSA1:),
      and want to direct the output from applications to several
      workstation displays in the same session. By specifying
      different logical names in the SET DISPLAY command, you
      can redirect the output without changing the logical name
      definition for DECW$DISPLAY. This allows you to display the
      output from most applications on your default display but
      occasionally display output on another workstation. You can
      also continue to run and display applications on your node. In
      this example, Clock is displayed on node FLOPSY, Calendar is
      displayed on node ZEPHYR, and Bookreader is displayed on your
      workstation.

      Note that to run your applications with the DCL command
      RUN/DETACHED, you must use the device name that equates to the
      logical display device name you specified in the SET DISPLAY
      command. Use the SHOW DISPLAY command to obtain this device
      name.

    3.$ SET DISPLAY/CREATE/GENERATE=TRUSTED-
      _$ /XAUTHORITY=XAUTHORITY_TEMP/NODE=ZEPHYR
      $ PIPE SHOW DISPLAY/EXTR | RSH FLOPSY "XAUTH NMERGE SYS$INPUT"
      $ SET HOST FLOPSY
      $ SET DISPLAY/NODE=ZEPHYR
      $ RUN SYS$SYSTEM:DECW$CLOCK

      In this example, you are logged into your workstation (WSA1:)
      and want to run the DECwindows Clock application on a remote
      node (FLOPSY) and display it on another workstation (ZEPHYR).
      Both systems are using Magic Cookie authorization to control
      access to the X display server.

      Assuming you are already authorized to connect to the server
      on node ZEPHYR, you create a display device that connects to
      ZEPHYR and generates a new authorization key. This key grants
      trusted connections to the server on ZEPHYR within 60 seconds
      of key generation. To restrict trusted access to the server,
      the key is stored in a new X authority file, XAUTHORITY_
      TEMP.DECW$XAUTH.

      The authorization key is then extracted and copied to FLOPSY,
      and merged with other entries in your X authority file on that
      system. You then set host to node FLOPSY and set display to
      node ZEPHYR. When you run the clock application from FLOPSY,
      it connects to the server on ZEPHYR and is allowed access as
      specified by the generated authorization key.

    4.$ SET DISPLAY/CREATE/VALUE=-
      _$ (NAME=DECW$SESSION_MANAGER,SET="tcpip/zephyr:9510")
      $ SHOW DISPLAY/SYMBOLS/ALL
          Device:    WSA23:  [super]
          Node:      0
          Transport: DECNET
          Server:    0
          Screen:    0

        User-defined values:

          "DECW$SESSION_MANAGER" = "tcpip/zephyr:9510"

      $ SHOW SYMBOL DECW$DISPLAY__DECW$SESSION_MANAGER
        DECW$DISPLAY__DECW$SESSION_MANAGER == "tcpip/zephyr:9510"

      $ SET DISPLAY UNTRUSTED/CREATE/XAUTHORITY=TEMP/GENERATE-
      _$ /VALUE=(NAME=DECW$SESSION_MANAGER,-)
      _$ SET="'DECW$DISPLAY__DECW$SESSION_MANAGER'"

      In this example, you create a display device, and set the
      DECW$SESSION_MANAGER property to the network address of a
      session manager on remote node ZEPHYR using port number 9510.
      The SHOW DISPLAY/SYMBOLS command then defines a DCL symbol for
      the port value. The symbol is then used to set the port value
      for a new display device.

    5.$ SET DISPLAY/CREATE/PROXY=GATEWY/NODE=hubbub.company.com-
      _$ /PMTRANSPORT=DECNET/NOLBXAUTHENTICATE/TRANSPORT=TCPIP

      $ SHOW DISPLAY
          Device:    WSA23:  [super]
          Node:      HUBBUB.COMPANY.COM
          Transport: TCPIP
          Server:    0
          Screen:    0

        Connection will use:
          LBX proxy on node:  gatewy.company.com
          Transport to proxy: TCPIP
          Server number:      63

      $ RUN SYS$SYSTEM:DECW$CLOCK

      In this example, you are logged into a local workstation
      (FLOPSY) and want to connect to an external host
      (hubbub.company.com), which is outside of your company's
      firewall. You use the proxy manager on a gateway host (GATEWY)
      to start the LBX proxy server, connect to the external host,
      and display the DECwindows Clock application.

      Note that DECnet is used within the local area network (LAN)
      to communicate to the proxy manager, and TCP/IP is used by
      the proxy server to communicate to the X display server on the
      external host. When using a managed proxy server, the proxy
      server chooses the transport for the client-to-proxy server
      connection.
Close Help