6    Documentation Notes

This chapter contains release notes that apply to Digital UNIX Version 4.0B documentation.

6.1    General Information About the Documentation

The following sections provide general information about changes to the Digital UNIX documentation set.

6.1.1    Revised Documentation

The following books have been updated for this release:

• Installation Guide

• System Administration

• Writing VMEbus Device Drivers

• Guide to Preparing Product Kits

Refer to the Documentation Overview, Glossary and Master Index for more information on existing volumes.

6.1.2    List of Available Patches

Lists of patches for known problems are provided on the Digital UNIX Operating System Volume 1 CD-ROM, in the following directory:

<mount point>/DOCUMENTATION/TEXT

The files are named as follows

Digital_UNIX_V3_2C_CLD_Fixes.txt Digital_UNIX_V3_2D_CLD_Fixes.txt Digital_UNIX_V3_2G_CLD_Fixes.txt Digital_UNIX_V4_0_CLD_Fixes.txt Digital_UNIX_V4_0A_CLD_Fixes.txt Digital_UNIX_V4_0B_CLD_Fixes.txt

6.1.3    Compressed PostScript Files

Some PostScript format files on the documentation CD-ROM can be stored in compressed PostScript. This compressed format saves disk storage space and requires less time to copy the files to other media. To decompress the files, use the uncompress or zcat commands.

There is an instruction file on the CD-ROM named as follows:

/DOCUMENTATION/POSTSCRIPT/00-READ-ME-FIRST

This chapter provides documentation release notes, and information on using the enhancements in Version 4.0B.

6.2    Reference Pages

This section provides information about the Digital UNIX Version 4.0B reference pages.

6.2.1    webman Utility for Netscape

The Digital UNIX system's documentation CD-ROM includes a tool called webman, which allows you to view the reference pages with the Netscape Navigator World Wide Web browser.

However, because of security restrictions imposed by the browser, it is not possible to view the files by opening them locally on the user's own system. Making the reference pages viewable requires that you set up your system (or one of the systems on your network) as a World Wide Web server by installing and running a server daemon. With a server running, all of the systems on your network can view the reference pages. Server software is available from third-party vendors such as Netscape Communications Corporation.

When the documentation CD-ROM is mounted as instructed in the Installation Guide, instructions for installing webman are in the following file:

/usr/share/doclib/online/DOCUMENTATION/HTML/webman/Installing_webman.txt

6.3    Device Driver Tutorial

Section 14.1.1 of Writing Device Drivers: Tutorial states that you should create a directory to contain your driver source as follows:

#  mkdir  /usr/sys/io/ESA100

When you create a new directory to replace ESA100 you must place it in the path /usr/sys/io/ using your directory selection to replace ESA100.

6.4    Network Administration Manual

The following sections describe changes to the Network Administration manual.

6.4.1    Section 4.2.2.2, "Verifying PPP Support in the Kernel" is Obsolete

Use the following instructions instead:

To verify that PPP is supported in the kernel, enter the following command:

#  sysconfig -s | grep ppp

If it is not loaded and configured, do the following:

1. Log in as root.

2. Save the /vmunix file.

3. Rebuild the kernel by running the doconfig program and selecting the Point-to-Point (PPP) option.

4. Copy the new vmunix file to /vmunix.

5. Edit the /etc/sysconfigtab file and add the following lines:

   ppp:
   nppp=2
   

   This provides for 2 PPP connections. If your system requires a greater number of PPP connections, increase the number.

6. Reboot the system.

6.4.2    Sections 4.2.3.1, 4.2.3.2, and 4.2.3.3 Are Obsolete

Use the instructions in the following sections instead.

6.4.2.1    Establishing a PPP Dial-Out Connection

After you have connected your modem to a serial port on your system, do the following:

1. Verify that you can communicate with the modem. Do the following:

   1. Edit the /etc/remote file and copy the kdebug entry.

   2. Modify the new entry, providing a system name for the entry, the correct Digital UNIX device (tty00 or tty01 depending on your system), the correct baud rate, and correct parity. See remote(4) for more information.

   3. Use the tip command to access the modem as follows:

      %  tip system_name
      

      system_name is the system name from the /etc/remote file.

   4. If your modem is using the AT command language, enter the following command:

      AT[Return]
      

      If the modem is not in quiet mode, it responds with an OK message.

2. Contact the remote system administrator or your internet service provider (ISP) and obtain the following information:

   • Your remote IP address and netmask, unless the remote system assigns the IP address dynamically

   • Characters that might need to be escaped

   • Instructions on how to log in and use the remote service

   This information is used to create a chat script, which automates the dial-out process.

3. Create a file for commands that the chat program uses to direct the modem what number to dial and what to send the remote system in order to start pppd. This file is called a chat script. Each entry in a chat script has the following format:

   string_chat_expects string_chat_sends

   For example, the following file, named /etc/ppp/chat-script, contains the following information:

    atdt2135476    [1]
   CONNECT     [2]
   login: myname      [3]
   Password: "\qmypassword"    [4]
   "$ " "\qpppd"       [5]
   

   1. chat expects nothing and sends a dial command to the modem. [Return to example]

   2. chat expects a CONNECT message and sends a carriage return (implied). [Return to example]

   3. chat expects the login: string and sends the myname string. [Return to example]

   4. chat expects the Password: string and sends the mypassword string. The eq prevents chat from logging it when you use the -v option. [Return to example]

   5. chat expects the $ (the shell prompt) and sends pppd to start the pppd daemon on the remote machine. The eq cancels the effect of the previous eq. [Return to example]

   See chat(8) for more information on chat and chat scripts.

   Note

   You might want to use the tip command to dial out and log in to the remote system and to write down the exact prompt, login sequence, and pppd start-up sequence.

4. Edit the /etc/ppp/options file and include the following pppd options as required by the remote system or ISP:

   defaultroute   [1]
   asyncmap 0  [2]
   mru 296 [3]
   netmask dd.dd.dd.dd  [4]
   lcp-echo-interval 60  [5]
   lcp-echo-failure 5   [6]
   noipdefault  [7]
   crtscts  [8]
   debug  [9]
   

   1. If you system is standalone and you are connecting to the Internet through the remote system, add a default route via the remote host by specifying this option. [Return to example]

   2. If the serial line is not completely 8-bit transparent, specify this option; asyncmap 200a0000 is appropriate if the serial link includes a telnet link. [Return to example]

   3. Reduces the MRU (maximum receive unit) on the local and remote systems to improve performance for multiple IP connections. [Return to example]

   4. Sets the interface netmask to the specified value. Your ISP should provide this information. [Return to example]

   5. Sends a Link Control Protocol (LCP) echo request frame to the remote system every 60 seconds. This determines whether the link to the remote system is still active. [Return to example]

   6. If the local system does not receive a response from the remote system after five LCP echo request frames, pppd considers the link dead and tears down the connection. [Return to example]

   7. Specifies that the remote system (ISP) is to provide an IP address to the local system, unless an IP address is specified explicitly on the command line or in an options file. [Return to example]

   8. Enables hardware flow control on the serial device. If the modem does not support hardware flow control, do not add this entry. See your modem documentation to verify this information. [Return to example]

   9. Enables debugging. All log messages are sent to the file specified in the /etc/syslog.conf file. After your connection is working correctly, remove this entry from the PPP options file. [Return to example]

   See pppd(8) for a complete list of pppd options.

5. Edit the /etc/syslog.conf file and do the following:

   1. Add the local2 facility (used by pppd and chat) to the line that specifies /dev/console as the message destination as follows:

      kern.debug;local2.notice      /dev/console
      

      In this example, the notice level is specified.

   2. Add the following entry to the file to create a ppp-log file:

      local2.debug       /etc/ppp/ppp-log
      

   3. Save the edits and close the file.

6. Stop and restart syslogd by entering the following commands:

   #  /sbin/init.d/syslog stop
   #  /sbin/init.d/syslog start
   

7. Invoke pppd on the local system to connect to the remote system. For example, the following command starts a link on tty01 and specifies the connect option to run the chat program using the specified chat script file.

   %  pppd /dev/tty01 38400 connect 'chat -v -f /etc/ppp/chat-script'
   

8. Issue the following command to monitor the ppp-log file and to determine whether the PPP connection is active:

   %  tail -f /etc/ppp/ppp-log
   

If any problems occur while using PPP, see Chapter 13 in Network Administration.

6.4.2.2    Establishing a PPP Dial-In Connection

After you have connected your modem to a serial port on your system, to configure a dial-in system, complete the following steps:

1. Set up your modem for dial-in access. See Section 4.3.2 in Network Administration for more information.

2. Edit the /etc/passwd file and create a dedicated entry for a PPP user. For the login shell field, specify /usr/sbin/startppp; for example:

   ppp1:password:10:20:Remote PPP User:/usr/users/guest:/usr/sbin/startppp
   

3. Edit the /etc/inittab file and create an entry for each terminal device that is to run PPP. For example:

   modem:3:respawn:/usr/sbin/getty /dev/tty00 M38400 vt100
   

   See inittab(4) for more information.

4. Issue the init q command to start the getty process immediately.

5. If the dial-in system is going to be a gateway for the dial-out system to reach other systems on the LAN, the dial-in system must be configured as IP router and must also run gated. Edit the /etc/gated.conf file and delete the nobroadcast option (if specified) in the rip statement. See Chapter 2 of Network Administration for basic network setup information and gated.conf(4) for gated options.

6. Edit the /etc/ppp/options file and include the following pppd options required to support dial-in access for all remote users:

   netmask dd.dd.dd.dd  [1]
   proxyarp  [2]
   crtscts  [3]
   asyncmap 0  [4]
   :remote_ip_address  [5]
   debug  [6]
   

   1. Sets the interface netmask to the specified value. [Return to example]

   2. Adds an entry to the local system's Address Resolution Protocol (ARP) table containing the IP address of the remote system and the Ethernet address of the local system. This is not necessary if gated is running. [Return to example]

   3. Enables hardware flow control for the serial port. [Return to example]

   4. If the serial line is not completely 8-bit transparent, specify this option; asyncmap 200a0000 is appropriate if the serial link includes a telnet link. [Return to example]

   5. Specifies an IP address for the remote system. [Return to example]

   If you want to specify options for each individual serial port, create a /etc/ppp/options.ttyxx file and include the remote IP address and any other options that apply to that specific serial port. See pppd(8) for a complete list of pppd options.

7. After an incoming call is received and a connection established, startppp runs in the background. The process ID is logged in the /etc/ppp/pppxx.pid file.

8. Enables debugging. All log messages are sent to the file specified in the /etc/syslog.conf file. After your connection is working correctly, remove this entry from the PPP options file.

If any problems occur while using PPP, see Chapter 13 in Network Administration.

6.5    System Administration Guide

The following notes describe changes to the System Administration Guide.

6.5.1    Environmental Monitoring

In the Environmental Monitoring section, the System Administration Guide incoreectly states:

When a fan failure is encountered, a message is broadcasted and an orderly shutdown ensues.

It should state:

When the cooling fan on an AlphaServer 1000A fails, the kernel logs the error, synchronizes the disks, then powers the system down. On all other fan failures, a hard shutdown ensues.

6.5.2    User Definable Messages in Environmental Monitoring

Any messages broadcasted or logged by the Environmental Monitoring utility can be modified. The messages are located in the following file:

/usr/share/sysman/envmon/EnvMon_UserDefinable_Msg.tcl

You must be root to edit this file. You can edit any message included in braces ({}). The instructions for editing this file are included in the comment (#) fields. Do not alter any other data in this file.

6.6    Technical Overview

The information on Maximum System Limits has moved from the Technical Overview to the Release Notes.

6.7    Assembly Language Programmer's Guide

The Assembly Language Programmer's Guide (Chapter 5) should include a description of the .rconst directive. This directive instructs the assembler to add subsequent data into the .rconst section. This behavior is similar to the .rdata directive, except that the entries cannot be relocatable.

6.8    DEC C Language Reference Manual

In the DEC C Language Reference Manual, the conventions table states that the DEC C extensions to the ANSI C standard are shown in teal in the printed manual, and are shaded in the online manual. This is incorrect.

6.9    Online Help Volumes.

The notes in this section refer to problems with the online help volumes.

The Help viewer has the following known problem:

• In some cases, the help viewer is not correctly initialized. As a result, it will sometimes exhibit the expected behavior the second time an action is taken, but not the first time.

  For example, the first time a quick help dialog box displays a reference page, the Backtrack button may be enabled even though there is no place to which to backtrack. If the dialog box is closed and then opened again, the Backtrack button is dimmed.

• Similarly, if a request for on-item help displays the correct help, but one line has scrolled off the top, the online help will typically be displayed in exactly the right position when the on-item help request is repeated.

For each of the SysMan applications online help is available from the Help menu or from the Help button in the main window.

The online help contains:

• An overview of the capabilities of the application

• A set of tasks illustrating typical uses of the application

• A reference section documenting every window and dialog box in the application.

The Using Help item on the Help menu displays a help volume supplied by CDE that explains how to use the online help.

6.9.1    General Problems

The following known problems occur in the online help:

• The Appearance menu is not consistently documented.

  In the Archiver, License Manager, and System Information applications, there is an Appearance item on one of the menus. The item should offer three options: Text Only, Large Icon, and Small Icon. In some help volumes, not all of these are documented.

• Some links from one help volume to another are displayed in a new view.

  There are a few links from one help volume to another that display in a new help viewer window. In some situations, a distracting proliferation of help viewer windows can result.

  You can get a new view when you want one using the New Window item on the File menu in the help viewer.

6.9.2    Integration

The SysMan configuration applications on-item help does not work on the items in the menu bar.

In all the SysMan applications, the keyboard method of getting on-item help does not work on the Help menu.

6.9.3    Help Volumes by Application

The following problems apply only to help in specific applications:

• Kernel Tuner

  The Kernel Tuner application records its changes immediately, so if a system failure occurs while the Kernel Tuner is running, any boot time changes will take effect the next time the system boots. If the file /etc/sysconfigtab contains invalid values, you can enter the following command at the boot prompt to boot using default values:

  boot -fl c
  

• Display Window

  The help volume for Display Window has opening instructions that show how to access the application from the CDE Application Manager. These should show that the Display Window icon appears in two groups.

• Network Configuration

  The names of the gated, joind, routed, and rwhod daemons are misspelled in the online help volume.

  In the Configuring Interfaces dialog box, the fields under To Obtain IP Address are relevant for all interfaces.

• Printer Configuration

  In the Local Printer Settings dialog box and the Remote Printer Settings dialog box, the aliases in the Printer Aliases field must be separated by vertical bars because spaces are allowed in an alias.

• Shutdown

  The /usr/sbin/shutdown command now sends the Shutdown Message each time a reminder is sent of the time remaining before the system is shut down.

  The /etc/nologin file is not created until immediately before the shutdown occurs.

  System shutdown messages are sent to all users that are locally or remotely logged-into the system being shutdown. Additionally, if the Broadcast to NFS Clients" option is selected, shutdown messages are broadcast to all hosts that are NFS clients of the system being shutdown.

• Disk Configuration

  The following corrected definitions replace the definitions in the glossary for Disk Configuration.

  • Skew

    A deviation from a reference direction, either by design or in response to lateral forces.

  • Track skew

    On a disk, the sector skew per track. The skew is the angle that sector 0 of the track changes from an imaginary radius line, due to a nonuniform number of sectors per track.

• BIND Configuration

  The following corrected definitions replace the definitions in the glossary for BIND Configuration:

  • BIND client

    A system that queries a BIND server for host name and address information, interprets the responses, and passes the information to requesting applications.

  • BIND server

    An authoritative source for information about one or more zones. It either maintains the master copy of the hosts database for the zone or obtains the information required to serve the hosts database from another server.

  • DCE

    Distributed Computing Environment. The capabilities of DCE are defined by the Open Software Foundation (OSF).

  • DCE cell

    A logical group of systems that share services offered by DCE.

  • DCE server

    The server in a DCE cell.

  • service type

    In BIND Configuration, the available service types are BIND client and BIND server. The service type determines whether a system is configured to be a BIND client or a BIND server.

6.10    Online PostScript Format Documentation

The Digital UNIX documentation set includes documents that are available only in PostScript format. The following list describes these documents and their locations:

• Digital UNIX Software Product Description

  The Software Product Description (SPD) is a legal description of the Digital UNIX product. It describes the software and gives information about its capabilities and about the hardware it supports. This information is intended for anyone who needs a legal description of the Digital UNIX product.

  The SPD is provided on the operating system distribution media in both PostScript and text versions. To obtain a copy of the PostScript version, mount the Digital UNIX V4.0 Operating System, Volume 1 CD-ROM. Then change to the mnt_point/DOCUMENTATION/POSTSCRIPT directory and print the following files:

  Digital_UNIX_Developers_Toolkit_SPD.ps
  Digital_UNIX_Logical_Storage_Manager_SPD.ps
  Digital_UNIX_Operating_System_SPD.ps
  Digital_UNIX_Server_Extensions_SPD.ps
  Prestoserve_for_Digital_UNIX_SPD.ps
  

  To obtain a copy of the text version, change to the mnt_point/DOCUMENTATION/TEXT directory and print the following files:

  Digital_UNIX_C_Developers_Extensions_SPD.txt
  Digital_UNIX_Logical_Storage_Manager_SPD.txt
  Digital_UNIX_Operating_System_SPD.txt
  Digital_UNIX_Server_Extensions_SPD.txt
  Prestoserve_for_Digital_UNIX_SPD.txt
  

• GNU Emacs Manual

  This manual (developed by the Free Software Foundation) provides information about how to use and customize the Emacs text editor. It is primarily a reference manual, but can also be used as a tutorial.

  This manual is intended for general users and anyone who uses Emacs. You can obtain a copy of this manual by printing the following file:

  /usr/lib/emacs/doc/emacs.ps

  This file is available only if the FSFEMACSSRC*** subset is installed on your system. (To use Emacs, install the OSFEMACS*** subset.)

• GNU Emacs Lisp Reference Manual

  This manual (developed by the Free Software Foundation) describes Emacs Lisp and presumes considerable familiarity with how to use the Emacs text editor. The earlier chapters describe Emacs features that have counterparts in many other programming languages. The later chapters describe features that are peculiar to Emacs Lisp or relate specifically to editing.

  This manual is for programmers. You can obtain a copy of this manual by printing the following file:

  /usr/lib/emacs/doc/elisp.ps

  This file is available only if the FSFEMACSSRC*** subset is installed on your system. (To use Emacs Lisp, install the OSFEMACS*** subset.)

• Display PostScript Documentation Supplements

  The Display PostScript system is described in the manual PostScript Language Reference Manual which is available in printed format from Digital. To update the Display PostScript documentation, Adobe System, Inc. provides a number of supplements describing new and changed features of the Display PostScript system.

  The Display PostScript documentation supplements are provided in compressed format in the following directory:

  /usr/share/doclib/dps

  Before you can print a copy of one of the supplements, you must uncompress that supplement. For example, to uncompress the Level 2 Changes for X, issue the following command:

  %  uncompress /usr/share/doclib/dps/\
  Developer-TechNote.1-001.ps.Z
  

  You can then print the resulting, uncompressed file:

  /usr/share/doclib/dps/\
  Developer-TechNote.1-001.ps

  You might want to remove the PostScript file once you have printed it to save space on your system.

  The following list describes the Display PostScript documentation supplements:

  • Level 2 Changes for X

    This supplement describes the changes made to the X implementations of the Display PostScript system for PostScript Level 2. This supplement is provided in the following file:

    Developer-TechNote.1-001.ps.Z

  • Type 2 Image Dictionary

    This supplement describes the Type 2 image dictionary, an operand for the image operator in the Display PostScript system. The Type 2 image dictionary is an extension to the Type 1 dictionary. It allows the image operator to use pixel data from a pixmap, the current window, or another window as source when copying into the current window. This supplement is provided in the following file:

    Developer-TechNote.1-002.ps.Z

  • Multiple Master Fonts in the DPS Toolkit Font Panel

    This supplement describes new support for multiple master fonts in the Display PostScript Toolkit for X font panel. The supplement also describes how the font panel supports nontypographic sorting and a value-changed callback. This supplement is provided in the following file:

    Developer-TechNote.1-003.ps.

  • Writing Applications That Use the Resource Location Library

    This supplement describes how applications can use resource paths to become easier to use and customize. Resource paths are included in calls to the resource location library, which applications can use to find resources such as fonts. This supplement is provided in the following file:

    Developer-TechNote.1-004.ps.

  • PostScript(tm) Language Reference Manual Supplement

    The version 2015 supplement to the PostScript(tm) Language Reference Manual which contains all updates that manual (232pp).

    2015supplement.ps.Z.

  • Adobe ShowPS Quick Reference (Card)

    This Quick Reference card describes the command syntax and lists the available X resources, command options and keyboard commands.

    ShowPSReferenceCard.ps

  • Adobe ShowPS User Guide

    General instructions for installing, starting and using the Adobe ShowPS PostScript previewer. Contains tutorial material and a troubleshooting guide (72pp).

    ShowPSUserGuide.ps.Z.

  • Adobe ShowPS Brochure

    A sample brochure in overhead format that gives an overview of the Adobe ShowPS PostScript previewer (5pp).

    ShowPS_Brochure.ps.Z.

• X Image Exension documentation

  The X Image Extension (XIE) code (developed by the X Consortium) provides a powerful mechanism for the transfer and display of virtually any image on X-capable hardware. Documentation for XIE is provided in compressed format in the following directory:

  /usr/share/doclib/xie

  Before you can print a copy of one of the XIE manuals, you must uncompress that manual. For example, to uncompress the X Image Extension Overview, issue the following command:

  %  gzip -d /usr/share/doclib/xie/xie_overview.ps.Z
  

  You can then print the resulting, uncompressed file:

  /usr/share/doclib/xie/xie_overview.ps.

  You might want to remove the PostScript file once you have printed it to save space on your system.

  The following list describes the manuals that describe the XIE code. A README file is also available in /usr/share/doclib/xie.

  • X Image Extension Overview

    This manual provides general information about the X Image Extension (XIE) code. Topics covered include: XIE design goals, XIE historical summary, XIE architecture, element definitions, and subsetting.

    This manual is provided in the following file:

    /usr/share/doclib/xie/overview.ps.gz

  • XIElib Specification

    This manual contains reference information about the XIElib functions, XIElib events, and XIElib errors. The Functions section covers the following types of functions: startup, LUT, photomap, ROI, photoflo, client data, abort and await, photoflo element, technique, and free.

    This manual is provided in the following file:

    /usr/share/doclib/xie/xielib.ps.gz

  • XIE Sample Implementation Architecture

    This manual provides an architecture overview of XIE, including chapters on the following topics: extension initialization, memory management, request dispatching, data representation, data structures, protocol requests, DIXIE photoflo management, DDXIE photoflo management, and photo elements.

    This manual is provided in the following file:

    /usr/share/doclib/xie/xieSIarch.ps.gz

  • X Image Extension Protocol Reference Manual, Version 5.0

    This manual specifies the X wire protocol for XIE. It defines the syntax, structure, and semantics of the XIE protocol elements. Topics covered include syntax specification, parameter types, resources, pipelined processing, import elements, process elements, export elements, events and errors, techniques, service class, and protocol encodings.

    This manual is provided in the following file:

    /usr/share/doclib/xie/XIEProto.ps.gz

• OSF/Motif Release Documentation

  OSF/Motif release notes and problems have been provided by the Open Software Foundation (OSF). These notes are contained in the following PostScript files:

  • /usr/doc/motif/Motif_rel_notes.ps

  • A list of known problems in Release 1.2.3: /usr/doc/motif/OPENBUGS

  These files are available only if you have installed the OSFXDEV*** subset on your system.

• STREAMS DLPI Paper

  This paper provides the specification for a STREAMS Data Link Provider Interface (DLPI) It complies with DIS 8886 and Logical Link Control (LLC) DIS 8802/2

  This paper is provided uncompressed in the following file:

  /usr/share/doclib/dlpi/dlpi.ps.

Depending on the optional software subsets or environments installed on your system, a number of other documents may also be available in the /usr/doc directory.

6.10.1    PostScript Manuals Replacing Online or Printed Volumes

Several X Window and DECwindows manuals are shipped in PostScript format only. To access these documents, mount the Digital UNIX Version 4.0B Documentation Volume 1 CD-ROM and read the following file:

<mount point>/DOCUMENTATION/POSTSCRIPT/00-READ-ME-FIRST

This file provides a list of documents and instructions for decompressing the files. Depending on the installation at your site, the files may already be mounted at the following location:

/usr/share/doclib/online/DOCUMENTATION/POSTSCRIPT .