BASEstar_Open_Client________________________________ Inst. & Management Guide Order Number: AA-QSKGA-TE February 1996 This manual contains instructions for installing and setting up BASEstar Open Client on OpenVMS, Digital UNIX, HP-UX, MS Windows and Windows NT platforms. 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. 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.0 Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ February 1996 © Digital Equipment Corporation 1996. 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 and Windows NT 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................................................... v 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 MS Windows Systems 2 Installing BASEstar Open Client on an MS Windows System 2.1 Checking the Media Software Distribution Kit..... 2-1 2.2 Before You Begin................................. 2-1 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-2 2.2.5 Software Pre-requisites ....................... 2-3 2.3 Unpacking the Kit................................ 2-3 2.4 Installation Procedure........................... 2-4 2.5 Error Recovery................................... 2-4 3 Configuring and Managing the BASEstar Open Environment on an MS Windows System 3.1 BASEstar Open Environment Components............. 3-1 3.1.1 Nodes ......................................... 3-1 3.1.2 Realms ........................................ 3-2 3.2 Setting Up a Realm............................... 3-2 3.3 Using the Communication Configuration File....... 3-3 iii 3.3.1 Editing the Default Version of the Communication Configuration File............... 3-4 3.4 Starting Up a Client Node........................ 3-5 3.5 Shutting Down a Client Node...................... 3-5 3.6 Log Information.................................. 3-5 Windows NT Systems 4 Installing BASEstar Open Client on a Windows NT 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.3 Unpacking the Kit................................ 4-3 4.4 Installation Procedure........................... 4-4 4.4.1 Installing the BASEstar Open Client Kit ....... 4-4 5 Configuring and Managing the BASEstar Open Client Environment on a Windows NT System 5.1 BASEstar Open Environment Components............. 5-1 5.1.1 Nodes ......................................... 5-1 5.1.2 Realms ........................................ 5-2 5.2 Setting Up a Realm............................... 5-2 5.3 Using the Communication Configuration File....... 5-3 5.3.1 Editing the Default Version ................... 5-4 5.4 Starting Up a Client Node........................ 5-5 5.4.1 Shutting Down a Client Node ................... 5-5 5.5 Log Information.................................. 5-6 5.6 The BASEstar Open Manager Utility................ 5-7 5.6.1 Configuring BASEstar Open Nodes and Realms .... 5-7 5.6.1.1 Setting up the Default Realm................ 5-8 5.6.1.2 Setting up the LNS Server Node(s)........... 5-9 5.6.1.3 Configuring BASEstar Open Autostart......... 5-10 5.6.2 Customizing the BASEstar Open Manager Window .. 5-11 iv Digital UNIX Systems 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 Requirements ......................... 6-3 6.5.3 Software Requirements ......................... 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 the BASEstar Open Client Environment on a Digital UNIX System 8.1 Reporting Errors................................. 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 PC-specific Utilities Section 10 Introduction to the Graphic Configuration Utility (GCU) 10.1 The Graphical Interface.......................... 10-1 10.1.1 Activating the Graphic Configuration Utility .. 10-2 10.1.2 Navigating a BASEstar Open Configuration Tree........................................... 10-2 10.1.2.1 Configuration of the Tree Hierarchy......... 10-2 10.1.2.2 Contents of the Configuration Tree Elements.................................... 10-3 10.1.3 Managing Objects .............................. 10-5 10.1.3.1 Creating an Object.......................... 10-5 10.1.3.2 Deleting an Object.......................... 10-6 10.1.3.3 Modifying an Object......................... 10-7 10.1.3.4 Object Attribute Dialog Boxes............... 10-7 10.1.3.5 Attribute Selection Dialog Boxes (Browser).. 10-8 11 BASEstar Open DDE Connectivity 11.1 Using the DDE Bridge............................. 11-4 11.2 Limitations...................................... 11-14 11.2.1 Automatic Configuration ....................... 11-15 11.2.2 Supported Datatypes ........................... 11-15 11.2.3 Domains ....................................... 11-16 A BASEstar Open Environment Variables (MS Windows and Windows NT Systems) A.1 Environment Variable List........................ A-1 A.2 Setting Installation-Dependent Environment Variables........................................ A-3 vi B Managing the BSTRCOM.CFG File (MS Windows and Windows NT Systems) 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 How the BSTRCOM.CFG File Is Used at Runtime...... B-5 C Directories and Files Installed on MS Windows and Windows NT Systems D Updating the DEC PathWorks Configuration (MS Windows Systems) E Directories and Files Installed on Digital UNIX Systems E.1 Files and Directories Installed by the BSTCLNT300 Kit.............................................. E-1 Index Examples D-1 Upgraded PROTOCOL.INI DEC PathWorks File ...... D-1 Figures 3-1 Default BSTRCOM.CFG File ...................... 3-4 5-1 Default BSTRCOM.CFG File ...................... 5-4 5-2 BASEstar Open Manager Window .................. 5-7 5-3 Default Realm Setup Dialog Box ................ 5-8 5-4 LNS Setup Dialog Box .......................... 5-9 5-5 LNS Server/s Check Dialog Box ................. 5-10 11-1 Exchanging Data Between BASEstar Open Servers and DDE Applications........................... 11-3 11-2 DDE Bridge Main Window ........................ 11-9 11-3 Configuring the DDE Bridge as a DDE Client .... 11-11 vii 11-4 Exporting Data_Point Names to the Clipboard ... 11-14 A-1 Sample BSTRUSER.BAT File ...................... A-4 Tables 1 Conventions Used in BASEstar Open ............. viii 10-1 Parent-Child Relationship Between Elements and Objects........................................ 10-4 10-2 BASEstar Open Objects and Attributes .......... 10-9 A-1 BASEstar Open Environment Variables ........... A-1 C-1 BASEstar Open Client Directories and Files on MS Windows and Windows NT Systems.............. C-1 C-2 Executable Images for PC Server .............. C-3 E-1 Files and Directories Installed by the BSTCLNT300 Kit................................. E-1 viii _________________________________________________________________ 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 describes how to install BASEstar Open Client on an MS Windows system. v o Chapter 3 explains how to configure and manage the BASEstar Open Client environment on your MS Windows personal computer. o Chapter 4 explains how to install BASEstar Open Client on a Windows NT system. o Chapter 5 provides an overview of the BASEstar Open Manager and explains how to configure and manage the BASEstar Open Client environment on your Windows NT 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 an Digital UNIX system. o Chapter 9 describes how to remove BASEstar Open Client from an Digital UNIX system. o Chapter 10 describes the Graphic Configuration utility, available on Windows NT and MS Windows systems. o Chapter 11 provides a detailed explanation of the concept of DDE connectivity. o Appendix A provides information about the BASEstar Open Client environment variables on MS Windows and Windows NT systems. o Appendix B provides additional information about the BSTRCOM.CFG file, which contains the BASEstar Open Client communication configuration on MS Windows and Windows NT systems. o Appendix C lists the files and directories that reside on MS Windows and Windows NT 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. vi o Appendix E lists the files and directories that reside on a Digital UNIX system 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 - BASEstar CIMfast Guide to SQL Support o DEComni API: - DEComni API User Guide - DEComni API Guide to Using Omni Directory Services (for supported platforms) - DEComni API Guide to Using OmniView (for supported platforms) o Device Access Software documentation - Specific manuals for each supported device vii 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. . . . 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.) (continued on next page) viii Table_1_(Cont.)_Conventions_Used_in_BASEstar_Open________________ ( ) 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. 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. (continued on next page) ix Table_1_(Cont.)_Conventions_Used_in_BASEstar_Open________________ 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:_ÅÀÁÂÃÄÇÈÉÊËÌÍÎÏÒÓÔÕÖÙÚÛÜÆÑ@Øß._____ x 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 platform-specific 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 MS Windows Systems _________________________________________________________________ 2 _________________________________________________________________ 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. 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 for MS Windows on your MS Windows system and which may not be included in this guide. o Media Your kit contains one 1.44 Mbyte 3 1/2" disk. o Documentation Your kit includes this manual. 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 Appendix C for a list of files included in the BASEstar Open Client for MS Windows kit. 2-1 Installing BASEstar Open Client on an MS Windows System 2.2 Before You Begin 2.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 will find them in the root directory on the distribution diskette in the DOC\RELNOTES.TXT file. 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 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. 2.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. 2.2.4 Hardware Pre-requisites You can install BASEstar Open Client for MS Windows on a 386- or 486-class PC, or on a Digital Alpha PC. In each case, the PC requires 1.5 Mbytes of available disk space and must be capable of running MS Windows Version 3.1. 2-2 Installing BASEstar Open Client on an MS Windows System 2.2 Before You Begin 2.2.5 Software Pre-requisites You cannot install BASEstar Open Client for MS Windows until you have installed MS Windows Version 3.1. ________________________ 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 2.3 Unpacking the Kit The BASEstar Open Client for MS Windows kit is distributed as a set of compressed files (with extension .xx_). The distribution set contains the following files: o BSTR.DLL - Dynamic Link Library of BASEstar Open o BSTR.LIB - Import library for the previous DLL o BSTRI.LIB o Include files: - BSTROSD.H - BSTRPPB.H - BSTRMSG.H - BSTRMSGL.H - BSTRSTAT.H 2-3 Installing BASEstar Open Client on an MS Windows System 2.3 Unpacking the Kit - BSTR.H - BSTRPUB.H o BSTR_MSG.TXT - Message catalog o WATCHD16.EXE - Watchdog executable program 2.4 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 3. To start the installation procedure, run the SETUP.BAT file supplied with the BASEstar Open kit. 2.5 Error Recovery If problems occur during the installation, the system displays error messages. If an error occurs while using BASEstar Open Client and you believe the error is caused by a problem 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 find an error in the BASEstar Open Client documentation, fill out and submit one of the Reader's Comments forms at the back of the document containing the error. Include the section and page number where the error occurred. 2-4 Installing BASEstar Open Client on an MS Windows System 2.5 Error Recovery When 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 the BASEstar Open Client being used. 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. 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. 2-5 3 _________________________________________________________________ Configuring and Managing the BASEstar Open Environment on an MS Windows System This chapter describes how to configure and manage the BASEstar Open Client environment on your MS Windows personal computer. 3.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. 3.1.1 Nodes A BASEstar Open Client node is an MS Windows personal computer on which BASEstar Open Client has been 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 must be started before you can run a BASEstar Open Client for MS Windows application. Only one Watchdog is needed per PC, and it can manage connections to many Realms and many 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 Watchdog process has the following run-time limitations: o Applications can handle a maximum of four Realms concurrently. o You can activate a maximum of sixteen application processes for each Realm. 3-1 Configuring and Managing the BASEstar Open Environment on an MS Windows System 3.1 BASEstar Open Environment Components 3.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 3.2. 3.2 Setting Up a Realm To set up a Realm, follow these steps: 1. Exit MS Windows. 2. Ensure that the BSTRUSER.BAT command file has been executed to set all the installation-dependent environment variables. The file is located under the C:\BSTR030\INST\ETC directory. (See Appendix A for details.) 3. Execute the BSTREALM.EXE command from the command line by specifying the names of one or more Realms to be set up. This command file creates a series of Realm-specific internal directories. BSTREALM also calls the standard MS-DOS editor so that you can modify the communication configuration file, BSTR_WORK_ROOT%\WORK\NODE\COM\BSTRCOM.CFG. To modify the file, follow the guidelines in Section 3.3. To ensure that you save any corrections before leaving the editor, choose the Save option from the File menu, followed by the Exit option. 3-2 Configuring and Managing the BASEstar Open Environment on an MS Windows System 3.2 Setting Up a Realm For example, if you want to set up REALM1 and REALM2, enter the following commands (assuming that BASEstar Open Client is installed under the default installation directory): C:\> C:\BSTR030\INST\ETC\BSTRUSER C:\> BSTREALM REALM1 REALM2 C:\> 3.3 Using 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 automatically request the PC Communication Servers currently active for any Realm. For this reason, the BSTRCOM.CFG file consists of two sections which contain information on Name Service Servers or/and PC Communication Servers. Refer to Appendix B for more information on the sections of the BSTRFCOM.CFG file. BASEstar Open assumes that the pathname of the BSTRCOM.CFG file is as follows: %BSTR_WORK_ROOT%\NODE\COM\BSTRCOM.CFG If BASEstar Open is unable to find a definition for the BSTR_WORK_ROOT environment variable, it uses the following pathname: C:\BSTR030\WORK\NODE\COM\BSTRCOM.CFG 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. 3-3 Configuring and Managing the BASEstar Open Environment on an MS Windows System 3.3 Using the Communication Configuration File 3.3.1 Editing the Default Version of the 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. You can use an ASCII editor at any time to edit the default BSTRCOM.CFG file. 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 3.2. Figure 3-1 shows the contents of the default BSTRCOM.CFG communication configuration file provided by BASEstar Open Client. Figure 3-1 Default BSTRCOM.CFG File # # Default BSTRCOM.CFG file # # # Name Service Servers Section # [LNS SERVERS] BSTR host1 6101 BSTR host2 6000 One entry is specified for each of the Name Service Servers that is active on the server Node(s) in your BASEstar Open distributed environment. Therefore, there can be up to two entries: the first for the primary, and the second for the secondary Name Service Server copies. At run-time, the Watchdog handles these entries in the order in which they are listed in the BSTRCOM.CFG file. You must 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. 3-4 and Managing the BASEstar Open Environment on an MS Windows System 3.3 Using the Communication Configuration File 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. 3.4 Starting Up a Client Node Before an application can access BASEstar Open services, you must do the following: 1. Start the MS Windows Client Node. 2. Start the Watchdog by double clicking on the Watchdog icon in the BASEstar Open Client for MS Windows Program Group window. 3.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 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 on the Watchdog, refer to Section B.3. 3.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 3-5 Configuring and Managing the BASEstar Open Environment on an MS Windows System 3.6 Log Information _________________________________________________________________ Component_________Log_File_______________________________________ 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. 3-6 Windows NT Systems _________________________________________________________________ 4 _________________________________________________________________ Installing BASEstar Open Client on a Windows NT System This chapter describes the pre-installation and installation procedures for BASEstar Open Client on a Windows NT 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 on your Windows NT system and which may not be included in this guide. o Media Your kit contains one 1.44 Mbyte 3 1/2" disk. 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 prerequisite hardware and software has already been installed. Refer to Appendix C for a list of files included in the BASEstar Open Client for Windows NT kit. 4-1 Installing BASEstar Open Client on a Windows NT System 4.2 Before You Begin 4.2.1 Release Notes BASEstar Open Client for Windows NT provides online release notes when important information must be conveyed after the documentation is printed. If release notes are provided, you will find them in the root directory on the distribution diskette in the DOC\RELNOTES.TXT file. 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 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. 4.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 Windows NT documentation. 4.2.4 Hardware Pre-requisites You can install BASEstar Open Client for Windows NT on a 386-, a 486-, a Pentium-class PC, or a Digital Alpha PC. In each case, the PC requires 1.5 Mbytes of available disk space and must be capable of running Windows NT Version 3.5 or 3.51. 4-2 Installing BASEstar Open Client on a Windows NT System 4.2 Before You Begin 4.2.5 Software Pre-requisites You cannot install BASEstar Open Client for Windows NT until you have installed Windows NT Version 3.5 or 3.51. TCP/IP services are included in Windows NT Version 3.5 or 3.51 kit. The Windows NT installation procedure gives you the option of installing TCP/IP services as well. You cannot use BASEstar Open server until you have installed TCP/IP services. 4.3 Unpacking the Kit The BASEstar Open Client for Windows NT kit is distributed as a set of compressed files (with extension .xx_). A command file, INSTALL.BAT, is also included and can be used to start the installation process + The distribution set contains the following files: o BSTR.DLL - Dynamic Link Library of BASEstar Open o BSTR.LIB - Import library for the previous DLL o BSTRI.LIB o Include files: - BSTROSD.H - BSTRPPB.H - BSTRMSG.H - BSTRMSGL.H - BSTRSTAT.H - BSTR.H - BSTRPUB.H o BSTR_MSG.TXT - Message catalog o WATCHD16.EXE - Watchdog executable program ____________________ + You can also copy the kit distribution files to your own directory and then expand them using the Windows NT utility expand, as follows: # expand -r *.* your_dir 4-3 Installing BASEstar Open Client on a Windows NT System 4.4 Installation Procedure 4.4 Installation Procedure Use the procedure described in this section to install BASEstar Open Client for Windows NT for the first time, or to reinstall it on a system where a version already exists. You can install or reinstall the BASEstar Open Client for Windows NT kit safely without damaging site-specific configuration information. 4.4.1 Installing the BASEstar Open Client Kit To installation BASEstar Open Client on Windows NT, run the file INSTALL.BAT provided in the BASEstar Open Client for Windows NT kit. 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. 4-4 5 _________________________________________________________________ Configuring and Managing the BASEstar Open Client Environment on a Windows NT System This chapter describes how to manage the BASEstar Open Client environment on your Windows NT personal computer and configure your BASEstar Open Client Node and Realm. 5.1 BASEstar Open Environment Components On a Windows NT 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 a Windows NT personal computer on which BASEstar Open has been 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 must be started before you can run any BASEstar Open Client for Windows NT application. Only one Watchdog is needed per PC, and it can manage connections to many Realms and many PC Communication Servers active on various server nodes. The Watchdog continuously checks for abnormal termination of BASEstar Open for Windows NT applications. In the event of abnormal termination, it performs an orderly closure of the connection with the Realm PC Communication Server. The Watchdog process has the following run-time limitations: o A maximum of four Realms can be concurrently operated by the applications. o For each Realm, a maximum of 64 application processes can be activated. 5-1 Configuring and Managing the BASEstar Open Client Environment on a Windows NT 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 Windows NT. 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.2. 5.2 Setting Up a Realm To set up a Realm, follow these steps: o For the first Realm: 1. Create the Realm on the server Node. 2. When installing the BASEstar Open Client for Windows NT kit, specify in the installation command line the same Realm name originally used to create the Realm on the server Node. o Subsequent Realms If you need to create other Realms after installing the PC Client, you must create and set them up manually, using either the appropriate CLI commands or the File Manager. For more information about CLI commands, refer to the BASEstar Open Command Language Interface. 5-2 Configuring and Managing the BASEstar Open Client Environment on a Windows NT System 5.3 Using the Communication Configuration File 5.3 Using the Communication Configuration File The communication configuration file (BSTRCOM.CFG) contains information about the Realms defined by BASEstar Open Client for Windows NT applications, enabling BASEstar Open to: o Establish TCP connections with the PC Communication Servers running on server Nodes of a Realm. These connections allow Windows NT 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 automatically request the PC Communication Servers currently active for any Realm. For this reason, the file BSTRCOM.CFG is composed of two sections which contain information on Name Service Servers or/and PC Communication Servers. Refer to Appendix B for more information on the sections of the BSTRFCOM.CFG file. BASEstar Open assumes that the pathname of the BSTRCOM.CFG file is as follows: %BSTR_WORK_ROOT%\NODE\COM\BSTRCOM.CFG If BASEstar Open is unable to find a definition for the BSTR_WORK_ROOT environment variable, it uses the following pathname: C:\BSTR030\WORK\NODE\COM\BSTRCOM.CFG 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-3 Configuring and Managing the BASEstar Open Client Environment on a Windows NT System 5.3 Using the Communication Configuration File 5.3.1 Editing the Default Version The default BSTRCOM.CFG file directs the Watchdog to select a PC Communication Server dynamically, choosing it at run- time from among those available. If it is a requirement that your Windows NT client Node uses specific PC Communication Server(s), you must add the relevant entries to your BSTRCOM.CFG file, as explained in Appendix B. You can use an ASCII editor at any time to edit the default BSTRCOM.CFG file. You do not need to reboot the system in order to make the changes operational. Remember that before Windows NT allows applications to operate in a given Realm, you must first set up that Realm following the instructions given in Section 5.2. Figure 5-1 shows the contents of the default BSTRCOM.CFG communication configuration file provided by BASEstar Open. Figure 5-1 Default BSTRCOM.CFG File # # Default BSTRCOM.CFG file # # # Name Service Servers Section # [LNS SERVERS] BSTR host1 6101 BSTR host2 6000 One entry is specified for each of the Name Service Servers that is active on the server Node(s) in your BASEstar Open distributed environment. Therefore, there can be up to two entries: the first for the primary and the second for the secondary Name Service Server copies. At run-time, the Watchdog handles these entries in the order in which they are listed in the BSTRCOM.CFG file. 5-4 and Managing the BASEstar Open Client Environment on a Windows NT System 5.3 Using the Communication Configuration File You must 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 must be found 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. 5.4 Starting Up a Client Node Before an application can access BASEstar Open services, you must do the following: 1. Start the Windows NT Client Node. 2. Start the Watchdog, in one of the following ways: o Run the Watchdog as a Windows NT Service using the Windows NT Services control panel. o Double click on the Watchdog icon in the BASEstar Open Client Program Group. o Type the following command line to run the Watchdog in foreground mode: # watchd32 o Type the following command line to run the Watchdog in background mode: # start watchd32 5.4.1 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. When you exit Windows NT, BASEstar Open shuts the Watchdog down in an orderly fashion. 5-5 Configuring and Managing the BASEstar Open Client Environment on a Windows NT System 5.5 Log Information 5.5 Log Information The log service is based on the Windows NT log facility. To access it, use the Windows NT Event Viewer. The log of the PC client is located under the APPLICATION option of the menu. The log message selectors are: o BASEstar Open Watchdog for the Watchdog o BASEstar Open DLL for DLL operations To increase the level of detail in the log messages, set the environment variable BSTR_DEBUG_TRACE to a numeric value, as follows: # set BSTR_DEBUG_TRACE=1 5-6 and Managing the BASEstar Open Client Environment on a Windows NT System 5.6 The BASEstar Open Manager Utility 5.6 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 5-2. Figure 5-2 BASEstar Open Manager Window 5.6.1 Configuring BASEstar Open Nodes and Realms You must 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 only makes provision for a single (default) Realm. However, you can register primary and secondary LNS server Nodes; this redundancy mechanism ensures access to the BASEstar Open environment if the primary LNS server node is unavailable for any reason. 5-7 Configuring and Managing the BASEstar Open Client Environment on a Windows NT System 5.6 The BASEstar Open Manager Utility Note that modifications to the default settings only take effect from the next Node Start operation. 5.6.1.1 Setting up the Default Realm Default_realm is the only Realm currently supported by BASEstar Open Client on Windows NT. To modify this default setting, pull down the Tools menu in the BASEstar Open Manager window and choose the Realm Setup option from the submenu. BASEstar Open Client displays the Default Realm Setup dialog box in Figure 5-3. Figure 5-3 Default Realm Setup Dialog Box Click in the Default REALM Name box and type a name for the default Realm. Click in the other box and specify the number of PC server instances to be started at Realm startup time. 5-8 and Managing the BASEstar Open Client Environment on a Windows NT System 5.6 The BASEstar Open Manager Utility 5.6.1.2 Setting up the LNS Server Node(s) To configure the LNS server Node(s), pull down the Tools menu in the BASEstar Open Manager window and choose the Node Setup option from the submenu. BASEstar Open Client displays the LNS Setup dialog box in Figure 5-4. Figure 5-4 LNS Setup Dialog Box To activate the primary LNS server on your local host, click on the Yes button in the Local Only portion of the dialog box. BASEstar Open Client confirms that the local host is the primary LNS server. If you wish to specify primary and secondary LNS servers, click on the No button in the Local Only portion of the dialog box. Type entries for Primary LNS Server and Secondary LNS Server in the respective fields (BASEstar Open Client does not allow you to specify the same Node name for each entry). 5-9 Configuring and Managing the BASEstar Open Client Environment on a Windows NT System 5.6 The BASEstar Open Manager Utility The LNS Server/s Check option in the Tools menu displays the dialog box illustrated in Figure 5-5, containing summary information regarding the status of the LNS server(s). To obtain an update of the current status of each server, click on the ACCESS SERVER/s button. Figure 5-5 LNS Server/s Check Dialog Box To generate a file containing all setup data stored in the Windows NT registry database, pull down the Dump Setup to File option. By default, BASEstar Open Client calls the file BSTREGD.TXT and stores it in the bin directory of the BASEstar Open tree. 5.6.1.3 Configuring BASEstar Open Autostart The Autostart function allows you to start up your Node and Realm automatically each time you boot the system. You can also request the BASEstar Open Manager to execute selected commands before and/or after rebooting. To enable/disable the automatic startup of your BASEstar Open Node and Realm on booting the system, pull down the Autostart Setup option in the BASEstar Open Setup menu. Click on the YES/NO button. 5-10 Configuring and Managing the BASEstar Open Client Environment on a Windows NT System 5.6 The BASEstar Open Manager Utility To specify the commands that you want BASEstar Open to execute before startup, create a file called BSTRINI1.BAT in the bstr\work directory. You might wish to specify commands for preparing your BASEstar Open environment in this file. Likewise, you can specify a series of commands for BASEstar Open to execute after startup, by creating a file called BSTRINI2.BAT in the bstr\work directory. At run-time, BASEstar Open: o Checks whether the bstr\work directory contains a file called BSTRINI1.BAT. If this is the case, it executes all the commands in the file. o Starts up your BASEstar Open Node and Realm. o Checks whether the bstr\work directory contains a file called BSTRINI2.BAT. If this is the case, it executes all the commands in the file. Click in the Autostart timeout (in minutes) box and enter the timeout interval for the Autostart procedure. If the automatic startup takes longer than the time specified, the BASEstar Open Manager terminates the startup automatically. The default timeout value is 30 minutes. 5.6.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 Tool Bar option is an ON/OFF item. Select this option to display/hide the tool bar underneath the menu bar of the console window, containing the , and buttons. You can use these buttons as an alternative to the options in the File menu. 5-11 Configuring and Managing the BASEstar Open Client Environment on a Windows NT System 5.6 The BASEstar Open Manager Utility 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 Windows NT registry database when you exit from the 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 the BASEstar Open tree. o Select Save Settings Now to save all current parameter settings in the Windows NT 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 messages are displayed in the console window. 5-12 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 preinstallation 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 for UNIX 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/bstclnt300/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 BSTCLNT300. 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 Requirements 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 Requirements To run BASEstar Open Client on an Digital UNIX system, you need Digital UNIX Version 3.2 (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 BSTCLNT300 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/bstclnt300 /usr/var/opt/bstclnt300 If the bstclnt300 directory node in the previous paths does not exist, the installation procedure creates it. If the bstclnt300 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. Appendix E lists the files and directories created during the installation procedure. 6.8 Error Recovery If errors occur during the installation, the system displays failure messages. If the installation fails due to insufficient disk space, a message appears. For example, if the disk space lack is detected while installing the BSTCLNT300, the following message is displayed: There is not enough file system space for subset BSTCLNT300 BASEstar Open Client (BSTCLNT300) will not be loaded. Errors may occur during the 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 error messages generated by these conditions, see the Digital UNIX documentation on system messages, recovery procedures, and Digital UNIX software installation. For information on system software requirements, see Section 6.5.3. If an error occurs while using BASEstar Open Client and you believe the error is caused by a problem with the product, take the appropriate action described in 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. 1996. 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.0 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.0 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.0 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.0 files is completed. 7-3 8 _________________________________________________________________ Configuring and Managing the BASEstar Open Client Environment 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 Reporting Errors If an error occurs while you are using BASEstar Open Client, and you believe the error is caused by a problem with the product, take the following steps: 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, submit a Software Performance Report (SPR). o If you purchased BASEstar Open Client less than 90 days previously, and you think the problem was caused by a software error, you can submit an SPR. If you find an error in the BASEstar Open Client documentation, fill out and submit one of the Reader's Comments forms at the back of the document containing the error. Specify the section and page number where the error occurred. 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 a description and version number of the BASEstar Open Client software being used. Demonstrate the problem with specific examples. 8-1 Configuring and Managing the BASEstar Open Client Environment on a Digital UNIX System 8.1 Reporting Errors 2. Reduce the problem to as small a size as possible. 3. Remember to include listings of any command files, INCLUDE files, or 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, 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. 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: # csh # source /etc/bstrclusers.csh # bstrcl_setup [-v] @@@ Using default kit_location: /usr/opt/bstclnt300 do you want to setup the kit installed in /usr/opt/bstclnt300? [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 Managing the BASEstar Open Client Environment 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 ypu 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/bstclnt300/etc/../spool_root] @@@ creating shell config file: /usr/opt/bstclnt300/etc/BSTRCOM_ayrton.mln.dec.com.CFG ... @@@ creating shell setup file: /usr/opt/bstclnt300/etc/bstrclusers.sh ... @@@ creating shell setup file: /usr/opt/bstclnt300/etc/bstrclusers.sh.h_ayrton.mln.dec.com ... @@@ creating c-shell setup file: /usr/opt/bstclnt300/etc/bstrclusers.csh ... @@@ creating c-shell setup file: /usr/opt/bstclnt300/etc/bstrclusers.csh.h_ayrton.mln.dec.com ... @@@ Setup successfully performed. The node has been configured. 8-3 Configuring and Managing the BASEstar Open Client Environment 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 Managing the BASEstar Open Client Environment 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 BSTCLNT300 9-1 PC-specific Utilities Section _________________________________________________________________ This section contains information relevant to MS Windows and Windows NT platforms only. 10 _________________________________________________________________ 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. ______________________________________________________ 10.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. 10-1 Introduction to the Graphic Configuration Utility (GCU) 10.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. 10.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. 10.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. 10.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 ____________________ [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. 10-2 Introduction to the Graphic Configuration Utility (GCU) 10.1 The Graphical Interface 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 10.1.3. 10.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 10-1 summarizes these rules. 10-3 Introduction to the Graphic Configuration Utility (GCU) 10.1 The Graphical Interface Table 10-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_Message X VMD_Named_Variable X VMD_Unnamed_Variable X VMD_Polling_Set X Node X Array_Data_Type X Structure_Data_Type X Protocol_Profile X VMD_Extension_ X Parameter__________________________________________________ For information regarding the use of the mouse in connection with objects displayed in the right-hand window, refer to Section 10.1.3. 10-4 Introduction to the Graphic Configuration Utility (GCU) 10.1 The Graphical Interface 10.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. 10.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 10-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 10.1.3.4. 10-5 Introduction to the Graphic Configuration Utility (GCU) 10.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 10.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. 10.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 10-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 10-6 Introduction to the Graphic Configuration Utility (GCU) 10.1 The Graphical Interface o Trigger 10.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 Actor o Activity o Data_Point o Device_Data_Point o Node o Program 10.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 10-7 Introduction to the Graphic Configuration Utility (GCU) 10.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. 10.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 10-2 lists the attributes that may be displayed, depending on the BASEstar Open object and attribute in question. 10-8 Introduction to the Graphic Configuration Utility (GCU) 10.1 The Graphical Interface Table_10-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______________ 10-9 11 _________________________________________________________________ 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 or Windows NT 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 or Windows NT 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 or Windows NT applications o Read unsolicited data values from MS Windows or Windows NT applications o Write data for MS Windows or Windows NT applications. 11-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 behave in turn as a DDE server and as a DDE client. The client initiates the communication and tells the server which data values it needs to: o Read o Receive unsolicited o Write. Figure 11-1 illustrates a bridge between BASEstar Open servers and DDE applications. From the BASEstar Open viewpoint, the bridge is a client application which uses the BASEstar Open public API to get Event notifications, and read and write Data_Point values; on the DDE side, the bridge uses the public API DDE Management Library (as defined by Microsoft). 11-2 BASEstar Open DDE Connectivity Figure 11-1 Exchanging Data Between BASEstar Open Servers and DDE Applications In order to behave as a DDE client, the bridge needs some kind of 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. No configuration information is necessary for it to behave as a DDE server, because in this case the partner DDE client is responsible for sending it through the standard DDE Application|Topic!Item string. The bridge can handle the connection with any kind of DDE-compliant application, including third party DASes that should become available, but is mainly designed to exchange data with personal productivity tools, such as spreadsheets. 11-3 BASEstar Open DDE Connectivity 11.1 Using the DDE Bridge 11.1 Using the DDE Bridge You can access the BASEstar Open DDE Bridge by means of an icon in the window of the BASEstar Open Client Program Group; to activate it, double click on the icon. By default, the bridge behaves as a DDE server, and waits for clients to initiate the data exchange. You can alter this behaviour by configuring it to act as a client. By changing the invocation command in the Properties dialog box of the File menu of the Program Manager, you can customize the DDE Bridge so that it makes better use of BASEstar Open resources. The syntax of the command is: bstrdde [switches] where bstrdde is the bridge-executable image. The possible switches are: o -e enbox_name Defines the name of the Enbox to be used by 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 Selects the BASEstar Open Domain in which the DDE Bridge will operate. The default Domain is "/" (the father of all the domains). o -f filename Tells the DDE Bridge from which file to load the configuration information needed to behave as a DDE client. There is no default setting: if you omit this switch, the bridge initially behaves as a DDE server. However, you can load the configuration information after starting the bridge. The configuration file is an ASCII file containing a series of lines with the following syntax: