Release Notes for the Online Documentation Library BNU V2.1 ----------------------------------------------------------- This release of the Bookshelf Navigation Utility (BNU) contains the following otherwise undocumented feature: o Limited support for PDF and PS files. The keywords "PDF" and "PS" are now supported in the ODL shelf file syntax. If encountered, the BNU will invoke Netscape Navigator on these files. Netscape Navigator for OpenVMS, when it does not recognize the file type, goes to the "default filetype" handler, which invokes the "Save As" option. This allows the user to save the file to another location for printing or later viewing on another platform that supports viewing PDF files. Netscape Navigator Version Upgrade: ---------------------------------- If your existing installed version of Netscape Navigator is earlier than V3.03, the ODL V2.1 installation will remove it before installing the latest Netscape Navigator for OpenVMS (Navigator Gold V3.03). "Options" settings, bookmarks, etc. are retained from your prior version of Navigator if present. Note that OpenVMS Alpha Version 6.2 or higher, or OpenVMS VAX Version 6.1 or higher is required. DECwindows Motif Version 1.2-4 for OpenVMS is also required. If you have DECWindows for OpenVMS Version 1.2-3, you must obtain the necessary upgrade patches prior to running the ODL setup script. To obtain these patches or more information on upgrading to the latest version of Navigator for VMS, refer to the following URL: http://www.openvms.digital.com/openvms/products/ips/ Additional Netscape Navigator documentation can be accessed from the Software Product Library CD-ROMs. Notes on Search: --------------- Search performance, particularly on shelf and book content, is recognized to be a serious problem. In efforts keep both the size and cost of the ODL to a minimum and to be able to provide some level of search capability, the existing functionality without indexing or caching was introduced. By using "New BNU" and creating more processes, the user can continue to interact with BNU while the search is taking place. Searching on shelf and book titles first, and limiting the scope of the search, particularly when searching on shelf and book content, is recommended. To give an example of typical search times, searching "Shelf and Book Content" on the entire DIGITAL UNIX ODL (one locally mounted CD) on an AlphaStation 600 with 128M of memory takes approximately eight minutes. A loaded system accessing multiple remote devices across the network and/or slower CD-ROM drives could take significantly longer. Cancelling a search is typically done with the "Stop Search" button, which stops the search from looking for additional matches at the time it is pressed. Alternatively, it may be desirable to cancel the BNU process that is performing the search operation. This can be accomplished through the use of the "Cancel other (new or search)" option from the "File" pulldown, or, on VMS, by exiting the BNU that the new BNU that started the search operation was invoked from. When the search operation begins, an application modal dialog appears stating the type of search being performed on how many books followed by "...". This message changes to indicate the percentage completed and how many matches have been detected at various points during the search. Application modality disallows interaction with all other BNU windows (of the BNU that is searching) at this time, until the search has completed. This is necessary to maintain the integrity of the search (and BNU) data structures during the search. Once this modal dialog is unmanaged (disappears from view) as a result of the search completing or being stopped, the new BNU containing the search results is launched and the ability to interact with the original BNU resumes. Note that depending on your software and hardware configuration, there may be a significant time lapse between the time this window disappears and the time the new BNU containing the search results is managed and visible. Do not click on anything during this interval. Wait for the new BNU window to appear. A similar time lapse is observed when starting a new BNU. Because of the fork and exec startup time, there is not much that can be done to visually indicate the need to wait a few more seconds at this point. Please be patient and give the search results BNU or new BNU a few moments to come up at this time before taking further user action with the search dialog or the rest of the original BNU. Note that additional searches invoke new BNU search windows. Notes on New BNU: ---------------- This option launches a new BNU, and is recommended prior to starting a search to allow continued interaction with the original BNU during the search. The "New BNU" option of the "File" pulldown menu allows the user to start several new BNU processes and search several different strings and/or categories of the ODL concurrently while continuing to browse in the original and/or other new bnus. The filename of the search results file on OpenVMS is "SYS$SCRATCH:BNU_SEARCH_pid_n", where pid is the process id of the BNU that performed the search, and n is the number of searches you currently have active from that BNU. On DIGITAL UNIX, it is "/tmp/bnu_search_pid_n", pid and n as above. Another file is maintained by your set of BNUs and keeps track of new and search BNU titles and process ids. On OpenVMS, it is "SYS$SCRATCH:BNU_PIDS_pid.TMP", and on DIGITAL UNIX it is "/tmp/bnu_pids_pid.tmp", pid as above. These are described here for informational purposes only, as they are created, maintained, and deleted "behind the scenes" by your set of BNUs in a session. New and Search BNUs are titled to describe their ancestry. Your first new BNU is titled "BNU_New.1:". Your second from the original BNU (a sibling to the first) is "BNU_New.2:". Starting a new BNU from your first new BNU appends to the title: it becomes "BNU_New.1_New.1". Search BNUs append the string "_Search.n", where n is the number of searches from that BNU, in a similar fashion. This is particulary relevent on OpenVMS. Cancel Other (New or Search) BNU(s): ------------------------------------ On OpenVMS, fork and exec of a new BNU process creates a "child" process to the original parent. Consequently, when a parent is cancelled (via either the "File Exit" pulldown or by the "Cancel Other (New or Search) BNU(s)", the child and its offspring are also cancelled. Additionally, on OpenVMS VAX only, cancelling a child by issuing a "stop/id=pid" system call from the parent has damaging effects to the parent. On DIGITAL UNIX, fork and exec duplicates and supplants the current process into a distinct process with no lineage. Because of these facts, the features available and behavior of the "Cancel Other (New or Search) BNU(s)" is different across the three platforms. On DIGITAL UNIX, any new BNU and/or the original BNU can cancel any new BNU (new meaning from "Search" or "New BNU") except the one you are currently in. Only the specified BNU will exit. Exiting any BNU does not effect any other BNU. On OpenVMS Alpha, the "Cancel Other (New or Search) BNU(s)" option is only available from the original BNU. Any new BNU can be selected. New BNUs which have children are designated in the options menu by their titles suffixed with an "*", indicating a "wildcard". Such BNUs when selected for cancel will result in the cancellation of their children as indicated by the wildcard. On OpenVMS VAX, "Cancel Other (New or Search) BNU(s)" is not available and remains insensitive. Cancelling a parent is accomplished through the "File Exit" pulldown from the parent. This is why a second level new BNU is recommended for search operations, so a search can be cancelled by exiting its parent, leaving the original BNU intact. On either OpenVMS, exiting the original BNU cancels any and all new BNUs as well. Caveats & Disclaimers: --------------------- With some previous versions of BNU, search operations were leaving a diagnostic debug log in the users current directory named "s.log". These can safely be deleted. BNU V2.1 and higher no longer create this log file. On some versions of VMS with some versions of Netscape Navigator, some figures in some of the books do not display. While attempts are made to insure the integrity of concurrent operations with multiple BNUs active, clicking at the wrong times when new BNUs are starting and the BNU_PIDS_pid.tmp file is open for write can have adverse effects. Searching within book contents uses the "grep" command on DIGITAL UNIX, and the "SEARCH" command on OpenVMS. In both cases, these are done on binary files, which is not necessarily recommended. Standard out is disabled for their use, which allows them to work and return a valid status. Some search matches may be missed using this method when formatting or positioning information is interspersed within the ascii in the binary file. "Cancel Other (New or Search) BNU(s)" involves, on DIGITAL UNIX, issuing a "kill -9" command, and on VMS, a "stop/proc=pid" command. Although it has shown no problems to date, proper SIGNAL handlers should be used to insure a more orderly shutdown of BNUs. As per the limited support for PDF and PS files described above, if one views the ODL using Bookreader alone (which is not recommended) via the [.DECW$BOOK]LIBRARY.ODL file, the ODL shelf file for DIGITAL C++ which contains references to PDF or PS files will generate an error and fail to open. The workaround is to use BNU, the recommended method for viewing the ODL. Warnings and Errors in running the ODL Setup Procedure ------------------------------------------------------ The ODL setup procedure utilizes the POLYCENTER Software Installation utility, which accesses the POLYCENTER Product Database (PPD). This database keeps track of product versions that are installed on the host system. Depending on the state of the PPD, instances of running the ODL setup procedure in which warnings or errors are encountered have been observed. Generally, warnings which refer to version dependency problems can be overlooked. An example warning message generated by the ODL setup procedure is as follows: %PCSIUI-I-DONEASK, execution phase starting The following product will be installed: DEC AXPVMS ODL V2.1 The following product will be removed: DEC AXPVMS ODL V1.8 The following products will be reconfigured: DEC AXPVMS HYPERHELP V5.1-2 DEC AXPVMS NS_NAV_EXPORT V3.0-3 %PCSI-E-SFTCNFINS, installed product DEC AXPVMS BNU V1.8 does not satisfy -PCSI-E-SFTCNFVER, DEC AXPVMS ODL V2.1 version requirements -PCSI-E-SFTVERREQ, DEC AXPVMS ODL V2.1 version requirements for DEC AXPVMS BNU a re -PCSI-E-SFTMINREQMAX, minimum V2.1, required (none), maximum (none), below ( none) Terminating is strongly recommended. Do you want to terminate? [YES] In cases such as these, it is generally recommended to respond "no" and permit the installation to procede despite the warning. If dependency problems continue, the following POLYCENTER command should be issued prior to running the ODL setup procedure again: PRODUCT REMOVE ODL You will be prompted to take action to optionally remove the ODL products that are no longer referenced. Respond "yes" to the offending product(s). This will cause them to be uninstalled so they will be installed on the next running of the ODL setup procedure.