DEComni_API_for_Digital_UNIX________________________ Release Notes March 1997 This document contains the release notes for DEComni API 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: DEComni API 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 DEComni API Docset........................... 1-1 1.2 Location of DEComni API Examples................. 1-1 1.3 Deinstalling DEComni API for DIGITAL UNIX........ 1-1 2 Release Notes Specific to Digital UNIX 2.1 New Features..................................... 2-1 2.1.1 Dynamic Loading of DASes ...................... 2-1 2.1.2 Improved Installation Procedure ............... 2-1 2.1.3 Deletion of Object Definitions ................ 2-1 2.1.4 Deletion of Object Definitions ................ 2-2 2.1.5 omni_server Support ........................... 2-2 2.2 Restrictions..................................... 2-3 2.2.1 Support for API Calls ......................... 2-3 2.2.2 D_FLOAT Variable Support ...................... 2-3 2.2.3 Using the omni_c_attr_monitor Attribute ....... 2-3 2.2.4 Using Include Files ........................... 2-3 2.2.5 Limit of Client Applications .................. 2-4 2.3 Known Problems................................... 2-5 2.3.1 Segmented Services and Allocated Data ......... 2-5 2.3.2 API and the Length Argument ................... 2-5 2.3.3 Aborted Connection ............................ 2-5 2.3.4 Using the omni_modify_definition Function ..... 2-5 2.3.5 Abort Processing .............................. 2-5 2.3.6 Control Structure and Synchronous Calls ....... 2-6 iii _________________________________________________________________ Preface v 1 _________________________________________________________________ General Notes The structure of this document is as follows: o Chapter 1 provides a general introduction to DEComni API Version 3.1 on Digital UNIX. o Chapter 2 lists all release notes concerning development issues specific to DEComni API on Digital UNIX. 1.1 The DEComni API Docset The DEComni API for Digital UNIX Version 3.1 docset includes the following manuals: o DEComni API for Digital UNIX Installation Guide o Guide to Using Omni Directory Services o DEComni API and DEComni MMS User Guide 1.2 Location of DEComni API Examples An example program used to build the IVP is shipped with the kit. It is located in the /usr/opt/DOUBASE310/examples directory. 1.3 Deinstalling DEComni API for DIGITAL UNIX If you need to deinstall DEComni API for DIGITAL UNIX for any reason (for example, to install a new version), you must also deinstall all currently installed DEComni API Device Access Software (DAS) (for example, DECosap) before deinstalling DEComni API. If any DEComni API DAS is left on the system when DEComni API is deinstalled, you will not be able to use the DEComni API DAS. Its deinstallation procedure could fail, and it will not work after DEComni API reinstallation, until the DAS has been deinstalled and reinstalled. General Notes 1-1 2 _________________________________________________________________ Release Notes Specific to Digital UNIX 2.1 New Features 2.1.1 Dynamic Loading of DASes DEComni API Version 3.1 allows Device Access Systems (DASes) to be integrated dynamically. A new DAS registration utility is provided in order to declare the newly installed DAS to DEComni API Version 3.1: omni_registry. New DASes register themself by specifying their shareable image. Using the information found in the registry database, DEComni API Version 3.1 can locate and load the shareable images of the installed DASes dynamically during its initialization phase. The omni_registry utility is only meaningful for new Device Access Software (DAS) writers. The procedure is transparent for users who only need to use the DEComni API Version 3.1 at application level. 2.1.2 Improved Installation Procedure Given that it is possible to load integrators dynamically, there is no further need for a server configuration phase during installation. 2.1.3 Deletion of Object Definitions A new API function, omni_delete_definition, allows a user application to delete: o A single object, by specifying the object handle o An entire branch of objects, by specifying the handle of the parent object Release Notes Specific to Digital UNIX 2-1 Release Notes Specific to Digital UNIX 2.1 New Features 2.1.4 Deletion of Object Definitions DEComni API Version 3.1 provides a new API function, omni_lookup_value, that allows a user application to parse the data sent by an incoming write or information report indication, and decide whether to accept or reject the data in question. You must still call the omni_get_value function in order to accept a given data value. 2.1.5 omni_server Support DEComni API Version 3.1 supports the omni_server process. 2-2 Release Notes Specific to Digital UNIX Release Notes Specific to Digital UNIX 2.2 Restrictions 2.2 Restrictions 2.2.1 Support for API Calls DEComni API does not support the following API call: o omni_cancel 2.2.2 D_FLOAT Variable Support There is no support for D_FLOAT variables. 2.2.3 Using the omni_c_attr_monitor Attribute The omni_c_attr_monitor attribute is used inconsistently. When defining a PI, you can specify one of the following three values for the omni_c_attr_monitor attribute: o omni_c_pimnt_not_present o omni_c_pimnt_permanent o omni_c_pimnt_current Its type is omni_l_pi_monitor. However, if you invoke omni_get_remote_attributes on a PI, and then try to retrieve the omni_c_attr_monitor attribute, a simple Boolean value (TRUE or FALSE) is returned. This is due to the level of detail returned by MMS. When defining a PI, in addition to specifying whether you want to activate the monitoring facility, you can also request DEComni API to activate monitoring permanently or only for the duration of the current connection. However, after an omni_get_remote_attributes on a PI, the only information returned concerns whether monitoring is on or off. DEComni API for Digital UNIX cannot provide the same level of detail associated with the omni_c_pi_monitor type, so instead uses the omni_c_boolean type. 2.2.4 Using Include Files When X/Motif and omni include files are used together, the compilation can result in "Status" compilation errors. These errors are caused by the following definitions within the X.h file: Release Notes Specific to Digital UNIX 2-3 Release Notes Specific to Digital UNIX 2.2 Restrictions #define Bool int #define Status int #define True 1 #define False 0 To prevent these errors, include all the X/Motif files after omni_defs.h. 2.2.5 Limit of Client Applications The maximum number of DEComni API client applications that you can connecte to the DEComni API server at one time is limited to the maximum number of open files permitted per process divided by two. This is an Digital UNIX system configuration parameter. For example, if the open file limit is 32, then only 16 DEComni API applications may be connected to the DEComni API server simultaneously. There are no limits if the client applications are linked with the "collapsed" shareable. 2-4 Release Notes Specific to Digital UNIX Release Notes Specific to Digital UNIX 2.3 Known Problems 2.3 Known Problems 2.3.1 Segmented Services and Allocated Data During segmented services, such as upload and download, DEComni API does not free the allocated data until the entire operation is complete. 2.3.2 API and the Length Argument The internal DEComni API (in the omni_server) does not use the length argument when specified in the argument list. This causes the memory to be overwritten in the omni_server, as though it were out of memory and failing. If the size of the buffer provided for a DEComni API function is smaller than the data that DEComni API writes to that buffer DEComni API writes over the memory up to the perceived data length. This causes unpredictable results. 2.3.3 Aborted Connection If a connection is aborted in the middle of an operation, the operation terminates with a status of omni_s_svc_incomplete. The association was terminated before service completion, and not abort status. 2.3.4 Using the omni_modify_definition Function Unpredictable results may occur if you attempt to modify an object definition that is currently in use. For example, modifying a variable definition while trying to read it. 2.3.5 Abort Processing The following are problems that may occur when an application aborts: o A client application does not receive the abort indication from the remote VMD if you execute the following sequence of actions: 1. The client calls the omni_get_indications_a function, specifying a completion routine. 2. The remote VMD sends the client an information report. 3. The remote VMD sends the client the abort indication. Release Notes Specific to Digital UNIX 2-5 Release Notes Specific to Digital UNIX 2.3 Known Problems 4. The completion routine gets the information report indication and calls omni_get_value in order to retrieve the value of the variable. The omni_get_value fails and receives the return code omni_s_invfunc. 5. The completion routine calls omni_get_indications again, but fails and receives the return code omni_s_ invfunc. o A timing problem in the processing of the DEComni API abort request may occur, causing DEComni API to hang. The abort request is sent but you may not be notified. Currently, there is no workaround for this problem. 2.3.6 Control Structure and Synchronous Calls If you specify a control structure for an application that uses synchronous calls, make sure that you set any control structure fields that do not contain significant information to zero. Failure to do so may cause DEComni API to use non-zero fields of the structure, thereby causing an ACCVIO. 2-6 Release Notes Specific to Digital UNIX