DEComni_API_for_Digital_UNIX________________________ Release Notes February 1996 This document contains the release notes for DEComni API 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: DEComni API 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 Features of DEComni API Version 3.0.............. 1-1 1.2 The DEComni API Docset........................... 1-1 1.3 Location of DEComni API Examples................. 1-2 1.4 Deinstalling DEComni API for Digital UNIX........ 1-2 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.1.5.1 Application Migration from omni_server to "Collapsed" Library Interface............... 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 Bug Fixes........................................ 2-5 2.3.1 Potential Deadlock ............................ 2-5 2.3.2 omni_s_invfunc on connect ..................... 2-5 2.3.3 Using omni_reject for Unsolicited Indications.................................... 2-5 2.4 Known Problems................................... 2-6 2.4.1 Segmented Services and Allocated Data ......... 2-6 2.4.2 API and the Length Argument ................... 2-6 iii 2.4.3 Aborted Connection ............................ 2-6 2.4.4 Using the omni_modify_definition Function ..... 2-6 2.4.5 Abort Processing .............................. 2-6 2.4.6 ODSCL Replace Command ......................... 2-7 3 Documentation Notes 3.1 DEComni API/MMS User Guide....................... 3-1 iv _________________________________________________________________ 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.0 on Digital UNIX. o Chapter 2 lists all release notes concerning development issues specific to DEComni API on Digital UNIX. o Chapter 3 lists all release notes concerning documentation issues specific to DEComni API on Digital UNIX. 1.1 Features of DEComni API Version 3.0 The new features provided by DEComni API Version 3.0 are as follows: o Improved installation and integration of DASes o The possibility of deleting object definitions o A routine that allows a user application to look at data received via a write or information report indication, and decide whether to accept (read) or reject the indication 1.2 The DEComni API Docset The DEComni API for Digital UNIX Version 3.0 docset includes the following manuals: o DEComni API for Digital UNIX Installation Guide o Guide to Using Omni Directory Services o DEComni API/MMS User Guide General Notes 1-1 General Notes 1.3 Location of DEComni API Examples 1.3 Location of DEComni API Examples An example program used to build the IVP is shipped with the kit. The example programs is located in the /usr/opt /DOUBASE300/examples directory. 1.4 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. 1-2 General Notes 2 _________________________________________________________________ Release Notes Specific to Digital UNIX 2.1 New Features 2.1.1 Dynamic Loading of DASes DEComni API Version 3.0 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.0: omni_ registry. New DASes register themself by specifying their shareable image. Using the information found in the registry database, DEComni API Version 3.0 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 DAS writers. The procedure is transparent for users who only need to use the DEComni API Version 3.0 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.0 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.0 is the last release on which the omni_server process will be supported. For this reason, you are strongly advised to use the new "collapsed" library interface that provides better performances. 2.1.5.1 Application Migration from omni_server to "Collapsed" Library Interface The DEComni API and DEComni MMS User Guide explains how to migrate an application using the omni_server to a Version 3.0 application linked to the collapsed shareable image. 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 calls: 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, when you invoke omni_get_remote_attributes on a PI, 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 can be connected 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 Bug Fixes 2.3 Bug Fixes 2.3.1 Potential Deadlock In the previous version of DEComni API, a potential deadlock situation occurred when there were several requests outstanding on a connection. This problem has now been resolved. 2.3.2 omni_s_invfunc on connect In the previous version of DEComni API, it was possibile to register an omni_s_invfunc error while calling omni_connect immediately after a previous disconnection or a previous failed connection request. This problem has been solved. 2.3.3 Using omni_reject for Unsolicited Indications The omni_reject function can now be used for indications of information reports and any other unconfirmed service. It completes the service locally without generating any answer back to the pear. Release Notes Specific to Digital UNIX 2-5 Release Notes Specific to Digital UNIX 2.4 Known Problems 2.4 Known Problems 2.4.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.4.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.4.3 Aborted Connection If a connection is aborted in the middle of an operation, the operation completes with the status of omni_s_svc_ incomplete. The association was terminated before service completion, and not abort status. 2.4.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.4.5 Abort Processing The following are problems that can occur during the aborting of an application: o A client application does not receive the abort indication from the remote VMD when a sequence of actions is executed as follows: 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. 2-6 Release Notes Specific to Digital UNIX Release Notes Specific to Digital UNIX 2.4 Known Problems 4. The client calls the omni_poll function that calls the completion routine. 5. 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 it receives the return code omni_s_ invfunc. 6. The completion routine calls omni_get_indications again, but it fails and receives the return code omni_s_invfunc. o A timing problem in the processing of the DEComni API abort request can occur and can cause DEComni API to hang. The abort request is sent but you may not be notified. Currently, there is no workaround for this problem. 2.4.6 ODSCL Replace Command The ODSCL modify command fails if the values in the replace instance have different string lengths. As a interim solution, specify the same length for both the original and replacement strings, e.g.: Change: ODSCL> mod dir name "/cn=MYVMD" replace "RSPTIMEOUT=0,10" to ODSCL> mod dir name "/cn=MYVMD" replace "RSPTIMEOUT=00,10" Release Notes Specific to Digital UNIX 2-7 3 _________________________________________________________________ Documentation Notes 3.1 DEComni API/MMS User Guide Some MMS DAS specific information previously documented in the DEComni MMS User Guide have been included into the old DEComni API User Guide which new name is: "DEComni API and DEComni MMS User Guide". Users who are interested in DASes different from MMS might want to skip sections labeled as DAS MMS specific. Documentation Notes 3-1