DECosap/AP_and_DECosap/H1_for_DIGITAL_UNIX__________ Release Notes March 1997 This document describes the release notes for DECosap /AP and DECosap/H1 for DIGITAL UNIX Version 3.1 software and documentation. Please read this document before using the product, and consult it before reporting problems to DIGITAL. Revision/Update Information: This is a new document for the current release. Software Version: DECosap/AP and DECosap /H1 Version 3.1 Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ March 1997 © Digital Equipment Corporation 1997. Possession, use, or copying of the software described in this documentation is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor. Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: Alpha AXP, BASEstar, DEC, DECmessageQ, DECnet, DECnet-DOS, DECosap, DEComni, DIGITAL, DIGITAL UNIX, FMS, LN03, MicroVAX, NAS, OpenVMS, OpenVMS Alpha, PATHWORKS, PDAS, Rdb/VMS, ReGIS, ThinWire, TK, ULTRIX, VAX, VAXcluster, VAX COBOL, VAX FORTRAN, VAX Pascal, VAX RMS, VMS/ULTRIX Connection, VT, and the DIGITAL logo. The following are third-party trademarks: Excel is a registered trademark of Microsoft Corporation. IBM is a registered trademark of IBM Corp. INGRES is a trademark of Ingres Corp. LOTUS 1-2-3 is a registered trademark of Lotus Development Corp. MS, Microsoft, and MS-DOS are registered trademarks of Microsoft Corporation. Network File System and NFS are trademarks of Sun Microsystems, Inc. ORACLE is a trademark of Oracle Corp. PostScript is a registered trademark of Adobe Systems Incorporated. SINEC AP, SINEC H1, SICOMP, Simatic, SINEC, SINUMERIK and SIROTEC are registered trademarks of Siemens, AG. UNIX is a registered trademark licensed exclusively by X /Open Company Ltd. Windows, Windows NT and Windows 95 are trademarks of Microsoft Corporation. Wonderware InTouch is a registered trademark of Wonderware Corporation. X/Open is a registered trademark of the X/Open Company Limited This document was prepared using VAX DOCUMENT, Version 2.1. _________________________________________________________________ Contents Preface................................................... v 1 General Notes 1.1 The DECosap/AP and DECosap/H1 Docset............. 1-1 1.2 Pre-requisites................................... 1-1 1.3 Warning.......................................... 1-1 2 Release Notes Specific to DIGITAL UNIX Platforms 2.1 Dynamic Loading of DASes......................... 2-1 2.2 Selective Support for Protocols.................. 2-1 2.3 Linking Your Application......................... 2-2 2.4 Using the User Data Buffer....................... 2-2 2.5 Features Not Documented Elsewhere................ 2-2 2.6 Restrictions..................................... 2-5 2.6.1 omni_cancel ................................... 2-5 2.6.2 Time Datatypes ................................ 2-5 2.6.3 Application Not Informed of Pending Indication..................................... 2-5 2.6.4 Maximum PDU Size .............................. 2-5 2.6.5 Establishing an Association Between Two SINEC H1 VMDS........................................ 2-5 2.6.6 Unnamed Variable Access ....................... 2-6 2.6.7 Type Definitions for FORTRAN Application ...... 2-6 2.6.8 Using Application Languages Other than C ...... 2-6 2.7 Bug Fixes........................................ 2-6 iii _________________________________________________________________ Preface v 1 _________________________________________________________________ General Notes 1.1 The DECosap/AP and DECosap/H1 Docset The DECosap/AP and DECosap/H1 for DIGITAL UNIX Version 3.1 docset comprises the following manuals: o DECosap for DIGITAL UNIX Installation Guide o DECosap for OSF/1 AXP Network Manager's and Programmer's Guide[1] 1.2 Pre-requisites The DECosap/AP and DECosap/H1 for DIGITAL UNIX Version 3.1 has the following pre-requisites: o DIGITAL UNIX Version 3.2 o DECnet/OSI for DIGITAL UNIX Version 3.2 or 4.0 o DEComni API for DIGITAL UNIX Version 3.2 or 4.0 1.3 Warning DIGITAL UNIX Versions 4.0, 4.0A and 4.0B contain a bug that prevents you from using DECosap/AP and DECosap/H1. For this reason, you require a mandatory patch kit for each version of the operating system, as indicated in the list below: o Version 4.0-OSF400-151 o Version 4.0A-OSF405-400151 o Version 4.0B-OSF410-400151 ____________________ [1] OSF/1 is now referred to as DIGITAL UNIX General Notes 1-1 2 _________________________________________________________________ Release Notes Specific to DIGITAL UNIX Platforms 2.1 Dynamic Loading of DASes DEComni API Version 3.1 allows you to integrate DECosap /AP and DECosap/H1 dynamically. DEComni API provides a registration utility for new integrators: omni_registry. This utility allows DECosap/AP and DECosap/H1 to register themselves under DEComni API by specifying their shareable images. Using the information in the registry database, DEComni API Version 3.1 is able to locate and load the shareable images dynamically during its initialization phase. 2.2 Selective Support for Protocols The DECosap/AP and DECosap/H1 Version 3.1 installation procedure allows you to install the support for SINEC AP and SINEC H1 protocols separately, as follows: o SINEC AP protocol support only o SINEC H1 protocol support only o Both SINEC AP and SINEC H1 protocol support Two alternative licences are available for each of the protocols. For each protocol, you can use either DECOSAP- AP or DECOSAP-H1, which are unlimited licenses, or DECOSAP-AP-USER and DECOSAP-H1-USER, which are licenses limited according to the connection number. It is recommended that you skip the installation of a protocol if the associated license has not been registered and loaded. Release Notes Specific to DIGITAL UNIX Platforms 2-1 Release Notes Specific to DIGITAL UNIX Platforms 2.3 Linking Your Application 2.3 Linking Your Application There are two solutions for using DECosap on DIGITAL UNIX platforms: o Link the application program to libomniclt.so and use the omni_server procedure: cc -o myprog myproc.c -lomniclt o Link the application program to libomniapi.so, an DEComni API shareable that allows you to write multithread applications: cc -o myprog myproc.c -lomniapi -threads 2.4 Using the User Data Buffer The user data buffer must always: o Reflect the DEComni API object it is associated with o Be large enough to contain all the data The buffer size to be passed to the DEComni API function call is the whole buffer size, even if only a part of the buffer is being used. If the size passed to the call is smaller than expected for the object buffer the omni_* calls fail for the SINEC AP and SINEC H1 protocol. It is strongly suggested that you use the macro sizeof from the C language. When a variable is accessed with an alternate access method (for example, using the handle method), the buffer to be passed to the omni_get_value, omni_put_value and omni_send_value function calls is the buffer for the whole variable though only the part (or the parts) of buffer referenced by the alternate access data type is accessed. 2.5 Features Not Documented Elsewhere The following features have not been included in the DECosap for DIGITAL UNIX documentation: o TSAP Format for SINEC H1 VMDs 2-2 Release Notes Specific to DIGITAL UNIX Platforms Release Notes Specific to DIGITAL UNIX Platforms 2.5 Features Not Documented Elsewhere The DECosap/AP and DECosap/H1 for DIGITAL UNIX Version 3.1 kit allows a new optional format to define the Read, Write and Message TSAPs for SINEC H1 VMDs in the ODS database. The old format, still supported, restricted the naming of TSAP to a string not longer than 7 character to which the character 'R', 'W', or 'M' was appended for the Read, Write and Message outgoing connection requests respectively. The new format is: /TSAP={R:ReadTSAP.W:WriteTSAP.M:MessageTSAP All the three TSAPs are optional and can be specified in any order, but at least one must be specified. The network connection is activated only if both the associated TSAP is defined and the associated open or not open service has been enabled for the VMD. o omni_get_remote_attributes The service omni_get_remote_attribute for Named Variables is supported in server mode as well. The service is handled automatically, and there is no application support required. o PAK Name and Policy for DECosap for DIGITAL UNIX The Product Authorization Key (PAK) for decosap has been split into two distinct PAK and changed the name from DECosap to DECosap-AP for the SINEC AP protocol services and DECosap-H1 for the SINEC H1 protocol services. A concurrent use version of the PAK, on a per connection basis, is also available. The PAK names are DECOSAP-AP- USER for the SINEC AP protocol services and DECOSAP-H1- USER for the SINEC H1 protocol services. You can find templates for the PAK form in the /usr/var/adm/lmf directory, to ease the PAK registration. o omni_print_value This function is provided to allow to print the value of the buffer associated to a variable. o omni_lookup_value Release Notes Specific to DIGITAL UNIX Platforms 2-3 Release Notes Specific to DIGITAL UNIX Platforms 2.5 Features Not Documented Elsewhere This function is provided to allow to look at the value of the buffer associated to a variable after the reception of a write indication without generating any confirmation. o Using numeric address for AP Unnamed Variables Unnamed Variables can also be defined by using the numeric address of the variable on the remote VMD for the SINEC AP protocol, as well as by using the unconstrained address format. The remote address of a Named Variable on a remote PLC can be obtained by means of the calls omni_get_remote_attributes specifying the handle of the remote Named Variable and omni_c_attr_all as attribute class, and omni_get_attributes using the context returned by omni_get_remote_attributes and omni_c_attr_address as attribute. The address returned by omni_get_attributes in an omni_r_address structure can be used to define an Unnamed Variable, using the information in the omni_l_address_type and omni_r_address_value fields of the returned structure to define, respectively, omni_c_attr_address_type and omni_c_address_number attributes of the variable. Refer to the DEComni API for DIGITAL UNIX Installation Guide and the DECosap for OSF/1 AXP Network Manager's and Programmer's Guide[1] for additional information about defining Named and Unnamed Variables. Depending on the implementation of the variable access by numeric address on the remote VMD, this procedure should speed up the access to remote variable defined by name on VMDs where several variables are defined and a search by name can take longer. As of Version 2.0 of DEComni API for DIGITAL UNIX, the omni_get_remote_attribute service is supported in server mode as well, and the access to Named Variable through their address number should be faster. ____________________ [1] OSF/1 is now referred to as DIGITAL UNIX 2-4 Release Notes Specific to DIGITAL UNIX Platforms Release Notes Specific to DIGITAL UNIX Platforms 2.5 Features Not Documented Elsewhere The numeric address format is strictly dependent on the architecture and operating system dependent and it is subject to change without notice. The use of numeric address returned by get_remote_attribute from a remote VMD emulated by a DEComni API application is not supported. 2.6 Restrictions The restrictions in this section apply to the DECosap/AP and DECosap/H1 Version 3.1 kit. 2.6.1 omni_cancel Due to a problem in DECosap/AP and DECosap/H1 for DIGITAL UNIX Version 3.1, the omni_cancel service may not work correctly. 2.6.2 Time Datatypes The application type omni_c_apptype_omni_time and the MMS type omni_c_mmstype_generalized_time are not supported by DECosap. The application type omni_c_apptype_unix_time and the MMS type omni_c_mmstype_binary_time are only supported by the SINEC AP services. 2.6.3 Application Not Informed of Pending Indication If an abort indication is received, all the other pending indications are aborted without notification. 2.6.4 Maximum PDU Size The maximum size for network PDUs supported by DECosap, for both the SINEC AP and SINEC H1 protocols, is 4096 bytes. This restricts the maximum size for data roughly to 4000 bytes, or less for complex variable. Longer PDUs may lead to unpredictable results. 2.6.5 Establishing an Association Between Two SINEC H1 VMDS A user application may hang if it tries to establish an association between two SINEC H1 VMDs whose definitions do not correspond in terms of services enabled (for example, one enabling read and write operations, and the other messages only). Release Notes Specific to DIGITAL UNIX Platforms 2-5 Release Notes Specific to DIGITAL UNIX Platforms 2.6 Restrictions 2.6.6 Unnamed Variable Access When using the Unnamed Variable access with a real Siemens PLC the only usable type is "octet string" and, as a consequence, alternate access is not allowed due to a restriction imposed by Siemens. 2.6.7 Type Definitions for FORTRAN Application The type definitions omni_osap_a_notopen_srvspt and omni_osh1_a_notopen_srvspt are not available for FORTRAN programmers. Instead, use BYTE*6 and BYTE*2 variables respectively. 2.6.8 Using Application Languages Other than C If you want to use a different application language from C, you must include commands for the following files in your OMNI_INTEGRATORS_DEFS. file: o OMNI_INTEGRATOR2_DEFS_INCLUDE. (for DECosap/AP), and/or o OMNI_INTEGRATOR3_DEFS_INCLUDE. (for DECosap/H1). 2.7 Bug Fixes This section describes the problems that have been fixed in DECosap/AP and DECosap/H1 for DIGITAL UNIX Version 3.1 o The Maximum Segment Size field in the Negotiated VMD structure was erroneously set by the omni_listen call. o DECosap always tried to negotiate a Maximum Segment Size of 512 bytes regardless of what you had specified in the VMD definition. o Under some circumstances, it was not possible to re- submit omni_listen calls for connections previously set and aborted/concluded. 2-6 Release Notes Specific to DIGITAL UNIX Platforms