BASEstar Open Device Connectivity DASware User Guide Order Number: AA-QT1HA-TE February 1996 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. 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.0 Digital Equipment Corporation Digital Equipment Corporation Digital Equipment Corporation Maynard, Massachusetts Maynard, Massachusetts Maynard, Massachusetts Index First Printing, February 1996 First Printing, February 1996 First Printing, February 1996 c 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 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 1 Introduction 1 Introduction 1 Introduction 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 Installation on Digital UNIX Systems..................... 2 - 2 Preparing for DASware installation .................... 2 - 2 Installing DASware .................................... 4 - 2 Files installed on your system ........................ 4 - 2 PART III Exchanging Data through Transport Networks Using PART III Exchanging Data through Transport Networks Using PART III Exchanging Data through Transport Networks Using BASEStar Open BASEStar Open BASEStar Open 3 Overview 3 Overview 3 Overview BASEstar Open Environment Components..................... 2 - 3 Exchanging Data Through a Transport Network.............. 4 - 3 Sending Data .......................................... 4 - 3 Receiving Data ........................................ 5 - 3 Encoding and Decoding Transport Network Data .......... 7 - 3 4 Configuring BASEstar Open 4 Configuring BASEstar Open 4 Configuring BASEstar Open Registering ODS Entries................................ 2 - 4 .. Creating Application Services Objects.................... 2 - 4 Creating Device Services Objects.........................4 2 - Creating Protocol_Profiles ............................4 2 - Creating VMDs ......................................... 3 - 4 Creating Variables .................................... 4 - 4 Creating Data Services Objects........................... 5 4- Creating Device_Data_Points for Receive Operations .... -5 4 Creating Device_Data_Points for Send Operations ....... 5 - 4 5 A Complete Example 5 A Complete Example 5 A Complete Example Example Overview......................................... - 5 2 Before Running the Example............................... 2 - 5 CLI Source...............................................5 3 - iii iii iii Exchanging Data through the Transport Network ............5 4 - PART III Exchanging Data through Transport Networks Using the PART III Exchanging Data through Transport Networks Using the PART III Exchanging Data through Transport Networks Using the DEComni API DEComni API DEComni API 6 Overview 6 Overview 6 Overview DEComni Environment Components ...........................6 2 - Exchanging Data Through the Transport Network ............6 3 - Writing Data through the Transport Network ............6 3 - Receiving Data from the Transport Network .............6 4 - Encoding and Decoding Transport Network Data ..........6 6 - 7 Configuring DEComni 7 Configuring DEComni 7 Configuring DEComni Registering ODS Entries ................................ 7 .. 2 - Setting the Application Profile ..........................7 2 - Creating VMD Definitions ................................ 7 . 2 - Creating Variable Definitions ............................7 2 - 8 Programming 8 Programming 8 Programming DEComni API Procedures for Data Exchange .................8 2 - Opening and Closing a Transport Network Connection 8 ....... 2 - Sending Data through the Transport Network ...............8 2 - Receiving Data from the Transport Network ................8 2 - 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 Creating ODS Entries for the RS 232 Transport Network A .... 2 - Through Direct Connection or LAT ......................A 2 - Through Telnet ................................ A ........ 3 - Creating ODS Entries for the TCP/IP Transport Network A .... 4 - Creating ODS Entries for the OSI Transport Transport Network 5 - A Figures Figures Figures - Figure 1 1: Communicating through a Transport Network 1 .... 1 - Figure 3-1: BASEstar Open Environment Components .........3 2 - Figure 3-2: BASEstar Open Objects and Operations 3 ......... 4 - - Figure 6 1: DEComni API Environment Components ...........6-2 Figure 6- EComni Definitions and API Procedures 2: D .......6-3 Tables Tables Tables 1: Available Platforms and DASware Modules Table 1- 1 ....... 2 - 1: DASware Subsets - Table 2 ...............................2-2 Table 2-2: Prerequisite Software for Digital UNIX (BASEstar Open Environment) ........................................2-3 Table 2-3: Prerequisite Software for Digital UNIX (DEComni Environment) .............................................2 3 - iv iv iv Table 2-4: Transport Networks and Software (Digital UNIX Platform)................................................ 3 2- Table 3 1: Protocol-Specific Information Added to Outgoing - Encoded Data (BASEstar Open)............................. 5 3- Table 3 2: Protocol-Specific Informat - ion Removed from Incoming Data (BASEstar Open)............................ 6 - 3 Table 3 3: Coding and Decoding Data According to Data Type - (BASEstar Open).......................................... 7 - 3 Table 4 1: Protocol_Profile Attributes (BASEstar Open) - ... 2 - 4 Table 4 2: VMD Attributes (BASEstar Open) - ................ 3 - 4 Table 4 3: Device Services Reception Variable Attributes - (BASEstar Open).......................................... 4 - 4 Table 4 4: Device Services Transmission Variable Attributes - 4-4 Table 4 5: Device_Data_Point Attributes for Receive - Operations (BASEstar Open)............................... 5 - 4 Table 4 6: Device_Data_Point Attributes for Send Oper - ations 5 - 4 Table 6 1: Protocol-Specific Information Added to Outgoing - Encoded Data (DEComni API)............................... 4 - 6 Table 6 2: Protocol-Specific Information Removed from - Incoming Data (DEComni API).............................. 5 - 6 Table 6 3: Coding/Decoding Data According to MMS Types - (DEComni API)............................................ 6 - 6 Table 7 1: DEComni API Application Profiles for DAS Modules - 2 - 7 Table 7 2: VMD Attributes (DEComni API) - .................. 2 - 7 Table 7 3: Variable Attributes (DEComni API) - ............. 3 - 7 Table 8-1: DEComni API Procedures for Data Exchange...... 2 - 8 Table A 1: Values of ODS Attributes for - RS 232 Transport Network..................................................A 2 - Table A 2: ODS Attributes for the RS 232 Transport Network - (Telnet)................................................. -3 A Table A 3: ODS Attributes for the TCP/IP Transport Network - A-4 Table A-4: ODS Attributes for the OSI Transport Transport Network..................................................A 5 - Examples Examples Examples Example 4-1: Creating Protocol_Profile Objects (BASEstar Open)....................................................4 3 - Example 4-2: Creating VMD Objects (BASEstar Open)........ - 4 3 Example 5-1: Creating BASEstar Open Objects..............5 3 - Example 5 2: Exchanging Data through the Transport Network - 5-4 Example A 1: OD - S Entries for RS 232 Direct Connection and LAT...................................................... 2 - A Example A 2: ODS Entries for RS 232 Telnet - ............... - A 3 Example A-3: ODS Entries for TCP/IP......................A 4 - Example A-4: ODS Entries for the OSI Transport Network... - A 5 v v v vi vi 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. 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 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 vii vii vii 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 Services . (for supported platforms) ix ix 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 through a Transport Network : Communicating through a Transport Network : Communicating through 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 exchange data using the DEComni API procedures . Transport Networks and Platforms Supported by DASware Transport Networks and Platforms Supported by DASware Transport Networks and Platforms Supported by DASware Table 1 lists the DASware modules available on -1 different platforms, which DAS modules are available and thus, which Transport Network can be used to exchange data through. Table Table Table : Available Platforms and DASware Modules : Available Platforms and DASware Modules : Available Platforms and DASware Modules - - -1 1 1 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) Digital 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 manual to know how you must configure BASEstar Open 1 1 1 2 2 2 DASware User Guide - - - and use its services to exchange data through the desired Transport Network (or Networks). 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 (or Networks). DASware User Guide 1 1 1- - -3 3 3 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 . Windows NT . 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 (or Networks) on your system. This chapter provides the instructions for installing DASware in the BASEstar Open and DEComni environments. DASware User Guide - - -1 1 1 2 2 2 installing DASware on Your Platform Installation on Digital UNIX Systems Installation on Digital UNIX Systems Installation on Digital UNIX Systems Table 2 1 lists the subsets included in the DASware - software product. Note that a subset is provided for each of the Transport Network supported on the Digital UNIX platform. Table Table Table 1 1 1: DASware Subsets (Digital UNIX Platform) : DASware Subsets (Digital UNIX Platform) : DASware Subsets (Digital UNIX Platform) 2 2 2- - - DASware Module DASware Module DASware Module Subset Name Subset Name Subset Name RS232 DASTK232300 TCP/IP DASTKTCP300 OSI Transport DASTKOSI300 Requirements change depending on whether you are installing DASware for use through BASEstar Open services or the DEComni API. 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 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. You then have a choice of two ways to perform the PAK registration in the License Database (LDB): . Before installing DASware 2 2 2 DASware User Guide - - -2 2 2 installing DASware on Your Platform 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 2 - 2 appropriately on your system. - - - 2 2 2 Table Table Table : Prerequisite Software for Digital UNIX : Prerequisite Software for Digital UNIX : Prerequisite 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 BSTR300 Ensure that the BASEstar BASEstar Open Server Open Device Connectivity for Digital UNIX (DEComni) has been Version 3.0 installed. In particular, check for the presence of the following subsets: DOUBASE300 . DASTK232300 . DASTKRUN300 . See the BASEstar Open DASware User Guide 3 3 3 2 2 2- - - installing DASware on Your Platform Installation Guide for your platform for details. Software Requirements (DEComni Environment) Software Requirements (DEComni Environment) Software Requirements (DEComni Environment) Check that the software products listed in Table 2-3 have been installed appropriately on your system. Table Table Table 3 3 3: Prerequisite Software for Digital UNIX : Prerequisite Software for Digital UNIX : Prerequisite Software for Digital UNIX 2 2 2- - - (DEComni Environment) (DEComni Environment) (DEComni Environment) Subset Name and Subset Name and Subset Name and Comments Comments Comments Description Description Description DOUBASE300 In particular, check for the DEComni API Version 3.0 presence of the following for Digital UNIX subsets: Version 3.0 DASTK232300 . DASTKRUN300 . See the DEComni API Installation Guide for your platform for details. Transport Network Specific Software Transport Network Specific Software Transport Network Specific Software You must also ensure that the appropriate Transport Network software have been installed and configured. Table 2 specifies, for each supported Transport 4 - Network, the needed Transport Network software. Table Table Table 2 2 2 : Transport Networks and Software (Digital : Transport Networks and Software (Digital : Transport Networks and Software (Digital 4 4 4 - - - UNIX Platform) UNIX Platform) UNIX Platform) Transport Transport Transport Transport Network Software Transport Network Software Transport Network Software Network Network Network RS232 The OSFLAT320 subset is required if LAT is used. The OSFLAT320 and OSFNET300 subsets are required if Telnet is used. (The capability to communicate through serial ports is embedded in the Operating System.) TCP/IP The OSFCLINET320 and OSFINET320 subsets are required. OSI Transport The DNABASE320 and DNAPGMR320 subsets are required. 2 2 2 4 4 4 DASware User Guide - - - installing DASware on Your Platform Disk Space Requirements Disk Space Requirements Disk Space Requirements The following table lists the disk space required to install and running 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 on performing a system disk backup, see your Digital UNIX documentation. Installing DASware Installing DASware Installing DASware This section describes the installation, deinstallation and IVP procedures for DASware for Digital UNIX. Installing DASware and running the Installation and Verification Procedure (IVP) on your Digital UNIX system takes approximately 5 to 10 minutes. Installation Procedure Installation Procedure Installation Procedure Install DASware as follows: 1. Log onto the system as superuser (root). Mount the distribution media on the desired 2. location (for example, mount -dr /dev/rz4c /CDROM). Change your working directory to the kit location 3. (for example, cd /CDROM/DASTKRUN300). Issue the 4. setld -l command to load the product 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 did not run the IVP at that time or the product does not work correctly, you can run the IVP at any time by issuing the following command: setld -v DASTKRUN300 Deinstallation Procedure Deinstallation Procedure Deinstallation Procedure DASware can be deinstalled as follows: 1. Log onto the system as superuser (root). DASware User Guide - - -5 5 5 2 2 2 installing DASware on Your Platform 2.Change your working directory to the kit location (for example, cd /CDROM/DASTKRUN300). 3.Issue the setld -d command: setld -d DASTKRUN300 setld -d DASTK232300 setld -d DASTKTCP300 setld -d DASTKOSI300 Files installed on your system Files installed on your system Files installed on your system This section lists directories and files created by DASware. /usr/opt/dastk_300/include: omni_integrator16_defs_include.h /usr/opt/dastk_300/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_300/shlib: libdastk.so libdastk232.so libdastkosi.so libdastktcp.so libdastkx25.so /var/opt/dastk_300/examples: 2 2 2 6 6 6 - - - DASware User Guide installing DASware on Your Platform dastk_ivp.c dastk_ivp_clp runivp_dastk DASware User Guide 2 2 2 7 7 7 - - - 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. 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 2 have been installed -5 appropriately on your system. Table Table Table : Prerequisite Software for Windows NT : Prerequisite Software for Windows NT : Prerequisite Software for Windows NT 5 5 5 - - - 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.0 Connectivity has been installed. See the BASEstar Open Installation Guide for your platform for details. Transport Network Specific Software Transport Network Specific Software Transport Network Specific Software You must also ensure that the appropriate Transport Network software have been installed and configured. Table 2 6 specifies, for each supported Transport - Network, the needed Transport Network software. Table Table Table : Transport Networks and Software (Windows : Transport Networks and Software (Windows : Transport Networks and Software (Windows 6 6 6 - - - 2 2 2 NT Platform) NT Platform) NT 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. 2 2 2 DASware User Guide 8 8 8 - - - installing DASware on Your Platform 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 on performing a system disk backup, see your Windows NT documentation. Installing DASware Installing DASware Installing DASware To install DASware on a Windows NT system run the INSTALL.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. 1. DASware User Guide - - - 2 2 2 9 9 9 PART I PART I PART I Exchanging Data through Transport Networks Using Exchanging Data through Transport Networks Using Exchanging Data through Transport Networks Using BASEstar Open BASEstar Open BASEstar Open 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 exchanging data with Transport Network partner applications through BASEstar Open services. 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 that are involved when BASEstar Open users exchange data through the Transport Networks supported by DASware. Figure Figure Figure - - -1 1 1 3 3 3 : 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 of a Device_Data_Point each time it receives a valid message from the Transport Network. 3 3 3 2 2 2 - - - DASware User Guide Overview 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 DEComni DEComni 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 : BASEstar Open Objects and Operations : BASEstar Open Objects and Operations : BASEstar Open Objects and Operations - - -2 2 2 3 3 3 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.) 2. Depending on the Transport Network in use, adds specific information to the outgoing encoded data (see Table 3-1for details). 3. Forwards the encoded data as a Transport Network specific Protocol Data Unit (PDU), for example, an RS 232 data stream or a TCP/IP message. 3 3 3 - - -4 4 4 DASware User Guide Overview _______________________ _______________________ _______________________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. ________________________________ ________________________________ ________________________________________________ ________________ ________________ Table Table Table 3 3 3- - -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 ____________ Digital 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. 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 DASware User Guide - - -5 5 5 3 3 3 Overview 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 Device Services first 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 2 Table 3- 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 received bytes exceeds that required to meet the Datatype, the exceeding bytes are lost. 3 3 3 DASware User Guide - - - 6 6 6 Overview _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ Data is received according to the BIGENDIAN mode, that is the MSB (Most Significant Byte) is received first. ________________________________ ________________________________ ________________________________________________ ________________ ________________ Table Table Table 3 3 3- - -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 ____________ Digital 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. OSI Transport No protocol-specific information is removed. DASware User Guide 3 3 3- - -7 7 7 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. Table Table Table 3 3 3 - - - 3 3 3 : Coding and Decoding Data According to Data : Coding and Decoding Data According to Data : Coding and Decoding Data According to Data Type (BASEstar Open) Type (BASEstar Open) Type (BASEstar Open) Data Type Data Type Data Type Exchanged as Exchanged as Exchanged as BOOLEAN 1 byte TIME Not supported VISIBLE_CHAR 1 byte INTEGER_8 1 byte INTEGER_16 2 bytes INTEGER_32 4 bytes UNSIGNED_8 1 byte UNSIGNED_16 2 bytes UNSIGNED_32 4 bytes F_FLOAT 4 bytes (IEEE float format) D_FLOAT Not supported BCD1, BCD2, BCD3, Not supported BCD4, BCD5, BCD6, BCD7, BCD8 OCTET 1 byte BIT 1 byte OBJECT_STATUS Not supported OBJECT_NAME Not supported Array_Datatype As many times as the number of elements it contains. A variable length array is treated as an array having a fixed length; the maximum length is assumed. Structure Datatype Packing of the Simple_Datatypes without padding. 3 3 3 - - - DASware User Guide 8 8 8 Overview DASware User Guide 3 3 3- - -9 9 9 4 4 4 Configuring BASEstar Open Configuring BASEstar Open Configuring BASEstar Open This chapter describes how you must configure BASEstar Open in order to exchange data with a partner application through any of the Transport Networks supported by DASware. To configure BASEstar Open, you must: Register the appropriate entries in the ODS . database. . Create the required Application Services Activity and Program objects. Create the required Device Services . Protocol_Profile, VMD and Variable objects. Create the required Device_Data_Points objects. . _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ For an explanation of BASEstar Open object attributes whose values are not specified here, refer to the BASEstar Open Command Language Interface and to the BASEstar Open Reference Guide. ________________________________ ________________________________ ________________________________________________ ________________ ________________ DASware User Guide 4 4 4 1 1 1 - - - Configuring BASEstar Open Registering ODS Entries Registering ODS Entries Registering ODS Entries You must create an ODS entry containing Transport Network-specific information for each Transport Network partner application with which you wish to exchange data. See Appendix A for details. Creating Application Services Objects Creating Application Services Objects Creating Application Services Objects You can use the DATADEV server or separate Device and Data servers. The DATADEV server makes both Data and Device Services servers available in a single process, thus simplifying configuration operations, optimizing performance, and allowing the same Device_Data_Point to be used for both send and receive operations. ______________________ ______________________ ______________________ _____________________ _____________________ _____________________ Note Note Note The DATADEV server is used throughout this manual, therefore you should modify the information and examples provided in this chapter if you want to use two separate Device and Data Services servers (for example, if your BASEstar Open version does not support DATADEV servers). ________________________________ ________________________________ ________________________________________________ ________________ ________________ See also Chapter 5 for examples showing the commands used to create the required Program and Activity objects. For further details, refer to the BASEstar Open Command Language Interface and to the BASEstar Open Reference Guide. Creating Device Services Objects Creating Device Services Objects Creating Device Services Objects 1. Protocol_Profiles 2. VMDs 3. Variables Creating Protocol_Profiles Creating Protocol_Profiles Creating Protocol_Profiles Device Services uses a Protocol_Profile to associate a VMD with the appropriate Transport network (that is, with the DASware module). You must create one Protocol_Profile for each Transport Network, and you can use it for all the VMDs that are associated with that Transport Network. Table 4 lists the 1 - Protocol_Profile attributes whose values are specific to the supported Transport Networks. 4 4 4 DASware User Guide 2 2 2 - - - Configuring BASEstar Open Table Table Table 4 4 4- - -1 1 1: Protocol_Profile Attributes (BASEstar : Protocol_Profile Attributes (BASEstar : Protocol_Profile Attributes (BASEstar Open) Open) Open) Attribute Attribute Attribute Description and Values Description and Values Description and Values Name Name Name -APPLPROFID The identifier of the DAS to be used. Possible values are: . 151 for RS 232 . 152 for TCP/IP . 153 for OSI Transport -MAXPDUSIZE The maximum length of the Protocol Data Unit (PDU) exchanged on the Transport Network, including the length of any headers and trailers added by the DAS. Example 4 shows the Protocol_Profiles for all the -1 supported Transport Networks. Example Example Example - - - : Creating Protocol_Profile Objects : Creating Protocol_Profile Objects : Creating Protocol_Profile Objects 1 1 1 4 4 4 (BASEstar Open) (BASEstar Open) (BASEstar Open) BSTR> CREATE PROTOCOL_PROFILE PP_TNRS232 -APPLPROFID 151\ -MAXPDUSIZE 1024 -LOG BSTR> CREATE PROTOCOL_PROFILE PP_TNTCPIP -APPLPROFID 152\ -MAXPDUSIZE 1024 -LOG BSTR> CREATE PROTOCOL_PROFILE PP_TNOSI -APPLPROFID 153\ -MAXPDUSIZE 1024 -LOG Creating VMDs Creating VMDs Creating VMDs A VMD is the gate that BASEstar Open makes available to its users to access a Transport Network partner. In fact, a DASware VMD is mainly characterized by the DVM_ACCESS_POINT attribute that must specify an ODS and a Transport Network Protocol_Profile. You need as many VMDs as many ODS entries you have planned to access a given Transport Network: this depends on your needs and on the protocol characteristics of the Transport Network in use. DASware User Guide - - - 4 4 4 3 3 3 Configuring BASEstar Open Table Table Table 4 4 4 2 2 2: VMD Attributes (BASEstar Open) : VMD Attributes (BASEstar Open) : VMD Attributes (BASEstar Open) - - - Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values -DVM_ACCESS_POINT A list of one or more descriptors, one for each access point clients use to access the VMD. An access point descriptor has the following format: < < : >: >: < < > > where: application_simple_name must specify an ODS entry that is consistent with the Transport Network in use and protocol_profile_name specifies a Protocol_Profile and thus a Transport Network. Example 4 2 - shows VMD objects that are valid for all the supported Transport Networks. The strings specified in the -MODEL and -VENDOR attributes are only used for documentation purposes. Example Example Example 2 2 2 - - - 4 4 4 : Creating VMD Objects (BASEstar Open) : Creating VMD Objects (BASEstar Open) : Creating VMD Objects (BASEstar Open) BSTR> CREATE VMD VMD_TNRS232_001\ -MODEL "DASware RS232" -VENDOR "OSFdirect"\ -DVM_ACCESS_POINTS ("/cn=OSFdirect":PP_TNRS232)\ -DESCRIPTION "For RS232 direct connection with XXX Device"\ -LOG BSTR> CREATE VMD VMD_TNRS232_002 -MODEL "DASware RS232" -VENDOR "ANYtelnet"\ -DVM_ACCESS_POINTS ("/cn=ANYtelnet":PP_TNRS232)\ -DESCRIPTION "For RS232 telnet connection with AAA system"\ -LOG BSTR> CREATE VMD VMD_TNTCPIP_001 -MODEL "DASware TCP/IP" -VENDOR "DASware"\ -DVM_ACCESS_POINTS ("/cn=localhost.dastk":PP_TNTCPIP)\ -DESCRIPTION "For TCP/IP direct connection"\ -LOG BSTR> CREATE VMD VMD_TNOSI_001 -MODEL "DASware OSI" -VENDOR "DASware"\ -DVM_ACCESS_POINTS ("/cn=localhost.dastk":PP_TNTCPIP)\ 4 4 4- - - DASware User Guide 4 4 4 Configuring BASEstar Open -DESCRIPTION "For OSI connection with TSAP DTKOSICLT"\ -LOG Creating Variables Creating Variables Creating Variables This section explains how you can create Device Services variables objects that will be linked to the Device_Data_Points used for exchanging data through a Transport Network. Note that the Datatype associated with these variables drives BASEstar Open in encoding and decoding the data exchanged between BASEstar Open users and Transport Network partner applications. Because the data type of the received data message often differs from the data type of the sent data message, a separate description is provided for the configuration characteristics of a "reception variable" and for those of a variable used to send data messages. Creating Variables for Receive Operations Creating Variables for Receive Operations Creating Variables for Receive Operations To receive data from a Transport Network partner application you can use a Named_Variable or an Unnamed_Variable. The first Named_Variable you define at a given remote VMD is assumed to be the "reception variable", and will be used for read operations only. If no Named_Variables are defined, the first Unnamed_Variable is used. Table 4- lists the attributes you must specify for a 3 correct definition of a reception variable. - - - 4 4 4 Table Table Table 3 3 3: Device Services Reception Variable : Device Services Reception Variable : Device Services Reception Variable Attributes (BASEstar Open) Attributes (BASEstar Open) Attributes (BASEstar Open) Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values -DATATYPE Name of the Datatype used by datatype_name BASEstar Open to decode the received PDU. See Chapter 3 for a description of the allowed Datatypes. notification -SEND This attribute must be set to ALWAYS. This setting directs BASEstar Open to update the value of the linked Device_Data_Point in unsolicited mode. -ACCESS Must be set to READ. access_type -ADDRTYPE Significant for address_type Unnamed_Variables only; it must be set to UNCONSTRAINED. DASware User Guide 5 5 5 - - - 4 4 4 Configuring BASEstar Open -ADDRESS address Significant for Unnamed_Variables only; it can be set to any value. Creating Variables for Send Operations Creating Variables for Send Operations Creating Variables for Send Operations You can define as many Named or Unnamed_Variables associated with the VMD as you need to send data to the partner application. Each of these variables can have a different Datatype, so you can send different types of data to the Transport Network partner application. Table 4 lists the attributes that you must specify -4 for a correct definition of a transmission variable. Table Table Table : Device Services Transmission Variable : Device Services Transmission Variable : Device Services Transmission Variable 4 4 4 - - - 4 4 4 Attributes Attributes Attributes Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values -DATATYPE Name of the Datatype used by datatype_name DASware to encode the sent PDU. See Appendix A for a description of the allowed Datatypes. -ACCESS Must be set to WRITE. access_type -ADDRTYPE Significant for address_type Unnamed_Variables only; it must be set to UNCONSTRAINED. -ADDRESS address Significant for Unnamed_Variables only; it can be set to any value. Creating Data Services Objects Creating Data Services Objects Creating Data Services Objects BASEstar Open users exchange data messages with Transport Network partner applications by means of Device_Data_Points., without taking into consideration communication and device characteristics. Creating Device_Data_Points for Receive Operations Creating Device_Data_Points for Receive Operations Creating Device_Data_Points for Receive Operations Table 4 5 - lists the values you must set to the Device_Data_Point attributes in order to receive data through a Transport Network. 4 4 4- - -6 6 6 DASware User Guide Configuring BASEstar Open Table Table Table 4 4 4- - -5 5 5: Device_Data_Point Attributes for Receive : Device_Data_Point Attributes for Receive : Device_Data_Point Attributes for Receive Operations (BASEstar Open) Operations (BASEstar Open) Operations (BASEstar Open) Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values -VMD_NAME vmd_name Must be set with the name of a Transport Network VMD. -VAR_NAME var_name Must be set with the name of the "reception variable" that is associated with the vmd_name VMD. -DATATYPE Must be set with the name of the datatype_name same Datatype associated with var_name the variable specified by the -VAR_NAME attribute. -DEVICE_ACCESS Must be set to READ to indicate device_access that the linked Device Services variable produces that value of the Device_Data_Point. -UPDATE_POLICY Must be set to UNSOLICITED to update_policy indicate that Data Services updates the cached value of the Device_Data_Point as soon as the value of the linked producer Device Services variable changes (that is, each time BASEstar Open receives data from the Transport Network). Creating Device_Data_Points for Send Operations Creating Device_Data_Points for Send Operations Creating Device_Data_Points for Send Operations - Table 4 lists the values you must set to the 6 Device_Data_Point attributes in order to send data to a Transport Network partner application. - - - 4 4 4 Table Table Table : Device_Data_Point Attributes for Send : Device_Data_Point Attributes for Send : Device_Data_Point Attributes for Send 6 6 6 Operations Operations Operations Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values -VMD_NAME vmd_name Must be set with the name of a Transport Network VMD. -VAR_NAME var_name Must be set with the name of a "Transmission Variable" associated with the vmd_name VMD. -DATATYPE Must be set with the name of the datatype_name same Datatype associated with var_name the variable specified by the -VAR_NAME attribute. -DEVICE_ACCESS Must be set to WRITE to indicate DASware User Guide - - - 4 4 4 7 7 7 Configuring BASEstar Open device_access that Data Services will use the provided value during the send operation of the Device_Data_Point to update the value of the linked Device Services variable (and therefore to cause BASEstar Open to forward a data message to the Transport Network). 4 4 4 8 8 8 DASware User Guide - - - Configuring BASEstar Open DASware User Guide 4 4 4- - -9 9 9 5 5 5 A Complete Example A Complete Example A Complete Example The example contained in this chapter shows you a possible BASEstar configuration that you can use to perform send and receive operations from/to any of the available Transport Networks. DASware User Guide - - - 5 5 5 1 1 1 A Complete Example Example Overview Example Overview Example Overview BASEstar Open being highly configurable, this example shows only one of many possible modes for implementing send and receive operations. ____________________ Send data operations It is assumed that send operations are executed in synchronous mode. According to configuration, each time a user issues a PUT VALUE command, BASEstar Open immediately forwards a data message through to the involved Transport Network. The command only terminates and returns control to the user when the operation has been completed. _______________________ Receive data operations In this example, BASEstar Open updates the value of the Device_Data_Point used for receive operations as soon as it receives data form the Transport Network. The user must keep reading the value of the same Device_Data_Point if he wants to know when its value changes due to reception of a new data message. However, you could change the BASEstar Open configuration in order to receive an Event each time BASEstar Open receives an unsolicited data message from the device; this would allow BASEstar Open users to be notified in an immediate and asynchronous mode of any change occurring on the device. Before Running the Example Before Running the Example Before Running the Example In addition to the general requirements described in Chapter 3 and Chapter 4 of this manual, the complete example requires that: . The Transport Network in use has been configured and is functioning on the system on which the partner application is running. . Transport Network partner application or The device with which you are exchanging data has been activated, can understand the received data and perform the appropriate actions. In the example, the partner application must be able to receive 4 bytes or 40 bytes of data, and must always answer with 4 bytes. In addition, you must: . my_tcpnode Replace with the TCP/IP name of your the BASEstar Open Node. 5 5 5- - -2 2 2 DASware User Guide A Complete Example . Replace my_DAS_id with the identifier of the DAS (that is, the identifier of the Transport Network) you wish to use. Replace . ODS_Entry with the name of the ODS entry that complies with the communication characteristics of the Transport Network in use. DASware User Guide - - -3 3 3 5 5 5 A Complete Example CLI Source CLI Source CLI Source Example 5 1 - shows the CLI commands used to create BASEstar Open objects and to activate the required servers. Example Example Example 5 5 5- - -1 1 1: Creating BASEstar Open Objects : Creating BASEstar Open Objects : Creating BASEstar Open Objects ! --------------------------------------------------- ---------------- ! The example is set up to work with the VOLATILE database, ! but you can easily adapt it to work with the PERMANENT database. ! --------------------------------------------------- ---------------- SET SCOPE VOLATILE ! --------------------------------------------------- ---------------- ! Create Common Services objects. ! --------------------------------------------------- ---------------- CREATE NODE NODE1 -PHYSICAL_NAME "my_tcpnode" CREATE ARRAY_DATATYPE ARRAY_OF_INTEGERS_16\ -NUM_OF_ELEMENTS 10 -DATATYPE INTEGER_32 CREATE PROTOCOL_PROFILE PP_TN\ -APPLPROFID My_DAS_id -MAXPDUSIZE 1024 -LOG CREATE VMD VMD_DASWARE -MODEL "DASware" -VENDOR "DIGITAL"\ -DVM_ACCESS_POINTS ODS_Entry:PP_TN)\ -DESCRIPTION "(VMD for data exhcange)" -LOG CREATE DOMAIN /DOM_DATA CREATE ACTOR /ACT_SERVERS ! --------------------------------------------------- ---------------- ! Create the Application Services objects needed to define both the 5 5 5 DASware User Guide - - -4 4 4 A Complete Example ! Data Services and Device Services servers. ! --------------------------------------------------- ---------------- CREATE PROGRAM /ACT_SERVERS/PRG_DATA\ -PROGRAM_KIND DATA CREATE ACTIVITY /ACT_SERVERS/ACY_DATA\ -PROGRAM /ACT_SERVERS/PRG_DATA -NODES (NODE1)\ -DOMAINS (/DOM_DATA)\ -STARTUP_TIMEOUT 120 -RECOVERY_POLICY NECESSARY CREATE PROGRAM /ACT_SERVERS/PRG_DEVICE\ -PROGRAM_KIND DEVICE CREATE ACTIVITY /ACT_SERVERS\ACY_DEVICE\ -PROGRAM /ACT_SERVERS/PRG_DEVICE -NODES (NODE1)\ -VMDS (/VMD_DASWARE)\ -STARTUP_TIMEOUT 120 -RECOVERY_POLICY NECESSARY ! --------------------------------------------------- ---------------- ! Execute the ACTOR to activate the Data and Device Services servers. ! --------------------------------------------------- ---------------- EXECUTE ACTOR /ACT_SERVERS ! --------------------------------------------------- ---------------- ! Create the Device Services objects. ! You can change the Datatypes associated with the variables to meet ! your application dialogue requirements. ! --------------------------------------------------- ---------------- CREATE NAMED_VAR VMD_DASWARE.VAR_RCV -DATATYPE INTEGER_32\ -SEND ALWAYS -ACCESSMODE READ CREATE NAMED_VAR VMD_DASWARE.VAR_SEND001\ -DATATYPE INTEGER_32\ -ACCESSMODE WRITE CREATE NAMED_VAR VMD_DASWARE.VAR_SEND002\ -DATATYPE ARRAY_OF_INTEGERS_32\ -ACCESSMODE WRITE DASware User Guide - - - 5 5 5 5 5 5 A Complete Example ! --------------------------------------------------- ---------------- ! Create the Data Services objects ! --------------------------------------------------- ---------------- CREATE DEVICE_DATA_POINT DP_RECEIVE\ -VMD_NAME VMD_DASWARE\ -VAR_NAME VAR_RCV -VAR_CLASS NAMED\ -DATATYPE INTEGER_32\ -DEVICE_ACCESS READ -UPDATE_POLICY UNSOLICITED -DEFAULT_VALUE 0 CREATE DEVICE_DATA_POINT DP_SEND001\ -VMD_NAME VMD_DASWARE\ -VAR_NAME VAR_SEND001 -VAR_CLASS NAMED \ -DATATYPE INTEGER_32\ -DEVICE_ACCESS WRITE CREATE DEVICE_DATA_POINT DP_SEND002 -VMD_NAME VMD_DASWARE\ -VAR_NAME VAR_SEND002 -VAR_CLASS NAMED \ -DATATYPE INTEGER_32\ -DEVICE_ACCESS WRITE Exchanging Data through the Transport Network Exchanging Data through the Transport Network Exchanging Data through the Transport Network You can now receive and send data through the Transport Network. A possible operation sequence that uses the objects previously created is described in Example 5 2 - . Example Example Example - - -2 2 2 5 5 5 : Exchanging Data through the Transport : Exchanging Data through the Transport : Exchanging Data through the Transport Network Network Network BSTR> PUT VALUE DEVICE_DATA_POINT DP_SEND001 (Integer 32) : 345 ......... Keep reading until you receive the '' .. '' answer! ...... ......... BSTR> GET VALUE DEVICE_DATA_POINT DP_RECEIVE 12 5 5 5 DASware User Guide - - -6 6 6 PART II PART II PART II Exchanging Data through Transport Networks Using the Exchanging Data through Transport Networks Using the Exchanging Data through Transport Networks Using the DEComni API DEComni API DEComni API This part provides an overview of the DEComni API components that are involved in DASware, and describes how DEComni applications can exchange data through the supported Transport Networks. It also explains how you must configure the DEComni API to work with DASware. 6 6 6 Overview Overview Overview This chapter describes the DEComni environment components that are involved when DEComni API applications exchange data with Transport Networks partner applications. This chapter also provides an overview of the operations a DEComni API application can perform using the features provided by DASware. By calling the appropriate procedures, a DEComni API application can send data to, and receive data from a remote partner application. DASware User Guide 1 1 1 6 6 6- - - Overview DEComni Environment Components DEComni Environment Components DEComni Environment Components Figure 6 1 shows the components that are involved - when DEComni API applications send and receive data through the supported Transport Networks. Figure Figure Figure 6 6 6 : DEComni API Environment Components : DEComni API Environment Components : DEComni API Environment Components - - -1 1 1 DEComni DEComni DEComni The DEComni API provides applications with a unique set of operations for device-independent access to any type of device or network. This device- independent approach to device connectivity is possible because each device is modeled as an MMS Virtual Manufacturing Device (VMD). A VMD is associated with a connection that allows you to communicate with Transport Network partner applications. A variable object corresponds to data item exchanged with the partner application. The DEComni API 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 component of the DEComni API that allows you to 6 6 6 2 2 2 - - - DASware User Guide Overview define Transport Network-specific addressing information. 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 6 6 6 3 3 3 - - - Overview Exchanging Data Through the Transport Network Exchanging Data Through the Transport Network Exchanging Data Through the Transport Network This section describes what happens when a DEComni API application sends and receives data through a Transport Network. It is assumed that the Transport Network connection has been established successfully. Figure 6 2 shows the definitions and the API - procedures a DEComni API application must use to exchange data with a Transport Network partner application. Figure Figure Figure : DEComni Definitions and API Procedures : DEComni Definitions and API Procedures : DEComni Definitions and API Procedures 2 2 2 6 6 6- - - Omni API VAR 1 omni_get_indications Omni API InforeportVALUE Inforeport Remote VMD omni_get_value VALUE _Reception Variable_ DAS RECEIV SEND P Omni API VAR 2 omni_put_value O.K. Writing Data through the Transport Network Writing Data through the Transport Network Writing Data through the Transport Network To send a data messages to a Transport Network partner application, an application must call the omni_put_value[_a] procedure, by specifying the handle of a named or an unnamed variable associated with a VMD that has been configured for the desired Transport Network. The omni_put_value[_a] call completes after the PDU has been delivered to the Transport Network Provider. On reception of the user data, the DAS performs the following operations: 1.Obtains the data to be sent through the Transport Network from the application buffer, and encodes it according to the Datatype associated with the used variable (see Section 7.3). 6 6 6 - - -4 4 4 DASware User Guide Overview 2. Depending on the Transport Network in use, adds specific protocol-specific information to the outgoing encoded data (see - Table 6 for details). 1 3. Forwards the encoded data as a Transport Network 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. ________________________________ ________________________________ ________________________________________________ ________________ ________________ 6 6 6- - - Table Table Table : Protocol-Specific Information Added to : Protocol-Specific Information Added to : Protocol-Specific Information Added to 1 1 1 Outgoing Encoded Data (DEComni API) Outgoing Encoded Data (DEComni API) Outgoing Encoded Data (DEComni API) Transport Transport Transport Protocol-Specific Information Protocol-Specific Information Protocol-Specific Information Network Network Network RS 232 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. 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. OSI Transport No protocol-specific information is added. Receiving Data from the Transport Network Receiving Data from the Transport Network Receiving Data from the Transport Network To receive data from the Transport Network, an application must: DASware User Guide 5 5 5 6 6 6- - - Overview 1.Call the omni_get_indications[_a] procedure, and specify a VMD that has been configured for the Transport Network. 2.When the omni_get_indications[_a] procedure returns an Inforeport indication, call the omni_get_value[a] procedure on the same VMD, to obtain the data received from the Transport Network. When receiving a message from the Transport Network, DASware generates an Information report that causes the completion of the omni_get_indications[_a] procedure call. The Inforeport indication returns the handle of the "reception variable" with which DASware has associated the received data. A "reception variable" is the first named variable that has been created for a given VMD. This variable is always used by DASware to return the data received from the Transport Network. If no Named_Variable has been defined, the first Unnamed_Variable is used. If there is not any variable associated with the VMD, any data DASware receives from the Transport Network are lost (and the omni_get_indications[_a] procedure returns an error). Data received from the Transport Network in one message is automatically interpreted by the device access software according to the Datatype associated with the "reception variable". On reception of a PDU from the Transport Network, (for example, an RS 232 data stream or a TCP/IP message), the DAS performs the following operations: 1.Removes any protocol-specific information from the data (see Table 6 2 - for details). 2.Decodes the received PDU according to the Datatype associated with the reception variable, as explained in Section 7.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 received bytes exceeds that required to meet the Datatype, the exceeding bytes are lost. 6 6 6 6 6 6 DASware User Guide - - - Overview _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ Data is received according to the BIGENDIAN mode, that is the MSB (Most Significant Byte) is received first. ________________________________ ________________________________ ________________________________________________ ________________ ________________ Table Table Table 6 6 6- - -2 2 2: Protocol-Specific Information Removed from : Protocol-Specific Information Removed from : Protocol-Specific Information Removed from Incoming Data (DEComni API) Incoming Data (DEComni API) Incoming Data (DEComni API) Transport Transport Transport Protocol-Specific Information Protocol-Specific Information Protocol-Specific Information Network Network Network RS 232 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. 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. OSI Transport No protocol-specific information is removed. DASware User Guide 7 7 7 - - - 6 6 6 Overview Encoding and Decoding Transport Network Data Encoding and Decoding Transport Network Data Encoding and Decoding Transport Network Data Table 6 3 shows the coding (and decoding) rules used - by DEComni when sending and receiving data through a Transport Network. The number of bytes involved in a send or receive operation depends on the MMS type associated with the variable in use, therefore: Table Table Table 3 3 3: Coding/Decoding Data According to MMS : Coding/Decoding Data According to MMS : Coding/Decoding Data According to MMS 6 6 6- - - Types (DEComni API) Types (DEComni API) Types (DEComni API) Data Type Data Type Data Type Exchanged as Exchanged as Exchanged as omni_c_mmstype_boole 1 byte an omni_c_mmstype_bit_s n ( + 7)/ 8 bytes where is n tr the number of bits in the string omni_c_mmstype_integ 1, 2 or 4 bytes, depending on er omni_c_symbol_size, that specifies the size of the variable (8, 16, or 32 bits) omni_c_mmstype_unsig 1, 2 or 4 bytes, depending on ned omni_c_symbol_size, that specifies the size of the variable (8, 16, or 32 bits) omni_c_mmstype_float 4 bytes (IEEE float format) ing_point omni_c_mmstype_real Not supported omni_c_mmstype_octet n bytes (as returned by _str sizeof()) omni_c_mmstype_visib bytes ( as returned by n le_str strlen() if varying or as returned by sizeof() otherwise) omni_c_mmstype_gener Not supported alized_time omni_c_mmstype_binar Not supported y_time omni_c_mmstype_bcd Not supported 6 6 6 DASware User Guide - - -8 8 8 7 7 7 Configuring DEComni Configuring DEComni Configuring DEComni You must configure DEComni in order to allow DEComni API applications to exchange data with partner application through any of the Transport Networks supported by DASware. Configuring DEComni means creating the required definitions using the following API procedures: . omni_define omni_get_definition . omni_modify_definition . As an alternative, you can configure the DEComni API using the ODF facility (if this is available on your platform). To configure the DEComni API for DASware, you must: Register the appropriate entries in the ODS 1. database. ODS entries define the parameters that are specific to the Transport Network currently in use. Set the application profile for the DAS module in 2. use. Create the required DEComni VMD and Variable 3. definitions. _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ For an explanation of the parameters regarding the DEComni API definitions whose values are not specified here, refer to the DEComni API and DEComni MMS User Guide for your platform. ________________________________ ________________________________ ________________________________________________ ________________ ________________ DASware User Guide 7 7 7- - -1 1 1 Configuring DEComni Registering ODS Entries Registering ODS Entries Registering ODS Entries You must create an ODS entry containing Transport Network-specific information for each Transport Network partner application with which you wish to exchange data. See Appendix A for details. Setting the Application Profile Setting the Application Profile Setting the Application Profile An application must invoke the omni_set_application_profile procedure to specify the appropriate application profile. This ensures that the definitions created after this procedure is called, are associated with the specified device access software. Table 7 lists the available 1 - application profiles. Table Table Table 1 1 1: DEComni API Application Profiles for DAS : DEComni API Application Profiles for DAS : DEComni API Application Profiles for DAS - - - 7 7 7 Modules Modules Modules DASware Module DASware Module DASware Module Application Profile Constant Application Profile Constant Application Profile Constant RS 232 omni_c_app_profile_dtk232 TCP/IP omni_c_app_profile_dtktcp OSI Transport omni_c_app_profile_dtkosi The following example shows how you invoke the omni_set_application_profile procedure for TCP/IP. status=omni_set_application_profile (omni_c_app_profile_dtktcp) Creating VMD Definitions Creating VMD Definitions Creating VMD Definitions A DASware VMD models a Transport Network connection. A DASware VMD is mainly characterized by the omni_c_attr_appl_simple_name attribute that must specify an appropriate ODS entry for the network you wish to use. Table 7-2 lists all the mandatory attributes that you must specify for a correct definition of a DASware VMD. Table Table Table 2 2 2 7 7 7- - - : VMD Attributes (DEComni API) : VMD Attributes (DEComni API) : VMD Attributes (DEComni API) Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values omni_c_attr_name The name of the VMD definition. 7 7 7 2 2 2 - - - DASware User Guide Configuring DEComni omni_c_attr_appl_s The name of an ODS entry that imple_name contains the addressing information required to access the Transport Network partner application. omni_c_vmd_max_seg The maximum length of the ment Protocol Data Unit (PDU) exchanged on the Transport Network, including the length of any headers and trailers added by DASware. Creating Variable Definitions Creating Variable Definitions Creating Variable Definitions To exchange data with a Transport network partner application, you can use both named or unnamed variables. The first named variable you define for a given VMD is assumed to be the "reception variable" and it will be used for receive operations only. If no named variables are defined, the first unnamed variable is used. You can define as many named or unnamed variables as you need that are associated with the VMD to send data to the partner application. Each of these variables can have a different data type, which allows you to send different types of data to the Transport Network partner application. 7 7 7- - - Table Table Table 3 3 3: Variable Attributes (DEComni API) : Variable Attributes (DEComni API) : Variable Attributes (DEComni API) Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values omni_c_attr_app_ty Name of the application type pe_descr used by the DAS to decode (encode) the received (sent) PDU. The associated MMS type must comply with those shown in Chapter 7. omni_c_attr_addres Only significant for s_type Unnamed_Variables; it must be set to unconstrained. omni_c_attr_addres Only significant for s_string Unnamed_Variables; it can be set to any value. DASware User Guide 7 7 7 3 3 3 - - - 8 8 8 Programming Programming Programming This chapter describes how you can use the DEComni API procedures to write a DEComni application that exchanges data with partner applications through the supported Transport Networks. Bear in mind the following considerations when using the API procedures to write DASware applications: . General syntax and programming rules, described in the DEComni API and DEComni MMS User Guide for your platform, are also valid when the API procedures are used in the DASware context. When using the . DEComni API and DEComni MMS User Guide for your platform, ignore the descriptions referring to services and functions that are not supported by the DASware modules. DASware User Guide 8 8 8 1 1 1 - - - Programming Programming Programming DEComni API Procedures for Data Exchange DEComni API Procedures for Data Exchange DEComni API Procedures for Data Exchange Table 8 1 lists the DEComni API procedures that - applications can invoke to send data to, and receive data from, partner applications.. Table Table Table 8 8 8 : DEComni API Procedures for Data Exchange : DEComni API Procedures for Data Exchange : DEComni API Procedures for Data Exchange - - -1 1 1 Procedure Name Procedure Name Procedure Name Description Description Description omni_abort_[a] Performs the forced closure of a Transport Network connection. omni_conclude_[a] Performs the forced closure of a Transport Network connection. (It behaves like the omni_abort_[a] procedure). omni_connect_[a] Opens a Transport Network connection. omni_get_indicatio Obtains connection-related and ns_[a] Inforeport indications (data received from the Transport Network). omni_put_value_[a] Sends data to the Transport Network. It is an unconfirmed operation, that is the procedure completes as soon as the data have been delivered to the Transport Network Opening and Closing a Transport Network Connection Opening and Closing a Transport Network Connection Opening and Closing a Transport Network Connection To open a Transport Network connection, a DEComni API application must call the omni_connect_[a] procedure, and specify a VMD that has been configured appropriately. The information associated with ODS specifies the addressing information DEComni uses to open the specific Transport Network connection. To close a Transport Network connection, an application can use the omni_conclude_[a] or the omni_abort_[a] procedure. Both these procedures cause a forced closure of the Transport Network connection. The application should use the omni_get_indications_[a] procedure to monitor any incoming omni_c_ind_abort indications that notify that the connection has been terminated in a forced way for any reason (for example, by the partner or by the Transport Network itself). 8 8 8 DASware User Guide 2 2 2 - - - Programming Programming Programming Sending Data through the Transport Network Sending Data through the Transport Network Sending Data through the Transport Network To send data through the Transport Network, an application must call the omni_put_value[_a] procedure, and specify the handle of a named or an unnamed variable associated with a VMD that has been configured for the desired Transport Network. The omni_put_value[_a] returns control to the application as soon as DEComni has delivered the message to the Transport Network Provider. The operations performed by DASware and the output sent to the Transport Network have been described in Chapter 7. Receiving Data from the Transport Network Receiving Data from the Transport Network Receiving Data from the Transport Network To receive data from the Transport Network, an application cannot directly call the omni_get_value_[a] procedure, but it must first call the omni_get_indications[_a] procedure. This because DASware modules generate an Inforeport each time they receive a message from the Transport Network Provider. Thus, an application that wants to wait for data coming from the Transport Network, must call the omni_get_indications[_a] procedure, and specify a VMD that has been configured for that Transport Network. When the omni_get_indications[_a] procedure returns control to the application with an omni_c_ind_info_report indication, the application must issue the omni_get_value procedure to get the value of the "reception variable". (Remember that the returned indication specifies a context that refers to the "reception variable".) The operations performed by the DAS when data is received from the Transport Network have been described in Chapter 7. DASware User Guide 8 8 8 3 3 3 - - - PART III PART III PART III Appendices Appendices Appendices A A A ODS Entry Attributes for DASware ODS Entry Attributes for DASware ODS Entry Attributes for DASware This appendix describes the ODS attributes (and their associated values) that allow you to create the ODS entries required by each Transport Network supported by DASware. An ODS entry contains the addressing parameters needed for the selected Transport Network, and must be specified in any VMD definitions that are used to access that Transport Network. The number of ODS entries you must create for a given Transport Network depends on your needs and on the protocol characteristics of the Transport Network itself. The information provided in this appendix is valid when using the DASware features either through the BASEstar Open services or the DEComni API. For details on the use of the ODS CLI, refer to the DEComni documentation included in your BASEstar Open documentation kit. DASware User Guide 1 1 1 - - - A A A ODS Entry Attributes for DASware Creating ODS Entries for the RS 232 Transport Network Creating ODS Entries for the RS 232 Transport Network Creating ODS Entries for the RS 232 Transport Network An RS 232 connection can be based on direct connection, LAT or Telnet port. Through Direct Connection or LAT Through Direct Connection or LAT Through Direct Connection or LAT Table A lists the class, the valid values and an -1 explanation for each ODS attribute. Table Table Table : Values of ODS Attributes for RS 232 : Values of ODS Attributes for RS 232 : Values of ODS Attributes for RS 232 - - -1 1 1 A A A Transport Network Transport Network Transport Network Attribute Attribute Attribute Description and Allowed Values Description and Allowed Values Description and Allowed Values oc Identifier of the ODS object class. Must be set to DTK232. portname Name of the communication port. Examples of valid values are tty00, TT00, LTA100 and COM1. baudrate Any valid baud rate supported by the Operating System and the hardware interface. Examples of valid values are 1200 and 9600. charlen Number of data bits. Allowed values are 5, 6, 7 and 8. stopbit Number of stop bits. Allowed values are 1 and 2. prtycheck Parity. Allowed values are NONE, ODD or EVEN. flowctrl Flow control. Allowed values are NONE, HW (standing for RTS/CTS) and SW (standing for XON/XOFF). modem Modem presence. Allowed values are 0 (modem not present, direct connection), and 1 (modem present, port handles modem signal and handshaking). stationid Station ID for multipoint connections. Allowed values are 0, 1-255. lev7conn Specifies if the connection is handled with messages at application level. Must be set to 0 because DASware does not exchange messages for connection at application level. rsptimeout Timeout, expressed in seconds, DASware User Guide - - -2 2 2 A A A ODS Entry Attributes for DASware for the reception of the response to a confirmed service, after which the service is terminated with failure. Not significant DASware. Example A-1 shows the configuration file commands that are used to create ODS registrations. Example Example Example : ODS Entries for RS 232 Direct Connection : ODS Entries for RS 232 Direct Connection : ODS Entries for RS 232 Direct Connection - - -1 1 1 A A A and LAT and LAT and LAT reg dir name "/cn=OSFdirect" attr "/oc=DTK232/lev7conn=0/portname=tty00 /baudrate=9600/charlen=8/stopbit=1/prtycheck=NONE/flo wctrl=NONE/modem=0" reg dir name "/cn=OSFlat" attr "/oc=DTK232/lev7conn=0/portname=tty08 /baudrate=9600/charlen=8/stopbit=1/prtycheck=NONE/flo wctrl=NONE/modem=0" reg dir name "/cn=VMSdirect" attr "/oc=DTK232/lev7conn=0/portname=TT00 /baudrate=9600/charlen=8/stopbit=1/prtycheck=NONE/flo wctrl=NONE/modem=0" reg dir name "/cn=VMSlat" attr "/oc=DTK232/lev7conn=0/portname=LTA100 /baudrate=9600/charlen=8/stopbit=1/prtycheck=NONE/flo wctrl=NONE/modem=0" reg dir name "/cn=WNTdirect" attr "/oc=DTK232/lev7conn=0/portname=COM1 /baudrate=9600/charlen=8/stopbit=1/prtycheck=NONE/flo wctrl=NONE/modem=0" Through Telnet Through Telnet Through Telnet - Table A 2 lists the class, the valid values and an explanation for each ODS attribute. DASware User Guide A A A 3 3 3 - - - ODS Entry Attributes for DASware Table Table Table A A A 2 2 2: ODS Attributes for the RS 232 Transport : ODS Attributes for the RS 232 Transport : ODS Attributes for the RS 232 Transport - - - Network (Telnet) Network (Telnet) Network (Telnet) Attribute Attribute Attribute Description and Allowed Values Description and Allowed Values Description and Allowed Values oc Identifier of the ODS object class. Must be set to DTK232. portname Name of the server port, expressed in the form @server.ip.address:port baudrate Any valid baud rate supported by the Operating System and the hardware interface. Examples of valid values are 1200 and 9600. charlen Number of data bits. Allowed values are 5, 6, 7 and 8. stopbit Number of stop bits. Allowed values are 1 and 2. prtycheck Parity. Allowed values are NONE, ODD and EVEN. flowctrl Flow control. Allowed values are NONE, HW (standing for RTS/CTS) and SW (standing for XON/XOFF). modem Modem presence. Allowed values are 0 (modem not present, direct connection), and 1 (modem present, port handles modem signal and handshaking). stationid Station ID for multipoint connections. Allowed values are 0, 1-255. lev7conn Specifies if the connection is handled with messages at application level. Must be set to 0 because the DASware modules do not exchange messages for connection at application level. rsptimeout Timeout, expressed in seconds, for the reception of the response to a confirmed service, after which the service is terminated with failure. Not significant for DASware. Example A 2 - shows the configuration file commands that are used to create ODS registrations. DASware User Guide 4 4 4 - - - A A A ODS Entry Attributes for DASware Example Example Example A A A 2 2 2: ODS Entries for RS 232 Telnet : ODS Entries for RS 232 Telnet : ODS Entries for RS 232 Telnet - - - reg dir name "/cn=ANYtelnet" attr "/oc=DTK232/lev7conn=0/portname=@127.0.0.1:2001/baudr ate=9600/charlen=8/ stopbit=1/prtycheck=NONE/flowctrl=NONE/modem=0/statio nid=1" DASware User Guide A A A 5 5 5 - - - ODS Entry Attributes for DASware Creating ODS Entries for the TCP/IP Transport Network Creating ODS Entries for the TCP/IP Transport Network Creating ODS Entries for the TCP/IP Transport Network Table A 3 lists the class, the valid values and an - explanation for each ODS attribute. Table Table Table A A A- - -3 3 3: ODS Attributes for the TCP/IP Transport : ODS Attributes for the TCP/IP Transport : ODS Attributes for the TCP/IP Transport Network Network Network Attribute Attribute Attribute Description and Allowed Values Description and Allowed Values Description and Allowed Values oc ODS object class identifier. Must be set to DTKTCP. netaddress The IP address of the target system. portnumber The TCP port number of the serving application on the target system. lev7conn Specifies if the connection is handled with messages at application level. Must be set to 0 because DASware does not exchange messages for connection at application level. rsptimeout Timeout, expressed in seconds, for the reception of the response to a confirmed service, after which the service is terminated with failure. Not significant for DASware. Example A-3 shows the configuration file commands that are used to create ODS registrations. Example Example Example A A A- - -3 3 3: ODS Entries for TCP/IP : ODS Entries for TCP/IP : ODS Entries for TCP/IP reg dir name "/cn=localhost.dastk" attr\ "/oc=DTKTCP/lev7conn=0/netaddress=127.0.0.1/portnumbe r=9999" DASware User Guide - - -6 6 6 A A A ODS Entry Attributes for DASware Creating ODS Entries for the OSI Transport Transport Network Creating ODS Entries for the OSI Transport Transport Network Creating ODS Entries for the OSI Transport Transport Network Table A-4 lists the class, the valid values and an explanation for each ODS attribute. A A A- - - Table Table Table 4 4 4: ODS Attributes for the OSI Transport : ODS Attributes for the OSI Transport : ODS Attributes for the OSI Transport Transport Network Transport Network Transport Network Attribute Attribute Attribute Description and Allowed Values Description and Allowed Values Description and Allowed Values oc ODS object class identifier. Must be set to DTKOSI. netaddress The OSI hexadecimal address of the target system. On VMS systems, the address must be prefixed by the name of a TEMPLATE. tsap The Transport Service Access Point (TSAP) on the target system. lev7conn Specifies if the connection is handled with messages at application level. Must be set to 0 because DASware does not exchange messages for connection at application level. rsptimeout Timeout, expressed in seconds, for the reception of the response to a confirmed service, after which the service is terminated with failure. Not significant for DASware. Example A 4 shows the configuration file commands - that are used to create ODS registrations. Example Example Example : ODS Entries for the OSI Transport : ODS Entries for the OSI Transport : ODS Entries for the OSI Transport 4 4 4 A A A- - - Network Network Network reg dir name "/cn=DASTK:osf.system" attr\ "/oc=DTKOSI/lev7conn=0/netaddress=49002E08002B08002B/ tsap=DTKOSISRV" reg dir name "/cn=DASTK:vms.system" attr\ "/oc=DTKOSI/lev7conn=0/netaddress=MYTEMPLATE%49002EAA 0004AA000421/tsap=DTKOSICLT" DASware User Guide A A A 7 7 7 - - - ODS Entry Attributes for DASware DASware User Guide A A A- - -8 8 8 Index Index Index selecting servers, 4-2 A A A Configuring the DEComni API creating ODS entries, 7-2 Accessing a device creating variable through BASEstar Open, 3 2 - definitions, 7-2 through the DEComni API, creating VMD definitions, 2 6- 7-2 Accessing DASware overview, 7 1 - through the DEComni API, setting the application 1 - 6 profile, 7 2 - Creating ODS entries B B B for OSI Transport Network, -5 A BASEstar Open components for RS 232 Transport Data Services, 3 2 - Network, A-2 Transport Network for TCP/IP Transport software, 3 3 - Network, A-4 BASEstar Open configuration creating Data Services D D D objects, 4-5 creating DASware, 1-1; 1-2 Device_Data_Points, 4 5 - access through the DEComni creating ODS entries, 4 2; - API, 6-1 1 - A definition, 1 1 - example, 5 1 - installation on Digital selecting servers, 4 2 - UNIX systems, 2 2 - installation overview, 2-1 C C C supported platforms, 1-2 supported Transport Configuring BASEstar Open Networks, 1 2 - creating Data Services Data Services objects, 4-5 role in BASEstar Open, 3-2 creating Data type, 6-6 Device_Data_Points, 4 5 - DEComni API, 6-6 creating ODS entries, 4-2; mapping incoming data, -1 A -6 6 example, 5-1 DASware User Guide 1 1 1 Index- Index- Index- mapping outgoing data, 6-6 Outgoing data, 6-4; 6-6 DEComni API Configuration data type mapping, 6 6 - creating ODS entries, 7-2 DEComni API, 6 -6 -4; 6 creating variable protocol-specific definitions, 7 2 - information, 6-4 creating VMD definitions, -2 7 P P P overview, 7 1 - setting the application Platforms profile, 7 2 - supported by DASware, 1 2 - DEComni components ODS, 6 2 - R R R Transport Network software, 6 2 - Receiving data Device access through the DEComni API, through BASEstar Open, 3 2 - 4 6- through the DEComni API, Reception variable, 6-4 2 6- definition of, 6 4 - Device access software, 1 1 - T T T I I I Transport Network software Incoming data, 6 6 - role when using DASware data type mapping, 6 6 - from BASEstar Open, 3-3 DEComni API, 6 6 - role when using DASware Installing DASware from the DEComni API, 6-2 Digital UNIX platform, 2-2 Transport Networks supported by DASware, 1-2 O O O V V V ODS entries creation for OSI Transport Network, Variable attributes -5 A access through the DEComni for RS 232 Transport API, 7 3 - Network, A 2 - VMD attributes for RS232 access through the DEComni using a direct API, 7-2 connection, A-2 using LAT, A 2 - W W W using Telnet, A 3 - for TCP/IP Transport Writing data Network, A 4 - through the DEComni API, ODS entry format for 3 - 6 DASware, A 1 - DASware User Guide Index- Index- Index- 2 2 2