BASEstar Open Device Connectivity Device Access Software for Siemens 3964 User Guide Order Number: AA-QT1RA-TE February 1996 February 1996 February 1996 This document describes the Device Access Software (DAS) for Siemens 3964 which allows BASEstar Open users and DEComni API applications to exchange data with Siemens devices supporting the Siemens 3964 protocols. 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: 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. Index- Index- Index-2 2 2 Device Access Software for Siemens 3964 User Guide Table of Contents Table of Contents Table of Contents iii iii iii 1 Introduction 1 Introduction 1 Introduction Communicating with Siemens 3964 Devices................. 1 - 1 Features of the Digital DAS for Siemens 3964............ 2 - 1 What's Next?............................................ 3 1- 2 Installing the DAS for Siemens 3964 on Your Platform 2 Installing the DAS for Siemens 3964 on Your Platform 2 Installing the DAS for Siemens 3964 on Your Platform Installation on Digital UNIX Systems..................... 2 - 2 Preparing for DAS for Siemens 3964 installation ....... 2 - 2 Installing the DAS for Siemens 3964 ................... 4 2- Files installed on your system ........................ 4 - 2 PART I Communicating with Siemens 3964 Devices Using BASEstar PART I Communicating with Siemens 3964 Devices Using BASEstar PART I Communicating with Siemens 3964 Devices Using BASEstar Open Open Open 3 Overview 3 Overview 3 Overview BASEstar Open Environment Components..................... 2 - 3 Exchanging Data Messages with a Siemens 3964 Device (3964[R] Protocol)................................................ 4 - 3 Sending Data .......................................... 4 - 3 Receiving Data ........................................ 4 3- Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Protocol)................................................ 6 - 3 Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) 7 - 3 . Datatypes and Memory Block Sizes......................... 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......................... 2 - 4 Creating Protocol_Profiles ............................ 2 - 4 Creating VMDs ......................................... 3 4- Creating Variables .................................... 5 - 4 Creating Data Services Objects........................... 6 - 4 Creating Device_Data_Points for Communication through the 3964[R] Protocol ......................................4-6 Creating Device_Data_Points for Communication through the 3964[R]_512 Protocol ..................................4 7 - 5 Examples 5 Examples 5 Examples Example 1: Exchanging Data Through the 3964[R] Protocol.. 2 5- Example Overview ...................................... - 5 2 Before Running the Example ............................ 2 5- CLI Source ............................................ - 5 2 Example 2: Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Protocol)................................ 5 . 5 - Example Overview ...................................... - 5 5 Before Running the Example ............................ -5 5 CLI Source ............................................ - 5 5 iii iii iii Example 3: Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) ................................................5-7 Example Overview ................................ 5 ...... 7 - Before Running the Example ............................5 7 - CLI Source ............................................5 7 - PART II Communicating with Siemens 3964 Devices Using the PART II Communicating with Siemens 3964 Devices Using the PART II Communicating with Siemens 3964 Devices Using the DEComni API DEComni API DEComni API 6 Overview 6 Overview 6 Overview DEComni Environment Components ...........................6-2 Exchanging Data Messages with a Siemens 3964 Device (3964[R] Protocol) ................................................6 3 - Receiving Data ................................ 6 ........ 3 - Sending Data Messages ................................ 6 . 4 - Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Protocol) ................................................6 4 - Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) 6 . -5 MMS Types and Siemens 3964 Memory Block Sizes ............6 5 - 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 a VMD for Communication Through the 3964[R] Protocol ..............................................7 2 - Creating a VMD for Communication Through the 3964[R]_RK512 Protocol ..............................................7 3 - Creating Variable Definitions ............................7 3 - Creating Variables for Communication Through the 3964[R] Protocol ..............................................7 3 - Creating Variables for Communication Through the 3964[R]_RK512 Protocol ................................7-3 8 Programming 8 Programming 8 Programming Programming with the 3964[R] Protocol ....................8 2 - Opening a Connection ..................................8 2 - Sending Data Messages ................................ 8 . -2 Receiving Data Messages ...............................8 2 - Programming with the 3964[R]_RK512 Protocol ..............8 3 - Opening and Closing a Connection ......................8-4 Reading and Writing Memory Blocks of a Siemens Device .8 4 - Fulfilling Requests for an Emulated Device ............8-4 PART III Appendices PART III Appendices PART III Appendices A ODS Entry Attributes for the Siemens 3964 Protocol A ODS Entry Attributes for the Siemens 3964 Protocol A ODS Entry Attributes for the Siemens 3964 Protocol Creating ODS Entries for the Siemens 3964 Protocol A ...... 2 - Configuring a LAT Port ................................ A .. 3 - iv OpenVMS Platform ..................................... 3 - A Digital UNIX Platform ................................ 3 A- B BASEstar Open Datatype Sizes B BASEstar Open Datatype Sizes B BASEstar Open Datatype Sizes C DEComni API MMS Type Sizes C DEComni API MMS Type Sizes C DEComni API MMS Type Sizes D Siemens 3964 Memory Addresses D Siemens 3964 Memory Addresses D Siemens 3964 Memory Addresses E DEComni API Network IOSB Messages E DEComni API Network IOSB Messages E DEComni API Network IOSB Messages v Figures Figures Figures Figure 1-1: Software Components for Siemens 3964 Communication ............................................1 1 - - Figure 1 2: Communicating with Siemens 3964 Devices ......1 2 - - Figure 3 1: BASEstar Open Environment Components 3 ......... 2 - - Figure 3 2: BASEstar Open Objects and Operations (3964[R] Protocol) ................................................3 4 - - Figure 3 3: Accessing the Memory of a Siemens 3964 Device Through BASEstar Open ................................ 3 .... 6 - - Figure 3 4: Emulating a Siemens 3964 Device Through BASEstar ................................ Open .....................3 7 - - Figure 6 1: DEComni Environment Components ...............6 2 - - Figure 6 2: DEComni Definitions and API Procedures (3964[R] Protocol) ................................................6 3 - - Figure 6 3: Accessing the Memory of a Siemens 3964 Device Through the DEComni API ................................ 6 .. 4 - - Figure 6 4: Emulating a Siemens 3964 Device Through the DEComni API ..............................................6 5 - Tables Tables Tables 1: Supported Siemens 3964 Protocols - Table 1 ..............1 2 - 1: Prerequisite Software for Digital UNIX (BASEstar - Table 2 Open Environment) ................................ 2 ........ 3 - 2: Prerequisite Software for Digital UNIX (DEComni - Table 2 Environment) .............................................2 3 - 1: Protocol_Profile Attributes - Table 4 ...................4 2 - 2: VMD Attributes - Table 4 ................................4-3 3: Reception Variable Attributes (3964[R] Protocol) - Table 4 4 5 - 4: Transmission Variable Attributes (3964[R] - Table 4 Protocol) ................................................4-5 5: Variable Attributes (3964[R]_RK512 Pro - Table 4 4 .. tocol) -6 6: Device_Data_Point Attributes for Receive - Table 4 Operations (3964[R] Protocol) ............................4-6 7: Device_Data_Point Attributes for Send Operations - Table 4 (3964[R] Protocol) ................................ 4 ....... -7 8: Device_Data_Point for Send and Receive Operations - Table 4 (3964[R]_512 Protocol) ................................ 4 ... 7 - 1: DEComni Application Profiles Table 7- ..................7 2 - Table 7-2: DEComni VMD Attributes ........................7-2 3: DEComni Variables Attributes - Table 7 ..................7-3 - Table 8 1: DEComni API Procedures for Data Exchange (3964[R] Protocol) ................................................8-2 Table 8 2: DEComni API Procedures for Data - Exchange (3964[R]_512 Protocol) ...................................8-3 1: ODS Entry Attributes for the Siemens 3964 Table A- Protocols ................................................A-2 1: BASEstar Open Simple Datatype Sizes - Table B ...........B 1 - -1: DEComni API MMS Type Sizes Table C ....................C 1 - Table D 1: DEComni - Attribute Values BlockType ............D-1 Examples Examples Examples Example 4-1: Creating Device Services Protocol_Profiles 4 .. -3 vi Example 4-2: Creating a Device Services VMD (3964[R] Protocol)................................................ 4 4- Example 4 3: Creating Device Services VMDs (3964[R]_RK512 - Protocol)................................................ 4 - 4 Example 5 1: Creating BASEstar Open O - bjects (3964[R] Protocol)................................................ 2 - 5 Example 5-2: Exchanging Data with a Siemens 3964 Device (3964[R] Protocol)....................................... 4 - 5 Example 5 3: Creating BASEstar Open Objects (3964[R]_RK512 - Protocol)................................................ 5 - 5 Example 5 4: Reading and Writing the Device Memory - (3964[R]_RK512 Protocol)................................ 6 - .5 Example 5 5: Parameter File (3964[R]_RK512 Protocol) - ..... 7 5- Example 5 6: Emulating a Siemens 3964 Device (3964[R]_RK512 - Protocol)................................................ - 5 7 Example 5-7: Reading and Writing the Emulated Device Memory (3964[R]_RK512 Protocol)................................ 5- . 9 Example A 1: ODS Entry for LAT - Port...................... - A 2 vii Preface Preface Preface This document describes how to install and use the Digital Device Access Software (DAS) for Siemens 3964, the software that allows BASEstar Open users and DEComni API applications to exchange data with Siemens 3964 devices supporting the Siemens 3964 protocols. Multiplatform Applicability Multiplatform Applicability Multiplatform Applicability Most of the information in this manual applies regardless of the operating system platform on which the DAS for Siemens 3964 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 the DAS for Siemens 3964 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 with Siemens 3964 devices. Structure of this Document Structure of this Document Structure of this Document This document is organized as follows: . Chapter 1 introduces you to the DAS for Siemens 3964; Chapter 2 contains the installation procedures. . Part I describes how Siemens 3964 devices are accessed through BASEstar Open services, how you must configure BASEstar Open for use with the DAS for Siemens 3964, and finally provides code examples that you can run in the BASEstar Open environment. . Part II describes how Siemens 3964 devices are accessed through the DEComni API, how you must viii configure DEComni for use with the DAS for Siemens 3964, and how you exchange data with the remote devices. Part III contains the appendices. . ix 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) x 1 1 1 Introduction Introduction Introduction The Digital Device Access Software (DAS) for Siemens 3964 allows both BASEstar Open users and DEComni applications to access Siemens 3964 devices supporting the 3964 protocols. Communicating with Siemens 3964 Devices Communicating with Siemens 3964 Devices Communicating with Siemens 3964 Devices Figure 1-1 shows how a system, equipped with the BASEstar Open or the DEComni product, can communicate with a Siemens 3964 device using the Siemens 3964 protocols. The system equipped with BASEstar Open or DEComni is an OpenVMS or Digital UNIX system. 1 1 1 Figure Figure Figure : Software Components for Siemens 3964 : Software Components for Siemens 3964 : Software Components for Siemens 3964 - - -1 1 1 Communication Communication Communication As illustrated in 2 - Figure 1 , a system (and thus BASEstar Open users or DEComni applications) can communicate with Siemens 3964 devices connected to a RS-232 port or to a terminal server via an Ethernet LAN. The system can connect several Siemens 3964 devices through a point-to-point connection. Device Access Software for Siemens 3964 User Guide 1 1 1 1 1 1- - - Introduction Figure Figure Figure 1 1 1 2 2 2: Communicating with Siemens 3964 Devices : Communicating with Siemens 3964 Devices : Communicating with Siemens 3964 Devices - - - Features of the Digital DAS for Siemens 3964 Features of the Digital DAS for Siemens 3964 Features of the Digital DAS for Siemens 3964 The Digital DAS for Siemens 3964 allows BASEstar Open users and DEComni applications to: . ange data messages with a Siemens 3964 device Exch using the Siemens 3964[R] protocol. . Access memory blocks on a Siemens 3964 device using the Siemens 3964[R]_RK512 protocol. The main features of the supported protocols are listed in Table 1 . 1 - In addition, a system equipped with BASEstar Open or DEComni can emulate Siemens 3964 devices that accept and fulfill requests coming from remote devices through the Siemens 3964[R]_RK512 protocol. Table Table Table : Supported Siemens 3964 Protocols : Supported Siemens 3964 Protocols : Supported Siemens 3964 Protocols 1 1 1 - - - 1 1 1 Protocol Protocol Protocol Features Features Features Version Version Version Siemens 3964 The Siemens 3964 protocol allows the exchange of data messages between your BASEstar Open or DEComni system and a Siemens device. 1 1 1 - - - Device Access Software for Siemens 3964 User Guide 2 2 2 Introduction Siemens The Siemens 3964R protocol is like 3964R the Siemens 3964 protocol but the Block Check Character (BCC) is also supported. Siemens The RK512 interpreter is layered 3964_RK512 above the Siemens 3964 protocol. This allows direct and named access to device memory blocks. Siemens Same as Siemens 3964_RK512 but the 3964R_RK512 RK512 interpreter is layered above the Siemens 3964R protocol. Device Access Software for Siemens 3964 User Guide 1 1 1- - -3 3 3 Introduction What's Next? What's Next? What's Next? In this chapter you have learnt about the features of the Digital DAS for Siemens 3964. If you intend to use the DAS for Siemens 3964 through BASEstar Open services, first read Chapter 2 to know how to install the DAS for Siemens 3964 on your system, and then read Part I of this manual to know how you must configure BASEstar Open and use its services to exchange data with Siemens 3964 devices. If you intend to use the DAS for Siemens 3964 through the DEComni API, first read Chapter 2 to know how to install the DAS for Siemens 3964 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 with Siemens 3964 devices. 1 1 1 - - -4 4 4 Device Access Software for Siemens 3964 User Guide 2 2 2 Installing the DAS for Siemens 3964 on Your Platform Installing the DAS for Siemens 3964 on Your Platform Installing the DAS for Siemens 3964 on Your Platform This chapter specifies the requirements and the procedures for installing the DAS for Siemens 3964 on the following platform: Digital UNIX . The chapter provides the instructions for installing the DAS for Siemens 3964 in the BASEstar Open and DEComni environments. Device Access Software for Siemens 3964 User Guide - - -1 1 1 2 2 2 Installing the DAS for Siemens 3964 on Your Platform Installation on Digital UNIX Systems Installation on Digital UNIX Systems Installation on Digital UNIX Systems Requirements change depending on whether you are installing the DAS for Siemens 3964 for use through BASEstar Open services or the DEComni API. Preparing for DAS for Siemens 3964 installation Preparing for DAS for Siemens 3964 installation Preparing for DAS for Siemens 3964 installation Before starting the installation procedure you should complete the preparation requirements outlined in this section. Release Notes Release Notes Release Notes Your documentation includes the Device Access Software for Siemens 3964 Release Notes, which you should read before installing and using the product. The release notes may contain information about changes to the application. After you install the Device Access Software for Siemens 3964 software, you can also access the online release notes in the form of an ASCII text file by entering the following command: # more /usr/opt/DASS3964_300/doc/relnotes.txt License Registration License Registration License Registration The Device Access Software for Siemens 3964 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 the Device Access Software for Siemens 3964 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 the Device Access Software for Siemens 3964 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 the Device Access Software for Siemens 3964, review the PAK status and install the PAKs for any prerequisite or optional software before you install the Device Access Software for Siemens 3964. To register a license under the Digital UNIX system, first log in as superuser. 2 2 2 Device Access Software for Siemens 3964 User Guide 2 2 2 - - - Installing the DAS for Siemens 3964 on Your Platform You then have a choice of two ways to perform the PAK registration in the License Database (LDB): . Before installing the Device Access Software for Siemens 3964 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 . the Device Access Software for Siemens 3964 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/DAS3964 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 the DAS for Siemens 3964 in the BASEstar Open environment, check that the software products listed in Table 2 1 - have been installed appropriately on your system. Table Table Table 2 2 2- - - : Prerequisite Software for Digital UNIX : Prerequisite Software for Digital UNIX : Prerequisite Software for Digital UNIX 1 1 1 (BASEstar Open Environment) (BASEstar Open Environment) (BASEstar Open Environment) Subset Name and Subset Name and Subset Name and Comments Comments Comments Description Description Description OSFLAT200 Install this product to DEC TCP/IP Services for make LAT support available Digital UNIX Version to DAS for Siemens 3964. 3.1 BSTR300 Ensure that the BASEstar Device Access Software for Siemens 3964 User Guide - - -3 3 3 2 2 2 Installing the DAS for Siemens 3964 on Your Platform 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 Installation Guide for your platform for details. Software Requirements (DEComni Environment) Software Requirements (DEComni Environment) Software Requirements (DEComni Environment) If you are installing the DAS for Siemens 3964 in the DEComni environment, check that the software products listed in Table 2 have been installed -2 appropriately on your system. Table Table Table 2 2 2: 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 DEComni API Version the presence of the 3.0 for Digital UNIX following subsets: Version 3.0 DASTK232300 . DASTKRUN300 . See the DEComni API Installation Guide for your platform for details. OSFLAT200 Install this product to DEC TCP/IP Services make LAT support available for Digital UNIX to DAS for Siemens 3964. Version 3.1 Disk Space Requirements Disk Space Requirements Disk Space Requirements The following table lists the disk space required to install the DAS for Siemens 3964. 2 2 2- - -4 4 4 Device Access Software for Siemens 3964 User Guide Installing the DAS for Siemens 3964 on Your Platform Usage Usage Usage (root) (root) (root) /usr/opt /usr/opt /usr/opt /var/opt /var/opt /var/opt (Kbytes) (Kbytes) (Kbytes) Installation 0 1103 381 Permanent 0 1103 339 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 the DAS for Siemens 3964 Installing the DAS for Siemens 3964 Installing the DAS for Siemens 3964 This section describes the installation, deinstallation and IVP procedures for the Device Access Software for Siemens 3964 for Digital UNIX. Installing the Device Access Software for Siemens 3964 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 the DAS for Siemens 3964 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/DASS3964300). Issue the 4. setld -l command to load the product onto the system, and follow the installation dialogs (for example, setld -l DASS3964300). 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 DASS3964300 Deinstallation Procedure Deinstallation Procedure Deinstallation Procedure The DAS for Siemens 3964 can be deinstalled as follows: Log onto the system as superuser (root). 1. Device Access Software for Siemens 3964 User Guide 5 5 5 - - - 2 2 2 Installing the DAS for Siemens 3964 on Your Platform 2.Change your working directory to the kit location (for example, cd /CDROM/DASS3964300). 3.Issue the setld -d DASS3964300 command. Files Installed on your System Files Installed on your System Files Installed on your System This section lists directories and files created by the Device Access Software for Siemens 3964. ./usr/opt/das3964_300/doc: das3964_guide.ps relnotes.ps relnotes.txt ./usr/opt/das3964_300/include: omni_integrator4_defs_include.h ./usr/opt/das3964_300/lib: libdas3964.a /usr/opt/das3964_300/shlib: libdas3964.so ./usr/var/opt: das3964_300 ./usr/var/opt/das3964_300/examples: das3964_ivp.c 2 2 2 - - - Device Access Software for Siemens 3964 User Guide 6 6 6 PART I PART I PART I Communicating with Communicating with Communicating with Siemens 3964 Devices Siemens 3964 Devices Siemens 3964 Devices Using BASEstar Open Using BASEstar Open Using BASEstar Open This part describes how Siemens 3964 devices are accessed through BASEstar Open services, and how you must configure BASEstar Open for use with the DAS for Siemens 3964. It also provides code examples 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 Siemens 3964 devices are accessed through BASEstar Open services. It also provides an overview of the operations a BASEstar Open user can perform using the features provided by the DAS for Siemens 3964: Exchanging data messages with a Siemens 3964 . device using the 3964[R] protocol. . Reading and writing the memory of a Siemens 3964 device using the 3964[R]_RK512 protocol. The chapter also discusses how a system equipped with BASEstar Open can emulate Siemens 3964 devices that accept and fulfill requests coming from the remote devices through the Siemens 3964[R]_RK512 protocol. Device Access Software for Siemens 3964 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 with Siemens 3964 devices. Figure Figure Figure 3 3 3 : BASEstar Open Environment Components : BASEstar Open Environment Components : BASEstar Open Environment Components - - -1 1 1 Data Services Data Services Data Services BASEstar Open users use Device_Data_Points to read and write memory locations of a Siemens 3964 device. When a user writes the value of a Device_Data_Point, BASEstar Open Device Services sends a message to the appropriate Siemens 3964 device. Vice versa, BASEstar Open updates the value of a Device_Data_Point each time it receives an unsolicited message from a Siemens 3964 device. Each Device_Data_Point is linked to a Device Services variable which, in turn, is associated with the VMD definition that models the target device. 3 3 3 2 2 2 - - - Device Access Software for Siemens 3964 User Guide Overview Device Services Device Services Device Services BASEstar Open Device Services provides 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 models a device as a MMS Virtual Manufacturing Device (VMD). Each Device Services VMD corresponds to a Siemens 3964 device. A variable associated with this VMD corresponds to a memory location on the same device. 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 Siemens 3964 devices connected through an RS232 port or a terminal server. Digital DAS for Siemens 3964 Digital DAS for Siemens 3964 Digital DAS for Siemens 3964 The Digital DAS for Siemens 3964 is a BASEstar Open device connectivity module that implements the Siemens 3964[R] and 3964[R]_RK512 protocols. Device Access Software for Siemens 3964 User Guide 3 3 3- - -3 3 3 Overview Exchanging Data Messages with a Siemens 3964 Device (3964[R] Exchanging Data Messages with a Siemens 3964 Device (3964[R] Exchanging Data Messages with a Siemens 3964 Device (3964[R] Protocol) Protocol) Protocol) The DAS for Siemens 3964 allows a BASEstar Open user to communicate with a Siemens 3964 device according to the 3964[R] protocol. Figure 3 2 shows the BASEstar Open objects and the - commands a BASEstar Open user must use to receive data messages from (and send data messages to) a remote Siemens 3964 device. Figure Figure Figure : BASEstar Open Objects and Operations : BASEstar Open Objects and Operations : BASEstar Open Objects and Operations 2 2 2 3 3 3- - - (3964[R] Protocol) (3964[R] Protocol) (3964[R] Protocol) Sending Data Sending Data Sending Data A BASEstar Open user must issue a PUT_VALUE command on a Device_Data_Point to send a data message to a remote Siemens 3964 device. The Device_Data_Point must be linked to a Device Services variable which is, in turn, associated with a VMD defined for that device. Several variables can be associated with the same VMD, and a user can use each of the Device_Data_Points linked to these variables to send data messages of different lengths. BASEstar Open sends the remote device a number of characters from the user buffer equal to the size in bytes of the Datatype that has been associated with the variable used for the send operation. 3 3 3 4 4 4 - - - Device Access Software for Siemens 3964 User Guide Overview The PUT_VALUE command returns control to the application as soon as BASEstar Open has sent the data through the local port successfully. 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 coming from a remote Siemens 3964 device. The Device_Data_Point must have been configured for receive operations, and must be linked to the "reception variable" associated with the VMD that models the device. BASEstar Open always uses the reception variable to return the data received from the Siemens 3964 device. The "reception variable" is the Device Services first Named_Variable that has been created for the VMD. If no Named_Variable has been defined, the first Unnamed_Variable is used. If no variable is associated with the remote VMD, any data received from the device 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 DAS nor with the device. 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 device, 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 device in one data message according to the Datatype associated with the "reception variable". 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. Device Access Software for Siemens 3964 User Guide 5 5 5 - - - 3 3 3 Overview Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Protocol) Protocol) Protocol) A BASEstar Open user gets (or puts) the value of a Device_Data_Point to read data from (or write data to) a physical memory location of a Siemens 3964 device. As shown in Figure 3-3, this Device_Data_Point must be linked to an Unnamed_Variable associated with a VMD that models the device. A GET_VALUE command reads data from the device memory, and returns in the user buffer a number of characters that is equal to the size of the BASEstar Open DataType associated with the variable used for read operations. A similar consideration applies to a PUT_VALUE command. Figure Figure Figure : Accessing the Memory of a Siemens 3964 : Accessing the Memory of a Siemens 3964 : Accessing the Memory of a Siemens 3964 - - -3 3 3 3 3 3 Device Through BASEstar Open Device Through BASEstar Open Device Through BASEstar Open To obtain a BASEstar Open configuration that is appropriate for your needs, you must consider the requirements of your overall application. - Figure 3 3 illustrates an example in which BASEstar Open operations are synchronous with user's actions; in fact: . Each time the user issues a PUT_VALUE command, BASEstar Open immediately updates the device memory. . Each time the user issues a GET_VALUE command, BASEstar Open immediately reads the device memory. However, you can configure BASEstar Open for asynchronous operations by means of a Polling_Set. In this case, BASEstar Open automatically reads the value of the device memory, and updates the value of 3 3 3 - - - Device Access Software for Siemens 3964 User Guide 6 6 6 Overview the Device_Data_Point asynchronously with respect to the user's actions. Device Access Software for Siemens 3964 User Guide 3 3 3- - -7 7 7 Overview Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) Figure 3 4 shows how BASEstar Open emulates a Siemens - 3964 device through a local VMD. When emulating a Siemens 3964 device, BASEstar Open acts as a server, that is, accepts and fulfills write and read requests coming from a remote Siemens 3964 device or a BASEstar Open user. Figure Figure Figure 4 4 4: Emulating a Siemens 3964 Device Through : Emulating a Siemens 3964 Device Through : Emulating a Siemens 3964 Device Through 3 3 3- - - BASEstar Open BASEstar Open BASEstar Open To direct BASEstar Open to act as server you must create a local VMD object for each Siemens 3964 device you want to emulate, and you must associate a Device Services Unnamed_Variable to the VMD for each memory block to be emulated. BASEstar Open users can exchange data messages with emulated Siemens 3964 devices as described in the section of this chapter entitled Exchanging Data Messages with a Siemens 3964 Device (3964[R] Protocol). Datatypes and Memory Block Sizes Datatypes and Memory Block Sizes Datatypes and Memory Block Sizes A GET_VALUE command returns in the user buffer a number of characters that is equal to the size of the BASEstar Open Datatype associated with the variable used in the read operation. The size (in bytes) of this data type must therefore be equal to the size (in bytes) of the data that are contained in a data block (represented by the variable). A similar consideration applies to the PUT_VALUE command. 3 3 3 Device Access Software for Siemens 3964 User Guide - - -8 8 8 Overview In order to simplify the calculation of the sizes of BASEstar Open Datatypes, Appendix B provides the sizes of the basic BASEstar Open Datatypes. Device Access Software for Siemens 3964 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 allow users to access a Siemens 3964 device. 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_Point objects. _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ For an explanation of the BASEstar Open object attributes whose values are not specified in this chapter, refer to the BASEstar Open Command Language Interface and to the BASEstar Open Reference Guide. ________________________________ ________________________________ ________________________________________________ ________________ ________________ Device Access Software for Siemens 3964 User Guide 1 1 1 - - - 4 4 4 Configuring BASEstar Open Registering ODS Entries Registering ODS Entries Registering ODS Entries For each Siemens 3964 device you must create an ODS entry which specifies Siemens 3964 protocol-specific information. 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 You must create the following Device Services objects, in the order listed below: 1.Protocol_Profile 2.VMD 3.Variables Creating Protocol_Profiles Creating Protocol_Profiles Creating Protocol_Profiles Device Services uses Protocol_Profiles to associate a VMD with the appropriate DAS. You must create one Protocol_Profile for each Siemens 3964 protocol, and you can use it for all the VMDs that are associated with that protocol. Table 4 1 lists the - Protocol_Profile attributes whose values are specific to the Siemens 3964 protocols. 4 4 4 Device Access Software for Siemens 3964 User Guide 2 2 2 - - - Configuring BASEstar Open Table Table Table 4 4 4- - -1 1 1: Protocol_Profile Attributes : Protocol_Profile Attributes : Protocol_Profile Attributes Attribute Attribute Attribute Description and Values Description and Values Description and Values Name Name Name - The identifier of the DAS to be used. APPLPROFID Possible values are: "31" for the Siemens 3964 protocol "32" for the Siemens 3964R protocol "33" for the Siemens 3964_RK512 protocol "34" for the Siemens 3964R_RK512 protocol - The maximum length of the data exchanged MAXPDUSIZE with the Siemens 3964 device. For the 3964[R] protocol, there is no limit in the size of the message exchanged. You can specify any value, provided it is supported by DEComni. For the 3964[R] _RK512 protocol, there is no limit in the size of the message exchanged between DEComni applications and Siemens 3964 devices, but the message is segmented for transmission over the communication line. This attribute must specify the segment size, which must be less than, or equal to 138 (including 10 bytes for the header). Example 4 shows how to create the 1 - Protocol_Profiles for all the supported protocols. Example Example Example 4 4 4 1 1 1: Creating Device Services : Creating Device Services : Creating Device Services - - - Protocol_Profiles Protocol_Profiles Protocol_Profiles BSTR> CREATE PROTOCOL_PROFILE PP_3964 -APPLPROFID 31\ -MAXPDUSIZE 1024 -LOG BSTR> CREATE PROTOCOL_PROFILE PP_3964R -APPLPROFID 32\ -MAXPDUSIZE 1024 -LOG BSTR> CREATE PROTOCOL_PROFILE PP_3964_RK512 - APPLPROFID 33\ -MAXPDUSIZE 138 -LOG BSTR> CREATE PROTOCOL_PROFILE PP_3964R_RK512 - APPLPROFID 34\ -MAXPDUSIZE 138 -LOG Creating VMDs Creating VMDs Creating VMDs A Device Services VMD models a Siemens 3964 device. - Table 4 lists the mandatory attributes that you 2 Device Access Software for Siemens 3964 User Guide 3 3 3 4 4 4- - - Configuring BASEstar Open must specify for a correct definition of a Siemens 3964 VMD for any of the supported protocols. Table Table Table 2 2 2: VMD Attributes : VMD Attributes : VMD Attributes 4 4 4- - - Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values - When creating a remote VMD (that is, DVM_ACCESS_POIN a VMD that models a real Siemens T 3964 device), a list of one or more access point descriptors, for each access point users use to access the remote device. An access point descriptor has the following format: application_simple_name: : :protoco l_profile_name where: application_simple_name must specify an ODS entry valid for the Siemens 3964 protocol in use (see Appendix A). protocol_profile_name must specify a Protocol_Profile created according to the explanations provided in this chapter. - When creating a local VMD (that is, CLIENT_ACCESS_P a VMD that models an emulated OINT Siemens 3964 device), a list of one or more descriptors, one for each access point users use to access the remote device. An access point descriptor has the following format: application_simple_name: : :protoco l_profile_name where: application_simple_name must specify an ODS entry valid for the used Siemens 3964 protocol (see Appendix A). protocol_profile_name must specify a Protocol_Profile created according to the explanations provided in this chapter. -MODEL Used for documentation purposes. -VENDOR Used for documentation purposes. 4 4 4- - -4 4 4 Device Access Software for Siemens 3964 User Guide Configuring BASEstar Open Creating a VMD for Communication through the 3964[R] Protocol Creating a VMD for Communication through the 3964[R] Protocol Creating a VMD for Communication through the 3964[R] Protocol To exchange data messages with a Siemens 3964 device using the 3964[R] protocol you must define a remote VMD. Example 4 shows how to create a valid remote -2 VMD. Example Example Example : Creating a Device Services VMD (3964[R] : Creating a Device Services VMD (3964[R] : Creating a Device Services VMD (3964[R] - - -2 2 2 4 4 4 Protocol) Protocol) Protocol) BSTR> CREATE VMD VMD_REMOTE_3964R -MODEL "SIEMENS 3964R"\ -VENDOR "BASEstar Open"\ -DVM_ACCESS_POINTS ("/cn=SIEMENS_3964":PP_3964R)\ -DESCRIPTION "For sending data to a Siemens 3964 device using\ the Siemens 30964R protocol."\ -LOG Creating a VMD for Communication through the 3964[R]_RK512 Creating a VMD for Communication through the 3964[R]_RK512 Creating a VMD for Communication through the 3964[R]_RK512 Protocol Protocol Protocol Depending on the operation you want to perform, you must define a remote VMD, a local VMD, or both: A remote VMD models a real Siemens 3964 device and . associated variables. For a remote VMD, a BASEstar Open user can act as a client that writes and reads the value of memory blocks physically located on the associated Siemens 3964 device. A local VMD models a Siemens 3964 device emulated . on the host system. For a local VMD, BASEstar Open acts as a server that fulfills write and read requests coming from both the Siemens 3964 device and BASEstar Open users. _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ A DATADEV or DEVICE server currently supports one local VMD. When needed, its name must be specified by the BSTR_LOCAL_VMD_NAME BASEstar Open global variable. ________________________________ ________________________________ ________________________________________________ ________________ ________________ Example 4-3 shows how to create the VMDs for communicating with a Siemens 3964 device using the Siemens 3964R_RK512 protocol. Device Access Software for Siemens 3964 User Guide - - -5 5 5 4 4 4 Configuring BASEstar Open Example Example Example 4 4 4 3 3 3 - - - : Creating Device Services VMDs : Creating Device Services VMDs : Creating Device Services VMDs (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) BSTR> CREATE VMD VMD_REMOTE_3964R_RK512 -MODEL "SIEMENS 3964R_RK512"\ -VENDOR "BASEstar Open"\ -DVM_ACCESS_POINTS ("/cn=REMOTE_3964_512":PP_3964R_RK512)\ -DESCRIPTION "Allows BASEstar Open users to write and read memory blocks of a Siemens 30964 device using the Siemens 3964[R]_RK512 protocol. -LOG BSTR> CREATE VMD VMD_LOCAL_3964R_RK512 -MODEL "SIEMENS 3964R_RK512"\ -VENDOR "BASEstar Open"\ -DVM_ACCESS_POINTS ("/cn=LOCAL_3964_512":PP_3964R_RK512)\ -DESCRIPTION "Emulates a Siemens 3964 device using the Siemens\ 3964[R]_RK512 protocol.\ -LOG 4 4 4- - - Device Access Software for Siemens 3964 User Guide 6 6 6 Configuring BASEstar Open Creating Variables Creating Variables Creating Variables Device Services variables model variables at a remote or a local VMD. Creating Variables for Communication through the 3964[R] Creating Variables for Communication through the 3964[R] Creating Variables for Communication through the 3964[R] Protocol Protocol Protocol 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. To receive data from Siemens 3964 devices you can use Named or Unnamed_Variables. 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 that you must 3 specify for a correct definition of a reception variable. 4 4 4 Table Table Table - - - : Reception Variable Attributes (3964[R] : Reception Variable Attributes (3964[R] : Reception Variable Attributes (3964[R] 3 3 3 Protocol) Protocol) Protocol) Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values -DATATYPE Name of the Datatype BASEstar Open datatype_name associates with the data received from the device. Appendix B specifies the sizes of the basic BASEstar Open Datatypes. -SEND This attribute must be set to notification ALWAYS or to ON_CHANGE. Such settings direct BASEstar Open to update in unsolicited mode the value of the linked Device_Data_Point on reception of data from the device. -ACCESS Must be set to READ. access_type -ADDRTYPE Significant for Unnamed_Variables address_type only; it must be set to UNCONSTRAINED. -ADDRESS address Significant for Unnamed_Variables only; it can be set to any value. You can define as many Named or Unnamed_Variables associated with a local VMD as you need to send data Device Access Software for Siemens 3964 User Guide 4 4 4 7 7 7 - - - Configuring BASEstar Open to a Siemens 3964 device. Each of these variables can have a different Datatype, which allows you to send different types of data to the Siemens 3964 device. Table 4 4 lists the attributes that you must specify - for a correct definition of a transmission variable. Table Table Table 4 4 4: Transmission Variable Attributes (3964[R] : Transmission Variable Attributes (3964[R] : Transmission Variable Attributes (3964[R] 4 4 4- - - Protocol) Protocol) Protocol) 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 know the number of bytes in the user buffer. Appendix B specifies the sizes of the basic BASEstar Open Datatypes. .-ACCESS Must be set to WRITE. access_type -ADDRTYPE Significant for Unnamed_Variables address_type only; it must be set to UNCONSTRAINED. -ADDRESS address Significant for Unnamed_Variables only; it can be set to any value. 4 4 4 8 8 8 - - - Device Access Software for Siemens 3964 User Guide Configuring BASEstar Open Creating Variables for Communication through the 3964[R]_RK512 Creating Variables for Communication through the 3964[R]_RK512 Creating Variables for Communication through the 3964[R]_RK512 Protocol Protocol Protocol You must use Unnamed_Variables to exchange data with a Siemens 3964 device. You can use the same variable for both read and write operations. Table 4-5 lists the attributes that you must specify for a correct definition of an Unnamed_Variable that can be associated with a VMD that models a real or an emulated Siemens 3964 device. 4 4 4- - - Table Table Table : Variable Attributes (3964[R]_RK512 : Variable Attributes (3964[R]_RK512 : Variable Attributes (3964[R]_RK512 5 5 5 Protocol) Protocol) Protocol) Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values -DATATYPE Name of a BASEstar Datatype. Its datatype_name size (in bytes) must match the size (in bytes) of the associated Siemens 3964 device memory block. See Appendix B for the sizes of the basic BASEstar Open DataTypes. -SEND Only significant for read notification operations. You can set any value provided it is consistent with the overall configuration. -ACCESSMODE You are suggested to set this access_mode attribute to WRITE, to have the same variable supporting both read and write operations. -ADDRTYPE It must be set to UNCONSTRAINED. address_type -ADDRESS This attribute must specify a valid address Siemens 3964 memory block address. See Appendix D. Creating Data Services Objects Creating Data Services Objects Creating Data Services Objects BASEstar Open users exchange data messages with devices by means of Device_Data_Points without taking into consideration communication and device characteristics. Creating Device_Data_Points for Communication through the Creating Device_Data_Points for Communication through the Creating Device_Data_Points for Communication through the 3964[R] Protocol 3964[R] Protocol 3964[R] Protocol Table 4- lists the attributes you must set to define 6 Device_Data_Points that will be used to receive data from a Siemens device using the 3964[R] protocol. Device Access Software for Siemens 3964 User Guide 9 9 9 4 4 4- - - Configuring BASEstar Open Table Table Table 4 4 4 6 6 6: Device_Data_Point Attributes for Receive : Device_Data_Point Attributes for Receive : Device_Data_Point Attributes for Receive - - - Operations (3964[R] Protocol) Operations (3964[R] Protocol) Operations (3964[R] Protocol) Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values -VMD_NAME Must be set with the name of a vmd_name remote VMD. -VAR_NAME Must be set with the name of the var_name "reception variable" that is associated with the vmd_name VMD. -VAR_CLASS Must be set to NAMED or UNNAMED var_class according to the class of the var_name Device Services variable. -DATATYPE Must be set with the name of the datatype_name same Datatype associated with the var_name variable specified by the - VAR_NAME attribute. -DEVICE_ACCESS Must be set to READ to indicate that device_access the linked Device Services variable produces the value of the Device_Data_Point. -UPDATE_POLICY Must be set to UNSOLICITED to update_policy indicate that Data Services updates the value of the Device_Data_Point according to what was specified by the -SEND attribute of the linked Device Services variable. 4 4 4 10 10 10 - - - Device Access Software for Siemens 3964 User Guide Configuring BASEstar Open Table 4- lists the attributes you must set to define 7 Device_Data_Points that will be used to send data to a Siemens device using the 3964[R] protocol. Table Table Table 4 4 4 : Device_Data_Point Attributes for Send : Device_Data_Point Attributes for Send : Device_Data_Point Attributes for Send - - -7 7 7 Operations (3964[R] Protocol) Operations (3964[R] Protocol) Operations (3964[R] Protocol) 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 local VMD. -VAR_NAME var_name Must be set with the name of a "transmission variable" associated with the vmd_name VMD. -VAR_CLASS Must be set to NAMED or UNNAMED var_class according to the class of the var_name Device Services variable. -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 device_access that Data Services will use the value provided by the PUT_VALUE command to update the value of the linked Device Services variable (and therefore to cause the DAS for Siemens 3964 to send the value to the Siemens device). Creating Device_Data_Points for Communication through the Creating Device_Data_Points for Communication through the Creating Device_Data_Points for Communication through the 3964[R]_512 Protocol 3964[R]_512 Protocol 3964[R]_512 Protocol A BASEstar Open user uses a Device_Data_Point associated with a remote (or local) VMD to write data directly to the memory of a real (or emulated) Siemens 3964 device. Table 4-8 lists the attributes you must set to create a Device_Data_Point that will be used to read and write device memory blocks. 4 4 4- - - Table Table Table : Device_Data_Point for Send and Receive : Device_Data_Point for Send and Receive : Device_Data_Point for Send and Receive 8 8 8 Operations (3964[R]_512 Protocol) Operations (3964[R]_512 Protocol) Operations (3964[R]_512 Protocol) 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 Device Access Software for Siemens 3964 User Guide - - -11 11 11 4 4 4 Configuring BASEstar Open remote VMD (that is, a VMD that models a remote Siemens 3964 device), or a local VMD (that is, a VMD that emulates a Siemens 3964 device on the host system). -VAR_NAME var_name Must be set with the name of a Device Services Unnamed_Variable associated with the vmd_name VMD. -VAR_CLASS Must be set to NAMED or UNNAMED var_class according to the class of the var_name Device Services variable. -DATATYPE Must be set with the name of the datatype_name same Datatype associated with the var_name variable specified by the -VAR_NAME attribute. -DEVICE_ACCESS You are suggested to set it to device_access RDWR to indicate that this Device_Data_Point can be used for both read and write operations. -UPDATE_POLICY Only significant for read update_policy operations. You can set any value provided it is consistent with the overall configuration. -ACCESS_POLICY Only significant for read access_policy operations. You can set any value provided it is consistent with the overall configuration. 4 4 4 12 12 12 - - - Device Access Software for Siemens 3964 User Guide 5 5 5 Examples Examples Examples This chapter contains three CLI examples: . The first example shows how BASEstar Open users can exchange data with a Siemens 3964 device using the 3964[R] protocol. . The second example shows how BASEstar Open users can read data from, and write data to memory blocks of a Siemens 3964 device using the 3964[R]_RK512 protocol. The third example shows how your system can emulate . a Siemens 3964 device accessible through the 3964[R]_RK512 protocol. Device Access Software for Siemens 3964 User Guide - - - 5 5 5 1 1 1 Examples Example 1: Exchanging Data Through the 3964[R] Protocol Example 1: Exchanging Data Through the 3964[R] Protocol Example 1: Exchanging Data Through the 3964[R] Protocol The example contained in this section describes how you can configure BASEstar Open to allow users to exchange data with a Siemens 3964 device using the 3964[R] protocol. 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 data operations are executed in synchronous mode. According to configuration, each time a user issues a PUT_VALUE command BASEstar Open immediately sends the data. The command only terminates and returns control to the user when the operation has been completed. _______________________ Receive data operations In this example, a user must keep reading the reception variable if he wants to know when its value changes due to reception of an unsolicited data message from the device. 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 It is assumed that the Siemens 3964 device has been configured, is functioning and can receive incoming data. Before you can use this example, you must: . Replace my_tcpnode with the TCP/IP name of your the BASEstar Open Node. . my_DAS_id Replace with the identifier of the Siemens 3964 protocol you wish to use. . Replace ODS_Remote3964 with the name of an ODS entry that complies with the communication characteristics of the Siemens 3964 device. 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. 5 5 5 2 2 2 Device Access Software for Siemens 3964 User Guide - - - Examples Example Example Example 5 5 5- - - : Creating BASEstar Open Objects (3964[R] : Creating BASEstar Open Objects (3964[R] : Creating BASEstar Open Objects (3964[R] 1 1 1 Protocol) Protocol) Protocol) ! --------------------------------------------------- ---------------- ! 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 the Common Services objects: Nodes, Actors, Domains, | Protocol_Profiles and VMDs ! --------------------------------------------------- ---------------- CREATE NODE NODE1 -PHYSICAL_NAME "my_tcpnode" CREATE ARRAY_DATATYPE ARRAY_OF_INTEGERS_16 - NUM_OF_ELEMENTS 10\ -DATATYPE INTEGER_32 CREATE DOMAIN /DOM_DATA CREATE ACTOR /ACT_SERVERS CREATE PROTOCOL_PROFILE PP_3964 -APPLPROFID My_DAS_id\ -MAXPDUSIZE 1024 -LOG CREATE VMD VMD_REM3964\ -MODEL "3964R" -VENDOR "Digital"\ -DVM_ACCESS_POINTS ODS_Remote3964:PP_3964)\ -DESCRIPTION "VMD for data exchange"\ -LOG ! --------------------------------------------------- ---------------- ! Create the objects needed to define the Data Services and ! Device Services servers. Device Access Software for Siemens 3964 User Guide 3 3 3 - - - 5 5 5 Examples ! --------------------------------------------------- ---------------- CREATE PROGRAM /ACT_SERVERS/PRG_DATA -PROGRAM_KIND DATADEV CREATE ACTIVITY /ACT_SERVERS/ACY_DATA\ -PROGRAM /ACT_SERVERS/PRG_DATA -NODES (NODE1)\ -DOMAINS (/DOM_DATA)\ -VMDS (/VMD_REM3964)\ -STARTUP_TIMEOUT 120 -RECOVERY_POLICY NECESSARY ! --------------------------------------------------- ---------------- ! Execute the ACTOR to activate the required servers. !(Connection with the device is set up by the Device Services ! server). ! --------------------------------------------------- ---------------- 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 UNNAMED_VAR VMD_REM3964.VAR_RCV -DATATYPE INTEGER_32\ -SEND ALWAYS -ACCESSMODE READ\ -ADDRESS XXX -ADDRESSTYPE UNCONSTRAINED CREATE UNNAMED_VAR VMD_REM3964.VAR_SEND001 -DATATYPE INTEGER_32\ -ACCESSMODE WRITE CREATE UNNAMED_VAR VMD_REM3964.VAR_SEND002\ -DATATYPE ARRAY_OF_INTEGERS_32 -ACCESSMODE WRITE ! --------------------------------------------------- ---------------- ! Create the Data Services objects. 5 5 5 Device Access Software for Siemens 3964 User Guide - - -4 4 4 Examples ! --------------------------------------------------- ---------------- CREATE DEVICE_DATA_POINT DP_RECEIVE\ -VMD_NAME VMD_REM3964\ -VAR_NAME VAR_RCV -VAR_CLASS UNNAMED\ -DATATYPE INTEGER_32 -DEVICE_ACCESS READ\ -UPDATE_POLICY UNSOLICITED CREATE DEVICE_DATA_POINT DP_SEND001\ -VMD_NAME VMD_REM3964\ -VAR_NAME VAR_SEND001 -VAR_CLASS UNNAMED\ -DATATYPE INTEGER_32 -DEVICE_ACCESS WRITE CREATE DEVICE_DATA_POINT DP_SEND002\ -VMD_NAME VMD_REM3964\ -VAR_NAME VAR_SEND002 -VAR_CLASS UNNAMED\ -DATATYPE ARRAY_OF_INTEGERS_32 -DEVICE_ACCESS WRITE You can now receive data from, and send data to a Siemens 3964 device using the 3964[R] protocol. A possible operation sequence that uses the objects previously created is described in Example 5- . 2 Example Example Example - - - : Exchanging Data with a Siemens 3964 : Exchanging Data with a Siemens 3964 : Exchanging Data with a Siemens 3964 2 2 2 5 5 5 Device (3964[R] Protocol) Device (3964[R] Protocol) Device (3964[R] Protocol) BSTR> PUT VALUE DEVICE_DATA_POINT DP_SEND001 (Integer 32) : 345 BSTR> GET VALUE DEVICE_DATA_POINT DP_RECEIVE 12 ......... "Keep receiving until you receive the answer!"/ ......... BSTR> PUT VALUE DEVICE_DATA_POINT DP_SEND002 array[10] of INTEGER_16 [0]: [Integer 32] : 3 [1]: [Integer 32] : 12 [2]: [Integer 32] : 4999 [3]: [Integer 32] : 3 Device Access Software for Siemens 3964 User Guide 5 5 5- - -5 5 5 Examples [4]: [Integer 32] : 3 [5]: [Integer 32] : 12 [6]: [Integer 32] : 3333 [7]: [Integer 32] : 33333 [8]: [Integer 32] : 2 [9]: [Integer 32] : 2 BSTR> GET VALUE DEVICE_DATA_POINT DP_RECEIVE 1234 5 5 5 Device Access Software for Siemens 3964 User Guide 6 6 6 - - - Examples Example 2: Accessing the Memory of a Siemens 3964 Device Example 2: Accessing the Memory of a Siemens 3964 Device Example 2: Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) The example contained in this section describes how you must configure BASEstar Open to allow users to read and write memory blocks of a remote Siemens 3964 device using the 3964[R]_RK512 protocol. Example Overview Example Overview Example Overview BASEstar Open being highly configurable, this example shows only one of many possible modes for implementing read and write operations. It is assumed that read and write operations are executed in synchronous mode. According to configuration, BASEstar Open physically accesses the memory of the addressed device each time a user issues a PUT_VALUE or a GET_VALUE command. The command only terminates and returns control to the user when the operation has been completed. Before Running the Example Before Running the Example Before Running the Example It is assumed that the Siemens 3964 device has been configured, is functioning and can receive incoming data. Before you can use this example, you must: Replace . my_tcpnode with the TCP/IP name of your the BASEstar Open Node. . Replace my_DAS_id with the identifier of the Siemens 3964[R]_RK512 protocol you wish to use. Replace . ODS_remote3964_RK512 with the name of an ODS entry that complies with the 3964[R]_512 protocol communication characteristics. CLI Source CLI Source CLI Source Example 5 shows the CLI commands that are used to 3 - create BASEstar Open objects and to activate the required servers. Example Example Example 5 5 5 : Creating BASEstar Open Objects : Creating BASEstar Open Objects : Creating BASEstar Open Objects 3 3 3 - - - (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) ! --------------------------------------------------- ---------------- ! The example is set up to work with the VOLATILE database, ! but you can easily adapt it to work with the PERMANENT database. Device Access Software for Siemens 3964 User Guide 5 5 5- - -7 7 7 Examples ! --------------------------------------------------- ---------------- SET SCOPE VOLATILE ! --------------------------------------------------- ---------------- ! Create the Common Services objects: Nodes, Actors, Domains, | Protocol_Profiles and VMDs. ! --------------------------------------------------- ---------------- CREATE NODE NODE1 -PHYSICAL_NAME "my_tcpnode" CREATE DOMAIN /DOM_DATA CREATE ACTOR /ACT_SERVERS CREATE PROTOCOL_PROFILE PP_3964_RK -APPLPROFID My_DAS_id\ -MAXPDUSIZE 138 -LOG CREATE VMD VMD_REM3964_RK\ -MODEL "S5-135U" -VENDOR "Siemens"\ -DVM_ACCESS_POINTS ODS_remote3964_RK512:PP_3964_RK)\ -DESCRIPTION "VMD for device access"\ -LOG ! --------------------------------------------------- ---------------- ! To simplify configuration, a single DATADEV server is started up. ! --------------------------------------------------- ---------------- CREATE PROGRAM /ACT_SERVERS/PRG_DATADEV -PROGRAM_KIND DATADEV CREATE ACTIVITY /ACT_SERVERS\ACY_DEVICE\ -PROGRAM /ACT_SERVERS/PRG_DEVICE -NODES (NODE1)\ -DOMAINS (/DOM_DATA)\ -VMDS (/VMD_REM3964_RK)\ -STARTUP_TIMEOUT 120 -RECOVERY_POLICY NECESSARY ! --------------------------------------------------- ---------------- ! Execute the ACTOR to activate the needed servers 5 5 5 8 8 8 - - - Device Access Software for Siemens 3964 User Guide Examples ! (The connection with the device is started up.) ! --------------------------------------------------- ---------------- EXECUTE ACTOR /ACT_SERVERS ! --------------------------------------------------- ---------------- ! Create the Device Services variable to access the DB:100:10 device ! memory block. ! You can change it to access another device memory block. ! --------------------------------------------------- ---------------- CREATE UNNAMED_VAR VMD_REM3964_RK.REMVAR_DB10010\ -DATATYPE INTEGER_32 -SEND NEVER -ACCESSMODE write\ -ADDRTYPE UNCONSTRAINED -ADDRESS "DB:100:0" ! --------------------------------------------------- ---------------- ! Create the Device_Data Point that allows BASEstar Open users to ! directly access the DB:100:10 device memory block. ! --------------------------------------------------- ---------------- CREATE DEVICE_DATA_POINT DP_REMDB10010\ -VMD_NAME VMD_REM3964_RK\ -VAR_NAME REMVAR_DB10010 -VAR_CLASS UNNAMED\ -DATATYPE INTEGER_32 -DEVICE_ACCESS RDWR\ -UPDATE_POLICY SOLICITED -ACCESS_POLICY ALWAYS Example 5- shows a possible sequence that allows a 4 user to read and write a memory block of the remote Siemens 3964 device. On successful completion of the following command sequence, you have first read the current value of the DB:100:10 directly from the memory of the device, then you have written a new value, and finally you have checked the written value by issuing another read command. Device Access Software for Siemens 3964 User Guide 9 9 9 - - - 5 5 5 Examples Example Example Example 5 5 5 4 4 4 - - - : Reading and Writing the Device Memory : Reading and Writing the Device Memory : Reading and Writing the Device Memory (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) BSTR> GET VALUE DEVICE_DATA_POINT DP_REMDB10010 12 BSTR> BSTR> PUT VALUE DEVICE_DATA_POINT DP_REMDB10010 (Integer 32) : 345 BSTR> BSTR> GET VALUE DEVICE_DATA_POINT DP_REMDB10010 345 5 5 5- - -10 10 10 Device Access Software for Siemens 3964 User Guide Examples Example 3: Emulating a Siemens 3964 Device (3964[R]_RK512 Example 3: Emulating a Siemens 3964 Device (3964[R]_RK512 Example 3: Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) Protocol) Protocol) The example contained in this section describes how to configure BASEstar Open in order to allow your system to emulate a Siemens 3964 device. Other Siemens 3964 devices can access the emulated device using the 3964[R]_RK512 protocol. Example Overview Example Overview Example Overview Using the BASEstar Open configuration shown in this example, a remote Siemens 3964 device can access the memory of a locally emulated device. BASEstar Open automatically fulfills a request. In addition, a BASEstar Open user can read and write the value of a variable on the emulated device. Before Running the Example Before Running the Example Before Running the Example It is assumed that the Siemens 3964 device has been configured, is functioning and can receive incoming data. Before you can use this example, you must: . Replace my_tcpnode with the TCP/IP name of your the BASEstar Open Node. Replace . my_DAS_id with the identifier of the Siemens 3964[R]_RK512 protocol you wish to use. Replace . ODS_local3964_RK512 with the name of an ODS entry that complies with the 3964[R]_512 protocol communication characteristics. Replace . parameter_file with the pathname of the parameter file. As shown in Example 5-5, the BSTR_LOCAL_VMD global variable must specify the name of the local VMD, and BSTR_CONN_MODE must be set to PASSIVE (this directs BASEstar Open to make the locally emulated device available to the remote device). Example Example Example 5 5 5 : Parameter File (3964[R]_RK512 Protocol) : Parameter File (3964[R]_RK512 Protocol) : Parameter File (3964[R]_RK512 Protocol) - - -5 5 5 /ACT_SERVERS/PRG_DATADEV.env: BSTR_LOCAL_VMD = VMD_LOC3964_RK /ACT_SERVERS/PRG_DATADEV.env: BSTR_CONN_MODE = PASSIVE CLI Source CLI Source CLI Source Example 5 shows the CLI commands that are used to 6 - create BASEstar Open objects and to activate the required servers. Device Access Software for Siemens 3964 User Guide 11 11 11 5 5 5- - - Examples Example Example Example 5 5 5 6 6 6 - - - : Emulating a Siemens 3964 Device : Emulating a Siemens 3964 Device : Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) (3964[R]_RK512 Protocol) ! --------------------------------------------------- ---------------- ! 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 the Common Services objects: Nodes, Actors, Domains, | Protocol_Profiles and VMDs. ! --------------------------------------------------- ---------------- CREATE NODE NODE1 -PHYSICAL_NAME "my_tcpnode" CREATE DOMAIN /DOM_DATA CREATE ACTOR /ACT_SERVERS CREATE PROTOCOL_PROFILE PP_3964_RK -APPLPROFID My_DAS_id\ -MAXPDUSIZE 138 -LOG CREATE VMD VMD_REM3964_RK\ -MODEL "S5-135U" -VENDOR "Siemesn"\ -DVM_ACCESS_POINTS ODS_Local3964_RK512:PP_3964_RK)\ -DESCRIPTION "Dummy remote VMD"\ -LOG CREATE VMD VMD_LOC3964_RK\ -MODEL "3964_RK512" -VENDOR "Digital"\ -CLIENT_ACCESS_POINTS ODS_Local3964_RK512:PP_3964_RK)\ -DESCRIPTION "Local VMD for device emulation"\ -LOG ! --------------------------------------------------- ---------------- 5 5 5 Device Access Software for Siemens 3964 User Guide - - - 12 12 12 Examples ! To simplify configuration, a single DATADEV server is started up. ! --------------------------------------------------- ---------------- CREATE PROGRAM /ACT_SERVERS/PRG_DATADEV -PROGRAM_KIND DATADEV\ -PARAMETER_FILE parameter_file CREATE ACTIVITY /ACT_SERVERS\ACY_DEVICE\ -PROGRAM /ACT_SERVERS/PRG_DEVICE -NODES (NODE1)\ -DOMAINS (/DOM_DATA)\ -VMDS (/VMD_REM3964_RK\ -STARTUP_TIMEOUT 120 -RECOVERY_POLICY NECESSARY ! --------------------------------------------------- ---------------- ! Execute the ACTOR to activate the needed servers ! (The connection with the device is started up.) ! --------------------------------------------------- ---------------- EXECUTE ACTOR /ACT_SERVERS ! --------------------------------------------------- ---------------- ! Create the Device Services variable associated with the ! DB:100:10 device memory block. ! You can change it to make available other device memory blocks. ! --------------------------------------------------- ---------------- CREATE UNNAMED_VAR VMD_REM3964_RK.LOCVAR_DB10010\ -DATATYPE INTEGER_32 -SEND NEVER -ACCESSMODE WRITE\ -ADDRTYPE UNCONSTRAINED -ADDRESS "DB:100:0" ! --------------------------------------------------- ---------------- ! Create the Device_Data Point that allows BASEstar Open users to ! directly access the DB:100:10 memory block on the Siemens device. Device Access Software for Siemens 3964 User Guide 5 5 5 13 13 13 - - - Examples ! --------------------------------------------------- ---------------- CREATE DEVICE_DATA_POINT DP_LOCDB10010\ -VMD_NAME VMD_LOC3964_RK\ -VAR_NAME LOCVAR_DB10010 -VAR_CLASS UNNAMED\ -DATATYPE INTEGER_32\ -DEVICE_ACCESS RDWR\ -UPDATE_POLICY UNSOLICITED -ACCESS_POLICY ALWAYS 5 5 5 Device Access Software for Siemens 3964 User Guide 14 14 14 - - - Examples Example 5-7 shows a possible sequence that allows a BASEstar Open user to read and write a memory block of the locally emulated Siemens 3964 device. Example Example Example 7 7 7 - - - 5 5 5 : Reading and Writing the Emulated Device : Reading and Writing the Emulated Device : Reading and Writing the Emulated Device Memory (3964[R]_RK512 Protocol) Memory (3964[R]_RK512 Protocol) Memory (3964[R]_RK512 Protocol) BSTR> GET VALUE DEVICE_DATA_POINT DP_LOCDB10010 12 BSTR> BSTR> PUT VALUE DEVICE_DATA_POINT DP_LOCDB10010 (Integer 32) : 345 BSTR> BSTR> GET VALUE DEVICE_DATA_POINT DP_LOCDB10010 345 Device Access Software for Siemens 3964 User Guide - - -15 15 15 5 5 5 PART II PART II PART II Communicating with Siemens 3964 Devices the Using Communicating with Siemens 3964 Devices the Using Communicating with Siemens 3964 Devices the Using DEComni API DEComni API DEComni API This part explains how to prepare DEComni API applications that are able to communicate with Siemens devices using the features of the DAS for Siemens 3964. 6 6 6 Overview Overview Overview This chapter describes the DEComni environment components that are involved when Siemens 3964 devices are accessed through the DEComni API. It also provides an overview of the operations a DEComni application can perform using the features provided by the DAS for Siemens 3964: Exchanging data messages with a Siemens 3964 . device (3964[R] protocol). . Reading and writing the memory of a Siemens 3964 device (3964[R]_RK512 protocol). The chapter also discusses how a system equipped with DEComni can emulate Siemens 3964 devices that accept and fulfill requests coming from the remote devices through the Siemens 3964[R]_RK512 protocol. Device Access Software for Siemens 3964 User Guide 6 6 6 1 1 1 - - - Overview DEComni Environment Components DEComni Environment Components DEComni Environment Components Figure 6 1 shows the components involved when DEComni - applications exchange data with Siemens 3964 devices. Figure Figure Figure 6 6 6- - -1 1 1: DEComni Environment Components : DEComni Environment Components : DEComni Environment Components 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 a MMS Virtual Manufacturing Device (VMD). A VMD is associated with a Siemens 3964 device. A variable object corresponds to data stored in the device memory. The DEComni API also allows new DAS modules to be added in a standardized way. The Omni Directory Services (ODS) database is the DEComni component that allows you to define the information required for addressing Siemens 3964 devices connected through an RS232 port or a terminal server. Digital DAS for Siemens 3964 Digital DAS for Siemens 3964 Digital DAS for Siemens 3964 The Digital DAS for Siemens 3964 is a BASEstar Open device connectivity module that implements the Siemens 3964[R] and 3964[R]_RK512 protocols. 6 6 6 - - - Device Access Software for Siemens 3964 User Guide 2 2 2 Overview Exchanging Data Messages with a Siemens 3964 Device (3964[R] Exchanging Data Messages with a Siemens 3964 Device (3964[R] Exchanging Data Messages with a Siemens 3964 Device (3964[R] Protocol) Protocol) Protocol) The DAS for Siemens 3964 allows a DEComni application to communicate with a Siemens 3964 device according to the 3964 [R] protocol. Figure 6 2 shows the DEComni definitions and the - DEComni API procedures an application must use to receive data messages from (and send data messages to) a remote Siemens 3964 device. Before a DEComni application can exchange data messages with a remote Siemens 3964 device, it must create the definitions of a remote VMD and of its associated variables. 6 6 6 Figure Figure Figure : DEComni Definitions and API Procedures : DEComni Definitions and API Procedures : DEComni Definitions and API Procedures 2 2 2 - - - (3964[R] Protocol) (3964[R] Protocol) (3964[R] Protocol) Receiving Data Receiving Data Receiving Data In order to receive data messages from a remote Siemens 3964 device, a DEComni application must issue an omni_get_indications procedure call. When DEComni receives a data message from the remote device, it generates an Information report on the remote VMD definition. This causes the completion of the omni_get_indications procedure. The returned context refers to the "reception variable in which DEComni returns the received data '' Device Access Software for Siemens 3964 User Guide - - -3 3 3 6 6 6 Overview message. The reception variable `` is the first '' Named_Variable that has been created for the remote VMD definition. If no Named_Variable has been created, the first Unnamed_Variable is used. If no variable is associated with the remote VMD, any data received from the remote device are lost and the omni_get_indications procedure returns an error. DEComni interprets the data received from the remote device in one message according to the MMS data type associated with the "reception variable". 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 data type, the exceeding bytes are lost. Sending Data Messages Sending Data Messages Sending Data Messages To send a data message to a Siemens 3964 device, a DEComni application must issue an omni_put_value procedure call on the remote VMD definition. The DEComni application can associate several variables with the local VMD, and can use each of them to send data messages of different lengths. The DAS for Siemens 3964 sends the remote device a number of characters taken from the user buffer equal to the size of the MMS data type that has been associated with the variable definition used for the send operation. The omni_put_value procedure returns control to the DEComni application as soon as the DAS for Siemens 3964 has sent the data through the local port successfully. Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Accessing the Memory of a Siemens 3964 Device (3964[R]_RK512 Protocol) Protocol) Protocol) The DAS forSiemens 3964 allows a DEComni application to access the memory of a Siemens 3964 device through the 3964 [R]_RK512 protocol. The Siemens 3964 device is modeled by a remote VMD definition. A DEComni application can act as client, that is, it can read and write the values of memory blocks on a Siemens 3964 device. 6 6 6 4 4 4 - - - Device Access Software for Siemens 3964 User Guide Overview Figure Figure Figure 6 6 6 3 3 3: Accessing the Memory of a Siemens 3964 : Accessing the Memory of a Siemens 3964 : Accessing the Memory of a Siemens 3964 - - - Device Through the DEComni API Device Through the DEComni API Device Through the DEComni API To act as a client of a Siemens 3964 device (that is, to read data from, and write data to, a physical memory location of a Siemens 3964 device), a DEComni application uses a remote VMD definition. An Unnamed Variable associated with this VMD must specify the address of a valid memory block on the addressed Siemens 3964 device. The same Unnamed Variable can be used in read and write operations. A DEComni client application calls the omni_put_value (or the omni_get_value) procedure, and specifies the handle of an Unnamed Variable associated with a remote VMD to write (or read) a memory block of the remote device. Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) Emulating a Siemens 3964 Device (3964[R]_RK512 Protocol) To act as a server of a remote Siemens 3964 device (that is, to emulate a Siemens 3964 device and therefore to fulfill write and read requests coming from a remote Siemens 3964 device), a DEComni server application uses a local VMD definition and its associated variables (see Figure 6 4 - ). Device Access Software for Siemens 3964 User Guide 6 6 6 5 5 5 - - - Overview Figure Figure Figure 6 6 6 4 4 4: Emulating a Siemens 3964 Device Through : Emulating a Siemens 3964 Device Through : Emulating a Siemens 3964 Device Through - - - the DEComni API the DEComni API the DEComni API Each Unnamed Variable associated with the local VMD must specify the address of a valid memory block at the emulated Siemens 3964 device. In this way, the block can be correctly addressed by other Siemens devices. When DEComni receives a read (or write) request from a remote device, it generates a Read (or Write) Indication, which causes the completion of the omni_get_indications procedure call. The context returned to the application by the omni_get_indications procedure refers to the variable, among those defined for the local VMD, whose Siemens 3964 memory address matches that specified in the remote client request. MMS Types and Siemens 3964 Memory Block Sizes MMS Types and Siemens 3964 Memory Block Sizes MMS Types and Siemens 3964 Memory Block Sizes The omni_get_value procedure returns in the user buffer a number of characters that is equal to the size of the MMS Type associated with the variable used in the read operation. The size (in bytes) of this data type must therefore be equal to the size of the data that are contained in a data block (represented by the variable). A similar consideration applies to the omni_put_value procedure. In order to simplify the calculation of the size of an MMS Type, Appendix C provides the sizes of the basic DEComni API MMS types. 6 6 6- - - Device Access Software for Siemens 3964 User Guide 6 6 6 7 7 7 Configuring DEComni Configuring DEComni Configuring DEComni You must configure DEComni in order to allow a DEComni application to access a Siemens 3964 device. Configuring DEComni means creating the required definitions using the following API procedures: omni_define . omni_get_definition . . omni_modify_definition _______________________ _______________________ _______________________Note Note Note_____________________ _____________________ _____________________ For an explanation of the DEComni definition attributes whose values are not specified in this chapter, refer to the DEComni API and DEComni MMS Programmer's Guide for your platform. ________________________________ ________________________________ ________________________________________________ ________________ ________________ To configure DEComni, you must: Register the appropriate entries in the OD . S database. . Set the required application profile. . Create the required DEComni VMD and Variable definitions. Device Access Software for Siemens 3964 User Guide 1 1 1 - - - 7 7 7 Configuring DEComni Registering ODS Entries Registering ODS Entries Registering ODS Entries For each Siemens 3964 device you must create an ODS entry which specifies Siemens 3964 protocol-specific information. 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 correctly associated with the desired Siemens 3964 protocol. Table 7-1 lists the available application profiles. Table Table Table : DEComni Application Profiles : DEComni Application Profiles : DEComni Application Profiles 1 1 1 7 7 7- - - Protocol Name Protocol Name Protocol Name Application Profile Constant Application Profile Constant Application Profile Constant 3964 omni_c_app_profile_3964 3964R omni_c_app_profile_3964r 3964_RK512 omni_c_app_profile_3964_rk512 3964R_RK512 omni_c_app_profile_3964r_rk512 The following example shows how an application can invoke the omni_set_application_profile procedure to set the application profile for the Siemens 3964 protocol. status=omni_set_application_profile (omni_c_app_profile_3964) Creating VMD Definitions Creating VMD Definitions Creating VMD Definitions A Siemens 3964 device is modeled by means of a VMD definition. Table 7 2 - lists the mandatory attributes that you must specify for a correct definition of a VMD. Table Table Table 7 7 7 2 2 2 - - - : DEComni VMD Attributes : DEComni VMD Attributes : DEComni VMD Attributes Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values omni_c_attr_name The name of a VMD definition. omni_c_attr_appl_si The name of an ODS entry. mple_name See Appendix A for a description of ODS entry attributes. 7 7 7 Device Access Software for Siemens 3964 User Guide - - -2 2 2 Configuring DEComni omni_c_vmd_max_segm The maximum length of the data ent exchanged with the Siemens 3964 device. For the 3964[R] protocol, there is no limit in the size of the message exchanged. You can specify any value, provided it is supported by DEComni. For the 3964[R]_RK512 protocol, there is no limit in the size of the message exchanged between DEComni applications and Siemens 3964 devices, but the message is segmented for transmission over the communication line. This attribute must specify the segment size, which must be less than, or equal to 138 (including 10 bytes for the header). Creating a VMD for Communication Through the 3964[R] Protocol Creating a VMD for Communication Through the 3964[R] Protocol Creating a VMD for Communication Through the 3964[R] Protocol A VMD is a gate that DEComni makes available to its applications to exchange data messages with a remote Siemens 3964 device using the Siemens 3964[R] protocol. Creating a VMD for Communication Through the 3964[R]_RK512 Creating a VMD for Communication Through the 3964[R]_RK512 Creating a VMD for Communication Through the 3964[R]_RK512 Protocol Protocol Protocol Depending on the operation you want to perform, you must define a remote VMD, a local VMD, or both: . A remote VMD models a remote Siemens 3964 device and associated variables. For a remote VMD, a DEComni client application acts as a client that writes and reads the value of memory blocks physically located on the associated Siemens 3964 device. A local VMD models a Siemens 3964 device emulated . on the host system. For a local VMD, BASEstar Open acts as a server that fulfills write and read requests coming from a Siemens 3964 device. Creating Variable Definitions Creating Variable Definitions Creating Variable Definitions You must create the definitions of the variables that will be used for exchanging data with Siemens 3964 devices. -3 Table 7 lists all the mandatory attributes that you must specify for a correct definition of a variable. Device Access Software for Siemens 3964 User Guide - - -3 3 3 7 7 7 Configuring DEComni Table Table Table 7 7 7 3 3 3: DEComni Variables Attributes : DEComni Variables Attributes : DEComni Variables Attributes - - - Attribute Name Attribute Name Attribute Name Description and Values Description and Values Description and Values omni_c_attr_app_ Name of the application type. The type_descr associated MMS type must be appropriate and must have a sufficient size in order to contain the data exchanged with the Siemens 3964 device. Appendix C specifies the size of the basic DEComni MMS types. Remember that the data type associated with these variables drives the DAS for Siemens 3964 in encoding/decoding the data exchanged between your application and the Siemens 3964 device. omni_c_attr_addr Only significant for Unnamed ess_type Variables, and must be set to omni_c_address_unconstrained. omni_c_attr_addr Only significant for Unnamed ess_string Variables. The value that you must provide depends on the protocol used. For the 3964[R] protocol, this attribute is not considered by the DAS for Siemens 3964, but you can use it to describe the type of the data message exchanged with the device. For the 3964[R]_RK512 protocol, this attribute must specify a valid memory block address of the Siemens 3964 device. See also the section below. Creating Variables for Communication Through the 3964[R] Creating Variables for Communication Through the 3964[R] Creating Variables for Communication Through the 3964[R] Protocol Protocol Protocol To exchange data with Siemens 3964 devices, you can use Named or Unnamed Variables. The first Named Variable you define at a given VMD is assumed to be the "reception variable", and it will be used for read operations only. If no Named_Variables are defined, the first Unnamed Variable is used. You can define as many Named or Unnamed Variables associated with the VMD as you need to send data to a Siemens 3964 device. Each of these variables can have a different data type, which allows you to send different types of data to the Siemens 3964 device. 7 7 7- - - Device Access Software for Siemens 3964 User Guide 4 4 4 Configuring DEComni Creating Variables for Communication Through the 3964[R]_RK512 Creating Variables for Communication Through the 3964[R]_RK512 Creating Variables for Communication Through the 3964[R]_RK512 Protocol Protocol Protocol When using the 3964[R]_RK512 protocol, you must use Unnamed Variables whose omni_c_attr_address_string attribute specifies a valid memory address of a Siemens 3964 device. See also Appendix D. Device Access Software for Siemens 3964 User Guide 7 7 7- - -5 5 5 8 8 8 Programming Programming Programming This chapter describes how you can use the DEComni API procedures to write a DEComni API application that is able to exchange data with a Siemens 3964 device. Bear in mind the following considerations when using the API procedures to write your application: General syntax and programming rules, that are . described in the DEComni API and DEComni MMS User Guide for your platform, are also valid when the API procedures are used in the DAS for Siemens 3964 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 DAS for Siemens 3964. Device Access Software for Siemens 3964 User Guide - - - 8 8 8 1 1 1 Programming Programming with the 3964[R] Protocol Programming with the 3964[R] Protocol Programming with the 3964[R] Protocol Programming with the 3964[R] protocol means preparing a DEComni application that is able to exchange data messages with a remote Siemens 3964 device using the 3964[R] protocol. Table 8 1 lists the DEComni API procedures that a - DEComni application can invoke to exchange data with a Siemens 3964 device. Table Table Table : DEComni API Procedures for Data Exchange : DEComni API Procedures for Data Exchange : DEComni API Procedures for Data Exchange - - -1 1 1 8 8 8 (3964[R] Protocol) (3964[R] Protocol) (3964[R] Protocol) Procedure Name Procedure Name Procedure Name Description Description Description omni_abort Causes the forced closure of a connection. Only local operations are performed. omni_conclude Causes the forced closure of a connection. It behaves like the omni_abort procedure. omni_connect Opens a connection. The request always completes successfully and the control is immediately returned to the calling application. Only local operations (for example, opening of the local port) are performed, and no negotiation is performed with the remote device. omni_get_indica Returns connection-related and tions Inforeport indications (for example, data received from the Siemens 3964 device, or connection aborted). omni_get_value Returns the data associated with a previously detected Inforeport indication. omni_put_value Writes data to the Siemens 3964 device. It is an unconfirmed operation because the procedure call completes as soon as the data have been sent through the local port. Opening a Connection Opening a Connection Opening a Connection To open a connection with a remote Siemens 3964 device when using the 3964[R] protocol, a DEComni 8 8 8 2 2 2 - - - Device Access Software for Siemens 3964 User Guide Programming application must call the omni_connect procedure and specify the handle of the remote VMD definition. A DEComni application must call the omni_get_indications procedure to monitor an incoming omni_c_ind_abort indication which notifies that the connection has been terminated for any reason. To close a connection, an application must call the omni_conclude or the omni_abort procedure. These procedures perform the same operations, have only local effect, and cause a forced closure of the connection. Sending Data Messages Sending Data Messages Sending Data Messages To send a data message to a Siemens 3964 device, a DEComni application must call the omni_put_value procedure, and specify the handle of a Named or Unnamed_Variable that is associated with the corresponding VMD definition. The omni_put_value returns control to the application as soon as the DAS for Siemens 3964 has sent the data through the local port. Receiving Data Messages Receiving Data Messages Receiving Data Messages A DEComni application that wants to wait for data coming from a remote Siemens 3964 device must call the omni_get_indications procedure, and specify the handle of the remote VMD associated with that device. Each time DEComni receives data from the remote device, it generates an Inforeport indication that causes the completion of the omni_get_indications procedure call. The omni_get_indications procedure returns to the application a context which always refers to the "reception variable": the application must issue an omni_get_value procedure call, and specify this context to get the value of the "reception variable", that is, the data received from the device. Programming with the 3964[R]_RK512 Protocol Programming with the 3964[R]_RK512 Protocol Programming with the 3964[R]_RK512 Protocol Programming with the 3964[R]_RK512 protocol means preparing server applications that are able to perform one or both of the following tasks: To behave as a client of a Siemens 3964 device, . and therefore to read and write memory blocks of that device. To behave as a server that fulfills read and write . requests coming from remote Siemens 3964 devices and addressed to the locally emulated device. Device Access Software for Siemens 3964 User Guide 3 3 3 - - - 8 8 8 Programming Table 8- lists the API procedures that an 2 application invokes to exchange data with a Siemens 3964 device. Table Table Table 8 8 8- - -2 2 2: DEComni API Procedures for Data Exchange : DEComni API Procedures for Data Exchange : DEComni API Procedures for Data Exchange (3964[R]_512 Protocol) (3964[R]_512 Protocol) (3964[R]_512 Protocol) Procedure Procedure Procedure Description Description Description Name Name Name (Local/Remote (Local/Remote (Local/Remote VMD) VMD) VMD) omni_abort Causes the forced closure of a (remote) connection. omni_conclude Causes the forced closure of a (remote) connection. It behaves like the omni_abort procedure. omni_connect Opens a connection to the Siemens (remote) 3964 device modeled by the specified remote VMD definition. The request always completes successfully and the control is immediately returned to the calling application. Only local operations (for example, opening of the local port) are performed, and no negotiation is performed with the remote device. omni_listen Makes the local VMD accessible to (local) remote clients. The request always completes successfully and the control is immediately returned to the calling application. Only local operations (for example, opening of the local port) are performed, and no negotiation is performed with the remote device. omni_get_indi Obtains connection-related cations indications and must always specify (remote) the handle of the remote VMD. When returning a Read Request or Write Request indication (corresponding to read or write requests issued by a Siemens 3964 device towards the locally emulated Siemens 3964 device), the returned context refers to a variable that is associated with the local VMD definition. omni_get_valu When specifying a variable e associated with a remote VMD, it (both local allows the DEComni client and remote) application to read the value of the associated Siemens 3964 device 8 8 8 Device Access Software for Siemens 3964 User Guide 4 4 4 - - - Programming memory block. When specifying a variable associated with a local VMD, it allows the DEComni server application to obtain the value associated with a Write Request indication. omni_put_valu When specifying a variable e associated with a remote VMD, it (both local allows the DEComni client and remote) application to write the value of the associated Siemens 3964 device memory block. When specifying a variable associated with a local VMD, it allows the DEComni server application to provide the DAS for Siemens 3964 with the value required to fulfill a previously received Read Request indication. Opening and Closing a Connection Opening and Closing a Connection Opening and Closing a Connection protocolAn application can use the omni_connect or omni_listen procedure to open a connection. The choice depends on specific application requirements and role (for example, if it is a server or client application), and on application programming interface rules. Both the omni_connect and omni_listen procedures have only local effect: they open the port that was configured in the ODS entry and was associated with the remote (or local) VMD. When using both a remote and a local VMD, you are suggested to define identical ODS entries (apart from the name) to be associated with the local and remote VMDs; in particular, you must specify the same operating system port. A DEComni application must call the omni_get_indications procedure to monitor an incoming omni_c_ind_abort indication which notifies that the connection has been terminated for any reason. To close a connection, an application calls the omni_conclude or the omni_abort procedure. These procedures perform the same operations, have only a local effect, and cause a forced closure of the connection. Reading and Writing Memory Blocks of a Siemens Device Reading and Writing Memory Blocks of a Siemens Device Reading and Writing Memory Blocks of a Siemens Device To read (or write) the value of a memory block of a remote Siemens 3964 device, a DEComni client application must call the omni_get_value (or Device Access Software for Siemens 3964 User Guide 8 8 8 5 5 5 - - - Programming omni_put_value) procedure, and specify the handle of an Unnamed Variable associated with corresponding remote VMD definition. Fulfilling Requests for an Emulated Device Fulfilling Requests for an Emulated Device Fulfilling Requests for an Emulated Device .A DEComni server application that wants to receive and fulfill Read and Write Request indications related to a locally emulated Siemens 3964 device, must call the omni_get_indications procedure, and specify the handle of the appropriate remote VMD definition. When the omni_get_indications procedure returns control to the application with an omni_c_ind_read indication, the application must issue an omni_put_value procedure call to provide the value to be returned to the client application. The omni_put_value procedure must specify the context returned by the omni_get_indications procedure. The context refers to the variable definition associated with the local VMD whose device memory address, specified in the omni_c_address_unconstrained attribute, corresponds to that specified in the client request. Similarly, when the omni_get_indications procedure returns control to the application with an omni_c_ind_write indication, the application must issue an omni_get_value procedure call to obtain the value provided by the client application; this value will be used to update the value of the variable specified in the context. 8 8 8 Device Access Software for Siemens 3964 User Guide 6 6 6 - - - PART III PART III PART III Appendices Appendices Appendices A A A ODS Entry Attributes for the Siemens 3964 Protocol ODS Entry Attributes for the Siemens 3964 Protocol ODS Entry Attributes for the Siemens 3964 Protocol This appendix describes the ODS attributes (and their associated values) that allow you to create the ODS entries required to access Siemens 3964 devices. An ODS entry contains the addressing parameters needed by the Siemens 3964 protocol, and must be specified in VMD definitions used to access Siemens 3964 devices. The information provided in this appendix is valid for all the supported protocols, and for both the BASEstar Open and DEComni API environments. For details on the use of the ODS CLI, refer to the DEComni documentation included in your documentation kit. Device Access Software for Siemens 3964 User Guide A A A- - -1 1 1 ODS Entry Attributes for the Siemens 3964 Protocol Creating ODS Entries for the Siemens 3964 Protocol Creating ODS Entries for the Siemens 3964 Protocol Creating ODS Entries for the Siemens 3964 Protocol Bear in mind that a connection to a Siemens 3964 device must be based on a LAT port. Table A-1 provides a name and an explanation for each ODS attribute. Table Table Table : ODS Entry Attributes for the Siemens 3964 : ODS Entry Attributes for the Siemens 3964 : ODS Entry Attributes for the Siemens 3964 - - -1 1 1 A A A Protocols Protocols Protocols 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 LAT communication port. Examples of valid values are tty00, TT00 and COM1. baudrate The supported speed is 9600 bits/sec. charlen The number of data bits must be set to 8. stopbit The number of stop bits must be set to 1. prtycheck The parity check must be set to NONE. flowctrl The flow control is not provided and must be set to NONE. modem Modem presence. Allowed values are 0 (modem not present, direct connection), and 1 (modem present, port handles modem signal and handshaking). stationid Not significant. lev7conn Specifies if the connection is handled with messages at application level. Must be set to 0 because Siemens 3964 protocols do not exchange messages for connection at application level. rsptimeout Timeout (in seconds) for the reception of the response to a confirmed service, after which the service is terminated with failure. Only applicable to the 3964[R]_RK512 protocol. Example A 1 - shows a configuration file command that can be used to create an ODS registration valid for all the supported Siemens 3964 protocols. A A A- - - Device Access Software for Siemens 3964 User Guide 2 2 2 ODS Entry Attributes for the Siemens 3964 Protocol Example Example Example A A A 1 1 1: ODS Entry for LAT Port : ODS Entry for LAT Port : ODS Entry for LAT Port - - - register directory name "/cn=SIEMENS_3964" attributes "/oc=DTK232 /levconn=0 /portname=tty00 /baudrate=9600 /charlen=8 /stopbit=1 /prtycheck=NONE /flowctrl=NONE /modem=0" Device Access Software for Siemens 3964 User Guide 3 3 3 A A A- - - ODS Entry Attributes for the Siemens 3964 Protocol Configuring a LAT Port Configuring a LAT Port Configuring a LAT Port OpenVMS Platform OpenVMS Platform OpenVMS Platform You can physically connect a device to a LAT port. To use a LAT port, the port must be configured using the LAT control program. For example, to configure port LTA001:, connected to the PORT_1 port of the TSRV1 terminal server, perform the following steps: 1.Log onto an account having the OPER privilege. 2.Invoke the LAT control program: $ mc latcp Create the LAT port: LATCP> create port LTA001: /application 3.Set the Terminal Server node and port names: LATCP> set port LTA001: /node=TSRV1/port=PORT_1 Digital UNIX Platform Digital UNIX Platform Digital UNIX Platform To set up the LAT service on a DEC OSF/1 system use the following command: /usr/sbin/latsetup Please refer to the DEC OSF/1 Network Manager's Guide or to the online man pages for details on the latsetup command. If you are not sure about which terminal special files are assigned to the LAT service, you can issue the following command: file /dev/tty* and look for the entries like: /dev/tty02: character special (5/0) LAT #0 DS200 terminal #0 Once you know which special files are assigned to the LAT services, you can set a reverse LAT connection to a terminal server port by issuing the command: /usr/sbin/latcp -A -ptty02 -HSERVER -RPORT_1 where tty02 is the name of the local LAT port you want to use for the connection, SERVER is the terminal server name, and PORT_1 is the name of the A A A 4 4 4 - - - Device Access Software for Siemens 3964 User Guide ODS Entry Attributes for the Siemens 3964 Protocol port you want to connect to, that is, the port on which the device is hooked on. In order to have this command automatically executed at system startup, you can add the command to the /sbin/init.d/lat file at the end of the start case (look at the end of file). In the example above the LAT port tty02 is used, which corresponds to the special file /dev/tty02. To use that port from a DEComni application, you should register a VMD entry by means of the odscl utility, using tty02 as the value for the /PORTNAME attribute (note that /dev is omitted). Device Access Software for Siemens 3964 User Guide A A A- - -5 5 5 B B B BASEstar Open Datatype Sizes BASEstar Open Datatype Sizes BASEstar Open Datatype Sizes The number of bytes involved in a write or read operation depends on the Datatype associated with the Device Services Variable in use. Table B-1 lists the size (in bytes) of the basic BASEstar Open Datatypes: this allows you to define a Datatype that has a size appropriate for the data to be exchanged with the Siemens 3964 device. B B B- - - Table Table Table 1 1 1: BASEstar Open Simple Datatype Sizes : BASEstar Open Simple Datatype Sizes : BASEstar Open Simple Datatype Sizes Datatype Datatype Datatype Exchanged as Exchanged as Exchanged as BOOLEAN 1 byte TIME Not supported VISIBLE_CHAR 1 byte INTEGER_8 1 byte INTEGER_16 2 bytes 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, BCD4, Not supported 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 Device Access Software for Siemens 3964 User Guide - - - B B B 1 1 1 C C C DEComni API MMS Type Sizes DEComni API MMS Type Sizes DEComni API MMS Type Sizes The number of bytes involved in a write or read operation depends on the MMS type associated with the DEComni variable in use. Table C-1 lists the size (in bytes) of the basic DEComni MMS types: this allows you to define a data type that has a size appropriate for the data to be exchanged with the Siemens 3964 device. C C C- - - Table Table Table 1 1 1: DEComni API MMS Type Sizes : DEComni API MMS Type Sizes : DEComni API MMS Type Sizes Data Type Data Type Data Type Exchanged as Exchanged as Exchanged as omni_c_mmstype_boolean 1 byte omni_c_mmstype_bit_str + 7)/ 8) bytes, where n ( n is the number of bits in the string omni_c_mmstype_integer 1, 2 or 4 bytes, depending on omni_c_symbol_size, that specifies the size of the variable (8, 16, or 32 bits) omni_c_mmstype_unsigned 1, 2 or 4 bytes, depending on omni_c_symbol_size, that specifies the size of the variable (8, 16, or 32 bits) omni_c_mmstype_floating 4 bytes (SINEC float _point format) omni_c_mmstype_real Not supported omni_c_mmstype_octet_st bytes (as returned by n r sizeof()) omni_c_mmstype_visible_ bytes (as returned by n str strlen() if varying or as returned by sizeof() otherwise) omni_c_mmstype_generali Not supported zed_time omni_c_mmstype_binary_t Not supported ime Device Access Software for Siemens 3964 User Guide 1 1 1 C C C- - - D D D Siemens 3964 Memory Addresses Siemens 3964 Memory Addresses Siemens 3964 Memory Addresses This appendix describes how to specify a valid Siemens 3964 memory address. For complete information refer to the Siemens product documentation of the specific Siemens 3964 device. The following syntax shows how you can define a valid memory address of a Siemens 3964 device. BlockType:BlockNumber:StartingAddress BlockType can assume any of the values specified in Table D-1. - - - Table Table Table D D D : DEComni : DEComni : DEComni 1 1 1 BlockType BlockType BlockType Attribute Values Attribute Values Attribute Values Block Type Block Type Block Type Description Description Description Block Block Block Starting Starting Starting Number Number Number Address Address Address DB Data Block From 1 to From 0 to 255 2047 DX Extended DB From 1 to From 0 to 255 2047 IB Input Byte From 0 to 255 For S5 150: 0 / 199 QB Output Byte From 0 to 127 FY Flag Byte From 0 to 127 PY Peripheral From 0 to 255 Byte CB Counter From 0 to 255 Location TB Timer From 0 to 255 Location AS Absolute From 0 to Address FFFF RS System From 0 to 511 Address OY Extended I/O From 0 to 511 Device Access Software for Siemens 3964 User Guide 1 1 1 D D D- - - E E E DEComni API Network IOSB Messages DEComni API Network IOSB Messages DEComni API Network IOSB Messages This appendix lists the DEComni API messages that can be returned by the DAS for Siemens 3964 in the Network IOSB. dastk_s_success 80125953 Explanation: Explanation: Explanation: das toolkit service completed successfully. User action: User action: User action: none. dastk_s_asoabort 80125962 Explanation: Explanation: Explanation: the association has been aborted by the peer. User action: User action: User action: none. dastk_s_asoalrdyexist 80125970 Explanation: Explanation: Explanation: an association with the same parameters already exists. User action: User action: User action: change vmd addressing parameters. dastk_s_nolicense 80125978 Explanation: Explanation: Explanation: no valid licenses have been loaded. User action: User action: User action: install and load a valid pak for this product. dastk_s_nosuchasn 80125986 Explanation: Explanation: Explanation: the specified application simple name has not been found in ODS. User action: User action: User action: check ods configuration. dastk_s_nosuchaso 80125994 Explanation: Explanation: Explanation: the specified association does not exist. User action: User action: User action: check if you refer to the right association. dastk_s_reqabort 80126002 Explanation Explanation Explanation: : : the specified request has been aborted. User action: User action: User action: none. dastk_s_reqtimeout 80126010 Explanation Explanation Explanation the timer for the specified request : : : expired. User action: User action: User action: none. dastk_s_connerr 80126018 Explanation Explanation Explanation a generic error occured on the : : : communication layer. User action: User action: User action: none. dastk_s_insfmem 80126026 Explanation Explanation Explanation: : : insufficient virtual memory. User action: User action: User action: none. Device Access Software for Siemens 3964 User Guide - - -1 1 1 E E E DEComni API Network IOSB Messages dastk_s_lentoolrg 80126034 Explanation Explanation Explanation pdu length exceeds the maximum : : : allowed value. User action: User action: User action: redesign user application to use smaller object values. dastk_s_generr 80126042 Explanation: Explanation: Explanation: generic error. User action: User action: User action: none. E E E 2 2 2 - - - Device Access Software for Siemens 3964 User Guide Index Index Index reception variable, 4-5; A A A 4 6 - selecting servers, 4-2 Accessing a device BASEstar Open Datatypes through BASEstar Open, 3- mapping, B 2 -1 through the DEComni API, BASEstar Open messages 2 6- returned in the Network IOSB, E 1 - B B B BASEstar Open users Datatype size, 3 7 - BASEstar Open components reading data DAS for Siemens 3964, 3 3; - 3964[R] protocol, 3-4 2 - 6 3964[R]_RK512 protocol, Data Services, 3 2 - 6; 3 7 - 3- DEComni API, 3-3 writing data Device Services, 3 3 - 3964[R] protocol, 3-4 ODS, 3 3 - BASEstar Open configuration C C C configuration example 3964[R] protocol, 5 2 - Closing a connection 3964[R]_RK512 protocol, through DEComni API 5; 5 - 5 7 - procedures creating Data Services 3964[R] protocol, 8-2 objects, 4 6 - 3964[R]_RK512 protocol, creating Device Sevices -4 8 objects, 4 2 - Configuring a LAT port, A 3 - creating ODS entries, 4-2 Configuring BASEstar Open creating creating Data Services Protocol_Profiles, 4-2 objects, 4-6 creating VMDs, 4 3 - creating Device Services Device_Data_Points for objects, 4-2 receive operations creating ODS entries, 4 2 - 3964[R] protocol, 4-6 creating Device_Data_Points for Protocol_Profiles, 4-2 send operations creating VMDs, 4-3 3964[R]_RK512 protocol, example 7 4- 3964[R] protocol, 5-2 Device Access Software for Siemens 3964 User Guide Index- Index- Index-1 1 1 3964[R]_RK512 protocol, writing data - 7 5 - 5; 5 3964[R] protocol, 6-3 overview, 4 1 - DEComni API configuration selecting servers, 4 2 - creating ODS entries, 7 2 - Configuring the DEComni API creating variable creating ODS entries, 7-2 definitions, 7 3 - creating variable creating VMD definitions, definitions, 7 3 - 7 2 - creating VMD definitions, overview, 7-1 2 - 7 setting the application overview, 7 1 - profile, 7-2 setting the application DEComni components profile, 7 2 - DEComni API, 6-2 ODS, 6 2 - D D D DEComni messages returned in the Network DAS for Siemens 3964 IOSB, E-1 features, 1 1 - DEComni MMS Types installation on Digital calculating the zize of, UNIX systems, 2 3 - 1 C- installation on OpenVMS Device access systems, 2 2 - through BASEstar Open, 3 2 - installation overview, 2 1 - through the DEComni API, role in BASEstar Open, 3- 2 6- 2 - 3; 6 Device Services Data exchange role in BASEstar Open, 3 3 - through DEcomni API Device_Data_Point attributes procedures for send operations 3964[R] protocol, 8 2 - 3964[R] protocol, 4 7 - 3964[R]_512 protocol, 8 3 - 3964[R]_RK512 protocol, Data Services 7 - 4 role in BASEstar Open, 3 2 - Decomni API I I I role in BASEstar Open, 3 3 - role in DEComni, 6 2 - Installing the DAS for DEComni API applications Siemens 3964 API procedures for Digital UNIX platform, 2 3 - connection to a device OpenVMS platform, 2 2 - 3964[R] protocol, 8-2 3964[R]_RK512 protocol, L L L 8 4 - API procedures for data LAT port exchange configuration, A-3 3964[R] protocol, 8 2 - 3964[R]_512, 8 3 - M M M 3964[R]_RK512 protocol, 4 8- Mapping BASEstar Open API procedures for device Datatypes, B 1 - emulation MMS data types in DEComni, 3964[R]_RK512 protocol, - C 1 4 - 8 reading data O O O 3964[R] protocol, 6 3 - 3964[R]_RK512 protocol, ODS 5 - - 4; 6 6 role in BASEstar Open, 3 3 - role in DEComni, 6-2 access through the DEComni ODS entry attributes for API, 7-3 Siemens 3964, A-2 VMD attributes Opening a connection access through BASEstar through DEComni API Open, 4 3 - procedures access through the DEComni 3964[R] protocol, 8 2 - API, 7-2 R R R W W W Reading data Writing data DEComni API BASEstar Open 3964[R] protocol, 6 3 - 3964[R] protocol, 3-4 through BASEstar Open through BASEstar Open 3964[R] protocol, 3 4 - 3964[R] protocol, 3-4 3964[R]_RK512protocol, 3- 3964[R]_RK512 protocol, 6; 3-7 - 7 6; 3- 3 through DEComni API Datatype size, 3-7 3964[R] protocol, 6 3 - through DEComni API through the DEComni API 3964[R] protocol, 6- - 3; 6 3964[R] protocol, 8 2 - 4 Reception variable 3964[R]_RK512 protocol, configuration, 4 5 - - - 6 4; 6 5 definition of, 3 -3 -5; 6 through the DEComni API 3964[R] protocol, 8-2 S S S Writing DEComni API applications Siemen 3964 API procedures for device memory addresses, connection to a device D-1 3964[R] protocol, 8-2 3964[R]_RK512 protocol, V V V 4 8- API procedures for data Variable attributes exchange access through BASEstar 3964[R] protocol, 8-2 Open, 4 5 - 3964[R]_512, 8-3 Device Access Software for Siemens 3964 User Guide Index- Index- Index-3 3 3