DECosap_for_Digital_UNIX____________________________ Release Notes February 1996 This document describes the release notes for DECosap for Digital UNIX Version 3.0 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 Version 3.0 Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ February 1996 © Digital Equipment Corporation 1996. Possession, use, or copying of the software described in this documentation is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: Alpha AXP, BASEstar, DEC, DECmessageQ, DECnet, DECnet-DOS, DECosap, DEComni, Digital, Digital UNIX, FMS, LN03, MicroVAX, NAS, OpenVMS, OpenVMS Alpha, PATHWORKS, PDAS, Rdb/VMS, ReGIS, ThinWire, TK, ULTRIX, VAX, VAXcluster, VAX COBOL, VAX FORTRAN, VAX Pascal, VAX RMS, VMS/ULTRIX Connection, VT, and the DIGITAL logo. The following are third-party trademarks: Excel is a registered trademark of Microsoft Corporation. IBM is a registered trademark of IBM Corp. INGRES is a trademark of Ingres Corp. LOTUS 1-2-3 is a registered trademark of Lotus Development Corp. MS, Microsoft, and MS-DOS are registered trademarks of Microsoft Corporation. Network File System and NFS are trademarks of Sun Microsystems, Inc. ORACLE is a trademark of Oracle Corp. PostScript is a registered trademark of Adobe Systems Incorporated. SINEC AP, SINEC H1, SICOMP, Simatic, SINEC, SINUMERIK and SIROTEC are registered trademarks of Siemens, AG. UNIX is a registered trademark licensed exclusively by X /Open Company Ltd. Windows and Windows NT are trademarks of Microsoft Corporation. Wonderware InTouch is a registered trademark of Wonderware Corporation. X/Open is a registered trademark of the X/Open Company Limited This document is available on CDROM. This document was prepared using VAX DOCUMENT, Version 2.1. _________________________________________________________________ Contents Preface................................................... v 1 General Notes 1.1 The DECosap Docset............................... 1-1 2 SINEC H1 Features 2.1 Application Programming Interface Calls.......... 2-1 3 SINEC AP Features 3.1 Application Programming Interface Calls.......... 3-1 3.2 Specific Restrictions for SINEC AP Connections... 3-8 4 MMS Types 4.1 MMS Simple Types................................. 4-1 4.2 MMS Complex Types................................ 4-1 5 Application Types 5.1 Application Simple Types......................... 5-1 5.2 Application Complex Types........................ 5-1 iii 6 Release Notes Specific to Digital UNIX Platforms 6.1 Dynamic Loading of DASes......................... 6-1 6.2 Defining Null-Internet........................... 6-1 6.3 Starting the DEComni Daemon...................... 6-1 6.4 Compiling and Linking your Application........... 6-2 6.5 Using the User Data Buffer....................... 6-2 6.6 Features Not Documented Elsewhere................ 6-3 6.7 Known Problems................................... 6-5 6.8 Bug Fixes........................................ 6-6 6.8.1 Incorrect Negative Float for DECosap/H1 ....... 6-7 6.9 Incorrect Decoding of Float 0 in DECosap/H1...... 6-7 iv _________________________________________________________________ Preface v 1 _________________________________________________________________ General Notes The structure of this document is as follows: o o 1.1 The DECosap Docset The DECosap for Digital UNIX Version 3.0 docset includes the following manuals: o o The DECosap for Digital UNIX Version 3.0 has the following prerequisites: o Digital UNIX Version 3.2 o DECnet OSI for Digital UNIX Version 3.0 or 3.2 o DEComni API for Digital UNIX Version 3.0 General Notes 1-1 2 _________________________________________________________________ SINEC H1 Features 2.1 Application Programming Interface Calls DECosap H1 for Digital UNIX supports the following calls: o omni_poll o omni_get_fd o omni_set_application_profile o omni_initialize o omni_terminate o omni_define - VMD - unnamed variable - message - domain - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_get_definitions - VMD - unnamed variable - message SINEC H1 Features 2-1 SINEC H1 Features 2.1 Application Programming Interface Calls - domain - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_modify_definitions - VMD - unnamed variable - message - domain - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_connect o omni_listen o omni_conclude o omni_accept_connect o omni_reject_connect o omni_abort o omni_reject 2-2 SINEC H1 Features SINEC H1 Features 2.1 Application Programming Interface Calls o omni_get_value - unnamed variable * simple types * complex types (full access) * read client * write server - message * write client (unacknowledged) o omni_put_value - unnamed variable * simple types * complex types (full access) * write client * read server o omni_get_indications - variable access services * unnamed variable - simple types - complex types . full access - read server - write server - serial transfer services * write client (unacknowledged) o omni_get_handle_by_name - VMD - unnamed variable - message - domain SINEC H1 Features 2-3 SINEC H1 Features 2.1 Application Programming Interface Calls - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_send_value - message * write server (unacknowledged) o omni_cancel o omni_get_remote_attributes - VMD * status client o omni_group_variables o omni_get_attribute - VMD * status client o omni_get_handle_list - VMD - unnamed variable - message - domain - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component 2-4 SINEC H1 Features SINEC H1 Features 2.1 Application Programming Interface Calls - application structure component o omni_end_list o omni_delete - domain * delete client o omni_delete_definition o omni_upload o omni_download o omni_start o omni_stop ________________________ Note ________________________ In DECosap for Digital UNIX Version 3.0 the SINEC H1 message services are not enabled by default. The application must ensure that these services are enabled when defining the H1 VMDs. ______________________________________________________ SINEC H1 Features 2-5 3 _________________________________________________________________ SINEC AP Features 3.1 Application Programming Interface Calls DECosap AP for Digital UNIX supports the following calls: o omni_poll o omni_get_fd o omni_set_application_profile o omni_initialize o omni_terminate o omni_define - VMD - named variable - unnamed variable - message - domain - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_get_definitions - VMD - named variable SINEC AP Features 3-1 SINEC AP Features 3.1 Application Programming Interface Calls - unnamed variable - message - domain - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_modify_definitions - VMD * status server * identify server - named variable - unnamed variable - domain - program invocation - message - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_connect o omni_listen o omni_conclude o omni_accept_connect 3-2 SINEC AP Features SINEC AP Features 3.1 Application Programming Interface Calls o omni_reject_connect o omni_accept_conclude o omni_reject_conclude o omni_abort o omni_reject o omni_get_value - named variable * simple types * complex types (both full access and alternate access) * read client * write server * information report client - unnamed variable * simple types * complex types (both full access and alternate access) * read client * write server * information report client - message * read client * write server (acknowledged) * write client (unacknowledged) * examine server o omni_put_value - named variable * simple types * complex types (both full access and alternate access) SINEC AP Features 3-3 SINEC AP Features 3.1 Application Programming Interface Calls * write client * read server - unnamed variable * simple types * complex types (both full access and alternate access) * write client * read server - message * write client (acknowledged) * read server o omni_get_indications - environment management services * conclude server - VMD support services * unsolicited status client - variable access services * named variable - simple types - complex types . full access . alternate access - read server - write server - information report client * unnamed variable - simple types - complex types . full access 3-4 SINEC AP Features SINEC AP Features 3.1 Application Programming Interface Calls . alternate access - read server - write server - information report client - serial transfer services + read server + write server + write client (unacknowledged) + exchange server o omni_get_handle_by_name - VMD - named variable - unnamed variable - message - domain - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_send_value - named variable * information report client * information report server - unnamed variable * information report client * information report server SINEC AP Features 3-5 SINEC AP Features 3.1 Application Programming Interface Calls - message * information report client * write server (unacknowledged) - VMD * unsolicited status server o omni_cancel o omni_get_remote_attributes - VMD * status client * list of objects client * identify client * capability list client - named variable * access attributes client * access attributes server - domain * attributes client - program invocation * attributes client o omni_exchange_data - exchange client - exchange server o omni_group_variables o omni_get_attribute - VMD * status client * list of objects client * identify client * capability list client 3-6 SINEC AP Features SINEC AP Features 3.1 Application Programming Interface Calls - named variable * access attributes client - unnamed variable * access attributes client - domain * attributes client - program invocation * attributes client o omni_get_handle_list - VMD - named variable - unnamed variable - message - domain - program invocation - MMS named type - application named type - MMS type specification - application type specification - MMS structure component - application structure component o omni_end_list o omni_create - program invocation * create client o omni_delete - domain * delete client SINEC AP Features 3-7 SINEC AP Features 3.1 Application Programming Interface Calls - program invocation * delete client o omni_delete_definition o omni_upload o omni_download o omni_start o omni_stop o omni_kill o omni_reset o omni_resume 3.2 Specific Restrictions for SINEC AP Connections DECosap AP for Digital UNIX has the following restriction with 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: that is due to a restriction imposed by Siemens. When using the Unnamed Variable access with the emulator you are allowed to request all the features applicable also to the Named Variable. 3-8 SINEC AP Features 4 _________________________________________________________________ MMS Types 4.1 MMS Simple Types DECosap for Digital UNIX supports the following MMS simple types: o Boolean o bit string o integer o unsigned o floating point o octet string o visible string o binary time o BCD 4.2 MMS Complex Types DECosap for Digital UNIX supports the following MMS complex types: o array o structure MMS Types 4-1 5 _________________________________________________________________ Application Types 5.1 Application Simple Types DECosap for Digital UNIX supports the following application simple types: o Boolean o bit string o integer o unsigned o f_floating point o terminated string o word counted string o scalar string o Boolean array o unix time 5.2 Application Complex Types DECosap for Digital UNIX supports the following application complex types: o array o structure Application Types 5-1 6 _________________________________________________________________ Release Notes Specific to Digital UNIX Platforms 6.1 Dynamic Loading of DASes DEComni API Version 3.0 allows DECosap/AP and DECosap /H1 to be integrated dynamically. DEComni API provides a registration utility for new integrators: omni_registry. This utility allows DECosap/AP and DECosap/H1 to register themself under DEComni API by specifying their shareable images. Using the information in the registry database, DEComni API Version 3.0 is able to locate and load the shareable images dynamically during its initialization phase. 6.2 Defining Null-Internet To define null-internet, add the following line to the DECnet/OSI Phase V configuration file /var/dna/scripts/start_routing.ncl: set routing circuit inactive area address {49::FF-FF} 6.3 Starting the DEComni Daemon To start the DEComni daemon, enter the following command: # /usr/sbin/omni_startup.sh It is recommended that the DEComni daemon is automatically started during system startup. Release Notes Specific to Digital UNIX Platforms 6-1 Release Notes Specific to Digital UNIX Platforms 6.4 Compiling and Linking your Application 6.4 Compiling and Linking your Application DEComni API Version 3.0 will be the last version of DEComni API to support omni_server. With DEComni API Version 3.0, a new facility is provided for linking applications: the "collapsed" approach. Using the "collapsed" approach, a DEComni API application is linked to the libomniapi.so shareable, so that the omni_server procedure is no longer required. To build your executable program with omni_server, use the following command: # cc -o myprog myprog.c -lomniclt -lcr_r -lmach -lbsd To build your executable program with the collapsed shareable, use the following command: # cc -o myprog myprog.c -lomniapi -lpthreads -lcr_r -lmach -lbsd Some rules need to be followed in order a migrate V2.x application to a Version 3.0 application in case you want to link the Version 3.0 "collapsed" shareable. Please refer to DEComni API and DEComni MMS User Guide for information about how to write an application that can link with the "collapsed" shareable. 6.5 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 6-2 Release Notes Specific to Digital UNIX Platforms Release Notes Specific to Digital UNIX Platforms 6.5 Using the User Data Buffer variable though only the part (or the parts) of buffer referenced by the alternate access data type is accessed. 6.6 Features Not Documented Elsewhere The following features have not been included in the DECosap for