BASEstar_Open_Client________________________________ Inst. & Management Guide Order Number: AA-QSKGB-TE March 1997 This manual contains instructions for installing and setting up the BASEstar Open Client product. It also provides detailed information regarding BASEstar Open Client PC-specific features, such as the Graphic Configuration utility and BASEstar Open DDE connectivity. Revision/Update Information: This is a new document for the current release. Operating System and Version: BASEstar Open is available on a broad range of both hardware and software platforms. Refer to the BASEstar Open Client Software Product Description for precise information. Software Version: BASEstar Open Client Version 3.1 Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ First printing, February 1996 Revised, April 1996 Revised, March 1997 © Digital Equipment Corporation 1997. All Rights Reserved. Possession, use, or copying of the software described in this documentation is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor. Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: Alpha AXP, BASEstar, DEC, DECmessageQ, DECnet, DECnet-DOS, DECosap, DEComni, DIGITAL, DIGITAL UNIX, FMS, LN03, MicroVAX, NAS, OpenVMS, OpenVMS Alpha, PATHWORKS, PDAS, Rdb/VMS, ReGIS, ThinWire, TK, ULTRIX, VAX, VAXcluster, VAX COBOL, VAX FORTRAN, VAX Pascal, VAX RMS, VMS/ULTRIX Connection, VT, and the DIGITAL logo. The following are third-party trademarks: Excel is a registered trademark of Microsoft Corporation. IBM is a registered trademark of IBM Corp. INGRES is a trademark of Ingres Corp. LOTUS 1-2-3 is a registered trademark of Lotus Development Corp. MS, Microsoft, and MS-DOS are registered trademarks of Microsoft Corporation. Network File System and NFS are trademarks of Sun Microsystems, Inc. ORACLE is a trademark of Oracle Corp. PostScript is a registered trademark of Adobe Systems Incorporated. SINEC AP, SINEC H1, SICOMP, Simatic, SINEC, SINUMERIK and SIROTEC are registered trademarks of Siemens, AG. UNIX is a registered trademark licensed exclusively by X /Open Company Ltd. Windows, Windows NT and Windows 95 are trademarks of Microsoft Corporation. Wonderware InTouch is a registered trademark of Wonderware Corporation. X/Open is a registered trademark of the X/Open Company Limited This document was prepared using VAX DOCUMENT, Version 2.1. _________________________________________________________________ Contents Preface................................................... ix 1 BASEstar Open's Client-Server Architecture 1.1 BASEstar Open Servers and Clients................ 1-1 1.1.1 Roles of BASEstar Open Servers and Clients .... 1-2 1.1.2 Configuration Differences ..................... 1-3 1.1.3 Product Differences ........................... 1-3 PC-based Platforms 2 Installing BASEstar Open Client on Windows NT and Windows 95 Systems 2.1 Checking the Media Software Distribution Kit..... 2-1 2.2 Before You Begin................................. 2-2 2.2.1 Release Notes ................................. 2-2 2.2.2 Installation and Work Directories ............. 2-2 2.2.3 Backing Up Your System Disk ................... 2-2 2.2.4 Hardware Pre-requisites ....................... 2-3 2.2.5 Software Pre-requisites ....................... 2-3 2.2.6 Disk Space Requirements ....................... 2-3 2.2.7 Installation Procedure Requirements ........... 2-4 2.3 Installation Procedure........................... 2-4 2.3.1 Installing the BASEstar Open Client ........... 2-4 2.3.2 Deinstalling the BASEstar Open Client Kit (Windows NT only).............................. 2-5 2.4 Getting Help and Reporting Problems.............. 2-6 iii 3 Configuring BASEstar Open Client on Windows NT and Windows 95 Systems 3.1 BASEstar Open Environment Components............. 3-1 3.2 The BASEstar Open Manager Utility................ 3-1 3.2.1 Configuring BASEstar Open Nodes and Realms .... 3-2 3.2.1.1 Setting up the Default Realm................ 3-2 3.2.2 Customizing the BASEstar Open Manager Window .. 3-4 4 Installing BASEstar Open Client on an MS Windows System 4.1 Checking the Media Software Distribution Kit..... 4-1 4.2 Before You Begin................................. 4-1 4.2.1 Release Notes ................................. 4-2 4.2.2 Installation and Work Directories ............. 4-2 4.2.3 Backing Up Your System Disk ................... 4-2 4.2.4 Hardware Pre-requisites ....................... 4-2 4.2.5 Software Pre-requisites ....................... 4-3 4.2.6 Installation Procedure Requirements ........... 4-3 4.3 Installation Procedure........................... 4-3 4.4 Getting Help and Reporting Problems.............. 4-4 5 Configuring BASEstar Open Client on an MS Windows System 5.1 BASEstar Open Environment Components............. 5-1 5.1.1 Nodes ......................................... 5-1 5.1.2 Realms ........................................ 5-2 5.2 Managing the Communication Configuration File.... 5-2 5.2.1 Modifying the Default Communication Configuration File............................. 5-3 5.3 Setting Up the Default Realm..................... 5-4 5.4 Starting Up a Client Node........................ 5-4 5.5 Shutting Down a Client Node...................... 5-5 5.6 Log Information.................................. 5-5 DIGITAL UNIX Systems iv 6 Preparing to Install BASEstar Open Client on a DIGITAL UNIX System 6.1 Release Notes.................................... 6-1 6.2 License Registration............................. 6-1 6.3 Checking the Media Software Distribution Kit..... 6-3 6.4 BASEstar Open Client Kits........................ 6-3 6.5 Installation Procedure Requirements.............. 6-3 6.5.1 Checking Login Privileges ..................... 6-3 6.5.2 Hardware Pre-requisites ....................... 6-3 6.5.3 Software Pre-requisites ....................... 6-4 6.5.4 Determining Disk Space Requirements ........... 6-4 6.5.5 Increasing Disk Space Available for BASEstar Open Client Installation....................... 6-4 6.6 Backing Up Your System Disk...................... 6-5 6.7 Stopping the Installation........................ 6-5 6.8 Error Recovery................................... 6-5 7 Installing BASEstar Open Client on a DIGITAL UNIX System 7.1 Responding to Installation Procedure Prompts..... 7-1 7.1.1 Selecting Subsets ............................. 7-1 7.1.2 Monitoring Displays During the Subset Loading Process........................................ 7-2 8 Configuring and Managing BASEstar Open Client on a DIGITAL UNIX System 8.1 Getting Help and Reporting Problems.............. 8-1 8.2 Setting Up and Starting the BASEstar Open Client Environment...................................... 8-2 8.2.1 Configuring the BASEstar Open Client Environment.................................... 8-2 8.2.2 Starting Up BASEstar Open Client .............. 8-4 8.2.3 Unsetting BASEstar Open Client ................ 8-4 8.2.4 Shutting Down BASEstar Open Client ............ 8-4 8.3 Displaying Documentation from CD-ROM............. 8-5 v 9 Removing BASEstar Open Client From a DIGITAL UNIX System 10 Environment Management Command Reference (UNIX) 10.1 Executing Environment Commands................... 10-1 10.1.1 Users and Commands ............................ 10-1 10.1.1.1 Executing a Command......................... 10-2 10.1.2 Privileges Needed to Run Environment Management Procedures..................................... 10-2 cli_bstr......................................... 10-4 bstrcl_setup..................................... 10-6 bstrcl_unset..................................... 10-9 bstrcl_start..................................... 10-10 bstrcl_shut...................................... 10-12 HP-UX Systems 11 Preparing to Install BASEstar Open Client on a HP-UX System 11.1 Release Notes.................................... 11-1 11.2 Checking the Media Software Distribution Kit..... 11-2 11.3 Installation Procedure Requirements.............. 11-2 11.3.1 Checking Login Privileges ..................... 11-2 11.3.2 Hardware Pre-requisites ....................... 11-2 11.3.3 Software Pre-requisites ....................... 11-3 11.3.4 Determining Disk Space Requirements ........... 11-3 11.4 Backing Up Your System Disk...................... 11-3 11.5 Stopping the Installation........................ 11-4 11.6 Error Recovery................................... 11-4 12 Installing BASEstar Open Client on a HP-UX System 12.1 Installing CD-ROM Consolidated Distribution Media............................................ 12-1 vi 13 Configuring BASEstar Open Client on a HP-UX System 13.1 Getting Help and Reporting Problems.............. 13-1 13.2 Setting Up and Starting the BASEstar Open Client Environment...................................... 13-2 13.2.1 Configuring the BASEstar Open Client Environment.................................... 13-2 13.2.2 Starting Up BASEstar Open Client .............. 13-4 13.2.3 Unsetting BASEstar Open Client ................ 13-4 13.2.4 Shutting Down BASEstar Open Client ............ 13-4 13.3 Displaying Documentation from CD-ROM............. 13-5 14 Removing BASEstar Open Client From a HP-UX System PC-specific Utilities 15 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface.......................... 15-1 15.1.1 Activating the Graphic Configuration Utility .. 15-2 15.1.2 Navigating a BASEstar Open Configuration Tree........................................... 15-2 15.1.2.1 Configuration of the Tree Hierarchy......... 15-3 15.1.2.2 Contents of the Configuration Tree Elements.................................... 15-3 15.1.3 Managing Objects .............................. 15-5 15.1.3.1 Creating an Object.......................... 15-5 15.1.3.2 Deleting an Object.......................... 15-6 15.1.3.3 Modifying an Object......................... 15-7 15.1.3.4 Object Attribute Dialog Boxes............... 15-7 15.1.3.5 Attribute Selection Dialog Boxes (Browser).. 15-8 16 BASEstar Open DDE Connectivity 16.1 Using the DDE Bridge............................. 16-2 16.2 Limitations...................................... 16-13 16.2.1 Automatic Configuration ....................... 16-13 16.2.2 Supported Datatypes ........................... 16-14 16.2.3 Domains ....................................... 16-14 vii A BASEstar Open Client Environment Variables (PC-based platforms) A.1 Environment Variable List........................ A-1 A.2 Setting Installation-Dependent Environment Variables........................................ A-3 B Managing the BSTRCOM.CFG File (MS Windows) B.1 Extended File Format............................. B-1 B.1.1 The [COM SERVERS] Section ..................... B-1 B.1.2 The [LNS SERVERS] Section ..................... B-2 B.1.3 Determining the Port Number for the Name Service Servers................................ B-3 B.2 Sample Communication Configuration File.......... B-4 B.3 Use of the BSTRCOM.CFG File at Run-time.......... B-5 C Directories and Files Installed on PC-based Systems D Updating the DEC PathWorks Configuration (MS Windows) E Directories and Files Installed on DIGITAL UNIX and HP-UX Systems E.1 Files and Directories Installed on DIGITAL UNIX Systems.......................................... E-1 E.2 Files and Directories Installed on HP-UX Systems.......................................... E-10 Index Examples 5-1 Default BSTRCOM.CFG File ...................... 5-3 A-1 Sample BSTRUSER.BAT File ...................... A-4 D-1 Upgraded PROTOCOL.INI DEC PathWorks File ...... D-1 viii Figures 3-1 BASEstar Open Manager Window .................. 3-2 3-2 Client Setup Dialog Box ....................... 3-3 3-3 COM Server Connectivity Check Dialog Box ...... 3-4 16-1 DDE Bridge Main Window ........................ 16-8 16-2 Configuring the DDE Bridge as a DDE Client .... 16-10 16-3 Exporting Data_Point Names to the Clipboard ... 16-13 Tables 1 Conventions Used in BASEstar Open ............. xii 2-1 Disk Space Requirements - Windows NT/Windows 95............................................. 2-3 10-1 User Access to Environment Management Commands and Users...................................... 10-2 10-2 Environment Management Privileges ............. 10-2 15-1 Parent-Child Relationship Between Elements and Objects........................................ 15-4 15-2 BASEstar Open Objects and Attributes .......... 15-9 A-1 BASEstar Open Environment Variables ........... A-1 C-1 BASEstar Open Client Directories and Files on PC-based Systems............................... C-1 C-2 Executable Images for PC Server .............. C-3 E-1 Files and Directories Installed on DIGITAL UNIX Systems........................................ E-1 E-2 Files and Directories Installed on a HP-UX System......................................... E-10 ix _________________________________________________________________ Preface This guide describes how to install the BASEstar Open Client software, and how to manage the BASEstar Open environment and make it available to end users. Multi-platform Applicability The information in this manual is only applicable to the implementation of BASEstar Open Client on supported platforms. Intended Audience This manual is addressed to system managers responsible for installing and setting up BASEstar Open Client software. Prerequisites Any user responsible for installing and managing the BASEstar Open Client environment must know how to manage the native operating system. A basic knowledge of BASEstar Open features is also recommended. Structure of this Document This document consists of the following chapters and appendices: o Chapter 1 provides a product overview and highlights the requirements for installing the BASEstar Open Client kit on the various supported platforms. o Chapter 2 explains how to install BASEstar Open Client on PC-based platforms. ix o Chapter 3 provides an overview of the BASEstar Open Manager and explains how to configure and manage the BASEstar Open Client environment on your Windows NT or Windows 95 personal computer. o Chapter 4 describes how to install BASEstar Open Client on an MS Windows system. o Chapter 5 explains how to configure and manage the BASEstar Open Client environment on your MS Windows personal computer. o Chapter 6 describes the procedures that you must complete before installing BASEstar Open Client on DIGITAL UNIX systems. o Chapter 7 describes the BASEstar Open Client installation procedure for DIGITAL UNIX systems. o Chapter 8 describes how to configure and start up BASEstar Open Client on a DIGITAL UNIX system. o Chapter 9 describes how to remove BASEstar Open Client from a DIGITAL UNIX system. o Chapter 11 describes the procedures that you must complete before installing BASEstar Open Client on a HP-UX system. o Chapter 12 describes the BASEstar Open Client installation procedure for HP-UX systems. o Chapter 13 describes how to configure and start up BASEstar Open Client on a HP-UX system. o Chapter 14 describes how to remove BASEstar Open Client from a HP-UX system. o Chapter 10 describes the general requirements for executing environment management commands on UNIX systems. It also contains a reference section that provides full details of each environment management command. o Chapter 15 describes the Graphic Configuration utility, available on Windows NT, Windows 95 and MS Windows systems. o Chapter 16 provides a detailed explanation of the concept of DDE connectivity. x o Appendix A provides information about the BASEstar Open Client environment variables on Windows NT, Windows 95 and MS Windows systems. o Appendix B provides additional information about the BSTRCOM.CFG file, which contains the BASEstar Open Client communication configuration on Windows NT, Windows NT and MS Windows systems. o Appendix C lists the files and directories that reside on Windows NT, Windows NT and MS Windows systems after you install BASEstar Open Client. o Appendix D describes how to update the DEC PathWorks configuration to improve performance on MS Windows systems. o Appendix E lists the files and directories that reside on DIGITAL UNIX and HP-UX systems after you install BASEstar Open Client. BASEstar Open Documentation Set This manual describes a software component or aspects of the BASEstar Open family of products. The complete set of documents relating to the BASEstar Open family is as follows: o BASEstar Open: - BASEstar Open Introduction - BASEstar Open Reference Guide - BASEstar Open Command Language Interface - BASEstar Open Application Programming Interface - BASEstar Open Messages - Platform-specific installation and management guides - BASEstar Open Guide to DCM-Modeled Device Connectivity (for supported platforms) o BASEstar CIMfast (for supported platforms): - BASEstar CIMfast User's Guide - BASEstar CIMfast Programmer's Reference Guide - BASEstar CIMfast Guide to DECmessageQ Support xi - BASEstar CIMfast Guide to SQL Support o DEComni API: - DEComni API and MMS User Guide - DEComni API Guide to Using Omni Directory Services (for supported platforms) - DEComni API Guide to Using OmniView (for supported platforms) - DEComni API Omni Definition Facility User Guide (for supported platforms) o Device Access Software documentation - Specific manuals for each supported device Conventions Table 1 lists the conventions used in the BASEstar Open documentation set. Table_1_Conventions_Used_in_BASEstar_Open________________________ % The default user prompt is your system name followed by a right angle bracket (>). In the BASEstar Open docset, a percent sign (%) is used to represent this prompt. / Indicates that you must hold down the Ctrl key while you press another key. In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) . A vertical ellipsis indicates the omission of . items from a code example or sample command; . the items are omitted because they are not important to the topic being discussed. (continued on next page) xii Table_1_(Cont.)_Conventions_Used_in_BASEstar_Open________________ . . . A horizontal ellipsis in format descriptions or in examples indicates one of the following possibilities: o Additional optional arguments in a statement have been omitted. o The preceding item or items can be repeated one or more times. o Additional parameters, values, or other information can be entered. [] In format descriptions, brackets indicate optional elements; you can select none, one, several, or all of the choices. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification, or in the syntax of a substring specification in an assignment statement.) ( ) In format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. boldface text Boldface text represents one of the following cases: o user input o the introduction of a new term o the status values true or false italic type Indicates titles of manuals, variables, arguments, data structures, fields, callable functions, operands, and utilities. Italic text also represents information that can vary in system messages (for example, Internal error number), command lines (for example, /PRODUCER=name), and command operands in text. (continued on next page) xiii Table_1_(Cont.)_Conventions_Used_in_BASEstar_Open________________ code type Indicates information that is part of the code for a program or application. numbers Unless otherwise noted, all numbers in the text are assumed to be decimal. Nondecimal radixes- binary, octal, or hexadecimal-are explicitly indicated. UPPERCASE TEXT Uppercase text indicates a command, the name of a file, the name of a file protection code, the abbreviation for a system privilege, the name of a field, or the value of an attribute where attributes are chosen from a list. "point_a + Literal string. Using quotation marks is point_b" optional unless there is a space, slash (/), or parenthesis in the string. BASEstar Open Valid characters for the names of BASEstar Open names objects are the alphanumeric characters (A-Z) and (0-9), the underscore (_), the dollar sign ($), and the following multinational __________________characters:_ÅÀÁÂÃÄÇÈÉÊËÌÍÎÏÒÓÔÕÖÙÚÛÜÆÑ@Øß._____ xiv 1 _________________________________________________________________ BASEstar Open's Client-Server Architecture 1.1 BASEstar Open Servers and Clients BASEstar Open provides a range of services that are typically required by industrial automation applications and not normally available from the underlying operating systems. These services include the possibility of responding to or generating asynchronous plant occurrences (Events), connecting to industrial automation devices, and distributing device data and information plantwide. In BASEstar Open, these services are provided by specific processes (BASEstar Open servers) such as the following: o Event Services server o Data & Device Services server o Application Management Services server o Packet Services server There are several ways in which user applications can access these services: o C language programs, which use the BASEstar Open Application Program Interface (API) o BASEstar Open's Command Line Interface (CLI) o BASEstar Open's high level language, CIMFAST From a purely BASEstar Open architectural point of view, these user applications can be considered clients of the requested BASEstar Open service provider (server). This client/server relationship exists regardless of whether the application resides on the same physical node as the server or on a different BASEstar Open network node. In fact, from a functionality point of view, the location of the requested BASEstar Open server has no impact on the application. 1-1 BASEstar Open's Client-Server Architecture 1.1 BASEstar Open Servers and Clients However, the application may be impacted in other ways depending on whether its node is a BASEstar Open Server node or a BASEstar Open Client node, for example in the level of system management support available. This consideration is fundamental to an analysis of the different roles of BASEstar Open Server nodes and Client nodes, as outlined in Section 1.1.1. 1.1.1 Roles of BASEstar Open Servers and Clients Server nodes represent the robust computing engine for industrial automation applications where plant data is collected, managed and made available throughout the network. On these nodes, which may be dual host to maximise reliability, you can activate and manage mission- critical applications under the control of BASEstar Open's Application Management Services (AMS). (AMS provides system management services for monitoring the status of applications and managing their orderly startup and shutdown). These server nodes also manage the connections to automation devices such as PLCs or Numeric Controllers. This environment may be part of the controlled computer room environment with all the procedures necessary for starting up applications and their recovery in the event of a failure. Client nodes, on the other hand, provide a less sophisticated, easier to use, "plug & play" environment for any application anywhere in the network which needs to access the services provided by BASEstar Open. For example, it is common practice to use PC-based client nodes as visualization stations distributed throughout the enterprise for providing up-to-date graphical or reporting information regarding the state of the plant, production status, etc. This type of node is often the typical desktop environment, with its suite of personal productivity tools and mail system, which, with the incorporation of the BASEstar Open Client software, becomes a viewing/reporting station providing real-time plant information. From a system management point of view, client nodes also provide several advantages with respect to a server nodes. It is easier to set them up and "plug them in" to a BASEstar Open network. 1-2 BASEstar Open's Client-Server Architecture 1.1 BASEstar Open Servers and Clients 1.1.2 Configuration Differences BASEstar Open configuration is the process by which BASEstar Open objects are described and defined. These objects like Data_Points, Devices, BASEstar Open services etc., once defined become part of one or more Realms and are physically located on one or more BASEstar Open Server Nodes. BASEstar Open Client nodes instead do not physically contain any BASEstar Open objects so are not part of a Realm but do provide access to Realms in support of BASEstar Open Client-based applications. Even though the BASEstar Open Client nodes are not impacted (modified), by the BASEstar Open configuration process the PC-based BASEstar Open Client can have an important role in this process. In fact, the PC-based client is often used as a configuration station on those PCs where the BASEstar Open Graphic Configuration utility is installed. 1.1.3 Product Differences All BASEstar Open services, including Event management, data Management and device management, are part of the BASEstar Open Server product. This product comes in two flavours: Development and Runtime. With a development license, you can link compiled C language programs which make calls to the BASEstar Open API against the BASEstar Open Runtime Library. You can then deploy these applications on server or client nodes. The Runtime License does not allow you to develop programs, but permits all developed applications to be deployed on the BASEstar Open Runtime Server product which includes all the BASEstar Open services. The BASEstar Open Client product does not offer the BASEstar Open services directly, but provides a means for BASEstar Open applications to obtain transparent access to these services, which are located on servers anywhere in the network. BASEstar Open has its own communication system for allowing client applications, regardless of where they are located, to access BASEstar Open services. 1-3 BASEstar Open's Client-Server Architecture 1.1 BASEstar Open Servers and Clients As a general indication, it is possible to summarise the differences between the BASEstar Open Server and the BASEstar Open Client product as follows: o BASEstar Open Server only - Device connection - Repository for BASEstar Open objects (Data_Points, Events etc.) - Application management via Application Management Services (AMS) - Trace troubleshooting facility - Execution of invoked BASEstar Open services o Available on both BASEstar Open Server and BASEstar Open Client - Ability to access BASEstar Open services Note that on previous versions of the BASEstar Open product (Version 2.0 and 1.0), the differences between server and client were not as distinct as is now the case. In fact, a subset of Application Management Services and the Trace feature were also part of BASEstar Open Client versions on OpenVMS and DIGITAL UNIX. For a detailed list of differences, refer to the BASEstar Open Client Release Notes. PC-based clients and servers support some features which are specific to the PC environment. These include: o A graphic configuration tool for configuring BASEstar Open objects o DDE bridge for communicating with DDE-compliant PC applications. ________________________ Note ________________________ The discussion in this chapter is of a generic nature; its aim is to clarify the conceptual differences between BASEstar Open Server nodes and BASEstar Open Client nodes. The availability of a given feature on a specific BASEstar Open platform depends on the released version of the product. For information 1-4 BASEstar Open's Client-Server Architecture 1.1 BASEstar Open Servers and Clients regarding specific functionalities, consult the detailed product documentation (SPD, release notes). ______________________________________________________ 1-5 PC-based Platforms _________________________________________________________________ 2 _________________________________________________________________ Installing BASEstar Open Client on Windows NT and Windows 95 Systems This chapter describes the pre-installation and installation procedures for BASEstar Open Client on: o Windows NT o Windows 95. 2.1 Checking the Media Software Distribution Kit Your DIGITAL Bill of Materials (BOM) and DIGITAL Indented Bills Report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or if you find that parts of it are missing, contact your DIGITAL representative. The kit contains the following: o Release Notes The release notes provide information that is important for you to know before installing BASEstar Open Client on your system and which may not be included in this guide. o Media Your kit contains a series of 1.44 Mbyte 3 1/2" disks. o Documentation Your kit includes this manual. 2-1 Installing BASEstar Open Client on Windows NT and Windows 95 Systems 2.2 Before You Begin 2.2 Before You Begin Before you start the installation procedure, read the release notes, gather the information that the procedure requires, and confirm that the pre-requisite hardware and software has already been installed. Refer to Table C-1 for a list of files included in the BASEstar Open Client kits for PC-based platforms. 2.2.1 Release Notes BASEstar Open Client provides online release notes that may contain important information about changes made to the application after the documentation was completed. If release notes are provided, you can access them by clicking on the Readme icon in the BASEstar Open Client Program Group. They are also located in the RELNOTES.TXT file in the root directory of your distribution diskette. DIGITAL strongly recommends that you read the release notes before you proceed with the installation procedure. 2.2.2 Installation and Work Directories Before you proceed with the installation, it is recommended that you specify the location of the following BASEstar Open Client directories: o Installation directory This directory is the tree under which the installation procedure copies all the files provided with the setup disk. BASEstar Open Client does not modify any of these files. o Work directory (optional) This directory is the tree under which BASEstar Open Client stores node-specific configuration and working data at run-time. 2.2.3 Backing Up Your System Disk DIGITAL recommends that you back up your system disk before installing any software. For details about how to perform a system disk backup, consult your PC-specific documentation. 2-2 Installing BASEstar Open Client on Windows NT and Windows 95 Systems 2.2 Before You Begin 2.2.4 Hardware Pre-requisites You can install BASEstar Open Client on the following hardware: o A 386-, a 486-, or a Pentium-class PC o A DIGITAL Alpha PC. The PC must also be capable of running Windows NT Version 3.51 or 4.0, or Windows 95. 2.2.5 Software Pre-requisites You cannot install BASEstar Open Client until you have installed either: o Windows NT Version 3.51 or 4.0 o Windows 95. The PC kit includes TCP/IP services. The installation procedures for Windows NT Windows 95 give you the option of installing TCP/IP services as well. You cannot use BASEstar Open server until you have installed TCP/IP services. 2.2.6 Disk Space Requirements Table 2-1 lists the disk space requirements for BASEstar Open Client on Windows NT and Windows 95 systems. Check the values in the table against the amount of free space available on the system where you intend to install BASEstar Open Client. Table_2-1_Disk_Space_Requirements_-_Windows_NT/Windows_95__ Intel____________Alpha_____________________________________ _______________________Installation________________________ 9.5 Mb 11.5 Mb ___________________________________________________________ _______________________Permanent_Use_______________________ 8.5_Mb___________10.5_Mb___________________________________ 2-3 Installing BASEstar Open Client on Windows NT and Windows 95 Systems 2.2 Before You Begin 2.2.7 Installation Procedure Requirements It takes between 30 seconds and 5 minutes to install BASEstar Open Client on Windows NT and Windows 95 systems, depending on the CPU that you are using. 2.3 Installation Procedure This section describes the procedure for installing: o BASEstar Open Client for Windows NT o BASEstar Open Client for Windows 95. The procedure is valid regardless of whether you are installing BASEstar Open Client for the first time, or reinstalling it on a system where a version already exists. It is possible to install or reinstall the BASEstar Open Client kit for either platform without damaging site- specific configuration information. ________________________ Note ________________________ In order to install BASEstar Open Client for Windows NT or Windows 95, you must be a member of the Administrators group. ______________________________________________________ 2.3.1 Installing the BASEstar Open Client Before you attempt to install the PC server kit on the required server, make sure that the BASEstar Open Client kit has already been installed. To start the installation procedure, run the SETUP.EXE file supplied with the BASEstar Open Client kit. Note that at the end of the installation, the BASEstar Open Client Program Group includes the Readme icon, containing the release notes for BASEstar Open Client Version 3.1. You can also install BASEstar Open Client in silent mode. This implies that instead of installing BASEstar Open Client interactively, the installation procedure reads the default parameters automatically from the the SETUP.ISS response file, specified by the -s switch. 2-4 Installing BASEstar Open Client on Windows NT and Windows 95 Systems 2.3 Installation Procedure To perform the installation in silent mode, execute the SETUP command as follows: # setup -s /F2pathname\logfile where pathname\logfile represents the full pathname of a writeable location for the installation logfile. As of BASEstar Open Client Version 3.1, the installation procedure prompts you to supply a software key. You must enter this code in order to make BASEstar Open Client Version 3.1 available on your system. Failure to do so implies restricted use of the product. If you do not enter the software key at installation time, or if you supply an incorrect software key, you can use the BASEstar Open Products Info utility to specify the correct software key. For information about how to obtain the software key, refer to the BASEstar Open Client Cover Letter. 2.3.2 Deinstalling the BASEstar Open Client Kit (Windows NT only) If you have installed BASEstar Open Client Version 3.0 in your environment, and you want to remove it before installing the BASEstar Open Client for Windows NT Version 3.1 kit, you must perform the following operations: o Delete the BASEstar Open Client Version 3.0 registry entries o Delete the BASEstar Open Client Version 3.0 Program Group. To delete the registry entries, follow these steps: 1. Run the registry editor (regedt32.exe). 2. Select the HKEY_LOCAL_MACHINE page. 3. Open the "SOFTWARE\DigitalEquipmentCorporation" key. 4. Chhose the Delete option from the Edit menu and delete: o "BASEstar Open Client" o "DEComni" 5. Select the HKEY_CURRENT_USER page. 6. Open the "SOFTWARE\DigitalEquipmentCorporation" key. 2-5 Installing BASEstar Open Client on Windows NT and Windows 95 Systems 2.3 Installation Procedure 7. Choose the Delete option from the Edit menu and delete: o "BASEstar Open Client" To delete the BASEstar Open Client Program Group, follow these steps: 1. From the Program Manager, select BASEstar Open Client. 2. Pull down the File menu and select the Delete option. You may also wish to delete the BASEstar Open Client Version 3.0 files and directories from your disk. To do so, follow these additional steps: 1. From the File Manager, select the BASEstar Open root directory. 2. Pull down the File menu and select the Delete option to delete all files starting from the BASEstar Open root. 2.4 Getting Help and Reporting Problems If an error occurs while you are using BASEstar Open Client, and you believe the error is the result of a problem associated with the product, take one of the following actions: o If you have a basic or DECsupport Software Agreement, call your Customer Support Center (CSC). The CSC provides telephone support for high-level advisory and remedial assistance. o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). o If you purchased BASEstar Open Client within the last 90 days and you think the problem is caused by a software error, you can submit an SPR. If you submit an SPR, please take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the description and version number of BASEstar Open Client that you were using. Demonstrate the problem with specific examples. 2. Reduce the problem to as small a size as possible. 2-6 Installing BASEstar Open Client on Windows NT and Windows 95 Systems 2.4 Getting Help and Reporting Problems 3. Remember to include listings of any command files, include files, relevant data files, and so forth. 4. Provide a listing of the program. 5. If the program is longer than 50 lines, submit a copy of it on machine-readable media (floppy diskette or magnetic tape). If necessary, also submit a copy of the program library used to build the application. 6. Report only one problem per SPR. This will facilitate a faster response. 7. Mail the SPR package to DIGITAL. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Concise, complete information helps DIGITAL give accurate and timely service to software problems. If you find an error in the BASEstar Open Client documentation, send an electronic mail message to manufacturing@digital.com. 2-7 3 _________________________________________________________________ Configuring BASEstar Open Client on Windows NT and Windows 95 Systems This chapter describes how to manage the BASEstar Open Client environment on Windows NT and Windows 95 personal computers, and how to configure your BASEstar Open Client Node and Realm. 3.1 BASEstar Open Environment Components It is possible to access more than one Realm from a BASEstar Open Client Node on a PC-based platform. This means that different user-written applications started on the Node can perform concurrent operations on objects belonging to different Realms. Each user-written application acts as an application component of the Realm it uses. In order to do this, it accesses the Realm objects made available by the BASEstar Open servers running on the Realm server Node. A Realm does not contain active environment components. To make a Realm active, you must set it up and specify its name in a configuration file together with the communications parameters required to establish connections with the distributed Realm server Nodes. For a description of how to set up a Realm, refer to Section 3.2.1.1. 3.2 The BASEstar Open Manager Utility This section explains how to use the BASEstar Open Manager to manage your environment and configure your BASEstar Open Client Node and Realm. To activate the BASEstar Open Manager utility, double click on the appropriate icon in the BASEstar Open Client Program Group. BASEstar Open Client displays the main BASEstar Open Manager window illustrated in Figure 3-1. 3-1 Configuring BASEstar Open Client on Windows NT and Windows 95 Systems 3.2 The BASEstar Open Manager Utility Figure 3-1 BASEstar Open Manager Window +------------------------------------------------------------------+ | File Customize Tools Options Help | +------------------------------------------------------------------+ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +------------------------------------------------------------------+ 3.2.1 Configuring BASEstar Open Nodes and Realms It is necessary to perform a series of setup activities involving the Nodes and Realms on a distributed system to ensure that all Nodes have transparent and global access to BASEstar Open objects, regardless of their location in the environment. The implementation of BASEstar Open Client on Windows NT and Windows 95 only makes provision for a single (default) Realm. However, you can specify up to eight LNS server Nodes to which your client can address service requests. 3.2.1.1 Setting up the Default Realm To set up your default Realm, pull down the Customize menu in the BASEstar Open Manager window and choose the Client setup... option. BASEstar Open Client displays the Client Setup dialog box in Figure 3-2. 3-2 Configuring BASEstar Open Client on Windows NT and Windows 95 Systems 3.2 The BASEstar Open Manager Utility Figure 3-2 Client Setup Dialog Box +---------------------------------------------------+ | Client Setup | +---------------------------------------------------+ | | | +----------+ | | Default REALM Name | | | | +----------+ | | | | | | LNS Servers +-----------------+ | | | | | | | | | | | | | | | | | | | | | | +-----------------+ | | | | +----+ +------+ | | | OK | |Cancel| | | +----+ +------+ | +---------------------------------------------------+ Click in the Default REALM Name box and type a name for the default Realm. Then click in the LNS Server box and type the names of up to eight LNS servers to which you want to allow your client to address service requests. In order for an LNS server to fulfill a service request for your client: o BASEstar Open must be running on the LNS server Node o Your default Realm must be running on the LNS server Node. To check that these conditions are satisfied, pull down the Tools menu and select the Connectivity Check... option. BASEstar Open displays a window similar to the one in Figure 3-3, notifying you of the COM server and LNS server selections. 3-3 Configuring BASEstar Open Client on Windows NT and Windows 95 Systems 3.2 The BASEstar Open Manager Utility Figure 3-3 COM Server Connectivity Check Dialog Box +---------------------------------------------------+ | COM server connectivity check | +---------------------------------------------------+ | | | +----------------------+ | | COM server Host |naxos3.mln.dec.com | | | +----------------------+ | | | | LNS server Host +----------------------+ | | |naxos3.mln.dec.com | | | +----------------------+ | | | | +-----------------+ | | | Close | | | +-----------------+ | +---------------------------------------------------+ To generate a file containing all setup data stored in the registry database, pull down the Customize menu and select the Dump Setup to File... option. By default, BASEstar Open Client calls the file BSTREGD.TXT and stores it in the \bin directory of your installation root; however, you can choose a different filename and directory location if you wish. 3.2.2 Customizing the BASEstar Open Manager Window The BASEstar Open Manager provides several menu options for personalizing the appearance of the BASEstar Open Manager window. You can access these customization commands via the Options menu: o Select Font... to alter the font family/size of the text that appears in the console window. o Select Background Color... to choose a different background color for the console window. o The Save Settings on Exit option is an ON/OFF item. Select this option to have BASEstar Open Client automatically save all parameter settings (text font /size, background color, screen position) in the registry database when you exit from the utility. 3-4 Configuring BASEstar Open Client on Windows NT and Windows 95 Systems 3.2 The BASEstar Open Manager Utility The Options menu also includes commands for manipulating the transcript file that contains the console messages: o The Transcript Control Messages option is an ON/OFF item. Select this option to generate a file into which BASEstar Open Client copies the messages displayed in the console window during startup/shutdown operations. By default, BASEstar Open Client calls the file BSTRCONS.TXT and stores it in the \bin directory of your installation root. o Select Save Settings Now to save all current parameter settings in the registry database. o Select Change Transcript File... to change the name /location of the transcript file in which the console messages are stored. BASEstar Open Client displays a dialog box and prompts you to type a new name/location. o Select Console Verbosity... to reduce/increase the frequency with which the BASEstar Open Manager displays messages in the console window. 3-5 4 _________________________________________________________________ Installing BASEstar Open Client on an MS Windows System This chapter describes the pre-installation and installation procedures for BASEstar Open Client on an MS Windows system. 4.1 Checking the Media Software Distribution Kit Your DIGITAL Bill of Materials (BOM) and DIGITAL Indented Bills Report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or if you find that parts of it are missing, contact your DIGITAL representative. The kit contains the following: o Release Notes The release notes provide information that is important for you to know before installing BASEstar Open Client for MS Windows on your MS Windows system and which may not be included in this guide. o Media Your kit contains a series of 1.44 Mbyte 3 1/2" disks. o Documentation Your kit includes this manual. 4.2 Before You Begin Before you start the installation procedure, read the release notes, gather the information that the procedure requires, and confirm that the pre-requisite hardware and software has already been installed. Refer to Appendix C for a list of files included in the BASEstar Open Client for MS Windows kit. 4-1 Installing BASEstar Open Client on an MS Windows System 4.2 Before You Begin 4.2.1 Release Notes BASEstar Open Client for MS Windows provides online release notes when important information must be conveyed after the documentation is printed. If release notes are provided, you can access them by clicking on the Readme icon in the BASEstar Open Client Program Group. They are also located in the RELNOTES.TXT file in the root directory of the distribution diskette. DIGITAL strongly recommends that you read the release notes before you proceed with the installation procedure. 4.2.2 Installation and Work Directories Before you proceed with the installation, it is recommended that you specify the location of the following BASEstar Open Client directories: o Installation directory This directory is the tree to which the installation procedure copies all the files provided with the setup disk. BASEstar Open Client never modifies any of these files. o Work directory This directory is the tree in which BASEstar Open Client stores node-specific configuration and working data at run-time. 4.2.3 Backing Up Your System Disk DIGITAL recommends that you back up your system disk before installing any software. For details of how to perform a system disk backup, consult your MS-DOS documentation. 4.2.4 Hardware Pre-requisites You can install BASEstar Open Client for MS Windows on a 386-, 486, or Pentium-class PC with 6 Mbytes of available disk space, capable of running MS Windows Version 3.1 or 3.11. 4-2 Installing BASEstar Open Client on an MS Windows System 4.2 Before You Begin 4.2.5 Software Pre-requisites You cannot install BASEstar Open Client for MS Windows until you have installed MS Windows Version 3.1 or 3.11. ________________________ Note ________________________ Although the Software Development Kit is not required for installation purposes, the fact that BASEstar Open Client is an API-based product implies that the native development tools are needed for application development. ______________________________________________________ You must also take the following constraints into consideration: o Libraries, executables, and Dynamic Link Libraries (DLLs) furnished with this kit must run in Windows 386 Enhanced Mode only. o The Watchdog and user-written applications need to access the following libraries at run-time: - MS Windows TOOLHELP.DLL library - WINSOCK.DLL 4.2.6 Installation Procedure Requirements It takes between 30 seconds and 5 minutes to install BASEstar Open Client on a MS Windows system, depending on the CPU that you are using. 4.3 Installation Procedure Use the procedure described in this section to install BASEstar Open Client for MS Windows for the first time, or to reinstall it on a system where a copy already exists. You can install or reinstall the BASEstar Open Client for MS Windows kit safely without damaging site- specific configuration information. After completing the installation, follow the instructions in Chapter 5. To start the installation procedure, run the SETUP.EXE file supplied with the BASEstar Open Client kit. Note that at the end of the installation, the BASEstar Open Client Program Group includes the following icons: 4-3 Installing BASEstar Open Client on an MS Windows System 4.3 Installation Procedure o The Readme icon, containing the release notes for MS Windows o The BSTRCOM Customization and the BSTRUSERS Customization icons. You will need to access these icons in order to edit the BSTRCOM.CFG communication configuration file (see Section 5.2) and the BSTRUSER.BAT installation-dependent environment variables file (see Section 5.3) respectively. 4.4 Getting Help and Reporting Problems If an error occurs while you are using BASEstar Open Client, and you believe the error is the result of a problem associated with the product, take one of the following actions: o If you have a basic or DECsupport Software Agreement, call your Customer Support Center (CSC). The CSC provides telephone support for high-level advisory and remedial assistance. o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). o If you purchased BASEstar Open Client within the last 90 days and you think the problem is caused by a software error, you can submit an SPR. If you submit an SPR, please take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the description and version number of BASEstar Open Client that you were using. Demonstrate the problem with specific examples. 2. Reduce the problem to as small a size as possible. 3. Remember to include listings of any command files, include files, relevant data files, and so forth. 4. Provide a listing of the program. 5. If the program is longer than 50 lines, submit a copy of it on machine-readable media (floppy diskette or magnetic tape). If necessary, also submit a copy of the program library used to build the application. 4-4 Installing BASEstar Open Client on an MS Windows System 4.4 Getting Help and Reporting Problems 6. Report only one problem per SPR. This will facilitate a faster response. 7. Mail the SPR package to DIGITAL. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Concise, complete information helps DIGITAL give accurate and timely service to software problems. If you find an error in the BASEstar Open Client documentation, send an electronic mail message to manufacturing@digital.com. 4-5 5 _________________________________________________________________ Configuring BASEstar Open Client on an MS Windows System This chapter describes how to configure and manage the BASEstar Open Client environment on your MS Windows personal computer. 5.1 BASEstar Open Environment Components On an MS Windows PC, the BASEstar Open environment consists of a Node with access to one or more Realms. These components are described in the sections that follow. 5.1.1 Nodes A BASEstar Open Client Node is an MS Windows personal computer on which BASEstar Open Client is installed. To make a BASEstar Open Client Node available in the BASEstar Open environment, you must start up the Watchdog component. The Watchdog is a background task that you must start before you can run a BASEstar Open Client for MS Windows application. You only need to start one Watchdog per PC; the Watchdog can manage connections to numerous Realms and PC Communication Servers active on various server Nodes. The Watchdog checks continuously for abnormal termination of BASEstar Open for MS Windows applications. In the event of abnormal termination, it performs an orderly closure of the connection with the Realm PC Communication Server. The following run-time limitations apply to the Watchdog process: o Applications can handle a maximum of eight Realms concurrently o You can activate a maximum of sixteen application processes for each Realm. 5-1 Configuring BASEstar Open Client on an MS Windows System 5.1 BASEstar Open Environment Components 5.1.2 Realms It is possible to access more than one Realm from a BASEstar Open Client Node on MS Windows. This means that different user-written applications started on the Node can perform concurrent operations on the objects of different Realms. Each user-written application acts as an application component of the Realm it uses. In order to do this, it accesses the Realm objects made available by the BASEstar Open servers running on the Realm server Node. A Realm does not contain active environment components. To make a Realm active, you must set it up and specify its name in a configuration file together with the communications parameters required to establish connections with the distributed Realm server Nodes. For a description of how to set up a Realm, refer to Section 5.3. 5.2 Managing the Communication Configuration File The communication configuration file (BSTRCOM.CFG) contains information about the Realms defined by BASEstar Open Client for MS Windows applications, enabling BASEstar Open to: o Establish TCP connections with the PC Communication Servers running on server Nodes of a Realm. These connections allow MS Windows applications to perform operations on the objects belonging to the Realm, regardless of how the Realm is distributed across server Nodes. o Establish UDP connections with the BASEstar Open active Name Service server on a BASEstar Open Node. These connections allow the Watchdog to make automatic requests to the PC Communication Servers currently active for any Realm. The BSTRCOM.CFG file therefore consists of two sections containing information about Name Service servers or/and PC Communication servers. You must edit the file in order to specify the name(s) of the server(s) to be made accessible to your client. 5-2 Configuring BASEstar Open Client on an MS Windows System 5.2 Managing the Communication Configuration File BASEstar Open Client assumes that the pathname of the BSTRCOM.CFG file is as follows: %BSTR_WORK_ROOT%\BSTRCOM.CFG If BASEstar Open Client is unable to find a definition for the BSTR_WORK_ROOT environment variable, it uses the following pathname: C:\BSTR030\WORK\BSTRCOM.CFG Refer to Appendix B for more information about the BSTRFCOM.CFG file. Having established the Realm name, the Watchdog retrieves the address of the Realm PC Communication Server(s) from the active Name Service server. It then attempts to connect the PC Communication Servers with the lowest workload. 5.2.1 Modifying the Default Communication Configuration File The default BSTRCOM.CFG file directs the Watchdog to select a PC Communication Server dynamically, choosing it at run- time from among those available. To edit the default BSTRCOM.CFG file, click on the BSTRCOM Customization icon in the BASEstar Open Program Group. Example 5-1 shows the contents of the default BSTRCOM.CFG communication configuration file provided by BASEstar Open Client. Example 5-1 Default BSTRCOM.CFG File # # Default BSTRCOM.CFG file # # # Name Service Servers Section # [LNS SERVERS] BSTR host1 6101 BSTR host2 6000 There is one entry for each of Name Service server active on the server Node(s) in your BASEstar Open distributed environment. The file therefore contains a maximum of two entries: one each for the primary and secondary Name 5-3 Configuring BASEstar Open Client on an MS Windows System 5.2 Managing the Communication Configuration File Service server copies. At run-time, the Watchdog handles these entries in the order in which they are listed in the BSTRCOM.CFG file. Update the file as follows: o Replace host1 with the IP host name of a BASEstar Open Server Node on which the primary instance of the Name Server is active. o Replace host2 with the IP host name of a BASEstar Open Server Node on which the secondary instance of the Name Server is active. Make sure that the specified IP host names are defined in the hosts configuration file on your PC and that the specified server Nodes have been started up successfully. You do not need to reboot the system in order to make the changes operational. Remember that before MS Windows allows applications to operate in a given Realm, you must first set up that Realm following the instructions given in Section 5.3. 5.3 Setting Up the Default Realm To set up a Realm, follow these steps: 1. Click on the BSTRUSERS Customization icon in the BASEstar Open Client Program Group. 2. Set the BSTR_REALM environment variable to the name of your Realm (see Appendix A for details). 5.4 Starting Up a Client Node Before an application can access BASEstar Open services, you must perform the following operations: 1. Execute the BSTRUSER.BAT command file to set all the installation-dependent environment variables. 2. Start MS Windows. 3. Start the Watchdog by double clicking on the Watchdog icon in the BASEstar Open Client Program Group. 5-4 Configuring BASEstar Open Client on an MS Windows System 5.5 Shutting Down a Client Node 5.5 Shutting Down a Client Node To shut down your Node, first make sure that all the BASEstar Open applications have been shut down, and then shut down the Watchdog task. To do this, double click on the Watchdog icon in the BASEstar Open Client Program Group. This causes a dialog box to appear; click on the System Menu button and select the Close option. The BASEstar Open Watchdog is shut down in an orderly fashion when you exit MS Windows. For further information about the Watchdog, refer to Section B.3. 5.6 Log Information All BASEstar Open environment and application components (applications and the Watchdog) that run on your MS Windows Node log information records in the following files: _________________________________________________________________ Component_________Log_File_______________________________________ Watchdog process %BSTR_WORK_ROOT%\NODE\COM\TRC \WATCHD16.LOG Application %BSTR_WORK_ROOT%\REALM\realm_name process [1]\TRC\BSTRtask_id[2].LOG [1]The_name_of_the_Realm_on_which_the_application_process_is_____ working. [2]The identifier of the MS Windows task in which the application is_running.______________________________________________________ Depending on whether or not you define the BSTR_DEBUG_TRACE environment variable, BASEstar Open only records information regarding unrecoverable errors or information related to more general events. The log files are in ASCII format; you can display them using the editor of your choice. The trace information is intended primarily to help DIGITAL support personnel. However, you can also use it for troubleshooting LAN and TCP/IP communication problems. 5-5 DIGITAL UNIX Systems _________________________________________________________________ 6 _________________________________________________________________ Preparing to Install BASEstar Open Client on a DIGITAL UNIX System Before attempting the installation procedures in Chapter 7, you should complete the pre-installation requirements outlined in this chapter. This chapter provides the necessary information to make your installation run smoothly. 6.1 Release Notes Your documentation includes the BASEstar Open Client Release Notes. Read this document before installing and using the product. The release notes may contain information about changes to the application. After installing the BASEstar Open Client software, you can also access the online release notes in the form of an ASCII text file by entering the following command: # more /usr/opt/bstclnt310/doc/relnotes.txt Your documentation may also include the BASEstar Open Release Notes Addendum or Read Before Installing letter (see Section 6.3). 6.2 License Registration BASEstar Open Client includes support for the DIGITAL UNIX License Management Facility (LMF). A License Product Authorization Key (License PAK) must be registered in the License Database (LDB) in order to use BASEstar Open Client on a newly-licensed node. The License PAK may be shipped along with the kit if you ordered the license and media together; otherwise, it is shipped separately to a location based on your license order. If you are installing BASEstar Open Client as an update on a node that is already licensed for this software, you willhave already completed the License PAK registration requirements. 6-1 Preparing to Install BASEstar Open Client on a DIGITAL UNIX System 6.2 License Registration If you are installing prerequisite or optional software along with BASEstar Open Client, review the PAK status and install the PAKs for any prerequisite or optional software before you install BASEstar Open Client. To register a license under the DIGITAL UNIX system, first log in as superuser. You then have a choice of two ways to perform the PAK registration in the License Database (LDB): o Before installing BASEstar Open Client At the superuser prompt, edit an empty PAK template with the lmf register command and include all the information on your License PAK as follows: # lmf register o After installing BASEstar Open Client At the superuser prompt, edit the partially completed PAK template with the lmf register command to add your unique License PAK information as follows: # lmf register - < /usr/var/adm/lmf/template For detailed information regarding licenses and associated PAKs, refer to the BASEstar Open Client Software Product Description (SPD). After you register your license, use the following lmf reset command to copy the license details from the License Database (LDB) to the kernel cache: # lmf reset For full details of how to use the DIGITAL UNIX License Management Facility, see the UNIX Guide to Software Licensing or the lmf(8) reference page. ________________________ Note ________________________ The installation procedure allows you to install the BASEstar Open Client files on your destination disk even if it does not find a registered license. A warning message informs you that the license has not been registered and you are prompted to continue. If this is the case, do not run the IVP. You cannot use BASEstar Open Client until a valid license is registered. ______________________________________________________ 6-2 Preparing to Install BASEstar Open Client on a DIGITAL UNIX System 6.2 License Registration 6.3 Checking the Media Software Distribution Kit Use the Bill of Materials (BOM) to check the contents of your BASEstar Open Client software distribution kit. The kit includes this installation guide and the CDROM optical disk for Alpha systems. Your distribution kit may also include a letter entitled BASEstar Open Client Release Notes Addendum or Read Before Installing BASEstar Open Client. This letter provides information that is important for you to know before installing the product and may not be included in this installation guide or release notes. If you have this letter, read it now. 6.4 BASEstar Open Client Kits The name of the BASEstar Open Client software kits for DIGITAL UNIX is BSTCLNT310. 6.5 Installation Procedure Requirements The time required to install BASEstar Open Client on DIGITAL UNIX systems is approximately 5 to 20 minutes. 6.5.1 Checking Login Privileges You must be able to log in as superuser on the system where you are installing BASEstar Open Client. You will only have sufficient privileges to install the BASEstar Open Client software if you are logged in as superuser. 6.5.2 Hardware Pre-requisites To perform the installation, you require a minimum hardware configuration as spelled out in the BASEstar Open Client Software Product Description (SPD). The minimum hardware requirements are as follows: o A supported Alpha AXP processor (for details, see the BASEstar Open Client Software Product Description) o A terminal o Sufficient free disk space as described in Section 6.5.4 6-3 Preparing to Install BASEstar Open Client on a DIGITAL UNIX System 6.5 Installation Procedure Requirements Check the SPD to see if there are further hardware requirements that apply to your particular application. 6.5.3 Software Pre-requisites To run BASEstar Open Client on an DIGITAL UNIX system, you need DIGITAL UNIX Version 4.0 (or higher). To check whether the kit is already loaded on your system, follow these steps: 1. Log in to the system where you intend to install BASEstar Open Client. 2. Enter the following command: # /usr/sbin/setld -i | grep BSTCLNT310 Check the displayed output for the name of the kit and any patches. If the kit is loaded, BASEstar Open displays the word "installed" after the kit identifier. 6.5.4 Determining Disk Space Requirements BASEstar Open Client on DIGITAL UNIX occupies approximately 10 Mb. 6.5.5 Increasing Disk Space Available for BASEstar Open Client Installation The BASEstar Open Client installation procedure creates the following directories and loads files into subordinate directories: /usr/opt/bstclnt310 /usr/var/opt/bstclnt310 If the bstclnt310 directory node in the previous paths does not exist, the installation procedure creates it. If the bstclnt310 node in the previous paths does exist, the installation procedure uses it. If you find that there is insufficient disk space for the BASEstar Open Client subsets, and know that you have additional space on alternative disks or disk partitions for your system, ask the system manager to take the necessary action. 6-4 Preparing to Install BASEstar Open Client on a DIGITAL UNIX System 6.6 Backing Up Your System Disk 6.6 Backing Up Your System Disk DIGITAL recommends that you back up your system disk before installing any software. For details of how to perform a system disk backup, refer to your UNIX documentation. 6.7 Stopping the Installation You can stop the installation procedure any time by using /. However, files created up to this point will not be deleted automatically; you must delete them interactively. Table E-1 lists the files and directories created during the installation procedure. 6.8 Error Recovery If a problem occurs during the installation, the system displays an appropriate error message. For example, if the installation procedure detects that there is insufficient disk space while installing BSTCLNT310, it displays the following message: There is not enough file system space for subset BSTCLNT310 BASEstar Open Client (BSTCLNT310) will not be loaded. Errors may occur during installation if: o The operating system version is incorrect o The prerequisite software version is incorrect o The system parameter values for successful installation are insufficient. For descriptions of the error messages generated by these conditions, see the DIGITAL UNIX documentation on system messages, recovery procedures, and DIGITAL UNIX software installation. For information about system software requirements, see Section 6.5.3. For details of how to report problems concerning BASEstar Open Client, refer to Section 8.1. 6-5 7 _________________________________________________________________ Installing BASEstar Open Client on a DIGITAL UNIX System This chapter describes how to install BASEstar Open Client on DIGITAL UNIX systems. Before starting the installation, read Chapter 6, which describes general operations and requirements for installing the product. This installation procedure allows you to install BASEstar Open Client locally. In a local (node-specific) installation, the system on which you install the product uses its own disks to run itself. The installation procedure loads BASEstar Open Client files onto the disks of your system. When you run BASEstar Open Client, its executable files are mapped into memory on the same system. 7.1 Responding to Installation Procedure Prompts This section explains the installation procedure prompts and displays. 7.1.1 Selecting Subsets After you enter the setld command for local (node-specific) installations, the installation procedure displays the names of the BASEstar Open Server subsets and asks you to specify the subsets that you want to load: Copyright (C) Digital Equipment Corporation. 1997. All Rights Reserved. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of DFARS 252.227-7013, or in FAR 52.227-19, or in FAR 52.227-14 Alt. III, as applicable. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor. The subsets listed below are optional: 7-1 Installing BASEstar Open Client on a DIGITAL UNIX System 7.1 Responding to Installation Procedure Prompts There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen or all at once on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. 1 BASEstar Open Client V3.1 Or you may choose one of the following options: 2) ALL of the above 3) CANCEL selections and redisplay menus 4) EXIT without installing any subsets Enter your choices or press RETURN to redisplay menus.) Choices (for example, 1 2 4-6):1 You are installing the following optional subsets: BASEstar Open Client V3.1 Is this correct? (y/n): If the displayed subsets are not the ones you intended to choose, enter n. In this case, the subset selection menu is again displayed, and you can correct your choice of optional subsets. If the displayed subsets are the ones you want to load, enter y. 7.1.2 Monitoring Displays During the Subset Loading Process The procedure displays a message that the installation is starting: Checking file system space required to install selected subsets: File system space checked OK. BASEstar Open Client V3.1 Copying from . (disk) Verifying The installation procedure continues. If, during the course of the installation, you encounter errors from the setld utility, see the Diagnostics section of the setld(8) reference page for an explanation of the error and the appropriate action to take. 7-2 Installing BASEstar Open Client on a DIGITAL UNIX System 7.1 Responding to Installation Procedure Prompts If the verification process fails, consult the /var/adm /smlogs/fverify.log file for information that may help you diagnose the problem. The final step of the installation procedure is signalled by the following prompt: Installation of BASEstar Open Client V3.1 files is completed. 7-3 8 _________________________________________________________________ Configuring and Managing BASEstar Open Client on a DIGITAL UNIX System This chapter describes the operations that you are advised to perform after installing BASEstar Open Client on a DIGITAL UNIX system, in order to ensure that it is ready for use. It also explains how to access the BASEstar Open Client documentation. 8.1 Getting Help and Reporting Problems If an error occurs while you are using BASEstar Open Client, and you believe the error is the result of a problem associated with the product, take one of the following actions: o If you have a basic or DECsupport Software Agreement, call your Customer Support Center (CSC). The CSC provides telephone support for high-level advisory and remedial assistance. o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). o If you purchased BASEstar Open Client within the last 90 days and you think the problem is caused by a software error, you can submit an SPR. If you submit an SPR, please take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the description and version number of BASEstar Open Client that you were using. Demonstrate the problem with specific examples. 2. Reduce the problem to as small a size as possible. 3. Remember to include listings of any command files, include files, relevant data files, and so forth. 8-1 Configuring and Managing BASEstar Open Client on a DIGITAL UNIX System 8.1 Getting Help and Reporting Problems 4. Provide a listing of the program. 5. If the program is longer than 50 lines, submit a copy of it on machine-readable media (floppy diskette or magnetic tape). If necessary, also submit a copy of the program library used to build the application. 6. Report only one problem per SPR. This will facilitate a faster response. 7. Mail the SPR package to DIGITAL. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Concise, complete information helps DIGITAL give accurate and timely service to software problems. If you find an error in the BASEstar Open Client documentation, send an electronic mail message to manufacturing@digital.com. 8.2 Setting Up and Starting the BASEstar Open Client Environment 8.2.1 Configuring the BASEstar Open Client Environment After installing BASEstar Open Client, you must execute a series of procedures to configure and start/stop the product: # /usr/opt/bstclnt310/etc/bstrcl_setup [-v] @@@ Using default kit_location: /usr/opt/bstclnt310 do you want to setup the kit installed in /usr/opt/bstclnt310? [yes] To configure BASEstar Open Client you must specify at least one name of a host where BASEstar Open Server is (or will be) installed. The LNS server of the host(s) you specify will be contacted sequentially to locate the Communication Server to connect to for a given realm. You can specify up to eight LNS servers. WARNING: you will be able to access only the realms that are (or will be) served by one of the LNS server you specify. When finished entering LNS server(s), press the RETURN key only. 8-2 Configuring and Managing BASEstar Open Client on a DIGITAL UNIX System 8.2 Setting Up and Starting the BASEstar Open Client Environment After asking you to confirm that you want to perform the setup procedure, the system prompts you for the name of at least one host on which BASEstar Open Server is installed: Enter the host name of a LNS server [no default]: naxos3.mln.dec.com Checking host ... Enter the host name of a LNS server [no default]: It then prompts you to enter: o The user name of the owner of the BASEstar Open Client work subdirectories. Type the user name that you wish to authorize to run BASEstar Open Client applications: User_name of the owner of the BASEstar work subdirectories: [root] o The group name authorized to access the BASEstar Open Client work subdirectories. Type a group name to cover any additional users you wish to authorize to run BASEstar Open Client applications on your system: Group_name authorized to access the BASEstar work subdirectories: [users] o The name of the BASEstar Open work root. Type the pathname of the directory where you want BASEstar Open Client to keep its run-time work tree: Name of the BASEstar work root: [/usr/var/opt/bstclnt310/etc/../spool_root] @@@ creating shell config file: /usr/opt/bstclnt310/etc/BSTRCOM_ayr.mln.dec.com.CFG ... @@@ creating shell setup file: /usr/opt/bstclnt310/etc/bstrclusers.sh ... @@@ creating shell setup file: /usr/opt/bstclnt310/etc/bstrclusers.sh.h_ayr.mln.dec.com ... @@@ creating c-shell setup file: /usr/opt/bstclnt310/etc/bstrclusers.csh ... @@@ creating c-shell setup file: /usr/opt/bstclnt310/etc/bstrclusers.csh.h_ayr.mln.dec.com ... @@@ Setup successfully performed. The node has been configured. 8-3 Configuring and Managing BASEstar Open Client on a DIGITAL UNIX System 8.2 Setting Up and Starting the BASEstar Open Client Environment 8.2.2 Starting Up BASEstar Open Client You cannot start up BASEstar Open Client unless you have the necessary authorization (see Section 8.2.1). To perform the startup procedure, execute the following commands: # csh # source /etc/bstrclusers.csh # bstrcl_start [-v] After executing the bstrcl_start command, you can run BASEstar Open Client applications. To do so, follow these steps: 1. Include one of the following statements in your .login file: o C shell # source /etc/bstrclusers.csh o Sh or Sh5 shell # . /etc/bstrclusers.sh 2. Set the environment variable BSTR_REALM to the name of the Realm that you wish to use on the system(s) running BASEstar Open servers. You cannot perform any BASEstar Open Client operations on these systems until you have configured and started the Realm. 8.2.3 Unsetting BASEstar Open Client You must unset BASEstar Open Client before you perform the shutdown procedure. Execute the following commands: # csh # source /etc/bstrclusers.csh # bstrcl_unset [-v] 8.2.4 Shutting Down BASEstar Open Client You cannot shut down BASEstar Open Client unless you have the necessary authorization (see Section 8.2.1). To perform the shutdown procedure, execute the following commands: 8-4 Configuring and Managing BASEstar Open Client on a DIGITAL UNIX System 8.2 Setting Up and Starting the BASEstar Open Client Environment # csh # source /etc/bstrclusers.csh # bstrcl_shut [-v] The bstrcl_shut procedure shuts down BASEstar Open Client without checking to see whether any client applications are running. Therefore, it is the responsibility of the user to ensure that no client applications are running before executing bstrcl_shut. 8.3 Displaying Documentation from CD-ROM The BASEstar Open Client documentation is located on the DIGITAL UNIX Layered Products Online Documentation CD-ROM in Bookreader (.DECW$BOOK) file format. You can display the Bookreader files on your workstation using the DECwindows Bookreader application. For information about how to access and display these files, refer to the DIGITAL UNIX Layered Products Disc User's Guide. 8-5 9 _________________________________________________________________ Removing BASEstar Open Client From a DIGITAL UNIX System This chapter describes how to remove BASEstar Open Client from a DIGITAL UNIX system. To deinstall BASEstar Open Client, follow these steps: 1. Shut down any BASEstar Open Client applications that are still running. 2. If necessary, shut down BASEstar Open Client, as described in Section 8.2.4. 3. Execute the following commands to undo the changes made by the bstrcl_setup procedure: # su root # csh # source /etc/bstrclusers.csh # bstrcl_unset [-v] 4. Execute the following command to remove the BASEstar Open Client software from your system: # setld -d BSTCLNT310 9-1 10 _________________________________________________________________ Environment Management Command Reference (UNIX) 10.1 Executing Environment Commands This section describes the general requirements for executing environment commands on your UNIX system. If you execute a command successfully, BASEstar Open Client returns the following exit status: 0 (zero) If a command fails, it returns a different value in the command exit status. It also displays one or more messages that provide information about the error(s) that occurred during execution of the command. 10.1.1 Users and Commands Not all users can issue the environment management commands. Table 10-1 indicates which user can issue a given command, where: o Root represents the superuser o Spool user indicates a user responsible for managing a given Node. For a given Node, the spool user is the root user (default) or the user whose name was specified when the advanced bstrcl_setup(1) command was executed for that Node. 10-1 Environment Management Command Reference (UNIX) 10.1 Executing Environment Commands Table 10-1 User Access to Environment Management Commands ___________and_Users_______________________________________ Command_______________User_________________________________ cli_bstr(1) ??? bstrcl_setup(1) Root bstrcl_start(1) Spool user bstrcl_shut(1) Spool user bstrcl_unset(1)_______Root_________________________________ 10.1.1.1 Executing a Command Follow the rules listed below when executing an environment command (except for the bstrcl_setup(1) command, the instructions for which are contained in the command description): o Log in as the appropriate user (as specified in Table 10-1) on the UNIX Node o Ensure that the installation-dependent global variables have been correctly set by executing the bstrclusers.[c]sh script file. 10.1.2 Privileges Needed to Run Environment Management Procedures Table 10-2 lists the privileges required to execute the BASEstar Open Client environment management commands. Table_10-2_Environment_Management_Privileges_______________ Privileges Required for Phase______________________Command_______Execution_________ Invoke the BASEstar Open cli_bstr(1) ??? CLI Set up BASEstar Open bstrcl_ Superuser Client setup(1) Start up BASEstar Open bstrcl_ Superuser Client start(1) (continued on next page) 10-2 Environment Management Command Reference (UNIX) 10.1 Executing Environment Commands Table_10-2_(Cont.)_Environment_Management_Privileges_______ Privileges Required for Phase______________________Command_______Execution_________ Shut down BASEstar Open bstrcl_ Superuser Client shut(1) Unset BASEstar Open bstrcl_ Superuser Client_____________________unset(1)________________________ 10-3 cli_bstr _________________________________________________________________ cli_bstr Invokes the BASEstar Open CLI. Syntax cli_bstr [-c] [-e "command1" "command2"..."command10"] [-f command_file] [-i startup_file] [-v] Description The cli_bstr command allows you to invoke the BASEstar Open CLI. You can execute CLI commands either interactively, or in batch mode by specifying the name of a command file from the command interpreter prompt. Options -c This option allows you to check the syntax and semantics of a CLI command file without executing the file. -e "command1" "command2"..."command10" This option allows you to execute up to ten CLI commands without leaving the platform-dependent command interpreter. After executing the specified commands, the command interpreter redisplays the CLI prompt. Enclose each CLI command between double quotes, and make sure that the commands are separated by at least one blank. -f command_file Pathname of a CLI command file that BASEstar Open executes at the shell prompt. -i startup_file An optional startup command file that you can request the CLI to execute. If you fail to specify the -i option, BASEstar Open does not execute a startup command file unless the following CLI command file exists in your home directory: o UNIX: 10-4 cli_bstr .cli_login o OpenVMS/Windows NT: cli_init.ini -v This option displays additional information on execution of the command. Examples 1. $ cli_bstr BSTR> This command invokes the CLI so that you can execute commands in interactive mode. 2. $ cli_bstr -e "SET SCOPE VOLATILE" "SHOW DATA_POINT \ /DOM1/DP3" $ This command sequence sets the VODB scope and displays the /DOM1/DP3 Data_Point. 3. $ cli_bstr -f exec2.com $ This command executes the exec2.com CLI command file at the shell prompt. See Also None 10-5 bstrcl_setup _________________________________________________________________ bstrcl_setup Defines the configuration parameters for the host on which you wish to run BASEstar Open Client and creates the BASEstar Open work tree. Syntax bstrcl_setup[-llocation] [-y] [-adv] [-v] [-first_lns_server host] [-default_lns_server_port port] [-work_root path] [-work_tree_owner user] [-work_tree_group group] [-work_tree_protection P] Description To configure BASEstar Open Client, you must specify the name of at least one host where BASEstar Open Server is (or will be) installed. The Watchdog contacts sequentially the LNS server of each specified host to locate the Communication Server for a given Realm. You can specify up to eight LNS servers. ________________________ Note ________________________ It is only possible to access Realms that are served by one of the specified LNS servers. ______________________________________________________ Options -l location Pathname of the installation directory for the kit that you wish to set up (if different from the default directory). Enter an absolute pathname. This option is only useful if BASEstar Open Client is installed on a diskless machine. -y Simplified setup procedure. The bstrcl_setup command assumes the default values for all parameters. 10-6 bstrcl_setup -adv Advanced setup procedure. The bstrcl_setup command prompts you to supply the UDP/IP port number of the LNS server and the protection mode for the BASEstar Open work subdirectories. -v This option displays additional information on the execution of the command. -first_lns_server host The hostname of the first LNS server. -default_lns_server_port port The UDP/IP port for the LNS server (the default value is 6101). You can also specify this parameter if you perform the advanced setup procedure (-adv). -work_root pathname The pathname of the BASEstar Open work root directory. If you do not specify this parameter, the bstrcl_setup command prompts you for the information. -work_tree_owner username The username of the owner of the BASEstar Open work subdirectories. If you do not specify this parameter, the bstrcl_setup command prompts you for the information. -work_tree_group group The group authorized to access the BASEstar Open work subdirectories. If you do not specify this parameter, the bstrcl_setup command prompts you for the information. -work_tree_protection NNN An octal value representing the protection mode of the BASEstar Open work subdirectories (the default value is 775). You can also specify this parameter if you perform the advanced setup procedure (-adv). 10-7 bstrcl_setup Usage Notes The bstrcl_setup command creates the following files: o $BSTR_ETC/bstrclusers.[c]sh o /etc/bstrclusers.[c]sh o $BSTR_ETC/bstrclusers.[c]sh.h_$HOST. It also creates the BASEstar Open work tree starting from the root directory that you specified, and records the location of the work root in the $BSTR_ETC/installation_file.h_$HOST file together with the Log Server configuration. The command saves a list of the LNS servers in the $BSTR_ETC/BSTRCOM_$HOST.CFG file. You can also store information in this file (in the [COM SERVERS] section)that allows the client to identify the Communication Server for each Realm that you wish to access. If the client locates this information for a given Realm, it connects directly to the Communication Server in question (without attempting to contact the LNS server). ________________________ Note ________________________ If you use bstrcl_setup to configure a host, you cannot use the same command to alter the configuration. Instead, you must use bstrcl_unset(1) to remove the configuration, and then reconfigure the host from scratch with bstrcl_setup. ______________________________________________________ See Also bstrcl_unset(1) bstrcl_start(1) bstrcl_shut(1) 10-8 bstrcl_unset _________________________________________________________________ bstrcl_unset Removes the BASEstar Open work tree and clears the BASEstar Open Client configuration defined by bstrcl_setup(1). Syntax bstrcl_unset [-l location] [-v] Description The bstrcl_unset command removes the BASEstar Open work tree, together with other run-time information needed by BASEstar Open Client to run on a node. Before executing this command, make sure that the BASEstar Open Client is not running: if bstrcl_unset detects a running client, it prompts the user to stop the client. Options -l location Pathname of the installation directory for the kit that you wish to remove (if different from the default directory). Enter an absolute pathname. -v This option displays additional information on the execution of the command. See Also bstrcl_setup(1) bstrcl_start(1) bstrcl_shut(1) 10-9 bstrcl_start _________________________________________________________________ bstrcl_start Starts up BASEstar Open Client. Syntax bstrcl_start [-v] [-c] Description The bstrcl_start command starts up BASEstar Open Client. You cannot execute this command unless you have already executed bstrcl_setup(1) successfully. Options -v This option displays additional information on the execution of the command. -c This option executes the $BSTR_ETC/bstrcl_host_startup/cleanlog.sh script. It also removes any old log files, leaving the last 120 lines of each log file. Usage Notes To complete the startup, the bstrcl_startup command executes the scripts found in the $BSTR_ETC/bstrcl_host_startup directory, according to the following order: 1. All check_*.sh scripts 2. All cleanup_*.sh scripts 3. The start[0-9][0-9]_*.sh and sync[0-9][0-9]_*.sh scripts for each startup phase. 10-10 bstrcl_start You can add your own phases to start up other applications that use BASEstar Open Client. ________________________ Note ________________________ You cannot run this command unless you have a valid BASEstar Open Client license. ______________________________________________________ Examples source /etc/bstrclusers.csh bstrcl_start See Also bstrcl_setup(1) bstrcl_unset(1) bstrcl_shut(1) 10-11 bstrcl_shut _________________________________________________________________ bstrcl_shut Shuts down BASEstar Open Client. Syntax bstrcl_shut [-v] [-c] Description The bstrcl_shut command shuts down BASEstar Open Client. Options -v This option displays additional information on the execution of the command. -c This option executes any cleanup scripts called clean[0-9][0-9]_*.sh in $BSTR_ETC/bstrcl_host_shutdown. Usage Notes To complete the shutdown, the bstrcl_shut command executes all scripts named shut[0-9][0-9]_*.sh that are located in the $BSTR_ETC/bstrcl_host_shutdown directory. See Also bstrcl_setup(1) bstrcl_unset(1) bstrcl_start(1) 10-12 HP-UX Systems _________________________________________________________________ 11 _________________________________________________________________ Preparing to Install BASEstar Open Client on a HP-UX System Before attempting the installation procedures in Chapter 12, you should complete the pre-installation requirements outlined in this chapter. This chapter provides the necessary information to make your installation run smoothly. 11.1 Release Notes Your documentation includes the BASEstar Open Client Release Notes. Read this document before installing and using the product. The release notes may contain information about changes to the application. After installing the BASEstar Open Client software, you can also access the online release notes in the form of an ASCII text file by entering one of the following command sequences (depending on your shell): o Sh or Sh5 shell: # source /etc/bstrclusers.sh # more $BSTR_LIB/../doc/relnotes.txt o C shell: # source /etc/bstrclusers.csh # more $BSTR_LIB/../doc/relnotes.txt Your documentation may also include the BASEstar Open Release Notes Addendum or Read Before Installing letter (see Section 11.2). 11-1 Preparing to Install BASEstar Open Client on a HP-UX System 11.2 Checking the Media Software Distribution Kit 11.2 Checking the Media Software Distribution Kit Use the Bill of Materials (BOM) to check the contents of your BASEstar Open Client software distribution kit. The kit includes this installation guide and the CDROM optical disk for HP-UX systems. Your distribution kit may also include a letter entitled BASEstar Open Client Release Notes Addendum or Read Before Installing BASEstar Open Client. This letter provides information that is important for you to know before installing the product and may not be included in this installation guide or release notes. If you have this letter, read it now. 11.3 Installation Procedure Requirements Installing BASEstar Open Client on your HP-UX systems takes approximately 20 minutes. 11.3.1 Checking Login Privileges You must be able to log in as superuser on the system where you are installing BASEstar Open Client. You will only have sufficient privileges to install the BASEstar Open Client software if you are logged in as superuser. 11.3.2 Hardware Pre-requisites To perform the installation, you require a minimum hardware configuration as spelled out in the BASEstar Open Client Software Product Description (SPD). The minimum hardware requirements are as follows: o A supported HP PA-RISC processor (for details, see the BASEstar Open Client Software Product Description) o A terminal o Sufficient free disk space as described in Section 11.3.4. Check the SPD to see if there are further hardware requirements that apply to your particular application. 11-2 Preparing to Install BASEstar Open Client on a HP-UX System 11.3 Installation Procedure Requirements 11.3.3 Software Pre-requisites To run BASEstar Open Client on a HP-UX system, you need HP-UX Version 9.01 (or higher). The Software Product Description contains a complete list of pre-requisite and optional software and their required version numbers. To check whether the kit is already loaded on your system, follow these steps: 1. Log in to the system where you intend to install BASEstar Open Client. 2. Enter the following command: # swlist -l product | grep BSTCLNT If the system responds as follows, the kit has already been loaded: BSTCLNT 3.1.0 BASEstar Open Cient 11.3.4 Determining Disk Space Requirements BASEstar Open Client on HP-UX occupies approximately 10 Mbytes. The BASEstar Open Client installation procedure creates the following directories and loads files into subordinate directories: /usr/opt/bstclnt310 If the bstclnt310 directory node in the previous paths does not exist, the installation procedure creates it. If the bstclnt310 node in the previous paths does exist, the installation procedure uses it. If you find that there is insufficient disk space for the BASEstar Open Client subsets, and know that you have additional space on alternative disks or disk partitions for your system, ask the system manager to take the necessary action. 11.4 Backing Up Your System Disk DIGITAL recommends that you back up your system disk before installing any software. For details of how to perform a system disk backup, refer to your UNIX documentation. 11-3 Preparing to Install BASEstar Open Client on a HP-UX System 11.5 Stopping the Installation 11.5 Stopping the Installation You can stop the installation procedure any time by using /. However, files created up to this point will not be deleted automatically; you must delete them interactively. Table E-2 lists the files and directories created during the installation procedure. 11.6 Error Recovery If a problem occurs during the installation, the system displays an appropriate error message. An error may occur during installation if: o The operating system version is incorrect o The prerequisite software version is incorrect o The system parameter values for successful installation are insufficient. For descriptions of the error messages generated by these conditions, see the HP-UX documentation on system messages, recovery procedures, and HP-UX software installation. For information about system software requirements, see Section 11.3.3. For details of how to report problems concerning BASEstar Open Client, refer to Section 13.1. 11-4 12 _________________________________________________________________ Installing BASEstar Open Client on a HP-UX System This chapter describes how to install BASEstar Open Client on HP-UX systems. Before starting the installation, read Chapter 11, which describes general operations and requirements for installing the product. This installation procedure allows you to install BASEstar Open Client locally. In a local (node-specific) installation, the system on which you install the product uses its own disks to run itself. The installation procedure loads BASEstar Open Client files onto the disks of your system. When you run BASEstar Open Client, its executable files are mapped into memory on the same system. 12.1 Installing CD-ROM Consolidated Distribution Media To install BASEstar Open Client on your HP-UX system, follow these steps: 1. Log in as root. 2. Decide which directory you want to use as your mount point. ________________________ Note ________________________ The name of the mount point directory is arbitrary. The mount point used for the examples in this chapter is /cdrom. If this directory does not exist, create it as follows: # mkdir /cdrom ______________________________________________________ 3. Load the software media into the appropriate drive and execute the following command: # mount -r -F cdfs / /cdrom 12-1 Installing BASEstar Open Client on a HP-UX System 12.1 Installing CD-ROM Consolidated Distribution Media where is the name of your CD-ROM device. 4. Run the swinstall program to install the software: # /usr/sbin/swinstall -s /cdrom/bstclnt310/kit/HP-UX_10.01 BSTCLNT The installation procedure displays the following information: ======= 05/20/96 13:50:24 METDST BEGIN swinstall SESSION (non-interactive) * Session started for user "root@tardoc". * Beginning Selection Phase. * Options: preview no target type root linkinstall no verbose 1 option file session file software file target file * Target connection succeeded for "tardoc:/". * Source connection succeeded for "tardoc:/cdrom/bstclnt310/kit/HP-UX_10.01". * Source: /cdrom/bstclnt310/kit/HP-UX_10.01 * Targets: tardoc:/ * Software selections: BSTCLNT.BSTCLNT,r=3.0.0,a=S700/S800_HP-UX_10.0,v=DEC * Selection Phase succeeded. * Beginning Analysis Phase. * Session selections have been saved in the file "/.sw/sessions/swinstall.last". * The analysis phase succeeded for "tardoc:/". * Analysis Phase succeeded. * Beginning Execution Phase. * The execution phase succeeded for "tardoc:/". * Execution Phase succeeded. NOTE: More information may be found in the agent logfile (location is tardoc:/var/adm/sw/swagent.log). 12-2 Installing BASEstar Open Client on a HP-UX System 12.1 Installing CD-ROM Consolidated Distribution Media ======= 05/20/96 13:52:29 METDST END swinstall SESSION (non-interactive) It then displays a list of the files that it creates on your system (see Section E.2). The end of the installation procedure is signalled by the following lines: /system/BSTCLNT/CDFinfo /system/BSTCLNT/customize /system/BSTCLNT/index Finished loading fileset "BSTCLNT". Beginning customize script for fileset "BSTCLNT" (1 of 1). Review the log file, /tmp/update.log, by: 1) typing "more /tmp/update.log"; 2) finding the correct date and time heading; 3) looking for any messages that begin with ERROR or WARNING. Do not attempt to interrupt the installation procedure at any time. A more reliable alternative is to deinstall the software after the installation procedure has terminated (see Chapter 14). For a complete list of the files and directories in the BASEstar Open Client for HP-UX kit, refer to Appendix E. 12-3 13 _________________________________________________________________ Configuring BASEstar Open Client on a HP-UX System This chapter describes the operations that you are advised to perform after installing BASEstar Open Client on a HP- UX system, in order to ensure that it is ready for use. It also explains how to access the BASEstar Open Client documentation. 13.1 Getting Help and Reporting Problems If an error occurs while you are using BASEstar Open Client, and you believe the error is the result of a problem associated with the product, take one of the following actions: o If you have a basic or DECsupport Software Agreement, call your Customer Support Center (CSC). The CSC provides telephone support for high-level advisory and remedial assistance. o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). o If you purchased BASEstar Open Client within the last 90 days and you think the problem is caused by a software error, you can submit an SPR. If you submit an SPR, please take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the description and version number of BASEstar Open Client that you were using. Demonstrate the problem with specific examples. 2. Reduce the problem to as small a size as possible. 3. Remember to include listings of any command files, include files, relevant data files, and so forth. 4. Provide a listing of the program. 13-1 Configuring BASEstar Open Client on a HP-UX System 13.1 Getting Help and Reporting Problems 5. If the program is longer than 50 lines, submit a copy of it on machine-readable media (floppy diskette or magnetic tape). If necessary, also submit a copy of the program library used to build the application. 6. Report only one problem per SPR. This will facilitate a faster response. 7. Mail the SPR package to DIGITAL. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Concise, complete information helps DIGITAL give accurate and timely service to software problems. If you find an error in the BASEstar Open Client documentation, send an electronic mail message to manufacturing@digital.com. 13.2 Setting Up and Starting the BASEstar Open Client Environment 13.2.1 Configuring the BASEstar Open Client Environment After installing BASEstar Open Client, you must execute a series of procedures to configure and start/stop the product: # /usr/opt/bstclnt310/etc/bstrcl_setup [-v] @@@ Using default kit_location: /usr/opt/bstclnt310 do you want to setup the kit installed in /usr/opt/bstclnt310? [yes] To configure BASEstar Open Client you must specify at least one name of a host where BASEstar Open Server is (or will be) installed. The LNS server of the host(s) you specify will be contacted sequentially to locate the Communication Server to connect to for a given realm. You can specify up to eight LNS servers. WARNING: you will be able to access only the realms that are (or will be) served by one of the LNS server you specify. When finished entering LNS server(s), press the RETURN key only. After asking you to confirm that you want to perform the setup procedure, the system prompts you for the name of at least one host on which BASEstar Open Server is installed: 13-2 Configuring BASEstar Open Client on a HP-UX System 13.2 Setting Up and Starting the BASEstar Open Client Environment Enter the host name of a LNS server [no default]: naxos3.mln.dec.com Checking host ... Enter the host name of a LNS server [no default]: It then prompts you to enter: o The user name of the owner of the BASEstar Open Client work subdirectories. Type the user name that you wish to authorize to run BASEstar Open Client applications: User_name of the owner of the BASEstar work subdirectories: [root] o The group name authorized to access the BASEstar Open Client work subdirectories. Type a group name to cover any additional users you wish to authorize to run BASEstar Open Client applications on your system: Group_name authorized to access the BASEstar work subdirectories: [users] o The name of the BASEstar Open work root. Type the pathname of the directory where you want BASEstar Open Client to keep its run-time work tree: Name of the BASEstar work root: [/usr/var/opt/bstclnt310/etc/../spool_root] @@@ creating shell config file: /usr/opt/bstclnt310/etc/BSTRCOM_ayr.mln.dec.com.CFG ... @@@ creating shell setup file: /usr/opt/bstclnt310/etc/bstrclusers.sh ... @@@ creating shell setup file: /usr/opt/bstclnt310/etc/bstrclusers.sh.h_ayr.mln.dec.com ... @@@ creating c-shell setup file: /usr/opt/bstclnt310/etc/bstrclusers.csh ... @@@ creating c-shell setup file: /usr/opt/bstclnt310/etc/bstrclusers.csh.h_ayr.mln.dec.com ... @@@ Setup successfully performed. The node has been configured. 13-3 Configuring BASEstar Open Client on a HP-UX System 13.2 Setting Up and Starting the BASEstar Open Client Environment 13.2.2 Starting Up BASEstar Open Client You cannot start up BASEstar Open Client unless you have the necessary authorization (see Section 13.2.1). To perform the startup procedure, execute the following commands: # csh # source /etc/bstrclusers.csh # bstrcl_start [-v] After executing the bstrcl_start command, you can run BASEstar Open Client applications. To do so, follow these steps: 1. Include one of the following statements in your .login file: o C shell # source /etc/bstrclusers.csh o Sh or Sh5 shell # . /etc/bstrclusers.sh 2. Set the environment variable BSTR_REALM to the name of the Realm that you wish to use on the system(s) running BASEstar Open servers. You cannot perform any BASEstar Open Client operations on these systems until you have configured and started the Realm. 13.2.3 Unsetting BASEstar Open Client You must unset BASEstar Open Client before you perform the shutdown procedure. Execute the following commands: # csh # source /etc/bstrclusers.csh # bstrcl_unset [-v] 13.2.4 Shutting Down BASEstar Open Client You cannot shut down BASEstar Open Client unless you have the necessary authorization (see Section 13.2.1). To perform the shutdown procedure, execute the following commands: 13-4 Configuring BASEstar Open Client on a HP-UX System 13.2 Setting Up and Starting the BASEstar Open Client Environment # csh # source /etc/bstrclusers.csh # bstrcl_shut [-v] The bstrcl_shut procedure shuts down BASEstar Open Client without checking to see whether any client applications are running. Therefore, it is the responsibility of the user to ensure that no client applications are running before executing bstrcl_shut. 13.3 Displaying Documentation from CD-ROM The BASEstar Open Client documentation is located on the HP-UX Layered Products Online Documentation CD-ROM in Bookreader (.DECW$BOOK) file format. You can display the Bookreader files on your workstation using the DECwindows Bookreader application. For information about how to access and display these files, refer to the HP-UX Layered Products Disc User's Guide. 13-5 14 _________________________________________________________________ Removing BASEstar Open Client From a HP-UX System This chapter describes how to remove BASEstar Open Client from a HP-UX system. To deinstall BASEstar Open Client, follow these steps: 1. Log in as root. 2. Shut down any BASEstar Open Client applications that are still running. 3. If necessary, shut down and unset BASEstar Open Client, as described in Section 13.2.4. 4. Execute the following deinstallation command: # /usr/sbin/swremove BSTCLNT 5. Execute the following command to remove the entire BASEstar Open Client directory tree: # rm -rf /usr/opt/bstclnt310 14-1 PC-specific Utilities _________________________________________________________________ This section contains information relevant to MS Windows and Windows NT platforms only. 15 _________________________________________________________________ Introduction to the Graphic Configuration Utility (GCU) The Graphic Configuration utility is a graphics tool, currently available on Windows NT and MS Windows platforms only. It allows you to create and manage BASEstar Open configurations in pure MS Windows style. (A BASEstar Open configuration is a collection of BASEstar Open objects that model the real life production environment.) BASEstar Open objects created by the Graphic Configuration utility can reside on any physical node of the network, depending on how you define the Realm which contains the objects. ________________________ Note ________________________ A Realm is not a BASEstar Open object. You cannot use the Graphic Configuration utility to create a Realm. You must use the appropriate command procedures to configure the Realm when you set up BASEstar Open Client on MS Windows platforms. On Windows NT platforms, you can use the BASEstar Open Manager to configure your Realm. ______________________________________________________ 15.1 The Graphical Interface The Graphic Configuration utility allows you to represent BASEstar Open objects in a configuration as components of a tree structure. This tree structure is analagous to a file system, where BASEstar Open Domains, Actors and VMDs correspond to directories, and Data_Points, Activities and Polling_Sets correspond to files. 15-1 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface The Graphic Configuration utility offers a graphical view of a BASEstar Open configuration. It allows you to: o Browse through a BASEstar Open configuration tree o Create and manage BASEstar Open objects The Graphic Configuration utility employs standard graphic icons, such as windows, dialog boxes, list boxes and menu bars. These icons supply all the views, commands, options and functions that you need to maintain a configuration. 15.1.1 Activating the Graphic Configuration Utility To activate the Graphic Configuration utility, double click on the Graphic Configuration utility icon in the BASEstar Open Client Program Group. Alternatively, you can run the BSTRCNFG.EXE executable which resides in the BSTRCNFG\BIN directory of your installation root as follows: bstrconfg.exe where realm_name represents the name of your BASEstar Open. 15.1.2 Navigating a BASEstar Open Configuration Tree The main window of the Graphic Configuration utility allows you to browse through a BASEstar Open configuration tree by displaying the BASEstar Open configuration as a graphical representation. It presents a BASEstar Open configuration tree in the same way that your Windows-based File Manager presents the contents of a file system. The main configuration window is a two-sided window divided by a split bar. Each window offers a different context: o The left-hand window displays the configuration tree hierarchy and the elements of the configuration tree. o The right-hand window displays the contents of the selected configuration tree element. 15-2 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface 15.1.2.1 Configuration of the Tree Hierarchy The configuration tree hierarchy is a collection of configuration tree elements. The left-hand window illustrates this tree structure. BASEstar Open Client defines parent-child relationships between objects as follows: o Realms[1], Domains, Actors and VMDs are the only objects that can assume parent status; that is, they can contain other BASEstar Open objects. o Domains, Actors, and VMDs are configuration tree elements. They are the only BASEstar Open objects that can appear in the left-hand window. The following rules apply to configuration tree elements: o Domain: one or more per configuration (Realm); one or more per Domain o Actor: one or more per configuration (Realm); one or more per Actor o VMD: one or more per configuration (Realm) For further information on managing objects, refer to Section 15.1.3. 15.1.2.2 Contents of the Configuration Tree Elements The Graphic Configuration utility displays the children associated with the configuration tree elements in the right-hand window. In BASEstar Open, a clear set of rules defines how objects are organized in a parent-child relationship; that is, which object can be a child of which parent configuration tree element. Table 15-1 summarizes these rules. ____________________ [1] A Realm is not a BASEstar Open object. However, since a Realm represents the root of a BASEstar Open configuration, it is used in the graphical representation of the parent-child relationship. 15-3 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface Table 15-1 Parent-Child Relationship Between Elements and ___________Objects_________________________________________ Child Appearance__________Parent_________ __________________________________Realm__Domain_Actor__VMD_ Domain Yellow X X Data_Point X Data_Point_Set X Device_Data_Point X Enbox X Event X Event_Set X Filter X Mapped_Data_Point X Packet X Port X Trigger X Actor Red X X Activity X Program X VMD Green X VMD_Extension_ X Parameter Named_Variable X Unnamed_Variable X Polling_Set X Node Blue X Array_Datatype X Structure_Datatype X Protocol_Profile X Timer_____________________________X________________________ For information regarding the use of the mouse in connection with objects displayed in the right-hand window, refer to Section 15.1.3. 15-4 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface 15.1.3 Managing Objects As well as providing a means of browsing through a configuration tree, the main Graphical Configuration window allows you to manage BASEstar Open objects. You can create, modify and delete BASEstar Open objects directly from the menu bar of the main Graphical Configuration window. In general, you can apply these operations to objects in both the permanent (PODB) and volatile (VODB) databases. To address a particular database, pull down the Open option from the File menu and choose either Permanent or Volatile. The menu associated with the Create option lists all the objects that you can include in a BASEstar Open configuration. If you select the Create and Modify options, BASEstar Open Client uses supplementary dialog boxes to display object attributes and additional windows (for example, list boxes) to resolve the relationship between object attributes. If you attempt to remove an object from the configuration using the Delete option, the Graphic Configuration utility displays a confirmation box. 15.1.3.1 Creating an Object BASEstar Open objects have a parent-child relationship. Follow these steps to create an object: 1. Click or double click on the configuration tree element in the left-hand window that is to be the parent. 2. Pull down the Create option from the Configure menu. The Graphic Configuration utility displays a list of object classes. 3. From the list displayed, choose the object type that you wish to create. (Depending on the selected configuration element, the Graphic Configuration utility displays in greyed text the objects that are not elegible for creation. Refer to Table 15-1 for details of parent- child relationships.) Once you have selected an object type for creation, the Graphic Configuration utility checks that the appropriate server is running and displays the Object Attribute dialog box for the object in question. For further information about these dialog boxes, refer to Section 15.1.3.4. 15-5 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface 4. Enter the relevant information about the object in the dialog box. If an object attribute affects other BASEstar Open objects, the Graphic Configuration utility lets you use the Browser to select the object. For further information about the Browser, refer to Section 15.1.3.5. 5. Click on the OK button when you have entered all the necessary attribute information for the object. The Graphic Configuration utility checks that you have completed the mandatory fields in the dialog box, and that all information is valid. If no errors occur during creation, it displays a message to confirm the success of the operation. 15.1.3.2 Deleting an Object To delete an object, first click on the object in the right-hand window. Pull down the Configure menu of the Graphic Configuration utility and select Delete. Before deleting the object, the Graphic Configuration utility requests confirmation of the operation. If no errors occur during deletion, it eliminates the object from the configuration. You can only delete one object at a time. Existing parent-child relationships or object attribute relationships may prevent you from deleting an object. For a summary of all these relationships, refer to Table 15-1. You can only delete the following objects in a VODB configuration: o Data_Point o Data_Point_Set o Enbox o Event o Event_Set o Filter o Packet o Port o Timer 15-6 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface o Trigger 15.1.3.3 Modifying an Object You can only modify an object if it appears in the right- hand window. To do so, follow these steps: 1. Click twice on the object in question. 2. Pull down the Configure menu of the Graphic Configuration utility and select Modify. The Graphic Configuration utility displays the Object Attribute dialog box containing the current attributes of the object. 3. Modify the object attributes as necessary. If the attribute that you are modify is related to another BASEstar Open object, the Graphic Configuration utility lets you use the Browser to select the object. If no errors occur during the modify operation, the process completes the operation, but the contents of the main Graphical Configuration window remain unchanged. You can only modify the following objects in a VODB configuration: o Activity o Actor o Data_Point o Device_Data_Point o Node o Program o Timer 15.1.3.4 Object Attribute Dialog Boxes BASEstar Open Client defines the attributes for each object, in terms of the following characteristics: o Type o Length o Possible relationships-mandatory or optional 15-7 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface Each time you create a new object or modify an existing object, the Graphic Configuration utility displays a object attribute form containing this information. When creating or modifying an object, BASEstar Open Client defines how attributes can be managed. In general, it is possible to specify all the attributes of an object during a create operation. However, you can only alter certain attributes during a modify operation. 15.1.3.5 Attribute Selection Dialog Boxes (Browser) When creating or modifying a BASEstar Open object, you may wish to supply an attribute that has a relationship with other BASEstar Open objects. With the aid of the Browser, you can list all available objects that are valid for the relationship. Table 15-2 lists the attributes that may be displayed, depending on the BASEstar Open object and attribute in question. 15-8 Introduction to the Graphic Configuration Utility (GCU) 15.1 The Graphical Interface Table_15-2_BASEstar_Open_Objects_and_Attributes____________ All objects of belonging ...______________to_...______objects_list__________________ One type Realm VMD_Extension_Parameter or Node or Domain or More than one Realm Array_Data_Type and type Structured_Data_Type One type Domain Event or Filter More than one Domain Data_Point and type Device_Data_Point One type All Event Domains More than one All Data_Point, type Domains Device_Data_Point and Mapped_ Data_Point One Type All Actors Program More than one VMD Named_Variable and type_________________________Unnamed_Variable______________ 15-9 16 _________________________________________________________________ BASEstar Open DDE Connectivity The term BASEstar Open DDE connectivity refers to the capability of linking two different data representations, namely: o The MS Windows, Windows NT or Windows 95 data representation, DDE o The BASEstar Open data representation. The link enables a bidirectional exchange of data between a BASEstar Open application and a DDE-compliant MS Windows, Windows NT or Windows 95 application. As a result, a generic DDE-compliant Windows NT application can: o Read solicited BASEstar Open data values o Read unsolicited BASEstar Open data values o Write BASEstar Open data values. For example, an MS Windows Excel user can: o Send the value of a BASEstar Open Data_Point to a spreadsheet cell o Update a spreadsheet cell automatically each time a BASEstar Open Data_Point changes its value o Update a BASEstar Open Data_Point with the value of a spreadsheet cell. It is possible to configure a BASEstar Open application to: o Read solicited data values from DDE-compliant MS Windows, Windows NT or Windows 95 applications o Read unsolicited data values from MS Windows, Windows NT or Windows 95 applications o Write data for MS Windows, Windows NT or Windows 95 applications. 16-1 BASEstar Open DDE Connectivity For example, the BASEstar Open application can: o Poll the value of an EXCEL spreadsheet cell o Receive notification when the value of an EXCEL spreadsheet cell changes o Update the value of an EXCEL spreadsheet cell when the value of a Data_Point changes. From a DDE viewpoint, both sides can alternate as a DDE server and a DDE client. The client initiates the communication by telling the server which data values it wishes to: o Read o Receive unsolicited o Write. In order for it to function as a DDE client, you must supply the DDE Bridge with some configuration information regarding the type of DDE links to be activated, and the mapping between BASEstar Open objects and DDE variables managed by the partner application. On the other hand, if the DDE Bridge is to behave as a DDE server, no configuration information is necessary, given that the partner DDE client is responsible for sending it through the standard DDE Application|Topic!Item string. The DDE Bridge can handle the connection with any kind of DDE-compliant application, including commercially available third party DASes, but is mainly designed to exchange data with personal productivity tools, such as spreadsheets. 16.1 Using the DDE Bridge To activate the BASEstar Open DDE Bridge, click on the appropriate icon in the BASEstar Open Client Program Group. By default, the DDE Bridge behaves as a DDE server; it waits for clients to initiate the data exchange. You can alter this behavior by configuring the DDE Bridge to act as a client. 16-2 BASEstar Open DDE Connectivity 16.1 Using the DDE Bridge You can also customize the DDE Bridge so that it makes better use of BASEstar Open resources. To do this, pull down the File menu of the Program Manager and change the invocation command in the Properties dialog box. The syntax of the command is: bstrdde [realm] [switches] where: o bstrdde is the bridge-executable image o realm is the name of your BASEstar Open Realm. The possible switches are: o -e enbox_name The name of the Enbox in which you want the DDE Bridge to receive notification of changes in the BASEstar Open data values that it monitors. The default name is dde_ enbox. o -d domain name The BASEstar Open Domain in which you want the DDE Bridge to operate. The default Domain is "/" (the father of all the Domains). o -f filename The name of a file containing the configuration information that you want the DDE Bridge to load in order to behave as a DDE client. There is no default setting: if you omit this switch, the DDE Bridge initially behaves as a DDE server. However, it is also possible to load the configuration information once you have started the DDE Bridge. The configuration file is an ASCII file containing a series of lines with the following syntax: