Document revision date: 10 November 2000

Use the XSET utility to query the server directly for parameter settings. Running the XSET utility is a good method to determine the current font path.

The following command shows how to invoke the XSET utility. Before executing this command, make sure you have the correct display selected by using the SET DISPLAY command. See Section 4.1 for more information about showing and setting the display.

$ SET DISPLAY/CREATE/NODE=node_name $ MCR DECW$UTILS:XSET Q

The following example illustrates a typical display:

Keyboard Control: auto repeat: on key click percent: 50 LED mask: 00000000 auto repeating keys: 0000000000000000 00000000f0011e20 0ffcfeffff0700d0 ffffffffffffffff bell percent: 50 bell pitch: 400 bell duration: 100 Pointer Control: acceleration: 7 = 7 / 1 threshold: 3 Screen Saver: prefer blanking: no allow exposures: no timeout: 600 cycle: 600 Colors: default colormap: 0x25 BlackPixel: 0 WhitePixel: 1 Font Path: DECW$FONT: Bug Mode: compatibility mode is enabled

This chapter includes the following information that you can use after DECwindows has started.

Topic	Section
Setting the Display	Section 4.1
Using the SHOW DISPLAY Command	Section 4.1.2
The Login Sequence	Section 4.2
Customizing the Session Manager Environment	Section 4.3
Creating a Custom Bookreader Directory	Section 4.3.1
Changing Your Logo	Section 4.3.2
Creating Dedicated Accounts	Section 4.3.3
Modifying Session Manager Behavior	Section 4.4
Modifying System Resource Files	Section 4.5
Customizing Print Formats	Section 4.6

4.1 Setting the Display

When a client application starts up, it opens one or more connections to a display server. The display server can be on the local machine or on a remote node. The application needs to tell the underlying toolkit, Intrinsics, or Xlib routines the node name and other connection information. This information is contained in a string called the display name.

The application can explicitly pass the display name to the underlying routines. Usually, though, the application passes a null display name to the underlying routines. When Xlib opens the display, it translates the logical name DECW$DISPLAY to find the display name. If DECW$DISPLAY is undefined, then Xlib translates the logical name SYS$OUTPUT.

The display name can be in one of the following forms. The brackets ([]) represent optional syntax and are not included as part of the display name.

node::server[.screen] node:server[.screen] WSAn:

node	Specifies the name of the node on which the display server is running. If the node name is followed by two colons, then Xlib uses the DECnet transport to establish the connection to the display server. If the node name is followed by one colon, then Xlib will use the TCP/IP transport. Note that the single-colon syntax is not supported in versions of DECwindows earlier than DECwindows Motif Version 1.2 for OpenVMS.
server	Specifies the (decimal) number of the display server on the host machine. A single CPU can have more than one display. Multiple displays are usually numbered starting with zero.
screen	Optional. Specifies, as a decimal number, the screen to be used on that server. A single server can display on multiple screens, and screens are numbered starting with zero.
WSA n:	Specifies the device name of a WS device that contains the transport, node, server number, and screen number.

Normally, the display is either inherited from a parent process or specified using the DCL command SET DISPLAY. The SET DISPLAY command creates or modifies a WSAn: device and sets the transport, node name, server number, and screen number.

SET DISPLAY also defines the DECW$DISPLAY logical name to point to this device. When Xlib sees that DECW$DISPLAY points to a WSAn: device, Xlib reads the transport, node name, and other information just as if the application had specified them explicitly.

4.1.1 Examples for Setting the Display

The following examples illustrate several methods to set the display.

Example 1

Either of the following two command sequences can be used to run the Clock application displaying to node DOG using the default server and screen numbers and using the DECnet transport.

$ DEFINE DECW$DISPLAY DOG::0 $ RUN SYS$SYSTEM:DECW$CLOCK

$ SET DISPLAY/CREATE/NODE=DOG $ RUN SYS$SYSTEM:DECW$CLOCK

Note that in the SET DISPLAY command the transport defaults to DECnet, and the server and screen numbers both default to zero. The /CREATE qualifier means that a new WSAn: device will be created.

Example 2

Either of the following two command sequences can be used to run the Clock application on node DOG using screen 1 and using the TCP/IP transport:

$ DEFINE DECW$DISPLAY DOG:0.1 $ RUN SYS$SYSTEM:DECW$CLOCK

$ SET DISPLAY/TRANSPORT=TCPIP/SCREEN=1 $ RUN SYS$SYSTEM:DECW$CLOCK

The SET DISPLAY command assumes that the WSAn: device has already been created and the node name has been set to DOG.

Example 3

The following example runs Clock in a detached process and displays the output on the local workstation display:

$ SET DISPLAY/CREATE/TRANSPORT=LOCAL $ RUN/DETACH/OUTPUT='F$TRNLNM("DECW$DISPLAY")' - _$ SYS$SYSTEM:DECW$CLOCK

This method takes advantage of the fact that Xlib translates the logical name SYS$OUTPUT to find the display name if DECW$DISPLAY is undefined. Xlib creates a WSAn: device using the SET DISPLAY command and then translates the DECW$DISPLAY logical name to find the device name of the WS device. Xlib passes this device name as the SYS$OUTPUT of the detached process.

The WS device is similar to the NL device in that QIO reads from the device return end-of-file and QIO writes to the device are ignored.

Example 4

A somewhat more complicated implementation of Example 3 takes advantage of a feature of LOGINOUT.EXE.

If SYS$ERROR points to a WS device, LOGINOUT defines DECW$DISPLAY to be the translation of SYS$ERROR and then redefines SYS$ERROR to be the translation of SYS$OUTPUT. This allows error messages from the detached process to be written to a log file.

$ SET DISPLAY/CREATE/TRANSPORT=LOCAL $ CREATE TEST.COM $ RUN SYS$SYSTEM:DECW$CLOCK $ RUN/DETACH/ERROR='F$TRNLNM("DECW$DISPLAY")' - _$ /INPUT=TEST.COM/OUTPUT=TEST.LOG - _$ SYS$SYSTEM:LOGINOUT

4.1.2 Using the SHOW DISPLAY Command

You can display information from a WS device by using the SHOW DISPLAY command. Example 1 shows the command sequence.

Example 1

$ SET DISPLAY/CREATE $ SHOW DISPLAY

Device: WSA9: [super] Node: 0 Transport: DECNET Server: 0 Screen: 0

You can use the /SYMBOL qualifier to allow the information from the SHOW DISPLAY command to be stored in DCL symbols, as shown in Example 2.

Example 2

$ SHOW DISPLAY/SYMBOL $ SHOW SYMBOL DECW$*

DECW$DISPLAY_NODE == "0" DECW$DISPLAY_SCREEN == "0" DECW$DISPLAY_SERVER == "0" DECW$DISPLAY_TRANSPORT == "DECNET"

In Example 1, WSA9: was created in supervisor mode.

A user with SYSNAM privilege can also create a display in executive mode. A supervisor-mode WS device is deleted when the last channel to it is deassigned, and when the creating process is logged out. However, an executive-mode WS device is not deleted unless the user explicitly deletes it with the SET DISPLAY/DELETE command.

Example 3 shows how a user with SYSNAM privilege can create a WS device in executive mode.

Example 3

$ SET DISPLAY/CREATE/EXEC $ SHOW DISPLAY

Device: WSA10: [exec] Node: 0 Transport: DECNET Server: 0 Screen: 0

When DECwindows is started after a system reboot, the command procedure DECW$STARTAPPS.COM creates an executive mode WS device (initially WSA1:), which is passed to the DECwindows login procedure to create the Start Session display. When the user logs in, this same WS device is used to create Session Manager.

When Session Manager starts an application, the WS device is passed to the application using the DECW$DISPLAY mechanisms described in Section 4.1. An example of this is a DECTERM window created from Session Manager (assuming that no SET DISPLAY commands have been issued in that window).

Note that a DECwindows application started from that DECTERM window displays on the local node without the user having to issue a SET DISPLAY command.

4.2 The Login Sequence

This section describes the DECwindows login process that begins when the Start Session dialog box appears to after Session Manager starts.

When you enter a correct user name and password in the Start Session dialog box, the following events occur:

1. LOGINOUT.EXE calls routines within DECW$LOGINOUT.EXE to perform the following functions:
   1. Checks the DW-MOTIF license to verify that the system is licensed to open connections to the display server. If not, DECW$LOGINOUT.EXE displays a warning message, restarts itself, and exits. A new Start Session dialog box displays.
   2. Changes the input pointer to a watch cursor.
   3. Modifies the security list to allow you to run applications that connect to the display server.
   4. Starts a process that executes DECW$WAITFORSM.EXE, which holds a connection to the server during the startup process.
   5. Sets the process name to DECW$SESSION.
   6. Intializes the Start Session process's accumulated CPU time to zero so that the user process is not charged for time spent displaying the Start Session dialog box.
   7. Passes SYS$MANAGER:DECW$STARTSM.COM as the command procedure that DCL executes.
   8. Exits. DCL takes control of the process.
2. SYS$MANAGER:DECW$STARTSM.COM executes as Session Manager's default DCL command procedure. It performs the following functions:
   1. If the logical name DECW$SM_WSQUOTA is defined, sets the Session Manager process's working set quota to the value of the logical name.
   2. Executes the system login command procedure as determined by the SYS$SYLOGIN logical name. By default, this is SYLOGIN.COM.
   3. If you did not specify /NOCOMMAND after the user name in the Start Session dialog box, executes your LOGIN.COM (or other login command procedure as specified in the UAF record). You can redefine the DECW$USER_DEFAULTS logical name in your LOGIN.COM to change the directory that is used for your resource files.
   4. Executes SYS$SYSTEM:DECW$WSINIT.EXE to read your workstation customization files. This program opens a connection to the display server and makes Xlib calls to apply your customizations, setting the screen background, pointer shape and color, and other workstation settings. It also creates a property on the root window to communicate your customizations to DECwindows applications that are started later.

      Note If you are logging in to a DECwindows Motif system for the first time after having used the XUI version of DECwindows, DECW$WSINIT.EXE will read your XUI resource files and convert them to DECwindows Motif format.

   5. Executes SYS$MANAGER:DECW$SYLOGIN.COM, if it exists.
   6. Executes SYS$LOGIN:DECW$LOGIN.COM, if it exists.
   7. Runs SYS$SYSTEM:DECW$SESSION.EXE to start Session Manager.

DECwindows Motif provides a template file that you can modify to customize the login sequence. The file is named:

SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.TEMPLATE

By using this file, you can modify the client areas listed in Table 4-1.

Table 4-1 Client Areas That Can Be Modified

Client Area	Global Symbol	Default
Directory used by Bookreader to find online books	DECW$BOOK	SYS$SYSROOT:[DECW$BOOK]
Directory for FileView command files	VUE$LIBRARY	DECW$SYSCOMMON: [VUE$LIBRARY.USER], DECW$SYSCOMMON: [VUE$LIBRARY.SYSTEM]
Directory for keymap files	DECW$KEYMAP	DECW$SYSCOMMON: [SYS$KEYMAP.DECW.USER], DECW$SYSCOMMON: [SYS$KEYMAP.DECW.SYSTEM]
Directory for DECwindows example programs	DECW$EXAMPLES	SYS$SYSROOT:[SYSHLP.EXAMPLES.DECW]
Directory for XDPS example programs	XDPS$EXAMPLES	SYS$SYSROOT:[SYSHLP.EXAMPLES.XDPS]
DCL command executed when DECwindows startup is complete	DECW$MAINAPP	Run SYS$SYSTEM:DECW$STARTLOGIN
Login logo	DECW$LOGINLOGO	None
Parameters to the SET DISPLAY command	DECW$APPSNODE DECW$APPSSERVER DECW$APPSSCREEN	Node 0 Server 0 Screen 0
Command procedure that runs after user authorization is complete	DECW$SESSIONCOM	SYS$MANAGER:DECW$STARTSM.COM
DECwindows SYLOGIN command procedure	DECW$SYLOGINCOM	None
Command that initializes the workstation with the correct user resource values	DECW$SESSIONINIT	Run SYS$SYSTEM:DECW$WSINIT
Command that runs a session	DECW$SESSIONMAIN	Run SYS$SYSTEM:DECW$SESSION
Command that resets a session	DECW$SESSIONEND	None
Log file for DECwindows LOGINOUT	DECW$LOGINLOG	None
Use of multiple connections during loginout	DECW$LOGINMANY	False
Log file for Session Manager can be turned off	DECW$SESSIONLOG	Log file on
Directory for computer-based instruction files	DECW$CBI	SYS$SYSROOT:[SYSCBI.DECW$CBI]
Directory where FileView creates public profile files	VUE$LIBRARY_WRITE	SYS$COMMON:[VUE$LIBRARY.USER]
Directory for utilities	DECW$UTILS	SYS$SYSROOT:[SYSHLP. EXAMPLES.DECW.UTILS]
Login logo can be run in a subprocess	DECW$LOGINLOGOSUB	False (detached process)
Define logical names for UNIX compatibility	DECW$UNIXLOGICALS	True
Require login or pause to perform snapshot	DECW$SNAPSHOT_SECURITY	True

To customize any of these areas, copy the SYS$MANAGER: DECW$PRIVATE_APPS_SETUP.TEMPLATE file to SYS$MANAGER: DECW$PRIVATE_APPS_SETUP.COM, as in the following example:

$ COPY SYS$COMMON:[SYSMGR]DECW$PRIVATE_APPS_SETUP.TEMPLATE - _$ SYS$COMMON:[SYSMGR]DECW$PRIVATE_APPS_SETUP.COM/LOG

Then edit the file to change the appropriate symbol.

The remaining sections in this chapter contain examples for customizing the DECwindows client environment using the template file.

This file contains two sections, a Cluster Common section, and a Cluster Member Workstation-Specific section. Add the new symbol to the appropriate section.

4.3.1 Creating a Custom Bookreader Directory

When you start Bookreader, the system uses the logical name DECW$BOOK to locate the file LIBRARY.DECW$BOOKSHELF. By default, the logical name DECW$BOOK equates to SYS$SYSROOT:[DECW$BOOK]. You can create a private directory containing the file LIBRARY.DECW$BOOKSHELF.

To do this, you need to create the directory and then define a global symbol in the DECW$PRIVATE_APPS_SETUP.COM file.

To create a private Bookreader directory called SYS$COMMON: [DECW$BOOK_LOCAL], you need to:

1. Create the directory, giving the world read access as in the following example:

   $ CREATE/DIRECTORY/PROTECTION=WORLD:R - _$ SYS$COMMON:[DECW$BOOK_LOCAL]

2. Copy the Bookreader LIBRARY.DECW$BOOKSHELF file to the new directory.

   $ COPY SYS$SYSROOT:[DECW$BOOK]LIBRARY.DECW$BOOKSHELF - _$ SYS$COMMON:[DECW$BOOK_LOCAL]/LOG

3. If the SYS$MANAGER directory does not contain the DECW$PRIVATE_APPS_SETUP.COM command file, copy the template file to a command file.

   $ COPY SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.TEMPLATE - _$ SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.COM/LOG

4. Edit the file and define the global symbol DECW$BOOK to point to your personal Bookreader directory.
   Add the following line:

   $ DECW$BOOK == "SYS$COMMON:[DECW$BOOK_LOCAL]"

5. Restart DECwindows Motif using the following command:

   $ @SYS$MANAGER:DECW$STARTUP RESTART

	privacy and legal statement
6300PRO_005.HTML