Specifies that this proxy server is allowed to initialize even when it cannot open all transport sockets specified by the /TRANSPORT qualifier. These transport sockets are used to receive client requests. Note that if the proxy server detects that one of the sockets is in use by another task, the server fails to initialize with the server number in use, and the next server number is tried (as discussed in the description of the /SERVER qualifier).

The default is /NOPARTIAL.

/RGB=file-specification

Specifies the file describing the color name to RGB resolution in this proxy server. This qualifier cannot be specified if the NORGB option is specified for the /OPTION qualifier.

The default is /RGB=SYS$MANAGER:DECW$RGB.DAT.

/SERVER=server-number

Specifies the server number to assign to this proxy server. Specify an integer from 0 to 63.

The proxy server first attempts to initialize using the specified server number. If an active server is already using the specified number, the proxy server tries the next lower number. This process is repeated until an unused server number is found or until the proxy server tries the number 0 and fails. If the number 0 fails and the number specified was not 63, the server number wraps and attempts are tried starting with the number 63. The process continues until all numbers have been tried. If all numbers are in use, the proxy server fails to initialize and terminates.

For managed proxy servers, the search for a free server number always starts at 63; any number specified by this qualifier is ignored.

A standalone server started as a subprocess always prints out the server number used on SYS$ERROR. For standalone proxy servers that are detached processes, use the /FIXED_SERVER qualifier to force the server to use the specified server number or fail. Otherwise, there is no method to determine the server number actually used by the server.

The default is /SERVER=63.

/TAGCACHE=cache-size

Specifies the size of this proxy server's tag cache (in bytes). Specify the value 0 to disable tag caching.

The default is /TAGCACHE=1048576 (2*20).

/TRANSPORTS="transport-string"

Specifies the transports that this proxy server monitors for incoming client requests. If the /PARTIAL qualifier is not used, all transports specified by this qualifier must initialize successfully or the proxy server fails to initialize with the server number in use and the next server number is tried, as discussed in the description of the /SERVER qualifier.

The default is /TRANSPORTS="LOCAL,DECNET,TCPIP".

/ZLEVEL=compression-level

Specifies the Zlib compression level used for stream compression. Specify an integer from 1 (least compression) to 9 (most compression).

The default is /ZLEVEL=6.

2.7.1.3 Stopping LBX Proxy Servers

You can stop LBX proxy servers either automatically or manually.

Stopping Servers Automatically

To stop an LBX proxy server automatically, use the /ONEXIT=TERMINATE qualifier when you start the server. For standalone proxy servers, specify this qualifier either on the LBXPROXY command line or in the lbxproxy-qualifiers parameter of the SYS$MANAGER:DECW$LBXPROXY command procedure.

For managed servers, specify this qualifier in the parameters argument in the LBX service definition in the proxy manager's configuration file.

Stopping Servers Manually

To stop an LBX proxy server manually, use the DCL STOP command.

2.7.2 Proxy Manager

The proxy manager configuration file contains the information that the proxy manager needs to be able to locate proxy services. Each line in the configuration file can contain one of the following:

• Comment -- Comment lines must begin with an exclamation character (!) in the first character position. All other characters in the line are ignored.
• Managed service entry -- Managed service entries have the following format:

  service-name MANAGED COMMAND command-file [parameters]

  
  where:

  service-name	Specifies the name of the managed service. The service name is case-insensitive. If the file contains multiple entries with the same service name, only the first occurrence has any effect. For the LBX service, the service name must be LBX. Service names must use characters in the X Portable Character Set with the exception of the Space, Tab, and Newline characters.
  command-file	Specifies the name of the command procedure that the proxy manager should invoke to create a new instance of a proxy server for this service. For the LBX service, this argument is usually SYS$MANAGER:DECW$LBXPROXY_SUB.COM.
  parameters	Specifies any parameters to pass to the command procedure specified in the command-file argument. All characters following the space after the command-file argument are passed as parameters to the command procedure. For the LBX service, the command procedure expects one quoted parameter: one or more command qualifiers.

  
  Currently, the only managed service supplied with DECwindows Motif is LBX.

• Unmanaged service entry -- Unmanaged service entries have the following format:

  service-name UNMANAGED address

  
  where:

  service-name	Specifies the name of the unmanaged service. The service name is case-insensitive. If the file contains multiple entries with the same service name, the manager tries each entry in order until an active and available proxy server is found. Service names must use characters in the X Portable Character Set with the exception of the Space, Tab, and Newline characters.
  address	Specifies the address of the proxy server in Inter-Client Exchange (ICE) format.

  
  Currently, no unmanaged service is supplied with DECwindows Motif.

You can configure the proxy manager to start automatically when DECwindows Motif starts or manually at a later time.

Starting at DECwindows Motif Startup

To start the proxy manager at DECwindows Motif startup, either edit the existing SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.COM file or copy the SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.TEMPLATE file to SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.COM and edit the newly created file. For more information, see the section in the Managing DECwindows Motif for OpenVMS Systems manual that describes how to customize the Session Manager environment.

The DECW$PRIVATE_APPS_SETUP.TEMPLATE file contains global symbols that are used to control the behavior of a DECwindows session and its applications. Table 2-3 describes the symbols present in this file that control the proxy manager.

Table 2-3 Global Symbols Controlling the Proxy Manager

Symbol	Description
DECW$PROXY_MANAGER_CONFIG	Specifies the name of the proxy manager's configuration file. The definition of this symbol causes the DECwindows startup process to start the proxy manager. The file name specified by this symbol overrides any configuration file specified in the DECW$PROXY_MANAGER_OPTIONS symbol. A default configuration file, SYS$MANAGER:DECW$LBXPROXY.DECW$PMCFG, is provided at installation time. This file has a single service entry for the LBX service.
DECW$PROXY_MANAGER_LOG	Specifies the name of the file that the proxy manager should use to log events. If the proxy manager starts and this symbol is undefined, the default log file is SYS$MANAGER:DECW$PROXYMANAGER.LOG.
DECW$PROXY_MANAGER_OPTIONS	Specifies any qualifiers that should be included on the XPROXYMANAGER command when the proxy manager is started. Note that the configuration file specified by the DECW$PROXY_MANAGER_CONFIG symbol always has precedence over any value specified by this symbol.
DECW$PROXY_MANAGER_QUOTAS	Specifies any qualifiers to include on the RUN command line used to start the proxy manager.

Starting Manually

To start the proxy manager manually, use the XPROXYMANAGER command:

XPROXYMANAGER [qualifiers]

For example, to start a proxy manager using the configuration file SYS$MANAGER:DECW$LBXPROXY.DECW$PMCFG and the log file SYS$MANAGER:DECW$PM.LOG, use the following command:

$ XPROXYMANAGER/CONFIGURATION_FILE=SYS$MANAGER:DECW$LBXPROXY.DECW$PMCFG - _$ /LOG=SYS$MANAGER:DECW$PM.LOG

2.7.2.3 Qualifiers

Enter XPROXYMANAGER command qualifiers in the same manner as you would for any other DCL command. For proxy managers started at DECwindows startup, you can specify these qualifiers in the definition of the DECW$PROXY_MANAGER_OPTIONS symbol.

/CONFIGURATION_FILE=file-specification

Specifies the configuration file that the proxy manager should use to define the available proxy services.

The default is SYS$LOGIN:DECW$XPROXYMANAGER.DECW$PMCFG.

/LOG=file-specification
/NOLOG

Specifies the log file that the proxy manager should use to log errors. The proxy manager uses this file to record each request for a proxy server. The default is /NOLOG. If the /VERBOSE qualifier is specified, the default is /LOG. If /LOG is specified without a value, the output is sent to SYS$ERROR by default.

If an incomplete specification is entered, the following directory specification is used to complete the command:

SYS$SYSDEVICE:[]DECW$XPROXYMANAGER.LOG

/PORT=integer

Specifies the port number that this server monitors for incoming requests. For the TCP/IP transport, this qualifier specifies an IP port number from the port number space shared by all users of TCP/IP. For the DECnet and Local transports, this qualifier specifies a number that is used to create a unique resource name from the name space of all users of the Inter-Client Exchange (ICE) protocol. Specify a value from 1 to 16383.

The default port number is 6500.

/TRANSPORT="transport-string"

Specifies the transports which this proxy manager monitors for incoming client requests.

The default is /TRANSPORT="LOCAL,DECNET,TCPIP".

/VERBOSE
/NOVERBOSE

Specifies whether the proxy manager should log each proxy request to the proxy manager log file, in addition to error messages.

If the /LOG qualifier is specified, the default is /VERBOSE. If the /LOG qualifier is not specified, the default is /NOVERBOSE.

2.7.2.4 Stopping a Proxy Manager

To stop a proxy manager, you must use the DCL STOP command. The STOP/EXIT=USER_MODE option (new to OpenVMS Alpha Version 7.3-1) is recommended.

Stopping the proxy manager also stops all managed proxy servers controlled by the proxy manager.

2.7.3 Authentication in an LBX Environment

When the proxy server connects to an X server, the proxy server undergoes authentication in the same manner as a client. How the proxy server obtains its authentication information depends on the type of proxy server.

A managed proxy server obtains its authentication information from the proxy manager. The proxy manager in turn receives the authentication information from the client. The client's default authentication information is contained in the client's X authority file. The client can control which X authority file is used by using the /XAUTHORITY qualifier to the SET DISPLAY command. The client can supply explicit authentication information on the SET DISPLAY command using the /LBXAUTHENTICATE and /LBXDATA qualifiers. The client also has the option of using the /NOLBXAUTHENTICATE qualifier to specify that the authentication information come from the proxy server's current X authority file. For more information about the SET DISPLAY command qualifiers for LBX, see Section 1.1.1.

A standalone proxy server obtains its authentication information from the information present in the current X authority file.

This chapter describes new features relating to system and application programming in the HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 environment. The features described in this chapter include new extensions, libraries, and functions available with the standard X11R6.6 implementation as well as those that are specific to the DECwindows Motif environment.

For information on how to program X Window System applications, see the X Window System and X Window System Toolkit (Scheifler and Gettys) series of manuals published by Butterworth-Heinemann.

3.1 Multithreading Support

HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 adds support for multithreaded client applications. Client applications that use the Compaq POSIX Threads Library or Compaq Ada tasks are now fully supported in the HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 environment.

Additionally, each of the following libraries are now fully thread-safe, supporting simultaneous calls from multiple threads:

• X11 library (Xlib)
• X Toolkit intrinsics library (Xt)
• X Extensions library
• Inter-Client Exchange (ICE) library
• Session Management Protocol (XSMP) library

Client applications linked against previous versions of DECwindows Motif are binary compatible with HP DECwindows Motif for HP OpenVMS Alpha Version 1.3, with the exception of those applications that use any changed or retired Xlib entry points documented in this manual as well as the hp DECwindows Motif for hp OpenVMS Alpha Release Notes.

An existing client application requires recompilation against the X11R6.6-compatible X Window libraries if the application:

• Produces a shared image potentially used by other multithreaded applications. If the image can be restricted to a single-threaded environment, binary compatibility is preserved and recompilation is not necessary. However, if an image uses any of the following macros defined in DECW$INCLUDE:XLIBINT.H, it must be recompiled:
  • LockDisplay
  • UnlockDisplay
  • LockMutex
  • UnlockMutex
• Uses the ConnectionNumber macro or XConnectionNumber function and assumes the return value is an event flag.
• Uses the XSelectAsyncEvent or XSelectAsyncInput function.
  Also note, that if an application uses the previous version of the CompositeClassExtensionRec structure, Xt warning messages may be generated.

  Note HP discourages the use of XSelectAsyncEvent and XSelectAsyncInput since they are non-standard functions. The equivalent functionality can be obtained by using threaded Xlib functions.

DECwindows Motif has always supported calls from user mode Asynchronous System Trap (AST) handlers as well as from normal user mode. With HP DECwindows Motif for HP OpenVMS Alpha Version 1.3, any application that enables support for multiple threads can no longer make calls to most X Window libraries from AST handlers, even when concurrent calls are restricted. The only supported exception is XtNoticeSignal, which can be called from AST handlers.

3.1.2 Levels of Thread Safety and Concurrency

New and existing DECwindows Motif shared images can be grouped according to the following levels of thread safety:

• Thread-safe--The image can be called concurrently from multiple threads.
• Thread-aware--The image can be used in an application that includes multiple threads. However, the application code must avoid making concurrent calls to the image, typically by using a global lock.
• Thread-unsafe--The image cannot be used in any application that has multiple thread support enabled.

Table 3-1 shows the current thread safety level for each of the DECwindows Motif shared images. Note that all images in the Translated Image Environment are thread-unsafe.

Table 3-1 Level of Thread Safety for DECwindows Motif Images

Image	Level of Thread Safety
DECW$AILSHR.EXE	unsafe
DECW$AILSHRR5.EXE	unsafe
DECW$BKRSHR.EXE	aware
DECW$BKRSHR12.EXE	aware
DECW$D2DXLIBSHR.EXE	aware
DECW$DWTLIBSHR.EXE	aware
DECW$DXMLIBSHR.EXE	aware
DECW$DXMLIBSHR12.EXE	aware
DECW$ICELIB.EXE	safe
DECW$LCNLIBSHR.EXE	safe
DECW$MAILSHR.EXE	unsafe
DECW$MAILSHR12.EXE	unsafe
DECW$MRMLIBSHR12.EXE	aware
DECW$PRINTWGTSHR.EXE	aware
DECW$SMSHR.EXE	safe
DECW$TERMINALSHR.EXE	aware
DECW$TERMINALSHR12.EXE	aware
DECW$XEXTLIBSHR.EXE	safe
DECW$XLIBSHR.EXE	safe
DECW$XMLIBSHR.EXE	aware
DECW$XMLIBSHR12.EXE	aware
DECW$XMULIBSHR.EXE	aware
DECW$XMULIBSHRR5.EXE	aware
DECW$XTLIBSHRR5.EXE	safe
DECW$XTRAPLIBSHR.EXE	aware
DECW$XTRAPLIBSHRR5.EXE	aware
DECW$XTSHR.EXE	aware

In addition to thread safety, HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 libraries offer varying levels of concurrency when called from multiple threads:

• X and X Extension libraries
  For most operations, Xlib and X Extension libraries allow a single concurrent operation on each display connection. If XOpenDisplay is called twice to open two separate server connections, both connections can be operated upon at the same time. However, there are a few operations for which a global lock is needed to prevent corruption of global data.
  Note that XSelectAsyncInput and XSelectAsyncEvents are not supported if multithreading has been enabled by a call to XInitThreads.
• X Toolkit Intrinsics library
  For most operations, Xt allows a single concurrent operation on each application context. There are a few operations for which a global lock is needed to prevent corruption of global data.
• Inter-Client Exchange and Session Manager libraries
  ICE and XSMP operations allow a single concurrent operation on each ICE connection.
• Transport library
  The transport library is used to communicate between the client application and the X server and between multiple client applications that use the ICE library. The final level of the transport code (which can communicate via global sections, DECnet, or TCP/IP) executes in OpenVMS inner mode, and as a result is serialized by the operating system.
  Running on only one kernel thread at a time, this code temporarily blocks all other kernel threads making OpenVMS system calls that execute in inner mode. However, whenever the transport code is blocked, such as when waiting for a connection to open or for a reply to arrive, it is blocked at user mode allowing other threads to execute and use the transport.