BASEstar Open Device Connectivity DASware User Guide Order Number: AA-QT1HB-TE March 1997 This document describes DASware, the Device Access Software (DAS) that allow BASEstar Open users and DEComni API applications to exchange data with partner applications in a protocol-independent way through the most commonly-used transport networks. This manual also describes the procedures to install and use DASware in the BASEstar Open and DEComni API environments. Revision/Update Information: Revision/Update Information: Revision/Update Information: This is a new document for the current release. Operating System and Version Operating System and Version Operating System and Version: BASEstar Open is available on a broad range of both hardware and software platforms. Refer to your Software Product Description for precise information. Software Version: Software Version: Software Version: Version 3.1 Digital Equipment Corporation Digital Equipment Corporation Digital Equipment Corporation Maynard, Massachusetts Maynard, Massachusetts Maynard, Massachusetts First Printing, February 1996 First Printing, February 1996 First Printing, February 1996 Revised, September 1996 Revised, September 1996 Revised, September 1996 Revised, March 1997 Revised, March 1997 Revised, March 1997 c Digital Equipment Corporation 1997. All Rights Reserved. Possession, use, or copying of the software described in this documentation is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor. Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: Alpha AXP, BASEstar Open, 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: MS, Microsoft, and MS-DOS are registered trademarks of Microsoft Corporation. UNIX is a registered trademark licensed exclusively by X/Open Company Ltd. Windows and Windows NT are trademarks of Microsoft Corporation. All other trademarks and registered trademarks are the property of their respective holders. Table of Contents Table of Contents Table of Contents Preface Preface Preface ................................ ................................ .................................................... .................... ....................vii vii vii 1 Introduction 1 Introduction 1 Introduction ................................ ................................ ............................................. ............. ............. 1 1 1 - - - 1 1 1 What is DASware?........................................ 1 1- Transport Networks and Platforms Supported by DASware... 2 - 1 What's Next?............................................ 2 - 1 2 Installing DASware on Your Platform 2 Installing DASware on Your Platform 2 Installing DASware on Your Platform ..................... ..................... ..................... 1 1 1 2 2 2- - - Installation on DIGITAL UNIX Systems.................... 2 - 2 Preparing for DASware Installation ................... 2 - 2 Installing DASware ................................... 6 - 2 Deinstalling DASware ................................ 6 - 2 . Files Installed on Your System ....................... 8 - 2 Getting Help and Reporting Problems .................. 8 2- Installation on OpenVMS Systems........................ 10 - 2 Preparing for DASware Installation .................. 10 - 2 Files Installed on Your System ...................... 12 - 2 Getting Help and Reporting Problems ................. 12 - 2 Installation on Windows NT Systems..................... 14 - 2 Preparing for DASware Installation .................. 14 - 2 Installing DASware .................................. 15 - 2 Deinstalling DASware ................................ 15 - 2 Getting Help and Reporting Problems .................2 15 - Installation on HP-UX Systems.......................... 17 2- Preparing for DASware Installation ..................2 17 - Files Installed on Your System ...................... -18 2 Getting Help and Reporting Problems .................2 19 - PART I Using BASEstar Open to Exchange Data Via Transport PART I Using BASEstar Open to Exchange Data Via Transport PART I Using BASEstar Open to Exchange Data Via Transport Networks Networks Networks 3 Overview 3 Overview 3 Overview ................................ ................................ ................................................. ................. ................. 1 1 1 - - - 3 3 3 BASEstar Open Environment Components.................... -2 3 Exchanging Data Through a Transport Network............. -4 3 Sending Data .........................................3-4 Receiving Data .......................................3 6 - Encoding and Decoding Transport Network Data ......... -9 3 iii 4 Configuring BASEstar Open 4 Configuring BASEstar Open 4 Configuring BASEstar Open ................................ ................................ ................................4 4 4 1 1 1 - - - Registering ODS Entries ................................ 4 . 2 - Creating Application Services Objects ...................4-2 Creating Device Services Objects ........................4 2 - Creating Protocol_Profiles ...........................4 2 - Creating VMDs ................................ 4 ........ -3 Creating Variables ................................ 4 ... 5 - Creating Data Services Objects ..........................4 6 - Creating Device_Data_Points for Receive Operations 4 ... 6 - Creating Device_Data_Points for Send Operations 4 ...... 7 - 5 A Complete Example 5 A Complete Example 5 A Complete Example ................................ ................................ ................................ 5 5 5 ....... ....... ....... 1 1 1 - - - Example Overview ........................................5 2 - Before Running the Example ..............................5 2 - CLI Source ..............................................5 4 - Exchanging Data Through the Transport Network ...........5 6 - PART II Using DEComni API to Exchange Data Via Transport PART II Using DEComni API to Exchange Data Via Transport PART II Using DEComni API to Exchange Data Via Transport Networks Networks Networks 6 Overview 6 Overview 6 Overview ................................ ................................ ................................................. ................. .................6 6 6 1 1 1 - - - DEComni API Environment Components ......................6 2 - Exchanging Data Through the Transport Network ...........6 5 - Writing Data Through the Transport Network ...........6 5 - Receiving Data from the Transport Network ............6 6 - Encoding and Decoding Transport Network Data 6 ......... 9 - 7 Configuring DEComni API 7 Configuring DEComni API 7 Configuring DEComni API ................................ ................................ ................................ 7 7 7 .. .. .. 1 1 1 - - - Registering ODS Entries ................................ 7 . 2 - Setting the Application Profile .........................7 2 - Creating VMD Definitions ................................7 2 - Creating Variable Definitions ...........................7-3 8 Programming 8 Programming 8 Programming ................................ ................................ .............................................. .............. ..............8 8 8- - -1 1 1 DEComni API Procedures for Data Exchange ................8-2 Opening and Closing a Transport Network Connection ......8 2 - Sending Data Through the Transport Network ..............8 3 - Receiving Data from the Transport Network ...............8-3 PART III Appendices PART III Appendices PART III Appendices A ODS Entry Attributes for DASware A ODS Entry Attributes for DASware A ODS Entry Attributes for DASware ......................... ......................... .........................A A A 1 1 1 - - - Creating ODS Entries for the RS 232 Transport Network A .... -1 Through Direct Connection or LAT ......................A 1 - Through Telnet ................................ A ........ -4 Creating ODS Entries for the TCP/IP Transport Network ....A 6 - Creating ODS Entries for the OSI Transport Network A ....... -7 iv B Configuring DASware OSI Transport Services on an HP-UX System B Configuring DASware OSI Transport Services on an HP-UX System B Configuring DASware OSI Transport Services on an HP-UX SystemB B B- - -1 1 1 Configuring OTS/9000 Software............................ 1 B- Obtaining Ethernet Card Information ................... 1 - B Configuring the OSI Transport for an 802.3 LAN (Null Internet Option) ...................................... 3 - B Configuring the OSI Transport for an 802.3 LAN (Full Internet Option) ...................................... 5 - B Configuring the OSI Transport for Running the IVP ..... 6 B- Figures Figures Figures Figure 1-1: Communicating Via a Transport Network........ 2 - 1 Figure 3-1: BASEstar Open Environment Components......... 2 - 3 Figure 3-2: BASEstar Open Objects and Operations......... 4 - 3 Figure 6-1: DEComni API Environment Components........... 2 - 6 Figure 6-2: DEComni API Definitions and Procedures....... 5 - 6 Tables Tables Tables Table 1-1: Available Platforms and DASware Modules....... 2 1- Table 2-1: DASware Subsets (DIGITAL UNIX Platform)....... 2 - 2 Table 2-2: Pre-requisite Software for DIGITAL UNIX (BASEstar Open Environment)........................................ 3 - 2 Table 2-3: Pre-requisite Software for DIGITAL UNIX (DEComni API Environment)......................................... 4 - 2 Table 2-4: Transport Network Software (DIGITAL UNIX Platform)................................................ 4 - 2 Table 2-5: Pre-requisite Software for OpenVMS (BASEstar Open Environment)............................................ 10 - 2 Table 2-6: Transport Network Software (OpenVMS Platform) 11 2- Table 2-7: Pre-requisite Software for Windows NT (BASEstar Open Environment)....................................... 14 - 2 Table 2-8: Transport Network Software (Windows NT Platform) 15 - 2 Table 2-9: Transport Network Software (HP-UX Platform).. 17 2- Table 3-1: Protocol-Specific Information Added to Outgoing Encoded Data (BASEstar Open)............................. 5 - 3 Table 3-2: Protocol-Specific Information Removed from Incoming Data (BASEstar Open)............................ -7 3 Table 3-3: Coding and Decoding Data by Datatype (BASEstar Open)....................................................3 9 - Table 4-1: Protocol_Profile Attributes (BASEstar Open)... - 4 3 Table 4-2: VMD Attributes (BASEstar Open)................ - 4 4 Table 4-3: Device Services Reception Variable Attributes (BASEstar Open).......................................... - 4 5 Table 4-4: Device Services Transmission Variable Attributes - 4 6 Table 4-5: Device_Data_Point Attributes for Receive Operations (BASEstar Open)............................... - 4 7 Table 4-6: Device_Data_Point Attributes for Send Operations4-7 Table 6-1: Protocol-Specific Information Added to Outgoing Encoded Data (DEComni API)............................... -6 6 Table 6-2: Protocol-Specific Information Removed from Incoming Data (DEComni API).............................. -8 6 Table 6-3: Coding/Decoding Data According to MMS Types (DEComni API)............................................ -9 6 v Table 7-1: DEComni API Application Profiles for DAS Modules7-2 Table 7-2: VMD Attributes (DEComni API) ..................7 2 - Table 7-3: Variable Attributes (DEComni API) .............7 3 - Table 8-1: DEComni API Procedures for Data Exchange 8 ...... 2 - Examples Examples Examples Example 4 1: Creating Protocol_Profile Objects (BASEstar - ................................ Open) ....................4 3 - Example 4-2: Creating VMD Objects (BASEstar Open) 4 ........ 4 - Example 5 Creating BASEstar Open Objects 1: - ..............5 4 - Example 5 2: Exchanging Data Through the Transport Network - 5 6 - Example A 1: ODS Entries for RS 232 Direct Connection and - LAT ......................................................A 2 - Example A-2: ODS Entries for RS 232 Telnet ...............A 5 - Example A-3: ODS Entries for TCP/IP ......................A 6 - Example A 4: ODS Entries for the OSI Transport Network - A ... -7 vi Preface Preface Preface This manual describes how to install and use DASware, the DIGITAL Device Access Software (DAS) that allows BASEstar Open users and DEComni API applications to exchange data with partner applications in a protocol-independent way through the most commonly used transport networks. Multiplatform Applicability Multiplatform Applicability Multiplatform Applicability Most of the information in this manual applies regardless of the operating system platform on which the DASware software is installed. Information relating to installation is typically platform- dependent. Note: Note: Note: Throughout this document, all references to UNIX systems apply collectively to both DIGITAL UNIX and HP-UX. Intended Audience Intended Audience Intended Audience This manual is addressed to: System managers who have to install and maintain DASware on any of the supported platforms. Application developers who have to configure and use BASEstar Open, or the DEComni API (or both) to exchange data through the transport networks supported by the DASware modules. Structure of this Document Structure of this Document Structure of this Document This document is organized as follows: Chapter 1 introduces you to DASware; Chapter 2 contains the installation procedures. Part I describes the environment components that are involved when DASware is accessed using vii vii vii BASEstar Open. It also describes how you can exchange data through the supported transport networks, and how you must configure BASEstar Open. A complete example is also provided. Part II describes the environment components that are involved when DASware is accessed using the DEComni API. It also describes how you can exchange data through the supported transport networks, and how you must configure the DEComni API. Part III contains the appendices. viii viii viii For More Information For More Information For More Information If you are using BASEstar Open services you will find related information in the following documents: BASEstar Open Introduction BASEstar Open Reference Guide BASEstar Open Command Language Interface BASEstar Open Application Programming Interface BASEstar Open Messages Platform-specific management guides If you are using DEComni API, you will find related information in the following documents: DEComni API and DEComni MMS User Guide DEComni API Guide to Using Omni Directory ix 1 1 1 Introduction Introduction Introduction This chapter provides you with an overview of DASware and of its main features. What is DASware? What is DASware? What is DASware? DASware is a DIGITAL product that allows both BASEstar Open users and DEComni API applications to exchange data with partner applications and devices in a protocol-independent way, through any of the supported transport networks. Both BASEstar Open and the DEComni API offer generic device and network access, which is independent of the specific operations and protocols. This is possible because, for each supported protocol or device, there is a Device Access Software (DAS) Device Access Software (DAS) Device Access Software (DAS) module that matches device- and protocol-specific characteristics into standardized BASEstar Open services or DEComni API calls. DASware is a set of modules that allow both BASEstar Open users and DEComni API applications to exchange data with partner applications and devices in a protocol-independent way, through the following transport networks: RS 232 TCP/IP OSI Transport (ISO 8072) DASware User Guide 1 1 1 - - - 1 1 1 Introduction Figure Figure Figure 1 1 1 1 1 1: Communicating Via a Transport Network : Communicating Via a Transport Network : Communicating Via a Transport Network - - - BASEstar Open users can send and receive data through the supported transport networks, simply by reading and writing the values of Device_Data_Points. Similarly, DEComni applications use DEComni API procedures to exchange data. However, DEComni API is only supported on OpenVMS and DIGITAL UNIX platforms. Transport Networks and Platforms Supported by DASware Transport Networks and Platforms Supported by DASware Transport Networks and Platforms Supported by DASware Table 1-1 lists the DASware modules available on different platforms, which DAS modules are available and thus, which transport network can be used to exchange data through. Table Table Table 1 1 1: Available Platforms and DASware Modules : Available Platforms and DASware Modules : Available Platforms and DASware Modules - - - 1 1 1 Platform Platform Platform Available DASware Modules Available DASware Modules Available DASware Modules OpenVMS RS 232, TCP/IP, and OSI Transport Layer (ISO 8072) UNIX RS 232, TCP/IP, and OSI Transport Layer (ISO 8072) Windows NT RS 232, and TCP/IP When installing DASware on a given platform, a DASware module is installed for each of the supported transport networks. What's Next? What's Next? What's Next? In this chapter you have learnt about the main features of DASware. If you intend to use DASware through BASEstar Open services, first read Chapter 2 to know how to install DASware on your system, and then read Part I of this 1 1 1 2 2 2 - - - DASware User Guide Introduction manual to know how you must configure BASEstar Open and use its services to exchange data through the desired transport network(s). If you intend to use DASware through the DEComni API, first read Chapter 2 to know how to install DASware on your system, and then read Part II of this manual to know how you must configure the DEComni API and use the API procedures to exchange data through the desired transport network(s). 3 - 1 2 2 2 Installing DASware on Your Platform Installing DASware on Your Platform Installing DASware on Your Platform This chapter specifies the requirements and the procedures for installing DASware on the following platforms: DIGITAL UNIX OpenVMS Windows NT HP-UX For each platform, a list is also provided of the packages and software components that you must install in order to make available the desired transport network(s) on your system. This chapter provides the instructions for installing DASware in the BASEstar Open and DEComni API environments. DASware User Guide 2 2 2 - - -1 1 1 Installing DASware on Your Platform Installation on DIGITAL UNIX Systems Installation on DIGITAL UNIX Systems Installation on DIGITAL UNIX Systems On DIGITAL UNIX systems, DASware is installed optionally as part of the DEComni API V3.1 installation procedure. You can either install DEComni API V3.1 as a separate product, or install it during the BASEstar Open V3.1installation procedure. Preparing for DASware Installation Preparing for DASware Installation Preparing for DASware Installation Before starting the installation procedure you should complete the preparation requirements outlined in this section. Requirements vary according to whether you are installing DASware for use via BASEstar Open services or via the DEComni API. Table 2-1 lists the subsets included in the DASware software product. Note that a subset is provided for each of the transport networks supported on the DIGITAL UNIX platform. Table Table Table : DASware Subsets (DIGITAL UNIX Platform) : DASware Subsets (DIGITAL UNIX Platform) : DASware Subsets (DIGITAL UNIX Platform) - - -1 1 1 2 2 2 DASware Module DASware Module DASware Module Subset Name Subset Name Subset Name RS232 DASTK232310 TCP/IP DASTKTCP310 OSI Transport DASTKOSI310 License Registration License Registration License Registration DASware 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 DASware 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 DASware as an update on a node already licensed for this software, you have already completed the License PAK registration requirements. If you are installing prerequisite or optional software along with DASware, review the PAK status and install the PAKs for any prerequisite or optional software before you install DASware. To register a license under the DIGITAL UNIX system, first log in as superuser. 2 2 2- - -2 2 2 DASware User Guide Installing DASware on Your Platform You then have a choice of two ways to perform the PAK registration in the License Database (LDB): Before installing DASware 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 After installing DASware At the superuser prompt, edit the partially completed PAK template in /usr/var/adm/lmf/template with the lmf register command to add your unique License PAK information as follows: # lmf register - < /usr/var/adm/lmf/DASWARE-RUN 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 complete information on using the DIGITAL UNIX License Management Facility, see the DIGITAL UNIX Guide to Software Licensing or the lmf(8) reference page. Software Requirements (BASEstar Open Environment) Software Requirements (BASEstar Open Environment) Software Requirements (BASEstar Open Environment) If you are installing DASware in the BASEstar Open environment, check that the subsets listed in Table have been installed on your system. 2-2 Table Table Table - - - 2 2 2 : Pre-requisite Software for DIGITAL UNIX : Pre-requisite Software for DIGITAL UNIX : Pre-requisite Software for DIGITAL UNIX 2 2 2 (BASEstar Open Environment) (BASEstar Open Environment) (BASEstar Open Environment) Subset Name and Subset Name and Subset Name and Comments Comments Comments Description Description Description BSTR310 Ensure that the BASEstar BASEstar Open Server Open Device Connectivity for DIGITAL UNIX (DEComni) has been Version 3.1 installed. In particular, check for the presence of the following subsets: DOUBASE310 DASware User Guide 2 2 2 3 3 3 - - - Installing DASware on Your Platform DASTK232310 DASTKRUN310 See the BASEstar Open Server Inst. & Management Guide for your platform for details. Software Requirements (DEComni API Environment) Software Requirements (DEComni API Environment) Software Requirements (DEComni API Environment) Check that the software products listed in Table 2-3 have been installed on your system. Table Table Table : Pre-requisite Software for DIGITAL UNIX : Pre-requisite Software for DIGITAL UNIX : Pre-requisite Software for DIGITAL UNIX 3 3 3 - - - 2 2 2 (DEComni API Environment) (DEComni API Environment) (DEComni API Environment) Subset Name and Subset Name and Subset Name and Comments Comments Comments Description Description Description DOUBASE310 In particular, check for the DEComni API for DIGITAL presence of the following UNIX Version 3.1 subsets: DASTK232310 DASTKRUN310 See the DEComni API Installation Guide for your platform for details. Transport Network Software Transport Network Software Transport Network Software You must also ensure that the appropriate transport network software have been installed and configured. Table 2-4 specifies the necessary transport network software for each supported transport network. Table Table Table : Transport Network Software (DIGITAL UNIX : Transport Network Software (DIGITAL UNIX : Transport Network Software (DIGITAL UNIX - - -4 4 4 2 2 2 Platform) Platform) Platform) Transport Transport Transport Transport Network Software Transport Network Software Transport Network Software Network Network Network RS232 The OSFLAT subset is required if LAT is used. The OSFLAT and OSFNET subsets are required if Telnet is used (the capability for communicating via serial ports is embedded in the operating system). TCP/IP The OSFCLINET and OSFINET subsets 2 2 2- - - 4 4 4 DASware User Guide Installing DASware on Your Platform are required. OSI Transport The DNABASE and DNAPGMR subsets are required. DASware User Guide - - - 2 2 2 5 5 5 Installing DASware on Your Platform Disk Space Requirements Disk Space Requirements Disk Space Requirements The table that follows lists the disk space required to install and run each DASware module. Usage (Kbytes) Usage (Kbytes) Usage (Kbytes) (root) (root) (root) /usr/opt /usr/opt /usr/opt /var/opt /var/opt /var/opt Installation 0 8000 2000 Permanent 0 8000 2000 Backing Up Your System Disk Backing Up Your System Disk 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 DIGITAL UNIX documentation. Installing DASware Installing DASware Installing DASware Installing DASware and running the Installation and Verification Procedure (IVP) on your DIGITAL UNIX system takes approximately 5 to 10 minutes. Install DASware as follows: 1.Log onto the system as superuser (root). 2.Mount the distribution media on the desired location (for example, -dr /dev/rz4c /CDROM mount ). 3.Change your working directory to the kit location (for example, cd /CDROM/DASTKRUN310). 4.Issue the command to load the product setld -l onto the system, and follow the installation dialogs. Running the IVP Running the IVP Running the IVP During the installation procedure, you can run the IVP as part of the installation. If you do not run the IVP at that time, or if the product does not work correctly, you can run the IVP at any time by executing the following command: setld -v DASTKRUN310 Deinstalling DASware Deinstalling DASware Deinstalling DASware Deinstall DASware as follows: 1.Log onto the system as superuser (root). 2 2 2 DASware User Guide 6 6 6 - - - Installing DASware on Your Platform 2. Change your working directory to the kit location (for example, cd /CDROM/DASTKRUN310). 3. Issue the setld -d command: setld -d DASTKRUN310 setld -d DASTK232310 setld -d DASTKTCP310 setld -d DASTKOSI310 DASware User Guide 2 2 2- - - 7 7 7 Installing DASware on Your Platform Files Installed on Your System Files Installed on Your System Files Installed on Your System This section lists the directories and files created by DASware. /usr/opt/dastk_310/include: omni_integrator16_defs_include.h /usr/opt/dastk_310/lib: dastk_232init.o dastk_tcpinit.o libdastk.a libdastkosi.a dastk_osiinit.o dastksts.cat libdastk232.a libdastktcp.a libdastkx25.a /usr/opt/dastk_310/shlib: libdastk.so libdastk232.so libdastkosi.so libdastktcp.so libdastkx25.so /var/opt/dastk_310/examples: dastk_ivp.c dastk_ivp_clp runivp_dastk Getting Help and Reporting Problems Getting Help and Reporting Problems Getting Help and Reporting Problems If an error occurs while you are using DASware, and you believe the error is the result of a problem associated with the product, take one of the following actions: 2 2 2- - - DASware User Guide 8 8 8 Installing DASware on Your Platform 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. If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). If you purchased the product within the last 90 days and you think the problem is casued by a software error, you can submit an SPR. If you submit an SPR, please take the following steps: Describe as accurately as possible the 1. circumstances and state of the system when the problem occurred. Include the description and version number of the product. Demonstrate the problem with specific examples. Reduce the problem to as small a size as possible. 2. Remember to include listings of any command files, 3. include files, relevant data files and so forth. Provide a list of the program. 4. 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 program per SPR. This will facilitate a faster response. Mail the SPR package to DIGITAL. 7. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Concise, complete information helps DIGITAL give timely and accurate service to software problems. If you find an error in the documentation, send an electronic mail message to manufacturing@digital.com. DASware User Guide 2 2 2- - -9 9 9 Installing DASware on Your Platform Installation on OpenVMS Systems Installation on OpenVMS Systems Installation on OpenVMS Systems On OpenVMS systems, DASware is installed optionally as part of the DEComni API V3.1 installation procedure. You can either install DEComni API V3.1 as a separate product, or install it during the BASEstar Open V3.1 installation procedure. On OpenVMS systems, the only transport network provided by DASware V3.1 is RS232. The information that follows is valid for both VAX and Alpha architectures, unless otherwise stated. Preparing for DASware Installation Preparing for DASware Installation Preparing for DASware Installation Before starting the installation procedure, complete the preparation requirements outlined in this section. Software Requirements (BASEstar Open Environment) Software Requirements (BASEstar Open Environment) Software Requirements (BASEstar Open Environment) If you are installing DASware in the BASEstar Open environment, check that the software products listed in Table 2-5 have been installed on your system. Table Table Table 2 2 2 : Pre-requisite Software for OpenVMS : Pre-requisite Software for OpenVMS : Pre-requisite Software for OpenVMS - - -5 5 5 (BASEstar Open Environment) (BASEstar Open Environment) (BASEstar Open Environment) Product Name Product Name Product Name Comments Comments Comments BASEstar Open Server for Ensure that the BASEstar OpenVMS Open Server Device Version 3.1 Connectivity has been installed. See the BASEstar Open Server Inst. & Management Guide for your platform for details. Transport Network Software Transport Network Software Transport Network Software You must also ensure that the appropriate transport network software has been installed and configured. Table 2-6 specifies the necessary transport network software for each supported transport network. 2 2 2 DASware User Guide - - - 10 10 10 Installing DASware on Your Platform Table Table Table 2 2 2- - -6 6 6: Transport Network Software (OpenVMS : Transport Network Software (OpenVMS : Transport Network Software (OpenVMS Platform) Platform) Platform) Transport Network Transport Network Transport Network Transport Network Provider Transport Network Provider Transport Network Provider RS232 LAT (provided with OpenVMS) Disk Space Requirements Disk Space Requirements Disk Space Requirements The table below lists the disk space required to install and run each DASware module. Usage Usage Usage Disk space Disk space Disk space (blocks) (blocks) (blocks) Installation 2000 Permanent 2000 Backing Up Your System Disk Backing Up Your System Disk 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 OpenVMS documentation. DASware User Guide - - -11 11 11 2 2 2 Installing DASware on Your Platform Files Installed on Your System Files Installed on Your System Files Installed on Your System This section lists directories and files created by DASware. SYS$COMMON:[SYSLIB] DASTK_SHR.EXE DASTK232_SHR.EXE OMNI_INTEGRATOR16_DEFS_INCLUDE.H OMNI_INTEGRATOR16_DEFS_INCLUDE.BAS OMNI_INTEGRATOR16_DEFS_INCLUDE.PAS OMNI_INTEGRATOR16_DEFS_INCLUDE.ADA OMNI_INTEGRATOR16_DEFS_INCLUDE.FOR OMNI_INTEGRATOR16_DEFS_INCLUDE.MAR OMNI_INTEGRATOR16_DEFS_INCLUDE.PLI OMNI_INTEGRATOR16_DEFS_INCLUDE.R32 ODS:[SCRIPTS] DASTK_SCHEMA.COM Getting Help and Reporting Problems Getting Help and Reporting Problems Getting Help and Reporting Problems If an error occurs while you are using DASware, and you believe the error is the result of a problem associated with the product, take one of the following actions: 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. If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). If you purchased the product within the last 90 days and you think the problem is casued by a software error, you can submit an SPR. If you submit an SPR, please take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the description and 2 2 2 - - -12 12 12 DASware User Guide Installing DASware on Your Platform version number of the product. Demonstrate the problem with specific examples. Reduce the problem to as small a size as possible. 2. Remember to include listings of any command files, 3. include files, relevant data files and so forth. 4. Provide a list 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. Report only one program per SPR. This will 6. facilitate a faster response. Mail the SPR package to DIGITAL. 7. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Concise, complete information helps DIGITAL give timely and accurate service to software problems. If you find an error in the documentation, send an electronic mail message to manufacturing@digital.com. DASware User Guide 13 13 13 - - - 2 2 2 Installing DASware on Your Platform Installation on Windows NT Systems Installation on Windows NT Systems Installation on Windows NT Systems On the Windows NT platform, DASware features can only be accessed through BASEstar Open services (the DEComni API is not currently available). Preparing for DASware Installation Preparing for DASware Installation Preparing for DASware Installation Before starting the installation procedure, you should complete the preparation requirements outlined in this section. License Registration License Registration License Registration The installation procedure prompts you to supply a software key. You must enter this code to make DASware available on your system. Failure to do so implies restricted use of the product. For information about how to obtain the software key, refer to your cover letter. Software Requirements (BASEstar Open Environment) Software Requirements (BASEstar Open Environment) Software Requirements (BASEstar Open Environment) If you are installing DASware in the BASEstar Open environment, check that the software products listed in Table 2-7 have been installed on your system. Table Table Table : Pre-requisite Software for Windows NT : Pre-requisite Software for Windows NT : Pre-requisite Software for Windows NT 7 7 7 - - - 2 2 2 (BASEstar Open Environment) (BASEstar Open Environment) (BASEstar Open Environment) Product Name Product Name Product Name Comments Comments Comments BASEstar Open Server for Ensure that the BASEstar Windows NT Open Server Device Version 3.1 Connectivity has been installed. See the BASEstar Open Server Inst & Management Guide for your platform for details. Transport Network Software Transport Network Software Transport Network Software You must also ensure that the appropriate transport network software have been installed and configured. Table 2-8 specifies the necessary transport network software for each supported transport network. 2 2 2 14 14 14 DASware User Guide - - - Installing DASware on Your Platform Table Table Table 2 2 2- - -8 8 8: Transport Network Software (Windows NT : Transport Network Software (Windows NT : Transport Network Software (Windows NT Platform) Platform) Platform) Transport Network Transport Network Transport Network Transport Network Provider Transport Network Provider Transport Network Provider RS232 Telnet or direct connection through serial communication port. (Telnet is implemented by the DAS module layered on TCP/IP). TCP/IP You can install TCP/IP services during installation of the Windows NT operating system. OSI Transport Not available. Backing Up Your System Disk Backing Up Your System Disk 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 Windows NT documentation. Installing DASware Installing DASware Installing DASware To install DASware on a Windows NT system, you must be a member of the Administrators group. To initiate the installation procedure, run the SETUP.EXE file from diskette 1 of the distribution set. The DASware installation procedure does not copy any files from the distribution media but uses files which were copied on your system by the BASEstar Open Server Device Connectivity installation procedure. Installing DASware on your Windows NT system takes approximately 1 minute. Deinstalling DASware Deinstalling DASware Deinstalling DASware To deinstall DASware, double click on the ``uninstaller DASware icon in the BASEstar Open '' Program Manager. Getting Help and Reporting Problems Getting Help and Reporting Problems Getting Help and Reporting Problems If an error occurs while you are using DASware, and you believe the error is the result of a problem associated with the product, take one of the following actions: 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. If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). DASware User Guide - - -15 15 15 2 2 2 Installing DASware on Your Platform If you purchased the product within the last 90 days and you think the problem is casued by a software error, you can submit an SPR. If you submit an SPR, please take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the description and version number of the product. 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 list 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 program 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 timely and accurate service to software problems. If you find an error in the documentation, send an electronic mail message to manufacturing@digital.com. 2 2 2 16 16 16 - - - DASware User Guide Installing DASware on Your Platform Installation on HP-UX Systems Installation on HP-UX Systems Installation on HP-UX Systems BASEstar Open Server installs the DASware software for HP-UX during the installation procedure. The BASEstar Open Server for HP-UX Version 3.1 installation procedure also installs the BASEstar Open Device Connection Application Programming Interface (DEComni API). This is the only software required to install DASware on your system. For further information, refer to the BASEstar Open Server Inst. & Management Guide for your platform. Preparing for DASware Installation Preparing for DASware Installation Preparing for DASware Installation Before starting the installation procedure, you should complete the preparation requirements outlined in this section. Transport Network Software Requirements Transport Network Software Requirements Transport Network Software Requirements You must ensure that the appropriate transport network software has been installed and configured. Table 2-9 specifies the necessary transport network software for each supported transport network. - - - Table Table Table 2 2 2 : Transport Network Software (HP-UX : Transport Network Software (HP-UX : Transport Network Software (HP-UX 9 9 9 Platform) Platform) Platform) Transport Transport Transport Transport Network Software Transport Network Software Transport Network Software Network Network Network RS232 No pre-requisite software. TCP/IP services are required if telnet is used. TCP/IP TCP/IP services OSI OTS/9000 OSI transport for HP-UX Disk Space Requirements (DASware-specific files) Disk Space Requirements (DASware-specific files) Disk Space Requirements (DASware-specific files) The table below lists the disk space required to install and run each DASware module. Usage (Kbytes) Usage (Kbytes) Usage (Kbytes) /usr/opt /usr/opt /usr/opt /var/opt /var/opt /var/opt Installation/p 5600 1200 ermanent Backing Up Your System Disk Backing Up Your System Disk 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 HP-UX documentation. DASware User Guide 2 2 2 17 17 17 - - - Installing DASware on Your Platform Running the Installation Verification Procedure (IVP) Running the Installation Verification Procedure (IVP) Running the Installation Verification Procedure (IVP) The DASware installation procedure does not execute an IVP as part of the installation. However, to run an IVP for the three protocols supported by DASware on HP-UX after completing the installation, execute the following commands: # setenv SHLIB_PATH /usr/lib # setenv NLSPATH /usr/lib/nls/msg/%N # cd /var/opt/dastk_310/examples # runivp_dastk 232 # runivp_dastk TCP # runivp_dastk OSI You can only run the OSI IVP if OTS/9000 has been configured. For information about how to configure the OTS/9000 OSI transport for running the IVP (loopback connection on the same machine) and for device connectivity, refer to Appendix B. Files Installed on Your System Files Installed on Your System Files Installed on Your System This section lists directories and files created by DASware. /var/opt/dastk_310/examples: dastk_ivp.c dastk_ivp runivp_dastk /var/opt/dastk_310/include: omni_integrator16_defs_include.h /usr/opt/dastk_310/lib: dastk_232init.o dastk_tcpinit.o libdastk.a libdastkosi.a dastk_osiinit.o dastksts.cat 2 2 2 18 18 18 DASware User Guide - - - Installing DASware on Your Platform libdastk232.a libdastktcp.a /usr/opt/dastk_310/shlib: libdastk.sl libdastk232.sl libdastkosi.sll libdastktcp.sl Getting Help and Reporting Problems Getting Help and Reporting Problems Getting Help and Reporting Problems If an error occurs while you are using DASware, and you believe the error is the result of a problem associated with the product, take one of the following actions: 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. If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). If you purchased the product within the last 90 days and you think the problem is casued by a software error, you can submit an SPR. If you submit an SPR, please take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the description and version number of the product. 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 list of the program. If the program is longer than 50 lines, submit a 5. 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. DASware User Guide 19 19 19 - - - 2 2 2 Installing DASware on Your Platform 6. Report only one program 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 timely and accurate service to software problems. If you find an error in the documentation, send an electronic mail message to manufacturing@digital.com. 2 2 2 - - -20 20 20 DASware User Guide PART I PART I PART I Using BASEstar Open to Exchange Data Via Transport Using BASEstar Open to Exchange Data Via Transport Using BASEstar Open to Exchange Data Via Transport Networks Networks Networks This part describes how you can exchange data through transport networks with partner applications using BASEstar Open services, and how you must configure BASEstar Open for use with DASware. It also provides a complete code example that you can run in the BASEstar Open environment. The Command Language Interface (CLI) is used to create and operate the required BASEstar Open objects. However, you could use the Application Programming Interface (API), or the Graphical Configuration Utility (GCU) to perform the same tasks. 3 3 3 Overview Overview Overview This chapter describes the BASEstar Open environment components that are involved when using BASEstar Open services to exchange data with transport network partner applications. It also provides an overview of the operations that can be performed by BASEstar Open users. DASware User Guide 3 3 3- - -1 1 1 Overview BASEstar Open Environment Components BASEstar Open Environment Components BASEstar Open Environment Components Figure 3-1 shows the environment components involved when you exchange data through the transport networks supported by DASware. Figure Figure Figure 3 3 3- - -1 1 1: BASEstar Open Environment Components : BASEstar Open Environment Components : BASEstar Open Environment Components Data Services Data Services Data Services BASEstar Open users use Device_Data_Points to send data to, and receive data from, a transport network. When a user puts the value of a Device_Data_Point, BASEstar Open forwards a message to the transport network. Vice versa, BASEstar Open updates the value 3 3 3 - - -2 2 2 DASware User Guide Overview of a Device_Data_Point each time it receives a valid message from the transport network. Each Device_Data_Point is linked to a Device Services variable which, in turn, is associated with the VMD configured for the selected transport network connection. Device Services Device Services Device Services BASEstar Open Device Services provide a unique set of operations to BASEstar Open users for device- independent access to any type of device or network. This device-independent approach to device connectivity is possible because Device Services model each device as a MMS Virtual Manufacturing Device (VMD). Each transport connection (for example, a TCP/IP connection) is mapped by a VMD. A variable associated with this VMD corresponds to a data item exchanged on the transport connection. DEComni API DEComni API DEComni API The DEComni API is the engine that provides BASEstar Open Device Services with MMS functions. DEComni also allows new DAS modules to be added to the BASEstar Open environment in a standardized way. The Omni Directory Services (ODS) database is the DEComni component that allows you to define the information required for addressing the supported transport network. Transport Network Software Transport Network Software Transport Network Software For each transport network you wish to use, you must install the software product (and any hardware required) that support the transport network. Before using a DASware module, ensure that you have already installed and configured the required transport network software on your system. DASware User Guide 3 3 3 3 3 3 - - - Overview Exchanging Data Through a Transport Network Exchanging Data Through a Transport Network Exchanging Data Through a Transport Network This section describes what happens when a BASEstar Open user uses a Device_Data_Point to send and receive data through a transport network. Figure 3-2 shows the objects and commands a BASEstar Open user must use to receive data messages from (and send data messages to) a transport network partner application. Figure Figure Figure 2 2 2: BASEstar Open Objects and Operations : BASEstar Open Objects and Operations : BASEstar Open Objects and Operations 3 3 3- - - DEVICE_DA Data VA CAC GET_V Inf VA SEND DEVICE_DA Data VA PUT_V VM Sending Data Sending Data Sending Data To send a data messages to a transport network partner application, a BASEstar Open user must issue a PUT VALUE command on a Device_Data_Point. As shown in Figure 3-2, the Device_Data_Point must be linked to a Device Services variable, which is, in turn, associated with a VMD that has been configured for accessing the desired partner application through the chosen transport network. Before sending a message, DASware performs the following operations: 1. Obtains the data to be forwarded to the transport network from the user buffer, and encodes it according to the datatype associated with the linked Device Services variable, as explained in Section 4.3. (For example, a value of the INTEGER_16 datatype is encoded as 2 bytes.) 3 3 3- - -4 4 4 DASware User Guide Overview 2. Depending on the transport network in use, adds specific information to the outgoing encoded data (see Table 3-1 for details). Forwards the encoded data as a transport network 3. specific Protocol Data Unit (PDU), for example, an RS 232 data stream or a TCP/IP message. _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ Data is transmitted to the transport network according to the BIGENDIAN mode, that is, the MSB (Most Significant Byte) is sent first. ________________________________ ________________________________ ________________________________________________ ________________ ________________ - - - 3 3 3 Table Table Table 1 1 1: Protocol-Specific Information Added to : Protocol-Specific Information Added to : Protocol-Specific Information Added to Outgoing Encoded Data (BASEstar Open) Outgoing Encoded Data (BASEstar Open) Outgoing Encoded Data (BASEstar Open) Transport Transport Transport Protocol-Specific Information Protocol-Specific Information Protocol-Specific Information Network Network Network RS 232 ____ UNIX DASware adds a trailer to the encoded data, consisting of a termination sequence that is specified by the value of the DTK232_TERM_STRING logical variable. For example, if the value of the DTK232_TERM_STRING logical variable is "13,10", the termination sequence consists of a Carriage Return character followed by a Line Feed. This sequence is transmitted to the line following the user data. __________ Windows NT DASware adds a trailer to the encoded data, consisting of a termination sequence specified by the value assigned to the END_TX_SEQ keyword in the file %DASTK%\LIB\def.fsm. If no value is specified for the DTK232_TERM_STRING global variable, the CR,LF termination sequence is assumed by default. TCP/IP The TCP/IP DAS is internally registered as "WORD COUNTED". This means that, during data transmission, DASware adds a header consisting of a 16-bits counter that contains the length (in bytes) of the data being transmitted. DASware User Guide 3 3 3 5 5 5 - - - Overview OSI Transport No protocol-specific information is added. Receiving Data Receiving Data Receiving Data A BASEstar Open user must issue a GET VALUE command on a Device_Data_Point to obtain from BASEstar Open the value of a data message received from the Transport network partner application. The Device_Data_Point must have been configured for receive operations, and must be linked to the `` reception variable'' associated with the VMD that models the transport network connection toward the partner application. BASEstar Open always uses the reception variable to return the data received from the transport network partner application. The "reception variable" is the first Device Services Named_Variable that has been created for a given VMD. If no Named_Variables have been defined, the first Unnamed_Variable is used. If no variable is associated with the remote VMD, any data received from the partner application are lost. The GET VALUE command returns to the user the cached value of the Device_Data_Point itself; that is, there is no interaction with the transport network. BASEstar Open updates the value of the Device_Data_Point regardless of the receive operations performed by the user. When receiving a message from the transport network, BASEstar Open generates an internal Inforeport that causes the unsolicited updating of the cached value of the Device_Data_Point that is linked to the Device Services "reception variable". BASEstar Open interprets the data received from the transport network, (for example, an RS 232 data stream or a TCP/IP message), according to the datatype associated with the "reception variable", as follows: 1. Removes any protocol-specific information from the data (see Table 3-2 for details). 2. Decodes the received PDU according to the datatype associated with the reception variable (see Section 4.3), and stores the decoded data into the user buffer. Note that if an insufficient number of bytes is received, the value returned in the user buffer is unpredictable; if instead the number of the 3 3 3- - - DASware User Guide 6 6 6 Overview received bytes exceeds that required to meet the datatype, the exceeding bytes are lost. _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ Data is received according to the BIGENDIAN mode, that is the MSB (Most Significant Byte) is received first. ________________________________ ________________________________ ________________________________________________ ________________ ________________ 3 3 3- - - Table Table Table 2 2 2: Protocol-Specific Information Removed from : Protocol-Specific Information Removed from : Protocol-Specific Information Removed from Incoming Data (BASEstar Open) Incoming Data (BASEstar Open) Incoming Data (BASEstar Open) Transport Transport Transport Protocol-Specific Information Protocol-Specific Information Protocol-Specific Information Network Network Network RS 232 ____ UNIX DASware considers that a data message has been received as soon as it encounters the termination sequence specified by the value of the DTK232_TERM_STRING logical variable. For example, if the value of the DTK232_TERM_STRING logical variable is "13,10", the DAS considers that a PDU has been received from the transport network when a Carriage Return character is encountered followed by a Line Feed. The termination sequence is discarded. __________ Windows NT DASware considers that a data message has been received as soon as it encounters the termination sequence specified by the value of the END_TX_SEQ keyword in the file %DASTK%\LIB\def.fsm. If no value is specified for the DTK232_TERM_STRING global variable, the CR,LF termination sequence is assumed by default. TCP/IP The TCP/IP DAS is internally registered as "WORD COUNTED". This means that the first two bytes of the TCP/IP PDU contain a 2-byte counter. The TCP/IP DAS always discards the first two PDU bytes after having received the PDU and before decoding it. DASware User Guide 3 3 3- - -7 7 7 Overview OSI Transport No protocol-specific information is removed. 3 3 3 8 8 8 - - - DASware User Guide Overview Encoding and Decoding Transport Network Data Encoding and Decoding Transport Network Data Encoding and Decoding Transport Network Data Table 3-3 shows the coding and decoding rules BASEstar Open uses when sending and receiving data through a transport network. The number of bytes involved in a send or receive operation depends on the datatype associated with the Device Services variable that is linked to the Device_Data_Point in use, therefore: For a send operation, each table entry specifies the number of user data bytes that will be included in the transport network PDU. For a receive operation, each table entry specifies the number of bytes that DASware takes from the received PDU before preparing the data to be passed to the user. 3 3 3- - - Table Table Table : Coding and Decoding Data by Datatype : Coding and Decoding Data by Datatype : Coding and Decoding Data by Datatype 3 3 3 (BASEstar Open) (BASEstar Open) (BASEstar Open) Datatype Datatype Datatype Exchanged as Exchanged as Exchanged as BOOLEAN 1 byte TIME Not supported VISIBLE_CHAR 1 byte INTEGER_8 1 byte INTEGER_16 2 bytes